TimeOut Edit BASIC - For AppleWorks 5.1

A. TimeOut Edit BASIC - What is It?

TimeOut Edit BASIC is a 21st century addition to the family of TimeOut Applications for use with AppleWorks 5.1 on the Apple II series of computers.

Considering that former Beagle Bro Alan Bird invented the TimeOut engine for AppleWorks, and also wrote arguably the best stand-alone BASIC program editor, Program Writer, it is surprising that a TimeOut Application of this nature wasn't released years ago. But, as far as I can determine, it wasn't.

Quite simply put, the purpose of TimeOut Edit BASIC is to allow users to load, view and edit Applesoft BASIC programs directly from within AppleWorks 5.1. Configuration options include displaying control characters in inverse and indenting long lines.

BASIC Loaded to AppleWorks Word Processor

TimeOut Edit BASIC 5.4 - (TO.EDITBASIC54) - March, 2019

Unlike other methods of editing BASIC programs in a text editor, TimeOut Edit BASIC does NOT require that a user first convert a BASIC program to a text file before loading it into AppleWorks for viewing or editing.

Such methods, of course, typically require that one add additional statements at the beginning of the loaded BASIC program that will OPEN a text file, WRITE to it, LIST the program, and then CLOSE the text file.

Then, a text editor must be launched to load the text file just written. This can be time consuming and is generally very inconvenient, particularly if all you want to do is view and examine a BASIC program within a scrolling full-screen window.

B. What are AppleWorks TimeOuts?

Conceived by Alan Bird, and somewhat analogous to desktop accessories on the Apple IIGS, TimeOuts are machine language applications that run from within AppleWorks when they are selected and summoned by the user from the TimeOut menu. This menu appears anytime the user enters the special command sequence <OA-ESC>.

As a result, the underlying AppleWorks processes that were running prior to selecting a TimeOut application are suspended and TimeOut is given temporary control. More importantly, the application benefits greatly by having access to the wide range of powerful internal AppleWorks routines, including the innovative AppleWorks memory manager.

TimeOut applications can work to enhance the suspended activity, (e.g. add thesaurus word substitution to an open word processor file) or they can perform a function completely unrelated to that which was suspended (e.g. provide an on-screen calculator).

To be correct, there are actually two different types of TimeOut applications -- (i) traditional TimeOuts and (ii) compiled macro TimeOuts.

The latter type, consisting of a compiled set of UltraMacros instructions, was first introduced by Randy Brandt in Issue 4 of the periodic disk magazine TimeOut Central (1991), and is created by the TimeOut application called TimeOut Macros2Menus. It allows users to access their macros from the convenience of the TimeOut menu. This type of TimeOut is written completely in the UltraMacros scripting language, compiled with the Ultra Compiler and then processed by the Macros2Menus TimeOut application. Not to be discounted, this type of TimeOut can be quite powerful.

