1. Overview
2. Getting Started
3. Preferences
4. Training Gestures
5. Creating Actions
6. Defining Applications
7. Ignored Windows
8. Variables available to all Lua scripts
9. Action Functions

StrokesPlus is a mouse gesture recognition program that allows you to automate repetitive tasks by simply drawing a gesture with your mouse or performing mouse and/or keyboard modifiers to fire off an action sequence.

Whether the action sequence you're wanting to fire uses a gesture, mouse/keyboard modifier(s), or both, you begin with pressing the selected Stroke button on your mouse. By default, the Stroke button is assigned to the right mouse button. To begin, press and hold the Stroke button and either draw the gesture or perform the mouse/keyboard modifier(s), then release the Stroke button. If the events are recognized as being tied to an action sequence, StrokesPlus will fire the action sequence.

In Figure 1 below, we're going to draw the letter R by holding down the right mouse button, drawing the gesture R, then release the right mouse button. The gesture R is assigned to an action which opens the Windows Run dialog and types "notepad" (Figure 2), presses Enter, pauses for a moment, then types "hello world" followed by pressing ALT+H (to open the Help menu in Notepad) and finally presses "a" to select About Notepad from the menu, which displays the About Notepad window (Figure 3).

Figure 1

Figure 2

Figure 3

Many of the common tasks which people choose to create action sequences for are the very mundane aspects of using Windows, such as minimizing or maximizing a window, refreshing a web page, or closing a program. But the extent to which you can leverage StrokesPlus to increase your productivity is only limited by your imagination!

StrokesPlus comes with several gestures already trained and a variety of common action sequences already defined. To do anything other than use StrokesPlus to fire action sequences, you must right-click the StrokesPlus icon in the tray area of your taskbar, near the clock (Figure 4).

Figure 4

From this menu, you can:

1. enter Training Mode (which can also be accomplished by middle-clicking the StrokesPlus icon)
2. change the Stroke button
3. enable or disable drawing of gestures on the screen
4. disable StrokesPlus (which can also be accomplished by left-clicking the StrokesPlus icon or pressing CTRL+SHIFT+WIN+Z)
5. Open the Ignore List window
6. Open the Actions window (which can also be accomplished by left double-clicking the StrokesPlus icon)
7. Open the Preferences window (which can also be accomplished by middle double-clicking the StrokesPlus icon)
8. Reload StrokesPlus' configuration data from StrokesPlus.xml
9. Open this Help page
10. Exit StrokesPlus (which can also be accomplished by pressing CTRL+ALT+SHIFT+WIN+END)

Figure 5 represents the Preferences window in StrokesPlus. From this window, you can change several of StrokesPlus' features to meet your preferences.

Stroke Button - the mouse or keyboard button used to initiate firing action sequences

Ignore Key - held down before pressing the Stroke button if you do not want StrokesPlus to attempt to recognize an action. this is helpful when you want to perform some action in Windows or another application which requires using the Stroke Button. If you use a Stroke key, make sure you don't have the same key selected as the ignore key or StrokesPlus won't work.Note: See Cancel Delay below for these situations as well.

Cancel Delay - this is how long StrokesPlus waits for an action to timeout. For example, if you decided to right-click and drag some files in Windows Explorer, StrokesPlus would begin to look for action sequences to fire when you let go of the Stroke button. However, if you want StrokesPlus to stop capturing the sequence, simply keep the Stroke button held down and stop moving the mouse. After the number of milliseconds specified for Cancel Delay, StrokesPlus will stop capturing mouse and keyboard events, then replay the mouse events that occurred. In this instance, it would instantly move the mouse back to the starting position and send the right-click message, then move the mouse back to where you had it. So in this example, you would see the files attached to the mouse cursor just as you would if you had right-clicked and dragged some files in Explorer without StrokesPlus running (or if you had held the Ignore Key before pressing the right mouse button).

Stroke Style - These fields allow you to customize how StrokesPlus draws gestures on the screen. Red, Green, and Blue indicate the color combination which represent the actual color of the line. Width specifies how thick the line is. Min. Segment Length specifies the distance between drawing segments; mainly, this lets you set a minimum draw distance before S+ considers you've started drawing a Stroke. Length indicates the maximum length (trail) that StrokesPlus will draw, 0 for infinite. This doesn't affect the actual gesture being drawn, just how long the line is on the screen. Opacity affects the transparency of the line; 1 being nearly invisible and 255 being opaque (solid). Show instructs StrokesPlus whether or not to even draw the line at all.

Advanced / Experimental Options - these settings should used with caution as some of them could cause problems with StrokesPlus or other applications.

