SandboxFileChooserDialog

SandboxFileChooserDialog — A dialog for choosing files meant to be manipulated over IPC by a sandboxed application

Stability Level

Unstable, unless otherwise indicated

Functions

GType sfcd_get_type ()
gboolean sfcd_is_accept_label ()
SandboxFileChooserDialog * sfcd_new ()
void sfcd_destroy ()
SfcdState sfcd_get_state ()
const gchar * sfcd_get_state_printable ()
const gchar * sfcd_get_dialog_title ()
gboolean sfcd_is_running ()
const gchar * sfcd_get_id ()
void sfcd_run ()
void sfcd_present ()
void sfcd_cancel_run ()
void sfcd_set_destroy_with_parent ()
gboolean sfcd_get_destroy_with_parent ()
void sfcd_set_extra_widget ()
GtkWidget * sfcd_get_extra_widget ()
void sfcd_select_filename ()
void sfcd_unselect_filename ()
void sfcd_select_all ()
void sfcd_unselect_all ()
void sfcd_select_uri ()
void sfcd_unselect_uri ()
void sfcd_set_action ()
GtkFileChooserAction sfcd_get_action ()
void sfcd_set_local_only ()
gboolean sfcd_get_local_only ()
void sfcd_set_select_multiple ()
gboolean sfcd_get_select_multiple ()
void sfcd_set_show_hidden ()
gboolean sfcd_get_show_hidden ()
void sfcd_set_do_overwrite_confirmation ()
gboolean sfcd_get_do_overwrite_confirmation ()
void sfcd_set_create_folders ()
gboolean sfcd_get_create_folders ()
void sfcd_set_current_name ()
void sfcd_set_filename ()
void sfcd_set_current_folder ()
void sfcd_set_uri ()
void sfcd_set_current_folder_uri ()
gboolean sfcd_add_shortcut_folder ()
gboolean sfcd_remove_shortcut_folder ()
GSList * sfcd_list_shortcut_folders ()
gboolean sfcd_add_shortcut_folder_uri ()
gboolean sfcd_remove_shortcut_folder_uri ()
GSList * sfcd_list_shortcut_folder_uris ()
gchar * sfcd_get_current_name ()
gchar * sfcd_get_filename ()
GSList * sfcd_get_filenames ()
gchar * sfcd_get_current_folder ()
gchar * sfcd_get_uri ()
GSList * sfcd_get_uris ()
gchar * sfcd_get_current_folder_uri ()

Signals

void destroy No Hooks
void hide Run First
void response Run Last
void show Run First

Types and Values

Object Hierarchy

    GObject
    ╰── SandboxFileChooserDialog
        ├── LocalFileChooserDialog
        ╰── RemoteFileChooserDialog

Includes

#include <sandboxutils.h>

Description

SandboxFileChooserDialog is an API for a file chooser dialog, based on the GtkFileChooserDialog class and GtkFileChooser interface. This dialog can be used to provide an interface to open files or directories, or to save files.

SandboxFileChooserDialog is designed to be wrapped and exposed over an IPC mechanism. The process handling the class on behalf of the sandboxed app is in charge of managing access control to make sure the app can read and write files that were selected in the dialog. This is best done from within the IPC wrapper rather than by modifying this class.

This class is thread-safe so long as you make sure to return from all of an instance's methods before destroying it.

It differs with other dialogs in that it has a SfcdState among:

SFCD_CONFIGURATION: initial state, in which the dialog's behavior, current file and directory, etc. can be modified to match your application's needs SFCD_RUNNING: switched to by calling sfcd_run(), in which the dialog cannot be modified or queried and can only be cancelled (see sfcd_cancel_run()), presented (sfcd_present()) or destroyed (sfcd_destroy()) SFCD_DATA_RETRIEVAL: retrieval: switched to automatically after a successful run, in which the dialog cannot be modified but the file(s) currently selected can be queried as in the original GtkFileChooserDialog

States allow preventing attacks where an app would modify the dialog after the user made a selection and before they clicked on the dialog's appropriate button. If the dialog is modified or reused, it switches back to a previous state in a rather conservative way, both to provide consistency on the restrictions it imposes and to allow some level of object reuse.

The SFCD_CONFIGURATION state is how a dialog starts. In this mode, you can call most setter methods to prepare the dialog before displaying it to the user. You cannot yet retrieve any chosen file since the user hasn't seen the dialog! You cannot call any configuration method while the dialog is running (to prevent you from forcing the user into accepting a certain file), and calling configuration methods after the dialog has run will cause it to return to this state, so you can reconfigure and rerun the dialog easily. You should use sfcd_run() to switch to the next state.

