home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / C / OTL-MC4.DMS / in.adf / Archive / Prog.lha / Docs / HotKeyHelp < prev    next >
Encoding:
Text File  |  1994-02-14  |  8.8 KB  |  188 lines
  1.  
  2. HotKeyHelp
  3. ==========
  4.  
  5.    Das   Programm   HotKeyHelp   ist   zuständig   für  den  Aufruf  eines
  6. HotHelp-Fensters  über  einen HotKey.  Das Programm installiert dazu einen
  7. Input-Handler,  der  alle  Tastatureingaben  abfängt  und überprüft.  Ggf.
  8. wird  dann das Hauptprogramm benachrichtigt, das dann ein (ab Version 3.00
  9. asynchrones) HotHelp-Fenster öffnet.
  10.  
  11.    Ab   Version   3.00   bietet   HotKeyHelp   darüber   hinaus  noch  ein
  12. ARexx-Interface  an,  über das beliebige Programme auf der ARexx-Ebene auf
  13. HotHelp-Funktionen  zugreifen  können.   Außerdem stellt HotKeyHelp selber
  14. auch noch einige ARexx-Funktionen zur Verfügung.
  15.  
  16.    Weiterhin   bietet   HotKeyHelp   ab   Version   3.00   auch  die  sog.
  17. Online-Projekte  an - diese müssen nicht extra durch HotHelpComp übersetzt
  18. werden;  statt  dessen  holt  sich  HotKeyHelp  auf  einen  HotKey hin den
  19. aktuellen  Textblock  eines Editors, übersetzt diesen und speichert ihn in
  20. einem Unterverzeichnis in 'HOTHELP:OnlineProjekte' ab.  Für jedes einzelne
  21. Online-Projekt  existiert  dort  ein  eigenes Verzeichnis.  Eine Übersicht
  22. über  alle  Schlüssel  wird  in der Datei 'HOTHELP:OPRIndex' festgehalten,
  23. damit    nicht   bei   jedem   Neustart   alle   Unterverzeichnisse   nach
  24. Schlüssel-Dateien   durchsucht   werden   müssen.   Wird  nun  später  ein
  25. entsprechender  Schlüssel-Begriff  in  einem  HotHelp-Fenster angefordert,
  26. liefert  HotKeyHelp  über  einen HotHelpHandler den vorher abgespeicherten
  27. Text, so daß dieser dargestellt werden kann - that's the whole stuff!
  28.  
  29.    Die  Library  selber stellt nur das recht allgemeingültige Werkzeug der
  30. HotHelp-Handler  zur  Verfügung;  alle anderen Aktionen zur Verwaltung der
  31. Online-Projekte   werden   von  HotKeyHelp  durchgeführt!   Es  ist  daher
  32. natürlich   auch   nicht  möglich,  über  Library-Funktionen  Einfluß  auf
  33. Online-Projekte zu nehmen - die Library selber weiß schließlich gar nichts
  34. von  diesen  Projekten!  Um diesem Problem abzuhelfen, bietet das Programm
  35. HotKeyHelp jedoch einige Möglichkeiten.
  36.  
  37.  
  38. Schnittstellen
  39. ==============
  40.  
  41.    HotKeyHelp besitzt ab Version 3.00 vier verschiedene Schnittstellen, um
  42. mit  der  Außenwelt  in  Kommunikation zu treten.  Schnittstelle 1 ist die
  43. wohl gebräuchlichste:  das User-Interface.  Der Anwender kann über HotKeys
  44. das Programm ansprechen, es mit einigen Parametern starten und auch wieder
  45. beenden.
  46.  
  47.    Als   zweite  Schnittstelle  kann  ab  OS  2.0  das  Commodities-System
  48. verwendet  werden.   HotKeyHelp  meldet  sich  als  Commodity  an und kann
  49. folglich  auch  über  das  System-Programm 'Exchange' kontrolliert werden.
  50. (zugegebenermaßen verhält sich HotKeyHelp zwar wie ein Commodity, arbeitet
  51. aber  intern  über  einen  simplen InputHandler, um auch unter OS 1.3 noch
  52. laufähig   zu   sein.    Vorteile   einer   zweigleisigen   Programmierung
  53. [Input-Handler   unter   1.3,  Commodity-Objekte  unter  2.0]  sind  nicht
  54. ersichtlich).
  55.  
  56.    Als dritte Schnittstelle dient der ARexx-Port des Programms, der in der
  57. entsprechenden Datei ausführlich beschrieben wird.
  58.  
  59.    Die  vierte  (und  am besten versteckte) Schnittstelle ist ein globaler
  60. Port   mit   dem   Namen  "HotKeyHelp's Port".   Über  diesen  Port  läuft
  61. normalerweise  nur  die  Kommunikation zwischen HotKeyHelp und den übrigen
  62. HotHelp-Tools ab; es ist jedoch auch durchaus möglich, den Port für eigene
  63. Zwecke  zu  verwenden.   Aber Vorsicht:  wer hierüber kommuniziert, sollte
  64. wissen,  was  er  tut - HotKeyHelp nimmt keinerlei Fehler-Überprüfung vor,
  65. sondern geht davon aus, daß die ankommenden Nachrichten korrekt formuliert
  66. sind.   Es wird zwar garantiert, daß die beschriebenen Nachrichten auch in
  67. späteren Versionen dieselben Bedeutungen haben - andere Nachrichten dürfen
  68. aber   auf   keinen   Fall  verwendet  werden!   Es  müssen  die  üblichen
  69. Vorsichtsmaßnahmen beachtet werden, wenn Nachrichten an einen fremden Port
  70. geschickt werden.
  71.  
  72.    An den Port müssen IntuiMessages verschickt werden, die der Einfachkeit
  73. halber  mit  (mehr  oder minder zweckentfremdeten) IDCMP_-Kennungen in der
  74. 'Class'-Variablen  versehen  werden.   Nachdem  eine  Message  verarbeitet
  75. wurde,  wird sie von HotKeyHelp über 'ReplyMsg ()' wieder zurückgeschickt.
  76. Im  Folgenden nun eine Übersicht über alle unterstützten Kennungen und die
  77. zugehörigen Aktionen.
  78.  
  79.  
  80. IDCMP_CLOSEWINDOW
  81. -----------------
  82.  
  83.    HotKeyHelp wird beendet.  Falls die 'IAddress'-Variable der verwendeten
  84. IntuiMessage-Struktur  anschließend einen Wert != NULL beinhaltet, muß der
  85. Wert  an 'UnLoadSeg ()' übergeben werden - es handelt sich um die SegListe
  86. des HotHelpHandlers, die auf diesem Weg zurückgegeben wird.
  87.  
  88.  
  89. IDCMP_NEWPREFS
  90. --------------
  91.  
  92.    Die HotHelp-Preferences haben sich geändert, so daß HotKeyHelp sich von
  93. der Library eine neue Kopie von deren internen Einstellungen besorgen muß.
  94.  
  95.  
  96. IDCMP_GADGETDOWN
  97. ----------------
  98.  
  99.    Auf  diese  Nachricht  hin  legt  HotKeyHelp  eine  Übersicht über alle
  100. Online-Projekte  an.  Das Programm geht dabei genauso vor wie die Funktion
  101. 'HH_ProjectList   ()':   Es  wird  eine  Liste  aus  HH_Project-Strukturen
  102. gebildet.   'IAddress'  der  verwendeten IntuiMessage muß dazu die Adresse
  103. einer  bereits korrekt initialisierten List-Struktur beinhalten; die Nodes
  104. mit  den  Namen  werden  am  Listenende  angehängt und müssen vom Aufrufer
  105. selber  wieder  freigegeben  werden.  Genauere Hinweise finden Sie bei der
  106. Beschreibung der 'HH_ProjectList ()'-Funktion.  Die Elemente 'version' und
  107. 'text_file'  der  Strukturen  werden  nicht  verwendet.   Im Gegensatz zur
  108. Funktion sind diese Projekte nicht unbedingt alphabetisch sortiert.
  109.  
  110.    Wenn  das  Element  'Code'  der IntuiMessage-Struktur nach Rückgabe der
  111. Nachricht  einen  Wert  ungleich  0  enthält,  ist  ein Fehler aufgetreten
  112. (Speicherplatzmangel).   HotKeyHelp  hat dies bereits über einen Requester
  113. dem  Benutzer  mitgeteilt  (zumindest  hat es das versucht; ob der Req bei
  114. Speicherplatzmangel  auch  aufgeht,  ist  dann  wieder  eine  ganz  andere
  115. Frage...).
  116.  
  117.  
  118. IDCMP_GADGETUP
  119. --------------
  120.  
  121.    Auf  diese  Nachricht  hin  legt  HotKeyHelp  eine  Übersicht über alle
  122. Schlüssel  eines  bestimmten Online-Projektes an.  Das Programm geht dabei
  123. so  vor  wie  die  Funktion  'HH_KeyList  ()':   Es  wird  eine  Liste aus
  124. HH_Key-Strukturen  gebildet.   'IAddress' der verwendeten IntuiMessage muß
  125. dazu  die  Adresse  einer  bereits  korrekt  initialisierten List-Struktur
  126. beinhalten;  die  Nodes  mit  den  Namen  werden  alphabetisch sortiert am
  127. Listenende  angehängt  und  müssen  vom Aufrufer selber wieder freigegeben
  128. werden.   'IDCMPWindow'  muß  auf  einen  String zeigen, der den Namen des
  129. gewünschten  Online-Projektes  beinhaltet.   Je  nach den Einstellungen in
  130. HotHelpPref  wird  die  Groß-/Kleinschreibung  des  Namens  beachtet  oder
  131. ignoriert.    Genauere  Hinweise  finden  Sie  bei  der  Beschreibung  der
  132. 'HH_KeyList ()'-Funktion.
  133.  
  134.    Wenn  das  Element  'Code'  der IntuiMessage-Struktur nach Rückgabe der
  135. Nachricht  einen  Wert != 0 enthält, ist ein Fehler aufgetreten.  Ein Wert
  136. von   1  kennzeichnet  Speicherplatzmangel  (wird  von  HotKeyHelp  selber
  137. angezeigt), ein Wert von 2 das Nicht-Auffinden des gewünschten Projektes.
  138.  
  139.  
  140. IDCMP_DISKINSERTED
  141. ------------------
  142.  
  143.    Diese  Nachricht  bringt HotKeyHelp dazu, ein komplettes Online-Projekt
  144. zu  löschen.   Dazu  muß in 'IAddress' ein Zeiger auf einen String mit dem
  145. Projekt-Namen  übergeben werden.  HotKeyHelp führt daraufhin die folgenden
  146. Aktionen   durch:    Löschen  aller  Schlüssel-Dateien  im  entsprechenden
  147. Verzeichnis,  Löschen  des Verzeichnis selber, Entfernen des Projektes aus
  148. der internen Liste und Abspeichern dieser gekürzten Liste.
  149.  
  150.  
  151. IDCMP_DISKREMOVED
  152. -----------------
  153.  
  154.    Diese   Nachricht  bewirkt  das  Löschen  eines  einzelnen  Schlüssels.
  155. 'IAddress' muß auf einen String mit dem Namen des Projektes zeigen, in dem
  156. der  Schlüssel liegt, während 'IDCMPWindow' auf einen String mit dem Namen
  157. des  Schlüssels  selber  zeigt.   HotKeyHelp  löscht  die Schlüssel-Datei,
  158. entfernt den Schlüssel aus der Liste und speichert diese wieder ab.
  159.  
  160.    ACHTUNG:   Der  Schlüssel 'Startseite' darf niemals entfernt werden, da
  161. ihm eine besondere Bedeutung zukommt!
  162.  
  163.  
  164. IDCMP_REQSET
  165. ------------
  166.  
  167.    Dieses  Kommando  gibt einem Projekt einen neuen Namen.  'IAddress' muß
  168. auf   einen   String   mit  dem  aktuellen  Namen  des  Projektes  zeigen,
  169. 'IDCMPWidnow'  auf  einen  String  mit dem neuen Namen.  Dieser darf nicht
  170. länger  als  30  Zeichen  sein  (inkl.   '\0') und darf weder ':' noch '/'
  171. enthalten.
  172.  
  173.  
  174. IDCMP_REQCLEAR
  175. --------------
  176.  
  177.    Mit Hilfe dieses Kommandos kann ein Schlüssel innerhalb eines Projektes
  178. einen  neuen Namen erhalten.  Es ist nicht möglich, einen Schlüssel in ein
  179. anderes    Projekt   zu   verlegen!    'IAddress'   muß   den   bisherigen
  180. Schlüssel-Begriff beinhalten, 'IDCMPWindow' den neuen Namen.  Der Name des
  181. Projektes, in dem der Schlüssel sich befindet, geht aus dem String hervor,
  182. auf den 'SpecialLink' zeigen muß.
  183.  
  184.    ACHTUNG:   Der Schlüssel 'Startseite' darf niemals umbenannt werden, da
  185. ihm eine besondere Bedeutung zukommt!
  186.  
  187.  
  188.