1. ------------------------------------------------------------------------------ 
  2. --                                                                          -- 
  3. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  4. --                     Copyright (C) 2000-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. --  <description> 
  25. --  Glib.Menu_Model.Gmenu_Model represents the contents of a menu -- an 
  26. --  ordered list of menu items. The items are associated with actions, which 
  27. --  can be activated through them. Items can be grouped in sections, and may 
  28. --  have submenus associated with them. Both items and sections usually have 
  29. --  some representation data, such as labels or icons. The type of the 
  30. --  associated action (ie whether it is stateful, and what kind of state it 
  31. --  has) can influence the representation of the item. 
  32. -- 
  33. --  The conceptual model of menus in Glib.Menu_Model.Gmenu_Model is 
  34. --  hierarchical: sections and submenus are again represented by GMenu_Models. 
  35. --  Menus themselves do not define their own roles. Rather, the role of a 
  36. --  particular Glib.Menu_Model.Gmenu_Model is defined by the item that 
  37. --  references it (or, in the case of the 'root' menu, is defined by the 
  38. --  context in which it is used). 
  39. -- 
  40. --  As an example, consider the visible portions of the menu in <xref 
  41. --  linkend="menu-example"/>. 
  42. -- 
  43. --  <figure id="menu-example"> 
  44. --  == An example menu == 
  45. -- 
  46. --  <graphic fileref="menu-example.png" format="PNG"></graphic> </figure> 
  47. --  There are 8 "menus" visible in the screenshot: one menubar, two submenus 
  48. --  and 5 sections: 
  49. -- 
  50. --     * the toplevel menubar (containing 4 items) 
  51. -- 
  52. --     * the View submenu (containing 3 sections) 
  53. -- 
  54. --     * the first section of the View submenu (containing 2 items) 
  55. -- 
  56. --     * the second section of the View submenu (containing 1 item) 
  57. -- 
  58. --     * the final section of the View submenu (containing 1 item) 
  59. -- 
  60. --     * the Highlight Mode submenu (containing 2 sections) 
  61. -- 
  62. --     * the Sources section (containing 2 items) 
  63. -- 
  64. --     * the Markup section (containing 2 items) 
  65. -- 
  66. --  <xref linkend="menu-model"/> illustrates the conceptual connection between 
  67. --  these 8 menus. Each large block in the figure represents a menu and the 
  68. --  smaller blocks within the large block represent items in that menu. Some 
  69. --  items contain references to other menus. 
  70. --  <figure id="menu-model"> 
  71. --  == A menu model == 
  72. -- 
  73. --  <graphic fileref="menu-model.png" format="PNG"></graphic> </figure> 
  74. --  Notice that the separators visible in <xref linkend="menu-example"/> 
  75. --  appear nowhere in <xref linkend="menu-model"/>. This is because separators 
  76. --  are not explicitly represented in the menu model. Instead, a separator is 
  77. --  inserted between any two non-empty sections of a menu. Section items can 
  78. --  have labels just like any other item. In that case, a display system may 
  79. --  show a section header instead of a separator. 
  80. -- 
  81. --  The motivation for this abstract model of application controls is that 
  82. --  modern user interfaces tend to make these controls available outside the 
  83. --  application. Examples include global menus, jumplists, dash boards, etc. To 
  84. --  support such uses, it is necessary to 'export' information about actions 
  85. --  and their representation in menus, which is exactly what the <link 
  86. --  linkend="gio-GActionGroup-exporter">GActionGroup exporter</link> and the 
  87. --  <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link> do for 
  88. --  Glib.Action_Group.Gaction_Group and Glib.Menu_Model.Gmenu_Model. The 
  89. --  client-side counterparts to make use of the exported information are 
  90. --  Gdbus.Action_Group.Gdbus_Action_Group and 
  91. --  Gdbus.Menu_Model.Gdbus_Menu_Model. 
  92. -- 
  93. --  The API of Glib.Menu_Model.Gmenu_Model is very generic, with iterators for 
  94. --  the attributes and links of an item, see 
  95. --  Glib.Menu_Model.Iterate_Item_Attributes and 
  96. --  Glib.Menu_Model.Iterate_Item_Links. The 'standard' attributes and link 
  97. --  types have predefined names: G_MENU_ATTRIBUTE_LABEL, 
  98. --  G_MENU_ATTRIBUTE_ACTION, G_MENU_ATTRIBUTE_TARGET, G_MENU_LINK_SECTION and 
  99. --  G_MENU_LINK_SUBMENU. 
  100. -- 
  101. --  Items in a Glib.Menu_Model.Gmenu_Model represent active controls if they 
  102. --  refer to an action that can get activated when the user interacts with the 
  103. --  menu item. The reference to the action is encoded by the string id in the 
  104. --  G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely identifies an 
  105. --  action in an action group. Which action group(s) provide actions depends on 
  106. --  the context in which the menu model is used. E.g. when the model is 
  107. --  exported as the application menu of a Gtk.Application.Gtk_Application, 
  108. --  actions can be application-wide or window-specific (and thus come from two 
  109. --  different action groups). By convention, the application-wide actions have 
  110. --  names that start with "app.", while the names of window-specific actions 
  111. --  start with "win.". 
  112. -- 
  113. --  While a wide variety of stateful actions is possible, the following is the 
  114. --  minimum that is expected to be supported by all users of exported menu 
  115. --  information: 
  116. -- 
  117. --     * an action with no parameter type and no state 
  118. -- 
  119. --     * an action with no parameter type and boolean state 
  120. -- 
  121. --     * an action with string parameter type and string state 
  122. -- 
  123. --  <formalpara> 
  124. --  == Stateless == 
  125. -- 
  126. --  A stateless action typically corresponds to an ordinary menu item. 
  127. -- 
  128. --  Selecting such a menu item will activate the action (with no parameter). 
  129. -- 
  130. --  </formalpara> 
  131. --  <formalpara> 
  132. --  == Boolean State == 
  133. -- 
  134. --  An action with a boolean state will most typically be used with a "toggle" 
  135. --  or "switch" menu item. The state can be set directly, but activating the 
  136. --  action (with no parameter) results in the state being toggled. 
  137. -- 
  138. --  Selecting a toggle menu item will activate the action. The menu item 
  139. --  should be rendered as "checked" when the state is true. 
  140. -- 
  141. --  </formalpara> 
  142. --  <formalpara> 
  143. --  == String Parameter and State == 
  144. -- 
  145. --  Actions with string parameters and state will most typically be used to 
  146. --  represent an enumerated choice over the items available for a group of 
  147. --  radio menu items. Activating the action with a string parameter is 
  148. --  equivalent to setting that parameter as the state. 
  149. -- 
  150. --  Radio menu items, in addition to being associated with the action, will 
  151. --  have a target value. Selecting that menu item will result in activation of 
  152. --  the action with the target value as the parameter. The menu item should be 
  153. --  rendered as "selected" when the state of the action is equal to the target 
  154. --  value of the menu item. 
  155. -- 
  156. --  </formalpara> 
  157. --  </description> 
  158. pragma Ada_2005; 
  159.  
  160. pragma Warnings (Off, "*is already use-visible*"); 
  161. with Glib;         use Glib; 
  162. with Glib.Object;  use Glib.Object; 
  163. with Glib.Variant; use Glib.Variant; 
  164.  
  165. package Glib.Menu_Model is 
  166.  
  167.    type Gmenu_Model_Record is new GObject_Record with null record; 
  168.    type Gmenu_Model is access all Gmenu_Model_Record'Class; 
  169.  
  170.    type Gmenu_Attribute_Iter_Record is new GObject_Record with null record; 
  171.    type Gmenu_Attribute_Iter is access all Gmenu_Attribute_Iter_Record'Class; 
  172.  
  173.    type Gmenu_Link_Iter_Record is new GObject_Record with null record; 
  174.    type Gmenu_Link_Iter is access all Gmenu_Link_Iter_Record'Class; 
  175.  
  176.    ------------------ 
  177.    -- Constructors -- 
  178.    ------------------ 
  179.  
  180.    function Get_Type_Menu_Model return Glib.GType; 
  181.    pragma Import (C, Get_Type_Menu_Model, "g_menu_model_get_type"); 
  182.  
  183.    function Get_Type_Menu_Attribute_Iter return Glib.GType; 
  184.    pragma Import (C, Get_Type_Menu_Attribute_Iter, "g_menu_attribute_iter_get_type"); 
  185.  
  186.    function Get_Type_Menu_Link_Iter return Glib.GType; 
  187.    pragma Import (C, Get_Type_Menu_Link_Iter, "g_menu_link_iter_get_type"); 
  188.  
  189.    ------------- 
  190.    -- Methods -- 
  191.    ------------- 
  192.  
  193.    function Get_Item_Attribute_Value 
  194.       (Self          : not null access Gmenu_Model_Record; 
  195.        Item_Index    : Gint; 
  196.        Attribute     : UTF8_String; 
  197.        Expected_Type : Glib.Variant.Gvariant_Type) 
  198.        return Glib.Variant.Gvariant; 
  199.    --  Queries the item at position Item_Index in Model for the attribute 
  200.    --  specified by Attribute. 
  201.    --  If Expected_Type is non-null then it specifies the expected type of the 
  202.    --  attribute. If it is null then any type will be accepted. 
  203.    --  If the attribute exists and matches Expected_Type (or if the expected 
  204.    --  type is unspecified) then the value is returned. 
  205.    --  If the attribute does not exist, or does not match the expected type 
  206.    --  then null is returned. 
  207.    --  Since: gtk+ 2.32 
  208.    --  "item_index": the index of the item 
  209.    --  "attribute": the attribute to query 
  210.    --  "expected_type": the expected type of the attribute, or null 
  211.  
  212.    function Get_Item_Link 
  213.       (Self       : not null access Gmenu_Model_Record; 
  214.        Item_Index : Gint; 
  215.        Link       : UTF8_String) return Gmenu_Model; 
  216.    --  Queries the item at position Item_Index in Model for the link specified 
  217.    --  by Link. 
  218.    --  If the link exists, the linked Glib.Menu_Model.Gmenu_Model is returned. 
  219.    --  If the link does not exist, null is returned. 
  220.    --  Since: gtk+ 2.32 
  221.    --  "item_index": the index of the item 
  222.    --  "link": the link to query 
  223.  
  224.    function Get_N_Items 
  225.       (Self : not null access Gmenu_Model_Record) return Gint; 
  226.    --  Query the number of items in Model. 
  227.    --  Since: gtk+ 2.32 
  228.  
  229.    function Is_Mutable 
  230.       (Self : not null access Gmenu_Model_Record) return Boolean; 
  231.    --  Queries if Model is mutable. 
  232.    --  An immutable Glib.Menu_Model.Gmenu_Model will never emit the 
  233.    --  Glib.Menu_Model.Gmenu_Model::items-changed signal. Consumers of the 
  234.    --  model may make optimisations accordingly. 
  235.    --  Since: gtk+ 2.32 
  236.  
  237.    procedure Items_Changed 
  238.       (Self     : not null access Gmenu_Model_Record; 
  239.        Position : Gint; 
  240.        Removed  : Gint; 
  241.        Added    : Gint); 
  242.    --  Requests emission of the Glib.Menu_Model.Gmenu_Model::items-changed 
  243.    --  signal on Model. 
  244.    --  This function should never be called except by 
  245.    --  Glib.Menu_Model.Gmenu_Model subclasses. Any other calls to this function 
  246.    --  will very likely lead to a violation of the interface of the model. 
  247.    --  The implementation should update its internal representation of the 
  248.    --  menu before emitting the signal. The implementation should further 
  249.    --  expect to receive queries about the new state of the menu (and 
  250.    --  particularly added menu items) while signal handlers are running. 
  251.    --  The implementation must dispatch this call directly from a mainloop 
  252.    --  entry and not in response to calls -- particularly those from the 
  253.    --  Glib.Menu_Model.Gmenu_Model API. Said another way: the menu must not 
  254.    --  change while user code is running without returning to the mainloop. 
  255.    --  Since: gtk+ 2.32 
  256.    --  "position": the position of the change 
  257.    --  "removed": the number of items removed 
  258.    --  "added": the number of items added 
  259.  
  260.    function Iterate_Item_Attributes 
  261.       (Self       : not null access Gmenu_Model_Record; 
  262.        Item_Index : Gint) return Gmenu_Attribute_Iter; 
  263.    --  Creates a Glib.Menu_Model.Gmenu_Attribute_Iter to iterate over the 
  264.    --  attributes of the item at position Item_Index in Model. 
  265.    --  You must free the iterator with g_object_unref when you are done. 
  266.    --  Since: gtk+ 2.32 
  267.    --  "item_index": the index of the item 
  268.  
  269.    function Iterate_Item_Links 
  270.       (Self       : not null access Gmenu_Model_Record; 
  271.        Item_Index : Gint) return Gmenu_Link_Iter; 
  272.    --  Creates a Glib.Menu_Model.Gmenu_Link_Iter to iterate over the links of 
  273.    --  the item at position Item_Index in Model. 
  274.    --  You must free the iterator with g_object_unref when you are done. 
  275.    --  Since: gtk+ 2.32 
  276.    --  "item_index": the index of the item 
  277.  
  278.    function Get_Name 
  279.       (Self : not null access Gmenu_Attribute_Iter_Record) 
  280.        return UTF8_String; 
  281.    --  Gets the name of the attribute at the current iterator position, as a 
  282.    --  string. 
  283.    --  The iterator is not advanced. 
  284.    --  Since: gtk+ 2.32 
  285.  
  286.    function Get_Name 
  287.       (Self : not null access Gmenu_Link_Iter_Record) return UTF8_String; 
  288.    --  Gets the name of the link at the current iterator position. 
  289.    --  The iterator is not advanced. 
  290.    --  Since: gtk+ 2.32 
  291.  
  292.    function Get_Value 
  293.       (Self : not null access Gmenu_Attribute_Iter_Record) 
  294.        return Glib.Variant.Gvariant; 
  295.    --  Gets the value of the attribute at the current iterator position. 
  296.    --  The iterator is not advanced. 
  297.    --  Since: gtk+ 2.32 
  298.  
  299.    function Get_Value 
  300.       (Self : not null access Gmenu_Link_Iter_Record) return Gmenu_Model; 
  301.    --  Gets the linked Glib.Menu_Model.Gmenu_Model at the current iterator 
  302.    --  position. 
  303.    --  The iterator is not advanced. 
  304.    --  Since: gtk+ 2.32 
  305.  
  306.    function Next 
  307.       (Self : not null access Gmenu_Attribute_Iter_Record) return Boolean; 
  308.    --  Attempts to advance the iterator to the next (possibly first) 
  309.    --  attribute. 
  310.    --  True is returned on success, or False if there are no more attributes. 
  311.    --  You must call this function when you first acquire the iterator to 
  312.    --  advance it to the first attribute (and determine if the first attribute 
  313.    --  exists at all). 
  314.    --  Since: gtk+ 2.32 
  315.  
  316.    function Next 
  317.       (Self : not null access Gmenu_Link_Iter_Record) return Boolean; 
  318.    --  Attempts to advance the iterator to the next (possibly first) link. 
  319.    --  True is returned on success, or False if there are no more links. 
  320.    --  You must call this function when you first acquire the iterator to 
  321.    --  advance it to the first link (and determine if the first link exists at 
  322.    --  all). 
  323.    --  Since: gtk+ 2.32 
  324.  
  325.    ------------- 
  326.    -- Signals -- 
  327.    ------------- 
  328.  
  329.    type Cb_Gmenu_Model_Gint_Gint_Gint_Void is not null access procedure 
  330.      (Self     : access Gmenu_Model_Record'Class; 
  331.       Position : Gint; 
  332.       Removed  : Gint; 
  333.       Added    : Gint); 
  334.  
  335.    type Cb_GObject_Gint_Gint_Gint_Void is not null access procedure 
  336.      (Self     : access Glib.Object.GObject_Record'Class; 
  337.       Position : Gint; 
  338.       Removed  : Gint; 
  339.       Added    : Gint); 
  340.  
  341.    Signal_Items_Changed : constant Glib.Signal_Name := "items-changed"; 
  342.    procedure On_Items_Changed 
  343.       (Self  : not null access Gmenu_Model_Record; 
  344.        Call  : Cb_Gmenu_Model_Gint_Gint_Gint_Void; 
  345.        After : Boolean := False); 
  346.    procedure On_Items_Changed 
  347.       (Self  : not null access Gmenu_Model_Record; 
  348.        Call  : Cb_GObject_Gint_Gint_Gint_Void; 
  349.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  350.        After : Boolean := False); 
  351.    --  Emitted when a change has occured to the menu. 
  352.    -- 
  353.    --  The only changes that can occur to a menu is that items are removed or 
  354.    --  added. Items may not change (except by being removed and added back in 
  355.    --  the same location). This signal is capable of describing both of those 
  356.    --  changes (at the same time). 
  357.    -- 
  358.    --  The signal means that starting at the index Position, Removed items 
  359.    --  were removed and Added items were added in their place. If Removed is 
  360.    --  zero then only items were added. If Added is zero then only items were 
  361.    --  removed. 
  362.    -- 
  363.    --  As an example, if the menu contains items a, b, c, d (in that order) 
  364.    --  and the signal (2, 1, 3) occurs then the new composition of the menu 
  365.    --  will be a, b, _, _, _, d (with each _ representing some new item). 
  366.    -- 
  367.    --  Signal handlers may query the model (particularly the added items) and 
  368.    --  expect to see the results of the modification that is being reported. 
  369.    --  The signal is emitted after the modification. 
  370.    --  
  371.    --  Callback parameters: 
  372.    --    --  "position": the position of the change 
  373.    --    --  "removed": the number of items removed 
  374.    --    --  "added": the number of items added 
  375.  
  376. end Glib.Menu_Model;