sfcd_get_type ()

GType
sfcd_get_type (void);

sfcd_is_accept_label ()

gboolean
sfcd_is_accept_label (const gchar *label);

Verifies whether a button label would be valid for use in a button with a response id suggesting the user accepts a file being selected. This function automatically removes underscores from labels before performing a comparison so you don't need to do it yourself.

The SfcdAcceptLabels array defines labels that are considered acceptable. indicating user acceptance. If you attempt to add a button to a SandboxFileChooserDialog with a response id among GTK_RESPONSE_ACCEPT, GTK_RESPONSE_OK, GTK_RESPONSE_YES or GTK_RESPONSE_APPLY and with a button not contained in SfcdAcceptLabels, it will be rejected and will not appear. This is to prevent malicious applications from tricking a user into accepting a file selection when they cancel an undesired dialog.

The current list of SfcdAcceptLabels goes as follows:

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
33
34
35
36
37
38
39
40
41
42

const gchar *SfcdAcceptLabels[] =
{
  "Accept",
  "Next",
  "Ok",
  "Choose",
  "Confirm",
  "Pick",
  "Yes",
  "Apply",
  "Select",
  "Add",
  "Append",
  "Save",
  "Save as...",
  "Save Copy",
  "Export",
  "Create",
  "Send",
  "Upload",
  "Rename",
  "Write",
  "Merge",
  "Extract",
  "Open",
  "Open as...",
  "Open Copy",
  "Open Read-Only",
  "Import",
  "Print",
  "Read",
  "View",
  "Preview",
  "Load",
  "Download",
  "Play",
  "Enqueue",
  "Attach",
  "Extract",
  "Compare",
  NULL
};

SfcdAcceptLabels

Since 0.4

sfcd_new ()

SandboxFileChooserDialog *
sfcd_new (const gchar *title,
          GtkWindow *parent,
          GtkFileChooserAction action,
          const gchar *first_button_text,
          ...);

Creates a new SandboxFileChooserDialog. Depending on the settings of Sandbox Utils (see sandboxutils_init()), this may either spawn a locally-owned GTK+ dialog or a handle to a remotely-owned dialog controlled over D-Bus.

This is equivalent to gtk_file_chooser_dialog_new() in the GTK+ API.

Since 0.5

sfcd_destroy ()

void
sfcd_destroy (SandboxFileChooserDialog *dialog);

Destroys the given instance of SandboxFileChooserDialog. Internally, this method only removes one reference to the dialog, so it may continue existing if you still have other references to it.

This method can be called from any SfcdState. It is equivalent to gtk_widget_destroy() in the GTK+ API.

Since 0.3

sfcd_get_state ()

SfcdState
sfcd_get_state (SandboxFileChooserDialog *dialog);

Gets the current SfcdState of an instance of SandboxFileChooserDialog.

This method can be called from any SfcdState. It has no GTK+ equivalent.

Since 0.3

sfcd_get_state_printable ()

const gchar *
sfcd_get_state_printable (SandboxFileChooserDialog *dialog);

Gets the current SfcdState of an instance of SandboxFileChooserDialog, in the form of a string that can be displayed. The string is not localized.

This method can be called from any SfcdState. It has no GTK+ equivalent.

Since 0.3

sfcd_get_dialog_title ()

const gchar *
sfcd_get_dialog_title (SandboxFileChooserDialog *dialog);

Gets the title of the GtkFileChooserDialog embedded in an instance of SandboxFileChooserDialog.

This method can be called from any SfcdState. It is equivalent to gtk_window_get_title() in the GTK+ API.

Since 0.3

sfcd_is_running ()

gboolean
sfcd_is_running (SandboxFileChooserDialog *dialog);

Returns whether an instance of SandboxFileChooserDialog is currently running, e.g., it is in the SFCD_RUNNING SfcdState.

This method can be called from any SfcdState. It has no GTK+ equivalent.

Since 0.3

sfcd_get_id ()

const gchar *
sfcd_get_id (SandboxFileChooserDialog *dialog);

Gets the identifier of the dialog . If dialog is a LocalFileChooserDialog, the identifier typically a unique string produced by the local process. If dialog is a RemoteFileChooserDialog, the identifier is produced by the remote process actually providing the dialog.

This method can be called from any SfcdState. It has no GTK+ equivalent.

Since 0.5

sfcd_run ()

void
sfcd_run (SandboxFileChooserDialog *dialog,
          GError **error);

