Typical usage

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

CtkFileChooserNative *native;
CtkFileChooserAction action = CTK_FILE_CHOOSER_ACTION_OPEN;
gint res;

native = ctk_file_chooser_native_new ("Open File",
                                      parent_window,
                                      action,
                                      "_Open",
                                      "_Cancel");

res = ctk_native_dialog_run (CTK_NATIVE_DIALOG (native));
if (res == CTK_RESPONSE_ACCEPT)
  {
    char *filename;
    CtkFileChooser *chooser = CTK_FILE_CHOOSER (native);
    filename = ctk_file_chooser_get_filename (chooser);
    open_file (filename);
    g_free (filename);
  }

g_object_unref (native);

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

CtkFileChooserNative *native;
CtkFileChooser *chooser;
CtkFileChooserAction action = CTK_FILE_CHOOSER_ACTION_SAVE;
gint res;

native = ctk_file_chooser_native_new ("Save File",
                                      parent_window,
                                      action,
                                      "_Save",
                                      "_Cancel");
chooser = CTK_FILE_CHOOSER (native);

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_native_dialog_run (CTK_NATIVE_DIALOG (native));
if (res == CTK_RESPONSE_ACCEPT)
  {
    char *filename;

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

g_object_unref (native);

For more information on how to best set up a file dialog, see CtkFileChooserDialog.

Response Codes

CtkFileChooserNative inherits from CtkNativeDialog, which means it will return CTK_RESPONSE_ACCEPT if the user accepted, and CTK_RESPONSE_CANCEL if he pressed cancel. It can also return CTK_RESPONSE_DELETE_EVENT if the window was unexpectedly closed.

Differences from CtkFileChooserDialog

There are a few things in the CtkFileChooser API that are not possible to use with CtkFileChooserNative, as such use would prohibit the use of a native dialog.

There is no support for the signals that are emitted when the user navigates in the dialog, including:

You can also not use the methods that directly control user navigation:

If you need any of the above you will have to use CtkFileChooserDialog directly.

No operations that change the the dialog work while the dialog is visible. Set all the properties that are required before showing the dialog.

Win32 details

On windows the IFileDialog implementation (added in Windows Vista) is used. It supports many of the features that CtkFileChooserDialog does, but there are some things it does not handle:

If any of these features are used the regular CtkFileChooserDialog will be used in place of the native one.

Portal details

When the org.freedesktop.portal.FileChooser portal is available on the session bus, it is used to bring up an out-of-process file chooser. Depending on the kind of session the application is running in, this may or may not be a CTK+ file chooser. In this situation, the following things are not supported and will be silently ignored:

macOS details

On macOS the NSSavePanel and NSOpenPanel classes are used to provide native file chooser dialogs. Some features provided by CtkFileChooserDialog are not supported:

ctk_file_chooser_native_new ()

CtkFileChooserNative *
ctk_file_chooser_native_new (const gchar *title,
                             CtkWindow *parent,
                             CtkFileChooserAction action,
                             const gchar *accept_label,
                             const gchar *cancel_label);

Creates a new CtkFileChooserNative.

Since: 3.20

ctk_file_chooser_native_get_accept_label ()

const char *
ctk_file_chooser_native_get_accept_label
                               (CtkFileChooserNative *self);

Retrieves the custom label text for the accept button.

Since: 3.20

ctk_file_chooser_native_set_accept_label ()

void
ctk_file_chooser_native_set_accept_label
                               (CtkFileChooserNative *self,
                                const char *accept_label);

Sets the custom label text for the accept button.

If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button.

Since: 3.20

ctk_file_chooser_native_get_cancel_label ()

const char *
ctk_file_chooser_native_get_cancel_label
                               (CtkFileChooserNative *self);

Retrieves the custom label text for the cancel button.

Since: 3.20

ctk_file_chooser_native_set_cancel_label ()

void
ctk_file_chooser_native_set_cancel_label
                               (CtkFileChooserNative *self,
                                const char *cancel_label);

Sets the custom label text for the cancel button.

If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button.

Since: 3.20