summaryrefslogtreecommitdiff
path: root/gtk/gtkfilechooser.c
diff options
context:
space:
mode:
Diffstat (limited to 'gtk/gtkfilechooser.c')
-rw-r--r--gtk/gtkfilechooser.c100
1 files changed, 38 insertions, 62 deletions
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index eee7976659..68aa4c4e18 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -43,34 +43,20 @@
* In the default implementation these are displayed in the left pane. It
* may be a bit confusing at first that these shortcuts come from various
* sources and in various flavours, so lets explain the terminology here:
- * <variablelist>
- * <varlistentry>
- * <term>Bookmarks</term>
- * <listitem>
- * are created by the user, by dragging folders from the
- * right pane to the left pane, or by using the "Add". Bookmarks
- * can be renamed and deleted by the user.
- * </listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>Shortcuts</term>
- * <listitem>
- * can be provided by the application. For example, a Paint program may
- * want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the
- * user.
- * </listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>Volumes</term>
- * <listitem>
- * are provided by the underlying filesystem abstraction. They are
- * the "roots" of the filesystem.
- * </listitem>
- * </varlistentry>
- * </variablelist>
- *
- * <refsect2 id="gtkfilechooser-encodings">
- * <title>File Names and Encodings</title>
+ *
+ * - Bookmarks: are created by the user, by dragging folders from the
+ * right pane to the left pane, or by using the "Add". Bookmarks
+ * can be renamed and deleted by the user.
+ *
+ * - Shortcuts: can be provided by the application. For example, a Paint
+ * program may want to add a shortcut for a Clipart folder. Shortcuts
+ * cannot be modified by the user.
+ *
+ * - Volumes: are provided by the underlying filesystem abstraction. They are
+ * the "roots" of the filesystem.
+ *
+ * ## File Names and Encodings
+ *
* When the user is finished selecting files in a
* #GtkFileChooser, your program can get the selected names
* either as filenames or as URIs. For URIs, the normal escaping
@@ -80,27 +66,24 @@
* <envar>G_FILENAME_ENCODING</envar> environment variable.
* Please see the GLib documentation for more details about this
* variable.
- * <note>
- * This means that while you can pass the result of
- * gtk_file_chooser_get_filename() to
- * open(2) or fopen(3), you may not be able to
- * directly set it as the text of a #GtkLabel widget unless you
- * convert it first to UTF-8, which all GTK+ widgets expect.
- * You should use g_filename_to_utf8() to convert filenames
- * into strings that can be passed to GTK+ widgets.
- * </note>
- * </refsect2>
- * <refsect2 id="gtkfilechooser-preview">
- * <title>Adding a Preview Widget</title>
- * <para>
+ *
+ * This means that while you can pass the result of
+ * gtk_file_chooser_get_filename() to open() or fopen(),
+ * you may not be able to directly set it as the text of a
+ * #GtkLabel widget unless you convert it first to UTF-8,
+ * which all GTK+ widgets expect. You should use g_filename_to_utf8()
+ * to convert filenames into strings that can be passed to GTK+
+ * widgets.
+ *
+ * ## 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.
- * </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
@@ -108,9 +91,8 @@
* 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>
+ *
+ * <para id="gtkfilechooser-preview">An example for using a preview widget:</para>
* |[<!-- language="C" -->
* {
* GtkImage *preview;
@@ -146,20 +128,17 @@
* gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
* }
* ]|
- * </example>
- * </refsect2>
- * <refsect2 id="gtkfilechooser-extra">
- * <title>Adding Extra Widgets</title>
- * <para>
+ *
+ * ## 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.
- * </para>
- * <example id="example-gtkfilechooser-extra">
- * <title>Sample Usage</title>
+ *
+ * An example for adding extra widgets:
* |[<!-- language="C" -->
*
* GtkWidget *toggle;
@@ -171,14 +150,11 @@
* gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
* }
* ]|
- * </example>
- * <note>
- * If you want to set more than one extra widget in the file
- * chooser, you can a container such as a #GtkBox or a #GtkGrid
- * and include your widgets in it. Then, set the container as
- * the whole extra widget.
- * </note>
- * </refsect2>
+ *
+ * If you want to set more than one extra widget in the file
+ * chooser, you can a container such as a #GtkBox or a #GtkGrid
+ * and include your widgets in it. Then, set the container as
+ * the whole extra widget.
*/