HomeAESAES fundamentalsFile-selector library

8.3 Application library

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

8.3.1 appl_bvset

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:

Parameter Meaning
bvdisk Bit-vector of the floppy disk drives present (bit 15 = Drive A: etc).
bvhard Bit-vector of the hard drives present (bit 15 = Drive A: etc).


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

8.3.1.1 Bindings for appl_bvset

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:

Address Element Contents
control control[0] 16 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # 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] bvdisk
int_in+2 int_in[1] bvhard
int_out int_out[0] Return-Wert

0# Source: APC_TOPNEXT, APC_KILL and APC_SYSTEM from the sourcecode.

8.3.2 appl_control

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.
Parameter Meaning
ap_cid The AES ID (apid) of the application you want to control.
ap_cwhat The type of control:
0 to 9
Reserved for N.AES
APC_TOPNEXT (0)
OAESis internal mode
APC_KILL (1)
OAESis internal mode
APC_SYSTEM (2)
XaAES internal mode
APC_HIDE (10)
Hide (fade out) application;
if ap_cid is -1, the active application will be hidden
APC_SHOW (11) Show (fade in) application;
if ap_cid is -1, all hidden applications are shown
APC_TOP (12)
Bring application to front (the application becomes the active one)
APC_HIDENOT (13)
Hide all applications except the one referred to by ap_cid (which becomes the active application)

If ap_cid is -1, all applications except the active one will be hidden
APC_INFO (14)
Inquire the application parameters of application ap_cid; if -1 is passed for ap_cid, then the parameters of the current application will be returned

For ap_cout a pointer to an integer is to be passed

N.AEShere deposits the application parameters in the form of a bitmask:
APCI_HIDDEN (1) Bit 0 is set if the application is faded out
APCI_HASMBAR (2) Bit 1 is set if the application posseses a menu bar
APCI_HASDESK (4) Bit 2 is set if the application possesses its own desktop
APC_MENU (15)
Returns address of the menu tree that the application ap_cid last initialized. For this a pointer to an OBJECT pointer is to be passed for ap_cout; the latter will be filled by shel_write with the searched for menu tree address.

If -1 is passed for ap_cid, then the menu tree address of the current application will be returned. If the value 0 is passed for ap_cid then the address of the system menu managed internally by shel_write will be returned. This is the menu box that pops open when one selects the left-most menu title and which contains the list of all applications and desk accessories initialized by shel_write.

If the application inquired for has not initialized a menu bar, or no application with the identification ap_cid exists, then a NULL pointer will be written to ap_cout

The return value of appl_control, mode APC_MENU is always the value 1

Note: If one uses this mode, one should be quite certain what one is doing! Altering the returned menu tree can lead to undefined system states. With active MiNT memory protection even a read access to the menu tree can lead to a termination of the application!
APC_WIDGETS (16)
Inquires or sets the 'default' positions of the window objects. ap_cout is a pointer to a MINWINOBJ(12)-sized (int16_t) buffer, which must be filled completely with -1 for inquiring the object order. The last WORD must be a 0. If an error-message is returned, then the buffer is too small for all objects and should be enlarged. In the buffer lie first of all the objects of the title-bar from left to right, followed by the objects of the vertical slider from top to bottom and then the objects of the horizontal slider from left to right. The list is terminated with a NULL-word. For setting the positions, the first objects have to be of the type topwidgets (from left to right), followed by the objects of the type rightwidgets (from top to bottom) and then the objects of the type bottomwidgets (from left to right). If the objects are duplicated or set incorrectly then an error will be reported.
APC_APP_CONFIG (17)
With this option you are able to inform to AES how you want your application should be considered.
ap_cout is a pointer to a string. At this time value supported are:
  • "app_debug=true" or "app_debug" : put the application in debug mode
  • "app_debug=false" : stop debug mode
  • "app_topmost=true" or "app_topmost" : Application windows will be always on top (compare to other classical application) but without focus (can be usefull for tesk bar for exemple)
  • "app_topmost=false" : remove previous option
  • "app_system" : application is a system application (used in appl_search for type APP_SYSTEM)
  • "app_texticon=opaque" : background icon text is opaque
  • "app_texticon=transparent" : background icon text is transparent
  • "app_signal_mesag=true": Request receive Unix Signal when even message is waiting see APC_INFORM_MESAG as it do exactly the same
  • "app_signal_mesag=false": Request stop receive Unix Signal when even message is waiting
