HomeXCONTROLXCONTROLProgrammierrichtlinen

9.1 Das XCONTROL

XControl ist ein modulares (erweiterbares) Kontrollfeld, das von Atari zuerst mit den Computern der TT und Mega-STE Serie ausgeliefert wurde.

Die einzelnen Module sind Dateien mit der Namenserweiterung '.CPX' (Control-Panel eXtension), und XControl selbst kann als Steuerungsprogramm für diese Module angesehen werden.

Wichtig: XControl sollte nur als Tool für Konfigurationsdialoge angesehen werden, und nicht für andere Zwecke mißbraucht werden.

Die Kommunikation zwischen XControl und seinen Modulen erfolgt über zwei Strukturen, die mit XCPB und CPXINFO bezeichnet werden. Über erstere werden einige Flags sowie eine ganze Reihe von Hilfsfunktionen zugänglich gemacht.

Beim Start lädt XControl alle verfügbaren CPX-Header; sofern im Header ein entsprechendes Flag gesetzt ist, werden alle CPX-Dateien einmal zum initialisieren aufgerufen. Für jedes einzelne Modul kann angegeben werden, ob es resident geladen werden soll (dies kann auch über das mitgelieferte Konfigurations-CPX verändert werden). Darüber hinaus ist es möglich, CPX-Module zu schreiben, die nur bestimmte Werte setzen. Man spricht in diesem Zusammenhang von 'Set-Only'-Modulen, die nur beim Booten bzw. erneuten Laden der CPX-Module durch XControl aufgerufen werden, und bei der Initialisierung einfach einen Nullzeiger zurückliefern.

Sobald ein CPX-Modul vom Anwender ausgewählt wird, lädt XControl dieses in den Speicher, und ruft die Funktion cpx_init auf. Anschließend wird noch cpx_call aufgerufen, wobei im wesentlichen nun das Modul selbst die Steuerung übernimmt.

Man unterscheidet zwischen Form-CPX und Event-CPX. Erstere sind relativ einfach zu programmieren, bieten jedoch nur eine eingeschränkte Flexibilität. Letztere sind flexibler, da sie die AES-Events direkt auswerten. Alle mit XControl 1.0 ausgelieferten CPX-Module sind Form-CPX Dateien, woraus geschlossen werden kann, daß Form-CPX in den meisten Fällen ausreichen.

Für die Dateinamen von CPX-Modulen gilt die folgende Terminologie:

Suffix Bedeutung
*.CP Standard-CPX ohne Header
*.CPX Standard-CPX, fertig zum Gebrauch
*.CPZ inaktive CPX (von XControl deaktiviert)
*.HDR Header für die CPX-Datei
*_R.CPX residente CPX-Datei
*_S.CPX Set-Only CPX-Datei

Der Aufbau einer CPX-Datei ist einem normalen Programm sehr ähnlich. Sie besteht aus einem 512 Byte großen Header und dem übrigen Dateiinhalt, bei dem es sich fast um eine normale GEMDOS-Programmdatei handelt. Der Header ist dabei wie folgt definiert:

typedef struct
{
    uint16_t magic;                 /* Magic-Konstante = 100   */

    struct
    {
        unsigned reserved : 13;  /* reserviert              */
        unsigned resident :  1;  /* RAM-resident            */
        unsigned bootinit :  1;  /* Boot-Initialisierung    */
        unsigned setonly  :  1;  /* Set-Only                */

    } flags;

    int32_t  cpx_id;                /* eindeutige CPX-ID       */
    uint16_t cpx_version;           /* CPX-Versionsnummer      */
    int8_t   i_text[14];            /* Icontext                */
    uint16_t sm_icon[48];           /* Bitmap (32*24 Pixel)    */
    uint16_t i_color;               /* Iconfarbe               */
    int8_t   title_text[18];        /* Name des CPX            */
    uint16_t t_color;               /* Textfarbe               */
    int8_t   buffer[64];            /* nicht-flüchtiger Puffer */
    int8_t   reserved[306];         /* reserviert              */

} CPXHEAD;

Zum Header noch einige Anmerkungen:

