## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

1.     -----------------------------------------------------------------------

2.     --               GtkAda - Ada95 binding for Gtk+/Gnome               --

3.     --                                                                   --

4.     --                 Copyright (C) 2002-2009, AdaCore                  --

5.     --                                                                   --

6.     -- This library is free software; you can redistribute it and/or     --

7.     -- modify it under the terms of the GNU General Public               --

8.     -- License as published by the Free Software Foundation; either      --

9.     -- version 2 of the License, or (at your option) any later version.  --

10.     --                                                                   --

11.     -- This library is distributed in the hope that it will be useful,   --

12.     -- but WITHOUT ANY WARRANTY; without even the implied warranty of    --

13.     -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --

14.     -- General Public License for more details.                          --

15.     --                                                                   --

16.     -- You should have received a copy of the GNU General Public         --

17.     -- License along with this library; if not, write to the             --

18.     -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --

19.     -- Boston, MA 02111-1307, USA.                                       --

20.     --                                                                   --

21.     -- As a special exception, if other files instantiate generics from  --

22.     -- this unit, or you link this unit with other files to produce an   --

23.     -- executable, this  unit  does not  by itself cause  the resulting  --

24.     -- executable to be covered by the GNU General Public License. This  --

25.     -- exception does not however invalidate any other reasons why the   --

26.     -- executable file  might be covered by the  GNU Public License.     --

27.     -----------------------------------------------------------------------

29.     --  <description>

30.     --  The Gtk_Clipboard object represents a clipboard of data shared between

31.     --  different processes or between different widgets in the same process. Each

32.     --  clipboard is identified by a name encoded as a Gdk_Atom. (Conversion to and

33.     --  from strings can be done with gdk.properties.atom_intern and

34.     --  gdk.properties.atom_name().) The default clipboard corresponds to the

35.     --  "CLIPBOARD" atom; another commonly used clipboard is the "PRIMARY"

36.     --  clipboard, which, in X, traditionally contains the currently selected text.

37.     --

38.     --  To support having a number of different formats on the clipboard at the

39.     --  same time, the clipboard mechanism allows providing callbacks instead of

40.     --  the actual data. When you set the contents of the clipboard, you can either

41.     --  supply the data directly (via functions like Set_Text), or you can supply a

42.     --  callback to be called at a later time when the data is needed (via

43.     --  Set_With_Data or Set_With_Owner.) Providing a callback also avoids having

44.     --  to make copies of the data when it is not needed.

45.     --

46.     --  Set_With_Data and Set_With_Owner are quite similar; the choice between the

47.     --  two depends mostly on which is more convenient in a particular situation.

48.     --  The former is most useful when you want to have a blob of data with

49.     --  callbacks to convert it into the various data types that you advertise.

50.     --  When the clear_func you provided is called, you simply free the data blob.

51.     --  The latter is more useful when the contents of clipboard reflect the

52.     --  internal state of a GObject (As an example, for the PRIMARY clipboard, when

53.     --  an entry widget provides the clipboard's contents the contents are simply

54.     --  the text within the selected region.) If the contents change, the entry

55.     --  widget can call Set_With_Owner() to update the timestamp for clipboard

56.     --  ownership, without having to worry about clear_func being called.

57.     --

58.     --  Requesting the data from the clipboard is essentially asynchronous. If the

59.     --  contents of the clipboard are provided within the same process, then direct

60.     --  function call will be made to retrieve the data, but if they are provided

61.     --  by another process, then the data needs to be retrieved from the other

62.     --  process, which may take some time. To avoid blocking the user interface,

63.     --  the call to request the selection, Request_Contents takes a callback that

64.     --  will be called when the contents are received (or when the request fails.)

65.     --  If you don't want to deal with providing a separate callback, you can also

66.     --  use Wait_For_Contents. What this does is run the GLib main loop recursively

67.     --  waiting for the contents. This can simplify the code flow, but you still

68.     --  have to be aware that other callbacks in your program can be called while

69.     --  this recursive mainloop is running.

70.     --

71.     --  Along with the functions to get the clipboard contents as an arbitrary data

72.     --  chunk, there are also functions to retrieve it as text, Request_Text and

73.     --  Wait_For_Text. These functions take care of determining which formats are

74.     --  advertised by the clipboard provider, asking for the clipboard in the best

