Pileus Git - ~andy/gtk/blob - docs/reference/gtk/migrating-GtkFileChooser.sgml

   1 <chapter id="gtk-migrating-GtkFileChooser">
   2   <chapterinfo>
   3     <author>
   4       <firstname>Federico</firstname>
   5       <surname>Mena-Quintero</surname>
   6       <affiliation>
   7         <address>
   8           <email>federico@ximian.com</email>
   9         </address>
  10       </affiliation>
  11     </author>
  12   </chapterinfo>
  13
  14   <title>Migrating from GtkFileSelection to GtkFileChooser</title>
  15
  16   <para>
  17     <link linkend="GtkFileChooser">GtkFileChooser</link>, starting
  18     with GTK+ 2.4, is the new set of APIs for file selection widgets
  19     and dialogs.  Previous versions of GTK+ used <link
  20     linkend="GtkFileSelection">GtkFileSelection</link>, which has
  21     numerous problems.
  22   </para>
  23
  24   <para>
  25     <link linkend="GtkFileChooser">GtkFileChooser</link> is an
  26     abstract interface that can be implemented by widgets that perform
  27     file selection tasks.  Two widgets in GTK+ implement this
  28     interface:  <link
  29     linkend="GtkFileChooserDialog">GtkFileChooserDialog</link> and
  30     <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>.
  31     Most applications simply need to use <link
  32     linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>, which
  33     is a dialog box that allows the user to select existing files for
  34     opening them, or to pick new filenames for saving documents.
  35     <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>
  36     is for special applications that need to embed a file selection
  37     widget inside a larger window.  In the context of GTK+, <link
  38     linkend="GtkFileChooserDialog">GtkFileChooserDialog</link> is
  39     simply a <link linkend="GtkDialog">GtkDialog</link> box with a
  40     <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>
  41     inside.
  42   </para>
  43
  44   <section id="gtkfilechooser-creating">
  45     <title>Creating a GtkFileChooserDialog</title>
  46
  47     <para>
  48       To create a <link
  49       linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>, you
  50       simply call gtk_file_chooser_dialog_new().  This function is
  51       similar to gtk_dialog_new() in that it takes parameters for the
  52       title of the dialog box and its transient parent, as well as its
  53       buttons.  In addition, it takes in an argument that determines
  54       whether the file chooser dialog will be used for opening
  55       existing files or for saving to a possibly new file.
  56     </para>
  57
  58     <para>
  59       Please see <xref linkend="gtkfilechooser-typical-usage"/> for
  60       how to create a simple file chooser dialog and extract the
  61       selected filename from it.
  62     </para>
  63   </section>
  64
  65   <section id="gtkfilechooser-selection-modes">
  66     <title>Selection Modes</title>
  67
  68     <para>
  69       <link linkend="GtkFileChooser">GtkFileChooser</link> can be used
  70       in two modes, to select a single file at a time or to select a
  71       set of more than one file.  To set this, use
  72       gtk_file_chooser_set_select_multiple().  In single-selection
  73       mode, you can use gtk_file_chooser_get_filename() to get a file
  74       name from the local file system or gtk_file_chooser_get_uri() to
  75       get a full-formed URI.  In multiple-selection mode, you can use
  76       gtk_file_chooser_get_filenames() to get a <link
  77       linkend="GSList">GSList</link> of filename strings, or
  78       gtk_file_chooser_get_uris() to get a list of URI strings.
  79     </para>
  80
  81     <para>
  82       Also, you can configure <link
  83       linkend="GtkFileChooser">GtkFileChooser</link> to select files
  84       or folders.  Consider a backup program that needs to let the
  85       user select a folder that will be backed up along with its
  86       subfolders.  To configure whether <link
  87       linkend="GtkFileChooser">GtkFileChooser</link> is used to select
  88       files or folders, use gtk_file_chooser_set_action().  In
  89       addition, this lets you configure whether the file chooser will
  90       be used to select existing files or folders (e.g. for
  91       "File/Open"), or to type in new filenames (for
  92       "File/Save&nbsp;As...").
  93     </para>
  94   </section>
  95
  96   <section id="gtkfilechooser-installing-preview">
  97     <title>Installing a Preview widget</title>
  98
  99     <para>
 100       Many applications need to have a preview facility within their
 101       file chooser dialogs.  Previous to GTK+ 2.4, one needed to
 102       access the <link
 103       linkend="GtkFileSelection">GtkFileSelection</link> widget
 104       hierarchy directly to hook in a preview widget.  With <link
 105       linkend="GtkFileChooser">GtkFileChooser</link>, there is a
 106       dedicated API to do this.
 107     </para>
 108
 109     <para>
 110       Please see the <link linkend="gtkfilechooser-preview">section on
 111       creating preview widgets</link> for more information.
 112     </para>
 113   </section>
 114
 115   <section id="gtkfilechooser-installing-extra-widgets">
 116     <title>Installing Extra Widgets</title>
 117
 118     <para>
 119       Some applications need to install extra widgets in a file
 120       chooser.  For example, an application may want to provide a
 121       toggle button to give the user the option of opening a file
 122       read-only.
 123     </para>
 124
 125     <para>
 126       Please see the <link linkend="gtkfilechooser-extra">section on
 127       creating extra widgets</link> for more information.
 128     </para>
 129   </section>
 130
 131   <section id="gtkfilechooser-new-features">
 132     <title>New features</title>
 133
 134     <para>
 135       New features in <link
 136       linkend="GtkFileChooser">GtkFileChooser</link> include the
 137       following:
 138     </para>
 139
 140     <itemizedlist>
 141       <listitem>
 142         <para>
 143           Ability to select URIs rather than just local files.  You
 144           must use a <link
 145           linkend="GtkFileSystem">GtkFileSystem</link> implementation
 146           that supports this, for example the gnome-vfs backend.
 147         </para>
 148       </listitem>
 149
 150       <listitem>
 151         <para>
 152           Present a list of application-specific shortcut folders.
 153           For example, a paint program may want to add a shortcut for
 154           its <filename>/usr/share/paint_program/Clipart</filename>
 155           folder.
 156         </para>
 157       </listitem>
 158
 159       <listitem>
 160         <para>
 161           Define custom filters so that not all the files in a folder
 162           are listed.  For example, you could filter out backup files,
 163           or show only image files.
 164         </para>
 165       </listitem>
 166     </itemizedlist>
 167
 168     <para>
 169       To see how to use these features, please consult the <link
 170       linkend="GtkFileChooser">GtkFileChooser</link> reference
 171       documentation.
 172     </para>
 173   </section>
 174 </chapter>
 175
 176 <!--
 177 Local variables:
 178 mode: sgml
 179 sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
 180 End:
 181 -->