home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / amok_lha / amok02.lha / IntuiStruct / Doc.textcraft (.txt) < prev    next >
Encoding:
IFF Formatted Text  |  1993-08-16  |  13.5 KB  |  159 lines
  1. Vorwort
  2. Dieses Modul entstand an dem Tag, an dem ich bemerkte, daß mein Listing bereits ca. 500 Zeilen lang war, und ich erst ein Window mit einem Menu und einigen Gadgets programmiert hatte...
  3. Es beinhaltet schon oft Dagewesenes (Hilfen zum Ã–ffnen von Screens und Windows) aber auch Interessantes und Neues (Elegante Unterstützung von Images, Gadgets und Menus).
  4. "IntuiStruct" ist Public Domain Software, dh. jeder darf es umsonst benutzen und sooft und für wen er will kopieren. Dabei sollte allerdings folgendes beachtet werden:
  5. -Diese Software darf nicht kommerziell genutzt werden, dh. mit ihrer Verbreitung oder Nutzung darf kein Gewinn erwirtschftet werden. Falls sie Ã¼ber Versand oder sonstwie vertrieben wird, dürfen die Gebühren lediglich kostendeckend sein. Ansonsten ist eine Absprache mit dem Autor und ein schriftliche Bestätigung erforderlich.
  6. -Lassen Sie bitte den Quellcode und die Dokumentation unverändert. Selbstverständlich dürfen Sie den Quellcode an Ihre Bedürfnisse anpassen, geben sie jedoch möglichst nur den Orginalcode zusammen mit der Orginaldokumentation an andere weiter. Nur so läßt sich der sog. Bit-Decay-Effekt (Software-Mutation) vermeiden.
  7. -Sollten Sie aber eine Verbesserung oder Erweiterung am Modul vornehmen, die sich wirklich lohnt weiterzugeben, tragen Sie bitte im Modulkopf unter "Update" Ihren Namen, das Datum und die Art der Ã„nderung ein (modification history). Fügen Sie im Modulkopf und in der Dokumentation immer nur hinzu, löschen Sie bitte nichts.
  8.  
  9. Screens, Windows, Text, Gadgets
  10. Die folgenden Prozeduren sind (fast) selbsterklärend und sind deshalb nur mit kurzen Bemerungen versehen.
  11.  
  12. StructScreen(NewScreen, depth, detailPen, blockPen, viewModes, type, defaultTitle);
  13. öffnet den Screen noch nicht sondern Ã¼bergibt nur die NewScreen- Struktur, sodaß vor OpenScreen() noch Werte verändert werden können. Nicht verlangte Parameter werden folgendermaßen initialisiert:
  14. leftEdge:=0;topEdge:=0;height:=stdScreenHeight;
  15. font:=NIL;gadgets:=NIL;customBitmap:=NIL;
  16. IF hires IN ViewModes THEN width:=640 ELSE width:=320 END
  17.  
  18. StructWindow(NewWindow, leftEdge, topEdgr, width, height, detailPen, blockPen, idcmpFlags, flags, title, screen, type);
  19. öffnet das Window noch nicht sondern Ã¼bergibt nur die NewWindow- Struktur, sodaß vor OpenWindow() noch Werte verändert werden können. Nicht verlangte Parameter werden folgendermaßen initialisiert:
  20. firstGadget:=NIL;checkMark:=NIL;bitMap:=NIL;minWidth:=0;
  21. minHeight:=0;maxWidth:=0;maxHeight:=0
  22.  
  23. StructText(IntuiText, frontPen, backPen, drawMode, leftEdge, topEdge, iText, nextText);
  24. initialisiert eine IntuiText-Struktur, nicht angegebene Werte:
  25. iTextFont:=NIL
  26.  
  27. StructGadget(Gadget, leftEdge, topEdge, width, height, flags, activation, gadgetType, gadgetRender, gadgetText, mutualExclude, gadgetID, nextGadget);
  28. initialisiert eine Gadget-Struktur, nicht angegeben Werte:
  29. selectRender:=NIL;specialInfo:=NIL;userData:=NIL;
  30. "mutualExclude" siehe Abschnitt weiter unten.
  31. StructProp(PropInfo, flags, horizPot, vertPot, horizBody, vertBody);
  32. initialisiert eine PropInfo-Struktur, die mit 
  33. Gadget.specialInfo:=ADR(PropInfo)
  34. an das Gadget geknüpft werden kann. Sonstige Parameter:
  35. keine (werden nur von Intuition selbst verwendet)
  36.  
  37. StructString(StringInfo, Buffer(*ARRAY OF CHAR!*), UndoBuffer(*ARRAY OF CHAR!*));
  38. initialisiert die StringInfo-Struktur folgendermaßen:
  39. buffer:=ADR(Buffer);undoBuffer:=ADR(UndoBuffer);bufferPos:=0;
  40. maxChars:=HIGH(Buffer);dispPos:=0;
  41. alle anderen Felder werden nicht initialisiert.
  42. Verknüpfung mit der Gadget-Struktur siehe StructProp.
  43. Mit "StructString" kann auch ein Integergadget erzeugt werden, wenn zusätzlich das longint-Flag der Gadget-Struktur gesetzt und das longInt-Feld der StringInfo initialisiert wird.
  44.  
  45. Mutual exclusion - gegenseitiger Ausschluß von Gadgets
  46. Damit ist gemeint, daß beim Anklicken eines bestimmten Gadgets automatisch andere abgeschaltet werden (was man bei Attribut-Items von Menus schon gewohnt ist). Im Intuition Reference Manual steht, diese Funktion sei noch nicht implementiert aber bereits vorgesehen. Sie werde in einer zukünftigen Version von Intuition verfügbar sein. Wer es aufgegeben hat, darauf zu warten, wird sich Ã¼ber die Prozedur
  47.  
  48. ExcludeGadget(Gadgets, Window, Requester, Mask)
  49.  
  50. freuen. Man ruft sie mit folgenden Parametern auf, nachdem man erkannt hat, daß ein Gadget, das andere ausschließen soll, aktiviert wurde.
  51.  
  52. Gadgets: Zeiger auf das erste User(!)-Gadget des Windows oder Requesters. Vorsicht: nicht den Zeiger Window.firstGadget verwenden! Er zeigt auf das erste System-Gadget des Windows.
  53. Window: Zeiger auf das Window, in dem sich das Gadget befindet
  54. Requester: Zeiger auf den Requester, falls es sich um das Gadget eines Requesters handelt, ansonsten NIL
  55. Mask: Maske der auszuschließenden Gadgets (gesetztes Bit=ausschließen, gelöschtes=unverändert lassen). Bit 0 steht für das erste Gadget in der verketteten Liste der User-Gadgets, Bit 1 für das zweite usw.
  56. Natürlich ist "mutual exclusion" nur bei toggleSelect-Gadgets sinnvoll, wenig Sinn haben auch Gadgets, die sich selbst ausschließen.
  57. Am besten wird die Maske im dafür vorgesehenen Feld der Gadget-Struktur abgelegt. Der Aufruf lautet dann etwa:
  58.  
  59. ExcludeGadget(GadgetStripPtr, MeinWindow, NIL,
  60. aktivesGadget.mutualExclude);
  61.  
  62. Entgegen der sonst Ã¼blichen Methode wird nicht RefreshGadgets( GadgetStripPtr,...) aufgerufen, was alle Gadgets neu zeichnet. Nur die betroffenen Gadgets werden neu gezeichnet. Dies verhindert das sonst, besonders bei sehr vielen Gadgets pro Window, zu beobachtende "Zucken" beim Anklicken eines Gadgets.
  63.  
  64.  
  65. Images elegant erzeugt
  66. Jetzt ist Schluß mit dem Ã„rger mit Hexadezimalen Zahlen, mit umständlicher Erzeugung der Image-Struktur und mit der Ungewißheit, ob die Bitplanes jetzt wirklich im ChipMem liegen. Hier ein Beispiel mit StructImage:
  67.  
  68. StructImage(Smily,X,Y,24,18,1(*depth*),[0,1](*PlanePick*),
  69. [](*PlaneOnOff*),NIL(*nextImage*));
  70. Long(000000001111111100000000L);
  71. Long(000001110000000011100000L);
  72. Long(000110000000000000011000L);
  73. Long(001000000000000000000100L);
  74. Long(010000110000000011000010L);
  75. Long(010000110000000011000010L);
  76. Long(100000000000000000000001L);
  77. Long(100000000000000000000001L);
  78. Long(100000000000000000000001L);
  79. Long(100001100000000001100001L);
  80. Long(010000011100001110000010L);
  81. Long(010000000011110000000010L);
  82. Long(001000000000000000000100L);
  83. Long(000110000000000000011000L);
  84. Long(000001110000000011100000L);
  85. Long(000000001111111100000000L);
  86. ImageEnd;
  87.  
  88. ChipMem für die Bitplane(s) wird automatisch alloziert und bei Programmbeendigung freigegeben, ohne daß man sich darum kümmern muß. Nach ImageEnd ist das Image zur Verwendung bereit.
  89. Man muß lediglich darauf achten, daß die Anzahl der Long() bzw Word() Aufrufe mit der Anzahl der für die Image-Bitplane(s) benötigten (Lang-)Wort Ã¼bereinstimmt. Sonst wird mit einer Fehlermeldung abgebrochen.
  90.  
  91. Menus
  92. Wer einmal ein umfangreiches Menu programmiert hat, der weiß, daß dies in eine ziemlich große Schreibarbeit ausartet. Erst muß für jeden Menupunkt (Item) und eventuell für die untergeordneten Punkte (SubItems) eine IntuiText-Struktur erzeugt werden. Dann wird für jedes Item und SubItem eine MenuItem-Struktur Initialisiert, die einen Zeiger auf die zugehörige IntuiText-Struktur enthält. Schließlich müssen die SubItems untereinander und mit ihrem Item, die Items untereinander und mit ihrem Menu(-kopf) verbunden werden, und endlich die Menus zum gesammten MenuStrip zusammengefügt werden.
  93. Mit dem vorliegenden Modul wird diese Prozedur enorm vereinfacht.
  94.  
  95. SubItem(ADR(Name), leftEdge, width, flags, mutualExclude, command);
  96. initialisiert eine MenuItem-Struktur (als SubItem) und die zugehörige IntuiText-Struktur. Parameter:
  97. leftEdge: Position des linken Rands der Selectbox des Subitems relativ zum linken Rand des Items, unter dem diese(s) SubItem steht/stehen
  98. width: Breite der Selectbox
  99. flags: MenuItemFlags (itemText muß gesetzt sein)
  100. mutualExclude: Ausschluß anderer Attributitems (Bit 0 für das oberste, also das zuletzt erzeugte SubItem)
  101. command: eventueller "Menuersatz-Key" (+rechte Amigataste), nur erforderlich, wenn das commSeq-Flag gesetzt ist
  102.  
  103. Alle anderen Felder werden später automatisch initialisiert (siehe LinkMenu). Die IntuiText-Struktur wird beim Aufruf von SubItem so initialisiert:
  104. frontPen:=0;backPen:=1;drawMode:=jam1;leftEdge:=0;topEdge:=0;
  105. iTextFont:=NIL;iText:=ADR(Name);nextText:=NIL;
  106. Wurde vorher (bzw. seit dem letzten Item-Aufruf) schon einmal SubItem aufgerufen, so wird das zuletzt definierte SubItem als nextItem in das gerade definierte SubItem eingetragen. Das bedeutet, wenn mehrmals hintereinander SubItem aufgerufen wird, sind die SubItems bereits von selbst miteinander verbunden. Das zuletzt definierte steht dabei als oberstes SubItem.
  107.  
  108. Das erzeugen von Items läuft fast genauso ab:
  109.  
  110. Item(ADR(Name), width, flags, mutualExclude, command);
  111. initialisiert eine MenuItem-Struktur und die zugehörige IntuiText-Struktur. Es muß hier kein leftEdge angegeben werden, da alle Items immer genau unter dem Menutitel stehen. Wurde seit dem letzten Item Aufruf ein oder mehrere male SubItem aufgerufen, so werden alle diese SubItems automatisch mit dem neuen Item verbunden. Ebenso sind alle seit dem letzten LinkMenu-Aufruf erzeugten Items mit diesem Item verbunden.
  112.  
  113. Sind alle Items und SubItems einer Menuspalte erzeugt, wird LinkMenu aufgerufen:
  114.  
  115. status:=LinkMenu(MenuStripPtr,Name,leftEdge,width,enabled);
  116. erzeugt eine Menu-Struktur und bindet diese an erster Stelle in den MenuStrip ein. Falls dies der erste Aufruf ist, sollte der MenuStrip-Pointer gleich NIL sein. LeftEdge und width beschreiben die Position und Größe der Menu-Selectbox in der Screen-Titelleiste. Enabled besagt, ob diese Menuspalte anwählbar (TRUE) oder gesperrt (FALSE) sein soll. Mit dem LinkMenu-Aufruf werden auch die Positionen aller Items und SubItems berechnet und in die MenuItem-Strukturen eingetragen. Das zuletzt definierte Item steht dabei direkt unter der Titelleiste, das vorletzte Item "StdHeight" Pixel darunter usw. Das erste (zuletzt definierte) SubItem eines Items steht direkt neben dem Item, alle nachfolgenden (vorher definierten) stehen "StdHeight" tiefer usw. Hat ein (Sub)Item das checkIt- oder das commSeq-Flag gesetzt, wird automatisch links seines Namens CheckWidth Pixel bzw. rechts CommWidth Pixel Platz reserviert.
  117. Ist status=TRUE, dann konnte das Menu korrekt erzeugt werden, ist es FALSE, dann trat ein Fehler auf. Es kann beispielsweise sein, daß für eine Item-Struktur kein Speicher mehr frei war. Falls ein neuer Versuch stattfinden soll, muß wieder mit dem untersten (Sub-)Item begonnen werden.
  118.  
  119. Es sei noch einmal erwähnt, daß die Items in umgekehrter Reihenfolge definiert werden müssen, wie sie später im Menu erscheinen sollen. Das zuletzt definierte Item steht an berster Stelle und hat die "ItemNum"- mer 0, das zuvor definierte steht darunter und hat die Nummer 1 usw.
  120. Am besten zeigt dies ein Beispiel. Es soll folgendes Menu programmiert werden:
  121.  
  122. CommandsAttributes
  123. do nothingmagic
  124. do lessmore magic
  125. do something -this
  126. that
  127.  
  128. In Modula mit Hilfe von IntuiStruct sieht das dann so aus:
  129.  
  130. MenuStripPtr:=NIL;
  131. Item(ADR("more magic"), 80, MenuItemFlagSet[checkIt, itemText,
  132.   itemEnabled, highComp, checked], LONGSET[0], ASCII.nul);
  133. Item(ADR("magic"), 80, MenuItemFlagSet[checkIt, itemText,
  134.   itemEnabled, highComp], LONGSET[1], ASCII.nul);
  135. LinkMenu(MenuStripPtr, ADR("Attributes"), 240, 80, TRUE);
  136.  
  137. SubItem(ADR("that"), 64, 32, MenuItemFlagSet[itemText,
  138.   itemEnabled, highComp], LONGSET[], ASCII.nul);
  139. SubItem(ADR("this"), 64, 32, MenuItemFlagSet[itemText,
  140.   itemEnabled, highComp], LONGSET[], ASCII.nul);
  141. Item(ADR("do something"), 96, MenuItemFlagSet[itemText,
  142.   itemEnabled, highComp], LONGSET[], ASCII.nul);
  143. Item(ADR("do less"), 96, MenuItemFlagSet[itemText,
  144.   itemEnabled, highComp], LONGSET[], ASCII.nul);
  145. Item(ADR("do nothing"), 96, MenuItemFlagSet[itemText,
  146.   itemEnabled, highComp], LONGSET[], ASCII.nul);
  147. LinkMenu(MenuStripPtr, ADR("Commands"), 0, 64
  148. , TRUE);
  149.  
  150. Nach Ã¶ffnen des Windows braucht man nur noch SetMenuStrip(WindowPtr, MenuStripPtr) auszuführen.
  151.  
  152. MenuNumbers
  153. Leider sin die Funktionen MENUNUM, ITEMNUM und SUBNUM (siehe Intuition Reference Manual S. 126/127) im M2Amiga Modul Intuition nicht Implementiert. In IntuiStruct ist dies jetzt nachgeholt. Dazu gehören auch die Konstanten MenuNull, NoItem und NoSub. Nützlich ist auch die (neue) Funktion MakeNum, wenn man zB. die Adresse eines bestimmten Items haben will, denn diese wird ja von IntuiStruct bei deren Definition geheimgehalten. MakeNum Ist gewissermaßen die Umkehrung von MenuNum, ItemNum und SubNum. Beispiel:
  154.  
  155. ItemAdr:=ItemAddress(MenuStripPtr,MakeNum(MenuNum,ItemNum,SubNum));Dokumentation zu "IntuiStruct" Version 1.0aSeite 
  156. Autor: Nicolas Benezan, Postwiesenstr.2, D7000 Stuttgart 60
  157. Unterstützung von Intuition in Modula
  158.  
  159.