Gtk-3.0 Python API Documentation

Implements: Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Dialog

The GtkAboutDialog offers a simple way to display information about a program like its logo, name, copyright, website and license. It is also possible to give credits to the authors, documenters, translators and artists who have worked on the program. An about dialog is typically opened when the user selects the <literal>About</literal> option from the <literal>Help</literal> menu. All parts of the dialog are optional. About dialog often contain links and email addresses. GtkAboutDialog displays these as clickable links. By default, it calls gtk_show_uri() when a user clicks one. The behaviour can be overridden with the #GtkAboutDialog::activate-link signal. To make constructing a GtkAboutDialog as convenient as possible, you can use the function gtk_show_about_dialog() which constructs and shows a dialog and keeps it around so that it can be shown again. Note that GTK+ sets a default title of <literal>_("About &percnt;s")</literal> on the dialog window (where &percnt;s is replaced by the name of the application, but in order to ensure proper translation of the title, applications should set the title property explicitly when constructing a GtkAboutDialog, as shown in the following example: <informalexample><programlisting> gtk_show_about_dialog (NULL, "program-name", "ExampleCode", "logo", example_logo, "title" _("About ExampleCode"), NULL); </programlisting></informalexample>

Subclass of: GObject.Object

A #GtkAccelGroup represents a group of keyboard accelerators, typically attached to a toplevel #GtkWindow (with gtk_window_add_accel_group()). Usually you won't need to create a #GtkAccelGroup directly; instead, when using #GtkUIManager, GTK+ automatically sets up the accelerators for your menus in the ui manager's #GtkAccelGroup. Note that <firstterm>accelerators</firstterm> are different from <firstterm>mnemonics</firstterm>. Accelerators are shortcuts for activating a menu item; they appear alongside the menu item they're a shortcut for. For example "Ctrl+Q" might appear alongside the "Quit" menu item. Mnemonics are shortcuts for GUI elements such as text entries or buttons; they appear as underlined characters. See gtk_label_new_with_mnemonic(). Menu items can have both accelerators and mnemonics, of course.

Implements: Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Label

The #GtkAccelLabel widget is a subclass of #GtkLabel that also displays an accelerator key on the right of the label text, e.g. 'Ctl+S'. It is commonly used in menus to show the keyboard short-cuts for commands. The accelerator key to display is not set explicitly. Instead, the #GtkAccelLabel displays the accelerators which have been added to a particular widget. This widget is set by calling gtk_accel_label_set_accel_widget(). For example, a #GtkMenuItem widget may have an accelerator added to emit the "activate" signal when the 'Ctl+S' key combination is pressed. A #GtkAccelLabel is created and added to the #GtkMenuItem, and gtk_accel_label_set_accel_widget() is called with the #GtkMenuItem as the second argument. The #GtkAccelLabel will now display 'Ctl+S' after its label. Note that creating a #GtkMenuItem with gtk_menu_item_new_with_label() (or one of the similar functions for #GtkCheckMenuItem and #GtkRadioMenuItem) automatically adds a #GtkAccelLabel to the #GtkMenuItem and calls gtk_accel_label_set_accel_widget() to set it up for you. A #GtkAccelLabel will only display accelerators which have %GTK_ACCEL_VISIBLE set (see #GtkAccelFlags). A #GtkAccelLabel can display multiple accelerators and even signal names, though it is almost always used to display just one accelerator key. <example> <title>Creating a simple menu item with an accelerator key.</title> <programlisting> GtkWidget *save_item; GtkAccelGroup *accel_group; /<!---->* Create a GtkAccelGroup and add it to the window. *<!---->/ accel_group = gtk_accel_group_new (<!-- -->); gtk_window_add_accel_group (GTK_WINDOW (window), accel_group); /<!---->* Create the menu item using the convenience function. *<!---->/ save_item = gtk_menu_item_new_with_label ("Save"); gtk_widget_show (save_item); gtk_container_add (GTK_CONTAINER (menu), save_item); /<!---->* Now add the accelerator to the GtkMenuItem. Note that since we called gtk_menu_item_new_with_label(<!-- -->) to create the GtkMenuItem the GtkAccelLabel is automatically set up to display the GtkMenuItem accelerators. We just need to make sure we use GTK_ACCEL_VISIBLE here. *<!---->/ gtk_widget_add_accelerator (save_item, "activate", accel_group, GDK_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE); </programlisting> </example>

Subclass of: GObject.Object

Accelerator maps are used to define runtime configurable accelerators. Functions for manipulating them are are usually used by higher level convenience mechanisms like #GtkUIManager and are thus considered "low-level". You'll want to use them if you're manually creating menus that should have user-configurable accelerators. Accelerator is uniquely defined by: <itemizedlist> <listitem><para>accelerator path</para></listitem> <listitem><para>accelerator key</para></listitem> <listitem><para>accelerator modifiers</para></listitem> </itemizedlist> The accelerator path must consist of "&lt;WINDOWTYPE&gt;/Category1/Category2/.../Action", where WINDOWTYPE should be a unique application-specific identifier that corresponds to the kind of window the accelerator is being used in, e.g. "Gimp-Image", "Abiword-Document" or "Gnumeric-Settings". The "Category1/.../Action" portion is most appropriately chosen by the action the accelerator triggers, i.e. for accelerators on menu items, choose the item's menu path, e.g. "File/Save As", "Image/View/Zoom" or "Edit/Select All". So a full valid accelerator path may look like: "&lt;Gimp-Toolbox&gt;/File/Dialogs/Tool Options...". All accelerators are stored inside one global #GtkAccelMap that can be obtained using gtk_accel_map_get(). See <link linkend="monitoring-changes">Monitoring changes</link> for additional details. <refsect2 id="manipulating-accelerators"> <title>Manipulating accelerators</title> <para> New accelerators can be added using gtk_accel_map_add_entry(). To search for specific accelerator, use gtk_accel_map_lookup_entry(). Modifications of existing accelerators should be done using gtk_accel_map_change_entry(). In order to avoid having some accelerators changed, they can be locked using gtk_accel_map_lock_path(). Unlocking is done using gtk_accel_map_unlock_path(). </para> </refsect2> <refsect2 id="saving-and-loading"> <title>Saving and loading accelerator maps</title> <para> Accelerator maps can be saved to and loaded from some external resource. For simple saving and loading from file, gtk_accel_map_save() and gtk_accel_map_load() are provided. Saving and loading can also be done by providing file descriptor to gtk_accel_map_save_fd() and gtk_accel_map_load_fd(). </para> </refsect2> <refsect2 id="monitoring-changes"> <title>Monitoring changes</title> <para> #GtkAccelMap object is only useful for monitoring changes of accelerators. By connecting to #GtkAccelMap::changed signal, one can monitor changes of all accelerators. It is also possible to monitor only single accelerator path by using it as a detail of the #GtkAccelMap::changed signal. </para> </refsect2>

Subclass of: Atk.Object

Implements: Gtk.Buildable

Known subclasses: Gtk.RecentAction, Gtk.ToggleAction

Subclass of: GObject.Object

Actions represent operations that the user can be perform, along with some information how it should be presented in the interface. Each action provides methods to create icons, menu items and toolbar items representing itself. As well as the callback that is called when the action gets activated, the following also gets associated with the action: <itemizedlist> <listitem><para>a name (not translated, for path lookup)</para></listitem> <listitem><para>a label (translated, for display)</para></listitem> <listitem><para>an accelerator</para></listitem> <listitem><para>whether label indicates a stock id</para></listitem> <listitem><para>a tooltip (optional, translated)</para></listitem> <listitem><para>a toolbar label (optional, shorter than label)</para></listitem> </itemizedlist> The action will also have some state information: <itemizedlist> <listitem><para>visible (shown/hidden)</para></listitem> <listitem><para>sensitive (enabled/disabled)</para></listitem> </itemizedlist> Apart from regular actions, there are <link linkend="GtkToggleAction">toggle actions</link>, which can be toggled between two states and <link linkend="GtkRadioAction">radio actions</link>, of which only one in a group can be in the "active" state. Other actions can be implemented as #GtkAction subclasses. Each action can have one or more proxy widgets. To act as an action proxy, widget needs to implement #GtkActivatable interface. Proxies mirror the state of the action and should change when the action's state changes. Properties that are always mirrored by proxies are #GtkAction:sensitive and #GtkAction:visible. #GtkAction:gicon, #GtkAction:icon-name, #GtkAction:label, #GtkAction:short-label and #GtkAction:stock-id properties are only mirorred if proxy widget has #GtkActivatable:use-action-appearance property set to %TRUE. When the proxy is activated, it should activate its action.

