                                Toolbar v1.2b
                                =============

Contents
========

1. Introduction
2. Notice
3. File List
4. Requirements
5. Installation
6. Usage
7. Configuration Files
  7.1. Caption Font
  7.2. Font Color
  7.3. Destination
  7.4. Insert Text
  7.5. Section Labels
8. Credits
9. Release Notes
10. To Do List
11. Known Problems

-----------------------------------------------------------------------------
1. Introduction
===============

Toolbar provides a way to add a customized floating toolbar to any 
application.  When a button is pressed a pre-defined sequence of 
keystrokes is sent to the desired window.  All options for the buttons 
and what they do may be altered within the configuration file.  Toolbar 
was inspired by the floating toolbars available in WinTeXShell, 
(http://www.physik.uni-bielefeld.de/experi/d3/persons/struve/texshell/) 
a nice freeware LaTeX editor, and by my inability to remember LaTeX 
commands.  (If you're interested, LaTeX is a "document preparation 
system"--like a word processor but without the WYSIAYG (What You See Is 
All You Get) feature/restriction.)

Although motivated by LaTeX, Toolbar is useful in many applications,
from source code editors to web page editors to web browsers.

-----------------------------------------------------------------------------
2. Notice
=========

Toolbar is free software.

There is no warranty for damages caused by using this software.  Toolbar 
sends keystrokes directly to the computer.  If not used properly this 
could corrupt or erase important information.  You have been warned.

Without written permission from the author (Rik Blok), you may not
distribute modified packages of this software, and may not distribute
this software for profit.

Before you send requests, questions and bug reports to the author,
please carefully read this file.  However, feedback is appreciated.

You may find the latest version of this software at
http://rikblok.cjb.net/files.html#Toolbar
(The address may be changed in future.)

Rik Blok
blok@physics.ubc.ca
http://rikblok.cjb.net
August 29, 2000

-----------------------------------------------------------------------------
3. File List
============

Pushkeys.hlp  - help file with definitions of keystrokes, etc.
ReadMe.txt    - this file
Source.zip    - source code (Borland C++Builder v1.0)
Toolbar.exe   - the main program
ToolbarG.exe  - program recompiled for German keyboard
samples\*.ini - sample Toolbar configuration files

-----------------------------------------------------------------------------
4. Requirements
===============

Supported operating systems:

	MS-Windows 95/98/Me
	MS-Windows NT 3.51 and 4.0

This software has successfully been tested on a Pentium 3 computer running 
Windows Me and a Pentium II running Windows NT 4.0.  It may (?) also run 
in the Windows 3.x environment if the Win32s extension has been 
installed.

-----------------------------------------------------------------------------
5. Installation
===============

Extract and copy all files to a single directory.  The configuration 
files (*.ini) are optional (but recommended).  

This program does not create any other files or modify the computer in 
any way.

To uninstall simply remove all installed files.

-----------------------------------------------------------------------------
6. Usage
========

Command-line:

	Toolbar.exe [path\]config[.ini]

