Illumination v0.19b by Daniel Parnell   25 May 2000

  The latest version of Illumination can always be found at
http://www.geocities.com/SiliconValley/Park/6797/illumination.html

  Welcome to the wonderful world of theme based windows!
Illumination allows Win32 (95, 98 and NT 4.0) users to change
their user interface to look like anything they want.
I decided to write this when I saw they Enlightenment X Windows
window manager.  I thought to myself "I'd love to work in an
environment like this".  Unfortunatly for me I have to use
Win32 at work so Enlightenment wasn't an option for me :(

  Illumnination is only at the proof of concept stage at the
moment, however I'm already beginning to make plans for a
full theme system for all window controls (however this is
a little ways off at the moment).

  When Illumination is run for the first time there is no
theme selected, so choose the "Configure" item from the Illumination
task bar icon and select a theme layout file.  Once this is
done, Illumination will make all further windows display with the
selected theme.

  Illumination now supports KDE themes.  See http://www.kde.org for
details on KDE and KDE themes.

  To stop Illumination simple right click on the icon in the task
bar and choose Exit.

  One more thing.  The first time a theme is selected nothing
will happen.  After restarting Illumination the theme should
then become visible.  Subsequent theme changes should be
automatic from then on.

NOTE:  BEFORE CLOSING ILLUMINATION MAKE SURE THERE ARE NO OTHER
       APPLICATIONS RUNNING AS THEY MAY CRASH

       AND ALWAYS REMEMBER THIS IS BETA SOFTWARE, SO I DON'T
       GARENTEE IT WONT CRASH CAUSING DATA LOSS

Daniel

daniel@oz.quests.com


**************************************
*** Information about Illumination ***
**************************************

Illumination was written using Delphi 4.0 C/S
The graphics were all stolen from variois other sources (enlightenment themes
and screen shots)

******************************************************
*** Forcing applications to use a particular theme ***
******************************************************

Create a file called THEMES.CFG in the same directory as Illumination.
Put entries in the file like the following

NOTEPAD.EXE=c:\illumination\foo\foo.lyt

This will force any application called NOTEPAD.EXE to use the theme
c:\illumination\foo\foo.lyt

Any number of entries can be placed in this file.

**************************
*** The Exclusion List ***
**************************

  The exclusion list is stored in the file EXCLUDE.CFG in the same
directory as Illumination.  It is broken up into three sections
[MODULES], [NONESTED], [WINDOWCLASSES] and [NOSIZEFIXUPS].

The [MODULES] and [NONESTED] sections contain module names (program names)
The first means NO windows created by that module will be Illuminated, while
the second means only top level windows will be Illuminated.  If an application
is having trouble with Illumination, try it in the [NONESTED] section first,
failing that put it in the [MODULES] section.

The [WINDOWCLASSES] section allows individual type of windows to be excluded.
The [NOSIZEFIXUPS] section also allows the size fixup code to be disabled for
specific window classes.

  A tool has been added to allow the module name and window class name of a
window to be determined easily called the "Window Finder".  This is accessible
under the Advanced menu on the Illumination popup menu.  Moving the cursor over
a window will display the caption, module and window class of the window under
it.  This information can then be used in the EXCLUDE.CFG file to force Illumination
to ignore windows of that type in the future.

  I would be interested in seeing the exclusion lists people come up with so I
see if Illumination can be made to work with all programs.

************************************
*** HOW DO I MAKE MY OWN THEMES? ***
************************************

  Theme files are broken up into several sections

[Images]
[Title Font]
[Inactive Font]
[Menu Font]
[Layout]
[Misc]
[Code]

  The [Images] section contains a list of image files to be used with the theme.
Each file is given an internal name and has an optional transparent color
expressed as a hex number (ie ffffff for white).
The images should be placed in the same directory as the layout file.

  The font secions are fairly self explanitary so I wont go into them in any
details.

The [Misc] section contains various extra information
There are four values currently defined in this section

WidthFixup, HeightFixup and MenuFixup.  The values in these three values
are added to the window width and height to try to overcome some more limitations
in the way windows works.

To get a zooming window effect like on a Macintosh add WindowZoom=1 to the [Misc]
section.

The most exciting value in this section is AutoExclude.  When this value is 1
then any bitmaps in the theme that have a transparent color will be used to
generate the window region.

For Example

[Misc]
AutoExclude=1
WidthFixup=88
HeightFixup=64
WindowZoom=1


  Now for the [Layout] section.  This is where the magic happens ;)
Each entry in this section describes the contents of a single rectangle
in the window and consists of the following items.

<Code> <Rect> <Normal> <Clicked> <Inactive> <MouseOver> <name>


