CtkFileChooserDialog: CTK+ 3 Reference Manual

CtkFileChooserDialog

CtkFileChooserDialog — A file chooser dialog, suitable for “File/Open” or “File/Save” commands

Functions

CtkWidget *

ctk_file_chooser_dialog_new ()

Types and Values

struct

CtkFileChooserDialog

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── CtkWidget
            ╰── CtkContainer
                ╰── CtkBin
                    ╰── CtkWindow
                        ╰── CtkDialog
                            ╰── CtkFileChooserDialog

Implemented Interfaces

CtkFileChooserDialog implements AtkImplementorIface, CtkBuildable and CtkFileChooser.

Includes

#include <ctk/ctk.h>

Description

CtkFileChooserDialog is a dialog box suitable for use with “File/Open” or “File/Save as” commands. This widget works by putting a CtkFileChooserWidget inside a CtkDialog. It exposes the CtkFileChooser interface, so you can use all of the CtkFileChooser functions on the file chooser dialog as well as those for CtkDialog.

Note that CtkFileChooserDialog does not have any methods of its own. Instead, you should use the functions that work on a CtkFileChooser.

If you want to integrate well with the platform you should use the CtkFileChooserNative API, which will use a platform-specific dialog if available and fall back to CtkFileChooserDialog otherwise.

Typical usage

In the simplest of cases, you can the following code to use CtkFileChooserDialog to select a file for opening:

CtkWidget *dialog;
CtkFileChooserAction action = CTK_FILE_CHOOSER_ACTION_OPEN;
gint res;

dialog = ctk_file_chooser_dialog_new ("Open File",
                                      parent_window,
                                      action,
                                      _("_Cancel"),
                                      CTK_RESPONSE_CANCEL,
                                      _("_Open"),
                                      CTK_RESPONSE_ACCEPT,
                                      NULL);

res = ctk_dialog_run (CTK_DIALOG (dialog));
if (res == CTK_RESPONSE_ACCEPT)
  {
    char *filename;
    CtkFileChooser *chooser = CTK_FILE_CHOOSER (dialog);
    filename = ctk_file_chooser_get_filename (chooser);
    open_file (filename);
    g_free (filename);
  }

ctk_widget_destroy (dialog);

To use a dialog for saving, you can use this:

CtkWidget *dialog;
CtkFileChooser *chooser;
CtkFileChooserAction action = CTK_FILE_CHOOSER_ACTION_SAVE;
gint res;

dialog = ctk_file_chooser_dialog_new ("Save File",
                                      parent_window,
                                      action,
                                      _("_Cancel"),
                                      CTK_RESPONSE_CANCEL,
                                      _("_Save"),
                                      CTK_RESPONSE_ACCEPT,
                                      NULL);
chooser = CTK_FILE_CHOOSER (dialog);

ctk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);

if (user_edited_a_new_document)
  ctk_file_chooser_set_current_name (chooser,
                                     _("Untitled document"));
else
  ctk_file_chooser_set_filename (chooser,
                                 existing_filename);

res = ctk_dialog_run (CTK_DIALOG (dialog));
if (res == CTK_RESPONSE_ACCEPT)
  {
    char *filename;

    filename = ctk_file_chooser_get_filename (chooser);
    save_to_file (filename);
    g_free (filename);
  }

ctk_widget_destroy (dialog);

Setting up a file chooser dialog

There are various cases in which you may need to use a CtkFileChooserDialog:

To select a file for opening. Use CTK_FILE_CHOOSER_ACTION_OPEN.
To save a file for the first time. Use CTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as “Untitled” with ctk_file_chooser_set_current_name().
To save a file under a different name. Use CTK_FILE_CHOOSER_ACTION_SAVE, and set the existing filename with ctk_file_chooser_set_filename().
To choose a folder instead of a file. Use CTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.

Note that old versions of the file chooser’s documentation suggested using ctk_file_chooser_set_current_folder() in various situations, with the intention of letting the application suggest a reasonable default folder. This is no longer considered to be a good policy, as now the file chooser is able to make good suggestions on its own. In general, you should only cause the file chooser to show a specific folder when it is appropriate to use ctk_file_chooser_set_filename(), i.e. when you are doing a Save As command and you already have a file saved somewhere.

Response Codes

CtkFileChooserDialog inherits from CtkDialog, so buttons that go in its action area have response codes such as CTK_RESPONSE_ACCEPT and CTK_RESPONSE_CANCEL. For example, you could call ctk_file_chooser_dialog_new() as follows:

CtkWidget *dialog;
CtkFileChooserAction action = CTK_FILE_CHOOSER_ACTION_OPEN;

dialog = ctk_file_chooser_dialog_new ("Open File",
                                      parent_window,
                                      action,
                                      _("_Cancel"),
                                      CTK_RESPONSE_CANCEL,
                                      _("_Open"),
                                      CTK_RESPONSE_ACCEPT,
                                      NULL);

This will create buttons for “Cancel” and “Open” that use stock response identifiers from CtkResponseType. For most dialog boxes you can use your own custom response codes rather than the ones in CtkResponseType, but CtkFileChooserDialog assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes:

This is because CtkFileChooserDialog 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 CtkFileChooserDialog to ensure proper operation.

Functions

ctk_file_chooser_dialog_new ()

CtkWidget *
ctk_file_chooser_dialog_new (const gchar *title,
                             CtkWindow *parent,
                             CtkFileChooserAction action,
                             const gchar *first_button_text,
                             ...);

Creates a new CtkFileChooserDialog. This function is analogous to ctk_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]
...	response ID for the first button, then additional (button, id) pairs, ending with `NULL`

Returns

a new CtkFileChooserDialog

Since: 2.4

Types and Values

struct CtkFileChooserDialog

struct CtkFileChooserDialog;