75.     --  available format and converting the results into the UTF-8 encoding. (The

76.     --  standard form for representing strings in GTK+.)

77.     --  </description>

78.     --  <c_version>2.8.17</c_version>

79.     --  <group>Inter-Process communication</group>

80.     --  <testgtk>create_clipboard.adb</testgtk>

82.     with Gdk.PixbufTo API docTo specTo body;

83.     with Gdk.TypesTo API docTo spec;

84.     with Gtk.SelectionTo API docTo specTo body;

85.     with Gtk.WidgetTo API docTo specTo body;

86.     with Interfaces.C.Strings;

87.     with System;

89.     package Gtk.ClipboardTo API docTo specTo body is

91.        type Gtk_Clipboard is new Glib.C_ProxyTo API docTo spec;

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

94.        --  Return the internal type used for clipboards

96.        function Get_ClipboardTo API docTo body

97.          (Widget    : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class;

98.           Selection : Gdk.Types.Gdk_AtomTo API docTo spec)

99.           return Gtk.Clipboard.Gtk_ClipboardTo API docTo spec;

100.        --  Returns the clipboard object for the given selection to be used with

101.        --  Widget. Widget must have a Gdk_Display associated with it, so must be

102.        --  attached to a toplevel window.

103.        --

104.        --  Return value: the appropriate clipboard object. If no clipboard already

105.        --  exists, a new one will be created. Once a clipboard object has been

106.        --  created, it is persistent for all time.

108.        function GetTo API docTo body

109.          (Selection : Gdk.Types.Gdk_AtomTo API docTo spec := Gdk.Types.Gdk_NoneTo API docTo spec)

110.           return Gtk_ClipboardTo API docTo spec;

111.        --  Return the clipboard object for the given selection. Cut/copy/paste menu

112.        --  items and keyboard shortcuts should use the default clipboard, returned

113.        --  by passing Gdk_None for Selection. The currently-selected object or text

114.        --  should be provided on the clipboard identified by Selection_Primary.

115.        --  Cut/copy/paste menu items conceptually copy the contents of the

116.        --  Selection_Primary clipboard to the default clipboard, i.e. they copy the

117.        --  selection to what the user sees as the clipboard.

118.        --

119.        --  (Passing Gdk_None is the same as using Atom_Intern ("CLIPBOARD", False).

120.        --  See http://standards.freedesktop.org/clipboards-spec/ for a

121.        --  detailed discussion of the "CLIPBOARD" vs. "PRIMARY" selections under

122.        --  the X window system. On Win32 the Selection_Primary clipboard is

123.        --  essentially ignored.)

124.        --

125.        --  It's possible to have arbitrary named clipboards; if you do invent new

126.        --  clipboards, you should prefix the selection name with an underscore

127.        --  (because the ICCCM requires that nonstandard atoms are

128.        --  underscore-prefixed), and namespace it as well. For example, if your

129.        --  application called "Foo" has a special-purpose clipboard, you might call

130.        --  it "_FOO_SPECIAL_CLIPBOARD".

131.        --

132.        --  Selection is a Gdk_Atom which identifies the clipboard to use.

133.        --

134.        --  If no clipboard already exists, a new one will be created. Once

135.        --  clipboard object has been created, it is persistent for all time and

136.        --  cannot be freed.

138.        procedure Set_Can_StoreTo API docTo body

139.          (Clipboard : Gtk_ClipboardTo API docTo spec;

140.           Targets   : Gtk.Selection.Target_Entry_ArrayTo API docTo spec);

141.        --  Hints that the clipboard data should be stored somewhere when the

142.        --  application exits or when Store is called.

143.        --  This value is reset when the clipboard owner changes. Where the

144.        --  clipboard data is stored is platform dependent.

145.        --  Targets is an array containing information about which forms should be

146.        --  stored, or an empty array to indicate that all forms should be stored.

148.        procedure StoreTo API docTo body (Clipboard : Gtk_ClipboardTo API docTo spec);

149.        --  Stores the current clipboard data somewhere so that it will stay

150.        --  around after the application has quit.

151.        --  See also Gdk.Display.Supports_Clipboard_Persistence and

152.        --  Gdk.Display.Store_Clipboard.

154.        function Get_OwnerTo API docTo body (Clipboard : Gtk_ClipboardTo API docTo spec) return Glib.Object.GObjectTo API docTo spec;