Starts running the dialog in a separate GMainLoop. Contrarily to the GTK+ gtk_dialog_run() method advocated to run a GtkFileChooserDialog, this method does not block until a response has been received by the dialog. One should register a callback on the “response” signal instead. For instance, consider the following code taken from the GTK+ documentation:

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

GtkWidget *dialog;

dialog = gtk_file_chooser_dialog_new ("Open File",
                                      parent_window,
                                      GTK_FILE_CHOOSER_ACTION_OPEN,
                                      _("_Cancel"), GTK_RESPONSE_CANCEL,
                                      _("_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);

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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

static void
on_open_dialog_response (SandboxFileChooserDialog *dialog,
                         gint                      response_id,
                         gpointer                  user_data)
{
  if (response_id == GTK_RESPONSE_OK)
  {
    GError *error = NULL;
    gchar *filename = sfcd_get_filename (dialog, error);

    // Check for errors - the server might've crashed, or a security policy
    // could be getting in the way.
    if (!error)
    {
      my_app_open_file (filename);
      g_free (filename);
    }
    else
    {
      my_app_report_error (error);
      g_error_free (error);
    }
  }

  sfcd_destroy (dialog);
}

[...]

void
my_open_function ()
{
  SandboxFileChooserDialog *dialog;

  dialog = sfcd_new (TRUE, // use the remote dialog that passes through sandboxing
                     "Open File",
                     parent_window,
                     GTK_FILE_CHOOSER_ACTION_OPEN,
                     _("_Cancel"), GTK_RESPONSE_CANCEL,
                     _("_Open"), GTK_RESPONSE_ACCEPT,
                     NULL);

  // Ask the dialog to tell us when the user picked a file
  g_signal_connect (dialog,
                    "response",
                    G_CALLBACK (on_open_dialog_response),
                    user_data);

  GError *error = NULL;
  sfcd_run (dialog, error);

  // Make sure to verify that the dialog is running
  if (error)
  {
    my_app_report_error (error);
    g_error_free (filename);
  }
}

Note that if the dialog was destroyed, you will never hear from it again. If you kept an extra reference to the dialog via g_object_ref(), make sure to also connect to “destroy” and to drop that reference when receiving this signal (with g_object_unref()).

This method can be called from the SFCD_CONFIGURATION or SFCD_DATA_RETRIEVAL states. It is roughly to gtk_dialog_run() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_present ()

void
sfcd_present (SandboxFileChooserDialog *dialog,
              GError **error);

Presents a currently running instance of SandboxFileChooserDialog. This method fails if the dialog is not running.

This method belongs to the SFCD_RUNNING state. It is equivalent to gtk_window_present() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_cancel_run ()

void
sfcd_cancel_run (SandboxFileChooserDialog *dialog,
                 GError **error);

Cancels a currently running instance of SandboxFileChooserDialog. This method fails if the dialog is not running. Internally, it hides the dialog's window which causes it to unmap, and the running loop will catch the unmap signal and emit a “response” signal. The response_id will be set to GTK_RESPONSE_NONE, which you should ignore in the callbacks you connected to this signal. the dialog will be back into a SFCD_CONFIGURATION SfcdState.

After being cancelled, the dialog still exists. If you no longer need it, destroy it with sfcd_destroy(). Note that you can also directly destroy the dialog while running.

This method belongs to the SFCD_RUNNING state. It is equivalent to gtk_widget_hide() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_set_destroy_with_parent ()

void
sfcd_set_destroy_with_parent (SandboxFileChooserDialog *dialog,
                              gboolean setting);

If setting is TRUE, then destroying the transient parent of window will also destroy window itself. This is useful for dialogs that shouldn't persist beyond the lifetime of the main window they're associated with, for example.

This method can be called from any SfcdState. It is equivalent to gtk_window_set_destroy_with_parent() in the GTK+ API.

Since 0.5

sfcd_get_destroy_with_parent ()

gboolean
sfcd_get_destroy_with_parent (SandboxFileChooserDialog *dialog);

Returns whether the window will be destroyed with its transient parent; See sfcd_set_destroy_with_parent() for more information.

This method can be called from any SfcdState. It is equivalent to gtk_window_get_destroy_with_parent() in the GTK+ API.

Since 0.5

sfcd_set_extra_widget ()

void
sfcd_set_extra_widget (SandboxFileChooserDialog *dialog,
                       GtkWidget *widget,
                       GError **error);

Sets an application-supplied widget to provide extra options to the user. Note that this widget does not have access to the internal structure of the SandboxFileChooserDialog or the underlying file system when sandboxed; it runs with the privileges of your own application.

This method can be called from any SfcdState. It is equivalent to gtk_file_chooser_set_extra_widget() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.5

sfcd_get_extra_widget ()

GtkWidget *
sfcd_get_extra_widget (SandboxFileChooserDialog *dialog,
                       GError **error);

Gets the GtkWidget that was added to dialog with sfcd_set_extra_widget().

This method can be called from any SfcdState. It is equivalent to gtk_file_chooser_get_extra_widget() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.5

sfcd_select_filename ()

void
sfcd_select_filename (SandboxFileChooserDialog *dialog,
                      const gchar *filename,
                      GError **error);

Selects a filename. If the file name isn't in the current folder of dialog , then the current folder of dialog will be changed to the folder containing filename .

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_select_filename() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

See also: sfcd_set_filename()

Since 0.6

sfcd_unselect_filename ()

void
sfcd_unselect_filename (SandboxFileChooserDialog *dialog,
                        const gchar *filename,
                        GError **error);

Unselects a currently selected filename. If the filename is not in the current directory, does not exist, or is otherwise not currently selected, does nothing.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_unselect_filename() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.6

sfcd_select_all ()

void
sfcd_select_all (SandboxFileChooserDialog *dialog,
                 GError **error);

Selects all the files in the current folder of a dialog.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_select_all() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.6

sfcd_unselect_all ()

void
sfcd_unselect_all (SandboxFileChooserDialog *dialog,
                   GError **error);

Unselects all the files in the current folder of a dialog.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_unselect_all() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.6

sfcd_select_uri ()

void
sfcd_select_uri (SandboxFileChooserDialog *dialog,
                 const gchar *uri,
                 GError **error);

Selects the file to by uri . If the URI doesn't refer to a file in the current folder of dialog , then the current folder of dialog will be changed to the folder containing filename .

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_select_uri() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.6

sfcd_unselect_uri ()

void
sfcd_unselect_uri (SandboxFileChooserDialog *dialog,
                   const gchar *uri,
                   GError **error);

Unselects the file referred to by uri . If the file is not in the current directory, does not exist, or is otherwise not currently selected, does nothing.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_unselect_uri() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.6

sfcd_set_action ()

void
sfcd_set_action (SandboxFileChooserDialog *dialog,
                 GtkFileChooserAction action,
                 GError **error);

Sets the GtkFileChooserAction that the dialog is performing. This influences whether the dialog will allow your user to open or save files, or to select or create folders. Look up the GtkFileChooser documentation for information on which types of are available.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_action() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.4

sfcd_get_action ()

GtkFileChooserAction
sfcd_get_action (SandboxFileChooserDialog *dialog,
                 GError **error);

Gets the GtkFileChooserAction that the dialog is performing; See sfcd_set_action() for more information.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_get_action() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.4

sfcd_set_local_only ()

void
sfcd_set_local_only (SandboxFileChooserDialog *dialog,
                     gboolean local_only,
                     GError **error);

Sets whether only local files can be selected in the dialog. If local_only is TRUE (the default), then the selected files are guaranteed to be accessible through the operating systems native file system and therefore the application only needs to worry about the filename functions in SandboxFileChooserDialog, like sfcd_get_filename(), rather than the URI functions like sfcd_get_uri(),

On some systems non-native files may still be available using the native filesystem via a userspace filesystem (FUSE).

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_local_only() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_get_local_only ()

gboolean
sfcd_get_local_only (SandboxFileChooserDialog *dialog,
                     GError **error);

Gets whether only local files can be selected in the dialog; See sfcd_set_local_only() for more information.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_get_local_only() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.3

sfcd_set_select_multiple ()

void
sfcd_set_select_multiple (SandboxFileChooserDialog *dialog,
                          gboolean select_multiple,
                          GError **error);

Sets whether multiple files can be selected in the dialog. This is only relevant if the action is set to be GTK_FILE_CHOOSER_ACTION_OPEN or GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_select_multiple() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_get_select_multiple ()

gboolean
sfcd_get_select_multiple (SandboxFileChooserDialog *dialog,
                          GError **error);

Gets whether multiple files can be selected in the dialog; See sfcd_set_select_multiple() for more information.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_get_select_multiple() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.3

sfcd_set_show_hidden ()

void
sfcd_set_show_hidden (SandboxFileChooserDialog *dialog,
                      gboolean show_hidden,
                      GError **error);

Sets whether hidden files and folders are displayed in the file dialog.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_show_hidden() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_get_show_hidden ()

gboolean
sfcd_get_show_hidden (SandboxFileChooserDialog *dialog,
                      GError **error);

Gets whether hidden files and folders are displayed in the dialog; See sfcd_set_show_hidden() for more information.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_get_show_hidden() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.3

sfcd_set_do_overwrite_confirmation ()

void
sfcd_set_do_overwrite_confirmation (SandboxFileChooserDialog *dialog,
                                    gboolean do_overwrite_confirmation,
                                    GError **error);

Sets whether a dialog in GTK_FILE_CHOOSER_ACTION_SAVE mode will present a confirmation dialog if the user types a file name that already exists. This is FALSE by default.

If set to TRUE, the dialog will show a stock confirmation dialog. There is currently no way to override this dialog, though customization will be allowed in the future, including proposing an alternative name based on the autocompletion plugin.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_do_overwrite_confirmation() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_get_do_overwrite_confirmation ()

gboolean
sfcd_get_do_overwrite_confirmation (SandboxFileChooserDialog *dialog,
                                    GError **error);

Gets whether a dialog is set to confirm for overwriting when the user types a file name that already exists; See sfcd_set_do_overwrite_confirmation() for more information.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_get_do_overwrite_confirmation() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.3

sfcd_set_create_folders ()

void
sfcd_set_create_folders (SandboxFileChooserDialog *dialog,
                         gboolean create_folders,
                         GError **error);

Sets whether the dialog will offer to create new folders. This is only relevant if the action is not set to be GTK_FILE_CHOOSER_ACTION_OPEN.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_create_folders() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_get_create_folders ()

gboolean
sfcd_get_create_folders (SandboxFileChooserDialog *dialog,
                         GError **error);

Gets whether the dialog will offer to create new folders; See sfcd_set_create_folders() for more information.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_get_create_folders() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.3

sfcd_set_current_name ()

void
sfcd_set_current_name (SandboxFileChooserDialog *dialog,
                       const gchar *name,
                       GError **error);

Sets the current name in the dialog, as if entered by the user. Note that the name passed in here is a UTF-8 string rather than a filename. This function is meant for such uses as a suggested name in a "Save As..." dialog. You can pass "Untitled.odt" or a similarly suitable suggestion for the name .

If you want to preselect a particular existing file, you should use sfcd_set_filename() or sfcd_set_uri() instead. Please see the documentation for those functions for an example of using sfcd_set_current_name() as well.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_current_name() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_set_filename ()

void
sfcd_set_filename (SandboxFileChooserDialog *dialog,
                   const gchar *filename,
                   GError **error);

Sets filename as the current filename for the dialog, by changing to the file's parent folder and actually selecting the file in list; all other files will be unselected. If the dialog is in GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name will also appear in the dialog's file name entry.

Note that the file must exist, or nothing will be done except for the directory change.

You should use this function only when implementing a File/Save As... dialog for which you already have a file name to which the user may save. For example, when the user opens an existing file and then does Save As... on it to save a copy or a modified version. If you don't have a file name already — for example, if the user just created a new file and is saving it for the first time, do not call this function. Instead, use something similar to this:

1
2
3
4
5
6
7
8
9
10

if (document_is_new)
  {
    /* the user just created a new document */
    sfcd_set_current_name (chooser, "Untitled document");
  }
else
  {
    /* the user edited an existing document */ 
    sfcd_set_filename (chooser, existing_filename);
  }

In the first case, the dialog will present the user with useful suggestions as to where to save his new file. In the second case, the file's existing location is already known, so the dialog will use it.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_filename() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_set_current_folder ()

void
sfcd_set_current_folder (SandboxFileChooserDialog *dialog,
                         const gchar *filename,
                         GError **error);

Sets the current folder for dialog from a local filename. The user will be shown the full contents of the current folder, plus user interface elements for navigating to other folders.

In general, you should not use this function. You should only cause the dialog to show a specific folder when it is appropriate to use sfcd_set_filename(), i.e. when you are doing a Save As... command and you already have a file saved somewhere.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_current_folder() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_set_uri ()

void
sfcd_set_uri (SandboxFileChooserDialog *dialog,
              const gchar *uri,
              GError **error);

Sets the file referred to by uri as the current file for the dialog , by changing to the URI's parent folder and actually selecting the URI in the list. If the dialog is GTK_FILE_CHOOSER_ACTION_SAVE mode, the URI's base name will also appear in the dialog's file name entry.

Note that the URI must exist, or nothing will be done except for the directory change.

You should use this function only when implementing a File/Save As... dialog for which you already have a file name to which the user may save. For example, when the user opens an existing file and then does Save As... on it to save a copy or a modified version. If you don't have a file name already — for example, if the user just created a new file and is saving it for the first time, do not call this function. Instead, use something similar to this:

1
2
3
4
5
6
7
8
9
10

if (document_is_new)
  {
    /* the user just created a new document */
    sfcd_set_current_name (chooser, "Untitled document");
  }
else
  {
    /* the user edited an existing document */ 
    sfcd_set_filename (chooser, existing_filename);
  }

In the first case, the dialog will present the user with useful suggestions as to where to save his new file. In the second case, the file's existing location is already known, so the dialog will use it.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_uri() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_set_current_folder_uri ()

void
sfcd_set_current_folder_uri (SandboxFileChooserDialog *dialog,
                             const gchar *uri,
                             GError **error);

Sets the current folder for dialog from an URI. The user will be shown the full contents of the current folder, plus user interface elements for navigating to other folders.

In general, you should not use this function. You should only cause the dialog to show a specific folder when it is appropriate to use sfcd_set_uri(), i.e. when you are doing a Save As... command and you already have a file saved somewhere.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_set_current_folder_uri() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_add_shortcut_folder ()

gboolean
sfcd_add_shortcut_folder (SandboxFileChooserDialog *dialog,
                          const gchar *folder,
                          GError **error);

Adds a folder to be displayed with the shortcut folders in a dialog. Note that shortcut folders do not get saved, as they are provided by the application. For example, you can use this to add a "/usr/share/mydrawprogram/Clipart" folder to the volume list.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_add_shortcut_folder() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_remove_shortcut_folder ()

gboolean
sfcd_remove_shortcut_folder (SandboxFileChooserDialog *dialog,
                             const gchar *folder,
                             GError **error);

Removes a folder from a dialog's list of shortcut folders.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_remove_shortcut_folder() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_list_shortcut_folders ()

GSList *
sfcd_list_shortcut_folders (SandboxFileChooserDialog *dialog,
                            GError **error);

Queries the list of shortcut folders in the dialog, as set by sfcd_add_shortcut_folder().

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to sfcd_list_shortcut_folders() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_add_shortcut_folder_uri ()

gboolean
sfcd_add_shortcut_folder_uri (SandboxFileChooserDialog *dialog,
                              const gchar *uri,
                              GError **error);

Adds a folder URI to be displayed with the shortcut folders in a dialog. Note that shortcut folders do not get saved, as they are provided by the application. For example, you can use this to add a "file:///usr/share/mydrawprogram/Clipart" folder to the volume list.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_add_shortcut_folder_uri() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_remove_shortcut_folder_uri ()

gboolean
sfcd_remove_shortcut_folder_uri (SandboxFileChooserDialog *dialog,
                                 const gchar *uri,
                                 GError **error);

Removes a folder URI from a dialog's list of shortcut folders.

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to gtk_file_chooser_remove_shortcut_folder_uri() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_list_shortcut_folder_uris ()

GSList *
sfcd_list_shortcut_folder_uris (SandboxFileChooserDialog *dialog,
                                GError **error);

Queries the list of shortcut folders in the dialog, as set by sfcd_add_shortcut_folder_uri().

This method belongs to the SFCD_CONFIGURATION state. It is equivalent to sfcd_list_shortcut_folder_uris() in the GTK+ API. Do remember to check if error is set after running this method.

Since 0.3

sfcd_get_current_name ()

gchar *
sfcd_get_current_name (SandboxFileChooserDialog *dialog,
                       GError **error);

Gets the current name in the dialog , as entered by the user in the text entry for "Name".

This is meant to be used in save dialogs, to get the currently typed filename when the file itself does not exist yet. For example, an application that adds a custom extra widget to the dialog for "file format" may want to change the extension of the typed filename based on the chosen format, say, from ".jpg" to ".png".

This method belongs to the SFCD_DATA_RETRIEVAL state. It is equivalent to gtk_file_chooser_get_current_name() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.4

sfcd_get_filename ()

gchar *
sfcd_get_filename (SandboxFileChooserDialog *dialog,
                   GError **error);

Gets the filename for the currently selected file in the dialog. The filename is returned as an absolute path. If multiple files are selected, one of the filenames will be returned at random.

If the dialog is in folder mode, this function returns the selected folder.

This method belongs to the SFCD_DATA_RETRIEVAL state. It is equivalent to gtk_file_chooser_get_filename() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.4

sfcd_get_filenames ()

GSList *
sfcd_get_filenames (SandboxFileChooserDialog *dialog,
                    GError **error);

sfcd_get_current_folder ()

gchar *
sfcd_get_current_folder (SandboxFileChooserDialog *dialog,
                         GError **error);

Gets the current folder of dialog as a local filename. See sfcd_set_current_folder().

Note that this is the folder that the dialog is currently displaying (e.g. "/home/username/Documents"), which is not the same as the currently-selected folder if the dialog is in GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER mode (e.g. "/home/username/Documents/selected-folder/". To get the currently-selected folder in that mode, use sfcd_get_uri() as the usual way to get the selection.

This method belongs to the SFCD_DATA_RETRIEVAL state. It is equivalent to gtk_file_chooser_get_current_folder() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.4

sfcd_get_uri ()

gchar *
sfcd_get_uri (SandboxFileChooserDialog *dialog,
              GError **error);

Lists all the selected files and subfolders in the current folder of dialog . The returned names are full absolute URIs.

This method belongs to the SFCD_DATA_RETRIEVAL state. It is equivalent to gtk_file_chooser_get_uris() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.3

sfcd_get_uris ()

GSList *
sfcd_get_uris (SandboxFileChooserDialog *dialog,
               GError **error);

Lists all the selected files and subfolders in the current folder of dialog . The returned names are full absolute paths. If files in the current folder cannot be represented as local filenames they will be ignored. (See sfcd_get_uris())

This method belongs to the SFCD_DATA_RETRIEVAL state. It is equivalent to gtk_file_chooser_get_filenames() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.4

sfcd_get_current_folder_uri ()

gchar *
sfcd_get_current_folder_uri (SandboxFileChooserDialog *dialog,
                             GError **error);

Gets the current folder of dialog as an URI. See sfcd_set_current_folder_uri().

Note that this is the folder that the dialog is currently displaying (e.g. "file:///home/username/Documents"), which is not the same as the currently-selected folder if the dialog is in GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER mode (e.g. "file:///home/username/Documents/selected-folder/". To get the currently-selected folder in that mode, use sfcd_get_uri() as the usual way to get the selection.

This method belongs to the SFCD_DATA_RETRIEVAL state. It is equivalent to gtk_file_chooser_get_current_folder_uri() in the GTK+ API. Do remember to check if error is set after running this method. If set, the return value is undefined.

Since 0.3

SFCD_IFACE

#define SFCD_IFACE SANDBOXUTILS_IFACE".SandboxFileChooserDialog"

SFCD_ERROR_DOMAIN

#define SFCD_ERROR_DOMAIN SFCD_IFACE".Error"

enum SfcdState

Describes the current state of a SandboxFileChooserDialog.

enum SfcdErrorCode

Describes an error related to the manipulation of a SandboxFileChooserDialog instance.

The “destroy” signal

void
user_function (SandboxFileChooserDialog *dialog,
               gpointer                  user_data)

Signals that all holders of a reference to the dialog should release the reference that they hold. May result in finalization of the widget if all references are released.

Flags: No Hooks

The “hide” signal

void
user_function (SandboxFileChooserDialog *dialog,
               gpointer                  user_data)

The ::hide signal is emitted when the dialog is hidden, for example when the user (or the window manager) minimizes your application's window.

Flags: Run First

The “response” signal

void
user_function (SandboxFileChooserDialog *dialog,
               gint                      response_id,
               gint                      return_state,
               gpointer                  user_data)

Emitted when an action widget is clicked, the dialog receives a delete event, or the application programmer calls gtk_dialog_response(). On a delete event, the response ID is GTK_RESPONSE_DELETE_EVENT. Otherwise, it depends on which action widget was clicked.

Note that the state of the dialog will depend on whether the response id translates as the user accepting an operation to take place or not. The GTK+ API defines GTK_RESPONSE_ACCEPT, GTK_RESPONSE_OK, GTK_RESPONSE_YES and GTK_RESPONSE_ACCEPT as meaning user acceptance. In Sandbox Utils, these response ids can only be used for buttons whose label is included into the acceptance-meaning labels.

Flags: Run Last

The “show” signal

void
user_function (SandboxFileChooserDialog *dialog,
               gpointer                  user_data)

The ::show signal is emitted when the dialog is shown, for example when the user opens your application's window after minimizing it.

Flags: Run First