Call Box Editors Manual
Version 1.0 Aug 15,1989


This code is for appending to APW/ORCA source code listings. A simple word processor can be used to edit the file, however the APW/ORCA assembler is needed to assemble the code into your application. Source code listings are easiest to hook-up to special processes, that templates might include, by allowing you to add symbolic references as required. (See Fig. 1.9)

Figure 1.9
Figure 1.9 Sample Source Code Listing

This type of code is for linking with the APW/ORCA linker. The code type ean be used by any language that uses this linker. Object code ean also be used by the loader call InitialLoad after you have changed the filetype to $B5 (LoadFile). Use the disk utilities in the CALL-BOX shell to change the filetype of this file. (See Fig. 1.10)

Figure 1.9
Figure 1.10 Sample Object Code Listing

Resources are stored in a resource fork of an extended ProDOS file. The exact filetype is not important and resources can be stored in any ProDOS file of any type.

Resources are defined with a 2 byte "type" number and a 4 byte "I.D." number. A type would be analogous to a window record, a pascal string, an icon etc ... An I.D. number would identify which pascal string or which icon you are pointing to in a group of pascal strings or icons.

The type for a window template resource is $1002. The I.D.'s can be anywhere between 0 and 7FFFFFFF.

Window template resources are in OMF2 format and are loaded using the system converter.

The source code created by this editor is a simple text file. It has a filetype of $B0 and is created in a form readily adaptable to source code listings created for APW or ORCA assemblers. You can use the filetype command in the APW/ORCA shell or the Disk Utilities function of the CALL-BOX shell to change the filetype.

Do not use periods (.) in the filename. This is commonplace in ProDOS, but periods are an illegal character in the assembler and will generate an error when assembled.

Window templates have pointers which are vital to making the window operate under your application. Two of these pointers are already installed (WinTitle and WinColor) but others must be put in before the window is opened. Each pointer contains a null ( 0 ) which tells the Window Manager to use internal default pointers which ignore the process calls. You must type in your own symbolic references where the directive and modifier: dc i4'0' exist in the template.

The pointers are:
wRefCon application use
wInfoRefCon value passed to wInfoDefProc
wFrameDefProc window frame drawing routine
wInfoDefProc Info bar drawing routine
wContDefProc contents area drawing routine

The simplest way of hooking-up a CALL-BOX generated source code file to your applications source code is to use the COPY directive.
                     (your code) 
               COPY Call-BoxWindow1 ;Your window template source file 
                     (your code) 
Another way is to use the COPY function of the APW/ORCA editor (OpenApple-C) to put a copy of you window template source code in its SYSTEMP file. It can then be inserted into your source listing with an INSERT function (OpenApple-V).

Adapting this source code for other assemblers is up to you. We will support Apple prefered format APW or ORCA only.

The object code created by the editor is a $B1 file. The file is in OMF2 format and is relocatable. The output is provided for Link-time integration or Library file use. To add an object module to a link add the filename to the link command in the APW or ORCA linker.
                LINK myprogram mywindowl mywindow2 (etc ... etc).
Where mywindowl and mywindow2 are the filenames of the object code files created with the CALL-BOX Window Editor.

This type of file can be used directly by your application similar to the way a library file is used. You must change the filetype of your object file to $B5 (Load File). The window template can then be loaded by the system loader using the InitialLoad call.
                PushWord MyID          ;Applications ID. number
                PushLong #Pathname     ;Pointer to pathname buffer
                PushWord #0            ;Spec. memo flag (set to 0)
                pla                    ;Size of buf.(N/A) 
                pla                    ;Addr of buf.(N/A) 
                PullLong WindPtr1      ;Pointer to the window template
                                       ;in memory
                pla                    ;Applications ID. number 
However you choose to use the object code template some hook-up is required for your window to properly operate in your application. Several pointers are contained in a window template that point to routines your application provides.

The pointer are:
wRefCon application use
w InfoRefCon value passed to wInfoDefProc
wFrameDefProc window frame drawing routine
wInfoDefProc Info bar drawing routine
wContDefProc contents area drawing routine

Add the following equates to your applications source code:
                _wRefCon                 equ 8 
                _wInfoRefCon             equ 44
                _wFrameDefProc           equ 50
                _wInfoDefProc            equ 54 
                _wContDefProc            equ 58
                _WinColor                equ 78
                _WinTitle                equ 86 
