gtk2/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml

<!-- ##### 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: