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

8.17 Resourcefunktionen

Diese Bibliothek enthält Funktionen, um die Resourcen eines GEM-Programms (Menüzeilen, Dialogboxen, Icons etc.) in den Speicher zu laden, und die Adressen der relevanten Objekte zu bestimmen. Für diesen Zweck stehen die folgenden Routinen zur Verfügung:

• rsrc_free	Resourcespeicher freigeben
• rsrc_gaddr	Adresse einer Datenstruktur ermitteln
• rsrc_load	Resourcedatei laden
• rsrc_obfix	Zeichen- in Pixelkoordinaten wandeln
• rsrc_rcfix	Zeichen- in Pixelkoordinaten wandeln
• rsrc_saddr	Adresse einer Datenstruktur speichern
• sys_recalc_cicon_colours

Hinweis: Die Auslagerung in eine Resource-Datei hat den unschätzbaren Vorteil, das optische Erscheinungsbild (und insbesondere die Sprache) leicht ändern zu können, ohne am Programm selbst Modifizierungen vornehmen zu müssen.

Querverweis: AES Style-Guidelines

8.17.1 rsrc_free

Name:	»Resource free« - gibt den Speicher einer Resourcedatei wieder frei.
AES-Nummer:	111
Deklaration:	int16_t rsrc_free ( void );
Beschreibung:	Die Funktion gibt den durch eine Resourcedatei belegten Speicherplatz wieder frei. Hinweis: Man sollte auf keinen Fall vergessen, diese Funktion am Ende eines Programms aufzurufen.
Ergebnis:	Ein Fehler ist nur dann aufgetreten, wenn als Ergebnis 0 zurückgegeben wird.
Verfügbar:	All AES versions.
Gruppe:	Resourceorganisation
Querverweis:	Binding rsrc_load

8.17.1.1 Bindings für rsrc_free

int16_t rsrc_free ( void );

Umsetzung:

int16_t rsrc_free (void)
{
   return ( crys_if(111) );
}

GEM-Arrays:

Adresse	Feldelement	Belegung
control	control[0]	111 # 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.17.2 rsrc_gaddr

Name:

»Resource get Address« - ermittelt die Adresse eines Objekts in einem Resourceset.

AES-Nummer:

112

Deklaration:

int16_t rsrc_gaddr ( int16_t re_gtype, int16_t re_gindex, void *gaddr );

Beschreibung:

Die Funktion ermittelt die Anfangsadressen verschiedener Objektstrukturen von im Speicher geladenen Resourcefiles. Es gilt:

Parameter	Bedeutung
re_gtype	Typ der gesuchten Struktur
	R_TREE 0 = Objektbaum
	R_OBJECT 1 = OBJECT
	R_TEDINFO 2 = TEDINFO
	R_ICONBLK 3 = ICONBLK
	R_BITBLK 4 = BITBLK
	R_STRING 5 = String
	R_IMAGEDATA 6 = imagedate
	R_OBSPEC 7 = ob_spec
	R_TEPTEXT 8 = te_ptext
	R_TEPTMPLT 9 = te_ptmplt
	R_TEPVALID 10 = te_pvalid
	R_IBPMASK 11 = ib_pmask
	R_IBPDATA 12 = ib_pdata
	R_IBPTEXT 13 = ib_ptext
	R_BIPDATA 14 = ib_pdate
	R_FRSTR 15 = ad_frstr
	R_FRIMG 16 = ad_frimg
re_gindex	Index der gesuchten Struktur
gaddr	Adresse der gewünschten Struktur

Hinweis: Wenn beispielsweise der Textzeiger innerhalb einer TEDINFO-Struktur gesucht werden soll, so muß nicht die Nummer des zugehörigen Objektes, sondern die Nummer der TEDINFO-Struktur übergeben werden. Für andere Codierungen gilt i.w. das gleiche.

Ergebnis:

Ein Fehler ist nur dann aufgetreten, wenn als Ergebnis 0 zurückgegeben wird.

Verfügbar:

All AES versions.

Gruppe:

Resourceorganisation

Querverweis:

Binding rsrc_load

8.17.2.1 Bindings für rsrc_gaddr

int16_t rsrc_gaddr ( int16_t re_gtype, int16_t re_gindex, void *gaddr );

Umsetzung:

int16_t rsrc_gaddr (int16_t re_gtype, int16_t re_gindex,
                    void *gaddr)
{
   int_in[0]  = re_gtype;
   int_in[1]  = re_gindex;
   control[4] = 1;

   crys_if (112);

   control[4] = 0;
   *gaddr = addr_out[0];

   return ( int_out[0] );
}

GEM-Arrays:

Adresse	Feldelement	Belegung
control	control[0]	112 # 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]	1 # Einträge in addr_out
int_in	int_in[0]	re_gtype
int_in+2	int_in[1]	re_gindex
int_out	int_out[0]	Return-Wert
addr_out	addr_out[0]	gaddr

8.17.3 rsrc_load

