From fe65ec5b87569f8bd4ec5171b60bd7c9326163cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javier=20Jard=C3=B3n?= Date: Wed, 13 Apr 2011 22:17:51 +0100 Subject: [PATCH] Move documentation to inline comments: GtkFileChooserDialog --- docs/reference/gtk/tmpl/.gitignore | 1 + .../gtk/tmpl/gtkfilechooserdialog.sgml | 174 ------------------ gtk/gtkfilechooserdialog.c | 128 +++++++++++++ 3 files changed, 129 insertions(+), 174 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 7f5914723e..9e0934f7b9 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -39,6 +39,7 @@ gtkexpander.sgml gtkfeatures.sgml gtkfixed.sgml gtkfilechooserbutton.sgml +gtkfilechooserdialog.sgml gtkfilechooserwidget.sgml gtkfilefilter.sgml gtkfontbutton.sgml diff --git a/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml b/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml deleted file mode 100644 index cc798bcb5f..0000000000 --- a/docs/reference/gtk/tmpl/gtkfilechooserdialog.sgml +++ /dev/null @@ -1,174 +0,0 @@ - -GtkFileChooserDialog - - -A file chooser dialog, suitable for "File/Open" or "File/Save" commands - - - - #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. - - - - Typical usage - - - In the simplest of cases, you can the following code to use - #GtkFileChooserDialog to select a file for opening: - - - -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); - - - - To use a dialog for saving, you can use this: - - - -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); - - - -
- Response Codes - - - #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: - - - -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); - - - - 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, - will have one of the following response - codes: - - #GTK_RESPONSE_ACCEPT - #GTK_RESPONSE_OK - #GTK_RESPONSE_YES - #GTK_RESPONSE_APPLY - - - - - 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. - - - - - To summarize, make sure you use a stock response - code when you use #GtkFileChooserDialog to ensure - proper operation. - - -
- - - - #GtkFileChooser, #GtkDialog - - - - - - - - - - - - - - - - - - - -@title: -@parent: -@action: -@first_button_text: -@Varargs: -@Returns: - - diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c index cf0dd75a6b..ea19777c7b 100644 --- a/gtk/gtkfilechooserdialog.c +++ b/gtk/gtkfilechooserdialog.c @@ -34,6 +34,134 @@ #include + +/** + * 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. + * + * + * Typical usage + * In the simplest of cases, you can the following code to use + * #GtkFileChooserDialog to select a file for opening: + * + * + * 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); + * + * + * To use a dialog for saving, you can use this: + * + * + * 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); + * + * + * + *
+ * Response Codes + * #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: + * + * + * 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); + * + * + * 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, + * will have one of the following response + * codes: + * + * + * #GTK_RESPONSE_ACCEPT + * #GTK_RESPONSE_OK + * #GTK_RESPONSE_YES + * #GTK_RESPONSE_APPLY + * + * + * 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. + * + * + * To summarize, make sure you use a + * stock response code + * when you use #GtkFileChooserDialog to ensure proper operation. + * + * + *
+ */ + + #define GTK_FILE_CHOOSER_DIALOG_GET_PRIVATE(o) (GTK_FILE_CHOOSER_DIALOG (o)->priv) static void gtk_file_chooser_dialog_finalize (GObject *object);