Amiga ISO Collection

home *** CD-ROM | disk | FTP | other *** search

/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / C / OTL-MC4.DMS / in.adf / Archive / Prog.lha / Docs / Funktionen < prev next >

Wrap

Text File | 1994-02-14 | 82.7 KB | 2,031 lines

HotHelp-Funktionen ================== Diese Datei beschreibt alle Funktionen der HotHelp.Library. Die Beschreibungen sind in Form von C-Kommentaren gehalten und in alphabetischer Reihenfolge abgelegt. Funktionen, die in späteren Library-Version neu hinzugekommen sind, werden durch die Kennung der entsprechenden Version am Kopf der Beschreibung gekennzeichnet - im Moment handelt es sich hierbei lediglich um das Kürzel '(V3)' für unter Version 3 hinzugekommene Funktionen. Die Funktionen können neben der alphabetischen Ordnung auch noch in mehrere Gruppen eingeteilt werden: Öffnen eines HotHelp-Fensters: ============================= HH_ShowHelp HH_ShowHelpTagList (V3) HH_EasyHelp HH_EasyASyncHelp (V3) Steuerung von asynchronen Fenstern: ================================== HH_ASyncActivate (V3) HH_ASyncCheckWindow (V3) HH_ASyncCloseWindow (V3) HH_ASyncCustomText (V3) HH_ASyncGadget (V3) HH_ASyncMenu (V3) HH_ASyncPage (V3) HH_ASyncScroll (V3) HH_ASyncSearch (V3) HH_ASyncStatus (V3) HH_ASyncStrGadget (V3) HH_ASyncWindowAddr (V3) Funktionen für HotHelp-Handler: ============================== HH_AddHandler (V3) HH_RemHandler (V3) HH_CheckPattern (V3) HH_Translate (V3) HH_TranslateFree (V3) Sonstige HotHelp-Funktionen: =========================== HH_AddProject HH_CheckProject (V3) HH_FontVersion HH_KeyList (V3) HH_OpenAll HH_ProjectList (V3) Allgemeine Funktionen: ===================== HH_Beep (V3) HH_BuildMenus (V3) HH_CreatePath (V3) HH_FileRequest (V3) HH_Request (V3) HH_ScanPalette (V3) HH_Semprini (V3) HH_SetPointer (V3) HH_StrCmp (V3) HH_StrNCmp (V3) HH_ToUpper (V3) /*----------------------------------------------------------------------*\ NAME HH_AddHandler - Installiert einen neuen Handler. (V3) SCHREIBWEISE VOID HH_AddHandler ( struct Interrupt * ir ) FUNKTION Mit dieser Funktion ist es möglich, HotHelp um einen neuen Handler zu erweitern (eine genaue Beschreibung von HotHelp-Handlern finden Sie in der Datei 'Handler'). Sowohl die verwendete Interrupt-Struktur als auch der Code der Handler-Funktion selber dürfen erst wieder geändert oder freigegeben werden, wenn der Handler durch 'HH_RemHandler ()' wieder entfernt wurde. EINGABEN ir: Zeiger auf eine Interrupt-Struktur. Dabei müssen die folgenden Felder initialisiert werden: is_Code: In dieser Variablen wird die Startadresse der Funktion festgehalten, die als Handler aufgerufen werden soll. is_Data: Der Inhalt dieser Variablen wird dem Handler später bei jedem Aufruf in Register A1 übergeben. Sofern benötigt, kann hier z.B. die Adresse eines vom Handler verwendeten Datenbereiches angegeben werden. is_Node.ln_Pri: Die Priorität des Handlers. Es kann ein Wert zwischen -128 und 127 angegeben werden. Je höher der Wert ist, desto eher wird der Handler im Fall eines unbekannten Schlüssels angesprochen. Im Normalfall sollte ein Wert von 0 angegeben werden. Alle anderen Elemente der Struktur sollten mit 0 initialisiert werden. ERGEBNIS BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_AddProject - Lädt ein neues Projekt SCHREIBWEISE LONG HH_AddProject ( BYTE * pro_path, BYTE * pro_name, LONG force ) FUNKTION Normalerweise werden beim Öffnen des ersten Hilfs-Fensters alle in 'HOTHELP:Projekte' gefundenen Projekte geladen. Über diese Funktion kann davon abweichend ein Projekt aus einem beliebigen Verzeichnis geladen werden. EINGABEN pro_path: Zeiger auf einen String mit dem Namen des Verzeichnisses, in dem sich das zu lesende Projekt befindet. pro_name: Name des Projektes, das geladen werden soll. force: Falls das Projekt ausgeschaltet ist, kann über diesen Parameter bestimmt werden, ob es dennoch geladen werden soll. Ist 'force' TRUE, wird der Zustand des Projektes ignoriert und es wird in jedem Fall geladen; ansonsten wird 'HH_ERROR_DISABLED' zurück- gegeben, wenn ein ausgeschaltetes Projekt angesprochen wurde. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncActivate - Aktivieren eines asynchronen HotHelp-Fensters. (V3) SCHREIBWEISE LONG HH_ASyncActivate ( LONG id ) FUNKTION Ein asynchrones Fenster kann mit Hilfe dieser Funktion wieder aktiviert werden. Dabei werden folgende Aktionen durchgeführt: Der Screen, auf dem sich das Window befindet, wird vor alle anderen gebracht. Falls er nach unten gezogen wurde, wird er wieder an den oberen Bildschirmrand gebracht. Das Fenster wird vor alle anderen Fenster gebracht und anschließend aktiviert. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncCheckWindow - Überprüft, ob ein asynchrones Fenster noch existiert. (V3) SCHREIBWEISE LONG HH_ASyncCheckWindow ( LONG id ) FUNKTION Diese Funktion überprüft, ob ein vorher geöffnetes asynchrones Fenster noch existiert oder ob es zwischenzeitlich bereits geschlossen wurde. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier untersucht werden soll. ERGEBNIS TRUE - Das überprüfte Fenster existiert noch. FALSE - Das überprüfte Fenster ist geschlossen. \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncCloseWindow - Schließen eines asynchronen HotHelp-Fensters. (V3) SCHREIBWEISE LONG HH_ASyncCloseWindow ( LONG id ) FUNKTION Mit dieser Funktion kann ein asynchrones Fenster wieder geschlossen werden, ohne daß der User das Schließ-Gadget benutzt. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncCustomText - Zeigt einen Text an, der nicht aus einer Projekt-Datei stammt. (V3) SCHREIBWEISE LONG HH_ASyncCustomText ( LONG id, struct HH_CustomText * text, BYTE * input_pro, BYTE * input_key ) FUNKTION Normalerweise zeigen HotHelp-Fenster nur Texte an, die sich in Projekt-Dateien befinden, die vom Programm HotHelpComp erstellt wurden. Mit Hilfe dieser Funktion ist es nun auch möglich, in einem asynchronen HotHelp-Fenster einen beliebigen Text anzeigen zu lassen. Dazu muß die Adresse des Speicherbereiches, in dem der Text abgelegt wurde, zusammen mit einigen weiteren Informationen in einer HH_CustomText-Struktur festgehalten und dann dieser Funktion übergeben werden. HotHelp stellt den entsprechenden Text dann dar. Diese Methode hat nur einen Nachteil: Da der Text nicht aus einer Projekt-Datei stammt, kann er auch nicht mehr zurückgeholt werden, wenn der Benutzer anschließend einen weiteren Text lädt. Das Vortext-Gadget zeigt in diesem Fall lediglich den Projekt-Text an, der vor dem Einfügen dieses Textes geladen war. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. text: Ein Zeiger auf eine initialisierte HH_CustomText-Struktur. Nähere Informationen finden Sie bei der Beschreibung der Struktur. input_pro, input_key: Über diese beiden Zeiger kann der Inhalt der beiden Eingabe-Gadgets geändert werden. Die hier angegebenen Strings ersetzen dazu den alten Inhalt des Projekt-und Schlüssel-Gadgets. Ist dies nicht gewünscht, muß für beide Variablen NULL übergeben werden. Es ist nicht möglich, nur eines der beiden String-Gadgets allein zu beeinflußen. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncGadget - Steuerung der Gadgets eines asynchronen HotHelp- Fensters. (V3) SCHREIBWEISE LONG HH_ASyncGadget ( LONG id, LONG mask ) FUNKTION Über diese Funktion können alle Gadgets eines HotHelp-Windows angesprochen werden, als hätte der Benutzer sie selber angewählt. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. mask: Eine Maske mit den HH_GADGET_-Codes. Werden mehrere Codes zusammen-geodert, werden die entsprechenden Gadgets nacheinander angewählt. Das Hilfe-Gadget kann durch diesen Aufruf nicht angesprochen werden. Ebenso wird ignoriert, wenn das Fenster vom Anwender in den Hilfsmodus geschaltet wurde. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncMenu - Steuerung der Menus eines asynchronen HotHelp-Fensters. (V3) SCHREIBWEISE LONG HH_ASyncMenu ( LONG id, WORD menu, WORD item ) FUNKTION Mit Hilfe dieser Funktion kann von außen die Auswahl eines Menupunktes durch den User simuliert werden. Das HotHelp-Fenster verhält sich genauso, als wenn der Benutzer das Menu von Hand angewählt hätte. Bei Angabe von unzulässigen Menu- oder Item-Werten wird ein Fehlercode zurückgegeben. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. menu: Die Nummer des Menus, aus dem das entsprechende Item angewählt wird. Die Zählung beginnt immer bei 0, so daß 0 für das Views-Menu steht, 1 für das Such-Menu etc. item: Die Nummer des Items innerhalb des Menus 'menu'. Auch hier beginnt die Zählung immer bei 0. Item 3 in Menu 2 setzt z.B. die Textmarke Nr. 4 auf die aktuelle Position. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncPage - Seitenweises Scrollen des Textes im HotHelp-Fenster (V3) SCHREIBWEISE LONG HH_ASyncPage ( LONG id, LONG step ) FUNKTION Diese Funktion dient dazu, den Text im entsprechenden HotHelp-Fenster um eine Seite nach oben, unten, rechts oder links bzw. an den Textanfang oder das Textende zu scrollen. Bitte beachten Sie, daß ein Links-/Rechts-Scrolling des Textes nur sinnvoll ist, wenn der Text über Zeilen verfügt, die nicht als Fließtext umgebrochen werden. Sie können das Vorhandensein solcher Zeilen über die Funktion 'HH_ASyncStatus ()' abfragen; wenn die Länge der längsten Zeile (txt_columns) größer ist als die Anzahl von darstellbaren Zeichen in einer Zeile (win_columns), kann über diese Funktion der sichtbare Textausschnitt verschoben werden (die Nummer der ersten dargestellten Spalte geht aus 'first_column' hervor). Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. step: Die Variable darf 8 verschiedene Werte annehmen: -1: Scrollt zeilenweise eine Seite in Richtung Textanfang. 1: Scrollt zeilenweise eine Seite in Richtung Textende. -2: Zeigt die oberste Seite des Textes an. 2: Zeigt die unterste Seite des Textes an. -3: Scrollt spaltenweise eine Seite in Richtung Zeilenanfang. 3: Scrollt spaltenweise eine Seite in Richtung Zeilenende. -4: Bringt den sichtbaren Textausschnitt ganz nach vorne, so daß die Anfänge aller Zeilen sichtbar sind. 4: Bringt den sichtbaren Textausschnitt ganz nach hinten, so daß das Ende der längsten Zeile des Textes sichtbar ist. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncScroll - Scrollen des Textes im HotHelp-Fenster (V3) SCHREIBWEISE LONG HH_ASyncScroll ( LONG id, LONG lines, LONG columns ) FUNKTION Diese Funktion dient dazu, den Text im entsprechenden HotHelp-Fenster um eine gewisse Anzahl von Zeilen nach oben oder unten zu scrollen. Werden beim Scrollen der Anfang oder das Ende des Textes erreicht, bricht die Funktion automatisch ab. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. lines: Die Anzahl von Zeilen, die gescrollt werden. Bei einem positiven Wert wird der Textausschnitt in Richtung Textende verschoben, bei einem negativen in Richtung Textanfang. 0 wird ignoriert. columns: Die Anzahl von Spalten, die gescrollt werden soll. Bei einem positiven Wert wird der Textausschnitt nach rechts, bei einem negativen nach links verschoben. 0 wird ignoriert. Bitte bachten Sie auch die bei 'HH_ASyncPage ()' gemachten Bemerkungen zum Thema Links-Rechts-Scrolling. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncSearch - Suchen innerhalb eines HotHelp-Fensters (V3) SCHREIBWEISE LONG HH_ASyncSearch ( LONG id, BYTE * str, UWORD flags ) FUNKTION Mit Hilfe dieser Funktion kann die Such-Funktion eines HotHelp-Fensters gesteuert werden. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. str: Zeiger auf den String mit dem Suchbegriff. Der String darf nicht leer sein! flags: Eine Kombination der drei HH_SEARCH_...-Flags, die den drei Checkmark-Gadgets im Such-Fenster entsprechen. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncStatus - Abfragen des Status eines asynchronen HotHelp-Fensters. (V3) SCHREIBWEISE LONG HH_ASyncStatus ( LONG id, struct HH_Status * status ) FUNKTION Über diese Funktion kann der Status eines asynchronen HotHelp-Fensters abgefragt werden. Dies umfaßt den eingegebenen Projekt- und Schlüssel-Begriff, Projekt- und Schlüssel des aktuell dargestellten Textes, die Anzahl von Zeilen und Spalten, die im Fenster angezeigt werden können, die Anzahl von Zeilen und Spalten im gesamten Text und die Nummer der ersten sichtbaren Zeile und Spalte. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. status: Zeiger auf eine HH_Status-Struktur, die von HotHelp mit sinnvollen Werten ausgefüllt wird (sofern kein Fehler auftritt; dann ist der Inhalt der Struktur undefiniert). ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG Da der Benutzer jederzeit den sichtbaren Textausschnitt verschieben oder einen neuen Text einlesen kann, kann nicht garantiert werden, daß die Struktur den tatsächlichen Inhalt des HotHelp-Fensters beschreibt. Ggf. sollte daher mit 'Forbid ()' gearbeitet werden. \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncStrGadget - Steuerung der String-Gadgets eines asynchronen HotHelp-Fensters. (V3) SCHREIBWEISE LONG HH_ASyncStrGadget ( LONG id, BYTE * new_project, BYTE * new_key, BYTE * old_project, BYTE * old_key, BOOL check_all, WORD group ) FUNKTION Diese Funktion ermöglicht das Setzen bzw. Auslesen der beiden String-Gadgets eines asynchronen HotHelp-Fensters. Auslesen und Setzen können auch miteinander verknüpft werden; in diesem Fall werden die alten Inhalte der Gadgets (vor der angeforderten Änderung) zurückgegeben. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. new_project, new_key: Zeiger auf den neuen Projekt- bzw. Schlüssel-String. Die Strings dürfen nicht länger als HH_PROJECT_LEN - 1 bzw. HH_KEY_LEN - 1 sein. Die Eingaben werden so behandelt, als hätte der User die Strings von Hand in die beiden Gadgets eingetragen und dann durch <Return> bestätigt. Soll ein String unverändert bleiben, kann die entsprechende Variable als NULL übergeben werden. Werden beide auf NULL gesetzt, werden sie ignoriert. old_project, old_key: Zeiger auf mindestens HH_PROJECT_LEN bzw. HH_KEY_LEN Speicher. Die Inhalte der beiden String-Gadgets werden in diese Bereiche kopiert. Wird statt einer Adresse NULL übergeben, wird die entsprechende Variable ignoriert. Bei zwei NULLs wird keine Aktion ausgeführt. Trat bei der Ausführung ein Fehler auf, beinhalten diese Variablen keine sinnvollen Werte. check_all: Dieser Parameter entspricht der 'OpenAll'-Option, die beim Öffnen eines HotHelp-Fensters angegeben werden kann. Er ist nur sinnvoll, wenn auch 'new_project' und/oder 'new_key' angegeben werden. Falls in dem angegebenen Projekt kein Schlüssel des gesuchten Namens gefunden wird und wenn hier TRUE übergeben wurde, durchsucht HotHelp anschließend alle übrigen Projekte nach diesem Schlüssel. Wird FALSE übergeben, wird lediglich eine Fehlermeldung ausgegeben. Auf diese Weise kann der Projekt-String als eine Art Vorgabe aufgefaßt werden: Wird der gesuchte Schlüssel dort gefunden, wird er dargestellt - andernfalls werden automatisch auch alle übrigen Projekte durchsucht. group: Über diesen Parameter kann die Schlüssel-Gruppe ausgewählt werden, aus der der gesuchte Schlüssel entnommen werden soll. Die Option ist sehr nützlich, wenn ein Schlüssel mehrmals in einem Projekt, aber jeweils in unterschiedlichen Gruppen auftaucht, um gezielt einen bestimmten dieser Schlüssel ansprechen zu können. Werte kleiner 1 und größer 255 werden ignoriert. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ASyncWindowAddr - Ermitteln der Window-Adresse eines asynchronen HotHelp-Fensters. (V3) SCHREIBWEISE LONG HH_ASyncWindowAddr ( LONG id, struct Window ** win ) FUNKTION Über diese Funktion kann die Adresse des Windows eines asynchronen HotHelp-Fensters ermittelt werden. Die Funktion darf auch auf Fenster angewendet werden, die bereits geschlossen wurden, da die Library diesen Fall abfängt. EINGABEN id: Die ID des asynchronen Fensters, die von 'HH_EasyASyncHelp ()' oder über das ID-Tag von 'HH_ShowHelpTagList ()' zurückgegeben wurde und die das Fenster beschreibt, das hier manipuliert werden soll. win: Wenn die Funktionen keinen Fehler zurückliefert (HH_ERROR_NONE), befindet sich in der Variable, auf die dieser Parameter zeigt, die Adresse der Window-Struktur des HotHelp-Fensters. Ansonsten ist ihr Inhalt undefiniert. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG Der Aufruf dieser Funktion und die Auswertung des Rückgabewertes muß grundsätzlich bei ausgeschaltetem Multitasking ('Forbid ()') erfolgen, da andernfalls immer die Gefahr besteht, daß das Fenster vom User geschlossen wird - was zu einem ungültigen Zeiger und wahrscheinlich zu einem Absturz führt! Die Window-Struktur darf nur ausgelesen werden - eine Änderung (gleich welcher Art) wird nicht unterstützt und kann zu beliebig katastrophalen Ergebnissen führen! \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_Beep - Aufblitzen des Bildschirms + Piepton (V3) SCHREIBWEISE VOID HH_Beep ( struct Screen * screen ) FUNKTION Während die Intuition-Funktion 'DisplayBeep ()' den Bildschirm nur kurz aufblitzen läßt, gibt diese Funktion gleichzeitig auch noch einen Piepton aus (sofern diese Option nicht über HotHelpPref ausgeschaltet wird). EINGABEN screen: Adresse des Screens, der aufblitzen soll bzw. NULL, wenn alle Screens kurz hervorgehoben werden sollen. ERGEBNIS BEMERKUNG Der Einfachkeit halber wird der Piepton einfach über die Hardware erzeugt. Erzeugt gleichzeitig noch ein anderes Programm Sound (z.B. auch über das Audio-Device), hört sich das Ergebnis wahrscheinlich nicht sehr gut an... Weiterhin muß noch beachtet werden, daß die Funktion nur von Prozessen aufgerufen werden darf, da sie die DOS-Funktion 'Delay ()' verwendet. \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_BuildMenus - Erzeugen von Menus aus NewMenu-Strukturen (V3) SCHREIBWEISE struct Menu * HH_BuildMenus ( struct NewMenu * newmenu, struct Remember ** remember, struct Screen * screen, struct TextFont * tf, BOOL * gadtools_menus, BOOL get_shortcuts ) FUNKTION Diese Funktion ähnelt den Funktionen 'CreateMenus ()' und 'LayoutMenus ()' der GadTools-Library, da sie aus einem Feld von NewMenu-Strukturen eine verkettete Liste von Menu-, MenuItem- und IntuiText-Strukturen erzeugt, die direkt als Menu ans Intuition weitergereicht werden kann. Ab OS 2.0 greift die Funktion dazu auf die GadTools-Library zurück; unter älteren OS-Versionen werden die benötigten Strukturen von Hand erzeugt. Ab OS 3.0 werden die Menus mit dem neuen NEWLOOK-Design erzeugt, so daß das entsprechende Fenster auch mit dem WFLG_NewLookMenus-Flag geöffnet werden sollte. EINGABEN newmenu: Zeiger auf ein Feld von NewMenu-Strukturen. Die folgenden Features dürfen nicht verwendet werden: IM_ITEM, IM_SUB, NM_IGNORE, 'nm_UserData'. Alle anderen GadTools-Möglichkeiten werden unterstützt. Shortcuts können auf zwei Wegen angegeben werden: als String in 'nm_CommKey' oder integriert in 'nm_Label'. Die zweite Möglichkeit ist sehr praktisch, wenn das Menu an mehrere Sprachen angepaßt werden soll, da der Shortcut und die Beschriftung zu einem String zusammengefaßt sind. Der Shortcut muß dazu (umgeben von zwei Underscores) an den Anfang des Strings gesetzt werden. "_s_Sichern" ist ein Beispiel für ein MenuItem mit dem Text "Sichern" und dem Shortcut "s". Unter OS 1.3 und 2.0 können andere Shortcuts als Kombinationen mit der Amiga-Taste (wie z.B. CTRL-1 in HotHelp-Fenstern) nur angezeigt werden, indem der entsprechende Text an den eigentlichen Itemtext angehängt wird; also: "Setze Marke 1 CTRL-1". Ab OS 3.0 können auch Shortcuts mit mehr als einem Zeichen angegeben werden. Damit ein Item mit mehrbuchstabigem Shortcut unter allen Betriebssystem-Versionen angezeigt werden kann, muß der Text in folgendem Format vorliegen: "_shortcut_ItemText shortcut". Das obige Beispiel müßte also als "_CTRL-1_Setze Marke 1 CTRL-1" abgelegt werden. Ist der Shortcut am Anfang des Strings also länger als ein Zeichen, geht HotHelp davon aus, daß der String in genau diesem Format vorliegt und behandelt ihn entsprechend. Die Library ändert zwar nicht die Strings in den NewMenu-Strukturen, dafür jedoch die NewMenu-Strukturen selber (Shortcuts am Stringanfang werden z.B. übersprungen, indem der 'nm_Label'-Zeiger einfach entsprechend erhöht wird). Dies sollte beachtet werden, wenn die Funktion mehrmals mit denselben Strukturen aufgerufen wird. remember: Falls noch Speicher für die Umwandlung benötigt wird, wird er über diesen Schlüssel von der Library angelegt; wird das Menu nicht mehr verwendet, kann der Speicher über 'FreeRemember ()' einfach wieder freigegeben werden. screen: Zeiger auf den Screen, auf dem das Menu später dargestellt werden soll. Ab OS 2.0 muß hier ein echter Screen übergeben werden; unter OS 1.3 reicht auch eine über 'GetScreenData ()' initialisierte Kopie aus. tf: Die Menus werden unter Verwendung dieses Zeichensatzes aufgebaut. Unter OS 1.3 wird, sofern die Menus zu groß für den Screen werden, auf Topaz-8 zurückgeschaltet. gadtools_menus: Die Variable, auf die dieser Parameter zeigt, kann nach der Ausführung einen der beiden folgenden Werte beinhalten: TRUE - Die Menus wurden mit Hilfe der GadTools-Library erzeugt; sie müssen später wieder über 'FreeMenus ()' und 'FreeRemember (remember) freigegeben werden. FALSE - Die Menus wurden von Hand erzeugt; sie werden freigegeben, indem der Schlüssel 'remember' an 'FreeRemember ()' übergeben wird. get_shortcuts: Dieses Flag muß gesetzt werden, wenn die Library die übergebenen Labels nach Shortcuts durchsuchen soll. ERGEBNIS Ein Zeiger auf den erzeugten Menustrip bzw. NULL, wenn ein Fehler auftrat. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_CheckPattern - Vergleich eines HotHelp-Patterns mit einem String (V3) SCHREIBWEISE BOOL HH_CheckPattern ( BYTE * pattern, BYTE * str ) FUNKTION Die Funktion vergleicht einen Muster-String mit einem weiteren String und entscheidet, ob das Muster den zweiten String beschreibt oder nicht. Sie sollte lediglich von Handlern verwendet werden, die von HotHelp ein Muster als Projekt- oder Schlüssel-Name erhalten. Der Handler kann dann mit Hilfe dieser Funktion alle von ihm verwalteten Projekte oder Schlüssel mit dem entsprechenden Muster auf Gleichheit überprüfen und so dem Benutzer eine Auswahl seiner Schlüssel zur Verfügung stellen. Dadurch wird gewährleistet, daß auch bei einer späteren Erweiterung von HotHelps Muster-Möglichkeiten die Handler dieselben Muster wie die jeweils aktuelle Library-Version anerkennen. Ausführliche Informationen über Handler finden Sie in der gleichnamigen Datei. EINGABEN pattern: Zeiger auf den String mit dem Muster, der von der Library an den Handler übergeben wurde. str: Zeiger auf den String, der mit dem Muster in 'pattern' verglichen werden soll. ERGEBNIS TRUE - 'pattern' und 'str' stimmen überein. FALSE - Keine Übereinstimmung. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_CheckProject - Überprüft, ob ein Projekt aktiv ist oder nicht (V3) SCHREIBWEISE BOOL HH_CheckProject ( BYTE * name ) FUNKTION Mit Hilfe dieser Funktion kann überprüft werden, ob ein bestimmtes Projekt existiert und aktiv ist - das bedeutet, daß jetzt Schlüssel aus diesem Projekt abgerufen werden können. Die Funktion liefert FALSE zurück, wenn das Projekt nicht existiert (also in 'HOTHELP:Projekte' keine entsprechende Header-Datei vorliegt) oder wenn das Projekt zwar existiert, aber über HotHelpPro deaktiviert wurde. HotHelp vergleicht den Namen des gesuchten Projektes ohne Beachtung von Groß- und Kleinschreibung. EINGABEN name: Name des gesuchten Projekts. ERGEBNIS TRUE - Es existiert ein aktives Projekt unter dem Namen 'name'. FALSE - Es existiert kein solches Projekt. BEMERKUNG Vor Aufruf der Funktion sollte über 'HH_OpenAll ()' sichergestellt werden, daß die Library ihre Ressourcen bereits geöffnet hat - andernfalls gibt die Funktion grundsätzlich FALSE zurück, da die Library noch keine Übersicht über die existierenden und aktiven Projekte aufgebaut hat. \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_CreatePath - Anlegen eines kompletten Pfades (V3) SCHREIBWEISE BOOL HH_CreatePath ( BYTE * path, struct DiskObject * dobj ) FUNKTION Während die DOS-Funktion 'CreateDir ()' immer nur das letzte Element eines Pfades neu erzeugt, legt diese Funktion alle noch fehlenden Verzeichnisse neu an. Existiert der komplette Pfad bereits, wird keine Aktion durchgeführt. Existiert der Pfad schon, beschreibt aber kein Verzeichnis, sondern eine Datei, wird FALSE zurückgegeben. EINGABEN path: Der Name des zu erzeugenden Pfades. dobj: Falls für jedes neu erzeugte Verzeichnis auch ein Icon angelegt werden soll, so muß hier eine entsprechend intialisierte DiskObject-Struktur übergeben werden, die ein Drawer-Icon beschreibt. Wird statt dessen NULL übergeben, werden keine Icons erzeugt. Falls beim Schreiben der Icon-Datei ein Fehler auftritt, wird dies NICHT zurück gemeldet - die Funktion scheitert nur, wenn ein Verzeichnis nicht angelegt werden konnte! ERGEBNIS TRUE - Alles klar. FALSE - Es ist ein Fehler aufgetreten - es existiert schon eine Datei unter diesem Namen, ein Teil des Pfades existiert schon als Datei oder ein Lock konnte nicht erlangt werden, weil das entsprechende Objekt schon verriegelt ist. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_EasyASyncHelp - ASynchrones Pendant zu 'HH_EasyHelp ()'. (V3) SCHREIBWEISE LONG HH_EasyASyncHelp ( BYTE * project, BYTE * key, struct Screen * screen, struct Window * window, BOOL last_pos, BOOL last_text ) FUNKTION Wie 'HH_EasyHelp ()' öffnet auch diese Funktion ein HotHelp-Fenster, wobei nur einige Einstellungen getroffen werden können. Während 'HH_EasyHelp ()' jedoch erst zum Aufrufer zurückkehrt, nachdem das Fenster wieder geschlossen wurde, kehrt diese Funktion unmittelbar nach dem Öffnen des Fensters zurück - das aufrufende Programm kann also parallel (asynchron) zu HotHelp weiter ablaufen. HotHelp steuert des neue Fenster vollkommen unabhängig vom aufrufenden Programm, so daß dieses auch beendet werden kann, solange das Fenster noch geöffnet ist. EINGABEN project, key: Zeiger auf maximal HH_PROJECT_LEN bzw. HH_KEY_LEN Bytes. Sie enthalten den Namen des gewünschten Projekts bzw. Schlüssels. Wird NULL übergeben, setzt HotHelp automatisch "*" dafür ein. Weiteres siehe bei den entsprechenden Feldern in der HH_NewWindow-Struktur. screen, window: Zeiger auf Screen und/oder Window, auf denen sich das HotHelp- Fenster öffnen soll. Wird für 'window' ein Wert ungleich NULL angegeben, wird das neue Fenster auf demselben Screen wie dieses Fenster geöffnet - 'screen' wird also ignoriert. Ist auch 'screen' NULL, öffnet sich das Fenster auf dem Workbench-Screen. last_pos: Wird hier TRUE übergeben, öffnet sich das Fenster an derselben Position wie das als letztes geschlossene Fenster, unabhängig davon, welches Programm dieses letzte Fenster geöffnet hatte! Ansonsten öffnet das Fenster sich an der mit HotHelpPref vorgegebenen Position. last_text: Wird hier TRUE übergeben, öffnet sich das Fenster mit demselben Inhalt wie das als letztes geschlossene Fenster, unabhängig davon, welches Programm dieses letzte Fenster geöffnet hatte! In diesem Fall werden 'project' und 'key' ignoriert. ERGEBNIS 0 - Das Fenster konnte nicht geöffnet werden. Es wurde bereits ein Requester mit einer entsprechenden Meldung ausgegeben. sonst - Die ID des neuen HotHelp-Handlers. Diese wird zur Kommunikation mit dem Handler benutzt, sofern das gewünscht ist. ACHTUNG: Im Gegensatz zu den übrigen Befehlen wird hier also kein Fehlercode zurückgegeben, sondern die ID, über die das Fenster mit Hilfe der 'HH_ASync...'-Funktionen von außen manipuliert werden kann. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_EasyHelp - Weniger komplexer Einstiegspunkt als 'HH_ShowHelp ()'. SCHREIBWEISE LONG HH_EasyHelp ( BYTE * project, BYTE * key, struct Screen * screen, struct Window * window, BOOL last_pos, BOOL last_text ) FUNKTION Die Funktion öffnet ein Fenster und stellt Hilfsinformationen zu einem gewünschten Thema dar. Dabei benötigt die Funktion weniger komplexe Eingabedaten als 'HH_ShowHelp ()', bietet dafür aber auch weniger Möglichkeiten, die Interna von HotHelp anzusprechen; es werden grundsätzlich immer die im HotHelpManager eingestellten Default-Werte benutzt. Wenn das kein Problem darstellt oder wenn die verwendete Programmier-Sprache keine zusammengesetzten Datentypen kennt, ist diese Funktion jedoch sicher der ideale Einstiegspunkt. EINGABEN project, key: Zeiger auf maximal HH_PROJECT_LEN bzw. HH_KEY_LEN Bytes. Sie enthalten den Namen des gewünschten Projekts bzw. Schlüssels. Wird NULL übergeben, setzt HotHelp automatisch "*" dafür ein. Weiteres siehe bei den entsprechenden Feldern in der HH_NewWindow-Struktur. screen, window: Zeiger auf Screen und/oder Window, auf denen sich das HotHelp- Fenster öffnen soll. Wird für 'window' ein Wert ungleich NULL angegeben, wird das neue Fenster auf demselben Screen wie dieses Fenster geöffnet - 'screen' wird also ignoriert. Ist auch 'screen' NULL, öffnet sich das Fenster auf dem Workbench-Screen. last_pos: Wird hier TRUE übergeben, öffnet sich das Fenster an derselben Position wie das als letztes geschlossene Fenster, unabhängig davon, welches Programm dieses letzte Fenster geöffnet hatte! Ansonsten öffnet das Fenster sich an der im HotHelpManager vorgegebenen Position. last_text: Wird hier TRUE übergeben, öffnet sich das Fenster mit demselben Inhalt wie das als letztes geschlossene Fenster, unabhängig davon, welches Programm dieses letzte Fenster geöffnet hatte! In diesem Fall werden 'project' und 'key' ignoriert. ERGEBNIS HH_ERROR_NONE - Das Fenster konnte problemlos geöffnet werden. Tritt später ein Fehler auf (z.B. Text kann nicht geladen werden), gibt HotHelp eine entsprechende Meldung in seinem Fenster aus - der Aufrufer erfährt davon jedoch nichts mehr (wozu auch?). sonst - Einer der HH_ERROR_-Codes. Die meisten der Fehler können nur auftreten, wenn das allererste HotHelp- Fenster seit dem letzten Booten geöffnet wird, da sie durch einen impliziten Aufruf der Funktion 'HH_OpenAll ()' hervorgerufen werden. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_FileRequest - Erfragen eines Verzeichnis- und Datei-Namens. (V3) SCHREIBWEISE BOOL HH_FileRequest ( struct Window * window, BYTE * title, BYTE * dir_buf, BYTE * file_buf, BYTE * pattern, UWORD flags ) FUNKTION Die Funktion stellt einen File-Requester zur Verfügung. Es wurde jedoch darauf verzichtet, speziell für HotHelp einen weiteren FileReq zu entwerfen; statt dessen versucht HotHelp, auf eine Reihe von anderen Shared Libraries zuzugreifen, die FileReqs anbieten. Als erstes wird versucht, die OS 2.0-Asl-Library zu öffnen und deren neuen Standard-Req zu verwenden. Schlägt dies fehl, weil das Programm unter OS 1.3 arbeitet, spricht HotHelp nacheinander die ReqTools-, die RCT- und die Arp-Library an. Sollte keine dieser vier Libraries gefunden werden (weil der User so dumm ist, mit einer absolut originalen 1.3-Workbench zu arbeiten...), greift HotHelp auf eine Notlösung zurück und fragt den User in einem Console-Window nach Verzeichnis- und Datei-Name... Die Auswertung der Parameter 'pattern', HHFR_SAVEMODE und HHFR_DRAWERSONLY hängt vom verwendeten FileReq ab; je nachdem, welche Library vorhanden ist, können sie auch gänzlich ignoriert werden... EINGABEN window: Zeiger auf ein Fenster, auf dessen Screen sich der Requester öffnen soll oder NULL, wenn der Default-Public-Screen verwendet werden soll. title: Zeiger auf einen String, der in der Titelzeile des Requesters angegeben werden soll. Wird NULL übergeben, wird als Standard-Überschrift 'Abfrage' (bzw. das entsprechende Wort der aktuellen Sprache) verwendet. dir_buf: Zeiger auf mindestens 260 BYTE. In diesem String kann der Anfangswert für das Verzeichnis-Gadget vorgeben werden. Bei positivem Abschluß befindet sich hierin der Name des vom User ausgewählten Verzeichnisses. Ansonsten enthält der Buffer keinen definierten Inhalt mehr. file_buf: Zeiger auf mindestens 40 BYTE, die den anfänglichen Inhalt des Datei-Gadgets vorgeben. Nach positiver Ausführung befindet sich hierin der Name der vom User ausgewählten Datei. Ansonsten ist der Inhalt des Strings nicht definiert. pattern: Zeiger auf einen String mit einem AmigaDOS-Pattern. Es werden nur die durch dieses Pattern beschriebenen Dateien angezeigt. Ein Übergabe-Wert von NULL signalisiert, daß kein Pattern gewünscht ist. flags: Es existieren momentan drei Flags, die hier gesetzt werden können: HHFR_SAVEMODE: Durch dieses Flag kann unterschieden werden, ob der Requester zum Laden oder zum Speichern verwendet werden soll. Dies hat z.B. Einfluß auf die Hintergrund- und Textfarbe. HHFR_DRAWERSONLY: Wird dieses Flag gesetzt, so ermöglicht der File-Requester lediglich die Auswahl eines Verzeichnisses, jedoch nicht den Namen einer Datei. Ist es gelöscht, wird wie üblich ein Verzeichnis- und Dateiname erfragt. HHFR_BLOCKWINDOW: Wenn dieses Flag gesetzt ist und wenn bei 'window' ein Fenster angegeben wurde, dann blockiert die Funktion dieses Fenster automatisch, bis der Requester wieder geschlossen wird. Der User kann dann in dem angegebenen Fenster weder Gadgets noch Menüs betätigen. ERGEBNIS TRUE - Der Pfadname der ausgewählten Datei geht aus 'dir_buf' und 'file_buf' hervor. FALSE - Der User hat die Auswahl abgebrochen oder es trat ein Systemfehler auf. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_FontVersion - Font-Typ der installierten Library testen. SCHREIBWEISE LONG HH_FontVersion ( VOID ) FUNKTION Mit Hilfe dieser Funktion läßt sich herausfinden, ob die installierte HotHelp-Library über einen eingebauten FastFont verfügt oder nicht. EINGABEN ERGEBNIS HH_FONT_NORMAL HH_FONT_FAST_8 BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_KeyList - Erzeugt eine Liste mit allen Schlüsseln eines Projekts (V3) SCHREIBWEISE LONG HH_KeyList ( BYTE * project, struct List * list ) FUNKTION Mit Hilfe dieser Funktion kann eine Liste aller Schlüssel eines bestimmten Projektes angefordert werden. Zu diesem Zweck wird für jeden Schlüssel eine HH_Key-Struktur angelegt und ausgefüllt. Die neuen Strukturen werden dann jeweils am Ende der Liste 'list' angehängt. Die Liste muß vorher bereits initialisiert worden sein und darf auch schon Elemente beinhalten. Die neuen Einträge werden alphabetisch aufsteigend am Listenende angefügt. HotHelp vergleicht den Namen des gesuchten Projektes ohne Beachtung von Groß- und Kleinschreibung. HotHelp legt den Speicher für die Strukturen dynamisch über 'AllocMem ()' an, kümmert sich dann aber nicht mehr weiter um diesen Speicherplatz. Das bedeutet, daß der Aufrufer die Listenelemente selber wieder freigeben muß, nachdem er sie komplett ausgewertet hat! Die Größe jeder Struktur geht aus dem Element 'struct_size' hervor; es darf auf keinen Fall einfach 'sizeof (struct HH_Key)' verwendet werden; dies könnte bei späteren Versionen der Library zu Speicherverlusten führen! ACHTUNG: Auch im Fall eines Fehlers können schon einige Strukturen in die Liste eingefügt worden sein, die dann - trotz des Fehlers - vom Aufrufer freigegeben werden müssen! EINGABEN project: Name des Projektes, dessen Schlüssel ermittelt werden sollen. Wenn kein Projekt unter diesem Namen existiert, gibt die Funktion keinen Fehlercode zurück, fügt aber auch keine Elemente in die Liste ein. Der Name wird immer ohne Beachtung von Groß-/Kleinschreibung verglichen. list: Zeiger auf eine bereits initialisierte List-Struktur. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG Vor Aufruf der Funktion sollte über 'HH_OpenAll ()' sichergestellt werden, daß die Library ihre Ressourcen bereits geöffnet hat - andernfalls verfügt die Library noch über keine Informationen über die Projekte, so daß das gesuchte Projekt auf keinen Fall gefunden wird und die Liste unverändert bleibt. \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_OpenAll - Öffnet alle benötigten Ressourcen SCHREIBWEISE LONG HH_OpenAll ( LONG quiet ) FUNKTION Normalerweise öffnet die HotHelp-Library alle benötigten Ressourcen (Projekte, Libraries, Speicher etc.) automatisch, sobald das erste Hilfs-Fenster geöffnet wird. Das führt beim Öffnen des ersten Fensters zu einer spürbaren Verzögerung. Um dem abzuhelfen, kann die Library mit Hilfe dieser Funktion zu einem beliebigen Zeitpunkt zum Öffnen ihrer benötigten Ressourcen veranlaßt werden. EINGABEN quiet: Der Parameter bezieht sich lediglich auf die Behandlung des normalerweise benötigten HOTHELP-Devices, aus dem die Vorein- stellungs-Datei und die Projekte gelesen werden. Ist die Variable gesetzt (also TRUE), durchsucht HotHelp zuerst die Device-Liste, ob ein solches Device überhaupt existiert. Nur wenn es gefunden wurde, versucht HotHelp, die Daten aus 'HOTHELP:' zu laden. Dieses Vorgehen verhindert, daß sich jedesmal einer dieser lästigen 'Please insert volume HOTHELP in any drive'-Requester öffnet, wenn die Library ohne ein HOTHELP-Device verwendet wird. Ist 'quiet' hingegen FALSE, wird direkt versucht, die Daten zu lesen - was evtl. einen Requester ergibt, wenn das Device nicht gefunden wurde. Normalerweise wird 'HH_OpenAll ()' implizit beim Öffnen des ersten HotHelp-Fensters aufgerufen. Um auch dabei Einfluß auf das Verhalten bzgl. 'HOTHELP:' nehmen zu können, existiert das HH_FLAG_QUIET-Flag, das dieselbe Wirkung hat wie dieser Parameter. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ProjectList - Erzeugt eine Liste mit allen aktiven Projekten (V3) SCHREIBWEISE LONG HH_ProjectList ( struct List * list ) FUNKTION Diese Funktion legt eine Liste mit Angaben über alle momentan aktiven Projekte an. Zu diesem Zweck wird für jedes Projekt eine HH_Project-Struktur angelegt und ausgefüllt. Die neuen Strukturen werden dann jeweils am Ende der Liste 'list' angehängt. Die Liste muß vorher bereits initialisiert worden sein und darf auch schon Elemente beinhalten. Die neuen Einträge werden alphabetisch aufsteigend am Listenende angefügt. HotHelp legt den Speicher für die Strukturen dynamisch über 'AllocMem ()' an, kümmert sich dann aber nicht mehr weiter um diesen Speicherplatz. Das bedeutet, daß der Aufrufer die Listenelemente selber wieder freigeben muß, nachdem er sie komplett ausgewertet hat! Die Größe jeder Struktur geht aus dem Element 'struct_size' hervor; es darf auf keinen Fall einfach 'sizeof (struct HH_Project)' verwendet werden; dies könnte bei späteren Versionen der Library zu Speicherverlusten führen! ACHTUNG: Auch im Fall eines Fehlers können schon einige Strukturen in die Liste eingefügt worden sein, die dann - trotz des Fehlers - vom Aufrufer freigegeben werden müssen! EINGABEN list: Zeiger auf eine bereits initialisierte List-Struktur. ERGEBNIS HH_ERROR_NONE - Alles klar. sonst - Einer der HH_ERROR_-Codes. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG Vor Aufruf der Funktion sollte über 'HH_OpenAll ()' sichergestellt werden, daß die Library ihre Ressourcen bereits geöffnet hat - andernfalls liefert die Funktion zwar keinen Fehler zurück, fügt aber auch keine Projekt-Namen in die Liste ein, da die Projekte noch nicht eingelesen wurden! \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_RemHandler - Entfernt einen Handler. (V3) SCHREIBWEISE VOID HH_RemHandler ( struct Interrupt * ir ) FUNKTION Diese Funktion muß verwendet werden, um einen vorher über 'HH_AddHandler ()' installierten Handler wieder zu entfernen. Dies muß spätestens am Ende des entsprechenden Programms durchgeführt werden. Falls der Handler gerade von einem anderen Prozeß verwendet wird, wartet die Funktion ab, bis der Handler wieder frei ist. EINGABEN ir: Zeiger auf die Interrupt-Struktur, die bei der Installation des Handlers an 'HH_AddHandler ()' übergeben worden ist. ERGEBNIS BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_Request - Öffnet einen Standard-Requester (V3) SCHREIBWEISE LONG HH_Request ( struct Window * window, WORD msg_id, BYTE * title, BYTE * str, BYTE * gadget_text, BOOL ask, BOOL build_only ) FUNKTION Mit Hilfe dieser Funktion kann auf einfache Weise ein Requester mit einem oder zwei Antwort-Gadgets erzeugt werden. Die Funktion verwendet dazu je nach der aktuellen Betriebssystem-Version entweder 'EasyRequestArgs ()' oder 'AutoRequest ()'. Sollte aus irgendeinem Grund die Intuition-Library nicht geöffnet werden können, wird die Meldung statt dessen in einem DOS-Console-Window angezeigt. Die Funktion wird von den HotHelp-Tools verwendet, um auch unter OS 1.3 einen Komfort ähnlich dem der 'EasyRequest ()'-Funktion zur Verfügung zu haben. EINGABEN window: Zeiger auf ein Window, auf dessen Screen sich der Requester öffnen soll bzw. NULL für den Default-Public-Screen. msg_id: Der hier angegebene Wert erläutert die Art der Nachricht näher. Wenn der User ARQ (den Requester-Improver von Martin Laubach) oder die RCT-Library installiert hat , wird die entsprechende kleine Animation oder eine mehr oder weniger passende Grafik im Requester-Fenster angezeigt. Andernfalls wird dieses Flag ignoriert. HH_MSG_DEFAULT - Es soll die dem Text entsprechende Standard-Animation abgespielt - ARQ z.B. untersucht dann wie üblich den übergebenen Text und wählt selber eine passende Animation aus. HH_MSG_INFO - Information HH_MSG_DISK - Diskette einlegen HH_MSG_DELETE - Löschen HH_MSG_GURU - Krititischer Fähler HH_MSG_RWERROR - Schreib-/Lese-Fehler HH_MSG_WPROTECT - Diskette ist schreibgeschützt HH_MSG_PRINTER - Drucker HH_MSG_QUESTION - Nachfrage HH_MSG_EXCLAM - Ausrufezeichen title: Dieser String wird als Titel des Requesters verwendet. Unter 1.3 taucht er als Überschrift innerhalb des Requesters auf, ab 2.0 erscheint er in der Titelzeile des Fensters. Wird NULL übergeben, wird als Standard-Überschrift 'Abfrage' (bzw. das entsprechende Wort der aktuellen Sprache) verwendet. str: Der String, der dargestellt werden soll. Soll er sich über mehrere Zeilen erstrecken, kann dies durch Einfügen von '\n' erzwungen werden. Unter OS 1.3 wird der String geparst und es werden automatisch entsprechend viele IntuiText-Strukturen angelegt. gadget_text: Wird hier NULL übergeben, werden für die Antwort-Gadgets Default-Texte verwendet ('Ja'/'Nein'/'OK' bzw. entsprechende Texte der aktuellen Sprache). Andernfalls stellt die Variable einen Zeiger auf einen String dar. Ist 'ask' gelöscht, wird der komplette String für das Bestätigungs-Gadget verwendet. Ist 'ask' hingegen gesetzt, erwartet HotHelp hier zwei Texte im Format "TextJa|TextNein" (also getrennt durch das '|'-Zeichen). Mehr als zwei Gadgets können nicht dargestellt werden, da diese Möglichkeit erst ab OS 2.0 existiert. Deshalb sollten auch nicht mehr als zwei einzelne Texte auf diese Weise übergeben werden - unter 2.0 würde zwar die Anzahl der Gadgets automatisch angepaßt, da hier die 'EasyRequest ()'-Funktion verwendet wird; unter 1.3 wären aber nur die beiden ersten Texte sichtbar... ask: Wird hier TRUE übergeben, befinden sich am unteren Rand des Requesters zwei Gadgets mit der Beschriftung 'JA' (links) und 'NEIN' (rechts). Wird das linke ausgewählt, gibt die Funktion TRUE zurück, ansonsten FALSE. Wenn für 'ask' FALSE übergeben wird, wird nur ein einzelnes Gadget mit der Beschriftung 'OK' erzeugt. Der Rückgabewert kann in diesem Fall ignoriert werden. Die Gadget-Beschriftungen sind an die aktuell eingestellte Sprache angepaßt. build_only: Dieser Parameter sollte normalerweise auf FALSE gesetzt werden, wenn der Requester normal behandelt werden soll. Wird TRUE übergeben, öffnet HotHelp lediglich den Requester und gibt einen Zeiger auf den neuen Requester zurück (oder NULL im Fehlerfall). Der Requester muß dann vom Aufrufer später explizit durch 'FreeSysRequest ()' geschlossen werden. ERGEBNIS (Ist abhängig von 'ask' und 'build_only'). BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ScanPalette - Untersucht eine Palette nach passenden Farbwerten SCHREIBWEISE BOOL HH_ScanPalette ( struct Screen * scr, struct Rectangle * rect ) FUNKTION Soll der Inhalt eines Fensters im neuen 3D-Look dargestellt werden, muß dazu bekannt sein, welche Farbe Weiß und welche Schwarz ist. Unter 1.3 ist auf der Workbench Farbe 1 Weiß und Farbe 2 Schwarz, unter 2.0 ist es genau umgekehrt. Ganz unangenehm wird es auf einem Custom-Screen mit unabhängiger Palette: dort können die Farben vollkommen beliebig verteilt sein. Insbesondere ist es ja auch möglich, daß das reine Schwarz und das reine Weiß gar nicht verwendet werden können, da die Hintergrund-Farbe bereits sehr hell oder sehr dunkel ist. Diese Funktion dient nun dazu, die Palette eines Screens zu untersuchen und die Farben herauszusuchen, die am ehesten zum Aufbau einer 3D-Oberfläche verwendet werden können. Wenn die Funktion erfolgreich verläuft, liefert sie in einer (zweckentfremdeten) Rectangle-Struktur vier Werte zurück, die jeweils eine Farbquelle angeben (der zweite Parameter für 'SetAPen ()' und 'SetBPen ()'): die Farbe für helle und für dunkle Rahmen, die Textfarbe sowie eine weitere Farbe, die zur Hervorhebung anderer Flächen verwendet werden kann. Bei einer normalen 1.3-Palette werden die folgenden Werte zurückgeliefert: Hell=1, Dunkel=2, Text=1 und Sonstiges=3. Die 2.0-Palette wird wie folgt ausgewertet: Hell=2, Dunkel=1, Text=1 und Sonstiges=3. Auch wenn die Farben nun durch ein Palette-Tool miteinander ausgetauscht würden, könnte die Funktion noch die korrekten Farbquellen identifizieren. Probleme treten lediglich auf Bildschirmen mit sehr kontrastarmen oder sehr vielen unterschiedlichen bunten Farben auf. Hier gibt die Funktion evtl. Werte an, die nicht optimal sind, oder kann gar keinen Vorschlag machen. Einigermaßen 'normale' Paletten (mittelhelle Hintergrundfarbe, Schwarz und Weiß und ein oder mehrere Kontrastfarben) werden jedoch ohne Probleme verarbeitet. Falls das Programm unter mindestens OS 2.0 läuft und der gewünschte Screen über eine NEWLOOK-DrawInfo verfügt, werden einfach die dort angegebenen Farbquellen verwendet. EINGABEN scr: Zeiger auf einen Screen, dessen Palette untersucht werden soll. Es muß ein Zeiger auf eine komplette Struktur übergeben werden, nicht nur eine Kopie, wie sie z.B. 'GetScreenData ()' liefert. rect: Zeiger auf eine Rectangle-Struktur. Nach erfolgreicher Ausführung enthalten ihre Elemente die Farbquellen für die vier verschiedenen Bereiche: MinX: Hell MaxX: Dunkel MinY: Text MaxY: Kontrastfarbe ERGEBNIS TRUE - Die Palette enthält passende Farben. FALSE - Die Farben sind zu kontrastarm, um vernünftige Werte ermitteln zu können. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_Semprini - Implementation des Semprini-Algorithmus. SCHREIBWEISE LONG HH_Semprini ( VOID ) FUNKTION Diese Funktion führt den 1969 von T.Jones, E.Idle, J.Cleese, M.Palin, G.Chapman und T.Gilliam an den bekannten BBC-Laboratories in London entwickelten Semprini-Algorithmus durch. Eine genauere Beschreibung dieses Algorithmus entnehmen Sie bitte dem Standardwerk von M.Python: 'How to make your Circus fly' EINGABEN Keine. ERGEBNIS TRUE oder ein Wert ungleich TRUE im Normalfall; sonst FALSE oder ein Wert ungleich FALSE. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_SetPointer - Setzen eines Standard-Mauszeigers. SCHREIBWEISE VOID HH_SetPointer ( struct Window * window, LONG type ) FUNKTION Die Funktion setzt für das übergebene Fenster einen der Standard-Mauszeiger. Hierbei handelt es sich entweder um das Abbild einer Stoppuhr, die anzeigt, daß das Programm momentan beschäftigt ist und nicht auf User-Eingabe reagiert, oder um einen Zeiger mit einem angehängten Fragezeichen, der symbolisiert, daß zu allen nun angeklickten Bildschirmbereichen ein Hilfstext dargestellt werden kann. Der neue Zeiger kann jederzeit über 'ClearPointer ()' wieder entfernt werden. EINGABEN window: Zeiger auf das Window, für das der Zeiger gesetzt werden soll. type: Typ des Zeigers. Momentan stehen zur Verfügung: HHP_SLEEP: Setzt den Stoppuhr-Zeiger. HHP_HELP: Setzt den Fragezeichen-Zeiger. ERGEBNIS BEMERKUNG Ab Betriebssystemversion 3.0 wird der System-Wartezeiger verwendet, der mit WA_PointerDelay angefordert wird. Vor Aufruf der Funktion muß über 'HH_OpenAll ()' sichergestellt werden, daß die Library ihre Ressourcen bereits geöffnet hat - ansonsten sieht der Mauszeiger nicht besonders gut aus... Bevor die HotHelp-Library geschlossen wird, muß sichergestellt werden, daß kein Fenster mehr einen über diese Funktion definierten Mauszeiger besitzt - schließlich ist es möglich, daß die Library unmittelbar nach dem Schließen aus dem Speicher entfernt wird, so daß auch die Grafik-Daten der Mauszeiger nicht mehr gültig sind! \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ShowHelp - Dreh- und Angelpunkt der HotHelp-Library SCHREIBWEISE LONG HH_ShowHelp ( struct HH_NewWindow * hh_nw ) FUNKTION Die Funktion öffnet ein Fenster und stellt Hilfsinformationen zu einem gewünschten Thema dar. EINGABEN hh_nw: Zeiger auf eine ausgefüllte HH_NewWindow-Struktur. Näheres siehe Beschreibung dieser Struktur. ERGEBNIS HH_ERROR_NONE - Das Fenster konnte problemlos geöffnet werden. Tritt später ein Fehler auf (z.B. Text kann nicht geladen werden), gibt HotHelp eine entsprechende Meldung in seinem Fenster aus - der Aufrufer erfährt davon jedoch nichts mehr (wozu auch?). sonst - Einer der HH_ERROR_-Codes. Die meisten der Fehler können nur auftreten, wenn das allererste HotHelp- Fenster seit dem letzten Booten geöffnet wird, da sie durch einen impliziten Aufruf der Funktion 'HH_OpenAll ()' hervorgerufen werden. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ShowHelpTagList - Neuer Dreh- und Angelpunkt der HotHelp-Library (V3) SCHREIBWEISE LONG HH_ShowHelpTagList ( struct HH_NewWindow * hh_nw, struct TagItem * tags ) FUNKTION Die Funktion öffnet ein Fenster und stellt Hilfsinformationen zu einem gewünschten Thema dar. Sie stellt eine Erweiterung der Funktion 'HH_ShowHelp ()' dar, da sie auch die Verwendung einer TagList zuläßt. Nur auf diese Weise können die neuen Features der Version 3 angesprochen werden. Obwohl bei Verwendung einer TagList die HH_NewWindow-Struktur überflüssig ist, wird ihre Verwendung weiterhin unterstützt, wodurch die Erweiterung bestehender Programme wesentlich erleichtert wird. TagItems werden vom Betriebssystem erst ab Version 2.0 unterstützt. Um davon unabhängig zu sein, untersucht HotHelp die TagList nicht über die Funktionen der Utility-Library, sondern selbstständig, so daß HotHelps TagItems auch unter V1.2 des OS verwendet werden können. Allerdings kann HotHelp momentan nur die vier Standard-Tags TAG_DONE, TAG_IGNORE, TAG_MORE und TAG_SKIP bearbeiten. Falls das OS in Zukunft noch weitere Tags anbieten sollte, so dürfen diese NICHT für HotHelp verwendet werden! Eine ausführliche Erklärung aller Tags finden Sie in der Datei 'Optionen'. Falls Sie noch nicht mit OS 2.0 arbeiten und noch keine Erfahrungen mit TagListen haben, finden Sie in den Demo-Programmen eine Reihe hilfreicher Beispiele. EINGABEN hh_nw: Zeiger auf eine ausgefüllte HH_NewWindow-Struktur. Näheres siehe Beschreibung dieser Struktur. Wird keine HH_NewWindow-Struktur verwendet, kann hier auch NULL übergeben werden. tags: Startadresse eines Feldes von TagItem-Strukturen. Das letzte Element muß den Wert TAG_DONE (0) aufweisen. Werden in der TagList Optionen verwendet, die auch in der HH_NewWindow-Struktur auftauchen, so werden die Einstellungen der TagList verwendet - diese hat also Vorrang vor der Struktur. ERGEBNIS HH_ERROR_NONE - Das Fenster konnte problemlos geöffnet werden. Tritt später ein Fehler auf (z.B. Text kann nicht geladen werden), gibt HotHelp eine entsprechende Meldung in seinem Fenster aus - der Aufrufer erfährt davon jedoch nichts mehr (wozu auch?). sonst - Einer der HH_ERROR_-Codes. Die meisten der Fehler können nur auftreten, wenn das allererste HotHelp- Fenster seit dem letzten Booten geöffnet wird, da sie durch einen impliziten Aufruf der Funktion 'HH_OpenAll ()' hervorgerufen werden. Es wurde bereits ein Requester mit der Fehlermeldung in Klartext ausgegeben. Ausgenommen davon sind nur Fehlercodes mit Werten kleiner 10. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_StrCmp - Stringvergleich; ignoriert Groß-/Kleinschreibung (V3) SCHREIBWEISE BOOL HH_StrCmp ( BYTE * str1, BYTE * str2 ) FUNKTION Ähnlich der 'strcmp ()'-Funktion vergleicht die Funktion zwei Strings, wobei jedoch die Groß- und Kleinschreibung ignoriert wird. Deutsche Umlaute werden korrekt behandelt (äöü). EINGABEN str1, str2: Die beiden zu vergleichenden Strings. ERGEBNIS -1: str1 < str2 0: str1 == str2 1: str1 > str2 BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_StrNCmp - Stringvergleich; ignoriert Groß-/Kleinschreibung (V3) SCHREIBWEISE BOOL HH_StrNCmp ( BYTE * str1, BYTE * str2 ) FUNKTION Wie 'HH_StrCmp ()' vergleicht auch diese Funktion zwei Strings ohne Berücksichtigung von Groß- und Kleinschreibung. Es werden jedoch maximal 'strlen (str2)' Zeichen untersucht; tritt bis dahin kein Unterschied auf, gelten die beiden Strings als identisch. EINGABEN str1: Der erste zu vergleichende String. str2: Der zweite zu vergleichende String. Seine Länge gibt an, wieviele Zeichen maximal untersucht werden sollen. ERGEBNIS -1: str1 < str2 0: str1 == str2 1: str1 > str2 BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_ToUpper - Konvertiert einen Klein- in einen Großbuchstaben (V3) SCHREIBWEISE UBYTE HH_ToUpper ( UBYTE c ) FUNKTION Falls es sich bei dem angegebenen ASCII-Zeichen um einen Kleinbuchstaben handelt, gibt die Funktion den entsprechenden Großbuchstaben zurück. Handelt es sich um eine Ziffer oder ein anderes Zeichen, wird dieses unverändert wieder zurückgegeben. EINGABEN c: Das umzusetzende Zeichen. ERGEBNIS Der zu dem Zeichen 'c' gehörende Großbuchstabe bzw. 'c' selber, wenn es sich nicht um einen Kleinbuchstaben handelt. BEMERKUNG \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_Translate - Übersetzt einen ASCII-Text in das HotHelp-Format, das für Handler und 'HH_ASyncCustomText ()' benötigt wird. (V3) SCHREIBWEISE LONG HH_TransLate ( struct HH_TranslateData * data, struct HH_CustomText * ctext ) FUNKTION Soll über einen Handler oder die Funktion 'HH_ASyncCustomText ()' ein HotHelp-Fenster mit einem frei definierten Text versehen werden, der nicht aus einer normalen Projekt-Datei stammt, so muß dieser Text in einem bestimmten Format vorliegen. Um dieses Format zu erhalten, gibt es zwei Möglichkeiten: Zum einen kann das Programm, das den Text darstellen möchte, diesen Stück für Stück selber zusammensetzen und mit allen erforderlichen Steuermarken versehen (siehe Datei 'TextAufbau'). Wesentlich leichter ist es jedoch, einen schon vorhandenen ASCII-Text mit Hilfe dieser Funktion automatisch übersetzen zu lassen. Wurde der Inhalt der HH_TranslateData-Struktur komplett ausgewertet (Schlüssel analysiert, übersetzter Text an HotHelp zur Darstellung übergeben etc.), muß 'HH_TranslateFree ()' verwendet werden, um alle bei der Übersetzung vorgenommenen Speicher-Reservierungen wieder freizugeben. Dies muß spätestens bei Programmende oder vor der nächsten Verwendung der Struktur geschehen! EINGABEN data: Zeiger auf eine initialisierte HH_TranslateData-Struktur. Näheres siehe bei der Struktur-Beschreibung. ctext: Soll der übersetzte Text anschließend in einem HotHelp-Fenster dargestellt werden, so muß dazu zuerst eine HH_CustomText-Struktur ausgefüllt werden. Am einfachsten ist es dazu, hier einfach die Adresse einer solchen Struktur anzugeben, die dann nach der Übersetzung automatisch ausgefüllt wird. Wird dies nicht gewünscht, kann hier auch NULL übergeben werden. Die Struktur darf natürlich nur verwendet werden, wenn die Funktion erfolgreich ablief. Ihr Inhalt wird ungültig, sobald 'data' an 'HH_TranslateFree ()' übergeben wurde. HotHelp kopiert lediglich die Struktur-Elemente 'hh_text', 'hh_text_len', 'hh_real_len' und 'tab_size' aus 'data' nach 'ctext'. Alle anderen Elemente (insbesondere 'version') müssen noch von Hand initialisiert werden - sie werden durch diesen Aufruf nicht geändert. ERGEBNIS TRUE - Die Übersetzung verlief fehlerfrei. FALSE - Es trat ein Fehler auf. Seine Ursache kann der 'error'-Variablen der Struktur entnommen werden. BEMERKUNG Vor Aufruf der Funktion muß über 'HH_OpenAll ()' sichergestellt werden, daß die internen Ressourcen der Library geöffnet worden sind - andernfalls kann die Übersetzung fehlschlagen! Wird die Funktion von einem Handler (siehe die gleichnamige Datei) aus aufgerufen, kann darauf jedoch verzichtet werden; bevor ein Handler aufgerufen wird, öffnet die Library automatisch ihre Ressourcen. \*----------------------------------------------------------------------*/ /*----------------------------------------------------------------------*\ NAME HH_TranslateFree - Gibt den bei 'HH_Translate ()' angelegten Speicher wieder frei. (V3) SCHREIBWEISE VOID HH_TransLateFree ( struct HH_TranslateData * data ) FUNKTION 'HH_TransLate ()' legt einige Speicherbereiche an ('hh_text', 'keys', etc.), in denen die umgesetzten Daten abgelegt werden. Ist deren Auswertung abgeschlossen, sollten diese Speicherbereiche mit Hilfe der Funktion 'HH_TranslateFree ()' wieder freigegeben werden. Die Funktion setzt alle Zeiger auf dynamisch allozierte Bereiche wieder auf NULL zurück, so daß diese anschließend nicht mehr verwendet werden sollten. Die Funktion muß nur aufgerufen werden, wenn 'HH_Translate ()' fehlerfrei verlief - es schadet aber auch nichts, wenn sie dennoch verwendet wird... EINGABEN data: Zeiger auf eine von 'HH_Translate ()' ausgefüllte HH_TranslateData-Struktur. ERGEBNIS BEMERKUNG \*----------------------------------------------------------------------*/