Table of Contents
6.9.5 FileChooser
The FileChooser control (gb.form) allows the user to select a file or a list of files in the same directory.
Figure 6.9.5.1: Selected Files in a FileChooser
The FileChooser control can be created:
Dim hFileChooser As FileChooser hFileChooser = New FileChooser ( Parent As Container ) As "EventName"
6.9.5.1 Properties
The FileChooser class has the following properties:
| Property | Data type | Description |
|---|---|---|
| Bookmarks | Collection[ ] | Sets or returns the list of private bookmarks. Each bookmark collection must contain a key “Path” which points to the path of the bookmark. Optional keys are “Name” and “Icon”. Other key names are ignored. |
| Dir | String | Returns the current directory or sets the directory |
| DirView | DirView | Returns the DirView control, which is used internally by the FileChooser. |
| Extension | Container | Returns the internal container that can be used to insert extensions within the FileChooser control. |
| FileChooser | FileChooser | Returns the FileChooser control that is used internally by the FileChooser. |
| Filter | String | Returns the filters used by the control element or sets them to display only certain file types. The filters are displayed in a separate ComboBox. Automatically, the filter entry 'All Files (*)' is inserted. The filter property receives a string array with the following structure: The first filter. The first filter description. The second filter. The second filter description. And so on… . A filter string is a list of file patterns with placeholders separated by a semicolon. A filter description can be any string. The filter string is automatically appended to the filter description. |
| FilterIndex | Integer | Returns the index or sets the index of the filter used by the FileChooser control. The index -1 is used to display all files. |
| Multi | Boolean | Returns the truth value or sets it if the user can only select one or more files. |
| Root | String | Returns or sets the root directory. If this property is not set, the home directory automatically becomes the root directory. |
| SelectedPath | String | Returns the path for the selected file. |
| SelectedPaths | String | Returns the list of all paths of the selected files if the Multi property is True. |
| Value | Variant | If the Multi property is False, then this property is a synonym for the SelectedPath property (data type String). If the Multi property is True, then this property is synonymous with the SelectedPaths property (String array data type). |
| ShowBookmark | Boolean | Returns or sets the truth value whether the bookmark field is visible or not. |
| ShowButton | Boolean | Returns the true value or sets the true value whether the default buttons ('OK' and 'Cancel') are visible or not. |
| ShowDetailed | Boolean | Returns the true value or sets the true value whether the files are displayed in a detail view or with icons or not. |
| ShowFile | Boolean | Returns or sets the truth value whether the file TextBox is visible or not. It is visible by default. |
| ShowDirectory | Boolean | Returns the truth value or sets the truth value whether directories are shown in the FileChooser or not. |
| ShowHidden | Boolean | Returns the truth value or sets the truth value whether the hidden files or directories are shown or hidden. |
| ShowPreview | Boolean | Returns the truth value or sets the truth value whether the thumbnails are displayed or not. |
Table 6.9.5.1.1 : Properties of the FileChooser class
6.9.5.2 Methods
The FileChooser class has these selected methods:
| Method | Description |
|---|---|
| Delete( ) | Deletes the control FileChooser. |
| Reload( ) | Reloads the contents of the view as if you had clicked the 'Refresh' button. |
Table 6.9.5.2.1 : Selected methods of the FileChooser class
6.9.5.3 Events
The FileChooser class has these selected events:
| Event | Description |
|---|---|
| Activate( ) | This event is triggered when a user double-clicks on a file or when the 'OK' button is clicked. |
| Cancel( ) | This event is triggered when a user clicked the 'Cancel' button. The SelectedPath property and the SelectedPaths property are empty. |
Table 6.9.5.3.1 : Selected events of the FileChooser class.
Notes:
You can get project-wide access to the path to a selected file with FileChooser.Multi = False if you store the value of the FileChooser.SelectedPath property in a (public) variable sFilePath = FileChooser.SelectedPath, for example.
Figure 6.9.5.3.1: Display file path of the selected file in the FileChooser.
Alternatively, you can use the assignment sFilePath = FileChooser.Value, because the value of this property depends on the set mode and returns only a string for FileChooser.Multi = False.
You get access to the file paths for all files selected in FileChooser.Multi = True mode if you store the list of selected files - stored in the FileChooser.SelectedPaths property - in a (public) array variable such as aFilePaths = FileChooser.SelectedPaths.
Alternatively, you can use the assignment aFilePaths = FileChooser.Value, because the value of this property depends on the mode set, but for FileChooser.Multi = True it returns a string array:
Figure 6.9.5.3.2: List of selected files in a FileChooser
You can use the FileChooser.Filter property to set all the file filters needed in the project and use the FileChooser.FilterIndex property to switch very flexibly to individual filter groups at runtime:
FileChooser1.Filter = ["*.png;*.jp*;*.gif", "Picture files", "*.txt;*.xml;*.conf", "Text files"] FileChooser1.FilterIndex = 0 ' Display images with the extensions png, jp* and gif only ' FileChooser1.FilterIndex = -1 ' Display all files
6.9.5.4 Digression Bookmarks
The Filechooser control element has its own bookmark system. Set the ShowBookmark property to True to display it. The bookmark menu is now visible and a drop-down menu of bookmarks is displayed when you click the Bookmark button.
The bookmark menu has its own context menu:
Figure 6.9.5.4.1: Bookmark menu in FileChooser
The drop-down menu contains 3 types of bookmarks:
(type 1) Standard bookmarks ①
(Type 2) Private bookmarks ②
(Type 3) User bookmarks ③
6.9.5.5 Default bookmarks
The default bookmarks point to Home and System. Note: You will only see the Desktop menu item additionally if the gb.desktop component is loaded.
6.9.5.6 Private Bookmarks
Private bookmarks are accessed through the Bookmarks property. Bookmarks is an array of collections by data type. Each bookmark collection must contain a key “Path” which points to the path of the bookmark. Optional keys are “Name” and “Icon”. All other key names are ignored. Important: The specified path must exist!
This bookmark type 2 is application-specific, is not stored permanently, but created at runtime. The relevant source code in the form open event is based on hints from Tony Morehen (tmorehen@ajm-software.com):
Public Sub Form_Open() Dim cPrivateBookmarks As Collection[] Dim cBookmark As Collection FMain.Resizable = True ... cPrivateBookmarks = New Collection[] cBookmark = New Collection ' Syntax: cBookmark.Add(Value,Key) {Path, [Name, Icon]} cBookmark.Add(User.Home &/ "BildTon/Fractale", "Path") cBookmark.Add("Fractals", "Name") cBookmark.Add("icon:/small/plugin", "Icon") cPrivateBookmarks.Add(cBookmark) cBookmark = New Collection cBookmark.Add(User.Home &/ "ZumPrivaten/Bilder", "Path") cBookmark.Add("Pictures", "Name") cBookmark.Add("icon:/small/image", "Icon") cPrivateBookmarks.Add(cBookmark) Filechooser1.Bookmarks = cPrivateBookmarks ' The alternative uses the inline syntax: ' Filechooser1.Bookmarks = [["Path": User.Home &/ "BildTon/Fractale", "Name": "Fractals", "Icon": "icon:/small/plugin"], ' ["Path": User.Home &/ "ZumPrivaten/Bilder", "Name": "Pictures", "Icon": "icon:/small/image"]] FileChooser1.ShowBookmark = True ... End
6.9.5.7 User bookmarks
It is necessary for the gb.settings component to be loaded in order to display user bookmarks. Create and edit user bookmarks via the menu items “Create bookmarks for current directory” and “Edit bookmarks”. The bookmarks are stored in the file path $HOME/.config/gambas3/gb.form.conf. This is the content of the gb.form.conf file created in the presented project:
[Bookmarks] Count=2 Bookmark1=["/home/hans/AirCard_785S","AirCard_785S"] Bookmark2=["/home/hans/V24T","V24T"]
Attention: The list of bookmarks is user-specific. It is used by all applications that use Gambas controls that have a bookmark menu - such as the DirChooser control.