AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Move documentation to inline comments: GtkFileChooserDialog

Browse Source
This commit is contained in:
Javier Jardón 2011-04-13 22:17:51 +01:00
parent 2da9a5791f
commit fe65ec5b87
3 changed files with 129 additions and 174 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gtk/tmpl/.gitignore vendored
View File

@ -39,6 +39,7 @@ gtkexpander.sgml
gtkfeatures.sgml
gtkfixed.sgml
gtkfilechooserbutton.sgml
gtkfilechooserdialog.sgml
gtkfilechooserwidget.sgml
gtkfilefilter.sgml
gtkfontbutton.sgml

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

@ -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 &mdash; 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:

128
gtk/gtkfilechooserdialog.c
View File

@ -34,6 +34,134 @@
#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 &mdash; 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)
static void gtk_file_chooser_dialog_finalize (GObject *object);