Support for enhanced FreeGEM features ===================================== GEM was GPLed in April 1999; since then I have uploaded source for a version ("FreeGEM") containing the extra functions in ViewMAX/2 and ViewMAX/3. The following functions apply to FreeGEM and ViewMAX: WORD xgrf_colour(WORD type, WORD fg, WORD bg, WORD style, WORD index); WORD xgrf_dtmfdb(LPMFDB newdesk); (there are also extra FreeGEM-only functions - see below). In xgrf_colour(): type is the user interface object type, 0-15. The ones defined in VIEWHELP.RSC are: #define CC_NAME 8 /* Active titlebar */ #define CC_SLIDER 9 /* Scrollbar background */ #define CC_DESKTOP 10 /* Desktop */ #define CC_BUTTON 11 /* Buttons and 3D areas */ #define CC_INFO 12 /* Information line */ #define CC_ALERT 13 /* Alert boxes (ignored) */ #define CC_SLCTDNAME 14 /* Inactive titlebar */ FreeGEM adds the following types (dependent on extended 3D support): #define CC_3DSHADE 16 /* Foreground is 3D highlight & background is 3D shadow*/ #define CC_RADIO 17 /* Foreground & background colours of * * the dot in the radio button */ #define CC_CHECK 18 /* Background is colour of tick */ In xgrf_dtmfdb(), the first reserved word of the MFDB contains the display mode for the image. It can be: #define DT_CENTER 1 Centred #define DT_TILE 2 Tiled There are also five extra object flags: #define ESCCANCEL 0x200 When applied to a button, ESC is a shortcut for it. You can make ESC a shortcut for a button in form_alert(), by passing the button number in the high byte of the 'default button' parameter. For example, form_alert ((3 << 8) | 1, ...) means button 1 is the default button, and button 3 has ESC as the shortcut. #define BITBUTTON 0x400 Not used by the AES. #define SCROLLER 0x800 When applied to a button, it may intercept "up" or "down" arrow keypresses; used in list boxes. #define FLAG3D 0x1000 Draw object in 3D. Buttons are always 3D. #define USECOLOURCAT 0x2000 Use the system colours set by xgrf_colour(). xgrf_color(). The object's colour value becomes the ViewMAX object type, as above. 3D objects always use system colours. FreeGEM adds: #define FL3DBAK 0x4000 Make a "sunken" 3D object rather than a "raised" one. #define SUBMENU 0x8000 Reserved - used in Atari GEM. and two extra object states: #define HIGHLIGHTED 0x100 Draw a highlight box round the object #define UNHIGHLIGHTED 0x200 Remove the highlight box NOTE: The supplied RCS has been extended to handle the extra flags. This is an experimental RCS which you should treat with caution. Save early, save often, and keep good backups. FreeGEM: Extra parameter to appl_init() ======================================= appl_init() now takes an extra parameter; a pointer to a structure of type X_BUF_V2. If you don't want to use this parameter, pass NULL. If a program wants to use the extra features in FreeGEM, it must pass a valid pointer; future GEM versions may use this as a test to see whether they should emulate FreeGEM or Atari GEM. To use the structure, fill it with zeroes and set its "buf_len" member to its size. On return, if the program is running under FreeGEM, the remainder of the structure will be filled with data (all pointers will be linear addresses): typedef struct x_buf_v2 { WORD buf_len; /* Size of structure passed. Set by caller; * on return, size of data returned by GEM */ WORD arch; /* 16 for 16-bit, 32 for any future * 32-bit version. 0 if not FreeGEM. */ LONG cc; /* Address of an array of 19 CLRCAT * structures (containing data from * xgrf_colour() calls). * This is so that they can be read by * a program without having to fiddle * with ViewMAX.INI */ LONG w_active; /* Address of the tree (18 elements) * that is used to draw window frames and * controls. The intention is that the * glyphs on the buttons could be changed * by a program. Use of this value is now * deprecated; wind_set() and wind_get() * (described below) should be used instead. */ LONG info; /* ASCII information such as a version * string. This will be max. 40 characters * with no newlines */ LONG abilities; /* The capabilities of this particular * FreeGEM build (taking into account compile- ********************************** time options, differing versions, etc.) * Abilities are: * * Bit 0 (ABLE_GETINFO) is set if the AES supports an Atari-style * appl_getinfo() call. * Bit 1 (ABLE_PROP) is set if the AES supports prop_get(), prop_put() and * prop_del() - see below. * Bit 2 (ABLE_WTREE) is set if the AES supports WF_OBFLAGS, WF_OBSPEC and * WF_OBTYPE - see below. * Bit 3 (ABLE_X3D) is set if the AES supports GEM/5 style 3D using the * DRAW3D and WHITEBAK object states. * Bit 4 (ABLE_XSHL) is set if the AES supports xhsl_getshell() and * xshl_setshell() calls - see below. * Bit 5 (ABLE_PROP2) is set if the AES supports prop_gui_get() and * prop_gui_set() - see below. * Bit 6 (ABLE_EMSDESK) is set if xgrf_dtmfdb() supports the use of EMS * memory. * Bit 7 (ABLE_XBVSET) is set if the AES supports 32 disc drives using the * appl_xbvset() / appl_xbvget() call. *********************************************/ } X_BUF_V2; FreeGEM: Property file ====================== There is a compile-time option in the latest GEM AES to include three extra functions: prop_get(), prop_put() and prop_del() (nos. 1010-1012). These are used to access a global settings file. The file currently has an extremely simple structure, but the functions allow for a more complicated tree-structured system. The syntax is: WORD prop_get(char *program, char *section, char *buf, WORD buflen, WORD options); "program" is a name that identifies your program. It should be formed of one or more words separated by dots - for example, the DEMO sample uses "PTK.DEMO". You should avoid program names starting "GEM." to avoid a clash with GEM itself. "section" is the name of the field to retrieve. Again, this should be one or more words separated by dots. DEMO uses "Pen.shade", "Pen.colour" and "Pen.size". "buf" is the address of the buffer to which the information will be written. "buflen" is the size of "buf", including the terminating 0. "options" should be 0 if the setting is per-user, 1 if it is for all users. This is for future expansion since GEM does not currently support multiple user profiles. It is recommended that "options" should be set to 0 if at all possible. This function returns: 0 - Property read successfully. 1 - Property was not found. -1 - File I/O error. -2 - Not enough memory to do this. WORD prop_put(char *program, char *section, char *buf, WORD options); The parameters and return values are as for prop_get() above, except that this function will never return 1. Note that prop_get() will remove leading spaces from returned values, so if you are writing a string value that may start with spaces, you must put it in quotes before calling prop_put(). WORD prop_del(char *program, char *section, WORD options); The parameters are as for prop_get() above. The current property file format is an ASCII file: \GEMAPPS\GEMSYS\GEM.CFG. The "program" and "section" fields are concatenated to produce a single string, making each line look like: PTK.DEMO.Pen.size: 5 PTK.DEMO.Pen.shade: 4 PTK.DEMO.Pen.colour: 4 You are strongly discouraged from allowing programs to edit this file directly! FreeGEM: xapp_getinfo() ======================= This function was added to correspond to the Atari appl_getinfo() function, takes the same parameters and returns the same results. You can call it as appl_getinfo() instead of xapp_getinfo() if you want. FreeGEM: xapp_getshell() & xapp_setshell() ========================================== These functions are used to change the name of the shell program (normally DESKTOP.APP). xapp_getshell() will return the program name (no path; it is assumed that the program is always in \GEMAPPS\GEMSYS). It returns 0 if this is the standard shell DESKTOP.APP, and 1 if the shell has been set using the GEM.CFG file or xapp_setshell(). xapp_setshell() sets the shell name. Again, no path can be passed. It returns 0 if successful, 1 if the filename was too long. FreeGEM: Window decorations =========================== The window decorations can be changed using wind_set() and wind_get(). This is how: #define WF_OBFLAG 1001 /* Window tree: flag words */ #define WF_OBTYPE 1002 /* Window tree: type words */ #define WF_OBSPEC 1003 /* Window tree: spec dwords */ wind_get(n, WF_OBFLAG, &a, &b, &c, &d) - a = object flags for decoration "n" wind_get(n, WF_OBTYPE, &a, &b, &c, &d) - a = object type of decoration "n" wind_get(n, WF_OBSPEC, &a, &b, &c, &d) - (b<<16)|a = spec of decoration "n" wind_set(n, WF_OBFLAG, a, b, c, d) - Set flags for decoration "n" to "a" wind_set(n, WF_OBSPEC, a, b, c, d) - Set spec of decoration "n" to (b<<16)|a The "n" parameter is one of: #define W_BOX 0 outline #define W_TITLE 1 titlebar outline #define W_CLOSER 2 close box #define W_NAME 3 titlebar #define W_FULLER 4 full-size box #define W_INFO 5 info bar #define W_DATA 6 work area outline #define W_WORK 7 work area #define W_SIZER 8 resize box #define W_VBAR 9 vertical scroll bar outline #define W_UPARROW 10 scroll up box #define W_DNARROW 11 scroll down box #define W_VSLIDE 12 vertical scroll bar #define W_VELEV 13 scroll thumb #define W_HBAR 14 horizontal scroll bar outline #define W_LFARROW 15 scroll left box #define W_RTARROW 16 scroll right box #define W_HSLIDE 17 horizontal scroll bar #define W_HELEV 18 horizontal scroll bar thumb FreeGEM: Extended 3D ==================== FreeGEM implements an extended 3D controls system, similar to that in GEM/5. This system works by overloading the WHITEBAK and DRAW3D flags; it is therefore incompatible with Atari GEM, which overloads WHITEBAK differently. If the ABLE_X3D bit is set in the AES abilities field, then the following features are available: * Checkboxes. Set the DRAW3D state and the SELECTABLE flag on a 2-dimensional object such as a G_STRING. * Radio buttons. Set the RBUTTON flag on a checkbox. By default, checkboxes and radio buttons display as if on a 3D background. Set the WHITEBAK state to make them display correctly on a white background. * Default buttons. Set the DEFAULT state and the DRAW3D flag on a G_BUTTON object, and a <=" symbol will appear on it. * Sunken 3D objects. Set the FL3DBAK flag on them rather than FLAG3D, and the object will be drawn sunken. * Ability to set 3D light/dark colours, tick and dot colours using xgrf_colour(). * 3D objects with no black border - set the WHITEBAK flag. FreeGEM: GUI properties ======================= prop_gui_get() (call 1013) and prop_gui_set() (call 1014) provide an extensible interface for miscellaneous user-interface options. The syntax is: WORD prop_gui_get(WORD option) Returns the value of the chosen option, zero if the option number is out of range. WORD prop_gui_set(WORD option, WORD value) Sets the chosen option to a new value. Returns the value used, which may not be the same as the value requested. The option numbers are: 0 - Return count of option words (currently returns 5; valid option numbers are 0-4). Cannot be set. 1 - If zero, 3D objects have square corners; if nonzero, the corners are rounded. 2 - If zero, window frames follow the GEM/2 style; otherwise they follow the GEM/5 style. If this is changed at runtime, windows will have a strange appearance until a new program is loaded. 3 - GEM emulation mode This is provided for future compatibility with other AES replacements (such as oAESis) which have extended the AES in different ways and with which FreeGEM is incompatible. When read, this will return the emulation mode of this AES: 0: GEM/1 subset. Programs should only assume features that are present in GEM/1. 1: Atari GEM. Object flags and types have Atari semantics. 2: FreeGEM. Object flags and types have FreeGEM semantics. When written, the variable is set to 0 if the desired emulation mode be not available, or the requested mode if it is. Currently, only modes 0 and 2 are available (and behave identically). Note for AES authors: If you want to support FreeGEM programs, check the number of parameters passed to appl_init(). If there is an address parameter (see X_BUF_V2 below), then the program is FreeGEM aware and you should set your emulation mode to 2. If the program then wants to use Atari object flags, it should immediately call prop_gui_set(3,1) to switch back to Atari mode. 4 - Menu flags Bit 0 set: The "Desk" menu is called "Desk" rather than taking the name of the current program. Bit 1 set: The "Desk" menu is on the left. FreeGEM: Desktop image in EMS ============================= xgrf_dtmfdb() returns a WORD value. If this value is nonzero, then the image passed has been copied into EMS memory and will be used for all programs (except those that create their own desktops, like SETTINGS.APP or the GEM/1 desktop). If the image has been copied into EMS memory you don't have to keep your copy of the image. Zero will be returned if: * There is no EMS memory. * There is not enough EMS memory for the image. * The image will not fit in the EMS page frame. FreeGEM: Switchable shells ========================== You can set the name of the desktop program to use by means of the xshl_setshell() call (no. 1031). This call takes one parameter in addr_in: the name of the desktop program (again, no path). It will return 0 if the desktop program was set, or 1 if the name was too long. To get the name of the desktop program, call xshl_getshell() (call 1030). It takes one parameter in addr_in - the address of a buffer for the name of the program. This call returns 0 if the default desktop (DESKTOP.APP) is in use, or 1 if a different desktop has been set by use of GEM.CFG or xshl_setshell(). Note that a normal GEM program is not suitable for use as a shell, since when it terminates it will be immediately re-run. FreeGEM and GEM/4: 32 drives ============================ GEM/4, GEM/5 and recent FreeGEM builds support 32 disc drives rather than 16. The function to do this is present on FreeGEM if the ABLE_XBVSET bit is set in the "abilities" bitmap. To retrieve or change the drive bitmaps, use appl_xbvget and appl_xbvset: WORD appl_xbvget(ULONG *bvdisk, ULONG *bvhard); This will return the two 32-bit drive vectors, with bit 31 indicating drive A: and bit 6 indicating drive Z:. WORD appl_xbvset(ULONG bvdisk, ULONG bvhard); This sets the drive vectors, as above.