Bei der Programmierung eines CPX-Moduls sind einige Feinheiten zu beachten. Da ein solches Modul (mit Ausnahme von 64 Byte) über keinen nichtvergänglichen Speicher verfügt, ist nichts erlaubt, was Speicher in irgendeiner Form fest reserviert. Insbesondere gehen Variableninhalte mit dem Verlassen der CPX in aller Regel verloren ! Daher sollte man:

Bei der Programmierung eines CPX-Moduls kann auf Funktionen der beiden folgenden Kategorien zurückgegriffen werden:

Hinweis: Als Alternative zu XCONTROL, welches von Atari nicht mehr weiterentwickelt wird, bieten sich verschiedene Programme an. Besonders empfehlenswert ist dabei COPS (COntrol Panel Server, mit dessen Hilfe sich nicht nur beliebig viele CPX-Module gleichzeitig öffnen lassen, sondern das auch Kontrollfelder mit größerer Arbeitsfläche als XCONTROL erlaubt.

9.1.1 CPX-Programmierrichtlinien

Bei der Programmierung eines CPX-Moduls sollte man tunlichst die folgenden Regeln beachten:

9.1.2 CPX-Funktionen

cpx_button Maustasten-Ereignis
cpx_call Aktivierungsroutine
cpx_close Close-Ereignis
cpx_draw Redraw-Ereignis
cpx_hook Preemption Hook
cpx_init Initialisierung
cpx_m1 Mausrechteck-Ereignis
cpx_m2 Mausrechteck-Ereignis
cpx_key Keyboard-Ereignis
cpx_timer Timer-Ereignis
cpx_wmove Fensterverschiebung

9.1.2.1 cpx_button

Name: »cpx_button« - Ereignis für die Maustasten
Deklaration: VOID cdecl (*cpx_button) (MRETS *mrets, int16_t nclicks, int16_t *event);
Beschreibung: Die Funktion wird bei einem aufgetretenen Maustastenereignis aufgerufen. Es gilt:
Parameter Bedeutung
mrets Maus-Parameter zum Event
nclicks Anzahl der Mausklicks
event auf den Wert 1 setzen, falls das CPX verlassen werden soll
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: CPX-Funktionen
Querverweis: cpx_key   cpx_timer

9.1.2.2 cpx_call

Name: »cpx_call« - Aufruf des CPX Moduls
Deklaration: int16_t cdecl (*cpx_call) ( GRECT *work );

int16_t cdecl (*cpx_call) ( GRECT *work, DIALOG *dialog );
Beschreibung: Die Funktion wird aufgerufen, wenn der Anwender das entsprechende Modul ausgewählt hat. Es gilt:
Parameter Bedeutung
work Rechteck mit den Koordinaten des XControl-Fensters
dialog Zeiger auf einen Fensterdialog


Hinweis: Die zweite Aufrufform steht nur unter COPS zur Verfügung. Der Parameter dialog enthält in diesem Fall einen Zeiger auf die Fensterdialogstruktur. Der Dialog wird von COPS nach dem cpx_init mit Hilfe von wdlg_create und wdlg_open geöffnet. Der Parameter work und der Objektbaum liegen bis zum ersten Aufruf von Xform_do bzw. bis zur Rückkehr aus der Funktion cpx_call außerhalb des sichtbaren Bildschirms.
Ergebnis: Die Funktion liefert einen der folgenden Werte zurück:

0 = Ende der Bearbeitung
<> 0 = CPX soll weiterbearbeitet werden
Gruppe: CPX-Funktionen
Querverweis: XCONTROL

9.1.2.3 cpx_close

Name: »cpx_close« - Ereignis zum Schließen des Fensters
Deklaration: VOID cdecl (*cpx_close) (int16_t flag);
Beschreibung: Die Funktion sorgt für das Schließen des CPX-Moduls. Es gilt:
Parameter Bedeutung
flag Grund des Schließens
0 = AC_CLOSE Message
<> 0 = WM_CLOSE Message


Hinweis: Die Funktion wird bei jeder AC_CLOSE bzw. WM_CLOSE Nachricht aufgerufen. Die CPX sollte dann sofort allen reservierten Speicher freigeben. Die Funktion muss bei jeder Event-CPX implementiert sein. AC_CLOSE ist als 'Abbruch', WM_CLOSE als 'Ok' zu werten.
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: CPX-Funktionen
Querverweis: cpx_init   XCONTROL

9.1.2.4 cpx_draw

Name: »cpx_draw« - Ereignis zum Neuzeichnen des CPX-Fensters
Deklaration: VOID cdecl (*cpx_draw) (GRECT *clip);
Beschreibung: Die Funktion sorgt für das Neuzeichnen von Teilen des CPX-Fensters. Es gilt:
Parameter Bedeutung
clip neu zu zeichnender Bereich, der auch als übergabe-Parameter für GetFirstRect benötigt wird.


Hinweis: Die nötige Rechteckliste muss per GetFirstRect und GetNextRect ermittelt werden.
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: CPX-Funktionen
Querverweis: cpx_wmove   GetFirstRect   GetNextRect

9.1.2.5 cpx_hook

Name: »cpx_hook« - Preemption Hook
Definiton int16_t cdecl (*cpx_hook) (int16_t event, int16_t *msg, MRETS *mrets, int16_t *key, int16_t *nclicks);
Beschreibung: Die Funktion wird sofort nach evnt_multi aufgerufen, also noch bevor XControl das Event bearbeitet. Es gilt:
Parameter Bedeutung
event aufgetretene Events
msg Ereignispuffer
mrets Mausparameter
key Tastendruck
nclicks Anzahl der Mausklicks
Ergebnis: Die Funktion liefert einen der folgenden Werte zurück:

0 = Event-Bearbeitung fortsetzen
<> 0 = Event-Bearbeitung abbrechen
Gruppe: CPX-Funktionen
Querverweis: cpx_button   cpx_draw   cpx_key   cpx_m1   cpx_m2   cpx_timer   cpx_wmove

9.1.2.6 cpx_init

Name: »cpx_init« - Initialisierung der CPX
Deklaration: CPXINFO * cdecl cpx_init (XCPB *xcpb);

CPXINFO* cdecl cpx_init (XCPB *xcpb, int32_t magic, int32_t version );
Beschreibung: Die Funktion sorgt für die Initialisierung der CPX. Es gilt:

Parameter Bedeutung
xcpb Zeiger auf die XCPB-Struktur von XControl


Hinweis: Die Funktion muss am Beginn des Textsegments der CPX-Datei stehen, und wird während der XControl-Initialisierung sowie beim Aktivieren der CPX aufgerufen.

Mit Hilfe der zweiten Aufrufform kann anhand der Parameter magic und version festgestellt werden, ob die CPX unter XCONTROL oder COPS läuft. Es bietet sich die folgende Routine an:
int16_t is_COPS ( int32_t magic, int32_t version )
{
   if ((magic == 'COPS') && (version >= 0x10000L))
      return (TRUE);      /* COPS */
   else return (FALSE);   /* XCONTROL */
}


Falls COPS erkannt wurde, kann die CPX einen bis zu 512*384 Pixel großen Objektbaum zeichnen und bei der Funktion Xform_do übergeben.
Ergebnis: Die Funktion liefert einen der folgenden Werte zurück:

NULL : 'Set Only'-CPX
sonst : Zeiger auf die CPXINFO-Struktur der CPX
Gruppe: CPX-Funktionen
Querverweis: cpx_close   XCONTROL

9.1.2.7 cpx_m1

Name: »cpx_m1« - Ereignis für ein Mausrechteck
Deklaration: VOID cdecl (*cpx_m1) (MRETS *mrets, int16_t *event);
Beschreibung: Die Funktion wird aufgerufen, wenn der Mauszeiger einen bestimmten Bereich betritt oder verläßt. Es gilt:
Parameter Bedeutung
mrets Parameter der Maus
event auf den Wert 1 setzen, wenn die CPX verlassen werden soll
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: CPX-Funktionen
Querverweis: cpx_m2   XCONTROL

9.1.2.8 cpx_m2

Name: »cpx_m2« - Ereignis für ein Mausrechteck
Deklaration: VOID cdecl (*cpx_m2) (MRETS *mrets, int16_t *event);
Beschreibung: Die Funktion wird aufgerufen, wenn der Mauszeiger einen bestimmten Bereich betritt oder verläßt. Es gilt:
Parameter Bedeutung
mrets Parameter der Maus
event auf den Wert 1 setzen, wenn die CPX verlassen werden soll
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: CPX-Funktionen
Querverweis: cpx_m1   XCONTROL

9.1.2.9 cpx_key

Name: »cpx_key« - Ereignis für einen Tastendruck
Deklaration: VOID cdecl (*cpx_key) (int16_t kstate, int16_t key, int16_t *event);
Beschreibung: Die Funktion wird aufgerufen, wenn ein Keyboard-Event aufgetreten ist. Es gilt:
Parameter Bedeutung
kstate Status der Umschalttasten (Alternate, Control, Shift, etc.)
key auslösende Taste
Highbyte : Scan-Code der Taste
Lowbyte : ASCII-Code der Taste
event auf den Wert 1 setzen, wenn die CPX verlassen werden soll
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: CPX-Funktionen
Querverweis: cpx_button   cpx_timer

9.1.2.10 cpx_timer

Name: »cpx_timer« - Timer Ereignis
Deklaration: VOID cdecl (*cpx_timer) (int16_t *event);
Beschreibung: Die Funktion wird aufgerufen, wenn ein Timer-Event aufgetreten ist. Es gilt:
Parameter Bedeutung
event auf den Wert 1 setzen, wenn die CPX verlassen werden soll


Hinweis: Timer-Events werden von Form-CPX nicht unterstützt.
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: CPX-Funktionen
Querverweis: cpx_button   cpx_key   XCONTROL

9.1.2.11 cpx_wmove

Name: »cpx_wmove« - Verschiebung des XControl-Fensters
Deklaration: VOID cdecl (*cpx_wmove) (GRECT *work);
Beschreibung: Die Funktion wird aufgerufen, wenn der Anwender das Xcontrol-Fenster bewegt. Es gilt:

Parameter Bedeutung
work neue Koordinaten des XControl-Fensters
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: CPX-Funktionen
Querverweis: cpx_draw   XCONTROL

9.1.3 XCONTROL-Funktionen

CPX_Save Defaults sichern
Get_Buffer Zwischenspeicher ermitteln
getcookie Cookie-Variablen abfragen
GetFirstRect Behandlung der Rechteckliste
GetNextRect Behandlung der Rechteckliste
MFsave Mausform sichern/wiederherstellen
Popup Popup-Menü
rsh_fix Objektbaum-Umwandlung
rsh_obfix Umwandlung eines Objektes
Set_Evnt_Mask Eventmaske setzen
Sl_arrow Slider-Arrow
Sl_dragx Sliderdrag-Bewegung
Sl_dragy Sliderdrag-Bewegung
Sl_size Slidergröße
Sl_x Positionierung eines Sliders
Sl_y Positionierung eines Sliders
Xform_do Formular-Verwaltung
XGen_Alert Alarmbox

9.1.3.1 CPX_Save

Name: »CPX_Save« - Defaults sichern
Deklaration: int16_t cdecl (*CPX_Save) (VOID *ptr, int32_t num);
Beschreibung: Die Funktion erlaubt das Speichern von Defaulteinstellungen einer CPX. Es gilt:

Parameter Bedeutung
ptr Adresse der zu speichernden Daten
num Anzahl der zu speichernden Bytes


Hinweis: XControl speichert die Einstellungen im DATA Segment der CPX. Daher müssen Entwickler selbst für ausreichend freien Speicherplatz im DATA-Segment sorgen. Dies geschieht über das Datenfeld 'SAVE_VARS' in CPXSTART.S.
Ergebnis: Die Funktion liefert einen der folgenden Werte zurück:

0 : Fehler aufgetreten
<> 0 : kein Fehler aufgetreten
Gruppe: XCONTROL-Funktionen
Querverweis: XCONTROL

9.1.3.2 Get_Buffer

Name: »Get_Buffer« - Zwischenspeicher ermitteln
Deklaration: VOID cdecl (*Get_Buffer) (VOID);
Beschreibung: Die Funktion ermittelt die Adresse eines 64 Byte großen, residenten Speicherbereiches.

Hinweis: In diesem Speicher kann die CPX Inhalte von Write-Only-Registern sichern, falls TOS keine Funktion zur Abfrage bietet (Beispiel: Fensterfarben). Es sei noch einmal darauf hingewiesen, daß jeder andere Speicher einer CPX flüchtig ist !
Ergebnis: Die Funktion liefert einen Zeiger auf den Speicherbereich zurück.
Gruppe: XCONTROL-Funktionen
Querverweis: XCONTROL

9.1.3.3 getcookie

Name: »getcookie« - Cookievariablen abfragen
Deklaration: int16_t cdecl (*getcookie) (int32_t cookie, int32_t *p_value);
Beschreibung: Die Funktion sucht einen Cookie, und ermittelt seinen Wert. Es gilt:
Parameter Bedeutung
cookie Cookie-Variable
p_value Adresse einer Variablen die den Wert aufnehmen soll, oder NULL, falls der Wert nicht von Interesse ist.
Ergebnis: Die Funktion liefert einen der folgenden Werte zurück:

0 : Cookie nicht gefunden
<>0 : Cookie gefunden
Gruppe: XCONTROL-Funktionen
Querverweis: Cookie-Jar

9.1.3.4 GetFirstRect

Name: »GetFirstRect« - Rechteckliste abfragen
Deklaration: GRECT * cdecl (*GetFirstRect) (GRECT *prect);
Beschreibung: Die Funktion ermittelt das erste Rechteck der Rechteckliste. Es gilt:

Parameter Bedeutung
prect zu aktualisierender Bereich


Hinweis: Die Funktion wird zum Neuzeichnen von Fensterbereichen nach einer WM_REDRAW Message benötigt; der Objektbaum wird jedoch von XControl selbst verwaltet.
Ergebnis: Die Funktion liefert einen der folgenden Werte zurück:

NULL : keine weiteren Ausschnitte vorhanden
sonst : wiederherzustellender Ausschnitt
Gruppe: XCONTROL-Funktionen
Querverweis: GetNextRect   XCONTROL

9.1.3.5 GetNextRect

Name: »GetNextRect« - Rechteckliste abfragen
Deklaration: GRECT * cdecl (*GetNextRect) (VOID);
Beschreibung: Die Funktion ermittelt das nächste Rechteck der Rechteckliste.

Hinweis: Die Funktion wird zum Neuzeichnen von Fensterbereichen nach einer WM_REDRAW Message benötigt; der Objektbaum wird jedoch von XControl selbst verwaltet.
Ergebnis: Die Funktion liefert einen der folgenden Werte zurück:

NULL : keine weiteren Ausschnitte vorhanden
sonst : wiederherzustellender Ausschnitt
Gruppe: XCONTROL-Funktionen
Querverweis: GetFirstRect   XCONTROL

9.1.3.6 MFsave

Name: »MFsave« - Mausform sichern oder wiederherstellen
Deklaration: VOID cdecl (*MFsave) (int16_t saveit, MFORM *mf);
Beschreibung: Die Funktion sichert oder restauriert die Form des Mauszeigers. Es gilt:
Parameter Bedeutung
savit
0 = Mausform wiederherstellen
1 = Mausform sichern
mf Speicherbereich zur Sicherung der Mausform
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: XCONTROL-Funktionen
Querverweis: graf_mouse   XCONTROL

9.1.3.7 Popup

Name: »Popup« - Verwaltung eines Popup-Menüs
Deklaration: int16_t cdecl (*Popup) (int8_t *items[], int16_t num_items, int16_t default_item, int16_t font_size, GRECT *button, GRECT *world);
Beschreibung: Die Funktion ermöglicht die komplette Verwaltung eines Popup-Menüs. Es gilt:
Parameter Bedeutung
items Array mit Zeichenketten für die einzelnen Einträge. Jeder Eintrag muss die gleiche Länge besitzen, sowie vorne mindestens zwei und am Ende mindestens ein Leerzeichen aufweisen.
num_items Anzahl der Einträge
default_item Default-Eintrag (Zählung beginnt bei 0), oder der Wert -1
font_size Zeichengröße: 8*16 oder 8*8-Font. Als Parameter sind die gleichen Werte wie in der TEDINFO-Struktur zu verwenden. Laut Atari wird z.Zt. nur der große Zeichensatz verwendet.
button Rechteck des Buttons, zu dem das Popup gehört.
world Rechteck des Hintergrund-Objekbaumes (i.d.R. der Objektbaum der CPX)


Hinweis: Bei zu vielen Einträgen (ab fünf) wird das Popup automatisch gescrollt; die Bearbeitung blockiert alle anderen Aktionen.
Ergebnis: Die Funktion liefert den gewählten Eintrag des Popups zurück, oder den Wert -1, wenn kein Element des Popups ausgewählt worden ist.
Gruppe: XCONTROL-Funktionen
Querverweis: Xform_do   XCONTROL

9.1.3.8 rsh_fix

Name: »rsh_fix« - Umwandlung eines Objektbaumes
Deklaration: VOID cdecl (*rsh_fix) (int16_t num_objs, int16_t num_frstr, int16_t num_frimg, int16_t num_tree, OBJECT *rs_object, TEDINFO *rs_tedinfo, int8_t *rs_string[], ICONBLK *rs_iconblk, BITBLK *rs_bitblk, int32_t *rs_frstr, int32_t *rs_frimg, int32_t *rs_trindex, struct foobar *rs_imdope);
Beschreibung: Die Funktion wandelt einen Objektbaum auf Basis von 8*16 Pixel großen Zeichen. Es gilt:

Parameter Bedeutung
num_objs Gesamtzahl der Objekte
num_frstr Gesamtzahl der Strings
num_frimg Gesamtzahl der Images
num_tree Gesamtzahl der Objektbäume
rs_object  
rs_tedinfo  
rs_string  
rs_iconblk  
rs_bitblk  
rs_frstr  
rs_frimg  
tr_trindex  
rs_imdope  


Hinweis: Die CPX hat somit unter allen Auflösungen die gleiche Pixelgröße. Bei der Arbeit mit einem RCS sollte man daher ebenfalls einen Grafikmodus mit 8*16 Pixel großen Zeichen wählen.

Die Koordinaten-Umwandlung darf natürlich nur ein einziges Mal stattfinden - XControl stellt dazu in der XCPB-Struktur das Flag 'SkipRshFix' zur Verfügung.
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: XCONTROL-Funktionen
Querverweis: rsh_obfix   XCONTROL

9.1.3.9 rsh_obfix

Name: »rsh_obfix« - Umwandlung eines Objektes
Deklaration: VOID cdecl (*rsh_obfix) (OBJECT *tree, int16_t curob);
Beschreibung: Die Funktion konvertiert die Größe und Position eines Objektes von einer Zeichendarstellung in die Pixeldarstellung. Es gilt:

Parameter Bedeutung
tree Adresse des Objektbaumes
curob zu konvertierendes Objekt
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: XCONTROL-Funktionen
Querverweis: rsh_fix   rsrc_obfix   XCONTROL

9.1.3.10 Set_Evnt_Mask

Name: »Set_Evnt_Mask« - Festlegen der Ereignis Maske
Deklaration: VOID cdecl (*Set_Evnt_Mask) (int16_t mask, MOBLK *m1, MOBLK *m2, int32_t time);
Beschreibung: Die Funktion legt fest, auf welche Ereignisse die CPX reagieren soll. Es gilt:

Parameter Bedeutung
mask erlaubte Events (analog evnt_multi)
m1 Mausrechteck und -richtung
m2 Mausrechteck und -richtung
time Zeit in Millisekunden für Timer-Event
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: XCONTROL-Funktionen
Querverweis: XCONTROL

9.1.3.11 Sl_arrow

Name: »Sl_arrow« - Behandlung des Sliderarrows
Deklaration: VOID cdecl (*Sl_arrow) (OBJECT *tree, int16_t base, int16_t slider, int16_t obj, int16_t inc, int16_t min, int16_t max, int16_t *value, int16_t direction, VOID (*foo) (VOID));
Beschreibung: Die Funktion ist aufzurufen, sobald der Pfeil eines Sliders angeklickt wird. Es gilt:
Parameter Bedeutung
tree Adresse des Objektbaumes
base Basisobjekt
slider Slider (Child des Basisobjektes)
obj Pfeil der angeklickt wurde
inc Anzahl der Einheiten die addiert bzw. subtrahiert werden sollen
min Minimalwert der angenommen werden kann
max Maximalwert der angenommen werden kann
value Adresse für aktuellen Wert
direction Richtung
0 = vertikal
1 = horizontal
foo Adresse einer Funktion (analog zu Sl_x, bzw. Sl_y).
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: XCONTROL-Funktionen
Querverweis: Sl_dragx   Sl_dragy   XCONTROL

9.1.3.12 Sl_dragx

Name: »Sl_dragx« - Draggen eines Sliders
Deklaration: VOID cdecl (*Sl_dragx) (OBJECT *tree, int16_t base, int16_t slider, int16_t min, int16_t max, int16_t *value, VOID (*foo) (VOID));
Beschreibung: Die Funktion verwaltet die Bewegung des horizontalen Sliders. Es gilt:

Parameter Bedeutung
tree Adresse des Objektbaumes
base Basisobjekt
slider Slider (Child des Basisobjektes)
min Minimalwert der angenommen werden kann
max Maximalwert der angenommen werden kann
value Adresse für aktuellen Wert
foo Adresse einer Funktion analog zu Sl_x
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: XCONTROL-Funktionen
Querverweis: Sl_dragy   XCONTROL

9.1.3.13 Sl_dragy

Name: »Sl_dragy« - Draggen eines Sliders
Deklaration: VOID cdecl (*Sl_dragy) (OBJECT *tree, int16_t base, int16_t slider, int16_t min, int16_t max, int16_t *value, VOID (*foo) (VOID));
Beschreibung: Die Funktion verwaltet die Bewegung des horizontalen Sliders. Es gilt:

Parameter Bedeutung
tree Adresse des Objektbaumes
base Basisobjekt
slider Slider (Child des Basisobjektes)
min Minimalwert der angenommen werden kann
max Maximalwert der angenommen werden kann
value Adresse für aktuellen Wert
foo Adresse einer Funktion analog zu Sl_y
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: XCONTROL-Funktionen
Querverweis: Sl_dragx   XCONTROL

9.1.3.14 Sl_size

Name: »Sl_size« - Größe des Sliders festlegen
Deklaration: VOID cdecl (*Sl_size) (OBJECT *tree, int16_t base, int16_t slider, int16_t num_items, int16_t visible, int16_t direction, int16_t min_size);
Beschreibung: Die Funktion stellt die Größe des Sliders ein. Es gilt:
Parameter Bedeutung
tree Adresse des Objektbaumes
base Basisobjekt
slider Slider (Child des Basisobjektes)
num_items Anzahl der vorhandenen Elemente
visible Anzahl der sichtbaren Elemente
direction Richtung
0 = vertical
1 = horizontal
min_size Minimalgröße des Sliders in Pixeln


Hinweis: Die Funktion wird benötigt, um die Relation der dargestellten Datenmenge zur vorhandenen zu erhalten.
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: XCONTROL-Funktionen
Querverweis: Sl_dragx   Sl_dragy   Sl_x   Sl_y   XCONTROL

9.1.3.15 Sl_x

Name: »Sl_x« - Positionierung eines Sliders
Deklaration: VOID cdecl (*Sl_x) (OBJECT *tree, int16_t base, int16_t slider, int16_t value, int16_t min, int16_t max, VOID (*foo) (VOID));
Beschreibung: Die Funktion positioniert den Slider innerhalb eines Basisobjektes in horizontaler Richtung. Es gilt:
Parameter Bedeutung
tree Adresse des Objektbaumes
base Basisobjekt
slider Slider (Child des Basisobjektes)
value neuer Wert, den der Slider repräsentieren soll
min Minimalwert den value annehmen darf
max Maximalwert den value annehmen darf
foo Adresse einer Funktion (oder NULL), die gleichzeitig mit der Slider-Neupositionierung aufgerufen wird; so lassen sich die Sliderbewegungen ausnutzen, um auch die angezeigten Werte zu erneuern.
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: XCONTROL-Funktionen
Querverweis: Sl_y   XCONTROL

9.1.3.16 Sl_y

Name: »Sl_y« - Positionierung eines Sliders
Deklaration: VOID cdecl (*Sl_y) (OBJECT *tree, int16_t base, int16_t slider, int16_t value, int16_t min, int16_t max, VOID (*foo) (VOID));
Beschreibung: Die Funktion positioniert den Slider innerhalb eines Basisobjektes in vertikaler Richtung. Es gilt:
Parameter Bedeutung
tree Adresse des Objektbaumes
base Basisobjekt
slider Slider (Child des Basisobjektes)
value neuer Wert, den der Slider repräsentieren soll
min Minimalwert den value annehmen darf
max Maximalwert den value annehmen darf
foo Adresse einer Funktion (oder NULL), die gleichzeitig mit der Slider-Neupositionierung aufgerufen wird; so lassen sich die Sliderbewegungen ausnutzen, um auch die angezeigten Werte zu erneuern.
Ergebnis: Die Funktion liefert kein Ergebnis.
Gruppe: XCONTROL-Funktionen
Querverweis: Sl_x   XCONTROL

9.1.3.17 Xform_do

Name: »Xform_do« - Verwaltung eines Formulars
Deklaration: int16_t cdecl (*Xform_do) (OBJECT *tree, int16_t startob, int16_t *puntmsg);
Beschreibung: Die Funktion übernimmt die Verwaltung eines Formulars, sowie (in geringem Umfang) die Bearbeitung von AES Nachrichten. Es gilt:

Parameter Bedeutung
tree Adresse des Objektbaumes
startob Startobjekt
puntmsg Mitteilungs-Puffer


Hinweis: Unter COPS kann die CPX einen bis zu 512*384 Pixel großen Objektbaum zeichnen und an diese Funktion übergeben.
Ergebnis: Die Funktion liefert einen der folgenden Werte zurück:
-1: puntmsg enthält eine Nachricht, die auszuwerten ist:
WM_REDRAW: die CPX muß solche Objekte selbst neuzeichnen, die nicht zum Objektbaum gehören. Die Rechteckliste kann über die Funktionen GetFirstRect und GetNextRect ermittelt werden.
AC_CLOSE:
WM_CLOSE: Die CPX wurde beendet; reservierter Speicher ist sofort freizugeben. AC_CLOSE ist als 'Abbruch', WM_CLOSE als 'Ok' zu werten.
CT_KEY: spezielle Nachricht, die das Auswerten von Tastendrücken erlaubt, sofern diese keine Auswirkungen auf EDIT-Felder haben können.

puntmsg[3] Highbyte : Scan-Code der Taste
puntmsg[3] Lowbyte : ASCII-Code der Taste
sonst: Nummer des angeklickten Objektes (ein Doppelklick wird im oberen Bit gekennzeichnet).
Gruppe: XCONTROL-Funktionen
Querverweis: form_do   form_xdo   Rechteckliste eines Fensters

9.1.3.18 XGen_Alert

Name: »XGen_Alert« - Anzeigen einer Alarmbox
Deklaration: int16_t cdecl (*XGen_Alert) (int16_t id);
Beschreibung: Die Funktion ermöglicht das Anzeigen einer einfachen Alarmbox. Es gilt:

Parameter Bedeutung
id Art der Meldung
   0 = "Voreinstellungen sichern?"
   1 = "Fehler bei Speicheranforderung!"
   2 = "Fehler beim Schreiben/Lesen von Dateien"
   3 = "Datei nicht gefunden"


Hinweis: Weitere Alarmboxen müssen selbst definiert werden. Hierzu bietet sich form_alert jedoch nicht an, da es die Alarmbox bezüglich der vollen Bildschirmfläche und nicht bezüglich des XControl-Fensters zentriert.
Ergebnis: Die Funktion liefert einen der folgenden Werte zurück:
   0 : Abbruch bzw. Cancel wurde angeklickt.
<> 0 : Ok wurde angeklickt (falls eine Alarmbox nur einen Button hat, so ist es der Ok-Button)
Gruppe: XCONTROL-Funktionen
Querverweis: form_alert   XCONTROL

HomeXCONTROLXCONTROLProgrammierrichtlinen