forked from AuroraMiddleware/gtk
c5fe469c82
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.
182 lines
6.2 KiB
Plaintext
182 lines
6.2 KiB
Plaintext
<chapter id="gtk-migrating-GtkFileChooser">
|
|
<chapterinfo>
|
|
<author>
|
|
<firstname>Federico</firstname>
|
|
<surname>Mena-Quintero</surname>
|
|
<affiliation>
|
|
<address>
|
|
<email>federico@ximian.com</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
</chapterinfo>
|
|
|
|
<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.
|
|
</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>
|
|
inside.
|
|
</para>
|
|
|
|
<section id="gtkfilechooser-creating">
|
|
<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
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
Please see <xref linkend="gtkfilechooser-typical-usage"/> for
|
|
how to create a simple file chooser dialog and extract the
|
|
selected filename from it.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="gtkfilechooser-selection-modes">
|
|
<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
|
|
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 <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
|
|
"File/Save As...").
|
|
</para>
|
|
</section>
|
|
|
|
<section id="gtkfilechooser-installing-preview">
|
|
<title>Installing a Preview widget</title>
|
|
|
|
<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
|
|
dedicated API to do this.
|
|
</para>
|
|
|
|
<para>
|
|
Please see the <link linkend="gtkfilechooser-preview">section on
|
|
creating preview widgets</link> for more information.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="gtkfilechooser-installing-extra-widgets">
|
|
<title>Installing Extra Widgets</title>
|
|
|
|
<para>
|
|
Some applications need to install extra widgets in a file
|
|
chooser. For example, an application may want to provide a
|
|
toggle button to give the user the option of opening a file
|
|
read-only.
|
|
</para>
|
|
|
|
<para>
|
|
Please see the <link linkend="gtkfilechooser-extra">section on
|
|
creating extra widgets</link> for more information.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="gtkfilechooser-new-features">
|
|
<title>New features</title>
|
|
|
|
<para>
|
|
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 <link
|
|
linkend="GtkFileSystem">GtkFileSystem</link> implementation
|
|
that supports this, for example the gnome-vfs backend.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Present a list of application-specific shortcut folders.
|
|
For example, a paint program may want to add a shortcut for
|
|
its <filename>/usr/share/paint_program/Clipart</filename>
|
|
folder.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Define custom filters so that not all the files in a folder
|
|
are listed. For example, you could filter out backup files,
|
|
or show only image files.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
To see how to use these features, please consult the <link
|
|
linkend="GtkFileChooser">GtkFileChooser</link> reference
|
|
documentation.
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
|
|
<!--
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
|
|
End:
|
|
-->
|