Implements: Gtk.Buildable

Subclass of: GObject.Object

Actions are organised into groups. An action group is essentially a map from names to #GtkAction objects. All actions that would make sense to use in a particular context should be in a single group. Multiple action groups may be used for a particular user interface. In fact, it is expected that most nontrivial applications will make use of multiple groups. For example, in an application that can edit multiple documents, one group holding global actions (e.g. quit, about, new), and one group per document holding actions that act on that document (eg. save, cut/copy/paste, etc). Each window's menus would be constructed from a combination of two action groups. </para> <para id="Action-Accel"> Accelerators are handled by the GTK+ accelerator map. All actions are assigned an accelerator path (which normally has the form <literal>&lt;Actions&gt;/group-name/action-name</literal>) and a shortcut is associated with this accelerator path. All menuitems and toolitems take on this accelerator path. The GTK+ accelerator map code makes sure that the correct shortcut is displayed next to the menu item. <refsect2 id="GtkActionGroup-BUILDER-UI"> <title>GtkActionGroup as GtkBuildable</title> <para> The #GtkActionGroup implementation of the #GtkBuildable interface accepts #GtkAction objects as &lt;child&gt; elements in UI definitions. Note that it is probably more common to define actions and action groups in the code, since they are directly related to what the code can do. The GtkActionGroup implementation of the GtkBuildable interface supports a custom &lt;accelerator&gt; element, which has attributes named key and modifiers and allows to specify accelerators. This is similar to the &lt;accelerator&gt; element of #GtkWidget, the main difference is that it doesn't allow you to specify a signal. </para> <example> <title>A #GtkDialog UI definition fragment.</title> <programlisting><![CDATA[ <object class="GtkActionGroup" id="actiongroup"> <child> <object class="GtkAction" id="About"> <property name="name">About</property> <property name="stock_id">gtk-about</property> <signal handler="about_activate" name="activate"/> </object> <accelerator key="F1" modifiers="GDK_CONTROL_MASK | GDK_SHIFT_MASK"/> </child> </object> ]]></programlisting> </example> </refsect2>

Subclass of: GObject.InitiallyUnowned

The #GtkAdjustment object represents a value which has an associated lower and upper bound, together with step and page increments, and a page size. It is used within several GTK+ widgets, including #GtkSpinButton, #GtkViewport, and #GtkRange (which is a base class for #GtkHScrollbar, #GtkVScrollbar, #GtkHScale, and #GtkVScale). The #GtkAdjustment object does not update the value itself. Instead it is left up to the owner of the #GtkAdjustment to control the value. The owner of the #GtkAdjustment typically calls the gtk_adjustment_value_changed() and gtk_adjustment_changed() functions after changing the value and its bounds. This results in the emission of the #GtkAdjustment::value_changed or #GtkAdjustment::changed signal respectively.

Implements: Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Bin

The #GtkAlignment widget controls the alignment and size of its child widget. The scale settings are used to specify how much the child widget should expand to fill the space allocated to the #GtkAlignment. The values can range from 0 (meaning the child doesn't expand at all) to 1 (meaning the child expands to fill all of the available space). The align settings are used to place the child widget within the available area. The values range from 0 (top or left) to 1 (bottom or right). Of course, if the scale settings are both set to 1, the alignment settings have no effect. <note> <para> Note that the desired effect can in most cases be achieved by using the #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties on the child widget, so #GtkAlignment should not be used in new code. </para> </note>

Implements: Gtk.AppChooser, Gtk.CellLayout, Gtk.Buildable, Gtk.CellEditable, Atk.ImplementorIface

Subclass of: Gtk.ComboBox

The #GtkAppChooserButton is a widget that lets the user select an application. It implements the #GtkAppChooser interface.

Implements: Gtk.AppChooser, Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Dialog

#GtkAppChooserDialog shows a #GtkAppChooserWidget inside a #GtkDialog. Note that #GtkAppChooserDialog does not have any interesting methods of its own. Instead, you should get the embedded #GtkAppChooserWidget using gtk_app_chooser_dialog_get_widget() and call its methods if the generic #GtkAppChooser interface is not sufficient for your needs.

Implements: Gtk.AppChooser, Gtk.Buildable, Gtk.Orientable, Atk.ImplementorIface

Subclass of: Gtk.Box

#GtkAppChooserWidget is a widget for selecting applications. It is the main building block for #GtkAppChooserDialog. Most applications only need to use the latter; but you can use this widget as part of a larger widget if you have special needs.

Implements: Gio.ActionGroup

Subclass of: Gio.Application

#GtkApplication is a class that handles many important aspects of a GTK+ application in a convenient fashion, without enforcing a one-size-fits-all application model. Currently, GtkApplication handles GTK+ initialization, application uniqueness, provides some basic scriptability by exporting 'actions', and manages a list of toplevel windows whose life-cycle is automatically tied to the life-cycle of your application. <example id="gtkapplication"><title>A simple application</title> <programlisting> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/bloatpad.c"> <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> </xi:include> </programlisting> </example>

Implements: Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Misc

GtkArrow should be used to draw simple arrows that need to point in one of the four cardinal directions (up, down, left, or right). The style of the arrow can be one of shadow in, shadow out, etched in, or etched out. Note that these directions and style types may be ammended in versions of GTK+ to come. GtkArrow will fill any space alloted to it, but since it is inherited from #GtkMisc, it can be padded and/or aligned, to fill exactly the space the programmer desires. Arrows are created with a call to gtk_arrow_new(). The direction or style of an arrow can be changed after creation by using gtk_arrow_set().

Implements: Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Frame

The #GtkAspectFrame is useful when you want pack a widget so that it can resize but always retains the same aspect ratio. For instance, one might be drawing a small preview of a larger image. #GtkAspectFrame derives from #GtkFrame, so it can draw a label and a frame around the child. The frame will be "shrink-wrapped" to the size of the child.

Implements: Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Window

A #GtkAssistant is a widget used to represent a generally complex operation splitted in several steps, guiding the user through its pages and controlling the page flow to collect the necessary data. The design of GtkAssistant is that it controls what buttons to show and to make sensitive, based on what it knows about the page sequence and the <link linkend="GtkAssistantPageType">type</link> of each page, in addition to state information like the page <link linkend="gtk-assistant-set-page-complete">completion</link> and <link linkend="gtk-assistant-commit">committed</link> status. If you have a case that doesn't quite fit in #GtkAssistants way of handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page type and handle buttons yourself. <refsect2 id="GtkAssistant-BUILDER-UI"> <title>GtkAssistant as GtkBuildable</title> <para> The GtkAssistant implementation of the GtkBuildable interface exposes the To add pages to an assistant in GtkBuilder, simply add it as a &lt;child&gt; to the GtkAssistant object, and set its child properties as necessary. </para> </refsect2>

Implements: Gtk.Buildable, Gtk.Orientable, Atk.ImplementorIface

Known subclasses: Gtk.ButtonBox, Gtk.AppChooserWidget, Gtk.VBox, Gtk.HBox

Subclass of: Gtk.Container

GtkBox is an widget which encapsulates functionality for a particular kind of container, one that organizes a variable number of widgets into a rectangular area. GtkBox has a number of derived classes, e.g. #GtkHBox and #GtkVBox. The rectangular area of a GtkBox is organized into either a single row or a single column of child widgets depending upon whether the box is of type #GtkHBox or #GtkVBox, respectively. Thus, all children of a GtkBox are allocated one dimension in common, which is the height of a row, or the width of a column. GtkBox uses a notion of <emphasis>packing</emphasis>. Packing refers to adding widgets with reference to a particular position in a #GtkContainer. For a GtkBox, there are two reference positions: the <emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box. For a #GtkVBox, the start is defined as the top of the box and the end is defined as the bottom. For a #GtkHBox the start is defined as the left side and the end is defined as the right side. Use repeated calls to gtk_box_pack_start() to pack widgets into a GtkBox from start to end. Use gtk_box_pack_end() to add widgets from end to start. You may intersperse these calls and add widgets from both ends of the same GtkBox. Because GtkBox is a #GtkContainer, you may also use gtk_container_add() to insert widgets into the box, and they will be packed with the default values for #GtkBox:expand and #GtkBox:fill. Use gtk_container_remove() to remove widgets from the GtkBox. Use gtk_box_set_homogeneous() to specify whether or not all children of the GtkBox are forced to get the same amount of space. Use gtk_box_set_spacing() to determine how much space will be minimally placed between all children in the GtkBox. Note that spacing is added <emphasis>between</emphasis> the children, while padding added by gtk_box_pack_start() or gtk_box_pack_end() is added <emphasis>on either side</emphasis> of the widget it belongs to. Use gtk_box_reorder_child() to move a GtkBox child to a different place in the box. Use gtk_box_set_child_packing() to reset the #GtkBox:expand, #GtkBox:fill and #GtkBox:padding child properties. Use gtk_box_query_child_packing() to query these fields. <note> <para> Note that a single-row or single-column #GtkGrid provides exactly the same functionality as #GtkBox. </para> </note>

