## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

## Index

Package: File_Chooser

- Goto spec source

# 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

- Goto declaration in source

    type Gtk_File_Chooser is new Glib.Types.GType_Interface;

### File_Chooser_Action

- Goto declaration in source

    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

- Goto declaration in source

    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

- Goto declaration in source

    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

- Goto declaration in source

(Glib.Properties.Property_Boolean)

    Do_Overwrite_Confirmation_Property
                                      : constant Glib.Properties.Property_Boolean;

Action_Property : constant Glib.Properties.Property_Enum;

### Extra_Widget_Property

- Goto declaration in source

(Glib.Properties.Property_Object)

    Extra_Widget_Property          : constant Glib.Properties.Property_Object;

### File_System_Backend_Property

- Goto declaration in source

(Glib.Properties.Property_String)

    File_System_Backend_Property   : constant Glib.Properties.Property_String;

### Filter_Property

- Goto declaration in source

(Glib.Properties.Property_Object)

    Filter_Property                : constant Glib.Properties.Property_Object;

### Local_Only_Property

- Goto declaration in source

(Glib.Properties.Property_Boolean)

    Local_Only_Property            : constant Glib.Properties.Property_Boolean;

### Preview_Widget_Property

- Goto declaration in source

(Glib.Properties.Property_Object)

    Preview_Widget_Property        : constant Glib.Properties.Property_Object;

### Preview_Widget_Active_Property

- Goto declaration in source

(Glib.Properties.Property_Boolean)

    Preview_Widget_Active_Property : constant Glib.Properties.Property_Boolean;

### Select_Multiple_Property

- Goto declaration in source

(Glib.Properties.Property_Boolean)

    Select_Multiple_Property       : constant Glib.Properties.Property_Boolean;

### Show_Hidden_Property

- Goto declaration in source

(Glib.Properties.Property_Boolean)

    Show_Hidden_Property           : constant Glib.Properties.Property_Boolean;

### Use_Preview_Label_Property

- Goto declaration in source

(Glib.Properties.Property_Boolean)

    Use_Preview_Label_Property     : constant Glib.Properties.Property_Boolean;

### Signal_Confirm_Overwrite

- Goto declaration in source

(Glib.Signal_Name)

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

### Signal_Current_Folder_Changed

- Goto declaration in source

(Glib.Signal_Name)

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

### Signal_File_Activated

- Goto declaration in source

(Glib.Signal_Name)

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

### Signal_Selection_Changed

- Goto declaration in source

(Glib.Signal_Name)

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

### Signal_Update_Preview

- Goto declaration in source

(Glib.Signal_Name)

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

# Subprograms & Entries

### Get_Type

- Goto spec in source
- Goto body in source

    function Get_Type return Gtk.Gtk_Type;

Return the internal value associated with a Gtk_File_Chooser

### Set_Action

- Goto spec in source
- Goto body in source

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

### Get_Action

- Goto spec in source
- Goto body in source

    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

- Goto spec in source

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

### Get_Local_Only

- Goto spec in source

    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

- Goto spec in source

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

### Get_Select_Multiple

- Goto spec in source

    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

- Goto spec in source

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

### Get_Show_Hidden

- Goto spec in source

    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

- Goto spec in source

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

### Get_Do_Overwrite_Confirmation

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

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

### Unselect_Filename

- Goto spec in source

    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

- Goto spec in source
- Goto body in source

    procedure Select_All (Chooser: Gtk_File_Chooser);

### Unselect_All

- Goto spec in source
- Goto body in source

    procedure Unselect_All (Chooser: Gtk_File_Chooser);

Selects all the files in the current folder of a file chooser.

### Set_Current_Folder

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

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

### Unselect_Uri

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

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

### Get_Preview_Widget

- Goto spec in source

    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

- Goto spec in source

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

### Get_Preview_Widget_Active

- Goto spec in source

    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

- Goto spec in source

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

### Get_Use_Preview_Label

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

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

### Get_Extra_Widget

- Goto spec in source

    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

- Goto spec in source

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

### Remove_Filter

- Goto spec in source

    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

- Goto spec in source

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

### Get_Filter

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

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

### Remove_Shortcut_Folder

- Goto spec in source

    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

- Goto spec in source

    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

- Goto spec in source

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

### Remove_Shortcut_Folder_Uri

- Goto spec in source

    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

- Goto spec in source

    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.