Tech Note #0: About Tutor-Tech Technical Notes
Revised by: Dave Lampert September 1990
Written by: Dave Lampert January 1989
This technical note outlines the current and revised technical
notes.
This is the first formal collection of technical notes on Tutor-Tech.
In future releases, new and revised technical notes will be included
to add to or replace existing technical notes. If there are subjects
which you would like to have discussed in a technical note or
questions or comments about existing technical notes, please contact
us at one of the following:
Mail: Techware Corporation
Developer Technical Support
Post Office Box 151085
Altamonte Springs, FL 32715-1085
Phone: (407) 695-9000
AppleLink: TECHWARE
America Online: DLampert
The following is a list of all technical notes to date.
#1: Tutor-Tech Stack File Format (versions 1.0 to 2.6)
#2: Tutor-Tech Scores File Format (versions 1.0 to 2.6)
#3: Differences Between Versions (versions 2.2 to 2.6)
#4: Tutor-Tech File Naming Conventions and Case Sensitivity
#5: Importing Double-Hires Pictures
#6: Animation Techniques
#7: Sony 1200 Videodisc Player Commands
#8: Echo Speech Synthesis and Mincing Word Dictionaries
#9: Using Tutor-Tech on AppleShare and Other Networks
#10: Creating Self-Running Stack Disks
#11: "Mac2Pic": Converting MacPaint to Apple II Single-Hires
Pictures
#12: "Portal": Converting Apple II SHR and DHR Pictures to
MacPaint
#13: Techniques for Reducing File Sizes
#14: Videodisc Stack Techniques
#15: Overlaying Video with Videodisc Player User Text
#16: Using Black & White or Color: Display Modes & Best
Results
#17: Printers and Graphics Printing Codes
#18: Custom Fonts and the Icon Editor Utility
#19: Preferences for Teacher, Student, and Grader Programs
#20: Using RAM Disks as Virtual Memory
#21: Fixing Damaged Tutor-Tech Files
#22: Old Apple IIe RGB Screens Excavated!
#23: Using VCRs with the BCD 450 and TIP on the Apple IIgs
#24: Revision A Apple IIe's and Double-Hires Graphics
Tutor-Tech Technical Notes
Tech Note #0: About Tutor-Tech Technical Notes
Revised by: Dave Lampert May 1992
Written by: Dave Lampert January 1989
This technical note outlines the current and revised technical
notes.
If there are subjects which you would like to have discussed in a
technical note or questions or comments about existing technical
notes, please contact us at one of the following:
Mail: Techware Corporation, Developer Technical Support
Post Office Box 151085
Altamonte Springs, FL 32715-1085
Phone: (407) 695-9000
AppleLink: TECHWARE
America Online: DLampert
The following is a list of all technical notes to date. New or
revised notes are marked.
#1: Tutor-Tech Stack File Format (versions 1.0 to 2.6)
#2: Tutor-Tech Scores File Format (versions 1.0 to 2.6)
#3: Differences Between Versions (versions 2.2 to 2.7)
REVISED
#4: Tutor-Tech File Naming Conventions and Case Sensitivity
#5: Importing Double-Hires Pictures
#6: Animation Techniques
#7: Sony 1200 Videodisc Player Commands
#8: Echo Speech Synthesis and Mincing Word Dictionaries
#9: Using Tutor-Tech on AppleShare and Other Networks
#10: Creating Self-Running Stack Disks
#11: "Mac2Pic": Converting MacPaint to Apple II Single-Hires
Pictures
#12: "Portal": Converting Apple II SHR and DHR Pictures to
MacPaint
#13: Techniques for Reducing File Sizes
#14: Videodisc Stack Techniques
#15: Overlaying Video with Videodisc Player User Text
#16: Using Black & White or Color: Display Modes & Best
Results
#17: Printers and Graphics Printing Codes
#18: Custom Fonts and the Icon Editor Utility
#19: Preferences for Teacher, Student, and Grader Programs
REVISED
#20: Using RAM Disks as Virtual Memory
#21: Fixing Damaged Tutor-Tech Files
#22: Old Apple IIe RGB Screens Excavated!
#23: Using VCRs with the BCD 450 and TIP on the Apple IIgs
REVISED
#24: Revision A Apple IIe's and Double-Hires Graphics
#25: XCMDs and XFCNs NEW
#26: Musical Notes NEW
#27: Keyboard Controlled Button Selection NEW
#28: Scoring Minutiae NEW
Tutor-Tech Technical Notes
Tech Note #1: Tutor-Tech Stack File Format (versions 1.0 to 2.6)
Revised by: Dave Lampert September 1990
Written by: Dave Lampert January 1989
This technical note details the file format for Tutor-Tech stack
files from version 1.0 to 2.6.
Changes since January 1989: Updated for versions
2.4, 2.5, and 2.6.
This document is updated for Tutor-Tech 2.6. All stack files are
upwardly compatible, possibly only with some minor conversion needed
on loading for version 1.x files. Files are also downward compatible
in all cases except when new features are used. For instance later
versions have imported speech balloons and transparent buttons.
What's in a Name?
Tutor-Tech stack file names may be no more than eight characters in
length. The score file names may be up to 15 characters in
length.
Tutor-Tech stack files are general binary files (file_type = $06).
The aux_type word is used to further define the ProDOS file name as
being in upper or lower case letters (similar to the method used by
AppleWorks). The aux_type word has 16 bits, 15 of which are used.
Each bit corresponds to a character position in the ProDOS file name.
If the bit is a one, the corresponding character is lower case. If
the bit is a zero, the corresponding character is upper case. The
lower case of the period (".") character is considered to be a space
(" "). The bits correspond to characters in this order:
First byte (low order) Second byte (high order)
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
ProDOS file name character position
If the file name has fewer than 15 characters, the bits corresponding
to unused character positions are set to zero. Bit 0 of the second
byte is always set to one.
For example, the file named "My File.Scores" would have a ProDOS file
name of "MY.FILE.SCORES" and an aux_type of $7D6E.
0 1 1 0 1 1 1 0 0 1 1 1 1 1 0 1
M y F i l e . S c o r e s
File Structure
Files range in size from 10 bytes (just one blank page) to 32,768
bytes. The first byte in the file is always $B0 (176 decimal). This
is a signature verifying that the file is a Tutor-Tech file.
The remainder of the file is a sequence of pages in numerically
ascending order. Tutor-Tech version 1.0 files allowed page numbers to
be defined as an 8 byte string composed of digits or spaces. During
the conversion to 2.x format, the pages are renumbered from 1
upward.
Each page begins with a page-start item (defined below) followed by
zero or more items which are on the page. The items are ordered from
the back-most layer to the front-most layer on the page. In other
words, a new item added to the page is inserted between the end of
the current page and the page-start item of the next page. The items
are identified by their header byte:
header byte item description
$B1 page-start
$B2 line
$B3 freehand
$B4 rectangle
$B5 oval
$B6 18 point wide lettering
$B7 9 point wide lettering
$B8 18 point condensed lettering
$B9 9 point condensed lettering
$BA round button
$BB field
$BC bitmap picture
$BD sound/speech balloon
$BE transparent button
The format of each item type is described below. But first let us
define some terms used in Tutor-Tech items.
item length word : a word following the header byte
of some item types, defining the total item length in bytes
(including the header byte). The first byte is low order; the second
byte is high order.
line type : a number representing one of the five
line types:
$00 = no line type
$01 =
$02 = ------------
$03 = --------
$04 = ________
pattern number : a number representing the fill
status and one of the 16 patterns or 16 colors:
$00 = no fill with black border
$01...$10 = pattern fill with black border
$80...$8F = no fill with color border
$C0...$CF = color fill with black border
position : a coordinate pair on the Tutor-Tech page
represented by three bytes. The first byte is the vertical
coordinate, ranging from 0 (the page top) to 191 (the page bottom).
The second and third bytes define the horizontal coordinate - the
number of pixels from the left side of the screen. Because the Apple
II screen is horizontally broken into 7-pixel bytes, the coordinate
is stored as a quotient (second byte) and remainder (third byte) upon
division by 7. The toolbox on the left of the screen is $0A (10
decimal) bytes wide, so the second byte ranges from $0A (the page's
left side) to $4F (the page's right side). The third byte ranges from
0 to 6.
destination : an eight byte string representing a
page number or file name to which a button or field may link. The
bytes in the string are ASCII values with bit 7 set. If the
destination is a page, the string will be the digits of the page
number, left justified, with filler spaces on the end. For example,
the destination page 123 would be the string of bytes, $B1 $B2 $B3
$A0 $A0 $A0 $A0 $A0. If the destination is a file name, the string is
the file name with filler spaces on the end. Pushing and popping
destinations simply add parentheses around the page number or use the
string "(Return)".
Now, we can define the item types.
Page-Start Item
0 header = $B1
1...7 page number string
8 page type = $A0, $AA, or $A1
This items signals the end of the previous page and the start of the
next. The page number string has the name of the page, with the
digits left justified, and the remaining bytes filled with spaces.
The bytes are ASCII values with bit 7 set. For example, the string
for page 123 would be $B1 $B2 $B3 $A0 $A0 $A0 $A0.
The last byte specifies the page type:
normal page = $A0 (a space character)
motivational page = $AA (a "*" character)
remedial page = $A1 (a "!" character)
The reason for this strange format is compatibility with Tutor-Tech
1.0 files.
Line Item
0 header = $B2
1...2 item length = $000B
3 line type
4 pattern
5...7 position 1
8...10 position 2
This item is a line drawn between two points in a specific line type
and color. This item was originally planned to store polygons, but
now it only contains two positions, and the pattern refers to the
frame, not the fill.
Freehand Item
0 header = $B3
1...2 item length = n
3 bit triplet counter
4 line type
5 pattern
6...8 starting position
9...n-1 shape table
This item is a freehand curve starting at a position and following a
shape table. The shape table is a series of bit triplets which
describe individual steps along the line. The eight possible moves
that can be recorded in each bit triplet are as follows:
0 1 2
3 4
5 6 7
There are eight bit triplets in a byte triplet (three bytes in a
row). Therefore, eight pixel steps along the line can be recorded in
three bytes. The first bit triplet is the set of bits 0 to 2 in the
first byte, and the last bit triplet is the set of bits 5 to 7 in the
last byte. Because the last byte triplet may not be completely full
with eight bit triplets, the bit triplet counter byte stores the
number of bit triplets used in the last byte triplet. This byte may
range from 0 to 7. If this byte is zero, it indicates the last byte
triplet is completely full.
If the freehand item is in color, the pixels are four times as wide,
and horizontal stepping moves four times the normal distance.
Rectangle
0 header = $B4
1 line type
2 pattern
3...5 position 1
6...8 position 2
This item is a filled or non-filled rectangle stretching between two
corner positions.
Oval
0 header = $B5
1 line type
2 pattern
3...5 position 1
6...8 position 2
This item is a filled or non-filled oval stretching between two
corners of an imaginary surrounding rectangle.
Lettering
0 header = $B6, $B7, $B8, or $B9
1...2 item length = n
3...5 position
6...n-1 text
This item is a line of text in one of four font sizes. The position
represents the bull's eye center of the leftmost character on the
line. The text is stored as ASCII with the high bit set. Some
extended ASCII characters have their high bit clear. Here is the
ASCII table:
$x0 $x1 $x2 $x3 $x4 $x5 $x6 $x7 $x8 $x9 $xA $xB $xC $xD $xE $xF
$8x a b g e f h q y l n
$9x Å s @ <> w ' Æ
$Ax space ! " # $ % & ' ( ) * + , . /
$Bx 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
$Cx @ A B C D E F G H I J K L M N O
$Dx P Q R S T U V W X Y Z [ \ ] ^ _
$Ex ` a b c d e f g h i j k l m n o
$Fx p q r s t u v w x y z { | } ~ 
$0x À Ä Ã á à â ä ã å Ç ç É é è ê ë
$1x í ì î ï Ñ ñ Ö Õ ó ò ô ö õ Ø ø Ü
$2x ú ù û ü Æ æ Ý ß
$3x '
$4x 
-
-- " " ' ' ÿ
Round Button
0 header = $BA
1 button type = 0, 1, or 2
2...4 position
5...12 destination
The round button can be a proceed button (type=0), correct button
(type=1), or incorrect button (type=2). The position represents the
center of the round button.
Field
0 header = $BB
1...2 item length = n
3...5 position
6...13 wrong destination
14...21 right destination
22...n-1 answer text
This item is a field with a key answer and two possible destinations.
The position represents the center of the square prompt. The key
answer text uses the character set defined above for the lettering
item.
Bitmap Picture
0 header = $BC
1...2 item length = n
3...5 top left position
6...8 bottom right relative position
9 status bits
10...n-1 bitmap
This item is an imported bitmap picture. The bottom right position is
relative to the top left position; in other words, it has the
dimensions of the picture. There are four bits defined in the status
byte:
bit 7 is set if the bitmap data is packed
bit 6 is set if the picture is not condensed
bit 5 is set if the picture is inversed
bit 4 is set if the picture is matted
The low four bits are always zero.
The bitmap is an array of bits defining the color of pixels. A set
bit represents black. A clear bit represents white. The bits are
grouped into seven bit bytes, with the low bit leftmost on the
screen. These bytes are grouped into lines, with the first byte
leftmost on the screen. If the picture's width is not a multiple of
seven, the remaining bits in the last byte are clear. The bitmap is a
group of these lines, with the first line topmost on the screen.
If the packing option is on (if bit 7 is set), each line in the
bitmap is packed in much the same way QuickDraw packs bitmaps on the
Macintosh. The packing method takes advantage of repeating patterns
on a fourteen pixel cycle. A packed line is composed of segments.
Each segment being either a group of unpatterned bytes or a pattern
repetition. An unpatterned segment begins with a count byte (which is
the number of bitmap bytes minus one). It is followed by the
unpatterned bytes. A pattern repetition segment is always three
bytes. The first byte is a negative number (highest bit set) which
represents the value $101 (257 decimal) minus the number of times to
repeat the pattern (which must be at least two). The second and third
bytes contain the fourteen bit pattern, seven bits in each byte. For
example, the segment "$05 $AA $55" means "repeat the bytes, $AA $55,
six times".
Sound/Speech Balloon
0 header = $BD
1...2 item length = n
3...5 top left position
6...6+c word or phrase (Pascal string)
7+c slot ASCII value
8+c...n-1 sound data
This item is an imported word or phrase from an Echo Word Dictionary.
The slot ASCII value is the character typed into the "Slot" field on
the speech import dialog box. It can be a digit "1" to "7" or "C"/"c"
for Echo Cricket/IIc. The sound data is the data read from the Echo
Word Dictionary, whose format uses the linear predictive coding.
Transparent Button
0 header = $BE
1 button type = 0, 1, or 2
2...4 top left position
5...7 bottom right position
8...15 destination
This item is just like a round button except it defines a rectangular
region which can be clicked, and the button is transparent when seen
by students.
Tutor-Tech Technical Notes
Tech Note #2: Tutor-Tech Score File Format (versions 1.0 to 2.6)
Written by: Dave Lampert September 1990
This technical note details the file format for Tutor-Tech score
files from version 1.0 to 2.6.
The format of Tutor-Tech score files has remained unchanged through
all versions 1.0 to 2.6. A score file contains up to 192 student
names along with their test scores and last page location. A score
file is paired with the stack file containing the test to be scored.
The score file name is the stack file name with the suffix ".Scores"
appended. See Tech Note #1 for the method by which upper and lower
case characters in the score file name are memorized.
The first byte of a score file is the signature byte $BF. The
remainder of the file is an array of student records, each 32 bytes
long. The format for each student record is:
0...19 student name
20...21 number of right answers
22...23 number of wrong answers
24...31 page where student left off
The student name may be up to twenty characters in length, and may
contain the name, social security number, or any other identifying
information. Extra characters not used are padded with spaces. The
text is stored as ASCII with the high bit set. Some extended ASCII
characters have their high bit clear. Refer to Tech Note #1 for the
full ASCII table.
The score is kept as two words, each with low order byte first. Every
time a scoring button is pressed or a field is answered, the score is
tallied as either right or wrong. The total number of scored
questions asked is simply the sum of these two tallies.
The last 8 bytes of each student record is used to keep the page
number where the student left off. The page number string has the
name of the page, with the digits left justified, and the remaining
bytes filled with spaces. The bytes are ASCII values with bit 7 set.
For example, the string for page 123 would be $B1 $B2 $B3 $A0 $A0 $A0
$A0 $A0. If the student has not begun the stack yet, all 8 bytes are
spaces ($A0). If the student has completed the stack (ending on a
page with no buttons or fields), then all 8 bytes are periods
($AE).
Tutor-Tech Technical Notes
Tech Note #3: Differences Between Versions (versions 2.2 to 2.6)
Written by: Dave Lampert September 1990
This technical note summarizes the differences between different
major Tutor-Tech releases.
Tutor-Tech has undergone many improvements since Tutor-Tech 1.0 made
its debut in January 1985. Listed below are just the major releases
and a summary of upgrades to the software.
Version 2.2 (released May 1988)
This is the first major release of the 2.x series. It had a formal
toolbox operating system with a much improved user interface:
improved tool selection, dialog boxes, informative error handling.
Some of the many new features included the selection tool and picture
importing. Copy protection was removed for greater flexibility. User
preferences were made available.
Version 2.3 (released August 1988)
The Samples disk was added to the package, containing clip art and
example stacks. The "Displays" stack was added to the Teacher disk to
aid in creating quality stacks. The improved selection tool featured
layer selection and multiple item selection and deselection. Larger
memory Apples with RAM disks could use the virtual memory preference
to eliminate disk swapping. The Pioneer 2000 and 4200 videodisc
players could be controlled by stacks. Echo digitized speech
synthesis was supported. Stacks could send commands or text to
printers or other slot-interface devices.
Version 2.3.2 (released November 1988)
AppleShare and other network usage improved by making student
scorekeeping files multiusable. Joystick clicking action was changed
from pressing both buttons to pressing Control-Q. Joysticks and mice
on Apple IIc's were distinguished at bootup time.
Version 2.4 (released May 1989)
Terminology was changed throughout the manual to the terms used by
HyperCard: targets became buttons; key targets became fields; lessons
became stacks. Transparent stretchable buttons were added. Stack
pages could contain many buttons and fields simultaneously. Pushing
and popping page features were added. Dialog boxes and scroll bars
looked more like their Macintosh counterparts. Clipboard features
were added. Double-hires graphics from DazzleDraw, ComputerEyes, or
ThunderScan, etc., could be imported. Several pages could be removed
with a single action. Button and field links to other stacks could be
tested while previewing. More interface cards and printers were
supported. Stacks could control Apple's Video Overlay Card along with
videodisc players. Speech and device-control features were improved.
Pioneer 2000 videodisc players could be controlled on Apple IIgs at
either fast or slow CPU speed.
Version 2.5 (released June 1989)
More Apple Video Overlay Card commands were supported to improve
overlay viewing. Joystick control on Apple IIc's was improved.
Joystick clicking action was changed to pressing only button 1 (or
pressing the Command key ( ). The Command key could be simulated by
pressing Control-"-" before a click or drag action. The screen dump
file names were changed to their Beagle graphics file names,
"Screen.Dump" and "Screen.Dump.AUX". Tutor-Tech 2.5 could boot
without needing the prefix set to its directory. Applied
Engineering's ColorLink and Digital Prism cards were supported for
RGB monitor users. Stack titles were centered in the top left area of
the screen. AppleShare worked correctly on all computers including
all Apple IIe environments. A bug which harmlessly caused picture
items to be 1 byte longer in memory was corrected. Some dialog
messages were slightly reworded.
Version 2.6 (released September 1989)
VCRs could be controlled by sending commands through the BCD 450
interface card. Tutor-Talk Tape control was added. Sunburst
Communication's Muppet Learning Keys were supported. The Echo speech
drivers no longer waited forever if Echo hardware was not connected.
Timeout error messages were added. Improved performance of the Echo
IIc. The joystick would become the active hand control at bootup time
only if it moved before the mouse did. Parts of pictures as small as
one line tall could be selected properly. The letters "m" and "w"
changed in the font set to reduce color bleeding. Linking between
stacks during previewing no longer redrew the page twice.
Version 3.0 (still under development)
This version is a complete overhaul of Tutor-Tech 2.x. Many new
features are planned, and no formal release date has been announced
yet.
Tutor-Tech Technical Notes
Tech Note #3: Differences Between Versions (versions 2.2 to 2.7)
Revised by: Dave Lampert May 1992
Written by: Dave Lampert September 1990
This technical note summarizes the differences between different
major Tutor-Tech releases. Changes since September
1990 : added 2.7.
Tutor-Tech has undergone many improvements since Tutor-Tech 1.0 made
its debut in January 1985. Listed below are just the major releases
and a summary of upgrades to the software.
Version 2.2 (released May 1988)
This is the first major release of the 2.x series. It had a formal
toolbox operating system with a much improved user interface:
improved tool selection, dialog boxes, informative error handling.
Some of the many new features included the selection tool and picture
importing. Copy protection was removed for greater flexibility. User
preferences were made available.
Version 2.3 (released August 1988)
The Samples disk was added to the package, containing clip art and
example stacks. The "Displays" stack was added to the Teacher disk to
aid in creating quality stacks. The improved selection tool featured
layer selection and multiple item selection and deselection. Larger
memory Apples with RAM disks could use the virtual memory preference
to eliminate disk swapping. The Pioneer 2000 and 4200 videodisc
players could be controlled by stacks. Echo digitized speech
synthesis was supported. Stacks could send commands or text to
printers or other slot-interface devices.
Version 2.3.2 (released November 1988)
AppleShare and other network usage improved by making student
scorekeeping files multiusable. Joystick clicking action was changed
from pressing both buttons to pressing Control-Q. Joysticks and mice
on Apple IIc's were distinguished at bootup time.
Version 2.4 (released May 1989)
Terminology was changed throughout the manual to the terms used by
HyperCard: targets became buttons; key targets became fields; lessons
became stacks. Transparent stretchable buttons were added. Stack
pages could contain many buttons and fields simultaneously. Pushing
and popping page features were added. Dialog boxes and scroll bars
looked more like their Macintosh counterparts. Clipboard features
were added. Double-hires graphics from DazzleDraw, ComputerEyes, or
ThunderScan, etc., could be imported. Several pages could be removed
with a single action. Button and field links to other stacks could be
tested while previewing. More interface cards and printers were
supported. Stacks could control Apple's Video Overlay Card along with
videodisc players. Speech and device-control features were improved.
Pioneer 2000 videodisc players could be controlled on Apple IIgs at
either fast or slow CPU speed.
Version 2.5 (released June 1989)
More Apple Video Overlay Card commands were supported to improve
overlay viewing. Joystick control on Apple IIc's was improved.
Joystick clicking action was changed to pressing only button 1 (or
pressing the Command key ( ). The Command key could be simulated by
pressing Control-"-" before a click or drag action. The screen dump
file names were changed to their Beagle graphics file names,
"Screen.Dump" and "Screen.Dump.AUX". Tutor-Tech 2.5 could boot
without needing the prefix set to its directory. Applied
Engineering's ColorLink and Digital Prism cards were supported for
RGB monitor users. Stack titles were centered in the top left area of
the screen. AppleShare worked correctly on all computers including
all Apple IIe environments. A bug which harmlessly caused picture
items to be 1 byte longer in memory was corrected. Some dialog
messages were slightly reworded.
Version 2.6 (released September 1989)
VCRs could be controlled by sending commands through the BCD 450
interface card. Tutor-Talk Tape control was added. Sunburst
Communication's Muppet Learning Keys were supported. The Echo speech
drivers no longer waited forever if Echo hardware was not connected.
Timeout error messages were added. Improved performance of the Echo
IIc. The joystick would become the active hand control at bootup time
only if it moved before the mouse did. Parts of pictures as small as
one line tall could be selected properly. The letters "m" and "w"
changed in the font set to reduce color bleeding. Linking between
stacks during previewing no longer redrew the page twice.
Version 2.7 (released May 1992)
Music generation was added. Stacks could control directories, launch
applications, and run XCMDs and XFCNs. Page referencing adds the
ability to create backgrounds, share duplicate items, or simplify
animation. I/O commands could be generalized for any slot. The FIELD
variable was added. Command-O was added as the shortcut for "Open" on
the File menu. Previewing in the Teacher program could simulate
keyboard control.
Version 3.0 (still under development)
This version is a complete overhaul of Tutor-Tech 2.x. Many new
features are planned, and no formal release date has been announced
yet.
Tutor-Tech Technical Notes
Tech Note #4: Tutor-Tech File Naming Conventions and Case
Sensitivity
Written by: Dave Lampert September 1990
This technical note discusses Tutor-Tech file names and how to avoid
cosmetic errors in your stacks.
Tutor-Tech stack file names may be no more than eight characters in
length. The score file names may be up to 15 characters in
length.
Tutor-Tech stack files are general binary files (file_type = $06).
The aux_type word is used to further define the ProDOS file name as
being in upper or lower case letters (similar to the method used by
AppleWorks). The aux_type word has 16 bits, 15 of which are used.
Each bit corresponds to a character position in the ProDOS file name.
If the bit is a one, the corresponding character is lower case. If
the bit is a zero, the corresponding character is upper case. The
lower case of the period (".") character is considered to be a space
(" "). The bits correspond to characters in this order:
First byte (low order) Second byte (high order)
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
ProDOS file name character position
If the file name has fewer than 15 characters, the bits corresponding
to unused character positions are set to zero. Bit 0 of the second
byte is always set to one.
For example, the file named "My File.Scores" would have a ProDOS file
name of "MY.FILE.SCORES" and an aux_type of $7D6E.
0 1 1 0 1 1 1 0 0 1 1 1 1 1 0 1
M y F i l e . S c o r e s
Precautions for Linking to Other Stacks
When you create a button or field that links to another stack, make
sure the destination is spelled correctly and also that the upper and
lower case usage is correct. Correct spelling is essential for
finding the file, and correct case usage is needed to be a
perfectionist. If you have a stack named "Catalog" and your button's
destination is "CATALOG", it will correctly link to the stack
"Catalog" but the upper left-hand corner of the screen will display
"CATALOG". Developers of commercial-quality stacks should avoid this,
since the stack title should always correctly identify the stack file
name right down to the upper and lower case usage.
Tutor-Tech Technical Notes
Tech Note #5: Importing Double-Hires Pictures
Written by: Dave Lampert September 1990
This technical note discusses importing from double-hires picture
files such as DazzleDraw files and Beagle graphics files, as well as
tricks for importing full-screen pictures.
Tutor-Tech 2.6 can import graphics directly from single-hires files,
DazzleDraw-type double-hires files, PrintShop and Newsroom files. You
can import graphics indirectly.
How do I import from the right half of a double-hires
picture?
When importing from double-hires pictures, only the left half of the
picture is displayed and is available for selection. This is due to
memory constraints, even when running on a large-memory Apple IIgs or
when using a virtual RAM disk. You can import graphics from the
center or right side with a little work.
The easiest way is to use DazzleDraw or your double-hires painting
program to grab the right side of the painting and move it to the
left. Resave the painting (perhaps in a temporary file, to preserve
the original full-screen painting). Then, run the Tutor-Tech Teacher
program, and import the graphics which now occupies the left half of
the painting.
If you have the picture files, but don't have access to a painting
program, you can use AppleSoft BASIC to scroll the center or right
side to the left side. To scroll the right side over to the left,
enter AppleSoft BASIC ("BASIC.SYSTEM" on your ProDOS User's Disk),
and type the following:
] BLOAD MYPAINTING,A$1FEC
] BSAVE TEMPPAINTING,A$2000,L$4000
You can substitute your own painting names for MYPAINTING and
TEMPPAINTING. The right side of the picture has moved to the left,
and the right side of the new picture is a partially scrambled left
side. To move the center half over to the left, type the
following:
] BLOAD MYPAINTING,A$1FF6
] BSAVE TEMPPAINTING,A$2000,L$4000
How do I import from Beagle graphics files?
There are two major file formats for double-hires pictures in the
Apple II world.
DazzleDraw paintings are saved as a single file with a length of
16384 bytes (a 33 block file). The first 8192 bytes of the file is
the portion of the image stored in auxiliary memory. The next 8192
bytes of the file is the portion stored in main memory. Tutor-Tech
imports this file type directly.
Beagle graphics files are saved as two separate files each with a
length of 8192 bytes (two 17 block files). For instance, a painting
saved as MYPAINTING will be stored in two files: "MYPAINTING" and
"MYPAINTING.AUX", containing the main and auxiliary memory images,
respectively. Tutor-Tech can import these two files separately, but
they appear to have periodic vertical slices chopped from them. To
import the pair of files as a double-hires image, you can use
AppleSoft BASIC to convert them to a single DazzleDraw-type file.
Enter AppleSoft BASIC ("BASIC.SYSTEM" on your ProDOS User's Disk),
and type the following (substituting your own painting names):
] BLOAD MYPAINTING,A$4000
] BLOAD MYPAINTING.AUX,A$2000
] BSAVE MYDDPAINTING,A$2000,L$4000
After converting to a DazzleDraw-type file, you may wish to scroll
the center or right side of the picture to the left before importing
in Tutor-Tech (see above).
How do I import from Tutor-Tech screen dumps?
You can save the current Tutor-Tech screen to a file on disk by
pressing Command( )-Shift-3 at any time. The cursor freezes as the
image is saved. See the Tutor-Tech User's Guide for more
information on this feature. The screen is saved on the last used
disk volume as a pair of Beagle graphics files (see format above). In
version 2.4 or earlier, the pair of files were named "Screen.OddCols"
and "Screen.EvenCols", containing the main and auxiliary memory
images, respectively. In version 2.5 and 2.6, the pair of files were
renamed "Screen.Dump" and "Screen.Dump.AUX". You can import from the
screen dump by combining these two files into a DazzleDraw-type file
as detailed above. To import from the center or right side of the
screen dump, you will need to combine the files and then also scroll
the picture (see above).
How do I import pictures wider than half a screen?
This is a difficult task, since Tutor-Tech only lets you select half
of a double-hires picture. Furthermore, Tutor-Tech reserves the
leftmost 70 pixels out of 560 for the graphical toolbox, so pictures
over 490 pixels wide will indicate the picture selection is too wide.
The only direct method is to import the left part of the image and
then import the right half of the image (cut at some memorable
position for selection consistency). The two sides can then be
reassembled with the Teacher's Selection Tool. Care must be taken to
exclude 70 pixels from among the left and right edges or the original
picture, otherwise, the two sides will not have ample room to
reassemble after importing.
A technically challenging method is to manually create a Tutor-Tech
file from a double-hires file. This may take a few dozen lines of
coding, for those familiar with assembly language. An example of this
type of trickery can be seen in the "Displays" file on the Teacher
program disk. The page with the spiral binding at the top contains a
double-hires picture (the spiral binding) which is wider than could
have been imported with existing tools. In addition, the spiral
binding is a repeated 16 pixel wide pattern, which makes this display
page more compact than it would be otherwise. This patterned picture
was specifically poked into memory, BSAVEd as a Tutor-Tech file, and
then copied into position. The complete Tutor-Tech Stack File format
is detailed in Tech Note #1.
How do I import or export Macintosh graphics?
You can convert MacPaint files to Apple II graphics files using the
"Mac2Pic" utility (see Tech Note #11). You can even capture
Tutor-Tech screen dumps and convert them over to Macintosh graphics
(see Tech Note #12). This is how Techware's graphics arts department
included Tutor-Tech images in the Tutor-Tech User's
Guide.
Tutor-Tech Technical Notes
Tech Note #6: Animation Techniques
Written by: Dave Lampert September 1990
This technical note describes tips and techniques for creating
animation sequences.
The Tutor-Tech User's Guide briefly discusses animation
basics. Animation can add pizazz to stacks and, if carefully created,
doesn't eat up bunches of memory. Here are some interesting methods
for animation we've used in some of our stacks.
Projectile Motion
If you want to animate an object so that it appears to move in a
straight line or curve without changing its own shape or form, this
is the easiest animation method. Draw the object in its first
position on the screen. Since you will be duplicating this object,
you should try to make it as memory-compact as possible, using about
a dozen or less Tutor-Tech graphics items. Imported pictures are
often too memory-consuming, unless they are under than one square
cm.
You can even animate a typed letter or letters. For instance, if you
want an arrow to fly across the screen, you should type the right
arrow with Control- -6 and the left arrow with Control- -\, rather
then importing arrow pictures from disk. Refer to Appendix A of the
Tutor-Tech User's Guide for a complete table of special
characters and their keystrokes.
Once you've drawn the object in its original location on the page,
then cover it up with a completely white box (choose the white
pattern and no line type before drawing with the filled rectangle
tool). Make the rectangle just enough to cover up the object
completely. Nothing will be visible on the page at this point. Then
choose "Select All" from the Edit menu, or select by dragging around
the covered object.
The next step is to duplicate the object with its cover-up rectangle.
Remember where the original object was (where its handles appeared),
choose duplicate, and drag the duplicated items to a location
slightly offset from the original location, in the direction of
travel. You can redrag to another location until you're satisfied
about this object second position along its trajectory. Don't drag by
a handle, since an item will stretch, and you will need to undo the
duplicated items and try again. Also, make sure the second copy
you've just made is left selected, since you will now duplicate many
times until the object moves to its final position (maybe across the
page). Tutor-Tech learns to duplicate in the same direction and
distance as the last duplication. If you deselect, it forgets this
offset, so finish your duplication before deselecting.
If the original duplication offset is too big, the object will leap
across the page in a few moves, which is poor animation. On the other
extreme, a small offset may take far too many duplications, which may
make the object move too slowly. If you are unsatisfied with the
offset direction or distance, remove all but the original object and
cover-up rectangle, and try again. The final step is to remove the
last cover-up rectangle (unless the object should disappear after the
animation). You can simply choose "Undo last" from the Edit menu to
remove this.
To make the trajectory curve during your mass-duplication, just
change the offset slightly every few duplications in the acceleration
direction.
Avoiding Animation Speeding Tickets
The Apple IIgs draws graphics up to three times as fast as the Apple
IIe does. If you design an animation sequence on the Apple IIe,
you'll be surprised by the animation speed on the Apple IIgs. Even if
you don't have an Apple IIgs, your stack may be seen by others on
Apple IIgs's. You can create your animation sequence in such a way
that it runs at the same speed on any computer.
To do this, you can borrow the timing feature of the the Video
Overlay Card driver, or any other Tutor-Tech driver. You don't need a
Video Overlay Card to use the driver, as long as you don't use other
commands on the command line besides the timing command. Refer to the
end of Appendix G in the Tutor-Tech User's Guide for
details on the " " wait command. You can include this command line
item in with the original object you draw, and duplicate it along
with the object and cover-up rectangle. Don't worry about seeing the
command text, since the students won't see it when the stack is
presented. For example, the command line " V 6" included in each
duplication will wait 6/60ths of a second for each frame of
animation.
Important: type the command line item
after you draw the object and
before you cover-up the object. If you don't draw
these in this order, use "Bring to Front" and "Send to Back" on the
Edit menu to arrange the items in this back-to-front ordering.
Tutor-Tech draws items from the backmost to the frontmost. The
animation looks the most continuous in the case where the waiting
occurs when the object is drawn but not yet covered up.
Mr. Twopence on the High-Wire
You may have seen the animation on the Tutor-Tech Samples Disk in the
"Geometry" file. The character, Mr. Twopence, is balancing on a
circus high-wire using a swaying balance pole. The swaying balance
pole has four positions in its cycle, and it cycles several times
before animation stops. Here's how it was done.
First, I drew the background of the entire page. I drew the first
balance pole position using two lines, one on each side of Mr.
Twopence. Then, I created a new page for temporary storage, and used
"Copy from Page " to copy from the page I'd drawn. I removed all
items on this temporary page except the two lines making up the
balance pole. I even removed the Mr. Twopence picture from between
the two lines. This temporary page then had only the pole's first
position, in the correct page location. Note that I didn't use the
clipboard commands "Copy" and "Paste" since they center the object on
the page when you paste it, and I wanted to keep the correct page
location also.
Next, I returned to the main page and used the selection tool to
stretch the ends of the lines to make the second position balance
pole. Just like with the first position, I created another temporary
page, copied the main page to it, and removed all but the balance
pole lines. I repeated this process for the third and fourth
positions. At this point, the main page had the complete background
and the last balance pole position, and the four temporary pages
(i.e., pages 2, 3, 4, and 5) each had one position of the balance
pole (page 5 was the last position).
I then created another temporary page as the animation assembly page,
where I could group a complete cycle of animation frames. I assembled
one animation cycle going through the four positions with the "Copy
from Page " feature. In between the animation frames, I added time
delays by drawing large no-line, white circles over to the side. This
is an old way to slow down animation; the better way is to use the "
" command described in the earlier section on animation speed. For
instance, I should have typed " V 6".
The order of assembly and the final outcome is:
Before the animation cycle begins, the main page will have the
last position (like page 5) already drawn around Mr. Twopence. The
first time page 5 is copied, it is drawn over the existing last
balance pole position, and since lines draw with an "exclusive-OR"
method, the second drawing inverts the first drawing, erasing it
effectively. I could have used cover-up rectangles, but they might
have accidentally covered up part of Mr. Twopence or the
high-wire.
Once the animation assembly page (page 6) was done, I returned to the
main page, and copied from page 6 a dozen or more times. Each time I
copied page 6, I copied another full animation loop. I previewed the
page quickly with "Preview Stack" on the Special menu to see to
complete length of animation. Each animation loop takes 0.4 second,
so a dozen loops would take almost 5 seconds. The last important
thing I almost forgot was to remove pages 2 through 6, since they
were only temporary pages. Voilà! The page was done!
Everything Moving Every-Which-Way
You may want to experiment with more complex animation, such as
moving two or more objects simultaneously. For instance, let's
consider a word fire-cracker: a moving word projectile explodes when
it gets to the center of the page, with each letter shooting in a
different direction. Sounds difficult? Not too bad for the
experienced Tutor-Tech stack-hacker!
First type the word at the bottom of the page (maybe in big letters).
Next to the big word, type a wait command, like " V 10" (preferably
in small letters for less distraction). Then, duplicate the big word
and move it directly on top of the original so it completely inverts
it (erasing both). These three text items make up an animation cycle.
Select all three, and duplicate with a slight offset toward the
center of the page (refer to the first section of this Tech
Note).
Now we're ready for the explosion! Choose "Undo last" from the Edit
menu so that the last copy of the big word is visible, and another
"Undo last" to remove the wait command. Now, you can make text items
for each letter in the big word. It's not as simple as just typing
over the big word, since that would edit the word itself. Use the
same big font and type one letter at a time at the top of the page,
and then select and drag the letter down on top of its corresponding
letter in the big word, inverting that letter. Repeat this for each
letter until the big word has disappeared completely. Then
Command-click with the selection tool to select the big word buried
under all the letter items. Refer to the Tutor-Tech User's
Guide , p. 59, for details on layered selection. When you see
the single set of four handles around the whole invisible big word
(you've selected the correct item), press Delete to chop it. The big
word now should reappear, since each letter item is no longer
inverting its corresponding letter.
Use the line tool to sketch in the path for each letter, beginning
where each letter is presently to positions at the edge of the page.
Remember the physics of fireworks? The center of gravity of all the
pieces travels along the original path upward (with a little turn
downward due to gravity). Use the lines as guidelines which you can
select and remove later. Duplicate one of the wait commands, and
stash it in an unused portion of the page. Then, one-by-one for each
letter, duplicate the letter and drag it back to sit on top of the
original so it erases it.
Now, you have the next animation cycle: each of the original letter
items, the wait command, and each of the erasing letters. The
difference this time is that after you duplicate the whole bunch
several times with the same upward offset, you will move each pair of
concentric letter items to the correct positions on its exploding
trajectory. Here's the procedure. Select all the letters items by
dragging the selection box around all of them. Be careful you don't
select any big words or wait command items below. Option-select to
also select the wait command you stashed at the bottom (it's part of
the animation cycle, too). Duplicate like you did before the big word
broke into pieces. Use approximately the same duplication offset you
used before. Keep duplicating until you hit the top of the page. If
it bounces off the top, press Delete to clear the bounced copy.
If you were to "Preview Stack" now, you'd just see the big word
smoothly move from bottom to top. This is the tedious part now. For
each letter, you need to relocate all of the letter pairs along the
old trajectory to points along the sketch lines. To complicate
things, you can't see the old letter pairs since they're inverted
twice. You can 'feel around' by selecting. Each subsequent one you
select, press Option-Command-select at the same point to also select
its twin letter under it. The handles of one item will invert out the
handles of the twin item, so the handles will be invisible also. Drag
the letter pair to the next point on the sketch lines.
This takes concentration and patience, so take the phone off the hook
before you do this. If all works out well, you'll have a tremendous
animation page. I'd like to see the great things you're doing with
animation, so please send me a copy on disk. Mail to the address
listed in Tech Note #0.
Tutor-Tech Technical Notes
Tech Note #7: Sony 1200 Videodisc Player Commands
Written by: Dave Lampert September 1990
This technical note describes the untested command set for the Sony
LDP-1200 videodisc player.
At the time of this publication, the Sony LDP-1200 videodisc player
has not been tested with Tutor-Tech. This command set is for those
developers who want to create Tutor-Tech stacks that control the Sony
1200. If you test these commands, we'd appreciate if you contact us
to report your results.
The Sony 1200 can be controlled using Tutor-Tech by sending commands
lines to the slot location where the Sony is connected. For instance,
an Apple IIe could be connected through a Super Serial Card in slot
2, or an Apple IIgs could use the built-in modem port in slot 2. In
both of these cases, commands would be sent by typing on a Tutor-Tech
page " 2 " followed by the command list. The "2" indicates slot 2.
The bullets on each side are typed by pressing the "8" key while
holding down the Option key (or the key). For more information on
command lines, refer to the Tutor-Tech User's Guide ,
Appendix G.
SEARCH U Enter a frame number (CAV discs) or a time code (CLV
discs)
i Enter a chapter number
Cn @ Search for frame/chapter/time n
sn @ Set the notify mark to frame/chapter/time
n ; useless in Tutor-Tech
Z Memorize the current videodisc position
[ Search for memorized videodisc position
STEP + Step forward one frame
, Step backward one frame
PLAY : Play forward at normal speed
; Play forward at fast (3 times) speed
< Play forward at slow (1/5 times) speed
=n @ Play forward at special (1/n times)
speed
> Scan forward at approximately 100x speed
J Play backward at normal speed
K Play backward at fast (3 times) speed
L Play backward at slow (1/5 times) speed
Mn @ Play backward at special (1/n times)
speed
N Scan backward at approximately 100x speed
? Stop playing/scanning and blank TV screen
O Stop playing/scanning and freeze frame
a Continue the previous play after stop command
B Menu: Play from beginning of program area
D:n @r @ Repeat r times
playing from current frame to n
AUDIO $ Audio off (muted)
% Audio on (may play left or right channels)
F Left channel on
G Left channel off
H Right channel on
I Right channel off
n CX noise reduction on
o CX noise reduction off
DISPLAY P Display index position on screen
Q Don't display index position on screen
& Switch video off
' Switch video on
CONTROL b Turn spindle motor on (first command sent)
c Turn spindle motor off
* Eject videodisc
( Autostop when Picture Stop Code is detected on videodisc
) Don't autostop when Picture Stop Code is detected on videodisc
t Enable Open/Close button
u Disable Open/Close button
n Wait for n /60 seconds. Type " " with
Option ( )-G.
At the time of this preliminary document, the " " (wait-until-ready)
command was not tested. For information on controlling text overlay
on the video image (Sony's User Index), refer to the Sony LDP-1200
Programmer's Reference Manual.
Tutor-Tech Technical Notes
Tech Note #8: Echo Speech Synthesis and Mincing Word Dictionaries
Revised by: Dave Lampert September 1990
Written by: Dave Lampert May 1990
This technical note describes the patch needed to import words from
the Echo 3.5" Words Disk.
Changes since May 1990: added Street's address and
formed into a tech note.
Tutor-Tech can import and speak words from the digitized dictionaries
provided with the Echo Speech Synthesizer from Street Electronics.
You can also import words from the 4000 word dictionary on a 3.5"
disk using the patch disk, "/ECHO.TABLES/". Contact us to receive
this disk free of charge. This disk only contains supplementary files
and is useless without Street Electronics' Echo 3.5" disk.
When you receive the disk, simply use a filer, such as ProDOS System
Utilities, to copy all the files from the disk "/ECHO.TABLES/" to
your work copy of the Echo 3.5" disk in the directory,
"/WORDS/DATA/".
When you're using Tutor-Tech to import words, do not select the
"TABLE" file in the top-level directory of the "/WORDS/" disk.
Instead, open the "DATA" directory and choose one the "TABLES..."
files. These tables have been alphabetically divided up to make them
smaller files. The file "TABLE.MISC" contains numbers and long
phrases.
Tutor-Tech Technical Notes
Tech Note #10: Creating Self-Running Stack Disks
Written by: Dave Lampert September 1990
This technical note describes stack disk organization and preferences
for self-running stacks.
If you are creating a set of stacks as a commercial product, or just
want your stacks to appear professional and complete, you can
organize your stacks on one or more disks and have the first disk
start automatically after booting the disk. Instead of needing to ask
the user which stack they wish to use first, you can automatically
open a welcome stack. This stack may display a professional
cover-page image, tell the user about the copyrights of this stack
package, give you credit for authoring the stacks, and let the user
click a button to move to the "Home" or "Catalog" stack. This second
stack on the disk may have small descriptive pictures and words to
graphically show the contents of the stack disk(s). Around these
pictures and words are transparent buttons linking to other stacks on
the disk. See the Tutor-Tech Demonstration Disk for a good example of
this organization. Each of the stacks should have a button the user
can click to return to the "Catalog" stack. The button should look
the same in all stacks, such as a small icon of a house ("Home") or
file cabinet (card "Catalog").
Your stack disk should contain ProDOS 8 (PRODOS), the Tutor-Tech
Student files (Toolbox.Obj, Fonts, Student.System, Student.Obj, and
Student.Prefs), and your stacks. If you will be distributing this
disk to others, whether for sale or for free, you must first obtain
distribution licensing from Apple (for ProDOS) and from Techware (for
the Student software).
To set the Startup Stack on this disk to the stack named "Welcome",
run the Tutor-Tech Teacher program, choose "Preferences ", click the
Disk button, choose and open the "Student.Prefs" file on the disk
you're creating, and then click the Read button. In the fourth text
field ("Startup Stack"), type the stack name, "Welcome". Click the
Write button and then the Done button.
If you have many stacks in this stack set, you may even create a set
with several disks. You should name or number each disk label in the
set but give each disk the same ProDOS volume name. Give the user
instructions to boot only the first disk in the set. This first disk
will be the only disk containing the ProDOS and Student program
files. These files use about 65K on the disk (just under 50% of a
5.25" disk), which is why you don't want to clutter each disk in the
set with them. Fill the remainder of the first disk and each
subsequent disk with your stacks.
If your "Catalog" stack or other stacks link to another stack on a
different disk in the set, don't link directly to that stack's name
(since the file wouldn't be found yet). Instead, link to a new page
which says "Please insert disk #5 into the disk drive, and click the
button to continue." The continue button then links to the other
stack. The button in that other stack that returns to the "Catalog"
stack should also ask the user to insert the first disk before
linking.
Another good idea is to put a copy of the "Catalog" stack on each
disk in the set so that your return buttons can link directly to the
"Catalog" stack. Each disk's "Catalog" stack displays all the stack
choices on all disks, and its buttons link to the stacks either
directly or indirectly through disk-insert message pages, depending
on which disk is currently in the drive (which version of the
"Catalog" stack is open). This eliminates the need to insert the
first disk every time just to use another stack in the set.
Tutor-Tech Technical Notes
Tech Note #11: "Mac2Pic": Converting MacPaint to Apple II
Single-Hires Pictures
Revised by: Dave Lampert September 1990
Written by: Dave Lampert January 1990
This technical note describes the "Mac2Pic" utility for picture file
conversion.
Changes since January 1990: added introduction and
formed into a tech note.
You can use Macintosh paintings and scanned images in Tutor-Tech by
first converting them over to an Apple II disk (ProDOS) and then
converting them to single-hires picture files using Techware's
"Mac2Pic" utility. Contact us to receive this disk free of charge.
Don't expect a full utility, though, since I wrote this program in
only two hours. I suggest that serious developers use one of several
commercial graphics conversion programs available which provide
greater usefulness.
Here's how to use "Mac2Pic" when you receive it:
1) Get your hands on the MacPaint picture you want to convert. Make
sure it's saved as a MacPaint file (not SuperPaint format, etc.).
Since "MAC2PIC" will only convert the top left corner of the
painting, shift or scale the picture to fit up there.
2) Use Apple File Exchange on your Macintosh to copy the file from
your Macintosh disk to an Apple II ProDOS disk.
3) Move over to your Apple II and enter Applesoft BASIC
("BASIC.SYSTEM" on your ProDOS User's Disk). Run the file "MAC2PIC"
by typing "BRUN MAC2PIC" once you've changed to its directory.
4) It will say "Type the MacPaint file name." Type the full pathname
(including prefix) for the ProDOS file you created with Apple File
Exchange.
5) It should flip into graphics, and draw the top left corner of the
MacPaint picture. If the page is all white, or part of your picture
is chopped off, go back to step 1 to rescale or shift the MacPaint
picture.
6) Press any key. It will flip back into text and show the BASIC
prompt "]". The hi-res picture is now just in memory. If you want
to save it on disk, type "BSAVE MYPIC,A$2000,L$2000" or use your own
name. If you just want to use it once to import into Tutor-Tech, you
might just want to save it in a RAM disk.
7) Run Tutor-Tech and use the Import... feature to select and paste
the picture.
Tutor-Tech Technical Notes
Tech Note #12: "Portal": Converting Apple II SHR and DHR Pictures to
MacPaint
Written by: Dave Lampert September 1990
This technical note describes the "Portal" utility for picture file
conversion.
If you want to convert Apple II pictures (single-hires or
double-hires) to MacPaint pictures, you can convert them using
Techware's "Portal" utility. Contact us to receive this utility free
of charge. Don't expect a full utility, though, since I wrote this
program in only four hours. We use it frequently here at Techware to
create PageMaker documents with Tutor-Tech screen dumps or Apple II
pictures.
Here's how to use "Portal" when you receive it:
1) Make sure you received both the Apple II 5.25" disk with "Portal"
and the target Macintosh 3.5" 400K disk containing "Big Picture".
2) Locate the Apple II picture you want to convert and rename it to
"SCREEN.PIC", or take a screen dump in Tutor-Tech (by pressing
Command( )-Shift-3 at any time (producing a Beagle graphics picture
pair). If you want to convert a DazzleDraw-type double-hires picture,
you can split it into a Beagle graphics picture pair by entering
AppleSoft BASIC ("BASIC.SYSTEM" on your ProDOS User's Disk), and
typing the following (substituting your own painting name):
] BLOAD MYDDPAINTING,A$2000
] BSAVE SCREEN.DUMP,A$4000,L$2000
] BSAVE SCREEN.DUMP.AUX,A$2000,L$2000
3) Set the prefix to the directory containing the single-hires
picture file or double-hires picture file pair. Then, run the system
file "Portal".
4) It will say "Press Return, (H)alfhite, or Escape". Place the "Big
Picture" target Macintosh 3.5" disk in a 3.5" drive connected to your
Apple II. The volume containing the Apple II picture should be online
as well. Very important: make sure there are no
other Macintosh disks or harddisks online. If so, they may be written
to accidentally, destroying the disk.
5) To convert a single-hires picture or double-hires picture to an
undistorted MacPaint file, press Return. Double-hires pictures will
convert to a MacPaint image twice as wide and twice as tall (each
pixel is doubled vertically to maintain the ascent ratio).
6) To convert a double-hires picture to a MacPaint file without
doubling each pixel, press "H". The MacPaint image will appear half
as tall as normal. If you will import the picture into another
document and want to reduce document file size by half, use this
feature and then squeeze the image to 50% vertically. For instance,
you can use MacDraw to stretch the MacPaint picture before pasting
into an application like PageMaker.
7) "Portal" will convert and write the picture to the Macintosh "Big
Picture" disk online. Then the same message will appear and wait.
Remove the Macintosh "Big Picture" disk and put it in a Macintosh
drive. Copy the "Big Picture" file off the disk, or open the file
with MacPaint and copy the image into the clipboard.
Important: do not change or save back the "Big
Picture" file, since it was manually created to be a fully unpacked
painting file. "Portal" can't convert into a file which has been
resaved.
8) When you are done, press Escape. If you have many pictures to
convert one after another, you can put each picture on a separate
disk with each disk sharing the same volume name. Then, you can
convert one after another, each time inserting the next source disk,
pressing Return or "H", and then copying the image from "Big Picture"
on the Macintosh.
Disclaimer: although this program has been used
successfully at Techware, we make no warranties it will work properly
on your Apple II. It is strongly recommended you remove all
uninvolved disks from all drives. Use this program at your own risk
(doesn't that sound menacing!).
Tutor-Tech Technical Notes
Tech Note #13: Techniques for Reducing File Sizes
Written by: Dave Lampert September 1990
This technical note discusses tips and techniques for designing
stacks compactly.
Stack which are more compact generally load, display, and save faster
than larger stacks. Tutor-Tech already makes every attempt to squeeze
the size of stacks. There are tips and techniques you can use to keep
stacks compact.
First let's start by seeing how much space each item takes in
memory:
each page uses 9 bytes plus the size of all the items it contains
each line uses 11 bytes
each freehand drawing uses 9 bytes plus 3 bytes for every 8 pixels of
line length
each rectangle or oval uses 9 bytes
each text line uses 6 bytes plus 1 byte for each character in the
text
each round button uses 13 bytes
each transparent button uses 16 bytes
each field uses 22 bytes plus 1 byte for each character in the answer
key
each picture uses 10 bytes plus the size of the picture data
each speech balloon uses 8 bytes plus the word length plus the speech
data length
As you can see, the most memory hungry items are freehand, pictures,
and speech. Pictures are packed as much as possible. Picture patterns
pack very well, but scanned images with hardly any pattern repetition
don't pack much. Speech uses Linear Predictive Coding which extremely
compresses speech down to under 1K per second. Still, these items
should be used responsibly to keep stacks compact.
For instance, if you created a stack with two dozen pages with arrow
buttons imported on each page to move to the next or previous pages,
the size of the arrow picture (55 bytes) would be multiplied by 48
for a total of 2640 bytes just for arrow buttons! Instead of using
arrow pictures, you should use the lettering tool and type the right
arrow with Control- -6 or the left arrow with Control- -\. These
would only be 7 bytes each, for a total of 336 bytes - an 87%
savings! Arrows are not the only special characters available in the
character set. Refer to Appendix A of the Tutor-Tech User's
Guide for a complete table of special characters and their
keystrokes.
Here are some other ways to reduce stack file sizes while
drawing:
You should never use the freehand tool to scribble a line to fill a
region with a pattern.
For horizontal or vertical lines, especially when numerous, use the
rectangle tool. In fact, if you set the line type to none and the
fill pattern to the one you want before drawing very short or very
thin filled rectangles, these items will take less space in memory
and even draw faster.
Don't go "Duplicate" crazy! Even though a single item may take a
small amount of memory, multiple duplication can eat up memory
fast.
You can also save space by organizing your stack pages more
efficiently. If you are creating a lesson stack which gives
motivation and remediation after quiz questions, you can create a few
generic motivation pages which are picked at random when motivation
is due. For more information on motivational pages, refer to the
section on page types in Tutor-Tech User's Guide .
If you find yourself duplicating an entire page at a time (with Copy
from Page ), there may be a more efficient way. For instance, if you
use help pages or pages which may be accessed by more than one page
in a stack, you should link to these pages by putting their page
number in parentheses. The return button on the page links back to
whichever page it came from by linking to "(Return)". This is called
pushing and popping of pages, and you can even do multiply-nested
pushing and popping. For more information, refer to the section on
buttons in Tutor-Tech User's Guide .
Tutor-Tech Technical Notes
Tech Note #14: Videodisc Stack Techniques
Written by: Dave Lampert September 1990
This technical note discusses tips and techniques for creating stacks
using videodiscs.
Creating Video Stacks for Several Videodisc Player Models
You may want to create a stack that will work on more than one model
of videodisc player. Unfortunately, the Pioneer 2000 and 4200 drivers
have different command sets, which means you'll need to create a
stack for each player type. It's not as hard as it sounds, but it
takes up twice the disk space. The best way is to create the entire
stack or set of stacks using one of the player models, and then only
when you're sure it's finish, duplicate the stack and translate the
videodisc commands. You might name the stacks "Video2000" and
"Video4200" and have a page in a main menu stack ask the user which
videodisc model they have. If they choose a 2000 or 4000 or
compatible, a button links to the "Video2000" stack. If they choose a
2200, 4200, or 8000, a button links to the "Video4200" stack.
Initializing the Videodisc Player
One of the first pages in your stack or set of stacks should
initialize the videodisc player settings. If you are supporting both
the Pioneer 2000 and 4200 model categories, then each of the two
player-specific stacks will send its corresponding initialization
codes. You type the command codes on command lines using the
Tutor-Tech text tool. Use any font size and type the line anywhere on
the page. To send command codes to a Pioneer 4200 or compatible
through a card in slot 2, for example, begin the text lines with " 2
". To send command codes to a Pioneer 2000 or compatible, begin the
text lines with " G ". The bullets on each side of the "2" or "G" are
typed by pressing the "8" key while holding down the Option key (or
the key). For more information on command lines, refer to the
Tutor-Tech User's Guide , Appendix G.
To initialize a Pioneer 2200, 4200, or 8000, send the command "SA".
This spins up the videodisc if it is present. Also, include the
commands "1VD" to enable video, "0RA" (zero-RA) to disable frame
number and user text display, and "3AD" to use stereo sound. The
command line might look like " 2 SA 1VD 0RA 3AD".
To initialize a Pioneer 2000 or compatible, send the commands "@3" to
switch video, "@6" to switch frame number display off, "@5" to turn
audio on, "T" to use stereo sound, and finally "P" to play (spinning
up the videodisc if present). The command line might look like " G
@3@6@5P".
Some videodiscs like those of Optical Data's Life Science Series have
two monaural audio tracks instead of stereo. One track is narrated in
English, the other in Spanish. With these discs, the initialization
page in your stacks can ask if the user wishes to hear English or
Spanish. The buttons on this page then link to two other pages in the
stack which set either the left or right audio. The commands for left
or right audio would be "1AD" or "2AD" (Pioneer 4200) or "L" or "R"
(Pioneer 2000), respectively.
Stacks Automatically Setting DIP Switches
If, for example, you use your Super Serial Card for communication
with the Pioneer 4200 as well as other devices like printers, and
you're fed up with changing the DIP (D ual
I nline P ackage or
D emands I mmeasurable
P atience) switches, your stacks can send command
codes to the interface card to configure them automatically.
Some of the command codes you may want to send are listed below:
The integral symbol, " ", is how a Control-I character appears on
a command line. To type this, press the "I" key while holding down
both the Control key and the Option key (or the key).
To set DIP switches on the videodisc player, you still need to do
this by hand, although you'll usually want to keep them at 4800 baud,
the fastest setting. Remember also that the videodisc player's DIP
switches are ignored until you turn the player off and back on.
Playing Movies and Knowing When to Stop
If you're using a Pioneer 4200 or compatible and want to play a movie
from, say, frame 1200 to 1799, the command you send would be "1200SE
1799PL".
For the Pioneer 2000 or compatible, it's not as easy. The command
"@0", which supposedly marks an ending frame for autostop, works only
in some cases on CAV (C onstant A
ngular V elocity) discs. To stop a movie at a
specific frame on all disc types, including CLV (C
onstant L inear V elocity) discs,
you need to search for the starting frame ("F1200S"), begin playing
("P"), wait for a certain amount of time using the " " wait command,
and finally freeze the video ("N") or completely stop the video
("Y"). The amount of time you wait is computed from the number of
frames you want to play. Each frame is 1/30th of a second, and the
wait command (" ") counts in ticks, or 1/60ths of a second. Subtract
the starting frame number from the ending frame number, double it,
and subtract about 6 to account for a slight delay of getting the
command sent. For example, to play frames 1200 to 1799, type the
command "F1200SP 1192N". Change the "6" adjustment if you find the
video stopping early or late.
Tutor-Tech Technical Notes
Tech Note #15: Overlaying Video with Videodisc Player User Text
Written by: Dave Lampert September 1990
This technical note details the commands for videodisc player
generated overlay text.
The Pioneer 2200, 4200, and 8000 videodisc players have a feature
where text can overlay the video image. This is most useful if you do
not have an Apple Video Overlay Card which permits overlaying of any
text or graphics.
Before reading on, you should be familiar with sending commands to
the videodisc player. Refer to the Tutor-Tech User's
Guide , Appendix G, Section 4. The key to understanding the
commands is that the ready command, " ", sends the player a carriage
return character and then waits for the ready signal, "R " to be
returned.
First, your stack should send the command:
The 2 indicates the interface card is in slot 2. Substitute
another slot number if different. Also, if you want the frame number,
chapter number, or both numbers to appear, substitute "5RA", "6RA",
or "7RA", respectively.
There are 8 lines of text that can be displayed, each up to 20
characters in length. Lowercase characters are changed to uppercase
letters. To define the new text "Hello there" to be displayed on line
5, for example, send the command:
The text, "HELLO THERE" should appear on the fifth line of the
user display area overlaying the video. You can continue to redefine
each line of text. If you want to clear a single line, use the
command above with no text between the two 's. If you want to clear
all lines, send the command:
For more information, refer to the Tutor-Tech User's Guide or your videodisc player's user manual.
Tutor-Tech Technical Notes
Tech Note #16: Using Black & White or Color: Display Modes &
Best Results
Written by: Dave Lampert September 1990
This technical note discusses designing stacks to look best in black
& white or color modes.
Because of limitations with the Apple II graphics mode, Tutor-Tech
graphics exhibits some color fringing - extra colors surrounding
graphics. Text, especially the smallest size, is most affected by
color fringing, even to the point of not being readable. The Apple
IIe and IIc double-hires graphics has a resolution of 560x192 black
and white pixels or 140x192 color pixels with 16 colors from which to
choose. Tutor-Tech offers drawing tools and patterns for both
monochrome (black & white) and color drawing. You can draw in
patterns or colors depending on the computer screen you plan to use
with your Apple II. Unfortunately, small text looks perfectly clear
only in monochrome viewing, so if you plan to use a color screen, use
one of the three larger sizes of fonts in your stacks.
Apple IIgs owner may be saying, "but doesn't the IIgs offer much
superior color graphics?". This is correct, but Tutor-Tech stacks are
designed to work on any Apple IIe, IIc, or IIgs. If you were to
create a stack on the Apple IIgs utilizing the better graphics, the
stack could not be viewed on Apple IIe's or IIc's. The IIgs does have
some advantages you can use. The IIgs Control Panel can control
whether the display shows color or monochrome. Your stacks can
control this option as well. If your stack has the command line, " V
T=M", the display type will change to monochrome. The command line, "
V T=C", sets the display type to color. The command line can be typed
with the text tool in any font anywhere on the page. When the page is
previewed or run by the Student program, the command line is executed
instead of being displayed.
If your stack is running on an Apple with a Composite Color Monitor,
the user can press a button on the monitor to toggle between color
and monochrome. Your stack can prompt the user to press the button
until some test graphics appear in different colors or just
monochrome.
Tutor-Tech Technical Notes
Tech Note #17: Printers and Graphics Printing Codes
Written by: Dave Lampert September 1990
This technical note discusses printer graphics codes, compatible
printer interface cards, and some patches and solutions when all else
fails.
Tutor-Tech supports 13 printer categories. Some categories like the
two Epson categories support many models of printers from several
manufacturers. If your printer is "Epson-compatible", for instance,
try selecting each Epson category on the printer list to see which
looks best.
If your printer's manual describes "graphics codes" or other printer
command codes, you can compare them with codes listed on the table
below.
Pins Page begin Line begin Line end Page end
Printer name (top-bot) codes codes codes codes
Anadex Printers bits 6-0 28 none '6' none
Apple Dot Matrix bits 0-7 Esc 'T14' Esc 'G0490' CR LF CR LF
ImageWriter I/II bits 0-8 see #1 below Esc 'G0490' CR LF CR LF
ImageWriter colorÝ bits 0-8 see #1 below CR Esc 'K' Esc
'G0490' CR LF Esc 'K0' CR LF
Citizen MSP-10 bits 7-0 see #2 below Esc '*' 4 490-256 1 CR LF CR
LF
C. Itoh 8510 bits 0-7 Esc 'T14' Esc 'S0490' CR LF CR LF
DMP 85 bits 0-7 Esc 'T14' Esc 'S0490' CR LF CR LF
Epson RX-80 bits 7-0 see #2 below Esc '*' 4 490-256 1 CR LF CR LF
Epson RX/MX/FX bits 7-0 Esc 'A' 7 Esc 'K' 490-256 1 CR LF Esc 'A' 6
CR LF
NEC 8023 bits 0-7 Esc 'T14' Esc 'S0490' CR LF CR LF
Okidata 82A/83A bits 0-7 3 none 3 14 3 2
Okidata 84 bits 7-0 Esc '%9' 14 Esc '%2' 3 490-384 CR LF CR LF
Star Gemini bits 7-0 Esc 'A' 7 Esc 'K' 490-256 1 CR LF Esc 'A' 6 CR
LF
Notes:
Ý uses a color dithering palette to produce all 16 screen
colors
a graphics code of $03 is sent twice to indicate it's not the command
code $03
Code abbreviations: Esc is ASCII 27, CR is ASCII 13, LF is ASCII 10,
is ASCII color digit
#1 (ImageWriter) Esc 'n' Esc 'T16' Esc '>' Esc 'Z' $80 0
#2 (Epson) CR Esc '@' Esc 'A' 7 Esc 'U1'
Tutor-Tech is compatible with 3 major types of printer interface
card. Tutor-Tech finds the card using the printer slot number you
typed in the "Choose Printer " dialog. The card is then identified
using identification bytes imbedded in the card's firmware at ($Cn0B)
and ($Cn0C), where "n" is the card's slot number ranging from 1 to 7.
If the bytes don't match the 3 major types, a generic serial
interface card is assumed. Here are the 3 types and the generic
type:
Interface card name ($Cn0B) ($Cn0C) Initialize / Ready condition
Print procedure
Super Serial standard card $01 $31 send Ctrl-I 'K' Ctrl-I 'Z' CR send
code to card firmware
Grappler+ (3.1) card $01 $14 ($C080+n0)=xxxxx011 store code in
($C080+n0)
Microtek (RV611E) card $FF $78 ($CnC1)=0xxxxxxx store code in
($C080+n0)
miscellaneous card if no matches n/a send code to card firmware.
Calling All Cards
If you are aware of other printers or interface cards which are not
currently supported by Tutor-Tech or you have suggestions for
improvement, please contact us so we may include changes in the next
version of Tutor-Tech. We will need to know the printer graphics
codes or interface card specifics to support the new printer or card.
If you want to send something, such as a manual, that you want
returned to you, please call us first before mailing it.
Printing from a Laser 128 or 128EX
Laser has introduced two new printers for the Laser computer: the
Laser 190A , which works like an Apple ImageWriter
I/II, and the Laser 190E , which works like the
Epson printers. If printing appears to be double-spacing or if text
and garbage graphics is printing, you may need to use the Laser's
Port Configuration. Press Control-P-Reset, or hold down the P key as
you turn on the computer. Choose the port through which you were
trying to print, either 1 or 2, and then make sure the settings are:
LF = no, WDTH = none, ZAP = no. Press Return and try printing again
with Tutor-Tech. For more information on your Laser or Port
Configuration, refer to your Laser User's Guide or
contact Laser Computer Corporation in Lake Zurich, IL at (708)
540-8086 or (708) 540-5022 for the support center.
Printing with a Tymac or Apple Parallel Card to Epsons
With some rare combinations of printers and unrecognized interface
cards, the printer may double-space graphics and print garbage text
and graphics. There is a patch disk available which sends the command
codes, "Ctrl-I H Ctrl-I K", to enable sending all 8 bits and to
disable adding extra linefeed characters. Contact us to receive this
disk free of charge.
When you receive this patch disk, copy the file "TOOLBOX.OBJ" to your
Tutor-Tech working copies (not the original disks!),
replacing the old copy of this file. Try reprinting.
Tutor-Tech Technical Notes
Tech Note #18: Custom Fonts and the Icon Editor Utility
Written by: Dave Lampert September 1990
This technical note discusses how you could create your own font for
use in Tutor-Tech.
If you are creating foreign language stacks with Tutor-Tech or want
to have special style letters, you may be interested in developing a
font containing the letters in that language. Tutor-Tech's standard
font already provides English, German, French, Spanish, Portugese,
Italian, Greek, and Scandanavian characters, as well as other symbols
for currency, science, and math. In some cases, this may still not be
enough. Rather than import images of special characters one by one
from graphics files, it's much easier to create a new font with the
characters, and then just type in the characters.
As an example, one enthusiastic user of Tutor-Tech in Chicago created
a Hebrew font for a series of stacks on Judaic tradition. Another
user in Edmonton has just begun developing a Ukrainian Cyrillic
character set for a series of stacks for Ukrainian bilingual
education.
If you are interested in developing a new font, or checking if one
was already created, contact Techware Technical Support. I can send
you the font editor disk, which will help you create a replacement
for the Tutor-Tech large font (which is used to draw large thin and
large fat letters in Tutor-Tech). Beginning with Tutor-Tech version
2.4, the large font was stored in the "FONTS" file. Before, both
small and large were in this file. The font editor disk creates the
"FONTS" file that is only compatible with versions 2.4 and later.
Tutor-Tech font files do not have the same format as Macintosh or
IIgs font files. You will need to use the utilities on our font
editor disk to create and edit the font, but this should only take a
few hours to add new letters.
If you only want to create a partial letter set (i.e., just the
uppercase letters), I suggest you create the new large font by using
the existing large font and just replace the lowercase letters "a" to
"z" with your foreign letters or special characters. This way, you
can type large letters in both English and your other letters. If you
want to create both upper and lower cases in the foreign language or
special character set, then you could substitute both "A" to "Z" and
"a" to "z", or even other characters.
Important: the "FONTS" file is expected to have 204
large characters of 36 bytes each for a total file size of 7344
bytes. You should only replace characters in the old
font set to keep 204 characters total. If you add, move, or remove
characters, there may be unexpected results.
After substituting the new letters and creating a new "FONTS" file,
copy this file over the old file on your working copies of the
Tutor-Tech Teacher or Student disks. Stacks which are opened after
booting these disks will display the new font letters. Here are brief
directions for using the font editor. If you have any questions,
please call Techware Technical Support.
1. Make a working copy of the font editor disk. Don't write protect
the working copy. The font editor is copyrighted software and may not
be otherwise copied or distributed.
2. Boot up the disk on a machine with a mouse or joystick. AppleSoft
BASIC will appear with the prompt "]" and wait for you to type a
command. Type "-editfont" to edit the new font. The editor will open.
Choose "Open..." from the "File" menu, select the file "NEWFONT" on
the disk, and choose the Open button. The font icon file containing
the 204 characters in the large font will open. Look through the
characters by pressing the up and down arrow keys. The letter will
appear true-size in the upper left, its magnification will appear on
the right, and the ASCII number for the letter will appear at the
middle left in the box. The letter "a", for example, is ASCII 97.
3. To edit a character, such as the "g" letter, move to the letter
with the up and down arrow keys, or click and type in the ASCII
number box ("g" = ASCII 103). Use the mouse to click or drag in the
magnified image of the letter "g". If you begin drawing on black, the
pen will draw white, and vice versa. To clear the letter "g" before
beginning the replacement letter, you can press "C" or choose "Clear"
from the "Icon" menu.
4. The "Icon" menu also offers "Invert" (or the "I" key) to reverse
black/white for the single letter, and "Restore" (or the "R" key) to
restore the original character before changes were made. Do not use
the "Add" or "Remove" commands. The file should continually have 204
characters in it (0 through 203).
5. After you've edited the font, save it by choosing "Save" from the
"File" menu (with the disk still in the drive). Then choose "Quit"
from the "File" menu. The font icon file "NEWFONT" will be saved. Now
it must be converted into the "FONTS" file. This file is both of the
large fonts (the fatter one is simply an expanded version of the
thinner one).
6. Boot up the disk again, and at the BASIC prompt "]", type
"-makefont". The font will automatically compile as you wait. If
errors occur, call Techware Technical Support. The file "FONTS" will
now be made. You still need to copy it to a working copy of your
Tutor-Tech Teacher or Student disk. Use your favorite disk filer to
copy the file "FONTS", replacing the old copy on the Tutor-Tech disk.
Boot up Tutor-Tech to try it.
Tutor-Tech Technical Notes
Tech Note #19: Preferences for Teacher, Student, and Grader
Programs
Written by: Dave Lampert September 1990
This technical note discusses the format and use of preference
files.
Preferences for the Teacher, Student, and Grader Programs are stored
in the three files, "Teacher.Prefs", "Student.Prefs", and
"Grader.Prefs", respectively. Each of these files is 224 ($E0) bytes
in length. The format for these preference files is:
0...31 Startup Prefix path
32...63 Exiting Prefix path
64...95 Exiting System path
96...127 Startup Stack path (Teacher or Student) or Scores File path
(Grader)
128...159 Virtual Prefix path (Teacher), Scores Prefix path
(Student), or unused (Grader)
160...175 fourth preference name
176...191 fifth preference name
192 null string count byte (always 0)
193 verification method for fourth preference
194 verification method for fifth preference
195 printer type number (1...13)
196 printer slot character ("1"..."7")
197...207 unused
208...219 unused (Teacher or Student) or grading method data
(Grader)
220...223 unused
The paths are ASCII (bit 7 clear) strings beginning with a count byte
and padded at the end with spaces (ASCII $20). The preference names
are the strings that appear in the "Preferences " dialog box beside
the fourth and fifth text fields. The verification method bytes
indicate the checking needed after typing one of the last two
preferences. A value of $00 means no checking, $80 means a prefix
path must be typed, and $C0 means a file path must be typed.
The printer type number indicates which printer is selected from the
"Choose Printer " list of 13 printers. The printer slot character is
the selected slot, with an ASCII value ranging from "1" to "7". The
default values are 3 (ImageWriter I/II) and "1" (slot 1).
In the "Grader.Prefs" file, the grading method data contains the
curving method byte ($00=none, $40=additive, $80=proportional), the
grading method byte ($00=by range, $80=by quota), the five bytes of
grade ranges (default is 94%, 86%, 78%, 70%, 0%), and the five bytes
of grade quotas from A to F (default is 5%, 20%, 50%, 20%, 5%).
You can edit these preferences files using the "Preferences " menu
feature in either the Teacher or Grader Programs. Refer to the
Tutor-Tech User's Guide for more information on
preference editing and usage. For ideas on using Startup Prefix and
Startup Stack preferences, refer to Tech Note #10. For more
information on using the Virtual Prefix preference, refer to Tech
Note #20.
Tutor-Tech Technical Notes
Tech Note #19: Preferences for Teacher, Student, and Grader
Programs
Revised by: Dave Lampert May 1992
Written by: Dave Lampert September 1990
This technical note discusses the format and use of preference files.
Changes since September 1990 : added hybrid flags
description.
Preferences for the Teacher, Student, and Grader Programs are stored
in the three files, "Teacher.Prefs", "Student.Prefs", and
"Grader.Prefs", respectively. Each of these files is 224 ($E0) bytes
in length. The format for these preference files is:
0...31 Startup Prefix path
32...63 Exiting Prefix path
64...95 Exiting System path
96...127 Startup Stack path (Teacher or Student) or Scores File path
(Grader)
128...159 Virtual Prefix path (Teacher), Scores Prefix path
(Student), or unused (Grader)
160...175 fourth preference name
176...191 fifth preference name
192 null string count byte (always 0)
193 verification method for fourth preference
194 verification method for fifth preference
195 printer type number (1...13)
196 printer slot character ("1"..."7")
197...207 unused
208...219 hybrid flags (Teacher or Student) or grading method data
(Grader)
220...223 unused
The paths are ASCII (bit 7 clear) strings beginning with a count byte
and padded at the end with spaces (ASCII $20). The preference names
are the strings that appear in the "Preferences " dialog box beside
the fourth and fifth text fields. The verification method bytes
indicate the checking needed after typing one of the last two
preferences. A value of $00 means no checking, $80 means a prefix
path must be typed, and $C0 means a file path must be typed.
The printer type number indicates which printer is selected from the
"Choose Printer " list of 13 printers. The printer slot character is
the selected slot, with an ASCII value ranging from "1" to "7". The
default values are 3 (ImageWriter I/II) and "1" (slot 1).
In the "Grader.Prefs" file, the grading method data contains the
curving method byte ($00=none, $40=additive, $80=proportional), the
grading method byte ($00=by range, $80=by quota), the five bytes of
grade ranges (default is 94%, 86%, 78%, 70%, 0%), and the five bytes
of grade quotas from A to F (default is 5%, 20%, 50%, 20%, 5%).
You can edit these preferences files using the "Preferences " menu
feature in either the Teacher or Grader Programs. Refer to the
Tutor-Tech User's Guide for more information on
preference editing and usage. For ideas on using Startup Prefix and
Startup Stack preferences, refer to Tech Note #10. For more
information on using the Virtual Prefix preference, refer to Tech
Note #20.
Hybrid Flags: Weird Wild Stuff!
Byte 208 ($D0) in the Teacher and Student preference files contains
four hybrid flags. Usually, all four are cleared. The meanings of the
four flags when set are:
bit 0 Don't erase page before drawing next page
bit 1 Don't check stack on loading for validity or conversion
bit 2 Don't look for corresponding scores file
bit 3 Kiosk: left bar is gray instead of showing Stop Hand icon
For example, if byte 208 ($D0) is $0F, all four hybrid features will
be used. All flags apply to the Student program. Only bit 0 applies
to the Teacher program, and only while previewing stacks.
To change these flags, you can either use a file byte editor,
EXERCISER.SYSTEM, or use the following BASIC commands (or likewise
for STUDENT.PREFS):
] CALL-151
* BLOAD TEACHER.PREFS,T$00,A$1000
* 10D0:0F (or other byte value)
* BSAVE TEACHER.PREFS,T$00,A$1000,L$E0
There are special design considerations for stacks which run with bit
0 hybrid status. Since the page is not erased to white before moving
to another page, you must erase the regions of the page which should
disappear. This is usually done with one or more white rectangles
with no line type. The regions that are not erased are still visible
on the screen. This saves you from putting a duplicate image on
subsequent pages and also avoids redrawing of the same image.
Many Techware commercial stacks use this hybrid feature to save
memory and create a more professional stack appearance. As an
example, Iraq Stack has a series of navigational buttons along the
bottom of the screen which are available to the user at any time
throughout the stack. The fancy "window" border and these buttons are
only drawn once when the startup disk boots. From then on, no page
erases over these regions, so they remain always visible. Though the
graphics is drawn only on this initial page, the transparent buttons
that cover the button images must be on every page. These transparent
buttons are prime candidates for page referencing. Reference pages
would only contain the transparent buttons, and no button images.
Another common need in professional-looking stacks is pop-up menus.
Again, you can use a combination of the hybrid feature and page
referencing. The result the user sees is a menu of text (or graphics)
choices, with one item highlighted.
If the highlighting method is non-intrusive to the menu image (i.e.,
a small arrow, pointing hand, or check mark beside the current
selection), then the menu image only needs to be drawn once, and each
page is simple: a page reference, the mark beside the selection for
that page, and then any contents for that menu item. The reference
refers to a page which includes a transparent button over each menu
choice, and also erases all marks beside each selection (perhaps with
one tall thin white rectangle).
After moving from page 10 to page 11, the student will see:
If the highlighting method is intrusive to the menu image (i.e., text
reverses to white on black), then the text of the menu image must be
on the reference page. Any individual page will draw a white box over
the whole menu image, draw a black box for a specific line (to be
covered later with text), refer to the reference page to draw the
menu and include buttons, and finally display any contents outside
the menu.
As you can see, great care must be taken when designing and
implementing hybrid stacks. It is important that for each page you
consider which pages may link to it, whether by an explicit link or
by a "(RETURN)" destination or even after displaying a motivational
page. Then decide if any unwanted material on any of these pages
needs to be covered up. Otherwise, you may have unesthetic bugs in
your stack. Good luck!
Tutor-Tech Technical Notes
Tech Note #20: Using RAM Disks as Virtual Memory
Written by: Dave Lampert September 1990
This technical note discusses using extra memory to boost Tutor-Tech
performance.
Tutor-Tech is designed to work with a minimum number of disk swaps.
Most of the frequently used tools and menus reside permanently in
memory; however, the Tutor-Tech Teacher must load additional code
from the Teacher Disk for the "Import ", "Speech ", and "Preview
Stack" menu features. If you have additional memory, such as the
extra memory of the Apple IIgs or a memory expansion card, you can
direct Tutor-Tech to use this memory to keep these additional code
segments. If this is the case, the Teacher program will preload this
additional code into the extra memory, and then never need to use the
original Teacher Disk again during that session. Tutor-Tech does not
use this additional memory for pictures, speech data, or stack pages.
Stacks are still limited to a maximum file size of 32K and DazzleDraw
pictures still only may import from their left half.
Apple and third-party memory expansion cards and the extended Apple
IIgs memory should be compatible with Tutor-Tech. The only
restriction is that the extra memory should behave as a RAM disk
volume accessible by ProDOS 8, and that it is not the standard
"/RAM/" volume in slot 3, drive 2. A RAM disk behaves like any other
storage volume. You can copy files to and from it, you can catalog
it, and you can even format the RAM disk. The only difference is that
all of the data is stored in memory instead of on a disk's magnetic
surface. This means that access is very fast - virtually
instantaneous.
If you have an Apple IIgs, your extra memory will automatically take
the name "/RAM5/". You can check if this is available by running the
ProDOS System Utilities and choosing List Volumes. If "/RAM5/" does
not appear on the list, use the Apple IIgs Control Panel to increase
the RAM disk size. Then reboot your Apple IIgs while holding down the
option key (Control-Command-Option-Reset). Refer to your Apple
IIgs Owner's Guide for more information on using the Control
Panel or the RAM disk.
If you have a memory expansion card, it will usually automatically
format itself as "/RAMn/", where "n" is the slot number where the
card is installed. Some cards fail to format themselves
automatically, in which case if you still intend to use them with
Tutor-Tech, format them with the ProDOS System Utilities before
running Tutor-Tech.
Some third-party memory expansion cards replace the Apple Auxiliary
Memory Card, providing the second half of the first 128K of basic
memory, plus additional memory. Tutor-Tech always deactivates the
standard RAM disk which comprises the second half of the first 128K.
This is because Tutor-Tech uses this memory directly, not under the
guise of a RAM disk. If your memory expansion card is like this (and
it behaves as though it resides in slot 3, drive 2), you cannot use
the additional memory with Tutor-Tech.
To set up the Teacher program to use the extra memory, choose
"Preferences " from the Special menu and type the name of the RAM
disk in the Virtual Prefix text field. The first character should
always be a "/", since it must be a valid ProDOS prefix. After
typing, click the Write button to save the preference on disk. The
preference will only take effect later, after you reboot
Tutor-Tech.
Tutor-Tech Technical Notes
Tech Note #21: Fixing Damaged Tutor-Tech Files
Written by: Dave Lampert September 1990
This technical note discusses repair of files which are corrupted or
partially saved on full disks.
There are two ways Tutor-Tech files can become damaged: the file
could be only partially saved on disk or the structure could become
corrupted. In most cases, the easiest way to fix the problem is to
restore a recent undamaged copy from a backup disk. If you did not
make a backup recently (for shame!!) or you want to salvage the
damaged copy, there are steps you can take.
The most frequent way files become damaged is after saving them back
to a disk without enough disk space available. When the disk becomes
full, the file is only partially saved and is not structurally sound.
Tutor-Tech will inform you that the disk is full and ask you to
resave the stack on a disk with enough space. You need to find a disk
with room on it and resave your stack before closing it.
If you try to open the partially saved copy, the error, "This is not
a Tutor-Tech stack file.", will probably appear.
To fix a partially saved stack, you need to be familiar with using
the machine language Monitor on your computer. Generally, you type
"CALL -151" in ProDOS BASIC to enter the Monitor. Refer to your
computer's owner's guide for more information on the Monitor. First,
catalog the disk with the stack to locate it and see its length in
bytes. Load the file into memory at address $4000 using the command,
"BLOAD my.stack,A$4000". Convert the file length in bytes to a
hexadecimal number and add to $4000 to get the ending address of the
file in memory. (The Apple IIgs Monitor does base conversions for you
when you type "=" before or after the number to convert). It should
be on an even $200 byte boundary, since the disk was full after a
discrete number of blocks were used.
Examine memory just before this ending address (i.e., the $80 bytes
previous). Armed with Tech Note #1 describing the stack format, look
for an item header (starting with the byte $B1 $BE). By tracing this
forward, you should find a few more items before the ending address.
The last item will not be complete, so it must be dropped from the
file. Let's say, for instance, this last item begins at $6DEF where
the ending address of the partial stack was $6E00. Subtract $4000
from the item's address to get the new file length, $2DEF. Then type
"BSAVE my.new.stack,A$4000,L$2DEF". Finally, run the Tutor-Tech
Teacher program and browse through the new salvaged stack. The last
pages and items may be missing and need to be redrawn.
Another way a stack file can become corrupted is to have its page
numbers mixed up. This has only happened in a few instances and I
have no idea how the stack becomes corrupted like this, but I do know
how to easily fix it. The tell-tale sign of this condition is that
when the stack opens, the message, "This is an old Tutor-Tech stack.
It will be converted in memory.", is reported. If you resave the
converted stack and then reopen, the same message appears. The
problem with the file is that two or more pages have the same page
number.
To fix this situation, divide the stack approximately into two
halves. For instance, if you have a stack with 15 pages, open it,
remove pages 8 to 15, and save it as "pp1..7". Open the original
again, remove pages 1 to 7, and save it as "pp8..15". Open each of
these half stacks. If one does not show the convert message, it is
'clean'. For each half that does show the message, it still contains
a duplicate page name, and you need to divide this half in half.
Reiterate this process, dividing the halves in half until all the
fragments are 'clean'. A single page stack will always be 'clean'.
Finally, reassemble the fragments using the "Add in " menu feature
for each fragment. Verify all the button and field links.
If you have stacks damaged in some other way not described above, or
you are unable to fix the stacks, you can send them in a disk mailer
to Techware at the address listed in Tech Note #0. We may be able to
fix the stacks at no charge.
Tutor-Tech Technical Notes
Tech Note #22: Old Apple IIe RGB Screens Excavated!
Written by: Dave Lampert September 1990
This technical note discusses the Tutor-Tech patch compatible with
the old Apple RGB card.
Recently on an archaeological expedition in Colorado, Dr.
François Wölfgang Bjørnopoulos unearthed a number
of Apple IIe RGB cards. Carbon dating reveals these cards were made
by Apple as recently as 1984, but then were discontinued for a yet
undetermined reason. Dr. Bjørnopoulos's discovery was even
more astounding in that these RGB cards were still in use as
interfaces between RGB screens and Apple IIe's.
A nearly disintegrated manual was also found at the site, describing
three viewing modes: Monochrome, Color, and Mixed Mode. Reports Dr.
Bjørnopoulos, "the ancient dwellers of this site would perform
poking rituals to invoke these modes."
Soon after the announcement of this discovery, scholars from
Techware's Antiquities & Mythology Department announced a new
Tutor-Tech patch that reenacted these rituals to invoke the viewing
modes. Contact this department if you wish to receive a free patch
disk.
When you receive the patch disk, there will be three files on it:
"TB.MONOCHROME", "TB.COLOR", and "TB.MIXED". Copy the desired file to
replace "TOOLBOX.OBJ" on your working copies of your Tutor-Tech
Teacher, Student, or Grader disks. Unconfirmed studies report the
"TB.MONOCHROME" displays black & white best, while "TB.MIXED"
displays color best. You may wish to conduct your own studies.
Tutor-Tech Technical Notes
Tech Note #23: Using VCRs with the BCD 450 and T.I.P. on the Apple
IIgs
Written by: Dave Lampert September 1990
This technical note discusses the Tutor-Tech patch compatible with
Micro Video Graphics' Tape Interface Port (T.I.P).
Tutor-Tech 2.6 can control many models of VCRs through the BCD 450
interface card from BCD Associates. The Apple II's CASSETTE IN port
is used to count video tape frames. Apple IIgs's do not have a
CASSETTE IN port, so in order to control VCRs from a IIgs, you need a
BCD 450 with the Tape Interface Port (T.I.P.) from Micro Video
Graphics. This chip modifies the BCD 450 to make it 'believe' that
there is a CASSETTE IN port whose value can be read in the I/O space
of the BCD 450 card's slot.
If you want to use this hardware configuration with Tutor-Tech, you
need the Tutor-Tech T.I.P. patch. Contact us to receive this patch
free of charge. We will need to know your Tutor-Tech serial number so
we may create your patch disks. The patch disks you will receive will
replace your existing Teacher and Student disks, but you should keep
the original disks anyway.
Here is information on the products mentioned:
Product Price Contact Address
BCD 450 $595.00 Bob Howard BCD Associates, Inc.
- 405-843-4574 7510 N. Broadway Ext., Suite 205
Oklahoma City, OK 73116
T.I.P. $79.95 Alvy Albert Micro Video Graphics
- 407-254-7619 or Post Office Box 1812
- 407-861-2671 Melbourne, FL 32936
Tutor-Tech free Product Support Techware Corporation
patch 1-407-695-9000 Post Office Box 151085
Altamonte Springs, FL 32715-1085
Tutor-Tech Technical Notes
Tech Note #23: Using VCRs with the BCD 450 and T.I.P. on the Apple
IIgs
Revised by: Dave Lampert May 1992
Written by: Dave Lampert September 1990
This technical note discusses the Tutor-Tech patch compatible with
Micro Video Graphics' Tape Interface Port (T.I.P). Changes
since September 1990 : addresses and products updated.
Tutor-Tech 2.6 can control many models of VCRs through the BCD 450
interface card from BCD Associates. The Apple II's CASSETTE IN port
is used to read and write video tape frames numbers. Apple IIgs's do
not have a CASSETTE IN port, so in order to control VCRs from a IIgs,
you need a BCD 450 with the Tape Interface Port (T.I.P.) from Micro
Video Graphics. This chip modifies the BCD 450 to make it 'believe'
that there is a CASSETTE IN port whose value can be read in the I/O
space of the BCD 450 card's slot.
If you want to use this hardware configuration with Tutor-Tech, you
need the Tutor-Tech T.I.P. patch. Contact us to receive this patch
free of charge. We will need to know your Tutor-Tech serial number so
we may create your patch disks. The patch disks you will receive will
replace your existing Teacher and Student disks, but you should keep
the original disks anyway.
Here is information on the products mentioned:
Product Price Contact Address
BCD 450 $595.00 Bob Howard BCD Associates, Inc.
BCD-IR $995.00 1-405-843-4574 128 N.W. 67th Street
VideoLink $1295.00 Oklahoma City, OK 73116
T.I.P. $79.95 Alvy Albert Micro Video Graphics
- 407-254-7619 or Post Office Box 1812
- 407-861-2671 Melbourne, FL 32936
Tutor-Tech free Product Support Techware Corporation
patch 1-407-695-9000 Post Office Box 151085
Altamonte Springs, FL 32715-1085
Tutor-Tech Technical Notes
Tech Note #24: Revision A Apple IIe's and Double-Hires Graphics
Written by: Dave Lampert September 1990
This technical note discusses Apple IIe requirements to run
Tutor-Tech.
Tutor-Tech displays graphics using the Apple IIe's double-hires
graphics mode (560x192). Apple IIe's require a jumper block on the
keyboard end of the 80-Column Card to allow use of the double-hires
mode. The jumper block is a small piece of plastic that fits over two
bare pins (Molex pins) extending out from the keyboard end of the
80-Column Card. If you run Tutor-Tech without the jumper block in
place, double-hires will not be properly displayed. The graphics will
appear chunky and uneven, the menus will have every second letter
removed from their titles, and the cursor will appear to move 'behind
bars'.
On Revision A Apple IIe's, the problem can't be fixed by adding the
jumper block, since these IIe's do not support double-hires at all.
Tutor-Tech will not work on Revision A Apple IIe's. Your Apple IIe's
are most likely Revision B or later, which began shipping about
mid-1983. To find out if your Apple IIe motherboard is Revision B,
look at the back of the motherboard where the part number is printed.
The part number "820-0064-B" indicates Revision B, which means the
Apple IIe will display double-hires properly.
For more detailed information, refer to Apple II Developer Technical
Support's Apple IIe Tech Note #3: Double High-Resolution
Graphics or the Apple IIe Extended 80-Column Text Card
Supplement .
Tutor-Tech Technical Notes
Tech Note #25: XCMDs and XFCNs
Written by: Dave Lampert May 1992
This technical note discusses how to program XCMDs and XFCNs.
Tutor-Tech 2.7 now offers external commands (XCMDs) and functions
(XFCNs) through the F command line. For example, the command line
will load the binary program "MYPROGRAM" into memory at address
$7200 and execute it. This can be any 6502 assembly program of file
type $06 (BIN) with an auxiliary type $7200. The maximum file size is
3K ($0C00). The command line
will simply execute the binary program currently at $7200. If no
program has been loaded, prepare for disaster.
Warning : when you are developing a stack in the Teacher
program which uses binary programs, you should save your work before
previewing (a message will warn you). You also must start previewing
so as to reload the binary program before calling it with the "&"
command. This is because the Teacher program code uses the same space
in memory. Previewing between stacks also erases the binary program
memory space, so each stack should specifically load the binary
program before using an "&" command (at least while you're
developing the stacks in the Teacher program).
You can use $7E00-$7EFF for data (this is also the item buffer). You
can freely use zero page memory from $00 to $7F. This zero page
memory may be overwritten if Toolbox routines are called. Since
auxiliary RAM is switched in $D000-$FFFF memory, don't call BASIC or
ROM routines. If your code can not fit within 3K, you can use
auxiliary memory with care. Contact us if you need help on this.
Passing Parameters
Your programs can behave as XCMDs or XFCNs. You can pass information
to the XCMD or XFCN, even using variables like the FIELD variable.
You can return values from XFCNs using the FIELD variable. The FIELD
variable is located at address $7F00 and is a Pascal string: count
byte n followed by n ASCII characters (see
table in Tech Note #1, page 5, but with opposite bit 7). The string
length should not exceed 20 characters if it is to be displayed on a
page within a text item.
Your binary program can read parameters after the "&" by looking
at the command line text item still in the Buffer ($7E00-$7EFF). The
command line is a lettering item whose format is described in Tech
Note #1, page 4. The text has already had every bit 7 reversed from
the ASCII values shown in the table. For example, the text " F &"
will appear as:
7E06: AC 46 AC 26
If your XCMD or XFCN requires one numerical parameter, for example,
do something like this:
MyProgram LDA Buffer+9
CMP #$26 ;'&' in command line
BNE Initialize ;if command line read XCMD/XFCN from disk
LDA Buffer+1 ;lettering item length
;SEC ;carry already set earlier from CMP
SBC #10 ;get length of just text past '&'
STA Buffer+9 ;it's OK to mess up Buffer, it's not saved
JSR TB ;call toolbox entry point
DB NoSpace ;this removes all spaces from string
DW Buffer+9
JSR TB ;call toolbox entry point
DB Str2Num ;this converts ASCII string to integer
DW readParam
BCS Error
LDA readParam ;low integer byte
LDX readParam+1 ;high integer byte
...
readParam DW 0 ;destination integer (0..65535)
DW Buffer+9 ;source string pointer
Toolbox calls are described further in this Tech Note.
Reading Other Items in the Stack
You can also use other items on the page as parameters or reference.
For example, you may write an XCMD that animates a picture moving
along a line or a freehand curve. You may require that the command
line " F &" be followed immediately by the picture item and then
the line or freehand item. You can read other items using the NxtItm
and GetItm routines. Pointers to these routines and three zero page
variables are accessible from the return address on the 6502 stack.
The Tutor-Tech routine which calls your binary program has the
form:
JSR $7200
RTS
DB LBlk ;stack memory block record (8 bytes)
DB ItmPtr ;current stack item ptr (word)
DB PgPtr ;current stack page ptr (word)
DW NxtItm ;procedure to identify next item
DW GetItm ;procedure to read in current item
For example, the following code gets the animation path by reading
the next item which it expects to be a line or a freehand curve. The
item is read into Buffer ($7E00) with a maximum length of $100.
ptrs EQU $10 ;zero page memory ($00-$0F used by GetItm)
getPath TSX
LDA $101,X ;low return address
STA ptrs+0
LDA $102,X ;high return address
STA ptrs+1
LDY #6
JSR callBack ;call NxtItm
BCS endOfStack
BEQ endOfPage
CMP #$B2 ;line item
BEQ readIt
CMP #$B3 ;freehand item
BNE wrongItem
readIt LDY #8
JSR callBack ;call GetItm
LDA Buffer ;item is in Buffer
CMP #$B2 ;line item
...
callBack LDA (ptrs),Y ;high address
PHA
DEY
LDA (ptrs),Y ;low address
PHA
PHP
RTI ;pop P, pop addr, jump to addr
Toolbox Calls
In addition to NxtItm and GetItm, there are eighty more routines that
comprise the Toolbox. These routines handle cursors, events,
graphics, menus, strings, memory, text editing, dialogs, filing,
printing, I/O, etc. All Toolbox calls have the following form:
JSR TB ;address is $3F5
DB CmdCode
DW CmdParams
BCS Error
The accumulator register A returns a value, usually zero if no error
occurred. The carry flag is returned as set if A>0, clear if A=0.
The Z and N flags are determined by A. The index registers X and Y
are unchanged. Since this Tech Note would easily be 50 pages if every
command, variable, and record structure were defined, the table lists
only the CmdCode, name, and a brief description. If you are
developing an XCMD or XFCN, and would find any of these routines
useful, one of our programmers will be happy to help you in detail.
Some common examples follow.
Event Manager
$02 GetCtrlr identifies current hand control
$03 MouseOff detach cursor or shut down mouse card
$04 SetPos moves cursor when no hand control present
$05 SetCur sets cursor image/mask
$06 ShowCur makes cursor visible
$07 HideCur makes cursor invisible
$08 ObscCur makes cursor invisible until cursor moves
$10 TestEvt service event handling periodically
$11 FlushEvt erase all pending events in queue
$12 GetEvt get event from queue and remove from queue
$13 EvtAvail get event from queue and leave in queue
$14 MMoved see if mouse moved since previous call
$18 Beep begin system beep
Graphics Manager
$20 ClipRect set graphics clipping rectangle
$21 ClrUpd clear update region (no more to be updated)
$22 AddUpd identify another region that needs updating
$23 GetUpd get region needing updating
$24 Pt2Rect convert point1 and point2 to rectangle
$25 Px2Rect convert two pixel coordinates to rectangle
$26 OffsetR translate a rectangle by a given vector
$27 InsetR shrink or expand a rectangle by a given vector
$28 SectR find intersection between two rectangles
$29 UnionR find union between two rectangles
$30 SetLPat set drawing line type and pattern/color
$31 PutDot draw a single pixel
$33 DrawLine draw a line
$34 SetSTHk set shape table hook (for freehand recording)
$35 DrawST draw shape table (freehand drawing)
$38 Erase draw a white rectangle
$39 Inverse invert a rectangle (black <-> white)
$3A DrawRect draw a rectangle with a line type and pattern
$3B Frame draw a 1:1 aspect ratio rectangle frame
$3C DrawOval draw an oval with a line type and pattern
$40 Push stash part of the screen on the graphics stack
$41 Pull fetch part of the screen previously stashed
$42 DrawPict draw a bitmap picture
$43 Scroll scroll part of the screen
$44 GetGStk get current graphics stack pointer
$45 SetGStk set current graphics stack pointer
$48 SetFont set current font type and leading
$49 DrawChar draw a single character
$4A DrawStr draw a string of characters (Pascal string)
$4B DrawTxt draw a string of characters (by pointers)
Menu Manager
$4C DefMenu define a menubar record
$4D DrawMenu redraw the menubar
$4E HitMenu begin interactive menu selection
Utilities
$50 CopyStr copy a Pascal string
$51 NoLTSp remove leading and trailing spaces
$52 NoSpace remove all spaces from a string
$53 Num2Str convert an integer to an ASCII string
$54 Str2Num convert an ASCII string to an integer
$55 Capital capitalize all letters in a string
$56 Search search for one string within another
$58 CopyMem copy a range of memory (in any bank)
$59 BlkAct copy, insert, delete, or cut memory
$5A BlkXHk set block extender procedure hook
Dialog Manager
$60 TxtEdit edit a line of text
$61 DrawWnd draw a window or dialog box window
$62 DrawBtn draw a rounded rectangle button
$64 DlgItem get pointer to dialog item
$65 DlgDraw draw a dialog item or all items in a record
$66 DlgRun begin interactive dialog
$67 Dialog open, draw, run, and close a dialog record
Application/Filing Service
$6C FConfig run standard preferences dialog
$6D GetPfx return current working directory
$6E CancDB run generic cancel dialog with your message
$6F LoadSeg load (and maybe call) a program segment
$71 CallMLI call a ProDOS routine
$72 SFGet run standard "open file" dialog
$73 SFLoad load a file into a memory block
$74 SFPut run standard "save file" dialog
$75 SFStore save a file from a memory block
$76 SFError handle standard ProDOS errors with dialog
$77 CheckFN verify string as valid ProDOS filename
$78 PgPrint print graphics screen using current printer
$79 Printer run dialog to choose printer and slot
$7A OutChar output character to Pascal or BASIC slot
$7B InChar input character from Pascal or BASIC slot
$7C ExitSys shut down toolbox and quit
$7D SysFail show system failure dialog
Responding to User Events
Your program can check the event queue using GetEvt or EvtAvail.
EvtAvail will leave the event still on the queue. The event will not
disappear until a GetEvt or FlushEvt call. GetEvt and EvtAvail will
read the event into an event record. If there is no event pending,
the evtCode is zero, and all event record fields are their current
values. The event record is eight bytes with the format:
evtCode byte 0 type of event
evtTicks byte 1..2 current time in ticks (sixtieths of a second)
evtPos byte 3..5 cursor position (see Tech Note #1, page 2)
evtBits byte 6 modifier keys and other flags
evtKey byte 7 ASCII of last character typed
The evtCode values for noEvent, mouseDown, mouseUp, and keyDown are
0, 1, 2, and 3, respectively. The evtKey ASCII codes are listed in
Tech Note #1, page 5, but have opposite bit 7. An example call to the
toolbox is:
JSR TB ;address is $3F5
DB GetEvt
DW Event
LDX Event+evtCode
BEQ noEvent
DEX
BEQ mouseDown
...
Event DS 8
If your program does not return in a short time (a quarter of a
second), you may want to include a TestEvt call in periodic loops, so
the event manager can check for user events and put any in the queue,
and do other tasks such as beeping and keeping time.
Calling ProDOS
Don't call the Machine Language Interface (MLI) of ProDOS directly.
The environment has the auxiliary RAM bank showing in $D000-$FFFF, so
ProDOS would swiftly bomb. Instead, call the CallMLI toolbox routine.
The CmdParams is a pointer to the param list, which is the ProDOS MLI
code byte followed by the MLI param list. For example,
JSR TB ;address is $3F5
DB CallMLI
DW GetPfx
...
GetPfx DB $C7 ;ProDOS MLI code
DB 1 ;ProDOS param count
DW DataBuf
More Information
This Tech Note was intentionally kept brief, since there's too much
to cover. If you have any questions, comments, or suggestions,
contact us at an address or phone number listed in Tech Note #0. We
will guide you in your development, send you existing XCMDs/XFCNs, or
even write the code for you.
Tutor-Tech Technical Notes
Tech Note #26: Musical Notes
Written by: Dave Lampert May 1992
This technical note discusses details of musical note
composition.
Command lines beginning with M generate music. Before reading this
Tech Note, you should already be familiar with the Tutor-Tech 2.7
User's Guide Supplement. This Tech Note describes details omitted
from the Supplement.
The following music command line will produce a scale of one
octave:
The "4" after the "C" means octave 4. The music generator is tuned
so A4 is 440 Hz (the A440 standard). The "q" means quarter note
duration. Both the "4" and "q" set defaults which are carried forward
until set again (such as by the "5" at the end). You may want to use
the defaults as variables. For instance, the following will play a
scale in any octave and duration as last set:
The "B#" is synonymous with "C" in the next octave. Since no
octave number was specified, the default octave is left
unchanged.
You can use "." and "3" after the duration to indicate dotting (150%
duration) and triplets (67% duration), respectively. You can have
several. ".." would mean 225% duration. "3." would mean 100%
duration. Likewise, flats ("b") and sharps ("#") can add up or cancel
if several are listed.
No characters in the command line are case sensitive. Even the flat
accidental "b" can be a "B". Furthermore, the delimiter between notes
is usually a space, but can be anything. The delimiter can even be
left out if the line is unambiguous (i.e., "AB" would look like A
flat). For clarity and consistency, it is suggested that the
delimiter be a space and keep all notes upper case, and the flat "b"
and all durations lower case. This also insures maximum compatibility
with HyperCard, in case your stack is converted.
There are two instruments to produce music. The default is instrument
0 (zero), called "Beep". This is simply a square wave. Instrument 1
is called "Buzz". This is composed of two slightly detuned square
waves. When two notes are played together, a square wave sum is
produced, where the mid-level amplitude is generated by a fast
resonance between the low and high speaker states at the high formant
frequency (higher than humanly audible). When buzzing or playing two
simultaneous notes or playing at a volume less than 10, the allowable
range of notes is D2 to C7. The seventh octave, although allowed, may
sound detuned, due to the limitations of frequency resolution of the
Apple II hardware.
The initial settings of the music variables are:
Your stack should not assume that these defaults are in effect.
You should explicitly set these or other settings in the beginning of
your stack.
Another detail regards staccato and held notes. In the example:
the note "C" is held while the notes and rest in parentheses are
played. If the staccato is set to 1 (the initial setting), then the
E, F, and G will play with the C for seven eighths of their quarter
note duration; the remaining eighth only plays the C by itself. The
rest note plays the C by itself for the full quarter note duration.
Therefore, the distinction between "C+E" and "C+(E)" is that in the
latter case, the C continues playing for the entire quarter note
duration.
Tutor-Tech Technical Notes
Tech Note #27: Keyboard Controlled Button Selection
Written by: Dave Lampert May 1992
This technical note discusses how buttons are selected when students
use keyboard.
When using a pointing device like a mouse or joystick, the student
directly clicks the button to activate it. Using keyboard, the
student presses arrow keys or the space bar to move between buttons
and presses Return to activate the button (jump to its destination).
The right arrow, down arrow, and space bar advance to the next
button; the left arrow and up arrow move to the previous button. All
buttons and fields are sorted on the page by their diagonal position:
top left first, bottom right last. When buttons/fields tie for
diagonal position, their absolute position in the stack is the
tie-breaker.
The rationale is that keyboard motion through buttons/fields should
not be dependent on absolute position alone (which might indicate the
correct answers to a perceptive student), and should work well when
buttons are generally vertically or horizontally oriented.
When buttons/fields are arranged around the page, not just in a line,
the motion between buttons can seem haphazard. You should always
check your stacks using keyboard control. This is now available in
the Teacher preview mode as well as in the Student program. One thing
to watch for is to have fields selected first so that typing field
answers is ready as soon as the student arrives at a page. Otherwise,
the student would need to use arrow keys to move to the field before
typing the answer. To have the field selected first, it should be
closest to the top left of the page.
Tutor-Tech Technical Notes
Tech Note #28: Scoring Minutiae
Written by: Dave Lampert May 1992
This technical note discusses the intricate mysteries of the scoring
process.
There are two methods of score recording: on disk or just in memory.
When the Tutor-Tech Student program first opens a stack (by the Book
Icon or by Startup Preferences), it checks for the existence of a
scores file with the same name suffixed by ".Scores". It looks in
either the same directory or a directory specified in the Scores
Preference.
If the scores file exists , scoring will be recorded
on disk. Scores for this stack are updated in its scores file.
Whenever a button/field jumps to another stack (chaining), Tutor-Tech
will look for that stack's corresponding scores file in which to
record scores. A message will appear if the scores file is absent or
unreadable, or if the current student is absent from the new scores
file. Upon jumping to a stack that already has student scores and a
bookmarker (the page at which the student stopped last), the old
scores and bookmarker is ignored. Instead, the student will go to the
first page of the stack, and the score will reset to zero right and
zero wrong. This has a useful application. To retake a test where a
student already completed the test, create a menu stack which links
to the test. If the student would choose the test directly from the
Book Icon, his or her name would not appear on the list from which to
select.
If the scores file does not exist , scoring will
only be recorded in memory. When jumping to other stacks, Tutor-Tech
will not even look for corresponding scores files. Only when the
student stops a stack, and chooses another using the Book Icon will
Tutor-Tech search for a scores file again.
Motivational pages should not contain scoring variables, since
correct button answers are not tallied until after the motivational
page is drawn. The RIGHT and ASKED variables will be one less than
they should be. If you want to show scores on motivational pages, use
a correct answer button on the first page of the stack as a
"Continue" button. The score will always be one more than usual,
balancing the scoring deficiency.