1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{MenuAttributeIter, MenuLinkIter};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::{boxed::Box as Box_, fmt, mem::transmute};

glib::wrapper! {
    /// [`MenuModel`][crate::MenuModel] represents the contents of a menu -- an ordered list of
    /// menu items. The items are associated with actions, which can be
    /// activated through them. Items can be grouped in sections, and may
    /// have submenus associated with them. Both items and sections usually
    /// have some representation data, such as labels or icons. The type of
    /// the associated action (ie whether it is stateful, and what kind of
    /// state it has) can influence the representation of the item.
    ///
    /// The conceptual model of menus in [`MenuModel`][crate::MenuModel] is hierarchical:
    /// sections and submenus are again represented by `GMenuModels`.
    /// Menus themselves do not define their own roles. Rather, the role
    /// of a particular [`MenuModel`][crate::MenuModel] is defined by the item that references
    /// it (or, in the case of the 'root' menu, is defined by the context
    /// in which it is used).
    ///
    /// As an example, consider the visible portions of this menu:
    ///
    /// ## An example menu # {`menu`-example}
    ///
    /// ![](menu-example.png)
    ///
    /// There are 8 "menus" visible in the screenshot: one menubar, two
    /// submenus and 5 sections:
    ///
    /// - the toplevel menubar (containing 4 items)
    /// - the View submenu (containing 3 sections)
    /// - the first section of the View submenu (containing 2 items)
    /// - the second section of the View submenu (containing 1 item)
    /// - the final section of the View submenu (containing 1 item)
    /// - the Highlight Mode submenu (containing 2 sections)
    /// - the Sources section (containing 2 items)
    /// - the Markup section (containing 2 items)
    ///
    /// The [example][menu-model] illustrates the conceptual connection between
    /// these 8 menus. Each large block in the figure represents a menu and the
    /// smaller blocks within the large block represent items in that menu. Some
    /// items contain references to other menus.
    ///
    /// ## A menu example # {`menu`-model}
    ///
    /// ![](menu-model.png)
    ///
    /// Notice that the separators visible in the [example][menu-example]
    /// appear nowhere in the [menu model][menu-model]. This is because
    /// separators are not explicitly represented in the menu model. Instead,
    /// a separator is inserted between any two non-empty sections of a menu.
    /// Section items can have labels just like any other item. In that case,
    /// a display system may show a section header instead of a separator.
    ///
    /// The motivation for this abstract model of application controls is
    /// that modern user interfaces tend to make these controls available
    /// outside the application. Examples include global menus, jumplists,
    /// dash boards, etc. To support such uses, it is necessary to 'export'
    /// information about actions and their representation in menus, which
    /// is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter]
    /// and the [GMenuModel exporter][gio-GMenuModel-exporter] do for
    /// [`ActionGroup`][crate::ActionGroup] and [`MenuModel`][crate::MenuModel]. The client-side counterparts to
    /// make use of the exported information are [`DBusActionGroup`][crate::DBusActionGroup] and
    /// [`DBusMenuModel`][crate::DBusMenuModel].
    ///
    /// The API of [`MenuModel`][crate::MenuModel] is very generic, with iterators for the
    /// attributes and links of an item, see [`MenuModelExt::iterate_item_attributes()`][crate::prelude::MenuModelExt::iterate_item_attributes()]
    /// and [`MenuModelExt::iterate_item_links()`][crate::prelude::MenuModelExt::iterate_item_links()]. The 'standard' attributes and
    /// link types have predefined names: [`MENU_ATTRIBUTE_LABEL`][crate::MENU_ATTRIBUTE_LABEL],
    /// [`MENU_ATTRIBUTE_ACTION`][crate::MENU_ATTRIBUTE_ACTION], [`MENU_ATTRIBUTE_TARGET`][crate::MENU_ATTRIBUTE_TARGET], [`MENU_LINK_SECTION`][crate::MENU_LINK_SECTION]
    /// and [`MENU_LINK_SUBMENU`][crate::MENU_LINK_SUBMENU].
    ///
    /// Items in a [`MenuModel`][crate::MenuModel] represent active controls if they refer to
    /// an action that can get activated when the user interacts with the
    /// menu item. The reference to the action is encoded by the string id
    /// in the [`MENU_ATTRIBUTE_ACTION`][crate::MENU_ATTRIBUTE_ACTION] attribute. An action id uniquely
    /// identifies an action in an action group. Which action group(s) provide
    /// actions depends on the context in which the menu model is used.
    /// E.g. when the model is exported as the application menu of a
    /// `GtkApplication`, actions can be application-wide or window-specific
    /// (and thus come from two different action groups). By convention, the
    /// application-wide actions have names that start with "app.", while the
    /// names of window-specific actions start with "win.".
    ///
    /// While a wide variety of stateful actions is possible, the following
    /// is the minimum that is expected to be supported by all users of exported
    /// menu information:
    /// - an action with no parameter type and no state
    /// - an action with no parameter type and boolean state
    /// - an action with string parameter type and string state
    ///
    /// ## Stateless
    ///
    /// A stateless action typically corresponds to an ordinary menu item.
    ///
    /// Selecting such a menu item will activate the action (with no parameter).
    ///
    /// ## Boolean State
    ///
    /// An action with a boolean state will most typically be used with a "toggle"
    /// or "switch" menu item. The state can be set directly, but activating the
    /// action (with no parameter) results in the state being toggled.
    ///
    /// Selecting a toggle menu item will activate the action. The menu item should
    /// be rendered as "checked" when the state is true.
    ///
    /// ## String Parameter and State
    ///
    /// Actions with string parameters and state will most typically be used to
    /// represent an enumerated choice over the items available for a group of
    /// radio menu items. Activating the action with a string parameter is
    /// equivalent to setting that parameter as the state.
    ///
    /// Radio menu items, in addition to being associated with the action, will
    /// have a target value. Selecting that menu item will result in activation
    /// of the action with the target value as the parameter. The menu item should
    /// be rendered as "selected" when the state of the action is equal to the
    /// target value of the menu item.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Signals
    ///
    ///
    /// #### `items-changed`
    ///  Emitted when a change has occurred to the menu.
    ///
    /// The only changes that can occur to a menu is that items are removed
    /// or added. Items may not change (except by being removed and added
    /// back in the same location). This signal is capable of describing
    /// both of those changes (at the same time).
    ///
    /// The signal means that starting at the index `position`, `removed`
    /// items were removed and `added` items were added in their place. If
    /// `removed` is zero then only items were added. If `added` is zero
    /// then only items were removed.
    ///
    /// As an example, if the menu contains items a, b, c, d (in that
    /// order) and the signal (2, 1, 3) occurs then the new composition of
    /// the menu will be a, b, _, _, _, d (with each _ representing some
    /// new item).
    ///
    /// Signal handlers may query the model (particularly the added items)
    /// and expect to see the results of the modification that is being
    /// reported. The signal is emitted after the modification.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`MenuModelExt`][trait@crate::prelude::MenuModelExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GMenuModel")]
    pub struct MenuModel(Object<ffi::GMenuModel, ffi::GMenuModelClass>);

    match fn {
        type_ => || ffi::g_menu_model_get_type(),
    }
}

