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 this file.

The three styles of image output are presented here using the same captured image.

Figure 4.41
Figure. 4.41 Sample Pixel Image Source Code Listing

Figure 4.42
Figure. 4.42 Sample icon source code listing

Figure 4.43
Figure. 4.43 Sample cursor source code listing

A binary filetype is the actual bytes that make up the image. These bytes can best be illustrated by Figs. 4.41,4.42 and 4.43. This filetype can be used by any language and is the most fundamental filetype in computing. Binary files need no relocation or special handling and can be loaded in the computer by standard P8, P16 or Applesoft commands.

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 refered to by a two byte "type" number and a four 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 image resources are $1003, $8001, $1004. The I.D.'s can be anywhere from 0 to 7FFFFFFF.

Image resources are in binary form and require no system converter to load to your IIgs.

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 this files filetype.

Each source code file created by this editor needs to have a filename that has no (.) periods in it. This is commonplace in ProDOS, but periods 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 CallBoxImage ;Your image 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 image 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
The binary code created by this editor is non-relocatable code and is very to install in your program. The binary image will be a separate disk file and can be loaded via P16, P8 or even Applesoft BASIC. There are no special handling considerations for binary images and a sample load might go something like this:

  • We will use GS/OS class 1 calls for this
  • Get the files length so you can allocate a spot for it
  • We will assume that you have set-up the parameter tables already
  •                 GETFILEINFOGS GETFILEBlock 
                    ldx #$24                ;Offset to the EOF 
                    lda GETFILEBlock,x 
                    sta temp                ;Save a copy of the EOF 
                    lda GETFILEBlock+2,x 
                    sta temp+2 
    ; Allocate a block to put the image in
                    PushLong #0             ;Space 
                    PushLong temp           ;Length
                    PushWord MyID          ;user I.D.
                    PushWord #0             ;Attributes (none)
                    PushLong #0             ;Location (anywhere) 
                    CopyLong ImageHandle    ;Fetch the handle 
                    PullLong $0             ;Deference it for a pointer
                    ldy #2 
                    lda [$0] 
                    sta READBlock+4         ;Put it in the READ parameter
                    lda [$O],y              ;block
                    sta READBlock+6 
    ; OPEN-READ-CLOSE the image file 
                    OPENGS OPENBlock        ;Open up the image file 
                    lda OPENRefNum          ;Pass the reference numbers
                    sta READRefNum 
                    sta CLOSERefNum
                    READGS READBlock        ;Read the file into the block
                    CLOSEGS CLOSEBlock      ;Close the file
    This will put any binary image in a legal memory block for use by your program.

    The images address can now be passed to the appropriate routine for plotting into a window or the super hi-res screen.

    Using the resource form of an image is quite similar to the binary form except that the P16 or PB calls are replaced by calls to the resource manager.

    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 #$8001        ;Requested Type (icon)
                    PushLong #1             ;Requested I.D.
                    CopyLong ResourceHandle ;Handle of resource in memory
                    PullLong $0             ;Deference it for a pointer 
                    lda [$0] 
                    sta ResourcePointer
                    lda [$O],y 
                    sta ResourcePointer+2 
    At this point the resource is available to your application. When you are done using this resource you can put it away with the Resource Manager call CloseResourceFile:
                    PushWord FileID 
    The images address can now be passed to the appropriate routine for plotting into a window or the super hi-res screen.

    The CALL BOX BASIC Interface uses binary code images. These images are loaded into your Applesoft application with syntax as defined in the CALL BOX BASIC Interface Manual. Images under Applesoft need no special care and feeding.

    <- Previous