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. -- -- -- -- -- -- -- -- -- -- -- --
  23. ----------------------------------------------------------------------- 
  24.  
  25. --  <description> 
  26. --  This package provides an interface to Gtk's configuration files. 
  27. --  GTK+ provides resource file mechanism for configuring various aspects of 
  28. --  the operation of a GTK+ program at runtime. 
  29. -- 
  30. --  Default files 
  31. --  ============= 
  32. -- 
  33. --  An application can cause GTK+ to parse a specific RC file by calling 
  34. --  Gtk.RC.Parse. In addition to this, certain files will be read at the end 
  35. --  of Gtk.Main.Init. Unless modified, the files looked for will be 
  36. --  <SYSCONFDIR>/gtk-2.0/gtkrc and .gtkrc-2.0 in the users home directory. 
  37. --  (<SYSCONFDIR> defaults to /usr/local/etc. It can be changed with the 
  38. --  --prefix or --sysconfdir options when configuring GTK+.) Note that although 
  39. --  the filenames contain the version number 2.0, all 2.x versions of GTK+ look 
  40. --  for these files. 
  41. -- 
  42. --  The set of these default files can be retrieved with 
  43. --  Gtk.RC.Get_Default_Files and modified with Gtk.RC.Add_Default_File and 
  44. --  Gtk.RC.Set_Default_Files. Additionally, the GTK2_RC_FILES environment 
  45. --  variable can be set to a G_SEARCHPATH_SEPARATOR_S-separated list of files 
  46. --  in order to overwrite the set of default files at runtime. 
  47. -- 
  48. --  For each RC file, in addition to the file itself, GTK+ will look for a 
  49. --  locale-specific file that will be parsed after the main file. For instance, 
  50. --  if LANG is set to ja_JP.ujis, when loading the default file ~/.gtkrc then 
  51. --  GTK+ looks for ~/.gtkrc.ja_JP and ~/.gtkrc.ja, and parses the first of 
  52. --  those that exists. 
  53. -- 
  54. --  Pathnames and patterns 
  55. --  ====================== 
  56. -- 
  57. --  A resource file defines a number of styles and key bindings and attaches 
  58. --  them to particular widgets. The attachment is done by the widget, 
  59. --  widget_class, and class declarations. As an example of such a statement: 
  60. --          widget "mywindow.*.GtkEntry" style "my-entry-class" 
  61. --  attaches the style "my-entry-class" to all widgets whose widget class 
  62. --  matches the pattern "mywindow.*.GtkEntry". 
  63. -- 
  64. --  The patterns here are given in the standard shell glob syntax. The "?" 
  65. --  wildcard matches any character, while "*" matches zero or more of any 
  66. --  character. The three types of matching are against the widget path, the 
  67. --  class path and the class hierarchy. Both the widget and the class paths 
  68. --  consists of a "." separated list of all the parents of the widget and the 
  69. --  widget itself from outermost to innermost. The difference is that in the 
  70. --  widget path, the name assigned by Gtk.Widget.Set_Name is used if present, 
  71. --  otherwise the class name of the widget, while for the class path, the class 
  72. --  name is always used. 
  73. -- 
  74. --  So, if you have a GtkEntry named "myentry", inside of a of a window named 
  75. --  "mywindow", then the widget path is: "mwindow.GtkHBox.myentry" while the 
  76. --  class path is: "GtkWindow.GtkHBox.GtkEntry". 
  77. -- 
  78. --  Matching against class is a little different. The pattern match is done 
  79. --  against all class names in the widgets class hierarchy (not the layout 
  80. --  hierarchy) in sequence, so the pattern: 
  81. --         class "GtkButton" style "my-style" 
  82. --  will match not just Gtk_Button widgets, but also Gtk_Toggle_Button and 
  83. --  Gtk_Check_Button widgets, since those classes derive from Gtk_Button. 
  84. -- 
  85. --  Additionally, a priority can be specified for each pattern, and styles 
  86. --  override other styles first by priority, then by pattern type and then by 
  87. --  order of specification (later overrides earlier). The priorities that can 
  88. --  be specified are (highest to lowest): 
  89. --        highest 
  90. --        rc 
  91. --        theme 
  92. --        application 
  93. --        gtk 
  94. --        lowest 
  95. -- 
  96. --  rc is the default for styles read from an RC file, theme is the default for 
  97. --  styles read from theme RC files, application should be used for styles an 
  98. --  application sets up, and gtk is used for styles that GTK+ creates 
  99. --  internally. 
  100. -- 
  101. --  Toplevel declarations 
  102. --  ===================== 
  103. -- 
  104. --  An RC file is a text file which is composed of a sequence of declarations. 
  105. --  '#' characters delimit comments and the portion of a line after a '#' is 
  106. --  ignored when parsing an RC file. 
  107. -- 
  108. --  The possible toplevel declarations are: 
  109. --     binding name { ... } 
  110. --         Declares a binding set. 
  111. --     class pattern [ style | binding ][ : priority ] name 
  112. --         Specifies a style or binding set for a particular branch of the 
  113. --         inheritance hierarchy. 
  114. --     include filename 
  115. --         Parses another file at this point. If filename is not an absolute 
  116. --         filename, it is searched in the directories of the currently open RC 
  117. --         files. 
  118. --         GTK+ also tries to load a locale-specific variant of the included 
  119. --         file. 
  120. --     module_path path 
  121. --         Sets a path (a list of directories separated by colons) that will be 
  122. --         searched for theme engines referenced in RC files. 
  123. --     pixmap_path path 
  124. --         Sets a path (a list of directories separated by colons) that will be 
  125. --         searched for pixmaps referenced in RC files. 
  126. --     im_module_file pathname 
  127. --         Sets the pathname for the IM modules file. Setting this from RC 
  128. --         files is deprecated; you should use the environment variable 
  129. --         GTK_IM_MODULE_FILE instead. 
  130. --     style name [ = parent ] { ... } 
  131. --         Declares a style. 
  132. --     widget pattern [ style | binding ][ : priority ] name 
  133. --         Specifies a style or binding set for a particular group of widgets 
  134. --         by matching on the widget pathname. 
  135. --     widget_class pattern [ style | binding ][ : priority ] name 
  136. --         Specifies a style or binding set for a particular group of widgets 
  137. --         by matching on the class pathname. 
  138. --     setting = value 
  139. --         Specifies a value for a setting. Note that settings in RC files are 
  140. --         overwritten by system-wide settings which are managed by an 
  141. --         XSettings manager. See Gtk.Settings. 
  142. -- 
  143. --  Styles 
  144. --  ====== 
  145. -- 
  146. --  A RC style is specified by a style declaration in a RC file, and then bound 
  147. --  to widgets with a widget, widget_class, or class declaration. All styles 
  148. --  applying to a particular widget are composited together with widget 
  149. --  declarations overriding widget_class declarations which, in turn, override 
  150. --  class declarations. Within each type of declaration, later declarations 
  151. --  override earlier ones. 
  152. -- 
  153. --  Within a style declaration, the possible elements are: 
  154. --     bg[state] = color 
  155. --       Sets the color used for the background of most widgets. 
  156. --     fg[state] = color 
  157. --       Sets the color used for the foreground of most widgets. 
  158. --     base[state] = color 
  159. --       Sets the color used for the background of widgets displaying editable 
  160. --       text. This color is used for the background of, among others, 
  161. --       Gtk_Text, Gtk_Entry, Gtk_List, and Gtk_CList. 
  162. --     text[state] = color 
  163. --       Sets the color used for foreground of widgets using base for the 
  164. --       background color. 
  165. --     xthickness = number 
  166. --       Sets the xthickness, which is used for various horizontal padding 
  167. --       values in GTK+. 
  168. --     ythickness = number 
  169. --       Sets the ythickness, which is used for various vertical padding 
  170. --       values in GTK+. 
  171. --     bg_pixmap[state] = pixmap 
  172. --       Sets a background pixmap to be used in place of the bg color (or for 
  173. --       GtkText, in place of the base color. The special value "<parent>" may 
  174. --       be used to indicate that the widget should use the same background 
  175. --       pixmap as its parent. The special value "<none>" may be used to 
  176. --       indicate no background pixmap. 
  177. --     font = font 
  178. --     fontset = font 
  179. --       Starting with GTK+ 2.0, the "font" and "fontset" declarations are 
  180. --       ignored; use "font_name" declarations instead. 
  181. --     font_name = font 
  182. --       Sets the font for a widget. font must be a Pango font name, e.g. "Sans 
  183. --       Italic 10". For details about Pango font names, see 
  184. --       Pango.Font.Font_Description_From_String. 
  185. --     stock["stock-id"] = { icon source specifications } 
  186. --       Defines the icon for a stock item. 
  187. --     engine "engine" { engine-specific settings } 
  188. --       Defines the engine to be used when drawing with this style. 
  189. --     class::property = value 
  190. --       Sets a style property for a widget class. 
  191. -- 
  192. --  The colors and background pixmaps are specified as a function of the state 
  193. --  of the widget. The states are: 
  194. --     NORMAL 
  195. --       A color used for a widget in its normal state. 
  196. --     ACTIVE 
  197. --       A variant of the NORMAL color used when the widget is in the 
  198. --       GTK_STATE_ACTIVE state, and also for the trough of a ScrollBar, tabs 
  199. --       of a NoteBook other than the current tab and similar areas. 
  200. --       Frequently, this should be a darker variant of the NORMAL color. 
  201. --     PRELIGHT 
  202. --       A color used for widgets in the GTK_STATE_PRELIGHT state. This state 
  203. --       is the used for Buttons and MenuItems that have the mouse cursor over 
  204. --       them, and for their children. 
  205. --     SELECTED 
  206. --       A color used to highlight data selected by the user. for instance, the 
  207. --       selected items in a list widget, and the selection in an editable 
  208. --       widget. 
  209. --     INSENSITIVE 
  210. --       A color used for the background of widgets that have been set 
  211. --       insensitive with Gtk.Widget.Set_Sensitive(). 
  212. -- 
  213. --  Colors can be specified as a string containing a color name (GTK+ knows all 
  214. --  names from the X color database /usr/lib/X11/rgb.txt), in one of the 
  215. --  hexadecimal forms #rrrrggggbbbb, #rrrgggbbb, #rrggbb, or #rgb, where r, g 
  216. --  and b are hex digits, or they can be specified as a triplet { r, g, b}, 
  217. --  where r, g and b are either integers in the range 0-65535 or floats in the 
  218. --  range 0.0-1.0. 
  219. -- 
  220. --  In a stock definition, icon sources are specified as a 4-tuple of image 
  221. --  filename or icon name, text direction, widget state, and size, in that 
  222. --  order. Each icon source specifies an image filename or icon name to use 
  223. --  with a given direction, state, and size. Filenames are specified as a 
  224. --  string such as "itemltr.png", while icon names (looked up in the current 
  225. --  icon theme), are specified with a leading @, such as @"item-ltr". The * 
  226. --  character can be used as a wildcard, and if direction/state/size are 
  227. --  omitted they default to *. So for example, the following specifies 
  228. --  different icons to use for left-to-right and right-to-left languages: 
  229. -- 
  230. --     stock["my-stock-item"] = { 
  231. --        { "itemltr.png", LTR, *, * }, 
  232. --        { "itemrtl.png", RTL, *, * }} 
  233. -- 
  234. --  This could be abbreviated as follows: 
  235. -- 
  236. --     stock["my-stock-item"] = { 
  237. --        { "itemltr.png", LTR }, 
  238. --        { "itemrtl.png", RTL }} 
  239. -- 
  240. --  You can specify custom icons for specific sizes, as follows: 
  241. -- 
  242. --     stock["my-stock-item"] = { 
  243. --        { "itemmenusize.png", *, *, "gtk-menu" }, 
  244. --        { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" } 
  245. --        { "itemgeneric.png" }} /* implicit *, *, * as a fallback */ 
  246. -- 
  247. --  The sizes that come with GTK+ itself are "gtk-menu", "gtk-small-toolbar", 
  248. --  "gtk-large-toolbar", "gtk-button", "gtk-dialog". Applications can define 
  249. --  other sizes (see also Gtk.Icon_Factory to learn more about this) 
  250. -- 
  251. --  It's also possible to use custom icons for a given state, for example: 
  252. -- 
  253. --     stock["my-stock-item"] = { 
  254. --        { "itemprelight.png", *, PRELIGHT }, 
  255. --        { "iteminsensitive.png", *, INSENSITIVE }, 
  256. --        { "itemgeneric.png" }} /* implicit *, *, * as a fallback */ 
  257. -- 
  258. --  When selecting an icon source to use, GTK+ will consider text direction 
  259. --  most important, state second, and size third. It will select the best match 
  260. --  based on those criteria. If an attribute matches exactly (e.g. you 
  261. --  specified PRELIGHT or specified the size), GTK+ won't modify the image; if 
  262. --  the attribute matches with a wildcard, GTK+ will scale or modify the image 
  263. --  to match the state and size the user requested. 
  264. -- 
  265. --  Key bindings 
  266. --  ============ 
  267. -- 
  268. --  Key bindings allow the user to specify actions to be taken on particular 
  269. --  key presses. The form of a binding set declaration is: 
  270. -- 
  271. --    binding name { 
  272. --       bind key { 
  273. --         signalname (param, ...) 
  274. --         ... 
  275. --       } 
  276. --       ... 
  277. --    } 
  278. -- 
  279. --  key is a string consisting of a series of modifiers followed by the name of 
  280. --  a key. The modifiers can be: 
  281. --     <alt>, <control>, <mod1>, <mod2>, <mod3>, <mod4>, <mod5> 
  282. --     <release>, <shft>, <shift> 
  283. --  <shft> is an alias for <shift> and <alt> is an alias for <mod1>. 
  284. -- 
  285. --  The action that is bound to the key is a sequence of signal names (strings) 
  286. --  followed by parameters for each signal. The signals must be action signals. 
  287. --  Each parameter can be a float, integer, string, or unquoted string 
  288. --  representing an enumeration value. The types of the parameters specified 
  289. --  must match the types of the parameters of the signal. 
  290. -- 
  291. --  Binding sets are connected to widgets in the same manner as styles, with 
  292. --  one difference: Binding sets override other binding sets first by pattern 
  293. --  type, then by priority and then by order of specification. The priorities 
  294. --  that can be specified and their default values are the same as for styles. 
  295. --  </description> 
  296. --  <c_version>2.8.17</c_version> 
  297. --  <group>Configuration and Themes</group> 
  298. --  <see>gtk-bindings.ads</see> 
  299.  
  300. with Glib.Object; 
  301. with Gtk.Settings; 
  302. with Gtk.Style; use Gtk.Style; 
  303. with Gtk.Widget; 
  304. with Gtkada.Types; use Gtkada.Types; 
  305.  
  306. package Gtk.Rc is 
  307.  
  308.    type Gtk_Rc_Style_Record is new Glib.Object.GObject_Record with private; 
  309.    type Gtk_Rc_Style is access all Gtk_Rc_Style_Record'Class; 
  310.  
  311.    procedure Gtk_New (Rc_Style : out Gtk_Rc_Style); 
  312.  
  313.    procedure Initialize (Rc_Style : access Gtk_Rc_Style_Record'Class); 
  314.  
  315.    function Get_Type return Glib.GType; 
  316.    --  Return the internal value associated with Gtk_Rc_Style. 
  317.  
  318.    function Copy (Orig : access Gtk_Rc_Style_Record) return Gtk_Rc_Style; 
  319.    --  Make a copy of the specified Gtk_Rc.Style. 
  320.    --  This function will correctly copy an rc style that is a member of a 
  321.    --  class derived from Gtk_Rc_Style. 
  322.  
  323.    procedure Add_Default_File (Filename : String); 
  324.    --  Add a file to the list of files to be parsed at the end of Gtk.Main.Init 
  325.  
  326.    procedure Set_Default_Files (Filenames : Chars_Ptr_Array); 
  327.    function Get_Default_Files return Chars_Ptr_Array; 
  328.    --  Set the list of files that GtkAda will read at the end of Gtk.Main.Init 
  329.  
  330.    function Get_Style 
  331.      (Widget : access Gtk.Widget.Gtk_Widget_Record'Class) return Gtk_Style; 
  332.    --  Find all matching RC styles for a given widget, composites them 
  333.    --  together, and then create a Gtk_Style representing the composite 
  334.    --  appearance. (GtkAda actually keeps a cache of previously created styles, 
  335.    --  so a new style may not be created) 
  336.    --  Return the resulting style. No refcount is added to the returned style, 
  337.    --  so if you want to save this style around, you should add a reference 
  338.    --  yourself. 
  339.  
  340.    procedure Parse (Filename : String); 
  341.    procedure Parse_String (Rc_String : String); 
  342.    --  Parse either a file or a string containing a gtk+ configuration (see the 
  343.    --  description at the top of this package). 
  344.  
  345.    function Reparse_All return Boolean; 
  346.    --  If the modification time on any previously read file for the 
  347.    --  default Gtk_Settings has changed, discard all style information 
  348.    --  and then reread all previously read RC files. 
  349.    --  Return True if the files were reread. 
  350.  
  351.    function Find_Module_In_Path (Module_File : String) return String; 
  352.  
  353.    function Get_Theme_Dir return String; 
  354.    --  Returns the standard directory in which themes should be installed. 
  355.    --  (GTK+ does not actually use this directory itself.) 
  356.  
  357.    function Get_Module_Dir return String; 
  358.    --  Returns a directory in which GTK+ looks for theme engines. This is a 
  359.    --  dynamic library loaded by gtk+ that will be responsible for drawing 
  360.    --  parts of the application (ie implement all the functions in Gtk.Style) 
  361.  
  362.    function Get_Im_Module_Path return String; 
  363.    --  Obtains the path in which to look for IM modules. See the documentation 
  364.    --  of the GTK_PATH environment variable for more details about looking up 
  365.    --  modules. This function is useful solely for utilities supplied with GTK+ 
  366.    --  and should not be used by applications under normal circumstances. 
  367.  
  368.    function Get_Im_Module_File return String; 
  369.    --  Obtains the path to the IM modules file. See the documentation of the 
  370.    --  GTK_IM_MODULE_FILE environment variable for more details. 
  371.  
  372.    function Reparse_All_For_Settings 
  373.      (Settings   : access Gtk.Settings.Gtk_Settings_Record'Class; 
  374.       Force_Load : Boolean) 
  375.       return Boolean; 
  376.    --  If the modification time on any previously read file 
  377.    --  for the given Gtk_Settings has changed, discard all style information 
  378.    --  and then reread all previously read RC files. 
  379.    --  If Force_Load is true, the files are reloaded even if unmodified. 
  380.    --  Return True if some files have been reparsed 
  381.  
  382.    procedure Reset_Styles 
  383.      (Settings : access Gtk.Settings.Gtk_Settings_Record'Class); 
  384.    --  This function recomputes the styles for all widgets that use a 
  385.    --  particular Gtk_Settings object. (There is one Gtk_Settings object 
  386.    --  per Gdk_Screen, see Gtk.Settings.Get_For_Screen); It is useful 
  387.    --  when some global parameter has changed that affects the appearance 
  388.    --  of all widgets, because when a widget gets a new style, it will 
  389.    --  both redraw and recompute any cached information about its 
  390.    --  appearance. As an example, it is used when the default font size 
  391.    --  set by the operating system changes. Note that this function 
  392.    --  doesn't affect widgets that have a style set explicitely on them 
  393.    --  with Gtk.Widget.Set_Style. 
  394.  
  395.    function Get_Style_By_Paths 
  396.      (Settings    : access Gtk.Settings.Gtk_Settings_Record'Class; 
  397.       Widget_Path : String := ""; 
  398.       Class_Path  : String := ""; 
  399.       Typ         : Glib.GType := Glib.GType_None) 
  400.      return Gtk.Style.Gtk_Style; 
  401.    --  Creates up a Gtk_Style from styles defined in a RC file by providing 
  402.    --  the raw components used in matching. This function may be useful 
  403.    --  when creating pseudo-widgets that should be themed like widgets but 
  404.    --  don't actually have corresponding GTK+ widgets. An example of this 
  405.    --  would be items inside a GNOME canvas widget. 
  406.    --  Returns null if nothing matching was found and the default style should 
  407.    --  be used. You must call Ref if you intend to keep a reference on the 
  408.    --  style. 
  409.  
  410.    ------------------------------ 
  411.    -- Widget related functions -- 
  412.    ------------------------------ 
  413.  
  414.    procedure Modify_Style 
  415.      (Widget : access Gtk.Widget.Gtk_Widget_Record'Class; 
  416.       Style  : access Gtk_Rc_Style_Record'Class); 
  417.    --  Modifies style values on the widget. Modifications made using this 
  418.    --  technique take precedence over style values set via an RC file, 
  419.    --  however, they will be overriden if a style is explicitely set on 
  420.    --  the widget using gtk_widget_set_style(). The #GtkRcStyle structure 
  421.    --  is designed so each field can either be set or unset, so it is 
  422.    --  possible, using this function, to modify some style values and 
  423.    --  leave the others unchanged. 
  424.    -- 
  425.    --  Note that modifications made with this function are not cumulative 
  426.    --  with previous calls to gtk_widget_modify_style() or with such 
  427.    --  functions as gtk_widget_modify_fg(). If you wish to retain 
  428.    --  previous values, you must first call gtk_widget_get_modifier_style(), 
  429.    --  make your modifications to the returned style, then call 
  430.    --  gtk_widget_modify_style() with that style. On the other hand, 
  431.    --  if you first call gtk_widget_modify_style(), subsequent calls 
  432.    --  to such functions gtk_widget_modify_fg() will have a cumulative 
  433.    --  effect with the initial modifications. 
  434.  
  435.    function Get_Modifier_Style 
  436.      (Widget : access Gtk.Widget.Gtk_Widget_Record'Class) return Gtk_Rc_Style; 
  437.    --  Return the current modifier style for the widget. 
  438.    --  (As set by Modify_Style.) If no style has previously set, a new 
  439.    --  Gtk_Rc_Style will be created with all values unset, and set as the 
  440.    --  modifier style for the widget. If you make changes to this rc 
  441.    --  style, you must call Modify_Style, passing in the 
  442.    --  returned rc style, to make sure that your changes take effect. 
  443.    -- 
  444.    --  Return value: the modifier style for the widget. This rc style is 
  445.    --    owned by the widget. If you want to keep a pointer to value this 
  446.    --    around, you must add a refcount using Ref. 
  447.  
  448. private 
  449.    type Gtk_Rc_Style_Record is new Glib.Object.GObject_Record with null record; 
  450.  
  451.    pragma Import (C, Get_Type, "gtk_rc_style_get_type"); 
  452. end Gtk.Rc; 
  453.  
  454. --  The following functions never had a binding and are now obsolescent: 
  455. --  No binding: gtk_rc_add_class_style 
  456. --  No binding: gtk_rc_add_widget_class_style 
  457. --  No binding: gtk_rc_add_widget_name_style 
  458.  
  459. --  These functions do not seem to be needed for normal applications: 
  460. --  No binding: gtk_rc_parse_color 
  461. --  No binding: gtk_rc_parse_priority 
  462. --  No binding: gtk_rc_parse_state 
  463. --  No binding: gtk_rc_scanner_new 
  464. --  No binding: gtk_rc_style_ref 
  465. --  No binding: gtk_rc_style_unref 
  466. --  No binding: gtk_rc_find_pixmap_in_path