User Tools

Site Tools


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 Selected Files in a FileChooser

The FileChooser control can be created:

Dim hFileChooser As FileChooser
hFileChooser = New FileChooser ( Parent As Container ) As "EventName" Properties

The FileChooser class has the following properties:

PropertyData typeDescription
BookmarksCollection[ ]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.
DirStringReturns the current directory or sets the directory
DirViewDirViewReturns the DirView control, which is used internally by the FileChooser.
ExtensionContainerReturns the internal container that can be used to insert extensions within the FileChooser control.
FileChooserFileChooserReturns the FileChooser control that is used internally by the FileChooser.
FilterStringReturns 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.
FilterIndexIntegerReturns the index or sets the index of the filter used by the FileChooser control. The index -1 is used to display all files.
MultiBooleanReturns the truth value or sets it if the user can only select one or more files.
RootStringReturns or sets the root directory. If this property is not set, the home directory automatically becomes the root directory.
SelectedPathStringReturns the path for the selected file.
SelectedPathsStringReturns the list of all paths of the selected files if the Multi property is True.
ValueVariantIf 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).
ShowBookmarkBooleanReturns or sets the truth value whether the bookmark field is visible or not.
ShowButtonBooleanReturns the true value or sets the true value whether the default buttons ('OK' and 'Cancel') are visible or not.
ShowDetailedBooleanReturns the true value or sets the true value whether the files are displayed in a detail view or with icons or not.
ShowFileBooleanReturns or sets the truth value whether the file TextBox is visible or not. It is visible by default.
ShowDirectoryBooleanReturns the truth value or sets the truth value whether directories are shown in the FileChooser or not.
ShowHiddenBooleanReturns the truth value or sets the truth value whether the hidden files or directories are shown or hidden.
ShowPreviewBooleanReturns the truth value or sets the truth value whether the thumbnails are displayed or not.

Table : Properties of the FileChooser class Methods

The FileChooser class has these selected methods:

Delete( )Deletes the control FileChooser.
Reload( )Reloads the contents of the view as if you had clicked the 'Refresh' button.

Table : Selected methods of the FileChooser class Events

The FileChooser class has these selected events:

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 : Selected events of the FileChooser class.


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 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 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 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 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 ③ 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. 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 (

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")
  cBookmark = New Collection
  cBookmark.Add(User.Home &/ "ZumPrivaten/Bilder", "Path")
  cBookmark.Add("Pictures", "Name")
  cBookmark.Add("icon:/small/image", "Icon")
  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 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:


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.




The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k6/k6.9/k6.9.5/start.txt · Last modified: 16.01.2022 (external edit)

Page Tools