155.        --  If the clipboard contents callbacks were set with Set_With_Owner, and

156.        --  the Set_With_Data or Clear has not subsequently called, returns the

157.        --  owner set by Set_With_Owner.

159.        procedure ClearTo API docTo body (Clipboard : Gtk_ClipboardTo API docTo spec);

160.        --  Clear the contents of the clipboard.

161.        --  Generally this should only be called between the time you call

162.        --  Set_With_Owner or Set_With_Data, and when the Clear_Func you supplied

163.        --  is called. Otherwise, the clipboard may be owned by someone else.

165.        ----------

166.        -- Text --

167.        ----------

169.        type Gtk_Clipboard_Text_Received_Func is access

170.          procedure (Clipboard : Gtk_ClipboardTo API docTo spec;

171.                     Text      : Interfaces.C.Strings.chars_ptr;

172.                     Data      : System.Address);

173.        pragma Convention (C, Gtk_Clipboard_Text_Received_FuncTo API docTo spec);

174.        --  Called when some text is received from the keyboard, or the retrieval

175.        --  fails.

176.        --  The Text parameter will contain the resulting text if the request

177.        --  succeeded, or Null_Ptr if it failed. This could happen for various

178.        --  reasons, in particular if the clipboard was empty or if the contents of

179.        --  the clipboard could not be converted into text form.

181.        procedure Set_TextTo API docTo body

182.          (Clipboard : Gtk_ClipboardTo API docTo spec;

183.           Text      : UTF8_StringTo API docTo spec);

184.        --  Set the contents of the clipboard.

186.        function Wait_For_TextTo API docTo body (Clipboard : Gtk_ClipboardTo API docTo spec) return UTF8_StringTo API docTo spec;

187.        --  Requests the contents of the clipboard as text and converts the result

188.        --  to UTF-8 if necessary. This function waits for the data to be received

189.        --  using the main loop, so events, timeouts, etc, may be dispatched during

190.        --  the wait.

191.        --

192.        --  Return "" if retrieving the selection data failed. (This could happen

193.        --  for various reasons, in particular if the clipboard was empty or if the

194.        --  contents of the clipboard could not be converted into text form)

196.        function Wait_Is_Text_AvailableTo API docTo body

197.          (Clipboard : Gtk_ClipboardTo API docTo spec) return Boolean;

198.        --  Test to see if there is text available to be pasted. This function waits

199.        --  for the data to be received using the main loop, so events, timeouts,

200.        --  etc, may be dispatched during the wait.

202.        procedure Request_TextTo API docTo body

203.          (Clipboard : Gtk_ClipboardTo API docTo spec;

204.           Callback  : Gtk_Clipboard_Text_Received_FuncTo API docTo spec;

205.           User_Data : System.Address);

206.        --  Requests the contents of the clipboard as text. When the text is later

207.        --  received, it will be converted to UTF-8 if necessary, and Callback will

208.        --  be called.

210.        ------------

211.        -- Images --

212.        ------------

214.        type Gtk_Clipboard_Image_Received_Func is access

215.          procedure (Clipboard : Gtk_ClipboardTo API docTo spec;

216.                     Pixbuf    : System.Address;

217.                     Data      : System.Address);

218.        pragma Convention (C, Gtk_Clipboard_Image_Received_FuncTo API docTo spec);

219.        --  Pixbuf will contain null if the request failed.

220.        --  Pixbuf must not be Unref. Pixbuf must be converted to GtkAda object

221.        --  using Gdk.Pixbuf.Convert.

223.        procedure Set_ImageTo API docTo body

224.          (Clipboard : Gtk_ClipboardTo API docTo spec;

225.           Pixbuf    : Gdk.Pixbuf.Gdk_PixbufTo API docTo spec);

226.        --  Sets the contents of the clipboard to the given pixbuf. GTK+ will take

227.        --  responsibility for responding for requests for the image, and for

228.        --  converting the image into the requested format.

230.        function Wait_For_ImageTo API docTo body

231.          (Clipboard : Gtk_ClipboardTo API docTo spec)

232.           return Gdk.Pixbuf.Gdk_PixbufTo API docTo spec;

233.        --  Requests the contents of the clipboard as image and converts the result

234.        --  to a pixbuf. This function waits for the data to be received using the

235.        --  main loop, so events, timeouts, etc, may be dispatched during the wait.

