gio/auto/
menu_item.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, Icon, MenuModel};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// #GMenuItem is an opaque structure type.  You must access it using the
10    /// functions below.
11    ///
12    /// # Implements
13    ///
14    /// [`trait@glib::ObjectExt`]
15    #[doc(alias = "GMenuItem")]
16    pub struct MenuItem(Object<ffi::GMenuItem>);
17
18    match fn {
19        type_ => || ffi::g_menu_item_get_type(),
20    }
21}
22
23impl MenuItem {
24    /// Creates a new #GMenuItem.
25    ///
26    /// If @label is non-[`None`] it is used to set the "label" attribute of the
27    /// new item.
28    ///
29    /// If @detailed_action is non-[`None`] it is used to set the "action" and
30    /// possibly the "target" attribute of the new item.  See
31    /// g_menu_item_set_detailed_action() for more information.
32    /// ## `label`
33    /// the section label, or [`None`]
34    /// ## `detailed_action`
35    /// the detailed action string, or [`None`]
36    ///
37    /// # Returns
38    ///
39    /// a new #GMenuItem
40    #[doc(alias = "g_menu_item_new")]
41    pub fn new(label: Option<&str>, detailed_action: Option<&str>) -> MenuItem {
42        unsafe {
43            from_glib_full(ffi::g_menu_item_new(
44                label.to_glib_none().0,
45                detailed_action.to_glib_none().0,
46            ))
47        }
48    }
49
50    /// Creates a #GMenuItem as an exact copy of an existing menu item in a
51    /// #GMenuModel.
52    ///
53    /// @item_index must be valid (ie: be sure to call
54    /// g_menu_model_get_n_items() first).
55    /// ## `model`
56    /// a #GMenuModel
57    /// ## `item_index`
58    /// the index of an item in @model
59    ///
60    /// # Returns
61    ///
62    /// a new #GMenuItem.
63    #[doc(alias = "g_menu_item_new_from_model")]
64    #[doc(alias = "new_from_model")]
65    pub fn from_model(model: &impl IsA<MenuModel>, item_index: i32) -> MenuItem {
66        unsafe {
67            from_glib_full(ffi::g_menu_item_new_from_model(
68                model.as_ref().to_glib_none().0,
69                item_index,
70            ))
71        }
72    }
73
74    /// Creates a new #GMenuItem representing a section.
75    ///
76    /// This is a convenience API around g_menu_item_new() and
77    /// g_menu_item_set_section().
78    ///
79    /// The effect of having one menu appear as a section of another is
80    /// exactly as it sounds: the items from @section become a direct part of
81    /// the menu that @menu_item is added to.
82    ///
83    /// Visual separation is typically displayed between two non-empty
84    /// sections.  If @label is non-[`None`] then it will be incorporated into
85    /// this visual indication.  This allows for labeled subsections of a
86    /// menu.
87    ///
88    /// As a simple example, consider a typical "Edit" menu from a simple
89    /// program.  It probably contains an "Undo" and "Redo" item, followed by
90    /// a separator, followed by "Cut", "Copy" and "Paste".
91    ///
92    /// This would be accomplished by creating three #GMenu instances.  The
93    /// first would be populated with the "Undo" and "Redo" items, and the
94    /// second with the "Cut", "Copy" and "Paste" items.  The first and
95    /// second menus would then be added as submenus of the third.  In XML
96    /// format, this would look something like the following:
97    ///
98    /// ```text
99    /// <menu id='edit-menu'>
100    ///   <section>
101    ///     <item label='Undo'/>
102    ///     <item label='Redo'/>
103    ///   </section>
104    ///   <section>
105    ///     <item label='Cut'/>
106    ///     <item label='Copy'/>
107    ///     <item label='Paste'/>
108    ///   </section>
109    /// </menu>
110    /// ```
111    ///
112    /// The following example is exactly equivalent.  It is more illustrative
113    /// of the exact relationship between the menus and items (keeping in
114    /// mind that the 'link' element defines a new menu that is linked to the
115    /// containing one).  The style of the second example is more verbose and
116    /// difficult to read (and therefore not recommended except for the
117    /// purpose of understanding what is really going on).
118    ///
119    /// ```text
120    /// <menu id='edit-menu'>
121    ///   <item>
122    ///     <link name='section'>
123    ///       <item label='Undo'/>
124    ///       <item label='Redo'/>
125    ///     </link>
126    ///   </item>
127    ///   <item>
128    ///     <link name='section'>
129    ///       <item label='Cut'/>
130    ///       <item label='Copy'/>
131    ///       <item label='Paste'/>
132    ///     </link>
133    ///   </item>
134    /// </menu>
135    /// ```
136    /// ## `label`
137    /// the section label, or [`None`]
138    /// ## `section`
139    /// a #GMenuModel with the items of the section
140    ///
141    /// # Returns
142    ///
143    /// a new #GMenuItem
144    #[doc(alias = "g_menu_item_new_section")]
145    pub fn new_section(label: Option<&str>, section: &impl IsA<MenuModel>) -> MenuItem {
146        unsafe {
147            from_glib_full(ffi::g_menu_item_new_section(
148                label.to_glib_none().0,
149                section.as_ref().to_glib_none().0,
150            ))
151        }
152    }
153
154    /// Creates a new #GMenuItem representing a submenu.
155    ///
156    /// This is a convenience API around g_menu_item_new() and
157    /// g_menu_item_set_submenu().
158    /// ## `label`
159    /// the section label, or [`None`]
160    /// ## `submenu`
161    /// a #GMenuModel with the items of the submenu
162    ///
163    /// # Returns
164    ///
165    /// a new #GMenuItem
166    #[doc(alias = "g_menu_item_new_submenu")]
167    pub fn new_submenu(label: Option<&str>, submenu: &impl IsA<MenuModel>) -> MenuItem {
168        unsafe {
169            from_glib_full(ffi::g_menu_item_new_submenu(
170                label.to_glib_none().0,
171                submenu.as_ref().to_glib_none().0,
172            ))
173        }
174    }
175
176    //#[doc(alias = "g_menu_item_get_attribute")]
177    //#[doc(alias = "get_attribute")]
178    //pub fn is_attribute(&self, attribute: &str, format_string: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> bool {
179    //    unsafe { TODO: call ffi:g_menu_item_get_attribute() }
180    //}
181
182    /// Queries the named @attribute on @self.
183    ///
184    /// If @expected_type is specified and the attribute does not have this
185    /// type, [`None`] is returned.  [`None`] is also returned if the attribute
186    /// simply does not exist.
187    /// ## `attribute`
188    /// the attribute name to query
189    /// ## `expected_type`
190    /// the expected type of the attribute
191    ///
192    /// # Returns
193    ///
194    /// the attribute value, or [`None`]
195    #[doc(alias = "g_menu_item_get_attribute_value")]
196    #[doc(alias = "get_attribute_value")]
197    pub fn attribute_value(
198        &self,
199        attribute: &str,
200        expected_type: Option<&glib::VariantTy>,
201    ) -> Option<glib::Variant> {
202        unsafe {
203            from_glib_full(ffi::g_menu_item_get_attribute_value(
204                self.to_glib_none().0,
205                attribute.to_glib_none().0,
206                expected_type.to_glib_none().0,
207            ))
208        }
209    }
210
211    /// Queries the named @link on @self.
212    /// ## `link`
213    /// the link name to query
214    ///
215    /// # Returns
216    ///
217    /// the link, or [`None`]
218    #[doc(alias = "g_menu_item_get_link")]
219    #[doc(alias = "get_link")]
220    pub fn link(&self, link: &str) -> Option<MenuModel> {
221        unsafe {
222            from_glib_full(ffi::g_menu_item_get_link(
223                self.to_glib_none().0,
224                link.to_glib_none().0,
225            ))
226        }
227    }
228
229    //#[doc(alias = "g_menu_item_set_action_and_target")]
230    //pub fn set_action_and_target(&self, action: Option<&str>, format_string: Option<&str>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
231    //    unsafe { TODO: call ffi:g_menu_item_set_action_and_target() }
232    //}
233
234    /// Sets or unsets the "action" and "target" attributes of @self.
235    ///
236    /// If @action is [`None`] then both the "action" and "target" attributes
237    /// are unset (and @target_value is ignored).
238    ///
239    /// If @action is non-[`None`] then the "action" attribute is set.  The
240    /// "target" attribute is then set to the value of @target_value if it is
241    /// non-[`None`] or unset otherwise.
242    ///
243    /// Normal menu items (ie: not submenu, section or other custom item
244    /// types) are expected to have the "action" attribute set to identify
245    /// the action that they are associated with.  The state type of the
246    /// action help to determine the disposition of the menu item.  See
247    /// #GAction and #GActionGroup for an overview of actions.
248    ///
249    /// In general, clicking on the menu item will result in activation of
250    /// the named action with the "target" attribute given as the parameter
251    /// to the action invocation.  If the "target" attribute is not set then
252    /// the action is invoked with no parameter.
253    ///
254    /// If the action has no state then the menu item is usually drawn as a
255    /// plain menu item (ie: with no additional decoration).
256    ///
257    /// If the action has a boolean state then the menu item is usually drawn
258    /// as a toggle menu item (ie: with a checkmark or equivalent
259    /// indication).  The item should be marked as 'toggled' or 'checked'
260    /// when the boolean state is [`true`].
261    ///
262    /// If the action has a string state then the menu item is usually drawn
263    /// as a radio menu item (ie: with a radio bullet or equivalent
264    /// indication).  The item should be marked as 'selected' when the string
265    /// state is equal to the value of the @target property.
266    ///
267    /// See g_menu_item_set_action_and_target() or
268    /// g_menu_item_set_detailed_action() for two equivalent calls that are
269    /// probably more convenient for most uses.
270    /// ## `action`
271    /// the name of the action for this item
272    /// ## `target_value`
273    /// a #GVariant to use as the action target
274    #[doc(alias = "g_menu_item_set_action_and_target_value")]
275    pub fn set_action_and_target_value(
276        &self,
277        action: Option<&str>,
278        target_value: Option<&glib::Variant>,
279    ) {
280        unsafe {
281            ffi::g_menu_item_set_action_and_target_value(
282                self.to_glib_none().0,
283                action.to_glib_none().0,
284                target_value.to_glib_none().0,
285            );
286        }
287    }
288
289    //#[doc(alias = "g_menu_item_set_attribute")]
290    //pub fn set_attribute(&self, attribute: &str, format_string: Option<&str>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
291    //    unsafe { TODO: call ffi:g_menu_item_set_attribute() }
292    //}
293
294    /// Sets or unsets an attribute on @self.
295    ///
296    /// The attribute to set or unset is specified by @attribute. This
297    /// can be one of the standard attribute names [`MENU_ATTRIBUTE_LABEL`][crate::MENU_ATTRIBUTE_LABEL],
298    /// [`MENU_ATTRIBUTE_ACTION`][crate::MENU_ATTRIBUTE_ACTION], [`MENU_ATTRIBUTE_TARGET`][crate::MENU_ATTRIBUTE_TARGET], or a custom
299    /// attribute name.
300    /// Attribute names are restricted to lowercase characters, numbers
301    /// and '-'. Furthermore, the names must begin with a lowercase character,
302    /// must not end with a '-', and must not contain consecutive dashes.
303    ///
304    /// must consist only of lowercase
305    /// ASCII characters, digits and '-'.
306    ///
307    /// If @value is non-[`None`] then it is used as the new value for the
308    /// attribute.  If @value is [`None`] then the attribute is unset. If
309    /// the @value #GVariant is floating, it is consumed.
310    ///
311    /// See also g_menu_item_set_attribute() for a more convenient way to do
312    /// the same.
313    /// ## `attribute`
314    /// the attribute to set
315    /// ## `value`
316    /// a #GVariant to use as the value, or [`None`]
317    #[doc(alias = "g_menu_item_set_attribute_value")]
318    pub fn set_attribute_value(&self, attribute: &str, value: Option<&glib::Variant>) {
319        unsafe {
320            ffi::g_menu_item_set_attribute_value(
321                self.to_glib_none().0,
322                attribute.to_glib_none().0,
323                value.to_glib_none().0,
324            );
325        }
326    }
327
328    /// Sets the "action" and possibly the "target" attribute of @self.
329    ///
330    /// The format of @detailed_action is the same format parsed by
331    /// g_action_parse_detailed_name().
332    ///
333    /// See g_menu_item_set_action_and_target() or
334    /// g_menu_item_set_action_and_target_value() for more flexible (but
335    /// slightly less convenient) alternatives.
336    ///
337    /// See also g_menu_item_set_action_and_target_value() for a description of
338    /// the semantics of the action and target attributes.
339    /// ## `detailed_action`
340    /// the "detailed" action string
341    #[doc(alias = "g_menu_item_set_detailed_action")]
342    pub fn set_detailed_action(&self, detailed_action: &str) {
343        unsafe {
344            ffi::g_menu_item_set_detailed_action(
345                self.to_glib_none().0,
346                detailed_action.to_glib_none().0,
347            );
348        }
349    }
350
351    /// Sets (or unsets) the icon on @self.
352    ///
353    /// This call is the same as calling g_icon_serialize() and using the
354    /// result as the value to g_menu_item_set_attribute_value() for
355    /// [`MENU_ATTRIBUTE_ICON`][crate::MENU_ATTRIBUTE_ICON].
356    ///
357    /// This API is only intended for use with "noun" menu items; things like
358    /// bookmarks or applications in an "Open With" menu.  Don't use it on
359    /// menu items corresponding to verbs (eg: stock icons for 'Save' or
360    /// 'Quit').
361    ///
362    /// If @icon is [`None`] then the icon is unset.
363    /// ## `icon`
364    /// a #GIcon, or [`None`]
365    #[doc(alias = "g_menu_item_set_icon")]
366    pub fn set_icon(&self, icon: &impl IsA<Icon>) {
367        unsafe {
368            ffi::g_menu_item_set_icon(self.to_glib_none().0, icon.as_ref().to_glib_none().0);
369        }
370    }
371
372    /// Sets or unsets the "label" attribute of @self.
373    ///
374    /// If @label is non-[`None`] it is used as the label for the menu item.  If
375    /// it is [`None`] then the label attribute is unset.
376    /// ## `label`
377    /// the label to set, or [`None`] to unset
378    #[doc(alias = "g_menu_item_set_label")]
379    pub fn set_label(&self, label: Option<&str>) {
380        unsafe {
381            ffi::g_menu_item_set_label(self.to_glib_none().0, label.to_glib_none().0);
382        }
383    }
384
385    /// Creates a link from @self to @model if non-[`None`], or unsets it.
386    ///
387    /// Links are used to establish a relationship between a particular menu
388    /// item and another menu.  For example, [`MENU_LINK_SUBMENU`][crate::MENU_LINK_SUBMENU] is used to
389    /// associate a submenu with a particular menu item, and [`MENU_LINK_SECTION`][crate::MENU_LINK_SECTION]
390    /// is used to create a section. Other types of link can be used, but there
391    /// is no guarantee that clients will be able to make sense of them.
392    /// Link types are restricted to lowercase characters, numbers
393    /// and '-'. Furthermore, the names must begin with a lowercase character,
394    /// must not end with a '-', and must not contain consecutive dashes.
395    /// ## `link`
396    /// type of link to establish or unset
397    /// ## `model`
398    /// the #GMenuModel to link to (or [`None`] to unset)
399    #[doc(alias = "g_menu_item_set_link")]
400    pub fn set_link(&self, link: &str, model: Option<&impl IsA<MenuModel>>) {
401        unsafe {
402            ffi::g_menu_item_set_link(
403                self.to_glib_none().0,
404                link.to_glib_none().0,
405                model.map(|p| p.as_ref()).to_glib_none().0,
406            );
407        }
408    }
409
410    /// Sets or unsets the "section" link of @self to @section.
411    ///
412    /// The effect of having one menu appear as a section of another is
413    /// exactly as it sounds: the items from @section become a direct part of
414    /// the menu that @self is added to.  See g_menu_item_new_section()
415    /// for more information about what it means for a menu item to be a
416    /// section.
417    /// ## `section`
418    /// a #GMenuModel, or [`None`]
419    #[doc(alias = "g_menu_item_set_section")]
420    pub fn set_section(&self, section: Option<&impl IsA<MenuModel>>) {
421        unsafe {
422            ffi::g_menu_item_set_section(
423                self.to_glib_none().0,
424                section.map(|p| p.as_ref()).to_glib_none().0,
425            );
426        }
427    }
428
429    /// Sets or unsets the "submenu" link of @self to @submenu.
430    ///
431    /// If @submenu is non-[`None`], it is linked to.  If it is [`None`] then the
432    /// link is unset.
433    ///
434    /// The effect of having one menu appear as a submenu of another is
435    /// exactly as it sounds.
436    /// ## `submenu`
437    /// a #GMenuModel, or [`None`]
438    #[doc(alias = "g_menu_item_set_submenu")]
439    pub fn set_submenu(&self, submenu: Option<&impl IsA<MenuModel>>) {
440        unsafe {
441            ffi::g_menu_item_set_submenu(
442                self.to_glib_none().0,
443                submenu.map(|p| p.as_ref()).to_glib_none().0,
444            );
445        }
446    }
447}