APC_INFORM_MESAG (18)
Request to AES to inform the application when there is a AES message waiting with a Unix Signal.
ap_cout : not used.
When the application receive a message the AES send the Signal SIGUSR2 (30) to the application, to manage the message should use classical event_mesag or event_multi functions. Calling one time this call request to AES to send Signal, calling a second time remove this order.
ap_cout Is filled by the AES dependent on ap_cwhat and only has a meaning for APC_INFO, APC_MENU, APC_WIDGETS and APC_APP_CONFIG. In other cases this parameter is ignored and passing of a NULL-pointer is then possible.


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

8.3.2.1 Bindings for appl_control

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:

Address Element Contents
control control[0] 129 # Function opcode
control+2 control[1] 2 # 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
int_in int_in[0] ap_cid
int_in+2 int_in[1] ap_cwhat
addr_in addr_in[0] ap_cout
int_out int_out[0] ap_creturn

8.3.3 appl_exit

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

8.3.3.1 Bindings for appl_exit

C: int16_t appl_exit ( void );
Binding:
int16_t appl_exit (void)
{
   return ( crys_if(19) );
}
GEM-Arrays:

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

8.3.4 appl_find

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:
High-Word Meaning
of ap_fpname  
   
-1 The function expects in the low-word the MiNT ID of an application and after the call returns the AES ID of this application.
-2 The function expects in the low-word the AES ID of an application and after the call returns the MiNT ID of this application.
-3 The AES ID of the topped application is returned. The low-word plays no effect here and can be 0. This is only available under MyAES (since 0.94a), N.AES and XaAE.


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

8.3.4.1 Bindings for appl_find

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:

Address Element Contents
control control[0] 13 # 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] ap_fpname
int_out int_out[0] Return value

8.3.5 appl_getinfo

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
ap_gout1: Font height (in points)
ap_gout2: Font ID
ap_gout3: Font type (0=system font, 1=outline font)


AES_SMALLFONT (1): Get AES small font information
ap_gout1: Font height (in points)
ap_gout2: Font ID
ap_gout3: Font type (0=system font, 1=outline font)


AES_SYSTEM (2): Colours
ap_gout1: VDI device number (device ID)
ap_gout2: Number of colours supported by AES object library
ap_gout3: Colour icons present (1) or not (0)
ap_gout4:
Bit 0: New resource file format (AES4) is supported
Bit 1: Indicates that Interface resource file format (RSHDR:rsh_vrsn = 3) is supported


AES_LANGUAGE (3): AES language
ap_gout1:
0 - English
1 - German
2 - French
3 - Reserved
4 - Spanish
5 - Italian
6 - Swedish


AES_PROCESS (4): General AES environment info 1
ap_gout1: Preemptive multitasking (1) or not (0)
ap_gout2: appl_find converts MiNT/AES ID's (1) or not (0)
ap_gout3: appl_search implemented (1) or not (0)
ap_gout4: rsrc_rcfix implemented (1) or not (0)


AES_PCGEM (5): General AES environment info 2
ap_gout1: objc_xfind implemented (1) or not (0)
ap_gout2: Reserved, always 0
ap_gout3: menu_click implemented (1) or not (0)
ap_gout4: shel_rdef/shel_wdef implemented (1)


AES_INQUIRE (6): General AES environment info 3
ap_gout1: appl_read -1 is valid param. (1) or not (0)
ap_gout2: shel_get -1 is valid param. (1) or not (0)
ap_gout3: menu_bar -1 is valid param. (1) or not (0)
ap_gout4: menu_bar 100 (MagiC) is valid param. (1) or not (0)


7: Reserved for MagiC and other OS extensions; MultiTOS sets all return values always to 0. In MagiC:
ap_gout1:
Bit 0: wdlg_xx functions implemented (1)
Bit 1: lbox_xx functions implemented (1)
Bit 2: fnts_xx functions implemented (1)
Bit 3: fslx_xx functions implemented (1)
Bit 4: pdlg_xx functions implemented (1) or not (0) in each case
ap_gout2: Reserved
ap_gout3: Reserved
ag_gout4: Reserved