impl MenuModel {
    pub const NONE: Option<&'static MenuModel> = None;
}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::MenuModel>> Sealed for T {}
}

/// Trait containing all [`struct@MenuModel`] methods.
///
/// # Implementors
///
/// [`DBusMenuModel`][struct@crate::DBusMenuModel], [`MenuModel`][struct@crate::MenuModel], [`Menu`][struct@crate::Menu]
pub trait MenuModelExt: IsA<MenuModel> + sealed::Sealed + 'static {
    //#[doc(alias = "g_menu_model_get_item_attribute")]
    //#[doc(alias = "get_item_attribute")]
    //fn is_item_attribute(&self, item_index: i32, attribute: &str, format_string: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> bool {
    //    unsafe { TODO: call ffi:g_menu_model_get_item_attribute() }
    //}

    /// Queries the item at position `item_index` in `self` for the attribute
    /// specified by `attribute`.
    ///
    /// If `expected_type` is non-[`None`] then it specifies the expected type of
    /// the attribute. If it is [`None`] then any type will be accepted.
    ///
    /// If the attribute exists and matches `expected_type` (or if the
    /// expected type is unspecified) then the value is returned.
    ///
    /// If the attribute does not exist, or does not match the expected type
    /// then [`None`] is returned.
    /// ## `item_index`
    /// the index of the item
    /// ## `attribute`
    /// the attribute to query
    /// ## `expected_type`
    /// the expected type of the attribute, or
    ///  [`None`]
    ///
    /// # Returns
    ///
    /// the value of the attribute
    #[doc(alias = "g_menu_model_get_item_attribute_value")]
    #[doc(alias = "get_item_attribute_value")]
    fn item_attribute_value(
        &self,
        item_index: i32,
        attribute: &str,
        expected_type: Option<&glib::VariantTy>,
    ) -> Option<glib::Variant> {
        unsafe {
            from_glib_full(ffi::g_menu_model_get_item_attribute_value(
                self.as_ref().to_glib_none().0,
                item_index,
                attribute.to_glib_none().0,
                expected_type.to_glib_none().0,
            ))
        }
    }

    /// Queries the item at position `item_index` in `self` for the link
    /// specified by `link`.
    ///
    /// If the link exists, the linked [`MenuModel`][crate::MenuModel] is returned. If the link
    /// does not exist, [`None`] is returned.
    /// ## `item_index`
    /// the index of the item
    /// ## `link`
    /// the link to query
    ///
    /// # Returns
    ///
    /// the linked [`MenuModel`][crate::MenuModel], or [`None`]
    #[doc(alias = "g_menu_model_get_item_link")]
    #[doc(alias = "get_item_link")]
    #[must_use]
    fn item_link(&self, item_index: i32, link: &str) -> Option<MenuModel> {
        unsafe {
            from_glib_full(ffi::g_menu_model_get_item_link(
                self.as_ref().to_glib_none().0,
                item_index,
                link.to_glib_none().0,
            ))
        }
    }

    /// Query the number of items in `self`.
    ///
    /// # Returns
    ///
    /// the number of items
    #[doc(alias = "g_menu_model_get_n_items")]
    #[doc(alias = "get_n_items")]
    fn n_items(&self) -> i32 {
        unsafe { ffi::g_menu_model_get_n_items(self.as_ref().to_glib_none().0) }
    }

    /// Queries if `self` is mutable.
    ///
    /// An immutable [`MenuModel`][crate::MenuModel] will never emit the [`items-changed`][struct@crate::MenuModel#items-changed]
    /// signal. Consumers of the model may make optimisations accordingly.
    ///
    /// # Returns
    ///
    /// [`true`] if the model is mutable (ie: "items-changed" may be
    ///  emitted).
    #[doc(alias = "g_menu_model_is_mutable")]
    fn is_mutable(&self) -> bool {
        unsafe { from_glib(ffi::g_menu_model_is_mutable(self.as_ref().to_glib_none().0)) }
    }

    /// Requests emission of the [`items-changed`][struct@crate::MenuModel#items-changed] signal on `self`.
    ///
    /// This function should never be called except by [`MenuModel`][crate::MenuModel]
    /// subclasses. Any other calls to this function will very likely lead
    /// to a violation of the interface of the model.
    ///
    /// The implementation should update its internal representation of the
    /// menu before emitting the signal. The implementation should further
    /// expect to receive queries about the new state of the menu (and
    /// particularly added menu items) while signal handlers are running.
    ///
    /// The implementation must dispatch this call directly from a mainloop
    /// entry and not in response to calls -- particularly those from the
    /// [`MenuModel`][crate::MenuModel] API. Said another way: the menu must not change while
    /// user code is running without returning to the mainloop.
    /// ## `position`
    /// the position of the change
    /// ## `removed`
    /// the number of items removed
    /// ## `added`
    /// the number of items added
    #[doc(alias = "g_menu_model_items_changed")]
    fn items_changed(&self, position: i32, removed: i32, added: i32) {
        unsafe {
            ffi::g_menu_model_items_changed(
                self.as_ref().to_glib_none().0,
                position,
                removed,
                added,
            );
        }
    }

    /// Creates a [`MenuAttributeIter`][crate::MenuAttributeIter] to iterate over the attributes of
    /// the item at position `item_index` in `self`.
    ///
    /// You must free the iterator with `g_object_unref()` when you are done.
    /// ## `item_index`
    /// the index of the item
    ///
    /// # Returns
    ///
    /// a new [`MenuAttributeIter`][crate::MenuAttributeIter]
    #[doc(alias = "g_menu_model_iterate_item_attributes")]
    fn iterate_item_attributes(&self, item_index: i32) -> MenuAttributeIter {
        unsafe {
            from_glib_full(ffi::g_menu_model_iterate_item_attributes(
                self.as_ref().to_glib_none().0,
                item_index,
            ))
        }
    }

    /// Creates a [`MenuLinkIter`][crate::MenuLinkIter] to iterate over the links of the item at
    /// position `item_index` in `self`.
    ///
    /// You must free the iterator with `g_object_unref()` when you are done.
    /// ## `item_index`
    /// the index of the item
    ///
    /// # Returns
    ///
    /// a new [`MenuLinkIter`][crate::MenuLinkIter]
    #[doc(alias = "g_menu_model_iterate_item_links")]
    fn iterate_item_links(&self, item_index: i32) -> MenuLinkIter {
        unsafe {
            from_glib_full(ffi::g_menu_model_iterate_item_links(
                self.as_ref().to_glib_none().0,
                item_index,
            ))
        }
    }

    /// Emitted when a change has occurred to the menu.
    ///
    /// The only changes that can occur to a menu is that items are removed
    /// or added. Items may not change (except by being removed and added
    /// back in the same location). This signal is capable of describing
    /// both of those changes (at the same time).
    ///
    /// The signal means that starting at the index `position`, `removed`
    /// items were removed and `added` items were added in their place. If
    /// `removed` is zero then only items were added. If `added` is zero
    /// then only items were removed.
    ///
    /// As an example, if the menu contains items a, b, c, d (in that
    /// order) and the signal (2, 1, 3) occurs then the new composition of
    /// the menu will be a, b, _, _, _, d (with each _ representing some
    /// new item).
    ///
    /// Signal handlers may query the model (particularly the added items)
    /// and expect to see the results of the modification that is being
    /// reported. The signal is emitted after the modification.
    /// ## `position`
    /// the position of the change
    /// ## `removed`
    /// the number of items removed
    /// ## `added`
    /// the number of items added
    #[doc(alias = "items-changed")]
    fn connect_items_changed<F: Fn(&Self, i32, i32, i32) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn items_changed_trampoline<
            P: IsA<MenuModel>,
            F: Fn(&P, i32, i32, i32) + 'static,
        >(
            this: *mut ffi::GMenuModel,
            position: libc::c_int,
            removed: libc::c_int,
            added: libc::c_int,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                MenuModel::from_glib_borrow(this).unsafe_cast_ref(),
                position,
                removed,
                added,
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"items-changed\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    items_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<MenuModel>> MenuModelExt for O {}

impl fmt::Display for MenuModel {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("MenuModel")
    }
}