gio/auto/action.rs
1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::ffi;
6use glib::{
7 prelude::*,
8 signal::{connect_raw, SignalHandlerId},
9 translate::*,
10};
11use std::boxed::Box as Box_;
12
13glib::wrapper! {
14 /// `GAction` represents a single named action.
15 ///
16 /// The main interface to an action is that it can be activated with
17 /// [`ActionExt::activate()`][crate::prelude::ActionExt::activate()]. This results in the 'activate' signal being
18 /// emitted. An activation has a `GVariant` parameter (which may be
19 /// `NULL`). The correct type for the parameter is determined by a static
20 /// parameter type (which is given at construction time).
21 ///
22 /// An action may optionally have a state, in which case the state may be
23 /// set with [`ActionExt::change_state()`][crate::prelude::ActionExt::change_state()]. This call takes a [type@GLib.Variant]. The
24 /// correct type for the state is determined by a static state type
25 /// (which is given at construction time).
26 ///
27 /// The state may have a hint associated with it, specifying its valid
28 /// range.
29 ///
30 /// `GAction` is merely the interface to the concept of an action, as
31 /// described above. Various implementations of actions exist, including
32 /// [`SimpleAction`][crate::SimpleAction].
33 ///
34 /// In all cases, the implementing class is responsible for storing the
35 /// name of the action, the parameter type, the enabled state, the optional
36 /// state type and the state and emitting the appropriate signals when these
37 /// change. The implementor is responsible for filtering calls to
38 /// [`ActionExt::activate()`][crate::prelude::ActionExt::activate()] and [`ActionExt::change_state()`][crate::prelude::ActionExt::change_state()]
39 /// for type safety and for the state being enabled.
40 ///
41 /// Probably the only useful thing to do with a `GAction` is to put it
42 /// inside of a [`SimpleActionGroup`][crate::SimpleActionGroup].
43 ///
44 /// ## Properties
45 ///
46 ///
47 /// #### `enabled`
48 /// If @action is currently enabled.
49 ///
50 /// If the action is disabled then calls to [`ActionExt::activate()`][crate::prelude::ActionExt::activate()] and
51 /// [`ActionExt::change_state()`][crate::prelude::ActionExt::change_state()] have no effect.
52 ///
53 /// Readable
54 ///
55 ///
56 /// #### `name`
57 /// The name of the action. This is mostly meaningful for identifying
58 /// the action once it has been added to a [type@Gio.ActionGroup]. It is immutable.
59 ///
60 /// Readable
61 ///
62 ///
63 /// #### `parameter-type`
64 /// The type of the parameter that must be given when activating the
65 /// action. This is immutable, and may be `NULL` if no parameter is needed when
66 /// activating the action.
67 ///
68 /// Readable
69 ///
70 ///
71 /// #### `state`
72 /// The state of the action, or `NULL` if the action is stateless.
73 ///
74 /// Readable
75 ///
76 ///
77 /// #### `state-type`
78 /// The [type@GLib.VariantType] of the state that the action has, or `NULL` if the
79 /// action is stateless. This is immutable.
80 ///
81 /// Readable
82 ///
83 /// # Implements
84 ///
85 /// [`ActionExt`][trait@crate::prelude::ActionExt]
86 #[doc(alias = "GAction")]
87 pub struct Action(Interface<ffi::GAction, ffi::GActionInterface>);
88
89 match fn {
90 type_ => || ffi::g_action_get_type(),
91 }
92}
93
94impl Action {
95 pub const NONE: Option<&'static Action> = None;
96
97 /// Checks if @action_name is valid.
98 ///
99 /// @action_name is valid if it consists only of alphanumeric characters,
100 /// plus `-` and `.`. The empty string is not a valid action name.
101 ///
102 /// It is an error to call this function with a non-UTF-8 @action_name.
103 /// @action_name must not be `NULL`.
104 /// ## `action_name`
105 /// a potential action name
106 ///
107 /// # Returns
108 ///
109 /// `TRUE` if @action_name is valid
110 #[doc(alias = "g_action_name_is_valid")]
111 pub fn name_is_valid(action_name: &str) -> bool {
112 unsafe { from_glib(ffi::g_action_name_is_valid(action_name.to_glib_none().0)) }
113 }
114
115 /// Parses a detailed action name into its separate name and target
116 /// components.
117 ///
118 /// Detailed action names can have three formats.
119 ///
120 /// The first format is used to represent an action name with no target
121 /// value and consists of just an action name containing no whitespace
122 /// nor the characters `:`, `(` or `)`. For example: `app.action`.
123 ///
124 /// The second format is used to represent an action with a target value
125 /// that is a non-empty string consisting only of alphanumerics, plus `-`
126 /// and `.`. In that case, the action name and target value are
127 /// separated by a double colon (`::`). For example:
128 /// `app.action::target`.
129 ///
130 /// The third format is used to represent an action with any type of
131 /// target value, including strings. The target value follows the action
132 /// name, surrounded in parens. For example: `app.action(42)`. The
133 /// target value is parsed using `GLib::Variant::parse()`. If a tuple-typed
134 /// value is desired, it must be specified in the same way, resulting in
135 /// two sets of parens, for example: `app.action((1,2,3))`. A string
136 /// target can be specified this way as well: `app.action('target')`.
137 /// For strings, this third format must be used if target value is
138 /// empty or contains characters other than alphanumerics, `-` and `.`.
139 ///
140 /// If this function returns `TRUE`, a non-`NULL` value is guaranteed to be returned
141 /// in @action_name (if a pointer is passed in). A `NULL` value may still be
142 /// returned in @target_value, as the @detailed_name may not contain a target.
143 ///
144 /// If returned, the [type@GLib.Variant] in @target_value is guaranteed to not be floating.
145 /// ## `detailed_name`
146 /// a detailed action name
147 ///
148 /// # Returns
149 ///
150 /// `TRUE` if successful, else `FALSE` with @error set
151 ///
152 /// ## `action_name`
153 /// the action name
154 ///
155 /// ## `target_value`
156 /// the target value,
157 /// or `NULL` for no target
158 #[doc(alias = "g_action_parse_detailed_name")]
159 pub fn parse_detailed_name(
160 detailed_name: &str,
161 ) -> Result<(glib::GString, Option<glib::Variant>), glib::Error> {
162 unsafe {
163 let mut action_name = std::ptr::null_mut();
164 let mut target_value = std::ptr::null_mut();
165 let mut error = std::ptr::null_mut();
166 let is_ok = ffi::g_action_parse_detailed_name(
167 detailed_name.to_glib_none().0,
168 &mut action_name,
169 &mut target_value,
170 &mut error,
171 );
172 debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
173 if error.is_null() {
174 Ok((from_glib_full(action_name), from_glib_full(target_value)))
175 } else {
176 Err(from_glib_full(error))
177 }
178 }
179 }
180
181 /// Formats a detailed action name from @action_name and @target_value.
182 ///
183 /// It is an error to call this function with an invalid action name.
184 ///
185 /// This function is the opposite of [`parse_detailed_name()`][Self::parse_detailed_name()].
186 /// It will produce a string that can be parsed back to the @action_name
187 /// and @target_value by that function.
188 ///
189 /// See that function for the types of strings that will be printed by
190 /// this function.
191 /// ## `action_name`
192 /// a valid action name
193 /// ## `target_value`
194 /// a [type@GLib.Variant] target value, or `NULL`
195 ///
196 /// # Returns
197 ///
198 /// a detailed format string
199 #[doc(alias = "g_action_print_detailed_name")]
200 pub fn print_detailed_name(
201 action_name: &str,
202 target_value: Option<&glib::Variant>,
203 ) -> glib::GString {
204 unsafe {
205 from_glib_full(ffi::g_action_print_detailed_name(
206 action_name.to_glib_none().0,
207 target_value.to_glib_none().0,
208 ))
209 }
210 }
211}
212
213mod sealed {
214 pub trait Sealed {}
215 impl<T: super::IsA<super::Action>> Sealed for T {}
216}
217
218/// Trait containing all [`struct@Action`] methods.
219///
220/// # Implementors
221///
222/// [`Action`][struct@crate::Action], [`PropertyAction`][struct@crate::PropertyAction], [`SimpleAction`][struct@crate::SimpleAction]
223pub trait ActionExt: IsA<Action> + sealed::Sealed + 'static {
224 /// Activates the action.
225 ///
226 /// @parameter must be the correct type of parameter for the action (ie:
227 /// the parameter type given at construction time). If the parameter
228 /// type was `NULL` then @parameter must also be `NULL`.
229 ///
230 /// If the @parameter [type@GLib.Variant] is floating, it is consumed.
231 /// ## `parameter`
232 /// the parameter to the activation
233 #[doc(alias = "g_action_activate")]
234 fn activate(&self, parameter: Option<&glib::Variant>) {
235 unsafe {
236 ffi::g_action_activate(self.as_ref().to_glib_none().0, parameter.to_glib_none().0);
237 }
238 }
239
240 /// Request for the state of @self to be changed to @value.
241 ///
242 /// The action must be stateful and @value must be of the correct type.
243 /// See [`state_type()`][Self::state_type()].
244 ///
245 /// This call merely requests a change. The action may refuse to change
246 /// its state or may change its state to something other than @value.
247 /// See [`state_hint()`][Self::state_hint()].
248 ///
249 /// If the @value [type@GLib.Variant] is floating, it is consumed.
250 /// ## `value`
251 /// the new state
252 #[doc(alias = "g_action_change_state")]
253 fn change_state(&self, value: &glib::Variant) {
254 unsafe {
255 ffi::g_action_change_state(self.as_ref().to_glib_none().0, value.to_glib_none().0);
256 }
257 }
258
259 /// Checks if @self is currently enabled.
260 ///
261 /// An action must be enabled in order to be activated or in order to
262 /// have its state changed from outside callers.
263 ///
264 /// # Returns
265 ///
266 /// whether the action is enabled
267 #[doc(alias = "g_action_get_enabled")]
268 #[doc(alias = "get_enabled")]
269 #[doc(alias = "enabled")]
270 fn is_enabled(&self) -> bool {
271 unsafe { from_glib(ffi::g_action_get_enabled(self.as_ref().to_glib_none().0)) }
272 }
273
274 /// Queries the name of @self.
275 ///
276 /// # Returns
277 ///
278 /// the name of the action
279 #[doc(alias = "g_action_get_name")]
280 #[doc(alias = "get_name")]
281 fn name(&self) -> glib::GString {
282 unsafe { from_glib_none(ffi::g_action_get_name(self.as_ref().to_glib_none().0)) }
283 }
284
285 /// Queries the type of the parameter that must be given when activating
286 /// @self.
287 ///
288 /// When activating the action using [`activate()`][Self::activate()], the
289 /// [type@GLib.Variant] given to that function must be of the type returned by
290 /// this function.
291 ///
292 /// In the case that this function returns `NULL`, you must not give any
293 /// [type@GLib.Variant], but `NULL` instead.
294 ///
295 /// # Returns
296 ///
297 /// the parameter type
298 #[doc(alias = "g_action_get_parameter_type")]
299 #[doc(alias = "get_parameter_type")]
300 #[doc(alias = "parameter-type")]
301 fn parameter_type(&self) -> Option<glib::VariantType> {
302 unsafe {
303 from_glib_none(ffi::g_action_get_parameter_type(
304 self.as_ref().to_glib_none().0,
305 ))
306 }
307 }
308
309 /// Queries the current state of @self.
310 ///
311 /// If the action is not stateful then `NULL` will be returned. If the
312 /// action is stateful then the type of the return value is the type
313 /// given by [`state_type()`][Self::state_type()].
314 ///
315 /// The return value (if non-`NULL`) should be freed with
316 /// `GLib::Variant::unref()` when it is no longer required.
317 ///
318 /// # Returns
319 ///
320 /// the current state of the action
321 #[doc(alias = "g_action_get_state")]
322 #[doc(alias = "get_state")]
323 fn state(&self) -> Option<glib::Variant> {
324 unsafe { from_glib_full(ffi::g_action_get_state(self.as_ref().to_glib_none().0)) }
325 }
326
327 /// Requests a hint about the valid range of values for the state of
328 /// @self.
329 ///
330 /// If `NULL` is returned it either means that the action is not stateful
331 /// or that there is no hint about the valid range of values for the
332 /// state of the action.
333 ///
334 /// If a [type@GLib.Variant] array is returned then each item in the array is a
335 /// possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is
336 /// returned then the tuple specifies the inclusive lower and upper bound
337 /// of valid values for the state.
338 ///
339 /// In any case, the information is merely a hint. It may be possible to
340 /// have a state value outside of the hinted range and setting a value
341 /// within the range may fail.
342 ///
343 /// The return value (if non-`NULL`) should be freed with
344 /// `GLib::Variant::unref()` when it is no longer required.
345 ///
346 /// # Returns
347 ///
348 /// the state range hint
349 #[doc(alias = "g_action_get_state_hint")]
350 #[doc(alias = "get_state_hint")]
351 fn state_hint(&self) -> Option<glib::Variant> {
352 unsafe { from_glib_full(ffi::g_action_get_state_hint(self.as_ref().to_glib_none().0)) }
353 }
354
355 /// Queries the type of the state of @self.
356 ///
357 /// If the action is stateful (e.g. created with
358 /// [`SimpleAction::new_stateful()`][crate::SimpleAction::new_stateful()]) then this function returns the
359 /// [type@GLib.VariantType] of the state. This is the type of the initial value
360 /// given as the state. All calls to [`change_state()`][Self::change_state()] must give a
361 /// [type@GLib.Variant] of this type and [`state()`][Self::state()] will return a
362 /// [type@GLib.Variant] of the same type.
363 ///
364 /// If the action is not stateful (e.g. created with [`SimpleAction::new()`][crate::SimpleAction::new()])
365 /// then this function will return `NULL`. In that case, [`state()`][Self::state()]
366 /// will return `NULL` and you must not call [`change_state()`][Self::change_state()].
367 ///
368 /// # Returns
369 ///
370 /// the state type, if the action is stateful
371 #[doc(alias = "g_action_get_state_type")]
372 #[doc(alias = "get_state_type")]
373 #[doc(alias = "state-type")]
374 fn state_type(&self) -> Option<glib::VariantType> {
375 unsafe { from_glib_none(ffi::g_action_get_state_type(self.as_ref().to_glib_none().0)) }
376 }
377
378 #[doc(alias = "enabled")]
379 fn connect_enabled_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
380 unsafe extern "C" fn notify_enabled_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
381 this: *mut ffi::GAction,
382 _param_spec: glib::ffi::gpointer,
383 f: glib::ffi::gpointer,
384 ) {
385 let f: &F = &*(f as *const F);
386 f(Action::from_glib_borrow(this).unsafe_cast_ref())
387 }
388 unsafe {
389 let f: Box_<F> = Box_::new(f);
390 connect_raw(
391 self.as_ptr() as *mut _,
392 b"notify::enabled\0".as_ptr() as *const _,
393 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
394 notify_enabled_trampoline::<Self, F> as *const (),
395 )),
396 Box_::into_raw(f),
397 )
398 }
399 }
400
401 #[doc(alias = "name")]
402 fn connect_name_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
403 unsafe extern "C" fn notify_name_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
404 this: *mut ffi::GAction,
405 _param_spec: glib::ffi::gpointer,
406 f: glib::ffi::gpointer,
407 ) {
408 let f: &F = &*(f as *const F);
409 f(Action::from_glib_borrow(this).unsafe_cast_ref())
410 }
411 unsafe {
412 let f: Box_<F> = Box_::new(f);
413 connect_raw(
414 self.as_ptr() as *mut _,
415 b"notify::name\0".as_ptr() as *const _,
416 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
417 notify_name_trampoline::<Self, F> as *const (),
418 )),
419 Box_::into_raw(f),
420 )
421 }
422 }
423
424 #[doc(alias = "parameter-type")]
425 fn connect_parameter_type_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
426 unsafe extern "C" fn notify_parameter_type_trampoline<
427 P: IsA<Action>,
428 F: Fn(&P) + 'static,
429 >(
430 this: *mut ffi::GAction,
431 _param_spec: glib::ffi::gpointer,
432 f: glib::ffi::gpointer,
433 ) {
434 let f: &F = &*(f as *const F);
435 f(Action::from_glib_borrow(this).unsafe_cast_ref())
436 }
437 unsafe {
438 let f: Box_<F> = Box_::new(f);
439 connect_raw(
440 self.as_ptr() as *mut _,
441 b"notify::parameter-type\0".as_ptr() as *const _,
442 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
443 notify_parameter_type_trampoline::<Self, F> as *const (),
444 )),
445 Box_::into_raw(f),
446 )
447 }
448 }
449
450 #[doc(alias = "state")]
451 fn connect_state_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
452 unsafe extern "C" fn notify_state_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
453 this: *mut ffi::GAction,
454 _param_spec: glib::ffi::gpointer,
455 f: glib::ffi::gpointer,
456 ) {
457 let f: &F = &*(f as *const F);
458 f(Action::from_glib_borrow(this).unsafe_cast_ref())
459 }
460 unsafe {
461 let f: Box_<F> = Box_::new(f);
462 connect_raw(
463 self.as_ptr() as *mut _,
464 b"notify::state\0".as_ptr() as *const _,
465 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
466 notify_state_trampoline::<Self, F> as *const (),
467 )),
468 Box_::into_raw(f),
469 )
470 }
471 }
472
473 #[doc(alias = "state-type")]
474 fn connect_state_type_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
475 unsafe extern "C" fn notify_state_type_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
476 this: *mut ffi::GAction,
477 _param_spec: glib::ffi::gpointer,
478 f: glib::ffi::gpointer,
479 ) {
480 let f: &F = &*(f as *const F);
481 f(Action::from_glib_borrow(this).unsafe_cast_ref())
482 }
483 unsafe {
484 let f: Box_<F> = Box_::new(f);
485 connect_raw(
486 self.as_ptr() as *mut _,
487 b"notify::state-type\0".as_ptr() as *const _,
488 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
489 notify_state_type_trampoline::<Self, F> as *const (),
490 )),
491 Box_::into_raw(f),
492 )
493 }
494 }
495}
496
497impl<O: IsA<Action>> ActionExt for O {}