gtk2/docs/reference/gtk/migrating-GtkFileChooser.sgml

160 lines
5.4 KiB
Plaintext
Raw Normal View History

<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>
2005-05-16 19:34:39 +00:00
#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>
2005-05-16 19:34:39 +00:00
#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>
<section id="gtkfilechooser-creating">
<title>Creating a GtkFileChooserDialog</title>
<para>
2005-05-16 19:34:39 +00:00
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
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>
2005-05-16 19:34:39 +00:00
#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
2005-05-16 19:34:39 +00:00
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>
2005-05-16 19:34:39 +00:00
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
2005-05-16 19:34:39 +00:00
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
"File/Open"), or to type in new filenames (for
"File/Save&nbsp;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
2005-05-16 19:34:39 +00:00
access the #GtkFileSelection widget hierarchy directly to hook in
a preview widget. With #GtkFileChooser, 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>
2005-05-16 19:34:39 +00:00
New features in #GtkFileChooser include the following:
</para>
<itemizedlist>
<listitem>
<para>
Ability to select URIs rather than just local files. You
2005-05-16 19:34:39 +00:00
must use a #GtkFileSystem 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>
2005-05-16 19:34:39 +00:00
To see how to use these features, please consult the #GtkFileChooser
reference documentation.
</para>
</section>
</chapter>
<!--
Local variables:
mode: sgml
sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
End:
-->