The code section is a value from the following list

    BORDER
    BOTTOM
    BOTTOMLEFT
    BOTTOMRIGHT
    CAPTION
    ERROR
    GROWBOX
    HSCROLL
    LEFT
    MENU
    NOWHERE
    REDUCE
    RIGHT
    SIZE
    SYSMENU
    TOP
    TOPLEFT
    TOPRIGHT
    TRANSPARENT
    VSCROLL
    ZOOM
    CLOSE
    MINIMIZE
    MAXIMIZE
    NEXT
    PREV
    HELP
    TASKLIST
    RESTORE
    SAVE
    POWER
    TITLE
    SHRINK
    UNSHRINK
    SHRINKFLIP

  Some of the items will only show up if the window in question has those items
(ie MAXIMIZE items will only be displayed if the window has a maximize button).
If a code is preceeded by a ! character then it will be displayed if the window
doesn't have that type of item (this is useful to display a disabled version
of a maximize button for example).

  The code can be followed by another code that is used for visibilty checking
instead of the default style for that code.  An example of this is shown below

BOTTOMRIGHT-SIZE  BR:-16,-16;BR:-2,-2 SizeBox              SizeBox              White

This shows the bitmap SizeBox if the window in question has the SIZE style, but
used the BOTTOMRIGHT code.

The following it a little more advanced use

CLIENT-SIZE       TL:1,19;BR:-17,-17
!CLIENT-SIZE      TL:1,19;BR:-3,-1

This defines two different client areas depening on if the window can be sized
or not.

There are two special codes
    CLIENT
    EXCLUDE

NOTE:  Each layout MUST have a CLIENT area otherwise nothing will be displayed
       in the window.

  To use the SHRINK, UNSHRINK and SHRINKFLIP codes a ShrinkRect item must be
added to the misc section.  This uses the same format as the rects used in the
[Layout] section.  For example

  [Misc]
  ShrinkRect=TL:0,0;TR:0,8

  [Layout]
  SHRINKFLIP TR:-26,1;TR:-20,7 ShrinkUp ShrinkDown ShrinkInactive

  The EXCLUDE code allows rectangular regions to be removed from the window
to create non-rectangular windows.  The window region is built up from the
declared window items, however if some of the bitmaps used are transparent
then the transparent areas will need to be excluded from the window.

  The rect item describes a rectangular area in the window.

<Top Left flags>:x,y;<Bottom Right Flags>:x,y

The valid flags are
  T - y coordinate is relative to the top of the window
  L - X coordinate is relative to the left of the window
  B - y coordinate is relative to the bottom of the window
  R - X coordinate is relative to the right of the window
  S - stretch any given bitmaps
  F - tile bitmap to fit the given rectangle
  
  After the rectangle has been defined there are three optional bitmap names
correspond to the normal, clicked and inactive bitmaps.

  The name section is used with the code section to identify which forth words
are to be used with which user interface element

The currently defined methods are

    OnIdle
    OnCalcRect
    OnPaint
    OnMouseEnter
    OnMouseExit
    
to declare a method definition in the code section do the following

[Layout]
# Code  Rect              Selected    Clicked    Inactive   Over     Name
TITLE   STL:1,0;TR:-3,19  None                                       Title

[Code]

: Title::OnCalcRect
  WINDOWTEXT TEXTWIDTH 58 + WINDOWSTYLE WS_MAXIMIZE AND IF 17 + THEN @LEFT + !RIGHT ;

The [Code] section is HIGHLY EXPERIMENTAL at the moment, however once it is
finished it will allow themes to be created that don't use any bitmaps at all!

The code in the [Code] section is written in a very small subset of the Forth
programming language (for more info see www.forthinc.com or the comp.lang.forth 
newsgroup).  I chose forth because it is very small, fast and EASY TO CODE ;)
It uses reverse polish notation (anybody with a HP calculator should be able to
pick it up without any trouble).


The following is the currently defined words

Window style constants
    WS_BORDER
    WS_BOTTOM
    WS_BOTTOMLEFT
    WS_BOTTOMRIGHT
    WS_CAPTION
    WS_ERROR
    WS_GROWBOX
    WS_HSCROLL
    WS_LEFT
    WS_MENU
    WS_NOWHERE
    WS_REDUCE
    WS_RIGHT
    WS_SIZE
    WS_SYSMENU
    WS_TOP
    WS_TOPLEFT
    WS_TOPRIGHT
    WS_TRANSPARENT
    WS_VSCROLL
    WS_ZOOM
    WS_CLOSE
    WS_MINIMIZE
    WS_MAXIMIZE
    WS_NEXT
    WS_PREV
    WS_HELP
    WS_TASKLIST
    WS_RESTORE
    WS_SAVE
    WS_POWER
    WS_TITLE

WINDOWTEXT   ( - title )
  pushes the current windows title onto the stack

TEXTWIDTH  ( text - width )
  pushes the width of the piece of text on the top of the stack onto the stack
            
TEXTHEIGHT ( text - height )
  pushes the height of the piece of text on the top of the stack onto the stack

@TOP ( - top)
  gets the top of this rect

!TOP ( top - )
  sets to top of this rect

@LEFT ( - left )
  gets the left of this rect

