QDT IconDraw User Manual

Version History:
	12-28-04	Original
	01-03-05			Minor spelling/grammer fixes
	01-23-05	Vers 1.00	minor cleanups, released

Copywrite ©:
	2004-2005	James Hunkins   [JDH Software Technologies]

Website:		http://www.jdh-stech.com

Document Notes:
- {vn.nnc} in the margin indicates that this section 
pertains to a feature from this version onwards
- {future} in the margin indicates that this is a planned 
but not yet implemented feature


>> Contents <<

Introduction	

Sections	
	Loose Items	
	Command/Format	
	Design Window	
	Real Time Icon Display Window  [ RTID ]	
	Color Choice Window	

Functions and Controls	
	Loose Items	
	Icon Size : Normal vs Small	
	File Handling	
		Load/Save	
		Close/Return [ ESC ]	
		Clear	
		Import	
		Copy	
	Icon Name	

Color Usage and Drawing	
	Picking a Color	
		Palette Organization	
	Setting Pixels	
	Icon Design Tips	
		Background versus Edge Colors	
		Transparency	

Icon Sharing	

Appendixes	
	Appendix A : QDT Icon 256 Color Palette	
	Appendix B: Software License and Warranty	
	Appendix C:	Additional Manuals and Technical Documents	
		User Manuals	
		Technical and Other Documents	
	Appendix D: Other Included Software	



>> Introduction <<

One of the cool things with any desktop environment is the 
graphics. Whether a user has the talent for designing cool 
icons or would rather just 'borrow' some of the thousands of 
publicly available ones, the idea is to use icons to make 
the desktop both pleasing to look at and easier to get 
around in. The human mind is very graphically oriented in 
the way it processes data. Meaningful, pleasant, well placed 
icons have a major impact on the usability of a computer's 
desktop.

IconDraw is a utility that allows the QDT user to import 
icons from other sources to the QDT format, to modify the 
imported icons, or to totally design new icons from scratch.  
The QDT format is specific to QDT only and was designed to 
reduce memory/disk space usage.



>> Sections <<

Loose Items

The row of items along the top of the display are loose 
items with standard QL functionality.

Command/Format

This area is on the left. Here one can set the size of the 
icon, do icon file operations, and name the icon.

Design Window

This is the large window in the center where the user 
draws/designs the icon itself. In this window, every square 
is equal to a pixel (a dot on the screen). The white squares 
with the dark center in this window represent transparent 
pixels. Any thing behind the icon will show through them.  
All other colors are represented as solid colored squares.

Real Time Icon Display Window  [ RTID ]

As the user designs the icon, its actual sized image is 
drawn in parallel in the upper right hand corner window.

Color Choice Window

The window in the lower right corner (the colored blocks) 
allows the user to select the color used for both the left 
and right mouse buttons. Approximately one half of the 
available colors are shown at one time as is shown in <Fig
not included>. The arrowed rectangle in this window switches
the color selection to the alternate group of colors. Chosen
colors for both mouse buttons are displayed just above this
window.

Functions and Controls

If a control item has text with an underscored letter, then 
that letter can be used as a Hot Key to select that item 
instead of using the cursor and mouse. buttons.

Selection terminology and alternates are given here:

	LMB = single click with the left mouse button
	  . alternate method is the [SPACE] bar instead of the 
		button
	RMB = single click with the right mouse button
	  . alternate method is the [SPACE] bar instead of the 
		button

Loose Items

	Move	[CF4]	standard QL Move
	Resize	[CF3]	not implemented at this time
	Refresh	[CF2]	not implemented at this time
	Sleep	[CF1]	standard QL Sleep
	Help	[F1]	not implemented at this time
	Esc	[ESC]	closes IconDraw and gives an option to 
			save
	RTID	[F4]	cycles through background colors, not 
			implemented at this time

Icon Size : Normal vs Small

Icons in QDT come in two sizes; Normal = 40x40 pixels and 
Small = 20x20 pixels.  The highlighted button here 
represents which mode is currently active.  Clicking on the 
non-highlighted button will switch the size mode and redraw 
the Design and Real Time Icon Display windows, showing the 
correct number of pixels across and the current design, if 
any, for that size.

