GtkFileChooserDialog: GTK+ 2 Reference Manual

GtkFileChooserDialog

GtkFileChooserDialog — A file chooser dialog, suitable for "File/Open" or "File/Save" commands

Functions

GtkWidget *	gtk_file_chooser_dialog_new ()
GtkWidget *	gtk_file_chooser_dialog_new_with_backend ()

Types and Values

struct

GtkFileChooserDialog

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkWindow
                            ╰── GtkDialog
                                ╰── GtkFileChooserDialog

Implemented Interfaces

GtkFileChooserDialog implements AtkImplementorIface, GtkBuildable and GtkFileChooser.

Includes

#include <gtk/gtk.h>

Description

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 45. 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:

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.

Functions

gtk_file_chooser_dialog_new ()

GtkWidget *
gtk_file_chooser_dialog_new (const gchar *title,
                             GtkWindow *parent,
                             GtkFileChooserAction action,
                             const gchar *first_button_text,
                             ...);

Creates a new GtkFileChooserDialog. This function is analogous to gtk_dialog_new_with_buttons().

Parameters

title	Title of the dialog, or `NULL`.	[allow-none]
parent	Transient parent of the dialog, or `NULL`.	[allow-none]
action	Open or save mode for the dialog
first_button_text	stock ID or text to go in the first button, or `NULL`.	[allow-none]

Returns

a new GtkFileChooserDialog

Since 2.4

gtk_file_chooser_dialog_new_with_backend ()

GtkWidget *
gtk_file_chooser_dialog_new_with_backend
                               (const gchar *title,
                                GtkWindow *parent,
                                GtkFileChooserAction action,
                                const gchar *backend,
                                const gchar *first_button_text,
                                ...);

gtk_file_chooser_dialog_new_with_backend has been deprecated since version 2.14 and should not be used in newly-written code.

Use gtk_file_chooser_dialog_new() instead.

Creates a new GtkFileChooserDialog with a specified backend. This is especially useful if you use gtk_file_chooser_set_local_only() to allow non-local files and you use a more expressive vfs, such as gnome-vfs, to load files.

Parameters

title	Title of the dialog, or `NULL`.	[allow-none]
parent	Transient parent of the dialog, or `NULL`.	[allow-none]
action	Open or save mode for the dialog
backend	The name of the specific filesystem backend to use.
first_button_text	stock ID or text to go in the first button, or `NULL`.	[allow-none]

Returns

a new GtkFileChooserDialog

Since 2.4

Types and Values

struct GtkFileChooserDialog

struct GtkFileChooserDialog;