-----------------------------------------------------------------------
-- GtkAda - Ada95 binding for Gtk+/Gnome --
-- --
-- Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet --
-- Copyright (C) 2000-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. --
-- --
-- --
-- --
-- --
-- --
-- --
-- --
-----------------------------------------------------------------------
--
-- This package provides an interface to Gtk's configuration files.
-- GTK+ provides resource file mechanism for configuring various aspects of
-- the operation of a GTK+ program at runtime.
--
-- Default files
-- =============
--
-- An application can cause GTK+ to parse a specific RC file by calling
-- Gtk.RC.Parse. In addition to this, certain files will be read at the end
-- of Gtk.Main.Init. Unless modified, the files looked for will be
-- /gtk-2.0/gtkrc and .gtkrc-2.0 in the users home directory.
-- ( defaults to /usr/local/etc. It can be changed with the
-- --prefix or --sysconfdir options when configuring GTK+.) Note that although
-- the filenames contain the version number 2.0, all 2.x versions of GTK+ look
-- for these files.
--
-- The set of these default files can be retrieved with
-- Gtk.RC.Get_Default_Files and modified with Gtk.RC.Add_Default_File and
-- Gtk.RC.Set_Default_Files. Additionally, the GTK2_RC_FILES environment
-- variable can be set to a G_SEARCHPATH_SEPARATOR_S-separated list of files
-- in order to overwrite the set of default files at runtime.
--
-- For each RC file, in addition to the file itself, GTK+ will look for a
-- locale-specific file that will be parsed after the main file. For instance,
-- if LANG is set to ja_JP.ujis, when loading the default file ~/.gtkrc then
-- GTK+ looks for ~/.gtkrc.ja_JP and ~/.gtkrc.ja, and parses the first of
-- those that exists.
--
-- Pathnames and patterns
-- ======================
--
-- A resource file defines a number of styles and key bindings and attaches
-- them to particular widgets. The attachment is done by the widget,
-- widget_class, and class declarations. As an example of such a statement:
-- widget "mywindow.*.GtkEntry" style "my-entry-class"
-- attaches the style "my-entry-class" to all widgets whose widget class
-- matches the pattern "mywindow.*.GtkEntry".
--
-- The patterns here are given in the standard shell glob syntax. The "?"
-- wildcard matches any character, while "*" matches zero or more of any
-- character. The three types of matching are against the widget path, the
-- class path and the class hierarchy. Both the widget and the class paths
-- consists of a "." separated list of all the parents of the widget and the
-- widget itself from outermost to innermost. The difference is that in the
-- widget path, the name assigned by Gtk.Widget.Set_Name is used if present,
-- otherwise the class name of the widget, while for the class path, the class
-- name is always used.
--
-- So, if you have a GtkEntry named "myentry", inside of a of a window named
-- "mywindow", then the widget path is: "mwindow.GtkHBox.myentry" while the
-- class path is: "GtkWindow.GtkHBox.GtkEntry".
--
-- Matching against class is a little different. The pattern match is done
-- against all class names in the widgets class hierarchy (not the layout
-- hierarchy) in sequence, so the pattern:
-- class "GtkButton" style "my-style"
-- will match not just Gtk_Button widgets, but also Gtk_Toggle_Button and
-- Gtk_Check_Button widgets, since those classes derive from Gtk_Button.
--
-- Additionally, a priority can be specified for each pattern, and styles
-- override other styles first by priority, then by pattern type and then by
-- order of specification (later overrides earlier). The priorities that can
-- be specified are (highest to lowest):
-- highest
-- rc
-- theme
-- application
-- gtk
-- lowest
--
-- rc is the default for styles read from an RC file, theme is the default for
-- styles read from theme RC files, application should be used for styles an
-- application sets up, and gtk is used for styles that GTK+ creates
-- internally.
--
-- Toplevel declarations
-- =====================
--
-- An RC file is a text file which is composed of a sequence of declarations.
-- '#' characters delimit comments and the portion of a line after a '#' is
-- ignored when parsing an RC file.
--
-- The possible toplevel declarations are:
-- binding name { ... }
-- Declares a binding set.
-- class pattern [ style | binding ][ : priority ] name
-- Specifies a style or binding set for a particular branch of the
-- inheritance hierarchy.
-- include filename
-- Parses another file at this point. If filename is not an absolute
-- filename, it is searched in the directories of the currently open RC
-- files.
-- GTK+ also tries to load a locale-specific variant of the included
-- file.
-- module_path path
-- Sets a path (a list of directories separated by colons) that will be
-- searched for theme engines referenced in RC files.
-- pixmap_path path
-- Sets a path (a list of directories separated by colons) that will be
-- searched for pixmaps referenced in RC files.
-- im_module_file pathname
-- Sets the pathname for the IM modules file. Setting this from RC
-- files is deprecated; you should use the environment variable
-- GTK_IM_MODULE_FILE instead.
-- style name [ = parent ] { ... }
-- Declares a style.
-- widget pattern [ style | binding ][ : priority ] name
-- Specifies a style or binding set for a particular group of widgets
-- by matching on the widget pathname.
-- widget_class pattern [ style | binding ][ : priority ] name
-- Specifies a style or binding set for a particular group of widgets
-- by matching on the class pathname.
-- setting = value
-- Specifies a value for a setting. Note that settings in RC files are
-- overwritten by system-wide settings which are managed by an
-- XSettings manager. See Gtk.Settings.
--
-- Styles
-- ======
--
-- A RC style is specified by a style declaration in a RC file, and then bound
-- to widgets with a widget, widget_class, or class declaration. All styles
-- applying to a particular widget are composited together with widget
-- declarations overriding widget_class declarations which, in turn, override
-- class declarations. Within each type of declaration, later declarations
-- override earlier ones.
--
-- Within a style declaration, the possible elements are:
-- bg[state] = color
-- Sets the color used for the background of most widgets.
-- fg[state] = color
-- Sets the color used for the foreground of most widgets.
-- base[state] = color
-- Sets the color used for the background of widgets displaying editable
-- text. This color is used for the background of, among others,
-- Gtk_Text, Gtk_Entry, Gtk_List, and Gtk_CList.
-- text[state] = color
-- Sets the color used for foreground of widgets using base for the
-- background color.
-- xthickness = number
-- Sets the xthickness, which is used for various horizontal padding
-- values in GTK+.
-- ythickness = number
-- Sets the ythickness, which is used for various vertical padding
-- values in GTK+.
-- bg_pixmap[state] = pixmap
-- Sets a background pixmap to be used in place of the bg color (or for
-- GtkText, in place of the base color. The special value "" may
-- be used to indicate that the widget should use the same background
-- pixmap as its parent. The special value "" may be used to
-- indicate no background pixmap.
-- font = font
-- fontset = font
-- Starting with GTK+ 2.0, the "font" and "fontset" declarations are
-- ignored; use "font_name" declarations instead.
-- font_name = font
-- Sets the font for a widget. font must be a Pango font name, e.g. "Sans
-- Italic 10". For details about Pango font names, see
-- Pango.Font.Font_Description_From_String.
-- stock["stock-id"] = { icon source specifications }
-- Defines the icon for a stock item.
-- engine "engine" { engine-specific settings }
-- Defines the engine to be used when drawing with this style.
-- class::property = value
-- Sets a style property for a widget class.
--
-- The colors and background pixmaps are specified as a function of the state
-- of the widget. The states are:
-- NORMAL
-- A color used for a widget in its normal state.
-- ACTIVE
-- A variant of the NORMAL color used when the widget is in the
-- GTK_STATE_ACTIVE state, and also for the trough of a ScrollBar, tabs
-- of a NoteBook other than the current tab and similar areas.
-- Frequently, this should be a darker variant of the NORMAL color.
-- PRELIGHT
-- A color used for widgets in the GTK_STATE_PRELIGHT state. This state
-- is the used for Buttons and MenuItems that have the mouse cursor over
-- them, and for their children.
-- SELECTED
-- A color used to highlight data selected by the user. for instance, the
-- selected items in a list widget, and the selection in an editable
-- widget.
-- INSENSITIVE
-- A color used for the background of widgets that have been set
-- insensitive with Gtk.Widget.Set_Sensitive().
--
-- Colors can be specified as a string containing a color name (GTK+ knows all
-- names from the X color database /usr/lib/X11/rgb.txt), in one of the
-- hexadecimal forms #rrrrggggbbbb, #rrrgggbbb, #rrggbb, or #rgb, where r, g
-- and b are hex digits, or they can be specified as a triplet { r, g, b},
-- where r, g and b are either integers in the range 0-65535 or floats in the
-- range 0.0-1.0.
--
-- In a stock definition, icon sources are specified as a 4-tuple of image
-- filename or icon name, text direction, widget state, and size, in that
-- order. Each icon source specifies an image filename or icon name to use
-- with a given direction, state, and size. Filenames are specified as a
-- string such as "itemltr.png", while icon names (looked up in the current
-- icon theme), are specified with a leading @, such as @"item-ltr". The *
-- character can be used as a wildcard, and if direction/state/size are
-- omitted they default to *. So for example, the following specifies
-- different icons to use for left-to-right and right-to-left languages:
--
-- stock["my-stock-item"] = {
-- { "itemltr.png", LTR, *, * },
-- { "itemrtl.png", RTL, *, * }}
--
-- This could be abbreviated as follows:
--
-- stock["my-stock-item"] = {
-- { "itemltr.png", LTR },
-- { "itemrtl.png", RTL }}
--
-- You can specify custom icons for specific sizes, as follows:
--
-- stock["my-stock-item"] = {
-- { "itemmenusize.png", *, *, "gtk-menu" },
-- { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
-- { "itemgeneric.png" }} /* implicit *, *, * as a fallback */
--
-- The sizes that come with GTK+ itself are "gtk-menu", "gtk-small-toolbar",
-- "gtk-large-toolbar", "gtk-button", "gtk-dialog". Applications can define
-- other sizes (see also Gtk.Icon_Factory to learn more about this)
--
-- It's also possible to use custom icons for a given state, for example:
--
-- stock["my-stock-item"] = {
-- { "itemprelight.png", *, PRELIGHT },
-- { "iteminsensitive.png", *, INSENSITIVE },
-- { "itemgeneric.png" }} /* implicit *, *, * as a fallback */
--
-- When selecting an icon source to use, GTK+ will consider text direction
-- most important, state second, and size third. It will select the best match
-- based on those criteria. If an attribute matches exactly (e.g. you
-- specified PRELIGHT or specified the size), GTK+ won't modify the image; if
-- the attribute matches with a wildcard, GTK+ will scale or modify the image
-- to match the state and size the user requested.
--
-- Key bindings
-- ============
--
-- Key bindings allow the user to specify actions to be taken on particular
-- key presses. The form of a binding set declaration is:
--
-- binding name {
-- bind key {
-- signalname (param, ...)
-- ...
-- }
-- ...
-- }
--
-- key is a string consisting of a series of modifiers followed by the name of
-- a key. The modifiers can be:
-- , , , , , ,
-- , ,
-- is an alias for and is an alias for .
--
-- The action that is bound to the key is a sequence of signal names (strings)
-- followed by parameters for each signal. The signals must be action signals.
-- Each parameter can be a float, integer, string, or unquoted string
-- representing an enumeration value. The types of the parameters specified
-- must match the types of the parameters of the signal.
--
-- Binding sets are connected to widgets in the same manner as styles, with
-- one difference: Binding sets override other binding sets first by pattern
-- type, then by priority and then by order of specification. The priorities
-- that can be specified and their default values are the same as for styles.
--
-- 2.8.17
-- Configuration and Themes
-- gtk-bindings.ads
with Glib.Object;
with Gtk.Settings;
with Gtk.Style; use Gtk.Style;
with Gtk.Widget;
with Gtkada.Types; use Gtkada.Types;
package Gtk.Rc is
type Gtk_Rc_Style_Record is new Glib.Object.GObject_Record with private;
type Gtk_Rc_Style is access all Gtk_Rc_Style_Record'Class;
procedure Gtk_New (Rc_Style : out Gtk_Rc_Style);
procedure Initialize (Rc_Style : access Gtk_Rc_Style_Record'Class);
function Get_Type return Glib.GType;
-- Return the internal value associated with Gtk_Rc_Style.
function Copy (Orig : access Gtk_Rc_Style_Record) return Gtk_Rc_Style;
-- Make a copy of the specified Gtk_Rc.Style.
-- This function will correctly copy an rc style that is a member of a
-- class derived from Gtk_Rc_Style.
procedure Add_Default_File (Filename : String);
-- Add a file to the list of files to be parsed at the end of Gtk.Main.Init
procedure Set_Default_Files (Filenames : Chars_Ptr_Array);
function Get_Default_Files return Chars_Ptr_Array;
-- Set the list of files that GtkAda will read at the end of Gtk.Main.Init
function Get_Style
(Widget : access Gtk.Widget.Gtk_Widget_Record'Class) return Gtk_Style;
-- Find all matching RC styles for a given widget, composites them
-- together, and then create a Gtk_Style representing the composite
-- appearance. (GtkAda actually keeps a cache of previously created styles,
-- so a new style may not be created)
-- Return the resulting style. No refcount is added to the returned style,
-- so if you want to save this style around, you should add a reference
-- yourself.
procedure Parse (Filename : String);
procedure Parse_String (Rc_String : String);
-- Parse either a file or a string containing a gtk+ configuration (see the
-- description at the top of this package).
function Reparse_All return Boolean;
-- If the modification time on any previously read file for the
-- default Gtk_Settings has changed, discard all style information
-- and then reread all previously read RC files.
-- Return True if the files were reread.
function Find_Module_In_Path (Module_File : String) return String;
function Get_Theme_Dir return String;
-- Returns the standard directory in which themes should be installed.
-- (GTK+ does not actually use this directory itself.)
function Get_Module_Dir return String;
-- Returns a directory in which GTK+ looks for theme engines. This is a
-- dynamic library loaded by gtk+ that will be responsible for drawing
-- parts of the application (ie implement all the functions in Gtk.Style)
function Get_Im_Module_Path return String;
-- Obtains the path in which to look for IM modules. See the documentation
-- of the GTK_PATH environment variable for more details about looking up
-- modules. This function is useful solely for utilities supplied with GTK+
-- and should not be used by applications under normal circumstances.
function Get_Im_Module_File return String;
-- Obtains the path to the IM modules file. See the documentation of the
-- GTK_IM_MODULE_FILE environment variable for more details.
function Reparse_All_For_Settings
(Settings : access Gtk.Settings.Gtk_Settings_Record'Class;
Force_Load : Boolean)
return Boolean;
-- If the modification time on any previously read file
-- for the given Gtk_Settings has changed, discard all style information
-- and then reread all previously read RC files.
-- If Force_Load is true, the files are reloaded even if unmodified.
-- Return True if some files have been reparsed
procedure Reset_Styles
(Settings : access Gtk.Settings.Gtk_Settings_Record'Class);
-- This function recomputes the styles for all widgets that use a
-- particular Gtk_Settings object. (There is one Gtk_Settings object
-- per Gdk_Screen, see Gtk.Settings.Get_For_Screen); It is useful
-- when some global parameter has changed that affects the appearance
-- of all widgets, because when a widget gets a new style, it will
-- both redraw and recompute any cached information about its
-- appearance. As an example, it is used when the default font size
-- set by the operating system changes. Note that this function
-- doesn't affect widgets that have a style set explicitely on them
-- with Gtk.Widget.Set_Style.
function Get_Style_By_Paths
(Settings : access Gtk.Settings.Gtk_Settings_Record'Class;
Widget_Path : String := "";
Class_Path : String := "";
Typ : Glib.GType := Glib.GType_None)
return Gtk.Style.Gtk_Style;
-- Creates up a Gtk_Style from styles defined in a RC file by providing
-- the raw components used in matching. This function may be useful
-- when creating pseudo-widgets that should be themed like widgets but
-- don't actually have corresponding GTK+ widgets. An example of this
-- would be items inside a GNOME canvas widget.
-- Returns null if nothing matching was found and the default style should
-- be used. You must call Ref if you intend to keep a reference on the
-- style.
------------------------------
-- Widget related functions --
------------------------------
procedure Modify_Style
(Widget : access Gtk.Widget.Gtk_Widget_Record'Class;
Style : access Gtk_Rc_Style_Record'Class);
-- Modifies style values on the widget. Modifications made using this
-- technique take precedence over style values set via an RC file,
-- however, they will be overriden if a style is explicitely set on
-- the widget using gtk_widget_set_style(). The #GtkRcStyle structure
-- is designed so each field can either be set or unset, so it is
-- possible, using this function, to modify some style values and
-- leave the others unchanged.
--
-- Note that modifications made with this function are not cumulative
-- with previous calls to gtk_widget_modify_style() or with such
-- functions as gtk_widget_modify_fg(). If you wish to retain
-- previous values, you must first call gtk_widget_get_modifier_style(),
-- make your modifications to the returned style, then call
-- gtk_widget_modify_style() with that style. On the other hand,
-- if you first call gtk_widget_modify_style(), subsequent calls
-- to such functions gtk_widget_modify_fg() will have a cumulative
-- effect with the initial modifications.
function Get_Modifier_Style
(Widget : access Gtk.Widget.Gtk_Widget_Record'Class) return Gtk_Rc_Style;
-- Return the current modifier style for the widget.
-- (As set by Modify_Style.) If no style has previously set, a new
-- Gtk_Rc_Style will be created with all values unset, and set as the
-- modifier style for the widget. If you make changes to this rc
-- style, you must call Modify_Style, passing in the
-- returned rc style, to make sure that your changes take effect.
--
-- Return value: the modifier style for the widget. This rc style is
-- owned by the widget. If you want to keep a pointer to value this
-- around, you must add a refcount using Ref.
private
type Gtk_Rc_Style_Record is new Glib.Object.GObject_Record with null record;
pragma Import (C, Get_Type, "gtk_rc_style_get_type");
end Gtk.Rc;
-- The following functions never had a binding and are now obsolescent:
-- No binding: gtk_rc_add_class_style
-- No binding: gtk_rc_add_widget_class_style
-- No binding: gtk_rc_add_widget_name_style
-- These functions do not seem to be needed for normal applications:
-- No binding: gtk_rc_parse_color
-- No binding: gtk_rc_parse_priority
-- No binding: gtk_rc_parse_state
-- No binding: gtk_rc_scanner_new
-- No binding: gtk_rc_style_ref
-- No binding: gtk_rc_style_unref
-- No binding: gtk_rc_find_pixmap_in_path