AES_MOUSE (8): Mouse support
ap_gout1: graf_mouse modes (258-260) supported (1) or not (0)
ap_gout2: Mouse form managed by the AES for each application (1) or not (0)
ap_gout3: Warning: Double assignment
- Mouse-wheels support (XaAES) - If a driver is installed which uses TORG 105, then this value is a bit-vector of the currently available mouse-wheels


AES_MENU (9): Menu support
ap_gout1: MultiTOS submenus supported (1) or not (0)
ap_gout2: MultiTOS popups supported (1) or not (0)
ap_gout3: MultiTOS scroll menus supported (1) or not (0)
ap_gout4: Extended MN_SELECTED message (object tree info in msg[5..7]) supported (1) or not (0)


AES_SHELL (10): shel_write
ap_gout1: Modes supported
Bit 0..7: Indicate highest legal value for (sh_wdoex & 0x00ff)
Bit 8..15: Indicate which bits in (sh_wdoex & 0xFF00) are supported as in MultiTOS
ap_gout2:
1: shel_write (0) makes previous shel_write calls invalid (i.e. the desktop becomes follower program) (TOS 1.04 and MagiC)
0: Launches program (MultiTOS)
ap_gout3:
1: shel_write (1) launches a program when the running one exits (TOS 1.04 and MagiC)
0: Launches program immediately (MultiTOS)
ap_gout4: ARGV style parameter passing via sh_wiscr supported (1) or not (0)


AES_WINDOW (11): window support
ap_gout1: Extended WF_ functions in wind_get/wind_set (0=not available, 1=available)
Bit 0: WF_TOP returns window below current one
Bit 1: wind_get(WF_NEWDESK) supported
Bit 2: wind_get/set(WF_COLOR)
Bit 3: wind_get/set(WF_DCOLOR)
Bit 4: wind_get(WF_OWNER)
Bit 5: wind_get/set(WF_BEVENT)
Bit 6: WF_BOTTOM
Bit 7: WF_ICONIFY
Bit 8: WF_UNICONIFY
Bit 9: WF_WHEEL
Bit 10: wind_get(WF_FIRSTAREAXYWH)
Bit 11: wind_get/set(WF_OPTS)
Bit 12: wind_get/set(WF_MENU)
Bit 13: wind_get/set(WF_WORKXYWH)
Bit 14: Supports wind_get(WF_CALCW2F/WF_CALCF2W) and wind_set(WO0_WCOWORK) modes
Bit 15: wind_set and wind_get can be called with the special handle -2. Then, wind_set and wind_get invoked with this special handle report if the mode is supported by the AES.
ap_gout2:
Bit 0: wind_get/set (WF_WIDGETS), N.AES
Bit 1..15: Reserved
ap_gout3: New widgets support: (0=supported, 1=not supported)
Bit 0: Iconifier
Bit 1: Backdrop button (MagiC)
Bit 2: [Shift]-click for backdrop
Bit 3: 'Hot' close-box (GEM/3 and MagiC)
Bit 4..15: Reserved, 0
ap_gout4: wind_update 'Check and set' implemented (1) or not (0)


AES_MESSAGE (12): Messages sent to applications
ap_gout1: Bit field of extra messages supported (0=no, 1=yes)
Bit 0: WM_NEWTOP is meaningful
Bit 1: WM_UNTOPPED is sent
Bit 2: WM_ONTOP is sent
Bit 3: AP_TERM is sent
Bit 4: MultiTOS Shutdown and Resolution change messages supported
Bit 5: CH_EXIT is sent
Bit 6: WM_BOTTOMED is sent
Bit 7: WM_ICONIFY is sent
Bit 8: WM_UNICONIFY is sent
Bit 9: WM_ALLICONIFY is sent
Bit 10: WM_REPOSED is sent
ap_gout2: Reserved, all 0
ap_gout3: WM_ICONIFY returns coordinates (1) or not (0)


