## 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-2006 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.     --  This package provides an interface to Gtk's configuration files.

32.     --  GTK+ provides resource file mechanism for configuring various aspects of

33.     --  the operation of a GTK+ program at runtime.

34.     --

35.     --  Default files

36.     --  =============

37.     --

38.     --  An application can cause GTK+ to parse a specific RC file by calling

39.     --  Gtk.RC.Parse. In addition to this, certain files will be read at the end

40.     --  of Gtk.Main.Init. Unless modified, the files looked for will be

41.     --  <SYSCONFDIR>/gtk-2.0/gtkrc and .gtkrc-2.0 in the users home directory.

42.     --  (<SYSCONFDIR> defaults to /usr/local/etc. It can be changed with the

43.     --  --prefix or --sysconfdir options when configuring GTK+.) Note that although

44.     --  the filenames contain the version number 2.0, all 2.x versions of GTK+ look

45.     --  for these files.

46.     --

47.     --  The set of these default files can be retrieved with

48.     --  Gtk.RC.Get_Default_Files and modified with Gtk.RC.Add_Default_File and

49.     --  Gtk.RC.Set_Default_Files. Additionally, the GTK2_RC_FILES environment

50.     --  variable can be set to a G_SEARCHPATH_SEPARATOR_S-separated list of files

51.     --  in order to overwrite the set of default files at runtime.

52.     --

53.     --  For each RC file, in addition to the file itself, GTK+ will look for a

54.     --  locale-specific file that will be parsed after the main file. For instance,

55.     --  if LANG is set to ja_JP.ujis, when loading the default file ~/.gtkrc then

56.     --  GTK+ looks for ~/.gtkrc.ja_JP and ~/.gtkrc.ja, and parses the first of

57.     --  those that exists.

58.     --

59.     --  Pathnames and patterns

60.     --  ======================

61.     --

62.     --  A resource file defines a number of styles and key bindings and attaches

63.     --  them to particular widgets. The attachment is done by the widget,

64.     --  widget_class, and class declarations. As an example of such a statement:

65.     --          widget "mywindow.*.GtkEntry" style "my-entry-class"

66.     --  attaches the style "my-entry-class" to all widgets whose widget class

67.     --  matches the pattern "mywindow.*.GtkEntry".

68.     --

69.     --  The patterns here are given in the standard shell glob syntax. The "?"

70.     --  wildcard matches any character, while "*" matches zero or more of any

71.     --  character. The three types of matching are against the widget path, the

72.     --  class path and the class hierarchy. Both the widget and the class paths

73.     --  consists of a "." separated list of all the parents of the widget and the

74.     --  widget itself from outermost to innermost. The difference is that in the

75.     --  widget path, the name assigned by Gtk.Widget.Set_Name is used if present,

76.     --  otherwise the class name of the widget, while for the class path, the class

77.     --  name is always used.

78.     --

79.     --  So, if you have a GtkEntry named "myentry", inside of a of a window named

80.     --  "mywindow", then the widget path is: "mwindow.GtkHBox.myentry" while the

81.     --  class path is: "GtkWindow.GtkHBox.GtkEntry".

82.     --

83.     --  Matching against class is a little different. The pattern match is done

84.     --  against all class names in the widgets class hierarchy (not the layout

85.     --  hierarchy) in sequence, so the pattern:

86.     --         class "GtkButton" style "my-style"

87.     --  will match not just Gtk_Button widgets, but also Gtk_Toggle_Button and

88.     --  Gtk_Check_Button widgets, since those classes derive from Gtk_Button.

89.     --

90.     --  Additionally, a priority can be specified for each pattern, and styles

91.     --  override other styles first by priority, then by pattern type and then by

92.     --  order of specification (later overrides earlier). The priorities that can

93.     --  be specified are (highest to lowest):

94.     --        highest

95.     --        rc

96.     --        theme

97.     --        application

98.     --        gtk

99.     --        lowest

100.     --

101.     --  rc is the default for styles read from an RC file, theme is the default for

102.     --  styles read from theme RC files, application should be used for styles an

103.     --  application sets up, and gtk is used for styles that GTK+ creates

104.     --  internally.

105.     --

106.     --  Toplevel declarations

107.     --  =====================

108.     --

109.     --  An RC file is a text file which is composed of a sequence of declarations.

110.     --  '#' characters delimit comments and the portion of a line after a '#' is

111.     --  ignored when parsing an RC file.

112.     --

113.     --  The possible toplevel declarations are:

114.     --     binding name { ... }

115.     --         Declares a binding set.

116.     --     class pattern [ style | binding ][ : priority ] name

