1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --   Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet   -- 
  5. --                Copyright (C) 2000-2007 AdaCore                    -- 
  6. --                                                                   -- 
  7. -- This library is free software; you can redistribute it and/or     -- 
  8. -- modify it under the terms of the GNU General Public               -- 
  9. -- License as published by the Free Software Foundation; either      -- 
  10. -- version 2 of the License, or (at your option) any later version.  -- 
  11. --                                                                   -- 
  12. -- This library is distributed in the hope that it will be useful,   -- 
  13. -- but WITHOUT ANY WARRANTY; without even the implied warranty of    -- 
  14. -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU -- 
  15. -- General Public License for more details.                          -- 
  16. --                                                                   -- 
  17. -- You should have received a copy of the GNU General Public         -- 
  18. -- License along with this library; if not, write to the             -- 
  19. -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      -- 
  20. -- Boston, MA 02111-1307, USA.                                       -- 
  21. --                                                                   -- 
  22. -- As a special exception, if other files instantiate generics from  -- 
  23. -- this unit, or you link this unit with other files to produce an   -- 
  24. -- executable, this  unit  does not  by itself cause  the resulting  -- 
  25. -- executable to be covered by the GNU General Public License. This  -- 
  26. -- exception does not however invalidate any other reasons why the   -- 
  27. -- executable file  might be covered by the  GNU Public License.     -- 
  28. ----------------------------------------------------------------------- 
  29.  
  30. --  <description> 
  31. --  Note that this package is currently not supported under Win32 systems. 
  32. -- 
  33. --  Together with Gtk_Plug, Gtk_Socket provides the ability to embed widgets 
  34. --  from one process into another process in a fashion that is transparent to 
  35. --  the user. One process creates a Gtk_Socket widget and, passes the XID of 
  36. --  that widget's window to the other process, which then creates a Gtk_Plug 
  37. --  window with that XID. 
  38. --  Any widgets contained in the Gtk_Plug then will appear inside the first 
  39. --  applications window. 
  40. -- 
  41. --  The XID of the socket's window is obtained by using the 
  42. --  XWindow function provided in this package. Before using 
  43. --  this macro, the socket must have been realized, and for hence, have been 
  44. --  added to its parent. 
  45. -- 
  46. --  Note that if you pass the XID of the socket to another process that will 
  47. --  create a plug in the socket, you must make sure that the socket widget is 
  48. --  not destroyed until that plug is created. Violating this rule will cause 
  49. --  unpredictable consequences, the most likely consequence being that the plug 
  50. --  will appear as a separate toplevel window. You can check if the plug has 
  51. --  been created by examining the plug_window field of the Gtk_Socket 
  52. --  structure. If this field is non-NULL, then the plug has been succesfully 
  53. --  created inside of the socket. 
  54. -- 
  55. --  When GtkAda is notified that the embedded window has been destroyed, then 
  56. --  it will destroy the socket as well. You should always, therefore, be 
  57. --  prepared for your sockets to be destroyed at any time when the main event 
  58. --  loop is running. 
  59. -- 
  60. --  A socket can also be used to swallow arbitrary pre-existing top-level 
  61. --  windows using Steal, though the integration when this is done will not be 
  62. --  as close as between a Gtk_Plug and a Gtk_Socket. All you need in that case 
  63. --  is the X11 window identifier for the external process. 
  64. -- 
  65. --  Note that it is recommended that the external window be first hidden before 
  66. --  being swallowed, so that Gtk.Socket works with most window managers. If 
  67. --  you start with visible windows, some window managers will not be able to 
  68. --  correctly merge the two windows (Enlightenment for instance). 
  69. --  </description> 
  70. --  <c_version>2.8.17</c_version> 
  71. --  <group>Inter-Process communication</group> 
  72.  
  73. with Gtk.Container; 
  74. with Gdk.Window; 
  75.  
  76. package Gtk.Socket is 
  77.  
  78.    type Gtk_Socket_Record is new 
  79.      Gtk.Container.Gtk_Container_Record with private; 
  80.    type Gtk_Socket is access all Gtk_Socket_Record'Class; 
  81.  
  82.    procedure Gtk_New (Widget : out Gtk_Socket); 
  83.    --  Create a new empty GtkSocket. 
  84.  
  85.    procedure Initialize (Widget : access Gtk_Socket_Record'Class); 
  86.    --  Internal initialization function. 
  87.    --  See the section "Creating your own widgets" in the documentation. 
  88.  
  89.    function Get_Type return Glib.GType; 
  90.    --  Return the internal value associated with a Gtk_Socket. 
  91.  
  92.    procedure Add_Id (Socket : access Gtk_Socket_Record; Id : Guint32); 
  93.    --  Add an XEMBED client, such as a Gtk_Plug, to the Gtk_Socket. 
  94.    --  The client may be in the same process or in a different process. 
  95.    -- 
  96.    --  To embed a Gtk_Plug in a Gtk_Socket, you can either create the 
  97.    --  Gtk_Plug with Gtk_New (0), call Gtk.Plug.Get_Id to get the 
  98.    --  window ID of the plug, and then pass that to the Gtk.Socket.Add_Id, or 
  99.    --  you can call Gtk.Socket.Get_Id to get the window ID for the socket, and 
  100.    --  call Gtk.Plug.Gtk_New passing in that ID. 
  101.    -- 
  102.    --  Id: the XID of a client participating in the XEMBED protocol. 
  103.    -- 
  104.    --  The Gtk_Socket must have already be added into a toplevel window 
  105.    --  before you can make this call. 
  106.  
  107.    function Get_Id (Socket : access Gtk_Socket_Record) return Guint32; 
  108.    --  Get the window ID of a Gtk_Socket widget, which can then be used to 
  109.    --  create a client embedded inside the socket, for instance with 
  110.    --  Gtk.Socket.Gtk_New (Id). The Gtk_Socket must have already been added 
  111.    --  into a toplevel window before you can make this call. 
  112.  
  113.    function Get_Plug_Window 
  114.      (Socket : access Gtk_Socket_Record) return Gdk.Window.Gdk_Window; 
  115.    --  Return the id of the embedded window. 
  116.  
  117.    ----------------- 
  118.    -- Obsolescent -- 
  119.    ----------------- 
  120.    --  All subprograms below are now obsolescent in gtk+. They might be removed 
  121.    --  from future versions of gtk+ (and therefore GtkAda). 
  122.    --  To find out whether your code uses any of these, we recommend compiling 
  123.    --  with the -gnatwj switch 
  124.    --  <doc_ignore> 
  125.  
  126.    procedure Steal (Socket : access Gtk_Socket_Record; Wid : Guint32); 
  127.    pragma Obsolescent;  --  Steal 
  128.    --  Reparent a pre-existing toplevel window into a Gtk_Socket. 
  129.    --  This is meant to embed clients that do not know about embedding into a 
  130.    --  Gtk_Socket, however doing so is inherently unreliable, and using 
  131.    --  this function is not recommended. 
  132.    --  The Gtk_Socket must have already be added into a toplevel window 
  133.    --  before you can make this call. 
  134.    --  Wid is the XID of an existing toplevel window. 
  135.  
  136.    --  </doc_ignore> 
  137.  
  138.    ---------------- 
  139.    -- Properties -- 
  140.    ---------------- 
  141.  
  142.    --  <properties> 
  143.    --  The following properties are defined for this widget. See 
  144.    --  Glib.Properties for more information on properties. 
  145.    -- 
  146.    --  </properties> 
  147.  
  148.    ------------- 
  149.    -- Signals -- 
  150.    ------------- 
  151.  
  152.    --  <signals> 
  153.    --  The following new signals are defined for this widget: 
  154.    -- 
  155.    --  - "plug_added" 
  156.    --    procedure Handler (Socket : access Gtk_Socket_Record'Class); 
  157.    --    Emitted when a client is successfully added to the socket 
  158.    -- 
  159.    --  - "plug_removed" 
  160.    --    function Handler 
  161.    --       (Socket : access Gtk_Socket_Record'Class) return Boolean; 
  162.    --    Emitted when a client is successfully removed from the socket. The 
  163.    --    default action is to destroy the socket, so you want to reuse it you 
  164.    --    must return True. 
  165.    -- 
  166.    --  </signals> 
  167.  
  168.    Signal_Plug_Added   : constant Glib.Signal_Name := "plug_added"; 
  169.    Signal_Plug_Removed : constant Glib.Signal_Name := "plug_removed"; 
  170.  
  171. private 
  172.  
  173.    type Gtk_Socket_Record is new Gtk.Container.Gtk_Container_Record 
  174.      with null record; 
  175.  
  176.    pragma Import (C, Get_Type, "gtk_socket_get_type"); 
  177. end Gtk.Socket; 
  178.  
  179. --  <example> 
  180. --  Obtaining the XID of a socket 
  181. -- 
  182. --  with Gtk.Socket; 
  183. --  use Gtk.Socket; 
  184. -- 
  185. --  Socket : Gtk_Socket; 
  186. -- 
  187. --  Gtk_New (Socket); 
  188. --  Show (Socket); 
  189. --  Add (Parent, Socket); 
  190. -- 
  191. --  --  The following call is only necessary if one of 
  192. --  --  the ancestors of the socket is not yet visible. 
  193. -- 
  194. --  Realize (Socket); 
  195. --  Put_Line ("The XID of the sockets window is" & 
  196. --            Guint32'Image (Get_Id (Socket))); 
  197. --  </example>