For most people, normal will be the preferred size as it 
allows the user to get the most detail in the icon, making 
it easier to see and quicker to recognize.

The small size has the advantage of allowing the user to 
squeeze as much as possible onto the desktop.  Be aware that 
this, if improperly used, can create a very cluttered desk 
and negatively impact the usability of the computing 
environment.

The small icons are also likely to be more commonly used in 
the planned File Manager.
 
File Handling

Load/Save

These options bring up the QMenu file load or save window as 
is appropriate.  The menu will default to the QDT icon 
location which is kept in the system variable QDTICON_LOC.  
The directory can be changed if needed.

It will also default to only showing files with the _ICON 
suffix (required by QDT).  This can be changed.

QDT will NOT recognize any ICON without the ICON suffix or 
not in the set directory location.  Icons stored in other 
locations can be edited and then moved and renamed as 
needed.

Saving is somewhat intelligent.  IconDraw will only save a 
size if it has one or more pixels that is not transparent.  
Therefore, if the user does not draw one of the sizes, the 
resulting Icon file will be smaller in size.

If the user chooses save when both sizes are empty, then the 
save request will be ignored.

Any modified Icon will not be visible in QDT until a restart 
unless it had not been loaded yet for the size indicated.  
An icon will have been loaded if it was in the  Desktop_QDT 
file at startup or was loaded through a notebook after that.

The default icons are used if an icon with the size 
requested can not be found or as the default when adding a 
new object.  These default Icons can be modified with 
IconDraw but the saved versions will not be used until they 
have been imported into the QDT base with the separate Icon 
Manager.  The default ICON names are:

	folder_c	folder_o	xfolder_c
	text		graphic		unknown
	prog



Close/Return [ ESC ]

This button (or pressing the [ESC] key) will close IconDraw.  
An option menu pops up to give possible responses to the "OK 
to Quit?" question of:

	Yes Ð no save		[Y]
	Yes Ð with Save		[S]
	No			[N]

Clear

Clear is pretty straight forward.  It will clear {set all 
pixels back to transparent} either the size being displayed 
or both sizes, depending on the choice made.  Clear brings 
up an option window with buttons representing:

	Abort	[A]
	Normal  [N]   or   Small  [S]	{ matches the current 
					  mode }
	Both 	[B]

Import

This feature allows importation of different graphics 
formats.  Obviously, sizes and colors that match the QDT 
requirements will result in accurate representations after 
the import.  Any variances will cause variances in the 
imported image that may require touching up.

The currently supported formats are:

Table 1 : Import Formats

  Format	   Vers Sizes	Rules			Scheduled
							Availability
  Windows BMP		20x20 	Non-inverted 24 bit	in development
					40x40		non-compressed
  Windows ICON						planned


When creating a base image in an outside graphical 
environment for import into QDT as an ICON, please be aware 
of the QDT Icon color palette.  Refer to Appendix 1 for more 
details.  A color swatch of this palette for Adobe Photoshop 
and compatible programs is available on the QDT website.  A 
full listing of the exact colors in this palette are 
available in the Icons technical manual listed in the 
Appendix section.  Use of colors outside of this palette 
will result in variances in the quality of the import.

Copy

This will attempt to copy the currently displayed size into 
the other size, expanding or compressing the pixels as is 
called for.  It will replace any pixels already drawn.

Icon Name

This is likely to be an overlooked item until users get 
their hands on the Icon Manager being developed or start 
using the upcoming Theme capabilities.

Many icons will be parts of sets, which the Icon Manager 
will recognize.  The reasons to use shorter names which 
likely will be different from the actual file names are:

	¥	the display of the icons in the Icon Manager will be 
		more readable
	¥	having icons of the same name but in different sets 
		will allow the Theme capabilities to simply swap icons 
		set quickly and nearly transparently.

