==========
BBHotSpots
==========




Abstract
========

BBHotSpots is a plugin for Blackbox for Windows <http://bb4win.org/>
to define `hotspot' that is a rectangler spot
and executes associated command if the mouse cursor enters or leaves itself.

For latest information, see <http://nicht.s8.xrea.com/2005/01/BBHotSpots>.




Requirements
============

BBHotSpots uses BBCmd <http://nicht.s8.xrea.com/2004/03/27/BBCmd>.
So you have to install it before install BBHotSpots.




Install / Uninstall
===================

Same as other plugins.




Settings
========

BBHotSpots reads its settings from the file named `BBHotSpots.rc'
which is in the same folder as `BBHotSpots.dll'.
It contains bro@ms one-per-line.
BBHotSpots just sends that bro@ms.




Bro@ms
======

@BBHotSpots load_settings
	Reload the settings.

@BBHotSpots engine <`hook' or `timer'>
	Change the method to check the position of the mouse cursor.
	`hook' has quicker response than `timer'.
	But sometime, it might cause some unexpected result.
	Default value: timer

@BBHotSpots interval <milli seconds>
	Change the interval to check the position of the mouse cursor.
	This is used for `timer' method.
	The value can't be less than 100.
	Default value: 1000

@BBHotSpots clear
	Delete all hotspots.

@BBHotSpots add <name> <x> <y> <width> <height> [state]
	Add new hotspot.

	`name' is the name of new hotspot.
	It is used to identify this hotspot from other hotspots.

	`x' and `y' are the position (the left-top corner) of the hotspot.
	`width' and `height' are the width or height of the hotspot.

	`state' is the initial state of the hotspot.
	It represents whether the hotspot is active or not.
	BBHotSpots doesn't execute the associated script
	if the hotspot is not active.
	This can be `true' or `false'.
	This can be omitted, and if so, it is treated as `true'.

@BBHotSpots del <name>
	Delete the hotspot named `name'.

@BBHotSpots set <name> <x> <y> <width> <height>
	Change the spot of the hotspot named `name'.

@BBHotSpots activate [name]
@BBHotSpots inactivate [name]
@BBHotSpots toggle [name]
	Change the state of the hotspot named `name'.
	If `name' is omitted, do it for each hotspot.

@BBHotSpots on-enter <name> <script>
@BBHotSpots on-leave <name> <script>
@BBHotSpots on-click <name> <script>
	Change the scripts of the hotspot named `name'.
	These scripts will be executed
	when the mouse cursor enters or leaves,
	or any button is clicked on the hotspot named `name'.
	`script' is a BBCmd script.
	See the documents of BBCmd for the details.

	NOTE: If you want to use on-click scripts,
	you have to change the cursor-checking method as `hook'
	(@BBHotSpots engine hook).

@BBHotSpots info [name]
	Show a bit of information about the hotspot named `name'.
	If `name' is omitted, do it for each hotspot.




Formats of x, y, width and height
---------------------------------

X and y can be one of the following formats:

N (zero or positive integer)
	Relative coordinates from the left-top corner of the screen in pixels.
	(0, 0) ... (screen_width-1, screen_height-1)

-N (negative integer)
	Relative coordinates from the right-bottom corner of the screen
	in pixels.
	(-screen_width, -screen_height) ... (-1, -1)

N%
	Relative coordinates from the left-top corner
	in percentage of the screen width/height.
	(0%, 0%) ... (100%-1, 100%-1)

left / top / right / bottom
	Place the hotspot on the left/top/right/bottom edge of the screen.

center
	Place the hotspot on the center of the screen.


Width and height can be one of the following formats:

N (positive integer)
	Absolute length in pixels.

N%
	Relative length from the percentage of the screen width or height.




BUGS
====

* Don't set script to delete a hotspot itself like the following.
  Such scripts will crash the shell.

          @BBHotSpots on-enter foo broam('@BBHotSpots del foo')
          @BBHotSpots on-leave bar broam('@BBHotSpots clear')

  However, `reconfig' and `restart' don't cause this problem.
  `broam('@BBHotSpots load_settings')' is also safe
  even if BBHotSpots.rc contains either `@BBHotSpots clear' or others.

* Don't write `@BBHotSpots load_settings' in BBHotSpots.rc.
  It causes an infinite loop and will crash or reeze the shell.

  (1) read BBHotSpots.rc.
  (2) send `@BBHotSpots load_settings'.
  (3) receive `@BBHotSpots load_settings'.
  (4) read BBHotSpots.rc.
  ...

* If the mouse cursor enters or leaves the spot
  which is covered by multiple hotspots,
  BBHotSpots will execute the script of the earliest defined one.




TODO
====

...




ChangeLog
=========

0.0.3	2005-01-30
	- Added bro@m `@BBHotSpots on-click <name> <script>'.

0.0.2	2005-01-26
	- Implemented `hook' method.

	- Fixed minor bugs.

0.0.1	2005-01-24
	- Modified not to write settings.

	- Added bro@m `@BBHotSpots info <name>'.

	- Added more formats for x, y, width and height.

	- Fixed minor bugs.

	- Modified to send any lines starting with `@' in BBHotSpots.rc,
	  and other lines are ignroed.

	- Fixed `@BBHotSpots load_settings': now it is safe to send
	  this bro@m from any hotspots.

	- Added a state for each hotspot.
	  It represents the hotspot is active or not.
	  If a hotspot is inactive, its associated scripts are not executed.

	- Renamed all bro@ms.

	- Now the length of hotspot name is unlimited
	  and may contain any spaces by quoting with single-quote.


0.0.0	2005-01-23
	- Initial version.




License
=======

BBHotSpots is released under the terms of GNU General Public License
either version 2 or (at your option) any later version.




Copyright (C) 2005 kana <nicht AT s8 DOT xrea DOT con>

[END]
