Utility structures

StepState Structure StepState() StepState structure is a double variable holder. It provides functions to handle their values and monitor their status in time. It is employed whenever is necessary to keep track of the status of a variable and trigger action based on changes. Its main use is with element indexes during tracking and painting.

NOTES: StepState structure makes use of the standard function "copy" which gets different meaning according to data types.
  • Do not use StepState with scene nodes instances or they will be duplicated.
  • Do not use StepState with Arrays, "deepCopy" is not supported.
  • Composite data types like Ray (Point3 position, Point3 direction) cannot perform equality test.
 
--------------------------------------------------------------------------------
-- STEPSTATE STRUCTURE
--------------------------------------------------------------------------------

struct StepState
(
    initStep = -1,
    prev = initStep,
    curr = initStep,

    function stepForward = ( prev = copy curr ),
    function stepBack = ( curr = copy prev ),
    function stepTo inputStep = ( prev = copy curr; curr = inputStep ),
    function stepToInit = ( prev = copy curr; curr = initStep ),

    function setSteps inputCurr inputPrev = ( curr = inputCurr; prev = inputPrev ),

    function resetSteps = ( curr = copy initStep; prev = copy initStep ),
    function resetCurr = ( curr = copy initStep ),
    function resetPrev = ( prev = copy initStep ),

    function isConst = ( return (curr == prev) ),

    function isSet = ( return ( (curr != initStep) and (prev != initStep) ) ),
    function isCurrSet = ( return (curr != initStep) ),
    function isPrevSet = ( return (prev != initStep) ),

    function isJustSet = ( return ( (curr != initStep) and (prev == initStep) ) ),
    function isJustReset = ( return ( (curr == initStep) and (prev != initStep) ) ),

    function getInit = ( return initStep )
)

Tracker Stucture Tracker() Tracker structure provides a set of function to organize the mouseTrack activities. It wraps the standard tracking function and divides it into manageable actions. Each sub-function can be filled with the code to be executed in that step.
Required structures: StepState, filed under Data Handling Structures start - start mouseTracking
stop - called after mouseTrack has been stopped. It can be called to force the stop of mouseTrack

freeMove - called continuously on mouse move without pressing any button

leftClick - called once on left mouse button pressed
rightClick - called once on right mouse button pressed

startDrag - called once on start mouse move with left mouse button pressed
drag - called continuously on mouse move with left mouse button pressed
endDrag - called once on mouse move without left mouse button pressed after drag

tracking - called continuously to manage the event functions 
--------------------------------------------------------------------------------
-- TRACKER STRUCTURE
--------------------------------------------------------------------------------

