callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More abbreviation conversion

Browse Source
This commit is contained in:
Matthias Clasen
2005-05-16 19:34:39 +00:00
parent 7b0e05fcca
commit ce16af5a93
12 changed files with 325 additions and 518 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/reference/gtk/Makefile.am
View File

@ -111,7 +111,17 @@ content_files = \
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 = \

70
docs/reference/gtk/glossary.xml
View File

@ -24,7 +24,7 @@
<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>
@ -48,10 +48,9 @@
<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.
@ -69,14 +68,11 @@
<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>
@ -94,8 +90,7 @@
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>
@ -130,15 +125,13 @@
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
@ -155,7 +148,7 @@
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>
@ -170,17 +163,13 @@
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>
@ -192,11 +181,8 @@
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>
@ -224,17 +210,14 @@
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>
@ -276,8 +259,7 @@
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>
@ -298,9 +280,8 @@
<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>
@ -323,7 +304,7 @@
<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>
@ -362,8 +343,7 @@
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>

20
docs/reference/gtk/gtk-docs.sgml
View File

@ -175,7 +175,7 @@
<!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">
@ -184,20 +184,20 @@
<!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>

19
docs/reference/gtk/migrating-GtkAboutDialog.sgml
View File

@ -3,15 +3,13 @@
<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>
@ -56,9 +54,9 @@
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>
@ -82,9 +80,8 @@
</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>

112
docs/reference/gtk/migrating-GtkAction.sgml
View File

@ -15,40 +15,35 @@
<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
@ -72,22 +67,20 @@
<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>
@ -102,8 +95,7 @@
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>
@ -113,8 +105,7 @@
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>
@ -142,11 +133,9 @@
<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>
@ -154,27 +143,22 @@
<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>
@ -184,8 +168,8 @@
<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>
@ -269,15 +253,12 @@ static GnomeUIInfo menubar[] = {
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>"&lt;ontrol&gt;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>"&lt;ontrol&gt;O"</literal>.
</para>
<programlisting>
@ -311,9 +292,8 @@ static GtkRadioActionEntry radio_entries[] = {
<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
@ -349,16 +329,12 @@ static const char *ui_description =
<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>
@ -370,7 +346,7 @@ GtkUIManager *ui_manager;
GtkAccelGroup *accel_group;
GError *error;
register_my_stock_icons ();
register_my_stock_icons (<!-- -->);
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
@ -382,7 +358,7 @@ gtk_action_group_add_actions (action_group, entries, G_N_ELEMENTS (entries), win
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);
@ -431,12 +407,12 @@ register_my_stock_icons (void)
GtkIconSource *icon_source;
gint i;
icon_factory = gtk_icon_factory_new ();
icon_factory = gtk_icon_factory_new (<!-- -->);
for (i = 0; i &lt; 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);

5
docs/reference/gtk/migrating-GtkColorButton.sgml
View File

@ -3,10 +3,9 @@
<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>

76
docs/reference/gtk/migrating-GtkComboBox.sgml
View File

@ -1,21 +1,18 @@
<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 &mdash; menu or list &mdash;
is no longer done at the API level, but has been made themeable via
@ -28,12 +25,12 @@
<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);
@ -48,23 +45,22 @@ gtk_widget_show (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>
@ -73,8 +69,8 @@ gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item");
<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));
@ -93,8 +89,7 @@ gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu);
</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;
@ -112,13 +107,13 @@ gtk_list_store_set (store, &amp;iter, 0, pixbuf3, 1, "Third Item", -1);
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,
@ -131,8 +126,7 @@ gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer,
<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;
@ -141,7 +135,7 @@ items = g_list_append (items, "First Item");
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"
@ -150,9 +144,9 @@ gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
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");
@ -170,8 +164,7 @@ gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third 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>
@ -181,29 +174,26 @@ gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item");
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>

72
docs/reference/gtk/migrating-GtkFileChooser.sgml
View File

@ -14,30 +14,20 @@
<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>
@ -45,10 +35,8 @@
<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
@ -66,25 +54,21 @@
<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
@ -99,10 +83,8 @@
<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>
@ -132,18 +114,15 @@
<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>
@ -166,9 +145,8 @@
</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>

40
docs/reference/gtk/migrating-GtkIconView.sgml
View File

@ -3,10 +3,8 @@
<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
@ -14,19 +12,17 @@
</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>
@ -81,7 +77,7 @@
/* 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);
@ -93,18 +89,15 @@
/* ... */
}
</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>
@ -124,7 +117,7 @@
}
</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>
@ -140,8 +133,7 @@
<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>

20
docs/reference/gtk/migrating-checklist.sgml
View File

