File: gtk-icon_factory.ads

package info (click to toggle)
libgtkada2 2.8.1-6lenny3
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 13,496 kB
  • ctags: 3,886
  • sloc: ada: 103,189; ansic: 45,411; perl: 5,500; sh: 2,812; makefile: 1,169; xml: 19
file content (416 lines) | stat: -rw-r--r-- 20,064 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
-----------------------------------------------------------------------
--              GtkAda - Ada95 binding for Gtk+/Gnome                --
--                                                                   --
--                    Copyright (C) 2004-2006 AdaCore                --
--                                                                   --
-- This library is free software; you can redistribute it and/or     --
-- modify it under the terms of the GNU General Public               --
-- License as published by the Free Software Foundation; either      --
-- version 2 of the License, or (at your option) any later version.  --
--                                                                   --
-- This library is distributed in the hope that it will be useful,   --
-- but WITHOUT ANY WARRANTY; without even the implied warranty of    --
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --
-- General Public License for more details.                          --
--                                                                   --
-- You should have received a copy of the GNU General Public         --
-- License along with this library; if not, write to the             --
-- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --
-- Boston, MA 02111-1307, USA.                                       --
--                                                                   --
-----------------------------------------------------------------------

--  <description>
--  Browse the available stock icons in the list of stock IDs found here. You
--  can also use the gtk-demo application for this purpose.
--
--  An icon factory manages a collection of Gtk_Icon_Set; a Gtk_Icon_Set
--  manages set of variants of a particular icon (i.e. a Gtk_Icon_Set contains
--  variants for different sizes and widget states). Icons in an icon factory
--  are named by a stock ID, which is a simple string identifying the icon.
--  Each Gtk_Style has a list of Gtk_Icon_Factory derived from the current
--  theme; those icon factories are consulted first when searching for an icon.
--  If the theme doesn't set a particular icon, GTK+ looks for the icon in a
--  list of default icon factories, maintained by gtk.icon_factory.add_default
--  and gtk.icon_factory.remove_default. Applications with icons should add
--  default icon factory with their icons, which will allow themes to override
--  the icons for the application.
--
--  To display an icon, always use Lookup_Icon_Set on the widget that
--  will display the icon, or the convenience function Gtk.Widget.Render_Icon.
--  These functions take the theme into account when looking up the icon to use
--  for a given stock ID.
--  </description>
--  <c_version>2.8.17</c_version>

with Glib.Object;
with Gdk.Pixbuf;
with Gtk.Enums;
with Gtk.Settings;
with Gtk.Style;
with Gtk.Widget;

