When the emulator is run, the screen of the emulated machine is
displayed in a standard X Window which we will call the emulation
window. This window will be updated in real time, displaying the same
contents that a real monitor or TV set would.

Below the emulation window there is an area which is used to display
information about the state of the emulator; we will call this area the
status bar.

On the extreme left of the status bar, there is a performance
meter. This displays the current relative speed of the emulator (as a
percentage) and the update frequency (in frames per second). All the
machines emulated are PAL, so the update frequency will be 50 frames
per second if your system is fast enough to allow emulation at
the speed of the real machine.

On the extreme right of the status bar, there is a drive status
indicator. This is only visible if the hardware-level ("True") 1541
emulation is turned on. In that case, the drive status indicator will
contain a rectangle emulating the drive LED and will display the current
track position of the drive's read/write head.

It is possible to execute some commands and change emulation parameters
while the emulator is running: when the pointer is over the emulation
window, two menus are available by pressing either the left or right
mouse buttons. The left mouse button will open the command menu
from which several emulation-related commands can be executed; the right
mouse button will open the settings menu from which emulation
parameters can be changed. The basic difference between the command and
the settings menu is that, while commands have only effect on the
current session, settings can be saved and later used with the "Save
settings" and "Load settings" right-button menu items, respectively.
"Restore default settings" restores the factory defaults.
See section 6 Settings and resources. for more information about how settings
work in VICE.

Sometimes commands can be reached via shortcuts or hotkeys,
i.e., it is possible to execute them by pressing a sequence of keys
instead of going through the menu with the mouse. Where shortcuts
exist, they are displayed in parentheses at the right edge of the menu
item. In VICE, all shortcuts must begin with the Meta or
Alt key. So, for example, to attach a disk image to drive #8 (the
corresponding menu item displays "M-8"), you have to press the
Meta (or Alt) and then 8.

Note that no other key presses are passed on to the emulated machine
while either Meta or Alt are held down.

At any time, if you get stuck or do not remember how to perform a
certain action, you can use the "Browse manuals" command (left button
menu). This will popup a browser and open the HTML version of this
documentation. Notice that this requires VICE to be properly (and
fully) installed with a `make install'.

The browser can be specified via the HTMLBrowserCommand string
resource (see section 6 Settings and resources for information about
resources). Every `%s' in the string will be replaced with a URL
to the VICE HTML pages.

In those situations where it is necessary to specify a file name, all
of the VICE emulators will pop up a file selector window allowing
you to select or specify a file interactively.

To the left of the file selector, there is a list of ancestor
directories: by clicking on them, you can ascend the directory tree. To
the right, there is a list of the files in the current directory; files
can be selected by clicking on them. If you click on a directory, that
directory becomes the current one; if you click on an ordinary file, it
becomes the active selection.

At the top, there is a directory box, with the complete path of
the current directory, and a file name box, with the name of the
currently selected file. At the bottom there are two buttons: "OK"
confirms the selected file and "Cancel" abandons the file selector
without cancelling the operation.

It is also possible to specify what files you want to show in the file
selector by writing an appropriate shell-like pattern in the directory
box; e.g., `~/*.[dx]64' will only show files in the home directory whose
name ends with either `.d64' or with `.x64'.

The emulator is able to emulate disk drives and tape
recorders if provided with suitable disk images or tape
images. An image is a raw dump of the contents of the media, and
must be attached before the emulator can use it. "Attaching" a
disk or tape image is like "virtually" inserting a diskette or a
cassette into the disk drive or the tape recorder: once an image is
attached, the emulator is able to use it as a storage media.

There are five commands (in the left button menu) that deal with disk
and tape images:

Attach Disk Image

Detach Disk Image

Attach Tape Image

Detach Tape Image

Smart-attach a file

The first four commands are used to insert and remove the virtual disks
and cassettes from the respective units. On the other hand, the
last commands tries to guess the type of the image you are attaching
from its name and size, and attaches it to the most reasonable device.

