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

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