HomeAESFileselektorenGrafikfunktionen

8.11 Formularfunktionen

Diese Bibliothek enthält nützliche Funktionen zur Verarbeitung von Dialog- bzw. Alarmboxen aller Art. Für diesen Zweck stehen die folgenden Routinen zur Verfügung:

form_alert Alertbox darstellen.
form_button Simulieren eines Mausklicks.
form_center Zentrieren eines Objektes.
form_dial Bildschirmspeicher reservieren und freigeben.
form_do Behandlung eines Dialogs.
form_error Betriebssystemfehlermeldung ausgeben.
form_keybd Auswerten einer Tastatureingabe.
form_popup Verwaltung eines Popup-Menüs.
form_wbutton Simulieren eines Mausklicks (im Fenster).
form_wkeybd Auswerten einer Tastatureingabe (im Fenster).
form_xdial Bildschirmspeicher reservieren/freigeben (Flydials).
form_xdo Erweiterte Dialogbehandlung.
form_xerr Betriebssystemfehlermeldung ausgeben.
xfrm_popup Verwaltung eines Popup-Menüs, erweiterte Version
x_form_center Zentrieren eines Objektes.
x_form_error Betriebssystemfehlermeldung ausgeben.

Hinweis: Einige dieser Funktionen sind nur unter MagiC vorhanden, und bieten viel zusätzlichen Komfort (z.B. verschiebbare Dialogboxen).

Querverweis: Dialogboxen   Style-Guidelines   Scrollende Eingabefelder

8.11.1 form_alert

Name: »Form alert box« - zeichnet eine Alarmbox.
AES-Nummer: 52
Deklaration: int16_t form_alert ( int16_t fo_adefbttn, CONST int8_t *fo_astring );
Beschreibung: Die Funktion stellt eine Alarmbox auf dem Bildschirm dar und gibt die Nummer des Buttons zurück, mit dem die Alarmbox verlassen wurde. Der Bildschirmhintergrund wird dabei vom AES gesichert.

Der Parameter fo_adefbttn bestimmt die Nummer des Defaultbuttons der darzustellenden Alarmbox. Es gilt:

Wert Bedeutung
0 kein Defaultbutton
1 erster Button
2 zweiter Button
3 dritter Button


Der Parameter fo_astring ist ein Zeiger auf den String, der das Aussehen der Alarmbox bestimmt. Das verwendete Format ist "[n][lines][buttons]" wobei n die Nummer des einzublendenden Icons ist:
n Bedeutung Symbole
   
0 kein Icon  
1 Ausrufezeichen

2 Fragezeichen

3 Stopschild

4 Info-Icon, ab AES 4.10

5 Diskettensymbol, ab AES 4.10

6 Bombe, XaAES


Hinweis: Die zur Verfügung stehenden Icons sollten nicht willkürlich eingesetzt werden, sondern zur jeweiligen Situation passen, d.h:
  • das Ausrufezeichen sollte für alle Arten von Mitteilungen benutzt werden, die der Benutzer nur kurz bestätigen soll.

  • das Fragezeichen dient für alle Abfragen, die vor einer Aktion ausgeführt werden sollten (z.B. das Löschen einer Datei).

  • das Stopschild sollte bei wichtigen Problemen eingesetzt werden, die der Benutzer unbedingt zur Kenntnis nehmen muss.



Die Komponente lines beschreibt die einzelnen Textzeilen. Es sind höchstens fünf Textzeilen mit maximal 30 Zeichen, die durch das Zeichen '|' getrennt werden, erlaubt.

Die Komponente buttons beschreibt die Texte für höchstens drei Buttons, die durch das Zeichen '|' getrennt werden.
MagiC:

Aufgrund der Kompatibilität zu GEM/3 können Alertboxen hier bis zu 40 Zeichen pro Textzeile, und 20 Zeichen pro Button enthalten. Darüberhinaus sind alle Alertboxen komplett über die Tastatur bedienbar, mit der Funktionstaste F1 den linken, F2 den mittleren und mit F3 den rechten Button.

ViewMAX/2

and later parse the "default button" parameter as two bytes; the low byte is the default button and the high byte is the cancel button (ESC is a shortcut for it). This style of parameter will crash earlier GEM versions.

Under Geneva,

the alert string can contain left bracket ("[") characters within the text of the buttons. These denote the keyboard equivalents to be used for the buttons. For example, this defines an alert with the equivalents [Alternate][H] and [Alternate][Y]:

form_alert( 1, "[1][Hi there!][[Hi!|B[ye!]" );

If an alert button does not contain a pre-defined keyboard equivalent, it will be considered for an automatic keyboard equivalent.

Note:DO NOT use this type of alert string when running without Geneva, as this will have unpredictable results.

Additionally, if an alert would normally not have a default button, Geneva always forces the rightmost button to be the default. For example:

form_alert( 2, "[1][Hi!][OK]" ); /* OK is the default */

Ergebnis: Als Ergebnis wird die Nummer des Buttons geliefert, mit dem die Alertbox verlassen wurde; dabei besitzt der ganz links stehende Button den Wert 1.
Verfügbar: In allen AES Versionen.
Gruppe: Formulare
Querverweis: Binding

8.11.1.1 Bindings für form_alert