For example, if using the file name for the KWB series, for 
the Just Words open folder, the user  could be looking at a 
name such as kwb-fc-JustWords or the simpler fcJustWords 
(kwb set, folder closed, apps) or even fc-JW.  They could 
then have several Icons in different designs called fc-JW 
which would be physically in different Icon sets.  Switching 
themes would use the same fc-JW icon name, just picking the 
icon from the different sets.  This will allow, if the mood 
strikes,  for going from a simple grey tone to a Garfield to 
a Candy Colored to whatever theme at the press of a few 
keystrokes.

The default name comes up as Unnamed for a new icon or if a 
name is not specified in the original file.

When saving a new Icon, the name is used as the basis for 
the saved name, which can be changed during the save 
process.


>> Color Usage and Drawing <<

In order to save room but give a fairly effective color 
palette, QDT uses approximately 256 colors and shades of 
grey for Icons.  Please refer to Appendix 1 for more details 
on the QDT Icon Palette.

Picking a Color

Two colors can be active at one time, each being assigned to 
the left or right mouse buttons.  The current colors are 
displayed just above the Color Choice Window as is shown in 
<Fig not included>.

To choose a new color for a mouse button, simply click on 
that color in the palette offered with the preferred mouse 
button and it will appear in the blocks above the palette 
(LMB or RMB) to confirm the selection.

To choose Transparent, click on the rectangle with the text 
"TRA" in the lower right hand corner of the palette window.  
The associated block above will be redrawn in black with a 
white border to verify that transparent. is now active.

To get the alternate palette page, click on the rectangle 
with the arrow next to the Transparent rectangle and the new 
set of colors will appear.  This selection will toggle back 
and forth between the two palette pages.

Palette Organization

The palette is displayed in two pages and is organized to 
help find like colors quicker.

The QL's 6 standard colors are displayed on both palette 
pages in the bottom row, left side.  Page 1 has white in the 
center, black to the right of the QL colors, and 4 shades of 
grey above the black.

Page 1 also groups the mid and light ranges of the colors 
along the left and top side, with a mixture of other colors 
in the lower right.

Page 2 has the darker shades of color laid out almost as if 
it was the back side of a surface that had page 1 on the 
front, wrapping around the edges.  Page 2 also has 25 shades 
of grey plus black and white, allowing for some fairly 
smooth shading, etc.

Please note that not all systems will display the grey 
shades as well as others so some Icon designs that take 
advantage of these may not look as nice on the lower color 
resolution systems.

Setting Pixels

To set a pixel of an icon, after the color is chosen, simply 
place the cursor over the pixel to be set and click with the 
appropriate mouse button.

To draw a line, a useful technique is to position the cursor 
and then, holding down either the [SPACE] bar (LMB 
equivalent) or the [RETURN] key  (RMB equivalent), use the 
arrow keys to move the cursor.  If going to fast with this, 
a few pixels may be skipped but they can be touched up 
later.  The cursor arrow keys can also be held down for 
several pixels, let the cursor key up momentarily and then 
repress it.  This will help avoid the missed pixels.
Icon Design Tips

Background versus Edge Colors

It is a good idea, at least until Alpha transparency is 
brought to QDT, to be very careful on the Icon edges.  A 
useful tip is to always edge the Icon with a distinctive 
color and/or border.  The normal size icon in <Figs not
included> is done this way and looks good with both light
and dark backgrounds.

The reason for this recommendation is that, while one icon's 
edge may look great on a dark or light field, when putting 
it against the opposite type of background, suddenly it 
looks like garbage instead of the beautifully designed work 
of art that was labored over. 

For example, if a light background is used, a bit of grey 
shading along the border may look great, smoothing the 
transition (commonly done by advanced image editing 
software).  But place this edging on a dark background and 
those lighter shades of grey will no longer look like a 
transition but instead like little lights going off or a 
band of brightness.  The small icon in <Fig not included>
were done this way.  While this icon looks very nice on the
light background in <Fig not included>, the edge around it
can definitely be seen in <Fig not included> Ð not a nice
thing.

Transparency

The use of transparent pixels can be fun but it can also get 
ugly if not used right.  A recommendation is to restrict 
transparent areas to either the outside of the icon or to 
large areas within.