117.     --         Specifies a style or binding set for a particular branch of the

118.     --         inheritance hierarchy.

119.     --     include filename

120.     --         Parses another file at this point. If filename is not an absolute

121.     --         filename, it is searched in the directories of the currently open RC

122.     --         files.

123.     --         GTK+ also tries to load a locale-specific variant of the included

124.     --         file.

125.     --     module_path path

126.     --         Sets a path (a list of directories separated by colons) that will be

127.     --         searched for theme engines referenced in RC files.

128.     --     pixmap_path path

129.     --         Sets a path (a list of directories separated by colons) that will be

130.     --         searched for pixmaps referenced in RC files.

131.     --     im_module_file pathname

132.     --         Sets the pathname for the IM modules file. Setting this from RC

133.     --         files is deprecated; you should use the environment variable

134.     --         GTK_IM_MODULE_FILE instead.

135.     --     style name [ = parent ] { ... }

136.     --         Declares a style.

137.     --     widget pattern [ style | binding ][ : priority ] name

138.     --         Specifies a style or binding set for a particular group of widgets

139.     --         by matching on the widget pathname.

140.     --     widget_class pattern [ style | binding ][ : priority ] name

141.     --         Specifies a style or binding set for a particular group of widgets

142.     --         by matching on the class pathname.

143.     --     setting = value

144.     --         Specifies a value for a setting. Note that settings in RC files are

145.     --         overwritten by system-wide settings which are managed by an

146.     --         XSettings manager. See Gtk.Settings.

147.     --

148.     --  Styles

149.     --  ======

150.     --

151.     --  A RC style is specified by a style declaration in a RC file, and then bound

152.     --  to widgets with a widget, widget_class, or class declaration. All styles

153.     --  applying to a particular widget are composited together with widget

154.     --  declarations overriding widget_class declarations which, in turn, override

155.     --  class declarations. Within each type of declaration, later declarations

156.     --  override earlier ones.

157.     --

158.     --  Within a style declaration, the possible elements are:

159.     --     bg[state] = color

160.     --       Sets the color used for the background of most widgets.

161.     --     fg[state] = color

162.     --       Sets the color used for the foreground of most widgets.

163.     --     base[state] = color

164.     --       Sets the color used for the background of widgets displaying editable

165.     --       text. This color is used for the background of, among others,

166.     --       Gtk_Text, Gtk_Entry, Gtk_List, and Gtk_CList.

167.     --     text[state] = color

168.     --       Sets the color used for foreground of widgets using base for the

169.     --       background color.

170.     --     xthickness = number

171.     --       Sets the xthickness, which is used for various horizontal padding

172.     --       values in GTK+.

173.     --     ythickness = number

174.     --       Sets the ythickness, which is used for various vertical padding

175.     --       values in GTK+.

176.     --     bg_pixmap[state] = pixmap

