+2003-11-18 Federico Mena Quintero <federico@ximian.com>
+
+ * gtk/tmpl/gtkfilechooser.sgml: Added sections section about
+ generating previews and including extra widgets.
+
+ * gtk/gtk-docs.sgml: Added a part about migrating old code to new
+ widgets.
+
+ * gtk/migrating-GtkFileChooser.sgml: New file.
+
+ * gtk/Makefile.am (content_files): Added
+ migrating-GtkFileChooser.sgml.
+
Tue Nov 18 00:12:23 2003 Matthias Clasen <maclas@gmx.de>
* gdk/gdk-sections.txt: Add gdk_drawable_copy_to_image.
MKDB_OPTIONS=--sgml-mode --output-format=xml
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
-content_files = \
- version.xml \
- running.sgml \
- building.sgml \
- changes-1.2.sgml \
- changes-2.0.sgml \
- compiling.sgml \
- framebuffer.sgml \
- objects_grouped.sgml \
- question_index.sgml \
- resources.sgml \
- text_widget.sgml \
- tree_widget.sgml \
- windows.sgml \
- x11.sgml \
+content_files = \
+ version.xml \
+ running.sgml \
+ building.sgml \
+ changes-1.2.sgml \
+ changes-2.0.sgml \
+ compiling.sgml \
+ framebuffer.sgml \
+ migrating-GtkFileChooser.sgml \
+ objects_grouped.sgml \
+ question_index.sgml \
+ resources.sgml \
+ text_widget.sgml \
+ tree_widget.sgml \
+ windows.sgml \
+ x11.sgml \
gtk-query-immodules-2.0.xml
# Images to copy into HTML directory
<!ENTITY gtk-Questions SYSTEM "question_index.sgml">
<!ENTITY gtk-Changes-1-2 SYSTEM "changes-1.2.sgml">
<!ENTITY gtk-Changes-2-0 SYSTEM "changes-2.0.sgml">
+<!ENTITY gtk-migrating-GtkFileChooser SYSTEM "migrating-GtkFileChooser.sgml">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY gtk-query-immodules SYSTEM "gtk-query-immodules-2.0.xml">
]>
</chapter>
</part>
+ <part id="migrating">
+ <title>Migrating from Previous Versions of GTK+</title>
+
+ <partintro>
+ <para>
+ This part describes what you need to change in programs use
+ older versions of GTK+ so that they can use the new features.
+ </para>
+ </partintro>
+
+ >k-migrating-GtkFileChooser;
+ </part>
+
<part>
<title>GTK+ Tools</title>
--- /dev/null
+<chapter id="gtk-migrating-GtkFileChooser">
+ <chapterinfo>
+ <title>Migrating from GtkFileSelection to GtkFileChooser</title>
+ <author>
+ <firstname>Federico</firstname>
+ <surname>Mena-Quintero</surname>
+ <affiliation>
+ <address>
+ <email>federico@ximian.com</email>
+ </address>
+ </affiliation>
+ </author>
+ </chapterinfo>
+
+ <para>
+ #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>
+ #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>
+ 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>
+ #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
+ 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>
+ 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
+ subfolders. To configure whether #GtkFileChooser is used to
+ select files or folders, use gtk_file_chooser_set_folder_mode().
+ </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 #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>
+ New features in #GtkFileChooser include the following:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ability to select URIs rather than just local files. You
+ must use a #GtkFileSystem implementation that supports this,
+ for example GtkFileSystemGnomeVFS.
+ </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
+ #GtkFileChooser reference documentation.
+ </para>
+ </section>
+</chapter>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
+End:
+-->
programming interface.
</para>
+ <refsect2 id="gtkfilechooser-preview">
+ <title>Adding a Preview Widget</title>
+
+ <para>
+ You can add a custom preview widget to a file chooser and then
+ get notification about when the preview needs to be updated.
+ To install a preview widget, use
+ gtk_file_chooser_set_preview_widget(). Then, connect to the
+ #GtkFileChooser::update-preview signal to get notified when
+ you need to update the contents of the preview.
+ </para>
+
+ <para>
+ Your callback should use
+ gtk_file_chooser_get_preview_filename() to see what needs
+ previewing. Once you have generated the preview for the
+ corresponding file, you must call
+ gtk_file_chooser_set_preview_widget_active() with a boolean
+ flag that indicates whether your callback could successfully
+ generate a preview.
+ </para>
+
+ <example id="example-gtkfilechooser-preview">
+ <title>Sample Usage</title>
+
+ <programlisting>
+{
+ GtkImage *preview;
+
+ ...
+
+ preview = gtk_image_new ();
+
+ gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
+ g_signal_connect (my_file_chooser, "update-preview",
+ G_CALLBACK (update_preview_cb), preview);
+}
+
+static void
+update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
+{
+ GtkWidget *preview;
+ char *filename;
+ GdkPixbuf *pixbuf;
+ gboolean have_preview;
+
+ preview = GTK_WIDGET (data);
+ filename = gtk_file_chooser_get_preview_filename (file_chooser);
+
+ pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
+ have_preview = (pixbuf != NULL);
+ g_free (filename);
+
+ gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
+ if (pixbuf)
+ gdk_pixbuf_unref (pixbuf);
+
+ gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
+}
+ </programlisting>
+ </example>
+ </refsect2>
+
+ <refsect2 id="gtkfilechooser-extra">
+ <title>Adding Extra Widgets</title>
+
+ <para>
+ You can add extra widgets to a file chooser to provide options
+ that are not present in the default design. For example, you
+ can add a toggle button to give the user the option to open a
+ file in read-only mode. You can use
+ gtk_file_chooser_set_extra_widget() to insert additional
+ widgets in a file chooser.
+ </para>
+
+ <example id="example-gtkfilechooser-extra">
+ <title>Sample Usage</title>
+
+ <programlisting>
+{
+ GtkWidget *toggle;
+
+ ...
+
+ toggle = gtk_check_button_new_with_label ("Open file read-only");
+ gtk_widget_show (toggle);
+ gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
+}
+ </programlisting>
+ </example>
+
+ <note>
+ <para>
+ If you want to set more than one extra widget in the file
+ chooser, you can a container such as a GtkVBox or a GtkTable
+ and include your widgets in it. Then, set the container as
+ the whole extra widget.
+ </para>
+ </note>
+ </refsect2>
+
+
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkFileChooserDialog, #GtkFileChooserWidget
</para>
+
+<!-- ##### STRUCT GtkFileChooser ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SIGNAL GtkFileChooser::current-folder-changed ##### -->
+<para>
+
+</para>
+
+@filechooser: the object which received the signal.
+
+<!-- ##### SIGNAL GtkFileChooser::file-activated ##### -->
+<para>
+
+</para>
+
+@filechooser: the object which received the signal.
+
+<!-- ##### SIGNAL GtkFileChooser::selection-changed ##### -->
+<para>
+
+</para>
+
+@filechooser: the object which received the signal.
+
+<!-- ##### SIGNAL GtkFileChooser::update-preview ##### -->
+<para>
+
+</para>
+
+@filechooser: the object which received the signal.
+
+<!-- ##### ARG GtkFileChooser:action ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:extra-widget ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:file-system ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:filter ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:folder-mode ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:local-only ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:preview-widget ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:preview-widget-active ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:select-multiple ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:show-hidden ##### -->
+<para>
+
+</para>
+
<!-- ##### ENUM GtkFileChooserAction ##### -->
<para>
Describes whether a #GtkFileChooser is being used to open
</para>
@chooser:
+@local_only:
+<!-- # Unused Parameters # -->
@files_only:
</para>
-@file_chooser:
+@chooser:
@Returns:
+<!-- # Unused Parameters # -->
+@file_chooser:
<!-- ##### FUNCTION gtk_file_chooser_get_preview_uri ##### -->
</para>
-@file_chooser:
+@chooser:
@Returns:
+<!-- # Unused Parameters # -->
+@file_chooser:
<!-- ##### FUNCTION gtk_file_chooser_set_extra_widget ##### -->
</para>
@chooser:
-@folder:
+@uri:
@error:
@Returns:
+<!-- # Unused Parameters # -->
+@folder:
<!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder_uri ##### -->
</para>
@chooser:
-@folder:
+@uri:
@error:
@Returns:
+<!-- # Unused Parameters # -->
+@folder:
<!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folder_uris ##### -->
-->
-<!-- ##### SIGNAL GtkFileChooser::current-folder-changed ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
-
-<!-- ##### SIGNAL GtkFileChooser::file-activated ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
-
-<!-- ##### SIGNAL GtkFileChooser::selection-changed ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
-
-<!-- ##### SIGNAL GtkFileChooser::update-preview ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
-
#GtkFileChooser.
</para>
- <example>
+ <example id="gtkfilechooser-typical-usage">
<title>Typical usage</title>
<para>
projects / ~andy / gtk / commitdiff