diff options
| author | Matthias Clasen <matthiasc@src.gnome.org> | 2007-07-01 23:38:07 +0000 |
|---|---|---|
| committer | Matthias Clasen <matthiasc@src.gnome.org> | 2007-07-01 23:38:07 +0000 |
| commit | e5ce8697ea29c41c872cbf16620807eb6df66095 (patch) | |
| tree | 89a776f3ff15c054a2b4308662e2f7c1646307aa | |
| parent | a49af564186aeca76d09ceca0058917c9a70531d (diff) | |
| download | gdk-pixbuf-e5ce8697ea29c41c872cbf16620807eb6df66095.tar.gz | |
Document GtkBuilder UI definitions
svn path=/trunk/; revision=18332
26 files changed, 597 insertions, 223 deletions
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index cd322e684..031c53d19 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2007-07-01 Matthias Clasen <mclasen@redhat.com> + + * gtk/tmpl/*.sgml: Document GtkBuilder ui definitions. + 2007-07-01 Johan Dahlin <jdahlin@async.com.br> * gtk/gtk-builder-convert.xml: Updates diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml index 7810f5017..1f65c9c5b 100644 --- a/docs/reference/gtk/tmpl/gtk-unused.sgml +++ b/docs/reference/gtk/tmpl/gtk-unused.sgml @@ -913,78 +913,12 @@ You may not attach these to signals created with the </para> -<!-- ##### ARG GtkFileChooser:action ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkFileChooser:do-overwrite-confirmation ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkFileChooser:extra-widget ##### --> -<para> - -</para> - - <!-- ##### ARG GtkFileChooser:file-system ##### --> <para> </para> -<!-- ##### ARG GtkFileChooser:file-system-backend ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkFileChooser:filter ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkFileChooser:local-only ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkFileChooser:preview-widget ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkFileChooser:preview-widget-active ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkFileChooser:select-multiple ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkFileChooser:show-hidden ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkFileChooser:use-preview-label ##### --> -<para> - -</para> - - <!-- ##### ENUM GtkFontFilterType ##### --> <para> A set of bit flags used to specify the filter being set @@ -1266,66 +1200,6 @@ after other user handlers and the default handler. </para> -<!-- ##### ARG GtkRecentChooser:filter ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkRecentChooser:limit ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkRecentChooser:local-only ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkRecentChooser:recent-manager ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkRecentChooser:select-multiple ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkRecentChooser:show-icons ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkRecentChooser:show-not-found ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkRecentChooser:show-private ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkRecentChooser:show-tips ##### --> -<para> - -</para> - - -<!-- ##### ARG GtkRecentChooser:sort-type ##### --> -<para> - -</para> - - <!-- ##### ARG GtkScrolledWindow:shadow ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkactiongroup.sgml b/docs/reference/gtk/tmpl/gtkactiongroup.sgml index 8f363a0fe..bed93558a 100644 --- a/docs/reference/gtk/tmpl/gtkactiongroup.sgml +++ b/docs/reference/gtk/tmpl/gtkactiongroup.sgml @@ -28,6 +28,18 @@ toolitems take on this accelerator path. The GTK+ accelerator map code makes sure that the correct shortcut is displayed next to the menu item. </para> +<refsect2 id="GtkActionGroup-BUILDER-UI"> +<title>GtkActionGroup as GtkBuildable</title> +<para> +The GtkActionGroup implementation of the GtkBuildable interface accepts +GtkAction objects as <child> elements in UI definitions. +</para> +<para> +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. +</para> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkbuilder.sgml b/docs/reference/gtk/tmpl/gtkbuilder.sgml index a882e3dcc..6050b877f 100644 --- a/docs/reference/gtk/tmpl/gtkbuilder.sgml +++ b/docs/reference/gtk/tmpl/gtkbuilder.sgml @@ -87,11 +87,24 @@ which are more limited in scope. <para> Beyond this general structure, several object classes define their own XML DTD fragments for filling in the ANY placeholders. -See +These are explained in their own sections, see +<link linkend="GtkWidget-BUILDER-UI">GtkWidget</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="GtkComboBoxEntry-BUILDER-UI">GtkComboBoxEntry</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>. </para> -<simplelist> - <member><link linkend="GtkDialog-BUILDER-UI">GtkDialog as GtkBuildable</link></member> -</simplelist> </refsect2> <!-- ##### SECTION See_Also ##### --> diff --git a/docs/reference/gtk/tmpl/gtkcelllayout.sgml b/docs/reference/gtk/tmpl/gtkcelllayout.sgml index b5ebf6fb1..4cc7ea12f 100644 --- a/docs/reference/gtk/tmpl/gtkcelllayout.sgml +++ b/docs/reference/gtk/tmpl/gtkcelllayout.sgml @@ -23,6 +23,33 @@ gtk_cell_layout_set_cell_data_func() that is called to determine the value of the attribute for each cell that is rendered. </para> +<refsect2 id="GtkCellLayout-BUILDER-UI"> +<title>GtkCellLayouts as GtkBuildable</title> +<para> +Implementations of GtkCellLayout which also implement the GtkBuildable +interface (#GtkCellView, #GtkIconView, #GtkComboBox, #GtkComboBoxEntry, +#GtkEntryCompletion, #GtkTreeViewColumn) accept GtkCellRenderer objects +as <child> elements in UI definitons. They support a custom +<attributes> element for their children, which can contain +multiple <attribute> elements. Each <attribute> element has +a name attribute which specifies a property of the cell renderer; the +content of the element is the attribute value. +</para> +<example> +<title>A UI definition fragment specifying attributes</title> +<programlisting><![CDATA[ +<object class="GtkCellView"> + <child> + <object class="GtkCellRendererText"/> + <attributes> + <attribute name="text">0</attribute> + </attributes> + </child>" +</object> +]]></programlisting> +</example> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml b/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml index 8ed57f505..72cd0ba11 100644 --- a/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml +++ b/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml @@ -11,6 +11,16 @@ allows the user to select a color much like the #GtkFileSelection provides a standard dialog for file selection. </para> +<refsect2 id="GtkColorSelectionDialog-BUILDER-UI"> +<title>GtkColorSelectionDialog as GtkBuildable</title> +<para> +The GtkColorSelectionDialog implementation of the GtkBuildable interface +exposes the embedded #GtkColorSelection as internal child with the +name "color_selection". It also exposes the buttons with the names +"ok_button", "cancel_button" and "help_button". +</para> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkcomboboxentry.sgml b/docs/reference/gtk/tmpl/gtkcomboboxentry.sgml index a5d364649..04d3a6379 100644 --- a/docs/reference/gtk/tmpl/gtkcomboboxentry.sgml +++ b/docs/reference/gtk/tmpl/gtkcomboboxentry.sgml @@ -43,6 +43,16 @@ it is possible to replace the child entry by a different widget using gtk_container_remove() and gtk_container_add(). </para> +<refsect2 id="GtkComboBoxEntry-BUILDER-UI"> +<title>GtkComboBoxEntry as GtkBuildable</title> +<para> +Beyond the <attributes> support that is shared by all +<link linkend="GtkCellLayout-BUILDER-UI">GtkCellLayout</link> implementation, +GtkComboBoxEntry makes the entry available in UI definitions as an internal +child with name "entry". +</para> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> #GtkComboBox diff --git a/docs/reference/gtk/tmpl/gtkcontainer.sgml b/docs/reference/gtk/tmpl/gtkcontainer.sgml index 8b3df0e60..3646fa7fc 100644 --- a/docs/reference/gtk/tmpl/gtkcontainer.sgml +++ b/docs/reference/gtk/tmpl/gtkcontainer.sgml @@ -6,66 +6,79 @@ Base class for widgets which contain other widgets <!-- ##### SECTION Long_Description ##### --> <para> -A GTK+ user interface is constructed by nesting widgets inside widgets. Container widgets are the inner -nodes in the resulting tree of widgets: they contain other widgets. So, for example, you might have a -#GtkWindow containing a #GtkFrame containing a GtkLabel. If you wanted an image instead of a textual label -inside the frame, you might replace the #GtkLabel widget with a #GtkImage widget. +A GTK+ user interface is constructed by nesting widgets inside widgets. +Container widgets are the inner nodes in the resulting tree of widgets: +they contain other widgets. So, for example, you might have a #GtkWindow +containing a #GtkFrame containing a GtkLabel. If you wanted an image instead +of a textual label inside the frame, you might replace the #GtkLabel widget +with a #GtkImage widget. </para> <para> -There are two major kinds of container widgets in GTK+. Both are subclasses of the abstract #GtkContainer -base class. +There are two major kinds of container widgets in GTK+. Both are subclasses +of the abstract #GtkContainer base class. </para> <para> -The first type of container widget has a single child widget and derives from #GtkBin. These containers -are <firstterm>decorators</firstterm>, which add some kind of functionality to the child. For example, -a #GtkButton makes its child into a clickable button; a #GtkFrame draws a frame around its child and -a #GtkWindow places its child widget inside a top-level window. +The first type of container widget has a single child widget and derives +from #GtkBin. These containers are <firstterm>decorators</firstterm>, which +add some kind of functionality to the child. For example, a #GtkButton makes +its child into a clickable button; a #GtkFrame draws a frame around its child +and a #GtkWindow places its child widget inside a top-level window. </para> <para> -The second type of container can have more than one child; its purpose is to manage -<firstterm>layout</firstterm>. This means that these containers assign sizes and positions to their children. -For example, a #GtkHBox arranges its children in a horizontal row, and a #GtkTable arranges the widgets it -contains in a two-dimensional grid. +The second type of container can have more than one child; its purpose is to +manage <firstterm>layout</firstterm>. This means that these containers assign +sizes and positions to their children. For example, a #GtkHBox arranges its +children in a horizontal row, and a #GtkTable arranges the widgets it contains +in a two-dimensional grid. </para> <para> -To fulfill its task, a layout container must negotiate the size requirements with its parent and its children. -This negotiation is carried out in two phases, <firstterm>size requisition</firstterm> and -<firstterm>size allocation</firstterm>. +To fulfill its task, a layout container must negotiate the size requirements +with its parent and its children. This negotiation is carried out in two +phases, <firstterm>size requisition</firstterm> and <firstterm>size +allocation</firstterm>. </para> <refsect2 id="size-requisition"><title>Size Requisition</title> <para> -The size requisition of a widget is it's desired width and height. This is represented by a #GtkRequisition. +The size requisition of a widget is it's desired width and height. +This is represented by a #GtkRequisition. </para> <para> -How a widget determines its desired size depends on the widget. A #GtkLabel, for example, requests enough space -to display all its text. Container widgets generally base their size request on the requisitions of their -children. +How a widget determines its desired size depends on the widget. +A #GtkLabel, for example, requests enough space to display all its text. +Container widgets generally base their size request on the requisitions +of their children. </para> <para> -The size requisition phase of the widget layout process operates top-down. It starts at a top-level widget, -typically a #GtkWindow. The top-level widget asks its child for its size requisition by calling -gtk_widget_size_request(). To determine its requisition, the child asks its own children for their requisitions -and so on. Finally, the top-level widget will get a requisition back from its child. +The size requisition phase of the widget layout process operates top-down. +It starts at a top-level widget, typically a #GtkWindow. The top-level widget +asks its child for its size requisition by calling gtk_widget_size_request(). +To determine its requisition, the child asks its own children for their +requisitions and so on. Finally, the top-level widget will get a requisition +back from its child. </para> </refsect2> <refsect2 id="size-allocation"><title>Size Allocation</title> <para> -When the top-level widget has determined how much space its child would like to have, the second phase of the -size negotiation, size allocation, begins. Depending on its configuration (see gtk_window_set_resizable()), the -top-level widget may be able to expand in order to satisfy the size request or it may have to ignore the size -request and keep its fixed size. It then tells its child widget how much space it gets by calling -gtk_widget_size_allocate(). The child widget divides the space among its children and tells each child how much -space it got, and so on. Under normal circumstances, a #GtkWindow will always give its child the amount of space -the child requested. +When the top-level widget has determined how much space its child would like +to have, the second phase of the size negotiation, size allocation, begins. +Depending on its configuration (see gtk_window_set_resizable()), the top-level +widget may be able to expand in order to satisfy the size request or it may +have to ignore the size request and keep its fixed size. It then tells its +child widget how much space it gets by calling gtk_widget_size_allocate(). +The child widget divides the space among its children and tells each child +how much space it got, and so on. Under normal circumstances, a #GtkWindow +will always give its child the amount of space the child requested. </para> <para> -A child's size allocation is represented by a #GtkAllocation. This struct contains not only a width and height, -but also a position (i.e. X and Y coordinates), so that containers can tell their children not only how much -space they have gotten, but also where they are positioned inside the space available to the container. +A child's size allocation is represented by a #GtkAllocation. This struct +contains not only a width and height, but also a position (i.e. X and Y +coordinates), so that containers can tell their children not only how much +space they have gotten, but also where they are positioned inside the space +available to the container. </para> <para> -Widgets are required to honor the size allocation they receive; a size request is only a request, and widgets -must be able to cope with any size. +Widgets are required to honor the size allocation they receive; a size +request is only a request, and widgets must be able to cope with any size. </para> </refsect2> <refsect2 id="child-properties"><title>Child properties</title> @@ -91,6 +104,29 @@ changes, use gtk_widget_child_notify(). </para> </refsect2> +<refsect2 id="GtkContainer-BUILDER-UI"> +<title>GtkContainer as GtkBuildable</title> +<para> +The GtkContainer implementation of the GtkBuildable interface +supports a <packing> element for children, which can +contain multiple <property> elements that specify +child properties for the child. +</para> +<example> +<title>Child properties in UI definitions</title> +<programlisting><![CDATA[ +<object class="GtkVBox"> + <child> + <object class="GtkLabel"/> + <packing> + <property name="pack-type">start</property> + </packing> + </child> +</object> +]]></programlisting> +</example> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkdialog.sgml b/docs/reference/gtk/tmpl/gtkdialog.sgml index 73ed5cb86..d3e2b02e1 100644 --- a/docs/reference/gtk/tmpl/gtkdialog.sgml +++ b/docs/reference/gtk/tmpl/gtkdialog.sgml @@ -104,10 +104,11 @@ void quick_message (gchar *message) { </example> </para> -<refsect2><title>GtkDialog as a GtkBuildable</title> +<refsect2 id="GtkDialog-BUILDER-UI"><title>GtkDialog as GtkBuildable</title> <para> -GtkDialog exposes the @vbox and @action_area as internal children -with the names "vbox" and "action_area". +The GtkDialog implementation of the GtkBuildable interface exposes the +@vbox and @action_area as internal children with the names "vbox" and +"action_area". </para> <para> GtkDialog supports a custom <action-widgets> element, which diff --git a/docs/reference/gtk/tmpl/gtkexpander.sgml b/docs/reference/gtk/tmpl/gtkexpander.sgml index b23139f34..37482eb78 100644 --- a/docs/reference/gtk/tmpl/gtkexpander.sgml +++ b/docs/reference/gtk/tmpl/gtkexpander.sgml @@ -6,32 +6,31 @@ A container which can hide its child <!-- ##### SECTION Long_Description ##### --> <para> -A #GtkExpander allows the user to hide or show its child by clicking on an expander triangle similar to -the triangles used in a #GtkTreeView. -</para> - - <para> - Normally you use an expander as you would use any other descendant - of #GtkBin; you create the child widget and use - gtk_container_add() to add it to the expander. When the expander - is toggled, it will take care of showing and hiding the child - automatically. - </para> - - <section id="expander-special-usage"> - <title>Special Usage</title> - - <para> - There are situations in which you may prefer to show and - hide the expanded widget yourself, such as when you want to - actually create the widget at expansion time. In this case, - create a #GtkExpander but do not add a child to it. The - expander widget has an <literal>expanded</literal> property - which can be used to monitor its expansion state. You should - watch this property with a signal connection as follows: - </para> - - <programlisting id="expander-callback-example"> +A #GtkExpander allows the user to hide or show its child by clicking +on an expander triangle similar to the triangles used in a #GtkTreeView. +</para> + +<para> +Normally you use an expander as you would use any other descendant +of #GtkBin; you create the child widget and use gtk_container_add() +to add it to the expander. When the expander is toggled, it will take +care of showing and hiding the child automatically. +</para> + +<section id="expander-special-usage"> +<title>Special Usage</title> + +<para> +There are situations in which you may prefer to show and hide the +expanded widget yourself, such as when you want to actually create +the widget at expansion time. In this case, create a #GtkExpander +but do not add a child to it. The expander widget has an +<literal>expanded</literal> property which can be used to monitor +its expansion state. You should watch this property with a signal +connection as follows: +</para> + +<programlisting id="expander-callback-example"> expander = gtk_expander_new_with_mnemonic ("_More Options"); g_signal_connect (expander, "notify::expanded", G_CALLBACK (expander_callback), NULL); @@ -56,9 +55,29 @@ expander_callback (GObject *object, /* Hide or destroy widgets */ } } - - </programlisting> - </section> +</programlisting> +</section> +<refsect2 id="GtkExpander-BUILDER-UI"> +<title>GtkExpander as GtkBuildable</title> +<para> +The GtkExpander implementation of the GtkBuildable interface +supports placing a child in the label position by specifying +"label" as the "type" attribute of a <child> element. +</para> +<example> +<title>A UI definition fragment with GtkExpander</title> +<programlisting><![CDATA[ +<object class="GtkExpander"> + <child type="label"> + <object class="GtkLabel" id="expander-label"/> + </child> + <child> + <object class="GtkEntry" id="expander-content"/> + </child> +</object> +]]></programlisting> +</example> +</refsect2> <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkfilechooser.sgml b/docs/reference/gtk/tmpl/gtkfilechooser.sgml index ef7f17a2f..a24691a91 100644 --- a/docs/reference/gtk/tmpl/gtkfilechooser.sgml +++ b/docs/reference/gtk/tmpl/gtkfilechooser.sgml @@ -672,6 +672,61 @@ gtk_widget_destroy (chooser); @filechooser: the object which received the signal. +<!-- ##### ARG GtkFileChooser:action ##### --> +<para> + +</para> + +<!-- ##### ARG GtkFileChooser:do-overwrite-confirmation ##### --> +<para> + +</para> + +<!-- ##### ARG GtkFileChooser:extra-widget ##### --> +<para> + +</para> + +<!-- ##### ARG GtkFileChooser:file-system-backend ##### --> +<para> + +</para> + +<!-- ##### ARG GtkFileChooser:filter ##### --> +<para> + +</para> + +<!-- ##### ARG GtkFileChooser:local-only ##### --> +<para> + +</para> + +<!-- ##### ARG GtkFileChooser:preview-widget ##### --> +<para> + +</para> + +<!-- ##### ARG GtkFileChooser:preview-widget-active ##### --> +<para> + +</para> + +<!-- ##### ARG GtkFileChooser:select-multiple ##### --> +<para> + +</para> + +<!-- ##### ARG GtkFileChooser:show-hidden ##### --> +<para> + +</para> + +<!-- ##### ARG GtkFileChooser:use-preview-label ##### --> +<para> + +</para> + <!-- ##### ENUM GtkFileChooserAction ##### --> <para> Describes whether a #GtkFileChooser is being used to open diff --git a/docs/reference/gtk/tmpl/gtkfontseldlg.sgml b/docs/reference/gtk/tmpl/gtkfontseldlg.sgml index 9afe5f60d..f25b1a620 100644 --- a/docs/reference/gtk/tmpl/gtkfontseldlg.sgml +++ b/docs/reference/gtk/tmpl/gtkfontseldlg.sgml @@ -20,6 +20,16 @@ To change the text which is shown in the preview area, use gtk_font_selection_dialog_set_preview_text(). </para> +<refsect2 id="GtkFontSelectionDialog-BUILDER-UI"> +<title>GtkFontSelectionDialog as GtkBuildable</title> +<para> +The GtkFontSelectionDialog implementation of the GtkBuildable interface +exposes the embedded #GtkFontSelection as internal child with the +name "font_selection". It also exposes the buttons with the names +"ok_button", "cancel_button" and "apply_button". +</para> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> <variablelist> diff --git a/docs/reference/gtk/tmpl/gtkframe.sgml b/docs/reference/gtk/tmpl/gtkframe.sgml index 901c06e1f..8f2bb4f01 100644 --- a/docs/reference/gtk/tmpl/gtkframe.sgml +++ b/docs/reference/gtk/tmpl/gtkframe.sgml @@ -13,6 +13,29 @@ top side of the frame. The position of the label can be controlled with gtk_frame_set_label_align(). </para> +<refsect2 id="GtkFrame-BUILDER-UI"> +<title>GtkFrame as GtkBuildable</title> +<para> +The GtkFrame implementation of the GtkBuildable interface +supports placing a child in the label position by specifying +"label" as the "type" attribute of a <child> element. +</para> +<example> +<title>A UI definition fragment with GtkFrame</title> +<programlisting><![CDATA[ +<object class="GtkFrame"> + <child type="label"> + <object class="GtkLabel" id="frame-label"/> + </child> + <child> + <object class="GtkEntry" id="frame-content"/> + </child> +</object> +]]></programlisting> +</example> +</refsect2> + + <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkliststore.sgml b/docs/reference/gtk/tmpl/gtkliststore.sgml index b5b8a716d..3577740d4 100644 --- a/docs/reference/gtk/tmpl/gtkliststore.sgml +++ b/docs/reference/gtk/tmpl/gtkliststore.sgml @@ -93,18 +93,70 @@ run on older versions of GTK+, it is worth keeping the iter around. </para> <title>Atomic Operations</title> <para> -It is important to note that only the methods @gtk_list_store_insert_with_values and -@gtk_list_store_insert_with_valuesv are atomic, in the sense that the row is being appended -to the store and the values filled in in a single operation with regard to #GtkTreeModel signaling. -In contrast, using e.g. @gtk_list_store_append and then @gtk_list_store_set will first create a row, -which triggers the "row_inserted" #GtkTreeModel signal on #GtkListStore. The row, however, is still -empty, and any signal handler connecting to "row_inserted" on this particular store should be prepared -for the situation that the row might be empty. -This is especially important if you are wrapping the #GtkListStore inside a #GtkTreeModelFilter and are -using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations to append rows to the #GtkListStore -will cause the #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the function must be prepared for that. +It is important to note that only the methods +gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv() +are atomic, in the sense that the row is being appended to the store and the +values filled in in a single operation with regard to #GtkTreeModel signaling. +In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set() +will first create a row, which triggers the #GtkTreeModel::row-inserted signal +on #GtkListStore. The row, however, is still empty, and any signal handler +connecting to "row-inserted" on this particular store should be prepared +for the situation that the row might be empty. This is especially important +if you are wrapping the #GtkListStore inside a #GtkTreeModelFilter and are +using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations +to append rows to the #GtkListStore will cause the +#GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the +function must be prepared for that. </para> </refsect2> +<refsect2 id="GtkListStore-BUILDER-UI"> +<title>GtkListStore as GtkBuildable</title> +<para> +The GtkListStore implementation of the GtkBuildable interface allows +to specify the model columns with a <columns> element that may +contain multiple <column> elements, each specifying one model +column. The "type" attribute specifies the data type for the column. +</para> +<para> +Additionally, it is possible to specify content for the list store +in the UI definition, with the <data> element. It can contain +multiple <row> elements, each specifying to content for one +row of the list model. Inside a <row>, the <col> elements +specify the content for individual cells. +</para> +<para> +Note that it is probably more common to define your models +in the code, and one might consider it a layering violation +to specify the content of a list store in a UI definition, +<emphasis>data</emphasis>, not <emphasis>presentation</emphasis>, +and common wisdom is to separate the two, as far as possible. +<!-- FIXME a bit inconclusive --> +</para> +<example> +<title>A UI Definition fragment for a list store</title> +<programlisting><![CDATA[ +<object class="GtkListStore"> + <columns> + <column type="gchararray"/> + <column type="gchararray"/> + <column type="gint"/> + </columns> + <data> + <row> + <col id="0">John</col> + <col id="1">Doe</col> + <col id="2">25</col> + </row> + <row> + <col id="0">Johan</col> + <col id="1">Dahlin</col> + <col id="2">50</col> + </row> + </data> +</object> +]]></programlisting> +</example> +</refsect2> <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkmenu.sgml b/docs/reference/gtk/tmpl/gtkmenu.sgml index d7a8e812d..18f7fec9d 100644 --- a/docs/reference/gtk/tmpl/gtkmenu.sgml +++ b/docs/reference/gtk/tmpl/gtkmenu.sgml @@ -407,7 +407,6 @@ will be called when the menu is later detached from the widget. </para> @attach_widget: the #GtkWidget that the menu is being detached from. - @menu: the #GtkMenu being detached. diff --git a/docs/reference/gtk/tmpl/gtknotebook.sgml b/docs/reference/gtk/tmpl/gtknotebook.sgml index c2d94e67b..ba0ad64d6 100644 --- a/docs/reference/gtk/tmpl/gtknotebook.sgml +++ b/docs/reference/gtk/tmpl/gtknotebook.sgml @@ -19,13 +19,39 @@ will be a popup menu allowing the users to switch pages. (see gtk_notebook_enable_popup(), gtk_noteobook_disable_popup()) </para> +<refsect2 id="GtkNotebook-BUILDER-UI"> +<title>GtkNotebook as GtkBuildable</title> +<para> +The GtkNoteboopk implementation of the GtkBuildable interface +supports placing children into tabs by specifying "tab" as the +"type" attribbute of a <child> element. Note that the content +of the tab must be created before the tab can be filled. +</para> +<example> +<title>A UI definition fragment with GtkNotebook</title> +<programlisting><![CDATA[ +<object class="GtkNotebook"> + <child> + <object class="GtkLabel" id="notebook-content"> + <property name="label">Content</property> + </object> + </child> + <child type="tab"> + <object class="GtkLabel" id="notebook-tab"> + <property name="label">Tab</property> + </object> + </child> +</object> +]]></programlisting> +</example> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> <variablelist> <varlistentry> <term>#GtkContainer</term> -<listitem><para>For functions that apply to every #GtkContainer -(like #GtkList).</para></listitem> +<listitem><para>For functions that apply to every #GtkContainer</para></listitem> </varlistentry> </variablelist> </para> diff --git a/docs/reference/gtk/tmpl/gtkradiobutton.sgml b/docs/reference/gtk/tmpl/gtkradiobutton.sgml index d29942539..002b1d0d7 100644 --- a/docs/reference/gtk/tmpl/gtkradiobutton.sgml +++ b/docs/reference/gtk/tmpl/gtkradiobutton.sgml @@ -128,8 +128,10 @@ Creates a new #GtkRadioButton, adding it to the same group as @group. As with gtk_radio_button_new(), a widget should be packed into the radio button. </para> -@group: an existing #GtkRadioButton. +@radio_group_member: @Returns: a new radio button. +<!-- # Unused Parameters # --> +@group: an existing #GtkRadioButton. <!-- ##### FUNCTION gtk_radio_button_new_with_label ##### --> @@ -149,9 +151,11 @@ Creates a new #GtkRadioButton with a text label, adding it to the same group as @group. </para> -@group: an existing #GtkRadioButton. +@radio_group_member: @label: a text string to display next to the radio button. @Returns: a new radio button. +<!-- # Unused Parameters # --> +@group: an existing #GtkRadioButton. <!-- ##### FUNCTION gtk_radio_button_new_with_mnemonic ##### --> @@ -169,7 +173,7 @@ as @group. </para> -@group: +@radio_group_member: @label: @Returns: diff --git a/docs/reference/gtk/tmpl/gtkrecentchooser.sgml b/docs/reference/gtk/tmpl/gtkrecentchooser.sgml index 7464b8669..85013ba6f 100644 --- a/docs/reference/gtk/tmpl/gtkrecentchooser.sgml +++ b/docs/reference/gtk/tmpl/gtkrecentchooser.sgml @@ -45,6 +45,56 @@ Recently used files are supported since GTK+ 2.10. @recentchooser: the object which received the signal. +<!-- ##### ARG GtkRecentChooser:filter ##### --> +<para> + +</para> + +<!-- ##### ARG GtkRecentChooser:limit ##### --> +<para> + +</para> + +<!-- ##### ARG GtkRecentChooser:local-only ##### --> +<para> + +</para> + +<!-- ##### ARG GtkRecentChooser:recent-manager ##### --> +<para> + +</para> + +<!-- ##### ARG GtkRecentChooser:select-multiple ##### --> +<para> + +</para> + +<!-- ##### ARG GtkRecentChooser:show-icons ##### --> +<para> + +</para> + +<!-- ##### ARG GtkRecentChooser:show-not-found ##### --> +<para> + +</para> + +<!-- ##### ARG GtkRecentChooser:show-private ##### --> +<para> + +</para> + +<!-- ##### ARG GtkRecentChooser:show-tips ##### --> +<para> + +</para> + +<!-- ##### ARG GtkRecentChooser:sort-type ##### --> +<para> + +</para> + <!-- ##### STRUCT GtkRecentChooserIface ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkscalebutton.sgml b/docs/reference/gtk/tmpl/gtkscalebutton.sgml index 4589ab99c..88c2a5311 100644 --- a/docs/reference/gtk/tmpl/gtkscalebutton.sgml +++ b/docs/reference/gtk/tmpl/gtkscalebutton.sgml @@ -12,7 +12,6 @@ applications, and GTK+ provides a #GtkVolumeButton subclass that is tailored for this use case. </para> - <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtksizegroup.sgml b/docs/reference/gtk/tmpl/gtksizegroup.sgml index a8f07b874..7784e3a1a 100644 --- a/docs/reference/gtk/tmpl/gtksizegroup.sgml +++ b/docs/reference/gtk/tmpl/gtksizegroup.sgml @@ -44,6 +44,29 @@ vertical size from the vertical requisition of all widgets that can be reached from the widget by a chain of size groups of type %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH. </para> +<refsect2 id="GtkSizeGroup-BUILDER-UI"> +<title>GtkSizeGroup as GtkBuildable</title> +<para> +Size groups can be specified in a UI definition by placing an +<object> element with <literal>class="GtkSizeGroup"</literal> +somewhere in the UI definition. The widgets that belong to the +size group are specified by a <widgets> element that may +contain multiple <widget> elements, one for each member +of the size group. The name attribute gives the id of the widget. +</para> +<example> +<title>A UI definition fragment with GtkSizeGroup</title> +<programlisting><![CDATA[ +<object class="GtkSizeGroup"> + <property name="mode">GTK_SIZE_GROUP_HORIZONTAL</property> + <widgets> + <widget name="radio1"/> + <widget name="radio2"/> + </widgets> +</object> +]]></programlisting> +</example> +</refsect2> <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtktreemodel.sgml b/docs/reference/gtk/tmpl/gtktreemodel.sgml index 3bd3dfcc2..8b6c7408c 100644 --- a/docs/reference/gtk/tmpl/gtktreemodel.sgml +++ b/docs/reference/gtk/tmpl/gtktreemodel.sgml @@ -188,6 +188,27 @@ enum </example> </para> +<refsect2 id="GtkTreeModel-BUILDER-UI"> +<title>GtkTreeModel as GtkBuildable</title> +<para> +The GtkTreeStore implementation of the GtkBuildable interface allows +to specify the model columns with a <columns> element that may +contain multiple <column> elements, each specifying one model +column. The "type" attribute specifies the data type for the column. +</para> +<example> +<title>A UI definition fragment with GtkTreeStore</title> +<programlisting><![CDATA[ +<object class="GtkTreeStore"> + <columns> + <column type="gchararray"/> + <column type="guint"/> + </columns> +</object> +]]></programlisting> +</example> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> #GtkTreeView, #GtkTreeStore, #GtkListStore, <link linkend="gtk-GtkTreeView-drag-and-drop">GtkTreeDnd</link>, #GtkTreeSortable diff --git a/docs/reference/gtk/tmpl/gtktreestore.sgml b/docs/reference/gtk/tmpl/gtktreestore.sgml index 95b450f22..b5a1b6ae2 100644 --- a/docs/reference/gtk/tmpl/gtktreestore.sgml +++ b/docs/reference/gtk/tmpl/gtktreestore.sgml @@ -12,8 +12,30 @@ can use all of the methods available there. It also implements the #GtkTreeSortable interface so it can be sorted by the view. Finally, it also implements the tree <link linkend="gtktreednd">drag and drop</link> interfaces. +</para> +<refsect2 id="GtkTreeStore-BUILDER-UI"> +<title>GtkTreeStore as GtkBuildable</title> +<para> +The GtkTreeStore implementation of the GtkBuildable interface allows +to specify the model columns with a <columns> element that may +contain multiple <column> elements, each specifying one model +column. The "type" attribute specifies the data type for the column. </para> +<example> +<title>A UI Definition fragment for a tree store</title> +<programlisting><![CDATA[ +<object class="GtkTreeStore"> + <columns> + <column type="gchararray"/> + <column type="gchararray"/> + <column type="gint"/> + </columns> +</object> +]]></programlisting> +</example> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtktreeview.sgml b/docs/reference/gtk/tmpl/gtktreeview.sgml index faf41a4b7..1b981bed7 100644 --- a/docs/reference/gtk/tmpl/gtktreeview.sgml +++ b/docs/reference/gtk/tmpl/gtktreeview.sgml @@ -42,6 +42,33 @@ former you can use gtk_tree_view_convert_widget_to_bin_window_coords() (and vice versa). </para> +<refsect2 id="GtkTreeView-BUILDER-UI"> +<title>GtkTreeView as GtkBuildable</title> +<para> +The GtkTreeView implementation of the GtkBuildable interface accepts +GtkTreeViewColumn objects as <child> elements in UI definitions. +</para> +<example> +<title>A UI definition fragment with GtkTreeView</title> +<programlisting><![CDATA[ +<object class="GtkTreeView"> + <property name="model">liststore1</property> + <child> + <object class="GtkTreeViewColumn"> + <property name="title">Test</property> + <child> + <object class="GtkCellRendererText"/> + <attributes>" + <attribute name="text">1</attribute> + </attributes> + </child> + </object> + </child> +</object> +]]></programlisting> +</example> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> #GtkTreeViewColumn, #GtkTreeSelection, #GtkTreeDnd, #GtkTreeMode, #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore, #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf, #GtkCellRendererText, #GtkCellRendererToggle diff --git a/docs/reference/gtk/tmpl/gtkuimanager.sgml b/docs/reference/gtk/tmpl/gtkuimanager.sgml index 26e53df76..f08e5f088 100644 --- a/docs/reference/gtk/tmpl/gtkuimanager.sgml +++ b/docs/reference/gtk/tmpl/gtkuimanager.sgml @@ -199,6 +199,50 @@ to which the submenu is associated. </para> </refsect2> +<refsect2 id="GtkUIManager-BUILDER-UI"> +<title>GtkUIManager as GtkBuildable</title> +<para> +The GtkUIManager implementation of the GtkBuildable interface accepts +GtkActionGroup objects as <child> elements in UI definitions. +</para> +<para> +A GtkUIManager UI definition as described above can be embedded in +an GtkUIManager <object> element in a GtkBuilder UI definition. +</para> +<para> +The widgets that are constructed by a GtkUIManager can be embedded in +other parts of the constructed user interface with the help of the +"constructor" attribute. See the example below. +</para> +<example> +<title>An embedded GtkUIManager UI definition</title> +<programlisting><![CDATA[ +<object class="GtkUIManager" id="uiman"> + <child> + <object class="GtkActionGroup"> + <child> + <object class="GtkAction" id="file"> + <property name="label">_File</property> + </object> + </child> + </object> + </child> + <ui> + <menubar name="menubar1"> + <menu action="file"> + </menu> + </menubar> + </ui> +</object> +<object class="GtkWindow" id="main-window"> + <child> + <object class="GtkMenuBar" id="menubar1" constructor="uiman"/> + </child> +</object> +]]></programlisting> +</example> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> #GtkBuilder diff --git a/docs/reference/gtk/tmpl/gtkvscrollbar.sgml b/docs/reference/gtk/tmpl/gtkvscrollbar.sgml index 9e73ef775..01d75afd2 100644 --- a/docs/reference/gtk/tmpl/gtkvscrollbar.sgml +++ b/docs/reference/gtk/tmpl/gtkvscrollbar.sgml @@ -2,21 +2,17 @@ GtkVScrollbar <!-- ##### SECTION Short_Description ##### --> -A vertical scrollbar + <!-- ##### SECTION Long_Description ##### --> <para> -The #GtkVScrollbar widget is a widget arranged vertically creating a -scrollbar. See #GtkScrollbar for details on scrollbars. #GtkAdjustment -pointers may be added to handle the adjustment of the scrollbar or it -may be left %NULL in which case one will be created for you. See -#GtkAdjustment for details. + </para> <!-- ##### SECTION See_Also ##### --> <para> -#GtkScrollbar, #GtkScrolledWindow + </para> diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml index c2e26da70..d7de8d48c 100644 --- a/docs/reference/gtk/tmpl/gtkwidget.sgml +++ b/docs/reference/gtk/tmpl/gtkwidget.sgml @@ -22,6 +22,23 @@ style properties and gtk_widget_style_get_property(), gtk_widget_style_get() or gtk_widget_style_get_valist() to obtain the value of a style property. </para> +<refsect2 id="GtkWidget-BUILDER-UI"> +<title>GtkWidget as GtkBuildable</title> +<para> +The GtkWidget implementation of the GtkBuildable interface supports a +custom <accelerator> element, which has attributes named key, +modifiers and signal and allows to specify accelerators. +</para> +<example> +<title>A UI definition fragment specifying an accelerator</title> +<programlisting><![CDATA[ +<object class="GtkButton"> + <accelerator key="q" modifiers="GDK_CONTROL_MASK" signal="clicked"/> +</object> +]]></programlisting> +</example> +</refsect2> + <!-- ##### SECTION See_Also ##### --> <para> |