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:

die erste Funktion im TEXT-Segment muß die Initialisierungsroutine für die CPX sein
zur Konstruktion eines CPX-Headers gibt es mehrere Toolkits
Header und gelinkte Programmdatei können in den meisten UNIX-ähnlichen Shells (z.B. der Mupfel aus Gemini) mit dem Kommando 'cat' zusammengefügt werden.
bei der CPX-Entwicklung ist es sehr praktisch, daß man XControl auch als Programm starten kann (Suffix ändern !). Dies erlaubt es, ohne permanentes Neu-Booten des Rechners zu arbeiten.
CPX-ID und -Versionsnummer sorgen dafür, daß jede CPX nur ein einziges mal (und auch nur die neueste Version) erscheint.

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:

Resourcen statisch einbinden
Speicheranforderungen nur kurzzeitig erlauben
virtuelle VDI-Workstations nicht dauerhaft anlegen

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

CPX-Funktionen
XCONTROL-Funktionen

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:

reservierter Speicher ist möglichst schnell wieder freizugeben
XControl-Funktionen sind immer auszunutzen, wenn dies möglich ist
die Benutzerschnittstelle ist einfach und in Anlehnung an die anderen CPX-Module zu gestalten
grafische Elemente sind Menükommandos vorzuziehen
'OK' und 'Abbruch' sind (wenn möglich) immer zu implementieren
Popup-Menüs sind als Text mit schattiertem Rechteck darzustellen
AC_CLOSE (Verlassen des Hauptprogramms) wird als 'Abbruch' gewertet
WM_CLOSE (Schließen des XControl-Fensters) wird als 'OK' gewertet
'Save'/'Sichern' ist als 'OK' ohne Verlassen des Dialogs zu werten
das Wurzelobjekt der CPX hat immer eine Größe von 256*176 Pixeln. Ausnahme: Unter COPS darf der Objektbaum eine Größe von bis zu 512*384 Pixeln besitzen.
Interrupt-Vektoren dürfen nicht verändert werden
Xform_do darf nicht mit Funktionen für Event-CPX vermischt werden
reservierter Speicher darf beim Verlassen der CPX nicht vergessen werden, da es sonst zu einer Fragmentierung des Speichers kommt
bereits von anderen CPX verwandte ID's dürfen nicht benutzt werden
geöffnete Dateien müssen wieder geschlossen werden
geöffnete VDI-Workstations sind auf jedenfall wieder zu schließen (spätestens bei einer AC_CLOSE bzw. WM_CLOSE Meldung), wenn sie nicht mehr benötigt werden

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

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: 816 oder 88-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

XCONTROL

Programmierrichtlinen