What now follows is the ColorTool document for the end user.

    Before using the dissidents ColorTool, the file "color.library" must be
copied to the libs drawer of your boot (WorkBench) disk.

    The dissidents ColorTool allows you to adjust all of the Amiga's colors
in a very straight-forward way. It is a window filled with several gadgets.
At the top are (up to) 32 color "boxes" representing the current colors. One
of the color boxes will have a border around it. This indicates that the box
is the active one. To make another color box the active one, you simply move
the mouse pointer over the desired box, and click the right mouse button.
The border will move to that color box, making that box the active one.
    Note that color box #1 appears to be invisible because it is the same
color as the background of the ColorTool window. If you click around the top
left corner of the window where a box "looks" like it might fit, you should
see the border surround this "invisible" color box. Initially, color box #2
is the active one. Because the border is the same color as this box, the
border seems to blend into the box, resulting in what appears to be a color
box larger than the others. If you select another box, note that color box
#2 is really the same size as the others.
    Below and to the right of the color boxes are 3 sliders. These sliders
adjust the amount of red, green, and blue in the active color box. To the
left of each slider is a letter followed by a number. The letter indicates
which color component the slider alters: R for red, G for green, and B for
blue. The number is that component's intensity. This ranges from 0 to 15.
For example, you might see the following combination next to the sliders.

    R15

    G3

    B0

This means that the active color box has a lot of red in it, a little green,
and no blue. To your eye, the resulting color box should be some shade of
red. As you move a slider knob, you will see the active box's color change.
Also, you will notice that the number to the left of the slider changes.
   When you select a new color box, the sliders are automatically adjusted
to display the amount of red, green, and blue in that color box.
   By selecting color boxes, and moving the 3 sliders, you can adjust all of
the colors in the current screen, observing the resulting changes as the
sliders move.
   There are several other gadgets below the color box. They are labeled
Default, Cancel, Save, Undo, Copy, and Spread.
   The Undo gadget is used to reverse the last change which you made to the
color boxes. If you move a slider, then decide that you don't like the
resulting change to the active color box, you can restore the color by
clicking the right mouse button on the word "Undo". You can even undo the
Undo. By clicking on "Undo" again, you should see that the results you just
canceled are back. This feature is useful for comparing a changed box to the
original box to determine whether you really like the change.
   The Copy gadget is used to copy the current color box to another box.
Make sure that the color box you wish to copy has the border around it (e.g.
it is the active box). Then, move the mouse pointer over the word "Copy" and
click the right button. The mouse pointer will turn into the word "TO". This
means that ColorTool now expects you to select a box where you want this color
"TO" be copied. When you select a new color box, its color will change to the
copied box, and this new box will be made the active one (e.g. the border
will move to the new box.) If you don't like the results, you can Undo this.
If you mistakenly click on "Copy" and see the "TO" pointer, simply click on
the same box that is now active to abort the Copy procedure.
   The Spread gadget allows you to pick two color boxes, a start and end box,
and have ColorTool alter all of the color boxes inbetween so that they are
various "shades" of the start and end boxes. Select a start box by clicking
on it, then click on the word "Spread". The "TO" mouse pointer will now
appear. Choose a color box for the end, and click on it. All of the boxes
inbetween will change to a smooth variety of shades from start to end. If
you don't like the results, "Undo" them.  If you click on "Spread" by
accident, just click on the same box that is now active to abort the Spread.
   The Default gadget restores ALL of the color boxes to the same colors as
when the ColorTool window first appeared. This is different than the Undo,
which simply restores only the last change. Use Default when you want to
restore the initial palette and start anew.

  NOTE: Since the Default gadget can be configured differently by each
        application, some programs may not restore the initial palette,
        but instead change all of the color boxes to preset values.

   The Save and Cancel gadgets are used to exit the ColorTool. When you have
finished altering the colors, click on one of these gadgets.
  The Save gadget will exit the ColorTool, implementing all of the color
adjustments you made to the current screen.
  The Cancel gadget will exit, but all of your adjustments will be discarded
and the screen will appear exactly as it did before the ColorTool appeared.
   The ColorTool gadgets are initially drawn in the colors of the first two
