-------------------------------------------------------------------------------- - GFA-FLYD, 'Fliegende Dialoge' in GFA-BASIC 3.x - - (c)1992-1993 Gregor Duchalski - - - - Version 4.0 - - Dokumentation - -------------------------------------------------------------------------------- Mit den hier vorliegenden Routinen k”nnen Sie endlich auch GFA-BASIC- Programme mit zeitgem„žen Dialogboxen versehen: -Frei verschiebbare Dialoge -Modale Fenster-Dialoge -Unterstrichene Dialogtitel -Ankreuz-Buttons (Checkboxen) -Runde Buttons (Radio-Buttons) -Tastaturbedienbare Buttons mit unterstr. Buchstaben -Menue-Nicelines -Popup-Mens -Farbicons (in Zusammenhang mit INTERFACE) Die Routinen funktionieren in allen ST/STE/TT-Aufl”sungen! Die Realisation der Objekte orientiert sich dabei eng an den Flydials von Julian Reschke, dem die Ehre gebhrt, hier einen weitreichenden Standard geschaffen zu haben. Danken m”chte ich: -Manuel Herrmann, von dem einige Ausgaberoutinen und Grundzge der Popup-Verwaltung stammen -Dirk Koenen fr die SOLID-Flydials -Alexander Lorenz, der die virtuelle Workstation in's Spiel brachte und etwas anderes in meinen Programmteil :-) -David Reitter, der die Shortcut-Routine beisteuerte und immer neue Fehler entdeckte -Mike Steffl fr seine unermdlichen Bugreports und Memohelp -Michael Heng fr den ausgiebigen Erfahrungsaustausch -Olaf Meisiek fr die Farbicon-Untersttzung -------------------------------------------------------------------------------- Programmstatus: Shareware... -------------------------------------------------------------------------------- Die Routinen sind Shareware, die Weitergabe ist erwnscht. Allerdings drfen die Funktionen nur komplett und ohne Žnderungen weitergegeben werden. Sollten Sie die Routinen in eigenen Programmen verwenden, so muž der Ursprung erw„hnt wer- den! Benutzen Sie die Routinen regelm„žig, so wird die Shareware-Gebhr von DM 25.- f„llig. Registrierte Benutzer erhalten folgende Sonderleistungen: -Eine Reihe von ntzlichen Zusatzroutinen und Programmen. Eine Beschreibung folgt weiter unten und in dem Text EXTENDED.TXT auf der Diskette. -Routinen zur Farbicon-Untersttzung -Den Quellcode der Ausgaberoutinen in Assembler. -Zugriff auf die GFA_FLYD-Gruppe in der Maus DO2, in der z.B. immer die neueste Version der Routinen liegt. Meine Adresse : Gregor Duchalski, Baueracker 15a, W-4690 Herne 1 (ab 1.Juli '93: 44628 Herne) oder per eMail: GREGOR DUCHALSKI @ DO (oder DO2) im Mausnetz Meine Bankverbindung: Konto-Nr.: 65 304 30 BLZ: 430 700 61 Deutsche Bank Herne Die jeweils neueste Version der Routinen k”nnen Sie auch durch Einsenden eines frankierten Rckumschlages und einer Leerdiskette an obige Adresse erhalten. WICHTIG - WICHTIG - WICHTIG - WICHTIG - WICHTIG - WICHTIG - WICHTIG - WICHTIG Geben Sie bitte bei šberweisungen im Feld fr Bemerkungen Ihren Namen und den Verwendungszweck an. Die Sharewaregebhr umfažt bereits die ”ffentliche Version, die zus„tzlichen Leistungen sind als Zugabe und nicht etwa als Gegenwert zu verstehen! Der Vertrieb ber PD-Versender ist ohne mein Einverst„ndnis nicht gestattet! Nur die ”ffentliche Version der Routinen ist frei kopierbar, die Version fr registrierte Benutzer darf nicht weitergegeben werden! WICHTIG - WICHTIG - WICHTIG - WICHTIG - WICHTIG - WICHTIG - WICHTIG - WICHTIG -------------------------------------------------------------------------------- Folgende Dateien enth„lt die ”ffentliche Version: -------------------------------------------------------------------------------- RELEASE.TXT Versions-History und Neuheiten der aktuellen Version. GFA_FLY4.LST Die Grundversion der fliegenden Dialoge im ASCII-Format. GFA_FLY4.INL INLINE-Code mit den Ausgaberoutinen. GFA_FLY4.RSC Resource-Datei zum Beispielprogramm. GFA_FLY4.UPL Der Text fr den Mailbox-Upload. Sollten Sie einen anderen verwenden mssen, so geben Sie bitte das Datum der Version mit an. Danke sehr. GFA_FLY4.TXT Dieser Text. FENSTER.LST Enth„lt die erweiterte Version der Lib mit Fensterdialogen. TOOL_BOX.RSC 'Werkzeugkasten' mit allen erweiterten Objekten. -------------------------------------------------------------------------------- Folgende Dateien enth„lt zus„tzlich die registrierte Version: -------------------------------------------------------------------------------- RELEASEE.TXT Infos zur aktuellen, erweiterten Version. *EXTENDED EXTENDED.LST Zus„tzliche Erweiterungs-Routinen, siehe unten. EXTENDED.TXT Beschreibung der Zusatz-Routinen. BUSYMAUS.INL INLINE fr die Busy-Maus-Routine aus EXTENDED.LST *SOURCE GFA_FLY4.S Der Assembler-Quellcode der Ausgaberoutinen MAKE_INL.LST Programm zur Nachbearbeitung des INLINEs. CIRCLE_H.INL Die Bitmap fr den 16*16 Circlebutton. CIRCLE_M.INL Die Bitmap fr den 16*8 Circlebutton. RADIO_H.INL Die Bitmap fr den 16*16 Radiobutton. RADIOS_H.INL Die Bitmap fr den 16*16 selekt. Radiobutton. RADIO_M.INL Die Bitmap fr den 8*16 Radiobutton. RADIOS_M.INL Die Bitmap fr den 8*16 selekt. Radiobutton. SOURCE.TXT Beschreibung der Sourcen. *FARBICON FARBICON.LST Beispiel-Listing fr die Farbicon-Untersttzung. FARBICON.RSC Beispiel-Resource. FARBICON.TXT Erl„uterungen zur Farbicon-Untersttzung. XRSRC.LST Die reinen XRSRC-Routinen ohne Beispiel zum Anh„ngen an bestehende Programme. RELO.INL INLINE mit einer Relozier-Routine. -------------------------------------------------------------------------------- Fenster-Dialoge erwnscht... -------------------------------------------------------------------------------- Diese Library ist in zwei Teile gegliedert, um sowohl Anf„ngern als auch Fort- geschrittenen gerecht zu werden. Die Grundversion finden Sie in der Datei GFA_FLY4.LST. Diese Routinen enthalten keine Fensterdialoge. Die zus„tzlichen Routinen fr Fenster-Dialoge finden Sie inkl. Beispiellisting in der Datei FENSTER.LST. Diese Routinen sind voll kompatibel zur Grundversion, lediglich die Prozeduren 'rsc_draw' und 'rsc_back' wurden erweitert sowie einige andere Prozeduren hinzugefgt. Diese Routinen fr k”nnen wahlweise auch 'normale' Dialoge darstellen und beinhalten quasi die Grundversion. -------------------------------------------------------------------------------- Handhabung... -------------------------------------------------------------------------------- Zu Programmbeginn sollte die Prozedur rsc_init aufgerufen werden. Sie initialisiert die von den RSC-Routinen ben”tigten globalen Variablen. Einige davon werden im Interesse der sauberen Programmierung wahrscheinlich sowieso von Ihrem Programm ben”tigt: ap_id& --> Die Applikations-Id unseres Programmes. mtos! --> Ist TRUE unter MultiTOS (und _nicht_ unter MultiGEM oder MAGX) rsc_vh& --> Handle der Flydial-Bildschirm-Workstation. planes& --> Anzahl Bitplanes. deskx& --> Ausmaže des Desktopbereiches... desky& deskw& deskh& ------------------------------------------------------------- Die Resource wird mit ~@rsc_laden(file$,anz_trees&,popup&,menu&) geladen und initialisiert. file$ ist hierbei der Dateiname, anz_trees& die Anzahl der B„ume (mit 0 beginnend). popup& bezeichnet den Popup-Baum (s.u.), menu& den Dropdown-Menbaum. Gibt es keinen dieser B„ume, so ist -1 zu setzen. Die Funktion liefert TRUE zurck, wenn die Resource korrekt geladen wurde. In dieser Funktion werden folgende globale Variablen initialisiert: rsc_trees --> Die Anzahl der Objektb„ume. rsc_popup& --> Der Index des Popup-Objektbaumes. rsc_menu& --> Der Index des Dropdown-Menbaumes. rscx&() --> Die Koordinaten der Dialoge, wie sie rscy&() von FORM_CENTER zurckgeliefert werden. rscw&() rsch&() rsc_adr%() --> Die Adressen der Objektb„ume. rsc_handle%() --> Enth„lt bei einem normalen Dialog die Adresse des gepuffer- ten Hintergrundes, bei einem Fenster-Dialog das Fenster- Handle. Anhand dieser Variable wird die sp„ter auch die Unterscheidung Fensterdialog<->normaler Dialog getroffen. ------------------------------------------------------------- Ein Dialog wird mit rsc_draw(tree_index&,window_flag!) gezeichnet. Ist window_flag!=TRUE, so wird der Dialog im Fenster dargestellt, ansonsten als normaler Dialog. In letzterem Fall wird nach M”glichkeit der Hintergrund gepuffert und die Adresse des Puffers in rsc_handle%() abgelegt. Aužerdem wird mit WIND_UPDATE(BEG_UPDATE) der Bildschirm fr andere Applika- tionen gesperrt. Bei einem Fensterdialog werden alle Mentitel bis auf den ersten disabled. Sollte kein Fenster mehr zur Verfgung stehen, so wird _immer_ ein normaler Dialog verwendet. Wenn ein Dialog niemals im Fenster dargestellt werden soll, k”nnen Sie ihn im RCS v”llig frei gestalten. Wenn er aber auch (oder immer) im Fenster dargestellt werden soll, gilt es folgendes zu beachten: -Er sollte einen unterstrichenen Titel haben. Dieser Titel wird n„mlich als Fenstertitel verwendet, ansonsten hat das Fenster keinen Titel. -Die ersten zwei Zeilen eines Dialoges werden nicht im Fenster dargestellt, da- her sollten sie keine Objekte aužer der Flugecke und dem Dialogtitel enthalten! ------------------------------------------------------------- Die Bearbeitung eines Dialoges erfolgt mit rsc&=@rsc_do(tree&,popup&) rsc& enth„lt nach dem Beenden der Dialogauswertung die Nummer des angew„hlten Objektes. Bei einem Doppelklick auf ein TOUCHEXIT-Objekt wird analog zur Origi- nal-FORM_DO das 15. Bit gesetzt. popup& ist ebenfalls eine Rckgabevariable, die nur ausgewertet werden muž, wenn ein Popup-Men angew„hlt wurde (s.u.). Bei einem Fensterdialog wird aus dieser Routine heraus die Prozedur 'message_ auswerten' aufgerufen, wenn ein Fenster des Programmes bedient wurde. Bei dieser Prozedur sollte es sich um Ihre globale Auswertung der Message-Ereig- nisse handeln. Das 'Toppen' eines eigenen Fensters ist w„hrend der Dialogdurch- fhrung nicht m”glich, die Fenster anderer Programme k”nnen aber in den Vorder- grund geholt werden. Auch das Schliežen eines eigenen Fensters ist nicht m”glich, da sonst u.U. die rsc_do-Routine verlassen werden k”nnte. Das wrde zu schwerwiegenden Problemem fhren. Sollten Sie sicher sein, daž das Schliežen eines Hintergrundfensters bei Ihrem Programm keine Probleme bedingt, k”nnen Sie das Schliežen aber trotzdem zulassen. Sollten Sie keine weiteren Fenster in Ihrem Programm verwenden, muž natrlich keine 'message_auswerten'-Prozedur existieren. Die entsprechenden Zeilen k”nnen dann zu REM werden. ------------------------------------------------------------- Der Dialog wird mit rsc_back(tree&) vom Bildschirm entfernt. Dabei wird bei einem normalen Dialog der gepufferte Hintergrund restauriert und die Bildschirm-Sperre mit WIND_UPDATE(END_UPDATE) aufgehoben. Bei einem Fensterdialog wird das Fenster geschlossen und die Men- titel wieder anw„hlbar gemacht. ------------------------------------------------------------- Am Programmende sollte rsc_exit aufgerufen werden. Hier werden die angeforderten Speicherbereiche freigegeben und die virtuelle Workstation geschlossen. ------------------------------------------------------------- Noch ein Wort zu dieser Library: Alle Routinen sind sehr komprimiert gehalten, d.h. es wurden m”glichst viele Zeilen in eine Prozedur gepackt. Das ist nor- malerweise kein guter Stil, in unserem Falle aber sinnvoll, damit die šbersicht im eigentlichen Programm nicht behindert wird. Die Routinen sind als 'Black- boxes' konzipiert, in die Sie normalerweise sowieso keinen Blick mehr werfen mssen. -------------------------------------------------------------------------------- Diese erweiterten Objekttypen gibt es... -------------------------------------------------------------------------------- Zur Festlegung der erweiterten Objekttypen wird das obere, unbenutzte Byte von OB_TYPE benutzt. Die Zuordnung entspricht dabei nahezu den Flydials von Julian Reschke bzw. den Mydials von Olaf Meisiek. Dadurch k”nnen die Dialoge bereits in INTERFACE ber 'Objektbaum testen' mit ihrem sp„teren Aussehen dargestellt werden. In der folgenden šbersicht sind jeweils der erweiterte Typ, der ursprngliche Objekttyp und die gesetzten Flags angegeben: ------------------- 17 'FlyDial' (IBOX) OUTLINED, CROSSED Das Objekt in der oberen rechten Ecke eines Dialoges, mit dem die Dialogbox verschoben werden kann. ------------------- 18 Radiobutton (BUTTON oder STRING) SELECTABLE, RBUTTON Ein runder Radiobutton. ------------------- 18 Checkbox (BUTTON) SELECTABLE, nicht EXIT Ein K„stchen mit einem Kreuz. ------------------- 18 Exitbutton (BUTTON) EXIT Ein 'normaler' Button, der aber ber die Tastatur bedient werden kann. ------------------- 18 String (STRING) TOUCHEXIT Ein tastaturbedienbarer String. Wenn das n„chste Objekt eine Popup-Button ist, so kann hiermit das Popup ge”ffnet werden. ------------------- 19 Unterstrichener Text (BUTTON oder STRING) Wird normalerweise fr den Titel eines Formulares verwendet. Die L„nge des Unterstrichs wird durch die Breite des Objektes bestimmt. ------------------- 20 Boxtitel (BUTTON) Ein Rahmen mit einem Titel in der linken oberen Ecke. ------------------- 21 Niceline (STRING) DISABLED Nur in Dropdown-Menues sinnvoll: Die Trennstriche '-----' werden umgestaltet. Nicelines sind auch in Popup-Mens verwendbar. Hinweis: Bei den Mydials bezeichnet der Typ 21 einen HELP-Button. Ich weiche in diesem einen Punkt davon ab, da so die Initialisierung beschleunigt wird. -------------- 22 Circlebutton (BOXCHAR) TOUCHEXIT Wird durch einen kleinen Kreis dargestellt und dient im Zusammenhang mit einem Popupmenue zum Weiterschalten der Meneintr„ge. Hinweis: M”chten Sie den Circlebutton als 'normales' Objekt ohne Verbindung zu einem Popup-Men verwenden, so sollte er durch ein anderes Objekt (z.B. BOX) unterlegt werden. ------------------- 31 Popup-Button (BOXTEXT) SHADOWED Der Button, der ein Popup-Menue erscheinen l„žt. Die Unterscheidung auf Popup-Button wird allerdings nicht anhand des erweiterten Objekttyps, sondern am Status SHADOWED festgemacht. Im unbenutzen Byte von OB_TYPE wird der Index des Popups plus 30 festgehalten, siehe unten. ------------------- Zus„tzliches Flags: Ein gesetzes Bit 14 in OB_FLAGS kennzeichnet einen Button, der durch Drcken der UNDO-Taste bedient werden kann. Ein gesetzes Bit 15 in OB_FLAGS kennzeichnet einen Button, der durch Drcken der HELP-Taste bedient werden kann. -------------------------------------------------------------------------------- Popup-Mens... -------------------------------------------------------------------------------- Alle Popup-Mens mssen sich in _einem_ Objektbaum befinden. Das Vater-Objekt ist eine schattierte Box, die Kind-Objekte sind vom Typ TEXT oder STRING und mssen in aufsteigender Reihenfolge sortiert sein. Ein Popup-Button ist ein schattierter Button. Ein eventueller Circlebutton muž Kindobjekt dieses Buttons sein. Jedem Popup-Button wird nun ein Popup-Menue zugeordnet, das beim Anklicken des Buttons erscheint. Das geschieht ber den erweiterten Objekttyp. Hier wird die Nummer des Popup-Mens plus 30 eingetragen. Wohlgemerkt, es geht hier nicht um die Objektnummer, sondern um den Index des Popup-Mens bezogen auf den Baum, in dem sich die Mens befinden. Enth„lt er z.B. 3 Mens, so gehen diese Nummern von 1-3. Die Bedienung eines Popup-Buttons wird automatisch in der rsc_do-Routine erledigt, die ja wie bereits bekannt aufgerufen wird: rsc&=@rsc_do(tree&,popup&) Nach dem Ausw„hlen eines Menuepunktes gibt die rsc_do-Routine wie gewohnt die Objektnummer des angew„hlten Objektes, in diesem Fall also des Popup-Buttons, zurck. Zus„tzlich enth„lt die Variable popup& den Index des angew„hlten Menue-Eintrages. Dieser kann nun ausgewertet werden, muž aber nicht. Popup-Mens sind auch ber die Tastatur steuerbar: Cursor hoch/runter: Eintrag rauf/runter. Esc/Undo : Bricht die Auswahl ab. Return/Enter : W„hlt einen Eintrag aus. Ein tastaturbedienbarer String (s.o.) unmittelbar vor dem Popup aktiviert ebenfalls das Men. -------------------------------------------------------------------------------- Erweiterungen... -------------------------------------------------------------------------------- Die Grundversion der Library ist sehr kurz und Speicherplatz sparend gehalten. Daher sind die Routinen fr -Zus„tzliche Tastaturkommandos -SOLID-Flydials -Farbicons -Zeichengenaues Cursor-Positionieren mit der Maus -Setzen und Auslesen eines Popup-Buttons nach dem Index des Eintrags -die Auswertung eines Men-Shortcuts -Setzen und Auslesen der OB_STATE/OB_FLAGS-Bits -Setzen und Abfragen einer Gruppe von Radiobuttons -die Anzeige eines Busy-Mauszeigers nicht in dieser Grundversion enthalten, weil sie den Programmcode doch stark anwachsen lassen und nicht immer n”tig sind. M”chten Sie nicht auf eines (oder alle) dieser Feature verzichten, so finden Sie die entsprechenden Routinen in der Datei EXTENDED.LST bzw. im Ordner FARBICON. Allerdings nur, wenn Sie sich als Benutzer registrieren lassen, denn in der ”ffentlichen Version fehlen diese Datei! -------------------------------------------------------------------------------- Goodies... -------------------------------------------------------------------------------- In den Assembler-INLINE ist ein spezieller BITBLT integriert, der direkt aufgerufen werden kann. Er stellt dann einen flexiblen Ersatz fr GET/PUT und auch den Basic-BITBLT dar. Aufgerufen wird er mit den folgenden Parametern, die denen des Original BITBLT entsprechen: rsc_bitblt(qadr%,qw&,qh&,zadr%,zw&,zh&,x&,y&,w&,h&,ax&,ay&) qadr% Adresse des Quellrasters qw& Breite in Pixeln qh& H”he in Pixeln zadr% Adresse des Zielrasters zw& Breite in Pixeln zh& H”he in Pixeln x&,y&,w&,h& Zu kopierender Bereich ax&,ay& Zielkoordinaten Hiebei wird immer im REPLACE-Modus kopiert. Es ist natrlich auch m”glich, die Assembler-Routinen mit ~C:bitblt%(..) direkt aufzurufen, dann k”nnen auch die Anzahl der Bitplanes und das Rasterformat angegeben werden. Schauen Sie sich dazu am besten die rsc_bitblt() Routine an. Fr Fortgeschrittene: Diese Funktion verwendet die VDI-Routine vrt_cpyfm() bzw. bei gleicher Anzahl Bitplanes automatisch vro_cpyfm(). ------------------------------------------------------------- Ebenfalls in den INLINE integriert ist eine spezielle OB_SPEC-Routine. Diese gibt fr jedes Objekt die Adresse zurck, an der Textstring des Objektes steht. So kann mit der Funktion DEFFN rsc_text$(rsc_adr%,obj&)=CHAR{C:rsc_obspec%(L:rsc_adr%,obj&)} einfach der entsprechende Text ausgelesen werden bzw. mit der Prozedur PROCEDURE rsc_text(rsc_adr%,obj&,a$) CHAR{C:rsc_obspec%(L:rsc_adr%,obj&)}=a$ RETURN der Text gesetzt werden. Ein umst„ndliches Unterscheiden nach dem Objekt- Typ entf„llt damit! -------------------------------------------------------------------------------- It's not a bug, it's a feature... -------------------------------------------------------------------------------- Die Routinen kmmern sich selbst um das Ein/Ausschalten der Maus (mit GRAF_ MOUSE) und funktionieren damit auch mit dem LINEA-freien GFA-Linker/Interpreter. Dabei kann es im normalen Interpreter zu Mausflecken kommen, die aber im Compiler nicht auftreten (And that's what we all work for, isn't it?). -------------------------------------------------------------------------------- Herne 1, 01.03.93