HomeAESApplication libraryPrint dialogs

8.4 File-selector library

The functions of this library make a file-selector available, which is used for loading and saving files. The following routines are present for this purpose:

fsel_boxinput Selects filename with file-selector (Boxkite)
fsel_exinput Selects filename with file-selector (AES 1.4 onwards)
fsel_input Selects filename with file-selector

Note: Unfortunately alternative file systems (keyword: long filenames) are not supported; as of MagiC 4 however this is taken over by the functions of the FSLX library.

See also: Extended file-selectors   Style guidelines

8.4.1 fsel_boxinput

Name: »File selection extended input« - Select filenames.
Opcode: 91
Syntax: int16_t fsel_boxinput ( int16_t *global, int8_t *fs_einpath, int8_t *fs_einsel, int16_t *fs_eexbutton, int8_t *elabel, FSEL_CALLBACK callback );
Description: The call fsel_boxinput makes a file-selector dialog box available, which can also be passed a title string. It is used in an extended version of the file-selector BoxKite.

The function can be passed the following parameters:
Parameter Meaning
   
fs_einpath Name of the default access path (absolute) with appended search mask; after the call it contains the new pathname
fs_einsel Name of the default file; after the call it contains the newly selected filename
fs_eexbutton Exit button:
0 = 'Cancel' was selected
1 = 'OK' was selected
fs_elabel Title-line
callback Address of a function that is called by BoxKite if a GEM message is to be passed to the main application.
This includes not just the message WM_REDRAW but also WM_MOVED, for instance, as there are some operating system versions that offer movement of windows lying at the back. Messages that implicitly open new windows or top existing ones, on the other hand, should be ignorerd or stored and only processed after return from the file-selector. WM_TOPPED messages are not passed through to the message callback.


Hint: BoxKite as of Version 2.00 also makes the functions of the MagiC file-selector available. The presence of this call should be checked for using appl_getinfo (opcode 7).
Return value: It is imperative that the return value of the function (0 = error) is respected, as a shortage of memory, for instance, may make it impossible to use a file-selector.
Availability: If BoxKite from Version 1.71 on is installed. This can be checked for by the presence of the cookie HBFS. But note that this is also present for versions earlier than Version 1.71.
Group: File-selector library
See also: Binding   XFS-concept in MagiC

8.4.1.1 Bindings for fsel_boxinput

C:

/* Message handler for updating background windows */
typedef void cdecl (* FSEL_CALLBACK)(int16_t *msg);

int16_t fsel_boxinput ( int16_t *global, int8_t *fs_einpath, int8_t *fs_einsel, int16_t *fs_eexbutton, int8_t *elabel, FSEL_CALLBACK callback );
Binding:
int16_t fsel_boxinput ( int16_t *global, int8_t *fs_einpath,
                        int8_t *fs_einsel, int16_t *fs_eexbutton,
                        int8_t *elabel, FSEL_CALLBACK callback )
{
  void *aespb[6], *addrin[6], *addrout[6];
  int contrl[5], intin[16], intout[7];

  aespb[0] = contrl;
  aespb[1] = global;
  aespb[2] = intin;
  aespb[3] = intout;
  aespb[4] = addrin;
  aespb[5] = addrout;

  contrl[0] = 91;
  contrl[1] = 0;
  contrl[2] = 2;
  contrl[3] = 4;
  contrl[4] = 0;

   addr_in[0] = fs_einpath;
   addr_in[1] = fs_einsel;
   addr_in[2] = elabel;
   addr_in[3] = callback;

  _crystal((AESPB *)aespb);

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

Address Element Contents
control control[0] 91 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 2 # Entry in int_out
control+6 control[3] 4 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] fs_einpath
addr_in+4 addr_in[1] fs_einsel
addr_in+8 addr_in[2] elabel
addr_in+12 addr_in[3] callback
int_out int_out[0] Return value
int_out+2 int_out[1] fs_eexbutton

Note: BoxKite requires information from the 'global' array of the main application. The supplied GEM bindings of development systems normally pass this automatically.

8.4.2 fsel_exinput

Name: »File selection extended input« - Select filenames.
Opcode: 91
Syntax: int16_t fsel_exinput ( int8_t *fs_einpath, int8_t *fs_einsel, int16_t *fs_eexbutton, int8_t *elabel );
Description: The call fsel_exinput makes a system file-selector dialog box available in which the user may choose a complete GEMDOS path specification. It may also be passed a title-string that is to appear in the file-selector (normally indicating the action the user is about to take).