AES_OBJECT (13): Object information
ap_gout1: 3D-objects via ob_flags implemented (1) or not (0)
ap_gout2: 0 - objc_sysvar not present
1 - MultiTOS 1.01 objc_sysvar present
2 - Extended objc_sysvar present
ap_gout3: Speedo and GDOS fonts permitted in TEDINFO (1) or not (0)
ap_gout4: Reserved for MagiC and other extensions; MultiTOS always sets all return values to 0. In MagiC and N.AES the following apply:
Bit 0: G_SWBUTTON supported
Bit 1: G_POPUP supported
Bit 2: WHITEBAK steuert Unterstriche und Buttons
Bit 3: G_SHORTCUT supported


AES_FORM (14): Forms (MagiC form_xdo and form_xdial)
ap_gout1: MagiC Flydials present (1) or not (0)
ap_gout2: MagiC keyboard tables present (1) or not (0)
ap_gout3: Last cursor position returned from obj_edit (1) or not (0)
ap_gout4: Reserved, 0


AES_EXTENDED (64): Extended functions
ap_gout1: shel_write(10) with AP_AESTERM possible (1) or not (0)
ap_gout2: Extended shel_write SHW_SHUTDOWN(4)/SHW_RESCHANGE(5) present (1) or not (0)
ap_gout3: appl_search:
Bit 0: Long names present
Bit 1: Mode APP_TASKINFO available
ap_gout4: form_error with all GEMDOS error-codes present (1) or not (0)


AES_NAES (65): Additional N.AES functions
ap_gout1: appl_control present (1) or not (0)
ap_gout2: Highest opcode for appl_control
ap_gout3: shel_help present (1) or not (0)
ap_gout4: wind_draw present (1) or not (0)


96: AES Version
There is an extended mode since XaAES from 2004-12-18.
ap_gout1: Major version number (decimal)
ap_gout2: Minor version number (decimal)
ap_gout3: Development Status (Beta, alpha, etc.)
This is a 16-bit integer where bits 0-7 (the low byte) is a value indicating the development status of the AES, see below (AES_DEVSTATUS_xxx) for meaning of different values. Bits 8-15 are flags, see below (AES_FDEVSTATUS_xxx) for current definitions.

AES_DEVSTATUS_ALPHA   0
AES_DEVSTATUS_BETA    1
AES_DEVSTATUS_RELEASE 2

AES_FDEVSTATUS_STABLE 0x100
ap_gout4: Target platform (m68k, etc.)
This is a value indicating which platform the AES was built for. See below (AES_ARCH_xxx) for meaning of different values.

Label Value Target platfrom
AES_ARCH_M68K 0 MC-68000
AES_ARCH_M68000 0 MC-68000
AES_ARCH_M68010 1 MC-68010
AES_ARCH_M68020 2 MC-68020
AES_ARCH_M68030 3 MC-68030
AES_ARCH_M68040 4 MC-68040
AES_ARCH_M68060 5 MC-68060
AES_ARCH_M6802060 6 MC-68020-060
AES_ARCH_COLDFILRE 7 Coldfire


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
ap_gout1: Available window options 0 - see wind_set/get(WF_OPTS, wopt0)
ap_gout2: Available window options 1 - see wind_set/get(WF_OPTS, wopt1)
ap_gout3: Available window options 2 - see wind_set/get(WF_OPTS, wopt2)
ap_gout4: Reserved - always cleared


98: Available extended AES functions
Since XaAES 2005-12-08
ap_gout1:
Bit 0: If set, the following MagiC 5.10-introduced functions exist; exists;
objc_wdraw
objc_wchange
objc_wedit
graf_wwatchbox
form_wbutton
form_wkeybd
Bit 1: If set, appl_options exists
Bit 2..15: Not yet defined, always reads 0
ap_gout2: Not yet defined, all bits reads 0
ap_gout3: Not yet defined, all bits reads 0
ap_gout4: Not yet defined, all bits reads 0


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
ap_gout1:
Bit 0: If set, extended slider management is available.
Bit 1: If set, extended objc_edit cursor management is present; see more info about this below
Bit 2..15: Not yet defined, always reads 0
ap_gout2: Not yet defined, all bits read 0
ap_gout3: Not yet defined, all bits read 0
ap_gout4: Not yet defined, all bits read 0


