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);
-
type File_Chooser_Confirmation is
(Confirmation_Confirm,
Confirmation_Accept_Filename,
Confirmation_Select_Again);
-
type File_Chooser_Error is
(Error_Non_Existent,
Error_Bad_Filename);
-
Subprograms
-
Configuration
-
procedure Set_Action
(Chooser : Gtk_File_Chooser; Action : File_Chooser_Action);
function Get_Action (Chooser : Gtk_File_Chooser) return File_Chooser_Action;
-
procedure Set_Local_Only
(Chooser : Gtk_File_Chooser; Local_Only : Boolean := True);
function Get_Local_Only (Chooser : Gtk_File_Chooser) return Boolean;
-
procedure Set_Select_Multiple
(Chooser : Gtk_File_Chooser; Select_Multiple : Boolean);
function Get_Select_Multiple (Chooser : Gtk_File_Chooser) return Boolean;
-
procedure Set_Show_Hidden
(Chooser : Gtk_File_Chooser; Show_Hidden : Boolean);
function Get_Show_Hidden (Chooser : Gtk_File_Chooser) return Boolean;
-
procedure Set_Do_Overwrite_Confirmation
(Chooser : Gtk_File_Chooser;
Do_Overwrite_Confirmation : Boolean);
function Get_Do_Overwrite_Confirmation
(Chooser : Gtk_File_Chooser) return Boolean;
-
procedure Set_Current_Name (Chooser : Gtk_File_Chooser; Name : UTF8_String);
Filename manipulation
-
function Get_Filename (Chooser : Gtk_File_Chooser) return String;
-
function Get_Filenames
(Chooser : Gtk_File_Chooser) return Gtk.Enums.String_SList.GSlist;
-
function Set_Filename
(Chooser : Gtk_File_Chooser; Filename : String) return Boolean;
-
function Select_Filename
(Chooser : Gtk_File_Chooser; Filename : String) return Boolean;
procedure Unselect_Filename
(Chooser : Gtk_File_Chooser; Filename : String);
-
procedure Select_All (Chooser : Gtk_File_Chooser);
procedure Unselect_All (Chooser : Gtk_File_Chooser);
-
function Set_Current_Folder
(Chooser : Gtk_File_Chooser; Filename : String) return Boolean;
-
function Get_Current_Folder (Chooser : Gtk_File_Chooser) return String;
URI manipulation
-
function Set_Uri
(Chooser : Gtk_File_Chooser; Uri : String) return Boolean;
-
function Get_Uri (Chooser : Gtk_File_Chooser) return String;
-
function Get_Uris
(Chooser : Gtk_File_Chooser) return Gtk.Enums.String_SList.GSlist;
-
function Select_Uri
(Chooser : Gtk_File_Chooser; Uri : String) return Boolean;
procedure Unselect_Uri (Chooser : Gtk_File_Chooser; Uri : String);
-
function Set_Current_Folder_Uri
(Chooser : Gtk_File_Chooser; Uri : String) return Boolean;
-
function Get_Current_Folder_Uri (Chooser : Gtk_File_Chooser) return String;
Preview widget
-
-
procedure Set_Preview_Widget_Active
(Chooser : Gtk_File_Chooser;
Active : Boolean);
function Get_Preview_Widget_Active
(Chooser : Gtk_File_Chooser) return Boolean;
-
procedure Set_Use_Preview_Label
(Chooser : Gtk_File_Chooser;
Use_Label : Boolean);
function Get_Use_Preview_Label (Chooser : Gtk_File_Chooser) return Boolean;
-
function Get_Preview_Filename (Chooser : Gtk_File_Chooser) return String;
-
function Get_Preview_Uri (Chooser : Gtk_File_Chooser) return String;
Extra widget
-
Filters
-
-
-
function List_Filters
(Chooser : Gtk_File_Chooser)
return Gtk.Object.Object_SList.GSlist;
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;
-
function List_Shortcut_Folders
(Chooser : Gtk_File_Chooser) return Gtk.Enums.String_SList.GSlist;
-
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;
-
function List_Shortcut_Folder_Uris
(Chooser : Gtk_File_Chooser) return Gtk.Enums.String_SList.GSlist;