Here is a pair of standalone choosers (one for
pictures and another for ordinary files) that you
can incorporate in your own programs. An
example program for calling the widgets is
provided, written in LiveCode.
However, your programs do not need to be
written in LiveCode in order to use the widgets.

This version of the widgets should run on
most Gnome 2·compatible versions of Linux.
However, regarding a few small details, special
preference has been given to Linux Mint.

The choosers can be used for file selection
("Open", or "Save As" functions with or without
a suggested file name), or for choosing
folders only.

Apart from the thumbnail preview picture
available in the Picture Chooser, these widgets
are identical in function.

In lines 9, 10, 11 and 12 of the INI parameters, the left, top, width and height no longer refer to the inner values favoured by LiveCode: they refer to the OUTER
coordinates and dimensions of the PHYSICAL window, so for example the "height" of the widget now includes the height of the title bar and the lower border.
I think this is more intuitive:

Finally, you will find, bundled with the Demo Pack, some folders and picture files with non English names which you can use to test the Unicode capabilities
of the widgets:

Some aspects of chooser widget usage might not have not been discussed adequately on this page, so for further information,
please consult the "readme" file that you will find accompanying the Demo Pack.

In the download pack you will find the Demo (file cDemo). Its purpose is to provide you with the means to employ the widgets in your own apps, in the simplest
way possible.

As it says in the red box, copy the functions and handlers from this Demo into your own application. Copy the widget standalones to your program folder.
You can then call the chooser widgets according to the examples demonstrated by the buttons at the bottom of the Demo. If you click on the word "code"
above a button, it will show you the coding within the button, e.g:

The example above shows you the coding required to call the simple "File Chooser" to choose one or more files.
It is explained as follows.

If you give the "prompt" variable some kind of content (i.e. it is not empty), the widget will display your message for a short time before it shows the directory
tree. Note that the message is automatically centralised. Here is the sequence:

After the messsage is shown, the HD treeview is faded in.
You can control how long the message and fade-in displays last (see below).
If these timings are not specified, the message is shown for 2 seconds and the transitional fade-in lasts for 1 second.

However, if you do not want to show a prompt at all, just make sure the prompt variable is empty.

The "parameter" variable determines what kind of widget you want to call and exactly how it should behave, i.e. whether it is to carry out the task of being a
simple file chooser, a folder chooser, or a "save as" widget. Be careful of a confusion in terminology here. Physically, you have 2 types of widget: a "file chooser"
and a "picture chooser". The only difference between the former and the latter is the fact that the latter (the "picture chooser") will show you a thumbnail preview
of any image files you are considering. It is important to clarify that BOTH widgets enable you to choose files or pictures (or save them), or choose a folder. Apart
from the preview thumbnail, they are identical in function.

1. If you want to choose a file or multiple files, then make the parameter variable EMPTY.

2. If you want to choose a folder only, then put "folder" or "folder/" into the parameter variable.
(The latter option simply puts a slash on the end of the folder path returned.)

Note that if you intend to call the simple file chooser to get the folder, it will appear without the right·hand pane for file selection.
However, if you intend to use the picture chooser to get the folder, it WILL show the right·hand pane for file selection. This is so that the operator can browse
folder contents with a thumbnail image preview. What will be returned, though, is the FOLDER name selected in the left·hand pane, NOT a file name that
might have been browsed in the right·hand pane.

3. If you put anything else into the parameter variable, it will be treated as a suggested file name for the purpose of "save as".
(Examples are "newfile.txt", "*.*", "*.png", "????", and so on.)

You will note that the suggested file name appears in a box at the bottom of the widget's file pane on the right hand side. If an illegal file name such as
"*.livecode" is suggested, the widget will refuse to close (unless cancelled) until the operator has typed or chosen a legal one.

Each line in the list of filters you specify needs to have the following format:

wildcard filter SINGLE SPACE description

e.g.

*.livecode Revolution LC stack

The path to the chosen file (or folder) is returned in the variable "choice".
For the purposes of the Demo only, this is displayed in the field at the bottom.

Here is an example of what might be returned in the choice variable if the operator chooses multiple files:

