This is an old version from the tos.hyp. The new is on GitHub!

HomeAESGrundlagen des AESDateiauswahl

8.3 Applikationsfunktionen

In dieser Bibliothek sind Funktionen enthalten, um eine GEM-Applikation zu initialisieren und zu terminieren; darüber hinaus erlauben diese Routinen die Kommunikation mit anderen Prozessen. Insgesamt stehen die folgenden Funktionen zur Verfügung:

appl_bvset Angeschlossene Laufwerke setzen.
appl_control Gezieltes Steuern von Anwendungen.
appl_exit AES-Anwenderprogramm abmelden und Kennung freigeben.
appl_find AES-Kennung einer anderen AES-Applikation ermitteln.
appl_getinfo System-Informationen ermitteln.
appl_getinfo_str erweiterte System-Informationen ermitteln.
appl_getcicon Ermitteln eines CICON (Icon Server)
appl_init AES-Anwendung anmelden.
appl_options Sets or gets application options
appl_read AES-Mitteilungen lesen.
appl_search Applikationen im System suchen.
appl_tplay Ereignisse abspielen.
appl_trecord Ereignisse aufzeichnen.
appl_write AES-Mitteilungen schreiben.
appl_xbvset Extended available drive bitmaps.
appl_yield AES-Prozeß-Switch erzwingen.
_appl_yield AES-Prozeß-Switch erzwingen.
x_appl_flags Controls execution flags
x_appl_font Changes font and window borders
x_appl_sleep Puts application to sleep, or wakes it up
x_appl_term Terminate an application and remove it from memory.

Hinweis: Besondere Beachtung verdient dabei appl_getinfo, mit dessen Hilfe sich leicht Eigenschaften des Betriebssystems zur Laufzeit erfragen lassen.

Querverweis: Style-Guidelines

8.3.1 appl_bvset

Name: »Application Bitvektor-Set« - setzt die angeschlossenen logischen Laufwerke für die Dateiauswahlbox
AES-Nummer: 16
Deklaration: int16_t appl_bvset ( uint16_t bvdisk, uint16_t bvhard );
Beschreibung: Die Funktion informiert das GEM über die vorhandenen logischen Laufwerke, die u.a. für die Dateiauswahl-box (Fileselector) benötigt werden. Es gilt:

Parameter Bedeutung
bvdisk Bitvektor der vorhandenen Diskettenlaufwerke (Bit-15 = Laufwerk-A etc).
bvhard Bitvektor der vorhandenen Festplattenlaufwerke (Bit-15 = Laufwerk-A etc).


Die Werte stehen der Applikation in global[13] und global[14] zur Verfügung.

In GEM/4 and GEM/5, use appl_xbvset to access drives beyond P.
Ergebnis: Der Rückgabewert der Funktion ist z.Zt. nicht bekannt.
Verfügbar: Die Funktion steht erst ab PC-GEM Version 2.0, KAOS 1.4.2 und MagiC zur Verfügung.
Gruppe: Applikationen
Querverweis: Binding   appl_xbvset   Dsetdrv

8.3.1.1 Bindings für appl_bvset

