1. ------------------------------------------------------------------------------ 
  2. --                  GtkAda - Ada95 binding for Gtk+/Gnome                   -- 
  3. --                                                                          -- 
  4. --                     Copyright (C) 2006-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. --  This package contains low-level subprograms that are used to interact or 
  26. --  configure the main loop. 
  27. --  This loop is responsible for processing events, monitoring input sources 
  28. --  like pipes, sockets,..., and calling callbacks at given time intervals. 
  29. --  New event sources can be created. 
  30. -- 
  31. --  To allow multiple independent sets of sources to be handled in different 
  32. --  threads, each source is associated with a main context. A main context can 
  33. --  only be running in a single thread, but sources can be added to it and 
  34. --  removed from it from other threads. 
  35. -- 
  36. --  Each event source is assigned a priority. The default priority, 
  37. --  G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. 
  38. --  Values greater than 0 denote lower priorities. Events from high priority 
  39. --  sources are always processed before events from lower priority sources. 
  40. -- 
  41. --  Idle functions can also be added, and assigned a priority. These will be 
  42. --  run whenever no events with a higher priority are ready to be processed. 
  43. -- 
  44. --  The GMainLoop data type represents a main event loop. A GMainLoop is 
  45. --  created with g_main_loop_new(). After adding the initial event sources, 
  46. --  g_main_loop_run() is called. This continuously checks for new events from 
  47. --  each of the event sources and dispatches them. Finally, the processing of 
  48. --  an event from one of the sources leads to a call to g_main_loop_quit() to 
  49. --  exit the main loop, and g_main_loop_run() returns. 
  50.  
  51. --  It is possible to create new instances of GMainLoop recursively. This is 
  52. --  often used in GTK+ applications when showing modal dialog boxes. Note that 
  53. --  event sources are associated with a particular GMainContext, and will be 
  54. --  checked and dispatched for all main loops associated with that 
  55. --  GMainContext. 
  56. -- 
  57. --  Creating new sources types 
  58. --  ========================== 
  59. -- 
  60. --  One of the unusual features of the GTK+ main loop functionality is that new 
  61. --  types of event source can be created and used in addition to the builtin 
  62. --  type of event source. A new event source type is used for handling GDK 
  63. --  events. 
  64. -- 
  65. --  New source types basically interact with with the main context in two ways. 
  66. --  Their prepare function in GSourceFuncs can set a timeout to determine the 
  67. --  maximum amount of time that the main loop will sleep before checking the 
  68. --  source again. In addition, or as well, the source can add file descriptors 
  69. --  to the set that the main context checks using g_source_add_poll(). 
  70. -- 
  71. --  Ada 
  72. --  === 
  73. -- 
  74. --  Some of these features duplicate Ada builtin tasking support, but the 
  75. --  latter might be more complex to use in the context of a graphical 
  76. --  application, since most of the time the windowing system doesn't support 
  77. --  multi-threaded applications. 
  78. --  </description> 
  79. --  <c_version>glib 2.10.2</c_version> 
  80. --  <group>Glib, the general-purpose library</group> 
  81. --  <testgtk>create_sources.adb</testgtk> 
  82.  
  83. package Glib.Main is 
  84.  
  85.    -------------------- 
  86.    -- G_Main_Context -- 
  87.    -------------------- 
  88.  
  89.    type G_Main_Context is new Glib.C_Proxy; 
  90.    --  This type represents a set of sources to handled in the main loop. 
  91.    --  Basically, this represents a main loop. There might be several main 
  92.    --  loops running at the same time, although gtk+ itself has only one, 
  93.    --  identified as the default main context. 
  94.  
  95.    function Main_Context_New return G_Main_Context; 
  96.    --  Create a new context 
  97.  
  98.    procedure Main_Context_Ref   (Context : G_Main_Context); 
  99.    procedure Main_Context_Unref (Context : G_Main_Context); 
  100.    --  Increase or decreate the reference counting for Context. When this 
  101.    --  reaches 0, the memory is freed. 
  102.  
  103.    function Main_Context_Default return G_Main_Context; 
  104.    --  Returns the default main context. This is the main context used for main 
  105.    --  loop functions when a main loop is not explicitly specified. 
  106.  
  107.    procedure Wakeup (Context : G_Main_Context); 
  108.    --  If context is currently waiting in a poll(), interrupt the poll(), and 
  109.    --  continue the iteration process. 
  110.  
  111.    function Acquire (Context : G_Main_Context) return Boolean; 
  112.    --  Tries to become the owner of the specified context. If some other thread 
  113.    --  is the owner of the context, returns FALSE immediately. Ownership is 
  114.    --  properly recursive: the owner can require ownership again and will 
  115.    --  release ownership when Release() is called as many times as Acquire(). 
  116.    --  You must be the owner of a context before you can call Prepare(), 
  117.    --  Query(), Check(), Dispatch(). 
  118.  
  119.    procedure Release (Context : G_Main_Context); 
  120.    --  Releases ownership of a context previously acquired by this thread with 
  121.    --  Acquire(). If the context was acquired multiple times, the only release 
  122.    --  ownership when Release() is called as many times as it was acquired. 
  123.  
  124.    function Is_Owner (Context : G_Main_Context) return Boolean; 
  125.    --  Determines whether this thread holds the (recursive) ownership of this 
  126.    --  context. This is useful to know before waiting on another thread 
  127.    --  that may be blocking to get ownership of context. 
  128.  
  129.    procedure Dispatch (Context : G_Main_Context); 
  130.    --  Dispatches all pending sources. 
  131.  
  132.    --------------- 
  133.    -- Main loop -- 
  134.    --------------- 
  135.  
  136.    function Depth return Integer; 
  137.    --  The main loop recursion level in the current thread. It returns 0 when 
  138.    --  called from the toplevel. 
  139.  
  140.    -------------- 
  141.    -- G_Source -- 
  142.    -------------- 
  143.  
  144.    type G_Source is new Glib.C_Proxy; 
  145.    --  This type represents an event source that can be monitored by the main 
  146.    --  loop. There are various internal types of such sources, that can be 
  147.    --  configured by setting appropriate callbacks (this is not yet doable in 
  148.    --  GtkAda). See Idle_Source_New and Timeout_Source_New. 
  149.  
  150.    type G_Source_Id is new Guint; 
  151.    --  The ID of a source within the context to which it is attached. 
  152.  
  153.    No_Source_Id : constant G_Source_Id; 
  154.  
  155.    type G_Source_Func is access function return Boolean; 
  156.  
  157.    type Source_Prepare_Func is access 
  158.      function (Source : G_Source; Timeout : access Gint) return Gboolean; 
  159.    pragma Convention (C, Source_Prepare_Func); 
  160.    --  Called before all the file descriptors are polled. If the source can 
  161.    --  determine that it is ready here (without waiting for the results of the 
  162.    --  poll() call) it should return TRUE. It can also return a timeout value 
  163.    --  which should be the maximum timeout (in milliseconds) which should be 
  164.    --  passed to the poll() call. The actual timeout used will be -1 if all 
  165.    --  sources returned -1, or it will be the minimum of all the timeout_ 
  166.    --  values returned which were >= 0. 
  167.  
  168.    type Source_Check_Func is access 
  169.      function (Source : G_Source) return Gboolean; 
  170.    pragma Convention (C, Source_Check_Func); 
  171.    --  Called after all the file descriptors are polled. The source should 
  172.    --  return TRUE if it is ready to be dispatched. Note that some time may 
  173.    --  have passed since the previous prepare function was called, so the 
  174.    --  source should be checked again here. 
  175.  
  176.    type G_Source_Func_User_Data is access 
  177.      function (User_Data : System.Address) return Gboolean; 
  178.    pragma Convention (C, G_Source_Func_User_Data); 
  179.    --  A callback for a G_Source. If it returns False, the source will be 
  180.    --  removed and no longer executed. User_Data is the data passed to 
  181.    --  Set_Callback. 
  182.  
  183.    type Source_Dispatch_Func is access 
  184.      function (Source   : G_Source; 
  185.                Callback : G_Source_Func_User_Data; 
  186.                Data     : System.Address) return Gboolean; 
  187.    pragma Convention (C, Source_Dispatch_Func); 
  188.    --  Called to dispatch the event source, after it has returned TRUE in 
  189.    --  either its prepare or its check function. The dispatch function is 
  190.    --  passed in a callback function and data. The callback function may be 
  191.    --  NULL if the source was never connected to a callback using 
  192.    --  Set_Callback(). 
  193.    --  In C, the exact profile of Callback depends on the type of Source. This 
  194.    --  is not possible in Ada, which expects a precise profile. 
  195.  
  196.    function Default_Dispatch 
  197.      (Source : G_Source; Cb : G_Source_Func_User_Data; Data : System.Address) 
  198.       return Gboolean; 
  199.    pragma Convention (C, Default_Dispatch); 
  200.    --  Default implementation for the dispatch callback for sources. This 
  201.    --  simply calls Cb and pass it Data. 
  202.  
  203.    type Source_Finalize_Func is access procedure (Source : G_Source); 
  204.    pragma Convention (C, Source_Finalize_Func); 
  205.    --  Called when the source is finalized. 
  206.  
  207.    type G_Source_Type is private; 
  208.    Null_Source_Type : constant G_Source_Type; 
  209.    function G_Source_Type_New 
  210.      (Prepare  : Source_Prepare_Func; 
  211.       Check    : Source_Check_Func; 
  212.       Dispatch : Source_Dispatch_Func := Default_Dispatch'Access; 
  213.       Finalize : Source_Finalize_Func := null) return G_Source_Type; 
  214.    --  Create a new type of sources. 
  215.    --  This function is specific to GtkAda. The returned value is never 
  216.    --  freed. Most of the time, you do not need to create a new source type, 
  217.    --  or even call Source_New. Most things can be implemented through the 
  218.    --  careful use of Idle and Timeout callbacks. However, creating a new 
  219.    --  source type allows for cleaner code, by sharing the common part of the 
  220.    --  handling. 
  221.    -- 
  222.    --  For idle sources, the prepare and check functions always return TRUE to 
  223.    --  indicate that the source is always ready to be processed. The prepare 
  224.    --  function also returns a timeout value of 0 to ensure that the poll() 
  225.    --  call doesn't block (since that would be time wasted which could have 
  226.    --  been spent running the idle function). 
  227.    -- 
  228.    --  For timeout sources, the prepare and check functions both return TRUE if 
  229.    --  the timeout interval has expired. The prepare function also returns a 
  230.    --  timeout value to ensure that the poll() call doesn't block too long and 
  231.    --  miss the next timeout. 
  232.    -- 
  233.    --  For file descriptor sources, the prepare function typically returns 
  234.    --  FALSE, since it must wait until poll() has been called before it knows 
  235.    --  whether any events need to be processed. It sets the returned timeout to 
  236.    --  -1 to indicate that it doesn't mind how long the poll() call blocks. In 
  237.    --  the check function, it tests the results of the poll() call to see if 
  238.    --  the required condition has been met, and returns TRUE if so. 
  239.  
  240.    function Source_New 
  241.      (Source_Type : G_Source_Type; User_Data : System.Address) return G_Source; 
  242.    --  Creates a new GSource structure. 
  243.    -- 
  244.    --  The source will not initially be associated with any GMainContext and 
  245.    --  must be added to one with Attach() before it will be executed. 
  246.  
  247.    function Get_User_Data (Source : G_Source) return System.Address; 
  248.    --  Return the user data passed to Source_New. This only applies to sources 
  249.    --  created through that function, and returns undefined results (or even 
  250.    --  segfaults) otherwise 
  251.  
  252.    procedure Source_Ref   (Source : G_Source); 
  253.    procedure Source_Unref (Source : G_Source); 
  254.    --  Increase or decrease the reference counting for Source. When this 
  255.    --  reaches 0, the Source is destroyed 
  256.  
  257.    procedure Source_Destroy (Source : G_Source); 
  258.    --  Removes the source from its context, and mark it as destroyed (the 
  259.    --  memory is not reclaimed while the reference counting doesn't reach 0). 
  260.    --  Source cannot be added to another context. 
  261.  
  262.    function Attach 
  263.      (Source  : G_Source; 
  264.       Context : G_Main_Context := null) return G_Source_Id; 
  265.    --  Add Source to Context. The Source will be executed within that context. 
  266.    --  If context is null, the source is added to the default context. 
  267.    --  Returns the Id of the source within Context. 
  268.  
  269.    function Remove (Id : G_Source_Id) return Boolean; 
  270.    procedure Remove (Id : G_Source_Id); 
  271.    --  Removes the source with the given id from the default main context. 
  272.    --  The id of. Return True if the source was found and removed 
  273.  
  274.    type G_Priority is new Gint; 
  275.    Priority_High         : constant G_Priority := -100; 
  276.    Priority_Default      : constant G_Priority := 0; 
  277.    Priority_High_Idle    : constant G_Priority := 100; 
  278.    Priority_Default_Idle : constant G_Priority := 200; 
  279.    Priority_Low          : constant G_Priority := 300; 
  280.    --  Priority_High and Priority_Low are not used within glib or gtk+. The 
  281.    --  priority for all graphical events is Priority_Default. gtk+ uses 
  282.    --  Priority_High_Idle+10 for resizing operations, and 
  283.    --  Priority_High_Idle+20 for redrawing operations, to ensure that resizing 
  284.    --  occurs before redrawing and avoid redrawing twice. 
  285.  
  286.    procedure Set_Priority (Source : G_Source; Priority : G_Priority); 
  287.    function  Get_Priority (Source : G_Source) return G_Priority; 
  288.    --  Sets the priority of a source. While the main loop is being run, a 
  289.    --  source will be dispatched if it is ready to be dispatched and no sources 
  290.    --  at a higher (numerically smaller) priority are ready to be dispatched. 
  291.  
  292.    procedure Set_Can_Recurse (Source : G_Source; Can_Recurse : Boolean); 
  293.    function  Get_Can_Recurse (Source : G_Source) return Boolean; 
  294.    --  Sets whether a source can be called recursively. If can_recurse is TRUE, 
  295.    --  then while the source is being dispatched then this source will be 
  296.    --  processed normally. Otherwise, all processing of this source is blocked 
  297.    --  until the dispatch function returns. 
  298.  
  299.    function Get_Id (Source : G_Source) return G_Source_Id; 
  300.    --  Returns the numeric ID for a particular source. The ID of a source is 
  301.    --  positive integer which is unique within a particular main loop context. 
  302.    --  The reverse mapping from ID to source is done by Find_Source_By_Id 
  303.  
  304.    function Find_Source_By_Id 
  305.      (Id : G_Source_Id; Context : G_Main_Context := null) return G_Source; 
  306.    --  Find a source given a context and its Id. 
  307.  
  308.    function Get_Context (Source : G_Source) return G_Main_Context; 
  309.    --  Gets the context with which the source is associated. Calling this 
  310.    --  function on a destroyed source is an error. The returned value is Null 
  311.    --  for sources that haven't been attached yet 
  312.  
  313.    ---------------------- 
  314.    -- Idle and timeout -- 
  315.    ---------------------- 
  316.  
  317.    function Idle_Source_New return G_Source; 
  318.    --  Return a newly allocated idle G_Source. Such a source is polled 
  319.    --  whenever the main loop is not processing events with a higher priority. 
  320.    --  This source must be attached to a main context before it will be 
  321.    --  executed. 
  322.  
  323.    function Timeout_Source_New (Interval : Guint) return G_Source; 
  324.    --  Return a newly allocated idle G_Source. Such a source is called at 
  325.    --  regular intervals. Internval is in milliseconds. 
  326.  
  327.    function Idle_Add (Func : G_Source_Func) return G_Source_Id; 
  328.    --  Adds a function to be called whenever there are no higher priority 
  329.    --  events pending in the default main loop. This function is given the 
  330.    --  priority Priority_Default_Idle. If the function returns False, it is 
  331.    --  automatically removed from the list of event sources and will not be 
  332.    --  called again. 
  333.    --  This function returns the Id of the event source. See Find_Source_By_Id. 
  334.    --  This is implemented by using Idle_Source_New internally. 
  335.  
  336.    function Timeout_Add 
  337.      (Interval : Guint; 
  338.       Func     : G_Source_Func) return G_Source_Id; 
  339.    --  Create a new function to be called periodically until it returns False. 
  340.    -- 
  341.    --  Note that timeout functions may be delayed, due to the processing of 
  342.    --  other event sources. Thus they should not be relied on for precise 
  343.    --  timing. After each call to the timeout function, the time of the next 
  344.    --  timeout is recalculated based on the current time and the given interval 
  345.    --  (it does not try to 'catch up' time lost in delays). 
  346.  
  347.    generic 
  348.       type Data_Type (<>) is private; 
  349.    package Generic_Sources is 
  350.       type G_Source_Func is access 
  351.         function (Data : Data_Type) return Boolean; 
  352.       --  If the function returns FALSE it is automatically 
  353.       --  removed from the list of event sources and will not be called again. 
  354.  
  355.       type Destroy_Notify is access  procedure (Data : in out Data_Type); 
  356.       --  Notify is called just prior to the destruction of Data. It is also 
  357.       --  called if the idle or timeout is destroyed through a call to 
  358.       --  Remove (Id); 
  359.  
  360.       function Idle_Add 
  361.         (Func     : G_Source_Func; 
  362.          Data     : Data_Type; 
  363.          Priority : G_Priority := Priority_Default_Idle; 
  364.          Notify   : Destroy_Notify := null) return G_Source_Id; 
  365.       --  Adds a function to be called whenever there are no higher priority 
  366.       --  events pending. 
  367.  
  368.       function Timeout_Add 
  369.         (Interval : Guint; 
  370.          Func     : G_Source_Func; 
  371.          Data     : Data_Type; 
  372.          Priority : G_Priority := Priority_Default; 
  373.          Notify   : Destroy_Notify := null) return G_Source_Id; 
  374.       --  Adds a function to be called at regular intervals (in milliseconds). 
  375.  
  376.       procedure Set_Callback 
  377.         (Source   : G_Source; 
  378.          Func     : G_Source_Func; 
  379.          Data     : Data_Type; 
  380.          Notify   : Destroy_Notify := null); 
  381.       --  Sets the callback function for a source. The callback for a source is 
  382.       --  called from the source's dispatch function. 
  383.       -- 
  384.       --  The exact type of func depends on the type of source; ie. you should 
  385.       --  not count on func being called with data as its first parameter. 
  386.       -- 
  387.       --  Typically, you won't use this function. Instead use functions 
  388.       --  specific to the type of source you are using. 
  389.  
  390.    private 
  391.       procedure Free_Data (D : System.Address); 
  392.       pragma Convention (C, Free_Data); 
  393.  
  394.       function General_Cb (D : System.Address) return Gint; 
  395.       pragma Convention (C, General_Cb); 
  396.    end Generic_Sources; 
  397.  
  398. private 
  399.    No_Source_Id : constant G_Source_Id := 0; 
  400.  
  401.    type G_Source_Type is new System.Address; 
  402.    Null_Source_Type : constant G_Source_Type := 
  403.      G_Source_Type (System.Null_Address); 
  404.  
  405.    pragma Import (C, Main_Context_New,     "g_main_context_new"); 
  406.    pragma Import (C, Main_Context_Ref,     "g_main_context_ref"); 
  407.    pragma Import (C, Main_Context_Unref,   "g_main_context_unref"); 
  408.    pragma Import (C, Main_Context_Default, "g_main_context_default"); 
  409.    pragma Import (C, Wakeup,               "g_main_context_wakeup"); 
  410.    pragma Import (C, Release,              "g_main_context_release"); 
  411.    pragma Import (C, Dispatch,             "g_main_context_dispatch"); 
  412.    pragma Import (C, Source_Ref,           "g_source_ref"); 
  413.    pragma Import (C, Source_Unref,         "g_source_unref"); 
  414.    pragma Import (C, Attach,               "g_source_attach"); 
  415.    pragma Import (C, Source_Destroy,       "g_source_destroy"); 
  416.    pragma Import (C, Set_Priority,         "g_source_set_priority"); 
  417.    pragma Import (C, Get_Priority,         "g_source_get_priority"); 
  418.    pragma Import (C, Get_Id,               "g_source_get_id"); 
  419.    pragma Import (C, Get_Context,          "g_source_get_context"); 
  420.    pragma Import (C, Idle_Source_New,      "g_idle_source_new"); 
  421.    pragma Import (C, Timeout_Source_New,   "g_timeout_source_new"); 
  422.    pragma Import (C, Depth,                "g_main_depth"); 
  423.    pragma Import (C, G_Source_Type_New,    "ada_allocate_g_source_funcs"); 
  424.    pragma Import (C, Source_New,           "ada_g_source_new"); 
  425.    pragma Import (C, Get_User_Data,        "ada_g_source_get_user_data"); 
  426.  
  427.    --  No binding: g_main_context_find_source_by_user_data 
  428.    --  No binding: g_main_context_find_source_by_funcs_user_data 
  429.    --  No binding: g_idle_remove_by_data 
  430.    --  No binding: g_source_remove_by_funcs_user_data 
  431.    --  No binding: g_source_remove_by_user_data 
  432.    --  No binding: g_source_get_current_time 
  433.    --  No binding: g_source_connect_closure 
  434.    --  No binding: g_source_set_callback_indirect 
  435.    --  No binding: g_get_current_time 
  436.  
  437.    --  Bounds through ada_g_source_new 
  438.    --  No binding: g_source_new 
  439.  
  440.    --  The following functions haven't been examined closely. Most of them 
  441.    --  deal with very low-level details, for which Ada generally has better 
  442.    --  equivalents anyway. 
  443.  
  444.    --  No binding: g_child_watch_add 
  445.    --  No binding: g_child_watch_add_full 
  446.    --  No binding: g_child_watch_source_new 
  447.    --  No binding: g_main_context_add_poll 
  448.    --  No binding: g_main_context_check 
  449.    --  No binding: g_main_context_get_poll_func 
  450.    --  No binding: g_main_context_iteration 
  451.    --  No binding: g_main_context_pending 
  452.    --  No binding: g_main_context_prepare 
  453.    --  No binding: g_main_context_query 
  454.    --  No binding: g_main_context_remove_poll 
  455.    --  No binding: g_main_context_set_poll_func 
  456.    --  No binding: g_main_context_wait 
  457.    --  No binding: g_main_loop_get_context 
  458.    --  No binding: g_main_loop_is_running 
  459.    --  No binding: g_main_loop_new 
  460.    --  No binding: g_main_loop_quit 
  461.    --  No binding: g_main_loop_ref 
  462.    --  No binding: g_main_loop_run 
  463.    --  No binding: g_main_loop_unref 
  464.    --  No binding: g_source_add_poll 
  465.    --  No binding: g_source_remove_poll 
  466.  
  467. end Glib.Main;