The SFCD_RUNNING state occurs from the moment you call sfcd_run() until the moment the “response” signal is emitted. In this mode, you cannot modify or query the dialog at all. All you can do is cancel or destroy it, and present it to the user if need be. The dialog will either switch back to the SFCD_CONFIGURATION mode if it was cancelled or destroyed (by you or by the user) or will transition to the SFCD_DATA_RETRIEVAL mode if the user successfuly selected a file/folder to open or filename to save to.

The SFCD_DATA_RETRIEVAL state is for when the dialog has been successfully run. If the action of the dialog was GTK_FILE_CHOOSER_ACTION_OPEN or GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER , retrieving the filenames selected by the user will grant your application access to these files (see sfcd_get_uri()). In the case of GTK_FILE_CHOOSER_ACTION_SAVE or GTK_FILE_CHOOSER_CREATE_FOLDER , you will be granted write access to the current name of the dialog upon retrieving it (see sfcd_get_current_name()).

As of now, it has not yet been decided whether your application will receive file paths or file descriptors or both in the SFCD_DATA_RETRIEVAL state.

Functions

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

Parameters

label

a prospective SandboxFileChooserDialog button label

 

Returns

True if the sanity check succeeds, False if the dialog or error were not as expected

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.

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 (see GtkFileChooserAction)

 

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 SandboxFileChooserDialog

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.

Parameters

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.

Parameters

Returns

the state of the dialog

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.

Parameters

Returns

the state of the dialog in the form of a G_TYPE_STRING

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.

Parameters

Returns

the title of the dialog embedded within the dialog

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.

Parameters

Returns

whether the dialog is running

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.

Parameters

Returns

the identifier of dialog . Do not free.

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:

Example 1. Typical GtkFileChooserDialog usage

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);

With Sandbox Utils, you would instead do the following:

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

setting

whether to destroy window with its transient parent

 

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.

Parameters

Returns

TRUE if the window will be destroyed with its transient parent.

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.

Parameters

dialog

a SandboxFileChooserDialog

 

widget

the extra GtkWidget controlled by your application

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

the extra application-provided widget attached to dialog

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()

Parameters

dialog

a SandboxFileChooserDialog

 

filename

the filename to select.

[type filename]

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

filename

the filename to unselect.

[type filename]

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

uri

the URI to select

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

uri

the URI to unselect

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

action

the GtkFileChooserAction that the dialog is performing

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

the action that the dialog is performing

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.

Parameters

dialog

a SandboxFileChooserDialog

 

local_only

TRUE if only local files can be selected

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

TRUE if only local files can be selected

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.

Parameters

dialog

a SandboxFileChooserDialog

 

select_multiple

TRUE if multiple files can be selected

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

TRUE if multiple files can be selected

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.

Parameters

dialog

a SandboxFileChooserDialog

 

show_hidden

TRUE if hidden files and folders should be displayed

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

TRUE if hidden files and folders are displayed

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.

Parameters

dialog

a SandboxFileChooserDialog

 

do_overwrite_confirmation

TRUE to confirm overwriting in save mode

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

TRUE if the dialog will present a confirmation dialog; FALSE otherwise

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.

Parameters

dialog

a SandboxFileChooserDialog

 

create_folders

TRUE if the Create Folder button should be displayed

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

TRUE if the Create Folder button should be displayed

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.

Parameters

dialog

a SandboxFileChooserDialog

 

name

the filename to use, as a UTF-8 string.

[type filename]

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

filename

the filename to set as current.

[type filename]

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

filename

the full path of the new current folder.

[type filename]

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

uri

the URI to set as current

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

uri

the URI for the new current folder

 

error

a placeholder for a GError

 

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.

Parameters

dialog

a SandboxFileChooserDialog

 

folder

filename of the folder to add.

[type filename]

error

a placeholder for a GError

 

Returns

TRUE if the folder could be added successfully, FALSE otherwise. In the latter case, the error will be set as appropriate.

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.

Parameters

dialog

a SandboxFileChooserDialog

 

folder

filename of the folder to remove.

[type filename]

error

a placeholder for a GError

 

Returns

TRUE if the operation succeeds, FALSE otherwise. In the latter case, the error will be set as appropriate.

