This library contains functions to initialize and terminate a GEM application; in addition these routines permit communication with other processes. In total, the following functions are available:
• appl_bvset | Sets connected logical drives |
• appl_control | Targeted control of applications |
• appl_exit | Deregisters AES user program and releases ID |
• appl_find | Gets AES ID of another AES application |
• appl_getinfo | Gets system information |
• appl_getinfo_str | Gets extended system information |
• appl_getcicon | Get a CICON (Icon server) |
• appl_init | Registers AES application |
• appl_options | Sets or gets application options |
• appl_read | Reads AES messages |
• appl_search | Searches for applications in system |
• appl_tplay | Plays back AES events |
• appl_trecord | Records AES events |
• appl_write | Writes AES messages |
• appl_xbvget | Gets connected logical drives |
• appl_xbvset | Extended version for reporting connected drives |
• appl_yield | Forces AES process-switch |
• _appl_yield | Forces AES process-switch |
• x_appl_flags | Controls execution flags |
• x_appl_font | Changes font and window borders |
• x_appl_sleep | Puts application to sleep, or wakes it up |
• x_appl_term | Terminate an application and remove it from memory. |
Note: Special attention is drawn here to appl_getinfo, with whose help one can easily inquire about the properties of the system at run-time.
See also: Style guidelines
Name: | »Application bit-vector set« - Set the available logical
drives for the file-selector.
| ||||||
Opcode: | 16
| ||||||
Syntax: | int16_t appl_bvset ( uint16_t bvdisk, uint16_t bvhard );
| ||||||
Description: | The call appl_bvset informs the GEM about the logical drives
that are present; required (amongst others) for the file-selector. The
following apply:
They are available to the application in global[13] and global[14]. In GEM/4 and GEM/5, use appl_xbvset to access drives beyond P. | ||||||
Return value: | Not known at present.
| ||||||
Availability: | The function is available only from PC-GEM Version 2.0
onwards, KAOS 1.4.2 and MagiC.
| ||||||
Group: | Application library
| ||||||
See also: | Binding appl_xbvset Dsetdrv
|
C: | int16_t appl_bvset ( uint16_t bvdisk, uint16_t bvhard );
| |||||||||||||||||||||||||||
Binding: |
int16_t appl_bvset (uint16_t bvdisk, uint16_t bvhard) { int_in[0] = bvdisk; int_in[1] = bvhard; return ( crys_if(16) ); } | |||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application control« - Targeted control of applications.
| ||||||||||||||||||||||||||||||||||
Opcode: | 129
| ||||||||||||||||||||||||||||||||||
Syntax: | int16_t appl_control ( int16_t ap_cid, int16_t ap_cwhat, void
*ap_cout);
| ||||||||||||||||||||||||||||||||||
Description: | The call appl_control can be used to control the activity of
applications.
Note: Hidden application have a '*' placed in front of their names in the applications menu, unless they did not have a window open during hiding. If the latter is the case only the active application is changed. So the '*' in front of the name means: One or more windows of this application are hidden. | ||||||||||||||||||||||||||||||||||
Return value: | 0 = An error has occurred
>0 = No error has arisen | ||||||||||||||||||||||||||||||||||
Availability: | The presence of the function can be checked via appl_getinfo (opcode
65).
| ||||||||||||||||||||||||||||||||||
Group: | Application library
| ||||||||||||||||||||||||||||||||||
See also: | Binding SM_M_SPECIAL
|
C: | int16_t appl_control ( int16_t ap_cid, int16_t ap_cwhat, void
*ap_cout);
| ||||||||||||||||||||||||||||||
Binding: |
int16_t appl_control ( int16_t ap_cid, int16_t ap_cwhat, void *ap_cout); { int_in[0] = ap_cid; int_in[1] = ap_cwhat; addr_in[0] = ap_cout; return ( crys_if(129) ); } | ||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application exit« - Deregister an application from the
AES.
|
Opcode: | 19
|
Syntax: | int16_t appl_exit ( void );
|
Description: | The call appl_exit deregisters an applicatiion from the AES
again and releases its application ID.
|
Return value: | An error has arisen only if a 0 is returned.
|
Availability: | All AES versions.
|
Group: | Application library
|
See also: | Binding appl_init
|
C: | int16_t appl_exit ( void );
| |||||||||||||||||||||
Binding: |
int16_t appl_exit (void) { return ( crys_if(19) ); } | |||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application find« - Obtain the application ID number of an
AES application.
| ||||||||||||
Opcode: | 13
| ||||||||||||
Syntax: | int16_t appl_find ( CONST int8_t *ap_fpname );
| ||||||||||||
Description: | The call appl_find obtains the application identifier of
another application running in parallel. ap_fpname points to
the filename of the application whose identifier is to be found
(without an extension).
Important: It is imperative that the name is eight characters long; if it shorter, it must be padded with blanks. The name string must be NULL-terminated. In MagiC and AES version 4.0 and above one can also obtain the ID of the current application by passing a NULL-pointer. In addition it is possible to recalculate the AES ID of an application to the MiNT ID, and vice versa. This is done as follows:
Note: The function works correctly only if the relevant program was launched with shel_write. One should also point out that threads can not be found with this function. For KAOS 1.4.2 and MagiC one can also obtain the name of an application by passing the string "?\0\n", where "n" represents the ap_id. If the function value returns 0, the ap_id is invalid. Otherwise the return is 1, and the string will be overwritten by the application's name. If two applications have the same name, only the first will be found. Some AES names are pre-defined: "SCRENMGR": Screen manager " ": Integrated desktop "?AGI ": appl_getinfo with AES versions < 4.00 is present | ||||||||||||
Return value: | A negative return value denotes that an error has arisen.
| ||||||||||||
Availability: | The presence of the additional features can be checked with
appl_getinfo (opcode 4).
| ||||||||||||
Group: | Application library
| ||||||||||||
See also: | Binding appl_search Screen-manager
|
C: | int16_t appl_find ( CONST int8_t *ap_fpname );
| ||||||||||||||||||||||||
Binding: |
int16_t appl_find (CONST int8_t *ap_fpname) { addr_in[0] = ap_fpname; return ( crys_if(13) ); } | ||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application get information« - Inquire information about
available function calls and properties of the AES.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Opcode: | 130
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Syntax: | int16_t appl_getinfo ( int16_t ap_gtype, int16_t *ap_gout1,
int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4 );
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description: | With the function appl_getinfo one can inquire certain
properties of the operating system at run-time.
ap_gtype determines the type of information that is to be returned in shorts pointed to by ap_gout1..4. Details are as follows: AES_LARGEFONT (0): Get AES regular font information
AES_SMALLFONT (1): Get AES small font information
AES_SYSTEM (2): Colours
AES_LANGUAGE (3): AES language
AES_PROCESS (4): General AES environment info 1
AES_PCGEM (5): General AES environment info 2
AES_INQUIRE (6): General AES environment info 3
7: Reserved for MagiC and other OS extensions; MultiTOS sets all return values always to 0. In MagiC:
AES_MOUSE (8): Mouse support
AES_MENU (9): Menu support
AES_SHELL (10): shel_write
AES_WINDOW (11): window support
AES_MESSAGE (12): Messages sent to applications
AES_OBJECT (13): Object information
AES_FORM (14): Forms (MagiC form_xdo and form_xdial)
AES_EXTENDED (64): Extended functions
AES_NAES (65): Additional N.AES functions
96: AES Version There is an extended mode since XaAES from 2004-12-18.
Together (ap_gout1 & ap_gout2), these two contain the decimal representation of the AES's version number. For XaAES v0.992, ap_gout1 contains 0 (0x0000) and ap_gout1 contains 992 (0x3e0). 97: Available WF_OPTS settings Since XaAES 2005-07-09
98: Available extended AES functions Since XaAES 2005-12-08
99: Available application options The bitmasks returned here are identical to the bitmasks used to modify the application options via appl_options(APL_OPTS). Needless to say, this option is not available if bit 0 in ap_gout1 is cleared after appl_getinfo(AES_FUNCTIONS). Since XaAES 2005-12-08
AES_WINX (22360): Information about extensions in WINX This information type exists since WINX 2.3
22528: XaAES No longer supported as of 2004-12-18. Look to ap_gtype = 96
Note: A problem with this function consists of establishing just when it may be called. Although it ought to be present as of AES version 4.0, MagiC 2.0 (and also MagiC 3.0) for example show the version 3.99. For this reason many programmers define the function appl_xgetinfo, in which a check is made whether appl_getinfo is present in the current system environment. Note: This function was backported to FreeGEM as xapp_getinfo (opcode 1020) and exists if the ABLE_GETINFO bit is set in the "abilities" bitmap. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Return value: | A return value of 0 indicates an error; with a value of 1, no
error has arisen.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Availability: | Available as of AES version 4.00.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Group: | Application library
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also: | Binding
|
C: | int16_t appl_getinfo ( int16_t ap_gtype, int16_t *ap_gout1,
int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4 );
| ||||||||||||||||||||||||||||||||||||
Binding: |
int16_t appl_getinfo (int16_t ap_gtype, int16_t *ap_gout1, int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4) { int_in[0] = ap_gtype; crys_if (130); *ap_gout1 = int_out[1]; *ap_gout2 = int_out[2]; *ap_gout3 = int_out[3]; *ap_gout4 = int_out[4]; return ( int_out[0] ); } | ||||||||||||||||||||||||||||||||||||
GEM-Arrays: |
|
/* The following code tests whether appl_getinfo is available in the current system environment, and if positive calls the aforesaid function. It is suggested that instead of appl_getinfo, only appl_xgetinfo be used in your own programs. */ GLOBAL int16_t appl_xgetinfo ( int16_t type, int16_t *out1, int16_t *out2, int16_t *out3, int16_t *out4 ) { BOOLEAN has_agi = FALSE; has_agi = ((_GemParBlk.global[0] == 0x399 && (is_MagiC() >= 0x0200)) || (_GemParBlk.global[0] >= 0x400) || (appl_find ("?AGI") >= 0)); if (has_agi) return (appl_getinfo (type, out1, out2, out3, out4)); else return (0); } /* appl_xgetinfo */
The query 'is_MagiC' is a function that evaluates the MagiC cookie and returns the version number. This is necessary as MagiC 2 already knows the function appl_getinfo, but does not as yet permit interro gation with "?AGI".
See also: Applications GEM Style guidelines
Name: | »Application get information« - Inquire extended information
about available function calls and properties.
| ||||||||
Opcode: | 130
| ||||||||
Syntax: | int16_t appl_getinfo_str ( int16_t ap_gtype, int16_t *ap_gout1,
int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4 );
| ||||||||
Description: | The call appl_getinfo_str is an extended version of
appl_getinfo. Instead of the integer values, it returns character
strings.
ap_gtype determines the type of information that is to be inquired for. Details are as follows: 96: AES Version
Note: A problem with this function consists of establishing just when it may be called. Although it ought to be present as of AES version 4.0, MagiC 2.0 (and also MagiC 3.0) for example show the version 3.99. For this reason many programmers define the function appl_xgetinfo, in which a check is made whether appl_getinfo is present in the current system environment. | ||||||||
Return value: | A return value of 0 indicates an error; with a value of 1, no
error has arisen.
| ||||||||
Availability: | As of XaAES from 2004-12-18.
| ||||||||
Group: | Application library
| ||||||||
See also: | Binding appl_getinfo
|
C: | int16_t appl_getinfo_str ( int16_t ap_gtype, int16_t *ap_gout1,
int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4 );
| ||||||||||||||||||||||||||||||||||||
Binding: |
int16_t appl_getinfo_str(int16_t ap_gtype, int16_t *ap_gout1, int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4) { int_in[0] = ap_gtype; addr_in[0] = (int32_t)ap_out1; addr_in[1] = (int32_t)ap_out2; addr_in[2] = (int32_t)ap_out3; addr_in[3] = (int32_t)ap_out4; crys_if (130); return ( int_out[0] ); } | ||||||||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application get Cicon«
| ||||||||||||||||||||||||||||||||||||||||
Opcode: | 131
| ||||||||||||||||||||||||||||||||||||||||
Syntax: | int16_t appl_getcicon(int16_t type,char *name,int16_t size,
int_16_t *cicon_width,int16_t *cicon_height, CICON **cicon_data);
| ||||||||||||||||||||||||||||||||||||||||
Description: | The goal of this function is to provide cicon server (24 bit
true color for MyAES or 32 picture) This function provide only CICON
data with bitmap and mask and not a full object icon. Data provide by
this function should be relocated and copy, AES not keep in memory
CICON block provided that should be copy.
| ||||||||||||||||||||||||||||||||||||||||
Return value: | A return value of 0 indicates an error, with a value of 1 no
error has arisen.
| ||||||||||||||||||||||||||||||||||||||||
Availability: | Since MyAES 0.96 beta1
| ||||||||||||||||||||||||||||||||||||||||
Group: | Application library
| ||||||||||||||||||||||||||||||||||||||||
See also: | Binding
|
C: | int16_t appl_getcicon(int16_t type,char *name,int16_t size,
int_16_t *cicon_width,int16_t *cicon_height, CICON **cicon_data);
| |||||||||||||||||||||||||||||||||||||||
Binding: |
int16_t appl_getcicon (int16_t type,const char *name,int16_t size, int16_t *cicon_width,int16_t *cicon_height CICON **cicon_data) { int_in[0] = type; int_in[1] = size; addr_in[0] = name; addr_out[0] = (void *)cicon_data; crys_if (131); *cicon_width = int_out[1]; *cicon_height = int_out[2]; return ( int_out[0] ); } | |||||||||||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application initialization« - Registers the application
under AES.
|
Opcode: | 10
|
Syntax: | int16_t appl_init ( void );
int16_t appl_init ( X_BUF_V2 *xbuf ); |
Description: | The call appl_init registers the program with the AES, and
initializes the internal parameter passing fields. It should be the
first function called by any application that wants to use GEM calls.
As first prototyped, the function accepted no parameters; however all
'C' compilers use this call to set up internal information as well as
to update the application's global array.
The extra parameter to an X_BUF_V2 is an extension in the FreeGEM AES. If addr_in[0] is set to 1 and an initialized X_BUF_V2 structure is passed in, then on return its arch member will be 0 for DRI GEM or ViewMAX, and 16 or 32 for FreeGEM. Note: The version number of the AES can be inquired after this call via the global field (global[0]). To test whether a program has been started from the AUTO folder, the following procedure is suggested:
Although this procedure is not documented officially, it is used by the mouse accelerator MACCEL by Atari in this way. KAOS-GEM 1.4.2 returns 'KA' in int_in[0] and 'OS' in int_in[1]. |
Return value: | The function returns the ID of the application. In case of an
error the value -1 is returned.
|
Availability: | All AES versions.
|
Group: | Application library
|
See also: | Binding appl_find appl_search appl_exit
|
C: | int16_t appl_init ( void );
| |||||||||||||||||||||
Binding: |
EXTERN AESPB c; int16_t appl_init (void) { c.cb_pcontrol = control; c.cb_pglobal = global; c.cb_pintin = int_in; c.cb_pintout = int_out; c.cb_padrin = addr_in; c.cb_padrout = addr_out; control[4] = 0; crys_if (10); return (int_out[0]); } | |||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application options« - Set or get application options.
| ||||||||||||||||||||||||||
Opcode: | 137
| ||||||||||||||||||||||||||
Syntax: | int16_t appl_options(int16_t mode, int16_t aopts0, int16_t
aopts1, int16_t aopts2, int16_t aopt3, int16_t *out0, int16_t *out1,
int16_t *out2, int16_t *out3);
| ||||||||||||||||||||||||||
Description: | The purpose of the appl_options function is to let application
set/get options available to it, such as the extended objc_edit mode.
| ||||||||||||||||||||||||||
Return value: | Return 1 = OK or 0 = error.
| ||||||||||||||||||||||||||
Availability: | The presence of the function can be checked with appl_getinfo (opcode
98).
| ||||||||||||||||||||||||||
Group: | Application library
| ||||||||||||||||||||||||||
See also: | Binding
|
C: | int16_t appl_options(int16_t mode, int16_t aopts0, int16_t
aopts1, int16_t aopts2, int16_t aopt3, int16_t *out0, int16_t *out1,
int16_t *out2, int16_t *out3);
| ||||||||||||||||||||||||||||||||||||||||||||||||
Binding: |
int16_t appl_options(int16_t mode, int16_t aopts0, int16_t aopts1, int16_t aopts2, int16_t aopt3, int16_t *out0, int16_t *out1, int16_t *out2, int16_t *out3) { int_in[0] = mode; int_in[1] = aopts0; int_in[2] = aopts1; int_in[3] = aopts2; int_in[4] = aopts3; crys_if(137); *out0 = int_out[1]; *out1 = int_out[2]; *out2 = int_out[3]; *out3 = int_out[4]; return ( int_out[0] ); } | ||||||||||||||||||||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application read« - Receives a message from another
application.
| ||||||||||
Opcode: | 11
| ||||||||||
Syntax: | int16_t appl_read ( int16_t ap_rid, int16_t ap_rlength, void
*ap_rpbuff );
| ||||||||||
Description: | The call appl_read aids inter-process communication between
processes running under the AES. It will halt the running
application until a sufficient number of bytes is available from the
message pipe. The following apply:
The function waits if necessary until the demanded number of bytes is actually available. In MagiC and MultiTOS the function has been extended in such a way that it returns immediately with a suitable message if no messages are waiting at present (ap_rid: -1). Note: appl_read works destructively, i.e. after the readout the messages are removed from the message-pipe. This makes it necessary to evaluate the read message in the same way as after a evnt_multi call, say. The presence of the extended features can be inquired with appl_getinfo (opcode 6). | ||||||||||
Return value: | If a 0 is returned then an error has occurred, else a positive
number is returned.
| ||||||||||
Availability: | All AES versions.
| ||||||||||
Group: | Application library
| ||||||||||
See also: | Binding appl_init appl_write evnt_mesag evnt_multi
|
C: | int16_t appl_read ( int16_t ap_rid, int16_t ap_rlength, void
*ap_rpbuff );
| ||||||||||||||||||||||||||||||
Binding: |
int16_t appl_read (int16_t ap_rid, int16_t ap_rlength, void *ap_rpbuff) { int_in[0] = ap_rid; int_in[1] = ap_rlength; addr_in[0] = ap_rpbuff; return ( crys_if(11) ); } | ||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application search« - Search for applications in system.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Opcode: | 18
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Syntax: | int16_t appl_search ( int16_t ap_smode, int8_t *ap_sname,
int16_t *ap_stype, int16_t *ap_sid );
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description: | Depending on the parameters, the function appl_search searches
for filenames of various applications running in the system. The
following apply:
It is possible to obtain the long name of the application if one knows its application ID. The long name is the one that was passed by the application at a menu_register call and is also displayed in the menu bar. If one knows the application ID apid of an application, then its long name will be transferred to the buffer longname by a following call of appl_search: appl_search(-apid, &longname[0], &type, &pid) type here is the bit-mask of the application type also returned normally, pid the MiNT-pid (not: apid) of the application. So the first parameter to be passed is the negative value of the application ID to obtain the long name of this application. This name can be up to 32 characters long (31 characters plus terminating NULL-byte), so one should reserve a correspondingly sized buffer for longname. APP_TASKINFO automatically returns the long name of an application and is available only under XaAES. With this routine one cannot find threads. Geneva has three extra modes:
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Return value: | The function returns the value 1 if no error has arisen, or the
value 0 if no further applications are present.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Availability: | The presence of this function can be ascertained with appl_getinfo
(opcode 4). Ascertaining of the long name and task information can be
recognized by appl_getinfo (opcode 64).
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Group: | Application library
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also: | Binding appl_find Broadcasting
|
C: | int16_t appl_search ( int16_t ap_smode, int8_t *ap_sname,
int16_t *ap_stype, int16_t *ap_sid );
| |||||||||||||||||||||||||||||||||
Binding: |
int16_t appl_search (int16_t ap_smode, int8_t *ap_sname, int16_t *ap_stype, int16_t *ap_sid) { int_in[0] = ap_smode; addr_in[0] = ap_sname; crys_if(18); *ap_stype = int_out[1]; *ap_sid = int_out[2]; return ( int_out[0] ); } | |||||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application play« - Play back AES events.
| ||||||||||
Opcode: | 14
| ||||||||||
Syntax: | int16_t appl_tplay ( APPLRECORD *ap_tpmem, int16_t ap_tpnum,
int16_t ap_tpscale );
| ||||||||||
Description: | The call appl_tplay offers the possibility to play back user
actions recorded with appl_trecord. The following apply:
| ||||||||||
Return value: | The function always returns the value 1.
| ||||||||||
Availability: | All AES versions.
| ||||||||||
Group: | Application library
| ||||||||||
See also: | Binding appl_trecord
|
C: | int16_t appl_tplay ( APPLRECORD *ap_tpmem, int16_t ap_tpnum,
int16_t ap_tpscale );
| ||||||||||||||||||||||||||||||
Binding: |
int16_t appl_tplay (APPLRECORD *ap_tpmem, int16_t ap_tpnum, int16_t ap_tpscale) { int_in[0] = ap_tpnum; int_in[1] = ap_tpscale; addr_in[0] = ap_tpmem; return ( crys_if(14) ); } | ||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application record« - Record AES events.
| ||||||||
Opcode: | 15
| ||||||||
Syntax: | int16_t appl_trecord ( APPLRECORD *ap_tbuffer, int16_t
ap_trcount );
| ||||||||
Description: | The call appl_trecord serves for recording user actions to be
able to play them back again later. The following apply:
| ||||||||
Return value: | The number of events actually recorded.
| ||||||||
Availability: | All AES versions. The function is only implemented properly
as of GEM Version 1.2.
| ||||||||
Group: | Application library
| ||||||||
See also: | Binding appl_tplay
|
C: | int16_t appl_trecord ( APPLRECORD *ap_tbuffer, int16_t
ap_trcount );
| |||||||||||||||||||||||||||
Binding: |
int16_t appl_trecord (APPLRECORD *ap_tbuffer, int16_t ap_trcount) { int_in[0] = ap_trcount; addr_in[0] = ap_tbuffer; return ( crys_if(15) ); } | |||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application write« - Send AES message to another
application.
| ||||||||||
Opcode: | 12
| ||||||||||
Syntax: | int16_t appl_write ( int16_t ap_wid, int16_t ap_wlength, void
*ap_wpbuff );
| ||||||||||
Description: | The call appl_write writes a number of bytes to a valid message
pipe. The following apply:
Notes: With this function an application has the possibility to send itself and receive a redraw message. As of MagiC Version 4.0 the following applies: if the parameter ap_wid has the value -2, then ap_wpbuff points to a XAESMSG structure. As of AES version 1.40, desk accessories may send MN_SELECTED messages to the desktop to trigger desktop functions. As of AES version 4.00 one can send shel_write(7...) to 'broadcast' a message to all running processes apart from the AES itself, the desktop and one's own application. | ||||||||||
Return value: | If a zero is returned then an error has arisen, else a positive
number is returned.
| ||||||||||
Availability: | All AES versions.
| ||||||||||
Group: | Application library
| ||||||||||
See also: | Binding appl_init appl_read appl_find Messages
|
C: | int16_t appl_write ( int16_t ap_wid, int16_t ap_wlength, void
*ap_wpbuff );
| ||||||||||||||||||||||||||||||
Binding: |
int16_t appl_write (int16_t ap_wid, int16_t ap_wlength, void *ap_wpbuff) { int_in[0] = ap_wid; int_in[1] = ap_wlength; addr_in[0] = ap_wpbuff; return ( crys_if(12) ); } | ||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Extended application bit-vector get« - Get the available
logical drives for the file-selector.
| ||||||||
Opcode: | 18
| ||||||||
Syntax: | int16_t appl_xbvget ( uint32_t *bvdisk, uint32_t *bvhard );
| ||||||||
Description: | The call appl_xbvget gets GEM the list of logical drives
that are present; it's needed, amongst others, for the file-selector,
and this extended version allows drives beyond P:. The following
apply:
| ||||||||
Return value: | The return value is always 1.
| ||||||||
Availability: | GEM/4, GEM/5 and FreeGEM.
The function to do this is present on FreeGEM if the ABLE_XBVSET bit is set in the "abilities" bitmap. | ||||||||
Group: | Application library
| ||||||||
See also: | Binding appl_bvset appl_xbvset
|
C: | int16_t appl_xbvget ( uint32_t *bvdisk, uint32_t *bvhard );
| ||||||||||||||||||||||||||||||
Binding: |
int16_t appl_xbvget (uint32_t *bvdisk, uint32_t *bvhard) { int_in[0] = 0; crys_if(18); *bvdisk = int_out[1..2]; *bvhard = int_out[3..4]; return ( int_out[0] ); } | ||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Extended application bit-vector set« - Set the available
logical drives for the file-selector.
| ||||||||
Opcode: | 18
| ||||||||
Syntax: | int16_t appl_xbvset ( uint32_t bvdisk, uint32_t bvhard );
| ||||||||
Description: | The call appl_xbvset informs GEM about the logical drives
that are present; it's needed, amongst others, for the file-selector,
and this extended version allows drives beyond P:. The following
apply:
| ||||||||
Return value: | Return value of the function is unknown at present.
| ||||||||
Availability: | GEM/4, GEM/5 and FreeGEM.
The function to do this is present on FreeGEM if the ABLE_XBVSET bit is set in the "abilities" bitmap. | ||||||||
Group: | Application library
| ||||||||
See also: | Binding appl_bvset appl_xbvget
|
C: | int16_t appl_xbvset ( uint32_t bvdisk, uint32_t bvhard );
| ||||||||||||||||||||||||||||||
Binding: |
int16_t appl_xbvset (uint32_t bvdisk, uint32_t bvhard) { int_in[0] = 1; addr_in[0] = bvdisk; addr_in[1] = bvhard; return ( crys_if(18) ); } | ||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application yield« - Force AES process-switch.
|
Opcode: | 17
|
Syntax: | int16_t appl_yield ( void );
|
Description: | With the aid of the function appl_yield one may force an AES
process change.
Note: This may be achieved in a similar way with a short call of the function evnt_timer. |
Return value: | Return value of the function is unknown at present.
|
Availability: | The function is available only under PC-GEM, Geneva, as well
as MagiC (in each case) as of Version 2.0, N.AES and XaAES.
|
Group: | Application library
|
See also: | Binding evnt_timer _appl_yield
|
C: | int16_t appl_yield ( void );
| |||||||||||||||||||||
Binding: |
int16_t appl_yield (void) { return ( crys_if(17) ); } | |||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application yield« - Force AES process-switch.
|
Syntax: | void _appl_yield ( void );
|
Description: | With the aid of the function _appl_yield one may force an
AES process change.
Note: This may be achieved in a similar way with a short call of the function evnt_timer or appl_yield. |
Return value: | The function does not return a result.
|
Availability: | The function is available TOS as of version 1.0, KAOS and MagiC
as of version 1.0.
|
Group: | Application library
|
See also: | Binding evnt_timer appl_yield
|
C: | void _appl_yield ( void );
|
Binding: |
_appl_yield: move.l a2,-(sp) move.w #201,d0 ; _appl_yield() trap #2 movea.l (sp)+,a2 rts |
Name: | »Control execution flags« - Get or set program flags
| ||||||||||||
Opcode: | 28928
| ||||||||||||
Syntax: | int16_t x_appl_flags( int16_t getset, int16_t index, APPFLAGS
*flags );
| ||||||||||||
Description: | The call x_appl_flags controls the execution flags that are
used when determining how an application gets run. It works in two
modes, globally and for a particular application.
Note: Changing the multitask attribute of an application in this manner will have no effect, since this can only be changed before the application is launched. Descriptions of each of the available flags can be found in the section of the manual describing the Task Manager's "Flags" dialog. | ||||||||||||
Return value: | 0 = Out of memory (mode 1)
Flags not found (all modes) | ||||||||||||
Availability: | The function is available only under Geneva.
| ||||||||||||
Group: | Application library
| ||||||||||||
See also: | Binding
|
C: | int16_t x_appl_flags( int16_t getset, int16_t index, APPFLAGS
*flags );
| ||||||||||||||||||||||||||||||
Binding: |
int16_t x_appl_flags( int16_t getset, int16_t index, APPFLAGS *flags ) { int_in[0] = getset; int_in[1] = index; addr_in[0] = flags; return ( crys_if(28928) ); } | ||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Change font and window borders« - (Geneva)
|
Opcode: | 28929
|
Syntax: | int16_t x_appl_font( int16_t getset, int16_t zero, XFONTINFO
*info );
|
Description: | The call x_appl_font changes the characteristics of the large
font used by Geneva, and also the window widget borders.
This function gives one control over what font is used to display characters in the menu bar, dialogs, etc. When Geneva first runs, it checks to see if the font ID saved in GENEVA.CNF is anything other than 1 (for a system font). If so, and GDOS is present, it loads all available fonts, and uses the correct font. If the particular font is not available, it reverts to the system font. Regardless of the font's availability, the closest point size to the one specified is used. The window widgets will have a width which is equal to the width of one character in the font, plus the value specified by the user. A similar calculation is used for the widget height. When any element in the structure pointed to by info is -2, the default value for that element (as though there had been no GENEVA.CNF file when Geneva loaded) is used; in the case of a getset value of zero (get), this default value is returned in the info structure. When getset is 1 and any element is -1, that element will cause Geneva to ignore the setting, leaving the old value in tact. Setting these values will have no immediate effect. The GENEVA.CNF file must be re-saved, and Geneva must be restarted before a change can be noticed. This example: XFONTINFO info = { -2, -2, -2, -2 }; x_appl_font( 0, 0, &info ); /* Get default values */ x_appl_font( 1, 0, &info ); /* Set to these values */ Is the same as: XFONTINFO info = { -2, -2, -2, -2 }; x_appl_font( 1, 0, &info ); /* Set to default values */ Set it to something else: XFONTINFO info = { 1, /* Select the system font */ 10, /* 10 point (8 x 16) */ 5, /* Widget width = 8 + 5 pixels */ 4 }; /* Widget height = 16 + 4 pixels */ x_appl_font( 1, 0, &info ); Cautions:
The parameter zero is reserved for future expansion. Must always be 0. |
Return value: | Return value of the function is unknown at present.
|
Availability: | The function is available only under Geneva.
|
Group: | Application library
|
See also: | Binding
|
C: | int16_t x_appl_font( int16_t getset, int16_t zero, XFONTINFO
*info );
| ||||||||||||||||||||||||||||||
Binding: |
int16_t x_appl_font( int16_t getset, int16_t zero, XFONTINFO *info ); { int_in[0] = getset; int_in[1] = zero; addr_in[0] = info; return ( crys_if(28929) ); } | ||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Put application to sleep« - or wake it up
| ||||||||
Opcode: | 28930
| ||||||||
Syntax: | int16_t x_appl_sleep( int16_t id, int16_t sleep );
| ||||||||
Description: | The call x_appl_sleep searches for the application whose ID
(found by appl_find or appl_search) is id and either puts it
to sleep or wakes it up. While an application is asleep, its windows
are automatically closed, and it does not receive any events.
The old state of wakefulness is always returned, unless an error occurs. There are several situations where an error code will be returned:
If an application puts itself to sleep, it will not be able to wake itself; this must be done by another application or by the user from the Desk menu. If an application which is asleep is about to be terminated for any reason, it is first awakened, so that it can receive the AP_TERM message. | ||||||||
Return value: | -1: Application not found, or the state could not be changed
| ||||||||
Availability: | The function is available only under Geneva.
| ||||||||
Group: | Application library
| ||||||||
See also: | Binding
|
C: | int16_t x_appl_sleep( int16_t id, int16_t sleep );
| |||||||||||||||||||||||||||
Binding: |
int16_t x_appl_sleep( int16_t id, int16_t sleep ); { int_in[0] = id; int_in[1] = sleep; return ( crys_if(28930) ); } | |||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Terminate application« - Terminate an application and remove
it from memory (Geneva).
|
Opcode: | 28931
|
Syntax: | int16_t x_appl_term( int16_t apid, int16_t retrn, int16_t
set_me );
|
Description: | The call x_appl_term will cause an application to terminate. It
is similar to shel_write mode 4, except that it allows for just one
application to be terminated.
If the application to be terminated does not recognize the AP_TERM message, the user will first be presented with an alert box confirming that he wants to terminate. |
Return value: | 0 = The application was not found
|
Availability: | The function is available only under Geneva.
|
Group: | Application library
|
See also: | Binding
|
C: | int16_t x_appl_term( int16_t apid, int16_t retrn, int16_t
set_me );
| ||||||||||||||||||||||||||||||
Binding: |
int16_t x_appl_term( int16_t apid, int16_t retrn, int16_t set_me ) { int_in[0] = apid; int_in[1] = retrn; int_in[2] = set_me; return ( crys_if(28931) ); } | ||||||||||||||||||||||||||||||
GEM-Arrays: |
|
Name: | »Application get information« - Inquire information about
available function calls and properties of the AES.
|
Opcode: | 1020
|
Syntax: | int16_t xappl_getinfo ( int16_t ap_gtype, int16_t *ap_gout1,
int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4 );
|
Description: | This is the GEM/3 equivalent of appl_getinfo() for the Atari.
It has a different name because internally it uses a different opcode
(130, which is used in the Atari AES, is already assigned to
xgrf_stepcalc() in GEM/3)
|