LibMouseGestures API

LibMouseGestures:New(target_frame)

Creates a new mouse gesture overlay for the given frame.

Parameters

target_frame

The frame that will receive mouse gestures

Return values

recorder

A LibMouseGestures recorder object

Usage

local libmg = LibStub("LibMouseGestures-1.0");
local frame = CreateFrame("Frame");
frame:SetPoint("CENTER", UIParent, "CENTER", 0, 0);
frame:SetWidth(300);
frame:SetHeight(200);
local recorder = libmg:New(frame);

Recorder API

A recorder object is an instantiated LibMouseGestures object and the staple of the library. Each frame that requires mouse gesture tracking will need its own separate recorder object, but fear not, the footprint is quite small.

Recorder:StartCapture(capture_script)

Starts recording a mouse gesture with the given capture script

Parameters

capture_script

The capture script that LibMouseGestures will follow

Return values

none

Usage

recorder:StartCapture{
        startButton        = "LeftButtonDown",
        stopButton        = "LeftButtonUp",
        cancelButton    = "RightButtonUp",
        updateFunc        = Rendermon_DrawTriangle,
        cancelFunc        = Rendermon_DrawWipe,
        stopFunc        = Rendermon_CreateRectangle,
        showTrail       = true,
        tooltip            = {
            "Click and drag to create a triangle.", -- tooltip title
            "Hold down SHIFT to force equal proportions",
            "Use right click to cancel."
        }
    });

See the Designing a capture script section at the bottom for information about the table structure and callbacks.

Recorder:GetGist()

Returns a human readable list of the gestures made since the last startFunc or nextFunc in a recording.

Parameters

none

Return values

gestures

A table containing the type of movements and the direction of these in the format [type, direction:

• line: A straight line was made
  • possible directions: up, down, left, right, left-up, left-down, right-up, right-down
• circle: A circle was made with the mouse
  • possible directions: clockwise, counterclockwise

Usage

function myMouseGestureDone(recorder,x1,y1,x2,y2)
    local gists = recorder:GetGist();
    for n = 1, #gists do
        local gist = gists[n];
        print("User made a", gist[1], "in a", gist[2], "direction");
    end
end

Recorder:GetBounds([enforceProportions])

Returns the top left coordinates and the width and height of the rectangle created between the initial point that started the capture and the current cursor position

Parameters

enforceProportions

An optional boolean value. If set to true, the height and width of the returned bounding rectangle will be identical if the SHIFT key is down.

Return values

x, y, width, height

the x, y coordinates of the top left corner of the bounding box and the width, height of this box.

Usage

function myMouseGestureUpdate(recorder,x1,y1,x2,y2)
    local x,y,w,h = recorder:GetBounds();
end

Recorder:GetMovementBounds()

Returns the top left and bottom right coordinates of the largest rectangular area traversed by the mouse during the recorded gesture.

Parameters

none

Return values

x1,y1,x2,y2

the x, y coordinates of the top left and bottom right corner of the traversed area.

Designing a capture script

A capture script is a table that specifies how the recorder responds to mouse actions. It typically contains at least a start and a stop action which will trigger the beginning and end of the recording. The table can have the following elements attached to it:

startButton

A description of the mouse action that will trigger the start of the gesture recording.

Possibly values are: LeftButtonUp, LeftButtonDown, RightButtonUp, RightButtonDown, MiddleButtonUp, MiddleButtonDown, Freehand

If startButton is set to Freehand, no mouse locking will occur, but results will instead be collected from the entire screen. To exit a recording with startButton set to None, You can define maxGestures in the script to stop after a defined number of gestures, or you can leave it out and LibMouseGestures will stop when the mouse stops making new gestures.

stopButton

A description of the mouse action that will stop (finish) the gesture recording

Possibly values are: LeftButtonUp, LeftButtonDown, RightButtonUp, RightButtonDown, MiddleButtonUp, MiddleButtonDown

nextButton

A description of the optional mouse action that will trigger nextFunc and start a new recording if defined. This can be used to simultaneously recording multiple gestures at once.

Possibly values are: LeftButtonUp, LeftButtonDown, RightButtonUp, RightButtonDown, MiddleButtonUp, MiddleButtonDown

cancelButton

A description of the optional mouse action that will cancel the recording and call cancelFunc instead of stopFunc.

Possibly values are: LeftButtonUp, LeftButtonDown, RightButtonUp, RightButtonDown, MiddleButtonUp, MiddleButtonDown

startFunc

An optional function that will be called on the first start of a gesture recording. This can be used to initializing values and so on. startFunc will only be called at the start of a capture, and not after a nextButton has fired.

Callback values: recorder, x1, y1, x2, y2 : The recorder object as well as the initial coordinates where the mouse triggered startFunc and the current cursor coordinates (which should be the same in this case)

updateFunc

A function that will be called after each OnUpdate event on the recording frame.

Callback values: recorder, x1, y1, x2, y2 : The recorder object as well as the initial coordinates where the mouse triggered startFunc (or the last called nextFunc) and the current cursor coordinates

stopFunc

A function that will be called when stopButton has triggered the end of a recording.

Callback values: recorder, x1, y1, x2, y2 : The recorder object as well as the initial coordinates where the mouse triggered startFunc (or the last called nextFunc) and the current cursor coordinates

nextFunc

A function that will be called when nextButton has triggered the stop of the current recording and immediate start of a new from the current position.

Callback values: recorder, x1, y1, x2, y2 : The recorder object as well as the initial coordinates where the mouse triggered startFunc (or the last called nextFunc) and the current cursor coordinates.

cancelFunc

A function that will be called when cancelButton has triggered the termination of a recording.

Callback values: recorder, x1, y1, x2, y2 : The recorder object as well as the initial coordinates where the mouse triggered startFunc (or the last called nextFunc) and the current cursor coordinates

tooltip

If set to either a string value or a table with multiple strings, a tooltip will be displayed next to the cursor when positioned over the recording frame. This can be used to provides tips on how to use the mouse gestures.

maxGestures

If startButton is set to Freehand, maxGestures can be used to set a hard cap on the number of gestures the user can make before the recording stops. Please note, that this will only work on linear gestures. If you need to record circular gestures, leave out this field and the library will sort it for you instead.

showTrail

boolean value. If set to true, a cursor trail will be shown while the gesture takes place. (can be used for debugging and whatnot)

Capture script examples

A simple script to capture a line being drawn by dragging the mouse from one position to another:

local captureScript = {
    startButton     = "LeftButtonDown",
    stopButton      = "LeftButtonUp",
    showTrail       = true,
    stopFunc        = DrawLine, -- calls DrawLine(recorder,x1,y1,x2,y2)
    tooltip         = "Hold down the mouse button to drag a line"
}

A sample script for making a polygon out of mouse clicks

local captureScript = {
    startButton     = "LeftButtonDown",
    nextButton      = "LeftButtonDown",
    stopButton      = "RightButtonUp",
    showTrail       = true,
    nextFunc        = AddPolyLine,
    stopFunc        = FinishPolyLine,
    tooltip         = "Click on the screen to place your markers"
}

A sample script to capture a mouse gesture with the left mouse button down

local captureScript = {
    startButton     = "LeftButtonDown",
    stopButton      = "LeftButtonUp",
    stopFunc        = ParseGesture,
}