Version 2.0 15 Jan-90
CALL WN the WINDOW commands
Windows are high level tool functions which are dependent on other toolbox functions as well as GS/OS (ProDOSl6) commands. The menu functions need to be initialized by using the "high level" startup command CALL TL,2,"Desk" (see CALL TL in this manualfor a complete description). This call will startup all tools needed for desktop applications ... the Window Manager is one of them.
Windows are designated as "entities" in the Call Box BASIC driver and these entities are created using the Call Box TPS Window Editor. The output type "object" must be used for windows that are to be used by the BASIC driver.
Figure 2.15 A Window entity
Operating a Window is automatic, you must load it and open it. Once a window is open you would probably draw something in it to display. To draw to a window you simply point to the windows port by using the port command CALL PT,O, (entity number) and then use drawing and text commands to create the windows contents. The TaskMaster call in your programs event loop is at the heart of window operations. TaskMaster will return task codes (see Figure 2.8) which will inform you if a particular part of a window was clicked in as well as other status information. If you want the "system" to handle the operation of the windows then you would take no action on the window type task codes and loop back to your TaskMaster call. Moving, growing-shrinking, Scrolling and Zooming the window will happen without any program lines on your part, and you usually only need to handle the go-away region task code (#22) in order to close the window.
Drawing to a Window
Each window has a contents region which displays the information contained in the window. This information is "drawn" to the window using any of the drawing commands included in the Call Box BASIC driver. Information can also be put in a window by using the "port to port" command (such as super hi-res pictures). When something is drawn to a window it will be drawn in "local" coordinates ... the mouse position is in "global" coordinates, if you wish to draw into the window using the mouse/cursor like a pen then you must convert the mouse X and Y positions to local coordinates using the "Global to Local" command in the port commands.
Before drawing to a window you must direct all drawing action to the window using the command "Set Port" in the port commands. When you first create a window the port is set to the window just created so the Set Port command will not be necessary. Windows can be drawn to even when they are not visible, a subsequent use of the command "Show window" will display the window with the contents already drawn. These few simple rules cover the handleing of the windows contents ... most other window functions are handled automatically by the system and need little or no attention.
Window Operation
After starting up and initializing Call Box BASIC load a Window entity created by the Call Box Window Editor.
10 CALL WN,O,N,"MyWindow"
Next you need to build the window which sets up the memory required by the window, this operation will not make the window visible.
12 CALL WN,1,N
 |
Note: At this point you need to draw the initial window contents as described above.
Pre-drawing the contents makes the windows contents appear quicker when the window is displayed. |
Once your window is all set-up you display it by using the Show Window command:
14 CALL WN,4,N,1
The window will now be visible on the screen and will operate automatically. Several windows can be up on the screen at one time and may overlap each other. When TaskMaster in your programs Event loop shows that a window region (refer to Figure 2.8) has had the mouse clicked in it you can run routines based on which item is clicked in or simply ignore the indication and have the system handle the operation itself by looping back to the TaskMaster command. One value returned by TaskMaster must be handled by your program and this is the close box (go away region) #22. To close your window issue a Hide Window or if you want to dispose of the window the Close window command.
16 CALL WN,4,N,0 or CALL WN,2,N
These are the minimum required window commands to operate a window. Other functions such as Get/Set origin and Set Title, add some custom functions to the repitorie of commands. There are 3 other commands that should be of value to you the programmer these are: Refresh Desktop, Duplicate a Window and Get Window Pointer/Entity number. Refresh Desktop should be issued prior to the use of windows, dialogs or menus ... this command sets up the desktop environment and redraws the whole desktop. Sometimes during an applications execution some non desktop commands such as drawing directly to the desktop will "trash" the looks of the screen. Issuing a Refresh Desktop command will straighten things out. The Duplicate a Window command will allow you to use the same window template for several window entities, this will eliminate the need to load a separate window template for each window entity. The Get Window Pointer/Entity Number command will return any of three pointers and indicators necessary for window manipulation. An example of the useof this command is when the mouse is clicked in the top-most window out of several windows visible at one time. If you wish to close this window then you need to know the entity number of this window for the Close Window command. TaskMaster will return the Windows pointer in the "D" variable. This pointer is converted to the entity number as follows:
100 CALL WN,8,N,D,2
The windows entity number is returned in the variable "N".
There are 9 commands that control windows. Windows must be used only when the desktop is active.
| COMMAND | FUNCTION | DESCRIPTION | CALL WN,O,N,"pathname" | LOAD WINDOW: | this loads a window template from disk as entity number (N). |
| CALL WN,1,N | BUILD WINDOW: | this creates the memory structure for the window (N). |
| CALL WN,2,N | CLOSE WINDOW: | this closes the window specified by (N) and releases its memory. |
| CALL WN,3 | REFRESH DESKTOP: | this redraws the entire desktop. |
| CALL WN,4,N,V | HIDE/SHOW WINDOW: | this will hide (V=O) or show (V=l) the window specified by (N). |
| CALL WN,5,N,X,Y,V | GET/SET ORIGIN: | this will get (V=O) or set (V=1) the origin (X, Y) of the windows contents. |
| CALL WN,6,N,A$ | SET TITLE: | this will change the title (A$) of the window specified by (N). |
| CALL WN,7,N1,N2 | DUPLICATE A WINDOW: | this will copy the window entity (N 1) to a new window entity (N2). |
| CALL WN,8,N,WP,V | GET WINDOW POINTER/ENTITY NUMBER: | This will return the background port pointer (V =0) or the windows port pointer (V = 1) or the entity number (V =2) of the window specified by (WP) in the variable (N). |
"pathname"
A ProDOS 8 pathname of the window template to load.
N
Entity number for this window (1-31).
V
Code number for the type of operation requested.
X
The input and output horizontal positions.
Y
The input and output vertical positions.
A$
The string used to set the windows title.
N1
The source window entity number.
N2
The destination window entity number.
WP
The window ports pointer.