The items of the path are separated with slashes, and the file items are separated with pipe symbols.
Because it is a single unit, the choice variable can be conveniently moved around in your app.

However, you will undoubtedly require the path and multiple chosen files to be split at some point, so for your convenience the widget functions also return
two other variables: thePath and theFiles.

thePath is returned as a single line.
theFiles is returned as a list.

If you click on the button at the very bottom, it will show you the list of files retrieved in the theFiles variable:

After copying the functions and handlers from the Demo to your app, do this to call a chooser widget:

1. Declare the variables choice, thePath and theFiles globally.
2. Give values to the variables prompt, parameter and filters.
3. Call either the FileChooser function or the PictureChooser function.
4. Grab the resulting choice, thePath or theFiles variables that are returned.

This has been explained in detail above.

The sides of the widget can be dragged in any direction. When you do this, the division between the panes is adjusted proportionally.
To further adjust the division between the panes, use the left and right arrow keys on the keyboard.

Each time you click on this button, the
folder tree in the left-hand pane will
regress to the previous folder in the path
shown at the top in the title bar.

If you move the mouse just under the title bar in this position, you will be able to see the widget's current build number.

As you can see, the widgets are now "self·tailoring". This means that most of the values in the widget's INI file can be altered manually via the widget itself.
You can, of course, alter any of the lines in the INI file programmatically (see an example in the Demo), but most of the time it is not necessary. Just set up
the widget manually according to your taste, and it maintains its characteristics until you alter the INI file again. Please note that the changes you make to
the INI file will not take effect until the widget is started again.

Most of the 16 fields are self-explanatory, but there are some notes below on those which require some explanation.

Line 1: Startup folder path

By default, the widget returns to the previously-chosen folder when it is called again. To achieve this, the widget itself puts the currently-chosen path into
line 1 of its own INI file. That's why it is disabled to prevent manual alteration which would be very short-lasting.

However, if you wish to start up a widget from a different folder, this can be done programmatically by setting line 1 of the INI file to the new path before
calling the widget.

Line 2: Prompt file name

Line 2 shows the name of the prompt file used by the functions in the Demo.

If you wish to change the name of the prompt file, then it can be done programmatically, but you will either need to change this name in the standard
widget-calling functions offered in the Demo, or you will need to write your own functions to use your alternative prompt file name. In practical terms,
you will probably never need to alter the name of this file.

Line 3: Prompt display and visual effect timings

The values inserted here determine how long the prompt should be shown for (in seconds), and also how long the visual transition to the main widget
display should last. If you leave it empty, the default is 2,1 - i.e. the prompt is shown for 2 seconds and the transition takes 1 second.

Any two values separated by a comma can be inserted here: e.g. 3,2.

If you do not want a prompt to be shown at all, you can put 0,0 in here. However, if you are using the recommended widget-calling functions as
demonstrated in the Demo, you can simply set the prompt variable to empty.

Line 4: Indent size

This sets the horizontal distance between the coloured folder nodes in the hierarchical folder tree on display in the widget's left-hand pane.
The distance between a node and the next one down the hierarchy cannot be less than 3 spaces.

Line 5: Font name

The main thing to be careful about when setting a font for the widget to use is the fact that not all available fonts display Unicode characters correctly!
You are advised to check this carefully when setting a given font for distribution of the widgets.

Line 6: Font size

Make sure that you choose a size which is not too big for the fixed size of the widget's buttons etc.

Line 13: Output mode

Originally, the path and file chosen by the operator and emitted by the widget could be put onto, and retrieved from, the clipboard.
This never worked in Linux because LC insists on clearing the clipboard when an app (including a widget) is closed. It only worked in Windows.
However, it has now become deprecated because apart from reporting the "choice" info as a single unit, the widgets now also put this info into line 1
of their INI files on the HD. (See the explanation for this above.)

Line 16: Suggested file name

This is where the "parameter variable" as described above is inserted.
In fact, this field can have values other than a file name (e.g. "folder", "*.*", etc.), and the rules for its usage are also described at the top of this page.
However, if you are using the widgets in the simplest possible and most constant way, and you do not wish to make changes to widget functions
programmatically, you can set it manually here. For example, clearing this field to empty would cause the widget to always behave as a file chooser.