Index

Package: File_Chooser

Description

package Gtk.File_Chooser is
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 </description>

Binding from C File version 2.8.17

Types

Gtk_File_Chooser 

type Gtk_File_Chooser is new Glib.Types.GType_Interface;

File_Chooser_Action 

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

File_Chooser_Confirmation 

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

File_Chooser_Error 

type File_Chooser_Error is
     (Error_Non_Existent,
      Error_Bad_Filename);
Identify the various errors that can occur while calling Gtk_File_Chooser functions

Constants & Global variables

Do_Overwrite_Confirmation_Property (Glib.Properties.Property_Boolean) 

Do_Overwrite_Confirmation_Property
                                  : constant Glib.Properties.Property_Boolean;
Action_Property : constant Glib.Properties.Property_Enum;

Extra_Widget_Property (Glib.Properties.Property_Object) 

Extra_Widget_Property          : constant Glib.Properties.Property_Object;

File_System_Backend_Property (Glib.Properties.Property_String) 

File_System_Backend_Property   : constant Glib.Properties.Property_String;

Filter_Property (Glib.Properties.Property_Object) 

Filter_Property                : constant Glib.Properties.Property_Object;

Local_Only_Property (Glib.Properties.Property_Boolean) 

Local_Only_Property            : constant Glib.Properties.Property_Boolean;

Preview_Widget_Property (Glib.Properties.Property_Object) 

Preview_Widget_Property        : constant Glib.Properties.Property_Object;

Preview_Widget_Active_Property (Glib.Properties.Property_Boolean) 

Preview_Widget_Active_Property : constant Glib.Properties.Property_Boolean;

Select_Multiple_Property (Glib.Properties.Property_Boolean) 

Select_Multiple_Property       : constant Glib.Properties.Property_Boolean;

Show_Hidden_Property (Glib.Properties.Property_Boolean) 

Show_Hidden_Property           : constant Glib.Properties.Property_Boolean;

Use_Preview_Label_Property (Glib.Properties.Property_Boolean) 

Use_Preview_Label_Property     : constant Glib.Properties.Property_Boolean;

Signal_Confirm_Overwrite (Glib.Signal_Name) 

Signal_Confirm_Overwrite      : constant Glib.Signal_Name :=
                                     "confirm-overwrite";

Signal_Current_Folder_Changed (Glib.Signal_Name) 

Signal_Current_Folder_Changed : constant Glib.Signal_Name :=
                                     "current-folder-changed";

Signal_File_Activated (Glib.Signal_Name) 

Signal_File_Activated         : constant Glib.Signal_Name :=
                                     "file-activated";

Signal_Selection_Changed (Glib.Signal_Name) 

Signal_Selection_Changed      : constant Glib.Signal_Name :=
                                     "selection-changed";

Signal_Update_Preview (Glib.Signal_Name) 

Signal_Update_Preview         : constant Glib.Signal_Name :=
                                     "update-preview";

Subprograms & Entries

Get_Type 

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

Set_Action 

procedure Set_Action 
(Chooser: Gtk_File_Chooser;
Action: File_Chooser_Action);

Get_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.

Set_Local_Only 

procedure Set_Local_Only 
(Chooser: Gtk_File_Chooser;
Local_Only: Boolean := True);

Get_Local_Only 

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,

Set_Select_Multiple 

procedure Set_Select_Multiple 
(Chooser: Gtk_File_Chooser;
Select_Multiple: Boolean);

Get_Select_Multiple 

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.

Set_Show_Hidden 

procedure Set_Show_Hidden 
(Chooser: Gtk_File_Chooser;
Show_Hidden: Boolean);

Get_Show_Hidden 

function Get_Show_Hidden 
(Chooser: Gtk_File_Chooser) return Boolean;
Sets whether hidden files and folders are displayed in the file selector

Set_Do_Overwrite_Confirmation 

procedure Set_Do_Overwrite_Confirmation 
(Chooser: Gtk_File_Chooser;
Do_Overwrite_Confirmation: Boolean);

Get_Do_Overwrite_Confirmation 

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.

Set_Current_Name 

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.

Get_Filename 

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.

Get_Filenames 

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.

Set_Filename 

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 &mdash; 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.

Select_Filename 

function Select_Filename 
(Chooser: Gtk_File_Chooser;
Filename: String) return Boolean;

Unselect_Filename 

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.

Select_All 

procedure Select_All 
(Chooser: Gtk_File_Chooser);

Unselect_All 

procedure Unselect_All 
(Chooser: Gtk_File_Chooser);
Selects all the files in the current folder of a file chooser.

Set_Current_Folder 

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.

Get_Current_Folder 

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.

Set_Uri 

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.

Get_Uri 

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.

Get_Uris 

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

Select_Uri 

function Select_Uri 
(Chooser: Gtk_File_Chooser;
Uri: String) return Boolean;

Unselect_Uri 

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.

Set_Current_Folder_Uri 

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.

Get_Current_Folder_Uri 

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.

Set_Preview_Widget 

procedure Set_Preview_Widget 
(Chooser: Gtk_File_Chooser;
Preview_Widget: access Gtk.Widget.Gtk_Widget_Record'Class);

Get_Preview_Widget 

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.

Set_Preview_Widget_Active 

procedure Set_Preview_Widget_Active 
(Chooser: Gtk_File_Chooser;
Active: Boolean);

Get_Preview_Widget_Active 

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.

Set_Use_Preview_Label 

procedure Set_Use_Preview_Label 
(Chooser: Gtk_File_Chooser;
Use_Label: Boolean);

Get_Use_Preview_Label 

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.

Get_Preview_Filename 

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.

Get_Preview_Uri 

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.

Set_Extra_Widget 

procedure Set_Extra_Widget 
(Chooser: Gtk_File_Chooser;
Extra_Widget: access Gtk.Widget.Gtk_Widget_Record'Class);

Get_Extra_Widget 

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

Add_Filter 

procedure Add_Filter 
(Chooser: Gtk_File_Chooser;
Filter: access Gtk.File_Filter.Gtk_File_Filter_Record'Class);

Remove_Filter 

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.

Set_Filter 

procedure Set_Filter 
(Chooser: Gtk_File_Chooser;
Filter: access Gtk.File_Filter.Gtk_File_Filter_Record'Class);

Get_Filter 

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.

List_Filters 

function List_Filters 
(Chooser: Gtk_File_Chooser) return Glib.Object.Object_List.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 Glib.Object.Object_List.Free.

Add_Shortcut_Folder 

function Add_Shortcut_Folder 
(Chooser: Gtk_File_Chooser;
Folder: String) return Glib.Error.GError;

Remove_Shortcut_Folder 

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.

List_Shortcut_Folders 

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.

Add_Shortcut_Folder_Uri 

function Add_Shortcut_Folder_Uri 
(Chooser: Gtk_File_Chooser;
Uri: String) return Glib.Error.GError;

Remove_Shortcut_Folder_Uri 

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.

List_Shortcut_Folder_Uris 

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.