Name:	»Resource load« - lädt eine Resourcedatei in den Speicher.
AES-Nummer:	110
Deklaration:	int16_t rsrc_load ( CONST int8_t *re_lpfname );
Beschreibung:	Die Funktion dient zum Laden und Initialisieren einer Resource-Datei. Der Parameter re_lpfname enthält dabei den Dateinamen der Resourcedatei. Hinweis: Die Datei wird in allen Verzeichnissen gesucht, die dem AES bekannt sind. Ab PC-GEM Version 2.0 wird übrigens bei Objektbäumen, die als Wurzel eine Box besitzen (z.B. bei allen Dialogboxen) das Flag SHADOWED im Objektstatus gesetzt. Das bedeutet, daß alle Dialogboxen statt umrahmt mit einem Schatten gezeichnet werden. Dies liegt in den Rechtsstreitigkeiten zwischen Apple und Digital Research begründet. Allerdings kann das SHADOWED Bit (nach dem rsrc_load) zur Laufzeit zurückgesetzt und das normale OUTLINED Bit gesetzt werden. Achtung: Eine Umwandlung von Bit-Images und Icons vom Standardformat in das geräteabhängige Format geschieht an dieser Stelle nicht. Dies muss ggfs. vom Programmierer selbst übernommen werden. MagiC seit Version 3 und Geneva können Resource im Interface-Format laden. Bei anderen AESen wird diese Möglichkeit durch appl_getinfo (Opcode 2) angezeigt.
Ergebnis:	Ein Fehler ist nur dann aufgetreten, wenn als Ergebnis 0 zurückgegeben wird.
Verfügbar:	In allen AES Versionen.
Gruppe:	Resourceorganisation
Querverweis:	Binding rsrc_free shel_find vr_trnfm

8.17.3.1 Bindings für rsrc_load

int16_t rsrc_load ( CONST int8_t *re_lpfname );

Umsetzung:

int16_t rsrc_load (CONST int8_t *re_lpfname)
{
   addr_in[0] = re_lpfname;
   return ( crys_if(110) );
}

GEM-Arrays:

Adresse	Feldelement	Belegung
control	control[0]	110 # 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]	re_lpfname
int_out	int_out[0]	Return-Wert

8.17.4 rsrc_obfix

Name:

»Resource Object fix« - wandelt Zeichensatz- in Pixel-Koordinaten um.

AES-Nummer:

114

Deklaration:

int16_t rsrc_obfix ( OBJECT *re_otree, int16_t re_oobject );

Beschreibung:

Die Funktion konvertiert die Größe und Position eines Objektes von einer Zeichendarstellung in die Pixeldarstellung. Es gilt:

Parameter	Bedeutung
re_otree	Adresse des Objektbaumes
re_oobject	Nummer des Objektes

Hinweis: Ein Aufruf dieser Funktion ist immer dann notwendig, wenn Objekte zur Laufzeit erzeugt werden, oder nicht per rsrc_load geladen werden.

Die Konvertierung erfolgt, indem das untere Byte der Koordinatenangabe mit der Größe eines Zeichens aus dem Systemzeichensatz multipliziert, und darauf das (vorzeichenbehaftete) obere Byte addiert wird. Ein Sonderfall: Bei einer Breite von genau 80 Zeichen wird die Breite des Bildschirms eingesetzt; dies wird z.B. beim Hintergrundobjekt des Menübaums benutzt.

Ergebnis:

Als Ergebnis wird immer der Wert 1 zurückgegeben.

Verfügbar:

All AES versions.

Gruppe:

Resourceorganisation

Querverweis:

Binding rsrc_load rsrc_rcfix

8.17.4.1 Bindings für rsrc_obfix

int16_t rsrc_obfix ( OBJECT *re_otree, int16_t re_oobject );

Umsetzung:

int16_t rsrc_obfix (OBJECT *re_otree, int16_t re_oobject)
{
   int_in[0]  = re_oobject;
   addr_in[0] = re_otree;

   return ( crys_if(114) );
}

GEM-Arrays:

Adresse	Feldelement	Belegung
control	control[0]	114 # 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]	re_oobject
addr_in	addr_in[0]	re_otree
int_out	int_out[0]	Return-Wert

8.17.5 rsrc_rcfix

Name:

»Resource Object Fix« - wandelt Zeichenkoordinaten in Pixelkoordinaten

AES-Nummer:

115

Deklaration:

int16_t rsrc_rcfix ( RSHDR *rc_header );

Beschreibung:

Diese in MagiC und MultiTOS vorhandene Funktion paßt von der Applikation bereits in den Speicher geladene Resourcedaten an. Dabei werden die Koordinaten von Zeichen- in Pixelkoordinaten gewandelt.

Falls die Applikation vor dem Aufruf dieser Funktion bereits eine RSC-Datei geladen hat, so muß diese vorher mit rsrc_free freigegeben werden. Das gleiche gilt beim Beenden der Applikation.