Match Precision - how finely StrokesPlus interpolates gestures to use for comparison. Default is 100 and there should be no need to change this setting.

Match Probability - the match likelihood of the drawn gesture to saved gestures. Higher makes the gesture matching more strict.

Aggressively Manage Memory - tells StrokesPlus to aggressively clean up memory at many points in the program's operation. Leave checked to ensure StrokesPlus uses the least amount of RAM while running. Uncheck if you want to let Windows manage the memory StrokesPlus uses; note that Windows is very liberal, only tidying up if other processes require memory used by other programs and available RAM has become limited.

Release/Reinitialize on Suspend/Resume - If checked, StrokesPlus will destory the tray icon and unhook the mouse and keyboard when Windows enters a suspended mode (e.g. selecting Sleep from the shutdown menu). When Windows resumes, StrokesPlus will recreate its icon and re-hook the mouse and keyboard (if S+ has not been disabled, of course).

Disable Multiple Instance Message - prevents StrokesPlus from displaying the popup message when you open more than one instance of StrokesPlus.

Disable New Gesture Message - prevents StrokesPlus from displaying the popup message when you click New to create a new gesture.

Reset Cancel Delay On Movement/Modifier - If unchecked, tells StrokesPlus to cancel gestures when the Cancel Delay is reached, regardless of mouse or keyboard activity.

Keep Gesture Draw Window On Top - always keep the transparent window to which StrokesPlus draws the gesture line on top. This can be helpful for low-power systems and prevent flickering UI elements for Windows XP users. However, there may be issues with other programs if they react to StrokesPlus' gesture window being above them. Therefore, this is an experimental feature.

