Toc Gallery Index Tree Gtk.File_Chooser

Implemented by

Description

This package provides an interface implemented by Gtk.File_Chooser_Widget and Gtk.File_Chooser_Button, and by your own file selection widgets if you wish to expose a standard interface.

Gtk_File_Chooser allows for shortcuts to various places in the filesystem. In the default implementation these are displayed in the left pane. It may be a bit confusing at first that these shortcuts come from various sources and in various flavours, so lets explain the terminology here: - Bookmarks are created by the user, by dragging folders from the right pane to the left pane, or by using the "Add". Bookmarks can be renamed and deleted by the user. - Shortcuts can be provided by the application or by the underlying filesystem abstraction (e.g. both the gnome-vfs and the Windows filesystems provide "Desktop" shortcuts). Shortcuts cannot be modified by the user. - Volumes are provided by the underlying filesystem abstraction. They are the "roots" of the filesystem.

File Names and Encodings

When the user is finished selecting files in a Gtk_File_Chooser, your program can get the selected names either as filenames or as URIs. For URIs, the normal escaping rules are applied if the URI contains non-ASCII characters. However, filenames are always returned in the character set specified by the G_FILENAME_ENCODING environment variable. Please see the Glib documentation for more details about this variable.

Important: This means that while you can pass the result of Get_Filename to low-level file system primitives , you will need to convert it to UTF-8 before using it in a Gtk_Label for instance. Conversion is done through Glib.Convert.Filename_To_UTF8.

You can add a custom preview widget to a file chooser and then get notification about when the preview needs to be updated. To install a preview widget, use gtk_file_chooser_set_preview_widget(). Then, connect to the GtkFileChooser::update-preview signal to get notified when you need to update the contents of the preview.

Preview widgets

You can add a custom preview widget to a file chooser and then get notification about when the preview needs to be updated. To install a preview widget, use Set_Preview_Widget. Then, connect to the GtkFileChooser::update-preview signal to get notified when you need to update the contents of the preview.

Your callback should use Get_Preview_Filename to see what needs previewing. Once you have generated the preview for the corresponding file, you must call Set_Preview_Widget_Active with a boolean flag that indicates whether your callback could successfully generate a preview.

Adding Extra Widgets You can add extra widgets to a file chooser to provide options that are not present in the default design. For example, you can add a toggle button to give the user the option to open a file in read-only mode. You can use Set_Extra_Widget to insert additional widgets in a file chooser.

If you want to set more than one extra widget in the file chooser, you can a container such as a GtkVBox or a GtkTable and include your widgets in it. Then, set the container as the whole extra widget.

Key bindings

The following default key bindings are provided, but you can use a gtkrc file to override them if you need (see gtk-rc.ads). Signal name | Key binding location-popup | Control-L (empty path) | / (path of "/") | ~ (home directory) up-folder | Alt-Up or backspace down-folder | Alt-Down home-folder | Alt-Home desktop-folder | Alt-D quick-bookmark | Alt-1 through Alt-0

Types

  • type File_Chooser_Action is (Action_Open, Action_Save, Action_Select_Folder, Action_Create_Folder);
    Describes whether a Gtk_File_Chooser is being used to open existing files or to save to a possibly new file. Action_Open: Will only let the user select existing file Action_Save: Select existing file or enter new filename Action_Select_Folder: Only pick an existing folder Action_Create_Folder: Select existing folder or enter new name
  • type File_Chooser_Confirmation is (Confirmation_Confirm, Confirmation_Accept_Filename, Confirmation_Select_Again);
    Used as a return value of handlers for the confirm-overwrite signal of a Gtk_File_Chooser. This value determines whether the file chooser will present the stock confirmation dialog, accept the user's choice of a filename, or let the user choose another filename. Confirmation_Confirm: Ask confirmation about overwriting existing file Confirmation_Accept_Filename: Accept the user's choice Confirmation_Select_Again: Let the user select another file
  • type File_Chooser_Error is (Error_Non_Existent, Error_Bad_Filename);
    Identify the various errors that can occur while calling Gtk_File_Chooser functions
  • type Gtk_File_Chooser is new Glib.Types.GType_Interface;

