So What Techncial Notes

Call Box
Controls in Windows

Written by: William Stephens - May 15,1990

This technical note describes how to create windows that have controls in them. This procedure gives you more flexibility than using just the Dialog Manager.

The Dialog Manager is a very convienient tool to use for user interaction but is limited in the types of controls it can present. You can take matters into your own hands and be your own Dialog Manager by using a Window that contains controls that you manage yourself. There is a little more work involved in managing your own controls than there is in operating the Dialog Manager, but the increased functionality of dialogs created this way far outweighs the added difficulty.

Virtually every call you will make with this type of window will be of the Long Call variety. Before we get into the exact procedure we should first cover the command syntax:

This call adds a control parameter list to the specified window record and returns the handle for the control created. This handle is used to find the control later on and should be stored by your program for each control created. If zero is returned then there was an error in creating the control.

CALL LC,_0,_W,_R,_T,F,V,P1 ,P2,_C,_0,_0\$0910\_CH

This call returns the handle of which control was hit (if any) based on the global mouse coordinates and the window pointer. You must supply a 4 byte buffer for the results.

CALL LC,0,_CH,X,Y,_W\$1310\P

This call acts like the Event Manager and tracks the mouse action you take after button down on the control. If you depress the mouse on a control and then without releasing, move the pointer off the control this routine will signify that no control has been selected.

CALL LC,0,X, Y,_0,_CH\$1510\P

This call draws all the controls in the specified window. This routine is usually used in update event loops and in wContDefProc's.

CALL LC,_W\$1010\

This call gets the value of the selected control.

CALL LC,0,_CH\$1A10\V

This call tells the Window Manager that a rectangle has changed and must be updated.

This call hilites or un-hilites the specified control. This call is used to blink or dim buttons and things like that.

CALL LC,H,_CH\$1110\

This call sets the value of the selected control.

CALL LC,V,_CH\$1910\V

This call sets the specified window with a new wContDetProc (window contents drawing procedure).

CALL LC,_P,_W\$490E\

This call sets up the Window Manager to handle update events.


This call ends the update session.


Windows pointer, Get from CALL WN,8 ...

Pointer to controls enclosing rectangle

Pointer to text string, Pascal 0

Control Flags (see fig. 14.1)

Controls Value.


Data size for scroll bar, if not scroll then 0.

View size for scroll bar, if not scroll then 0.

Standard Control TypeValues:
$00000000 (0) = Button
$02000000 (33554432) = Check Box
$04000000 (67108864) = Radio Button
$06000000 (100663296) = Scroll Bar
$08000000 (134217728) = Size Box

Controls handle.

Horizontal mouse coordinate

Vertical mouse coordinate

Contents Draw pointer usually 0

Window rectangle pointer

Hilite Flag 0 = none, 1-253 = part code, 255 = inactive

Figure 14.1
Figure 14.1 Control Manager Flag Bits

This procedure is shown in the program "control.demo" on the C.B.P.A.2 Sampler disk. This program was created by starting off using the "Desktop.Tmplt" program found on C.B.P.A.l and then control operating code was added.

The fIrst thing you need is a Window for your controls to be drawn in. Use the Call Box Window Editor to create a window with the following specifIcations ...

Window type: Alert
Normal Rectangle: 25,150,175,550
Zoom Rectangle: 0,0,0,0
wDataH and wMaxH: 150
wDataW and wMaxW: 400

Save this window away to disk as an object file named "ctrl.window". Now load up the program template called "Desktop.Tmplt" and save it to disk as the program "my.ctrl.demo". All of the following steps will involve adding program lines to the "my.ctrl.demo"program ... Let's roll up our sleeves and make a control window now!

Next we need is a work area for some of the control parameters. In this example I will use a "Direct Page" (see tech note 4) because I will not need over 256 bytes of space and both poke/peek and LongPoke/LongPeek commands work there. For larger control records you can use a larger block of memory as allocated by the Memory Manager in tech note 2. You may, however wish to use several direct pages instead because even though using direct pages decreases the available Applesoft code memory, both kinds of peeks and pokes will work. Memory Manager memory blocks can only be LongPeeked or LongPoked unless they are located in bank zero ... which is impossible because Call Box BASIC and the SYSTEM own all of bank zero and nothing is left down there to allocate except for direct page requests made to ProDOS8 and Call Box BASIC.

Type in line 56010 which allocates a direct page for your use and assigns the variable UP to point to it.
56010  CALL PO,4,704,$F52001A9 : CALL PO,2,708,$60BE : CALL704 : A = PEEK(PO + 244) :
       A = A + 1 : POKE PO + 244,A : UP = PO - (A*256) 
You now need to install the control wContDefProc. This is a native mode machine code routine which is specifIed as follows:
wContDefProc      pea      $0000           ;Push on the Window
                  pea      $0000           ;Pointer
                  Idx      #$1010
                  jsl      $E10000         ;_DrawControls
                  rtl                      ;Exit
