Call Box Editors Manual
Version 1.0 Aug 15,1989


This type of code is for appending to APW/ORCA source code listings. A simple word processor is adequate for editing ths file.

Figure 2.24
Figure 2.24 Sample Source Code Listing

This type of code is for linking with the APW/ORCA linker. The code type can be used by any language that uses this linker. Object code can 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. 2.25)

Figure 2.25
Figure 2.25 Sample Object Code Dump

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 dialog template resource is $1000. The I.D.'s can be anywhere between 0 and 7FFFFFFF.

Dialog 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.

Dialog templates have a pointer table to access the various items they contain. Under normal operation you would not access these records directly but rather with tool calls designed specifically for that purpose. Sometimes, however, you need to set default conditions that may not be set in the loaded dialog template. This is where you break the rules and access the items directly.

The process is simple: Index to the table item you want to work on and use the address found there as the address to the dialogs item. At this point you need to index to the specific piece of data and make your change.

No other special considerations need to be made to use these dialog templates.

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-BoxDialog1 ;Your dialog 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 your window template source code in its SYSTEMP file, which 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 dialog editor is a $Bl file. This type offile is in OMF2 format and is relocatable. This form of output is provided for Linktime 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 mydialog1 mydialog2 (etc ... etc).

Where mydialogl and mydialog2 are the filenames of the object code files created with the CALL-BOX Dialog 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 dialog template can then be loaded by the system loader using the InitialLoad call.
                PushWord MyID           ;Applications I.D. 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 DlogPtr1       ;Pointer to the dialog template
                                        ;In memory 
                pla                     ;Applications I.D. number
This is all that is required to install this template into your program. Use standard dialog box operating procedures as outlined in the Toolbox reference manuals.

NOTE: This process applies to dialog records that are stored as resources as well.

Resources created by the CALL-BOX WYSIWYG editors are in OMF2 format and must be "relocated" in memory. The Resource Manager call ResourceConverter is used to install the resources. For each type of resource your application is going to use you must "Log In" an 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 In" this converter for each resource type using the Resource Manager call ResourceConverter. This step is repeated for each different type of relocatable resource your application will need.
                PushLong ConverterPointer ;OMF2 converter pointer
                PushWord #$1000           ;Dialog Template type
                PushWord #                ;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 can now manipulate the resources from this point on. A typical sequence of events from this point 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
                _ OpenResourceFile
                PullWord FileID           ;Open resource file LD. 
And LOAD it:
                PushLong #0               ;Space for results
                PushWord #$1000           ;Requested Type
                PushLong #1               ;Requested I.D.
                PullLong ResourceHandle   ;Handle of resource in memory 
At this point the resource is avaliable to your application. When you are done using this resource you can put it away with the Resource Manager call CloseResourceFile:
                PushWord FileID 
Be sure to "Log Out" your resource converter when your finished by issuing a Log Out ResourceConverter call.
                PushLong ConverterPointer ;OMF2 converter pointer
                PushWord #$1000           ;Dialog 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 will suffice for most of your CALL-BOX resource usage.

CALL-BOX Dialog Template resources are handled the same as object files are in your application except 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 dialog templates. These templates are loaded into your Applesoft application as defined in the CALL-BOX BASIC Interface Manual. Dialogs under Applesoft are structured the same as if under a PI6 application and need no special care or feeding.

Direct template access as presented in USING OBJECT CODE is possible but difficult from the CALL-BOX BASIC interface. The procedure is the same but all indexing and addressing must be done with LONG PEEK and LONG POKE, calls. Fortunately these commands are capable of specifying the values in either decimal, hex, or binary and can handle WORD and LONG values.

<- Previous | Next ->