--------------------------------------------------------------------------------
- GFA-FLYD, 'Fliegende Dialoge' in GFA-BASIC 3.x                               -
- (c)1992-1993 Gregor Duchalski                                                -
-                                                                              -
- Version 4.0                                                                  -
- Dokumentation                                                                -
--------------------------------------------------------------------------------

Mit den hier vorliegenden Routinen knnen Sie endlich auch GFA-BASIC-
Programme mit zeitgemen 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-Auflsungen!

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 mchte 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 erwhnt wer-
den! Benutzen Sie die Routinen regelmig, so wird die Shareware-Gebhr von
DM 25.- fllig. 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 knnen 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 umfat bereits die ffentliche Version, die zustzlichen
Leistungen sind als Zugabe und nicht etwa als Gegenwert zu verstehen!

Der Vertrieb ber PD-Versender ist ohne mein Einverstndnis 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 enthlt 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        Enthlt die erweiterte Version der Lib mit Fensterdialogen.           

  TOOL_BOX.RSC       'Werkzeugkasten' mit allen erweiterten Objekten.

--------------------------------------------------------------------------------
Folgende Dateien enthlt zustzlich die registrierte Version:
--------------------------------------------------------------------------------

  RELEASEE.TXT       Infos zur aktuellen, erweiterten Version.

 *EXTENDED
  EXTENDED.LST       Zustzliche 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       Erluterungen zur Farbicon-Untersttzung.
  XRSRC.LST          Die reinen XRSRC-Routinen ohne Beispiel zum Anhngen an
                     bestehende Programme.
  RELO.INL           INLINE mit einer Relozier-Routine.

--------------------------------------------------------------------------------
Fenster-Dialoge erwnscht...
--------------------------------------------------------------------------------
Diese Library ist in zwei Teile gegliedert, um sowohl Anfngern als auch Fort-
geschrittenen gerecht zu werden. Die Grundversion finden Sie in der Datei 
GFA_FLY4.LST. Diese Routinen enthalten keine Fensterdialoge.

Die zustzlichen 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 knnen 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 bentigten
globalen Variablen. Einige davon werden im Interesse der sauberen
Programmierung wahrscheinlich sowieso von Ihrem Programm bentigt:

 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&      --> Ausmae 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 Bume (mit 0 beginnend). popup& bezeichnet den Popup-Baum (s.u.),
menu& den Dropdown-Menbaum. Gibt es keinen dieser Bume, 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 Objektbume.
 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 Objektbume.

 rsc_handle%() --> Enthlt bei einem normalen Dialog die Adresse des gepuffer-
                   ten Hintergrundes, bei einem Fenster-Dialog das Fenster-
                   Handle. Anhand dieser Variable wird die spter 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 Mglichkeit der 
Hintergrund gepuffert und die Adresse des Puffers in rsc_handle%() abgelegt.
Auerdem 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, knnen Sie ihn im
RCS vllig 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 nmlich 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 auer der Flugecke und dem Dialogtitel enthalten!

        -------------------------------------------------------------

Die Bearbeitung eines Dialoges erfolgt mit

 rsc&=@rsc_do(tree&,popup&)

rsc& enthlt nach dem Beenden der Dialogauswertung die Nummer des angewhlten
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 angewhlt 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 whrend der Dialogdurch-
fhrung nicht mglich, die Fenster anderer Programme knnen aber in den Vorder-
grund geholt werden. Auch das Schlieen eines eigenen Fensters ist nicht
mglich, da sonst u.U. die rsc_do-Routine verlassen werden knnte. Das wrde
zu schwerwiegenden Problemem fhren. Sollten Sie sicher sein, da das
Schlieen eines Hintergrundfensters bei Ihrem Programm keine Probleme bedingt,
knnen Sie das Schlieen aber trotzdem zulassen.

Sollten Sie keine weiteren Fenster in Ihrem Programm verwenden, mu natrlich
keine 'message_auswerten'-Prozedur existieren. Die entsprechenden Zeilen
knnen 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 anwhlbar 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 mglichst 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 knnen die Dialoge bereits
in INTERFACE ber 'Objektbaum testen' mit ihrem spteren 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 Kstchen 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 nchste Objekt eine Popup-Button
   ist, so kann hiermit das Popup geffnet werden.

-------------------
19 Unterstrichener Text (BUTTON oder STRING)

   Wird normalerweise fr den Titel eines Formulares verwendet. Die Lnge
   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 Meneintrge.
   Hinweis: Mchten 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 lt. 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.

-------------------

Zustzliches 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. Enthlt 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 Auswhlen eines Menuepunktes gibt die rsc_do-Routine wie gewohnt die
Objektnummer des angewhlten Objektes, in diesem Fall also des Popup-Buttons,
zurck. Zustzlich enthlt die Variable popup& den Index des angewhlten
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      : Whlt 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

 -Zustzliche 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 ntig sind. Mchten 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&          Hhe in Pixeln

zadr%        Adresse des Zielrasters
zw&          Breite in Pixeln
zh&          Hhe in Pixeln

x&,y&,w&,h&  Zu kopierender Bereich
ax&,ay&      Zielkoordinaten

Hiebei wird immer im REPLACE-Modus kopiert. Es ist natrlich auch mglich, die
Assembler-Routinen mit ~C:bitblt%(..) direkt aufzurufen, dann knnen 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 umstndliches Unterscheiden nach dem Objekt-
Typ entfllt 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
