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.Action_Group.Gaction_Group represents a group of actions. Actions can 
  26. --  be used to expose functionality in a structured way, either from one part 
  27. --  of a program to another, or to the outside world. Action groups are often 
  28. --  used together with a Glib.Menu_Model.Gmenu_Model that provides additional 
  29. --  representation data for displaying the actions to the user, e.g. in a menu. 
  30. -- 
  31. --  The main way to interact with the actions in a GActionGroup is to activate 
  32. --  them with Glib.Action_Group.Activate_Action. Activating an action may 
  33. --  require a Glib.Variant.Gvariant parameter. The required type of the 
  34. --  parameter can be inquired with Glib.Action_Group.Get_Action_Parameter_Type. 
  35. --  Actions may be disabled, see Glib.Action_Group.Get_Action_Enabled. 
  36. --  Activating a disabled action has no effect. 
  37. -- 
  38. --  Actions may optionally have a state in the form of a 
  39. --  Glib.Variant.Gvariant. The current state of an action can be inquired with 
  40. --  Glib.Action_Group.Get_Action_State. Activating a stateful action may change 
  41. --  its state, but it is also possible to set the state by calling 
  42. --  Glib.Action_Group.Change_Action_State. 
  43. -- 
  44. --  As typical example, consider a text editing application which has an 
  45. --  option to change the current font to 'bold'. A good way to represent this 
  46. --  would be a stateful action, with a boolean state. Activating the action 
  47. --  would toggle the state. 
  48. -- 
  49. --  Each action in the group has a unique name (which is a string). All method 
  50. --  calls, except Glib.Action_Group.List_Actions take the name of an action as 
  51. --  an argument. 
  52. -- 
  53. --  The Glib.Action_Group.Gaction_Group API is meant to be the 'public' API to 
  54. --  the action group. The calls here are exactly the interaction that 'external 
  55. --  forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have with 
  56. --  actions. 'Internal' APIs (ie: ones meant only to be accessed by the action 
  57. --  group implementation) are found on subclasses. This is why you will find - 
  58. --  for example - Glib.Action_Group.Get_Action_Enabled but not an equivalent 
  59. --  <function>set</function> call. 
  60. -- 
  61. --  Signals are emitted on the action group in response to state changes on 
  62. --  individual actions. 
  63. -- 
  64. --  Implementations of Glib.Action_Group.Gaction_Group should provide 
  65. --  implementations for the virtual functions Glib.Action_Group.List_Actions 
  66. --  and Glib.Action_Group.Query_Action. The other virtual functions should not 
  67. --  be implemented - their "wrappers" are actually implemented with calls to 
  68. --  Glib.Action_Group.Query_Action. 
  69. -- 
  70. --  </description> 
  71. pragma Ada_2005; 
  72.  
  73. pragma Warnings (Off, "*is already use-visible*"); 
  74. with GNAT.Strings; use GNAT.Strings; 
  75. with Glib;         use Glib; 
  76. with Glib.Object;  use Glib.Object; 
  77. with Glib.Types;   use Glib.Types; 
  78. with Glib.Variant; use Glib.Variant; 
  79.  
  80. package Glib.Action_Group is 
  81.  
  82.    type Gaction_Group is new Glib.Types.GType_Interface; 
  83.    Null_Gaction_Group : constant Gaction_Group; 
  84.  
  85.    ------------------ 
  86.    -- Constructors -- 
  87.    ------------------ 
  88.  
  89.    function Get_Type return Glib.GType; 
  90.    pragma Import (C, Get_Type, "g_action_group_get_type"); 
  91.  
  92.    ------------- 
  93.    -- Methods -- 
  94.    ------------- 
  95.  
  96.    procedure Action_Added (Self : Gaction_Group; Action_Name : UTF8_String); 
  97.    --  Emits the Glib.Action_Group.Gaction_Group::action-added signal on 
  98.    --  Action_Group. 
  99.    --  This function should only be called by Glib.Action_Group.Gaction_Group 
  100.    --  implementations. 
  101.    --  Since: gtk+ 2.28 
  102.    --  "action_name": the name of an action in the group 
  103.  
  104.    procedure Action_Enabled_Changed 
  105.       (Self        : Gaction_Group; 
  106.        Action_Name : UTF8_String; 
  107.        Enabled     : Boolean); 
  108.    --  Emits the Glib.Action_Group.Gaction_Group::action-enabled-changed 
  109.    --  signal on Action_Group. 
  110.    --  This function should only be called by Glib.Action_Group.Gaction_Group 
  111.    --  implementations. 
  112.    --  Since: gtk+ 2.28 
  113.    --  "action_name": the name of an action in the group 
  114.    --  "enabled": whether or not the action is now enabled 
  115.  
  116.    procedure Action_Removed 
  117.       (Self        : Gaction_Group; 
  118.        Action_Name : UTF8_String); 
  119.    --  Emits the Glib.Action_Group.Gaction_Group::action-removed signal on 
  120.    --  Action_Group. 
  121.    --  This function should only be called by Glib.Action_Group.Gaction_Group 
  122.    --  implementations. 
  123.    --  Since: gtk+ 2.28 
  124.    --  "action_name": the name of an action in the group 
  125.  
  126.    procedure Action_State_Changed 
  127.       (Self        : Gaction_Group; 
  128.        Action_Name : UTF8_String; 
  129.        State       : Glib.Variant.Gvariant); 
  130.    --  Emits the Glib.Action_Group.Gaction_Group::action-state-changed signal 
  131.    --  on Action_Group. 
  132.    --  This function should only be called by Glib.Action_Group.Gaction_Group 
  133.    --  implementations. 
  134.    --  Since: gtk+ 2.28 
  135.    --  "action_name": the name of an action in the group 
  136.    --  "state": the new state of the named action 
  137.  
  138.    procedure Activate_Action 
  139.       (Self        : Gaction_Group; 
  140.        Action_Name : UTF8_String; 
  141.        Parameter   : Glib.Variant.Gvariant); 
  142.    --  Activate the named action within Action_Group. 
  143.    --  If the action is expecting a parameter, then the correct type of 
  144.    --  parameter must be given as Parameter. If the action is expecting no 
  145.    --  parameters then Parameter must be null. See 
  146.    --  Glib.Action_Group.Get_Action_Parameter_Type. 
  147.    --  Since: gtk+ 2.28 
  148.    --  "action_name": the name of the action to activate 
  149.    --  "parameter": parameters to the activation 
  150.  
  151.    procedure Change_Action_State 
  152.       (Self        : Gaction_Group; 
  153.        Action_Name : UTF8_String; 
  154.        Value       : Glib.Variant.Gvariant); 
  155.    --  Request for the state of the named action within Action_Group to be 
  156.    --  changed to Value. 
  157.    --  The action must be stateful and Value must be of the correct type. See 
  158.    --  Glib.Action_Group.Get_Action_State_Type. 
  159.    --  This call merely requests a change. The action may refuse to change its 
  160.    --  state or may change its state to something other than Value. See 
  161.    --  Glib.Action_Group.Get_Action_State_Hint. 
  162.    --  If the Value GVariant is floating, it is consumed. 
  163.    --  Since: gtk+ 2.28 
  164.    --  "action_name": the name of the action to request the change on 
  165.    --  "value": the new state 
  166.  
  167.    function Get_Action_Enabled 
  168.       (Self        : Gaction_Group; 
  169.        Action_Name : UTF8_String) return Boolean; 
  170.    --  Checks if the named action within Action_Group is currently enabled. 
  171.    --  An action must be enabled in order to be activated or in order to have 
  172.    --  its state changed from outside callers. 
  173.    --  Since: gtk+ 2.28 
  174.    --  "action_name": the name of the action to query 
  175.  
  176.    function Get_Action_Parameter_Type 
  177.       (Self        : Gaction_Group; 
  178.        Action_Name : UTF8_String) return Glib.Variant.Gvariant_Type; 
  179.    --  Queries the type of the parameter that must be given when activating 
  180.    --  the named action within Action_Group. 
  181.    --  When activating the action using Glib.Action_Group.Activate_Action, the 
  182.    --  Glib.Variant.Gvariant given to that function must be of the type 
  183.    --  returned by this function. 
  184.    --  In the case that this function returns null, you must not give any 
  185.    --  Glib.Variant.Gvariant, but null instead. 
  186.    --  The parameter type of a particular action will never change but it is 
  187.    --  possible for an action to be removed and for a new action to be added 
  188.    --  with the same name but a different parameter type. 
  189.    --  Since: gtk+ 2.28 
  190.    --  "action_name": the name of the action to query 
  191.  
  192.    function Get_Action_State 
  193.       (Self        : Gaction_Group; 
  194.        Action_Name : UTF8_String) return Glib.Variant.Gvariant; 
  195.    --  Queries the current state of the named action within Action_Group. 
  196.    --  If the action is not stateful then null will be returned. If the action 
  197.    --  is stateful then the type of the return value is the type given by 
  198.    --  Glib.Action_Group.Get_Action_State_Type. 
  199.    --  The return value (if non-null) should be freed with Glib.Variant.Unref 
  200.    --  when it is no longer required. 
  201.    --  Since: gtk+ 2.28 
  202.    --  "action_name": the name of the action to query 
  203.  
  204.    function Get_Action_State_Hint 
  205.       (Self        : Gaction_Group; 
  206.        Action_Name : UTF8_String) return Glib.Variant.Gvariant; 
  207.    --  Requests a hint about the valid range of values for the state of the 
  208.    --  named action within Action_Group. 
  209.    --  If null is returned it either means that the action is not stateful or 
  210.    --  that there is no hint about the valid range of values for the state of 
  211.    --  the action. 
  212.    --  If a Glib.Variant.Gvariant array is returned then each item in the 
  213.    --  array is a possible value for the state. If a Glib.Variant.Gvariant pair 
  214.    --  (ie: two-tuple) is returned then the tuple specifies the inclusive lower 
  215.    --  and upper bound of valid values for the state. 
  216.    --  In any case, the information is merely a hint. It may be possible to 
  217.    --  have a state value outside of the hinted range and setting a value 
  218.    --  within the range may fail. 
  219.    --  The return value (if non-null) should be freed with Glib.Variant.Unref 
  220.    --  when it is no longer required. 
  221.    --  Since: gtk+ 2.28 
  222.    --  "action_name": the name of the action to query 
  223.  
  224.    function Get_Action_State_Type 
  225.       (Self        : Gaction_Group; 
  226.        Action_Name : UTF8_String) return Glib.Variant.Gvariant_Type; 
  227.    --  Queries the type of the state of the named action within Action_Group. 
  228.    --  If the action is stateful then this function returns the 
  229.    --  Glib.Variant.Gvariant_Type of the state. All calls to 
  230.    --  Glib.Action_Group.Change_Action_State must give a Glib.Variant.Gvariant 
  231.    --  of this type and Glib.Action_Group.Get_Action_State will return a 
  232.    --  Glib.Variant.Gvariant of the same type. 
  233.    --  If the action is not stateful then this function will return null. In 
  234.    --  that case, Glib.Action_Group.Get_Action_State will return null and you 
  235.    --  must not call Glib.Action_Group.Change_Action_State. 
  236.    --  The state type of a particular action will never change but it is 
  237.    --  possible for an action to be removed and for a new action to be added 
  238.    --  with the same name but a different state type. 
  239.    --  Since: gtk+ 2.28 
  240.    --  "action_name": the name of the action to query 
  241.  
  242.    function Has_Action 
  243.       (Self        : Gaction_Group; 
  244.        Action_Name : UTF8_String) return Boolean; 
  245.    --  Checks if the named action exists within Action_Group. 
  246.    --  Since: gtk+ 2.28 
  247.    --  "action_name": the name of the action to check for 
  248.  
  249.    function List_Actions 
  250.       (Self : Gaction_Group) return GNAT.Strings.String_List; 
  251.    --  Lists the actions contained within Action_Group. 
  252.    --  The caller is responsible for freeing the list with g_strfreev when it 
  253.    --  is no longer required. 
  254.    --  Since: gtk+ 2.28 
  255.  
  256.    function Query_Action 
  257.       (Self           : Gaction_Group; 
  258.        Action_Name    : UTF8_String; 
  259.        Enabled        : access Boolean; 
  260.        Parameter_Type : access Glib.Variant.Gvariant_Type; 
  261.        State_Type     : access Glib.Variant.Gvariant_Type; 
  262.        State_Hint     : access Glib.Variant.Gvariant; 
  263.        State          : access Glib.Variant.Gvariant) return Boolean; 
  264.    --  Queries all aspects of the named action within an Action_Group. 
  265.    --  This function acquires the information available from 
  266.    --  Glib.Action_Group.Has_Action, Glib.Action_Group.Get_Action_Enabled, 
  267.    --  Glib.Action_Group.Get_Action_Parameter_Type, 
  268.    --  Glib.Action_Group.Get_Action_State_Type, 
  269.    --  Glib.Action_Group.Get_Action_State_Hint and 
  270.    --  Glib.Action_Group.Get_Action_State with a single function call. 
  271.    --  This provides two main benefits. 
  272.    --  The first is the improvement in efficiency that comes with not having 
  273.    --  to perform repeated lookups of the action in order to discover different 
  274.    --  things about it. The second is that implementing 
  275.    --  Glib.Action_Group.Gaction_Group can now be done by only overriding this 
  276.    --  one virtual function. 
  277.    --  The interface provides a default implementation of this function that 
  278.    --  calls the individual functions, as required, to fetch the information. 
  279.    --  The interface also provides default implementations of those functions 
  280.    --  that call this function. All implementations, therefore, must override 
  281.    --  either this function or all of the others. 
  282.    --  If the action exists, True is returned and any of the requested fields 
  283.    --  (as indicated by having a non-null reference passed in) are filled. If 
  284.    --  the action doesn't exist, False is returned and the fields may or may 
  285.    --  not have been modified. 
  286.    --  Since: gtk+ 2.32 
  287.    --  "action_name": the name of an action in the group 
  288.    --  "enabled": if the action is presently enabled 
  289.    --  "parameter_type": the parameter type, or null if none needed 
  290.    --  "state_type": the state type, or null if stateless 
  291.    --  "state_hint": the state hint, or null if none 
  292.    --  "state": the current state, or null if stateless 
  293.  
  294.    ------------- 
  295.    -- Signals -- 
  296.    ------------- 
  297.  
  298.    type Cb_Gaction_Group_UTF8_String_Void is not null access procedure 
  299.      (Self        : Gaction_Group; 
  300.       Action_Name : UTF8_String); 
  301.  
  302.    type Cb_GObject_UTF8_String_Void is not null access procedure 
  303.      (Self        : access Glib.Object.GObject_Record'Class; 
  304.       Action_Name : UTF8_String); 
  305.  
  306.    Signal_Action_Added : constant Glib.Signal_Name := "action-added"; 
  307.    procedure On_Action_Added 
  308.       (Self  : Gaction_Group; 
  309.        Call  : Cb_Gaction_Group_UTF8_String_Void; 
  310.        After : Boolean := False); 
  311.    procedure On_Action_Added 
  312.       (Self  : Gaction_Group; 
  313.        Call  : Cb_GObject_UTF8_String_Void; 
  314.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  315.        After : Boolean := False); 
  316.    --  Signals that a new action was just added to the group. This signal is 
  317.    --  emitted after the action has been added and is now visible. 
  318.  
  319.    type Cb_Gaction_Group_UTF8_String_Boolean_Void is not null access procedure 
  320.      (Self        : Gaction_Group; 
  321.       Action_Name : UTF8_String; 
  322.       Enabled     : Boolean); 
  323.  
  324.    type Cb_GObject_UTF8_String_Boolean_Void is not null access procedure 
  325.      (Self        : access Glib.Object.GObject_Record'Class; 
  326.       Action_Name : UTF8_String; 
  327.       Enabled     : Boolean); 
  328.  
  329.    Signal_Action_Enabled_Changed : constant Glib.Signal_Name := "action-enabled-changed"; 
  330.    procedure On_Action_Enabled_Changed 
  331.       (Self  : Gaction_Group; 
  332.        Call  : Cb_Gaction_Group_UTF8_String_Boolean_Void; 
  333.        After : Boolean := False); 
  334.    procedure On_Action_Enabled_Changed 
  335.       (Self  : Gaction_Group; 
  336.        Call  : Cb_GObject_UTF8_String_Boolean_Void; 
  337.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  338.        After : Boolean := False); 
  339.    --  Signals that the enabled status of the named action has changed. 
  340.    --  
  341.    --  Callback parameters: 
  342.    --    --  "action_name": the name of the action in Action_Group 
  343.    --    --  "enabled": whether the action is enabled or not 
  344.  
  345.    Signal_Action_Removed : constant Glib.Signal_Name := "action-removed"; 
  346.    procedure On_Action_Removed 
  347.       (Self  : Gaction_Group; 
  348.        Call  : Cb_Gaction_Group_UTF8_String_Void; 
  349.        After : Boolean := False); 
  350.    procedure On_Action_Removed 
  351.       (Self  : Gaction_Group; 
  352.        Call  : Cb_GObject_UTF8_String_Void; 
  353.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  354.        After : Boolean := False); 
  355.    --  Signals that an action is just about to be removed from the group. This 
  356.    --  signal is emitted before the action is removed, so the action is still 
  357.    --  visible and can be queried from the signal handler. 
  358.  
  359.    type Cb_Gaction_Group_UTF8_String_Gvariant_Void is not null access procedure 
  360.      (Self        : Gaction_Group; 
  361.       Action_Name : UTF8_String; 
  362.       Value       : Glib.Variant.Gvariant); 
  363.  
  364.    type Cb_GObject_UTF8_String_Gvariant_Void is not null access procedure 
  365.      (Self        : access Glib.Object.GObject_Record'Class; 
  366.       Action_Name : UTF8_String; 
  367.       Value       : Glib.Variant.Gvariant); 
  368.  
  369.    Signal_Action_State_Changed : constant Glib.Signal_Name := "action-state-changed"; 
  370.    procedure On_Action_State_Changed 
  371.       (Self  : Gaction_Group; 
  372.        Call  : Cb_Gaction_Group_UTF8_String_Gvariant_Void; 
  373.        After : Boolean := False); 
  374.    procedure On_Action_State_Changed 
  375.       (Self  : Gaction_Group; 
  376.        Call  : Cb_GObject_UTF8_String_Gvariant_Void; 
  377.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  378.        After : Boolean := False); 
  379.    --  Signals that the state of the named action has changed. 
  380.    --  
  381.    --  Callback parameters: 
  382.    --    --  "action_name": the name of the action in Action_Group 
  383.    --    --  "value": the new value of the state 
  384.  
  385.    ---------------- 
  386.    -- Interfaces -- 
  387.    ---------------- 
  388.    --  This class implements several interfaces. See Glib.Types 
  389.    -- 
  390.    --  - "Gaction_Group" 
  391.  
  392.    function "+" (W : Gaction_Group) return Gaction_Group; 
  393.    pragma Inline ("+"); 
  394.  
  395. private 
  396.  
  397. Null_Gaction_Group : constant Gaction_Group := 
  398.    Gaction_Group (Glib.Types.Null_Interface); 
  399. end Glib.Action_Group;