package Gtk.Icon_Factory is

   --------------------
   -- Icon factories --
   --------------------

   type Gtk_Icon_Factory_Record is new Glib.Object.GObject_Record with private;
   type Gtk_Icon_Factory is access all Gtk_Icon_Factory_Record'Class;

   procedure Gtk_New (Widget : out Gtk_Icon_Factory);
   procedure Initialize (Widget : access Gtk_Icon_Factory_Record'Class);
   --  Creates or initializes a new Icon_Factory.

   function Get_Type return Glib.GType;
   --  Return the internal value associated with a Icon_Factory.

   procedure Add_Default (Factory : access Gtk_Icon_Factory_Record);
   --  Adds an icon factory to the list of icon factories searched by
   --  Lookup_Icon_Set. This means that, for example,
   --  Gtk.Image.New_From_Stock will be able to find icons in Factory.
   --  There will normally be an icon factory added for each library or
   --  application that comes with icons. The default icon factories
   --  can be overridden by themes.

   procedure Remove_Default (Factory : access Gtk_Icon_Factory_Record);
   --  Removes an icon factory from the list of default icon
   --  factories. Not normally used; you might use it for a library that
   --  can be unloaded or shut down.

   ---------------
   -- Icon sets --
   ---------------

   --  An icon set represents a single icon in various sizes and widget states.
   --  It can provide a Gdk_Pixbuf for a given size and state on request, and
   --  automatically caches some of the rendered Gdk_Pixbuf objects.
   --
   --  Normally you would use Gtk.Widget.Render_Icon instead of using icon sets
   --  directly. The one case where you'd use an icon set is to create
   --  application-specific icon sets to place in an icon factory.

   type Gtk_Icon_Set is new Glib.C_Proxy;

   function Gtk_New return Gtk_Icon_Set;
   --  Create an empty Gtk_Icon_Set.

   function Gtk_New (Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf) return Gtk_Icon_Set;
   --  Creates a new icon set with Pixbuf as the default/fallback source
   --  image. If you don't add any additional icon sources (see below) to the
   --  icon set, all variants of the icon will be created from Pixbuf,
   --  using scaling, pixelation, etc. as required to adjust the icon size
   --  or make the icon look insensitive/prelighted.

   procedure Add
     (Factory  : access Gtk_Icon_Factory_Record;
      Stock_Id : String;
      Set      : Gtk_Icon_Set);
   --  Adds the given icon set to the icon factory, under the name Stock_Id.
   --  Stock_Id should be namespaced for your application, e.g.
   --  "myapp-whatever-icon".  Normally applications create an icon factory,
   --  then add it to the list of default factories with Add_Default. Then they
   --  pass the Stock_Id to widgets such as Gtk_Image to display the icon.
   --  Themes can provide an icon with the same name (such as
   --  "myapp-whatever-icon") to override your application's default icons. If
   --  an icon already existed in Factory for Stock_Id, it is unreferenced and
   --  replaced with the new icon set.

   function Lookup_Icon_Set
     (Style  : access Gtk.Style.Gtk_Style_Record'Class; Stock_Id : String)
      return Gtk_Icon_Set;
   --  Retrieve an icon set by its name. The icon might exist in various sizes,
   --  that can be manipulated through the result set

   function Lookup
     (Factory  : access Gtk_Icon_Factory_Record;
      Stock_Id : String) return Gtk_Icon_Set;
   --  Looks up Stock_Id in the icon factory, returning an icon set if found,
   --  otherwise null. For display to the user, you should use
   --  Lookup_Icon_Set on the Gtk_Style for the widget that will
   --  display the icon, instead of using this function directly, so that
   --  themes are taken into account.

   function Lookup_Default (Stock_Id : String) return Gtk_Icon_Set;
   --  Looks for an icon in the list of default icon factories.  For
   --  display to the user, you should use Lookup_Icon_Set on
   --  the Gtk_Style for the widget that will display the icon, instead of
   --  using this function directly, so that themes are taken into
   --  account.

   function Icon_Set_Get_Type return Glib.GType;
   --  Return the internal type value for Gtk_Icon_Set

   function Copy (Icon_Set : Gtk_Icon_Set) return Gtk_Icon_Set;
   pragma Import (C, Copy, "gtk_icon_set_copy");
   --  Copies Icon_Set by value.

   function Get_Sizes (Icon_Set : Gtk_Icon_Set) return Gint_Array;
   --  Obtains a list of icon sizes this icon set can render.

   function Ref   (Icon_Set : Gtk_Icon_Set) return Gtk_Icon_Set;
   function Unref (Icon_Set : Gtk_Icon_Set) return Gtk_Icon_Set;
   pragma Import (C, Ref,   "gtk_icon_set_ref");
   pragma Import (C, Unref, "gtk_icon_set_unref");
   --  Increase or decrease the reference counting for the icon set. When this
   --  reaches 0, the memory is reclaimed

   function Render_Icon
     (Icon_Set  : Gtk_Icon_Set;
      Style     : access Gtk.Style.Gtk_Style_Record'Class;
      Direction : Gtk.Enums.Gtk_Text_Direction;
      State     : Gtk.Enums.Gtk_State_Type;
      Size      : Gtk.Enums.Gtk_Icon_Size;
      Widget    : Gtk.Widget.Gtk_Widget := null;
      Detail    : String := "")
      return Gdk.Pixbuf.Gdk_Pixbuf;
   --  Renders an icon using Render_Icon below. In most cases, the other
   --  version of Render_Icon is better, since it automatically provides most
   --  of the arguments from the current widget settings. This function never
   --  returns null; if the icon can't be rendered (perhaps because an image
   --  file fails to load), a default "missing image" icon will be returned
   --  instead.
   --  Widget is the widget that will display the icon, or null. This is
   --  typically used to determine the screen (and thus the colormap depth).
   --  Detail is the string to pass to the theme engine to provide more
   --  information. Passing anything but the empty string will disable
   --  caching.

   ------------------
   -- Icon sources --
   ------------------

   --  An icon source contains a Gdk_Pixbuf (or image filename) that serves as
   --  the base image for one or more of the icons in an icon set, along with a
   --  specification for which icons in the icon set will be based on that
   --  pixbuf or image file. An icon set contains a set of icons that represent
   --  "the same" logical concept in different states, different global text
   --  directions, and different sizes.
   --
   --  So for example a web browser's "Back to Previous Page" icon might point
   --  in a different direction in Hebrew and in English; it might look
   --  different when insensitive; and it might change size depending on
   --  toolbar mode (small/large icons). So a single icon set would contain all
   --  those variants of the icon. An icon set contains a list of icon sources
   --  from which it can derive specific icon variants in the set.
   --
   --  In the simplest case, an icon set contains one source pixbuf from which
   --  it derives all variants.
   --
   --  If you want to use a different base pixbuf for different icon variants,
   --  you create multiple icon sources, mark which variants they'll be used to
   --  create, and add them to the icon set with Add_Source (see below).
   --
   --  By default, the icon source has all parameters wildcarded. That is, the
   --  icon source will be used as the base icon for any desired text
   --  direction, widget state, or icon size.

   type Gtk_Icon_Source is new Glib.C_Proxy;

   function Gtk_New return Gtk_Icon_Source;
   --  Create a new icon source.

   function Icon_Source_Copy (Source : Gtk_Icon_Source) return Gtk_Icon_Source;
   --  Returns a copy of Gtk_Icon_Source. This function is generally not
   --  useful

   function Icon_Source_Get_Type return Glib.GType;
   --  Return the internal type used for Gtk_Icon_Source

   function Render_Icon
     (Style     : access Gtk.Style.Gtk_Style_Record'Class;
      Source    : Gtk.Icon_Factory.Gtk_Icon_Source;
      Direction : Gtk.Enums.Gtk_Text_Direction;
      State     : Gtk.Enums.Gtk_State_Type;
      Size      : Gtk.Enums.Gtk_Icon_Size;
      Widget    : Gtk.Widget.Gtk_Widget := null;
      Detail    : String := "")
      return Gdk.Pixbuf.Gdk_Pixbuf;
   --  Renders the icon specified by Source at the given Size according to the
   --  given parameters and returns the result in pixbuf.

   procedure Add_Source
     (Set    : Gtk_Icon_Set;
      Source : Gtk_Icon_Source);
   --  Icon sets have a list of icon sources, which they use as base
   --  icons for rendering icons in different states and sizes. Icons are
   --  scaled, made to look insensitive, etc. in Gtk.Icon.Set_Render_Icon,
   --  but an icon set needs base images to work with. The base images and
   --  when to use them are described by an icon source.
   --  This function copies Source, so you can reuse the same source
   --  immediately without affecting the icon set.

   procedure Free (Source : Gtk_Icon_Source);
   --  Free memory allocated to Source.

   procedure Set_Filename
     (Source : Gtk_Icon_Source; Filename : String);
   function Get_Filename (Source : Gtk_Icon_Source) return String;
   --  Set the name of an image file to use as a base image when creating
   --  icon variants for an icon set. The filename must be absolute.

   procedure Set_Pixbuf
     (Source : Gtk_Icon_Source; Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf);
   function Get_Pixbuf
     (Source : Gtk_Icon_Source) return Gdk.Pixbuf.Gdk_Pixbuf;
   --  Set a pixbuf to use as a base image when creating icon variants
   --  for an icon set. If an icon source has both a filename and a pixbuf
   --  set, the pixbuf will take priority.

   procedure Set_Size
     (Source : Gtk_Icon_Source; Size : Gtk.Enums.Gtk_Icon_Size);
   function Get_Size
     (Source : Gtk_Icon_Source) return Gtk.Enums.Gtk_Icon_Size;
   --  Set the icon size this icon source is intended to be used with

   procedure Set_Icon_Name (Source : Gtk_Icon_Source; Icon_Name : String);
   function  Get_Icon_Name (Source : Gtk_Icon_Source) return String;
   --  Retrieves the source icon name, or "" if none is set. The icon comes
   --  from an icon theme in this case.

   procedure Set_Size_Wildcarded
     (Source : Gtk_Icon_Source; Wildcarded : Boolean);
   function Get_Size_Wildcarded (Source : Gtk_Icon_Source) return Boolean;
   --  Change the wilcarded state of the size for the icon source.
   --
   --  If the icon size is wildcarded, this source can be used as the base
   --  image for an icon of any size.  if the size is not wildcarded, then
   --  the size the source applies to should be set with Set_Size,
   --  and the icon source will only be used with that specific size.
   --
   --  Gtk prefers non-wildcarded sources (exact matches) over wildcarded
   --  sources, and will use an exact match when possible.
   --
   --  Gtk will normally scale wildcarded source images to produce
   --  an appropriate icon at a given size, but will not change the size
   --  of source images that match exactly.

   procedure Set_Direction_Wildcarded
     (Source  : Gtk_Icon_Source;  Setting : Boolean);
   function Get_Direction_Wildcarded
     (Source : Gtk_Icon_Source) return Boolean;
   --  If the text direction is wildcarded, this source can be used as the base
   --  image for an icon in any Gtk_Text_Direction.
   --  If the text direction is not wildcarded, then the text direction the
   --  icon source applies to should be set with Set_Direction(), and the icon
   --  source will only be used with that text direction.
   --  Gtk_Icon_Set prefers non-wildcarded sources (exact matches) over
   --  wildcarded sources, and will use an exact match when possible

   procedure Set_Direction
     (Source : Gtk_Icon_Source; Direction : Gtk.Enums.Gtk_Text_Direction);
   function Get_Direction
     (Source : Gtk_Icon_Source) return Gtk.Enums.Gtk_Text_Direction;
   --  Sets the text direction this icon source is intended to be used
   --  with.
   --  Setting the text direction on an icon source makes no difference if the
   --  text direction is wildcarded. Therefore, you should usually call
   --  Set_Direction_Wildcarded() to un-wildcard it in addition to calling this
   --  function.

   procedure Set_State_Wildcarded
     (Source  : Gtk_Icon_Source;  Setting : Boolean);
   function Get_State_Wildcarded (Source  : Gtk_Icon_Source) return Boolean;
   --  If the widget state is wildcarded, this source can be used as the base
   --  image for an icon in any Gtk_State_Type. If the widget state is not
   --  wildcarded, then the state the source applies to should be set with
   --  Set_State and the icon source will only be used with that specific
   --  state.
   --  Gtk_Icon_Set prefers non-wildcarded sources (exact matches) over
   --  wildcarded sources, and will use an exact match when possible.
   --  Gtk_Icon_Set will normally transform wildcarded source images to produce
   --  an appropriate icon for a given state, for example lightening an image
   --  on prelight, but will not modify source images that match exactly.

   procedure Set_State
     (Source : Gtk_Icon_Source; State  : Gtk.Enums.Gtk_State_Type);
   function Get_State
     (Source : Gtk_Icon_Source) return Gtk.Enums.Gtk_State_Type;
   --  Sets the widget state this icon source is intended to be used
   --  with.
   --  Setting the widget state on an icon source makes no difference if the
   --  state is wildcarded. Therefore, you should usually call
   --  Set_State_Wildcarded to un-wildcard it in addition to calling this
   --  function.

   ----------------
   -- Icon sizes --
   ----------------
   --  There are a number of predefined icon sizes (see gtk-enums.ads). These
   --  are used in the various gtk+ contexts. However, you can also define your
   --  own icon sizes to use in your application.

   function Icon_Size_From_Name (Name : String) return Gtk.Enums.Gtk_Icon_Size;
   --  Looks up the icon size associated with Name.
   --  Predefined icon sizes are associated with the following names:
   --    Icon_Size_Menu          => "gtk-menu"          (16x16)
   --    Icon_Size_Button        => "gtk-button"        (20x20)
   --    Icon_Size_Small_Toolbar => "gtk-small-toolbar" (18x18)
   --    Icon_Size_Large_Toolbar => "gtk-large-toolbar" (24x24)
   --    Icon_Size_Dnd           => "gtk-dnd"           (32x32)
   --    Icon_Size_Dialog        => "gtk-dialog"        (48x48)
   --  You can also define your own names (see Icon_Size_Register)

   function Icon_Size_Get_Name (Size : Gtk.Enums.Gtk_Icon_Size) return String;
   --  Gets the canonical name of the given icon size

   procedure Icon_Size_Lookup
     (Size          : Gtk.Enums.Gtk_Icon_Size;
      Width, Height : out Gint);
   --  Obtains the pixel size of a semantic icon size, possibly
   --  modified by user preferences for the default Gtk_Settings.
   --  (See Icon_Size_Lookup_For_Settings).
   --  This function isn't normally needed, Render_Icon is the usual way to get
   --  an icon for rendering, then just look at the size of the rendered
   --  pixbuf. The rendered pixbuf may not even correspond to the width/height
   --  returned by Icon_Size_Lookup, because themes are free to render the
   --  pixbuf however they like, including changing the usual size.
   --  Sizes are set to -1 if Size is invalid.

   procedure Icon_Size_Lookup_For_Settings
     (Settings : access Gtk.Settings.Gtk_Settings_Record'Class;
      Size     : Gtk.Enums.Gtk_Icon_Size;
      Width    : out Gint;
      Height   : out Gint);
   --  Obtains the pixel size of a semantic icon size, possibly modified by
   --  user preferences for a particular Gtk_Settings.

   function Icon_Size_Register
     (Name   : String;
      Width  : Gint;
      Height : Gint)
      return Gtk.Enums.Gtk_Icon_Size;
   --  Registers a new icon size, along the same lines as Icon_Size_Menu,
   --  etc. Returns the integer value for the size.

   procedure Icon_Size_Register_Alias
     (Alias : String;  Target : Gtk.Enums.Gtk_Icon_Size);
   --  Registers Alias as another name for Target.
   --  So calling Icon_Size_From_Name with Alias as argument will return Target

   -------------
   -- Signals --
   -------------

   --  <signals>
   --  The following new signals are defined for this widget:
   --  </signals>

private
   type Gtk_Icon_Factory_Record is
     new Glib.Object.GObject_Record with null record;

   pragma Import (C, Get_Type, "gtk_icon_factory_get_type");
   pragma Import (C, Set_Size, "gtk_icon_source_set_size");
   pragma Import (C, Get_Size, "gtk_icon_source_get_size");
   pragma Import (C, Icon_Set_Get_Type, "gtk_icon_set_get_type");
   pragma Import (C, Icon_Source_Get_Type, "gtk_icon_source_get_type");
   pragma Import (C, Set_Direction, "gtk_icon_source_set_direction");
   pragma Import (C, Get_Direction, "gtk_icon_source_get_direction");
   pragma Import (C, Set_State, "gtk_icon_source_set_state");
   pragma Import (C, Get_State, "gtk_icon_source_get_state");
   pragma Import (C, Icon_Source_Copy, "gtk_icon_source_copy");
   pragma Import (C, Set_Pixbuf, "gtk_icon_source_set_pixbuf");
   pragma Import (C, Get_Pixbuf, "gtk_icon_source_get_pixbuf");
end Gtk.Icon_Factory;