Home AESAES Eigenschaft-FunktionenEigenschaft-Funktionen ShellfunktionenShellfunktionen

8.21 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.21.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.21.1.1 Bindings für rsrc_free

C: 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.21.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  = imagedata
  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 = bi_pdata
  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.21.2.1 Bindings für rsrc_gaddr

C: 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.21.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 Resourcen im sogenannten 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.21.3.1 Bindings für rsrc_load

C: 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.21.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.21.4.1 Bindings für rsrc_obfix

C: 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.21.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.21.5.1 Bindings für rsrc_rcfix

C: 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.21.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.21.6.1 Bindings für rsrc_saddr

C: 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
Home AESAES Eigenschaft-FunktionenEigenschaft-Funktionen ShellfunktionenShellfunktionen