MQCommandPlugin class

(new in Rev2.41)

MQCommandPlugin class inherits a MQStationPlugin class, and it provides functions to implement a command plug-in.

You can make a command plug-in with a simple implementation and without taking care of complex message procedures between a plug-in and a main part of Metasequoia by inheriting this MQCommandPlugin class and implementing required virtual functions.

In MQCommandPlugin class, each plug-in member functions and messages are declared as virtual functions. It is necessary to implement the virtual function in the inherited class.

 

Class
MQCommandPlugin Constructor
Declared in the super class
GetPlugInID Get a plug-in ID
GetPlugInName Get a plug-in name
EnumString Get a string displayed on a button
Initialize Initialize an application
Exit Exit an application
Activate A message for activating or deactivation a window
IsActivated A message for checking an activated state of a window
OnMinimize A message for minimizing a window
OnReceiveUserMessage A message for receive a plug-in own message
OnDraw A message for drawing
OnNewDocument A message for initializing a document
OnEndDocument A message for exiting a document
OnSaveDocument A message for saving a document
OnUndo A message for an undo
OnRedo A message for an redo
OnUpdateUndo A message for updating an undo state
OnObjectModified A message for editing objects
OnObjectSelected A message for selecting objects
OnUpdateObjectList A message for changing a current object
OnMaterialModified A message for modifying parameters of materials
OnUpdateMaterialList A message for changing a current material
OnUpdateScene A message for updating a scene
Plug-in
GetPlugInType Get a plug-in type
Message procedure
OnLeftButtonDown When a left button is pressed
OnLeftButtonMove When a mouse is moved with pressing a left button
OnLeftButtonUp When a left button is released
OnMiddleButtonDown When a middle button is pressed
OnMiddleButtonMove When a mouse is moved with pressing a middle button
OnMiddleButtonUp When a middle button is released
OnRightButtonDown When a right button is pressed
OnRightButtonMove When a mouse is moved with pressing a right button
OnRightButtonUp When a right button is released
OnMouseMove When a mouse is moved
OnMouseWheel When a mouse wheel is rotated
OnKeyDown When a key is pressed
OnKeyUp When a key is released
Supplemental functions for the super class
OpenSetting Open a setting file
CloseSetting Close a setting file
GetResourceString Get a resource string
GetSettingValue Get a setting value
GetSystemColor Get a system color
GetResourceCursor Get a default mouse cursor
GetScreenMouseCursor Get a mouse cursor for a screen
SetScreenMouseCursor Set a mouse cursor for a screen
SendUserMessage Send a plug-in own message to the other plug-ins
WindowClose Close a window
BeginCallback Begin the callback procedure
ExecuteCallback Implementation for the callback
CreateDrawingObject Add a drawing object in OnDraw()
CreateDrawingMaterial Add a material for a drawing object in OnDraw()
DeleteDrawingObject Delete a drawing object
DeleteDrawingMaterial Delete a material for drawing objects
GetCurrentUndoState Get a current undo state
GetSceneOption Get display options of the scene
Supplemental functions
UpdateUndo Update an undo buffer
RedrawScene Reserve updating a scene
RedrawAllScene Reserve updating all scenes
GetEditOption Get edit options
GetSnappedPos Get a snapped position
HitTest Detect a target
HitTestObjects Detect a target in specified objects
SetMouseCursor Set a mouse cursor
SetStatusString Set a display string on a status bar
SetHelpPage Set a help page

struct MOUSE_BUTTON_STATE {
    POINT MousePos;	// The position of a mouse cursor
    int Wheel;		// The amount of rotations of a mouse wheel (Multiple or divisor of WHEEL_DELTA)
    BOOL LButton;	// Whether the left button is pressed
    BOOL MButton;	// Whether the middle button is pressed
    BOOL RButton;	// Whether the right button is pressed
    BOOL Shift;		// Whether the Shift key is pressed
    BOOL Ctrl;		// Whether the Ctrl key is pressed
    BOOL Alt;		// Whether the Alt key is pressed
    float Pressure; // The pressure of a tablet or a touch operation (0-1)    
};

