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}