Tools

From Second Life Wiki
Jump to navigation Jump to search

Anything which can take effect when you click on the graphical display of the world appears to be categorised as a tool (base class LLTool). Tools are handled by the tool manager (class LLToolMgr).

The tool manager tracks four toolsets: basic, camera, mouselook, and face edit. (Global variables gBasicToolset, gCameraToolset, gMouselookToolset, and gFaceEditToolset, all instances of LLToolset).

The list of tools directly loaded into the tool manager is as follows:

Tool Name Global Variable Implementing Class Toolsets Effect
Null gToolNull LLTool(NULL) None Does nothing but be "selected" pre-initialisation when no tools exist yet
Pie gToolPie LLToolPie() Basic Default tool in normal usage - triggers left click action on objects, triggers grabs when physical objects dragged, and displays pie menus on right click
Camera gToolCamera LLToolCamera() Basic, Camera Dollies camera with mouse motion
Grab gToolGrab LLToolGrab() Basic Moves physical objects around
Translate gToolTranslate LLToolCompTranslate() Basic Position tool from build window
Scale gToolStretch LLToolCompScale() None Scale tool from build window
Rotate gToolRotate LLToolCompRotate() None Rotation tool from build window
Face gToolFace LLToolFace() None Selects object face for Select Texture
Pipette gToolPipette LLToolPipette() None Lifts texture from clicked surface
Individual gToolIndividual LLToolIndividual() None "Selects an individual object, not a linkset"
Create gToolCreate LLToolCompCreate() Basic Create button from build window
Land gToolLand LLToolBrushLand() Basic Terraforming
Parcel gToolParcel LLToolSelectLand() Basic Parcel merge/split
CompGun gToolGun LLToolCompGun() Mouselook Toggles between crosshairs and grab in mouselook
Gun (none) LLToolGun() None Provides crosshairs - instantiated within CompGun
Morph gToolMorph LLToolMorph() Face Edit Not implemented, commented out and class is missing
DragAndDrop gToolDragAndDrop LLToolDragAndDrop() None ?
ObjPicker gToolObjPicker LLToolObjPicker() None Picks a single object and reports it back, for Bug and Abuse Reports
SelectRect (none) LLToolSelectRect() None Rectangular drag selection box - instantiated within other tools
Select (none) LLToolSelect() None Selects link set or single prim, as determined by checkbox on build window - instantiated within other tools

Active tool

At any given moment the tool manager tracks three "active" tools:

The current tool is the tool currently selected by normal means.

The override tool is the tool currently temporarily activated by a held-down key combination. It appears this is set by the getCurrentTool method of the tool manager, whose single parameter is a control key mask. This follows the following rules:

  • If the user is in the middle of dragging for a translation, rotation, or stretch, nothing can be overridden.
  • Transient tools, and the Camera, Gun, and Grab tools cannot be overridden, with one exception: the Camera tool can override the Grab tool.
  • If ALT is down in the mask passed to getCurrentTool, and the current tool can be overridden by the Camera, the Camera tool becomes the override tool.
  • If CTRL is down in the mask passed to getCurrentTool, and the current tool can be overridden, the Rotate tool becomes the override tool - unless the Pie tool is the current tool, in which case the Grab tool becomes the override tool.
  • If CTRL-SHIFT is down in the mask passed to getCurrentTool, and the current tool can be overridden, the Scale tool becomes the override tool - unless the Pie tool is the current tool, in which case the Grab tool becomes the override tool.

The transient tool is the tool currently temporarily activated by something other than a held-down key combination. This is not set in getCurrentTool, but is set from outside via a call to setTransientTool. Transient tools currently appear to be:

  • Camera movement focused on avatar when the left mouse button held down over the avatar.
  • Pipette tool when invoked from colour or texture picker.
  • ObjPicker tool when invoked from Bug or Abuse Report window.
  • Grab when invoked from Pie tool on a dragged physical object.
  • The "Drop" bit of the DragAndDrop tool when a drag has begun.

When Second Life loses the focus, the current tool is stored in a seperate variable as the saved tool, and then the actual current tool is set to Null. This is reversed when Second Life regains the focus. (By onAppFocusLost() and onAppFocusGained() in LLToolMgr.) Due to a condition in these methods, the only tool which actually recieves selected and deselected events when this happens is the Gun tool, because when in use it hides the mouse pointer and so the mouse pointer needs to be restored when Second Life loses the focus.

Composite Tools

Composite tools (those which extend LLToolComposite) combine the functions of a number of other tools. The base class LLToolComposite defines a protected property mCur which holds the actual LLTool to which the composite tool is currently delegating, and by default overrides all LLTool methods with methods which call the appropriate LLTool method on the tool currently held in mCur.

There are five composite tools, all defined in lltoolcomp.cpp:

  • The Translate, Scale, and Rotate tools all combine LLToolSelect, an appropriate "Manipulator" instance (which handles actual dragging - LLManipTranslate, LLManipScale, and LLManipRotate respectively), plus a LLToolSelectRect (rectangle selection). These instances are stored in local variables of the respective composite tools.
  • The Create tool is similar to Translate, Scale, and Rotate, except instead of a Manipulator it combines an instance of LLToolPlacer.
  • The Gun tool combines LLToolGun, plus the Grab and Null tools.

Toolsets

Toolsets appear to be used to allow tools to be stored in ordered lists which can be moved through step by step. Each toolset store a list of tools which can be rotated through via selectFirstTool, selectNextTool and selectPrevTool methods. Tools can also be selected based on index in the list selectToolByIndex. When a tool is selected in any toolset it is immediately also selected in the Tool Manager and thus becomes active within Second Life. The selectTool method of a toolset will select the specified tool immediately and move the toolset's list pointer to that tool; if the tool is not in the toolset then the selectTool call will still work, but a future call to selectNextTool or selectPrevTool will return the first tool in the set.