where:

	[path\]config[.ini] (required) - a toolbar configuration to load.  
	The path is optional as is the extension if it is ".ini".  If an 
	absolute path is specified (with a drive letter or a leading "\") 
	then only that path is searched.  Otherwise the relative path from 
	the current directory is searched first and, if not found, the 
	relative path from the application directory (where Toolbar.exe 
	resides) is searched.  Finally, if still not found the Windows 
	folder is searched.

Examples:

	Let's assume Toolbar.exe is in "C:\Utilities\TB", the current 
	working directory is C:\My Documents", and the Windows directory is
	"C:\Windows".  Then the following commands will search for

	Command                             Search
	-------                             ------
	Toolbar.exe "C:\Other Path\greek"   C:\Other Path\greek.ini
	Toolbar.exe greek                   C:\My Documents\greek.ini
	                                    C:\Utilities\TB\greek.ini
	                                    C:\Windows\greek.ini
	Toolbar.exe LaTeX\greek             C:\My Documents\LaTeX\greek.ini
	                                    C:\Utilities\TB\LaTeX\greek.ini
	                                    C:\Windows\LaTeX\greek.ini

Toolbar is intentionally designed to quit if run again while still 
running (if the same configuration file is specified).  This allows it 
to act as a toggle when placed on an editor's toolbar/menu.  Click once 
and the Toolbar is displayed, click again and it is removed.

-----------------------------------------------------------------------------
7. Configuration Files
======================

The configuration files (*.ini) tell the toolbar what buttons to display 
and what actions to take when a button is pushed.  To modify the 
functionality of a toolbar you must edit the configuration file manually 
(with Notepad, for example).  (If anybody writes a graphical 
configuration file editor please email it to me.  Thanks.)  

The configuration files are standard Windows .INI files with sections 
(lines denoted by "[Section Name]"), keys (denoted by "variable=value"), 
and comments (denoted by "; ignores everything after the semi-colon"). 

The configuration files can be shared between computers and should 
function properly with little/no modification.  If you think you have a 
good configuration file, feel free to send it to me and I'll post it on 
my web page or bundle it with the next release of Toolbar.

Each Toolbar configuration file has the following required sections and
keys (note: semi-colons indicate comments and are not supported in 
actual configuration files.  To get this sample to work, remove the
comments.):

------ begin sample configuration file ------

[Toolbar]
Title=Toolbar Caption
ButtonSize=25            ; minimum height/width of buttons (in pixels)
ShowHints=1              ; 1=show hint when mouse idle over button / 0=don't
CutAndPaste=1            ; 1=send ctrl-x before and ctrl-v after keystrokes / 0=don't
Destination="Some Title" ; title of window to send keystrokes to (see Section 7.3 below)
StayOnTop=1              ; 1=stay on top of other windows / 0=don't (optional)
TaskbarButton=0          ; 1=display application button on taskbar / 0=don't (optional)
Sleep=1                  ; # milliseconds to pause between keystrokes (>=0, default=0)

[Button1]                ; a separate section for each button (see Section 7.5 below)
Hint=hint for button 1
InsertText="text to send to window when button 1 pressed" ; (see Section 7.4 below)
Font=Times New Roman,10,I,0,clBtnText,0 ; caption font (see Section 7.1 below)
Caption=caption          ; text to display on button face (using Font)

[Button2]
Hint=hint for button 2
InsertText="text to send to window when button 2 pressed"
Font=Symbol,10,,0,clBtnText,0
Caption=S                    ; show greek letter Sigma (summation symbol)
Destination=Another window   ; override default destination

[TToolbarMainForm]
; Saves positioning and sizing information between runs.
; This section is optional and will be generated automatically when the 
; Toolbar is moved or resized.

------- end sample configuration file -------

  ---------------------------------------------------------------------------
  7.1. Caption Font
  -----------------

	The caption font consists of 6 values separated by commas.  The
	values represent:

	Position	Type     Description                   	Example
	--------	----     -----------                    -------
	       1	text     family                         Times New Roman
	       2	integer  size                           10
	       3	text     styles ("B"=bold, "I"=italic,  BI
	        	         "U"=underline, "S"=strikeout)
	       4	integer  pitch (0=default, 1=fixed,     0
	        	         2=variable)
	       5	text     color (see 7.2 below)          clBtnText
		   6	integer  ignored.  Use 0.               0

	The above example would be "Font=Times New Roman,10,BI,0,clBtnText,0".
	
  ---------------------------------------------------------------------------
  7.2. Font Color
  ---------------

	The color of the font may be a blue-green-red hexadecimal string 
	preceeded with 0x (for example, "0xFF0000"=blue, "0x00FF00"=green, 
	"0x0000FF"=red), or one of the following pre-defined colors:

	clBlack        	clMaroon
	clGreen        	clOlive
	clNavy         	clPurple
	clTeal         	clGray
	clSilver       	clRed
	clLime         	clYellow
	clBlue         	clFuchsia
	clAqua         	clWhite
	clScrollBar    	clBackground
	clActiveCaption	clInactiveCaption
	clMenu         	clWindow
	clWindowFrame  	clMenuText
	clWindowText   	clCaptionText
	clActiveBorder 	clInactiveBorder
	clAppWorkSpace 	clHighlight
	clHighlightText	clBtnFace
	clBtnShadow    	clGrayText
	clBtnText      	clInactiveCaptionText
	clBtnHighlight 	cl3DDkShadow
	cl3DLight      	clInfoText
	clInfoBk       	clNone

  ---------------------------------------------------------------------------
  7.3. Destination
  ----------------

	You can optionally set the title of the destination window to send 
	the keystrokes to with the "Destination=" key in the "[Toolbar]" 
	section of the configuration file.  You can also override the 
	destination for individual buttons by specifying the "Destination="
	key within a button's group.

	This string does not match the title exactly but rather uses regular 
	expressions, a powerful way to match complex strings.  The following 
	is an excerpt from the Borland C++Builder help file:

	------ begin excerpt ------

	Regular expressions are characters that customize a search string. 
	The regular expressions that C++Builder recognizes are:

	Character	Description

 	^	A circumflex at the start of the string matches the start of a 
 	line.

 	$	A dollar sign at the end of the expression matches the end of a 
 	line.

	.	A period matches any character.

	*	An asterisk after a string matches any number of occurrences of
 	that string followed by any characters, including zero characters. 
 	For example, bo* matches bot, bo and boo but not b.

 	+	A plus sign after a string matches any number of occurrences of 
 	that string followed by any characters except zero characters. For 
 	example, bo+ matches boo, and booo, but not bo or be.

	[ ]	Characters in brackets match any one character that appears in 
	the brackets, but no others. For example [bot] matches b, o, or t.

	[^]	A circumflex at the start of the string in brackets means NOT. 
	Hence, [^bot] matches any characters except b, o, or t.

	[-]	A hyphen within the brackets signifies a range of characters. 
	For example, [b-o] matches any character from b through o. 

	{ }	Braces group characters or expressions. Groups can be nested, 
	with a maximum number of 10 groups in a single pattern.

	\  	A backslash before a wildcard character tells the Code editor to 
	treat that character literally, not as a wildcard. For example, \^ 
	matches ^ and does not look for the start of a line.

	------- end excerpt -------

	To send to any window (whichever window was active before the user 
	pressed a Toolbar button) just delete the "Destination=" key in the
	configuration file or set it to a blank string ("").

	The following examples demonstrate how the Destination key might be 
	used:

	Destination=""                      ; match previously active window
	Destination="^UltraEdit-32 - \["    ; match window starting with "UltraEdit-32 - ["
	Destination="^Untitled - Notepad$"  ; match "Untitled - Notepad" exactly
	Destination=" - Notepad$"           ; match window ending with " - Notepad"

  ---------------------------------------------------------------------------
  7.4. Insert Text
  ----------------

	Toolbar is basically just a front-end for the excellent PushKeys
	utility.  As such, it uses all the same keystrokes and notation
	and this information is available in the help file "PushKeys.hlp"
	in the root folder.

	The only changes from the help file are that {SLEEP} accepts
	decimal amounts for millisecond timing and the addition of
	the {EMPTYCLIPBOARD}/{EMPTYCLIP} keystroke to empty the 
	clipboard.

  ---------------------------------------------------------------------------
  7.5. Section Labels
  -------------------

	Buttons are defined by the section labels "[Button#]" where the #s
	are sequential numbers, beginning with one.  Make sure you define
	the sections with an unbroken sequence of numbers or Toolbar will
	be unable to find all of the buttons.  Toolbar also requires that
	InsertText be a non-empty string or it will assume the sequence
	has been broken.

-----------------------------------------------------------------------------
8. Credits
==========

This program was made possible by the generous sharing of program
segments by various experts.  Thanks to:

	Fedor Koshevnikov <fkozh@usa.net>, Igor Pavluk <ipavluk@usa.net> and
	Serge Korolev <korolev@usa.net> for their TFormStorage component
	(part of the RxLib library) <http://rx.demo.ru>

...and...

	Axel Friedrich <axel.friedrich@operamail.com>
	for the German keyboard code in Pushkeys

...and...

	PUSHKEYS 1.0 for C

	original version 1.0 for Visual Basic
	Copyright by Data Solutions Pty Ltd (ACN 010 951 498)
	All rights reserved.
	Email for info: clatta@ozemail.com.au

	Ported to C by Alexander Frink (Alexander.Frink@Uni-Mainz.DE) January 1998.

Toolbar is predominantly a shell for PushKeys, an excellent utility
which sends keystrokes directly to the foreground window.  Included in
the Toolbar source code (source.zip) is the revised version of PushKeys
(C version) with the following changes:

	v1.0e	Rik Blok <rikblok@mail.com> August 29, 2000
		- allows setting of millisecond delay between keystrokes
		with global variable PushKeySleep=... (>=0, default=0).
	v1.0d	Rik Blok <rikblok@mail.com> August 24, 2000
		- support for executing other programs with {RUN ...} keystroke
		(eg. {RUN notepad.exe c:\windows\win.ini})
	v1.0c	Axel Friedrich <axel.friedrich@operamail.com> and
		Rik Blok <rikblok@mail.com> February 24, 2000
		- German keyboard support with #define GERMAN_KEYBD
	v1.0b	Rik Blok <rikblok@mail.com> December 12, 1998
		- added support for millisecond sleeps via {SLEEP 0.001} etc.
		- added {EMPTYCLIPBOARD}/{EMPTYCLIP} keystroke to empty the
		  clipboard
		- replaced _strupr() routine with strupr()
		- moved internal function prototypes from header file to main
		  file
		- Successfully compiled with Borland C++Builder 1.0 under
		Windows 95b.

-----------------------------------------------------------------------------
9. Release Notes
================

v1.2b August 29, 2000
	- added "Sleep" integer option to ini file to slow down typing rate
v1.2  August 27, 2000
	- supports separate destination windows for each button
	- {RUN ...} command to execute other programs
	- no longer uses ButtonCount= item

v1.1  February 16, 2000
	- recompiled with German keyboard support (ToolbarG.exe)

v1.0c February 24, 1999
	- added "StayOnTop" and "TaskbarButton" boolean options to
	ini file

v1.0b February 13, 1999
	- added Pushkeys.hlp to root folder for help with keystrokes

v1.0  January 4, 1999
	- first release

-----------------------------------------------------------------------------
10. To Do List
==============

Here are some ideas of how I think Toolbar could be improved.  I'd like
some feedback on these.  Which do you think are important?  If you have
any suggestions of your own please let me know.

- a configuration program so the user doesn't have to muck around with
  the ini file directly.  Anybody feel like doing this?
- more documentation
- support for glyphs on buttons
- a dialog box allowing the user to select a configuration file if none
  specified on the command-line (instead of the error message)
- install/uninstall program

-----------------------------------------------------------------------------
11. Known Problems
==================

- only USA (and German) keyboards are supported
- if CutAndPaste is on (=1) then pressing a Toolbar button will erase
  the clipboard even if no text was selected.
- Toolbar can wreak havoc on your system if you're not careful.  Be sure
  to only press a Toolbar button if the previously active window is the
  desired destination window or if the "Destination" variable is set
  correctly in the configuration file.  If keystrokes are sent to the
  wrong window the effect could be unpredictable.
- I think Toolbar objects to unusual sizes and positions (off the screen)
  and crashes.  This may be due to the TFormStorage component I use.  I
  haven't looked into this problem closely.
- I encountered a window I could not match using the exact window title
  (using Destination="^some title$").  I don't know why but it matched
  fine when I removed the trailing "$".  (Maybe the title had trailing
  spaces?)
- comments (prefixed with semicolons ';') are only allowed on separate
  lines of the configuration file
- if an InsertText string is more than a few characters the keyboard buffer
  may fill up and characters could be dropped.
  Solution:
  Try increasing the "[Toolbar]Sleep=..." value to slow down the typing
  rate.  Alternatively, insert a "{SLEEP 0.1}" after every few characters
  in the InsertText string.
