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
committed by
Federico Mena Quintero
Federico Mena Quintero
parent
9ab57a8f29
commit
c5fe469c82
@ -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>
|
||||
|
||||
Reference in New Issue
Block a user