236.        --  The returned value must be freed with a call to Unref.

238.        function Wait_Is_Image_AvailableTo API docTo body (Clipboard : Gtk_ClipboardTo API docTo spec) return Boolean;

239.        --  Test to see if there is an image available to be pasted. This is done by

240.        --  requesting the TARGETS atom and checking if it contains any of the

241.        --  supported image targets. This function waits for the data to be received

242.        --  using the main loop, so events, timeouts, etc, may be dispatched during

243.        --  the wait.

244.        --  This function is a little faster than calling Wait_For_Image since it

245.        --  doesn't need to retrieve the actual image data.

247.        procedure Request_ImageTo API docTo body

248.          (Clipboard : Gtk_ClipboardTo API docTo spec;

249.           Callback  : Gtk_Clipboard_Image_Received_FuncTo API docTo spec;

250.           User_Data : System.Address);

251.        --  Requests the contents of the clipboard as image. When the image is

252.        --  later received, it will be converted to a pixbuf, and Callback

253.        --  will be called.

255.        --------------------

256.        -- Other contents --

257.        --------------------

259.        type Gtk_Clipboard_Get_Func is access procedure

260.          (Clipboard          : Gtk_ClipboardTo API docTo spec;

261.           Selection_Data     : Gtk.Selection.Selection_DataTo API docTo spec;

262.           Info               : GuintTo API docTo spec;

263.           User_Data_Or_Owner : System.Address);

264.        pragma Convention (C, Gtk_Clipboard_Get_FuncTo API docTo spec);

265.        --  Called when the actual clipboard data is requested. Selection_Data

266.        --  should be modified to return the data.

267.        --  Info describes the expected format (see Gtk.Selection.Target_Entry).

268.        --  If User_Data is the owner (ie when you used Set_With_Owner), you must

269.        --  convert it to a proper Gtk_Widget by using Gtk.Widget.Convert.

271.        type Gtk_Clipboard_Clear_Func is access procedure

272.          (Clipboard          : Gtk_ClipboardTo API docTo spec;

273.           User_Data_Or_Owner : System.Address);

274.        pragma Convention (C, Gtk_Clipboard_Clear_FuncTo API docTo spec);

275.        --  Called when the contents of the clipboard is overriden. Get_Func will

276.        --  not be called subsequently.

277.        --  If User_Data is the owner (ie when you used Set_With_Owner), you must

278.        --  convert it to a proper Gtk_Widget by using Gtk.Widget.Convert.

280.        type Gtk_Clipboard_Received_Func is access procedure

281.          (Clipboard      : Gtk_ClipboardTo API docTo spec;

282.           Selection_Data : Gtk.Selection.Selection_DataTo API docTo spec;

283.           User_Data      : System.Address);

284.        pragma Convention (C, Gtk_Clipboard_Received_FuncTo API docTo spec);

285.        --  Called when data from the clipboard is made available to the application

287.        type Gtk_Clipboard_Targets_Received_Func is access procedure

288.          (Clipboard      : Gtk_ClipboardTo API docTo spec;

289.           Atoms          : Gdk.Types.Gdk_Atom_ArrayTo API docTo spec;

290.           N_Atoms        : GintTo API docTo spec;

291.           User_Data      : System.Address);

292.        pragma Convention (C, Gtk_Clipboard_Targets_Received_FuncTo API docTo spec);

293.        --  Called when the application has requested the list of supported targets

294.        --  for the current clipboard

296.        function Set_With_DataTo API docTo body

297.          (Clipboard  : Gtk_ClipboardTo API docTo spec;

298.           Targets    : Gtk.Selection.Target_Entry_ArrayTo API docTo spec;

299.           Get_Func   : Gtk_Clipboard_Get_FuncTo API docTo spec;

300.           Clear_Func : Gtk_Clipboard_Clear_FuncTo API docTo spec;

301.           User_Data  : System.Address)

302.           return Boolean;

303.        --  Virtually sets the contents of the specified clipboard by providing a

304.        --  list of supported formats for the clipboard data and a function to call

305.        --  to get the actual data when it is requested. No actual copy of the data

306.        --  is made until someones actually requests it.

307.        --  Targets contains information about the available forms for the clipboard

308.        --  data.

309.        --  This function returns True if setting the clipboard data succeeded.

311.        function Set_With_OwnerTo API docTo body

