gtk2/docs/reference/gtk/migrating-GtkFileChooser.sgml
Federico Mena Quintero c5fe469c82 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.
2004-02-27 22:06:40 +00:00

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&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
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:
-->