Version 1.0 Aug 15,1989
CHAPTER 2 - THE DIALOG EDITOR (Continued)
SOURCE CODE FILETYPE $B0
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 Sample Source Code Listing
OBJECT CODE FILETYPE $B1
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 Sample Object Code Dump
RESOURCE FILETYPE (any)
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.
USING SOURCE CODE
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.
USING OBJECT CODE
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)
_InitialLoad
pla ;Size of Dir.pg/Stack buf.(N/A)
pla ;Addr of Dir.pg/Stack 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.
USING RESOURCES
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
_GetCodeResConverter
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
_ResourceConverter
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.
_LoadResource
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
_CloseResourceFile
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
_ResourceConverter
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)
BASIC CONSIDERATIONS
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 ->