Type in line 56020 to put this code in memory.
56020  DATA 244,0,0,244,0,0,162,16,16,34,0,0,225,107 : FOR X = 0 TO 13 : READ A : POKE UP 
       + X,A : NEXT : DX = 16
The next thing to do is to put in the control rectangles and the control text if any. These two items need to be poked into your workspace because the control manager handles these items by their pointers and not the actual data themselves. This is a common type of referencing in tools and this is why you usually need some kind of workspace to use tools effectively. In this example we will use all 5 types of standard controls, namely: Simple Button, Check Box, Radio Button, Scroll Bar and Grow Box. I have divided the 256 byte work area into 16- 16 byte long sections where each section handles either a rectangle or a Pascal type 0 string. The first 16 bytes of this area contains the wContDefProc you just entered with line 56020. The first rectangle will be located 16 bytes into the area and its corresponding string will reside 128 bytes from the beginning of the rectangle. The second will be 32 bytes in and 160 bytes respectively and so on. This scheme is easy to index and is written by the control poker code at 55000.

Let's enter the control poker code first:
55000  REM 
              Control Poker

55010  READ A : CALL PO,2,0 + DX + UP,A : READ A : CALL PO,2,2 + DX
       + UP,A : READ A : CALL PO,2,4 + DX + UP,A : READ A : CALL
       PO,2,6 + DX + UP,A : READ A$ : DX = DX + 128 : GOSUB 55900 :
       DX = DX - 112 : RETURN
55900  L1 = LEN (A$) : FOR I = 1 TO L1 : A = ASC (MID$ (A$,1,1)) : POKE
       DX + UP + I,A : NEXT: POKE DX + UP,L1 : RETURN 
Use the following lines to poke the controls rectangles and text:
56029  REM 
             Poke in the controls rectangles and text

56030  DATA 46,240,60,300,Button : GOSUB 55000
56032  DATA 68,240,82,400,Check Box : GOSUB 55000
56034  DATA 86,240,100,380,Radio Button: GOSUB 55000
56036  DATA 106,240,120,380,. : GOSUB 55000
56038  DATA 129,240,143,268,. : GOSUB 55000
This completes the Environmental Initialization for your program. Basically, you have created and initialized your direct page work area and installed the support data for the 5 controls. There is a bit more initialization left to do but some other things must happen first. You will notice that line 20 of your program ends with a GOSUB 56000 which runs all the code you just typed in. Add one more statement to the end of this line. This statement puts a pointer to the Call Box BASIC TaskRecord in the variable VR. This pointer is needed for Update event detection later on.

VR = ( PEEK (PO + 120) * 65536) + 593

Next you need to load your window in as entity number 4:
52     CALL WN,0,4,"entity:window:ctrl.window" : CALL WN,1,4 :
       GOSUB 42
Now that the window is in we can complete the control initialization. The following line derives the windows pointer and then patches this pointer into the control wContDefProc located in your direct page workspace:
110    CALL WN,8,4,WP,1 : CALL PO,2,1 + UP,0 - INT (WP / 65536) : 
       CALL PO,2,4 + UP,0 + WP - INT(WP / 65536) * 65536 
It's now time to issue the NewControl calls which add the controls to the window:
112    CALL LC,_0,_WP,_16 + UP,_16 + 128 + UP,!0000000000000011   
114    CALL LC,_0,_WP,_32 + UP,_32 + 128 + UP,!0000000000000000
116    CALL LC,_O,_WP,_49 + UP,_48 + 128 + UP,!0000000000000000
118    CALL LC,_0,_WP,_64 + UP,_64 + 128 + UP,!0000000000011100   
120    CALL LC,_0,_WP,_80 + UP,_80 + 128 + UP,!0000000000000000
the final step in getting this window up is to hookup the wContDefProc, show the window and draw the controls:
180    CALL LC,_UP,_WP\$490E\ : CALL WN,4,4,1 : CALL LC,_WP\$1010\ 
If you run your program at this point you will see your window with the 5 controls drawn in it. These controls will not work as of yet but they will at least be there! The following discussion is about how to operate the controls that you have created. Operating the controls is similar to operating a dialog box except that you use TaskMaster to get your events rather than a proprietary dialog manager command like ModalDialog. You want to respond to Window Content Hit events (code 19) in order to find, track and respond to control hits.

