SeeUCON v1.0 by ThEo

* INTRODUCTION.
SeeUCON is a simple Java program. It's a front-end for the uCON64 program
written by various developers. SeeUCON is developed using some 1.9.8 beta
versions of the uCON64 program. You can download uCON64 at
http://ucon64.sf.net. SeeUCON is not a standalone program. It needs uCON64 to
really execute actions, and it needs Java 2 to run.
This is the first release, so please let me know if you find bugs of any kind,
so I can fix them for the next release.

* FEATURES.
- Nearly all current uCON64 options supported
- Easy upgrading, using an XML style configuration file
- Low disk usage
- Runs on Windows variants, Unix, Linux, and any other platform supporting Java
- Progress bar for actions that take a lot of time(if uCON64 displays one)
- Paths and defaults can be set easily in configuration file
- Free under GNU general public license
- Output redirection to text screen (shell, dosprompt), GUI window or file
- Learning the command line options of uCON64 for every action
- Nice graphical environment
- 'write once, run anywhere'

* REQUIREMENTS.
SeeUCON is written in Java, using the Java 2 SDK (a.k.a. the JDK). It uses the
Swing classes provided with the Java platform. To run the program you need to
have either the JDK or the JRE installed and working. You can download the JDK
and the JRE at http://java.sun.com/j2se/1.4/download.html. If you only want to
run SeeUCON just download the JRE (around 10 MB for Windows, around 20 MB for
Linux).
SeeUCON needs uCON64 1.9.8beta3 or a newer version. Under Windows XP you might
need the Win32 version of uCON64. You also need the Win32 version of uCON64
under Windows to see some of the error messages that uCON64 produces.

* INSTALLATION.
After downloading the zip file, extract all the files to a directory you like.
The complete package exists of these files (they should all be installed in the
same directory):

AllOptions.cfg
license.txt
readme.txt
run.bat
run.sh
SeeUCON.jar
SeeUCON.png
splash.jpg

It's important that you edit the file AllOptions.cfg before running SeeUCON.
Just start any text editor. In the file you'll find a brief explanation how it
works. You do not have to change any Console or Option definition, just change
the standard paths as you like. Find this line:

$DEFAULT_UCON_PATH
ididnotreadthedoc

and replace ididnotreadthedoc by the right location of the uCON64 executable.
Something like:

/usr/local/bin/ucon64
for Unix systems
or
c:\ucon64\ucon64.exe
for Windows systems.

Don't forget to add the executable-file to the path string. When you try to
execute a command in SeeUCON, and you get a command line message like: "Can't
read uCON64 output", you probably didn't set the DEFAULT_UCON_PATH line to a
valid location. If uCON64 is in your system's path, you can just write "ucon64"
(without the quotes) as the command line. If you like you can also change the
other default paths and settings.
There is a known problem with the DOS version of uCON64 under Windows XP (and
maybe Windows NT and Windows 2000) in combination with SeeUCON. See the
section BUGS.

* RUNNING.
To run SeeUCON you have to start the Java Virtual Machine. You do this with the
java command. Make sure that you put the directory that holds the java
executable in the path (under Windows the Java installer should do this for
you). Open a DOS box or shell and go to the directory where SeeUCON was
extracted to, and type

java -jar SeeUCON.jar

This should start SeeUCON.
As an alternative you could also start the frontend from a file manager like
Windows Explorer or Konqueror. Under Windows double click on SeeUCON.jar or
run.bat. Under Unix click on run.sh after you have edited run.sh so that
SEEUCONDIR is set to the directory where SeeUCON can be found. You may also
need to make it executable (chmod +x run.sh). Some error messages and warnings
of SeeUCON are only displayed on the command line, so start using run.bat or
run.sh only after SeeUCON works correctly.

Every console console panel contains blue and yellow buttons. The yellow
buttons are so-called toggle buttons. This kind of button will stay selected if
you release the mouse button after a click. If you click again they will get
deselected. Some of the toggle buttons are grouped together, because it makes
no sense to select several conflicting options. For example, in the General
panel there are two groups, one for "Force header"/"Force no header" and one
for "Force interleaved"/"Force not interleaved".

The program should work well in Windows 95/98/ME/NT/2000/XP, but also in Linux
and Unix variants that support the Java Virtual Machine. I heard it even works
on Macintosh platforms. It has been tested on Red Hat Linux 7.2, Windows 98 SE
and Windows XP.

