Docs

Getting Started

Conventions

This document uses the following formatting conventions:

ℹ️ NOTE: Information that is useful but incidental to the text appears like this.

⚠️ WARNING: Important warnings appear like this.

Keyboard shortcuts will be called out using these symbols:

△ = Open Apple

▲ = Solid Apple

Compatibility

Apple II DeskTop requires an Apple II, compatible, or emulator with at least 128k of RAM and Double-HiRes graphics support. This includes the Apple IIe (except Revision A motherboards), Enhanced Apple IIe, Apple IIc and IIc Plus, Apple IIgs, Apple IIe Option Card for Macintosh, the Laser 128 family, or emulators such as Virtual ][ or AppleWin.

A mouse is strongly recommended, although most functions are available via the keyboard.

ℹ️ NOTE: The M0100 mouse is known to have compatibility issues with the IIc and IIc+ where the mouse may not be detected, or one axis may stop being measured. This is due to a hardware problem affecting only some mice with that model number. Mice with models starting with A2 should function correctly. (This problem is not specific to Apple II DeskTop.) More details

DeskTop uses the double-hires display mode. On systems with built-in or optional RGB adapters (e.g. Apple IIgs, Le Chat Mauve, Video 7, AppleColor RGB card) and a compatible monitor, DeskTop will automatically switch the display to monochrome mode. On systems with a color composite monitor, the display may appear in color and text may be blurry. To make the text more readable, manually switch the monitor or computer to monochrome mode if possible while running DeskTop. The AppleColor Composite Monitor IIe has a toggle button in the control panel. The Laser 128 line of computers has a MONO/COLOR switch above the keyboard. Emulators usually have a color/monochrome option as well.

DeskTop is a ProDOS 8 application, and works best on a mass storage device or at least an 800k floppy. Running from 140k is possible (without desk accessories) but is not recommended.

ℹ️ NOTE: Certain features are known to fail with versions of ProDOS before 1.1. Booting with a newer version is recommended.

⚠️ WARNING: DeskTop is not compatible with the experimental ProDOS 2.5. Booting with an earlier version (e.g. ProDOS 2.4.2) is required. Files already on disks with mixed-case names created with ProDOS 2.5 will be displayed correctly.

Installation

Apple II DeskTop is distributed in two ways:

  • A2DeskTop.po is an 800k image containing the full application and all accessories. You can transfer it to an 3.5" floppy using ADTPro.
  • DeskTop.po, DeskAccessories.po and Preview.po are 140k images containing different parts of the application. You can transfer the files to 5.25" floppies using ADTPro.

An Apple II DeskTop installation has the following structure on a mass storage device:

  • 📁 A2.DESKTOP - application directory - You can name this anything and it can be in any subdirectory
    • 📄 DESKTOP.SYSTEM - system file - You run this this to launch DeskTop. If the optional SELECTOR file is present in the application directory, it will launch instead.
    • 📄 DESKTOP2 - (application file)
    • 📁 DESK.ACC - (subdirectory) contains Desk Accessories (DAs)
    • 📁 PREVIEW - (subdirectory) contains file preview handlers (special type of DAs)

At runtime, DeskTop will create other files within the application directory:

    • 📄 QUIT.TMP holds the original ProDOS quit routine.
    • 📄 SELECTOR.LIST holds the Selector menu entries, which allow for quick launching of other applications.
    • 📄 DESKTOP.CONFIG holds settings, if changed in the Control Panel DA. Delete this to reset settings.

The DeskTop

Using the DeskTop

Overview

The DeskTop is a program for managing the contents of disks, running programs, and previewing text and graphics files. It provides a graphical user interface like the macOS Finder or the Windows Explorer shell. It requires the ProDOS operating system for the Apple II. It works best with a mouse, although most functions are available via keyboard as well.

ℹ️ NOTE: It is assumed that the reader is familiar with modern desktop operating systems and using the mouse to control windows, icons and menus. Only features specific to DeskTop will be called out.

Starting DeskTop

Execute the DESKTOP.SYSTEM file from a ProDOS selector (such as BITSY BYE) to launch DeskTop. The ProDOS /RAM volume will be disconnected while DeskTop is running, and any contents will be lost.

ℹ️ NOTE: If a RAM expansion card such as an Apple II Memory Expansion Card or RAMWorks card and a RAM disk is present, then the DeskTop application will copy itself the RAM disk. This allows DeskTop to restart faster. Hold down the △ key while starting to prevent this.

Once DeskTop has started, a menu bar will appear at the top of the screen. Icons for ProDOS volumes will appear along the right side of the screen (and bottom if necessary).

Working With Disks

Icons represent the type of volume:

  • 5.25" floppy icon for disks in Disk II drives
  • 3.5" floppy icon for 800k disks
  • RAM card icon for RAM disks
  • file share icon for AppleTalk file shares
  • ProFile external hard disk icon for other disk types.

A Trash can icon will appear in the lower right of the screen. If your system has a real-time clock and appropriate ProDOS driver, a clock showing the day of the week and current time will appear in the upper right.

DeskTop Icons

If a drive supports ejecting disks, drag the volume icon to the Trash to eject it, or use the Special > Eject Disk command or the △-E shortcut.

On some systems and some drive types, DeskTop can detect if a disk is manually ejected or replaced. On others, it is necessary to use commands. Special > Check All Drives will close all windows and check all drives for disks. Use Special > Check Drive to check only the drive holding the selected disk.

ProDOS disks can be formatted or erased using Special > Format a Disk ... or Special > Erase a Disk ... respectively.

ProDOS, DOS 3.3, and Pascal formatted disks can be copied using the Special > Disk Copy ... command.

ℹ️ NOTE: Disk Copy is a launched as a separate program. You may restart DeskTop after running this command by selecting File > Quit.

Working With Files

Double-click a volume icon to show a window containing icons for each file in the volume. Double-click a folder icon to show a window containing the contents of the folder. If a mouse is not available, use the File > Open command or △-O shortcut.

ℹ️ NOTE: Hold down △ while double-clicking a folder (or selecting File > Open) to close the parent window. (This does not work with the △-O shortcut.)

Icons represent different ProDOS file types:

  • Directory - DIR
  • Text - TXT
  • Graphics - FOT/$08, or certain BIN files:
    • BIN files with aux type $2000 or $4000 taking up 17 blocks (Hires) or 33 blocks (Double-Hires)
    • BIN files with aux type $5800 taking up 3 blocks (Minipix/Print Shop)
  • Binary and Relocatable files - BIN, REL
  • BASIC programs - BAS
  • DeskTop Accessory programs - $F1, auxtype $640 or $8640
  • System files (like ProDOS) - SYS
  • Application files (like BASIC.SYSTEM) - SYS with ".SYSTEM" suffix
  • AppleWorks word processing files, spreadsheets, and databases - AWP, ASP, ADB
  • ProDOS command files - CMD
  • Apple IIgs-specific files - $5x, $Ax, $Bx, $Cx
  • Generic (any other type)

ℹ️ NOTE: DeskTop is limited to displaying up to 127 icons at once. If there are not enough icons available to display a directory's files, DeskTop will ask you to close a window and try again.

File Type Icons

Moving, Copying, and Deleting Files

Drag a volume icon onto a folder or volume icon to copy the contents of the source volume into the destination.

Select more than one icon by dragging a rectangle around the icons, or by holding △ while clicking each icon.

Drag files to a window, volume icon, or folder icon from the same volume to move files. To copy files on the same volume instead, hold down △ while dropping.

Drag files to a window, volume icon, or folder from a different volume to copy files.

Drag file icons to the Trash to delete them, or use the △-Delete shortcut.

⚠️ WARNING: Deleted files can not be recovered from the Trash, unlike in modern operating systems.

You can use the File > Copy a File ... and File > Delete a File ... commands instead of selecting icons. The commands will show a dialog allowing selection of the files to operate on by directory and name.

View Options

The View menu allows changing how the contents of a window appear: as icons, or as a textual list sorted by name, date, size or type.

ℹ️ NOTE: Unlike modern operating systems, you can only select the contents of the window when viewed as icons. When shown as a list, you can only scroll the window contents.

Running Programs

You can run System files and Application files by double-clicking or using the File > Open command. If these support quitting back to ProDOS, DeskTop will restart.

You can run BASIC programs by double-clicking or using the File > Open command, if BASIC.SYSTEM is present on the same volume. At the BASIC prompt, type BYE to return to DeskTop.

You can run DeskTop Accessory files (shown with the Apple icon) by double-clicking or using the File > Open command.

ℹ️ NOTE: You can't run a Binary file by double-clicking, but you can run it with the △-O shortcut or by holding down △ while selecting File > Open.

Previewing Files

You can preview Text, Graphics and Font files without leaving DeskTop. Either double-click the file, or select the file use the File > Open command. Use the Esc key to exit preview.

  • Text files: click the Proportional button in the top right to toggle to Fixed mode, or vice versa.
  • Graphics files: tap the spacebar to switch between color and monochrome mode. This is only supported on systems with RGB adapters (e.g. Apple IIgs, Le Chat Mauve, Video 7, AppleColor RGB card).

ℹ️ NOTE: Previews are handled by desk accessories present in the PREVIEW directory.

Text File Preview

Image File Preview

Font File Preview

Using BASIS.SYSTEM

ProDOS 2.4's Bitsy Bye introduces the notion of BASIS.SYSTEM as a fallback interpreter. When double-clicking or using the File > Open command on a file other than the types listed above (SYS, BIN, BAS, TXT, FOT, FNT), if a file named BASIS.SYSTEM is present in the same directory or a parent directory, then it will be used to invoke the file.

ℹ️ NOTE: Different ProDOS 2.4 disks will use custom files named BASIS.SYSTEM to support different file types. For example, a disk with video demos will name the player application BASIS.SYSTEM so that selecting video files from Bitsy Bye will launch it automatically. Bitsy Bye only looks in the root directory of the drive, unlike DeskTop.

Startup Menu

The Startup menu shows options for restarting the computer from any slot known to contain a disk drive. For example, Start > Slot 6 is equivalent to typing PR#6 from BASIC.

Selector Menu

The Selector Menu allows configuring applications as list entries that appear in the menu itself. Up to 8 list entries can be added, and can then be run from the menu or using the △-1 through △-8 shortcuts.

The run list entries also appear in the separate Selector application (see below); 16 additional "other run list" entries can be added which only appear in the Selector.

When adding or editing an entry, it can be set to be copied to a RAM disk either when DeskTop is started or when the entry is first used, for faster startup. If so specified, the entire directory containing the application along with any subdirectories will be copied to the RAM disk at the appropriate time.

ℹ️ NOTE: Any type of file can be specified as a run list entry, but SYS, BAS, and BIN files make the most sense.

Desk Accessories

The Apple menu contains accessories which can be run without leaving DeskTop. Some accessories operate on the current selection. Some launch interactive windows. Some are useful utilities, while others are purely for entertainment.

ℹ️ NOTE: The Apple IIgs supported different types of desk accessories (CDAs and NDAs). These are not compatible with DeskTop.

Calculator

Shows a simple four-function calculator (add, subtract, multiply, divide). You can click buttons or press a key to enter values or perform operations. Click the e button to enter an exponent or the c button to clear.

Date

Shows the current date. If your system does not have a real-time clock, the ProDOS date can be set. This will apply to file operations until ProDOS restarts.

Control Panel

Allows changing some DeskTop preferences. The options include:

  • Desktop Pattern. Use the arrows to select from preset patterns, or edit the pattern by clicking in the big grid. Click the mini desktop to apply the pattern. Most patterns are optimized for monochrome displays, but some striped patterns are included that will appear as solid colors on color displays.
  • Double-Click Speed. This adjusts the time that DeskTop waits to detect a double-click. On faster machines (with accelerators or on emulated machines) increase the time DeskTop waits by choosing an option on the left.
  • Calibrate Joystick. This shows the X/Y coordinates of the joystick (or paddles) and the button states.
  • Rate of Insertion Point Blinking. This adjusts how fast the insertion point blinks in text input fields.

ℹ️ NOTE: When the Control Panel closes, the updated settings are written to a DESKTOP.CONFIG file.

Eyes

Shows a resizable window with eyes that track the movement of the mouse.

Key Caps

Shows a keyboard map, and indicates the keys you press. The "standard" layout will be shown for the Apple IIe or IIc. The "extended" layout will be shown for the IIc Plus or Apple IIgs. You can close the window using the keyboard by typing △-Q.

Puzzle

Shows a simple puzzle with 15 moving tiles. Click once to scramble the puzzle, and click the pieces to try and restore the puzzle to a solved state.

Run Basic Here

Runs BASIC.SYSTEM with the PREFIX set to the path of the current window. Type BYE to return to DeskTop.

ℹ️ NOTE: BASIC.SYSTEM must be present on the same volume as DeskTop.

Screen Dump

Dumps a screenshot to an ImageWriter II attached to a Super Serial Card in Slot 1.

Screen Saver

Clears the screen and shows a somewhat entertaining distraction. Press Esc or click the mouse to return to the DeskTop.

Sort Directory

This accessory will reorder the files in the current window (volume or directory).

    • If any files are selected, these are moved to the start of the directory listing, in selection order; other files appear after, order unchanged.
    • If no files are selected, all files are sorted by type (DIR, TXT, SYS, then others), and further sorted alphabetically by filename

ℹ️ NOTE: The Sort Directory accessory will only work with local disks. It will not work with network file shares.

This Apple

Shows details about the system. This includes the model of Apple, the version of ProDOS, the size of any expanded RAMWorks-style memory, the CPU type, and the contents of slots.

Keyboard Control

It is possible to execute most functions of Apple II DeskTop with the keyboard. Menus will display shortcuts for many actions. These shortcuts can also be used:

Menus

  • Esc - enter menu mode; Arrow keys to navigate, Return to select

Windows

  • △-` or △-Tab - Cycle through open windows
  • △-G - Resize window; Arrow keys to resize, Return to finish
  • △-M - Move window; Arrow keys to move, Return to finish
  • △-X - Scroll contents; Arrow keys to scroll, Esc or Return when done

Icons

  • △-H - Highlight icon; Left/Right Arrow keys to navigate, Esc or Return when done
  • △-A - Select all icons
  • △-Delete - Delete selected icons, or eject selected volumes

Menu Shortcuts

  • File Menu
    • △-F - New Folder
    • △-O - Open
    • △-W - Close
    • △-A - Select All
    • △-I - Get Info
    • △-Y - Copy a File
    • △-D - Delete a File
    • △-Q - Quit
  • View
    • △-J - View As Icons
    • △-N - View By Name
    • △-T - View By Date
    • △-K - View By Size
    • △-L - View By Type
  • Special
    • △-E - Eject Disk
    • △-S - Format a Disk
    • △-Z - Erase a Disk
  • Selector
    • △-0 - Run Selector
    • △-1 ... △-9 - Selector Entries

Mouse Keys

  • To enter Mouse Keys mode, hold down △ and then press and release ▲.
  • While holding △ down, you can you can navigate the cursor with the Arrow keys, and click using ▲.
  • To exit Mouse Keys mode, release △.

⚠️ WARNING: Some keyboard controls behave unpredictably on the Apple IIe if a mouse card is present but no mouse is attached.

The Selector

Using the Selector

TODO

Tips and Tricks

Customizing the Apple menu entries

You can use the Sort Directory DA to order the files in the DESK.ACC folder, which controls the menu order:

  • Open the A2.DESKTOP/DESK.ACC folder
  • Hold △ and click on each file in the desired order
  • Select Sort Directory from the Apple menu, and verify the order
  • Restart (File > Quit, relaunch)

To remove items from the Apple menu, you can do either of the following.

  • Move the DA file out of the DESK.ACC folder. You can run it later by double-clicking if needed.
  • Use a utility to change the aux type from $640 to $8640.

Copy the SHOW.TEXT.FILE and SHOW.IMAGE.FILE accessories from the PREVIEW directory to the DESK.ACC directory to make them appear on the Apple menu. You can then use them to preview files that do not have the correct ProDOS file types. After restarting, select a file to preview, then select the accessory from the Apple menu.

Secrets and Mysteries

  • The Calculator desk accessory has a tiny monogram resembling "JB" drawn in the title bar - possibly the "J. Bernard" thanked in the credits?
  • The string "Rien" appears in a couple of places in the code. Is this a name?
  • In the This Apple desk accessory, type E to see what other Apple models look like.