Don't Hide Gesture Draw Window - when you're not drawing a gesture, the draw window is normally sent behind all other windows to increase performance and eliminate flickering and mouse lag when starting a new gesture. Uncheck this option to instruct StrokesPlus to hide the window completely. (This setting has no effect if Keep Gesture Draw Window On Top is checked.

Enable Mouse Wheel Relay - StrokesPlus will relay all mouse wheel scroll events directly to the control below the mouse cursor regardless of state. This lets you scroll controls, lists, windows which aren't active or selected by only scrolling the mouse wheel over top of them.

Fire Recognition on Mouse Wheel Scroll - StrokesPlus will attempt to recognize and fire actions when the mouse wheel is scrolled up or down (only when the Stroke button is being held down). This allows you to have actions which fire for each tick, this is helpful for volume actions, switching tabs, etc.

Capture Modifiers on Stroke Button Down* - In addition to capturing modifiers when they occur after the Stroke button is pressed, StrokesPlus will also get their state at the moment the Stroke button is pressed. So if you had the Control key held prior to pressing the Stroke button pressed (and held down at the time), the Control modifier would be recognized as part of the action definition.

Play Sound for No Match - plays a sound if the gesture doesn't exist or doesn't match a defined action

Sound (file) - The WAV file to play when no match. If empty, the sound defined for Question within Windows is played.

Figure 5

StrokesPlus comes with many gestures pre-trained, however, you can enter Training Mode if you want to create your own by selecting Training Mode from the StrokesPlus tray icon. You can also train StrokesPlus about existing gestures. For example, say that the way you draw the letter "R" on the screen is different than the way I do, StrokesPlus has learned the way I draw "R" and it may not recognize it when you draw "R". By entering Training Mode and drawing "R", you will see the window in Figure 7. If StrokesPlus recognizes the gesture, the text box will be pre-populated with the name of the gesture it believes was drawn. If StrokesPlus was incorrect in recognizing the gesture you intended, enter the name of the correct gesture here and click Save. This will add your drawing to the collection of point patterns associated with that gesture name. The more point patterns a gesture has associated with it, the better StrokesPlus may be at recognizing it.

Of course, if your drawing of "R" is dramatically different than the way I draw "R", it would be best to delete the "R" gesture from the Actions window and recreate one using only your point patterns so StrokesPlus will learn your style of "R" much faster. You will find that most gestures require only one point pattern (training capture), while others, like "R" and "B" will need several training sets for each letter since they're fairly similar, geometrically.

Figure 6

Actions are the lifeblood of StrokesPlus. Here is where you tell StrokesPlus exactly what to do when you complete a gesture.

An action is recognized if all of the criteria are met. This includes the Gesture, Mouse Modifiers, and/or Key Modifiers. Only one of these items must be selected to be recognized by StrokesPlus. For example, I have an action defined with only the Left Button mouse modifier; no Gesture or Key Modifier selected; so all I do is press the Stroke button (right, for me) and press the left mouse button and let go of the right button. This is great for very repetitive tasks; I use it for opening links in a new browser tab. I also have an action defined with only Scroll Up which I use to increase the volume.

Though most gesture involve drawing something on the screen as it's very easy to have many gestures where there are only so many mouse buttons. Note that modifiers do not have to be held for the duration of the sequence, only performed once after the Stroke button is pressed. So if you pressed the Stroke button and started to draw, you could tap the Control key once before releasing the Stroke button and it would be recognized as the drawing+Control key and if you have an action defined with that drawing and the Control key, StrokesPlus would fire the Lua script for the action.

The Available Actions dropdown displays a list of all actions exposed to Lua. The Info button will pop up a message describing the action. Clicking Insert will paste a snippet of the action into the Lua text box at the location of the cursor.

The Autosave check box tells StrokesPlus if you want it to automatically save changes when you switch to a different app or action, or close the Actions window. If Autosave is not checked, you must click Save before changing actions or closing the window, or changes will be lost.

Variables and Actions cover the variables and actions StrokesPlus exposes to Lua. For general Lua syntax, simply search Google for "Lua Programming Reference".

Figure 7

Global Actions are those which will fire regardless of what application is under the mouse (excluding Ignored windows, covered in the next section). However, you may want to have an entire set of gestures which are specific to only only application; like a web browser. To achieve this, click the Add App button, enter a name, and click OK. You will see a whole bunch of fields available to qualify and application and a Find Window box with a crosshair that can be used to locate an application, or only part of an application.

Only one field is required and generally the File Name is sufficient and will ensure the entire program is always matched. After using the Find Window crosshair, many of the fields will be populated with values. While you can leave them all as-is, it can create a very narrow scope that defines the app; potentially only a certain area of the app or only if the application's title happens to be exactly what was captured after using the Find Window tool. As I said, clear out all of the fields but File Name unless you're certain about the impact of how the qualifiers will affect your desired result.

The various Pattern fields are used to match based on regular expressions (uses BOOST regex library, FYI). This can be helpful if you want to match a broad or perhaps very specific type of condition to define an application.

When a gesture is complete, StrokesPlus will attempt to match applications first. If no match is found, then it will check the Global Actions for a match, unless Do not process Global Actions for this app, only app actions is checked

Figure 8

Ignored windows are those which will cause StrokesPlus to ignore the Stroke button when it's pressed on a window which is in the ignore list. To add a window to the ignored list, click the Add button, enter a name, and click OK. You will see a whole bunch of fields available to qualify and application and a Find Window box with a crosshair that can be used to locate an application, or only part of an application.

Only one field is required and generally the File Name is sufficient and will ensure the entire program is always matched. After using the Find Window crosshair, many of the fields will be populated with values. While you can leave them all as-is, it can create a very narrow scope that defines the ignored window; potentially only a certain area of the app or only if the application's title happens to be exactly what was captured after using the Find Window tool. As I said, clear out all of the fields but File Name unless you're certain about the impact of how the qualifiers will affect your desired result.

The various Pattern fields are used to match based on regular expressions (uses BOOST regex library, FYI). This can be helpful if you want to match a broad or perhaps very specific type of condition to define an application which is to be ignored.

Don't forget to click Save after making any changes in this window.

Figure 9

The following variables are populated automatically when completing a gesture. They are often used by many of the action functions (covered in the next section) to identify the window(s) to be affected by the action.

Additionally, alien.core and alien.struct are available to Lua scripts for making direct DLL calls. You do not need to include:

require "alien"

..in your Lua script (as many sample scripts on the Internet do), you will receive an error, unless the alien DLLs are somewhere in the path, but I'm not so sure they would play well together...so that's at your own risk.

Example Lua Script to directly call user32.dll to display a message box (not via the bound acMessageBox(), this is directly calling it):

   local alien = alien.core
   local mb = alien.load("user32.dll")
   local messagebox = mb.MessageBoxA
   messagebox:types{ ret = 'long', abi = 'stdcall', 'long', 'pointer', 'string', 'long' }
   test = "test"
   messagebox(0, test, "test2", 0)

Note that making direct DLL calls can cause S+/the Lua engine to crash hard if you screw something up in the script or defining the call(s), so this is a use at your own risk feature. I would recommend installing Lua for Windows and testing scripts in there if you're having problems or before adding to an action (removing require "alien" references).

Also, you may include any variables or functions in the file StrokesPlus.lua in the same folder as StrokesPlus.exe. When StrokesPlus loads (or you select Reload Config from the tray menu), any Lua in StrokesPlus.lua is executed and persisted. For example, if you wanted to create your own Lua function that you wanted to be able to call from any action, you could store it in StrokesPlus.lua. Or perhaps you want to create some global variables that are shared across actions, they could be declared/initialized there as well.