Associated Programs

From Doors CS, Doors CSE, and Doors CE Wiki
Jump to: navigation, search

You are here: Developers' SDK >> Associated Programs

The Associated Program (AP) system allows Doors CS to recognize specially-formatted programs as data files with an associated viewer program. When the user runs the data files, Doors CS recognizes them as AP files and instead launches the viewer program, giving it pointers to the data file as necessary. It also handles unarchiving the file before running the viewer and rearchives the files after the viewer closes.

The header format for an associated file contains eight bytes:

	.org datastart
	.db $BB,$6D		;required
	.db $C9			;don't let the TI-OS run this
	.db $31,$80		;this is an AP file
	.db 0,1,4		;3-byte type code (see Registered Filetypes
Start:

The header for an associated program that is a viewer for the files above:

Main Program

; Program Name: 
; Author: 
; Version: 
; Date: 
; Written for Doors CS 7.0 and higher (http://dcs.cemetech.net)

.nolist
#include "dcs7.inc"
.list
	.org progstart
	.db $BB,$6D
Init:
	xor d
	ret
	jr Start
	
	.dw $0000
	.db $07,$00
	.dw Icon
	.dw $0000
	.dw Apstart			;the routine to open files DCS will start you here instead of $9D95 if AP file pending
	.db $31,$7F			;argh, this be an APMain
	.db $02				;number of accepted filetypes
MyTypes:
	.db 0,1,4			;whatever this is
	.db 0,1,2			;DDE6 text
START:                          	;main routines
	[...]
APStart:

When a user simply runs the specified program from Doors CS, it will start at $9D95, jump to Start, and begin executing there, as usual. If a user clicks a file meant to be opened with this program, Doors CS will take care of copying the file to RAM if necessary, setting up the viewer program, and then executing it. However, execution will start at APStart instead of at $9D95. When the program begins executing at APStart, the ix register will contain a pointer to the first data byte of the AP file, ie, the first byte after the 8-byte header. The header will be at ix-8 through ix-1, and the size of the file, including the 8-byte header, will be at ix-10 (LSB) and ix-9 (MSB). The size of the data section of the AP file is of course the file size minus 8.

Within your program, you can modify the AP file as necessary, including inserting memory and deleting memory (be sure to update the size word accordingly!). Make sure you leave the header intact, and only insert or delete memory at ix or higher. When your program quits, Doors CS will writeback the file to the archive if necessary, or delete the temporary RAM copy if it is unchanged. If you call the FileOpen, FileSave, or FileSaveAs within your program, any open AP files will be closed, including removing the RAM copy and writing it back, even if the user chooses not to open a new file.

Documentation

Routines

  • FileOpen - hooks into the GUI system. Returns pointers to data.
  • FileSave - creates a new file given a name, data, and size. GUIless.
  • FileSaveAs - hooks into the GUI system. Creates a new file with specified name, data, size, and type.