forked from AuroraMiddleware/gtk
Put explicit <link> elements instead of #Symbol, because the latter
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
Federico Mena Quintero
parent
9ab57a8f29
commit
c5fe469c82
@ -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>
|
||||
|
||||
* gtk/tmpl/gtkoptionmenu.sgml:
|
||||
|
||||
@ -1112,8 +1112,6 @@ GtkFileChooserError
|
||||
gtk_file_chooser_error_quark
|
||||
gtk_file_chooser_set_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_get_local_only
|
||||
gtk_file_chooser_set_select_multiple
|
||||
|
||||
@ -15,36 +15,40 @@
|
||||
|
||||
<para>
|
||||
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
|
||||
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 #GtkAction mechanism.
|
||||
around the <link linkend="GtkAction">GtkAction</link> mechanism.
|
||||
</para>
|
||||
|
||||
<section id="actions-and-action-groups">
|
||||
<title>Actions and Action Groups</title>
|
||||
|
||||
<para>
|
||||
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
|
||||
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
|
||||
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 #GtkAction object will emit an
|
||||
action, the corresponding <link
|
||||
linkend="GtkAction">GtkAction</link> object will emit an
|
||||
"activate" signal.
|
||||
</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
|
||||
actions such as "new document", "about", and "exit"; then one
|
||||
group for each open document with actions specific to the
|
||||
@ -68,20 +72,22 @@
|
||||
<title>User Interface Manager Object</title>
|
||||
|
||||
<para>
|
||||
#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.
|
||||
<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
|
||||
corresponding actions and action groups.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
#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 #GtkUIManager as appropriate.
|
||||
<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
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
@ -135,25 +141,28 @@
|
||||
<listitem>
|
||||
<para>
|
||||
Separate your existing GnomeUIInfo entries into normal
|
||||
actions, toggle actions, and radio actions, and then create a
|
||||
separate array of #GtkActionEntry structures for each
|
||||
group. This will allow you to create the necessary
|
||||
#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.
|
||||
actions, toggle actions, and radio actions, and then create
|
||||
a separate array of <link
|
||||
linkend="GtkActionEntry">GtkActionEntry</link> 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
|
||||
"shape" that your menus and toolbars will have; it simply
|
||||
defines the set of commands that will appear in them.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Create an XML description of your menus and toolbars for use
|
||||
with #GtkUIManager. This defines the actual shape of the
|
||||
menus and toolbars.
|
||||
with <link linkend="GtkUIManager">GtkUIManager</link>. 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
|
||||
#GtkAction and #GtkUIManager.
|
||||
<link linkend="GtkAction">GtkAction</link> and <link
|
||||
linkend="GtkUIManager">GtkUIManager</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
@ -248,14 +257,14 @@ 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 #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,
|
||||
<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
|
||||
separate from normal actions. Also, note that <link
|
||||
linkend="GtkActionEntry">GtkActionEntry</link> structures take
|
||||
key names in the format of gdk_accelerator_parse() rather than
|
||||
key values plus modifiers; you will have to convert these
|
||||
values by hand. For example, <constant>GDK_F11</constant>
|
||||
with no modifiers is equivalent to a key name of
|
||||
<literal>"F11"</literal>. Likewise, <literal>"o"</literal>
|
||||
with <constant>GDK_CONTROL_MASK</constant> is equivalent to
|
||||
<literal>"<ontrol>O"</literal>.
|
||||
</para>
|
||||
|
||||
@ -290,15 +299,15 @@ 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 #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 entries</link>,
|
||||
not in the XML itself. This is because the XML description
|
||||
only contains <emphasis>identifiers</emphasis> for the items
|
||||
in the GUI, rather than human-readable names.
|
||||
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
|
||||
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
|
||||
entries</link>, not in the XML itself. This is because the
|
||||
XML description only contains <emphasis>identifiers</emphasis>
|
||||
for the items in the GUI, rather than human-readable names.
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
@ -328,13 +337,16 @@ static const char *ui_description =
|
||||
<title>Creating the Menu Bar</title>
|
||||
|
||||
<para>
|
||||
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 #GtkUIManager
|
||||
put them into a window.
|
||||
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
|
||||
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.
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
|
||||
@ -14,33 +14,42 @@
|
||||
<title>Migrating from GtkFileSelection to GtkFileChooser</title>
|
||||
|
||||
<para>
|
||||
#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.
|
||||
<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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
#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.
|
||||
<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>
|
||||
inside.
|
||||
</para>
|
||||
|
||||
<section id="gtkfilechooser-creating">
|
||||
<title>Creating a GtkFileChooserDialog</title>
|
||||
|
||||
<para>
|
||||
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
|
||||
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
|
||||
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
|
||||
existing files or for saving to a possibly new file.
|
||||
@ -57,24 +66,26 @@
|
||||
<title>Selection Modes</title>
|
||||
|
||||
<para>
|
||||
#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 #GSList of filename
|
||||
strings, or gtk_file_chooser_get_uris() to get a list of URI
|
||||
strings.
|
||||
<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
|
||||
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_uris() to get a list of URI strings.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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 #GtkFileChooser is used to
|
||||
select files or folders, use gtk_file_chooser_set_action(). In
|
||||
Also, you can configure <link
|
||||
linkend="GtkFileChooser">GtkFileChooser</link> 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
|
||||
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
|
||||
"File/Open"), or to type in new filenames (for
|
||||
@ -88,9 +99,11 @@
|
||||
<para>
|
||||
Many applications need to have a preview facility within their
|
||||
file chooser dialogs. Previous to GTK+ 2.4, one needed to
|
||||
access the #GtkFileSelection widget hierarchy directly to hook
|
||||
in a preview widget. With #GtkFileChooser, there is a dedicated
|
||||
API to do this.
|
||||
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
|
||||
dedicated API to do this.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -119,15 +132,18 @@
|
||||
<title>New features</title>
|
||||
|
||||
<para>
|
||||
New features in #GtkFileChooser include the following:
|
||||
New features in <link
|
||||
linkend="GtkFileChooser">GtkFileChooser</link> include the
|
||||
following:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Ability to select URIs rather than just local files. You
|
||||
must use a #GtkFileSystem implementation that supports this,
|
||||
for example GtkFileSystemGnomeVFS.
|
||||
must use a <link
|
||||
linkend="GtkFileSystem">GtkFileSystem</link> implementation
|
||||
that supports this, for example the gnome-vfs backend.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
@ -150,8 +166,9 @@
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
To see how to use these features, please consult the
|
||||
#GtkFileChooser reference documentation.
|
||||
To see how to use these features, please consult the <link
|
||||
linkend="GtkFileChooser">GtkFileChooser</link> reference
|
||||
documentation.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user