callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added sections section about generating previews and including extra

Browse Source 
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.
This commit is contained in:
Federico Mena Quintero
2003-11-18 22:50:26 +00:00
committed by Federico Mena Quintero
parent 97dbeec935
commit 5c243e9be8
6 changed files with 404 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/reference/ChangeLog
View File

@ -1,3 +1,16 @@
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.

31
docs/reference/gtk/Makefile.am
View File

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

14
docs/reference/gtk/gtk-docs.sgml
View File

@ -179,6 +179,7 @@
<!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">
]>
@ -533,6 +534,19 @@ that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
</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>
&gtk-migrating-GtkFileChooser;
</part>
<part>
<title>GTK+ Tools</title>

159
docs/reference/gtk/migrating-GtkFileChooser.sgml Normal file
View File

@ -0,0 +1,159 @@
<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:
-->

233
docs/reference/gtk/tmpl/gtkfilechooser.sgml
View File

@ -15,11 +15,198 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
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
@ -98,6 +285,8 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
</para>
@chooser:
@local_only:
<!-- # Unused Parameters # -->
@files_only:
@ -320,8 +509,10 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
</para>
@file_chooser:
@chooser:
@Returns:
<!-- # Unused Parameters # -->
@file_chooser:
<!-- ##### FUNCTION gtk_file_chooser_get_preview_uri ##### -->
@ -329,8 +520,10 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
</para>
@file_chooser:
@chooser:
@Returns:
<!-- # Unused Parameters # -->
@file_chooser:
<!-- ##### FUNCTION gtk_file_chooser_set_extra_widget ##### -->
@ -433,9 +626,11 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
</para>
@chooser:
@folder:
@uri:
@error:
@Returns:
<!-- # Unused Parameters # -->
@folder:
<!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder_uri ##### -->
@ -444,9 +639,11 @@ File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
</para>
@chooser:
@folder:
@uri:
@error:
@Returns:
<!-- # Unused Parameters # -->
@folder:
<!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folder_uris ##### -->
@ -467,31 +664,3 @@ End:
-->
<!-- ##### 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.

2
docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml
View File

@ -20,7 +20,7 @@ A file chooser dialog, suitable for "File/Open" or "File/Save" commands.
#GtkFileChooser.
</para>
<example>
<example id="gtkfilechooser-typical-usage">
<title>Typical usage</title>
<para>