color boxes. In fact, color box #2 is the foreground color (e.g. the color
that all of the gadgets appear to be). Sometimes, when color box #1 and #2
are almost the same color, the ColorTool gadgets can barely be seen. If this
condition occurs, by using the Function keys, you can change the color of
the gadgets without altering the palette. Press each of the 10 Function keys
on your keyboard, one at a time, until the ColorTool gadgets can be seen
well. One of the function keys should yield a serviceable result. If not,
hold down the ALT key, and press each of the 10 keys again. If you still
cannot see the ColorTool gadgets clearly, hold down the CTRL key and press
the w key. This will alter the first two color boxes (changing them to black
and white respectively). You can then make changes to the other color boxes,
and afterwards restore the first two by pressing CTRL and w again.
   Some people prefer to describe a color in terms of Hue, Saturation, and
Value instead of by its red, green, and blue components. By clicking in the
area where the R, G, and B intensities are displayed (e.g. the letters and
numbers), the sliders will change to Hue, Saturation, and Value sliders.
Note that the R, G, and B will change to H, S, and V. Also, the numbers will
represent the value for the sliders. (Though these values are really meaning-
less for HSV, they are included for reference.) Generally speaking, the Hue
slider chooses the color (frequency). As you move the Hue slider you should
see the color box change from red to green to blue. The Saturation determines
the amount of "pigmentation" of the color. If you set Hue to 0 and saturation
to 15, then you should see a definite shade of red. As Saturation goes to 0,
you will notice that the "red" seems to disappear from the color box, leaving
some shade of black, white, or grey. The Value slider determines the bright-
ness of the color. A Value of 0 will most certainly give a very dark, black-
ish color whereas a Value of 15 will give a very bright color. When Satura-
tion is 0, the Hue setting becomes meaningless because you have no "pigment"
in the color. Now, moving the value knob will give you all of the black,
white, and grey shades. For this special case, "--" is displayed for the
Hue value, and the slider knob is forced to maximum right position to remind
you that this color box is in "black and white" mode. To better understand
the intuitive approach of HSV, try the following examples:

  1). Set Saturation to 15 so that your color has the maximum amount of
      pigmentation. Set Value to 15 so that the color is bright. Now move
      the Hue knob and note how the color box changes shade.

  2). Set Hue to 0 so that you have a bright red shade. Now slowly lower
      the Saturation knob. Notice how the red seems to "disappear" from the
      color until finally you are left with no red in the color at all.

  3). Now move the Value knob from 15 to 0. Notice that the color box changes
      from black to white. This is because Saturation is 0 (i.e. you removed
      all the color or pigmentation from the color box).

  4). Set Saturation and Value to 15 so that you have the bright red again.
      Now adjust the Value knob. Notice how turning down the Value makes the
      red darker until finally you have a very dark shade.

    To go back to an RGB display, just click on the same display area where
the HSV numbers are printed out.
   The ColorTool adjusts the screen colors of the program which called it.
Amiga screens can be various sizes and depths. What this means is that some
screens may have more possible colors than others (i.e. 32 instead of 16).
The ColorTool will display only as many color boxes as there are colors for
the screen.
   Only one application can be displaying the ColorTool at a time. If you
run two programs which try to call up the ColorTool SIMULTANEOUSLY, one of
the two will not be able to present the ColorTool. You will have to adjust
the colors for the first application, then select ColorTool's Save (or Can-
cel) before the other application can use the ColorTool.

   «««««««««««««««««««««««««««««««« »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»

   What now follows is the ColorTool document for developers.

   Please read the end users document. If you skipped to this section without
reading the preceding information, you're probably a much too careless pro-
grammer to be plunging ahead. If you're one of those BASIC hackers who loaded
the example application into AmigaBasic without even reading this far, then
I pity your hapless soul.
   The ColorTool is actually a standard, disk-based library that your applica-
tion can open just like intuition or graphics. The library is called
"color.library". There is only one function in this library, DoColor. This
function is designed to modify the colors of a screen, so you must have
opened a screen before calling DoColor. DoColor opens the ColorTool window,
handles all of the user's interaction (making changes to your screen's colors),
and returns control to your program when the user selects Save or Cancel.
   The ColorTool handles screens of all sizes and depths, automatically dis-