These equates are the offsets to pointers from the beginning of the window template. Use them to index into the window template or to hook the window up to your window procedures.

Let's hook-up a contents drawing routine to a window template ...
                PushLong WindPtr1       ;Put the windows pointer in
                PullLong $0             ;a direct page location 
                ldy #_wContDefProc      ;Load Y with the offset
                lda #DrawContRoutine    ;Get the draw rout. (lo)
                sta [$0],y              ;Put it in the template 
                iny                     ;Advance to (hi) 
                lda #DrawContRoutine+2  ;Get the draw rout. (hi)
                sta [$0],y              ;Put it in the template 
Repeat this process for each reference you wish to link in. Once the template is hooked-up you can proceed with a _NewWindow call and get on with the business of being an application.

NOTE: This process also applies to window records that are stored as resources.

USING RESOURCES All resources created by the CALL-BOX WYSIWYG editors are in OMF2 format and need to be "relocated" in memory. The Resource Manager call ResourceConverter is used to install these resources. For each resource your application is going to use you must "Log In" an appropriate OMF2 converter. To find an OMF2 converter use the Miscellaneous Tools call GetCodeResConverter. You need only make this call once.
                PushLong #0               ;Space for results
                PullLong ConverterPointer ;Pointer to OMF2 converter
This call fetches a pointer to an internal OMF2 converter routine. You now need to "Log Inll this converter for each resource type your application will be using (with the Resource Manager call ResourceConverter). This step is repeated for each type of relocatable resource your application will require.
                PushLong ConverterPointer ;OMF2 converter pointer
                PushWord #$1002           ;Window Template type
                PushWord #1               ;Log In, Applic. conv. list
                bcs MemoryError 
This sets up the resource manager to install and relocate these resources when they are called with OpenResource. You manipulate the resources from this point on. A typical sequence of events may be:

OPEN your resource file:
                PushWord #0               ;Space for results
                PushWord #0               ;Req. file access
                PushLong #0               ;Res. header address
                PushLong #PathName        ;Pointer to a class 1 pathname 
                PullWord FileID           ;Open resource file I.D. 
And LOAD it into memory:
                PushLong #0               ;Space for results
                PushWord #$1002           ;Requested Type
                PushLong #1               ;Requested I.D.
                PullLong ResourceHandle   ;Handle of resource in memory 
At this point the resource is available to your application. When you are finished using the resource you can put it away with the call CloseResourceFile:
                PushWord FileID 
Be sure to "Log Out" your resource converter when your done by issueing a "Log Out" ResourceConverter call.
                PushLong ConverterPointer ;OMF2 converter pointer
                PushWord #$1002           ;Window Template type
                PushWord #0               ;Log Out, Applic. conv. list
                bcs MemoryError 
This covers the fundamental operation of resources in your application. There are several other functions you can perform with the Resource Manager but the previously outlined procedure should suffice for most of your CALL-BOX resource usage.

CALL-BOX Window Template resources are handled similar to object files are from within your application with the exception that the Resource Manager handles the loading and saving.
Reference: Universe ToolBox Update (Ch 21:Resource Manager 3/22/89)
           Universe ToolBox Update (Ch 15:Miscellaneous Tools 3/22/89) 

The CALL-BOX BASIC Interface uses object code window templates. These templates are loaded into your Applesoft application as defined in the CALL-BOX BASIC Interface Manual. Windows under Applesoft are structured differently than in other languages and do not have the flexibility that other languages provide. While simpler to use from Applesoft, some functionality is lost.

Windows in Applesoft BASIC have two data areas. The additional area is a background pixel buffer where you do all your window drawing. This simplifies and standardizes the wContDefProc (contents drawing routine) and eliminates the need for the process to be programmed in BASIC. The wContDefProc is hard-wired as a _PProPort call which uses this buffer as the source pixel image. Whatever you do with Quickdraw II in this background pixel buffer will automatically be reflected in the windows contents region.

Info Bars are not supported for windows used from Applesoft BASIC. The procedure would be too much of a hassle to be practical.

NOTE: Info bars if supported in future releases of the CALL-BOX BASIC interface, will cause the buffer overhead to double and increase the memory needed to support the window.

Custom Frame procedures are not supported for the same reason. No plans are contemplated to support this procedure in future releases.

<- Previous | Next ->