LayoutTool

Availability  Future
Component  Layout
Header  lwlaytool.h

Layout tool plug-ins are just custom Layout tools. To the user, they behave like Layout's built-in tools (the tools activated by the Move, Rotate and Scale buttons, for example).

Support for this class isn't complete.

Activation Function

   XCALL_( int ) MyLayoutTool( int version, GlobalFunc *global,
      LWLayoutTool *local, void *serverData );

The local argument to a Layout tool's activation function is an LWLayoutTool.

   typedef struct st_LWLayoutTool {
      LWInstance         instance;
      LWLayoutToolFuncs *tool;
   } LWLayoutTool;

The activation function fills in the instance field and the callbacks of the tool field and returns. As with handlers, the remaining interaction between Layout and the plug-in takes place through the callbacks.

instance

A pointer to your user data. This will be passed to each of the tool callbacks.

tool

Points to a structure containing function pointers for your callbacks, described below.

Tool Functions

The tool field of the LWLayoutTool is a pointer to an LWLayoutToolFuncs.

   typedef struct st_LWLayoutToolFuncs {
      void         (*done)   (LWInstance);
      void         (*draw)   (LWInstance, LWCustomObjAccess *);
      const char * (*help)   (LWInstance, LWToolEvent *);
      int          (*dirty)  (LWInstance);
      int          (*count)  (LWInstance, LWToolEvent *);
      int          (*handle) (LWInstance, LWToolEvent *, int i,
                                LWDVector pos);
      int          (*start)  (LWInstance, LWToolEvent *);
      int          (*adjust) (LWInstance, LWToolEvent *, int i);
      int          (*down)   (LWInstance, LWToolEvent *);
      void         (*move)   (LWInstance, LWToolEvent *);
      void         (*up)     (LWInstance, LWToolEvent *);
      void         (*event)  (LWInstance, int code);
      LWXPanelID   (*panel)  (LWInstance);
   } LWLayoutToolFuncs;

done( inst )

Destroy the instance. Called when the user discards the tool.

draw( inst, custobj_access )

Display a wireframe representation of the tool in a 3D viewport. Typically this draws the handles.

helptext = help( inst, event )

Returns a text string to be displayed as a help tip for this tool.

dirty = dirty( inst )

Returns flag bit if either the wireframe or help string need to be refreshed.

nhandles = count( inst, event )

Returns the number of handles. If zero, then start is used to set the initial handle point.

priority = handle( inst, event, handle, pos )

Returns the 3D location and priority of the handle, or zero if the handle is currently invalid.

handle = start( inst, event )

Take an initial mouse-down position and return the index of the handle that should be dragged.

handle = adjust( inst, event, handle )

Drag the given handle to a new location and return the index of the handle that should continue being dragged (often the same as the input).

rawmouse = down( inst, event )

Process a mouse-down event. If this function returns false, handle processing will be done instead of raw mouse event processing.

move( inst, event )

Process a mouse-move event. This is only called if the down function returned true.

up( inst, event )

Process a mouse-up event. This is only called if the down function returned true.

event( inst, code )

Process a general event: DROP, RESET or ACTIVATE

panel = panel( inst )

Create and return a view-type xPanel for the tool instance. Use of this panel is currently not implemented.