312.          (Clipboard  : Gtk_ClipboardTo API docTo spec;

313.           Targets    : Gtk.Selection.Target_Entry_ArrayTo API docTo spec;

314.           Get_Func   : Gtk_Clipboard_Get_FuncTo API docTo spec;

315.           Clear_Func : Gtk_Clipboard_Clear_FuncTo API docTo spec;

316.           Owner      : access Glib.Object.GObject_RecordTo API docTo specTo body'Class)

317.           return Boolean;

318.        --  Same as Set_With_Data, but an actual object is passed instead of a

319.        --  generic user_data. This takes care of referencing the object as

320.        --  appropriate.

322.        function Wait_For_TargetsTo API docTo body

323.          (Clipboard : Gtk_ClipboardTo API docTo spec) return Gdk.Types.Gdk_Atom_ArrayTo API docTo spec;

324.        --  Returns a list of targets that are present on the clipboard, or an empty

325.        --  array if there aren't any targets available.

326.        --  This function waits for the data to be received using the main

327.        --  loop, so events, timeouts, etc, may be dispatched during the wait.

329.        function Wait_For_ContentsTo API docTo body

330.          (Clipboard : Gtk_ClipboardTo API docTo spec;

331.           Target    : Gdk.Types.Gdk_AtomTo API docTo spec)

332.           return Gtk.Selection.Selection_DataTo API docTo spec;

333.        --  Requests the contents of the clipboard using the given target. This

334.        --  function waits for the data to be received using the main loop, so

335.        --  events, timeouts, etc, may be dispatched during the wait.

336.        --  The result must be freed.

338.        function Wait_Is_Target_AvailableTo API docTo body

339.          (Clipboard : Gtk_ClipboardTo API docTo spec; Target : Gdk.Types.Gdk_AtomTo API docTo spec) return Boolean;

340.        --  Checks if a clipboard supports pasting data of a given type. This

341.        --  function can be used to determine if a "Paste" menu item should be

342.        --  insensitive or not.

343.        --  If you want to see if there's text available on the clipboard, use

344.        --  Wait_Is_Text_Available instead.

345.        --  The value for Target is similar to the one in Gtk.Selection.Target_Entry

347.        procedure Request_ContentsTo API docTo body

348.          (Clipboard : Gtk_ClipboardTo API docTo spec;

349.           Target    : Gdk.Types.Gdk_AtomTo API docTo spec;

350.           Callback  : Gtk_Clipboard_Received_FuncTo API docTo spec;

351.           User_Data : System.Address);

352.        --  Requests the contents of clipboard as the given target.

353.        --  When the results of the result are later received the supplied callback

354.        --  will be called.

356.        procedure Request_TargetsTo API docTo body

357.          (Clipboard : Gtk_ClipboardTo API docTo spec;

358.           Callback  : Gtk_Clipboard_Targets_Received_FuncTo API docTo spec;

359.           User_Data : System.Address);

360.        --  Requests the contents of the clipboard as list of supported targets.

361.        --  When the list is later received, Callback will be called.

363.        -------------

364.        -- Signals --

365.        -------------

367.        --  <signals>

368.        --  The following new signals are defined for this widget:

369.        --

370.        --  - "owner_change"

371.        --    Emitted when the owner of the clipboard has changed

372.        --

373.        --  </signals>

375.        Signal_Owner_Change : constant Glib.Signal_NameTo API docTo spec := "owner_change";

377.     private

378.        pragma Import (C, Get_TypeTo API docTo spec,          "gtk_clipboard_get_type");

379.        pragma Import (C, GetTo API docTo spec,               "gtk_clipboard_get");

380.        pragma Import (C, ClearTo API docTo spec,             "gtk_clipboard_clear");

381.        pragma Import (C, StoreTo API docTo spec,             "gtk_clipboard_store");

382.        pragma Import (C, Request_TextTo API docTo spec,      "gtk_clipboard_request_text");

383.        pragma Import (C, Request_ImageTo API docTo spec,     "gtk_clipboard_request_image");

384.        pragma Import (C, Wait_For_ContentsTo API docTo spec, "gtk_clipboard_wait_for_contents");

385.     end Gtk.ClipboardTo API docTo specTo body;

387.     --  No binding: gtk_clipboard_get_display

388.     --  No binding: gtk_clipboard_get_for_display