XCONTROL

XCONTROL

Programming guidelines

9.1 About XCONTROL

XControl is a modular (extendable) control field desk accessory that was first shipped by Atari with the TT030 and Mega-STE series of computers.

The individual modules are files with the extension '.CPX' (Control Panel eXtension), and XControl itself can be taken as the control program for these modules.

Important: XControl should be used only as a tool for configuration dialogs, and not misused for other purposes.

The communication between XControl and its modules takes place via two structures that are denoted XCPB and CPXINFO. The former makes some flags as well as a whole string of help functions available.

At system start-up XControl loads all available CPX headers, using up to 512 bytes of system memory per header; provided the corresponding flag is set in the header, each of the CPX files is called once for initialization. One can specify for each individual module whether it is to be loaded as resident or not (this can be changed also with the bundled configuration CPX). In addition it is possible to write CPX modules that set only certain values; these so-called 'set only' modules are called only during booting or renewed loading of the CPX modules with XControl, and simply return a NULL-pointer during the initialization.

As soon as a user selects a CPX module, XControl loads it into memory and calls the function cpx_init. Subsequently cpx_call is called, for which essentially the module itself now takes control.

One can differentiate between a Form CPX and an Event CPX. The former are relatively simple to program, but offer only limited flexibility. The latter are more flexible, since they evaluate the AES events directly. All the CPX modules supplied with XControl 1.0 are Form CPX files, from which one can deduce that Form CPXs suffice in most cases.

The following terminology applies for the filenames of CPX modules:

The format of a CPX file is very similar to that of a normal program. It consists of a 512-byte header and the remaining file content that is almost a normal GEMDOS program file, including a standard 28-byte GEMDOS header.

typedef struct
{
    uint16_t magic;                 /* Magic constant = 100   */

    struct
    {
        unsigned reserved : 13;  /* Reserved                */
        unsigned resident :  1;  /* RAM-resident if set     */
        unsigned bootinit :  1;  /* Boot initialize if set  */
        unsigned setonly  :  1;  /* Set-only CPX if set     */

    } flags;

    int32_t  cpx_id;                /* Unique CPX ID                   */
    uint16_t cpx_version;           /* CPX version number              */
    int8_t   i_text[14];            /* Icon text                       */
    uint16_t sm_icon[48];           /* Icon bitmap (32*24 pixel)       */
    uint16_t i_color;               /* Icon colour                     */
    int8_t   title_text[18];        /* Name of the CPX (16 chars. max) */
    uint16_t t_color;               /* Text colour                     */
    int8_t   buffer[64];            /* Non-volatile buffer             */
    int8_t   reserved[306];         /* Reserved                        */

} CPXHEAD;

Some notes about the header:

• The first function in the TEXT segment has to be the initialization routine for the CPX
• There are everal toolkits for the construction of a CPX header
• Header and linked program file can be joined in most UNIX-like shells (e.g. Mupfel from Gemini) with the command 'cat'
• During CPX development it is very practical that XControl can be launched also as a program (alter the suffix!); this allows working without permanent rebooting of the computer
• CPX ID and version number ensure that each CPX appears only once (and also only the latest version)

While programming a CPX module one should note some subtleties: As such a module has no non-volatile memory available (apart from 64 bytes), nothing is permitted that reserves fixed memory in any way. In particular, all variable contents are lost when leaving the CPX as a rule!

Hence one should:

• Incorporate resources statically
• Only permit short-term memory allocation
• Not create permanent virtual VDI workstations

For the programming of a CPX module one can fall back on the functions from the following categories:

• CPX functions
   

• XCONTROL functions
   

Note: There are several alternatives to XCONTROL, which is not being developed by Atari any more. One that is particularly recommended is COPS (COntrol Panel Server, which not only permits simultaneous opening of any mumber of CPX modules, but also allows control fields with a larger working area than XCONTROL.

Other alternatives are ZCONTROL and a supplementary function of the Freedom2 file-selector.

9.1.1 CPX programming guidelines

When programming a CPX module one should keep to the following rules if possible:

• Release reserved memory as soon as possible
• XControl functions should always be used if this is possible
• The user interface should be as simple as possible and fashioned in a similar way to other CPX modules
• Graphical elements are to be preferred to menu commands
• 'OK' and 'Cancel' should always be implemented (if possible)
• Popup menus should be depicted as text with a shadowed rectanle
• AC_CLOSE (quitting of the main program) is evaluated as 'Cancel'
• WM_CLOSE (closing of the XControl window) is evaluated as 'OK'
• 'Save' is evaluated as 'OK' without quitting the dialog
• The root object of the CPX always has a size of 256*176 pixels Exception: Under COPS the object tree may have a size of up to 512*384 pixels
• Interrupt vectors may not be altered
• Xform_do may not be mixed with functions for Event CPXs
• One must not forget about reserved memory when quitting the CPX, as this would lead to fragmentation of the memory otherwise
• One must not use IDs already being used by other CPXs
• Opened files must be closed again
• Opened VDI workstations must be closed again in every case (at the latest at the receipt of a AC_CLOSE or WM_CLOSE message), if they are no longer needed

9.1.2 CPX functions

9.1.2.1 cpx_button

9.1.2.2 cpx_call

9.1.2.3 cpx_close

9.1.2.4 cpx_draw

9.1.2.5 cpx_hook

9.1.2.6 cpx_init

int16_t is_COPS ( int32_t magic, int32_t version )
{
   if ((magic == 'COPS') && (version >= 0x10000L))
      return (TRUE);      /* COPS */
   else return (FALSE);   /* XCONTROL */
}

9.1.2.7 cpx_m1

9.1.2.8 cpx_m2

9.1.2.9 cpx_key

9.1.2.10 cpx_timer

9.1.2.11 cpx_wmove

9.1.3 XCONTROL functions

9.1.3.1 CPX_Save

9.1.3.2 Get_Buffer

9.1.3.3 getcookie

9.1.3.4 GetFirstRect

9.1.3.5 GetNextRect

9.1.3.6 MFsave

9.1.3.7 Popup

9.1.3.8 rsh_fix

9.1.3.9 rsh_obfix

9.1.3.10 Set_Evnt_Mask

9.1.3.11 Sl_arrow

9.1.3.12 Sl_dragx

9.1.3.13 Sl_dragy

9.1.3.14 Sl_size

9.1.3.15 Sl_x

9.1.3.16 Sl_y

9.1.3.17 Xform_do

9.1.3.18 XGen_Alert

XCONTROL

XCONTROL

Programming guidelines