The reason for this is two fold.  QDT displays icons as 
actual windows that can sit on top of other windows.  If the 
window underneath the icon with transparency has a lot of 
small detail, that will tend to blend into the icon and make 
the icon hard to see or confusing to look at.  By avoiding 
small areas of transparency and using good edging, the icon 
will be able to better stand out, even against a cluttered 
backdrop.

The other problem is that, at this time, we don't have a way 
of automatically refreshing icons after windows move out 
from under them.  If a window moves from underneath, any 
transparency in the icon will continue to show the old 
window pixels until a manual QDT screen refresh is issued.  
This may be fixed in the future but would take a very 
complex bit of programming so is not high on the priority 
list.


>> Icon Sharing <<

A large part of the QL community spirit is the sharing 
between its members.  With this in mind, a space will be set 
up on the QDT website for sharing icons.  Instructions for 
submitting icons (single or sets), rules of use, etc. will 
be posted, along with download locations for any icons 
accepted.

JDH Software Technologies has the final say and right of 
refusal to post any Icon for sharing for any reason, 
especially is there is any question of the ownership of the 
original graphics.

With that all said, please do share the little works of art 
so that we can all enjoy a more colorful and efficient 
computing environment.

The QDT website can be located from the JDH Software 
Technologies home page at:

	http://www.jdh-stech.com



>> Appendixes <<


Appendix A : QDT Icon 256 Color Palette

For the SMSQ/E hi-color mode, the original QDT icon palette 
was taken directly from the default 256 color palette 
supplied by SMSQ/E and the extended colors capability. The 
256 versus 16 million color selection was chosen to save two 
bytes per pixel in stored icons. Unfortunately, when viewing 
the original palette if displayed from colors 0 to 254 (255 
is reserved by QDT for transparency), the color spread is 
not ideal for drawing and the arrangement made it difficult 
to find related colors.

To fix this QDT's implementation now gives a wider range of 
colors outside the original 256 color palette but preserves 
the original byte per pixel size savings. The icons will 
continue to store the data using a 256 color palette. 
However, when drawing the icons, the palette will be 
remapped by QDT into the full 24 bit real color thru an 
internally stored QDT Icon Palette.

The color selection of the new palette is derived from what 
are known as the internet safe colors. This is simply a 
mapping of 216 colors from the standard 16 million using a 6 
x 6 x 6 grid. By taking each of the three colors and 
changing them from 0 to 255, incrementing them by 51 each 
time, 216 colors are achieved. The details can be seen at 
the website:

	http://the-light.com/colclick.html 

In addition to this set of standard colors, QDT includes a 
total of 25 shades of grey. The 216 original palette only 
includes 4 shades. It should be noted that not all SMSQ/E 
capable systems may display all the additional grey shades 
equally and some detail may be lost if the extra shades are 
used.

IconDraw breaks up the palette into two different windows. 
It loosely takes the standard cube method of displaying the 
palette (see above web page for details) and remaps it into 
the two individual square windows. Each section within a 
window will have a light grey divider line to help visually 
separate each color grouping.

The most common of the 216 palette are mapped into both 
pages on the left and upper edges, with the bulk and 
brighter colors on page 1 (see below). The 6 primary colors 
are duplicated on each page in the lower left hand edge. On 
page 1 in the lower middle vertical, the 216 palette based 
grey shades are available. The same grey shades plus the 
additional shades from the QDT icon palette are displayed in 
about the same area on page 2. The blank areas in the images 
shown here (lower right) are used by IconDraw for 
'transparent' and for page switching. The remaining colors 
from the 216 internet safe palette are grouped in the 
remaining sections on both pages, approximately in the 
middle right areas.

Both pages of the new QDT Icon palette are displayed here. 
For a comparison, the original palette page 1 is displayed 
to the right of the two new pages.


Appendix B: Software License and Warranty

The following is a direct copy of the license that is 
included with the QDT package.  It can be read from within 
the QDT installer where the user agreement is required 
before the installation can be continued.  The text can also 
be found in the QDT DOCS_ directory as "license_txt".

