Topic       : The GFA-Basic Compendium
Author      : GFA Systemtechnik GmbH
Version     : GFABasic.HYP v2.98 (12/31/2023)
Subject     : Documentation/Programming
Nodes       : 899
Index Size  : 28056
HCP-Version : 3
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Document not found
@help       : Help
@options    : +g -i -s +z
@width      : 75
@hostname   : STRNGSRV
@hostname   : CAB     
@hostname   : HIGHWIRE
@hostname   : THING   
View Ref-FileThis section will introduce two examples of accessory programming. They do not
perform any meaningful activity but serve illustration purposes only. The first
example program generates a window with a randomly selected fill pattern as its
contents. It runs both as an accessory and as a program. The other example
appears as a dialog box with radio buttons, an edit field and buttons.

First to the window program: it first reserves 5120 bytes for itself and then
obtains its application ID. Then it checks if its ID is 0. A value of 0 would
mean that it had be started as a program and not as an accessory.

If started as an accessory, it now enters its name into the menu. Then it
branches to an endless loop consisting of only two instructions. The first
being EVNT_MESAG(), which waits for events. The 0 parameter ensures that
messages can be evaluated with the aid of MENU(1) to MENU(8). The second
instruction calls the sub-procedure message which reacts to any messages
received.

If not started as an accessory, the program opens a window and defines a
routine for message evaluation. This routine is identical to the one performing
the task of message evaluation in the accessory version. The REPEAT-UNTIL loop
will now wait for events until the procedure message sets the variable exit! to
TRUE.

The procedure message is almost identical in structure to a normal window
management routine in a normal program. It first reads the coordinates of the
current window into the variables x&, y&, b&, and h&.

The SELECT-CASE instruction branches according to the different possible
messages received by MENU(1). The first such message is also the most
important: the redraw message.

As soon as this message is received, the AES is informed about the imminent
screen redraw with WIND_UPDATE(1). We now go through the rectangles list of the
window in which the redraws take place.

Each rectangle is drawn in a random fill pattern. Unless two adjacent
rectangles happen to be drawn in identical fill patterns by chance, you can
examine the way GEM manages the rectangles list. For redrawing the rectangles
it would, strictly speaking, be sufficient to draw the rectangle only in the
area affected by a clipping.

But the method followed is the same as in a conventional window program. The
clipping is imposed on the rectangle to be drawn and the entire working area of
the window is redrawn. In your own program, you would have to replace the PBOX
command with a routine to draw the window contents.

The remaining messages can be dealt with by only a few instructions. In the
example, commands specific to GFA BASIC, such as TOPW, FULLW etc., are
generally used. At the WM_CLOSED message, in addition to CLOSEW, the variable
exit! is set to TRUE. This is to cover the possibility of the program not
running as an accessory.

This routine differs from a normal window management routine by its ability to
react to the message AC_OPEN. This message reports that the user has selected
the accessory. As a result, the window is opened.

The areas over written by the accessory must be redrawn by the program from
which the accessory was called. The task of sending an appropriate redraw
message to that program is performed by GEM and need not be considered in this
listing.

$m5120
ap_id&=APPL_INIT()
'
IF ap_id&<>0
  me_id&=MENU_REGISTER(ap_id&,"  Window-ACC ")
  DO
    ~EVNT_MESAG(0)
    message
  LOOP
