Call Box BASIC
Version 2.0 15 Jan-90



The Call Box BASIC driver gives Applesoft BASIC new commands and capabilities that utilize the Apple lIgs Toolbox. These tools give you the ability to draw in either 320 or 640 mode plus make use of Icons, Cursors, Fonts, Dialogs, Menus, Windows... In fact, almost any tool Call is made possible with the Call Box BASIC Interface.

Call Box BASIC in the Launching Shell
The Call Box TPS (Toolbox Programming System) launching shell has a menu bar selection named BASIC. This menu contains selections which deal with Call Box BASIC and Applesoft.

Applesoft BASIC
This selection puts you in Applesoft BASIC and ProDOS 8. All of the usual Applesoft and ProDOS 8 functions are available here.

Call Box BASIC
This selection puts you in Call Box BASIC, ProDOS 8 and
SoDOS. Call Box BASIC is an enhanced Applesoft BASIC and SoDos is a GS/OS emulator.

Configure CB.VARS
This selection allows you to change the variable names given to the Call Box functions.

Call Box Demo
This selection runs a Demo/Tutorial on the Call Box BASIC driver. This program demonstrates by example each interface command and shows programming line examples with each demonstration.

The launching shell provides you with a convenient environment from which you can create Call Box BASIC programs. Call Box BASIC programs can be used on bootable 3.5-inch disks and can be launched from any program launcher using RAM or Hard Disk Drives.

Bootable 3.5" Call Box Program Disks
A bootable program disk can be made by inserting a blank disk in Slot 5 Drive I and then selecting FILE-FORMAT DISK from the Call Box Launching Shell. This will format the disk as volume CB.BASIC. Next select FILE-INSTALLER and run the script named INITIALIZE CB.BASIC, this will install GS/OS and all the necessary Call Box files to make-up a bootable disk. When this disk is booted it will result in running a mock STARTUP program using Call Box BASIC. Replace this program with your own program(s)... your ready to go!

Launchable Call Box Programs
Call Box BASIC programs can be launched by any program launcher capable of launching BASIC programs. Launchers that use the desktop like HyperLaunch and the Finder need no special handling but launchers that use the text screen display like ProSel will need to run the CB.PreLaunch program before running Call Box BASIC programs in order to install and initialize the desktop tools. The boot volume must contain the init file called CB.Init in any case. Your Call Box BASIC programs should be in their own subdirectory which must also contain the files CB and CB.VARS. More than one Call Box style subdirectory can exist and any kind of file can be in these subdirectorys as long as the minimum required files are present, which are CB and CB.VARS. The file CB.PreLaunch can be put anywhere.