The function can be passed the following parameters:
Parameter Meaning
   
fs_einpath Name of the default access path (absolute) with appended search mask; after the call it contains the new pathname
fs_einsel Name of the default file; after the call it contains the newly selected filename
fs_eexbutton Exit button:
0 = 'Cancel' was selected
1 = 'OK' was selected
fs_elabel Titelzeile


Notes: The function should be nested with wind_update (BEG_MCTRL or END_MCTRL) to prevent double-clicks being passed on to underlying windows.

fs_einpath points to a character buffer at least 128 bytes long (200 bytes if CD-ROMs are to be accessed). fs_einsel points to a 13-byte buffer (12 for filename characters plus a terminating NULL). fs_elabel points to a buffer up to 30 characters long.
Return value: It is imperative that the return value of the function (0 = error) is respected, as a shortage of memory, for instance, may make it impossible to use a file-selector.
Availability: This function is available only from AES 1.4 onwards.

It is also present in FreeGEM. To check for this feature, use appl_init and check that xbuf.arch is non-zero.

If it is available, it should be used rather than the fsel_input call, as with the latter the user is not reminded what the function is actually doing.
Group: File-selector library
See also: Binding   fsel_input   XFS-concept in MagiC

8.4.2.1 Bindings for fsel_exinput

C: int16_t fsel_exinput ( int8_t *fs_einpath, int8_t *fs_einsel, int16_t *fs_eexbutton, int8_t *elabel );
Binding:
int16_t fsel_exinput (int8_t *fs_einpath, int8_t *fs_einsel,
                      int16_t *fs_eexbutton, int8_t *elabel)
{
   addr_in[0] = fs_einpath;
   addr_in[1] = fs_einsel;
   addr_in[2] = elabel;

   crys_if (91);

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

Address Element Contents
control control[0] 91 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 2 # Entry in int_out
control+6 control[3] 3 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] fs_einpath
addr_in+4 addr_in[1] fs_einsel
addr_in+8 addr_in[2] elabel
int_out int_out[0] Return value
int_out+2 int_out[1] fs_eexbutton

8.4.3 fsel_input

Name: »File selection input« - Selects filenames.
Opcode: 90
Syntax: int16_t fsel_input ( int8_t *fs_iinpath, int8_t *fs_iinsel, int16_t *fs_iexbutton );
Description: The call fsel_input makes a file-selector dialog box available: The following apply:
Parameter Meaning
   
fs_iinpath Name of the default access path (absolute) with appended search mask; after the call it contains the new pathname
fs_iinsel Name of the default file; after the call it contains the newly selected filename
fs_iexbutton Exit button:
0 = 'Cancel' was selected
1 = OK' was selected


Notes: The function should be nested with wind_update (BEG_MCTRL or END_MCTRL) to prevent double-clicks being passed on to underlying windows.

fs_iinpath points to a character buffer at least 128 bytes long (200 bytes if CD-ROMs are to be accessed). fs_iinsel points to a 13-byte buffer (12 for filename characters plus a terminating NULL).

Incidentally, AES versions earlier than 1.4 can only display a maximum of 100 files; there a 'ping' warns if not all files can be displayed.
Return value: It is imperative that the return value of the function (0 = error) is respected, as a shortage of memory, for instance, may make it impossible to use a file-selector.
Availability: All AES versions, not present in ViewMAX/3, and will crash ViewMAX/2.
Group: File-selector library
See also: Binding   fsel_exinput   XFS-concept in MagiC

8.4.3.1 Bindings for fsel_input

C: int16_t fsel_input ( int8_t *fs_iinpath, int8_t *fs_iinsel, int16_t *fs_iexbutton );
Binding:
int16_t fsel_input (int8_t *fs_iinpath, int8_t *fs_iinsel,
                    int16_t *fs_iexbutton)
{
   addr_in[0] = fs_iinpath;
   addr_in[1] = fs_iinsel;

   crys_if (90);

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

Address Element Contents
control control[0] 90 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 2 # 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] fs_iinpath
addr_in+4 addr_in[1] fs_iinsel
int_out int_out[0] Return value
int_out+2 int_out[1] fs_iexbutton

HomeAESApplication libraryPrint dialogs