=========================
QDT (QL Desktop) License
All Official Full Release Versions

Copyright © 2004-2005 James D Hunkins
                   JDH Software Technologies
  -> All rights reserved.

This is a legal agreement between you and JDH Software 
Technologies (James Hunkins) covering your use of QDT and 
any programs included with the original package (the 
"Software"). Be sure to read the following agreement before 
using the Software.

BY USING THE SOFTWARE (REGARDLESS IF YOU HAVE REGISTERED THE 
SOFTWARE OR NOT), YOU ARE AGREEING TO BE BOUND BY THE TERMS 
OF THIS AGREEMENT. IF YOU DO NOT AGREE TO THE TERMS OF THIS 
AGREEMENT, DO NOT USE THE SOFTWARE AND DESTROY ALL COPIES IN 
YOUR POSSESSION.

The Software is owned by JDH Software Technologies and is 
protected by United States copyright laws and international 
treaty provisions. Therefore, you must treat the Software 
like any other copyrighted material (e.g., a book or musical 
recording).

Redistribution of this release package in any form is not 
permitted.  Distribution is only allowed through authorized 
distributors as per agreements made exclusively with JDH 
Software Technologies.

Use of this package is permitted by the original purchaser 
only for their own personal use. Separate copies can be put 
onto different computers as long as only one copy is in use 
at one time (the book usage concept) and all copies are only 
used by the purchaser of this license and/or his immediate 
household or organization.

Distribution of any additional included software not 
developed by JDH Software Technologies is controlled as per 
documentation included with all such software.

Any usage outside of this described model must receive 
specific written authorization from JDH Software 
Technologies.

The Software and its related documentation are provided "AS 
IS" and without warranty of any kind and JDH Software 
Technologies expressly disclaims all other warranties, 
expressed or implied, including, but not limited to, the 
implied warranties of merchantability and fitness for a 
particular purpose. Under no circumstances shall JDH 
Software Technologies be liable for any incidental, special, 
or consequential damages that result from the use or 
inability to use the Software or related documentation, even 
if JDH Software Technologies has been advised of the 
possibility of such damages. In no event shall JDH Software 
Technologies' liability exceed the license fee paid, if any.

This Agreement shall be governed by the laws of the State of 
California. If for any reason a court of competent 
jurisdiction finds any provision of the Agreement, or 
portion thereof, to be unenforceable, that provision of the 
Agreement shall be enforced to the maximum extent 
permissible so as to effect the intent of the parties, and 
the remainder of this Agreement shall continue in full force 
and effect.

This software package may include licensed code from other 
developers as noted below along with voluntary contributions 
made by many individuals.  For more information on JDH 
Software Technologies, refer to the website "http://www.jdh-
stech.com".

Graphics/Color Development Support:
  Thorsten Herbert, Italy

Additional Icons By:
  Roy Wood, England

=========================
Included licensed code in non-demo version : included in the 
QDT pricing

  QMenu menu extensions
    Copyright© 1989-97 Jochen Merz Software

=========================
Included Non-licensed code : no charge distribution

  FI2config_obj     FileInfo2
  FileInfo2_bin
  FileInfo2_txt
  FI2config_help
    Copyright © 1993-1999 Thierry Godefroy

  MenuConfig 02
    Copyright © 1992-2003 Jochen Merz Software


Appendix C:	Additional Manuals and Technical Documents

As of the latest update of this manual, the following 
documents are either available or in preparation.


User Manuals

	QDT Quick Start Guide

	QDT User Manual

	QDT Installer User Manual

	QDT Notebook User Manual


Technical and Other Documents

	QDT Icons Technical Reference

	QDT: Icon Color Swatch for Adobe Photoshop


Appendix D: Other Included Software

See the QDT User's Manual for a list of all licensed and no 
cost included software used by IconDraw and the other QDT 
components


QDT IconDraw User Manual			Last Updated: 1/24/05
Copyright © 2004-2005	JDH Software Technologies	James Hunkins