Script Structure for menu or tool scripts


functions available to a script



*pfx = two or three letter script prefix (usually the initials of the script creator)

pfx_ScriptName:Name() return String - script "long name" - called when the user opens the "Help > About Scripts" menu

pfx_ScriptName:Version() return String - script version identifier

pfx_ScriptName:Description() return string - long description

pfx_ScriptName:BeginnerDescription() return string - a description when beginner mode is on

pfx_ScriptName:BeginnerDisabledDescription() return string

pfx_ScriptName:Creator() return string - author's name / designation / affiliation

pfx_ScriptName:UILabel() return string - Label shown in the UI (menu or tool bar) - called by Moho when (setting up a menu?)

pfx_ScriptName:ColorizeIcon() return bool - true = use the Moho 12 UI colorisation

pfx_ScriptName:Run(moho, view) - called when button or menu script is activated

pfx_ScriptName:IsRelevant(moho) - called when tool is changed and moving in/out of frame zero. Note that if IsRelevant returns "false" then other routines, especially IsEnabled, are not executed. (The icon for tool that is "not relevant" is not shown in the tools palette.)

pfx_ScriptName:IsEnabled(moho) - called when tool is changed and moving in/out of frame zero. The icon for a tool that is "not enabled" is dimmed in the tool palette.)

pfx_ScriptName:OnMouseDown(moho, mouseEvent) - called when mouse left-click is pressed

pfx_ScriptName:OnMouseMoved(moho, mouseEvent) - called when mouse is moved while holding left button

pfx_ScriptName:OnMouseUp(moho, mouseEvent) - called when mouse left-click is released

pfx_ScriptName:OnKeyDown(moho, keyEvent) - called when keyboard key is pressed

pfx_ScriptName:OnKeyUp(moho, keyEvent) - called when keyboard key is released

pfx_ScriptName:NonDragMouseMove() - return bool (return true to have "MouseMoved()" called even if the mouse button is not down) - called at script activation

pfx_ScriptName:SavePrefs(prefs) return void - prefs: see class ScriptPrefs - this typically does many prefs:Setxxx - called by Moho when (a different script is started?)

pfx_ScriptName:LoadPrefs(prefs) - called at script activation

pfx_ScriptName:ResetPrefs() - called when the reset tool or reset all tools button is pressed. The script needs to reset its variables (?? moho does not do this automatically)

pfx_ScriptName:OnInputDeviceEvent(moho, InputDeviceEvent) - called when an event on a connected device (e.g. tablet) occurs - not wholly clear to me if this is "any" input device (i.e. it's "pass through" by Moho) or just ones that moho will trap and pre-process (this seems more probable)

pfx_ScriptName:DrawMe(moho, view)

pfx_ScriptName:DoLayout(moho, layout)

pfx_ScriptName:HandleMessage(moho, view, msg)

For the dialog methods, see the LM_SimpleDialog class.

There is also a function: string = MOHO.Localize ("Index string/=Base text") used in localisation (see below)


Template tool script structure


the following is an example of a typical script preamble
ScriptName = "pfx_ScriptName" -- Provide Moho with the name of this script object

pfx_ScriptName = {} -- a table that will be used by Moho

pfx_ScriptName.BASE_STR = nnnn -- a numeric value that indexes the localisation files. if the script author wishes to provide localisation, it will be necessary to update the localisation files provided as part of the release

function pfx_ScriptName:Name()
return "text"
end

function pfx_ScriptName:Version()
return "text" -- typically a text string that is of the form nn.n
end

function pfx_ScriptName:IsBeginnerScript()
return Boolean
end

function pfx_ScriptName:Description()
return "text"
end

function pfx_ScriptName:BeginnerDescription()
return "text"
end

function pfx_ScriptName:BeginnerDisabledDescription()
return "text"
end

function pfx_ScriptName:Creator()
return "text"
end

function pfx_ScriptName:UILabel()
return "text"
end

function pfx_ScriptName:IsRelevant(moho)
-- code to determine if the tool is relevant or not (i.e. will it appear in the tools window at all?)
return Boolean
end

function pfx_ScriptName:IsEnabled(moho)
-- code to determine if enabled (i.e. will the tool be active) or not (i.e. inactive with its icon greyed out)
return Boolean
end






After this basic set-up a menu script will have a top-level function
function pfx_ScriptName:Run(moho)
-- code
end


and a tool script will have a basic structure that is based on input device events - for example
function pfx_ScriptName:OnMouseDown(moho, mouseEvent)
-- code
end

function pfx_ScriptName:OnMouseMoved(moho, mouseEvent)
-- code
end

function pfx_ScriptName:OnMouseUp(moho, mouseEvent)
-- code
end


Both may need to set up a user dialogue:
function pfx_ScriptName:DoLayout(moho, layout)
-- code
end
function pfx_ScriptName:HandleMessage(moho, view, msg)
-- code
end


Also see LM_SimpleDialog



Script Structure for embedded (layer) scripts



Embedded scripts run whenever Moho refreshes the display - typically when you interact with the interface - and so can be run many times on each frame.

An embedded script must have a top level function named LayerScript:

function LayerScript(moho)
-- layer script code
end


It is possible to include code in the layer script to check if the code has already executed without the frame having changed but this is often not necessary. The following gives an example of how to do this.

function LayerScript(moho)
if type (HS_lastF) == "nil" then
HS_lastF, HS_lastLF, HS_lastDF, HS_lastDLF = -1,0,0,0
end
local F, LF, DF, DLF
F, LF, DF, DLF = moho.frame, moho.layerFrame, moho.drawingFrame, moho.drawinglayerFrame
if not (HS_lastF == F and HS_lastLF == LF and HS_lastDF == DF and HS_lastDLF == DLF) then
print (F, " ", LF, " ", DF, " ", DLF)
end
HS_lastF, HS_lastLF, HS_lastDF, HS_lastDLF = F, LF, DF, DLF
end

Notice that variables to be preserved across invocations of the layer script need to Global (and therefore follow global variable naming conventions). To check if a variable has been defined one approach is to see if it is of type "nil".

The above code prints out the various "frame" numbers once on each selected frame.

(timeline) Frame 0 (moho.frame) is a special case where some initialisation may be necessary and/or no "animation" (e.g. changing bone or point position) is required.

for example:

function LayerScript(moho)
if moho.frame == 0 then
-- do initialisation
return true
end
-- do script body
end


Note that in the above example both initialisation and the code body may run many times without the timeline frame changing.