Subprograms

  • function Get_Type return Gtk.Gtk_Type;
    Return the internal value associated with a Gtk_File_Chooser
  • Configuration

  • procedure Set_Action (Chooser : Gtk_File_Chooser; Action : File_Chooser_Action);
    function Get_Action (Chooser : Gtk_File_Chooser) return File_Chooser_Action;
    Sets the type of operation that the chooser is performing; the user interface is adapted to suit the selected action. For example, an option to create a new folder might be shown if the action is Action_Save, but not if the action is Action_Open.
  • procedure Set_Local_Only (Chooser : Gtk_File_Chooser; Local_Only : Boolean := True);
    function Get_Local_Only (Chooser : Gtk_File_Chooser) return Boolean;
    Sets whether only local files can be selected in the file selector. If Local_Only is True (the default), then the selected file are files are guaranteed to be accessible through the operating systems native file file system and therefore the application only needs to worry about the filename functions in Gtk_File_Chooser, like Get_Filename, rather than the URI functions like Get_Uri,
  • procedure Set_Select_Multiple (Chooser : Gtk_File_Chooser; Select_Multiple : Boolean);
    function Get_Select_Multiple (Chooser : Gtk_File_Chooser) return Boolean;
    Sets whether multiple files can be selected in the file selector. This is only relevant if the action is set to be Action_Open or Action_Save. It cannot be set with either of the folder actions.
  • procedure Set_Show_Hidden (Chooser : Gtk_File_Chooser; Show_Hidden : Boolean);
    function Get_Show_Hidden (Chooser : Gtk_File_Chooser) return Boolean;
    Sets whether hidden files and folders are displayed in the file selector
  • procedure Set_Do_Overwrite_Confirmation (Chooser : Gtk_File_Chooser; Do_Overwrite_Confirmation : Boolean);
    function Get_Do_Overwrite_Confirmation (Chooser : Gtk_File_Chooser) return Boolean;
    Sets whether a file chooser in Action_Save mode will present a confirmation dialog if the user types a file name that already exists. This is False by default. Regardless of this setting, Chooser will emit the "confirm-overwrite" signal when appropriate. If all you need is the stock confirmation dialog, set this property to True You can override the way confirmation is done by actually handling the "confirm-overwrite" signal; please refer to its documentation for the details.
  • procedure Set_Current_Name (Chooser : Gtk_File_Chooser; Name : UTF8_String);
    Sets the current name in the file selector, 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. If you want to preselect a particular existing file, you should use Set_Filename or Set_Uri instead.
  • Filename manipulation

  • function Get_Filename (Chooser : Gtk_File_Chooser) return String;
    Gets the filename for the currently selected file in the file selector. If multiple files are selected, one of the filenames will be returned at random. If the file chooser is in folder mode, this function returns the selected folder. Return value: The currently selected filename, or "" if no file is selected, or the selected file can't be represented with a local filename.
  • function Get_Filenames (Chooser : Gtk_File_Chooser) return Gtk.Enums.String_SList.GSlist;
    Lists all the selected files and subfolders in the current folder of Chooser. The returned names are full absolute paths. If files in the current folder cannot be represented as local filenames they will be ignored. (See Get_Uris). The returned value must be freed by the caller, through Gtk.Enums.Free_String_List.
  • function Set_Filename (Chooser : Gtk_File_Chooser; Filename : String) return Boolean;
    Sets Filename as the current filename for the file chooser, by changing to the file's parent folder and actually selecting the file in list. If the Chooser is in Action_Save mode, the file's base name will also appear in the dialog's file name entry. If the file name isn't in the current folder of Chooser, then the current folder of Chooser will be changed to the folder containing Filename. This is equivalent to a sequence of Unselect_All followed by Select_Filename. Note that the file must exist, or nothing will be done except for the directory change. If you are implementing a "File/Save As..." dialog, you should use this function if you already have a file name to which the user may save; for example, when the user opens an existing file and then does "File/Save As..." on it. 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 Set_Current_Name.

    Returns True if both the folder could be changed and the file was selected successfully.

  • function Select_Filename (Chooser : Gtk_File_Chooser; Filename : String) return Boolean;
    procedure Unselect_Filename (Chooser : Gtk_File_Chooser; Filename : String);
    Selects a filename. If the file name isn't in the current folder of Chooser, then the current folder of Chooser will be changed to the folder containing Filename. Returns True if both the folder could be changed and the file was selected successfully.
  • procedure Select_All (Chooser : Gtk_File_Chooser);
    procedure Unselect_All (Chooser : Gtk_File_Chooser);
    Selects all the files in the current folder of a file chooser.
  • function Set_Current_Folder (Chooser : Gtk_File_Chooser; Filename : String) return Boolean;
    Sets the current folder for Chooser 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. Filename is an absolute file name. Returns True if the folder could be changed successfully.
  • function Get_Current_Folder (Chooser : Gtk_File_Chooser) return String;
    Gets the current folder of Chooser as a local filename. Returns "" if the file chooser was unable to load the last folder that was requested from it, for instance with a call to Set_Current_Folder with an invalid directory. Also returns "" if the selected path cannot be represented as a local filename.
  • URI manipulation

  • function Set_Uri (Chooser : Gtk_File_Chooser; Uri : String) return Boolean;
    Sets the file referred to by Uri as the current file for the file chooser, by changing to the URI's parent folder and actually selecting the URI in the list. If the Chooser is Action_Save mode, the URI's base name will also appear in the dialog's file name entry. If the URI isn't in the current folder of Chooser, then the current folder of Chooser will be changed to the folder containing Uri. This is equivalent to a sequence of Unselect_All followed by Select_Uri. Note that the URI must exist, or nothing will be done except for the directory change. See also Set_Filename Return True if both the folder could be changed and the URI was selected successfully.
  • function Get_Uri (Chooser : Gtk_File_Chooser) return String;
    Gets the URI for the currently selected file in the file selector. If multiple files are selected, one of the filenames will be returned at random. If the file chooser is in folder mode, this function returns the selected folder.
  • function Get_Uris (Chooser : Gtk_File_Chooser) return Gtk.Enums.String_SList.GSlist;
    Lists all the selected files and subfolders in the current folder of Chooser. The returned names are full absolute URIs. The returned value must be freed by the caller
  • function Select_Uri (Chooser : Gtk_File_Chooser; Uri : String) return Boolean;
    procedure Unselect_Uri (Chooser : Gtk_File_Chooser; Uri : String);
    Selects the file by Uri. If the URI doesn't refer to a file in the current folder of Chooser, then the current folder of Chooser will be changed to the folder containing Uri. Return True if both the folder could be changed and the URI was selected successfully.
  • function Set_Current_Folder_Uri (Chooser : Gtk_File_Chooser; Uri : String) return Boolean;
    Sets the current folder for Chooser from an URI. The user will be shown the full contents of the current folder, plus user interface elements for navigating to other folders. Return True if the folder could be changed successfully.
  • function Get_Current_Folder_Uri (Chooser : Gtk_File_Chooser) return String;
    Gets the current folder of Chooser as an URI, or "" if the chooser was unable to load the last folder set by Set_Current_Folder_Uri.
  • Preview widget

  • procedure Set_Preview_Widget (Chooser : Gtk_File_Chooser; Preview_Widget : access Gtk.Widget.Gtk_Widget_Record'Class);
    function Get_Preview_Widget (Chooser : Gtk_File_Chooser) return Gtk.Widget.Gtk_Widget;
    Sets an application-supplied widget to use to display a custom preview of the currently selected file. To implement a preview, after setting the preview widget, you connect to the "update-preview" signal, and call Get_Preview_Filename() or Get_Preview_Uri on each change. If you can display a preview of the new file, update your widget and set the preview active using Set_Preview_Widget_Active. Otherwise, set the preview inactive. When there is no application-supplied preview widget, or the application-supplied preview widget is not active, the file chooser may display an internally generated preview of the current file or it may display no preview at all.
  • procedure Set_Preview_Widget_Active (Chooser : Gtk_File_Chooser; Active : Boolean);
    function Get_Preview_Widget_Active (Chooser : Gtk_File_Chooser) return Boolean;
    Sets whether the preview widget set by Set_Preview_Widget should be shown for the current filename. When Active is set to false, the file chooser may display an internally generated preview of the current file or it may display no preview at all.
  • procedure Set_Use_Preview_Label (Chooser : Gtk_File_Chooser; Use_Label : Boolean);
    function Get_Use_Preview_Label (Chooser : Gtk_File_Chooser) return Boolean;
    Sets whether the file chooser should display a stock label with the name of the file that is being previewed; the default is True. Applications that want to draw the whole preview area themselves should set this to False and display the name themselves in their preview widget.
  • function Get_Preview_Filename (Chooser : Gtk_File_Chooser) return String;
    Gets the filename that should be previewed in a custom preview widget. See Set_Preview_Widget. Return "" if no file is selected or it can't be represented as a local filename.
  • function Get_Preview_Uri (Chooser : Gtk_File_Chooser) return String;
    Gets the URI that should be previewed in a custom preview widget. See Set_Preview_Widget. Return "" if no file is selected.
  • Extra widget

  • procedure Set_Extra_Widget (Chooser : Gtk_File_Chooser; Extra_Widget : access Gtk.Widget.Gtk_Widget_Record'Class);
    function Get_Extra_Widget (Chooser : Gtk_File_Chooser) return Gtk.Widget.Gtk_Widget;
    Sets an application-supplied widget to provide extra options to the user
  • Filters

  • procedure Add_Filter (Chooser : Gtk_File_Chooser; Filter : access Gtk.File_Filter.Gtk_File_Filter_Record'Class);
    procedure Remove_Filter (Chooser : Gtk_File_Chooser; Filter : access Gtk.File_Filter.Gtk_File_Filter_Record'Class);
    Adds or Removes Filter to the list of filters that the user can select between. When a filter is selected, only files that are passed by that filter are displayed. Note that the Chooser takes ownership of the filter, so you have to ref and sink it if you want to keep a reference.
  • procedure Set_Filter (Chooser : Gtk_File_Chooser; Filter : access Gtk.File_Filter.Gtk_File_Filter_Record'Class);
    function Get_Filter (Chooser : Gtk_File_Chooser) return Gtk.File_Filter.Gtk_File_Filter;
    Sets the current filter; only the files that pass the filter will be displayed. If the user-selectable list of filters is non-empty, then the filter should be one of the filters in that list. Setting the current filter when the list of filters is empty is useful if you want to restrict the displayed set of files without letting the user change it.
  • function List_Filters (Chooser : Gtk_File_Chooser) return Gtk.Object.Object_SList.GSlist;
    Lists the current set of user-selectable filters. The list contains Gtk_File_Filter instances. Do not free the contents of list, still owned by gtk+, but you must free the list itself with Gtk.Object.Object_SList.Free.
  • Shorcut folders

  • function Add_Shortcut_Folder (Chooser : Gtk_File_Chooser; Folder : String) return Glib.Error.GError;
    function Remove_Shortcut_Folder (Chooser : Gtk_File_Chooser; Folder : String) return Glib.Error.GError;
    Adds a folder to be displayed with the shortcut folders in a file chooser. 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. Return null if the folder could be added successfully, or the code of the error otherwise.
  • function List_Shortcut_Folders (Chooser : Gtk_File_Chooser) return Gtk.Enums.String_SList.GSlist;
    Queries the list of shortcut folders in the file chooser, as set by Add_Shortcut_Folder. The returned value must be freed by the user.
  • function Add_Shortcut_Folder_Uri (Chooser : Gtk_File_Chooser; Uri : String) return Glib.Error.GError;
    function Remove_Shortcut_Folder_Uri (Chooser : Gtk_File_Chooser; Uri : String) return Glib.Error.GError;
    Adds a folder URI to be displayed with the shortcut folders in a file chooser. 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. Return null if the folder could be added successfully, or the code of the error otherwise.
  • function List_Shortcut_Folder_Uris (Chooser : Gtk_File_Chooser) return Gtk.Enums.String_SList.GSlist;
    Queries the list of shortcut folders in the file chooser, as set by Add_Shortcut_Folder_Uri. The returned value must be freed by the user.

Signals

Properties

Alphabetical Index