177.     --       Sets a background pixmap to be used in place of the bg color (or for

178.     --       GtkText, in place of the base color. The special value "<parent>" may

179.     --       be used to indicate that the widget should use the same background

180.     --       pixmap as its parent. The special value "<none>" may be used to

181.     --       indicate no background pixmap.

182.     --     font = font

183.     --     fontset = font

184.     --       Starting with GTK+ 2.0, the "font" and "fontset" declarations are

185.     --       ignored; use "font_name" declarations instead.

186.     --     font_name = font

187.     --       Sets the font for a widget. font must be a Pango font name, e.g. "Sans

188.     --       Italic 10". For details about Pango font names, see

189.     --       Pango.Font.Font_Description_From_String.

190.     --     stock["stock-id"] = { icon source specifications }

191.     --       Defines the icon for a stock item.

192.     --     engine "engine" { engine-specific settings }

193.     --       Defines the engine to be used when drawing with this style.

194.     --     class::property = value

195.     --       Sets a style property for a widget class.

196.     --

197.     --  The colors and background pixmaps are specified as a function of the state

198.     --  of the widget. The states are:

199.     --     NORMAL

200.     --       A color used for a widget in its normal state.

201.     --     ACTIVE

202.     --       A variant of the NORMAL color used when the widget is in the

203.     --       GTK_STATE_ACTIVE state, and also for the trough of a ScrollBar, tabs

204.     --       of a NoteBook other than the current tab and similar areas.

205.     --       Frequently, this should be a darker variant of the NORMAL color.

206.     --     PRELIGHT

207.     --       A color used for widgets in the GTK_STATE_PRELIGHT state. This state

208.     --       is the used for Buttons and MenuItems that have the mouse cursor over

209.     --       them, and for their children.

210.     --     SELECTED

211.     --       A color used to highlight data selected by the user. for instance, the

212.     --       selected items in a list widget, and the selection in an editable

213.     --       widget.

214.     --     INSENSITIVE

215.     --       A color used for the background of widgets that have been set

216.     --       insensitive with Gtk.Widget.Set_Sensitive().

217.     --

218.     --  Colors can be specified as a string containing a color name (GTK+ knows all

219.     --  names from the X color database /usr/lib/X11/rgb.txt), in one of the

220.     --  hexadecimal forms #rrrrggggbbbb, #rrrgggbbb, #rrggbb, or #rgb, where r, g

221.     --  and b are hex digits, or they can be specified as a triplet { r, g, b},

222.     --  where r, g and b are either integers in the range 0-65535 or floats in the

223.     --  range 0.0-1.0.

224.     --

225.     --  In a stock definition, icon sources are specified as a 4-tuple of image

226.     --  filename or icon name, text direction, widget state, and size, in that

227.     --  order. Each icon source specifies an image filename or icon name to use

228.     --  with a given direction, state, and size. Filenames are specified as a

229.     --  string such as "itemltr.png", while icon names (looked up in the current

230.     --  icon theme), are specified with a leading @, such as @"item-ltr". The *

231.     --  character can be used as a wildcard, and if direction/state/size are

232.     --  omitted they default to *. So for example, the following specifies

233.     --  different icons to use for left-to-right and right-to-left languages:

234.     --

235.     --     stock["my-stock-item"] = {

236.     --        { "itemltr.png", LTR, *, * },

237.     --        { "itemrtl.png", RTL, *, * }}

238.     --

239.     --  This could be abbreviated as follows:

240.     --

241.     --     stock["my-stock-item"] = {

242.     --        { "itemltr.png", LTR },

243.     --        { "itemrtl.png", RTL }}

244.     --

245.     --  You can specify custom icons for specific sizes, as follows:

246.     --

247.     --     stock["my-stock-item"] = {

248.     --        { "itemmenusize.png", *, *, "gtk-menu" },

249.     --        { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }

250.     --        { "itemgeneric.png" }} /* implicit *, *, * as a fallback */

251.     --

252.     --  The sizes that come with GTK+ itself are "gtk-menu", "gtk-small-toolbar",

253.     --  "gtk-large-toolbar", "gtk-button", "gtk-dialog". Applications can define

254.     --  other sizes (see also Gtk.Icon_Factory to learn more about this)

255.     --

256.     --  It's also possible to use custom icons for a given state, for example:

257.     --

258.     --     stock["my-stock-item"] = {

259.     --        { "itemprelight.png", *, PRELIGHT },

260.     --        { "iteminsensitive.png", *, INSENSITIVE },

261.     --        { "itemgeneric.png" }} /* implicit *, *, * as a fallback */

262.     --

263.     --  When selecting an icon source to use, GTK+ will consider text direction

264.     --  most important, state second, and size third. It will select the best match

265.     --  based on those criteria. If an attribute matches exactly (e.g. you

266.     --  specified PRELIGHT or specified the size), GTK+ won't modify the image; if

267.     --  the attribute matches with a wildcard, GTK+ will scale or modify the image

268.     --  to match the state and size the user requested.

269.     --

270.     --  Key bindings

271.     --  ============

272.     --

273.     --  Key bindings allow the user to specify actions to be taken on particular

274.     --  key presses. The form of a binding set declaration is:

275.     --

276.     --    binding name {

277.     --       bind key {

278.     --         signalname (param, ...)

279.     --         ...

280.     --       }

281.     --       ...

282.     --    }

283.     --

284.     --  key is a string consisting of a series of modifiers followed by the name of

285.     --  a key. The modifiers can be:

286.     --     <alt>, <control>, <mod1>, <mod2>, <mod3>, <mod4>, <mod5>

287.     --     <release>, <shft>, <shift>

288.     --  <shft> is an alias for <shift> and <alt> is an alias for <mod1>.

289.     --

290.     --  The action that is bound to the key is a sequence of signal names (strings)

291.     --  followed by parameters for each signal. The signals must be action signals.

292.     --  Each parameter can be a float, integer, string, or unquoted string

293.     --  representing an enumeration value. The types of the parameters specified

294.     --  must match the types of the parameters of the signal.

295.     --

296.     --  Binding sets are connected to widgets in the same manner as styles, with

297.     --  one difference: Binding sets override other binding sets first by pattern

298.     --  type, then by priority and then by order of specification. The priorities

299.     --  that can be specified and their default values are the same as for styles.

300.     --  </description>

301.     --  <c_version>2.8.17</c_version>

302.     --  <group>Configuration and Themes</group>

303.     --  <see>gtk-bindings.ads</see>

305.     with Glib.ObjectTo API docTo specTo body;

306.     with Gtk.SettingsTo API docTo specTo body;

307.     with Gtk.StyleTo API docTo specTo body; use Gtk.StyleTo API docTo specTo body;

308.     with Gtk.WidgetTo API docTo specTo body;

309.     with Gtkada.TypesTo API docTo specTo body; use Gtkada.TypesTo API docTo specTo body;

311.     package Gtk.RcTo API docTo specTo body is

313.        type Gtk_Rc_Style_RecordTo API docTo body is new Glib.Object.GObject_RecordTo API docTo specTo body with private;

314.        type Gtk_Rc_Style is access all Gtk_Rc_Style_RecordTo API docTo specTo body'Class;

316.        procedure Gtk_NewTo API docTo body (Rc_Style : out Gtk_Rc_StyleTo API docTo spec);

318.        procedure InitializeTo API docTo body (Rc_Style : access Gtk_Rc_Style_RecordTo API docTo specTo body'Class);

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

321.        --  Return the internal value associated with Gtk_Rc_Style.

323.        function CopyTo API docTo body (Orig : access Gtk_Rc_Style_RecordTo API docTo specTo body) return Gtk_Rc_StyleTo API docTo spec;

324.        --  Make a copy of the specified Gtk_Rc.Style.

325.        --  This function will correctly copy an rc style that is a member of a

326.        --  class derived from Gtk_Rc_Style.

328.        procedure Add_Default_FileTo API docTo body (Filename : String);

329.        --  Add a file to the list of files to be parsed at the end of Gtk.Main.Init

331.        procedure Set_Default_FilesTo API docTo body (Filenames : Chars_Ptr_ArrayTo API docTo spec);

332.        function Get_Default_FilesTo API docTo body return Chars_Ptr_ArrayTo API docTo spec;

333.        --  Set the list of files that GtkAda will read at the end of Gtk.Main.Init

335.        function Get_StyleTo API docTo body

336.          (Widget : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class) return Gtk_StyleTo API docTo spec;

337.        --  Find all matching RC styles for a given widget, composites them

338.        --  together, and then create a Gtk_Style representing the composite

339.        --  appearance. (GtkAda actually keeps a cache of previously created styles,

340.        --  so a new style may not be created)

341.        --  Return the resulting style. No refcount is added to the returned style,

342.        --  so if you want to save this style around, you should add a reference

343.        --  yourself.

345.        procedure ParseTo API docTo body (Filename : String);

346.        procedure Parse_StringTo API docTo body (Rc_String : String);

347.        --  Parse either a file or a string containing a gtk+ configuration (see the

348.        --  description at the top of this package).

350.        function Reparse_AllTo API docTo body return Boolean;

351.        --  If the modification time on any previously read file for the

352.        --  default Gtk_Settings has changed, discard all style information

353.        --  and then reread all previously read RC files.

354.        --  Return True if the files were reread.

356.        function Find_Module_In_PathTo API docTo body (Module_File : String) return String;

358.        function Get_Theme_DirTo API docTo body return String;

359.        --  Returns the standard directory in which themes should be installed.

360.        --  (GTK+ does not actually use this directory itself.)

362.        function Get_Module_DirTo API docTo body return String;

363.        --  Returns a directory in which GTK+ looks for theme engines. This is a

364.        --  dynamic library loaded by gtk+ that will be responsible for drawing

365.        --  parts of the application (ie implement all the functions in Gtk.Style)

367.        function Get_Im_Module_PathTo API docTo body return String;

368.        --  Obtains the path in which to look for IM modules. See the documentation

369.        --  of the GTK_PATH environment variable for more details about looking up

370.        --  modules. This function is useful solely for utilities supplied with GTK+

371.        --  and should not be used by applications under normal circumstances.

373.        function Get_Im_Module_FileTo API docTo body return String;

374.        --  Obtains the path to the IM modules file. See the documentation of the

375.        --  GTK_IM_MODULE_FILE environment variable for more details.

377.        function Reparse_All_For_SettingsTo API docTo body

378.          (Settings   : access Gtk.Settings.Gtk_Settings_RecordTo API docTo spec'Class;

379.           Force_Load : Boolean)

380.           return Boolean;

381.        --  If the modification time on any previously read file

382.        --  for the given Gtk_Settings has changed, discard all style information

383.        --  and then reread all previously read RC files.

384.        --  If Force_Load is true, the files are reloaded even if unmodified.

385.        --  Return True if some files have been reparsed

387.        procedure Reset_StylesTo API docTo body

388.          (Settings : access Gtk.Settings.Gtk_Settings_RecordTo API docTo spec'Class);

389.        --  This function recomputes the styles for all widgets that use a

390.        --  particular Gtk_Settings object. (There is one Gtk_Settings object

391.        --  per Gdk_Screen, see Gtk.Settings.Get_For_Screen); It is useful

392.        --  when some global parameter has changed that affects the appearance

393.        --  of all widgets, because when a widget gets a new style, it will

394.        --  both redraw and recompute any cached information about its

395.        --  appearance. As an example, it is used when the default font size

396.        --  set by the operating system changes. Note that this function

397.        --  doesn't affect widgets that have a style set explicitely on them

398.        --  with Gtk.Widget.Set_Style.

400.        function Get_Style_By_PathsTo API docTo body

401.          (Settings    : access Gtk.Settings.Gtk_Settings_RecordTo API docTo spec'Class;

402.           Widget_Path : String := "";

403.           Class_Path  : String := "";

404.           Typ         : Glib.GTypeTo API docTo spec := Glib.GType_NoneTo API docTo spec)

405.          return Gtk.Style.Gtk_StyleTo API docTo spec;

406.        --  Creates up a Gtk_Style from styles defined in a RC file by providing

407.        --  the raw components used in matching. This function may be useful

408.        --  when creating pseudo-widgets that should be themed like widgets but

409.        --  don't actually have corresponding GTK+ widgets. An example of this

410.        --  would be items inside a GNOME canvas widget.

411.        --  Returns null if nothing matching was found and the default style should

412.        --  be used. You must call Ref if you intend to keep a reference on the

413.        --  style.

415.        ------------------------------

416.        -- Widget related functions --

417.        ------------------------------

419.        procedure Modify_StyleTo API docTo body

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

421.           Style  : access Gtk_Rc_Style_RecordTo API docTo specTo body'Class);

422.        --  Modifies style values on the widget. Modifications made using this

423.        --  technique take precedence over style values set via an RC file,

424.        --  however, they will be overriden if a style is explicitely set on

425.        --  the widget using gtk_widget_set_style(). The #GtkRcStyle structure

426.        --  is designed so each field can either be set or unset, so it is

427.        --  possible, using this function, to modify some style values and

428.        --  leave the others unchanged.

429.        --

430.        --  Note that modifications made with this function are not cumulative

431.        --  with previous calls to gtk_widget_modify_style() or with such

432.        --  functions as gtk_widget_modify_fg(). If you wish to retain

433.        --  previous values, you must first call gtk_widget_get_modifier_style(),

434.        --  make your modifications to the returned style, then call

435.        --  gtk_widget_modify_style() with that style. On the other hand,

436.        --  if you first call gtk_widget_modify_style(), subsequent calls

437.        --  to such functions gtk_widget_modify_fg() will have a cumulative

438.        --  effect with the initial modifications.

440.        function Get_Modifier_StyleTo API docTo body

441.          (Widget : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class) return Gtk_Rc_StyleTo API docTo spec;

442.        --  Return the current modifier style for the widget.

443.        --  (As set by Modify_Style.) If no style has previously set, a new

444.        --  Gtk_Rc_Style will be created with all values unset, and set as the

445.        --  modifier style for the widget. If you make changes to this rc

446.        --  style, you must call Modify_Style, passing in the

447.        --  returned rc style, to make sure that your changes take effect.

448.        --

449.        --  Return value: the modifier style for the widget. This rc style is

450.        --    owned by the widget. If you want to keep a pointer to value this

451.        --    around, you must add a refcount using Ref.

453.     private

454.        type Gtk_Rc_Style_RecordTo API docTo spec is new Glib.Object.GObject_RecordTo API docTo specTo body with null record;

456.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_rc_style_get_type");

457.     end Gtk.RcTo API docTo specTo body;

459.     --  The following functions never had a binding and are now obsolescent:

460.     --  No binding: gtk_rc_add_class_style

461.     --  No binding: gtk_rc_add_widget_class_style

462.     --  No binding: gtk_rc_add_widget_name_style

464.     --  These functions do not seem to be needed for normal applications:

465.     --  No binding: gtk_rc_parse_color

466.     --  No binding: gtk_rc_parse_priority

467.     --  No binding: gtk_rc_parse_state

468.     --  No binding: gtk_rc_scanner_new

469.     --  No binding: gtk_rc_style_ref

470.     --  No binding: gtk_rc_style_unref

471.     --  No binding: gtk_rc_find_pixmap_in_path