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. pragma Ada_2005; 
  25.  
  26. pragma Warnings (Off, "*is already use-visible*"); 
  27. with Gdk.Device;     use Gdk.Device; 
  28. with Gdk.Event;      use Gdk.Event; 
  29. with Gdk.Types;      use Gdk.Types; 
  30. with Gtk.Widget;     use Gtk.Widget; 
  31. with Pango.Language; use Pango.Language; 
  32.  
  33. package Gtk.Main is 
  34.  
  35.    --------------- 
  36.    -- Callbacks -- 
  37.    --------------- 
  38.  
  39.    type Gtk_Key_Snoop_Func is access function 
  40.      (Grab_Widget : not null access Gtk.Widget.Gtk_Widget_Record'Class; 
  41.       Event       : Gdk.Event.Gdk_Event_Key) return Gint; 
  42.    --  Key snooper functions are called before normal event delivery. They can 
  43.    --  be used to implement custom key event handling. 
  44.    --  "grab_widget": the widget to which the event will be delivered 
  45.    --  "event": the key event 
  46.  
  47.    ------------- 
  48.    -- Methods -- 
  49.    ------------- 
  50.  
  51.    function Key_Snooper_Install (Snooper : Gtk_Key_Snoop_Func) return Guint; 
  52.    pragma Obsolescent (Key_Snooper_Install); 
  53.    --  Installs a key snooper function, which will get called on all key 
  54.    --  events before delivering them normally. 
  55.    --  Deprecated since 3.4, Key snooping should not be done. Events should be 
  56.    --  handled by widgets. 
  57.    --  "snooper": a Gtk_Key_Snoop_Func 
  58.  
  59.    generic 
  60.       type User_Data_Type (<>) is private; 
  61.       with procedure Destroy (Data : in out User_Data_Type) is null; 
  62.    package Key_Snooper_Install_User_Data is 
  63.  
  64.       type Gtk_Key_Snoop_Func is access function 
  65.         (Grab_Widget : not null access Gtk.Widget.Gtk_Widget_Record'Class; 
  66.          Event       : Gdk.Event.Gdk_Event_Key; 
  67.          Func_Data   : User_Data_Type) return Gint; 
  68.       --  Key snooper functions are called before normal event delivery. They can 
  69.       --  be used to implement custom key event handling. 
  70.       --  "grab_widget": the widget to which the event will be delivered 
  71.       --  "event": the key event 
  72.       --  "func_data": data supplied to Gtk.Main.Key_Snooper_Install 
  73.  
  74.       function Key_Snooper_Install 
  75.          (Snooper   : Gtk_Key_Snoop_Func; 
  76.           Func_Data : User_Data_Type) return Guint; 
  77.       pragma Obsolescent (Key_Snooper_Install); 
  78.       --  Installs a key snooper function, which will get called on all key 
  79.       --  events before delivering them normally. 
  80.       --  Deprecated since 3.4, Key snooping should not be done. Events should 
  81.       --  be handled by widgets. 
  82.       --  "snooper": a Gtk_Key_Snoop_Func 
  83.       --  "func_data": data to pass to Snooper 
  84.  
  85.    end Key_Snooper_Install_User_Data; 
  86.  
  87.    ---------------------- 
  88.    -- GtkAda additions -- 
  89.    ---------------------- 
  90.  
  91.    procedure Init; 
  92.    --  Initialize GtkAda's internal structures. 
  93.    --  This subprogram should be called before any other one in GtkAda. 
  94.    --  If GtkAda could not be initialized (no access to the display, etc.), the 
  95.    --  application exits with an error 
  96.  
  97.    function Init_Check return Boolean; 
  98.    --  Initialize GtkAda's internal structures. 
  99.    --  Return False if there was an error (no access to the display, etc.) 
  100.  
  101.    --------------- 
  102.    -- Functions -- 
  103.    --------------- 
  104.  
  105.    function Get_Major_Version return Guint; 
  106.    --  Returns the major version number of the GTK+ library. (e.g. in GTK+ 
  107.    --  version 3.1.5 this is 3.) 
  108.    --  This function is in the library, so it represents the GTK+ library your 
  109.    --  code is running against. Contrast with the GTK_MAJOR_VERSION macro, 
  110.    --  which represents the major version of the GTK+ headers you have included 
  111.    --  when compiling your code. 
  112.    --  Since: gtk+ 3.0 
  113.  
  114.    function Get_Minor_Version return Guint; 
  115.    --  Returns the minor version number of the GTK+ library. (e.g. in GTK+ 
  116.    --  version 3.1.5 this is 1.) 
  117.    --  This function is in the library, so it represents the GTK+ library your 
  118.    --  code is are running against. Contrast with the GTK_MINOR_VERSION macro, 
  119.    --  which represents the minor version of the GTK+ headers you have included 
  120.    --  when compiling your code. 
  121.    --  Since: gtk+ 3.0 
  122.  
  123.    function Get_Micro_Version return Guint; 
  124.    --  Returns the micro version number of the GTK+ library. (e.g. in GTK+ 
  125.    --  version 3.1.5 this is 5.) 
  126.    --  This function is in the library, so it represents the GTK+ library your 
  127.    --  code is are running against. Contrast with the GTK_MICRO_VERSION macro, 
  128.    --  which represents the micro version of the GTK+ headers you have included 
  129.    --  when compiling your code. 
  130.    --  Since: gtk+ 3.0 
  131.  
  132.    function Get_Binary_Age return Guint; 
  133.    --  Returns the binary age as passed to <application>libtool</application> 
  134.    --  when building the GTK+ library the process is running against. If 
  135.    --  <application>libtool</application> means nothing to you, don't worry 
  136.    --  about it. 
  137.    --  Since: gtk+ 3.0 
  138.  
  139.    function Get_Interface_Age return Guint; 
  140.    --  Returns the interface age as passed to 
  141.    --  <application>libtool</application> when building the GTK+ library the 
  142.    --  process is running against. If <application>libtool</application> means 
  143.    --  nothing to you, don't worry about it. 
  144.    --  Since: gtk+ 3.0 
  145.  
  146.    function Check_Version 
  147.       (Required_Major : Guint; 
  148.        Required_Minor : Guint; 
  149.        Required_Micro : Guint) return UTF8_String; 
  150.    --  Checks that the GTK+ library in use is compatible with the given 
  151.    --  version. Generally you would pass in the constants GTK_MAJOR_VERSION, 
  152.    --  GTK_MINOR_VERSION, GTK_MICRO_VERSION as the three arguments to this 
  153.    --  function; that produces a check that the library in use is compatible 
  154.    --  with the version of GTK+ the application or module was compiled against. 
  155.    --  Compatibility is defined by two things: first the version of the 
  156.    --  running library is newer than the version 
  157.    --  Required_Major.required_minor.Required_Micro. Second the running library 
  158.    --  must be binary compatible with the version 
  159.    --  Required_Major.required_minor.Required_Micro (same major version.) 
  160.    --  This function is primarily for GTK+ modules; the module can call this 
  161.    --  function to check that it wasn't loaded into an incompatible version of 
  162.    --  GTK+. However, such a check isn't completely reliable, since the module 
  163.    --  may be linked against an old version of GTK+ and calling the old version 
  164.    --  of Gtk.Main.Check_Version, but still get loaded into an application 
  165.    --  using a newer version of GTK+. 
  166.    --  "required_major": the required major version 
  167.    --  "required_minor": the required minor version 
  168.    --  "required_micro": the required micro version 
  169.  
  170.    procedure Disable_Setlocale; 
  171.    --  Prevents gtk_init, gtk_init_check, gtk_init_with_args and 
  172.    --  gtk_parse_args from automatically calling 'setlocale (LC_ALL, "")'. You 
  173.    --  would want to use this function if you wanted to set the locale for your 
  174.    --  program to something other than the user's locale, or if you wanted to 
  175.    --  set different values for different locale categories. 
  176.    --  Most programs should not need to call this function. 
  177.  
  178.    function Get_Default_Language return Pango.Language.Pango_Language; 
  179.    --  Returns the Pango.Language.Pango_Language for the default language 
  180.    --  currently in effect. (Note that this can change over the life of an 
  181.    --  application.) The default language is derived from the current locale. 
  182.    --  It determines, for example, whether GTK+ uses the right-to-left or 
  183.    --  left-to-right text direction. 
  184.    --  This function is equivalent to Pango.Language.Get_Default. See that 
  185.    --  function for details. 
  186.  
  187.    function Events_Pending return Boolean; 
  188.    --  Checks if any events are pending. 
  189.    --  This can be used to update the UI and invoke timeouts etc. while doing 
  190.    --  some time intensive computation. 
  191.    --  == Updating the UI during a long computation == 
  192.    --    /* computation going on... */ 
  193.    --    while (gtk_events_pending ()) 
  194.    --    gtk_main_iteration (); 
  195.    --    /* ...computation continued */ 
  196.  
  197.    procedure Main_Do_Event (Event : Gdk.Event.Gdk_Event); 
  198.    --  Processes a single GDK event. 
  199.    --  This is public only to allow filtering of events between GDK and GTK+. 
  200.    --  You will not usually need to call this function directly. 
  201.    --  While you should not call this function directly, you might want to 
  202.    --  know how exactly events are handled. So here is what this function does 
  203.    --  with the event: 
  204.    --     * Compress enter/leave notify events. If the event passed build an 
  205.    --  enter/leave pair together with the next event (peeked from GDK), both 
  206.    --  events are thrown away. This is to avoid a backlog of (de-)highlighting 
  207.    --  widgets crossed by the pointer. 
  208.    --     * Find the widget which got the event. If the widget can't be 
  209.    --  determined the event is thrown away unless it belongs to a INCR 
  210.    --  transaction. 
  211.    --     * Then the event is pushed onto a stack so you can query the 
  212.    --  currently handled event with Gtk.Main.Get_Current_Event. 
  213.    --     * The event is sent to a widget. If a grab is active all events for 
  214.    --  widgets that are not in the contained in the grab widget are sent to the 
  215.    --  latter with a few exceptions: 
  216.    --     * Deletion and destruction events are still sent to the event widget 
  217.    --  for obvious reasons. 
  218.    --     * Events which directly relate to the visual representation of the 
  219.    --  event widget. 
  220.    --     * Leave events are delivered to the event widget if there was an 
  221.    --  enter event delivered to it before without the paired leave event. 
  222.    --     * Drag events are not redirected because it is unclear what the 
  223.    --  semantics of that would be. Another point of interest might be that all 
  224.    --  key events are first passed through the key snooper functions if there 
  225.    --  are any. Read the description of Gtk.Main.Key_Snooper_Install if you 
  226.    --  need this feature. 
  227.    --     * After finishing the delivery the event is popped from the event 
  228.    --  stack. 
  229.    --  "event": An event to process (normally passed by GDK) 
  230.  
  231.    procedure Main; 
  232.    --  Runs the main loop until Gtk.Main.Main_Quit is called. 
  233.    --  You can nest calls to Gtk.Main.Main. In that case Gtk.Main.Main_Quit 
  234.    --  will make the innermost invocation of the main loop return. 
  235.  
  236.    function Main_Level return Guint; 
  237.    --  Asks for the current nesting level of the main loop. 
  238.  
  239.    procedure Main_Quit; 
  240.    --  Makes the innermost invocation of the main loop return when it regains 
  241.    --  control. 
  242.  
  243.    function Main_Iteration return Boolean; 
  244.    --  Runs a single iteration of the mainloop. 
  245.    --  If no events are waiting to be processed GTK+ will block until the next 
  246.    --  event is noticed. If you don't want to block look at 
  247.    --  Gtk.Main.Main_Iteration_Do or check if any events are pending with 
  248.    --  Gtk.Main.Events_Pending first. 
  249.  
  250.    function Main_Iteration_Do (Blocking : Boolean) return Boolean; 
  251.    --  Runs a single iteration of the mainloop. If no events are available 
  252.    --  either return or block depending on the value of Blocking. 
  253.    --  "blocking": True if you want GTK+ to block if no events are pending 
  254.  
  255.    function True return Boolean; 
  256.    --  All this function does it to return True. 
  257.    --  This can be useful for example if you want to inhibit the deletion of a 
  258.    --  window. Of course you should not do this as the user expects a reaction 
  259.    --  from clicking the close icon of the window... 
  260.    --  == A persistent window == 
  261.    --    include <gtk/gtk.h>< 
  262.    --    int 
  263.    --    main (int argc, char **argv) 
  264.    --    { 
  265.    --       GtkWidget *win, *but; 
  266.    --       gtk_init (&amp;argc, &amp;argv); 
  267.    --       win = gtk_window_new (GTK_WINDOW_TOPLEVEL); 
  268.    --       g_signal_connect (win, "delete-event", 
  269.    --          G_CALLBACK (gtk_true), NULL); 
  270.    --       g_signal_connect (win, "destroy", 
  271.    --          G_CALLBACK (gtk_main_quit), NULL); 
  272.    --       but = gtk_button_new_with_label ("Close yourself. I mean it!"); 
  273.    --       g_signal_connect_swapped (but, "clicked", 
  274.    --          G_CALLBACK (gtk_object_destroy), win); 
  275.    --       gtk_container_add (GTK_CONTAINER (win), but); 
  276.    --       gtk_widget_show_all (win); 
  277.    --       gtk_main (); 
  278.    --       return 0; 
  279.    --    } 
  280.  
  281.    function False return Boolean; 
  282.    --  Analogical to Gtk.Main.True, this function does nothing but always 
  283.    --  returns False. 
  284.  
  285.    function Grab_Get_Current return Gtk.Widget.Gtk_Widget; 
  286.    --  Queries the current grab of the default window group. 
  287.  
  288.    procedure Device_Grab_Add 
  289.       (Widget       : not null access Gtk.Widget.Gtk_Widget_Record'Class; 
  290.        Device       : not null access Gdk.Device.Gdk_Device_Record'Class; 
  291.        Block_Others : Boolean); 
  292.    --  Adds a GTK+ grab on Device, so all the events on Device and its 
  293.    --  associated pointer or keyboard (if any) are delivered to Widget. If the 
  294.    --  Block_Others parameter is True, any other devices will be unable to 
  295.    --  interact with Widget during the grab. 
  296.    --  Since: gtk+ 3.0 
  297.    --  "widget": a Gtk.Widget.Gtk_Widget 
  298.    --  "device": a Gdk.Device.Gdk_Device to grab on. 
  299.    --  "block_others": True to prevent other devices to interact with Widget. 
  300.  
  301.    procedure Device_Grab_Remove 
  302.       (Widget : not null access Gtk.Widget.Gtk_Widget_Record'Class; 
  303.        Device : not null access Gdk.Device.Gdk_Device_Record'Class); 
  304.    --  Removes a device grab from the given widget. 
  305.    --  You have to pair calls to Gtk.Main.Device_Grab_Add and 
  306.    --  Gtk.Main.Device_Grab_Remove. 
  307.    --  Since: gtk+ 3.0 
  308.    --  "widget": a Gtk.Widget.Gtk_Widget 
  309.    --  "device": a Gdk.Device.Gdk_Device 
  310.  
  311.    procedure Key_Snooper_Remove (Snooper_Handler_Id : Guint); 
  312.    pragma Obsolescent (Key_Snooper_Remove); 
  313.    --  Removes the key snooper function with the given id. 
  314.    --  Deprecated since 3.4, Key snooping should not be done. Events should be 
  315.    --  handled by widgets. 
  316.    --  "snooper_handler_id": Identifies the key snooper to remove 
  317.  
  318.    function Get_Current_Event return Gdk.Event.Gdk_Event; 
  319.    --  Obtains a copy of the event currently being processed by GTK+. 
  320.    --  For example, if you are handling a Gtk.Button.Gtk_Button::clicked 
  321.    --  signal, the current event will be the Gdk.Event.Gdk_Event_Button that 
  322.    --  triggered the ::clicked signal. 
  323.  
  324.    function Get_Current_Event_Time return Guint32; 
  325.    --  If there is a current event and it has a timestamp, return that 
  326.    --  timestamp, otherwise return GDK_CURRENT_TIME. 
  327.  
  328.    procedure Get_Current_Event_State 
  329.       (State             : out Gdk.Types.Gdk_Modifier_Type; 
  330.        Has_Current_Event : out Boolean); 
  331.    --  If there is a current event and it has a state field, place that state 
  332.    --  field in State and return True, otherwise return False. 
  333.    --  "state": a location to store the state of the current event 
  334.  
  335.    function Get_Current_Event_Device return Gdk.Device.Gdk_Device; 
  336.    --  If there is a current event and it has a device, return that device, 
  337.    --  otherwise return null. 
  338.  
  339.    function Get_Event_Widget 
  340.       (Event : Gdk.Event.Gdk_Event) return Gtk.Widget.Gtk_Widget; 
  341.    --  If Event is null or the event was not associated with any widget, 
  342.    --  returns null, otherwise returns the widget that received the event 
  343.    --  originally. 
  344.    --  "event": a Gdk.Event.Gdk_Event 
  345.  
  346.    procedure Propagate_Event 
  347.       (Widget : not null access Gtk.Widget.Gtk_Widget_Record'Class; 
  348.        Event  : Gdk.Event.Gdk_Event); 
  349.    --  Sends an event to a widget, propagating the event to parent widgets if 
  350.    --  the event remains unhandled. 
  351.    --  Events received by GTK+ from GDK normally begin in 
  352.    --  Gtk.Main.Main_Do_Event. Depending on the type of event, existence of 
  353.    --  modal dialogs, grabs, etc., the event may be propagated; if so, this 
  354.    --  function is used. 
  355.    --  Gtk.Main.Propagate_Event calls Gtk.Widget.Event on each widget it 
  356.    --  decides to send the event to. So Gtk.Widget.Event is the lowest-level 
  357.    --  function; it simply emits the Gtk.Widget.Gtk_Widget::event and possibly 
  358.    --  an event-specific signal on a widget. Gtk.Main.Propagate_Event is a bit 
  359.    --  higher-level, and Gtk.Main.Main_Do_Event is the highest level. 
  360.    --  All that said, you most likely don't want to use any of these 
  361.    --  functions; synthesizing events is rarely needed. There are almost 
  362.    --  certainly better ways to achieve your goals. For example, use 
  363.    --  Gdk.Window.Invalidate_Rect or Gtk.Widget.Queue_Draw instead of making up 
  364.    --  expose events. 
  365.    --  "widget": a Gtk.Widget.Gtk_Widget 
  366.    --  "event": an event 
  367.  
  368. end Gtk.Main;