@ -51,7 +51,7 @@ do_popup_menu (GtkWidget *my_widget, GdkEventButton *event)
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);
@ -65,7 +65,7 @@ do_popup_menu (GtkWidget *my_widget, GdkEventButton *event)
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,
@ -127,7 +127,7 @@ my_widget_popup_menu_handler (GtkWidget *widget)
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>
@ -138,9 +138,8 @@ my_widget_popup_menu_handler (GtkWidget *widget)
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>
@ -218,7 +217,7 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
<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
@ -233,8 +232,7 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
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>,
@ -254,7 +252,7 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
<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>
@ -271,7 +269,7 @@ my_widget_key_press_event_handler (GtkWidget *widget, GdkEventKey *event)
{
guint modifiers;
modifiers = gtk_accelerator_get_default_mod_mask ();
modifiers = gtk_accelerator_get_default_mod_mask (<!-- -->);
if (event-&gt;keysym == GDK_F10
&amp;&amp; (event-&gt;state &amp; modifiers) == GDK_CONTROL_MASK)

303
docs/reference/gtk/question_index.sgml
View File

@ -96,22 +96,17 @@ from functions?
<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).
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 <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
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>
@ -193,12 +188,10 @@ or Linux system with gettext installed, type <literal>info
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>
@ -206,13 +199,10 @@ follows for convenience:
#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:
@ -238,14 +228,10 @@ 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)
@ -285,9 +271,7 @@ The zero byte doesn't occur as part of a character, so that UTF-8 strings can
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
@ -343,9 +327,8 @@ very convenient. Be careful when mixing hexadecimal escapes with ordinary text;
<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>
@ -429,28 +412,19 @@ How do I load an image or animation from a file?
<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 &mdash; 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 &mdash; 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>
@ -463,8 +437,7 @@ How do I draw text ?
<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>
@ -476,7 +449,7 @@ using code like the following:
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>
@ -498,9 +471,7 @@ How do I measure the size of a piece of text ?
<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);
@ -511,7 +482,7 @@ using code like the following:
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>
@ -558,12 +529,9 @@ volatile GType dummy = GTK_TYPE_BLAH;
<answer>
<para>
See <link linkend="TreeWidget">tree widget overview</link> &mdash; 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>
@ -577,17 +545,13 @@ less flexible and result in an inferior user interface.
<answer>
<para>
See <link linkend="TextWidget">text widget overview</link> &mdash; 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>
@ -600,11 +564,9 @@ see <link linkend="GtkEntry">GtkEntry</link>.
<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>
@ -617,31 +579,16 @@ would use a combo box?
<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>
@ -649,23 +596,16 @@ How do I change the color of a widget?
</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>
@ -675,36 +615,32 @@ How do I change the font of a widget?
</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, "&lt;big&gt;big text&lt;/big&gt;");
</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>
@ -717,15 +653,14 @@ How do I disable/ghost/desensitize a widget?
</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>
@ -733,13 +668,8 @@ How do I get the contents of the entire text widget as a string?
</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>
@ -762,12 +692,13 @@ How do I make a text widget display its complete contents in a specific font?
</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>
@ -781,21 +712,17 @@ How do I make a text view scroll to the end of the buffer automatically ?
<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>
@ -803,7 +730,7 @@ To ensure that the end of the buffer remains visible, use
<qandadiv><title><link linkend="GtkTreeView">GtkTreeView</link></title>
<qandadiv><title>#GtkTreeView</title>
<qandaentry>
<question><para>
@ -812,28 +739,25 @@ How do I associate some data with a row in the tree?
<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>
@ -845,53 +769,36 @@ How do I put an image and some text in the same column?
<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>
@ -937,15 +844,15 @@ set_up_new_columns (GtkTreeView *myview)
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. */
@ -972,7 +879,7 @@ How do I hide the expander arrows in my tree view ?
<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>

94
docs/reference/gtk/text_widget.sgml
View File

@ -6,7 +6,8 @@
</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>
@ -14,11 +15,9 @@
<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>
@ -38,15 +37,12 @@ be called "bold" and make the text inside the tag bold. However, the tag
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.
@ -60,9 +56,8 @@ is convenient if you're creating tags on-the-fly).
<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
@ -73,11 +68,10 @@ number of characters you pass through a state with a different number).
<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
@ -86,21 +80,18 @@ inserted text.
<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>
@ -123,13 +114,12 @@ considered a line separator.
<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));
@ -140,11 +130,10 @@ might look like this:
* 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>
@ -154,21 +143,13 @@ with <link linkend="gtk-text-view-set-buffer">gtk_text_view_set_buffer()</link>.
<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 &mdash; such as
font and foreground color &mdash; 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 &mdash; such as font and foreground color &mdash; 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;
@ -178,7 +159,7 @@ For other attributes there are dedicated methods on
GdkColor color;
GtkTextTag *tag;
view = gtk_text_view_new ();
view = gtk_text_view_new (<!-- -->);
buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view));
@ -208,8 +189,7 @@ For other attributes there are dedicated methods on
<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>