Subclass of: GObject.Object

A GtkBuilder is an auxiliary object that reads textual descriptions of a user interface and instantiates the described objects. To pass a description to a GtkBuilder, call gtk_builder_add_from_file() or gtk_builder_add_from_string(). These functions can be called multiple times; the builder merges the content of all descriptions. A GtkBuilder holds a reference to all objects that it has constructed and drops these references when it is finalized. This finalization can cause the destruction of non-widget objects or widgets which are not contained in a toplevel window. For toplevel windows constructed by a builder, it is the responsibility of the user to call gtk_widget_destroy() to get rid of them and all the widgets they contain. The functions gtk_builder_get_object() and gtk_builder_get_objects() can be used to access the widgets in the interface by the names assigned to them inside the UI description. Toplevel windows returned by these functions will stay around until the user explicitly destroys them with gtk_widget_destroy(). Other widgets will either be part of a larger hierarchy constructed by the builder (in which case you should not have to worry about their lifecycle), or without a parent, in which case they have to be added to some container to make use of them. Non-widget objects need to be reffed with g_object_ref() to keep them beyond the lifespan of the builder. The function gtk_builder_connect_signals() and variants thereof can be used to connect handlers to the named signals in the description. <refsect2 id="BUILDER-UI"> <title>GtkBuilder UI Definitions</title> <para> GtkBuilder parses textual descriptions of user interfaces which are specified in an XML format which can be roughly described by the DTD below. We refer to these descriptions as <firstterm>GtkBuilder UI definitions</firstterm> or just <firstterm>UI definitions</firstterm> if the context is clear. Do not confuse GtkBuilder UI Definitions with <link linkend="XML-UI">GtkUIManager UI Definitions</link>, which are more limited in scope. </para> <programlisting><![CDATA[ <!ELEMENT interface (requires|object)* > <!ELEMENT object (property|signal|child|ANY)* > <!ELEMENT property PCDATA > <!ELEMENT signal EMPTY > <!ELEMENT requires EMPTY > <!ELEMENT child (object|ANY*) > <!ATTLIST interface domain #IMPLIED > <!ATTLIST object id #REQUIRED class #REQUIRED type-func #IMPLIED constructor #IMPLIED > <!ATTLIST requires lib #REQUIRED version #REQUIRED > <!ATTLIST property name #REQUIRED translatable #IMPLIED comments #IMPLIED context #IMPLIED > <!ATTLIST signal name #REQUIRED handler #REQUIRED after #IMPLIED swapped #IMPLIED object #IMPLIED last_modification_time #IMPLIED > <!ATTLIST child type #IMPLIED internal-child #IMPLIED > ]]></programlisting> <para> The toplevel element is &lt;interface&gt;. It optionally takes a "domain" attribute, which will make the builder look for translated strings using dgettext() in the domain specified. This can also be done by calling gtk_builder_set_translation_domain() on the builder. Objects are described by &lt;object&gt; elements, which can contain &lt;property&gt; elements to set properties, &lt;signal&gt; elements which connect signals to handlers, and &lt;child&gt; elements, which describe child objects (most often widgets inside a container, but also e.g. actions in an action group, or columns in a tree model). A &lt;child&gt; element contains an &lt;object&gt; element which describes the child object. The target toolkit version(s) are described by &lt;requires&gt; elements, the "lib" attribute specifies the widget library in question (currently the only supported value is "gtk+") and the "version" attribute specifies the target version in the form "&lt;major&gt;.&lt;minor&gt;". The builder will error out if the version requirements are not met. Typically, the specific kind of object represented by an &lt;object&gt; element is specified by the "class" attribute. If the type has not been loaded yet, GTK+ tries to find the <function>_get_type()</function> from the class name by applying heuristics. This works in most cases, but if necessary, it is possible to specify the name of the <function>_get_type()</function> explictly with the "type-func" attribute. As a special case, GtkBuilder allows to use an object that has been constructed by a #GtkUIManager in another part of the UI definition by specifying the id of the #GtkUIManager in the "constructor" attribute and the name of the object in the "id" attribute. Objects must be given a name with the "id" attribute, which allows the application to retrieve them from the builder with gtk_builder_get_object(). An id is also necessary to use the object as property value in other parts of the UI definition. </para> <note><para> Prior to 2.20, GtkBuilder was setting the "name" property of constructed widgets to the "id" attribute. In GTK+ 2.20 or newer, you have to use gtk_buildable_get_name() instead of gtk_widget_get_name() to obtain the "id", or set the "name" property in your UI definition. </para></note> <para> Setting properties of objects is pretty straightforward with the &lt;property&gt; element: the "name" attribute specifies the name of the property, and the content of the element specifies the value. If the "translatable" attribute is set to a true value, GTK+ uses gettext() (or dgettext() if the builder has a translation domain set) to find a translation for the value. This happens before the value is parsed, so it can be used for properties of any type, but it is probably most useful for string properties. It is also possible to specify a context to disambiguate short strings, and comments which may help the translators. GtkBuilder can parse textual representations for the most common property (strings like "TRUE", "t", "yes", "y", "1" are interpreted as %TRUE, strings like "FALSE, "f", "no", "n", "0" are interpreted as %FALSE), enumerations (can be specified by their name, nick or integer value), flags (can be specified by their name, nick, integer value, optionally combined with "|", e.g. "GTK_VISIBLE|GTK_REALIZED") and colors (in a format understood by gdk_color_parse()). Objects can be referred to by their name. Pixbufs can be specified as a filename of an image file to load. In general, GtkBuilder allows forward references to objects &mdash; an object doesn't have to be constructed before it can be referred to. The exception to this rule is that an object has to be constructed before it can be used as the value of a construct-only property. Signal handlers are set up with the &lt;signal&gt; element. The "name" attribute specifies the name of the signal, and the "handler" attribute specifies the function to connect to the signal. By default, GTK+ tries to find the handler using g_module_symbol(), but this can be changed by passing a custom #GtkBuilderConnectFunc to gtk_builder_connect_signals_full(). The remaining attributes, "after", "swapped" and "object", have the same meaning as the corresponding parameters of the g_signal_connect_object() or g_signal_connect_data() functions. A "last_modification_time" attribute is also allowed, but it does not have a meaning to the builder. Sometimes it is necessary to refer to widgets which have implicitly been constructed by GTK+ as part of a composite widget, to set properties on them or to add further children (e.g. the @vbox of a #GtkDialog). This can be achieved by setting the "internal-child" propery of the &lt;child&gt; element to a true value. Note that GtkBuilder still requires an &lt;object&gt; element for the internal child, even if it has already been constructed. A number of widgets have different places where a child can be added (e.g. tabs vs. page content in notebooks). This can be reflected in a UI definition by specifying the "type" attribute on a &lt;child&gt;. The possible values for the "type" attribute are described in the sections describing the widget-specific portions of UI definitions. </para> <example> <title>A GtkBuilder UI Definition</title> <programlisting><![CDATA[ <interface> <object class="GtkDialog" id="dialog1"> <child internal-child="vbox"> <object class="GtkVBox" id="vbox1"> <property name="border-width">10</property> <child internal-child="action_area"> <object class="GtkHButtonBox" id="hbuttonbox1"> <property name="border-width">20</property> <child> <object class="GtkButton" id="ok_button"> <property name="label">gtk-ok</property> <property name="use-stock">TRUE</property> <signal name="clicked" handler="ok_button_clicked"/> </object> </child> </object> </child> </object> </child> </object> </interface> ]]></programlisting> </example> <para> Beyond this general structure, several object classes define their own XML DTD fragments for filling in the ANY placeholders in the DTD above. Note that a custom element in a &lt;child&gt; element gets parsed by the custom tag handler of the parent object, while a custom element in an &lt;object&gt; element gets parsed by the custom tag handler of the object. These XML fragments are explained in the documentation of the respective objects, see <link linkend="GtkWidget-BUILDER-UI">GtkWidget</link>, <link linkend="GtkLabel-BUILDER-UI">GtkLabel</link>, <link linkend="GtkWindow-BUILDER-UI">GtkWindow</link>, <link linkend="GtkContainer-BUILDER-UI">GtkContainer</link>, <link linkend="GtkDialog-BUILDER-UI">GtkDialog</link>, <link linkend="GtkCellLayout-BUILDER-UI">GtkCellLayout</link>, <link linkend="GtkColorSelectionDialog-BUILDER-UI">GtkColorSelectionDialog</link>, <link linkend="GtkFontSelectionDialog-BUILDER-UI">GtkFontSelectionDialog</link>, <link linkend="GtkExpander-BUILDER-UI">GtkExpander</link>, <link linkend="GtkFrame-BUILDER-UI">GtkFrame</link>, <link linkend="GtkListStore-BUILDER-UI">GtkListStore</link>, <link linkend="GtkTreeStore-BUILDER-UI">GtkTreeStore</link>, <link linkend="GtkNotebook-BUILDER-UI">GtkNotebook</link>, <link linkend="GtkSizeGroup-BUILDER-UI">GtkSizeGroup</link>, <link linkend="GtkTreeView-BUILDER-UI">GtkTreeView</link>, <link linkend="GtkUIManager-BUILDER-UI">GtkUIManager</link>, <link linkend="GtkActionGroup-BUILDER-UI">GtkActionGroup</link>. <link linkend="GtkMenuItem-BUILDER-UI">GtkMenuItem</link>, <link linkend="GtkMenuToolButton-BUILDER-UI">GtkMenuToolButton</link>, <link linkend="GtkAssistant-BUILDER-UI">GtkAssistant</link>, <link linkend="GtkScale-BUILDER-UI">GtkScale</link>, <link linkend="GtkComboBoxText-BUILDER-UI">GtkComboBoxText</link>, <link linkend="GtkRecentFilter-BUILDER-UI">GtkRecentFilter</link>, <link linkend="GtkFileFilter-BUILDER-UI">GtkFileFilter</link>, <link linkend="GtkTextTagTable-BUILDER-UI">GtkTextTagTable</link>. </para> </refsect2>

Implements: Gtk.Activatable, Gtk.Buildable, Atk.ImplementorIface

Known subclasses: Gtk.FontButton, Gtk.ScaleButton, Gtk.LinkButton, Gtk.ColorButton, Gtk.ToggleButton

Subclass of: Gtk.Bin

The #GtkButton widget is generally used to attach a function to that is called when the button is pressed. The various signals and how to use them are outlined below. The #GtkButton widget can hold any valid child widget. That is it can hold most any other standard #GtkWidget. The most commonly used child is the #GtkLabel.

Implements: Gtk.Buildable, Gtk.Orientable, Atk.ImplementorIface

Known subclasses: Gtk.HButtonBox, Gtk.VButtonBox

Subclass of: Gtk.Box

Implements: Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Widget

#GtkCalendar is a widget that displays a Gregorian calendar, one month at a time. It can be created with gtk_calendar_new(). The month and year currently displayed can be altered with gtk_calendar_select_month(). The exact day can be selected from the displayed month using gtk_calendar_select_day(). To place a visual marker on a particular day, use gtk_calendar_mark_day() and to remove the marker, gtk_calendar_unmark_day(). Alternative, all marks can be cleared with gtk_calendar_clear_marks(). The way in which the calendar itself is displayed can be altered using gtk_calendar_set_display_options(). The selected date can be retrieved from a #GtkCalendar using gtk_calendar_get_date(). Users should be aware that, although the Gregorian calendar is the legal calendar in most countries, it was adopted progressively between 1582 and 1929. Display before these dates is likely to be historically incorrect.

Implements: Gtk.CellLayout, Gtk.Buildable, Gtk.Orientable

Subclass of: Gtk.CellArea

The #GtkCellAreaBox renders cell renderers into a row or a column depending on its #GtkOrientation. GtkCellAreaBox uses a notion of <emphasis>packing</emphasis>. Packing refers to adding cell renderers with reference to a particular position <emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box. When the #GtkCellAreaBox is oriented in the %GTK_ORIENTATION_VERTICAL orientation, the start is defined as the top of the box and the end is defined as the bottom. In the %GTK_ORIENTATION_HORIZONTAL orientation start is defined as the left side and the end is defined as the right side. Alignments of #GtkCellRenderers rendered in adjacent rows can be configured by configuring the #GtkCellAreaBox:align child cell property with gtk_cell_area_cell_set_property() or by specifying the "align" argument to gtk_cell_area_box_pack_start() and gtk_cell_area_box_pack_end().

Subclass of: GObject.Object

The #GtkCellAreaContext object is created by a given #GtkCellArea implementation via its #GtkCellAreaClass.create_context() virtual method and is used to store cell sizes and alignments for a series of #GtkTreeModel rows that are requested and rendered in the same context. #GtkCellLayout widgets can create any number of contexts in which to request and render groups of data rows. However its important that the same context which was used to request sizes for a given #GtkTreeModel row also be used for the same row when calling other #GtkCellArea APIs such as gtk_cell_area_render() and gtk_cell_area_event().

Subclass of: Gtk.CellRendererText

Subclass of: Gtk.CellRendererText

Subclass of: Gtk.CellRenderer

Implements: Gtk.Orientable

Subclass of: Gtk.CellRenderer

Subclass of: Gtk.CellRendererText

Subclass of: Gtk.CellRenderer

GtkCellRendererSpinner renders a spinning animation in a cell, very similar to #GtkSpinner. It can often be used as an alternative to a #GtkCellRendererProgress for displaying indefinite activity, instead of actual progress. To start the animation in a cell, set the #GtkCellRendererSpinner:active property to %TRUE and increment the #GtkCellRendererSpinner:pulse property at regular intervals. The usual way to set the cell renderer properties for each cell is to bind them to columns in your tree model using e.g. gtk_tree_view_column_add_attribute().

Known subclasses: Gtk.CellRendererCombo, Gtk.CellRendererAccel, Gtk.CellRendererSpin

Subclass of: Gtk.CellRenderer

A #GtkCellRendererText renders a given text in its cell, using the font, color and style information provided by its properties. The text will be ellipsized if it is too long and the #GtkCellRendererText:ellipsize property allows it. If the #GtkCellRenderer:mode is %GTK_CELL_RENDERER_MODE_EDITABLE, the #GtkCellRendererText allows to edit its text using an entry.

Subclass of: Gtk.CellRenderer

Implements: Gtk.CellLayout, Gtk.Buildable, Gtk.Orientable, Atk.ImplementorIface

Subclass of: Gtk.Widget

A #GtkCellView displays a single row of a #GtkTreeModel using a #GtkCellArea and #GtkCellAreaContext. A #GtkCellAreaContext can be provided to the #GtkCellView at construction time in order to keep the cellview in context of a group of cell views, this ensures that the renderers displayed will be properly aligned with eachother (like the aligned cells in the menus of #GtkComboBox). #GtkCellView is #GtkOrientable in order to decide in which orientation the underlying #GtkCellAreaContext should be allocated. Taking the #GtkComboBox menu as an example, cellviews should be oriented horizontally if the menus are listed top-to-bottom and thus all share the same width but may have separate individual heights (left-to-right menus should be allocated vertically since they all share the same height but may have variable widths).

Implements: Gtk.Activatable, Gtk.Buildable, Atk.ImplementorIface

Known subclasses: Gtk.RadioButton

Subclass of: Gtk.ToggleButton

Implements: Gtk.Activatable, Gtk.Buildable, Atk.ImplementorIface

Known subclasses: Gtk.RadioMenuItem

Subclass of: Gtk.MenuItem

Subclass of: GObject.Object

Implements: Gtk.Activatable, Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Button

The #GtkColorButton is a button which displays the currently selected color an allows to open a color selection dialog to change the color. It is suitable widget for selecting a color in a preference dialog.

Implements: Gtk.Buildable, Gtk.Orientable, Atk.ImplementorIface

Subclass of: Gtk.VBox

Implements: Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Dialog

Implements: Gtk.CellLayout, Gtk.Buildable, Gtk.CellEditable, Atk.ImplementorIface

Known subclasses: Gtk.AppChooserButton, Gtk.ComboBoxText

Subclass of: Gtk.Bin

A GtkComboBox is a widget that allows the user to choose from a list of valid choices. The GtkComboBox displays the selected choice. When activated, the GtkComboBox displays a popup which allows the user to make a new choice. The style in which the selected value is displayed, and the style of the popup is determined by the current theme. It may be similar to a Windows-style combo box. The GtkComboBox uses the model-view pattern; the list of valid choices is specified in the form of a tree model, and the display of the choices can be adapted to the data in the model by using cell renderers, as you would in a tree view. This is possible since GtkComboBox implements the #GtkCellLayout interface. The tree model holding the valid choices is not restricted to a flat list, it can be a real tree, and the popup will reflect the tree structure. To allow the user to enter values not in the model, the 'has-entry' property allows the GtkComboBox to contain a #GtkEntry. This entry can be accessed by calling gtk_bin_get_child() on the combo box. For a simple list of textual choices, the model-view API of GtkComboBox can be a bit overwhelming. In this case, #GtkComboBoxText offers a simple alternative. Both GtkComboBox and #GtkComboBoxText can contain an entry.

Implements: Gtk.CellLayout, Gtk.Buildable, Gtk.CellEditable, Atk.ImplementorIface

Subclass of: Gtk.ComboBox

A GtkComboBoxText is a simple variant of #GtkComboBox that hides the model-view complexity for simple text-only use cases. To create a GtkComboBoxText, use gtk_combo_box_text_new() or gtk_combo_box_text_new_with_entry(). You can add items to a GtkComboBoxText with gtk_combo_box_text_append_text(), gtk_combo_box_text_insert_text() or gtk_combo_box_text_prepend_text() and remove options with gtk_combo_box_text_remove(). If the GtkComboBoxText contains an entry (via the 'has-entry' property), its contents can be retrieved using gtk_combo_box_text_get_active_text(). The entry itself can be accessed by calling gtk_bin_get_child() on the combo box. <refsect2 id="GtkComboBoxText-BUILDER-UI"> <title>GtkComboBoxText as GtkBuildable</title> <para> The GtkComboBoxText implementation of the GtkBuildable interface supports adding items directly using the &lt;items&gt element and specifying &lt;item&gt elements for each item. Each &lt;item&gt element supports the regular translation attributes "translatable", "context" and "comments". <example> <title>A UI definition fragment specifying GtkComboBoxText items</title> <programlisting><![CDATA[ <object class="GtkComboBoxText"> <items> <item translatable="yes">Factory</item> <item translatable="yes">Home</item> <item translatable="yes">Subway</item> </items> </object> ]]></programlisting> </example> </para> </refsect2>

Implements: Gtk.StyleProvider

Subclass of: GObject.Object

GtkCssProvider is an object implementing the #GtkStyleProvider interface. It is able to parse <ulink url="http://www.w3.org/TR/CSS2">CSS</ulink>-like input in order to style widgets. <refsect2 id="gtkcssprovider-files"> <title>Default files</title> <para> An application can cause GTK+ to parse a specific CSS style sheet by calling gtk_css_provider_load_from_file() and adding the provider with gtk_style_context_add_provider() or gtk_style_context_add_provider_for_screen(). In addition, certain files will be read when GTK+ is initialized. First, the file <filename><envar>$XDG_CONFIG_HOME</envar>/gtk-3.0/gtk.css</filename> is loaded if it exists. Then, GTK+ tries to load <filename><envar>$HOME</envar>/.themes/<replaceable>theme-name</replaceable>/gtk-3.0/gtk.css</filename>, falling back to <filename><replaceable>datadir</replaceable>/share/themes/<replaceable>theme-name</replaceable>/gtk-3.0/gtk.css</filename>, where <replaceable>theme-name</replaceable> is the name of the current theme (see the #GtkSettings:gtk-theme-name setting) and <replaceable>datadir</replaceable> is the prefix configured when GTK+ was compiled, unless overridden by the <envar>GTK_DATA_PREFIX</envar> environment variable. </para> </refsect2> <refsect2 id="gtkcssprovider-stylesheets"> <title>Style sheets</title> <para> The basic structure of the style sheets understood by this provider is a series of statements, which are either rule sets or '@-rules', separated by whitespace. </para> <para> A rule set consists of a selector and a declaration block, which is a series of declarations enclosed in curly braces ({ and }). The declarations are separated by semicolons (;). Multiple selectors can share the same declaration block, by putting all the separators in front of the block, separated by commas. </para> <example><title>A rule set with two selectors</title> <programlisting language="text"> GtkButton, GtkEntry { } </programlisting> </example> </refsect2> <refsect2 id="gtkcssprovider-selectors"> <title>Selectors</title> <para> Selectors work very similar to the way they do in CSS, with widget class names taking the role of element names, and widget names taking the role of IDs. When used in a selector, widget names must be prefixed with a '&num;' character. The '*' character represents the so-called universal selector, which matches any widget. </para> <para> To express more complicated situations, selectors can be combined in various ways: <itemizedlist> <listitem><para>To require that a widget satisfies several conditions, combine several selectors into one by concatenating them. E.g. <literal>GtkButton&num;button1</literal> matches a GtkButton widget with the name button1.</para></listitem> <listitem><para>To only match a widget when it occurs inside some other widget, write the two selectors after each other, separated by whitespace. E.g. <literal>GtkToolBar GtkButton</literal> matches GtkButton widgets that occur inside a GtkToolBar.</para></listitem> <listitem><para>In the previous example, the GtkButton is matched even if it occurs deeply nested inside the toolbar. To restrict the match to direct children of the parent widget, insert a '>' character between the two selectors. E.g. <literal>GtkNotebook > GtkLabel</literal> matches GtkLabel widgets that are direct children of a GtkNotebook.</para></listitem> </itemizedlist> </para> <example> <title>Widget classes and names in selectors</title> <programlisting language="text"> /&ast; Theme labels that are descendants of a window &ast;/ GtkWindow GtkLabel { } /&ast; Theme notebooks, and anything that's within these &ast;/ GtkNotebook { } /&ast; Theme combo boxes, and entries that are direct children of a notebook &ast;/ GtkComboBox, GtkNotebook > GtkEntry { } /&ast; Theme any widget within a GtkBin &ast;/ GtkBin * { } /&ast; Theme a label named title-label &ast;/ GtkLabel&num;title-label { } /&ast; Theme any widget named main-entry &ast;/ &num;main-entry { } </programlisting> </example> <para> Widgets may also define style classes, which can be used for matching. When used in a selector, style classes must be prefixed with a '.' character. </para> <para> Refer to the documentation of individual widgets to learn which style classes they define and see <xref linkend="gtkstylecontext-classes"/> for a list of all style classes used by GTK+ widgets. </para> <para> Note that there is some ambiguity in the selector syntax when it comes to differentiation widget class names from regions. GTK+ currently treats a string as a widget class name if it contains any uppercase characters (which should work for more widgets with names like GtkLabel). </para> <example> <title>Style classes in selectors</title> <programlisting language="text"> /&ast; Theme all widgets defining the class entry &ast;/ .entry { } /&ast; Theme spinbuttons' entry &ast;/ GtkSpinButton.entry { } </programlisting> </example> <para> In complicated widgets like e.g. a GtkNotebook, it may be desirable to style different parts of the widget differently. To make this possible, container widgets may define regions, whose names may be used for matching in selectors. </para> <para> Some containers allow to further differentiate between regions by applying so-called pseudo-classes to the region. For example, the tab region in GtkNotebook allows to single out the first or last tab by using the :first-child or :last-child pseudo-class. When used in selectors, pseudo-classes must be prefixed with a ':' character. </para> <para> Refer to the documentation of individual widgets to learn which regions and pseudo-classes they define and see <xref linkend="gtkstylecontext-classes"/> for a list of all regions used by GTK+ widgets. </para> <example> <title>Regions in selectors</title> <programlisting language="text"> /&ast; Theme any label within a notebook &ast;/ GtkNotebook GtkLabel { } /&ast; Theme labels within notebook tabs &ast;/ GtkNotebook tab GtkLabel { } /&ast; Theme labels in the any first notebook tab, both selectors are equivalent &ast;/ GtkNotebook tab:nth-child(first) GtkLabel, GtkNotebook tab:first-child GtkLabel { } </programlisting> </example> <para> Another use of pseudo-classes is to match widgets depending on their state. This is conceptually similar to the :hover, :active or :focus pseudo-classes in CSS. The available pseudo-classes for widget states are :active, :prelight (or :hover), :insensitive, :selected, :focused and :inconsistent. </para> <example> <title>Styling specific widget states</title> <programlisting language="text"> /&ast; Theme active (pressed) buttons &ast;/ GtkButton:active { } /&ast; Theme buttons with the mouse pointer on it, both are equivalent &ast;/ GtkButton:hover, GtkButton:prelight { } /&ast; Theme insensitive widgets, both are equivalent &ast;/ :insensitive, *:insensitive { } /&ast; Theme selection colors in entries &ast;/ GtkEntry:selected { } /&ast; Theme focused labels &ast;/ GtkLabel:focused { } /&ast; Theme inconsistent checkbuttons &ast;/ GtkCheckButton:inconsistent { } </programlisting> </example> <para> Widget state pseudoclasses may only apply to the last element in a selector. </para> <para> To determine the effective style for a widget, all the matching rule sets are merged. As in CSS, rules apply by specificity, so the rules whose selectors more closely match a widget path will take precedence over the others. </para> </refsect2> <refsect2 id="gtkcssprovider-rules"> <title>&commat; Rules</title> <para> GTK+'s CSS supports the &commat;import rule, in order to load another CSS style sheet in addition to the currently parsed one. </para> <example> <title>Using the &commat;import rule</title> <programlisting language="text"> &commat;import url ("path/to/common.css"); </programlisting> </example> <para id="css-binding-set"> In order to extend key bindings affecting different widgets, GTK+ supports the &commat;binding-set rule to parse a set of bind/unbind directives, see #GtkBindingSet for the supported syntax. Note that the binding sets defined in this way must be associated with rule sets by setting the gtk-key-bindings style property. </para> <para> Customized key bindings are typically defined in a separate <filename>gtk-keys.css</filename> CSS file and GTK+ loads this file according to the current key theme, which is defined by the #GtkSettings:gtk-key-theme-name setting. </para> <example> <title>Using the &commat;binding rule</title> <programlisting language="text"> &commat;binding-set binding-set1 { bind "&lt;alt&gt;Left" { "move-cursor" (visual-positions, -3, 0) }; unbind "End"; }; &commat;binding-set binding-set2 { bind "&lt;alt&gt;Right" { "move-cursor" (visual-positions, 3, 0) }; bind "&lt;alt&gt;KP_space" { "delete-from-cursor" (whitespace, 1) "insert-at-cursor" (" ") }; }; GtkEntry { } </programlisting> </example> <para> GTK+ also supports an additional &commat;define-color rule, in order to define a color name which may be used instead of color numeric representations. Also see the #GtkSettings:gtk-color-scheme setting for a way to override the values of these named colors. </para> <example> <title>Defining colors</title> <programlisting language="text"> &commat;define-color bg_color &num;f9a039; &ast; { } </programlisting> </example> </refsect2> <refsect2 id="gtkcssprovider-symbolic-colors"> <title>Symbolic colors</title> <para> Besides being able to define color names, the CSS parser is also able to read different color expressions, which can also be nested, providing a rich language to define colors which are derived from a set of base colors. </para> <example> <title>Using symbolic colors</title> <programlisting language="text"> &commat;define-color entry-color shade (&commat;bg_color, 0.7); GtkEntry { } GtkEntry:focused { shade (&num;fff, 0.5), 0.8); } </programlisting> </example> <para> The various ways to express colors in GTK+ CSS are: </para> <informaltable> <tgroup cols="3"> <thead> <row> <entry>Syntax</entry> <entry>Explanation</entry> <entry>Examples</entry> </row> </thead> <tbody> <row> <entry>rgb(@r, @g, @b)</entry> <entry>An opaque color; @r, @g, @b can be either integers between 0 and 255 or percentages</entry> <entry><literallayout>rgb(128, 10, 54) rgb(20%, 30%, 0%)</literallayout></entry> </row> <row> <entry>rgba(@r, @g, @b, @a)</entry> <entry>A translucent color; @r, @g, @b are as in the previous row, <entry><literallayout>rgba(255, 255, 0, 0.5)</literallayout></entry> </row> <row> <entry>&num;@xxyyzz</entry> <entry>An opaque color; @xx, @yy, @zz are hexadecimal numbers specifying @r, @g, @b variants with between 1 and 4 hexadecimal digits per component are allowed</entry> <entry><literallayout>&num;ff12ab &num;f0c</literallayout></entry> </row> <row> <entry>&commat;name</entry> <entry>Reference to a color that has been defined with &commat;define-color </entry> <entry>&commat;bg_color</entry> </row> <row> <entry>mix(@color1, @color2, @f)</entry> <entry>A linear combination of @color1 and @color2. @f is a floating point number between 0 and 1.</entry> <entry><literallayout>mix(&num;ff1e0a, &commat;bg_color, 0.8)</literallayout></entry> </row> <row> <entry>shade(@color, @f)</entry> <entry>A lighter or darker variant of @color. @f is a floating point number. </entry> <entry>shade(&commat;fg_color, 0.5)</entry> </row> <row> <entry>lighter(@color)</entry> <entry>A lighter variant of @color</entry> </row> <row> <entry>darker(@color)</entry> <entry>A darker variant of @color</entry> </row> </tbody> </tgroup> </informaltable> </refsect2> <refsect2 id="gtkcssprovider-gradients"> <title>Gradients</title> <para> Linear or radial Gradients can be used as background images. </para> <para> A linear gradient along the line from (@start_x, @start_y) to (@end_x, @end_y) is specified using the syntax <literallayout>-gtk-gradient (linear, color-stop (@position, @color), ...)</literallayout> where @start_x and @end_x can be either a floating point number between 0 and 1 or one of the special values 'left', 'right' or 'center', @start_y and @end_y can be either a floating point number between 0 and 1 or one of the special values 'top', 'bottom' or 'center', @position is a floating point number between 0 and 1 and @color is a color expression (see above). The color-stop can be repeated multiple times to add more than one color stop. 'from (@color)' and 'to (@color)' can be used as abbreviations for color stops with position 0 and 1, respectively. </para> <example> <title>A linear gradient</title> <inlinegraphic fileref="gradient1.png" format="PNG"/> <para>This gradient was specified with <literallayout>-gtk-gradient (linear, left top, right bottom, from(&commat;yellow), to(&commat;blue))</literallayout></para> </example> <example> <title>Another linear gradient</title> <inlinegraphic fileref="gradient2.png" format="PNG"/> <para>This gradient was specified with <literallayout>-gtk-gradient (linear, 0 0, 0 1, color-stop(0, &commat;yellow), color-stop(0.2, &commat;blue), color-stop(1, &num;0f0))</literallayout></para> </example> <para> A radial gradient along the two circles defined by (@start_x, @start_y, syntax <literallayout>-gtk-gradient (radial, color-stop (@position, @color), ...)</literallayout> where @start_radius and @end_radius are floating point numbers and the other parameters are as before. </para> <example> <title>A radial gradient</title> <inlinegraphic fileref="gradient3.png" format="PNG"/> <para>This gradient was specified with <literallayout>-gtk-gradient (radial, center center, 0, center center, 1, from(&commat;yellow), to(&commat;green))</literallayout></para> </example> <example> <title>Another radial gradient</title> <inlinegraphic fileref="gradient4.png" format="PNG"/> <para>This gradient was specified with <literallayout>-gtk-gradient (radial, 0.4 0.4, 0.1, 0.6 0.6, 0.7, color-stop (0, &num;f00), color-stop (0.1, &num;a0f), color-stop (0.2, &commat;yellow), color-stop (1, &commat;green))</literallayout></para> </example> </refsect2> <refsect2 id="gtkcssprovider-slices"> <title>Border images</title> <para> Images can be used in 'slices' for the purpose of creating scalable borders. </para> <inlinegraphic fileref="slices.png" format="PNG"/> <para> The syntax for specifying border images of this kind is: <literallayout>url(@path) @top @right @bottom @left [repeat|stretch]? [repeat|stretch]?</literallayout> The sizes of the 'cut off' portions are specified with the @top, @right, @bottom and @left parameters. The 'middle' sections can be repeated or stretched to create the desired effect, by adding the 'repeat' or 'stretch' options after the dimensions. If two options are specified, the first one affects the horizontal behaviour and the second one the vertical behaviour. If only one option is specified, it affects both. </para> <example> <title>A border image</title> <inlinegraphic fileref="border1.png" format="PNG"/> <para>This border image was specified with <literallayout>url("gradient1.png") 10 10 10 10</literallayout> </para> </example> <example> <title>A repeating border image</title> <inlinegraphic fileref="border2.png" format="PNG"/> <para>This border image was specified with <literallayout>url("gradient1.png") 10 10 10 10 repeat</literallayout> </para> </example> <example> <title>A stretched border image</title> <inlinegraphic fileref="border3.png" format="PNG"/> <para>This border image was specified with <literallayout>url("gradient1.png") 10 10 10 10 stretch</literallayout> </para> </example> </refsect2> <refsect2 id="gtkcssprovider-transitions"> <para>Styles can specify transitions that will be used to create a gradual change in the appearance when a widget state changes. The following syntax is used to specify transitions: <literallayout>@duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]?</literallayout> The @duration is the amount of time that the animation will take for a complete cycle from start to end. If the loop option is given, the animation will be repated until the state changes again. The option after the duration determines the transition function from a small set of predefined functions. <figure><title>Linear transition</title> <graphic fileref="linear.png" format="PNG"/> </figure> <figure><title>Ease transition</title> <graphic fileref="ease.png" format="PNG"/> </figure> <figure><title>Ease-in-out transition</title> <graphic fileref="ease-in-out.png" format="PNG"/> </figure> <figure><title>Ease-in transition</title> <graphic fileref="ease-in.png" format="PNG"/> </figure> <figure><title>Ease-out transition</title> <graphic fileref="ease-out.png" format="PNG"/> </figure> </para> </refsect2> <refsect2 id="gtkcssprovider-properties"> <title>Supported properties</title> <para> Properties are the part that differ the most to common CSS, not all properties are supported (some are planned to be supported eventually, some others are meaningless or don't map intuitively in a widget based environment). </para> <para> There is also a difference in shorthand properties, for example in common CSS it is fine to define a font through the different @font-family, @font-style, @font-size properties, meanwhile in GTK+'s CSS only the canonical </para> <para> The currently supported properties are: </para> <informaltable> <tgroup cols="4"> <thead> <row> <entry>Property name</entry> <entry>Syntax</entry> <entry>Maps to</entry> <entry>Examples</entry> </row> </thead> <tbody> <row> <entry>engine</entry> <entry>engine-name</entry> <entry>#GtkThemingEngine</entry> <entry>engine: clearlooks; </row> <row> <entry>background-color</entry> <entry morerows="2">color (see above)</entry> <entry morerows="2">#GdkRGBA</entry> <entry morerows="2"><literallayout>background-color: &num;fff; </entry> </row> <row> <entry>color</entry> </row> <row> <entry>border-color</entry> </row> <row> <entry>font</entry> <entry>@family [@style] [@size]</entry> <entry>#PangoFontDescription</entry> <entry>font: Sans 15;</entry> </row> <row> <entry>margin</entry> <entry morerows="1"><literallayout>@width </entry> <entry morerows="1">#GtkBorder</entry> <entry morerows="1"><literallayout>margin: 5; </entry> </row> <row> <entry>padding</entry> </row> <row> <entry>background-image</entry> <entry><literallayout>gradient (see above) or url(@path)</literallayout></entry> <entry>#cairo_pattern_t</entry> <entry><literallayout>-gtk-gradient (linear, left top, right top, from (&num;fff), to (&num;000)); -gtk-gradient (linear, 0.0 0.5, 0.5 1.0, from (&num;fff), color-stop (0.5, &num;f00), to (&num;000)); -gtk-gradient (radial, center center, 0.2, center center, 0.8, color-stop (0.0, &num;fff), color-stop (1.0, &num;000)); url ('background.png');</literallayout> </entry> </row> <row> <entry>border-width</entry> <entry>integer</entry> <entry>#gint</entry> <entry>border-width: 5;</entry> </row> <row> <entry>border-radius</entry> <entry>integer</entry> <entry>#gint</entry> <entry>border-radius: 5;</entry> </row> <row> <entry>border-style</entry> <entry>[none|solid|inset|outset]</entry> <entry>#GtkBorderStyle</entry> <entry>border-style: solid;</entry> </row> <row> <entry>border-image</entry> <entry><literallayout>border image (see above)</literallayout></entry> <entry>internal use only</entry> <entry><literallayout>border-image: url("/path/to/image.png") 3 4 3 4 stretch; </entry> </row> <row> <entry>transition</entry> <entry>transition (see above)</entry> <entry>internal use only</entry> <entry><literallayout>transition: 150ms ease-in-out; </entry> </row> <row> <entry>gtk-key-bindings</entry> <entry>binding set name list</entry> <entry>internal use only</entry> <entry><literallayout>gtk-bindings: binding1, binding2, ...;</literallayout> </entry> </row> </tbody> </tgroup> </informaltable> <para> GtkThemingEngines can register their own, engine-specific style properties with the function gtk_theming_engine_register_property(). These properties can be set in CSS like other properties, using a name of the form <literallayout>-<replaceable>namespace</replaceable>-<replaceable>name</replaceable></literallayout>, where <replaceable>namespace</replaceable> is typically the name of the theming engine, and <replaceable>name</replaceable> is the name of the property. Style properties that have been registered by widgets using gtk_widget_class_install_style_property() can also be set in this way, using the widget class name for <replaceable>namespace</replaceable>. </para> <example> <title>Using engine-specific style properties</title> <programlisting> * { -GtkPaned-handle-size: 6; -clearlooks-colorize-scrollbar: false; } </programlisting> </example> </refsect2>

Implements: Gtk.Buildable, Atk.ImplementorIface

Known subclasses: Gtk.RecentChooserDialog, Gtk.ColorSelectionDialog, Gtk.AboutDialog, Gtk.FontSelectionDialog, Gtk.MessageDialog, Gtk.FileChooserDialog, Gtk.AppChooserDialog

Subclass of: Gtk.Window

Dialog boxes are a convenient way to prompt the user for a small amount of input, e.g. to display a message, ask a question, or anything else that does not require extensive effort on the user's part. GTK+ treats a dialog as a window split vertically. The top section is a #GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should be packed. The bottom area is known as the <structfield>action_area</structfield>. This is generally used for packing buttons into the dialog which may perform functions such as cancel, ok, or apply. #GtkDialog boxes are created with a call to gtk_dialog_new() or gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is recommended; it allows you to set the dialog title, some convenient flags, and add simple buttons. If 'dialog' is a newly created dialog, the two primary areas of the window can be accessed through gtk_dialog_get_content_area() and gtk_dialog_get_action_area(), as can be seen from the example below. A 'modal' dialog (that is, one which freezes the rest of the application from user input), can be created by calling gtk_window_set_modal() on the dialog. Use the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a #GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the #GTK_DIALOG_MODAL flag to make a dialog modal. If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(), gtk_dialog_add_button(), gtk_dialog_add_buttons(), or gtk_dialog_add_action_widget(), clicking the button will emit a signal called #GtkDialog::response with a response ID that you specified. GTK+ will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the #GtkResponseType enumeration (these all have values less than zero). If a dialog receives a delete event, the #GtkDialog::response signal will be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT. If you want to block waiting for a dialog to return before returning control flow to your code, you can call gtk_dialog_run(). This function enters a recursive main loop and waits for the user to respond to the dialog, returning the response ID corresponding to the button the user clicked. For the simple dialog in the following example, in reality you'd probably use #GtkMessageDialog to save yourself some effort. But you'd need to create the dialog contents manually if you had more than a simple message in the dialog. <example> <title>Simple GtkDialog usage</title> <programlisting> /&ast; Function to open a dialog box displaying the message provided. &ast;/ void quick_message (gchar *message) { GtkWidget *dialog, *label, *content_area; /&ast; Create the widgets &ast;/ dialog = gtk_dialog_new_with_buttons ("Message", main_application_window, GTK_DIALOG_DESTROY_WITH_PARENT, GTK_STOCK_OK, GTK_RESPONSE_NONE, NULL); content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog)); label = gtk_label_new (message); /&ast; Ensure that the dialog box is destroyed when the user responds &ast;/ g_signal_connect_swapped (dialog, "response", G_CALLBACK (gtk_widget_destroy), dialog); /&ast; Add the label, and show everything we've added to the dialog &ast;/ gtk_container_add (GTK_CONTAINER (content_area), label); gtk_widget_show_all (dialog); } </programlisting> </example> <refsect2 id="GtkDialog-BUILDER-UI"><title>GtkDialog as GtkBuildable</title> <para> The GtkDialog implementation of the #GtkBuildable interface exposes the "action_area". </para> <para> GtkDialog supports a custom &lt;action-widgets&gt; element, which can contain multiple &lt;action-widget&gt; elements. The "response" attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs @action_area). </para> <example> <title>A <structname>GtkDialog</structname> UI definition fragment.</title> <programlisting><![CDATA[ <object class="GtkDialog" id="dialog1"> <child internal-child="vbox">" <object class="GtkVBox" id="vbox"> <child internal-child="action_area"> <object class="GtkHButtonBox" id="button_box"> <child> <object class="GtkButton" id="button_cancel"/> </child> <child> <object class="GtkButton" id="button_ok"/> </child> </object> </child> </object> </child> <action-widgets> <action-widget response="3">button_ok</action-widget> <action-widget response="-5">button_cancel</action-widget> </action-widgets> </object> ]]></programlisting> </example> </refsect2>

Implements: Gtk.Buildable, Atk.ImplementorIface

Subclass of: Gtk.Widget

The #GtkDrawingArea widget is used for creating custom user interface elements. It's essentially a blank widget; you can draw on it. After creating a drawing area, the application may want to connect to: <itemizedlist> <listitem> <para> Mouse and button press signals to respond to input from the user. (Use gtk_widget_add_events() to enable events you wish to receive.) </para> </listitem> <listitem> <para> The #GtkWidget::realize signal to take any necessary actions when the widget is instantiated on a particular display. (Create GDK resources in response to this signal.) </para> </listitem> <listitem> <para> The #GtkWidget::configure-event signal to take any necessary actions when the widget changes size. </para> </listitem> <listitem> <para> The #GtkWidget::draw signal to handle redrawing the contents of the widget. </para> </listitem> </itemizedlist> The following code portion demonstrates using a drawing area to display a circle in the normal widget foreground color. Note that GDK automatically clears the exposed area to the background color before sending the expose event, and that drawing is implicitly clipped to the exposed area. <example> <title>Simple GtkDrawingArea usage</title> <programlisting> gboolean draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data) { guint width, height; GdkRGBA color; width = gtk_widget_get_allocated_width (widget); height = gtk_widget_get_allocated_height (widget); cairo_arc (cr, width / 2.0, height / 2.0, MIN (width, height) / 2.0, 0, 2 * G_PI); gtk_style_context_get_color (gtk_widget_get_style_context (widget), 0, &amp;color); gdk_cairo_set_source_rgba (cr, &amp;color); cairo_fill (cr); return FALSE; } [...] GtkWidget &ast;drawing_area = gtk_drawing_area_new (<!-- -->); gtk_widget_set_size_request (drawing_area, 100, 100); g_signal_connect (G_OBJECT (drawing_area), "draw", G_CALLBACK (draw_callback), NULL); </programlisting> </example> Draw signals are normally delivered when a drawing area first comes onscreen, or when it's covered by another window and then uncovered. You can also force an expose event by adding to the "damage region" of the drawing area's window; gtk_widget_queue_draw_area() and gdk_window_invalidate_rect() are equally good ways to do this. You'll then get a draw signal for the invalid region. The available routines for drawing are documented on the <link linkend="gdk3-Cairo-Interaction">GDK Drawing Primitives</link> page and the cairo documentation. To receive mouse events on a drawing area, you will need to enable them with gtk_widget_add_events(). To receive keyboard events, you will need to set the "can-focus" property on the drawing area, and you should probably draw some user-visible indication that the drawing area is focused. Use gtk_widget_has_focus() in your expose event handler to decide whether to draw the focus indicator. See gtk_render_focus() for one way to draw focus.

Implements: Gtk.Buildable, Gtk.Editable, Gtk.CellEditable, Atk.ImplementorIface

Known subclasses: Gtk.SpinButton

Subclass of: Gtk.Widget

The #GtkEntry widget is a single line text entry widget. A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation of the widget, the widget will scroll so that the cursor position is visible. When using an entry for passwords and other sensitive information, it can be put into "password mode" using gtk_entry_set_visibility(). In this mode, entered text is displayed using a 'invisible' character. By default, GTK+ picks the best invisible character that is available in the current font, but it can be changed with gtk_entry_set_invisible_char(). Since 2.16, GTK+ displays a warning when Caps Lock or input methods might interfere with entering text in a password entry. The warning can be turned off with the #GtkEntry:caps-lock-warning property. Since 2.16, GtkEntry has the ability to display progress or activity information behind the text. To make an entry display such information, use gtk_entry_set_progress_fraction() or gtk_entry_set_progress_pulse_step(). Additionally, GtkEntry can show icons at either side of the entry. These icons can be activatable by clicking, can be set up as drag source and can have tooltips. To add an icon, use gtk_entry_set_icon_from_gicon() or one of the various other functions that set an icon from a stock id, an icon name or a pixbuf. To trigger an action when the user clicks an icon, connect to the #GtkEntry::icon-press signal. To allow DND operations from an icon, use gtk_entry_set_icon_drag_source(). To set a tooltip on an icon, use gtk_entry_set_icon_tooltip_text() or the corresponding function for markup. Note that functionality or information that is only available by clicking on an icon in an entry may not be accessible at all to users which are not able to use a mouse or other pointing device. It is therefore recommended that any such functionality should also be available by other means, e.g. via the context menu of the entry.

Subclass of: GObject.Object

The #GtkEntryBuffer class contains the actual text displayed in a #GtkEntry widget. A single #GtkEntryBuffer object can be shared by multiple #GtkEntry widgets which will then share the same text content, but not the cursor position, visibility attributes, icon etc. #GtkEntryBuffer may be derived from. Such a derived class might allow text to be stored in an alternate location, such as non-pageable memory, useful in the case of important passwords. Or a derived class could integrate with an application's concept of undo/redo.

Implements: Gtk.CellLayout, Gtk.Buildable

Subclass of: GObject.Object

#GtkEntryCompletion is an auxiliary object to be used in conjunction with #GtkEntry to provide the completion functionality. It implements the #GtkCellLayout interface, to allow the user to add extra cells to the #GtkTreeView with completion matches. "Completion functionality" means that when the user modifies the text in the entry, #GtkEntryCompletion checks which rows in the model match the current content of the entry, and displays a list of matches. By default, the matching is done by comparing the entry text case-insensitively against the text column of the model (see gtk_entry_completion_set_text_column()), but this can be overridden with a custom match function (see gtk_entry_completion_set_match_func()). When the user selects a completion, the content of the entry is updated. By default, the content of the entry is replaced by the text column of the model, but this can be overridden by connecting to the #GtkEntryCompletion::match-selected signal and updating the entry in the signal handler. Note that you should return %TRUE from the signal handler to suppress the default behaviour. To add completion functionality to an entry, use gtk_entry_set_completion(). In addition to regular completion matches, which will be inserted into the entry when they are selected, #GtkEntryCompletion also allows to display "actions" in the popup window. Their appearance is similar to menuitems, to differentiate them clearly from completion strings. When an action is selected, the #GtkEntryCompletion::action-activated signal is emitted. GtkEntryCompletion uses a #GtkTreeModelFilter model to represent the subset of the entire model that is currently matching. While the GtkEntryCompletion signals #GtkEntryCompletion::match-selected and #GtkEntryCompletion::cursor-on-match take the original model and an iter pointing to that model as arguments, other callbacks and signals (such as #GtkCellLayoutDataFuncs or #GtkCellArea::apply-attributes) will generally take the filter model as argument. As long as you are only calling gtk_tree_model_get(), this will make no difference to you. If for some reason, you need the original model, use gtk_tree_model_filter_get_model(). Don't forget to use gtk_tree_model_filter_convert_iter_to_child_iter() to obtain a matching iter.