Short Manual For The Color-Icon-Routines - Date: 06/25/97
---------------------------------------------------------


First of all, read the following: You use the programs and routines 
found in this archive and all applications which make use of them at 
your own risk! I cannot guarantee for their full functionality and do 
not acceppt and liability or responsibility for any direct or indirect 
damage that may arise, either financial, material or any other kind 
from either the use or misuse of the programs/routines/applications or 
their uselessness for a specific purpose.

Now to the more pleasing things (if anybody's still reading...)


Introduction
------------

With the publication of the Falcon030, Atari introduced a new AES which 
is capable of displaying color icons. Unfortunately, resource files 
containing color icons can only be used on the Falcon or with 
MultiTOS/MagiC 3, so their benefit is quite limited. But with the 
routines found in this archive, you are able to use color icons in your 
own C-programs independent of the version of the AES.


Usage
-----

The usage is quite simple: If you want to use a resource file 
containing color icons in your program, you simply have to replace the 
calls rsrc_load, rsrc_gaddr and rsrc_free by rsc_load, rsc_gaddr and 
rsc_free and add an #include "new_rsc.h" to your sourcecode. The rest 
is automatically done by the routines, i.e. a dialog with color icons 
can then simply be displayed via objc_draw. Of course, you have to add 
drawcicn.c and new_rsc.c to your make/project file to ensure the new 
routines are available for the linker. The sourcecode of the 
demonstration program (demo.c) serves as a short example. The only 
difference between rsc_load and rsrc_load (besides the handling of 
color icons, of course) is that the data of monochrome icons and 
bitmaps is converted into device dependent format (I doubt that anyone 
has ever done this her/himself...)

If you want to use embedded resources instead of a resource file, you 
can display color icons as well. In that case, you have to include 
"drawcicn.h", open a virtual VDI-workstation and call init_routines 
with the new handle as the parameter. After that, all object trees 
contatining color icons have to be converted via init_tree; they are 
then ready to be displayed with objc_draw. At the end of your program, 
don't forget to close the workstation and call deinit_routines to free 
all memory allocated for the color icons. You only have to add 
drawcicn.c to your make/projectfile because you don't need the routines 
to handle extended resource files.

The drawing of the color icons is achieved by using USERDEF-objects. 
When a resource file is loaded with rsc_load or an object tree is 
prepared with init_tree, all color icons are converted into USERDEFs, 
as far as suitable data for the current color depth is found. Icons 
with 2 or 16 colors will also be used in resolutions with more colors, 
even in Hi/Truecolor. All color icons without usable data for the 
current color depth will be converted into simple monochrome icons. The 
same happens when there is memory shortage during conversion. Init_tree 
returns zero to indicate that one or more color icons could not be 
transformed successfully (there's no such indication when using 
rsc_load, sorry).

If you need information about the dimensions of a color icon or want to 
change the text (btw, the format of the extended resource files only 
allows 12 characters for the icon text), you have to look at the object 
type, because the color icon was converted into either a G_USERDEF or a 
G_ICON. The following function automatically returns a pointer to the 
correct ICONBLK:

ICONBLK *get_iconblk(OBJECT *tree, WORD obj)
{
	if ((tree[obj].ob_type & 0xff) == G_USERDEF)
	{
		return(((DRAW_CICON *)tree[obj].ob_spec.userdef->ub_parm)->
			original->monoblk);
	}
	else
		return(tree[obj].ob_spec.iconblk);
}

Of course, this function only works for objects which have been color 
icons before the conversion.


Information On The Sourcecode
-----------------------------

The sources have been written using Pure C and can therefore be 
compiled with it without changes, even with the MiNT-library (in the 
latter case, you have to copy the Pure C-include files aes.h and vdi.h 
to the include directory of the MiNTLib). Principally, the adaption for 
other ANSI-like compilers shouldn't be too difficult. If you have 
succeeded in doing so for your compiler, please send the new sources 
(adapted with preprocessor commands) or a diff to me. Don't forget to 
tell me the date of the original file(s) when you send a diff!

Many thanks to Mario Becroft, who has adapted the routines for the use 
with Lattice C, as described above.

The source new_rsc.c may also serve as a basis for a converter that 
creates sourcecode for a certain programming language out of a resource 
file which can then be included directly into the program.

The sourcecode is fully documented in (poor) English. If you have 
questions (either of technical or lingual nature), feel free to contact 
me.


Copying And Using
-----------------

The routines may be freely distributed, if you regard the following 
points:

- No file may be altered, added or removed without my permission
- drawcicn.[ch]+convert.s and new_rsc.[ch] may also be distributed 
  without this documentation, but always all corresponding files 
  together. I recommend to distrbute new_rsc together with drawcicn, 
  since it refers to routines only found in drawcicn.
- This manual and the demonstration program may only be distributed in 
  the original package, which contains two files: archive.lzh and 
  archive.sig. The first one includes the following files: demo.lzh - 
  archive with the demo program (demo.app, demo.c, demo.h, demo.hrd, 
  demo.prj und demo.rsc), drawcicn.lzh - archive with the routines for 
  converting and displaying color icons (drawcicn.c, drawcicn.h and 
  convert.s), new_rsc.lzh - archive with the routines to use extended 
  resource files (new_rsc.c and new_rsc.h), and, last not least, 
  manual.eng and manual.ger. The .sig-file is a PGP-signature for 
  archive.lzh to give you a possibility to check the authenticity of 
  the files. Send me an EMail to the address found below to receive my 
  public key.

You may use my routines in your own productions without paying any fee, 
but you have to make a note, either in the documentation or in the 
program itself, that you've used my routines and that they were written 
by me. Furthermore, I'd appreciate if you'd honor the work I've put 
into this routines by sending a donation (material or financial). See 
the next section for my bank account. Thank you!


Contacting The Author
---------------------

I you have any questions, want to report a bug, make a suggestion, send 
me the adapted sourcecodes for the use with your compiler or get my 
public PGP key, please contact me. My address:

Thomas Binder
Johann-Valentin-May-Strasse 7
64665 Alsbach-Haehnlein
Germany

Phone: +49 62 57 / 6 43 04

InterNet: binder@rbg.informatik.th-darmstadt.de
           or
          gryf@hrz.th-darmstadt.de
MausNet: Thomas Binder @ HD (No Binaries, no mails > 16K!)
IRC: Gryf

Dresdner Bank AG Frankfurt am Main
Account-No.: 9 024 050 00
Sort code: 500 800 00


History
-------

See the sourcefiles for a detailed history!


I hope you have success in using my color-icon-routines!