AES_WINX (22360): Information about extensions in WINX
This information type exists since WINX 2.3
ap_gout1: Bit-vector for WF_ functions in wind_get/wind_set:
Bit 0: WF_WINX
Bit 1: WF_WINXCFG
Bit 2: WF_DDELAY
Bit 3: WF_SHADE
Bit 4: WF_STACK
Bit 5: WF_TOPALL
Bit 6: WF_BOTTOMALL
Bit 7: WF_KIND
ap_gout2: Bit-vector for AES messages:
Bit 0: Extended WM_ARROWED
Bit 1: WM_SHADED message is sent
Bit 2: WM_UNSHADED message is sent
ap_gout3: Bit-vector for extensions of AES functions
Bit 0: wind_calc permits WC_WIN modes
ap_gout4: Bit-vector for general information about the AES
Bit 0: DPAT writing desk background is suported directly by the AES


22528: XaAES
No longer supported as of 2004-12-18. Look to ap_gtype = 96
ap_gout1: Major version number
ap_gout2: Minor version number
ap_gout3: Target platform this XaAES was compiled for
ap_gout4: Status (beta, alpha, etc.)


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: Available as of AES version 4.00.
Group: Application library
See also: Binding

8.3.5.1 Bindings for appl_getinfo

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:

Address Element Contents
control control[0] 130 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 5 # 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] ap_gtype
int_out int_out[0] Return value
int_out+2 int_out[1] ap_gout1
int_out+4 int_out[2] ap_gout2
int_out+6 int_out[3] ap_gout3
int_out+8 int_out[4] ap_gout4

8.3.5.2 appl_xgetinfo