C: int16_t form_alert ( int16_t fo_adefbttn, CONST int8_t *fo_astring );
Umsetzung:
int16_t form_alert (int16_t fo_adefbttn, CONST int8_t *fo_astring)
{
   int_in[0]  = fo_adefbttn;
   addr_in[0] = fo_astring;

   return ( crys_if(52) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 52 # Opcode der Funktion
control+2 control[1] 1 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] fo_adefbttn
addr_in addr_in[0] fo_astring
int_out int_out[0] Return-Wert

8.11.2 form_button

Name: »Form Button« - simuliert das Anklicken eines Objektes
AES-Nummer: 56
Deklaration: int16_t form_button ( OBJECT *fo_btree, int16_t fo_bobject, int16_t fo_bclicks, int16_t *fo_bnxtobj );
Beschreibung: Die Funktion simuliert das Anklicken eines Objektes. Es gilt:
Parameter Bedeutung
   
fo_btree Adresse des Objektbaumes
fo_bobject zu bearbeitendes Objekt
fo_bclicks Anzahl der Mausklicks
fo_bnxtobj neues aktuelles Objekt, oder 0, falls das nächste Objekt den Status HIDDEN oder DISABLED besitzt bzw. nicht editierbar ist.


Hinweis: Bei einem Doppelklick auf ein Objekt mit TOUCHEXIT, wird im Parameter fo_bnxtobj Bit-15 gesetzt. Die Rechteckliste wird von dieser Funktion nicht beachtet.
Ergebnis: Der Rückgabewert der Funktion ist Null, falls ein Exitobjekt selektiert wurde, sonst ist er positiv.
Verfügbar: All AES versions.
Gruppe: Formulare
Querverweis: Binding   OBJECT   evnt_multi   form_keybd

8.11.2.1 Bindings für form_button

C: int16_t form_button ( OBJECT *fo_btree, int16_t fo_bobject, int16_t fo_bclicks, int16_t *fo_bnxtobj );
Umsetzung:
int16_t form_button (OBJECT *fo_btree, int16_t fo_bobject,
                     int16_t fo_bclicks, int16_t *fo_bnxtobj)
{
   int_in[0]  = fo_bobject;
   int_in[1]  = fo_bclicks;
   addr_in[0] = fo_btree;

   crys_if (56);

   *fo_bnxtobj = int_out[1];
   return ( int_out[0] );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 56 # Opcode der Funktion
control+2 control[1] 2 # Einträge in int_in
control+4 control[2] 2 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] fo_bobject
int_in+2 int_in[1] fo_bclicks
addr_in addr_in[0] fo_btree
int_out int_out[0] Return-Wert
int_out+2 int_out[1] fo_bnxtobj

8.11.3 form_center

Name: »Form centered Object« - zentriert ein Objekt auf dem Bildschirm.
AES-Nummer: 54
Deklaration: int16_t form_center ( OBJECT *fo_ctree, int16_t *fo_cx, int16_t *fo_cy, int16_t *fo_cw, int16_t *fo_ch );
Beschreibung: Die Funktion zentriert ein Objekt in der Bildschirmmitte, und liefert die tatsächliche Position des Objektes zurück. Es gilt:

Parameter Bedeutung
fo_ctree Adresse des Objektbaumes
fo_cx x-Koordinate
fo_cy y-Koordinate
fo_cw Breite
fo_ch Höhe (jeweils zentriert)


Hinweis: Die Funktion berücksichtigt auch spezielle Attribute des Objektes, wie z.B. OUTLINED (nicht jedoch SHADOWED).

Ab PC-GEM/3 wird der Objektbaum in y-Richtung nicht mehr auf dem ganzen Bildschirm zentriert. Begründet wurde dies damit, dass ein Benutzer auf Großbildschirmen ansonsten einen zu weiten Weg von der Menüzeile bis zum Objekt (etwa einer Dialogbox) zurücklegen muss.
Ergebnis: Als Ergebnis wird immer eine 1 zurückgegeben.
Verfügbar: All AES versions.
Gruppe: Formulare
Querverweis: Binding   x_form_center   OBJECT   objc_offset

8.11.3.1 Bindings für form_center

C: int16_t form_center ( OBJECT *fo_ctree, int16_t *fo_cx, int16_t *fo_cy, int16_t *fo_cw, int16_t *fo_ch );
Umsetzung:
int16_t form_center (OBJECT *fo_ctree, int16_t *fo_cx,
                     int16_t *fo_cy, int16_t *fo_cw,
                     int16_t *fo_ch)
{
   addr_in[0] = fo_ctree;

   crys_if (54);

   *fo_cx = int_out[1];
   *fo_cy = int_out[2];
   *fo_cw = int_out[3];
   *fo_ch = int_out[4];

   return (int_out[0]);
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 54 # Opcode der Funktion
control+2 control[1] 0 # Einträge in int_in
control+4 control[2] 5 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
addr_in addr_in[0] fo_ctree
int_out int_out[0] Return-Wert
int_out+2 int_out[1] fo_cx
int_out+4 int_out[2] fo_cy
int_out+6 int_out[3] fo_cw
int_out+8 int_out[4] fo_ch

8.11.4 form_dial

Name: »Form Dialog Space« - reserviert oder gibt Speicherplatz frei für ein Dialogobjekt.
AES-Nummer: 51
Deklaration: int16_t form_dial ( int16_t fo_diflag, int16_t fo_dilittlx, int16_t fo_dilittly, int16_t fo_dilittlw, int16_t fo_dilittlh, int16_t fo_dibigx, int16_t fo_dibigy, int16_t fo_dibigw, int16_t fo_dibigh );
Beschreibung: Die Funktion übernimmt abhängig von den übergebenen Parametern verschiedene Aufgaben. Es gilt:
Parameter Bedeutung
   
fo_diflag Auszuführende Aktion:
0 = FMD_START Bildschirmausschnitt reservieren.
1 = FMD_GROW zeichnet mehrere sich ausdehnende Rechtecke
2 = FMD_SHRINK zeichnet mehrere schrumpfende Rechtecke
3 = FMD_FINISH gibt den reservierten Bildschirmausschnitt wieder frei
1000 = X_FMD_START (Geneva)
Store the information in the rectangular screen area described by the "fo_dibig" parameters for restoration later. If there is insufficient free memory for the area to be saved, then form_dial will return a 0 (error) condition.
1003 = X_FMD_FINISH (Geneva)
Copy back the information previously saved with X_FMD_START. This MUST be done whenever X_FMD_START is used, but not if an error occurred during the X_FMD_START.
fo_dilittlx x-Koordinate
fo_dilittly y-Koordinate
fo_dilittlw Breite
fo_dilittlh Höhe des kleinsten Rechteckes
fo_dibigx x-Koordinate
fo_dibigy y-Koordinate
fo_dibigw Breite
fo_dibigh Höhe des größten Rechteckes


Hinweis: Durch den Opcode FMD_FINISH erhalten alle betroffenen Fenster vom AES eine WM_REDRAW Nachricht. Die Menüzeile kann auf diese Art jedoch nicht restauriert werden, da sie außerhalb des Arbeitsbereichs des Desktop-Fensters liegt.

Die Opcodes FMD_GROW und FMD_SHRINK sind in PC-GEM Version 2.0 den Rechtsstreitigkeiten zwischen Apple und Digital Research zum Opfer gefallen.
Ergebnis: Ein Fehler ist nur dann aufgetreten, wenn als Ergebnis 0 zurückgegeben wird.
Verfügbar: In allen AES Versionen.
Gruppe: Formulare
Querverweis: Binding   evnt_mesag   form_xdial   graf_growbox   graf_shrinkbox

8.11.4.1 Bindings für form_dial

C: int16_t form_dial ( int16_t fo_diflag, int16_t fo_dilittlx, int16_t fo_dilittly, int16_t fo_dilittlw, int16_t fo_dilittlh, int16_t fo_dibigx, int16_t fo_dibigy, int16_t fo_dibigw, int16_t fo_dibigh );
Umsetzung:
int16_t form_dial (int16_t fo_diflag, int16_t fo_dilittlx,
                   int16_t fo_dilittly, int16_t fo_dilittlw,
                   int16_t fo_dilittlh, int16_t fo_dibigx,
                   int16_t fo_dibigy, int16_t fo_dibigw,
                   int16_t fo_dibigh)
{
   int_in[0]  = fo_diflag;
   int_in[1]  = fo_dilittlx;
   int_in[2]  = fo_dilittly;
   int_in[3]  = fo_dilittlw;
   int_in[4]  = fo_dilittlh;
   int_in[5]  = fo_dibigx;
   int_in[6]  = fo_dibigy;
   int_in[7]  = fo_dibigw;
   int_in[8]  = fo_dibigh;

   return ( crys_if(51) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 51 # Opcode der Funktion
control+2 control[1] 9 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 0 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] fo_diflag
int_in+2 int_in[1] fo_dilittlx
int_in+4 int_in[2] fo_dilittly
int_in+6 int_in[3] fo_dilittlw
int_in+8 int_in[4] fo_dilittlh
int_in+10 int_in[5] fo_dibigx
int_in+12 int_in[6] fo_dibigy
int_in+14 int_in[7] fo_dibigw
int_in+16 int_in[8] fo_dibigh
int_out int_out[0] Return-Wert

8.11.5 form_do

Name: »Form do Dialog« - führt den Dialog mit dem Anwender durch.
AES-Nummer: 50
Deklaration: int16_t form_do ( OBJECT *fo_dotree, int16_t fo_dostartob );
Beschreibung: Die Funktion übernimmt die Behandlung von Benutzeraktionen in einem Formular. Es gilt:
Parameter Bedeutung
   
fo_dotree Zeiger auf den Objektbaum der Dialogbox
fo_dostartob Nummer des Editobjekts, wo sich zu Dialogbeginn der Textcursor befinden soll (0 falls der Objektbaum kein Editobjekt enthält)


Hinweis: Die Funktion kehrt erst dann zurück, wenn der Benutzer ein Objekt mit EXIT- bzw. TOUCHEXIT Status aktiviert.
Ergebnis: Als Ergebnis wird der Index des Objekts zurückgegeben, mit dessen Hilfe der Dialog beendet wurde. Bei einem Doppelklick wird zusätzlich das 15. Bit gesetzt.
Verfügbar: All AES versions.
Gruppe: Formulare
Querverweis: Binding   form_xdo   OBJECT

8.11.5.1 Bindings für form_do

C: int16_t form_do ( OBJECT *fo_dotree, int16_t fo_dostartob );
Umsetzung:
int16_t form_do (OBJECT *fo_dotree, int16_t fo_dostartob)
{
   int_in[0]  = fo_dostartob;
   addr_in[0] = fo_dotree;

   return ( crys_if(50) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 50 # Opcode der Funktion
control+2 control[1] 1 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] fo_dostartob
addr_in addr_in[0] fo_dotree
int_out int_out[0] Return-Wert

8.11.6 form_error

Name: »Form Error« - stellt eine Fehlerbox für TOS-Fehler dar.
AES-Nummer: 53
Deklaration: int16_t form_error ( int16_t fo_enum );
Beschreibung: Die Funktion gibt eine MS-DOS Fehlernummer im Klartext (d.h. in einer Alertbox) aus.

Der Parameter fo_enum ist dabei die entsprechende Fehlernummer.

Hinweis: Diese Funktion ist aus Kompatibilitätsgründen zum PC-GEM vorhanden. Auf TOS-Systemen muß daher zunächst die GEMDOS-Fehlernummer auf die MS-DOS Codierung umgerechnet werden. Für die Umrechnung (GEMDOS -> MS-DOS) kann z.B. die folgende Formel benutzt werden: ( fo_enum) - 30.

In N.AES gibt es einer erweiterte Form von form_error mit allen GEMDOS-Fehlercodes. Deren vorhandensein kann mit appl_getinfo (Opcode 64) festgestellt werden.

Geneva interpreted a negative number as a GEMDOS/BIOS error code, and an appropriate error message is displayed. For instance, the call:
form_error(-33);
produces an alert with the text "There is no file with this name".
Ergebnis: Als Ergebnis wird die Nummer (1-3) der ausgewählten Option zurückgegeben. Bei jetzigen GEM-Versionen steht jedoch nur eine Option zur Verfügung.
Verfügbar: In allen AES Versionen.
Gruppe: Formulare
Querverweis: Binding   form_xerr   form_error in N.AES

8.11.6.1 Bindings für form_error

C: int16_t form_error ( int16_t fo_enum );
Umsetzung:
int16_t form_error (int16_t fo_enum)
{
   int_in[0] = fo_enum;
   return ( crys_if(53) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 53 # Opcode der Funktion
control+2 control[1] 1 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 0 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] fo_enum
int_out int_out[0] Return-Wert

8.11.7 form_keybd

Name: »Form Keyboard« - Nimmt Tastatureingaben in ein Formular vor.
AES-Nummer: 55
Deklaration: int16_t form_keybd ( OBJECT *fo_ktree, int16_t fo_kobject, int16_t fo_kobnext, int16_t fo_kchar, int16_t *fo_knxtobject, int16_t *fo_knxtchar );
Beschreibung: Die Funktion übernimmt Tastatureingaben in ein Formular. Es gilt:
Parameter Bedeutung
   
fo_ktree Adresse des Objektbaumes
fo_kobject Nummer des Edit-Objektes
fo_kobnext unbenutzt, sollte 0 sein
fo_kchar eingegebenes Zeichen
fo_knxtobject Edit-Objekt für nächsten Aufruf
fo_knxtchar 0 = Zeichen war Cursortaste, Tabulator oder Return
>0 = übergebenes Zeichen


Bei der Eingabe wird ggfs. das Edit-Objekt geändert (Cursortasten oder Tabulator), oder das Default-Objekt selektiert (Return).

Hinweis zu MagiC, N.AES: Wird als Objektnummer der Wert 0x8765 angegeben, so werden Tasten verarbeitet, die zusammen mit der Alternate-Taste betätigt wurden. Falls ein passendes Objekt gefunden wurde, wird der Wert 1 zurückgegeben, das Zeichen gelöscht, und in fo_knxtobject die zugehörige Objektnummer übergeben.
Ergebnis: Der Rückgabewert der Funktion ist Null, falls ein Exitobjekt gewählt wurde, sonst ist er positiv.
Verfügbar: All AES versions.
Gruppe: Formulare
Querverweis: Binding   OBJECT   objc_edit   form_button   form_wkeybd

8.11.7.1 Bindings für form_keybd

C: int16_t form_keybd ( OBJECT *fo_ktree, int16_t fo_kobject, int16_t fo_kobnext, int16_t fo_kchar, int16_t *fo_knxtobject, int16_t *fo_knxtchar );
Umsetzung:
int16_t form_keybd (OBJECT *fo_ktree, int16_t fo_kobject,
                    int16_t fo_kobnext, int16_t fo_kchar,
                    int16_t *fo_knxtobject, int16_t *fo_knxtchar)
{
   int_in[0]  = fo_kobject;
   int_in[1]  = fo_kchar;
   int_in[2]  = fo_kobnext;
   addr_in[0] = fo_ktree;

   crys_if (55);

   *fo_knxtobject = int_out[1];
   *fo_knxtchar   = int_out[2];

   return ( int_out[0] );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 55 # Opcode der Funktion
control+2 control[1] 3 # Einträge in int_in
control+4 control[2] 3 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] fo_kobject
int_in+2 int_in[1] fo_kchar
int_in+4 int_in[2] fo_kobnext
addr_in addr_in[0] fo_ktree
int_out int_out[0] Return-Wert
int_out+2 int_out[1] fo_knxtobject
int_out+4 int_out[2] fo_knxtchar

8.11.8 form_popup

Name: »Form Popup« - verwaltet ein Popup-Menü
AES-Nummer: 135
Deklaration: int16_t form_popup ( OBJECT *tree, int16_t x, int16_t y );
Beschreibung: Die Funktion stellt ein Popup-Menü auf dem Bildschirm dar, und übernimmt dessen Verwaltung. Es gilt:
Parameter Bedeutung
   
tree Adresse des Objektbaumes
x x-Koordinate
y y-Koordinate, um die die Box zentriert werden soll.


Hinweis: Falls die Parameter x und y den Wert 0 besitzen, werden die entsprechenden Werte aus der Objektstruktur beachtet, und das zentrieren entfällt. Es wird immer dafür gesorgt, daß das Popup vollständig auf dem Bildschirm liegt.

Wählbare Objekte müssen den Status SELECTABLE, nicht wählbare Objekte den Status DISABLED erhalten. Das Objekt mit der Nummer 0 im Objektbaum, sollte den Typ G_BOX oder G_IBOX besitzen.
Ergebnis: Die Funktion liefert die Nummer des gewählten Objektes aus dem Popup-Menü oder den Wert -1.
Verfügbar: Seit MagiC 1.11, kann aber auch per appl_getinfo (Opcode 9) abgefragt werden, da andere System die Funktion auch kennen.
Gruppe: Formulare
Querverweis: Binding   OBJECT   xfrm_popup

8.11.8.1 Bindings für form_popup

C: int16_t form_popup ( OBJECT *tree, int16_t x, int16_t y );
Umsetzung:
int16_t form_popup (OBJECT *tree, int16_t x, int16_t y)
{
   int_in[0]  = x;
   int_in[1]  = y;
   addr_in[0] = tree;

   return ( crys_if(135) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 135 # Opcode der Funktion
control+2 control[1] 2 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] x
int_in+2 int_in[1] y
addr_in addr_in[0] tree
int_out int_out[0] Return-Wert

8.11.9 form_wbutton

Name: »Form Window Button« - simuliert das Anklicken eines Objektes in einem Fenster.
AES-Nummer: 63
Deklaration: int16_t form_wbutton ( OBJECT *fo_btree, int16_t fo_bobject, int16_t fo_bclicks, int16_t *fo_bnxtobj, int16_t whandle );
Beschreibung: Die Funktion simuliert das Anklicken eines Objektes in einem Fenster. Es gilt:
Parameter Bedeutung
   
fo_btree Adresse des Objektbaumes
fo_bobject zu bearbeitendes Objekt
fo_bclicks Anzahl der Mausklicks
fo_bnxtobj neues aktuelles Objekt, oder 0, falls das nächste Objekt den Status HIDDEN oder DISABLED besitzt bzw. nicht editierbar ist.
whandle Kennung des Fensters.


Hinweis: Bei einem Doppelklick auf ein Objekt mit TOUCHEXIT, wird im Parameter fo_bnxtobj Bit-15 gesetzt.

Die Funktion entspricht im wesentlichen form_button mit dem Unterschied, dass hier die Rechteckliste eines Fensters beachtet wird. Die Funktion steht in MagiC ab Version 5.10 zur Verfügung.
Ergebnis: Der Rückgabewert der Funktion ist Null, falls ein Exitobjekt selektiert wurde, sonst ist er positiv.
Verfügbar: ab MagiC Version 5.10
Gruppe: Formulare
Querverweis: Binding   OBJECT   evnt_multi   form_keybd

8.11.9.1 Bindings für form_wbutton

C: int16_t form_wbutton ( OBJECT *fo_btree, int16_t fo_bobject, int16_t fo_bclicks, int16_t *fo_bnxtobj, int16_t whandle );
Umsetzung:
int16_t form_wbutton (OBJECT *fo_btree, int16_t fo_bobject,
                      int16_t fo_bclicks, int16_t *fo_bnxtobj,
                      int16_t whandle)
{
   int_in[0]  = fo_bobject;
   int_in[1]  = fo_bclicks;
   int_in[2]  = whandle;

   addr_in[0] = fo_btree;

   crys_if (63);

   *fo_bnxtobj = int_out[1];
   return ( int_out[0] );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 63 # Opcode der Funktion
control+2 control[1] 3 # Einträge in int_in
control+4 control[2] 2 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] fo_bobject
int_in+2 int_in[1] fo_bclicks
int_in+4 int_in[2] whandle
addr_in addr_in[0] fo_btree
int_out int_out[0] Return-Wert
int_out+2 int_out[1] fo_bnxtobj

8.11.10 form_wkeybd

Name: »Form Window Keyboard« - Nimmt Tastatureingaben in ein Formular in einem Fenster vor.
AES-Nummer: 64
Deklaration: int16_t form_wkeybd ( OBJECT *fo_ktree, int16_t fo_kobject, int16_t fo_kobnext, int16_t fo_kchar, int16_t *fo_knxtobject, int16_t *fo_knxtchar, int16_t whandle );
Beschreibung: Die Funktion übernimmt Tastatureingaben in ein Formular in einem Fenster. Es gilt:
Parameter Bedeutung
   
fo_ktree Adresse des Objektbaumes
fo_kobject Nummer des Edit-Objektes
fo_kobnext unbenutzt, sollte 0 sein
fo_kchar eingegebenes Zeichen
fo_knxtobject Edit-Objekt für nächsten Aufruf
fo_knxtchar 0 = Zeichen war Cursortaste, Tabulator oder Return
>0 = übergebenes Zeichen
whandle Kennung des Fensters.


Bei der Eingabe wird ggfs. das Edit-Objekt geändert (Cursortasten oder Tabulator), oder das Default-Objekt selektiert (Return).

Hinweis zu MagiC: Wird als Objektnummer der Wert 0x8765 angegeben, so werden Tasten verarbeitet, die zusammen mit der Alternate-Taste betätigt wurden. Falls ein passendes Objekt gefunden wurde, wird der Wert 1 zurückgegeben, das Zeichen gelöscht, und in fo_knxtobject die zugehörige Objektnummer übergeben.

Diese Funktion entspricht im wesentlichen form_keybd mit dem Unterschied, dass hier die Rechteckliste eines Fensters beachtet wird.
Ergebnis: Der Rückgabewert der Funktion ist Null, falls ein Exitobjekt gewählt wurde, sonst ist er positiv.
Verfügbar: ab MagiC Version 5.10
Gruppe: Formulare
Querverweis: Binding   OBJECT   objc_edit   form_button

8.11.10.1 Bindings für form_wkeybd

C: int16_t form_wkeybd ( OBJECT *fo_ktree, int16_t fo_kobject, int16_t fo_kobnext, int16_t fo_kchar, int16_t *fo_knxtobject, int16_t *fo_knxtchar, int16_t whandle );
Umsetzung:
int16_t form_wkeybd (OBJECT *fo_ktree, int16_t fo_kobject,
                     int16_t fo_kobnext, int16_t fo_kchar,
                     int16_t *fo_knxtobject, int16_t *fo_knxtchar,
                     int16_t whandle)
{
   int_in[0]  = fo_kobject;
   int_in[1]  = fo_kchar;
   int_in[2]  = fo_kobnext;
   int_in[3]  = whandle;

   addr_in[0] = fo_ktree;

   crys_if (64);

   *fo_knxtobject = int_out[1];
   *fo_knxtchar   = int_out[2];

   return ( int_out[0] );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 64 # Opcode der Funktion
control+2 control[1] 4 # Einträge in int_in
control+4 control[2] 3 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] fo_kobject
int_in+2 int_in[1] fo_kchar
int_in+4 int_in[2] fo_kobnext
int_in+6 int_in[3] whandle
addr_in addr_in[0] fo_ktree
int_out int_out[0] Return-Wert
int_out+2 int_out[1] fo_knxtobject
int_out+4 int_out[2] fo_knxtchar

8.11.11 form_xdial

Name: »Form XDialog Space« - reserviert oder gibt Speicherplatz frei für ein Dialogobjekt.
AES-Nummer: 51
Deklaration: int16_t form_xdial ( int16_t fo_diflag, int16_t fo_dilittlx, int16_t fo_dilittly, int16_t fo_dilittlw, int16_t fo_dilittlh, int16_t fo_dibigx, int16_t fo_dibigy, int16_t fo_dibigw, int16_t fo_dibigh, void **flydial );
Beschreibung: Die Funktion übernimmt abhängig von den übergebenen Parametern verschiedene Aufgaben. Es gilt:
Parameter Bedeutung
   
fo_diflag 0 = FMD_START reserviert Bildschirmspeicher für den Dialog.
3 = FMD_FINISH restauriert den Bildschirm und gibt den Puffer mit dem geretteten Hintergrund wieder frei.
fo_dilittlx x und y Koordinate,
fo_dilittly Breite und Höhe,
fo_dilittlw des kleinsten sich ausdehnenden bzw.
fo_dilittlh schließenden Rechtecks.
fo_dibigx x und y Koordinate,
fo_dibigy Breite und Höhe,
fo_dibigw des größten sich ausdehnenden bzw.
fo_dibigh schließenden Rechtecks.
flydial siehe unten


Hinweis: Wenn flydial ungleich 0 ist, wird getestet, ob genügend Speicher zur Verfügung steht, um den Hintergrund der Dialogbox zu retten. Ein Zeiger auf die geretteten Daten wird dann in dieser Variablen vermerkt. Falls nicht genügend Speicher zur Verfügung steht, um den Hintergrund zu retten, ist die per form_xdo zu bearbeitende Dialogbox nicht verschiebbar; in diesem Fall wird auch keine 'Flugecke' im Dialog angezeigt.
Ergebnis: Ein Fehler ist nur dann aufgetreten, wenn als Ergebnis 0 zurückgegeben wird.
Verfügbar: Das Vorhandensein der Flydials kann per appl_getinfo (Opcode 14) abgefragt werden.
Gruppe: Formulare
Querverweis: Binding   evnt_mesag   form_dial   graf_growbox   graf_shrinkbox

8.11.11.1 Bindings für form_xdial

C: int16_t form_xdial ( int16_t fo_diflag, int16_t fo_dilittlx, int16_t fo_dilittly, int16_t fo_dilittlw, int16_t fo_dilittlh, int16_t fo_dibigx, int16_t fo_dibigy, int16_t fo_dibigw, int16_t fo_dibigh, void **flydial );
Umsetzung:
int16_t form_xdial (int16_t fo_diflag, int16_t fo_dilittlx,
                    int16_t fo_dilittly, int16_t fo_dilittlw,
                    int16_t fo_dilittlh, int16_t fo_dibigx,
                    int16_t fo_dibigy, int16_t fo_dibigw,
                    int16_t fo_dibigh, void **flydial)
{
   int_in[0]  = fo_diflag;
   int_in[1]  = fo_dilittlx;
   int_in[2]  = fo_dilittly;
   int_in[3]  = fo_dilittlw;
   int_in[4]  = fo_dilittlh;
   int_in[5]  = fo_dibigx;
   int_in[6]  = fo_dibigy;
   int_in[7]  = fo_dibigw;
   int_in[8]  = fo_dibigh;
   addr_in[0] = flydial;
   addr_in[1] = 0;              /* reserviert */

   return ( crys_if(51) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 51 # Opcode der Funktion
control+2 control[1] 9 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 2 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] fo_diflag
int_in+2 int_in[1] fo_dilittlx
int_in+4 int_in[2] fo_dilittly
int_in+6 int_in[3] fo_dilittlw
int_in+8 int_in[4] fo_dilittlh
int_in+10 int_in[5] fo_dibigx
int_in+12 int_in[6] fo_dibigy
int_in+14 int_in[7] fo_dibigw
int_in+16 int_in[8] fo_dibigh
addr_in addr_in[0] flydial
addr_in+4 addr_in[1] 0
int_out int_out[0] Return-Wert

8.11.12 form_xdo

Name: »Form do XDialog« - führt einen erweiterten Dialog mit dem Anwender durch.
AES-Nummer: 50
Deklaration: int16_t form_xdo ( OBJECT *tree, int16_t startob, int16_t *lastcrsr, XDO_INF *tabs, void *flydial );
Beschreibung: Die Funktion übernimmt die Behandlung von Benutzeraktionen in einem Formular.
Parameter Bedeutung
   
tree Zeiger auf den Objektbaum der Dialogbox
startob Nummer des Editobjekts, wo sich zu Dialogbeginn der Textcursor befinden soll (0 falls der Objektbaum kein Editobjekt enthält).
lastcrsr enthält die Nummer des Objekts, in dem sich der Cursor beim Beenden des Dialogs befand.
tabs Zeiger auf Tastatur-Tabellen oder NULL
flydial der entsprechende von form_xdial gelieferte Parameter, oder NULL, wenn auf Flydials verzichtet wird.
Ergebnis: Als Ergebnis wird der Index des Objekts zurückgegeben, mit dessen Hilfe der Dialog beendet wurde.
Verfügbar: Die Funktion steht nur unter MagiC (ab Version 2.0) zur Verfügung. Das Vorhandensein der Flydials, der Tastaturtabellen sowie der Möglichkeit, die letzte Cursorposition zu erfragen, kann per appl_getinfo (Opcode 14) abgefragt werden.
Gruppe: Formulare
Querverweis: Binding   form_do

8.11.12.1 Bindings für form_xdo

C: int16_t form_xdo ( OBJECT *tree, int16_t startob, int16_t *lastcrsr, XDO_INF *tabs, void *flydial );
Umsetzung:
int16_t form_xdo (OBJECT *tree, int16_t startob, int16_t *lastcrsr,
                  XDO_INF *tabs, void *flydial)
{
   int_in[0]  = startob;
   addr_in[0] = tree;
   addr_in[1] = tabs;
   addr_in[2] = flydial;

   crys_if (50);

   *lastcrsr = int_out[1];
   return ( int_out[0] );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 50 # Opcode der Funktion
control+2 control[1] 1 # Einträge in int_in
control+4 control[2] 2 # Einträge in int_out
control+6 control[3] 3 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] startob
addr_in addr_in[0] tree
addr_in+4 addr_in[1] tabs
addr_in+8 addr_in[2] flydial
int_out int_out[0] Return-Wert
int_out+2 int_out[1] lastcrsr

8.11.13 form_xerr

Name: »Form XError« - stellt eine Fehlerbox für TOS-Fehler dar.
AES-Nummer: 136
Deklaration: int16_t form_xerr ( int32_t errcode, int8_t *errfile );
Beschreibung: Gibt eine Fehlerbox auf dem Bildschirm aus, die die übergebene Fehlernummer im Klartext beinhaltet. Im Gegensatz zu form_error entfällt jedoch eine Umrechnung vom TOS in das MSDOS Format.
Parameter Bedeutung
   
errcode normaler, negativer GEMDOS oder BIOS Fehlercode. Falls dieser EBREAK (Programmabbruch per Control-C) oder E_OK (kein Fehler) ist, wird keine Alertbox angezeigt.
errfile Pfad einer Datei, in der der Fehler aufgetreten ist. Bei einem Nullpointer wird der Parameter ignoriert; -1 bedeutet daß die Zeile "Programm gab zurück:" der Meldung vorangestellt wird.
Ergebnis: Als Ergebnis wird die Nummer (1-3) der ausgewählten Option zurückgegeben. Bei der jetzigen GEM-Version steht jedoch nur eine Option zur Verfügung.
Verfügbar: Die Funktion steht nur unter MagiC (ab Version 2.0) zur Verfügung.
Gruppe: Formulare
Querverweis: Binding   form_error

8.11.13.1 Bindings für form_xerr

C: int16_t form_xerr ( int32_t errcode, int8_t *errfile );
Umsetzung:
int16_t form_xerr (int32_t errcode, int8_t *errfile)
{
   int_in[0]  = errcode (High);
   int_in[1]  = errcode (Low);
   addr_in[0] = errfile;

   return ( crys_if(136) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 136 # Opcode der Funktion
control+2 control[1] 2 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] errcode (High)
int_in+2 int_in[1] errcode (Low)
addr_in addr_in[0] errfile
int_out int_out[0] Return-Wert

8.11.14 xfrm_popup

Name: »Form Popup« - verwaltet ein Popup-Menü
AES-Nummer: 135
Deklaration: int16_t xfrm_popup( OBJECT *tree, int16_t x, int16_t y, int16_t firstscrlob, int16_t lastscrlob, int16_t nlines, void cdecl (*init)(OBJECT *tree, int16_t scrollpos, int16_t nlines, void *param), void *param, int16_t *lastscrlpos )
Beschreibung: Die Funktion stellt ein Popup-Menü auf dem Bildschirm dar, und übernimmt dessen Verwaltung. Es gilt:
Parameter Bedeutung
   
tree Adresse des Objektbaumes
x x-Koordinate
y y-Koordinate, um die die Box zentriert werden soll.
firstscrlob Objektnummer des ersten scrollenden Objekts
lastscrlob Objektnummer des letzten scrollenden Objekts
nlines Anzahl tatsächlich vorhandener Zeilen
init Callback- Routine zum Umsetzen der Objekte. , und sind die Parameter, die an xfrm_popup übergeben wurden. gibt die aktuelle Scrollposition an. Sie liegt in: 0..(nlines-(lastscrlob-firstscrlob+1). Soll das Popup nicht scrollen, muß init == NULL übergeben werden.
param benutzerdefinierter Parameter
lastscrlpos letzte Scrollposition


Hinweis: Falls die Parameter x und y den Wert 0 besitzen, werden die entsprechenden Werte aus der Objektstruktur beachtet, und das zentrieren entfällt. Es wird immer dafür gesorgt, daß das Popup vollständig auf dem Bildschirm liegt.

Wählbare Objekte müssen den Status SELECTABLE, nicht wählbare Objekte den Status DISABLED erhalten. Das Objekt mit der Nummer 0 im Objektbaum, sollte den Typ G_BOX oder G_IBOX besitzen.

  1. Der Objektbaum wird vor dem ersten Zeichnen automatisch durch Aufruf der init()- Routine initialisiert.

  2. Die Variable braucht nicht initialisiert zu werden, das System beginnt immer bei Scrollpos 0.

  3. Die Init-Routine ist dafür verantwortlich, das erste/und/oder letzte Scrollobjekt mit einem Pfeil zu initialisieren.

  4. Die scrollenden Objekte sind .. . Die Objektnummern müssen direkt aufeinanderfolgen. Die Objekte müssen untereinander liegen und alle dieselbe Größe haben.

Ergebnis: Die Funktion liefert die Nummer des gewählten Objektes aus dem Popup-Menü oder den Wert -1.
Verfügbar: Die Funktion steht ab MagiC 5.03 zur Verfügung.
Gruppe: Formulare
Querverweis: Binding   OBJECT   form_popup

8.11.14.1 Bindings für xfrm_popup

C: int16_t xfrm_popup( OBJECT *tree, int16_t x, int16_t y, int16_t firstscrlob, int16_t lastscrlob, int16_t nlines, void cdecl (*init)(OBJECT *tree, int16_t scrollpos, int16_t nlines, void *param), void *param, int16_t *lastscrlpos )
Umsetzung:
int16_t xfrm_popup( OBJECT *tree, int16_t x, int16_t y,
                    int16_t firstscrlob, int16_t lastscrlob,
                    int16_t nlines,
                    void  cdecl (*init)(OBJECT *tree, int16_t scrollpos,
                    int16_t nlines, void *param),
                    void *param, int16_t *lastscrlpos )
{
   int_in[0]  = x;
   int_in[1]  = y;
   int_in[2]  = firstscrlob;
   int_in[3]  = lastscrlob;
   int_in[4]  = nlines;
   int_in[5]  = *lastscrlpos;
   addr_in[0] = tree;
   addr_in[1] = init;
   addr_in[2] = param;

   int_out[1] = *lastscrlpos;   /* vorbesetzen */

   crys_if(135)

   *lastscrlpos = int_out[1];
   return ( int_out[0] );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 135 # Opcode der Funktion
control+2 control[1] 6 # Einträge in int_in
control+4 control[2] 2 # Einträge in int_out
control+6 control[3] 3 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] x
int_in+2 int_in[1] y
int_in+4 int_in[2] firstscrlob
int_in+6 int_in[3] lastscrlob
int_in+8 int_in[4] nlines
int_in+10 int_in[5] lastscrlpos
addr_in addr_in[0] tree
addr_in+4 addr_in[1] init
addr_in+8 addr_in[2] param
int_out int_out[0] Return-Wert
int_out+2 int_out[1] lastscrlpos

8.11.15 x_form_center

Name: »Form centered Object« - zentriert ein Objekt auf dem Bildschirm.
AES-Nummer: 28944
Deklaration: int16_t x_form_center( OBJECT *tree, int16_t *cx, int16_t *cy, int16_t *cw, int16_t0 *ch );
Beschreibung: Center a dialog on the screen, taking into account all object attributes that can affect the outer border.

Parameter Meaning
tree Object tree being modified
cx X-coordinate of the outer rectangle
cy Y-coordinate of the outer rectangle
cw Width of the outer rectangle
ch Height of the outer rectangle


This function is essentially identical in purpose to the AES form_center call, however it takes all attributes which can affect the size of the outer border of the object tree (SHADOWED, OUTLINED, 3D effect, etc.) into consideration. The returned rectangle describes the entire area containing these effects.
Ergebnis: Als Ergebnis wird immer eine 1 zurückgegeben.
Verfügbar: Die Funktion steht nur unter Geneva zur Verfügung.
Gruppe: Formulare
Querverweis: Binding   form_center

8.11.15.1 Bindings für x_form_center

C: int16_t x_form_center( OBJECT *tree, int16_t *cx, int16_t *cy, int16_t *cw, int16_t0 *ch );
Umsetzung:
int16_t x_form_center( OBJECT *tree, int16_t *cx, int16_t *cy,
                       int16_t *cw, int16_t0 *ch )
{
   addr_in[0] = tree;

   crys_if(28944);

   *cx = int_out[1];
   *cy = int_out[2];
   *cw = int_out[3];
   *ch = int_out[4];

   return (int_out[0]);
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 28944 # Opcode der Funktion
control+2 control[1] 0 # Einträge in int_in
control+4 control[2] 5 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
addr_in addr_in[0] tree
int_out int_out[0] Return-Wert
int_out+2 int_out[1] cx
int_out+4 int_out[2] cy
int_out+6 int_out[3] cw
int_out+8 int_out[4] ch

8.11.16 x_form_error

Name: »Form Error« - stellt eine Fehlerbox für TOS-Fehler dar.
AES-Nummer: 28945
Deklaration: int16_t x_form_error ( uint8_t *fmt, int16_t errnum );
Beschreibung: This function takes the error code specified by errnum and finds an appropriate error message string. It then inserts this text into a program-defined alert string and displays an alert.

The fmt should be in standard form_alert format, with a "%s" to indicate the location where the error message should be inserted. Since an alert can contain no more than five lines of 30 characters each, and the pre-defined error messages can take up to three lines, there should be no more than two lines of text surrounding the inserted error text.

Example:
if( x_form_error( "[1][Error!|%s][Continue|Quit]", -33 ) == 1 )
  continue...
else quit...
Ergebnis: Als Ergebnis wird die Nummer (1-3) der ausgewählten Option zurückgegeben.
Verfügbar: Die Funktion steht nur unter Geneva zur Verfügung.
Gruppe: Formulare
Querverweis: Binding   form_error   form_xerr   form_err in N.AES

8.11.16.1 Bindings für x_form_error

C: int16_t x_form_error ( uint8_t *fmt, int16_t errnum );
Umsetzung:
int16_t x_form_error ( uint8_t *fmt, int16_t errnum )
{
   int_in[0] = errnum;

   adrin[0] = fmt;

   return ( crys_if(28945) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 28945 # Opcode der Funktion
control+2 control[1] 1 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
addr_in addr_in[0] fmt
int_in int_in[0] enum
int_out int_out[0] Return-Wert

HomeAESFileselektorenGrafikfunktionen