In CGUI there are two functions for browsing the file system. If you use
the functions in your program you must link with the libaldat.a library
located in the lib directory of you Allegro directory.
const char *FileSelect(const char *masks, const char *rpath, int flags,
const char *winheader, const char *buttonlabel);
Opens a file selector dialogue. Simple usage:
char *fn;
FILE *filep;
fn = FileSelect("*.txt", "", 0, "Select a file", "OK");
/* fn points to a full path string, the memory will be deallocated by
the file-browser - you must not do. */
filep = fopen(fn, "r");
...
This function may be useful if your program needs to let the user
specifiy a file to load, or maybe a filename
and path to store things in or just to specify a path where the
program shall put files or seach for files. The user will expect a
file-browser to behave slightly different in each of these 3 cases.
You can control its beaviour using the `flags' parameter.
The dialogue is modal (i.e. the parent window of the file selector is
locked for mouse input until the file-selector has been closed).
The user may browse within Allegro datafiles.
The user closes the dialogue either by use of a cancel-button
or a confirm-button. If cancel was pressed, the return value will be
a pointer to an empty string.
Reuturn value:
The return value is a pointer to a string containing the full path to
the seleceted file (or directory). If an object in a datafile was
selected it is separated from name of the datafile with the '#'
character. If the flag `FS_MULTIPLE_SELECTION' is set the user may
possibly have selected more than one file. If so, each file will be
enclosed in quotation marks, '"', and separated with semicolon,';' (e.g.
like "highscore.txt";"readme.txt") and `UnPackSelection' can be used
to extract single file names from the returned string.
The memory location of the string, is valid only directly after the
return and belongs to the file-selector, so if you need to use the path
later on you have to make a copy to save.
Parameters:
- masks: A string containing the patterns to search matching files for.
Multiple masks are allowed: separate with semicolon (e.g.
"*.txt;*.doc")
- rpath: Restriction path. The given path is used as an restriction
for the browsing. The user will be able to browse from the given point
(witch is always the starting point - the path stored in the datafile
will be ignored) and downwards, not above it in the directory tree.
In particular you can restrict the browsing to some Allegro datafile.
- flags: The `flags' variable control some of the properties of the
browser. Their names and meaning are as follows:
- FS_BROWSE_DAT: Will display Allegros' datafiles as directories
and lets the user browse them as if they actually where
directories.
- FS_DISABLE_EDIT_DAT: Set this flag if you allow the user to
browse datafiles but not want him/her to change them.
- FS_WARN_EXISTING_FILE: Will warn the user if he/she specifies a
filename that is already existing. Typically used in store
operations.
- FS_FORBID_EXISTING_FILE: Never give up...
- FS_REQUIRE_EXISTING_FILE: Will only accept a name specification
that really exist. Typically used in load operations.
- FS_SELECT_DIR: When the user selects a directory, that name will
be put into the name-selection field. If the user instead tries to
select a file, that operation will be ignored.
Typically used when the user is supposed to specify a directory
name.
- FS_DISABLE_CREATE_DIR: Don't let the user create directories.
- FS_DISABLE_DELETING: Don't let the user delete files or
directories.
- FS_DISABLE_COPYING: Don't let the user copy files or directories.
- FS_SHOW_MENU: Shows a menu to the user. The menu contains:
- Check-box: Show the image of an image file or object.
- Check-box: Show the original file name of a data-file object.
- Check-box: Show the file or object time.
- Check-box: Show the file or object size.
- Check-box: Show the file attributes of disk files.
- Check-box: Show hidden and system disk files.
- Check-box: Show the file names case-formatted.
- Selection: Open a file manager.
- Selection: Open a subwindow showing the copy buffer.
- FS_NO_SETTINGS_IN_CONFIG: By default the browser retrievs the
previos user configuration from the current config-file (and
stores the new one when closing). Use this flag to suppresse this
behaviour. The data concerned are:
- The initial path (starting point) when opening.
- Flag telling if the image of an image file or object shall be
displayed.
- Flag telling if the original file name of a data-file object
shall be displayed.
- Flag telling if file time shall be displayed.
- Flag telling if file size shall be displayed.
- Flag telling if file attributes shall be displayed.
- Flag telling if hidden/system file shall be displayed.
- Flag telling if formatted case of file-names shall be
displayed.
- The width of each column in the file-list of the browser.
- The width of the file-list of the browser.
- The height of the file-list of the browser.
- The window position.
- A flag indication if the copy-buffer was opened last time.
- A flag indication if the copy-buffer is in add-mode or not.
- The sorting criterias.
The settings for the file-manager is separated from those of
the file-selector.
- FS_MULTIPLE_SELECTION: Let the user select more than one file.
- FS_NO_DRAG_DROP: Disables the feature of dragging files and
directories.
- FS_SAVE_AS: Makes the file selector beahave slightly different
from the default. Currently the only difference is that a name
entered by the user (typed or selected) will not be rubbed from the
selection field when changing directory.
- winheader: A string that will be used as header of the browser
window. If you pass the empty string, a default text will be used.
- buttonlabel: A string that will be used as label of the confirm
button. If you pass the empty string, a default text will be used.
Note! The implementation of the browser is a list, and by default lists
get an event for SINGLE CLICK. In the browser the user can double-click
to select a certain file or directory directly (this is a common
behaviour of bowsers). However, what will happen if doubel-clicking on
e.g. a directory for opening it? If the drag-drop is active it will in
most cases be seen as a try to grip the object and therby it will be
inserted into the copy-buffer.
See also:
FileManager,
UnPackSelection.
This function may be used to unpack individual filenames (including path)
from the return string of `FileSelect'.
The return value points to the first file of *flist and is dynamic memory
and it is your responsibility to free it. *flist will be advanced to next
file and will point to the string end when no more files.
See also:
FileSelect.
Creates a dialogue that lets the user inspect and maintain the
file system.
- Files and directories may be deleted and copied, either
by use of hot-keys, menu-selection or drag-and-drop.
- Directories may be created.
- The contents of the file-list to display may be
configured by the user.
- The size of many window objects may be configured by the user.
- There are special copy features, allowing the user to walk around
and marking files for copying and also the possibility to
display the current set of files marked for copying.
- I is possible for the user to start new file-managers that can
used for e.g. drag-and-drop.
- The possibility of multiple file-masks.
- The user may edit the name and attributes of files and directories.
- Modifications of the various window settings and feature modes made
by the user will be stored in the current config file, and are
retrieved next time a file-manager is opened. Specially the current
directory will be stored.
Parameters:
- winheader: A string used as header of the browser window.
- flags: The flags variable control some of the properties of the
browser. Thier names and meaning is as follows:
- FM_BROWSE_DAT: Will display Allegro's datafiles as directories
and lets the user browse them as if they actually where
directories.
- FM_DISABLE_EDIT_DAT: Set this flag if you allow the user to
browse datafiles but not want him/her to change them.
- FM_DISABLE_CREATE_DIR: Don't let the user create directories.
- FM_DISABLE_DELETING: Don't let the user delete file or
directories.
- FM_DISABLE_COPYING: Don't let the user copy files or directories.
- FM_DO_NOT_SHOW_MENU: By default a menu is created (See
FileBrowse about the contents). This flag suppresses the default.
- FM_NO_SETTINGS_IN_CONFIG: By default the browser retrievs the
previos user configuration from the current config-file (and
stores the new one when closing). Use this flag to suppresses this
behaviour. The data concerned are:
- The path to use when opening.
- Flag telling if the image of an image file or object shall be
displayed.
- Flag telling if the original file name of a data-file object
shall be displayed.
- Flag telling if file time shall be displayed.
- Flag telling if file size shall be displayed.
- Flag telling if file attributes shall be displayed.
- Flag telling if hidden/system file shall be displayed.
- Flag telling if formatted case of file-names shall be
displayed.
- The width of each column in the file-list of the browser.
- The width of the file-list of the browser.
- The height of the file-list of the browser.
- The window position.
- A flag indication if the copy-buffer was opened last time.
- A flag indication if the copy-buffer is in add-mode or not.
- The status field width.
- The sorting criterias.
The settings for the file-manager is separated from those of
the file-selector.
- FM_NO_FLOATING: This will force the browsing window to be modal.
(by default it is a floating window).
See also:
FileSelect.
int RegisterFileType(const char *ext,
void (*Handler)(void *privatedata, char *path), void *privatedata,
const char *actionname, const char *icon, const char *typetext,
void (*Viewer)(void *privatedata, void *viewdata));
This function will register a file type so that the file-browser
will identify it and give it some special handling. There are three
things that can be done:
- Assign an icon to that file type (to be displayed in the browser).
- Assign a name to that file type (to be displayed in the inspect/edit
dialogue).
- Assign a call-back function to that file type. This will give the
user the opportunity to perform some action with such files
as input. Optionally you can pass a name for the action.
- Assign a pre-viewer for that file type.
If e.g. you only want to register an icon or name just pass NULL for the
data and call-back parameters.
The registration will be reflected both in the file-selector and the
file-manager concerning icon and info. The action registration will
however only have effect in the file-manager.
All registering is global, i.e. if the browser is used in different
contexts they will be present at all of them. You can disable a
registration by calling with all parameters set to NULL.
Parameters:
- ext: The file extension to register e.g. "txt" for "*.txt"
files.
Note: this is not the usual "file-mask". Only the substring following
a possible '.' in the filename must be passed and it must also be a
distinct string - no wildcards.
If you alternativly want to make a registration for a datfile object
type, just pass the name of the data-object type prefixed by a '#',
e.g. like "#RLE" for rle sprites.
- Handler: The name of a function to be called when the user selects a
file of this type (i.e. click with the right mouse button and selects
"action name"). The call-back will be executed without closing the
fila-manager dialogue.
`Handler' takes the following parameters:
- data: A pointer to any data (this will be the same value as
previously passed to `RegisterFileType').
- path: The path and filename that was selected.
- privatedata: A pointer to any data. It will be passed to `Handler'
and `Viewer' when called.
- actionname: An optional string that specifies the action for the
user, (e.g. "Edit" or "Execute"). The action-name will e.g. be
displayed in the drop-down menu where the action is executed. If
omitted the default text will be "Action".
- icon: An icon that the browser will show to the left of any file
of this type. If you want the icon to be displayed properly without
clipping: keep the size within 22x16. The icon must have been loaded
globally with the CGUI-function `CguiLoadImage' prior to the registration.
- typetext: A string that tells the user what type of file this is
(i.e. as an alternative to the icon, but may possibly be more
exhaustive).
- Viewer: A function that understands files of type `ext'. It will be
called when the file browser is about to view the content of a file.
This may be done in some different contexts depending on what the user
does (which can be restricted by your settings) and which options the
user has set (which availibility for modification can also be
restriced by your settings). E.g. in the inspect/edit dialogue of file
object and in the pre-view.
`Viewer' shall take two parameters. The first one is your `privatedata'
and the second is:
- if `ext' defines an file extension then viewdata is the fullpath
name to the a file of type `ext'.
- if `ext' defines a data-file type the viewdata is a pointer to
a datafile object.
`Viewer' is supposed to add some object that displays the content of
the file in a some way.
Pass an empty string for those parameters not used.
Pass NULL-pointers for call-backs you don't need.
Returns 0 if fail (ext is empty) else non-zero.
Back to contents