Home AESAES Window libraryWindow library Form libraryForm library

8.10 Extended file-selectors

The following functions were introduced with MagiC 4, and permit management of the file-selector:

• fslx_close Closes the file-selector and releases memory
• fslx_do Faster call-up of the file-selector
• fslx_evnt Releases file-selector for use
• fslx_getnxtfile Obtains all further selected entries
• fslx_open Initializes and opens file-selector
• fslx_set_flags Sets certain flags for the whole system

Note: The existence of these functions can be checked with a call of appl_getinfo (opcode 7).

The main advantage of using these routines lies in the ability of the functions specified here to work also with alternative file-systems (catchword: long filenames).

See also:
File-selector as a dialog   File-selector in a window   Operation of file-selectors

8.10.1 fslx_close

Name: »File selectionX close« - Close the file-selector and release memory.
 
Opcode: 191
 
Syntax: int16_t fslx_close ( void *fsd );
 
Description: The call fslx_close closes the file-selector, and releases the specified descriptor. The following apply:
 
Parameter Meaning
   
fsd Descriptor that was passed at the successful opening of a file-selector window
Return value: The function returns the value 1 if successful, else the value 0.
 
Availability: The presence of this call should be checked for using appl_getinfo (opcode 7).
 
Group: Extended file-selectors
 
See also: Binding   fslx_open
 

8.10.1.1 Bindings for fslx_close

C: int16_t fslx_close ( void *fsd );
 
Binding:
  
int16_t fslx_close ( void *fsd )
{
   addr_in[0] = fsd;
   crys_if (191);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 191 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] fsd
int_out int_out[0] Return value

8.10.2 fslx_do

Name: »File selectionX do« - Faster call-up of the file-selector.
 
Opcode: 194
 
Syntax: void *fslx_do ( int8_t *title, int8_t *path, int16_t pathlen, int8_t *fname, int16_t fnamelen, int8_t *patterns, XFSL_FILTER *filter, int8_t *paths, int16_t *sort_mode, int16_t flags, int16_t *button, int16_t *nfiles, int8_t **pattern );
 
Description: The call fslx_do displays a file-selector box on the screen, and takes over its handling. The following apply:
 
Parameter Meaning
   
title Title of the file-selector, or NULL
path Complete path, which starts with the drive letter, and ends with '\'
pathlen Length of the path-receiving buffer
fname Buffer for the filename
fnamelen Length of the filename-receiving buffer
patterns Filename masks such as '*.TXT', '*.PRG' or '*.IMG'; these alternative selectable masks are separated by EOS and terminated by EOS, EOS
filter Filter function which is called before the mask comparison (or NULL); if this returns the value 0 the file is invalid, while a value of 1 will display the filename
paths Path history; the alternative selectable paths are separated by EOS and terminated by EOS, EOS
sort_mode Sort-mode for the display:
0 = By name
1 = By date
2 = By size
3 = By type
4 = Unsorted (physical order)
flags Various settings:
1 = DOSMODE - This is the compatibility mode, also used by fsel_(ex)input, and returns filenames basically in the 8+3 format; for this all subdirectories are called with Dopendir (name, 1)
2 = Do not follow symbolic links; so in that case the date, time as well as the XATTR structure that will pass filter will belong to the link itself
8 = Multiple selection - In this case several files can be selected and passed at a time
button Index of the selected button:
0 = 'Cancel' button
1 = 'OK' button
nfiles Number of selected files
pattern Selected file mask, such as '*.TXT'

Note: The function is a combination of fslx_open and fslx_evnt, but uses a non-windowed dialog box.
 
Return value: The function returns a pointer to a descriptor, which is to be specified for the other routines.
 
Availability: The presence of this call should be checked for using appl_getinfo (opcode 7).
 
Group: Extended file-selectors
 
See also: Binding   fslx_open   fslx_evnt
 

8.10.2.1 Bindings for fslx_do

C: void *fslx_do ( int8_t *title, int8_t *path, int16_t pathlen, int8_t *fname, int16_t fnamelen, int8_t *patterns, XFSL_FILTER *filter, int8_t *paths, int16_t *sort_mode, int16_t flags, int16_t *button, int16_t *nfiles, int8_t **pattern );
 
Binding:
  