C: int16_t appl_bvset ( uint16_t bvdisk, uint16_t bvhard );
Umsetzung:
int16_t appl_bvset (uint16_t bvdisk, uint16_t bvhard)
{
   int_in[0]  = bvdisk;
   int_in[1]  = bvhard;
   return ( crys_if(16) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 16 # 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] 0 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] bvdisk
int_in+2 int_in[1] bvhard
int_out int_out[0] Return-Wert

8.3.2 appl_control

Name: »Application control« - Gezieltes Steuern von Anwendungen.
AES-Nummer: 129
Deklaration: int16_t appl_control ( int16_t ap_cid, int16_t ap_cwhat, void *ap_cout);
Beschreibung: Die Funktion erlaubt ein gezieltes Steuern von Anwendungen.
Parameter Bedeutung
ap_cid Die Applikationsidentifikation (apid) der Anwendung, die gesteuert werden soll.
ap_cwhat Die Art der Steuerung:
0 bis 9
Reserviert für N.AES.
APC_TOPNEXT (0)
OAESis interner Mode
APC_KILL (1)
OAESis interner Mode
APC_SYSTEM (2)
XaAES interner Mode
APC_HIDE (10)
Applikation ausblenden
Wird für ap_cid -1 übergeben, so wird die aktuelle Anwendung ausgeblendet.
APC_SHOW (11)
Applikation einblenden
Wird für ap_cid -1 übergeben, so werden alle ausgeblendeten Anwendungen eingeblendet.
APC_TOP (12)
Applikation in den Vordergrund bringen (zur aktuellen Anwendung machen).
APC_HIDENOT (13)
Ausblenden aller Anwendungen bis auf die in ap_cid angegebene, welche zur neuen aktuellen Anwendung wird. Wird für ap_cid -1 übergeben, so werden alle Anwendungen bis auf die aktuelle ausgeblendet.
APC_INFO (14)
Abfragen von Applikationsparametern der Anwendung ap_cid. Wird für ap_cid -1 übergeben, so werden die Parameter der aktuellen Anwendung geliefert.

Für ap_cout ist ein Zeiger auf einen Integer zu übergeben. N.AES hinterlegt hier die Applikationsparameter in Form einer Bitmaske:
APCI_HIDDEN (1) Bit 0 ist gesetzt, wenn die Applikation ausgeblendet ist.
APCI_HASMBAR (2) Bit 1 ist gesetzt, wenn die Applikation eine Menüleiste besitzt.
APCI_HASDESK (4) Bit 2 ist gesetzt, wenn die Applikation einen eigenen Desktop besitzt.
APC_MENU (15)
Liefert die Adresse des Menübaums, den die Anwendung ap_cid zuletzt angemeldet hat. Hierzu ist für ap_cout ein Zeiger auf einen OBJECT-Zeiger zu übergeben; letzterer wird vom N.AES mit der gesuchten Menübaumadresse gefüllt.

Wird für ap_cid -1 übergeben, so wird die Menübaumadresse der aktuellen Anwendung geliefert. Übergibt man für ap_cid den Wert 0, so wird die Adresse des vom N.AES intern verwalteten Systemmenüs geliefert. Dies ist die Menübox, die aufklappt, wenn man den am weitesten links stehenden Menütitel anwählt und welche die Liste aller beim N.AES angemeldeten Anwendungen und Accessories enthält.

Hat die abgefragte Anwendung keine Menüleiste angemeldet oder existiert keine Anwendung mit der Identifikation ap_cid, so wird ein Nullzeiger nach ap_cout geschrieben.

Der Rückgabewert von appl_control, Modus APC_MENU ist immer der Wert 1.

Hinweis: Wenn man diesen Modus verwendet, sollte man sich ganz sicher sein, was man tut! Das Verändern des gelieferten Menübaums kann zu undefinierten Systemzuständen führen. Bei aktivem MiNT-Speicherschutz kann bereits ein Lesezugriff auf den Menübaum den Abbruch der Anwendung bewirken.
APC_WIDGETS (16)
Erfragt oder setzt die 'default' Positionen der Fensterobjekte. ap_cout ist ein Zeiger auf einen MINWINOBJ(12) großen (int16_t) Buffer, der zum abfragen der Objektreihenfolge komplett mit -1 gefüllt sein muß. Das letzte Word muß eine 0 sein. Wird eine Fehlermeldung zurückgeliefert reicht der Buffer nicht für alle Objekte und sollte vergrößert werden. Im Buffer liegen als erstes die Objekte der Titelleiste von links nach rechts, danach die Objekte des Vertikalsliders von oben nach unten und dann die Objekte des Horizontalsliders von links nach rechts. Abgeschlossen wird die Liste mit einem 0 Word. Zum setzen der Positionen müßen die ersten Objekte vom Typ topwidgets sein (von links nach rechts), danach die Objekte des Typs rightwidgets (von oben nach unten) und dann die Objekte des Typs bottomwidgets (von links nach rechts). Sollten Objekte doppelt oder falsch gesetzt sein wird ein Fehler gemeldet.
APC_APP_CONFIG (17)
With this option you are able to inform to AES how you want your application should be considered.
ap_cout is a pointer to a string. At this time value supported are:
  • "app_debug=true" or "app_debug" : put the application in debug mode
  • "app_debug=false" : stop debug mode
  • "app_topmost=true" or "app_topmost" : Application windows will be always on top (compare to other classical application) but without focus (can be usefull for tesk bar for exemple)
  • "app_topmost=false" : remove previous option
  • "app_system" : application is a system application (used in appl_search for type APP_SYSTEM)
  • "app_texticon=opaque" : background icon text is opaque
  • "app_texticon=transparent" : background icon text is transparent
  • "app_signal_mesag=true": Request receive Unix Signal when even message is waiting see APC_INFORM_MESAG as it do exactly the same
  • "app_signal_mesag=false": Request stop receive Unix Signal when even message is waiting
APC_INFORM_MESAG (18)
Request to AES to inform the application when there is a AES message waiting with a Unix Signal.
ap_cout : not used.
When the application receive a message the AES send the Signal SIGUSR2 (30) to the application, to manage the message should use classical event_mesag or event_multi functions. Calling one time this call request to AES to send Signal, calling a second time remove this order.
ap_cout Wird abhängig von ap_cwhat gefüllt oder gelesen und hat nur für APC_INFO, APC_MENU, APC_WIDGETS und APC_APP_CONFIG eine Bedeutung. In den anderen Fällen wird dieser Parameter ignoriert, die Übergabe eines Nullzeigers ist dann möglich.


Hinweis: Ausgeblendeten Anwendungen wird in der Menüleiste ein '*' vorangestellt, es sei denn, sie hatten im Moment der Ausblendung kein Fenster offen. In diesem Fall wird nur die Anwendung gewechselt.

Der '*' vor dem Namen bedeutet genau: Einige oder alle geöffneten Fenster dieser Anwendung sind ausgeblendet.
Ergebnis:  0 = ein Fehler ist aufgetreten
>0 = kein Fehler aufgetreten
Verfügbar: Das Vorhandensein der Funktion ist über appl_getinfo (Opcode 65) nachprüfbar.
Gruppe: Applikationen
Querverweis: Binding   SM_M_SPECIAL

8.3.2.1 Bindings für appl_control

C: int16_t appl_control ( int16_t ap_cid, int16_t ap_cwhat, void *ap_cout);
Umsetzung:
int16_t appl_control ( int16_t ap_cid, int16_t ap_cwhat,
                       void *ap_cout);
{
   int_in[0]  = ap_cid;
   int_in[1]  = ap_cwhat;
   addr_in[0] = ap_cout;

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

Adresse Feldelement Belegung
control control[0] 129 # 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] ap_cid
int_in+2 int_in[1] ap_cwhat
addr_in addr_in[0] ap_cout
int_out int_out[0] ap_creturn

8.3.3 appl_exit

Name: »Application exit« - meldet eine Applikation vom AES ab.
AES-Nummer: 19
Deklaration: int16_t appl_exit ( void );
Beschreibung: Meldet eine Applikation beim AES wieder ab und gibt deren Applikations-ID frei.
Ergebnis: Ein Fehler ist nur dann aufgetreten, wenn als Ergebnis 0 zurückgegeben wird.
Verfügbar: Alle AES Versionen
Gruppe: Applikationen
Querverweis: Binding   appl_init

8.3.3.1 Bindings für appl_exit

C: int16_t appl_exit ( void );
Umsetzung:
int16_t appl_exit (void)
{
   return ( crys_if(19) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 19 # Opcode der Funktion
control+2 control[1] 0 # 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_out int_out[0] Return-Wert

8.3.4 appl_find

Name: »Application find« - ermittelt die Applikationsnummer einer AES-Anwendung.
AES-Nummer: 13
Deklaration: int16_t appl_find ( CONST int8_t *ap_fpname );
Beschreibung: Diese Funktion ermittelt die Applikationsidentifikation einer anderen, parallel laufenden Applikation. Dabei zeigt ap_fpname auf den Namen der Applikation deren Identifikator gefunden werden soll.

Wichtig: Der Name muß unbedingt acht Zeichen lang sein, ist er kürzer, so muß er mit Leerzeichen aufgefüllt werden.

In MagiC und AES 4.0 kann man zusätzlich durch Übergabe eines Nullpointers die ID der aktuellen Applikation ermitteln. Darüber hinaus ist es möglich, die AES-ID einer Applikation in die MiNT-ID umzurechnen und umgekehrt, und zwar wie folgt:
High-Word Bedeutung
von ap_fpname  
   
-1 Die Funktion erwartet im Low-Word die MiNT-ID einer Applikation und liefert nach dem Aufruf die AES-ID dieser Applikation zurück.
-2 Die Funktion erwartet im Low-Word die AES-ID einer Applikation und liefert nach dem Aufruf die MiNT-ID dieser Applikation zurück.
-3 Es wird die AES-ID der obersten Applikation geliefert. Das Low-Word spielt dabei keine rolle und kann 0 sein. Steht nur unter MyAES (ab 0.94a), N.AES und XaAES zur Verfügung.


Hinweis: Die Funktion arbeitet nur dann korrekt, wenn das betreffende Programm per shel_write gestartet worden ist. Es sei ferner darauf hingewiesen, daß Threads über diese Funktion nicht gefunden werden können.

Bei KAOS 1.4.2 und MagiC kann man den Applikationsname auch ermitteln in dem man den String "?\0\n" übergibt, wobei n die ap_id darstellt. Ist der Funktionswert 0 ist die ap_id ungültig. Ansonsten erhält man eine 1, und der String wurde mit dem Applikationsnamen überschrieben. Besitzen zwei Applikationen den selben Namen wird nur der erste gefunden.

Einige AES-Namen sind vordefiniert:
"SCRENMGR": Bildschirmmanager.
"        ": Integriertes Desktop.
"?AGI    ": appl_getinfo() bei AES-Versionen < 4.00 vorhanden
Ergebnis: Ein Rückgabewert kleiner Null kennzeichnet einen aufgetretenen Fehler.
Verfügbar: Das Vorhandensein der zusätzlichen Features ist über appl_getinfo (Opcode 4) nachprüfbar.
Gruppe: Applikationen
Querverweis: Binding   appl_search   Screen-Manager

8.3.4.1 Bindings für appl_find

C: int16_t appl_find ( CONST int8_t *ap_fpname );
Umsetzung:
int16_t appl_find (CONST int8_t *ap_fpname)
{
   addr_in[0] = ap_fpname;
   return ( crys_if(13) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 13 # Opcode der Funktion
control+2 control[1] 0 # 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] ap_fpname
int_out int_out[0] Return-Wert

8.3.5 appl_getinfo

Name: »Application get information« - Informationen über vorhandene Funktionsaufrufe und Eigenschaften erfragen.
AES-Nummer: 130
Deklaration: int16_t appl_getinfo ( int16_t ap_gtype, int16_t *ap_gout1, int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4 );
Beschreibung: Mit dieser Funktion lassen sich gezielt Eigenschaften des Betriebssystems zur Laufzeit erfragen.

ap_gtype bestimmt die Art der Informationen, die erfragt werden sollen. Es bedeutet:

AES_LARGEFONT (0): Informationen über den normalen AES-Zeichensatz
ap_gout1: Fonthöhe
ap_gout2: Font-ID
ap_gout3: Font-Typ (0=system, 1=FSM)


AES_SMALLFONT (1): Informationen über den kleinen Zeichensatz
ap_gout1: Fonthöhe
ap_gout2: Font-ID
ap_gout3: Font-Typ (0=system, 1=FSM)


AES_SYSTEM (2): Farben
ap_gout1: VDI-Gerätenummer (device id)
ap_gout2: Farben für OBJECTs
ap_gout3: Farbicons vorhanden (1) bzw. nicht (0)
ap_gout4:
Bit 0: neues RSC-Format (AES4) vorhanden
Bit 1: Interface Resource File Format (RSHDR:rsh_vrsn = 3) wird unterstützt.


AES_LANGUAGE (3): Sprache
ap_gout1:
0 - Englisch
1 - Deutsch
2 - Französisch
3 - reserviert
4 - Spanisch
5 - Italienisch
6 - Schwedisch


AES_PROCESS (4): allgemeine Informationen-1
ap_gout1: Multitasking präemptiv (1) oder nicht (0)
ap_gout2: appl_find konvertiert MiNT/AES-ID's (1) oder nicht (0)
ap_gout3: appl_search vorhanden (1) oder nicht (0)
ap_gout4: rsrc_rcfix vorhanden (1) oder nicht (0)


AES_PCGEM (5): allgemeine Informationen-2
ap_gout1: objc_xfind vorhanden (1) oder nicht (0)
ap_gout2: reserviert, immer 0
ap_gout3: menu_click vorhanden (1) oder nicht (0)
ap_gout4: shel_rdef/shel_wdef vorhanden (1) oder nicht (0)


AES_INQUIRE (6): allgemeine Informationen-3
ap_gout1: appl_read (-1) vorhanden (1) oder nicht (0)
ap_gout2: shel_get (-1) vorhanden (1) oder nicht (0)
ap_gout3: menu_bar (-1) vorhanden (1) oder nicht (0)
ap_gout4: menu_bar (100) (MagiC) vorhanden (1) oder nicht (0)


7: reserviert für MagiC und andere Erweiterungen, MultiTOS setzt alle Rückgabewerte immer auf 0. In MagiC gilt:
ap_gout1:
Bit 0: wdlg_xx()-Funktionen vorhanden (1)
Bit 1: lbox_xx()-Funktionen vorhanden (1)
Bit 2: fnts_xx()-Funktionen vorhanden (1)
Bit 3: fslx_xx()-Funktionen vorhanden (1)
Bit 4: pdlg_xx()-Funktionen vorhanden (1)
ap_gout2: reserviert
ap_gout3: reserviert
ag_gout4: reserviert


AES_MOUSE (8): Maus
ap_gout1: graf_mouse Modi (258-260) vorhanden (1) oder nicht (0)
ap_gout2: Mausform vom AES für jede Applikation verwaltet (1) oder nicht (0)
ap_gout3: Achtung doppelt Belegung
- Mausrad Unterstützung (XaAES)
- Falls ein Treiber installiert ist der TORG 105 unterstützt steht hier ein Bitvektor der verfügbaren Mausräder.


AES_MENU (9): Menüs
ap_gout1: MultiTOS-Submenüs vorhanden (1) oder nicht (0)
ap_gout2: MultiTOS-Popups vorhanden (1) oder nicht (0)
ap_gout3: MultiTOS-Scrollmenüs vorhanden (1) oder nicht (0)
ap_gout4: erweiterte MN_SELECTED-Nachricht vorhanden (1) oder nicht (0)


AES_SHELL (10): shel_write
ap_gout1: vorhandene Modi
Bit 0..7: höchster zulässiger Wert für sh_wdoex & 0x00ff
Bit 8..15: Bits von sh_wdoex & 0xff00, die wie in MultiTOS behandelt werden.
ap_gout2:
1: shel_write (0) macht vorherige shel_write Aufrufe ungültig (d.h. das Desktop wird Nachfolgeprogramm) (TOS 1.04 und MagiC)
0: startet Programm (MultiTOS)
ap_gout3:
1: shel_write (1) startet Programm nach Beendigung des laufenden (TOS 1.04 und MagiC)
0: startet Programm sofort (MultiTOS)
ap_gout4: ARGV via sh_wiscr unterstützt (1) oder nicht (0)


AES_WINDOW (11): Fenster
ap_gout1: gesetzte Bits sind unterstützte Funktionen:
Bit 0: WF_TOP liefert zweitoberstes Fenster
Bit 1: wind_get (WF_NEWDESK)
Bit 2: wind_g/set (WF_COLOR)
Bit 3: wind_g/set (WF_DCOLOR)
Bit 4: wind_get (WF_OWNER)
Bit 5: wind_g/set (WF_BEVENT)
Bit 6: WF_BOTTOM
Bit 7: WF_ICONIFY
Bit 8: WF_UNICONIFY
Bit 9: WF_WHEEL
Bit 10: wind_get(WF_FIRSTAREAXYWH)
Bit 11: wind_get/set(WF_OPTS)
Bit 12: wind_get/set(WF_MENU)
Bit 13: wind_get/set(WF_WORKXYWH)
Bit 14: wind_get(WF_CALCW2F/WF_CALCF2W) und WO0_WCOWORK
Bit 15: wind_set und wind_get können mit dem speziellen handle -2 aufgerufen werden. Wind_set und wind_get liefern dann mit spezielen handle und dem Modus ob dieser vorhanden ist (1) oder nicht (0).
ap_gout2:
Bit 0: wind_get/set (WF_WIDGETS), N.AES
Bit 1..15: reserviert
ap_gout3: vorhandene Fensterbuttons
Bit 0: Iconifier
Bit 1: Backdrop-Button (MagiC)
Bit 2: Shift-Click für Backdrop
Bit 3: "Hot" Closebox (GEM/3 und MagiC)
Bit 4..15: reserviert, 0
ap_gout4: wind_update 'check and set' vorhanden (1) oder nicht (0)


AES_MESSAGE (12): Nachrichten
ap_gout1: gesetzte Bits sind unterstützte Nachrichten:
Bit 0: WM_NEWTOP
Bit 1: WM_UNTOPPED
Bit 2: WM_ONTOP
Bit 3: AP_TERM
Bit 4: MultiTOS-Auflösungswechsel
Bit 5: CH_EXIT
Bit 6: WM_BOTTOMED
Bit 7: WM_ICONIFY
Bit 8: WM_UNICONIFY
Bit 9: WM_ALLICONIFY
Bit 10: WM_REPOSED
ap_gout2: reserviert, alle 0
ap_gout3: WM_ICONIFY liefert Koordinaten (1) oder nicht (0)


AES_OBJECT (13): OBJECTs
ap_gout1: 3D-Objekte über ob_flags vorhanden (1) oder nicht (0)
ap_gout2: 0 - objc_sysvar nicht vorhanden
1 - MultiTOS 1.01 objc_sysvar
2 - extended objc_sysvar
ap_gout3: Speedo- und GDOS-Fonts im TEDINFO erlaubt (1) oder nicht (0)
ap_gout4: reserviert für MagiC und andere Erweiterungen, MultiTOS setzt alle Rückgabewerte immer auf 0. In MagiC und N.AES gilt:
Bit 0: G_SWBUTTON vorhanden
Bit 1: G_POPUP vorhanden
Bit 2: WHITEBAK steuert Unterstriche und Buttons
Bit 3: G_SHORTCUT vorhanden


AES_FORM (14): Formulare (MagiC form_xdo und form_xdial)
ap_gout1: MagiC-Flydials vorhanden (1) oder nicht (0)
ap_gout2: MagiC-Tastaturtabellen vorhanden (1) oder nicht (0)
ap_gout3: letzte Cursorposition wird zurückgegeben (1) oder nicht (0)
ap_gout4: reserviert, 0


AES_EXTENDED (64): Erweiterte Funktionen
ap_gout1: shel_write(10) mit AP_AESTERM möglich (1) oder nicht (0)
ap_gout2: extended shel_write() SHW_SHUTDOWN(4)/SHW_RESCHANGE(5) vorhanden (1) oder nicht (0)
ap_gout3: appl_search:
Bit 0: Langnamen vorhanden
Bit 1: Modus APP_TASKINFO vorhanden
ap_gout4: form_error() mit allen GEMDOS-Fehlercodes vorhanden (1) oder nicht (0)


AES_NAES (65): Zusätzliche N.AES Funktionen
ap_gout1: appl_control() vorhanden (1) oder nicht (0)
ap_gout2: höchster Opcode für appl_control()
ap_gout3: shel_help() vorhanden (1) oder nicht (0)
ap_gout4: wind_draw() vorhanden (1) oder nicht (0)


AES_VERSION (96): AES Version
There is an extended mode since XaAES from 2004-12-18.
ap_gout1: Major version number (decimal)
ap_gout2: Minor version number (decimal)
ap_gout3: Development Status (Beta, alpha, etc.)
This is a 16-bit integer where bits 0-7 (the low byte) is a value indicating the development status of the AES, see below (AES_DEVSTATUS_xxx) for meaning of different values. Bits 8-15 are flags, see below (AES_FDEVSTATUS_xxx) for current definitions.

AES_DEVSTATUS_ALPHA   0
AES_DEVSTATUS_BETA    1
AES_DEVSTATUS_RELEASE 2

AES_FDEVSTATUS_STABLE 0x100
ap_gout4: Zielplattform (m68k, etc.)
This is a value indicating which platform the AES was built for. See below (AES_ARCH_xxx) for meaning of different values.

Label Wert Zielplattform
AES_ARCH_M68K 0 MC-68000
AES_ARCH_M68000 0 MC-68000
AES_ARCH_M68010 1 MC-68010
AES_ARCH_M68020 2 MC-68020
AES_ARCH_M68030 3 MC-68030
AES_ARCH_M68040 4 MC-68040
AES_ARCH_M68060 5 MC-68060
AES_ARCH_M6802060 6 MC-68020-060
AES_ARCH_COLDFILRE 7 Coldfire


Together (ap_gout1 & ap_gout2), these two contain the decimal representation of the AES's version number. For XaAES v0.992, ap_gout1 contains 0 (0x0000) and ap_gout1 contains 992 (0x3e0).

AES_WOPTS (97): Available WF_OPTS settings
since XaAES 2005-07-09
ap_gout1: available window options 0 - see wind_set/get(WF_OPTS, wopt0)
ap_gout2: available window options 1 - see wind_set/get(WF_OPTS, wopt1)
ap_gout3: available window options 2 - see wind_set/get(WF_OPTS, wopt2)
ap_gout4: reserved - always cleared


AES_FUNCTIONS (98): Available extended AES function
since XaAES 2005-12-08
ap_gout1:
Bit 0: If set, the following MagiC 5.10 introduced functions exists;
objc_wdraw
objc_wchange
objc_wedit
graf_wwatchbox
form_wbutton
form_wkeybd
Bit 1: If set, appl_options() exists.
Bit 2..15: Not yet defined, always reads 0.
ap_gout2: Not yet defined, all bits reads 0
ap_gout3: Not yet defined, all bits reads 0
ap_gout4: Not yet defined, all bits reads 0


AES_AOPTS (99): Available application options
The bitmasks returned here are identical to the bitmasks used to modify the application options via appl_options(APL_OPTS). Needless to say, this option is not available if bit 0 in ap_gout1 is cleared after appl_getinfo(AES_FUNCTIONS).
since XaAES 2005-12-08
ap_gout1:
Bit 0: If set, extended slider management is available.
Bit 1: If set, extended objc_edit() cursor management is present. See more info about this below.
Bit 2..15: Not yet defined, always reads 0.
ap_gout2: Not yet defined, all bits reads 0
ap_gout3: Not yet defined, all bits reads 0
ap_gout4: Not yet defined, all bits reads 0


AES_WINX (22360): Infos zu Erweiterungen in WINX
dieser Informationstyp existiert seit WINX 2.3
ap_gout1: Bitvektor für WF_-Funktionen in wind_get/wind_set
Bit 0: WF_WINX
Bit 1: WF_WINXCFG
Bit 2: WF_DDELAY
Bit 3: WF_SHADE
Bit 4: WF_STACK
Bit 5: WF_TOPALL
Bit 6: WF_BOTTOMALL
Bit 7: WF_KIND
ap_gout2: Bitvektor für AES-Nachrichten
Bit 0: Erweitertes WM_ARROWED
Bit 1: WM_SHADED Nachricht wird versandt
Bit 2: WM_UNSHADED Nachricht wird versandt
ap_gout3: Bitvektor für Erweiterungen von AES-Funktionen
Bit 0: wind_calc erlaubt WC_WIN-Modi
ap_gout4: Bitvektor für allgemeine Informationen zum AES
Bit 0: DPAT-Schreibtischhintergrund wird vom AES direkt unterstützt


22358: XaAES
Wird ab dem 2004-12-18 nicht mehr unterstützt. Siehe ap_gtype = 96
ap_gout1: Hautpversionnummer
ap_gout2: Unterversionnummer
ap_gout3: Zielplattform für die XaAES erstellt wurde.
ap_gout4: Status (Beta, alpha, etc.)


Hinweis: Ein Problem dieser Funktion besteht darin, festzustellen, wann sie überhaupt aufgerufen werden darf. Zwar sollte sie ab AES-Version 4.0 vorhanden sein, MagiC 2.0 (und auch MagiC 3.0) besitzt aber beispielsweise die Version 3.99. Aus diesem Grund definieren viele Programmierer die Funktion appl_xgetinfo, in der überprüft wird, ob appl_getinfo in der aktuellen Systemumgebung vorhanden ist.
Ergebnis: Ein Rückgabewert von 0 zeigt einen Fehler an; bei einem Wert von 1 ist kein Fehler aufgetreten.
Verfügbar: Available as of AES version 4.00.
Gruppe: Applikationen
Querverweis: Binding

8.3.5.1 Bindings für appl_getinfo

C: int16_t appl_getinfo ( int16_t ap_gtype, int16_t *ap_gout1, int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4 );
Umsetzung:
int16_t appl_getinfo (int16_t ap_gtype, int16_t *ap_gout1,
                      int16_t *ap_gout2, int16_t *ap_gout3,
                      int16_t *ap_gout4)
{
   int_in[0] = ap_gtype;

   crys_if (130);

   *ap_gout1 = int_out[1];
   *ap_gout2 = int_out[2];
   *ap_gout3 = int_out[3];
   *ap_gout4 = int_out[4];

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

Adresse Feldelement Belegung
control control[0] 130 # Opcode der Funktion
control+2 control[1] 1 # Einträge in int_in
control+4 control[2] 5 # 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] ap_gtype
int_out int_out[0] Return-Wert
int_out+2 int_out[1] ap_gout1
int_out+4 int_out[2] ap_gout2
int_out+6 int_out[3] ap_gout3
int_out+8 int_out[4] ap_gout4

8.3.5.2 appl_xgetinfo

/* Der folgende Code testet, ob appl_getinfo in der aktuellen
   Systemumgebung zur Verfügung steht, und ruft im positiven
   Fall die besagte Funktion auf.

   Es bietet sich an, statt appl_getinfo nur appl_xgetinfo
   in eigenen Programmen zu verwenden. */


GLOBAL int16_t appl_xgetinfo ( int16_t type, int16_t *out1, int16_t *out2,
                            int16_t *out3, int16_t *out4 )
{

   BOOLEAN has_agi = FALSE;

   has_agi = ((_GemParBlk.global[0] == 0x399 && (is_MagiC() >= 0x0200))
             || (_GemParBlk.global[0] >= 0x400)
             || (appl_find ("?AGI") >= 0));

   if (has_agi)
      return (appl_getinfo (type, out1, out2, out3, out4));
   else
      return (0);
} /* appl_xgetinfo */

Die Abfrage is_MagiC ist eine Funktion, welche den MagiC-Cookie auswertet und die Versionsnummer zurückliefert. Dies ist notwendig da bereits MagiC 2 die Funktion appl_getinfo kennt, allerdings noch nicht die Abfrage per "?AGI" erlaubt.

Querverweis: Applikationen   GEM   Style-Guidelines

8.3.6 appl_getinfo_str

Name: »Application get information« - Informationen über vorhandene Funktionsaufrufe und Eigenschaften erfragen.
AES-Nummer: 130
Deklaration: int16_t appl_getinfo_str ( int16_t ap_gtype, int16_t *ap_gout1, int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4 );
Beschreibung: Dies ist eine erweiterte Version von appl_getinfo. Statt der integer Werte liefert sie Zeichenketten zurück.

ap_gtype bestimmt die Art der Informationen, die erfragt werden sollen. Es bedeutet:

96: AES Version
ap_gout1: This is a character string with a fixed lenght of 8 bytes, into which the AES will write its unique AES ID. the AES ID is a left-aligned, space padded string, and can be considered to be the current AES's short name. For XaAES this string is filled with " XaAES". This string is not null-terminated.
ap_gout2: This is a character buffer that the application must ensure can take up to 256 (255 + 0 termination) characters. The AES fills its long name description into this buffer. Lines in here are delimitted using CR (ascii 13). For XaAES, this buffer contains the following after the call;
"XaAES Ain't the AES, a free MultiTasking AES for FreeMiNT"
ap_gout3: This is a character buffer that the application must ensure can take up to 256 (255 + 0 termination) characters. The AES fills this buffer with the following information where each element is delimitted by the "|" (ascii 0x7c) character. The string is constructed as follows;
"asci version|development status|architecture target| build date & time|compiler used",0
Example string returned might be;
"0.992|Alpha|m68k|Dec 17 2004 22:58:52|gcc 2.95.3",0
ap_gout4: reserved, set to NULL.


Hinweis: Ein Problem dieser Funktion besteht darin, festzustellen, wann sie überhaupt aufgerufen werden darf. Zwar sollte sie ab AES-Version 4.0 vorhanden sein, MagiC 2.0 (und auch MagiC 3.0) besitzt aber beispielsweise die Version 3.99. Aus diesem Grund definieren viele Programmierer die Funktion appl_xgetinfo, in der überprüft wird, ob appl_getinfo in der aktuellen Systemumgebung vorhanden ist.
Ergebnis: Ein Rückgabewert von 0 zeigt einen Fehler an; bei einem Wert von 1 ist kein Fehler aufgetreten.
Verfügbar: since XaAES from 2004-12-18
Gruppe: Applikationen
Querverweis: Binding   appl_getinfo

8.3.6.1 Bindings für appl_getinfo_str

C: int16_t appl_getinfo_str ( int16_t ap_gtype, int16_t *ap_gout1, int16_t *ap_gout2, int16_t *ap_gout3, int16_t *ap_gout4 );
Umsetzung:
int16_t appl_getinfo_str (int16_t ap_gtype, int16_t *ap_gout1,
                          int16_t *ap_gout2, int16_t *ap_gout3,
                          int16_t *ap_gout4)
{
   int_in[0] = ap_gtype;

   addr_in[0] = (int32_t)ap_out1;
   addr_in[1] = (int32_t)ap_out2;
   addr_in[2] = (int32_t)ap_out3;
   addr_in[3] = (int32_t)ap_out4;

   crys_if (130);

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

Adresse Feldelement Belegung
control control[0] 130 # 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] 4 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] ap_gtype
addr_in addr_in[0] ap_gout1
addr_in+4 addr_in[1] ap_gout2
addr_in+8 addr_in[2] ap_gout3
addr_in+12 addr_in[3] ap_gout4
int_out int_out[0] Return-Wert

8.3.7 appl_getcicon

Name: »Application get Cicon«
AES-Nummer: 131
Deklaration: int16_t appl_getcicon(int16_t type,char *name,int16_t size, int_16_t *cicon_width,int16_t *cicon_height, CICON **cicon_data);
Beschreibung: The goal of this function is to provide cicon server (24 bit true color for MyAES or 32 picture) This function provide only CICON data with bitmap and mask and not a full object icon. Data provide by this function should be relocated and copy, AES not keep in memory CICON block provided that should be copy.
Parameter Bedeutung
   
type type&0xFF : kind of icon type:
0 : Application icon
1 : File extension icon
2 : Reserved
3 : Load PNG file as icon from specific path
4 : Other icon (any other specific icon)



If type&0x100 = 0 cicon_data return a CICON block as need by AES for display color icon else cicon_data return a simple bitmap block in ARBG format with 8 bit transparency (this format is not recognize by AES)
name name of the cicon to load, some exemple:
with type&0xFF:
0 : name = "purec"
1 : name = "html"
3 : name = "C:\myprog\mypng\pngname.png"
4 : name = "computer"
size Size of the cicon to load, there is 3 different case:
size > 0 is the size of the icon requested and should be a multiple of 16
size = 0 the default cicon size is requested and is set by aes configuration
size = -1 the return cicon can be of any size and can change from a cicon to another
cicon_width cicon width return
cicon_height cicon height return
cicon_data Return block of type CICON + mask + icon bitmap if type&0x100 = 0 else a bitmap 32 bit with alpha chanel in the format ARGB 8 bits per chanel.

Relocation of cicon_data, cicon_data provide CICON block + mask + bitmap


num_planes : number of planes

*col_data, *col_mask, *sel_data, *sel_mask: provide relative position from the start of cicon_data and should be relocated


As the block can be free by the AES you should copy the block for your need, the size of the block to copy is:
number_of_block = 0
if(cicon_data->col_data) number_of_block++;
if(cicon_data->col_mask) number_of_block++;
if(cicon_data->sel_data) number_of_block++;
if(cicon_data->sel_mask) number_of_block++;

size = sizeof(CICON) + (cicon_data->num_planes * cicon_width * cicon_height * number_of_block)/8 + cicon_width*cicon_height;

CICON *newcicon;
newcicon = malloc(size);
memcpy(newcicon,cicon_data);
if(cicon_data->col_data) newcicon->col_data += newcicon;
if(cicon_data->col_mask) newcicon->col_mask += newcicon;
if(cicon_data->sel_data) newcicon->sel_data += newcicon;
if(cicon_data->sel_mask) newcicon->sel_mask += newcicon;



In the case of 32 bits bitmap size of the bloc = cicon_width * cicon_height * 4
Ergebnis: Ein Fehler ist aufgetreten, wenn als Ergebnis 0 zurückgegeben wird. Bei einem Ergebnis von 1 ist alles OK.
Verfügbar: Seit MyAES 0.96 beta1
Gruppe: Applikationen
Querverweis: Binding

8.3.7.1 Bindings für appl_getcicon

C: int16_t appl_getcicon(int16_t type,char *name,int16_t size, int_16_t *cicon_width,int16_t *cicon_height, CICON **cicon_data);
Umsetzung:
int16_t appl_getcicon (int16_t type,const char *name,int16_t size,
                        int16_t *cicon_width,int16_t *cicon_height
                        CICON **cicon_data)
{
   int_in[0] = type;
   int_in[1] = size;

   addr_in[0] = name;

   addr_out[0] = (void *)cicon_data;

   crys_if (131);

   *cicon_width = int_out[1];
   *cicon_height = int_out[2];

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

Adresse Feldelement Belegung
control control[0] 131 # Opcode der Funktion
control+2 control[1] 2 # 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] 1 # Einträge in addr_out
int_in int_in[0] type
int_in+2 int_in[1] size
addr_in addr_in[0] name
int_out int_out[0] Return-Wert
int_out+2 int_out[1] cicon_width
int_out+4 int_out[2] cicon_height
addr_out addr_out[0] cicon_data

8.3.8 appl_init

Name: »Application Initialization« - meldet die Applikation unter AES an.
AES-Nummer: 10
Deklaration: int16_t appl_init ( void );
int16_t appl_init ( X_BUF_V2 *xbuf );
Beschreibung: Die Funktion meldet das Programm beim AES an, und initialisiert die internen Parameterübergabefelder.

The extra parameter to an X_BUF_V2 is an extension in the FreeGEM AES. If addr_in[0] is set to 1 and an initialised X_BUF_V2 structure is passed in, then on return its arch member will be 0 for DRI GEM or ViewMAX, and 16 or 32 for FreeGEM.

Hinweis: Die Versionsnummer des AES läßt sich nach diesem Aufruf über das Globalfeld (global[0]) erfragen.

Um zu testen, ob ein Programm aus dem Auto-Ordner heraus gestartet worden ist, bietet sich folgendes Verfahren an:
  • Wert 0 in global[0] schreiben
  • Funktion appl_init aufrufen
  • Globalfeld (global[0]) inspizieren: steht dort immer noch eine Null, so ist das AES noch nicht betriebsbereit, und das Programm wurde aus dem Auto-Ordner heraus gestartet.


Dieses Verfahren ist zwar nicht offiziell dokumentiert, wird aber auch im Mausbeschleuniger MACCEL von Atari so angewendet.

KAOS-GEM 1.4.2 liefert in int_in[0] 'KA' und int_in[1] 'OS' zurück.
Ergebnis: Die Funktion liefert die ID der Applikation zurück. Im Fehlerfall wird der Wert -1 zurückgegeben.
Verfügbar: All AES versions.
Gruppe: Applikationen
Querverweis: Binding   appl_find   appl_search   appl_exit

8.3.8.1 Bindings für appl_init

C: int16_t appl_init ( void );
Umsetzung:
EXTERN AESPB c;

int16_t appl_init (void)
{
   c.cb_pcontrol = control;
   c.cb_pglobal  = global;
   c.cb_pintin   = int_in;
   c.cb_pintout  = int_out;
   c.cb_padrin   = addr_in;
   c.cb_padrout  = addr_out;

   control[4] = 0;
   crys_if (10);

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

Adresse Feldelement Belegung
control control[0] 10 # Opcode der Funktion
control+2 control[1] 0 # 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_out int_out[0] Return-Wert

8.3.9 appl_options

Name: »-« -
AES-Nummer: 137
Deklaration: int16_t appl_options(int16_t mode, int16_t aopts0, int16_t aopts1, int16_t aopts2, int16_t aopt3, int16_t *out0, int16_t *out1, int16_t *out2, int16_t *out3);
Beschreibung: Its purpose is to let application set/get options available to it, such as the extended objc_edit mode.
Parameter Bedeutung
   
mode Selects the mode. If mode is AOPT_CLEAR (0), then the selected options found in aopt0 - aopt3 is cleared, disabling then. If AOPT_SET (1) then the selected option bit is set, enabling them.
aopt0 The first 16 of options which have the following meaning;
Bit 0 - AO0_WF_SLIDER
If this bit is set, blah, blah, yeah.
Bit 1 - AO0_OBJC_EDIT
If this options is enabled, objc_edit()... blah
aopt1 The second group of 16 options, none of which is defined yet. Always reads 0.
aopt2 The third group of 16 options, none of which is defined yet. Always reads 0.
aopt3 The third group of 16 options, none of which is defined yet. Always reads 0.
out0
out1
out2
out3
Ergebnis: Return 1 = OK or 0 = error.
Verfügbar: Das Vorhandensein der Funktion ist über appl_getinfo (Opcode 98) nachprüfbar.
Gruppe: Applikationen
Querverweis: Binding

8.3.9.1 Bindings für appl_options

C: int16_t appl_options(int16_t mode, int16_t aopts0, int16_t aopts1, int16_t aopts2, int16_t aopt3, int16_t *out0, int16_t *out1, int16_t *out2, int16_t *out3);
Binding:
int16_t appl_options(int16_t mode,
                int16_t aopts0, int16_t aopts1, int16_t aopts2, int16_t aopt3,
                int16_t *out0, int16_t *out1, int16_t *out2, int16_t *out3)
{
   int_in[0]  = mode;
   int_in[1]  = aopts0;
   int_in[2]  = aopts1;
   int_in[3]  = aopts2;
   int_in[4]  = aopts3;

   crys_if(137);

  *out0 = int_out[1];
  *out1 = int_out[2];
  *out2 = int_out[3];
  *out3 = int_out[4];

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

Adresse Feldelement Belegung
control control[0] 137 # Opcode der Funktion
control+2 control[1] 5 # Einträge in int_in
control+4 control[2] 5 # 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] mode
int_in+2 int_in[1] aopts0
int_in+4 int_in[2] aopts1
int_in+6 int_in[3] aopts2
int_in+8 int_in[4] aopts3
int_out int_out[0] Return-Wert
int_out+2 int_out[1] out0
int_out+4 int_out[2] out1
int_out+6 int_out[3] out2
int_out+8 int_out[4] out3

8.3.10 appl_read

Name: »Application read« - empfängt eine Mitteilung einer anderen Applikation.
AES-Nummer: 11
Deklaration: int16_t appl_read ( int16_t ap_rid, int16_t ap_rlength, void *ap_rpbuff );
Beschreibung: Die Funktion liest eine Anzahl von Bytes aus der Message-Pipe. Es gilt:
Parameter Bedeutung
   
ap_rid ID der Applikation, aus deren Ereignispuffer gelesen werden soll.
ap_rlength Anzahl der zu lesenden Bytes
ap_rpbuff Adresse des Puffers, in dem die Daten abgelegt werden sollen


Die Funktion wartet ggfs. bis die angeforderte Anzahl an Bytes tatsächlich zur Verfügung steht. In MagiC und MultiTOS ist die Funktion so erweitert worden, daß sie mit einer entsprechenden Meldung zurückkehrt, wenn keine Daten vorhanden sind (ap_rid: -1).

Hinweis: appl_read arbeitet destruktiv, d.h. daß Nachrichten nach dem Auslesen aus der Message-Pipe entfernt werden. Dies macht es notwendig, die gelesene Nachricht so auszuwerten, wie es beispielsweise nach einem evnt_multi-Aufruf geschieht.

Das Vorhandensein des erweiterten Feature kann über appl_getinfo (Opcode 6) abgefragt werden.
Ergebnis: Wird eine Null zurückgegeben, so ist ein Fehler aufgetreten, sonst wird eine positive Zahl als Ergebnis zurückgegeben.
Verfügbar: In allen AES Versionen.
Gruppe: Applikationen
Querverweis: Binding   appl_init   appl_write   evnt_mesag   evnt_multi

8.3.10.1 Bindings für appl_read

C: int16_t appl_read ( int16_t ap_rid, int16_t ap_rlength, void *ap_rpbuff );
Umsetzung:
int16_t appl_read (int16_t ap_rid, int16_t ap_rlength,
                   void *ap_rpbuff)
{
   int_in[0]  = ap_rid;
   int_in[1]  = ap_rlength;
   addr_in[0] = ap_rpbuff;

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

Adresse Feldelement Belegung
control control[0] 11 # 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] ap_rid
int_in+2 int_in[1] ap_rlength
addr_in addr_in[0] ap_rpbuff
int_out int_out[0] Return-Wert

8.3.11 appl_search

Name: »Application search« - im System vorhandene Applikationen suchen.
AES-Nummer: 18
Deklaration: int16_t appl_search ( int16_t ap_smode, int8_t *ap_sname, int16_t *ap_stype, int16_t *ap_sid );
Beschreibung: Je nach Parameter sucht die Funktion verschiedene im System vorhandene Applikationen. Es bedeuten:
Parameter Bedeutung
   
ap_smode Suche
APP_FIRST 0 erste Applikation
APP_NEXT 1 nächste Applikation
APP_DESK 2 System Shell
APP_TASKINFO 0x100 Taskinformation anfordern, XaAES
    Bit das hinzugefügt werden kann.
ap_sname Puffer der den Namen der gefundenen Applikation aufnimmt (mindestens 9 Bytes).
ap_stype Typ des Prozesses als Bitvektor
APP_SYSTEM 0x001 System-Prozeß
APP_APPLICATION 0x002 Applikation
APP_ACCESSORY 0x004 Accessory
APP_SHELL 0x008 System Shell
APP_HIDDEN 0x100 Task ist ausgeblendet, XaAES
    nur bei APP_TASKINFO
APP_FOCUS 0x200 Aktive Applikation, XaAES
    nur bei APP_TASKINFO
ap_sid ID der gefundenen Applikation


Es ist möglich der Langname einer Applikation zu ermittelt, wenn man ihre Applikations-ID kennt.

Der Langname ist derjenige, der von der Applikation bei einem menu_register()- Aufruf übergeben wurde und auch in der Menüleiste dargestellt wird.

Kennt man die Applikations-ID apid einer Anwendung, so wird ihr Langname durch folgenden Aufruf von appl_search in den Buffer langname übertragen:

appl_search(-apid, &langname[0], &typ, &pid)

type ist hierbei die auch normalerweise gelieferte Bitmaske des Applikationstyps, pid die MiNT-pid (nicht: apid) der Applikation.

Als erster Parameter ist also der negative Wert der Applikations-ID zu übergeben, um den Langnamen eben dieser Applikation zu ermitteln. Dieser Name kann maximal 32 Zeichen lang sein (31 Zeichen plus ein Nullbyte), man sollte also einen entsprechend großen Buffer für langname reservieren.

APP_TASKINFO liefert automatisch den Langnamen einer Applikation und steht nur unter XaAES zur Verfügung.

Mit dieser Routine können keine Threads gefunden werden.

Geneva have three extra modes:
  • X_APS_CHEXIT (-1)
    Retrieves the name, ID, and type of the last application to exit. This makes it possible for a program which receives a CH_EXIT notice to determine the name of the program which exited. Note that this information is not buffered; this means that if one process terminates and its parent does not make the appl_search() call before a second one does, the information will no longer reflect the first process which terminated.

  • X_APS_CHILD0 (0x7100)
    Retrieve the data concerning the child of the current application which has the lowest application ID. (This is not necessarily the first child application the parent ran.)

  • X_APS_CHILD (0x7101)
    Retrieve the data for each additional child of the current application.

Ergebnis: Die Funktion liefert den Wert 1, wenn kein Fehler aufgetreten ist, bzw. den Wert 0, wenn keine weiteren Applikationen vorhanden sind.
Verfügbar: Das Vorhandensein dieser Funktion kann per appl_getinfo (Opcode 4) festgestellt werden. Die Ermittlung des Langname und Taskinformationen erkennt man an appl_getinfo (Opcode 64).
Gruppe: Applikationen
Querverweis: Binding   appl_find   Broadcasting

8.3.11.1 Bindings für appl_search

C: int16_t appl_search ( int16_t ap_smode, int8_t *ap_sname, int16_t *ap_stype, int16_t *ap_sid );
Umsetzung:
int16_t appl_search (int16_t ap_smode, int8_t *ap_sname,
                     int16_t *ap_stype, int16_t *ap_sid)
{
   int_in[0]  = ap_smode;
   addr_in[0] = ap_sname;

  crys_if(18);

  *ap_stype = int_out[1];
  *ap_sid   = int_out[2];

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

Adresse Feldelement Belegung
control control[0] 18 # Opcode der Funktion
control+2 control[1] 1 # 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] ap_smode
addr_in addr_in[0] ap_sname
int_out int_out[0] Return-Wert
int_out+2 int_out[1] ap_stype
int_out+4 int_out[2] ap_sid

8.3.12 appl_tplay

Name: »Application play« - spielt aufgezeichnete AES-Ereignisse ab.
AES-Nummer: 14
Deklaration: int16_t appl_tplay ( APPLRECORD *ap_tpmem, int16_t ap_tpnum, int16_t ap_tpscale );
Beschreibung: Die Funktion bietet die Möglichkeit, aufgezeichnete Benutzeraktionen wieder abzuspielen. Es gilt:
Parameter Bedeutung
   
ap_tpmem Adresse des Puffers, in welchem sich die abzuspielenden Ereignisse befinden
ap_tpnum Anzahl der auszuführenden Ereignisse
ap_tpscale Geschwindigkeitsfaktor für das Abspielen der Ereignisse. Ein Wert von 100 steht für normale Geschwindigkeit
Ergebnis: Als Ergebnis wird immer der Wert 1 zurückgegeben.
Verfügbar: All AES versions.
Gruppe: Applikationen
Querverweis: Binding   appl_trecord

8.3.12.1 Bindings für appl_tplay

C: int16_t appl_tplay ( APPLRECORD *ap_tpmem, int16_t ap_tpnum, int16_t ap_tpscale );
Umsetzung:
int16_t appl_tplay (APPLRECORD *ap_tpmem, int16_t ap_tpnum,
                    int16_t ap_tpscale)
{
   int_in[0]  = ap_tpnum;
   int_in[1]  = ap_tpscale;
   addr_in[0] = ap_tpmem;

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

Adresse Feldelement Belegung
control control[0] 14 # 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] ap_tpnum
int_in+2 int_in[1] ap_tpscale
addr_in addr_in[0] ap_tpmem
int_out int_out[0] Return-Wert

8.3.13 appl_trecord

Name: »Application record« - nimmt AES-Ereignisse auf.
AES-Nummer: 15
Deklaration: int16_t appl_trecord ( APPLRECORD *ap_tbuffer, int16_t ap_trcount );
Beschreibung: Die Funktion dient zum Speichern von Benutzeraktionen, um diese später wieder abzuspielen. Es gilt:
Parameter Bedeutung
   
ap_tbuffer Adresse des Speicherbereichs, in dem die Ereignisse abgelegt werden sollen
ap_trcount Anzahl der zu speichernden Ereignisse
Ergebnis: Als Ergebnis wird die Anzahl der tatsächlich aufgezeichneten Ereignisse zurückgeliefert.
Verfügbar: All AES versions. Die Funktion ist erst ab GEM-Version 1.2 richtig implementiert.
Gruppe: Applikationen
Querverweis: Binding   appl_tplay

8.3.13.1 Bindings für appl_trecord

C: int16_t appl_trecord ( APPLRECORD *ap_tbuffer, int16_t ap_trcount );
Umsetzung:
int16_t appl_trecord (APPLRECORD *ap_tbuffer,
                      int16_t ap_trcount)
{
   int_in[0]  = ap_trcount;
   addr_in[0] = ap_tbuffer;

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

Adresse Feldelement Belegung
control control[0] 15 # 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] ap_trcount
addr_in addr_in[0] ap_tbuffer
int_out int_out[0] Return-Wert

8.3.14 appl_write

Name: »Application write« - sendet eine Mitteilung an eine andere Applikation.
AES-Nummer: 12
Deklaration: int16_t appl_write ( int16_t ap_wid, int16_t ap_wlength, void *ap_wpbuff );
Beschreibung: Die Funktion schreibt eine Anzahl von Bytes in eine Message-Pipe. Es gilt:
Parameter Bedeutung
   
ap_wid ID der Applikation, zu der die Nachricht geschickt werden soll
ap_wlength Anzahl der zu sendenden Bytes
ap_wpbuff Adresse des Puffers mit der zu übertragenden Nachricht


Hinweis: Durch diese Funktion besitzt eine Applikation auch die Möglichkeit, sich selbst eine Redraw-Nachricht zukommen zu lassen. Ab MagiC Version 4.0 gilt: besitzt der Parameter ap_wid den Wert -2, so zeigt ap_wpbuff auf eine XAESMSG-Struktur.
Ergebnis: Wird eine Null zurückgegeben, so ist ein Fehler aufgetreten, sonst wird eine positive Zahl als Ergebnis zurückgegeben.
Verfügbar: All AES versions.
Gruppe: Applikationen
Querverweis: Binding   appl_init   appl_read   appl_find   Nachrichten

8.3.14.1 Bindings für appl_write

C: int16_t appl_write ( int16_t ap_wid, int16_t ap_wlength, void *ap_wpbuff );
Umsetzung:
int16_t appl_write (int16_t ap_wid, int16_t ap_wlength,
                    void *ap_wpbuff)
{
   int_in[0]  = ap_wid;
   int_in[1]  = ap_wlength;
   addr_in[0] = ap_wpbuff;

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

Adresse Feldelement Belegung
control control[0] 12 # 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] ap_wid
int_in+2 int_in[1] ap_wlength
addr_in addr_in[0] ap_wpbuff
int_out int_out[0] Return-Wert

8.3.15 appl_xbvset

Name: »Extended application bit-vector set«
AES-Nummer: 18
Deklaration: int16_t appl_bvset ( uint16_t bvdisk, uint16_t bvhard );
Beschreibung: Die Funktion informiert das GEM über die vorhandenen logischen Laufwerke, die u.a. für die Dateiauswahl-box (Fileselector) benötigt werden. Es gilt:
Parameter Bedeutung
   
bvdisk Bitvektor der vorhandenen Diskettenlaufwerke (Bit-31 = Laufwerk-A etc).
bvhard Bitvektor der vorhandenen Festplattenlaufwerke (Bit-31 = Laufwerk-A etc).
Ergebnis: Der Rückgabewert der Funktion ist z.Zt. nicht bekannt.
Verfügbar: GEM/4, GEM/5 und FreeGEM.

The function to do this is present on FreeGEM if the ABLE_XBVSET bit is set in the "abilities" bitmap.
Gruppe: Applikationen
Querverweis: Binding   appl_bvset

8.3.15.1 Bindings für appl_xbvset

C: int16_t appl_xbvset ( uint32_t bvdisk, uint32_t bvhard );
Umsetzung:
int16_t appl_xbvset (uint32_t bvdisk, uint32_t bvhard)
{
   int_in[0]  = 1;
   addr_in[0] = bvdisk;
   addr_in[1] = bvhard;

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

Adresse Feldelement Belegung
control control[0] 18 # 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] 2 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
addr_in addr_in[0] bvdisk
addr_in+4 addr_in[1] bvhard
int_out int_out[0] Return-Wert

8.3.16 appl_yield

Name: »Application yield« - Prozeßwechsel erzwingen
AES-Nummer: 17
Deklaration: int16_t appl_yield ( void );
Beschreibung: Mit Hilfe dieser Funktion kann ein AES-Prozeßwechsel erzwungen werden.

Hinweis: Dies kann analog durch einen kurzen Aufruf der Funktion evnt_timer erreicht werden.
Ergebnis: Der Rückgabewert der Funktion ist z.Zt. nicht bekannt.
Verfügbar: Die Funktion steht nur unter PC-GEM, Geneva, sowie MagiC (jeweils) ab Version 2.0, N.AES und XaAES zur Verfügung.
Gruppe: Applikationen
Querverweis: Binding   evnt_timer   _appl_yield

8.3.16.1 Bindings für appl_yield

C: int16_t appl_yield ( void );
Umsetzung:
int16_t appl_yield (void)
{
   return ( crys_if(17) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 17 # Opcode der Funktion
control+2 control[1] 0 # 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_out int_out[0] Return-Wert

8.3.17 _appl_yield

Name: »Application yield« - Prozeßwechsel erzwingen
Deklaration: void _appl_yield ( void );
Beschreibung: Mit Hilfe dieser Funktion kann ein AES-Prozeßwechsel erzwungen werden.

Hinweis: Dies kann analog durch einen kurzen Aufruf der Funktion evnt_timer oder appl_yield erreicht werden.
Ergebnis: Die Funktion liefert kein Ergebnis zurück.
Verfügbar: Die Funktion ist verfügbar seit TOS 1.0, KAOS und MagiC seit Version 1.0.
Gruppe: Applikationen
Querverweis: Binding   evnt_timer   appl_yield

8.3.17.1 Bindings für _appl_yield

C: void _appl_yield ( void );
Umsetzung:
_appl_yield:    move.l  a2,-(sp)
                move.w  #201,d0         ; _appl_yield()
                trap    #2
                movea.l (sp)+,a2
                rts

8.3.18 x_appl_flags

Name: »Control execution flags« - (Geneva)
AES-Nummer: 28928
Deklaration: int16_t x_appl_flags( int16_t getset, int16_t index, APPFLAGS *flags );
Beschreibung: The call x_appl_flags controls the execution flags that are used when determining how an application gets run. It works in two modes, globally and for a particular application.
Mode 0: Get by index
Get the 'nth' block of global application flags. If index is zero, the Default flags will be retrieved. If flags is not NULL, the flags will be copied into the APPFLAGS structure pointed to by the flags parameter.
Mode 1: Set by index
Set the 'nth' block of global application flags. If flags is not NULL, the flags will be copied from the APPFLAGS structure pointed to by the flags parameter. If index is zero, the Default flags will be set, in which case the name and desc fields of the APPFLAGS are not altered. If index is less than zero, a new APPFLAGS structure will be added to the end of the global list, and it will be given the contents of flags.
Mode 2: Delete by index
Delete the 'nth' block of global application flags. The index parameter must be a number greater than zero (since the Default flags cannot be deleted.) The flags parameter is not used in this mode.
Mode 3: Get by application ID
Get the application flags for a particular process.index must be a valid application ID. If flags is not NULL, the flags will be copied into the APPFLAGS structure pointed to by the flags parameter.
Mode 4: Set by application ID
Set the application flags for a particular process.index must be a valid application ID. If flags is not NULL, the flags will be set for the application.
Mode 5: (X_APF_SEARCH) (since Update 004)
Use the APPFLAGS name element to search for the set of flags that would be used by Geneva were it to run the application with that name. Note that the name element is overwritten in the process. The index parameter is not used.

Example: Get the flags for FOO.PRG and force it to run in single-tasking mode:
APPFLAGS a;
SHWRCMD shwrcmd;

strcpy( a.name, "FOO.PRG" );
x_appl_flags( X_APF_SEARCH, 0, &a );
a.flags.s.multitask = 0;
shwrcmd.name = "FOO.PRG";
shwrcmd.app_flags = a.flags.l;
shel_write( XSHD_FLAGS|XSHW_RUNANY, 0, 0, (char *)&shwrcmd, "" );


Note: Changing the multitask attribute of an application in this manner will have no effect, since this can only be changed before the application is launched.

Descriptions of each of the available flags can be found in the section of the manual describing the Task Manager's "Flags" dialog.
Ergebnis: 0: Out of memory (mode 1)
Flags not found (all modes)
Verfügbar: Die Funktion steht nur unter Geneva zur Verfügung.
Gruppe: Applikationen
Querverweis: Binding

8.3.18.1 Bindings für x_appl_flags

C: int16_t x_appl_flags( int16_t getset, int16_t index, APPFLAGS *flags );
Umsetzung:
int16_t x_appl_flags( int16_t getset, int16_t index, APPFLAGS *flags )
{
   int_in[0]  = getset;
   int_in[1]  = index;
   addr_in[0] = flags;
   return ( crys_if(28928) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 28928 # 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] getset
int_in+2 int_in[1] index
addr_in addr_in[0] flags
int_out int_out[0] Return-Wert

8.3.19 x_appl_font

Name: »Change font and window borders« - (Geneva)
AES-Nummer: 28929
Deklaration: int16_t x_appl_font( int16_t getset, int16_t zero, XFONTINFO *info );
Beschreibung: Change the characteristics of the large font used by Geneva, and also the window gadget borders.

This function gives one control over what font is used to display characters in the menu bar, dialogs, etc.

When Geneva first runs, it checks to see if the font ID saved in GENEVA.CNF is anything other than 1 (for a system font). If so, and GDOS is present, it loads all available fonts, and uses the correct font. If the particular font is not available, it reverts to the system font.

Regardless of the font's availability, the closest point size to the one specified is used. The window gadgets will have a width which is equal to the width of one character in the font, plus the value specified by the user. A similar calculation is used for the gadget height.

When any element in the structure pointed to by info is -2, the default value for that element (as though there had been no GENEVA.CNF file when Geneva loaded) is used; in the case of a getset value of zero (get), this default value is returned in the info structure.

When getset is 1 and any element is -1, that element will cause Geneva to ignore the setting, leaving the old value in tact.

Setting these values will have no immediate effect. The GENEVA.CNF file must be re-saved, and Geneva must be restarted before a change can be noticed.

This example:
XFONTINFO info = { -2, -2, -2, -2 };
x_appl_font( 0, 0, &info ); /* get default values             */
x_appl_font( 1, 0, &info ); /* set to these values            */

Is the same as:

XFONTINFO info = { -2, -2, -2, -2 };
x_appl_font( 1, 0, &info ); /* set to default values          */

Set it to something else:

XFONTINFO info = { 1,       /* Select the system font         */
                  10,       /* 10 point (8 x 16)              */
                   5,       /* Gadget width = 8 + 5 pixels    */
                   4 };     /* Gadget height = 16 + 4 pixels  */
x_appl_font( 1, 0, &info );


Cautions:
  • Only monospaced fonts should be used.

  • While Geneva will work properly with any size font, some programs may not function properly with larger or smaller fonts. This is especially true when it comes to fonts which are more than 8 pixels wide.



The parameter zero is reserved for future expansion. Must always be 0.
Ergebnis: Return value of the function is unknown at present.
Verfügbar: Die Funktion steht nur unter Geneva zur Verfügung.
Gruppe: Applikationen
Querverweis: Binding

8.3.19.1 Bindings für x_appl_font

C: int16_t x_appl_font( int16_t getset, int16_t zero, XFONTINFO *info );
Umsetzung:
int16_t x_appl_font( int16_t getset, int16_t zero, XFONTINFO *info );
{
   int_in[0]  = getset;
   int_in[1]  = zero;
   addr_in[0] = info;
   return ( crys_if(28929) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 28929 # 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] getset
int_in+2 int_in[1] zero
addr_in addr_in[0] info
int_out int_out[0] Return-Wert

8.3.20 x_appl_sleep

Name: »Put application to sleep« - or wake it up (Geneva)
AES-Nummer: 28930
Deklaration: int16_t x_appl_sleep( int16_t id, int16_t sleep );
Beschreibung: The call x_appl_sleep searches for the application whose ID (found by appl_find or appl_search) is id and either puts it to sleep or wakes it up. While an application is asleep, its windows are automatically closed, and it does not receive any events.

Parameter Bedeutung
sleep  0: Awaken application
   1: Put application to sleep
  -1: No change


The old state of wakefulness is always returned in xas_return, unless an error occurs. There are several situations where an error code will be returned:
  • There is no application with the ID specified.
  • The application was the only program awake and the user tried to put it to sleep.
  • The application has a single-tasking child.


If an application puts itself to sleep, it will not be able to wake itself; this must be done by another application or by the user from the Desk menu.

If an application which is asleep is about to be terminated for any reason, it is first awakened, so that it can receive the AP_TERM message.
Ergebnis: -1: Application not found, or the state could not be changed
bit 0 set: Application was–sleep
bit 1 set: Application is multitasking is clear, the application is single-tasking
Verfügbar: Die Funktion steht nur unter Geneva zur Verfügung.
Gruppe: Applikationen
Querverweis: Binding

8.3.20.1 Bindings für x_appl_sleep

C: int16_t x_appl_sleep( int16_t id, int16_t sleep );
Umsetzung:
int16_t x_appl_sleep( int16_t id, int16_t sleep );
{
   int_in[0]  = id;
   int_in[1]  = sleep;
   return ( crys_if(28930) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 28930 # 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] 0 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] id
int_in+2 int_in[1] sleep
int_out int_out[0] Return-Wert

8.3.21 x_appl_term

Name: »Terminate application« - Terminate an application and remove it from memory (Geneva).
AES-Nummer: 28931
Deklaration: int16_t x_appl_term( int16_t apid, int16_t retrn, int16_t set_me );
Beschreibung: The call x_appl_term will cause an application to terminate. It is similar to shel_write mode 4, except that it allows for just one application to be terminated.
  • apid is the application ID of the application to be terminated.
  • retrn is a value which is returned to the program which launched the application; this should usually correspond to a GEMDOS error number, or 0 for no error.
  • The set_me parameter must always be non-zero.


If the application to be terminated does not recognize the AP_TERM message, the user will first be presented with an alert box confirming that he wants to terminate.
Ergebnis: 0: The application was not found
Verfügbar: Die Funktion steht nur unter Geneva zur Verfügung.
Gruppe: Applikationen
Querverweis: Binding

8.3.21.1 Bindings für x_appl_term

C: int16_t x_appl_term( int16_t apid, int16_t retrn, int16_t set_me );
Umsetzung:
int16_t x_appl_term( int16_t apid, int16_t retrn, int16_t set_me )
{
   int_in[0]  = apid;
   int_in[1]  = retrn;
   int_in[2]  = set_me;
   return ( crys_if(28931) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 28931 # Opcode der Funktion
control+2 control[1] 3 # 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] apid
int_in+2 int_in[1] retrn
int_in+4 int_in[2] set_me
int_out int_out[0] Return-Wert

HomeAESGrundlagen des AESDateiauswahl