/* 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

8.3.6 appl_getinfo_str

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
ap_gout1: This is a character string with a fixed lenght of 8 bytes, into which the AES will write its unique AES ID. The AES ID is a left-aligned, space padded string, and can be considered to be the current AES's short name. For XaAES this string is filled with "XaAES". This string is not NULL-terminated.
ap_gout2: This is a character buffer that the application must ensure can take up to 256 (255 + '0' termination) characters. The AES fills its long name description into this buffer. Lines in here are delimitted using CR (ASCII 13). For XaAES, this buffer contains the following after the call:
"XaAES Ain't the AES, a free MultiTasking AES for FreeMiNT"
ap_gout3: This is a character buffer that the application must ensure can take up to 256 (255 + '0' termination) characters. The AES fills this buffer with the following information where each element is delimitted by the "|" (ASCII 0x7c) character. The string is constructed as follows:

"asci version|development status| architecture target| build date & time| compiler used",0

Example string returned might be:
"0.992|Alpha|m68k|Dec 17 2004 22:58:52|gcc 2.95.3",0
ap_gout4: Reserved, set to NULL.


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

8.3.6.1 Bindings for appl_getinfo_str

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:

Address Element Contents
control control[0] 130 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 4 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] ap_gtype
addr_in addr_in[0] ap_gout1
addr_in+4 addr_in[1] ap_gout2
addr_in+8 addr_in[2] ap_gout3
addr_in+12 addr_in[3] ap_gout4
int_out int_out[0] Return value

8.3.7 appl_getcicon

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.
Parameter Meaning
   
type type&0xFF : kind of icon type:
0 : Application icon
1 : File extension icon
2 : Reserved
3 : Load PNG file as icon from specific path
4 : Other icon (any other specific icon)



If type&0x100 = 0 cicon_data return a CICON block as need by AES for display color icon else cicon_data return a simple bitmap block in ARBG format with 8 bit transparency (this format is not recognize by AES)
name name of the cicon to load, some exemple:
with type&0xFF:
0 : name = "purec"
1 : name = "html"
3 : name = "C:\myprog\mypng\pngname.png"
4 : name = "computer"
size Size of the cicon to load, there is 3 different case:
size > 0 is the size of the icon requested and should be a multiple of 16
size = 0 the default cicon size is requested and is set by aes configuration
size = -1 the return cicon can be of any size and can change from a cicon to another
cicon_width cicon width return
cicon_height cicon height return
cicon_data Return block of type CICON + mask + icon bitmap if type&0x100 = 0 else a bitmap 32 bit with alpha chanel in the format ARGB 8 bits per chanel.

Relocation of cicon_data, cicon_data provide CICON block + mask + bitmap


num_planes : number of planes

*col_data, *col_mask, *sel_data, *sel_mask: provide relative position from the start of cicon_data and should be relocated


As the block can be free by the AES you should copy the block for your need, the size of the block to copy is:
number_of_block = 0
if(cicon_data->col_data) number_of_block++;
if(cicon_data->col_mask) number_of_block++;
if(cicon_data->sel_data) number_of_block++;
if(cicon_data->sel_mask) number_of_block++;

size = sizeof(CICON) + (cicon_data->num_planes * cicon_width * cicon_height * number_of_block)/8 + cicon_width*cicon_height;

CICON *newcicon;
newcicon = malloc(size);
memcpy(newcicon,cicon_data);
if(cicon_data->col_data) newcicon->col_data += newcicon;
if(cicon_data->col_mask) newcicon->col_mask += newcicon;
if(cicon_data->sel_data) newcicon->sel_data += newcicon;
if(cicon_data->sel_mask) newcicon->sel_mask += newcicon;



In the case of 32 bits bitmap size of the bloc = cicon_width * cicon_height * 4
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

8.3.7.1 Bindings for appl_getcicon

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:

Address Element Contents
control control[0] 131 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 3 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 1 # Entry in addr_out
int_in int_in[0] type
int_in+2 int_in[1] size
addr_in addr_in[0] name
int_out int_out[0] Return value
int_out+2 int_out[1] cicon_width
int_out+4 int_out[2] cicon_height
addr_out addr_out[0] cicon_data

8.3.8 appl_init

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:
  • Write the value 0 in global[0]
  • Call function appl_init
  • Inspect global field (global[0]): If there is still a zero there, then the AES is not yet ready for operation and the program was started from the AUTO folder.


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

8.3.8.1 Bindings for appl_init

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:

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

8.3.9 appl_options

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.
Parameter Meaning
   
mode Selects the mode. If mode is AOPT_CLEAR (0), then the selected options found in aopt0 - aopt3 are cleared, disabling them. If AOPT_SET (1), then the selected option bit is set, enabling them.
aopt0 The first group of 16 options which have the following meaning:
Bit 0 - AO0_WF_SLIDER
If this bit is set, blah, blah, yeah.
Bit 1 - AO0_OBJC_EDIT
If this options is enabled, objc_edit... blah
aopt1 The second group of 16 options, none of which is defined yet. Always reads 0.
aopt2 The third group of 16 options, none of which is defined yet. Always reads 0.
aopt3 The third group of 16 options, none of which is defined yet. Always reads 0.
out0
out1
out2
out3
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

8.3.9.1 Bindings for appl_options

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:

Address Element Contents
control control[0] 137 # Function opcode
control+2 control[1] 5 # Entry in int_in
control+4 control[2] 5 # 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] mode
int_in+2 int_in[1] aopts0
int_in+4 int_in[2] aopts1
int_in+6 int_in[3] aopts2
int_in+8 int_in[4] aopts3
int_out int_out[0] Return value
int_out+2 int_out[1] out0
int_out+4 int_out[2] out1
int_out+6 int_out[3] out2
int_out+8 int_out[4] out3

8.3.10 appl_read

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:
Parameter Meaning
   
ap_rid ID of the application from whose event buffer the data should be read
ap_rlength Number of bytes to be read
ap_rpbuff Address of the buffer in which the data is to be stored


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

8.3.10.1 Bindings for appl_read

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:

Address Element Contents
control control[0] 11 # Function opcode
control+2 control[1] 2 # 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
int_in int_in[0] ap_rid
int_in+2 int_in[1] ap_rlength
addr_in addr_in[0] ap_rpbuff
int_out int_out[0] Return value

8.3.11 appl_search

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:
Parameter Meaning
   
ap_smode Search for:
APP_FIRST 0 First application
APP_NEXT 1 Next application
APP_DESK 2 System shell
APP_TASKINFO 0x100 Request task info,
    XaAES bit that may be added.
ap_sname Buffer that receives the name of the found application filename (at least 9 bytes including a terminating NULL-byte)
ap_stype Type of the process as bit-vector:
APP_SYSTEM 0x001 System process
APP_APPLICATION 0x002 Application
APP_ACCESSORY 0x004 Accessory
APP_SHELL 0x008 System shell
APP_HIDDEN 0x100 Task is disabled,
    XaAES only for APP_TASKINFO
APP_FOCUS 0x200 Active application,
    XaAES only for APP_TASKINFO
ap_sid ID of the found application


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:
  • X_APS_CHEXIT (-1)
    Retrieves the name, ID, and type of the last application to exit. This makes it possible for a program which receives a CH_EXIT notice to determine the name of the program which exited. Note that this information is not buffered; this means that if one process terminates and its parent does not make the appl_search call before a second one does, the information will no longer reflect the first process which terminated.

  • X_APS_CHILD0 (0x7100)
    Retrieve the data concerning the child of the current application which has the lowest application ID. (This is not necessarily the first child application the parent ran.)

  • X_APS_CHILD (0x7101)
    Retrieve the data for each additional child of the current application.

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

8.3.11.1 Bindings for appl_search

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:

Address Element Contents
control control[0] 18 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 3 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] ap_smode
addr_in addr_in[0] ap_sname
int_out int_out[0] Return value
int_out+2 int_out[1] ap_stype
int_out+4 int_out[2] ap_sid

8.3.12 appl_tplay

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:
Parameter Meaning
   
ap_tpmem Address of the buffer that contains the events to be replayed
ap_tpnum Number of events to be executed
ap_tpscale Speed factor for how fast AES will try to replay the events (0..10000); a value of 100 = normal speed
Return value: The function always returns the value 1.
Availability: All AES versions.
Group: Application library
See also: Binding   appl_trecord

8.3.12.1 Bindings for appl_tplay

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:

Address Element Contents
control control[0] 14 # Function opcode
control+2 control[1] 2 # 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
int_in int_in[0] ap_tpnum
int_in+2 int_in[1] ap_tpscale
addr_in addr_in[0] ap_tpmem
int_out int_out[0] Return value

8.3.13 appl_trecord

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:
Parameter Meaning
   
ap_tbuffer Address of memory block in which the events are to be stored
ap_trcount Number of events to be stored
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

8.3.13.1 Bindings for appl_trecord

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:

Address Element Contents
control control[0] 15 # Function opcode
control+2 control[1] 1 # 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
int_in int_in[0] ap_trcount
addr_in addr_in[0] ap_tbuffer
int_out int_out[0] Return value

8.3.14 appl_write

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:
Parameter Meaning
   
ap_wid ID of the application to which the message is to be sent
ap_wlength Number of bytes to be sent
ap_wpbuff Address of buffer containing the message to be transferred


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

8.3.14.1 Bindings for appl_write

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:

Address Element Contents
control control[0] 12 # Function opcode
control+2 control[1] 2 # 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
int_in int_in[0] ap_wid
int_in+2 int_in[1] ap_wlength
addr_in addr_in[0] ap_wpbuff
int_out int_out[0] Return value

8.3.15 appl_xbvset

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:
Parameter Meaning
   
bvdisk Bit-vector of floppy drives present (bit 31 = Drive A: etc).
bvhard Bit-vector of hard drives present (bit 31 = Drive A: etc).
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

8.3.15.1 Bindings for appl_xbvset

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:

Address Element Contents
control control[0] 18 # Function opcode
control+2 control[1] 1 # 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
int_in int_in[0] 1
addr_in addr_in[0] bvdisk
addr_in+4 addr_in[1] bvhard
int_out int_out[0] Return value

8.3.16 appl_yield

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

8.3.16.1 Bindings for appl_yield

C: int16_t appl_yield ( void );
Binding:
int16_t appl_yield (void)
{
   return ( crys_if(17) );
}
GEM-Arrays:

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

8.3.17 _appl_yield

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

8.3.17.1 Bindings for _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

8.3.18 x_appl_flags

Name: »Control execution flags« - (Geneva)
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.
Mode 0: Get by index
Get the 'nth' block of global application flags. If index is zero, the Default flags will be retrieved. If flags is not NULL, the flags will be copied into the APPFLAGS structure pointed to by the flags parameter.
Mode 1: Set by index
Set the 'nth' block of global application flags. If flags is not NULL, the flags will be copied from the APPFLAGS structure pointed to by the flags parameter. If index is zero, the Default flags will be set, in which case the name and desc fields of the APPFLAGS are not altered. If index is less than zero, a new APPFLAGS structure will be added to the end of the global list, and it will be given the contents of flags.
Mode 2: Delete by index
Delete the 'nth' block of global application flags. The index parameter must be a number greater than zero (since the Default flags cannot be deleted.) The flags parameter is not used in this mode.
Mode 3: Get by application ID
Get the application flags for a particular process.index must be a valid application ID. If flags is not NULL, the flags will be copied into the APPFLAGS structure pointed to by the flags parameter.
Mode 4: Set by application ID
Set the application flags for a particular process.index must be a valid application ID. If flags is not NULL, the flags will be set for the application.
Mode 5: (X_APF_SEARCH) (since Update 004)
Use the APPFLAGS name element to search for the set of flags that would be used by Geneva were it to run the application with that name. Note that the name element is overwritten in the process. The index parameter is not used.

Example: Get the flags for FOO.PRG and force it to run in single-tasking mode:
APPFLAGS a;
SHWRCMD shwrcmd;

strcpy( a.name, "FOO.PRG" );
x_appl_flags( X_APF_SEARCH, 0, &a );
a.flags.s.multitask = 0;
shwrcmd.name = "FOO.PRG";
shwrcmd.app_flags = a.flags.l;
shel_write( XSHD_FLAGS|XSHW_RUNANY, 0, 0, (char *)&shwrcmd, "" );


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

8.3.18.1 Bindings for x_appl_flags

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:

Address Element Contents
control control[0] 28928 # Function opcode
control+2 control[1] 2 # 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
int_in int_in[0] getset
int_in+2 int_in[1] index
addr_in addr_in[0] flags
int_out int_out[0] Return value

8.3.19 x_appl_font

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:
  • Only Monospaced fonts should be used.

  • While Geneva will work properly with any size font, some programs may not function properly with larger or smaller fonts. This is especially true when it comes to fonts which are more than 8 pixels wide.



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

8.3.19.1 Bindings for x_appl_font

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:

Address Element Contents
control control[0] 28929 # Function opcode
control+2 control[1] 2 # 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
int_in int_in[0] getset
int_in+2 int_in[1] zero
addr_in addr_in[0] info
int_out int_out[0] Return value

8.3.20 x_appl_sleep

Name: »Put application to sleep« - or wake it up (Geneva)
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.

Parameter Meaning
sleep  0: Awaken application
   1: Put application to sleep
  -1: No change


The old state of wakefulness is always returned in xas_return, unless an error occurs. There are several situations where an error code will be returned:
  • There is no application with the ID specified.
  • The application was the only program awake and the user tried to put it to sleep.
  • The application has a single-tasking child.


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
bit 0 set: Application was sleep
bit 1 set: Application is multitasking is clear, the application is single-tasking
Availability: The function is available only under Geneva.
Group: Application library
See also: Binding

8.3.20.1 Bindings for x_appl_sleep

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:

Address Element Contents
control control[0] 28930 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # 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] id
int_in+2 int_in[1] sleep
int_out int_out[0] Return value

8.3.21 x_appl_term

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.
  • apid is the application ID of the application to be terminated.
  • retrn is a value which is returned to the program which launched the application; this should usually correspond to a GEMDOS error number, or 0 for no error.
  • The set_me parameter must always be non-zero.


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

8.3.21.1 Bindings for x_appl_term

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:

Address Element Contents
control control[0] 28931 # Function opcode
control+2 control[1] 3 # Entry in int_in
control+4 control[2] 1 # 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] apid
int_in+2 int_in[1] retrn
int_in+4 int_in[2] set_me
int_out int_out[0] Return value

HomeAESAES fundamentalsFile-selector library