1----------------------------------------------------------------------- 2-- GtkAda - Ada95 binding for Gtk+/Gnome -- 3-- -- 4-- Copyright (C) 2004-2013, 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----------------------------------------------------------------------- 28 29-- <description> 30-- Browse the available stock icons in the list of stock IDs found here. You 31-- can also use the gtk-demo application for this purpose. 32-- 33-- An icon factory manages a collection of Gtk_Icon_Set; a Gtk_Icon_Set 34-- manages set of variants of a particular icon (i.e. a Gtk_Icon_Set contains 35-- variants for different sizes and widget states). Icons in an icon factory 36-- are named by a stock ID, which is a simple string identifying the icon. 37-- Each Gtk_Style has a list of Gtk_Icon_Factory derived from the current 38-- theme; those icon factories are consulted first when searching for an icon. 39-- If the theme doesn't set a particular icon, GTK+ looks for the icon in a 40-- list of default icon factories, maintained by gtk.icon_factory.add_default 41-- and gtk.icon_factory.remove_default. Applications with icons should add 42-- default icon factory with their icons, which will allow themes to override 43-- the icons for the application. 44-- 45-- To display an icon, always use Lookup_Icon_Set on the widget that 46-- will display the icon, or the convenience function Gtk.Widget.Render_Icon. 47-- These functions take the theme into account when looking up the icon to use 48-- for a given stock ID. 49-- </description> 50-- <c_version>2.8.17</c_version> 51-- <see>Gtk.Icon_Theme</see> 52 53with Glib.Object; 54with Gdk.Pixbuf; 55with Gtk.Enums; 56with Gtk.Settings; 57with Gtk.Style; 58with Gtk.Widget; 59 60package Gtk.Icon_Factory is 61 62 -------------------- 63 -- Icon factories -- 64 -------------------- 65 66 type Gtk_Icon_Factory_Record is new Glib.Object.GObject_Record with private; 67 type Gtk_Icon_Factory is access all Gtk_Icon_Factory_Record'Class; 68 69 procedure Gtk_New (Widget : out Gtk_Icon_Factory); 70 procedure Initialize (Widget : access Gtk_Icon_Factory_Record'Class); 71 -- Creates or initializes a new Icon_Factory. 72 73 function Get_Type return Glib.GType; 74 -- Return the internal value associated with a Icon_Factory. 75 76 procedure Add_Default (Factory : access Gtk_Icon_Factory_Record); 77 -- Adds an icon factory to the list of icon factories searched by 78 -- Lookup_Icon_Set. This means that, for example, 79 -- Gtk.Image.New_From_Stock will be able to find icons in Factory. 80 -- There will normally be an icon factory added for each library or 81 -- application that comes with icons. The default icon factories 82 -- can be overridden by themes. 83 84 procedure Remove_Default (Factory : access Gtk_Icon_Factory_Record); 85 -- Removes an icon factory from the list of default icon 86 -- factories. Not normally used; you might use it for a library that 87 -- can be unloaded or shut down. 88 89 --------------- 90 -- Icon sets -- 91 --------------- 92 93 -- An icon set represents a single icon in various sizes and widget states. 94 -- It can provide a Gdk_Pixbuf for a given size and state on request, and 95 -- automatically caches some of the rendered Gdk_Pixbuf objects. 96 -- 97 -- Normally you would use Gtk.Widget.Render_Icon instead of using icon sets 98 -- directly. The one case where you'd use an icon set is to create 99 -- application-specific icon sets to place in an icon factory. 100 101 type Gtk_Icon_Set is new Glib.C_Proxy; 102 103 function Gtk_New return Gtk_Icon_Set; 104 -- Create an empty Gtk_Icon_Set. 105 106 function Gtk_New (Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf) return Gtk_Icon_Set; 107 -- Creates a new icon set with Pixbuf as the default/fallback source 108 -- image. If you don't add any additional icon sources (see below) to the 109 -- icon set, all variants of the icon will be created from Pixbuf, 110 -- using scaling, pixelation, etc. as required to adjust the icon size 111 -- or make the icon look insensitive/prelighted. 112 113 procedure Add 114 (Factory : access Gtk_Icon_Factory_Record; 115 Stock_Id : String; 116 Set : Gtk_Icon_Set); 117 -- Adds the given icon set to the icon factory, under the name Stock_Id. 118 -- Stock_Id should be namespaced for your application, e.g. 119 -- "myapp-whatever-icon". Normally applications create an icon factory, 120 -- then add it to the list of default factories with Add_Default. Then they 121 -- pass the Stock_Id to widgets such as Gtk_Image to display the icon. 122 -- Themes can provide an icon with the same name (such as 123 -- "myapp-whatever-icon") to override your application's default icons. If 124 -- an icon already existed in Factory for Stock_Id, it is unreferenced and 125 -- replaced with the new icon set. 126 127 function Lookup_Icon_Set 128 (Style : access Gtk.Style.Gtk_Style_Record'Class; Stock_Id : String) 129 return Gtk_Icon_Set; 130 -- Retrieve an icon set by its name. The icon might exist in various sizes, 131 -- that can be manipulated through the result set 132 133 function Lookup 134 (Factory : access Gtk_Icon_Factory_Record; 135 Stock_Id : String) return Gtk_Icon_Set; 136 -- Looks up Stock_Id in the icon factory, returning an icon set if found, 137 -- otherwise null. For display to the user, you should use 138 -- Lookup_Icon_Set on the Gtk_Style for the widget that will 139 -- display the icon, instead of using this function directly, so that 140 -- themes are taken into account. 141 142 function Lookup_Default (Stock_Id : String) return Gtk_Icon_Set; 143 -- Looks for an icon in the list of default icon factories. For 144 -- display to the user, you should use Lookup_Icon_Set on 145 -- the Gtk_Style for the widget that will display the icon, instead of 146 -- using this function directly, so that themes are taken into 147 -- account. 148 149 function Icon_Set_Get_Type return Glib.GType; 150 -- Return the internal type value for Gtk_Icon_Set 151 152 function Copy (Icon_Set : Gtk_Icon_Set) return Gtk_Icon_Set; 153 pragma Import (C, Copy, "gtk_icon_set_copy"); 154 -- Copies Icon_Set by value. 155 156 function Get_Sizes (Icon_Set : Gtk_Icon_Set) return Gint_Array; 157 -- Obtains a list of icon sizes this icon set can render. 158 159 procedure Ref (Icon_Set : Gtk_Icon_Set); 160 procedure Unref (Icon_Set : Gtk_Icon_Set); 161 pragma Import (C, Ref, "gtk_icon_set_ref"); 162 pragma Import (C, Unref, "gtk_icon_set_unref"); 163 -- Increase or decrease the reference counting for the icon set. When this 164 -- reaches 0, the memory is reclaimed 165 166 function Render_Icon 167 (Icon_Set : Gtk_Icon_Set; 168 Style : access Gtk.Style.Gtk_Style_Record'Class; 169 Direction : Gtk.Enums.Gtk_Text_Direction; 170 State : Gtk.Enums.Gtk_State_Type; 171 Size : Gtk.Enums.Gtk_Icon_Size; 172 Widget : Gtk.Widget.Gtk_Widget := null; 173 Detail : String := "") 174 return Gdk.Pixbuf.Gdk_Pixbuf; 175 -- Renders an icon using Render_Icon below. In most cases, the other 176 -- version of Render_Icon is better, since it automatically provides most 177 -- of the arguments from the current widget settings. This function never 178 -- returns null; if the icon can't be rendered (perhaps because an image 179 -- file fails to load), a default "missing image" icon will be returned 180 -- instead. 181 -- Widget is the widget that will display the icon, or null. This is 182 -- typically used to determine the screen (and thus the colormap depth). 183 -- Detail is the string to pass to the theme engine to provide more 184 -- information. Passing anything but the empty string will disable 185 -- caching. 186 187 ------------------ 188 -- Icon sources -- 189 ------------------ 190 191 -- An icon source contains a Gdk_Pixbuf (or image filename) that serves as 192 -- the base image for one or more of the icons in an icon set, along with a 193 -- specification for which icons in the icon set will be based on that 194 -- pixbuf or image file. An icon set contains a set of icons that represent 195 -- "the same" logical concept in different states, different global text 196 -- directions, and different sizes. 197 -- 198 -- So for example a web browser's "Back to Previous Page" icon might point 199 -- in a different direction in Hebrew and in English; it might look 200 -- different when insensitive; and it might change size depending on 201 -- toolbar mode (small/large icons). So a single icon set would contain all 202 -- those variants of the icon. An icon set contains a list of icon sources 203 -- from which it can derive specific icon variants in the set. 204 -- 205 -- In the simplest case, an icon set contains one source pixbuf from which 206 -- it derives all variants. 207 -- 208 -- If you want to use a different base pixbuf for different icon variants, 209 -- you create multiple icon sources, mark which variants they'll be used to 210 -- create, and add them to the icon set with Add_Source (see below). 211 -- 212 -- By default, the icon source has all parameters wildcarded. That is, the 213 -- icon source will be used as the base icon for any desired text 214 -- direction, widget state, or icon size. 215 216 type Gtk_Icon_Source is new Glib.C_Proxy; 217 218 function Gtk_New return Gtk_Icon_Source; 219 -- Create a new icon source. 220 221 function Icon_Source_Copy (Source : Gtk_Icon_Source) return Gtk_Icon_Source; 222 -- Returns a copy of Gtk_Icon_Source. This function is generally not 223 -- useful 224 225 function Icon_Source_Get_Type return Glib.GType; 226 -- Return the internal type used for Gtk_Icon_Source 227 228 function Render_Icon 229 (Style : access Gtk.Style.Gtk_Style_Record'Class; 230 Source : Gtk.Icon_Factory.Gtk_Icon_Source; 231 Direction : Gtk.Enums.Gtk_Text_Direction; 232 State : Gtk.Enums.Gtk_State_Type; 233 Size : Gtk.Enums.Gtk_Icon_Size; 234 Widget : Gtk.Widget.Gtk_Widget := null; 235 Detail : String := "") 236 return Gdk.Pixbuf.Gdk_Pixbuf; 237 -- Renders the icon specified by Source at the given Size according to the 238 -- given parameters and returns the result in pixbuf. 239 240 procedure Add_Source 241 (Set : Gtk_Icon_Set; 242 Source : Gtk_Icon_Source); 243 -- Icon sets have a list of icon sources, which they use as base 244 -- icons for rendering icons in different states and sizes. Icons are 245 -- scaled, made to look insensitive, etc. in Gtk.Icon.Set_Render_Icon, 246 -- but an icon set needs base images to work with. The base images and 247 -- when to use them are described by an icon source. 248 -- This function copies Source, so you can reuse the same source 249 -- immediately without affecting the icon set. 250 251 procedure Free (Source : Gtk_Icon_Source); 252 -- Free memory allocated to Source. 253 254 procedure Set_Filename 255 (Source : Gtk_Icon_Source; Filename : String); 256 function Get_Filename (Source : Gtk_Icon_Source) return String; 257 -- Set the name of an image file to use as a base image when creating 258 -- icon variants for an icon set. The filename must be absolute. 259 260 procedure Set_Pixbuf 261 (Source : Gtk_Icon_Source; Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf); 262 function Get_Pixbuf 263 (Source : Gtk_Icon_Source) return Gdk.Pixbuf.Gdk_Pixbuf; 264 -- Set a pixbuf to use as a base image when creating icon variants 265 -- for an icon set. If an icon source has both a filename and a pixbuf 266 -- set, the pixbuf will take priority. 267 268 procedure Set_Size 269 (Source : Gtk_Icon_Source; Size : Gtk.Enums.Gtk_Icon_Size); 270 function Get_Size 271 (Source : Gtk_Icon_Source) return Gtk.Enums.Gtk_Icon_Size; 272 -- Set the icon size this icon source is intended to be used with 273 274 procedure Set_Icon_Name (Source : Gtk_Icon_Source; Icon_Name : String); 275 function Get_Icon_Name (Source : Gtk_Icon_Source) return String; 276 -- Retrieves the source icon name, or "" if none is set. The icon comes 277 -- from an icon theme in this case. 278 279 procedure Set_Size_Wildcarded 280 (Source : Gtk_Icon_Source; Wildcarded : Boolean); 281 function Get_Size_Wildcarded (Source : Gtk_Icon_Source) return Boolean; 282 -- Change the wilcarded state of the size for the icon source. 283 -- 284 -- If the icon size is wildcarded, this source can be used as the base 285 -- image for an icon of any size. if the size is not wildcarded, then 286 -- the size the source applies to should be set with Set_Size, 287 -- and the icon source will only be used with that specific size. 288 -- 289 -- Gtk prefers non-wildcarded sources (exact matches) over wildcarded 290 -- sources, and will use an exact match when possible. 291 -- 292 -- Gtk will normally scale wildcarded source images to produce 293 -- an appropriate icon at a given size, but will not change the size 294 -- of source images that match exactly. 295 296 procedure Set_Direction_Wildcarded 297 (Source : Gtk_Icon_Source; Setting : Boolean); 298 function Get_Direction_Wildcarded 299 (Source : Gtk_Icon_Source) return Boolean; 300 -- If the text direction is wildcarded, this source can be used as the base 301 -- image for an icon in any Gtk_Text_Direction. 302 -- If the text direction is not wildcarded, then the text direction the 303 -- icon source applies to should be set with Set_Direction(), and the icon 304 -- source will only be used with that text direction. 305 -- Gtk_Icon_Set prefers non-wildcarded sources (exact matches) over 306 -- wildcarded sources, and will use an exact match when possible 307 308 procedure Set_Direction 309 (Source : Gtk_Icon_Source; Direction : Gtk.Enums.Gtk_Text_Direction); 310 function Get_Direction 311 (Source : Gtk_Icon_Source) return Gtk.Enums.Gtk_Text_Direction; 312 -- Sets the text direction this icon source is intended to be used 313 -- with. 314 -- Setting the text direction on an icon source makes no difference if the 315 -- text direction is wildcarded. Therefore, you should usually call 316 -- Set_Direction_Wildcarded() to un-wildcard it in addition to calling this 317 -- function. 318 319 procedure Set_State_Wildcarded 320 (Source : Gtk_Icon_Source; Setting : Boolean); 321 function Get_State_Wildcarded (Source : Gtk_Icon_Source) return Boolean; 322 -- If the widget state is wildcarded, this source can be used as the base 323 -- image for an icon in any Gtk_State_Type. If the widget state is not 324 -- wildcarded, then the state the source applies to should be set with 325 -- Set_State and the icon source will only be used with that specific 326 -- state. 327 -- Gtk_Icon_Set prefers non-wildcarded sources (exact matches) over 328 -- wildcarded sources, and will use an exact match when possible. 329 -- Gtk_Icon_Set will normally transform wildcarded source images to produce 330 -- an appropriate icon for a given state, for example lightening an image 331 -- on prelight, but will not modify source images that match exactly. 332 333 procedure Set_State 334 (Source : Gtk_Icon_Source; State : Gtk.Enums.Gtk_State_Type); 335 function Get_State 336 (Source : Gtk_Icon_Source) return Gtk.Enums.Gtk_State_Type; 337 -- Sets the widget state this icon source is intended to be used 338 -- with. 339 -- Setting the widget state on an icon source makes no difference if the 340 -- state is wildcarded. Therefore, you should usually call 341 -- Set_State_Wildcarded to un-wildcard it in addition to calling this 342 -- function. 343 344 ---------------- 345 -- Icon sizes -- 346 ---------------- 347 -- There are a number of predefined icon sizes (see gtk-enums.ads). These 348 -- are used in the various gtk+ contexts. However, you can also define your 349 -- own icon sizes to use in your application. 350 351 function Icon_Size_From_Name (Name : String) return Gtk.Enums.Gtk_Icon_Size; 352 -- Looks up the icon size associated with Name. 353 -- Predefined icon sizes are associated with the following names: 354 -- Icon_Size_Menu => "gtk-menu" (16x16) 355 -- Icon_Size_Button => "gtk-button" (20x20) 356 -- Icon_Size_Small_Toolbar => "gtk-small-toolbar" (18x18) 357 -- Icon_Size_Large_Toolbar => "gtk-large-toolbar" (24x24) 358 -- Icon_Size_Dnd => "gtk-dnd" (32x32) 359 -- Icon_Size_Dialog => "gtk-dialog" (48x48) 360 -- You can also define your own names (see Icon_Size_Register) 361 362 function Icon_Size_Get_Name (Size : Gtk.Enums.Gtk_Icon_Size) return String; 363 -- Gets the canonical name of the given icon size 364 365 procedure Icon_Size_Lookup 366 (Size : Gtk.Enums.Gtk_Icon_Size; 367 Width, Height : out Gint); 368 -- Obtains the pixel size of a semantic icon size, possibly 369 -- modified by user preferences for the default Gtk_Settings. 370 -- (See Icon_Size_Lookup_For_Settings). 371 -- This function isn't normally needed, Render_Icon is the usual way to get 372 -- an icon for rendering, then just look at the size of the rendered 373 -- pixbuf. The rendered pixbuf may not even correspond to the width/height 374 -- returned by Icon_Size_Lookup, because themes are free to render the 375 -- pixbuf however they like, including changing the usual size. 376 -- Sizes are set to -1 if Size is invalid. 377 378 procedure Icon_Size_Lookup_For_Settings 379 (Settings : access Gtk.Settings.Gtk_Settings_Record'Class; 380 Size : Gtk.Enums.Gtk_Icon_Size; 381 Width : out Gint; 382 Height : out Gint); 383 -- Obtains the pixel size of a semantic icon size, possibly modified by 384 -- user preferences for a particular Gtk_Settings. 385 386 function Icon_Size_Register 387 (Name : String; 388 Width : Gint; 389 Height : Gint) 390 return Gtk.Enums.Gtk_Icon_Size; 391 -- Registers a new icon size, along the same lines as Icon_Size_Menu, 392 -- etc. Returns the integer value for the size. 393 394 procedure Icon_Size_Register_Alias 395 (Alias : String; Target : Gtk.Enums.Gtk_Icon_Size); 396 -- Registers Alias as another name for Target. 397 -- So calling Icon_Size_From_Name with Alias as argument will return Target 398 399 ------------- 400 -- Signals -- 401 ------------- 402 403 -- <signals> 404 -- The following new signals are defined for this widget: 405 -- </signals> 406 407private 408 type Gtk_Icon_Factory_Record is 409 new Glib.Object.GObject_Record with null record; 410 411 pragma Import (C, Get_Type, "gtk_icon_factory_get_type"); 412 pragma Import (C, Set_Size, "gtk_icon_source_set_size"); 413 pragma Import (C, Get_Size, "gtk_icon_source_get_size"); 414 pragma Import (C, Icon_Set_Get_Type, "gtk_icon_set_get_type"); 415 pragma Import (C, Icon_Source_Get_Type, "gtk_icon_source_get_type"); 416 pragma Import (C, Set_Direction, "gtk_icon_source_set_direction"); 417 pragma Import (C, Get_Direction, "gtk_icon_source_get_direction"); 418 pragma Import (C, Set_State, "gtk_icon_source_set_state"); 419 pragma Import (C, Get_State, "gtk_icon_source_get_state"); 420 pragma Import (C, Icon_Source_Copy, "gtk_icon_source_copy"); 421 422end Gtk.Icon_Factory; 423