Call Box BASIC and Desk Accessories
Classic Desk Accessories (CDA's) are always available by pressing OPEN APPLE-CONTROL-ESCAPE and 3 are supplied with the Call Box Toolbox Programming System.

Reveal:
This one will show the text screen while the Super Hi-res screen is active.

Applesoft Memory:
This one shows the current boundaries and locations in Applesoft BASIC.

Call Box Memory:
This one shows special locations and data behind the scenes in Call Box BASIC.

New Desk Accessories (NDA's)
Call Box BASIC gives you the ability to display and run desktops from Applesoft BASIC. The system menu bar in a desktop application has a (colored) Apple menu selection which contains all of the active New Desk Accessories in the :SYSTEM:DESK.ACCS subdirectory of your boot volume. Some caution must be observed with NDA's... NDA's that access disks or ones that show GS/OS or P16 system status will probably hang or crash while Call Box BASIC is active. As an
example, one of our machines has the following NDA's in it: Memory, Analog Clock, Clock, System Control and Control Panel. Everything operates except the Control Panel NDA and the STATUS function of the System Control NDA. Trial and error will sort out what will work and what will not.

Call Box BASIC Program Structure
The file CB must be run to startup the Call Box BASIC driver. This file loads into bank 0 at $2000 and then executes itself. When it is done this area is freed up and can be used by Applesoft code Many programs will be small enough to fit under this area and can run CB from within them. Larger programs should have a smaller program initialize CB and load in the entities, then run a second program (which can be ~ to 31K in length) which can subsequently RUN or CHAIN other programs... all without shutting down Call Box BASIC. VARS files can be used to pass incredible length and complexity. The loading of Entities, Fonts, Icons, Cursors, and Pictures from within any of the program segments will not interfere with even the largest of segments. The demo in the Call Box Launching Shell is a good example of this. The actual structure of the program code is really up to you... (spaghetti code* works just fine!)

Each Applesoft program segment must RESTORE CB,VARS if they are RUN, if these Applesoft segments are CHAINed then the variables are preserved from segment to segment and only an initial RESTORE CB.VARS is needed in the first segment.

Spaghetti code... Program code that is written without a plan, resulting in redundant routines, patches and entangled program flow.

BASIC Concepts
The Apple llgs has a vast memory area of which only a small portion is used for Applesoft BASIC. Applesoft does not run under ProDOS 16 or GS/OS and tools do not run under ProDOS 8... well this is not exactly true, most tools need to be installed under ProDOS 16, after that any System can use them as long as certain rules and restrictions are observed.

The Call Box BASIC driver can be thought of as a tool manager for Applesoft BASIC giving novice and advanced programmer alike the ability to use most of the advanced features of the Apple IIgs with ease. The BASIC Interface also handles memory allocation/de-allocation and organization in those areas not under the control of ProDOS 8 or Applesoft. Namely bank I and up.

The memory area above bank 0 can contain tools, desk accessories, handles, pointers, flags and various and sundry pieces of data or code that makes your lIgs what it is. There are special memory areas and ROM up there as well. You do not need to know about these things to create Call Box driven programs, but if you want more information try the Apple IIgs reference manuals published by Addison-Wesely as a starting point.

Entities
The Call Box BASIC driver has to have a way of knowing what type of data it is dealing with be it a font, icon, window, dialog or menu etc... To accomplish this task, the data is broken down into a particular type called an entity. Each entity has a kind and an I.D. associated with it. You need only use the entity I.D. when writing your programs but each kind of entity is restricted in the number of I.D's it can have so it is important to know these as well.

TypeKindI.D.Description of reserved I.D.'s
GrafPortPort0-31Port 0= SHGR screenin $E1
WindowPort

DialogPort

MenuPort

FontImage0-15Font 0 is Shaston 8
CursorImage0-15
IconImage0-63
Figure 2.1 Entity types

The Entities come in 2 kinds:

Port
A port is a special record that Quickdraw II keeps to define the drawing environment. Graphic ports are always 200 x 320 or 200 x 640 pixels in size, depending on the screen mode. Ports need graphic images drawn to them, otherwise their contents appear as a blank rectangle. Drawing takes the form of either loading in a pixel image or filetype $CI picture from disk, or drawing directly to the port using Quickdraw II commands. Ports are also Managed screen items such as Windows, Dialogs and Menus, all of these items are handled in similar ways by the toolbox managers.

Image
An image is a data segment that can reside anywhere in memory "as is" and has no absolute references. The file format for images is binary. Port entity I.D. 0 is reserved for the super hi-res screen. This allows up to 31 port entities that can be defined elsewhere in memory. Each image entity has its own set of I.D.'s (0 - is with some pre- defined, refer to Figure 2.1) so there can be 16 of each type of image entity with the exception of Icon image entities of which there can be 64 in addition to the 32 port entities already mentioned.

You do not need to worry about where the entities you will use in your program reside in memory. The Call Box BASIC driver manages this for you, however, you must specify the particular I.D. number of the entity you wish to use so the BASIC driver will know where to look as well as determine the kind of entity being dealt with.

Bank Zero Memory Use
The Call Box BASIC driver and various tools need some pages in bank zero. Normally, these pages would be dynamically allocated by the memory manager (Toolset #2). Applesoft BASIC and ProDOS 8 use most of the available memory in bank zero. The only safe and trackable area of bank zero common to both P8 and the memory manager is the area between ProDOS 8 and its buffers, see Figure 2.2. The exact address at which this allocation takes place can vary depending on how the memory is being used when the Call Box BASIC driver is initialized. If another application is using the same area, the BASIC driver will fit around it automatically. Additional memory for other tools is allocated between the already allocated pages and the ProDOS buffers. This causes the ProDOS buffers and HIMEM to move down in memory.


Figure 2.2 Direct page allocation

User Buffer
Every program needs some space to use for storing bits of data and to use as a "scratchpad" workspace. This space is located at the bank zero (this means that you can directly peek and poke it) address specified by variable UA and is as big as variable UL specifies.

When using the Long Call command (see CALL LC) you will often need to pass a pointer to a string or for a place to put a string. You would use the User Buffer for this purpose. Sometimes you need to pass a pointer to a pattern or table. You would write the pattern or table in the User Buffer and then pass the address of the buffer to the Long Call routine.

By using the User Buffer and Long Call you can operate the toolbox with a precision only found in assembly language.


Making a Call Box BASIC Desktop Application
A standard sequence of steps is used to create a desktop application, the first of which is to make a plan! This plan looks like drawings, each one being a different screen display which are linked by a logic diagram describing how the program will operate (the exact form that the plan takes is up to you, this is just my own personal conceptualization).

From this plan you use the Editors in the Call Box Launching Shell to create the entities you will be needing based on your drawings. Make sure that when you create an entity, you record any l.D. numbers associated with controls or items it may contain. You will need these for your Applesoft code.

You now would enter Call Box BASIC and start writing your program. This program will start off by starting up Call Box BASIC, RESTORING CB.VARS, HOMEing the screen and setting up the super hi-res screen and the desktop. Next you would load all of the entities you will be using in your program and start-up the system menu bar and anything else that needs to be up at startup.

After this "housekeeping" is finished you call TaskMaster (see CALL EV...) and check the results to see where or what was selected by the mouse or the keyboard. The main thing in a desktop application is to check and see if the mouse was pressed in the system menu bar, you would also check and see if the click was in the close region of the currently active window as well as other things determined by your particular program structure. If none of these things have occurred then you would loop back to the TaskMaster call. If you had a click in the system menu bar then you would run a subroutine indexed by the menu item I.D. returned to you by TaskMaster. When the subroutine was finished you would UnHilite the menu bar selection and loop back to the TaskMaster call. This type of action keeps occurring until you select the menu item that you have setup as Quit. At this point you would close any open entities, shutoff Call Box BASIC and either END or BYE the program.

The previous description is very generalized and simple... however. ..this is the fundamental structure for all or at least most desktop applications. Reference the commands Event, Window, Menu and Dialog in this manual for more exact programming examples and examine the programs on the Call Box disks (the Applesoft ones.. filetype BAS) to get an understanding of how to get one of these things up and running.

Using Call Box BASIC
The principle behind the BASIC driver is twofold: to make toolbox calls accessible to Applesoft and to make them as simple as possible to use. In order to keep things orderly, while not compromising on power and flexibility, the following method is used. To access the toolbox, you issue a CALL statement from BASIC. Some CALLs are predefined to access a particular tool function, while some allow you complete access to the entire toolsets, as long as you understand bow the toolset works.

CALLs take the form of a variable name and parameters if necessary.
For example:

100 CALL QF

This command would shutdown the BASIC interface (QF stands for Quit Function)
Whereas:

100 CALL SC,1

This command would turn on the super hi-res screen (SC for Screen) but more on commands later.

The BASIC driver is the file named CB. It is a "System" file of type $FF. You talk to the BASIC interface through the variables in the file C B. VAR S which is an Applesoft~ProDOS 8 variable file. The BASIC driver (CB) is initialized by running the file CB directly from the keyboard or from within a program:


PRINT CHR$(4) ;"-CB"

This installs the Call Box BASIC driver, allocates some memory, starts-up the Tool Locator, Memory Manager, Misc. Tools, Integer Math, Quickdraw II, Event Manager, and Quickdraw II aux. Other tools are started-up as needed using the CALL TL (tools) commands.

CB bootstraps in from address $00'2000 so if you are executing it from a program, the size of the program should be smaller than $1800 (to allow room for simple variables) or the -CB will overwrite the BASIC program. Once CB has finished executing, the entire range from $800 to HIMEM is free for Applesoft BASIC.

A usual tactic for installing CB is from within a short STARTUP program. This technique is just fine, but it should be n6ted that editing while CB is active causes several bus problems which, while not terminal, can be quite annoying - like, no more repeat key function. CB will shutdown itself automatically when a non-Applesoft error occurs but you will have to handle the CALL QF in all other circumstances.

The other half of this equation is the flle CB.VARS. Every program that uses CB needs to include the following line before any CB calls are made:

PRINT CHR$(4) ;"RESTORE CB.VARS"

This installs the variables that you need for the Call Box BASIC driver.

Many times when you are making an Applesoft program it is necessary to hit the old CONTROL-RESET and break out of some endless loop. This type of event is quite destructive to the tools and will most probably result in a bouncing apple system error message $0206... not the Applesoft cursor like you expected.

The last little hint is to be sure to issue a CALL QF before exiting to anywhere... This is analogous to putting your toys away, If you don't you will get away with it for a little while but later on when your father (GS/ OS) gets home he'll CRASH the whole system!


Error Messages
Errors are returned in text mode regardless of the display mode when the error occurred. A typical error message would look like this:

Tool not supported
Error in line ->75
]

You will be in Applesoft immediate mode and all variables will be null and the Call Box BASIC driver will be shut down.. You will have to re-initialize the Call Box BASIC driver to run your program again.

The following is a list of Call Box generated error messages... Applesoft returns its own messages and can be distinguished from Call Box error messages by their appearance. Presently, you cannot trap Call Box errors.

l/O Error
Pathname has invalid syntax
Path to files subdirectory is bad
Volume directory not found
Damaged disk
Access refused
Disk full
Disk is write protected
Font not found
Template not found
Resource not found
Out of memory (mem.mgr)
Tool not found
Bad parameter
Tool not supported
Not Dialog
Not Window
Not Menu
Entity is already assigned

Command Structure
This section describes the Call Box BASIC interface commands. These commands are arranged in alphabetical order. Before you look at the commands let's review the command syntax first.

Call Box commands are Calls to a global page address followed by parameters, separated by commas. The parameters can be of several different types as described in Figure 2.3 and the global page address are automatically installed by RESTORE-mg CB.VARS described in Figure 2.4.

A typical command line may look like this...

CALL SC,O,640 : CALL SB,O,!1OOOOOOO,O,200 : CALL SC,3,$FFFF

This line sets the screen mode to 640, sets the SCBs to use 640 mode and palette 0, and finally clears the screen to white.

CONSTANT: Decimal (0123456789)
Hex ($0123456789ABCDEF)
Binary (!01)
VARIABLE: Floating point (A.. ZZ)
Integer (A%.. ZZ%)
STRING: String ("string text")
String variable (A$.. ZZ$)
MATH EXPRESSION: Must start with a numeric value and may not contain hex or binary representations.
Figure 2.3 Legal Parameter Types

The types can be mixed in a single call without incident. The numeric limits are the same as Applesofts.

AR = Arc LN = Line P0 = Big Poke SC = Screen
AY = Super Array ME = Menu PT = Port SF = Standard File
CU = Cursor OV = Oval QF = Shutdown TL = Tool
DI = Dialog PB = Big Peek RE = Rectangle TX = Text
EV = Event PL = Palette RR = RRectangle UA = Buffer Addr.
GS = DOS PN = Pen SB = SCB's UL = Buffer length
LC = Long Call

WN = Window
Figure 2.4 CB.VARS Variable Equivalents

A command has 3 basic parts:


Figure 2.5 Command Structure

Call statement:
This is a standard Applesoft CALL statement using the variables supplied by the CB.VARS file.

Function code:
Most calls have function codes. The function code identifies the particular operation you want.

Parameters:
This is any data needed to complete the call such as color number, height, width, mode, etc. etc... All parameters are separated by commas.

Be sure to RESTORE CB.VARS the very first thing in your program to assure that the Call variables are available... changing a program line, issuing a CLEAR or a NEW will wipe out these variables.

From within an Applesoft program:

PRINT CHR$(4) ;"RESTORE CB.VARS"

or from the keyboard directly:

RESTORE CB.VARS

Observe the usual rules of good programming in Applesoft BASIC like, put frequently used subroutines at the beginning of your program, don't go overboard with REM statements and use the X = FRE(O) to clean up string storage when you are concatenating strings a lot and so on.