HINWEIS Die paladin.library funktioniert erst ab Kickstart 2.0 oder höher ! Alle Funktionen der Library verwenden die locale.library von OS2.1/3.0 Dadurch werden alle Texte der Library in der aktuellen Sprache angezeigt, wenn alle 'Paladin.catalog'-Dateien in den LOCALE: Verzeichnissen liegen. Wer keine locale.library hat, der wird nur englische Texte erhalten, sonst aber keine Abstriche an der Leistung der paladin.library machen müssen. TABLE OF CONTENTS - paladin.library 38.102 (6.10.1992) paladin.library/BndryOff paladin.library/EasyFileReq paladin.library/ExpandPath paladin.library/FlushMem paladin.library/FreeEasyMenu paladin.library/GetScreenXY paladin.library/HandleMsg paladin.library/NewCloseWindow paladin.library/ReqAllocVec paladin.library/ReqOpenFile paladin.library/SetAfPt paladin.library/SetDrPt paladin.library/SetEasyMenu paladin.library/SetOPen paladin.library/SetWrMsk paladin.library/SleepWindow paladin.library/WakeUpWindow paladin.library/BndryOff paladin.library/BndryOff NAME BndryOff -- Umrandung ausschalten SYNOPSIS BndryOff(rastport) -126 A1 FUNCTION Mit Hilfe dieser Funktion (ein ehemaliges C-Makro) können Sie veranlassen, daß das AREAOUTLINE-Flag im angegebenen Rastport gelöscht wird. Danach werden die Umrandungslinien bei RectFill()- und den Area...()-Befehlen nicht mehr gezeichnet. INPUTS rastport - Adresse des Rastports, in dem das AREAOUTLINE-Bit gelöscht werden soll. RESULT Keines WARNING Keine SEE ALSO SetOPen paladin.library/EasyFileReq paladin.library/EasyFileReq NAME EasyFileReq -- ASL-Filerequester ohne großen Aufwand aufrufen SYNOPSIS file = EasyFileReq(filename,tags) D0 -132 A0 A1 FUNCTION Öffnet einen ASL-Filerequester mit den Standardwerten. Durch die Angabe von ASL-Tags kann der Requster sehr leicht den eigenen Wünschen angepasst werden. In A0 wird ein Zeiger auf einen Buffer übergeben, in den der vollständige Name (+Pfad) der ausgewählten Datei eingetragen wird. Er sollte mindestens 300 Bytes groß sein, damit bei langen Pfaden keine Probleme auftreten. Steht hier beim Aufruf ein Dateiname, so wird dieser vom Requester übernommen. Wichtige Hinweise zu den Tags: - Ab V38 der asl.library gibt es den BoolTag ASLFR_SleepWindow (= $8008002b). Der Tag funktioniert mit dieser Funktion auch unter der asl.library V36 ! - werden Tags für die Position und Größe des ASL-Requesters angegeben ($80080003-$80080006), so werden die darin enthaltenen Werten am Ende der Funktion durch die letzte Position und Größe des ASL-Requesters ersetzt ! - Die Tags zur Angabe von Verzeichnis- ($80080009) und Datei- namen ($80080009) überschreiben eine evt. Dateiangabe in A0. Außerdem müssen die bei diesen Tags angegebenen Strings groß genug sein, da sie durch den Namen der ausgewählte Datei überschrieben werden. Also: beim Verzeichnisnamen Platz für mindestens 250 Bytes und beim Dateinamen Platz für mindestens 50 Bytes lassen ! INPUTS filename - Zeiger auf einen Buffer mit dem Namen einer Datei oder Verzeichnisses, das dem Requester übergeben werden soll. Der Buffer sollte mindestens 300 Bytes groß sein. tags - Zeiger auf eine Tagliste mit ASL-Tags. Besonderheiten dazu siehe oben. RESULT file - Zeiger auf den Namen (ohne Pfad) des ausgewählten Files oder NULL = Abbruch / Fehler Im Buffer von A0 steht der vollständige Name des ausgewählten Files. WARNING Die angegebenen Buffer sollten auf jeden Fall groß genug sein, da sonst wichtige Daten im Speicher durch Dateinamen über- schrieben werden könnten. SEE ALSO paladin.library/ExpandPath paladin.library/ExpandPath NAME ExpandPath -- Alle assigns in einem Pfad ersetzen SYNOPSIS chars = ExpandPath(filename,buffer) D0:16 -90 A0 A1 FUNCTION Ermittelt den vollen Pfadnamen für einen angegebenen Pfad. Darin enthaltene assigns werden durch die vollständigen Pfadnamen ersetzt. INPUTS filename - Zeiger auf den Namen einer Datei oder Verzeichnisses mit einem assign darin. Dabei ist es egal, ob eine angegebene Datei existiert oder nicht. Beispiel: 'KEYMAPS:test',0 buffer - Zeiger auf einen Buffer, in dem der vollständige Name ohne assign reingeschrieben wird. Der Buffer sollte groß genug sein, um lange Pfadnamen aufnehmen zu können, z.B. 300 Bytes oder länger. Dabei kann als Buffer auch A0 benutzt werden. Ist A1=NULL dann wird ebenfalls A0 als Ergebnisbuffer benutzt. Ergebnisbsp.: 'System2.1:devs/keymaps/test',0 RESULT chars - Anzahl der Zeichen im Ergebnisstring (das Nullbyte wird nicht dazu gerechnet). NULL = Fehler, Pfad nicht gefunden Im Ergebnisbuffer steht dann nur ein Bullbyte. NOTE Wird nur ein Pfad- und kein Dateiname angegeben, so ist das letzte Zeichen des Ergebnisstrings immer ein ':' oder '/'. WARNING Der angegebenen Buffer sollten auf jeden Fall groß genug sein, da sonst wichtige Daten im Speicher durch den Dateinamen über- schrieben werden könnten. SEE ALSO paladin.library/FlushMem paladin.library/FlushMem NAME FlushMem -- So viel Speicher wie möglich wieder freigeben SYNOPSIS FlushMem() -54 FUNCTION Es wird versucht, so viel Speicher wie möglich freizumachen. Dabei werden alle Daten, die nicht gebraucht werden, wie z.B. Libraries, Devices, Catalogs, Fonts usw. aus dem Speicher entfernt. INPUTS Keine RESULT Keines WARNING Keine SEE ALSO CLI-Befehl: 'avail flush', Workbenchmenu: 'Debug/flushlibs' paladin.library/FreeEasyMenu paladin.library/FreeEasyMenu NAME FreeEasyMenu -- Einen EasyMenu-Speicher wieder freigeben SYNOPSIS Success = SetEasyMenu(Window) D0 -150 A0 FUNCTION Den bei der Funktion 'SetEasyMenu' belegten Speicher wieder freigeben. Sollte direkt nach CloseWindow aufgerufen werden. Hiermit kann aber kein Menu aus dem Fenster entfernt werden ! INPUTS Window - Zeiger auf das Fenster, in dem das Menu mit SetEasyMenu eingebunden wurde. Dabei sollte das Menu schon aus dem Fenster entfernt oder das Fenster geschlossen worden sein. RESULT Success - NULL (Fehler). WARNING Keine SEE ALSO SetEasyMenu, NewCloseWindow paladin.library/GetScreenXY paladin.library/GetScreenXY NAME GetScreenXY -- Darstellungsdimensionen und -typ besorgen SYNOPSIS standardX/Y,overscanX/Y,displayID = GetScreenXY(screen) D0/D1:16 D2/D3:16 D4 -96 A0 FUNCTION Mit Hilfe dieser Funktion können Sie sich Darstellungs- spezifische Werte des angegebenen Screens besorgen, ohne einen Speicherbereich zu reservieren, der dann mit diesen Daten gefüllt würde. Die Ergebnisse sind unabhängig von der Screengröße und richten sich nur nach der Darstellung. INPUTS screen - Zeiger auf den Screen, dessen Werte ermittelt werden sollen. RESULT standard X/Y - in D0 und D1 stehen die Standard-Werte des Screens für den aktuellen Darstellungstyp. Bei einem Hires Screen steht also in D0 640. Bei einem Productivity Screen würde in D1 der Wert 480 stehen. overscan X/Y - in D2 und D3 werden die aktuellen Textoverscanwerte eingetragen. displayID - Der 32Bit-Wert der Darstellung steht in D4. WARNING Keine SEE ALSO paladin.library/HandleMsg paladin.library/HandleMsg NAME HandleMsg -- Task in Wartezustand versetzen und auf Messages warten SYNOPSIS IM_Class,IM_Code,IM_Qualifier,IM_Object = HandleMsg(window) D0 D1 D2 A0 -138 A0 FUNCTION Hiermit wird das Programm in den Wartezustand versetzt (keine Rechenzeit verbrauchen, Multitasking einhalten). Nur bei auftretenden Messages wird reagiert, die wichtigsten Informationen isoliert und die Message wieder zurückgeschickt. Dabei wird die GadTools-Library verwendet kann also auch bei GadTools Gadgets wie z.B. Cycle-GG verwendet werden. INPUTS window - Zeiger auf das Fenster, das auf Messages warten soll. RESULT IM_Class - IDCMP-Klassifizierung der Msg IM_Code - Daten (z.B. Tastencode, Menupunkt) IM_Qualifier - Kopie von InputEvent IM_Object - Zeiger auf das Objekt, von dem die Msg kam (z.B. Gadget) Genaue Beschreibung siehe Intuition-Message. WARNING Keine SEE ALSO paladin.library/NewCloseWindow paladin.library/NewCloseWindow NAME NewCloseWindow -- Fenster schliessen und alles freigeben SYNOPSIS NewCloseWindow(window) -60 A0 FUNCTION Diese Funktion schließt das angegebene Fenster. Gibt, falls ein mit SetEasyMenu eingerichtetes Menu benutzt wurde, den dabei benutzten Speicher wieder frei. Falls das Fenster beim Aufruf "schlafen" sollte, wird es vorher aufgeweckt. INPUTS window - Zeiger auf das Fenster, das geschlossen werden soll. RESULT Keines WARNING Keine SEE ALSO SleepWindow, WakeUpWindow, SetEasyMenu, FreeEasyMenu paladin.library/ReqAllocVec paladin.library/ReqAllocVec NAME ReqAllocVec -- Besorgt Speicher und fängt Fehler mit Requestern ab. SYNOPSIS memory = ReqAllocVec(byteSize,requirements) D0 -66 D0 D1 FUNCTION Besorgt den angegebenen Speicher mit Hilfe von AllocVec (siehe exec.library). Dazu werden auftretende Fehler durch Requester abgefangen. Ist z.B. nicht genug Speicher vorhanden, so wird dem Benutzer dies mitgeteilt und ihm die Möglichkeit gegeben, Abzubrechen oder den benötigten Platz zu schaffen. INPUTS byteSize - Größe des gewünschten Bereichs in Bytes requirements - Art des Speichers (siehe auch exec.library) z.B. MEMB_PUBLIC = $1 MEMB_CHIP = $2 MEMB_FAST = $4 MEMB_CLEAR = $10000 RESULT memory - Adresse des Speicherbereichs oder NULL (Fehler) WARNING Keine SEE ALSO paladin.library/ReqOpenFile paladin.library/ReqOpenFile NAME ReqOpenFile -- Öffnet ein File und fängt Fehler mit Requestern ab. SYNOPSIS fielhandle,gadget = ReqOpenFile(filename,window,accessMode) D0 D1 -72 A0 A1 D0:16 FUNCTION Öffnet ein File im angegebenen Modus. Alle dabei auftretenden Fehler werden mit Hilfe von Requestern abgefangen und angezeigt. Zusätzlich zu den alten Modi von Open (Read, Write, ReadWrite) können hiermit noch bereits existierende Files optional durch neue ersetzt werden oder vom überschreiben verschont werden. Dadurch fällt die lästige Fehlerabfrage bei der Open-Funktion weg. INPUTS filename - Zeiger auf den Namen der Datei, die geöffnet werden soll. window - Zeiger auf das Fenster, auf dessen Screen der Requester geöffnet wird. NULL = Workbench accessMode - Flags, die den Zugriff auf die Datei angeben: OF_Read = $0001; Lesen OF_Write = $0002; Schreiben OF_Replace = $0004; immer Ersetzen OF_Cancel_GG = $0008; 'Abbruch'-Gadget Nr.0 OF_Ok_GG = $0010; 'Ok'-Gadget Nr.1 OF_IgnoreAll_GG = $0020; 'Alles Ignorieren'-Gadget Nr.2 OF_Ignore_GG = $0040; 'Ignorieren'-Gadget Nr.3 OF_ReplaceAll_GG = $0080; 'Alles Ersetzen'-Gadget Nr.4 OF_Replace_GG = $0100; 'Ersetzen'-Gadget Nr.5 OF_Read - Öffnet eine Datei zum Lesen von Daten. Existiert die Datei nicht oder tritt ein anderer Fehler auf, so wird der Benutzer mit einem Requester, der die angegebenen Gadgets enthält, darauf hingewiesen. OF_Write - Öffnet eine Datei zum Schreiben von Daten. Wenn die Datei bereits existiert oder ein anderer Fehler auftritt, so wird der Benutzer mit einem Requester, der die angegebenen Gadgets enthält, darauf hingewiesen. OF_Replace - Öffnet eine Datei zum Schreiben von Daten. Wenn die Datei bereits existiert, so wird sie durch die neue ohne eine Meldung überschrieben. Eignet sich besonders für ReplaceAll. OF_Cancel_GG - Requester haben ein 'Abbruch'-Gadget. Ergebnisnummer = 0 OF_Ok_GG - Requester haben ein 'Ok'-Gadget. Ergebnisnummer = 1 OF_IgnoreAll_GG - Requester haben ein 'Alles ignorieren'-Gadget. Ergebnisnummer = 2 OF_Ignore_GG - Requester haben ein 'Ignorieren'-Gadget. Ergebnisnummer = 3 OF_ReplaceAll_GG - Requester haben ein 'Alles ersetzen'-Gadget. Ergebnisnummer = 4 OF_Replace_GG - Requester haben ein 'Ersetzen'-Gadget. Ergebnisnummer = 5 RESULT filehandle - BPTR-Zeiger auf eine FileHandle-Struktur. D0= 0: Abbruch oder kein File vorhanden gadget - Nummer des ausgewählten Gadgets (s.o.) D1=-1: kein Gadget ausgewählt, kein Requester angezeigt. EXAMPLE D1 = $0049; es sollen 1 Datei gelesen werden. Die Datei existiert nicht, nun kann der Benutzer den Fehler ignorieren oder Abbrechen. Dies muß dann im Programm verarbeitet werden. D1 = $018A; es sollen 6 Dateien geschrieben werden. Die Datei existiert schon. Der Benutzer kann entweder abbrechen oder die Datei durch die neue ersetzen ('Ersetzen' oder 'Alles ersetzen' anwählen). Wird 'Alles ersetzen' ausgewählt, sollte der Aufruf für die restlichen Files mit D1 = $0006 erfolgen. D1 = $0003 Entspricht dem alten ReadWrite der Dos-Open Funktion. Da keine Gadgets angegeben wurden, wird bei Problemen auch kein Requester dargestellt. WARNING Keine SEE ALSO paladin.library/SetAfPt paladin.library/SetAfPt NAME SetAfPt -- Festlegung des Linienmusters SYNOPSIS SetAfPt(rastport,pattern,areasize) -102 A1 A0 D0:8 FUNCTION Mit Hilfe dieses ehemaligen C-Makro können Sie ein Füllmuster festlegen, das von nun an von den Befehlen RectFill(), Flood() und Area...() benutzt wird. Sie haben die Möglichkeit, ein einfarbiges Füllmuster, das mit der Farbe des APens und im aktuellen Zeichenmodus gezeichnet wird, oder ein mehrfarbiges Füllmuster zu definieren. Dabei ist die Breite des Musters auf 16 Punkte begrenzt, die Höhe kann variiren. INPUTS rastport - Adresse der Rastport-Struktur, der ein neues Füll- muster übergeben werden soll. pattern - Im Muster-Array wird das Bitmuster des Füllmusters abgespeichert. Die Dimension des Arrays richtet sich nach areasize: areasize - gibt an, wie hoch das neue Füllmuster ist. Dabei sind nur Höhen, die eine Potenz von 2 sind (0,1,2,4,8,...) zulässig. Sie geben in areasize aber nicht, wie zu erwarten wäre, die Höhe der Zeilen direkt an, sondern die Potenz zu Basis 2, die die Höhe bestimmt. Bei mehrfarbigen Füllmustern wird diese Potenz mit negativem Vorzeichen angegeben. Das Muster-Array muß dann ein Bitmuster für jede Bitplane zur verfügung stellen. RESULT Keines WARNING Keine SEE ALSO paladin.library/SetDrPt paladin.library/SetDrPt NAME SetDrPt -- Festlegung des Linienmusters SYNOPSIS SetDrPt(rastport,pattern) -108 A1 D0:16 FUNCTION Dieses ehemalige C-Makro legt das Linienmuster fest, in dem von nun an Linien gezeichnet werden. Das Muster ist nur 16 Punkte breit. Somit wiederholt es sich nach 16 gezeichneten Punkten der Linie. INPUTS rastport - Rastport, in dem das Linienmuster geändert werden soll. pattern - Gibt das neue Linienmuster an. Jedes gesetzte Bit dieses Wortes repräsentiert einen gesetzten Punkt der Linie. RESULT Keines WARNING Keine SEE ALSO paladin.library/SetEasyMenu paladin.library/SetEasyMenu NAME SetEasyMenu -- Einrichten und setzen eines kompletten Menus SYNOPSIS Menu = SetEasyMenu(Window,EasyMenu,TagList,LocaleData) D0 -144 A0 A1 A2 A3 FUNCTION Diese Funktion ist der einfachste Weg, ein Menu zu erstellen und im angegebenen Fenster einzubinden. Zusätzlich kann die Funktion die Zeiger auf die verwendeten Texte durch neue ersetzen, die auf Texte im angegebenen Katalog verweisen. So kann ein komplettes Menu ohne Aufwand Locale-orientiert programmiert werden. Natürlich werden auch eingestellte Farben und Fonts durch den Einsatz von GadTools berücksichtigt. INPUTS Window - Zeiger auf das Fenster, in dem das Menu eingebunden werden soll. EasyMenu - Zeiger auf eine EasyMenu-Liste. Die Reihenfolge der Strukturen ist wichtig (siehe auch GadTools). Die Liste wird mit einem NULL-Word beendet. TagList - Zeiger auf eine TagList mit Tags für das Menu. (siehe auch GadTools). Sonst NULL. LocaleData - Zeiger auf die LocaleData Struktur. Ist nur dann erforderlich, wenn das Menu mit Locale-Texten ausgestattet werden soll. Sonst NULL. Mehr zur Locale-Programmierung mit dem Labeln 'LOCALE_START' und 'LOCALE_END' siehe im AMIGA- Magazin 10+11/92 und die MakeCat-Dokumentation! Dec Hex STRUCTURE EasyMenu,0 0 $0 UBYTE EM_Type ;s.u. (siehe auch GadTools-NewMenu) 1 $1 UBYTE EM_EasyFlags ;s.u. 2 $2 UWORD EM_Flags ;s.u. (siehe auch Intuition-Menu) 4 $4 APTR EM_Label ;Zeiger auf Text 8 $8 APTR EM_CommKey ;Zeiger auf ShortCut oder NULL 12 $C APTR EM_Private ;noch auf NULL setzen! 16 $10 LABEL EM_SIZEOF Dec Hex STRUCTURE LocaleData,0 0 $0 APTR Catalog ;Zeiger auf den offenen Katalog 4 $4 APTR LOCALE_START ;Zeiger auf das Label 'Locale_Start' 8 $8 LABEL LM_SIZEOF EM_Type: NM_End = $0 ;Ende der EasyMenu-Struktur NM_Title = $1 ;MenuTitel NM_Item = $2 ;Menupunkt NM_Sub = $3 ;Unterpunkt NM_Ignore = $40 ;Eintrag ignorieren (ab V39) NM_Image = $80 ;Image statt Text verwenden EM_EasyFlags: EF_TranslateLabel = $1 ;LocaleLabel verwenden EF_TranslateShort = $2 ;LocaleShort verwenden EF_BarLabel = $10 ;Trennlinie einfügen EM_Flags: IM_CheckIt = $1 ;abhaken bei Anwahl NM_MenuDisable = $1 ;Anwahl unmöglich (nur bei EM_Type=1) IM_MenuToggle = $8 ;umschalten bei Anwahl NM_ItemDisable = $10 ;Anwahl unmöglich (bei EM_Type=2,3) IM_Checked = $100 ;wenn CheckIt: Item ist abgehakt RESULT Menu - Fertig eingebundener Menu-Strip oder NULL (Fehler). EXAMPLE Eine EasyMenu-Struktur könnte zum Beispiel so aussehen: EasyMenu dc.l $01010000,MText_100,0,0 ;Der 1. Menutitel (Locale) dc.l $02000080,MText_110,A_Key,0 ;1. Menupunkt mit ShortCut dc.l $02000000,MText_120,0,0 ;2. Menupunkt mit Submenu dc.l $03000000,MText_121,0,0 ;1. Submenupunkt dc.l $03100000,0,0,0 ;Ein Trennstrich dc.l $03030000,MText_122,B_Key,0 ;2. Submenupunkt mit ShortCut (beides Locale) dc.l $03000000,-1,0,0 ;Auch ein Trennstrich dc.l $82000000,Image,0,0 ;Ein Image statt Text dc.l $02000000,MText_140,0,0 ;Und noch ein Menupunkt dc.w 0 ;Ende des Menus WARNING keine SEE ALSO FreeEasyMenu, NewCloseWindow paladin.library/SetOPen paladin.library/SetOPen NAME SetOPen -- Umrandungsfarbstift festlegen SYNOPSIS OldOPen = SetOPen(rastport,pen) D0 -120 A1 D0:8 FUNCTION Ähnlich wie SetAPen() und SetBPen() legt dieses ehemaliges C-Makro einen neuen Umrandungsstift fest. Dieser wird besonders bei RectFill()-, Flood()- und den Area...()-Befehlen verwendet. Während er bei RectFill() und Area...() einen aktiven Part übernimmt, bestimmt der OPen (bzw. AOlPen) bei Flood() die Grenzen der zu füllenden Fläche. In D0 wird der bisher benutzte OPen zurückgegeben. Sollten Sie schon mit OS3.0 (V39) arbeiten, so wird automatisch SetOutlinePen aufgerufen! INPUTS rastport - Rastport, dessen Umrandungsstift geändert werden soll. pen - Nummer des Farbregisters, in dessen Farbe die Um- randungslinien gezeichnet werden sollen. RESULT OldOPen - Nummer des Farbregisters, das bisher als OPen benutzt wurde. WARNING Keine SEE ALSO BndryOff paladin.library/SetWrMsk paladin.library/SetWrMsk NAME SetWrMsk -- Festlegen der Bitplanes, die beschrieben werden können. SYNOPSIS SetWrMsk(rastport,mask) -114 A1 D0:8 FUNCTION Dieses ehemalige C-Makro legt fest, welche Bitplanes einer BitMap von Schreiboperationen (Punkt setzen bzw. löschen, Linie ziehen, etc.) betroffen werden können. Sollten Sie schon mit OS3.0 (V39) arbeiten, so wird automatisch SetWriteMask aufgerufen! INPUTS rastport - Rastport, dessen Schreibmaske geändert werden soll. mask - Bit-Maske der Bitplanes, die betroffen werden können. Dabei repräsentiert Bit 0 die Bitplane[0], Bit 1 die Plane[1] usw. RESULT Keines WARNING Keine SEE ALSO paladin.library/SleepWindow paladin.library/SleepWindow NAME SleepWindow -- Fenster "einschläfern" SYNOPSIS success = SleepWindow(window) D0 -78 A0 FUNCTION Bringt ein Fenster in den Wartestatus: Alle Gadgets werden gesperrt, das Menu verschwindet und ein Sleep-Mauszeiger erscheint. INPUTS window - Zeiger auf das Fenster, das in den Wartestatus gebracht werden soll. RESULT success - NULL: Fenster schläft schon. WARNING Keine SEE ALSO WakeUpWindow, NewCloseWindow paladin.library/WakeUpWindow paladin.library/WakeUpWindow NAME WakeUpWindow -- Fenster wieder "aufwecken" SYNOPSIS success = WakeUpWindow(window) D0 -84 A0 FUNCTION Weckt ein Fenster wieder auf, das mit SleepWindow in den Wartestatus gebracht wurde. INPUTS window - Zeiger auf das Fenster, das wieder aktiv werden soll. RESULT success - NULL: Fenster war schon wach. WARNING Keine SEE ALSO SleepWindow, NewCloseWindow