Add the following line to detect a hit in the contents region of your window:
240    IF C = 19 THEN 500 : REM Contents Hit! 
This line will route any mouse click in your window to the routine at 500. The first thing you need to do at 500 is to check and see if a control was hit and if it was, which control it is. The FindControl command does this task and returns the controls handle. The next step is to fetch this handle and then TrackControl which checks if the mouse button was released in the same control. If it is then this can be considered a valid control hit which you can now process. Type in the following lines to Find and then Track your control:
500    CALL LC,0,_250+UP,X,Y,_WP\$1310\P : REM FindControl 
510    IF P = 0 THEN 200 
515    CALL PE,4,250 + UP,H : REM Fetch the control handle 
520    CALL LC,0,X,Y,_0,_H\$1510\P : REM TrackControl 
525    IF P = 0 THEN 200 
Now we are in the home stretch ... all that is left to handle is comparing the returned control handle to the handles returned from the NewControl calls and then taking some action based on which control was hit. Type in the following lines to compare the handles:
530    IF H = C1 THEN 598 : REM Button Hit! 
535    IF H = C2 THEN 600 : REM Check Box Hit! 
540    IF H = C3 THEN 600 : REM Radio Button Hit! 
545    IF H = C4 THEN 620 : REM Scroll Bar Hit! 
550    IF H = C5 THEN 598 : REM Grow Box Hit!
As you can see some of the control handlers are the same ... as a matter of fact I am only using 3 handlers for 5 controls. These handlers are analogous to some routine that you want to run in response to a control hit. Buttons and the Grow Box have no radical function except to remain at value 0 until you click in it when the value changes to 1 ... trapping the value of a button is kind of meaningless because just the fact that you detected a hit in the control is enough justification to act upon the hit. For our purposes we will use a "Do Nothing" routine for these controls:
598   GOTO 200 
Check boxes and Radio Buttons have a more complicated life. These controls display and retain a status (either checked and unchecked or selected and WlSelected). You handle these controls just the same way you do in Dialogs, the only thing that changes is the Set and Get commands ... the methodology is identical. In this example we will use a "value toggle" routine for both:
600   CALL LC,0,_H\$1A10W : CALL LC,1 - V,_H\$191 0\ : GOTO 200 
This leaves us with scroll bars which are more complicated still. Scroll Bars actually have 5 parts to them ... 2 arrows, 1 thumb and 2 page regions (the greyed areas). Each of these parts has a part code. (see fig. 14.2)

Figure 14.2
Figure 14.2 Control Manager Part Codes

In this example we will handle the arrow and page regions the same to simplify this example. Each part code usually responds to a different handler. The plan here is to check which part of the Scroll Bar was hit and then alter the value of the Scroll bar to suit... a click on the left arrow or page will cause the control value to decrease by 1 and a click on the right arrow or page will increment it.

Type in the following lines to install this simple scroll bar handler:
620   IF P = 6 OR P = 8 THEN 650 : REM Part Code = Rt.Ar. or Rt.Pg. 
630   IF P = 5 OR P = 7 THEN 660 : REM Part Code = Lt.Ar. or Lt.Pg. 
640   GOTO 200 
650   CALL LC,0,_H\$1A10W : IF V = 9 THEN 200 
651   V = V + 1 : CALL LC,V,_H\$191 0\ : GOTO 200 
660   CALL LC,0,_H\$1A10W : IF V = 0 THEN 200 
661   V = V - 1 : CALL LC,V,_H\$1910\ : GOTO 200 
Now that you think you are done it is tiule to inform you that there is one more detail to take care of ... that is Update Events! If something changes in your window the Window Manager will fix up the window to appear just right automatically, this is one of the benifits of using the desktop environment. As you may have noticed you have not entered any commands to draw the controls except initially in the setup code. You will not have to handle this task directly ... the Window Manager handles this for you through the wContDetProc and the Update code. The Update code is very similar to the wContDetProc except that 3 new commands are needed. These commands are InvalRect, BeginUpdate and EndUpdate. You will have to install 3 more lines of code to handle Update events. One line installs a rectangle for the whole window, one line detects the Update Event and the last is the update event handler: Type in the following lines to complete your Control Window:
56040  DATA 0,0,150,400,. : GOSUB 55000 

230    CALL PE,2,VR,V : IF V = 6 THEN 295 : REM Update Event 

295    CALL LC,_96 + UP\$3A0E\ : CALL LC,_WP\$1E0E\ : CALL
       LC,_WP\$1010\ : CALL LC,_WP\$1F0E\ : GOTO 200
This is about it for this tech note. I have given you the basics and you can take it from here altho proceeding without the Apple IIgs Toolbox Reference Manuals is kind of like buying a new car and telling the salesman to leave the drive shaft out! Everything appears to be there but the car will not move on its own. The Toolbox Reference's present much more information than is economically possible in a forum like this.

Some of the benifits in putting controls in windows is that you can also put other things in there as well ... like Line Edit Items, List Controls, Icons; Quickdraw.artwork and virtually any graphic device possible with the Apple IIgs Toolbox. The handling of these other items may possibly be outlined in futtlre tech notes but don't count on it... these tech notes take a lot of time and effort to produce and there is more important fish to fry!

Further Reference
Call Box BASIC Manual V2.1
Apple IIgs Toolbox Reference Vol. 1,2 and 3 Tech Note 2 and 4

Call Box - So What Software 10221 Slater Ave. Suite 103 Fountain Valley, CA. 92708