playing only as many color boxes as the screen's depth allows. Also, the
ColorTool is designed to fit into any standard size screen.
   DoColor returns a 0 if the user selects SAVE and a 1 if he selects CAN-
CEL. (If he selected Cancel, your screen's colors will already have been
restored). There are also a few errors that DoColor can return. These errors
are negative numbers, and indicate that the ColorTool could not be presented
to the user.
   In order to conserve memory, the ColorTool can only be displayed by one
application at any given time. Though many applications can have it open and
use it, no two applications can SIMULTANEOUSLY display the ColorTool.
   There are two arguments passed to DoColor. One is the address of the
screen whose colors you wish the ColorTool to adjust. The other argument is
the address of a default colorMap (actually a collTable as described in
the GRAPHICS_VIEW include file from Commodore). This is a table of (up to)
32 WORDS representing the colors of the screen. When the user clicks on the
Default gadget, these colors are loaded into the screen. If you pass a NULL
(0), then the screen's initial colors are used instead. Possible uses are:

   1). An application could have a preset (or recommended) color setting
       invoked by the Default gadget.
   2). The application could allow a user to save a color table within a
       configuration file. Later, this table could become the one that
       gets passed in to DoColor for the Default gadget.

  result=DoColor(defaultTable, screen)
   d0               a0           a1

   Here are the possible error returns from DoColor.

 -4 = library in use, another application is displaying it
 -3 = passed a null screen address. I told you to open one, pinhead.
 -2 = screen has no depth (planes). Please don't do this to me.
 -1 = color window can't open (probably out of memory). Buy some more.

  The files that you should have received with this document are as follows:

  color.library      the ColorTool library which must be copied to the libs
                     dir of your boot disk

  ColorTest.asm      an example application in assembly

  ColorTest.c        an example application in C
  ColorInterface.asm  the C poot that all inefficient, high level languages
                      like C need to be linked with (assemble this file)

  BasicILBM          an AmigaBasic application (It could be worse. It could
                     be Pascal or Modula2. You know, that gibberish that
                     computer science instructors pretend is a real language.)
  color.bmap         the bmap file for BASIC
  color_lib.fd       the fd file for BASIC

  TEST               the executable of the assembly example

  Furthermore, the C and BASIC examples utilize two, public domain libraries
that are already available on Fish disks. One is a file requester, and the
other is an ilbm reader/writer. The documentation and development tools for
these are included on the dissidents' custom library disk.
  The C example presents the file requester so that you can load an ilbm
picture (using the ilbm library). After the picture is loaded and displayed,
if you press any key, the ColorTool will be presented. As you play with the
sliders, you can see the changes to the screen colors. When you press the
right mouse button, the picture will disappear, and the file requester will
be presented to load the next ilbm. Exit the program by clicking on the file
requester's CANCEL gadget.
  The Asm example is very straight-forward. Because it doesn't load any
graphics images, you really can only see the changes made to the first two
colors. If you run the example from the cli, then you can specify the
screen size and depth as follows:

  type an l or h (for HIRES or LORES) followed by a number for the depth

  For example,

  ColorTest l 5

  opens a LORES screen with 5 bitplanes (32 colors)

  ColorTest h 2

  opens a HIRES screen with 2 bitplanes (4 colors)

  Note how the ColorTool "fits" into various screen sizes, and presents the
proper number of color boxes.

  Incidentally, the library was written in the only language that matters:
assembly. It is approximately 6.6 K in size. Because it uses no uninitialized
data, it does not consume any more memory when loaded into the amiga.

  The ColorTool library is copyright 1989 by dissidents software. You may
use and distribute the library with any software (commercial or otherwise)
provided that you do not alter the ColorTool library in any way.

  For additional information, contact

  Jeff Glatt
  6 Sycamore Drive East
  New Hartford, NY 13413

  dissidents
  730 Dawes Avenue
  Utica, NY  13502
  (315) 797-0343