void *fslx_do ( int8_t *title, int8_t *path, int16_t pathlen,
                int8_t *fname, int16_t fnamelen,
                int8_t *patterns, XFSL_FILTER *filter,
                int8_t *paths, int16_t *sort_mode,
                int16_t flags, int16_t *button,
                int16_t *nfiles, int8_t **pattern )
{
   addr_in[0] = title;
   addr_in[1] = path;
   addr_in[2] = fname;
   addr_in[3] = patterns;
   addr_in[4] = filter;
   addr_in[5] = paths;

   int_in[0] = pathlen;
   int_in[1] = fnamelen;
   int_in[2] = *sort_mode;
   int_in[3] = flags;

   crys_if (194);

   *button    = int_out[1];
   *nfiles    = int_out[2];
   *sort_mode = int_out[3];
   *pattern   = addr_out[1];

   return ( (void *) addr_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 194 # Function opcode
control+2 control[1] 4 # Entry in int_in
control+4 control[2] 4 # Entry in int_out
control+6 control[3] 6 # Entry in addr_in
control+8 control[4] 2 # Entry in addr_out
addr_in addr_in[0] title
addr_in+4 addr_in[1] path
addr_in+8 addr_in[2] fname
addr_in+12 addr_in[3] patterns
addr_in+16 addr_in[4] filter
addr_in+20 addr_in[5] paths
int_in int_in[0] pathlen
int_in+2 int_in[1] fnamelen
int_in+4 int_in[2] sort_mode
int_in+6 int_in[3] flags
addr_out addr_out[0] Return value
addr_out+4 addr_out[1] pattern
int_out int_out[0] 1
int_out+2 int_out[1] button
int_out+4 int_out[2] nfiles
int_out+6 int_out[3] sort_mode

8.10.3 fslx_evnt

Name: »File selectionX event« - Takes over the handling of the file-selector.
 
Opcode: 193
 
Syntax: int16_t fslx_evnt ( void *fsd, EVNT *events, int8_t *path, int8_t *fname, int16_t *button, int16_t *nfiles, int16_t *sort_mode, int8_t **pattern );
 
Description: The call fslx_evnt takes over the handling of the file-selector displayed on the screen. The following apply:
 
Parameter Meaning
   
fsd Descriptor that was passed at a successful opening of a file-selector window
events EVNT-structure; the events are serviced by the dialog if they are intended for the associated window
path Pointer to the selected path
fname Pointer to the selected filename
button Index of the selected button
0 = 'Cancel' button
1 = 'OK' button
nfiles Number of selected files
sort_mode Selected sort-mode
pattern Seleted file pattern, such as '*.TXT'

Note: Events, i.e. mouse clicks, messages and keypresses are passed on to the file-selector window and serviced by it if appropriate. When an event has been serviced then the corresponding bit in the EVENT structure will be cleared.
 
Return value: The function returns the value 0 if the dialog is to be terminated, else the value 1.
 
Availability: The presence of this call should be checked for using appl_getinfo (opcode 7).
 
Group: Extended file-selectors
 
See also: Binding
 

8.10.3.1 Bindings for fslx_evnt

C: int16_t fslx_evnt ( void *fsd, EVNT *events, int8_t *path, int8_t *fname, int16_t *button, int16_t *nfiles, int16_t *sort_mode, int8_t **pattern );
 
Binding:
  
int16_t fslx_evnt ( void *fsd, EVNT *events, int8_t *path,
                    int8_t *fname, int16_t *button,
                    int16_t *nfiles,
                    int16_t *sort_mode, int8_t **pattern )
{
   addr_in[0] = fsd;
   addr_in[1] = events;
   addr_in[2] = path;
   addr_in[3] = fname;

   crys_if (193);

   *button    = int_out[1];
   *nfiles    = int_out[2];
   *sort_mode = int_out[3];
   *pattern   = addr_out[0];

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 193 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 4 # Entry in int_out
control+6 control[3] 4 # Entry in addr_in
control+8 control[4] 1 # Entry in addr_out
addr_in addr_in[0] fsd
addr_in+4 addr_in[1] events
addr_in+8 addr_in[2] path
addr_in+12 addr_in[3] fname
addr_out addr_out[0] pattern
int_out int_out[0] Return value
int_out+2 int_out[1] button
int_out+4 int_out[2] nfiles
int_out+6 int_out[3] sort_mode

8.10.4 fslx_getnxtfile

Name: »File selectionX get next file« - Obtains all further selected entries in the file-selector.
 
Opcode: 192
 
Syntax: int16_t fslx_getnxtfile ( void *fsd, int8_t *fname );
 
Description: The call fslx_getnxtfile otains all the further, selected entries in the file-selector. The following apply:
 
Parameter Meaning
   
fsd Descriptor that was passed at a successful opening of a file-selector window
fname Name of the obtained entry

Note: If the flag GETMULTI was passed with fslx_do or fslx_open, then fslx_do or fslx_evnt will return in the parameter nfiles the number of files that are still selected in addition to the one in fname. One can call these further files with fslx_getnxtfile. Only after this may one call fslx_close.
 
Return value: The function returns the value 0 if no further file is selected, else the value 1 if one filename was still to be copied.
 
Availability: The presence of this call should be checked for using appl_getinfo (opcode 7).
 
Group: Extended file-selectors
 
See also: Binding   fslx_open   fslx_close
 

8.10.4.1 Bindings for fslx_getnxtfile

C: int16_t fslx_getnxtfile ( void *fsd, int8_t *fname );
 
Binding:
  
int16_t fslx_getnxtfile ( void *fsd, int8_t *fname )
{
   addr_in[0] = fsd;
   addr_in[1] = fname;

   crys_if (192);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 192 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] fsd
addr_in+4 addr_in[1] fname
int_out int_out[0] Return value

8.10.5 fslx_open

Name: »File selectionX open« - Initializes and opens the file-selector
 
Opcode: 190
 
Syntax: void *fslx_open ( int8_t *title, int16_t x, int16_t y, int16_t *whdl, int8_t *path, int16_t pathlen, int8_t *fname, int16_t fnamelen, int8_t *patterns, XFSL_FILTER *filter, int8_t *paths, int16_t sort_mode, int16_t flags );
 
Description: The call fslx_open initializes and opens the file-selector box. The following apply:
 
Parameter Meaning
   
title Window title of file-selector, may be NULL
x X-coordinate, and
y Y-coordinate of the top left corner of the window; for x=y=-1 the window will be centred
whdl Window handle after successful opening
path Complete path, starts with drive and ends with '\'.
From MagiC 6.10 onwards the path may be initialized incompletely, as with fsel_xxx, e.g. as an empty string; MagiC will then complete the path in a sensible way
pathlen Length of path buffer, i.e. maximum pathlength + 1 (for EOS)
fname Buffer for the filename
fnamelen Length of filename buffer, i.e. maximum length of filename + 1 (for EOS)
patterns Filemask, e.g. '*.TXT' or '*.PRG,*.APP'. The alternatively selectable masks are separated by EOS and terminated by EOS,EOS.
From MagiC 6.10 onwards a NULL-pointer may be passed here, in which case MagiC then uses '*\0'.
filter May be NULL. The filter function is called before the mask comparison. If it returns 0 then the file is invalid, if 1 is returned then the filename will be displayed.
paths Path "history" e.g. "C:\\BIN\\" etc. The alternatively selectable paths are separated by EOS and terminated by EOS,EOS. A NULL-pointer may be passed here.
sort_mode Sort-mode for the display:
SORTBYNAME (0) = By name
SORTBYDATE (1) = By date
SORTBYSIZE (2) = By size
SORTBYTYPE (3) = By type
SORTBYNONE (4) = Unsorted (physical order)
SORTDEFAULT (-1) = Default

SORTDEFAULT exists from Magic 6.10 onwards and means that the sort mode saved in the system will be used.
flags Various settings:
1 = (DOSMODE) This is the compatibility mode that is also used by fsel_(ex)input and basically returns filenames in the 8+3 format; for this all directories are called with Dopendir(DOPEN_COMPAT)
2 = (NFOLLOWSLKS) Symbolic links will not be followed, i.e. date and time etc., as well as the XATTR-structure that is passed to filter, belong to the link itself
8 = If GETMULTI is set, one can select and pass several files at the same time; for this fslx_getnxtfile is used if fslx_evnt or fslx_do in the parameter nfiles signals that there are still further files selected
Return value: The function returns a descriptor for the further actions, else the value NULL if an error has arisen.
 
Availability: The presence of this call should be checked for using appl_getinfo (opcode 7).
 
Group: Extended file-selectors
 
See also: Binding   fslx_close
 

8.10.5.1 Bindings for fslx_open

C: void *fslx_open ( int8_t *title, int16_t x, int16_t y, int16_t *whdl, int8_t *path, int16_t pathlen, int8_t *fname, int16_t fnamelen, int8_t *patterns, XFSL_FILTER *filter, int8_t *paths, int16_t sort_mode, int16_t flags );
 
Binding:
  
void *fslx_open ( int8_t *title, int16_t x, int16_t y,
                  int16_t *whdl, int8_t *path,
                  int16_t pathlen, int8_t *fname,
                  int16_t fnamelen, int8_t *patterns,
                  XFSL_FILTER *filter, int8_t *paths,
                  int16_t sort_mode, int16_t flags )
{
   addr_in[0] = title;
   addr_in[1] = path;
   addr_in[2] = fname;
   addr_in[3] = patterns;
   addr_in[4] = filter;
   addr_in[5] = paths;

   int_in[0] = x;
   int_in[1] = y;
   int_in[2] = pathlen;
   int_in[3] = fnamelen;
   int_in[4] = sort_mode;
   int_in[5] = flags;

   crys_if (190);

   *whdl = int_out[0];
   return ( (void *) addr_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 190 # Function opcode
control+2 control[1] 6 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 6 # Entry in addr_in
control+8 control[4] 1 # Entry in addr_out
addr_in addr_in[0] title
addr_in+4 addr_in[1] path
addr_in+8 addr_in[2] fname
addr_in+12 addr_in[3] patterns
addr_in+16 addr_in[4] filter
addr_in+20 addr_in[5] paths
int_in int_in[0] x
int_in+2 int_in[1] y
int_in+4 int_in[2] pathlen
int_in+6 int_in[3] fnamelen
int_in+8 int_in[4] sort_mode
int_in+10 int_in[5] flags
addr_out addr_out[0] Return value
int_out int_out[0] whdl

8.10.6 fslx_set_flags

Name: »File selectionX set flags« - Sets certain flags of the file-selector for the whole system.
 
Opcode: 195
 
Syntax: int16_t fslx_set_flags ( int16_t flags, int16_t *oldval );
 
Description: The call fslx_set_flags sets certain flags of the file-selector box for the whole system. The following apply:
 
Parameter Meaning
   
flags Various flags:
1 = SHOW8P3 is valid only for the display of directories on DOS drives; it corresponds to the switch "Show TOS Files as '8+3'" in Magxdesk
oldval Previous value
Return value: The function return the value 0 in case of error, else the value 1 for error-free execution.
 
Availability: The presence of this call should be checked for using appl_getinfo (opcode 7).
 
Group: Extended file-selectors
 
See also: Binding   fslx_open   fslx_close
 

8.10.6.1 Bindings for fslx_set_flags

C: int16_t fslx_set_flags ( int16_t flags, int16_t *oldval );
 
Binding:
  
int16_t fslx_set_flags ( int16_t flags, int16_t *oldval )
{
   int_in[0] = 0;
   int_in[1] = flags;

   crys_if (195);

   *oldval = int_out[1];
   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 195 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 2 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] 0
int_in+2 int_in[1] flags
int_out int_out[0] Return value
int_out+2 int_out[1] oldval

8.10.7 Operation of file-selectors from MagiC 4 onwards

MagiC as from Version 4.0 makes its own file-selector box available, which apart from support of long filenames also offers some operating niceties otherwise known only from alternative file-selectors. The following table gives a synopsis of the more important shortcuts:

Key presses Function
   
Return No file selected: Returns the text in the editable field to the program.
File selected: Returns the selected file.
Folder selected: Opens the folder.
Alt-A..Z Opens the respective drive in current directory
Ctrl-Esc Rereads the directory
Ctrl-Backspace or
Ctrl-H Goes back one directory level
Ctrl-D Deselects all entries. With this one can force the return of the input filename in place of the selected file.
Cursor up,down Moves selection up/down
Ctrl-Cursor up,down Scrolls up/down
Sh-Cursor up,down Moves selection by one page
Sh-Ctrl-Cursor up,down Scrolls page by page
Home Selects topmost element
Sh-Home Selects lowest element

There are some things to note for the operation of the buttons too: A double-click on the 'parent' field jumps back to the root directory. A click on a line selects the object. In cases where several files are selectable (can be influenced through the system call), these can be selected with a [Shift]-click.
In each case one can deselect one file with [Shift]-click.

Further, one should note:

See also: Key assignments

8.10.8 File-selector as a dialog

fsel = fslx_do(..., &button, &nfiles, ...);

if (fsel) /* Was the selector open? */
{
   if (button)
   {
      while (--nfiles) /* Several files? */
         fslx_getnxtfile(...);   /* Get them all */
   }

   fslx_close(fsel); /* Release everything again */
}

8.10.9 File-selector in a window

fsel = fslx_open(...);
if (fsel)
{
   do {
      evnt.mwhich = evnt_multi(...);
      rv = fslx_evnt(fsel, &evnt, ..., &nfiles, ...);

      /* Evaluate bits for own windows/menus */
   } while (rv);

   while (--nfiles) fslx_getnxtfile(...);
   fslx_close(fsel);
}
Home AESAES Window libraryWindow library Form libraryForm library