visual_index.xml
expand_content_files = \
- tree_widget.sgml
+ glossary.xml \
+ migrating-checklist.sgml \
+ migrating-GtkAction.sgml \
+ migrating-GtkComboBox.sgml \
+ migrating-GtkFileChooser.sgml \
+ migrating-GtkIconView.sgml \
+ migrating-GtkAboutDialog.sgml \
+ migrating-GtkColorButton.sgml \
+ tree_widget.sgml \
+ text_widget.sgml \
+ question_index.sgml
# Images to copy into HTML directory
HTML_IMAGES = \
<para>
A <glossterm linkend="container">container</glossterm> that
can hold at most one child widget. The base class for bins is
- <link linkend="GtkBin">GtkBin</link>.
+ #GtkBin.
</para>
<glossseealso>
<glossterm linkend="container">container</glossterm>
<glossdef>
<para>
GTK+ contains several widgets which display data in columns,
- e.g. the <link linkend="GtkTreeView">GtkTreeView</link>.
+ e.g. the #GtkTreeView.
These <glossterm linkend="view-column">view columns</glossterm> in
- the tree view are represented by
- <link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link>
+ the tree view are represented by #GtkTreeViewColumn
objects inside GTK+. They should not be confused with
<glossterm linkend="model-column">model columns</glossterm> which
are used to organize the data in tree models.
<emphasis>parent</emphasis> of the <emphasis>child</emphasis>
widgets. Some containers don't draw anything on their own,
but rather just organize their children's <glossterm
- linkend="geometry">geometry</glossterm>; for example, <link
- linkend="GtkVBox">GtkVBox</link> lays out its children
- vertically without painting anything on its own. Other
- containers include decorative elements; for example, <link
- linkend="GtkFrame">GtkFrame</link> contains the frame's child
- and a label in addition to the shaded frame it draws. The
- base class for containers is <link
- linkend="GtkContainer">GtkContainer</link>.
+ linkend="geometry">geometry</glossterm>; for example, #GtkVBox lays out
+ its children vertically without painting anything on its own. Other
+ containers include decorative elements; for example, #GtkFrame contains
+ the frame's child and a label in addition to the shaded frame it draws.
+ The base class for containers is #GtkContainer.
</para>
<glossseealso>
<glossterm linkend="container">widget</glossterm>
of a keyboard, a pointing device and one or more
<glossterm linkend="screen">screens</glossterm>.
Applications open a display to show windows and interact with the user.
- In GDK, a display is represented by a
- <link linkend="GdkDisplay">GdkDisplay</link>.
+ In GDK, a display is represented by a #GdkDisplay.
</para>
</glossdef>
</glossentry>
actually shows the GdkWindows it created when it was
<glossterm linkend="realization">realized</glossterm>. When a
widget is mapped, it must turn on its
- <constant>GTK_MAPPED</constant> <link
- linkend="GtkWidgetFlags">flag</link>.
+ %GTK_MAPPED <link linkend="GtkWidgetFlags">flag</link>.
</para>
<para>
Note that due to the asynchronous nature of the X window
system, a widget's window may not appear on the screen
- immediatly after one calls <link
- linkend="gdk-window-show"><function>gdk_window_show()</function></link>:
+ immediatly after one calls gdk_window_show():
you must wait for the corresponding map <glossterm
linkend="event">event</glossterm> to be received. You can do
this with the <link
A column in a tree model, holding data of a certain type.
The types which can be stored in the columns of a model
have to be specified when the model is constructed, see
- e.g. <link linkend="gtk-list-store-new">gtk_list_store_new()</link>.
+ e.g. gtk_list_store_new().
</para>
<glossseealso>
<glossterm linkend="view-column">view column</glossterm>
These widgets follow the well-known model-view pattern, which separates
the data (the model) to be displayed from the component which does the
actual visualization (the view). Examples of this pattern in GTK+ are
- the <link linkend="GtkTreeView">GtkTreeView</link>/<link linkend="GtkTreeModel">GtkTreeModel</link>
- and
- <link linkend="GtkTextView">GtkTextView</link>/<link linkend="GtkTextBuffer">GtkTextBuffer</link>
+ the #GtkTreeView/#GtkTreeModel and #GtkTextView/#GtkTextBuffer
</para>
<para>
One important advantage of this pattern is that it is possible to
display the same model in multiple views; another one that the
separation of the model allows a great deal of flexibility, as
- demonstrated by e.g.
- <link linkend="GtkTreeModelSort">GtkTreeModelSort</link> or
- <link linkend="GtkTreeModelFilter">GtkTreeModelFilter</link>.
+ demonstrated by e.g. #GtkTreeModelSort or #GtkTreeModelFilter.
</para>
</glossdef>
</glossentry>
A widget that does not have a GdkWindow of its own on which to
draw its contents, but rather shares its <glossterm
linkend="parent">parent's</glossterm>. Such a widget has the
- <constant>GTK_NO_WINDOW</constant> <link
- linkend="GtkWidgetFlags">flag</link> set, and can be tested
- with the <link
- linkend="gtk-widget-no-window:caps"><function>GTK_WIDGET_NO_WINDOW()</function></link>
- macro.
+ %GTK_NO_WINDOW <link linkend="GtkWidgetFlags">flag</link> set, and
+ can be tested with the GTK_WIDGET_NO_WINDOW() macro.
</para>
</glossdef>
</glossentry>
also attach a <glossterm linkend="style">style</glossterm> to
it. A widget becomes unrealized by destroying its associated
GdkWindow. When a widget is realized, it must turn on its
- <constant>GTK_REALIZED</constant> <link
- linkend="GtkWidgetFlags">flag</link>.
+ %GTK_REALIZED <link linkend="GtkWidgetFlags">flag</link>.
</para>
<para>
Widgets that don't own the GdkWindow on which they draw are
- called <glossterm linkend="no-window">no-window
- widgets</glossterm>. This can be tested with the <link
- linkend="gtk-widget-no-window:caps"><function>GTK_WIDGET_NO_WINDOW()</function></link>
- macro. Normally, these widgets draw on their parent's
- GdkWindow.
+ called <glossterm linkend="no-window">no-window widgets</glossterm>.
+ This can be tested with the GTK_WIDGET_NO_WINDOW() macro. Normally,
+ these widgets draw on their parent's GdkWindow.
</para>
<para>
Each screen can stretch across multiple physical monitors.
</para>
<para>
- In GDK, screens are represented by
- <link linkend="GdkScreen">GdkScreen</link> objects.
+ In GDK, screens are represented by #GdkScreen objects.
</para>
</glossdef>
</glossentry>
<glossdef>
<para>
A <glossterm linkend="widget">widget</glossterm> that does not
- require a <glossterm linkend="parent">parent</glossterm>
- container. The only toplevel widgets in GTK+ are <link
- linkend="GtkWindow">GtkWindow</link> and widgets derived from it.
+ require a <glossterm linkend="parent">parent</glossterm> container.
+ The only toplevel widgets in GTK+ are #GtkWindow and widgets derived from it.
</para>
<glossseealso>
<glossterm linkend="container">container</glossterm>
<glossdef>
<para>
A displayed column in a tree view, represented by a
- <link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> object.
+ #GtkTreeViewColumn object.
</para>
<glossseealso>
<glossterm linkend="model-column">model column</glossterm>
linkend="geometry">geometry</glossterm> of the widgets: every
widget thus has a parent except those widgets which are
<glossterm linkend="toplevel">toplevels</glossterm>. The base
- class for widgets is <link
- linkend="GtkWidget">GtkWidget</link>.
+ class for widgets is #GtkWidget.
</para>
<glossseealso>
<glossterm linkend="container">container</glossterm>
<!ENTITY visual-index SYSTEM "visual_index.xml">
<!ENTITY index-Objects-Grouped SYSTEM "objects_grouped.sgml">
-<!ENTITY gtk-TextWidget SYSTEM "text_widget.sgml">
+<!ENTITY gtk-TextWidget SYSTEM "xml/text_widget.sgml">
<!ENTITY gtk-TreeWidget SYSTEM "xml/tree_widget.sgml">
<!ENTITY gtk-Compiling SYSTEM "compiling.sgml">
<!ENTITY gtk-Building SYSTEM "building.sgml">
<!ENTITY gtk-Windows SYSTEM "windows.sgml">
<!ENTITY gtk-Framebuffer SYSTEM "framebuffer.sgml">
<!ENTITY gtk-X11 SYSTEM "x11.sgml">
-<!ENTITY gtk-Questions SYSTEM "question_index.sgml">
+<!ENTITY gtk-Questions SYSTEM "xml/question_index.sgml">
<!ENTITY gtk-Changes-1-2 SYSTEM "changes-1.2.sgml">
<!ENTITY gtk-Changes-2-0 SYSTEM "changes-2.0.sgml">
-<!ENTITY gtk-migrating-checklist SYSTEM "migrating-checklist.sgml">
-<!ENTITY gtk-migrating-GtkFileChooser SYSTEM "migrating-GtkFileChooser.sgml">
-<!ENTITY gtk-migrating-GtkAction SYSTEM "migrating-GtkAction.sgml">
-<!ENTITY gtk-migrating-GtkComboBox SYSTEM "migrating-GtkComboBox.sgml">
-<!ENTITY gtk-migrating-GtkIconView SYSTEM "migrating-GtkIconView.sgml">
-<!ENTITY gtk-migrating-GtkAboutDialog SYSTEM "migrating-GtkAboutDialog.sgml">
-<!ENTITY gtk-migrating-GtkColorButton SYSTEM "migrating-GtkColorButton.sgml">
+<!ENTITY gtk-migrating-checklist SYSTEM "xml/migrating-checklist.sgml">
+<!ENTITY gtk-migrating-GtkFileChooser SYSTEM "xml/migrating-GtkFileChooser.sgml">
+<!ENTITY gtk-migrating-GtkAction SYSTEM "xml/migrating-GtkAction.sgml">
+<!ENTITY gtk-migrating-GtkComboBox SYSTEM "xml/migrating-GtkComboBox.sgml">
+<!ENTITY gtk-migrating-GtkIconView SYSTEM "xml/migrating-GtkIconView.sgml">
+<!ENTITY gtk-migrating-GtkAboutDialog SYSTEM "xml/migrating-GtkAboutDialog.sgml">
+<!ENTITY gtk-migrating-GtkColorButton SYSTEM "xml/migrating-GtkColorButton.sgml">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY gtk-query-immodules SYSTEM "gtk-query-immodules-2.0.xml">
<!ENTITY gtk-update-icon-cache SYSTEM "gtk-update-icon-cache.xml">
-<!ENTITY gtk-glossary SYSTEM "glossary.xml">
+<!ENTITY gtk-glossary SYSTEM "xml/glossary.xml">
]>
<book id="index">
<bookinfo>
<title>Migrating from GnomeAbout to GtkAboutDialog</title>
<para>
- Since version 2.6, GTK+ provides the <link
- linkend="GtkIconView">GtkAboutDialog</link> widget as a replacement for
+ Since version 2.6, GTK+ provides the #GtkAboutDialog widget as a replacement for
the <structname>GnomeAbout</structname> dialog in the libgnomeui library.
</para>
<para>
- <link linkend="GtkIconView">GtkAboutDialog</link> supports all features
- found in <structname>GnomeAbout</structname>. The
- <structname>GtkAboutDialog</structname> API is bigger, since it follows
+ #GtkAboutDialog supports all features found in <structname>GnomeAbout</structname>.
+ The <structname>GtkAboutDialog</structname> API is bigger, since it follows
the GTK+ policy to have getters and setters for all widget properties,
but it isn't much more complex than <structname>GnomeAbout</structname>.
</para>
NULL);
g_object_unref (pixbuf);
</programlisting></informalexample>
- If the <link linkend="g-object-new"><function>g_object_new()</function></link> construction scares you,
- you can also use <link linkend="g-object-new"><function>gtk_about_dialog_new()</function></link> to
- construct the dialog and then use the setters for the individual properties.
+ If the g_object_new() construction scares you, you can also use
+ gtk_about_dialog_new() to construct the dialog and then use the setters for
+ the individual properties.
</para>
<para>
</para></listitem>
<listitem><para>
If your credits contain email addresses or URLs, you can turn them
- into clickable links using
- <link linkend="gtk-about-dialog-set-email-hook"><function>gtk_about_dialog_set_email_hook()</function></link> and
- <link linkend="gtk-about-dialog-set-url-hook"><function>gtk_about_dialog_set_url_hook()</function></link>.
+ into clickable links using gtk_about_dialog_set_email_hook() and
+ gtk_about_dialog_set_url_hook().
</para></listitem>
</itemizedlist>
</para>
<para>
Prior to GTK+ 2.4, there were several APIs in use to create menus
- and toolbars. GTK+ itself included <link
- linkend="GtkItemFactory">GtkItemFactory</link>, which was
+ and toolbars. GTK+ itself included #GtkItemFactory, which was
historically used in the GIMP; libgnomeui provided the gnome-ui
set of macros; libbonoboui provided a complex mechanism to do menu
merging across embedded components. GTK+ 2.4 includes a system
for creating menus and toolbars, with merging of items, based
- around the <link linkend="GtkAction">GtkAction</link> mechanism.
+ around the #GtkAction mechanism.
</para>
<section id="actions-and-action-groups">
<title>Actions and Action Groups</title>
<para>
- A <link linkend="GtkAction">GtkAction</link> represents an
- operation that the user can perform from the menus and toolbars
- of an application. It is similar to "verbs" in other menu
- systems. A <link linkend="GtkAction">GtkAction</link> has a
- name, which is its identifier, and it can have several widgets
- that represent it in the user interface. For example, an action
- for <symbol>EditCopy</symbol> can have a menu item as well as a
- toolbar button associated to it. If there is nothing selected
+ A #GtkAction represents an operation that the user can perform from
+ the menus and toolbars of an application. It is similar to "verbs"
+ in other menu systems. A #GtkAction has a name, which is its identifier,
+ and it can have several widgets that represent it in the user interface.
+ For example, an action for <symbol>EditCopy</symbol> can have a menu item
+ as well as a toolbar button associated to it. If there is nothing selected
in the document, the application can simply de-sensitize the
<symbol>EditCopy</symbol> action; this will cause both the menu
item and the toolbar button to be de-sensitized automatically.
Similarly, whenever the user selects the menu item or the
toolbar button associated to the <symbol>EditCopy</symbol>
- action, the corresponding <link
- linkend="GtkAction">GtkAction</link> object will emit an
+ action, the corresponding #GtkAction object will emit an
"activate" signal.
</para>
<para>
- <link linkend="GtkActionGroup">GtkActionGroup</link> is simply a
- group of <link linkend="GtkAction">GtkAction</link> objects. An
+ #GtkActionGroup is simply a group of #GtkAction objects. An
application may want to have several groups: one for global
actions such as "new document", "about", and "exit"; then one
group for each open document with actions specific to the
<title>User Interface Manager Object</title>
<para>
- <link linkend="GtkUIManager">GtkUIManager</link> is an object
- that can construct menu and toolbar widgets from an XML
- description. These widgets are in turn associated to
+ #GtkUIManager is an object that can construct menu and toolbar widgets
+ from an XML description. These widgets are in turn associated to
corresponding actions and action groups.
</para>
<para>
- <link linkend="GtkUIManager">GtkUIManager</link> supports
- merging of menus and toolbars for applications that have
- multiple components, each with separate sets of commands. For
- example, a word processor that can embed images may want to have
+ #GtkUIManager supports merging of menus and toolbars for applications
+ that have multiple components, each with separate sets of commands.
+ For example, a word processor that can embed images may want to have
toolbar buttons for Bold and Italic when the cursor is on a text
block, but Crop and Brightness/Contrast buttons when the cursor
is on an image. These actions, which change depending on the
state of the application, can be merged and de-merged from a
- <link linkend="GtkUIManager">GtkUIManager</link> as appropriate.
+ #GtkUIManager as appropriate.
</para>
</section>
array of <structname>GnomeUIInfo</structname> structures, which
contain information for menu or toolbar items such as their
label, icon, and accelerator key. Then, one calls
- <function>gnome_app_fill_menu()</function> or
- <function>gnome_app_fill_toolbar()</function>, or one of the
+ gnome_app_fill_menu() or gnome_app_fill_toolbar(), or one of the
related functions, to create the appropriate widgets based on
these structures.
</para>
pass back pointers to the widgets that got created. This means
that the structures cannot simply be kept around if the program
requires multiple instances of the user interface (e.g. several
- windows); each new invocation of
- <function>gnome_app_fill_menu()</function> would overwrite the
+ windows); each new invocation of gnome_app_fill_menu() would overwrite the
widget fields of the structures.
</para>
<para>
Separate your existing GnomeUIInfo entries into normal
actions, toggle actions, and radio actions, and then create
- a separate array of <link
- linkend="GtkActionEntry">GtkActionEntry</link> structures
+ a separate array of #GtkActionEntry structures
for each group. This will allow you to create the necessary
- <link linkend="GtkActionGroup">GtkActionGroup</link>
- objects. Note that this does not describe the actual
+ #GtkActionGroup objects. Note that this does not describe the actual
"shape" that your menus and toolbars will have; it simply
defines the set of commands that will appear in them.
</para>
<listitem>
<para>
Create an XML description of your menus and toolbars for use
- with <link linkend="GtkUIManager">GtkUIManager</link>. This
- defines the actual shape of the menus and toolbars.
+ with #GtkUIManager. This defines the actual shape of the menus and toolbars.
</para>
</listitem>
<listitem>
<para>
Port the code that uses gnome-app and gnome-app-helper to
- <link linkend="GtkAction">GtkAction</link> and <link
- linkend="GtkUIManager">GtkUIManager</link>.
+ #GtkAction and #GtkUIManager.
</para>
</listitem>
<listitem>
<para>
If your GnomeUIInfo entries use GNOME_APP_PIXMAP_DATA or
GNOME_APP_PIXMAP_FILENAME for pixmaps, you have to create a
- <link linkend="GtkIconFactory">GtkIconFactory</link>, add it
- to the list of default factories, then create a
- <link linkend="GtkIconSet">GtkIconSet</link> for each of your
- own icons. Add the sets to the factory, and use the id in the
- <link linkend="GtkActionEntry">GtkActionEntry</link> like a
- regular GTK+ stock id.
+ #GtkIconFactory, add it to the list of default factories, then create a
+ #GtkIconSet for each of your own icons. Add the sets to the factory, and
+ use the id in the #GtkActionEntry like a regular GTK+ stock id.
</para>
</listitem>
</orderedlist>
<para>
The following code shows a declaration of a simple menu bar to
- be used with <function>gnome_app_fill_menu()</function> or
- similar. The menu hierarchy looks like this:
+ be used with gnome_app_fill_menu() or similar. The menu hierarchy looks
+ like this:
</para>
<itemizedlist>
The following code is the set of actions that are present in
the <link linkend="gnomeuiinfo-example">previous
example</link>. Note that the toggle and radio entries are
- separate from normal actions. Also, note that <link
- linkend="GtkActionEntry">GtkActionEntry</link> structures take
- key names in the format of gdk_accelerator_parse() rather than
- key values plus modifiers; you will have to convert these
- values by hand. For example, <constant>GDK_F11</constant>
- with no modifiers is equivalent to a key name of
- <literal>"F11"</literal>. Likewise, <literal>"o"</literal>
- with <constant>GDK_CONTROL_MASK</constant> is equivalent to
- <literal>"<ontrol>O"</literal>.
+ separate from normal actions. Also, note that #GtkActionEntry
+ structures take key names in the format of gdk_accelerator_parse()
+ rather than key values plus modifiers; you will have to convert these
+ values by hand. For example, %GDK_F11 with no modifiers is equivalent
+ to a key name of <literal>"F11"</literal>. Likewise, <literal>"o"</literal>
+ with %GDK_CONTROL_MASK is equivalent to <literal>"<ontrol>O"</literal>.
</para>
<programlisting>
<para>
After extracting the actions, you will need to create an XML
description of the actual layout of your menus and toolbars
- for use with <link linkend="GtkUIManager">GtkUIManager</link>.
- The following code shows a simple menu bar that corresponds to
- the <link linkend="gnomeuiinfo-example">previous
+ for use with #GtkUIManager. The following code shows a simple
+ menu bar that corresponds to the <link linkend="gnomeuiinfo-example">previous
example</link>. Note that the <guimenu>File</guimenu> and
<guimenu>View</guimenu> menus have their names specified in
the <link linkend="gnomeuiinfo-action-entries">action
<title>Creating the Menu Bar</title>
<para>
- In this last example, we will create a <link
- linkend="GtkActionGroup">GtkActionGroup</link> based on the
- <link linkend="gnomeuiinfo-action-entries">action
- entries</link> we created above. We will then create a <link
- linkend="GtkUIManager">GtkUIManager</link> with the <link
+ In this last example, we will create a #GtkActionGroup based on the
+ <link linkend="gnomeuiinfo-action-entries">action entries</link>
+ we created above. We will then create a #GtkUIManager with the <link
linkend="gnomeuiinfo-xml">XML description</link> of the menu
layout. We will also extract the accelerator group and the
- widgets from the <link
- linkend="GtkUIManager">GtkUIManager</link> put them into a
- window.
+ widgets from the #GtkUIManager put them into a window.
</para>
<programlisting>
GtkAccelGroup *accel_group;
GError *error;
-register_my_stock_icons ();
+register_my_stock_icons (<!-- -->);
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
gtk_action_group_add_toggle_actions (action_group, toggle_entries, G_N_ELEMENTS (toggle_entries), window);
gtk_action_group_add_radio_actions (action_group, radio_entries, G_N_ELEMENTS (radio_entries), 0, radio_action_callback, window);
-ui_manager = gtk_ui_manager_new ();
+ui_manager = gtk_ui_manager_new (<!-- -->);
gtk_ui_manager_insert_action_group (ui_manager, action_group, 0);
accel_group = gtk_ui_manager_get_accel_group (ui_manager);
GtkIconSource *icon_source;
gint i;
- icon_factory = gtk_icon_factory_new ();
+ icon_factory = gtk_icon_factory_new (<!-- -->);
for (i = 0; i < n_stock_icons; i++)
{
- icon_set = gtk_icon_set_new ();
- icon_source = gtk_icon_source_new ();
+ icon_set = gtk_icon_set_new (<!-- -->);
+ icon_source = gtk_icon_source_new (<!-- -->);
gtk_icon_source_set_filename (icon_source, stock_icons[i].filename);
gtk_icon_set_add_source (icon_set, icon_source);
gtk_icon_source_free (icon_source);
<title>Migrating from GnomeColorPicker to GtkColorButton</title>
<para>
- Since version 2.6, GTK+ provides the <link linkend="GtkColorButton">GtkColorButton</link>
+ Since version 2.6, GTK+ provides the #GtkColorButton
widget as a replacement for the <structname>GnomeColorPicker</structname>
- widget in the libgnomeui
- library.
+ widget in the libgnomeui library.
</para>
<para>
<chapter id="gtk-migrating-GtkComboBox">
- <title>Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and GtkComboBoxEntry</title>
+ <title>Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and
+ GtkComboBoxEntry</title>
<para>
Prior to 2.4, GTK+ offered two widgets for the task of selecting one
- item from a list of options.
- <link linkend="GtkOptionMenu">GtkOptionMenu</link> presents the list of
- options as a menu while <link linkend="GtkCombo">GtkCombo</link> presents
- them in a Windows-style list popup. The only difference between the two
- is that a <link linkend="GtkCombo">GtkCombo</link> allows to manually
- edit the selected value, while the
- <link linkend="GtkOptionMenu">GtkOptionMenu</link> does not.
+ item from a list of options. #GtkOptionMenu presents the list of
+ options as a menu while #GtkCombo presents them in a Windows-style list
+ popup. The only difference between the two is that a #GtkCombo allows to
+ manually edit the selected value, while the #GtkOptionMenu does not.
</para>
<para>
In GTK+ 2.4, a unified API for list selection was introduced, with
- <link linkend="GtkComboBox">GtkComboBox</link> for the non-editable case
- and <link linkend="GtkComboBoxEntry">GtkComboBoxEntry</link> for the
+ #GtkComboBox for the non-editable case and #GtkComboBoxEntry for the
editable case.
The selection of the display style — menu or list —
is no longer done at the API level, but has been made themeable via
<para>
Here is an example of a simple, but typical use of
- <link linkend="GtkOptionMenu">GtkOptionMenu</link>:
+ #GtkOptionMenu:
<informalexample><programlisting>
GtkWidget *option_menu, *menu, *menu_item;
-option_menu = gtk_option_menu_new ();
-menu = gtk_menu_new ();
+option_menu = gtk_option_menu_new (<!-- -->);
+menu = gtk_menu_new (<!-- -->);
menu_item = gtk_menu_item_new_with_label ("First Item");
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu);
</programlisting></informalexample>
In order to react to the user's selection, connect to the "changed"
- signal on the option menu and use <link linkend="gtk-option-menu-get-history"><function>gtk_option_menu_get_history()</function></link>
+ signal on the option menu and use gtk_option_menu_get_history()
to retrieve the index of the selected item.
</para>
<para>
- And here is how it would be done with a
- <link linkend="GtkComboBox">GtkComboBox</link>:
+ And here is how it would be done with a #GtkComboBox:
<informalexample><programlisting>
GtkWidget *combo_box;
-combo_box = gtk_combo_box_new_text ();
+combo_box = gtk_combo_box_new_text (<!-- -->);
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item");
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item");
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item");
</programlisting></informalexample>
In order to react to the user's selection, connect to the "changed"
- signal on the combo box and use <link linkend="gtk-combo-box-get-active"><function>gtk_combo_box_get_active()</function></link>
+ signal on the combo box and use gtk_combo_box_get_active()
to retrieve the index of the selected item.
</para>
<informalexample><programlisting>
GtkWidget *option_menu, *menu, *menu_item;
-option_menu = gtk_option_menu_new ();
-menu = gtk_menu_new ();
+option_menu = gtk_option_menu_new (<!-- -->);
+menu = gtk_menu_new (<!-- -->);
menu_item = gtk_image_menu_item_new_with_label ("First Item");
gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf1));
</programlisting></informalexample>
</para>
<para>
- can be done using a <link linkend="GtkComboBox">GtkComboBox</link>
- as follows:
+ can be done using a #GtkComboBox as follows:
<informalexample><programlisting>
GtkListStore *store;
GtkTreeIter iter;
combo_box = gtk_combo_box_new_with_model (GTK_TREE_MODEL (store));
-renderer = gtk_cell_renderer_pixbuf_new ();
+renderer = gtk_cell_renderer_pixbuf_new (<!-- -->);
gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo_box), renderer, FALSE);
gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer,
"pixbuf", 0,
NULL);
-renderer = gtk_cell_renderer_text_new ();
+renderer = gtk_cell_renderer_text_new (<!-- -->);
gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo_box), renderer, TRUE);
gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer,
"text", 1,
<title>Migrating from GtkCombo to GtkComboBoxEntry</title>
<para>
- Here is an example of a simple, but typical use of a
- <link linkend="GtkCombo">GtkCombo</link>:
+ Here is an example of a simple, but typical use of a #GtkCombo:
<informalexample><programlisting>
GtkWidget *combo;
GList *items = NULL;
items = g_list_append (items, "Second Item");
items = g_list_append (items, "Third Item");
-combo = gtk_combo_new ();
+combo = gtk_combo_new (<!-- -->);
gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
</programlisting></informalexample>
In order to react to the user's selection, connect to the "changed"
to retrieve the selected text.
</para>
<para>
- And here is how it would be done using <link linkend="GtkComboBoxEntry">GtkComboBoxEntry</link>:
+ And here is how it would be done using #GtkComboBoxEntry:
<informalexample><programlisting>
-combo_box = gtk_combo_box_entry_new_text ();
+combo_box = gtk_combo_box_entry_new_text (<!-- -->);
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item");
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item");
<para>
The new widgets have more to offer than a mere combination of the
- features of <link linkend="GtkOptionMenu">GtkOptionMenu</link> and
- <link linkend="GtkCombo">GtkCombo</link>. Notable new features
+ features of #GtkOptionMenu and #GtkCombo. Notable new features
include:
<variablelist>
<varlistentry>
would be a "color combo" where the individual items are small
square color swatches. The new widgets support gridded display
with the functions
- <link linkend="gtk-combo-box-set-wrap-width"><function>gtk_combo_box_set_wrap_width()</function></link>,
- <link linkend="gtk-combo-box-set-row-span-column"><function>gtk_combo_box_set_row_span_column()</function></link> and
- <link linkend ="gtk-combo-box-set-column-span-column"><function>gtk_combo_box_set_column_span_column()</function></link>.
+ gtk_combo_box_set_wrap_width(),
+ gtk_combo_box_set_row_span_column() and
+ gtk_combo_box_set_column_span_column().
</para></listitem>
</varlistentry>
<varlistentry>
<term>Display of icons</term>
- <listitem><para>An often-heard complaint about
- <link linkend="GtkOptionMenu">GtkOptionMenu</link> is that the
- icons which appear in the image menu items in its menu are not
+ <listitem><para>An often-heard complaint about #GtkOptionMenu is that
+ the icons which appear in the image menu items in its menu are not
displayed in the button showing the selected item. This limitation
- has been removed in <link linkend="GtkComboBox">GtkComboBox</link>;
- the selected item appears in the same way as the options in
- the popup.
+ has been removed in #GtkComboBox; the selected item appears in the
+ same way as the options in the popup.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Full tree model power</term>
<listitem><para>
Since the new widgets are built around the same models that are
- used for <link linkend="GtkTreeView">GtkTreeView</link>, all of
- the powerful machinery of tree models and cell renderers can be
- used.
+ used for #GtkTreeView, all of the powerful machinery of tree models
+ and cell renderers can be used.
</para></listitem>
</varlistentry>
</variablelist>
<title>Migrating from GtkFileSelection to GtkFileChooser</title>
<para>
- <link linkend="GtkFileChooser">GtkFileChooser</link>, starting
- with GTK+ 2.4, is the new set of APIs for file selection widgets
- and dialogs. Previous versions of GTK+ used <link
- linkend="GtkFileSelection">GtkFileSelection</link>, which has
- numerous problems.
+ #GtkFileChooser, starting with GTK+ 2.4, is the new set of APIs for file
+ selection widgets and dialogs. Previous versions of GTK+ used #GtkFileSelection,
+ which has numerous problems.
</para>
<para>
- <link linkend="GtkFileChooser">GtkFileChooser</link> is an
- abstract interface that can be implemented by widgets that perform
- file selection tasks. Two widgets in GTK+ implement this
- interface: <link
- linkend="GtkFileChooserDialog">GtkFileChooserDialog</link> and
- <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>.
- Most applications simply need to use <link
- linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>, which
- is a dialog box that allows the user to select existing files for
- opening them, or to pick new filenames for saving documents.
- <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>
- is for special applications that need to embed a file selection
- widget inside a larger window. In the context of GTK+, <link
- linkend="GtkFileChooserDialog">GtkFileChooserDialog</link> is
- simply a <link linkend="GtkDialog">GtkDialog</link> box with a
- <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>
+ #GtkFileChooser is an abstract interface that can be implemented by widgets
+ that perform file selection tasks. Two widgets in GTK+ implement this
+ interface: #GtkFileChooserDialog and #GtkFileChooserWidget. Most applications
+ simply need to use #GtkFileChooserDialog, which is a dialog box that allows the
+ user to select existing files for opening them, or to pick new filenames for
+ saving documents. #GtkFileChooserWidget is for special applications that need to
+ embed a file selection widget inside a larger window. In the context of GTK+,
+ #GtkFileChooserDialog is simply a #GtkDialog box with a #GtkFileChooserWidget.
inside.
</para>
<title>Creating a GtkFileChooserDialog</title>
<para>
- To create a <link
- linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>, you
- simply call gtk_file_chooser_dialog_new(). This function is
- similar to gtk_dialog_new() in that it takes parameters for the
+ To create a #GtkFileChooserDialog, you simply call gtk_file_chooser_dialog_new().
+ This function is similar to gtk_dialog_new() in that it takes parameters for the
title of the dialog box and its transient parent, as well as its
buttons. In addition, it takes in an argument that determines
whether the file chooser dialog will be used for opening
<title>Selection Modes</title>
<para>
- <link linkend="GtkFileChooser">GtkFileChooser</link> can be used
- in two modes, to select a single file at a time or to select a
- set of more than one file. To set this, use
+ #GtkFileChooser can be used in two modes, to select a single file at a
+ time or to select a set of more than one file. To set this, use
gtk_file_chooser_set_select_multiple(). In single-selection
mode, you can use gtk_file_chooser_get_filename() to get a file
name from the local file system or gtk_file_chooser_get_uri() to
get a full-formed URI. In multiple-selection mode, you can use
- gtk_file_chooser_get_filenames() to get a <link
- linkend="GSList">GSList</link> of filename strings, or
+ gtk_file_chooser_get_filenames() to get a #GSList of filename strings, or
gtk_file_chooser_get_uris() to get a list of URI strings.
</para>
<para>
- Also, you can configure <link
- linkend="GtkFileChooser">GtkFileChooser</link> to select files
+ Also, you can configure #GtkFileChooser to select files
or folders. Consider a backup program that needs to let the
user select a folder that will be backed up along with its
- subfolders. To configure whether <link
- linkend="GtkFileChooser">GtkFileChooser</link> is used to select
+ subfolders. To configure whether #GtkFileChooser is used to select
files or folders, use gtk_file_chooser_set_action(). In
addition, this lets you configure whether the file chooser will
be used to select existing files or folders (e.g. for
<para>
Many applications need to have a preview facility within their
file chooser dialogs. Previous to GTK+ 2.4, one needed to
- access the <link
- linkend="GtkFileSelection">GtkFileSelection</link> widget
- hierarchy directly to hook in a preview widget. With <link
- linkend="GtkFileChooser">GtkFileChooser</link>, there is a
+ access the #GtkFileSelection widget hierarchy directly to hook in
+ a preview widget. With #GtkFileChooser, there is a
dedicated API to do this.
</para>
<title>New features</title>
<para>
- New features in <link
- linkend="GtkFileChooser">GtkFileChooser</link> include the
- following:
+ New features in #GtkFileChooser include the following:
</para>
<itemizedlist>
<listitem>
<para>
Ability to select URIs rather than just local files. You
- must use a <link
- linkend="GtkFileSystem">GtkFileSystem</link> implementation
- that supports this, for example the gnome-vfs backend.
+ must use a #GtkFileSystem implementation that supports this,
+ for example the gnome-vfs backend.
</para>
</listitem>
</itemizedlist>
<para>
- To see how to use these features, please consult the <link
- linkend="GtkFileChooser">GtkFileChooser</link> reference
- documentation.
+ To see how to use these features, please consult the #GtkFileChooser
+ reference documentation.
</para>
</section>
</chapter>
<title>Migrating from GnomeIconList to GtkIconView</title>
<para>
- Since version 2.6, GTK+ provides the <link
- linkend="GtkIconView">GtkIconView</link>
- widget. It is similar in functionality to the
- <structname>GnomeIconList</structname> widget in the
+ Since version 2.6, GTK+ provides the #GtkIconView widget. It is similar in
+ functionality to the <structname>GnomeIconList</structname> widget in the
libgnomeui library, both widgets provide a way to lay out named icons in
a grid. The distinctive feature of the GTK+ widget is that it follows the
model-view pattern, allowing it to share the actual data (i.e. the names
</para>
<para>
- <link linkend="GtkIconView">GtkIconView</link> currently doesn't support
- some features found in <structname>GnomeIconList</structname>. Icons can
- not be positioned freely, the spacing is not customizable, and it is not
- possible to edit the names of icons.
+ #GtkIconView currently doesn't support some features found in
+ <structname>GnomeIconList</structname>. Icons can not be positioned freely,
+ the spacing is not customizable, and it is not possible to edit the names of
+ icons.
</para>
<para>
To convert an application that uses <structname>GnomeIconList</structname>
- to <link linkend="GtkIconView">GtkIconView</link>, the first step is to
- organize your data in a <link linkend="GtkTreeModel">GtkTreeModel</link>.
+ to #GtkIconView, the first step is to organize your data in a #GtkTreeModel.
<structname>GnomeIconList</structname> lets you directly insert data with
- <function>gnome_icon_list_insert()</function> and
- <function>gnome_icon_list_insert_pixbuf()</function> and their
+ gnome_icon_list_insert() and gnome_icon_list_insert_pixbuf() and their
append variants. So, if you previously had a function to fill your icon
list similar to this one:
<informalexample><programlisting>
/* do other initialization... */
/* construct the GtkIconView */
- icon_view = gtk_icon_view_new ();
+ icon_view = gtk_icon_view_new (<!-- -->);
model = gtk_list_store_new (3, GDK_TYPE_PIXBUF, G_TYPE_STRING, G_TYPE_POINTER);
gtk_icon_view_set_pixbuf_column (GTK_ICON_VIEW (icon_view), PIXBUF_COLUMN);
/* ... */
}
</programlisting></informalexample>
- This example uses a <link linkend="GtkListStore">GtkListStore</link> as
- model, but part of the elegance of the model-view pattern is that you can
- easily use another tree model implementation, or even write your own
- custom tree model.
+ This example uses a #GtkListStore as model, but part of the elegance of the
+ model-view pattern is that you can easily use another tree model implementation,
+ or even write your own custom tree model.
</para>
<para>
Your application may make use of extra data attached to the icons in the
- <structname>GnomeIconList</structname> via
- <function>gnome_icon_list_set_icon_data()</function> and
- <function>gnome_icon_list_get_icon_data()</function>. With
- <link linkend="GtkIconView">GtkIconView</link> such data is most
+ <structname>GnomeIconList</structname> via gnome_icon_list_set_icon_data() and
+ gnome_icon_list_get_icon_data(). With #GtkIconView such data is most
conveniently stored in an extra column in the tree model, so you would
call a function like
<informalexample><programlisting>
}
</programlisting></informalexample>
assuming that your tree model has a <literal>DATA_COLUMN</literal> of type
- <literal>G_TYPE_POINTER</literal>.
+ %G_TYPE_POINTER.
</para>
<para>
<listitem><para>
<structname>GtkIconView</structname> can not be frozen in the same
way as <structname>GnomeIconList</structname> can with
- <function>gnome_icon_list_freeze()</function> and
- <function>gnome_icon_list_thaw()</function>. Instead you can
+ gnome_icon_list_freeze() and gnome_icon_list_thaw(). Instead you can
replace the whole model of a <structname>GtkIconView</structname>,
instead of doing many small changes to the existing model.
</para></listitem>
GtkWidget *menu;
int button, event_time;
- menu = gtk_menu_new ();
+ menu = gtk_menu_new (<!-- -->);
g_signal_connect (menu, "deactivate",
G_CALLBACK (gtk_widget_destroy), NULL);
else
{
button = 0;
- event_time = gtk_get_current_event_time ();
+ event_time = gtk_get_current_event_time (<!-- -->);
}
gtk_menu_popup (GTK_MENU (popup), NULL, NULL, NULL, NULL,
in the case where the <parameter>event</parameter> is
<constant>NULL</constant>. This function should compute the
desired position for a menu when it is invoked through the
- keyboard. For example, <xref linkend="GtkEntry"/> aligns the
+ keyboard. For example, #GtkEntry aligns the
top edge of its popup menu with the bottom edge of the entry.
</para>
</note>
able to take the keyboard focus. In general, widgets should
be fully usable through the keyboard and not just the mouse.
The very first step of this is to ensure that your widget
- turns on the <link
- linkend="gtkwidgetflags"><constant>GTK_CAN_FOCUS</constant></link>
- FLAG.
+ turns on the %GTK_CAN_FOCUS <link
+ linkend="gtkwidgetflags">flag</link>.
</para>
</note>
</section>
<title>Why</title>
<para>
With
- <function>gtk_accelerator_get_default_mod_mask()</function>
+ gtk_accelerator_get_default_mod_mask()
you can test for modifier keys reliably; this way your key
event handlers will work correctly even if
<keycap>NumLock</keycap> or <keycap>CapsLock</keycap> are
Modifiers are keys like <keycap>Control</keycap> and
<keycap>NumLock</keycap>. When implementing a <link
linkend="GtkWidget-key-press-event">GtkWidget::key_press_event</link>
- handler, you should use
- <function>gtk_accelerator_get_default_mod_mask()</function> to
+ handler, you should use gtk_accelerator_get_default_mod_mask() to
test against modifier keys. This function returns a bit mask
which encompasses all the modifiers which the user may be
actively pressing, such as <keycap>Control</keycap>,
<literal>GDK_CONTROL_MASK | GDK_LOCK_MASK</literal>, and the
simple test will fail. By taking the logical-and of
<structfield>event->state</structfield> and
- <function>gtk_accelerator_get_default_mod_mask()</function>, you
+ gtk_accelerator_get_default_mod_mask(), you
can ignore the modifiers which are not actively pressed by the
user at the same time as the base key.
</para>
{
guint modifiers;
- modifiers = gtk_accelerator_get_default_mod_mask ();
+ modifiers = gtk_accelerator_get_default_mod_mask (<!-- -->);
if (event->keysym == GDK_F10
&& (event->state & modifiers) == GDK_CONTROL_MASK)
<answer>
<para>
-See the documentation for <link linkend="GObject">GObject</link> and
-<link linkend="GtkObject">GtkObject</link>. For <link
-linkend="GObject">GObject</link> note specifically <link
-linkend="g-object-ref">g_object_ref()</link> and <link
-linkend="g-object-unref">g_object_unref()</link>. <link
-linkend="GtkObject">GtkObject</link> is a subclass of <link
-linkend="GObject">GObject</link> so the same points apply, except that
-it has a "floating" state (explained in its documentation).
-</para>
-
-<para>
-For strings returned from functions, they will be declared "const"
-(using <link linkend="G-CONST-RETURN-CAPS">G_CONST_RETURN</link>) if they
-should not be freed. Non-const strings should be freed with <link
-linkend="g-free">g_free()</link>. Arrays follow the same rule. (If
-you find an exception to the rules, please report a bug to <ulink
+See the documentation for #GObject and #GtkObject. For #GObject note specifically
+g_object_ref() and g_object_unref(). #GtkObject is a subclass of #GObject so the
+same points apply, except that it has a "floating" state (explained in its
+documentation).
+</para>
+
+<para>
+For strings returned from functions, they will be declared "const" (using
+#G_CONST_RETURN) if they should not be freed. Non-const strings should be freed
+with g_free(). Arrays follow the same rule. (If you find an exception to the rules,
+please report a bug to <ulink
url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
</para>
gettext</literal> to read the documentation.
</para>
<para>
-The short checklist on how to use gettext is: call
-<function>bindtextdomain()</function> so gettext can find the files
-containing your translations, call <function>textdomain()</function>
-to set the default translation domain, then call
-<function>gettext()</function> to look up each string to be translated
-in the default domain. Conventionally, people define macros as
+The short checklist on how to use gettext is: call bindtextdomain() so gettext
+can find the files containing your translations, call textdomain() to set the
+default translation domain, then call gettext() to look up each string to be
+translated in the default domain. Conventionally, people define macros as
follows for convenience:
<informalexample>
<programlisting>
#define N_(x) x
</programlisting>
</informalexample>
-You use <function>N_()</function> (N stands for no-op) to mark
-a string for translation in a context where a function call
-to <function>gettext()</function> is not allowed, such as in
-an array initializer. You eventually have to call
-<function>gettext()</function> on the string to actually fetch the
-translation. <function>_()</function> both marks the string for
-translation and actually translates it.
+You use N_() (N stands for no-op) to mark a string for translation in a context
+where a function call to gettext() is not allowed, such as in an array initializer.
+You eventually have to call gettext() on the string to actually fetch the
+translation. _() both marks the string for translation and actually translates it.
</para>
<para>
Code using these macros ends up looking like this:
</informalexample>
</para>
<para>
-Libraries using gettext should use <function>dgettext()</function>
-instead of <function>gettext()</function>, which allows
-them to specify the translation domain each time they
-ask for a translation. Libraries should also avoid calling
-<function>textdomain()</function>, since they'll be specifying
-the domain instead of using the default.
-For <function>dgettext()</function> the <function>_()</function> macro
-can be defined as:
+Libraries using gettext should use dgettext() instead of gettext(), which allows
+them to specify the translation domain each time they ask for a translation. Libraries
+should also avoid calling textdomain(), since they'll be specifying the domain instead
+of using the default.For dgettext() the _() macro can be defined as:
<informalexample>
<programlisting>
#define _(x) dgettext ("MyDomain", x)
More information about Unicode and UTF-8 can be found in the
<ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</ulink>.
GLib provides functions for converting strings between UTF-8 and other
- encodings, see
-<link linkend="g-locale-to-utf8">g_locale_to_utf8()</link> and <link
- linkend="g-convert">g_convert()</link>.
+ encodings, see g_locale_to_utf8() and g_convert().
</para>
<para>
Text coming from external sources (e.g. files or user input), has to be
<listitem><para>
If the string literals can be represented in an encoding which your toolchain
can handle (e.g. IS0-8859-1), you can write your source files in that encoding
-and use <link linkend="g-convert">g_convert()</link> to convert the strings to
-UTF-8 at runtime. Note that this has some runtime overhead, so you may want to
-move the conversion out of inner loops.
+and use g_convert() to convert the strings to UTF-8 at runtime. Note that this has
+some runtime overhead, so you may want to move the conversion out of inner loops.
</para></listitem>
</varlistentry>
</variablelist>
<answer>
<para>
-To load an image file straight into a display widget, use <link
-linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
-<footnote><para> If the file load fails, <link
-linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
-will display a "broken image" graphic — to detect a failed load
-yourself, use <link
-linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>
-directly then <link
-linkend="gtk-image-new-from-pixbuf">gtk_image_new_from_pixbuf()</link>.
-</para></footnote>. To load an image for another purpose, use <link
-linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>.
-To load an animation, use <link
-linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>.
-<link
-linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>
-can also load non-animated images, so use it in combination with
-<link
- linkend="gdk-pixbuf-animation-is-static-image">gdk_pixbuf_animation_is_static_image()</link> to load a file of unknown type.
+To load an image file straight into a display widget, use gtk_image_new_from_file()
+<footnote><para> If the file load fails, gtk_image_new_from_file() will display no
+image graphic — to detect a failed load yourself, use gdk_pixbuf_new_from_file()
+directly, then gtk_image_new_from_pixbuf().</para></footnote>.
+To load an image for another purpose, use gdk_pixbuf_new_from_file(). To load an
+animation, use gdk_pixbuf_animation_new_from_file().
+gdk_pixbuf_animation_new_from_file() can also load non-animated images, so use it
+in combination with gdk_pixbuf_animation_is_static_image() to load a file of unknown
+type.
</para>
<para>
To load an image or animation file asynchronously (without blocking), use
-<link linkend="GdkPixbufLoader">GdkPixbufLoader</link>.
+#GdkPixbufLoader.
</para>
</answer>
<answer>
<para>
-To draw a piece of text, use a Pango layout and
-<link linkend="gdk-draw-layout">gdk_draw_layout()</link>,
+To draw a piece of text, use a Pango layout and gdk_draw_layout(),
using code like the following:
<informalexample>
<programlisting>
g_object_unref (layout);
</programlisting>
</informalexample>
-Do not use the deprecated <link linkend="GdkFont">GdkFont</link> and <link linkend="gdk-draw-text">gdk_draw_text()</link>.
+Do not use the deprecated #GdkFont and gdk_draw_text().
</para>
<para>
<answer>
<para>
To obtain the size of a piece of text, use a Pango layout and
-<link
- linkend="pango-layout-get-pixel-size">pango_layout_get_pixel_size()</link>,
-using code like the following:
+pango_layout_get_pixel_size(), using code like the following:
<informalexample>
<programlisting>
layout = gtk_widget_create_pango_layout (widget, text);
g_object_unref (layout);
</programlisting>
</informalexample>
-Do not use the deprecated function <link linkend="gdk-text-width">gdk_text_width()</link>.
+Do not use the deprecated function gdk_text_width().
</para>
<para>
<answer>
<para>
See <link linkend="TreeWidget">tree widget overview</link> — you
-should use the <link linkend="GtkTreeView">GtkTreeView</link> widget.
-(A list is just a tree with no branches, so the tree widget is used
-for lists as well.) Do not use the deprecated widgets <link
-linkend="GtkTree">GtkTree</link> or <link
-linkend="GtkCList">GtkCList</link>/<link
-linkend="GtkCTree">GtkCTree</link> in newly-written code, they are
+should use the #GtkTreeView widget. (A list is just a tree with no branches,
+so the tree widget is used for lists as well.) Do not use the deprecated
+widgets #GtkTree or #GtkCList/#GtkCTree in newly-written code, they are
less flexible and result in an inferior user interface.
</para>
</answer>
<answer>
<para>
See <link linkend="TextWidget">text widget overview</link> — you
-should use the <link linkend="GtkTextView">GtkTextView</link> widget.
-Do not use the deprecated widget <link
-linkend="GtkText">GtkText</link> in newly-written code, it has a
-number of problems that are best avoided.
+should use the #GtkTextView widget. Do not use the deprecated widget #GtkText
+in newly-written code, it has a number of problems that are best avoided.
</para>
<para>
-If you only have a small amount of text, <link
-linkend="GtkLabel">GtkLabel</link> may also be appropriate of course.
-It can be made selectable with <link linkend="gtk-label-set-selectable">
-gtk_label_set_selectable()</link>. For a single-line text entry,
-see <link linkend="GtkEntry">GtkEntry</link>.
+If you only have a small amount of text, #GtkLabel may also be appropriate of course.
+It can be made selectable with gtk_label_set_selectable(). For a single-line text
+entry, see #GtkEntry.
</para>
</answer>
</qandaentry>
<answer>
<para>
-<link linkend="GtkImage">GtkImage</link> can display images
-in just about any format GTK+ understands. You can also
-use <link linkend="GtkDrawingArea">GtkDrawingArea</link> if you need
-to do something more complex, such as draw text or graphics over the
-top of the image.
+#GtkImage can display images in just about any format GTK+ understands. You can also
+use #GtkDrawingArea if you need to do something more complex, such as draw text or
+graphics over the top of the image.
</para>
</answer>
</qandaentry>
<answer>
<para>
-With GTK+, a <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
-recommended instead of a combo box, if the user is selecting from a
-fixed set of options. That is, non-editable combo boxes are not
-encouraged. <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
-much easier to use than <link linkend="GtkCombo">GtkCombo</link>
-as well. Use <link linkend="GtkCombo">GtkCombo</link> only when you
-need the editable text entry.
-</para>
-<para>
-(As a future enhancement to GTK+, a new widget to replace <link
-linkend="GtkOptionMenu">GtkOptionMenu</link> and <link
-linkend="GtkCombo">GtkCombo</link> is planned. This widget will be
-themeable to look like either a combo box or the current option menu,
-and will address some shortcomings in the <link
-linkend="GtkCombo">GtkCombo</link> API. <ulink
-url="http://bugzilla.gnome.org/show_bug.cgi?id=50554">Bug
-50554</ulink> tracks this issue, if you want to check status or post
-comments.)
+With GTK+, a #GtkComboBox is the recommended widget to use for this use case.
+This widget looks like either a combo box or the current option menu, depending
+on the current theme. If you need an editable text entry, use #GtkComboBoxEntry.
</para>
</answer>
</qandaentry>
</qandadiv>
-<qandadiv><title><link linkend="GtkWidget">GtkWidget</link></title>
+<qandadiv><title>#GtkWidget</title>
<qandaentry>
<question><para>
</para></question>
<answer><para>
-See <link linkend="gtk-widget-modify-fg">gtk_widget_modify_fg()</link>,
-<link linkend="gtk-widget-modify-bg">gtk_widget_modify_bg()</link>,
-<link linkend="gtk-widget-modify-base">gtk_widget_modify_base()</link>,
-and <link
-linkend="gtk-widget-modify-text">gtk_widget_modify_text()</link>. See
-<link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
-discussion. You can also change widget color by installing a resource
-file and parsing it with <link
-linkend="gtk-rc-add-default-file">gtk_rc_add_default_file()</link>.
+See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(),
+and gtk_widget_modify_text(). See <link linkend="gtk-Resource-Files">GTK+
+resource files</link> for more discussion. You can also change widget color by
+installing a resource file and parsing it with gtk_rc_add_default_file().
The advantage of a resource file is that users can then override the
color you've chosen.
</para>
-<para>To change the background color for widgets such as <link
-linkend="GtkLabel">GtkLabel</link> that have no background, place them
-in a <link linkend="GtkEventBox">GtkEventBox</link> and set the
-background of the event box.
+<para>To change the background color for widgets such as #GtkLabel that have no
+background, place them in a #GtkEventBox and set the background of the event box.
</para></answer>
</qandaentry>
</para></question>
<answer><para>
-This has several possible answers, depending on what exactly you want to
-achieve. One option is <link
-linkend="gtk-widget-modify-font">gtk_widget_modify_font()</link>. Note that this function can be used to change only the font size, as in the following example:
+This has several possible answers, depending on what exactly you want to achieve.
+One option is gtk_widget_modify_font(). Note that this function can be used to
+change only the font size, as in the following example:
<programlisting>
- PangoFontDesc *font_desc = pango_font_description_new ();
+ PangoFontDesc *font_desc = pango_font_description_new (<!-- -->);
pango_font_description_set_size (font_desc, 40);
gtk_widget_modify_font (widget, font);
pango_font_description_free (font_desc);
</programlisting>
</para>
<para>
-If you want to make the text of a label larger, you can use <link
-linkend="gtk-label-set-markup">gtk_label_set_markup()</link>:
+If you want to make the text of a label larger, you can use gtk_label_set_markup():
<programlisting>
gtk_label_set_markup (label, "<big>big text</big>");
</programlisting>
This is preferred for many apps because it's a relative size to the
-user's chosen font size. See <link
-linkend="g-markup-escape-text">g_markup_escape_text()</link>
-if you are constructing such strings on the fly.
+user's chosen font size. See g_markup_escape_text() if you are constructing such
+strings on the fly.
</para>
<para>
You can also change the font of a widget by putting
<programlisting>
gtk-font-name = "Sans 30"
</programlisting>
-in a resource file and parsing it with <link
-linkend="gtk-rc-add-default-file">gtk_rc_add_default_file()</link>.
-The advantage of a resource file is that users can then override the
-font you've chosen. See
+in a resource file and parsing it with gtk_rc_add_default_file(). The advantage of
+a resource file is that users can then override the font you've chosen. See
<link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
discussion.
</para>
</para></question>
<answer><para> In GTK+ a disabled widget is termed "insensitive." See
-<link
-linkend="gtk-widget-set-sensitive">gtk_widget_set_sensitive()</link>.
+gtk_widget_set_sensitive().
</para></answer>
</qandaentry>
</qandadiv>
-<qandadiv><title><link linkend="GtkTextView">GtkTextView</link></title>
+<qandadiv><title>#GtkTextView</title>
<qandaentry>
<question><para>
</para></question>
<answer><para>
-
-See <link
- linkend="gtk-text-buffer-get-bounds">gtk_text_buffer_get_bounds()</link>
- and <link
- linkend="gtk-text-buffer-get-text">gtk_text_buffer_get_text()</link>
-or <link
- linkend="gtk-text-iter-get-text">gtk_text_iter_get_text()</link>.
+See gtk_text_buffer_get_bounds() and gtk_text_buffer_get_text()
+or gtk_text_iter_get_text().
</para>
<para>
<informalexample><programlisting>
</para></question>
<answer><para>
-If you use <link
- linkend="gtk-text-buffer-insert-with-tags">gtk_text_buffer_insert_with_tags()</link> with appropriate tags to select the font, the inserted text will have the desired appearance, but text typed in by the user before or after the tagged block will appear in the default style.
+If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select the
+font, the inserted text will have the desired appearance, but text typed in by the
+user before or after the tagged block will appear in the default style.
</para>
<para>
-To ensure that all text has the desired appearance, use <link
- linkend="gtk-widget-modify-font">gtk_widget_modify_font()</link> to change the default font for the widget.
+To ensure that all text has the desired appearance, use gtk_widget_modify_font()
+to change the default font for the widget.
</para></answer>
</qandaentry>
<answer>
<para>
The "insert" <link linkend="GtkTextMark">mark</link> marks the insertion point
-where <link linkend="gtk-text-buffer-insert">gtk_text_buffer_insert()</link>
-inserts new text into the buffer. The text is inserted
+where gtk_text_buffer_insert() inserts new text into the buffer. The text is inserted
<emphasis>before</emphasis> the "insert" mark, so that it generally stays
at the end of the buffer. If it gets explicitly moved to some other position,
-e.g. when the user selects some text,
-use <link linkend="gtk-text-buffer-move-mark">gtk_text_buffer_move_mark()</link>
-to set it to the desired location before inserting more text.
-The "insert" mark of a buffer can be obtained with <link
-linkend="gtk-text-buffer-get-insert">gtk_text_buffer_get_insert()</link>.
+e.g. when the user selects some text, use gtk_text_buffer_move_mark() to set it to
+the desired location before inserting more text. The "insert" mark of a buffer can be
+obtained with gtk_text_buffer_get_insert().
</para>
<para>
To ensure that the end of the buffer remains visible, use
-<link
- linkend="gtk-text-view-scroll-to-mark">gtk_text_view_scroll_to_mark()</link> to scroll to the "insert" mark after inserting new text.
+gtk_text_view_scroll_to_mark() to scroll to the "insert" mark after inserting new text.
</para>
</answer>
</qandaentry>
-<qandadiv><title><link linkend="GtkTreeView">GtkTreeView</link></title>
+<qandadiv><title>#GtkTreeView</title>
<qandaentry>
<question><para>
<answer>
<para>
-Remember that the <link linkend="GtkTreeModel">GtkTreeModel</link>
-columns don't necessarily have to be displayed. So you can put
-non-user-visible data in your model just like any other data, and
-retrieve it with <link
-linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
-See the <link linkend="TreeWidget">tree widget overview</link>.
+Remember that the #GtkTreeModel columns don't necessarily have to be displayed.
+So you can put non-user-visible data in your model just like any other data, and
+retrieve it with gtk_tree_model_get(). See the
+<link linkend="TreeWidget">tree widget overview</link>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question><para>
-What's the <link linkend="GtkTreeView">GtkTreeView</link> equivalent of
-<link linkend="gtk-clist-find-row-from-data">gtk_clist_find_row_from_data()</link>?
+What's the #GtkTreeView equivalent of gtk_clist_find_row_from_data()?
</para></question>
<answer>
<para>
-As there is no separate data column in the <link linkend="GtkTreeModel">GtkTreeModel</link>, there's no
+As there is no separate data column in the #GtkTreeModel, there's no
built in function to find the iter from data. You can write a custom
searching function to walk the tree and find the data, or use
-<link linkend="gtk-tree-model-foreach">gtk_tree_model_foreach()</link>.
+gtk_tree_model_foreach().
</para>
</answer>
</qandaentry>
<answer>
<para>
-You can pack more than one <link
-linkend="GtkCellRenderer">GtkCellRenderer</link> into a single
-<link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> using
-<link
- linkend="gtk-tree-view-column-pack-start">gtk_tree_view_column_pack_start()</link> or <link linkend="gtk-tree-view-column-pack-end">gtk_tree_view_column_pack_end()</link>. So pack both a <link
-linkend="GtkCellRendererPixbuf">GtkCellRendererPixbuf</link>
-and a <link
-linkend="GtkCellRendererText">GtkCellRendererText</link> into the
-column.
+You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn using
+gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). So pack both
+a #GtkCellRendererPixbuf and a #GtkCellRendererText into the column.
</para>
</answer>
</qandaentry>
<qandaentry>
<question><para>
-I can set data easily on my <link
- linkend="GtkTreeStore">GtkTreeStore</link>/<link
- linkend="GtkListStore">GtkListStore</link> models using <link
-linkend="gtk-tree-model-get">gtk_list_store_set()</link> and <link
-linkend="gtk-tree-model-get">gtk_tree_store_set()</link>, but can't read
- it back?
+I can set data easily on my #GtkTreeStore/#GtkListStore models using
+gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
</para></question>
<answer>
<para>
-Both the <link
- linkend="GtkTreeStore">GtkTreeStore</link> and the <link
- linkend="GtkListStore">GtkListStore</link> implement the
- <link linkend="GtkTreeModel">GtkTreeModel</link>
- interface. Consequentially, the can use any function
- this interface implements. The easiest way to read a
- set of data back is to use
- <link
-linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
+Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
+interface. Consequentially, the can use any function this interface implements.
+The easiest way to read a set of data back is to use gtk_tree_model_get().
</para>
</answer>
</qandaentry>
<qandaentry>
<question><para>
-How do I change the way that numbers are formatted by <link linkend="GtkTreeView">GtkTreeView</link>?
+How do I change the way that numbers are formatted by #GtkTreeView?
</para></question>
<answer><para>
-Use <link linkend="gtk-tree-view-insert-column-with-data-func">gtk_tree_view_insert_column_with_data_func()</link>
-or <link linkend="gtk-tree-view-column-set-cell-data-func">gtk_tree_view_column_set_cell_data_func()</link>
-and do the conversion from number to string yourself (with, say,
-<link linkend="g-strdup-printf">g_strdup_printf()</link>).
+Use gtk_tree_view_insert_column_with_data_func()
+or gtk_tree_view_column_set_cell_data_func() and do the conversion from number to
+string yourself (with, say, g_strdup_printf()).
</para>
<para>
gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns));
/* Create a GtkCellRendererText */
- renderer = gtk_cell_renderer_text_new ();
+ renderer = gtk_cell_renderer_text_new (<!-- -->);
/* Create a new column that has a title ("Example column"),
* uses the above created renderer that will render the double
* value into text from the associated model's rows.
*/
- column = gtk_tree_view_column_new ();
+ column = gtk_tree_view_column_new (<!-- -->);
gtk_tree_view_column_set_title (column, "Example column");
- renderer = gtk_cell_renderer_text_new ();
+ renderer = gtk_cell_renderer_text_new (<!-- -->);
gtk_tree_view_column_pack_start (column, renderer, TRUE);
/* Append the new column after the GtkTreeView's previous columns. */
<answer><para>
Set the expander-column property of the tree view to a hidden column.
-See <link linkend="gtk-tree-view-set-expander-column">gtk_tree_view_set_expander_column()</link> and <link linkend="gtk-tree-view-column-set-visible">gtk_tree_view_column_set_visible()</link>.
+See gtk_tree_view_set_expander_column() and gtk_tree_view_column_set_visible().
</para></answer>
</qandaentry>
</refmeta>
<refnamediv>
-<refname>Text Widget Overview</refname><refpurpose>Overview of <link linkend="GtkTextBuffer">GtkTextBuffer</link>, <link linkend="GtkTextView">GtkTextView</link>, and friends</refpurpose>
+<refname>Text Widget Overview</refname>
+<refpurpose>Overview of #GtkTextBuffer, #GtkTextView, and friends</refpurpose>
</refnamediv>
<refsect1>
<para>
GTK+ has an extremely powerful framework for multiline text editing. The
-primary objects involved in the process are <link
-linkend="GtkTextBuffer">GtkTextBuffer</link>, which represents the text being
-edited, and <link linkend="GtkTextView">GtkTextView</link>, a widget which can
-display a <link linkend="GtkTextBuffer">GtkTextBuffer</link>. Each buffer can
-be displayed by any number of views.
+primary objects involved in the process are #GtkTextBuffer, which represents the
+text being edited, and #GtkTextView, a widget which can display a #GtkTextBuffer.
+Each buffer can be displayed by any number of views.
</para>
<para>
concept is more general than that; tags don't have to affect appearance. They
can instead affect the behavior of mouse and key presses, "lock" a range of
text so the user can't edit it, or countless other things. A tag is
-represented by a
-<link linkend="GtkTextTag">GtkTextTag</link> object. One <link
-linkend="GtkTextTag">GtkTextTag</link> can be applied to any number of text
-ranges in any number of buffers.
+represented by a #GtkTextTag object. One #GtkTextTag can be applied to any number
+of text ranges in any number of buffers.
</para>
<para>
-Each tag is stored in a <link
-linkend="GtkTextTagTable">GtkTextTagTable</link>. A tag table defines a set of
+Each tag is stored in a #GtkTextTagTable. A tag table defines a set of
tags that can be used together. Each buffer has one tag table associated with
it; only tags from that tag table can be used with the buffer. A single tag
table can be shared between multiple buffers, however.
<para>
Most text manipulation is accomplished with <firstterm>iterators</firstterm>,
-represented by a <link linkend="GtkTextIter">GtkTextIter</link>. An iterator
-represents a position between two characters in the text buffer. <link
-linkend="GtkTextIter">GtkTextIter</link> is a struct designed to be allocated
+represented by a #GtkTextIter. An iterator represents a position between two
+characters in the text buffer. #GtkTextIter is a struct designed to be allocated
on the stack; it's guaranteed to be copiable by value and never contain any
heap-allocated data. Iterators are not valid indefinitely; whenever the buffer
is modified in a way that affects the number of characters in the buffer, all
<para>
Because of this, iterators can't be used to preserve positions across buffer
-modifications. To preserve a position, the <link
-linkend="GtkTextMark">GtkTextMark</link> object is ideal. You can think of a
-mark as an invisible cursor or insertion point; it floats in the buffer, saving
-a position. If the text surrounding the mark is deleted, the mark remains in
-the position the text once occupied; if text is inserted at the mark, the
+modifications. To preserve a position, the #GtkTextMark object is ideal. You can
+think of a mark as an invisible cursor or insertion point; it floats in the buffer,
+saving a position. If the text surrounding the mark is deleted, the mark remains
+in the position the text once occupied; if text is inserted at the mark, the
mark ends up either to the left or to the right of the new text, depending on
its <firstterm>gravity</firstterm>. The standard text cursor in left-to-right
languages is a mark with right gravity, because it stays to the right of
<para>
Like tags, marks can be either named or anonymous. There are two marks built-in
-to <link linkend="GtkTextBuffer">GtkTextBuffer</link>; these are named
-<literal>"insert"</literal> and <literal>"selection_bound"</literal> and refer
-to the insertion point and the boundary of the selection which is not the
-insertion point, respectively. If no text is selected, these two marks will be
-in the same position. You can manipulate what is selected and where the cursor
-appears by moving these marks around.
+to #GtkTextBuffer; these are named <literal>"insert"</literal> and
+<literal>"selection_bound"</literal> and refer to the insertion point and the
+boundary of the selection which is not the insertion point, respectively. If no
+text is selected, these two marks will be in the same position. You can manipulate
+what is selected and where the cursor appears by moving these marks around.
<footnote>
<para>
If you want to place the cursor in response to a user action, be sure to use
-<link
-linkend="gtk-text-buffer-place-cursor">gtk_text_buffer_place_cursor()</link>,
-which moves both at once
-without causing a temporary selection (moving one then the other temporarily
-selects the range in between the old and new positions).
+gtk_text_buffer_place_cursor(), which moves both at once without causing a
+temporary selection (moving one then the other temporarily selects the range in
+between the old and new positions).
</para>
</footnote>
</para>
<title>Simple Example</title>
<para>
-The simplest usage of <link linkend="GtkTextView">GtkTextView</link>
-might look like this:
+The simplest usage of #GtkTextView might look like this:
<informalexample><programlisting>
GtkWidget *view;
GtkTextBuffer *buffer;
- view = gtk_text_view_new ();
+ view = gtk_text_view_new (<!-- -->);
buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view));
* will be emitted, such as "changed", "insert_text", and so on.
*/
</programlisting></informalexample>
-In many cases it's also convenient to first create the buffer with <link
-linkend="gtk-text-buffer-new">gtk_text_buffer_new()</link>, then create a
-widget for that buffer with <link linkend="gtk-text-view-new-with-buffer">gtk_text_view_new_with_buffer()</link>.
-Or you can change the buffer the widget displays after the widget is created
-with <link linkend="gtk-text-view-set-buffer">gtk_text_view_set_buffer()</link>.
+In many cases it's also convenient to first create the buffer with
+gtk_text_buffer_new(), then create a widget for that buffer with
+gtk_text_view_new_with_buffer(). Or you can change the buffer the widget
+displays after the widget is created with gtk_text_view_set_buffer().
</para>
</refsect1>
<para>
-There are two ways to affect text attributes in
-<link linkend="GtkTextView">GtkTextView</link>.
-You can change the default attributes for a given
-<link linkend="GtkTextView">GtkTextView</link>, and you can
-apply tags that change the attributes for a region of text.
-For text features that come from the theme — such as
-font and foreground color — use standard
-<link linkend="GtkWidget">GtkWidget</link>
-functions such as
-<link linkend="gtk-widget-modify-font">gtk_widget_modify_font()</link>
-or
-<link linkend="gtk-widget-modify-text">gtk_widget_modify_text()</link>.
-For other attributes there are dedicated methods on
-<link linkend="GtkTextView">GtkTextView</link> such as
-<link linkend="gtk-text-view-set-tabs">gtk_text_view_set_tabs()</link>.
+There are two ways to affect text attributes in #GtkTextView.
+You can change the default attributes for a given #GtkTextView, and you can
+apply tags that change the attributes for a region of text. For text features
+that come from the theme — such as font and foreground color — use
+standard #GtkWidget functions such as gtk_widget_modify_font() or
+gtk_widget_modify_text(). For other attributes there are dedicated methods on
+#GtkTextView such as gtk_text_view_set_tabs().
<informalexample><programlisting>
GtkWidget *view;
GdkColor color;
GtkTextTag *tag;
- view = gtk_text_view_new ();
+ view = gtk_text_view_new (<!-- -->);
buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view));
<para>
The <application>gtk-demo</application> application that comes with
-GTK+ contains more example code for <link
-linkend="GtkTextView">GtkTextView</link>.
+GTK+ contains more example code for #GtkTextView.
</para>
</refsect1>
projects / ~andy / gtk / commitdiff