Tools

Tools extend the functionality of PointShop3D at runtime, without changing existing code! They appear in the toolbar of PointShop3D and allow the user to interact with the Object, e.g. by painting or carving into its surface.
This tutorial describes how to write your own tools for PointShop3D and how to setup a Visual Studio project file as to compile them.

Setup the Visual Studio Project
Write the tools
Install the tools
Example

Setup the Visual Studio Project

Code Generation

Debug

Set Use run-time library to Multithreaded DLL

Release

Set Use run-time library to Multithreaded DLL

Preprocessor

Debug

Set Preprocessor definitions to TOOL_EXPORTS,WIN32,_DEBUG,_WINDOWS,_MBCS,_USRDLL,QT_THREAD_SUPPORT,QT_DLL
Set Additional include directories to $(QTDIR)\include

Release

Set Preprocessor definitions to TOOL_EXPORTS,WIN32,NDEBUG,_WINDOWS,_MBCS,_USRDLL,QT_THREAD_SUPPORT,QT_DLL
Set Additional include directories to $(QTDIR)\include,..\..\Core\DataStructures\src\

Link

Debug

Set Object/Library modules to kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib $(QTDIR)\lib\qt-mt230nc.lib $(QTDIR)\lib\qtmain.lib

Release

Top of page

Write the tool

Your plugin must implement the ToolInterface:

  class TOOL_API ToolInterface : public QObject {

    Q_OBJECT

    public:

      virtual QToolButton *addButtonToToolBar (QToolBar *toolBar) = 0;
      virtual QToolButton *getToolButton() = 0;
      virtual QCursor *getToolCursor() const = 0;
      virtual QWidget *getToolConfigurationWidget() const = 0;
      virtual bool isAvailable() const = 0;
      virtual void handleMousePressEvent (QMouseEvent *event);
      virtual void handleMouseReleaseEvent (QMouseEvent *event) = 0;
      virtual void handleMouseMoveEvent (QMouseEvent *event) = 0;
      virtual void handleKeyPressEvent (QKeyEvent *event);
      virtual void handleKeyReleaseEvent (QKeyEvent *event) = 0;
      virtual void selectTool() = 0;
      virtual void deselectTool() = 0;
      virtual void setGlobalTransformationActive (bool isOn);
      inline  bool isGlobalTransformationActive();

    public slots:

      virtual void handleRendererWidgetRepainted() = 0;

  };

addButtonToToolBar

This method is called once the tool is loaded and added dynamically to the QToolBar. It returns the QToolButton it has created and added to the QToolBar. This method can also be used to initialise the tool, e.g. setup the "What's This" text, connect to signals (e.g. the signal brushChanged from the BrushChooserTool as to get informed whenever the Brush has changed) or load icons and mouse cursors.

getToolButton

This method returns the QToolButton which has been created in addButtonToToolBar.

getToolCursor

This method returns the current QCursor which should appear as soon as the mouse is over the QWidget of the renderer.

getToolConfigurationWidget

This method returns a QWidget which appears in the Tool Settings dialog whenever this tool is selected. Its size must be 240 by 160 pixels (width, height). If no such QWidget is available 0 may be returned.

isAvailable

This method returns true if this tool is available. You may want to check:

If there is an Object loaded: Scene::getInstance()->getNofObjects()
If an interactive renderer is available: RendererManager::getInstance()->getMainRenderer()->isInteractive()
If there is a selection: CoreTools::getInstance()->getSelectionTool()->hasSelection()
If there are Brushes available: CoreResourceTools::getInstance()->getBrushChooserTool()->getSelectedBrush()
Any other conditions

Note that isAvailable is called automatically by the application whenever a new scene is loaded or the renderer changes and the plugin is enabled/disabled accordingly. If your plugin depends on Brushes or the selection it has to get informed about state changes itself by connecting to the corresponding signals sent by the SelectionTool (selectionChanged) respective the BrushChooserTool (brushChanged).

handleMousePressEvent

This method is called whenever the mouse button is pressed in the QWidget of the renderer. These are the places where you implement your actual tool functionality.

By default, this method checks if the global transformation mode is set to true (see setGlobalTransformationActive) and if yes the navigation tool is used to transform the scene. If you overwrite this method and want to use this functionality, you should call the ToolInterface::handleMousePressEvent.

handleMouseMoveEvent, handleMouseReleaseEvent

These methods are called whenever the mouse moves or the mouse button is released in the QWidget of the renderer. These are the places where you implement your actual tool functionality.

handleKeyPressEvent

This method is called whenever a key is pressed which has not yet been processed by the PointShop3D application (e.g. certain shortcut keys).

By default, pressing Q switches the global transformation mode (see setGlobalTransformationActive). If you overwrite this method and want to use this functionality, you should call the ToolInterface::handleKeyPressEvent.

handleKeyReleaseEvent

This method is called whenever a key is released which has not yet been processed by the PointShop3D application (e.g. certain shortcut keys).

selectTool

This method is called whenever the user has selected this tool. You might want to allocate some data here or render the image with additional data.

deselectTool

This method is called whenever the user has deselected this tool (by selecting another tool). You might want to deallocate some data here.

handleRendererWidgetRepainted

This slot is called whenever the QWidget of the renderer has repainted its content. You may use a QPainter to update your own drawings.

In addition to the ToolInterface the plugin must implement the following C-style functions:

  extern "C" {
    TOOL_API ToolInterface *createTool();
    TOOL_API const char *getToolName();
  }

TemplateTool.h

Top of page

TemplateTool.cpp

Top of page

Fr Aug 29 15:29:45 W. Europe Daylight Time 2003