* USAGE EXAMPLES.
Most parts of SeeUCON speak for themselves, but some things are less obvious.
Therefore, I'll present here a few examples on how to use SeeUCON.

Example 1 - Creating a 128 Megabit multirom for the Flash Advance Linker
1) At "Choose consoletype:" choose GameBoy Advance
2) Go to ROM and click on "Pick"
3) First select the loader file and then all ROM files that should make up the
   multirom by holding the Ctrl button and clicking on the files
4) Click on "Open"
   If you want to add ROM files from another directory go to step 3
5) Go to FILE and click on "Pick"
6) Select the directory where you want to create the multirom
7) Type a name at "File name:"
8) Click on "Open"
9) Click on the button "Make 128 Mbit multirom"
SeeUCON should display a window that shows what uCON64 has done.

Example 2 - Seeing info on a SNES ROM and forcing some settings
1) Go to ROM and click on "Pick"
2) Select a ROM file and click on "Open"
3) At "Choose consoletype:" choose Super Nintendo
4) Click on "Force not HiROM"
5) Click on "Force Super Nintendo"
6) Click on "Sticky options"
7) At "Choose consoletype:" choose General
8) Click on "Info"
The option "Sticky options" is useful if you want options to stay active while
you select another console options screen. To remove all previous sticky
options just uncheck the checkbox. The button "Show command line" can be quite
useful if you want to see which options were active (note the past tense).

Example 3 - Converting a NES ROM in iNES format (smb3.nes) to UNIF and
            specifying supported controller types
1) Go to ROM and click on "Pick"
2) Select smb3.nes and click on "Open"
3) At "Choose consoletype:" choose NES
4) Go to FILE and type -mapr TSROM
5) Click on "Regular joypad" and "Powerpad"
6) Click on "Convert to UNIF"
You should see a message that states where uCON64 wrote the new UNIF file. That
you have to type "-mapr" is a limitation of SeeUCON that may be solved in a
next version. For the NES switch "-mirr" you will have to do the same thing.
If you would like to use the toggle button "Use dump info" in the previous
example you would have to type the name of the info file after TSROM. You could
also select an info file first and then prepend the text -mapr TSROM (without
quotes and before the first quote of the file name).

* PROBLEMS.
If the "Executing..."-window (the one with the text "Please wait while
executing uCON64...") doesn't display any progress for a long time something
probably went wrong. You can abort uCON64 by closing that window. Press on the
button "Show command line" and try that exact command by typing it in a command
shell. If it then works without problems please contact me. If it still doesn't
work, contact the author of uCON64.

Note that some error messages of uCON64 will only be visible in SeeUCON if you
use the Win32 version of uCON64. The reason that you won't see those messages
with the DOS version is that DOS doesn't have a so-called "error stream", which
makes it impossible for SeeUCON to catch the error output of uCON64.

You can report every SeeUCON-related problem, bug, comment and request to me by
sending an e-mail to t_odink@hotmail.com, and I'll see what I can do. Nothing
you can think of or request is useless. More feedback means better, faster code
and fewer errors. I appreciate any feedback very much, and it will encourage me
to do updates.

* BUGS.
Known Bugs in version 1.0

- When closing the window that shows the progressbar, the window closes but the
  main window doesn't become available for some time. This is because Java
  doesn't seem to be able to kill the uCON64 process. The window should become
  available after an empty result window is shown. It should be possible in
  Java to kill a process, but in my tests using Windows 98, it didn't work.
  The problem doesn't seem to occur under Red Hat Linux 7.2 and Windows XP.

- Under certain circumstances SeeUCON can't start the DOS uCON64 executable
  under Windows XP. In that case you will get an error message telling you that
  ntvdm.exe ([Windows] New Technology Virtual DOS Machine) couldn't set up an
  environment for the uCON64 executable. This problem doesn't occur with the
  Win32 uCON64 executable.

* LICENCE.
This program is distributed under the GNU public licence. What this means, you
can read in the file licence.txt distributed with this package.
The author of this software will not take responsibility for any damage caused
by using this software.

* THANKS.
I would like to thank
dbjh - for testing, advice, some code and friendship.
noisyb - for placing SeeUCON on the uCON64 site, and some "output to GUI" code.

29-7-2002
ThEo
t_odink@hotmail.com