struct Tracker
(
    theNode = undefined,
    nState = StepState #freeMove,
    nComMode = #select,

--------------------------------------------------------------------------------
-- TRACKER - FREE MOVE
--------------------------------------------------------------------------------

    function freeMove &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt =
    (
        format "FREE MOVE\n"
    ),

--------------------------------------------------------------------------------
-- TRACKER - LEFT CLICK
--------------------------------------------------------------------------------

    function leftClick &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt =
    (
        format "LEFT CLICK\n"
    ),

--------------------------------------------------------------------------------
-- TRACKER - START DRAG
--------------------------------------------------------------------------------

    function startDrag &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt =
    (
        format "START DRAG\n"
    ),

--------------------------------------------------------------------------------
-- TRACKER - DRAG
--------------------------------------------------------------------------------

    function drag &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt =
    (
        format "DRAG\n"
    ),

--------------------------------------------------------------------------------
-- TRACKER - END DRAG
--------------------------------------------------------------------------------

    function endDrag &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt =
    (
        format "END DRAG\n"
    ),

--------------------------------------------------------------------------------
-- TRACKER - RIGHT CLICK
--------------------------------------------------------------------------------

    function rightClick &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt =
    (
        format "RIGHT CLICK\n"

        nStep = #stop
    ),

--------------------------------------------------------------------------------
-- TRACKER - TRACKING FUNCTION
--------------------------------------------------------------------------------

    function tracking nMessage rHit oMesh iMeshFace bShift bCtrl bAlt =
    (
        local nStep = #continue

        nState.stepTo nMessage

        if ( ( (nState.prev == #freeMove) and (nState.curr == #mousePoint) ) or \
             ( (nState.prev == #mousePoint) and (nState.curr == #mousePoint) ) ) then -- left click
        (
            leftClick &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt
        )
        else if ( ( (nState.prev == #freeMove) and (nState.curr == #mouseMove) ) or \
                  ( (nState.prev == #mousePoint) and (nState.curr == #mouseMove) ) ) then -- start drag
        (
            startDrag &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt
        )
        else if ( (nState.prev == #mouseMove) and (nState.curr == #mouseMove) ) then -- drag
        (
            drag &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt
        )
        else if ( (nState.prev == #mouseMove) and (nState.curr == #mousePoint) ) then -- end drag
        (
            endDrag &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt
        )
        else if (nState.curr == #mouseAbort) then -- right click
        (
            rightClick &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt
        )
        else -- free move
        (
            freeMove &nStep &rHit &oMesh &iMeshFace &bShift &bCtrl &bAlt
        )

        return nStep
    ),

--------------------------------------------------------------------------------
-- TRACKER - STOP TRACKING
--------------------------------------------------------------------------------

    function stop =
    (
        format "STOP TRACKING\n"

        try ( toolMode.commandMode = nComMode ) catch ( toolMode.commandMode = #select )
    ),

--------------------------------------------------------------------------------
-- TRACKER - START TRACKING
--------------------------------------------------------------------------------

    function start =
    (
        format "START TRACKING\n"

        if ( (isValidNode theNode) and ((superClassOf theNode) == GeometryClass) ) do
        (
            nComMode = toolMode.commandMode

            mouseTrack on:theNode trackCallBack:tracking
            stop()
        )
    )

--------------------------------------------------------------------------------

)

Painter Structure Painter() Painter structure organizes main functions that define thePainterInterface behaviours. It provides the framework for painting tools. systemStartPaintSession - start thePainterInterface
systemEndPaintSession - called when the system shuts down thePainterInterface, like on sub-object level selection chenge. It can be called to force the stop of thePainterInterface.

startStroke - called once on start mouse move with left mouse button pressed
paintStroke - called continuously on mouse move with left mouse button pressed
endStroke - called once on mouse move without left mouse button pressed after paintStroke
cancelStroke - called once when stroke is aborted by pressing ESC 
--------------------------------------------------------------------------------
-- PAINTER STRUCTURE
--------------------------------------------------------------------------------

struct Painter
(
    theNode = undefined,

--------------------------------------------------------------------------------
-- PAINTER - START STROKE
--------------------------------------------------------------------------------

    function startStroke =
    (
        format "START STROKE\n"

        thePainterInterface.undoStart()
    ),

--------------------------------------------------------------------------------
-- PAINTER - PAINT STROKE
--------------------------------------------------------------------------------

    function paintStroke =
    (
        format "PAINT STROKE\n"
    ),

--------------------------------------------------------------------------------
-- PAINTER - END STROKE
--------------------------------------------------------------------------------

    function endStroke =
    (
        format "END STROKE\n"

        thePainterInterface.undoAccept()
    ),

--------------------------------------------------------------------------------
-- PAINTER - CANCEL STROKE
--------------------------------------------------------------------------------

    function cancelStroke =
    (
        format "CANCEL STROKE\n"

        thePainterInterface.undoCancel()
    ),

--------------------------------------------------------------------------------
-- PAINTER - SYSTEM END PAINT SESSION
--------------------------------------------------------------------------------

    function systemEndPaintSession =
    (
        format "SYSTEM END PAINT SESSION\n"

        thePainterInterface.endPaintSession()
    ),

--------------------------------------------------------------------------------
-- PAINTER - SYSTEM START PAINT SESSION
--------------------------------------------------------------------------------

    function systemStartPaintSession =
    (
        format "SYSTEM START PAINT SESSION\n"

        if ( (isValidNode theNode) and ((superClassOf theNode) == Geometry) ) do
        (
            thePainterInterface.initializeNodes 0 theNode

            thePainterInterface.scriptFunctions startStroke paintStroke endStroke cancelStroke systemEndPaintSession

            thePainterInterface.startPaintSession()
        )
    )

--------------------------------------------------------------------------------

)

Files Handler Structure FilesHandler() FilesHandler structure provides essential functions to manage files like copying and deleting full directory trees, or multiple files.

Thanks to Denis Trofimov "denisT" and Rene Baca "MerlinEl" for bugfixes and code enhancements. delTree sRoot - delete the entire directory tree, sRoot included
delFromTree sRoot - delete the entire directory tree, sRoot excluded
delFiles sRoot sPattern - delete all files in directory sRoot, matching sPattern

copyTree sRoot sTarget - copy the entire sRoot directory tree into sTarget directory
copyFiles sRoot sTarget - copy all files from sRoot directory into sTarget directory

deleteTempFiles - delete every file and folder from system user 3ds Max temp directory 
--------------------------------------------------------------------------------
-- FILES HANDLER STRUCTURE
--------------------------------------------------------------------------------

struct FilesHandler
(
    function _getFilesRecursive sRoot sPattern =
    (
        sRoot = trimRight sRoot "\\"
        sRoot += "\\"

        local asDirectory = (getDirectories (sRoot + "*"))

        for d in asDirectory do
            join asDirectory (getDirectories (d + "*"))

        insertItem sRoot asDirectory 1

        local asFiles = #()

        for f in asDirectory do
            join asFiles (getFiles (f + sPattern))

        return #(asFiles, asDirectory)
    ),

    function delTree sRoot =
    (
        sRoot = trimRight sRoot "\\"
        sRoot += "\\"

        try ( DOSCommand ("rd \"" + sRoot + "\" /S /Q") ) ) catch ()
    ),

    function delFromTree sRoot =
    (
        local asPaths = _getFilesRecursive sRoot "*.*"

        for theItem in asPaths[1] do
            deleteFile theItem

        for i = (asPaths[2].count) to 2 by -1 do
        (
            local sPath = trimRight asPaths[2][i] "\\"
            try ( DOSCommand ("rd \"" + sPath + "\"") ) catch ()
        )
    ),

    function delFiles sRoot sPattern =
    (
        sRoot = trimRight sRoot "\\"
        sRoot += "\\"

        local asFiles = getFiles (sRoot + sPattern)

        for theItem in asFiles do
            deleteFile theItem
    ),

    function copyTree sRoot sTarget =
    (
        local asPaths = _getFilesRecursive sRoot "*.*"

        sTarget = trimRight sTarget "\\"
        sTarget += "\\"

        for theItem in asPaths[2] do
            makeDir (sTarget + (subString theItem (sRoot.count+1) -1)) all:true

        for theItem in asPaths[1] do
            copyFile theItem (sTarget + (subString theItem (sRoot.count+1) -1))
    ),

    function copyFiles sRoot sTarget =
    (
        sRoot = trimRight sRoot "\\"
        sRoot += "\\"

        sTarget = trimRight sTarget "\\"
        sTarget += "\\"

        local asFiles = getFiles (sRoot + "*.*")

        for theItem in asFiles do
            copyFile theItem (sTarget + (filenameFromPath theItem))
    ),

    function deleteTempFiles = delFromTree (getDir #temp)
)

Undo Handler Structure UndoHandler() Undo Handler provides essential functions to manage 3ds Max undo system. Please refer to "TheHold" in MaxScript Reference. See also the SDK documentation on theHold methods. 
--------------------------------------------------------------------------------
-- UNDO HANDLER STRUCTURE
--------------------------------------------------------------------------------

struct UndoHandler
(
    function setHold =
    (
        try ( if (not theHold.holding()) do ( theHold.begin() ) ) catch ()
    ),

    function getHold sTag =
    (
        try ( if (theHold.holding()) do ( theHold.accept sTag ) ) catch ()
    ),

    function resetHold sTag =
    (
        try ( if (theHold.holding()) do ( theHold.accept sTag ) ) catch ()
        try ( if (not theHold.holding()) do ( theHold.begin() ) ) catch ()
    ),

    function resumeHold =
    (
        try ( if (theHold.isSuspended()) do ( theHold.resume() ) catch ()
    )
)