See also: sfcd_add_shortcut_folder()

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

A list of folder filenames, or NULL if there are no shortcut folders. Free the returned list with g_slist_free(), and the filenames with g_free().

See also: sfcd_add_shortcut_folder().

[element-type filename][transfer full]

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.

Parameters

dialog

a SandboxFileChooserDialog

 

uri

URI of the folder to add

 

error

a placeholder for a GError

 

Returns

TRUE if the folder could be added successfully, FALSE otherwise. In the latter case, the error will be set as appropriate.

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.

Parameters

dialog

a SandboxFileChooserDialog

 

uri

URI of the folder to remove

 

error

a placeholder for a GError

 

Returns

TRUE if the operation succeeds, FALSE otherwise. In the latter case, the error will be set as appropriate.

See also: sfcd_add_shortcut_folder_uri()

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

A list of folder URIs, or NULL if there are no shortcut folders. Free the returned list with g_slist_free(), and the URIs with g_free().

See also: sfcd_add_shortcut_folder_uri().

[element-type utf8][transfer full]

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.

This method should not be used as it was in GTK+ to pick the typed name and complete or modify their extension. App can no longer choose arbitrary names in the context of sandboxing. A specific API for automatic filename completion will be provided in the future

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

The raw text from the dialog's "Name" entry. Free this with g_free(). Note that this string is not a full pathname or URI; it is whatever the contents of the entry are. Note also that this string is in UTF-8 encoding, which is not necessarily the system's encoding for filenames.

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

The currently selected filename, or NULL if no file is selected, or the selected file can't be represented with a local filename. Free with g_free().

[type filename]

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

the full path of the current folder, or NULL if the current path cannot be represented as a local filename. Free with g_free(). This function will also return NULL if the dialog was unable to load the last folder that was requested from it; for example, as would be for calling sfcd_set_current_folder() on a nonexistent folder.

[type filename]

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

a GSList containing the URIs of all selected files and subfolders in the current folder. Free the returned list with g_slist_free(), and the filenames with g_free().

[element-type utf8][transfer full]

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

a GSList containing the filenames of all selected files and subfolders in the current folder. Free the returned list with g_slist_free(), and the filenames with g_free().

[element-type filename][transfer full]

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.

Parameters

dialog

a SandboxFileChooserDialog

 

error

a placeholder for a GError

 

Returns

the URI for the current folder. Free with g_free(). This function will also return NULL if the dialog was unable to load the last folder that was requested from it; for example, as would be for calling sfcd_set_current_folder_uri() on a nonexistent folder.

Since 0.3

Types and Values

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.

Members

SFCD_WRONG_STATE

Indicates the dialog was destroyed or a bug was detected.

 

SFCD_CONFIGURATION

Indicates the dialog can be modified and configured prior to being displayed.

 

SFCD_RUNNING

Indicates the dialog is being displayed and cannot be modified or queried.

 

SFCD_DATA_RETRIEVAL

Indicates the dialog successfully ran and the selection of the user can now be retrieved.

 

enum SfcdErrorCode

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

Members

SFCD_ERROR_CREATION

Occurs when a dialog could not be created.

 

SFCD_ERROR_LOOKUP

Occurs when a dialog could not be found in external storage. Not used within SandboxFileChooserDialog.

 

SFCD_ERROR_FORBIDDEN_CHANGE

Occurs when one attempts to modify a dialog when not allowed by its current state. See SfcdState.

 

SFCD_ERROR_FORBIDDEN_QUERY

Occurs when one attempts to obtain information from a dialog when not allowed by its current state. See SfcdState.

 

SFCD_ERROR_TOOLKIT_CALL_FAILED

Occurs if the SandboxFileChooserDialog code functionned properly but the toolkit itself returned an error when calling a method of the underlying GtkFileChooserDialog. from a dialog when not allowed by its current state. See SfcdState.

 

SFCD_ERROR_UNKNOWN

Occurs if the cause of an error cannot be determined. Usually you get this error when a sanity check failed, probably indicating a bug in SandboxUtils.

 

Signal Details

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.

Parameters

dialog

the dialog on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

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.

Parameters

dialog

the dialog on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

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.

Parameters

dialog

the dialog on which the signal is emitted

 

response_id

the response id obtained when the dialog finished running

 

return_state

the state of the dialog after running

 

user_data

user data set when the signal handler was connected.

 

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.

Parameters

dialog

the dialog on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First