The former, and traditional type of TimeOut application, of which TimeOut Edit BASIC is an example, was conceived by Alan Bird of Beagle Bros and first introduced in 1987. Written entirely in 6502 assembly language and assembled into object code, and requiring a fair amount of knowledge of the internal workings of AppleWorks including the TimeOut engine itself, this traditional type of TimeOut formed the basis for the wildly commercially successful TimeOut series of AppleWorks add-ons. Although the vast majority of traditional TimeOuts were written by one or more of the Beagle Bros, a few TimeOut applications were released by some non-Beagles, including Douglas Gum (Office Productivity Software), the late Barclay Clemesha (TimeOut Central), Christian Serreau (The AppleWorks Gazette), Daniel Lurot (POMS #40) and Robert Coustal (POMS #41).

Although the learning curve for someone wanting to write a traditional TimeOut application is fairly steep, the advantages of using the myriad of internal AppleWorks routines for keyboard, text and number processing, screen display and menu handling, as well as AppleWorks full-featured file selection routine are most attractive even for programmers who wish to write applications unrelated to AppleWorks' core Spreadsheet, Data Base and Word Processing functions.

As far as I can tell, TimeOut Edit BASIC is the first new TimeOut application released in over twenty years. Included is heavily commented source code in both Merlin and .pdf formats that should allow those so inclined at least to consider writing their own TimeOuts for AppleWorks.

C. TimeOut Edit BASIC - How Does It Operate?

1. Select Edit BASIC 5.4 from the <OA-ESC> TimeOut Menu.

2. Review Application Notes on Splash Screen.

3. Select BASIC File to Load/View/Edit.

TimeOut Edit BASIC will restrict the display and selection to just two types: (i) BASIC files (ProDOS File Type $FC) and (ii) ProDOS directories and subdirectories.

Remember that AppleWorks 5.1 allows one to point and shoot through file directories. Use <TAB> to change drives, <OA-,> to move UP one level, and <OA-.> or <RETURN> to move DOWN one level.

4. Type an Editing Name for the Text File Just Created.

Note that TimeOut Edit BASIC will suggest a new name for you based on the original BASIC file name, but with a .T suffix appended to the end. Feel free to change this to anything you like.

5. Begin Viewing and/or Editing the BASIC File Just Loaded.

Note that TimeOut Edit BASIC will default to saving the file as a TEXT file,

Remember, with AppleWorks 5.1 there is no longer any need to 'print' a Word Processor file to a TEXT file in order to save it as a TEXT file. Any file loaded as a TEXT file (as well as a file created by TimeOut Edit BASIC) will be saved as a TEXT file provided that you have this feature selected in your AppleWorks preferences.

Main Menu -> 5. Other Activities -> 5. Select standard settings for AppleWorks -> 13. Word Processor options -> 8. Save text files as text

If you plan to EXEC the edited file to enter the Applesoft program into memory, be sure that you save the file as TEXT.

D. AppleWorks TimeOuts - How to Install?

TimeOuts are easy to install as they simply are copied into the TIMEOUT subdirectory within the main AppleWorks directory. The TimeOut will always be added to the TimeOut menu when AppleWorks is launched, provided that you have activated TimeOut in your AppleWorks preferences.

Main Menu -> 5. Other Activities -> 5. Select standard settings for AppleWorks -> 4. TimeOut options -> 1. TimeOut activated

E. AppleWorks TimeOuts - How to Configure?

To Configure a TimeOut application, select 'Utilities' from the TIMEOUT Menu and choose option 1, Configure. Then, select the application you wish to configure and follow the screen prompts.

TimeOut Edit BASIC has two Configuration Options:

1. Show Control Characters in INVERSE (Yes or No)
2. # of Characters to Indent Long Lines (0 - 8)

F. AppleWorks TimeOuts - How to Un-Install?

To uninstall a TimeOut application, merely delete it from the TIMEOUT subdirectory and restart AppleWorks. That's all.

G. Questions and Suggestions

If you have any questions about any of this, or suggestions for improvements, please post them in comp.sys.apple2 with the subject 'TimeOut Edit BASIC'. This will allow for idea exchange and improvements.

H. Revision History

First Public Release - March 2, 2019

1. TimeOut Edit BASIC 5.4 - (TO.EDITBASIC.54) [Version 5.4]

I. Program Internals

TimeOut Edit BASIC is not a complicated program.

In a nutshell, it patches and uses the already existing AppleWorks routines to 'Make a new file for the Word Processor', and interjects itself into the text file reading routine to de-tokenize the tokenized BASIC file and pass it to the word processing module.

Importantly, it also ensures that the AppleWorks internal file save-type byte located at $7C68 is set to 'TEXT', so that when the de-tokenized and edited file is saved back to disk, a 'TEXT' file (as opposed to an AppleWorks Word Processor file) is saved. That file can then be 'EXECed' back into memory at the BASIC prompt to re-create the Applesoft program.

J. Future Additions

Certainly, TimeOut Edit BASIC is not a replacement for Alan Bird's Program Writer, as it has no renumber feature and does not attempt to check BASIC syntax. Any syntax errors made will not become readily apparent until you 'EXEC' the saved program into memory from the BASIC prompt, or run the program itself.

I have toyed with a couple of things, though. Randy Brandt wrote TimeOut Line Sort (from PowerPack) for sorting lines in the Word Processing module, but it is strictly an A-Z or Z-A sort, and doesn't work well on wrapped lines. Could it be updated to accommodate sorting the numbered lines in a BASIC program?

Randy also wrote TimeOut Program Selector (also from PowerPack). I can see that a stripped-down version of this could allow one, after completing the editing of a BASIC program in AppleWorks, to QUIT directly from AppleWorks and wind up with a BASIC prompt in the same directory to which the edited program was just saved. At that point, the file could be EXECed into memory for testing.

If there is something that you would like to see, please either pass it on, or perhaps write it yourself and share it.

K. Credits

I must first express my thanks to Ewen Wannop for conceiving and writing his superb desktop disassembly program 'BrkDown'. Without it, I suspect I would have never been able to decipher the internal workings of AppleWorks to the extent I have. Yes, there are other disassemblers for the Apple II -- BrkDown, using the GS/OS desktop interface, is like none of the others. It makes disassembling a program enjoyable, in fact.

Next, I thank the late Joe Walters, who, when I asked him if he knew how to write a TimeOut application, sent me a special disk that he had earlier obtained from a former Beagle Bro. It contained some sample source code for constructing a TimeOut application. Analyzing that sample code was extraordinarily helpful.

I am also grateful for the work of Frenchmen Daniel Lurot and Robert Coustal, who in issues #40 and #41 of the French Apple Magazine POMS (1989), not only released the first non-Beagle TimeOuts ever written (TimeOut FontViewer and TimeOut Calendrier), but also their Merlin source code for the applications. Although I had never seen POMS until recently and then only at the behest of Antoine Vignau, and had to rely heavily on Google Translate to bolster my understanding of the French language, Lurot and Coustal's source code was instructive regarding how to write a TimeOut, and was impressive considering that those men had to disassemble existing Beagle TimeOuts in order to glean exactly what was required. Currently, their TimeOuts work only with French AppleWorks version 1.4 (U.S. version 2.0), but I plan to release an update to Lurot's TimeOut FontViewer that will enable it to work with AppleWorks 5.1.

Of great help was the work of another Frenchman, Christian Serreau, who detailed in a series of articles in the NAUG AppleWorks Forum and in the disk magazine The AppleWorks Gazette many of the inner workings of AppleWorks itself.

Finally, I must mention 'Mr. AppleWorks', Randy Brandt. Over 20 years ago, he released on the GEnie Apple II Bulletin Board a disk containing the source code to some of the UltraMacros DOT commands. Included in that source was an AW.EQUATES file that listed the names and addresses (but not the detailed descriptions) for many of the major internal AppleWorks routines. That information was most helpful.

Armed with the knowledge obtained from my AppleWorks friends, and wanting (for some reason) to load BASIC files directly into AppleWorks, I was prepared to write TimeOut Edit BASIC which I hope you find as useful as I do.

L. Download

This download consists of an archived (ShrinkIt) '.shk' file.

The '.shk' will contain not only TimeOut Edit BASIC, but also a 'ReadMe' file and the assembler source code for the TimeOut application in both Merlin16 and Merlin32 formats.

Download TimeOut Edit BASIC as .shk archive file

Download TimeOut Edit BASIC as disk image

M. Source Code

View/Download .pdf of Merlin Source Code for TimeOut Edit BASIC 5.4

N. Other AppleWorks Accessories

The AppleWorks InitPack, last updated in 2017, offers ten (10) 'Inits' for AppleWorks that add a myriad of new features to the program.

See it here:

AppleWorks InitPack 2017

O. Distribution

TimeOut EditBASIC and its source code are Copyrighted Freeware, and may be freely distributed and posted elsewhere without charge or other permission.