## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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.     -----------------------------------------------------------------------

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>

73.     with Gtk.ContainerTo API docTo specTo body;

74.     with Gdk.WindowTo API docTo specTo body;

76.     package Gtk.SocketTo API docTo specTo body is

78.        type Gtk_Socket_RecordTo API docTo body is new

79.          Gtk.Container.Gtk_Container_RecordTo API docTo specTo body with private;

80.        type Gtk_Socket is access all Gtk_Socket_RecordTo API docTo specTo body'Class;

82.        procedure Gtk_NewTo API docTo body (Widget : out Gtk_SocketTo API docTo spec);

83.        --  Create a new empty GtkSocket.

85.        procedure InitializeTo API docTo body (Widget : access Gtk_Socket_RecordTo API docTo specTo body'Class);

86.        --  Internal initialization function.

87.        --  See the section "Creating your own widgets" in the documentation.

89.        function Get_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

90.        --  Return the internal value associated with a Gtk_Socket.

92.        procedure Add_IdTo API docTo body (Socket : access Gtk_Socket_RecordTo API docTo specTo body; Id : Guint32To API docTo spec);

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.

107.        function Get_IdTo API docTo body (Socket : access Gtk_Socket_RecordTo API docTo specTo body) return Guint32To API docTo spec;

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.

113.        function Get_Plug_WindowTo API docTo body

114.          (Socket : access Gtk_Socket_RecordTo API docTo specTo body) return Gdk.Window.Gdk_WindowTo API docTo spec;

115.        --  Return the id of the embedded window.

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>

126.        procedure StealTo API docTo body (Socket : access Gtk_Socket_RecordTo API docTo specTo body; Wid : Guint32To API docTo spec);

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.

136.        --  </doc_ignore>

138.        ----------------

139.        -- Properties --

140.        ----------------

142.        --  <properties>

143.        --  The following properties are defined for this widget. See

144.        --  Glib.Properties for more information on properties.

145.        --

146.        --  </properties>

148.        -------------

149.        -- Signals --

150.        -------------

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>

168.        Signal_Plug_Added   : constant Glib.Signal_NameTo API docTo spec := "plug_added";

169.        Signal_Plug_Removed : constant Glib.Signal_NameTo API docTo spec := "plug_removed";

171.     private

173.        type Gtk_Socket_RecordTo API docTo spec is new Gtk.Container.Gtk_Container_RecordTo API docTo specTo body

174.          with null record;

176.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_socket_get_type");

177.     end Gtk.SocketTo API docTo specTo body;

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>