afgui - Alien Flash GUI
-----------------------

(c) 2011 Hannu Nuotio <nojoopa@users.sf.net>


1. Intro
--------

afgui is a small utility for dealing with Alien Flash .crt images and
the actual cartridge via the USB connection. It's the pointy-clicky
version of aftool.

afgui is mostly GPL, see COPYING_tool. Some bits taken from VICE(minus).

ui_fltk.c is FLTK license, see COPYING_fltk. Based on FLTK examples.
To satisfy the license:
           afgui is based in part on the work of
           the FLTK project (http://www.fltk.org).

For more info on Alien Flash, see:
http://t-winkler.net/dokuwiki/doku.php?id=en:af:start


2. Usage
--------


2.1. Starting
-------------

afgui can be started by simply doing:
    afgui
...or via the usual UI means.

To load a .crt image at start, do:
    afgui my_cart.crt

Some more options exist. Below is the output of "aftool -h":

--< snip >--
Usage: afgui [AFCRT]

Available OPTIONs:
  -h           Show more help.
  -o OUTAFCRT  Save Alien Flash .crt to file OUTAFCRT. (default = use INAFCRT)
  -d USBDRV    Select Alien Flash USB driver.
  -u USBPAR    Set Alien Flash USB parameter.
  -b VAL       Set USB read block size. (default = $40)
  -x VAL       Set USB write block size. (default = $800)
  -r VAL       Use VAL (in hex) reads after chip erase. (default = $4000)
  -w VAL       Use VAL (in hex) reads after byte program. (default = $1)
  -e           Do erases in created AFTT files. (default = don't erase)
  -t TEXT      Use TEXT (max 16 chars) as description for .prg/.d64.
  -n TEXT      Use TEXT (max 32 chars) as cart name for created .crt.
  -q           Be quieter.
--< snip >--

Note that some of these OPTIONS (namely -o and -q) only affect aftool.


2.2. Basics
-----------

The right side of the window has information/functions related to the USB
connection. The left/center has information/functions on the (in-memory)
flash image. The menu has all the available functions, while only some have
corresponding buttons.

One important thing to keep in mind: everything that comes from or goes to
the Alien Flash USB connection passes through the (in-memory) flash image.
For example, to send "blah.d64" from your hard drive to your Alien Flash,
you'd first "Inject D64" to the flash image and then "Send D64" it.

Below is a crude illustration of the operations:

                              | Load image
                              |
            Inject ->         v           Send ->
    hard drive  <--->    flash image    <--USB-->    Alien Flash
                <- Extract    |         <- Receive
                              |
                              v Save image


2.3. Image contents
-------------------

The ROM SLOT column in the middle of the window shows which ROM SLOTs of the
image contain something. The used colors:

 - gray: the slot is completely empty (all $ff)
 - yellow: the slot has some data in it (but won't boot)
 - blue: the slot has the CBM80 signature but no boot vectors
 - green: the slot has boot vectors (or at least some data in those locations)

The Action Replay, PRG and D64 slots on the left show if those are available
in ROM SLOT 0 (green: yes, gray: no). The PRG and D64 names from the Alien
Flash File header ($0100xx and $0400xx) are shown if the files are available.


3. Future
---------

Fix the freezing during USB transfers.
Add PRG/D64 naming functions.