!LEFT ( left - )
  sets the left of this rect

@BOTTOM ( - bottom )
  gets the bottom of this rect

!BOTTOM ( bottom - )
  sets the bottom of this rect

@RIGHT ( - right )
  gets the right of this rect

!RIGHT ( right - )
  sets the right of this rect

RECTTOP ( element - top )
  gets the top of the given ui element

RECTLEFT ( element - left )
  gets the left of the given ui element

RECTBOTTOM ( element - bottom ) 
  gets the bottom of the given ui element

RECTRIGHT ( element - right ) 
  gets the right of the given element

WINDOWSTYLE ( - style )
  gets the windows style

@PENCOLOR ( - color )
  gets the pen color

!PENCOLOR ( color - )
  sets the pen color

@BRUSHCOLOR ( color - )
  gets the pen color

!BRUSHCOLOR ( color - )
  sets the pen color

MOVETO ( x y - )
  moves the pen to the given position

LINETO ( x y - )
  draws a line from the pen's current position to the given position

PUTPIXEL ( x y color - )
  sets the pixel at the given position to the given color

GETPIXEL ( x y - color )
  gets the pixel color at the given position

RECTANGLE ( x1 y1 x2 y2 - )
  draws a rectangle with the given size


FILLRECT ( x1 y1 x2 y2 - )
  fills a rectangle with the given size

@RECT ( - x1 y1 x2 y2 )
  gets the current rectangle

!RECT ( x1 y1 x2 y2 - )
  sets the current rectangle

RECTWIDTH ( - width ) 
  returns the width of the current ui element

RECTHEIGHT ( - height )
  returns the height of the current ui element

WINDOWACTIVE ( - flag )
  returns non-zero if the current window is active

The following words are the standard Forth words that are defined
	: 
	;
	+
	-
	*
	/
	DUP
	DROP
	SWAP
	IF
	ELSE
	THEN
	BEEP
	DISP
	DO
	LOOP
	I
	BEGIN
	AGAIN
	UNTIL
	CREATE
	DOES
	ALLOT
	!
	@
	2/
	2*
	>R
	R>
	IMMEDIATE
	HERE
	>
	<
	=
	>=
	<=
	<>
	1+
	1-
	AND
	OR
	XOR
	NOT
	RAND
	CONSTANT
	VARIABLE

CHANGE LOG:

May 25, 2000
  - Added some more code to make sure that all window procs are unhooked when the DLL is unloaded
  
May 24, 2000
  - Added some code to try and reduce the flicker some themes have under some circumstances
  - Fixed the code used to move windows around on the screen so it doesn't
    move the cursor to the center of the caption area
  - A few other minor bugs

April 12, 2000

  - Fixed some bugs in the Forth interpreter, and fixed the Forth theme to work with the latest version of
    the theme format.
  - Moved over to Delphi 5.0

October 21, 1999

  - Added support for the newer versions of KDE.  So far I have tested 1.1.1
    and 1.2 themes, but the others should also work :)

August 18, 1999
  - Added the zooming window effect

May 24, 1999
  - Added code to handle the Alt-Space key combo and so avoid yucky screen
    problems

May 19, 1999
  - Added shrink/unshrink/shrinkflip
  - The system menu now works, although it still needs some more work

April 29, 1999
  - Fixed a couple more bugs
  - Added code to support a mouse over image.
    This also means that the OnMouseEnter and OnMouseExit forth events
    should work, although I havn't tested them
  
April 20, 1999
  - Looks like I've not been updating this.  I can't remember what I've
    done so I wont bother trying ;)
  - Added the "Auto Apply" check box
  - Added support for forcing a particular program to use a given theme
    regardless of the theme setting

January 15, 1999
  - Updated the file selector to show KDE themes

Januray 14, 1999
  - Added preliminay support for KDE themes
  - More small bug fixes

January 24, 1999
  - Fixed a few more minor display problems
  - Added support for the theme information block

January 12, 1999
  - Fixed a stack of display bugs mainly to do with the auto-exclusion code
    It now support non-stretched and tiled bitmaps properly
  - Added code to allow the theme to change instantly when a new theme is selected
  - Added the NoSizeFixups section to the exclude list
  
January 1, 1999
  - Fixed problems with TAB characters in theme files
  - Fixed redraw problems when resizing windows (well they are fixed on my machine anyway)
  - Various other small bug fixes

December 12, 1998
  - Various bug fixes
  - Fixed problem some people were having where a 217 error would stop Illumination from starting

November 28, 1998
  - More bug fixes
  - Added AutoExclusion
  
November 16, 1998

  - More menu fixes (system menu)
  - Added bitmap tiling

November 14, 1998

  - Added Enabled menu item
  - Added Exclusion list
  - Added Window Finder

November 7, 1998

  - Bug fixes
  - Added the forth

October 25, 1998

  - Wrote custom menu handling code to get rid of screen glitches
  - Added code to allow code to be given another codes style
  - Created the MacOS theme


