forked from AuroraMiddleware/gtk
544dfb8169
2004-03-26 Federico Mena Quintero <federico@ximian.com> * gtk/tmpl/gtkfilechooserdialog.sgml: Added a section about using known response codes for "accept"-type buttons, rather than custom responses. This is related to bugs #136237 and #138263.
154 lines
3.9 KiB
Plaintext
154 lines
3.9 KiB
Plaintext
<!-- ##### 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 use #GtkFileChooserDialog
|
|
as in the following code:
|
|
</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>
|
|
</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>
|
|
|
|
<!-- ##### STRUCT GtkFileChooserDialog ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_file_chooser_dialog_new ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@title:
|
|
@parent:
|
|
@action:
|
|
@first_button_text:
|
|
@Varargs:
|
|
@Returns:
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_file_chooser_dialog_new_with_backend ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@title:
|
|
@parent:
|
|
@action:
|
|
@backend:
|
|
@first_button_text:
|
|
@Varargs:
|
|
@Returns:
|
|
|
|
|
|
<!--
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-parent-document: ("../gtk-docs.sgml" "book" "refsect1")
|
|
End:
|
|
-->
|