forked from AuroraMiddleware/gtk
Move documentation to inline comments: GtkFileChooserDialog
This commit is contained in:
Javier Jardón
parent
2da9a5791f
commit
fe65ec5b87
1
docs/reference/gtk/tmpl/.gitignore
vendored
1
docs/reference/gtk/tmpl/.gitignore
vendored
@ -39,6 +39,7 @@ gtkexpander.sgml
|
|||||||
gtkfeatures.sgml
|
gtkfeatures.sgml
|
||||||
gtkfixed.sgml
|
gtkfixed.sgml
|
||||||
gtkfilechooserbutton.sgml
|
gtkfilechooserbutton.sgml
|
||||||
|
gtkfilechooserdialog.sgml
|
||||||
gtkfilechooserwidget.sgml
|
gtkfilechooserwidget.sgml
|
||||||
gtkfilefilter.sgml
|
gtkfilefilter.sgml
|
||||||
gtkfontbutton.sgml
|
gtkfontbutton.sgml
|
||||||
|
|||||||
@ -1,174 +0,0 @@
|
|||||||
<!-- ##### SECTION Title ##### -->
|
|
||||||
GtkFileChooserDialog
|
|
||||||
|
|
||||||
<!-- ##### SECTION Short_Description ##### -->
|
|
||||||
A file chooser dialog, suitable for "File/Open" or "File/Save" commands
|
|
||||||
|
|
||||||
<!-- ##### SECTION Long_Description ##### -->
|
|
||||||
<para>
|
|
||||||
#GtkFileChooserDialog is a dialog box suitable for use with
|
|
||||||
"File/Open" or "File/Save as" commands. This widget works by
|
|
||||||
putting a #GtkFileChooserWidget inside a #GtkDialog. It exposes
|
|
||||||
the #GtkFileChooserIface interface, so you can use all of the
|
|
||||||
#GtkFileChooser functions on the file chooser dialog as well as
|
|
||||||
those for #GtkDialog.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Note that #GtkFileChooserDialog does not have any methods of its
|
|
||||||
own. Instead, you should use the functions that work on a
|
|
||||||
#GtkFileChooser.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<example id="gtkfilechooser-typical-usage">
|
|
||||||
<title>Typical usage</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
In the simplest of cases, you can the following code to use
|
|
||||||
#GtkFileChooserDialog to select a file for opening:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
GtkWidget *dialog;
|
|
||||||
|
|
||||||
dialog = gtk_file_chooser_dialog_new ("Open File",
|
|
||||||
parent_window,
|
|
||||||
GTK_FILE_CHOOSER_ACTION_OPEN,
|
|
||||||
GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
|
|
||||||
GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
|
|
||||||
NULL);
|
|
||||||
|
|
||||||
if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
|
|
||||||
{
|
|
||||||
char *filename;
|
|
||||||
|
|
||||||
filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
|
|
||||||
open_file (filename);
|
|
||||||
g_free (filename);
|
|
||||||
}
|
|
||||||
|
|
||||||
gtk_widget_destroy (dialog);
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
To use a dialog for saving, you can use this:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
GtkWidget *dialog;
|
|
||||||
|
|
||||||
dialog = gtk_file_chooser_dialog_new ("Save File",
|
|
||||||
parent_window,
|
|
||||||
GTK_FILE_CHOOSER_ACTION_SAVE,
|
|
||||||
GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
|
|
||||||
GTK_STOCK_SAVE, GTK_RESPONSE_ACCEPT,
|
|
||||||
NULL);
|
|
||||||
gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
|
|
||||||
|
|
||||||
if (user_edited_a_new_document)
|
|
||||||
{
|
|
||||||
gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (dialog), default_folder_for_saving);
|
|
||||||
gtk_file_chooser_set_current_name (GTK_FILE_CHOOSER (dialog), "Untitled document");
|
|
||||||
}
|
|
||||||
else
|
|
||||||
gtk_file_chooser_set_filename (GTK_FILE_CHOOSER (dialog), filename_for_existing_document);
|
|
||||||
|
|
||||||
|
|
||||||
if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
|
|
||||||
{
|
|
||||||
char *filename;
|
|
||||||
|
|
||||||
filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
|
|
||||||
save_to_file (filename);
|
|
||||||
g_free (filename);
|
|
||||||
}
|
|
||||||
|
|
||||||
gtk_widget_destroy (dialog);
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<section id="gtkfilechooserdialog-response-codes">
|
|
||||||
<title>Response Codes</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
#GtkFileChooserDialog inherits from #GtkDialog, so buttons that
|
|
||||||
go in its action area have response codes such as
|
|
||||||
#GTK_RESPONSE_ACCEPT and #GTK_RESPONSE_CANCEL. For example, you
|
|
||||||
could call gtk_file_chooser_dialog_new() as follows:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
GtkWidget *dialog;
|
|
||||||
|
|
||||||
dialog = gtk_file_chooser_dialog_new ("Open File",
|
|
||||||
parent_window,
|
|
||||||
GTK_FILE_CHOOSER_ACTION_OPEN,
|
|
||||||
GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
|
|
||||||
GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
|
|
||||||
NULL);
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This will create buttons for "Cancel" and "Open" that use stock
|
|
||||||
response identifiers from #GtkResponseType. For most dialog
|
|
||||||
boxes you can use your own custom response codes rather than the
|
|
||||||
ones in #GtkResponseType, but #GtkFileChooserDialog assumes that
|
|
||||||
its "accept"-type action, e.g. an "Open" or "Save" button,
|
|
||||||
<emphasis>will</emphasis> have one of the following response
|
|
||||||
codes:
|
|
||||||
<simplelist id="gtkfilechooserdialog-responses">
|
|
||||||
<member>#GTK_RESPONSE_ACCEPT</member>
|
|
||||||
<member>#GTK_RESPONSE_OK</member>
|
|
||||||
<member>#GTK_RESPONSE_YES</member>
|
|
||||||
<member>#GTK_RESPONSE_APPLY</member>
|
|
||||||
</simplelist>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This is because #GtkFileChooserDialog must intercept responses
|
|
||||||
and switch to folders if appropriate, rather than letting the
|
|
||||||
dialog terminate — the implementation uses these known
|
|
||||||
response codes to know which responses can be blocked if
|
|
||||||
appropriate.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
To summarize, make sure you use a <link
|
|
||||||
linkend="gtkfilechooserdialog-responses">stock response
|
|
||||||
code</link> when you use #GtkFileChooserDialog to ensure
|
|
||||||
proper operation.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<!-- ##### SECTION See_Also ##### -->
|
|
||||||
<para>
|
|
||||||
#GtkFileChooser, #GtkDialog
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<!-- ##### SECTION Stability_Level ##### -->
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### SECTION Image ##### -->
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### STRUCT GtkFileChooserDialog ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
|
|
||||||
<!-- ##### FUNCTION gtk_file_chooser_dialog_new ##### -->
|
|
||||||
<para>
|
|
||||||
|
|
||||||
</para>
|
|
||||||
|
|
||||||
@title:
|
|
||||||
@parent:
|
|
||||||
@action:
|
|
||||||
@first_button_text:
|
|
||||||
@Varargs:
|
|
||||||
@Returns:
|
|
||||||
|
|
||||||
|
|
||||||
@ -34,6 +34,134 @@
|
|||||||
|
|
||||||
#include <stdarg.h>
|
#include <stdarg.h>
|
||||||
|
|
||||||
|
|
||||||
|
/**
|
||||||
|
* SECTION:gtkfilechooserdialog
|
||||||
|
* @Short_description: A file chooser dialog, suitable for "File/Open" or "File/Save" commands
|
||||||
|
* @Title: GtkFileChooserDialog
|
||||||
|
* @See_also: #GtkFileChooser, #GtkDialog
|
||||||
|
*
|
||||||
|
* #GtkFileChooserDialog is a dialog box suitable for use with
|
||||||
|
* "File/Open" or "File/Save as" commands. This widget works by
|
||||||
|
* putting a #GtkFileChooserWidget inside a #GtkDialog. It exposes
|
||||||
|
* the #GtkFileChooserIface interface, so you can use all of the
|
||||||
|
* #GtkFileChooser functions on the file chooser dialog as well as
|
||||||
|
* those for #GtkDialog.
|
||||||
|
*
|
||||||
|
* Note that #GtkFileChooserDialog does not have any methods of its
|
||||||
|
* own. Instead, you should use the functions that work on a
|
||||||
|
* #GtkFileChooser.
|
||||||
|
*
|
||||||
|
* <example id="gtkfilechooser-typical-usage">
|
||||||
|
* <title>Typical usage</title>
|
||||||
|
* In the simplest of cases, you can the following code to use
|
||||||
|
* #GtkFileChooserDialog to select a file for opening:
|
||||||
|
* <para>
|
||||||
|
* <informalexample><programlisting>
|
||||||
|
* GtkWidget *dialog;
|
||||||
|
*
|
||||||
|
* dialog = gtk_file_chooser_dialog_new ("Open File",
|
||||||
|
* parent_window,
|
||||||
|
* GTK_FILE_CHOOSER_ACTION_OPEN,
|
||||||
|
* GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
|
||||||
|
* GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
|
||||||
|
* NULL);
|
||||||
|
*
|
||||||
|
* if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
|
||||||
|
* {
|
||||||
|
* char *filename;
|
||||||
|
*
|
||||||
|
* filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
|
||||||
|
* open_file (filename);
|
||||||
|
* g_free (filename);
|
||||||
|
* }
|
||||||
|
*
|
||||||
|
* gtk_widget_destroy (dialog);
|
||||||
|
* </programlisting></informalexample>
|
||||||
|
* </para>
|
||||||
|
* To use a dialog for saving, you can use this:
|
||||||
|
* <para>
|
||||||
|
* <informalexample><programlisting>
|
||||||
|
* GtkWidget *dialog;
|
||||||
|
*
|
||||||
|
* dialog = gtk_file_chooser_dialog_new ("Save File",
|
||||||
|
* parent_window,
|
||||||
|
* GTK_FILE_CHOOSER_ACTION_SAVE,
|
||||||
|
* GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
|
||||||
|
* GTK_STOCK_SAVE, GTK_RESPONSE_ACCEPT,
|
||||||
|
* NULL);
|
||||||
|
* gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
|
||||||
|
*
|
||||||
|
* if (user_edited_a_new_document)
|
||||||
|
* {
|
||||||
|
* gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (dialog), default_folder_for_saving);
|
||||||
|
* gtk_file_chooser_set_current_name (GTK_FILE_CHOOSER (dialog), "Untitled document");
|
||||||
|
* }
|
||||||
|
* else
|
||||||
|
* gtk_file_chooser_set_filename (GTK_FILE_CHOOSER (dialog), filename_for_existing_document);
|
||||||
|
*
|
||||||
|
* if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
|
||||||
|
* {
|
||||||
|
* char *filename;
|
||||||
|
*
|
||||||
|
* filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
|
||||||
|
* save_to_file (filename);
|
||||||
|
* g_free (filename);
|
||||||
|
* }
|
||||||
|
*
|
||||||
|
* gtk_widget_destroy (dialog);
|
||||||
|
* </programlisting></informalexample>
|
||||||
|
* </para>
|
||||||
|
* </example>
|
||||||
|
* <section id="gtkfilechooserdialog-response-codes">
|
||||||
|
* <title>Response Codes</title>
|
||||||
|
* #GtkFileChooserDialog inherits from #GtkDialog, so buttons that
|
||||||
|
* go in its action area have response codes such as
|
||||||
|
* #GTK_RESPONSE_ACCEPT and #GTK_RESPONSE_CANCEL. For example, you
|
||||||
|
* could call gtk_file_chooser_dialog_new() as follows:
|
||||||
|
* <para>
|
||||||
|
* <informalexample><programlisting>
|
||||||
|
* GtkWidget *dialog;
|
||||||
|
*
|
||||||
|
* dialog = gtk_file_chooser_dialog_new ("Open File",
|
||||||
|
* parent_window,
|
||||||
|
* GTK_FILE_CHOOSER_ACTION_OPEN,
|
||||||
|
* GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
|
||||||
|
* GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
|
||||||
|
* NULL);
|
||||||
|
* </programlisting></informalexample>
|
||||||
|
* </para>
|
||||||
|
* This will create buttons for "Cancel" and "Open" that use stock
|
||||||
|
* response identifiers from #GtkResponseType. For most dialog
|
||||||
|
* boxes you can use your own custom response codes rather than the
|
||||||
|
* ones in #GtkResponseType, but #GtkFileChooserDialog assumes that
|
||||||
|
* its "accept"-type action, e.g. an "Open" or "Save" button,
|
||||||
|
* <emphasis>will</emphasis> have one of the following response
|
||||||
|
* codes:
|
||||||
|
* <para>
|
||||||
|
* <simplelist id="gtkfilechooserdialog-responses">
|
||||||
|
* <member>#GTK_RESPONSE_ACCEPT</member>
|
||||||
|
* <member>#GTK_RESPONSE_OK</member>
|
||||||
|
* <member>#GTK_RESPONSE_YES</member>
|
||||||
|
* <member>#GTK_RESPONSE_APPLY</member>
|
||||||
|
* </simplelist>
|
||||||
|
* </para>
|
||||||
|
* This is because #GtkFileChooserDialog must intercept responses
|
||||||
|
* and switch to folders if appropriate, rather than letting the
|
||||||
|
* dialog terminate — the implementation uses these known
|
||||||
|
* response codes to know which responses can be blocked if
|
||||||
|
* appropriate.
|
||||||
|
* <para>
|
||||||
|
* <note>
|
||||||
|
* To summarize, make sure you use a
|
||||||
|
* <link linkend="gtkfilechooserdialog-responses">stock response code</link>
|
||||||
|
* when you use #GtkFileChooserDialog to ensure proper operation.
|
||||||
|
* </note>
|
||||||
|
* </para>
|
||||||
|
* </section>
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
#define GTK_FILE_CHOOSER_DIALOG_GET_PRIVATE(o) (GTK_FILE_CHOOSER_DIALOG (o)->priv)
|
#define GTK_FILE_CHOOSER_DIALOG_GET_PRIVATE(o) (GTK_FILE_CHOOSER_DIALOG (o)->priv)
|
||||||
|
|
||||||
static void gtk_file_chooser_dialog_finalize (GObject *object);
|
static void gtk_file_chooser_dialog_finalize (GObject *object);
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user