gtkfilechooserdialog.sgml 4.79 KB
Newer Older
1 2 3 4
<!-- ##### SECTION Title ##### -->
GtkFileChooserDialog

<!-- ##### SECTION Short_Description ##### -->
5
A file chooser dialog, suitable for "File/Open" or "File/Save" commands
6 7

<!-- ##### SECTION Long_Description ##### -->
8 9 10 11 12 13 14 15
    <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>
16

17 18 19 20 21
    <para>
      Note that #GtkFileChooserDialog does not have any methods of its
      own.  Instead, you should use the functions that work on a
      #GtkFileChooser.
    </para>
22

23
    <example id="gtkfilechooser-typical-usage">
24
      <title>Typical usage</title>
25

26
      <para>
27 28
	In the simplest of cases, you can the following code to use
	#GtkFileChooserDialog to select a file for opening:
29 30 31 32 33 34 35 36 37
      </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,
38
				      GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
39 40 41 42 43 44 45 46 47 48 49
				      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);
  }

50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
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);

68 69 70 71 72 73 74 75 76
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);


77 78 79 80 81 82 83 84 85
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);
  }

86 87 88 89
gtk_widget_destroy (dialog);
      </programlisting>
    </example>

90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
  <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>

145 146 147 148
<!-- ##### SECTION See_Also ##### -->
    <para>
      #GtkFileChooser, #GtkDialog
    </para>
149

Matthias Clasen's avatar
2.7.0  
Matthias Clasen committed
150 151 152
<!-- ##### SECTION Stability_Level ##### -->


153
<!-- ##### SECTION Image ##### -->
Owen Taylor's avatar
Owen Taylor committed
154 155


156
<!-- ##### STRUCT GtkFileChooserDialog ##### -->
157 158 159 160 161
<para>

</para>


162
<!-- ##### FUNCTION gtk_file_chooser_dialog_new ##### -->
Owen Taylor's avatar
Owen Taylor committed
163 164 165 166 167 168 169 170 171 172 173 174
<para>

</para>

@title: 
@parent: 
@action: 
@first_button_text: 
@Varargs: 
@Returns: