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

Put explicit <link> elements instead of #Symbol, because the latter

Browse Source 
2004-02-27  Federico Mena Quintero  <federico@ximian.com>

	* gtk/migrating-GtkAction.sgml: Put explicit <link> elements
	instead of #Symbol, because the latter doesn't get substituted by
	gtk-doc outside of template files.  Thanks to Matthias for
	pointing this out.

	* gtk/migrating-GtkFileChooser.sgml: Likewise.

	* gtk/gtk-sections.txt: Removed gtk_file_chooser_{set,get}_folder_mode.
This commit is contained in:
Federico Mena Quintero
2004-02-27 22:06:40 +00:00
committed by Federico Mena Quintero
parent 9ab57a8f29
commit c5fe469c82
4 changed files with 135 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/reference/ChangeLog
View File

@ -1,3 +1,14 @@
2004-02-27 Federico Mena Quintero <federico@ximian.com>
* gtk/migrating-GtkAction.sgml: Put explicit <link> elements
instead of #Symbol, because the latter doesn't get substituted by
gtk-doc outside of template files. Thanks to Matthias for
pointing this out.
* gtk/migrating-GtkFileChooser.sgml: Likewise.
* gtk/gtk-sections.txt: Removed gtk_file_chooser_{set,get}_folder_mode.
Fri Feb 27 22:51:35 2004 Matthias Clasen <maclas@gmx.de> Fri Feb 27 22:51:35 2004 Matthias Clasen <maclas@gmx.de>
* gtk/tmpl/gtkoptionmenu.sgml: * gtk/tmpl/gtkoptionmenu.sgml:

2
docs/reference/gtk/gtk-sections.txt
View File

@ -1112,8 +1112,6 @@ GtkFileChooserError
gtk_file_chooser_error_quark gtk_file_chooser_error_quark
gtk_file_chooser_set_action gtk_file_chooser_set_action
gtk_file_chooser_get_action gtk_file_chooser_get_action
gtk_file_chooser_set_folder_mode
gtk_file_chooser_get_folder_mode
gtk_file_chooser_set_local_only gtk_file_chooser_set_local_only
gtk_file_chooser_get_local_only gtk_file_chooser_get_local_only
gtk_file_chooser_set_select_multiple gtk_file_chooser_set_select_multiple

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

@ -15,36 +15,40 @@
<para> <para>
Prior to GTK+ 2.4, there were several APIs in use to create menus Prior to GTK+ 2.4, there were several APIs in use to create menus
and toolbars. GTK+ itself included #GtkItemFactory, which was and toolbars. GTK+ itself included <link
linkend="GtkItemFactory">GtkItemFactory</link>, which was
historically used in the GIMP; libgnomeui provided the gnome-ui historically used in the GIMP; libgnomeui provided the gnome-ui
set of macros; libbonoboui provided a complex mechanism to do menu set of macros; libbonoboui provided a complex mechanism to do menu
merging across embedded components. GTK+ 2.4 includes a system merging across embedded components. GTK+ 2.4 includes a system
for creating menus and toolbars, with merging of items, based for creating menus and toolbars, with merging of items, based
around the #GtkAction mechanism. around the <link linkend="GtkAction">GtkAction</link> mechanism.
</para> </para>
<section id="actions-and-action-groups"> <section id="actions-and-action-groups">
<title>Actions and Action Groups</title> <title>Actions and Action Groups</title>
<para> <para>
A #GtkAction represents an operation that the user can perform A <link linkend="GtkAction">GtkAction</link> represents an
from the menus and toolbars of an application. It is similar to operation that the user can perform from the menus and toolbars
"verbs" in other menu systems. A #GtkAction has a name, which of an application. It is similar to "verbs" in other menu
is its identifier, and it can have several widgets that systems. A <link linkend="GtkAction">GtkAction</link> has a
represent it in the user interface. For example, an action for name, which is its identifier, and it can have several widgets
<symbol>EditCopy</symbol> can have a menu item as well as a 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 toolbar button associated to it. If there is nothing selected
in the document, the application can simply de-sensitize the in the document, the application can simply de-sensitize the
<symbol>EditCopy</symbol> action; this will cause both the menu <symbol>EditCopy</symbol> action; this will cause both the menu
item and the toolbar button to be de-sensitized automatically. item and the toolbar button to be de-sensitized automatically.
Similarly, whenever the user selects the menu item or the Similarly, whenever the user selects the menu item or the
toolbar button associated to the <symbol>EditCopy</symbol> toolbar button associated to the <symbol>EditCopy</symbol>
action, the corresponding #GtkAction object will emit an action, the corresponding <link
linkend="GtkAction">GtkAction</link> object will emit an
"activate" signal. "activate" signal.
</para> </para>
<para> <para>
#GtkActionGroup is simply a group of #GtkAction objects. An <link linkend="GtkActionGroup">GtkActionGroup</link> is simply a
group of <link linkend="GtkAction">GtkAction</link> objects. An
application may want to have several groups: one for global application may want to have several groups: one for global
actions such as "new document", "about", and "exit"; then one actions such as "new document", "about", and "exit"; then one
group for each open document with actions specific to the group for each open document with actions specific to the
@ -68,20 +72,22 @@
<title>User Interface Manager Object</title> <title>User Interface Manager Object</title>
<para> <para>
#GtkUIManager is an object that can construct menu and toolbar <link linkend="GtkUIManager">GtkUIManager</link> is an object
widgets from an XML description. These widgets are in turn that can construct menu and toolbar widgets from an XML
associated to corresponding actions and action groups. description. These widgets are in turn associated to
corresponding actions and action groups.
</para> </para>
<para> <para>
#GtkUIManager supports merging of menus and toolbars for <link linkend="GtkUIManager">GtkUIManager</link> supports
applications that have multiple components, each with separate merging of menus and toolbars for applications that have
sets of commands. For example, a word processor that can embed multiple components, each with separate sets of commands. For
images may want to have toolbar buttons for Bold and Italic when example, a word processor that can embed images may want to have
the cursor is on a text block, but Crop and Brightness/Contrast toolbar buttons for Bold and Italic when the cursor is on a text
buttons when the cursor is on an image. These actions, which block, but Crop and Brightness/Contrast buttons when the cursor
change depending on the state of the application, can be merged is on an image. These actions, which change depending on the
and de-merged from a #GtkUIManager as appropriate. state of the application, can be merged and de-merged from a
<link linkend="GtkUIManager">GtkUIManager</link> as appropriate.
</para> </para>
</section> </section>
@ -135,25 +141,28 @@
<listitem> <listitem>
<para> <para>
Separate your existing GnomeUIInfo entries into normal Separate your existing GnomeUIInfo entries into normal
actions, toggle actions, and radio actions, and then create a actions, toggle actions, and radio actions, and then create
separate array of #GtkActionEntry structures for each a separate array of <link
group. This will allow you to create the necessary linkend="GtkActionEntry">GtkActionEntry</link> structures
#GtkActionGroup objects. Note that this does not describe for each group. This will allow you to create the necessary
the actual "shape" that your menus and toolbars will have; <link linkend="GtkActionGroup">GtkActionGroup</link>
it simply defines the set of commands that will appear in them. 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> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Create an XML description of your menus and toolbars for use Create an XML description of your menus and toolbars for use
with #GtkUIManager. This defines the actual shape of the with <link linkend="GtkUIManager">GtkUIManager</link>. This
menus and toolbars. defines the actual shape of the menus and toolbars.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Port the code that uses gnome-app and gnome-app-helper to Port the code that uses gnome-app and gnome-app-helper to
#GtkAction and #GtkUIManager. <link linkend="GtkAction">GtkAction</link> and <link
linkend="GtkUIManager">GtkUIManager</link>.
</para> </para>
</listitem> </listitem>
</orderedlist> </orderedlist>
@ -248,14 +257,14 @@ static GnomeUIInfo menubar[] = {
The following code is the set of actions that are present in The following code is the set of actions that are present in
the <link linkend="gnomeuiinfo-example">previous the <link linkend="gnomeuiinfo-example">previous
example</link>. Note that the toggle and radio entries are example</link>. Note that the toggle and radio entries are
separate from normal actions. Also, note that #GtkActionEntry separate from normal actions. Also, note that <link
structures take key names in the format of linkend="GtkActionEntry">GtkActionEntry</link> structures take
gdk_accelerator_parse() rather than key values plus modifiers; key names in the format of gdk_accelerator_parse() rather than
you will have to convert these values by hand. For example, key values plus modifiers; you will have to convert these
<constant>GDK_F11</constant> with no modifiers is equivalent values by hand. For example, <constant>GDK_F11</constant>
to a key name of <literal>"F11"</literal>. Likewise, with no modifiers is equivalent to a key name of
<literal>"o"</literal> with <literal>"F11"</literal>. Likewise, <literal>"o"</literal>
<constant>GDK_CONTROL_MASK</constant> is equivalent to with <constant>GDK_CONTROL_MASK</constant> is equivalent to
<literal>"&lt;ontrol&gt;O"</literal>. <literal>"&lt;ontrol&gt;O"</literal>.
</para> </para>
@ -290,15 +299,15 @@ static GtkRadioActionEntry radio_entries[] = {
<para> <para>
After extracting the actions, you will need to create an XML After extracting the actions, you will need to create an XML
description of the actual layout of your menus and toolbars description of the actual layout of your menus and toolbars
for use with #GtkUIManager. The following code shows a simple for use with <link linkend="GtkUIManager">GtkUIManager</link>.
menu bar that corresponds to the <link The following code shows a simple menu bar that corresponds to
linkend="gnomeuiinfo-example">previous example</link>. Note the <link linkend="gnomeuiinfo-example">previous
that the <guimenu>File</guimenu> and <guimenu>View</guimenu> example</link>. Note that the <guimenu>File</guimenu> and
menus have their names specified in the <link <guimenu>View</guimenu> menus have their names specified in
linkend="gnomeuiinfo-action-entries">action entries</link>, the <link linkend="gnomeuiinfo-action-entries">action
not in the XML itself. This is because the XML description entries</link>, not in the XML itself. This is because the
only contains <emphasis>identifiers</emphasis> for the items XML description only contains <emphasis>identifiers</emphasis>
in the GUI, rather than human-readable names. for the items in the GUI, rather than human-readable names.
</para> </para>
<programlisting> <programlisting>
@ -328,13 +337,16 @@ static const char *ui_description =
<title>Creating the Menu Bar</title> <title>Creating the Menu Bar</title>
<para> <para>
In this last example, we will create a #GtkActionGroup based In this last example, we will create a <link
on the <link linkend="gnomeuiinfo-action-entries">action linkend="GtkActionGroup">GtkActionGroup</link> based on the
entries</link> we created above. We will then create a <link linkend="gnomeuiinfo-action-entries">action
#GtkUIManager with the <link linkend="gnomeuiinfo-xml">XML entries</link> we created above. We will then create a <link
description</link> of the menu layout. We will also extract linkend="GtkUIManager">GtkUIManager</link> with the <link
the accelerator group and the widgets from the #GtkUIManager linkend="gnomeuiinfo-xml">XML description</link> of the menu
put them into a window. layout. We will also extract the accelerator group and the
widgets from the <link
linkend="GtkUIManager">GtkUIManager</link> put them into a
window.
</para> </para>
<programlisting> <programlisting>

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

@ -14,33 +14,42 @@
<title>Migrating from GtkFileSelection to GtkFileChooser</title> <title>Migrating from GtkFileSelection to GtkFileChooser</title>
<para> <para>
#GtkFileChooser, starting with GTK+ 2.4, is the new set of APIs <link linkend="GtkFileChooser">GtkFileChooser</link>, starting
for file selection widgets and dialogs. Previous versions of GTK+ with GTK+ 2.4, is the new set of APIs for file selection widgets
used #GtkFileSelection, which has numerous problems. and dialogs. Previous versions of GTK+ used <link
linkend="GtkFileSelection">GtkFileSelection</link>, which has
numerous problems.
</para> </para>
<para> <para>
#GtkFileChooser is an abstract interface that can be implemented <link linkend="GtkFileChooser">GtkFileChooser</link> is an
by widgets that perform file selection tasks. Two widgets in GTK+ abstract interface that can be implemented by widgets that perform
implement this interface: #GtkFileChooserDialog and file selection tasks. Two widgets in GTK+ implement this
#GtkFileChooserWidget. Most applications simply need to use interface: <link
#GtkFileChooserDialog, which is a dialog box that allows the user linkend="GtkFileChooserDialog">GtkFileChooserDialog</link> and
to select existing files for opening them, or to pick new <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>.
filenames for saving documents. #GtkFileChooserWidget is for Most applications simply need to use <link
special applications that need to embed a file selection widget linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>, which
inside a larger window. In the context of GTK+, is a dialog box that allows the user to select existing files for
#GtkFileChooserDialog is simply a #GtkDialog box with a opening them, or to pick new filenames for saving documents.
#GtkFileChooserWidget inside. <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>
inside.
</para> </para>
<section id="gtkfilechooser-creating"> <section id="gtkfilechooser-creating">
<title>Creating a GtkFileChooserDialog</title> <title>Creating a GtkFileChooserDialog</title>
<para> <para>
To create a #GtkFileChooserDialog, you simply call To create a <link
gtk_file_chooser_dialog_new(). This function is similar to linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>, you
gtk_dialog_new() in that it takes parameters for the title simply call gtk_file_chooser_dialog_new(). This function is
of the dialog box and its transient parent, as well as its 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 buttons. In addition, it takes in an argument that determines
whether the file chooser dialog will be used for opening whether the file chooser dialog will be used for opening
existing files or for saving to a possibly new file. existing files or for saving to a possibly new file.
@ -57,24 +66,26 @@
<title>Selection Modes</title> <title>Selection Modes</title>
<para> <para>
#GtkFileChooser can be used in two modes, to select a single <link linkend="GtkFileChooser">GtkFileChooser</link> can be used
file at a time or to select a set of more than one file. To set in two modes, to select a single file at a time or to select a
this, use gtk_file_chooser_set_select_multiple(). In set of more than one file. To set this, use
single-selection mode, you can use gtk_file_chooser_set_select_multiple(). In single-selection
gtk_file_chooser_get_filename() to get a file name from the mode, you can use gtk_file_chooser_get_filename() to get a file
local file system or gtk_file_chooser_get_uri() to get a name from the local file system or gtk_file_chooser_get_uri() to
full-formed URI. In multiple-selection mode, you can use get a full-formed URI. In multiple-selection mode, you can use
gtk_file_chooser_get_filenames() to get a #GSList of filename gtk_file_chooser_get_filenames() to get a <link
strings, or gtk_file_chooser_get_uris() to get a list of URI linkend="GSList">GSList</link> of filename strings, or
strings. gtk_file_chooser_get_uris() to get a list of URI strings.
</para> </para>
<para> <para>
Also, you can configure #GtkFileChooser to select files or Also, you can configure <link
folders. Consider a backup program that needs to let the user linkend="GtkFileChooser">GtkFileChooser</link> to select files
select a folder that will be backed up along with its or folders. Consider a backup program that needs to let the
subfolders. To configure whether #GtkFileChooser is used to user select a folder that will be backed up along with its
select files or folders, use gtk_file_chooser_set_action(). In subfolders. To configure whether <link
linkend="GtkFileChooser">GtkFileChooser</link> is used to select
files or folders, use gtk_file_chooser_set_action(). In
addition, this lets you configure whether the file chooser will addition, this lets you configure whether the file chooser will
be used to select existing files or folders (e.g. for be used to select existing files or folders (e.g. for
"File/Open"), or to type in new filenames (for "File/Open"), or to type in new filenames (for
@ -88,9 +99,11 @@
<para> <para>
Many applications need to have a preview facility within their Many applications need to have a preview facility within their
file chooser dialogs. Previous to GTK+ 2.4, one needed to file chooser dialogs. Previous to GTK+ 2.4, one needed to
access the #GtkFileSelection widget hierarchy directly to hook access the <link
in a preview widget. With #GtkFileChooser, there is a dedicated linkend="GtkFileSelection">GtkFileSelection</link> widget
API to do this. hierarchy directly to hook in a preview widget. With <link
linkend="GtkFileChooser">GtkFileChooser</link>, there is a
dedicated API to do this.
</para> </para>
<para> <para>
@ -119,15 +132,18 @@
<title>New features</title> <title>New features</title>
<para> <para>
New features in #GtkFileChooser include the following: New features in <link
linkend="GtkFileChooser">GtkFileChooser</link> include the
following:
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
Ability to select URIs rather than just local files. You Ability to select URIs rather than just local files. You
must use a #GtkFileSystem implementation that supports this, must use a <link
for example GtkFileSystemGnomeVFS. linkend="GtkFileSystem">GtkFileSystem</link> implementation
that supports this, for example the gnome-vfs backend.
</para> </para>
</listitem> </listitem>
@ -150,8 +166,9 @@
</itemizedlist> </itemizedlist>
<para> <para>
To see how to use these features, please consult the To see how to use these features, please consult the <link
#GtkFileChooser reference documentation. linkend="GtkFileChooser">GtkFileChooser</link> reference
documentation.
</para> </para>
</section> </section>
</chapter> </chapter>