File bowsing

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: 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.
char *UnPackSelection(char **flist)

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.
void FileManager(const char *winheader, int flags);

Creates a dialogue that lets the user inspect and maintain the file system. Parameters:
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:

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: 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