Der Vorteil dieser Funktion besteht darin, daß die Resource-Datei des Programms in den Programmcode eingebunden werden kann. Es reicht dann aus, einfach rsrc_rcfix aufzurufen, und ein Laden via rsrc_load kann entfallen.

rc_header:

Adresse des RSC-Headers im Speicher; hinter diesem müssen die RSC-Daten liegen.

Ergebnis:

z.Zt. unbekannt.

Verfügbar:

Nur verfügbar in MagiC und AES Versions 4.0 und größer. Das Vorhandensein dieser Funktion kann per appl_getinfo (Opcode 4) festgestellt werden.

Gruppe:

Resourceorganisation

Querverweis:

Binding rsrc_load rsrc_obfix

8.17.5.1 Bindings für rsrc_rcfix

int16_t rsrc_rcfix ( RSHDR *rc_header );

Umsetzung:

int16_t rsrc_rcfix ( RSHDR *rc_header )
{
   addr_in[0] = rc_header;
   return ( crys_if(115) );
}

GEM-Arrays:

Adresse	Feldelement	Belegung
control	control[0]	115 # 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]	rc_header
int_out	int_out[0]	Return-Wert

8.17.6 rsrc_saddr

Name:

»Resource store Address« - speichert die Adresse eines Objektes.

AES-Nummer:

113

Deklaration:

int16_t rsrc_saddr ( int16_t re_stype, int16_t re_sindex, void *saddr );

Beschreibung:

Die Funktion speichert die Anfangsadresse einer Datenstruktur im Speicher. Es gilt:

Parameter

Bedeutung

re_stype

Typ der Struktur

R_TREE	0	=	Objektbaum
R_OBJECT	1	=	Individual OBJECT
R_TEDINFO	2	=	TEDINFO Struktur
R_ICONBLK	3	=	ICONBLK Struktur
R_BITBLK	4	=	BITBLK Struktur
R_STRING	5	=	Free string data
R_IMAGEDATA	6	=	Free image data
R_OBSPEC	7	=	ob_spec Feld in OBJECT
R_TEPTEXT	8	=	te_ptext in TEDINFO
R_TEPTMPLT	9	=	te_ptmplt in TEDINFO
R_TEPVALID	10	=	te_pvalid in TEDINFO
R_IBPMASK	11	=	ib_pmask in ICONBLK
R_IBPDATA	12	=	ib_pdata in ICONBLK
R_IBPTEXT	13	=	ib_ptext in ICONBLK
R_BIPDATA	14	=	ib_pdata in BITBLK
R_FRSTR	15	=	ad_frstr free string
R_FRIMG	16	=	ad_frimg free image

re_sindex

Position innerhalb der Datenstruktur

saddr

abzuspeichernde Adresse

Ergebnis:

Ein Fehler ist nur dann aufgetreten, wenn als Ergebnis 0 zurückgegeben wird.

Verfügbar:

All AES versions.

Gruppe:

Resourceorganisation

Querverweis:

Binding rsrc_gaddr OBJECT

8.17.6.1 Bindings für rsrc_saddr

int16_t rsrc_saddr ( int16_t re_stype, int16_t re_sindex, void *saddr );

Umsetzung:

int16_t rsrc_saddr (int16_t re_stype, int16_t re_sindex,
                    void *saddr)
{
   int_in[0]  = re_stype;
   int_in[1]  = re_sindex;
   addr_in[0] = saddr;

   return ( crys_if(113) );
}

GEM-Arrays:

Adresse	Feldelement	Belegung
control	control[0]	113 # 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]	re_stype
int_in+2	int_in[1]	re_sindex
addr_in	addr_in[0]	saddr
int_out	int_out[0]	Return-Wert

8.17.7 sys_recalc_cicon_colours

Name:	???
AES-Nummer:	0 (Unterfunktion 5)
Deklaration:	void sys_recalc_cicon_colours( uint16_t colour_values[3256] );
Beschreibung:	Übergib rgb-Tripel in Promille für die Iconwandlung bei "direct colour" Bildschirm-Modi. Wird laut Andreas Kromke nur von MagxDesk verwendet, um Icons umzurechnen. Ist nicht näher dokumentiert.
Ergebnis:	Unbekannt.
Verfügbar:	Ab MagiC 5.20 vom 20.11.97
Gruppe:	Resourceorganisation
Querverweis:	Binding

8.17.7.1 Bindings für sys_recalc_cicon_colours

void *sys_recalc_cicon_colours( uint16_t colour_values[3*256] );

Umsetzung:

void *sys_recalc_cicon_colours( uint16_t colour_values[3*256] );
{
   int_in[0]  = 5;               /* Subcode 5: */
   addr_in[0] = colour_values;

   crys_if(0);
}

GEM-Arrays:

Adresse	Feldelement	Belegung
control	control[0]	0 # Opcode der Funktion
control+2	control[1]	1 # Einträge in int_in
control+4	control[2]	0 # 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]	5
addr_in	addr_in[0]	colour_values