Overview
Loading the Module
Configuration
Bangs
The Groups Feature
Example Configuration
Known Issues
Author and Contact
xHotspot.dll is a Litestep module which can check periodically areas on your desktop for the mouse cursor entering or leaving -- in short words, a hotspot module. xHotspots can either be rectangular or elliptic (thus also round), and they can be combined to form groups behaving as if they were one compact area.
It is highly recommended to read the section on groups in order to understand how grouping works.
To load xHotspot put a (Net)LoadModule line into one of your configuration files (usually theme.rc):
*NetLoadModule xHotspot-0.1.1
or
LoadModule "$ModulesDir$xHotspot-0.1.1.dll"
Now, you are ready for configuration (see below). After that, recycle Litestep to load xHotspot and let your configuration take effect.
xHotspots are created by one of the following two statements. It is also possible to create them at runtime via !xHotspotCreate.
This creates an xHotspot with the given name:
*xHotspot (name)
This creates an xHotspot real group with the given name (see the section on groups for details):
*xHotspotGroup (name)
Every setting for a hotspot must be preceded by its name. The following settings are possible:
Type (Rectangular | Elliptic)
Sets the type of the hotspot. The default is set to Rectangular.
X (number)
Sets the horizontal position. For rectangular hotspots, this is the upper left edge, for elliptic hotspots, it is the centre coordinate.
Y (number)
Sets the vertical position. For rectangular hotspots, this is the upper left edge, for elliptic hotspots, it is the centre coordinate.
Width (number)
For rectangular hotspots, this sets the width. For elliptic hotspots, it sets the size of the horizontal radius.
Height (number)
For rectangular hotspots, this sets the Height. For elliptic hotspots, it sets the size of the vertical radius.
(number) can be any Litestep number, that is, negative, percent and centre numbers will work, as well as real negative coordinates (preceeded by '~').
UpdateInterval (ms)
Sets the interval in milliseconds after which the hotspot checks for mouse-in/out.
Enabled (bool)
Sets whether the hotspot starts activated or not. A hotspot is enabled by default.
OnEnter (command)
Sets a Litestep command which is executed on mouse-in.
OnLeave (command)
Sets a Litestep command which is executed on mouse-out.
AddToGroup (name)
Adds the hotspot to the specified group (see group section for details).
!xHotspotCreate (name)
Creates a hotspot accordingly to its settings made in step.rc.
!xHotspotDestroy (name)
Destroys a hotspot (believe it or not ;) ).
!xHotspotEnable (name)
Enables a hotspot, that is, the hotspots checks for mouse-in/out until it is stopped.
!xHotspotDisable (name)
Disables a hotspot, that is, the hotspot stops checking for mouse-in/out until it is enabled.
!xHotspotToggle (name)
Toggles a hotspot, that is, enables it if it is disabled, and the other way round.
!xHotspotMove (name) (x) (y)
Moves the given hotspot to the given position. For rectangular hotspots, this is the upper left edge, for elliptic, it is the centre.
!xHotspotMoveBy (name) (x) (y)
Moves the given hotspot relatively to its current position.
!xHotspotResize (name) (width) (height)
Resizes the given hotspot to the given size. For elliptic hotspots, width sets the horizontal radius, height the vertical.
!xHotspotResizeBy (name) (width) (height)
Resizes the given hotspot relatively to its current size. For elliptic hotspots, width means the horizontal radius, height the vertical.
!xHotspotReposition (name) (x) (y) (width) (height)
Moves and resizes the given hotspot to the given values.
!xHotspotRepositionBy (name) (x) (y) (width) (height)
Moves and resizes the given hotspot relatively to its current position and size.
!xHotspotIfInside (name) (command if true) (command if false)
Executes the first command if the cursor is inside of the given hotspot, else the second command.
Note that !xHotspotMove, !xHotspotResize and !xHotspotReposition(By) do not work for xHotspot groups.
xHotspot includes two types of grouping.
The first kind of grouping is similar to the xLabel grouping feature. It is called "normal grouping". Single xHotspots (including group hotspots of both types) can be added to a group in order to apply settings to the group, which are then inherited to the hotspots. The following bangs can be applied to groups of this type: !xHotspotEnable, !xHotspotDisable, !xHotspotToggle, !xHotspotMoveBy.
The second kind of grouping is called "real grouping". Real groups are interpreted as one complex-shaped hotspot. A hotspot added to a real group does not work on its own, but as part of the group. It actually only defines one area of the group hotspot, whereas its own OnEnter/OnLeave and UpdateInterval settings are ignored. Therefore, these settings should be given for the group. If the mouse enters any of the group's hotspots, the OnEnter action is triggered, and the OnLeave action will only be triggered when the mouse is not anymore inside any of the group's hotspots.
Real groups are created simply by explicitly creating a hotspot group (*xHotspotGroup myRealGroup). The following bangs can be applied to groups of this type: !xHotspotEnable, !xHotspotDisable, !xHotspotToggle, !xHotspotMoveBy, !xHotspotIfInside. A disabled hotspot will not be checked by the group.
Please be aware of strange effects that may occur when you uncomment a real group statement (*xHotspotGroup myGroup), as there is still a normal group which is created implicitly as long as a hotspot is added to it (somehotspotAddToGroup myGroup)
This creates a spot in the top left corner which opens the Popup:
*xHotspot popupspot popupspotX 0 popupspotY 0 popupspotWidth 1 popupspotHeight 1 popupspotOnEnter !Popup popupspotAddToGroup popupgroup
This creates a spot in the top right corner which opens the theme popup:
*xHotspot themespot themespotX -1 themespotY 0 themespotWidth 1 themespotHeight 1 themespotOnEnter !PopupTheme themespotAddToGroup popupgroup
This creates a spot in the bottom left corner which toggles the two other hotspots. Entering once will disable them, entering a second time will again enable them:
*xHotspot switchspot switchspotX 0 switchspotY -1 switchspotWidth 1 switchspotHeight 1 switchspotOnEnter !xHotspotToggle popupgroup
If you now create a real group called popupgroup, the two spots will then become part of that group, and their settings will be "overwritten":
*xHotspotGroup popupgroup popupgroupOnEnter !alert "We're a real group now"
- xHotspot will only work on your primary monitor (I think...); Multimonitor support will be added later.
- There is a bug somewhere around nested calls of !IfInside badly crashing LS sometimes. It seems to be related to LsLua and/or the core, but it has not been investigated yet.
- Excessive testing was not done, so bugs are probable (oops, banana software...). Please report them the email address below.
Author: ElkMonster
Email: emr at elkworld dot de