This is a structure for storing status of mouse buttons and a keyboard.

(new in Rev4.20)

Pressure is added.


MQCommandPlugin::MQCommandPlugin();

This is a constructor.


virtual int MQCommandPlugin::GetPlugInType();

Return value
A plug-in type
[MQPLUGIN_TYPE_COMMAND] Command

It implements a virtual function declared in MQBasePlugin::GetPlugInType(). It is not necessary to implement this function in an inherited class.


virtual BOOL MQCommandPlugin::OnLeftButtonDown(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a left button is pressed.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnLeftButtonMove(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a mouse is moved with pressing a left button.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnLeftButtonUp(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a left button is released.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnMiddleButtonDown(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a middle button is pressed.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnMiddleButtonMove(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a mouse is moved with pressing a middle button.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnMiddleButtonUp(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a middle button is released.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnRightButtonDown(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a right button is pressed.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnRightButtonMove(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a mouse is moved with pressing a right button.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnRightButtonUp(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a right button is released.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnMouseMove(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a mouse has been moved.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnMouseWheel(MQDocument doc, MQScene scene, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a mouse wheel has been rotated.

The amount of a rotation of a wheel is stored in state.Wheel by the multiple or divisor of WHEEL_DELTA.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnKeyDown(MQDocument doc, MQScene scene, int key, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
key
A virtual key code
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a key is pressed.

The virtual key code of 'key' is the same as the contents acquired by WM_KEYDOWN.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


virtual BOOL MQCommandPlugin::OnKeyUp(MQDocument doc, MQScene scene, int key, MOUSE_BUTTON_STATE& state);

doc
A document
scene
A scene
key
A virtual key code
state
States of mouse buttons
Return value
Whether the message has been done with
[TRUE] The message has been done with
[FALSE] The message has not been done with

This method is called when a key is released.

The virtual key code of 'key' is the same as the contents acquired by WM_KEYUP.

It must return TRUE if a plug-in own operation has been done with, and return FALSE if when you want to do with a default operation.


void MQCommandPlugin::UpdateUndo();

void MQCommandPlugin::UpdateUndo(const wchar_t *str);

str
A displayed string

It updates an undo buffer.

Actually, this function only reserves an updating of an undo buffer. It is done with after exiting an event procedure in a plugin and returning a procedure to the main part of Metasequoia.

(new in Rev4.30)

str specifies a displayed string in a menu and so on.

 

Attention: In Ver2.4.3 or older version, it does not make any change by calling UpdateUndo() in ExecuteCallback().


void MQCommandPlugin::RedrawScene(MQScene scene);

scene
A scene

It updates the specified scene.

Actually, this function only reserves to redraw. It is done with after exiting an event procedure in a plugin and returning a procedure to the main part of Metasequoia.


void MQCommandPlugin::RedrawAllScene();

It updates for all scenes.

Actually, this function only reserves to redraw. It is done with after exiting an event procedure in a plugin and returning a procedure to the main part of Metasequoia.


void MQCommandPlugin::GetEditOption(EDITOPTION& option);

option
Edit options

It gets edit options. The edit options are stored in 'option'.

struct EDIT_OPTION {
    BOOL EditVertex;                // Enable vertex editing
    BOOL EditLine;                  // Enable line editing
    BOOL EditFace;                  // Enable face editing
    BOOL SelectRect;                // Selection with rectangle
    BOOL SelectRope;                // Selection with rope
    BOOL SnapX;                     // Edit along X axis
    BOOL SnapY;                     // Edit along Y axis
    BOOL SnapZ;                     // Edit along Z axis
    COORDINATE_TYPE CoordinateType; // A type of a coordinate
    SNAP_GRID_TYPE SnapGrid;        // Snap to a grid
    BOOL Symmetry;                  // Symmetry editing
    float SymmetryDistance;         // Distance for symmetry editing
    BOOL CurrentObjectOnly;         // Edit current object only
    SNAP_PLANE_TYPE SnapPlane;      // Snap to a plane (new in Rev 4.20)
    MQPoint SnapPlanePos;           // Position of snapping plane (new in Rev 4.20)
    MQPoint SnapPlaneDir;           // Direction of snapping plane (new in Rev 4.20)
    BOOL SnapVertex;                // Snap to vertices (new in Rev 4.20)
    BOOL SnapLine;                  // Snap to lines (new in Rev 4.20)
    BOOL SnapFace;                  // Snap to faces (new in Rev 4.20)
};
CoordinateType
A type of a coordinate
[COORDINATE_SCREEN] Screen coordinate
[COORDINATE_WORLD] World coordinate
[COORDINATE_LOCAL] Local coordinate
SnapGrid
Snap in each axis (Use & operator for checking because multiple values are set)
[SNAP_GRID_X] Snap in the X axis
[SNAP_GRID_Y] Snap in the Y axis
[SNAP_GRID_Z] Snap in the Z axis

[deprecated]
MQPoint MQCommandPlugin::GetSnappedPos(MQScene scene, const MQPoint& p, SNAP_GRID_TYPE type);

(new in Rev4.20)
MQPoint MQCommandPlugin::GetSnappedPos(MQScene scene, const MQPoint& p, const EDIT_OPTION& option, const GET_SNAP_PARAM& snap_param);

scene
A scene
p
A position before snapping
type
The direction for snapping (One or multiple values can be selected)
[SNAP_GRID_X] Snap in the X axis
[SNAP_GRID_Y] Snap in the Y axis
[SNAP_GRID_Z] Snap in the Z axis
option
Edit option
snap_param
Snapping parameters
Return value
A position after snapping

It gets a snapped position for a grid, a plane, vertices, lines, faces and so on specified in the edit option.

'eye_dir' is usually specified TRUE when a vertices is operated directly or a center of a handle is operated. It is FALSE when a X, Y or Z axis of a handle is operated.

Please change the contents of the edit option if you want to snap to elements that are not specified in the current edit option.

 

Attention: The deprecated format is still left, but please replace it with the new format to enable to snap elements except a grid.

struct GET_SNAP_PARAM {
    BOOL SnapEyeDir;                // Snap on the eye direction
    BOOL IgnoreSelected;            // Ignore selected elements
    BOOL IgnoreCurObj;              // Ignore current object
};
SnapEyeDir
It specifies whether to snap to the eye direction.
It is usually specified TRUE when a vertices is operated directly or a center of a handle is operated. It is FALSE when a X, Y or Z axis of a handle is operated.
IgnoreSelected
It specifies whether ignore selected vertices, lines and faces or not.
When the selected part is moved, TRUE is specified for avoiding to snap the target to move.
IgnoreCurObj
It specifies whether ignore selected vertices, lines and faces or not.
When the current object is moved, TRUE is specified for avoiding to snap the current object to move.

BOOL MQCommandPlugin::HitTest(MQScene scene, POINT p, HIT_TEST_PARAM& param);

scene
A scene
p
A screen coordinate
param
Parameters
Return value
[TRUE] A vertex, a line or a face has been detected
[FALSE] Nothing is detected

(new in Rev2.49)

It detects a face, a line or a vertex on or near the specified position in the scene.

When you call this function with input the target to TestVetex, TestLine and TestFace in param and this function returns TRUE, it stores a type of the target into HitType, a position of the target into HitPos, and indices into ObjectIndex, VertexIndex, LineIndex and FaceIndex.

struct HIT_TEST_PARAM {
    // input
    BOOL TestVertex;        // Detect vertices
    BOOL TestLine;          // Detect lines
    BOOL TestFace;          // Detect faces
    BOOL DisableFrontOnly;  // Disable of detection of front faces only

    // output
    HIT_TYPE HitType;       // A type of the detected target
    MQPoint HitPos;         // A position of the detected target
    int ObjectIndex;        // A index of the detected object
    int VertexIndex;        // A index of the vertex (Only when a vertex is detected)
    int LineIndex;          // A index of the line (Only when a line is detected)
    int FaceIndex;          // A index of the face (Only when a face is detected)
};
TestVertex
Whether to detect vertices
[TRUE] Enable to detect vertices
[FALSE] Disable to detected vertices
TestLine
Whether to detect lines
[TRUE] Enable to detect lines
[FALSE] Disable to detect lines
TestFace
Whether to detect faces
[TRUE] Enable to detect faces
[FALSE] Disable to detect faces
HitType
A kind of the detected target
[HIT_TEST_VERTEX] A vertex has been detected
[HIT_TEST_LINE] A line has been detected
[HIT_TEST_FACE] A face has been detected
[HIT_TEST_NONE] Nothing has been detected
HitPos
A position of the detected target (in a world coordinate)
ObjectIndex
An index of the detected object
VertexIndex
An index of the detected vertex (Only when a vertex has been detected)
LineIndex
An index of the detected line (Only when a line has been detected)
FaceIndex
An index of the detected face (Only when a line or a face has been detected)


Example for calling a function (in OnLeftButtonDown, OnMouseMove and so on)
    // Get edit options.
    EDIT_OPTION option;
    GetEditOption(option);

    // Detect the target on the mouse cursor, and select it.
    HIT_TEST_PARAM param;
    param.TestVertex = option.EditVertex;
    param.TestLine = option.EditLine;
    param.TestFace = option.EditFace;
    if(HitTest(scene, state.MousePos, param)){
        if(param.HitType == HIT_TYPE_VERTEX){
            doc->AddSelectVertex(param.ObjectIndex, param.VertexIndex);
        }else if(param.HitType == HIT_TYPE_FACE){
            doc->AddSelectFace(param.ObjectIndex, param.FaceIndex);
        }else if(param.HitType == HIT_TYPE_LINE){
            doc->AddSelectLine(param.ObjectIndex, param.FaceIndex, param.LineIndex);
        }
    }


BOOL MQCommandPlugin::HitTestObjects(MQScene scene, POINT p, const std::vector<MQObject>& objects, HIT_TEST_PARAM& param);

scene
A scene
p
A screen coordinate
objects
An array of objects
param
Parameters
Return value
[TRUE] A vertex, a line or a face has been detected
[FALSE] Nothing is detected

(new in Rev4.02)

It detects a face, a line or a vertex on or near the specified position in the specified objects.

'objects' can contain not only objects in the document but also a drawing object created by CreateDrawingObject() and an object created by MQ_CreateObject() which is not added to the document.

An index in the 'objects' array will be stored to 'param.ObjectIndex' when anything is detected.


void MQCommandPlugin::SetMouseCursor(HCURSOR cursor);

cursor
A mouse cursor for views

(new in Rev2.46)

It changes a mouse cursor for views.

Please specify a cursor that is obtained by MQBasePlugin::GetResourceCursor() or is a resource cursor obtained by LoadCursor() of Win32-API with the DLL instance. The operation is not ensured when a predefined cursor obtained by LoadCursor() with the NULL instance is specified.


void MQCommandPlugin::SetStatusString(const char *str);

void MQCommandPlugin::SetStatusString(const wchar_t *str);

str
A display string (ANSI character code for 'char')

(new in Rev2.49)

It sets a display string on a status bar.


void MQCommandPlugin::SetHelpPage(const wchar_t *url);

url
URL for a help page

(new in Rev4.11)

It specifies a URL for a help page displayed with synchronizing a command.

This function is not used in a user plug-in because it is necessary for a help page. It is used by standard embeded plug-ins.