Version 1.0 Aug 15,1989
CHAPTER 3 - THE MENU 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 the file.
The source code for a menu bar and menus indicates the different menus it contains with symbolic references, object code and resources on the other hand have a dialog template style pointer table added to the beginning of the menu template.
Figure.3.34 Sample Source Code Listing
OBJECT CODE FILETYPE $B1
This type of code is for linking with the APW/ORCA linker. This 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. 3.35)
Figure.3.35 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 in fact resources can be stored in any ProDOS file of any type.
Resources are referred to by a two 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 menu template resource is $1001. The I.D.'s can be anywhere from 0 to 7FFFFFFF.
Menu 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 $BO 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 this files filetype.
Each source code file created by this editor needs to have a filename that has no (.) peroids in it. This is commonplace in ProDOS, but peroids are an illegal character in the assembler and will generate an error when assembled.
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-Boxmenu1 ;Your menu 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 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 like APW or ORCA only on this editor.
USING OBJECT CODE
The object code created by this editor is a filetype $Bl file. This type of file is in OMF2 format and is relocatable. This form of output is provided for Linktime integration or Library file like use. To add an object module to a link add the filename to the link command in the APW or ORCA linker.
LINK myprogram mymenul mymenu2 (etc ... etc).
Where mymenul and mymenu2 are the filenames of the object code files created with the CALL BOX menu Editor.This type of file can be used directly by your application like a library file is used. You must change the filetype of your object file to $B5 (Load File) and then the menu template can 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 menu template
;In memory
pla ;Applications I.D. number
This is all that is required to install this template into your program.
Inserting the menu in the system is slightly different than usual.Menu templates have a pointer table at the beginning of them used to access the various menus they contain. _InsertMenu needs the address of the particular menu record to build the menu in the systems memory. You would usually point to a menu record and then call _InsertMenu for each menu your menu bar will contain. When this menu template is in OMF2 form you will not know where a particular menu record is at, the only thing you will know for certain is where the menu template begins. Fortunately we have added an address table at the beginning of the menu template which points to each menu in the template.
To insert this type of menu bar use the following algorithmn:
ldy#O
PushLong #TmpltAddress ;Get the tmplt addr. in z-page
PullLong $0
Again lda [$O],y ;Fetch the table address
sta ThisMenu
iny
iny
lda [$O],y
sta ThisMenu+2
ora ThisMenu ;is it null?
beq AlIDone ;if so then done inserting
phy ;Preserve the index
PushLong #ThisMenu ;Push the handle
PushWord #0 ;and the flag
_InsertMenu ;Insert this menu
ply ;Restore index
iny ;Advance to the next pointer
iny
bra Again ;Loop back
AllDone rts ;EXIT!!!
NOTE: This process applies to menu templates that are stored as resources as well.USING RESOURCES
All resources created by the CALL BOX WYSIWYG EDITORS are in OMF2 format and need to be "relocated" into memory. The Resource Manager call ResourceConverter is used to install these resources in memory. For each type of resource your application is going to use you must "Log In" an OMF2 converter for that type. 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 your application will be using with the Resource Manager call ResourceConverter.
This step would be repeated for each different type of relocatable resource your application will need.
PushLong ConverterPointer ;OMF2 converter pointer
PushWord #$1001 ;Dialog Template type
PushWord #1 ;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 OPEN, LOAD, UPDATE or whatever to 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 into memory:
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:
Push Word FileID
_CloseResourceFile
Be sure to "Log Out" your resource converter when your done by issuing a Log Out type ResourceConverter call.
PushLong ConverterPointer ;OMF2 converter pointer
PushWord #$1001 ;Menu Template type
PushWord #0 ;Log Out, Applic. conv. list
_Resource Converter
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 useage.CALL BOX menu Template resources are handled the same as object files are from within your application except that the Resource Manager handles the loading and saveing.
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 menu templates. These templates are loaded into your Applesoft application with syntax as defined in the CALL BOX BASIC Interface Manual. Menus under Applesoft need no special care and feeding.
<- Previous | Next ->