Supported formats are D64 and X64 for disk images (devices
8, 9 and 10) and T64 for tape images. Notice that T64
support is read-only, and that the cassette is automatically
rewound when you reach its end.

Another important feature is that raw Commodore BASIC binary files and
.P00 files can be attached as tapes. As you can autostart a
tape image when it is attached (see section 5.5.2 "Autostarting" an image), this allows you to
autostart these particular files as well.

You can attach a disk for which you do not have write permissions: when this
happens, the 1541 emulator will emulate a write-protected disk. This is
also useful if you want to prevent certain disk images from being
written to; in the latter case, just remove the write permission for
that file, e.g., by doing a chmod a-w.

It is possible to examine the directory of a disk or tape image before
attaching it. Just press the "Contents" button in the file selector
window and a new window will pop up with the contents of the selected
image.

Notice that this function automatically translates the directory from
PETSCII to ASCII; but, due to differences in the two encodings, it is
not always possible to translate all the characters, so you might get
funny results when "weird" characters such as the semi-graphical ones
are being used.

If you want to reset the machine and run the first program on a certain
image without typing any commands at the Commodore BASIC prompt, you can
use the "Autostart" button in the file selector window after selecting
a proper disk or tape image file.

Notice that, if true drive emulation is turned on, it will be turned off
before running the program and then turned on again after it has been
loaded. This way, you get the maximum possible speed while loading the
file, but you do not lose compatibility once the program itself is
running.

This method is not completely safe, because some autostarting methods
might cause the true drive emulation not to be turned on again. In such
cases, the best thing to do is to disable kernal traps (which will cause
true drive emulation to be always kept turned on), or to manually load
the program with true drive emulation turned on.

It is also possible to attach disk or tape images that have been
compressed through various algorithms; compression formats are
identified from the file extension. The following formats are supported
(the expected file name extension is in parenthesis):

GNU Zip (.gz or .z);

BZip version 2 (.bz2);

PkZip (.zip);

GNU Zipped TAR archives (.tar.gz, .tgz);

Zoo (.zoo).

PkZip, tar.gz, lha and zoo support is
read-only and always uses the firstT64 or
D64 file in the archive. So archives containing multiple files
will always be handled as if they contain only a single file.

Since version 0.15, the VICE emulators have been able to attach disks
packed with Zipcode or Lynx directly, removing the need to manually
convert them into D64 or X64 files with c1541.
This is achieved by automatically invoking c1541, letting it
decode the file into a temporary image and attaching the resulting
temporary image read-only. For this to work, the directory containing
c1541 must be in your PATH.

This uses the -unlynx and -zcreate options of c1541
(see section 13.3 c1541 commands and options); these commands are not very
reliable yet, and could fail with certain kinds of Lynx and Zipcode
images (for example, they cannot deal with DEL files properly).
So please use them with caution.

Lynx files usually come as `.lnx' files which are unpacked into
single disk images. On the other hand, Zipcode files do not have a
particular extension (although `.z64' is sometimes used), and
represent a disk by means of component files, named as follows:

`1!NAME'

`2!NAME'

`3!NAME'

`4!NAME'

If you attach as a disk image (or smart-attach) any one of these files,
the emulator will simply pick up the other three (by examining
the name) and then build a disk image using all four.

You can reset the emulated machine at any time by using the "Reset"
command from the command menu. There are two types of reset:

soft reset, which simply resets the CPU and all the other chips;

hard reset, which also clears up the contents of RAM.

A soft reset is the same as a hardware reset achieved by pulling
the RESET line down; a hard reset is more like a power
on/power off sequence in that it makes sure the whole RAM is cleared.

It is possible that a soft reset may not be enough to take the machine
to the OS initialization sequence: in such cases, you will have to do a
hard reset instead.

This is especially the case for the CBM-II emulators. Those machines
examine a memory location and if they find a certain "magic" value they
only do what you know from the C64 as Run/Stop-Restore.
Therefore, to really reset a CBM-II use hard reset.