ELSE
  TITLEW #1,"Window-Program"
  INFOW #1," in GFA-BASIC 3.0"
  OPENW #1,50,50,200,100,&X111111
  handle&=W_HAND(#1)
  ON MENU MESSAGE GOSUB message
  exit!=FALSE
  REPEAT
    ON MENU
  UNTIL exit!
ENDIF
'
PROCEDURE message
  x&=MENU(5)
  y&=MENU(6)
  b&=MENU(7)
  h&=MENU(8)
  '
  SELECT MENU(1)
  CASE 20 ! /*** WM_REDRAW ***/
    ~WIND_UPDATE(1)
    ~WIND_GET(handle&,11,rx&,ry&,rb&,rh&) !First rectangle in the list
    ~WIND_GET(handle&,4,ax&,ay&,ab&,ah&) !Working area in window
    REPEAT
      IF RC_INTERSECT(ax&,ay&,ab&,ah&,rx&,ry&,rb&,rh&)
        CLIP rx&,ry&,rb&,rh& OFFSET ax&,ay&
        DEFFILL 1,2,RAND(25)
        PBOX 0,0,PRED(ab&),PRED(ah&)
        CLIP 0,0,WORK_OUT(0),WORK_OUT(1)
      ENDIF
      ~WIND_GET(handle&,12,rx&,ry&,rb&,rh&) !Next rectangle in list
    UNTIL rb&=0 AND rh&=0 !No more in list
    ~WIND_UPDATE(0)
  CASE 21 ! /*** WM_TOPPED ***/
    TOPW #1
  CASE 22,41 ! /*** WM_CLOSED and AC_CLOSE ***/
    CLOSEW #1
    exit!=TRUE
  CASE 23 ! /*** WM_FULLED ***/
    FULLW #1
  CASE 27 ! /*** WM SIZED ***/
    ~WIND_SET(handle&,5,x&,y&,MAX(180,b&),MAX(80,h&))
  CASE 28 ! /*** WM_MOVED ***/
    ~WIND_SET(handle&,5,x&,y&,b&,h&)
  CASE 40 ! /*** AC_OPEN ***/
    TITLEW #1,"Window-Accessory"
    INFOW #1," in GFA-BASlC 3.0"
    OPENW #1,50,50,200,100,&X111111
    handle&=W_HAND(#1)
  ENDSELECT
RETURN

Now to the next sample program in which a dialog box is used. This program
reserves quite a lot of memory space for itself to begin with, almost 13kb.
This space is required primarily to save, with GET, the screen area covered by
the dialog box.

In the window program, GEM sent out a redraw message when the accessory window
was closed. If the dialog boxes of an accessory are to disappear from the
screen and the old contents of the area restored, another method has to be
chosen.

One possibility is to trigger the redraw message for the screen area affected.
For this purpose, there exists the FORM_DIAL(3,...) routine. Another
possibility is illustrated by the program following. It is possible to read in
the screen area covered by the dialog box with GET, and then to restore it
later with PUT.

Using FORM_DIAL() requires less memory space. However, the program that is to
perform the redraw may need some time for this task. Using GET and PUT is
considerably faster.

This program, by the way, also calls an alert box. The screen area covered is
automatically redrawn by GEM. GEM uses a similar method for this as the one
chosen in our program with GET and PUT. The area covered by the alert box,
therefore, does not have to be redrawn by the BASIC program since GEM will be
doing it.

After determining the application ID the program checks if it has been started
as an accessory. If not, it wiil terminate itself. In contrast to the
previously discussed window demo, this demo will therefore run as an accessory
oniy.

Next the accessory attempts to load in its resource file. If it cannot find
this, it must not be terminated like a normal program because it wouid then get
into an endless loop with an EVNT instruction.

If the resource file has been found, the program assigns object numbers to the
dialog box variables. This part of the program consists of the LST file written
by the Resource Construction Set. Once this is done, the address of the dialog
box tree is obtained and a default text assigned to the editable field.

Only now is the accessory entered into the menu. In the following loop, it
waits to be called via (MENU(1)=40). As soon as this call arrives, the
dimensions of the dialog box are calculated and the corresponding screen area,
with a additional safety margin, is saved. The dialog box can now be drawn and
managed with FORM_DO().

On quitting the dialog box, the exit object is reset to its previous state and
the screen area overwritten by the box restored with PUT.

In the following lines, the information entered into the dialog box by the
user, is read and displayed in an alert box. Then the accessory returns to the
endless loop, where it awaits its next call.

$m12800
ap_id&=APPL_INIT()
IF ap_id&=0
  ALERT 1,"Program runs only|as an accessory",1," Return ",a|
  END
ENDIF
'
IF RSRC_LOAD("dial_acc.rsc")=0
  DO !If the RSC file cannot be found, then
    ~EVNT_TIMER(-1) !simply wait for as long as it takes
  LOOP !because there is nothing to do
ENDIF
'
' Object numbers from the construction set
LET dialog&=0 !RSC_TREE
LET text&=8 !Obj in #0
LET abbruch&=2 !Obj in #0
LET return&=3 !Obj in #0
LET radio1&=5 !Obj in #0
LET radio2&=6 !Obj in #0
LET radio3&=7 !Obj in #0
'
~RSRC_GADDR(0,dialog&,dialog_adr%)
CHAR{{OB-SPEC(dialog_adr%,text&)}}="Testtext"
me_id&=MENU_REGISTER(ap_id&,"  Dialog-ACC ")
'
DO
  ~EVNT_MESAG(0)
  IF MENU(1)=40
    ~FORM_CENTER(dialog_adr%,x&,y&,b&,h&)
    ~WIND_UPDATE(1)
    GET x&-4,y&-4,x&+b&+4,y&+b&+4,rette$ !For Redraw.
    ~OBJC_DRAW(dialog_adr%,0,3,x&,y&,b&,h&)
    ex&=FORM_DO(dialog_adr%,0)
    ~OBJC_CHANGE(dialog_adr%,ex&,0,x&,y&,b&,h&,0,0)
    PUT x&-4,y&-4,rette$ !Redraw.
    ~WIND_UPDATE(0)
    t$=CHAR{{OB_SPEC(dialog_adr%,text&)}}
    IF BTST(OB_STATE(dialog_adr%,radio1&),0)
      r$="1"
    ELSE IF BTST(OB_STATE(dialog_adr%,radio2&),0)
      r$="2"
    ELSE IF BTST(OB_STATE(dialog_adr%,radio3&),0)
      r$="3"
    ENDIF
    a$="Text: "+t$+"|Radio_Button: "+r$+"|Exit-Button: "+STR$(ex&)
    ALERT 1,a$,1," Ok ",a|
  ENDIF
LOOP