diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 1c5a81b912..ba1fba06c7 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,16 @@ +2003-11-18 Federico Mena Quintero + + * 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 * gdk/gdk-sections.txt: Add gdk_drawable_copy_to_image. diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 3efd254bc1..206f117c3f 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -77,21 +77,22 @@ GTKDOC_LIBS = \ 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 diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index c32ec5a516..8cba90713a 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -179,6 +179,7 @@ + ]> @@ -533,6 +534,19 @@ that is, GUI components such as GtkButton or + + Migrating from Previous Versions of GTK+ + + + + This part describes what you need to change in programs use + older versions of GTK+ so that they can use the new features. + + + + >k-migrating-GtkFileChooser; + + GTK+ Tools diff --git a/docs/reference/gtk/migrating-GtkFileChooser.sgml b/docs/reference/gtk/migrating-GtkFileChooser.sgml new file mode 100644 index 0000000000..24071d107b --- /dev/null +++ b/docs/reference/gtk/migrating-GtkFileChooser.sgml @@ -0,0 +1,159 @@ + + + Migrating from GtkFileSelection to GtkFileChooser + + Federico + Mena-Quintero + +
+ federico@ximian.com +
+ + + + + + #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. + + + + #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. + + +
+ Creating a GtkFileChooserDialog + + + 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. + + + + Please see for + how to create a simple file chooser dialog and extract the + selected filename from it. + +
+ +
+ Selection Modes + + + #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. + + + + 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(). + +
+ +
+ Installing a Preview widget + + + 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. + + + + Please see the section on + creating preview widgets for more information. + +
+ +
+ Installing Extra Widgets + + + 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. + + + + Please see the section on + creating extra widgets for more information. + +
+ +
+ New features + + + New features in #GtkFileChooser include the following: + + + + + + Ability to select URIs rather than just local files. You + must use a #GtkFileSystem implementation that supports this, + for example GtkFileSystemGnomeVFS. + + + + + + Present a list of application-specific shortcut folders. + For example, a paint program may want to add a shortcut for + its /usr/share/paint_program/Clipart + folder. + + + + + + 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. + + + + + + To see how to use these features, please consult the + #GtkFileChooser reference documentation. + +
+ + + diff --git a/docs/reference/gtk/tmpl/gtkfilechooser.sgml b/docs/reference/gtk/tmpl/gtkfilechooser.sgml index b4a45cd9c0..3cce81c814 100644 --- a/docs/reference/gtk/tmpl/gtkfilechooser.sgml +++ b/docs/reference/gtk/tmpl/gtkfilechooser.sgml @@ -15,11 +15,198 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog. programming interface. + + Adding a Preview Widget + + + 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. + + + + 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. + + + + Sample Usage + + +{ + 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); +} + + + + + + Adding Extra Widgets + + + 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. + + + + Sample Usage + + +{ + 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); +} + + + + + + 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. + + + + + #GtkFileChooserDialog, #GtkFileChooserWidget + + + + + + + + + + + + +@filechooser: the object which received the signal. + + + + + + +@filechooser: the object which received the signal. + + + + + + +@filechooser: the object which received the signal. + + + + + + +@filechooser: the object which received the signal. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Describes whether a #GtkFileChooser is being used to open @@ -98,6 +285,8 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog. @chooser: +@local_only: + @files_only: @@ -320,8 +509,10 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog. -@file_chooser: +@chooser: @Returns: + +@file_chooser: @@ -329,8 +520,10 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog. -@file_chooser: +@chooser: @Returns: + +@file_chooser: @@ -433,9 +626,11 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog. @chooser: -@folder: +@uri: @error: @Returns: + +@folder: @@ -444,9 +639,11 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog. @chooser: -@folder: +@uri: @error: @Returns: + +@folder: @@ -467,31 +664,3 @@ End: --> - - - - - -@filechooser: the object which received the signal. - - - - - - -@filechooser: the object which received the signal. - - - - - - -@filechooser: the object which received the signal. - - - - - - -@filechooser: the object which received the signal. - diff --git a/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml b/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml index 1c82b9cb99..778037e048 100644 --- a/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml +++ b/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml @@ -20,7 +20,7 @@ A file chooser dialog, suitable for "File/Open" or "File/Save" commands. #GtkFileChooser. - + Typical usage