mgui/toolbase.h

Go to the documentation of this file.

/**
 * \file mgui/toolbase.h
 * \brief MGUI::TOOL_BASE class definitions.
 *
 * \if NODOC
 * $Id: toolbase.h_v 1.6 2003/12/16 15:49:31 mju Exp $
 *
 * $Log: toolbase.h_v $
 * Revision 1.6  2003/12/16 15:49:31  mju
 * Use dlgshell.
 *
 * Revision 1.5  2003/10/01 22:32:36  dwilliss
 * doxygen
 *
 * Revision 1.4  2003/09/15 13:49:32  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.3  2003/01/10 23:07:47  mju
 * Initial tool set now donw.
 *
 * Revision 1.2  2003/01/09 21:05:34  mju
 * Revised design.
 *
 * Revision 1.1  2003/01/08 22:50:23  mju
 * Initial revision
 * \endif
**/

#ifndef  INC_MGUI_TOOLBASE_H
#define  INC_MGUI_TOOLBASE_H

#ifndef  INC_MGUI_CTRL_H
   #include <mgui/ctrl.h>
#endif

#ifndef  INC_MGUI_TOOLCANV_H
   #include <mgui/toolcanv.h>
#endif

#ifndef  INC_MGUI_DLGSHELL_H
   #include <mgui/dlgshell.h>
#endif

#ifndef  INC_MI32_TRANS2DC_H
   #include <mi32/trans2dc.h>
#endif

#ifndef GENERATING_DOXYGEN_OUTPUT
class REGION2D;
namespace MGD {
   class CONTEXT;
   }
#endif // GENERATING_DOXYGEN_OUTPUT

namespace MGUI {

//=====================================================================================================================
//!   Base class for graphic tools.
//! Derived tool clients should only override the v_OnNotifyChange virtual method to receive tool change notifications.
//! Tool implementations should NOT override the v_OnNotifyChange virtual methods (but may define new v_OnNotify...
//! methods) as this avoids the need for derived tool client classes to call base methods.
class TOOL_BASE {
   public:

      //! Adjustment flags for Move() and Resize() methods.
      enum ADJUSTFLAGS {
         ADJUST_Default =        0x00,       //!< Values are relative tool coordinates
         ADJUST_Absolute =       0x01,       //!< Adjustment values are absolute
         ADJUST_ScreenCoords =   0x02,       //!< Adjustment values are in screen pixels
         ADJUST_Notify =         0x80        //!< Send notification message
         };

      //! Options for standard and manual control forms.
      enum CTRLOPT {
         CTRLOPT_Default =       0x00,
         CTRLOPT_Manual =        0x01,    //!< Include "manual" controls if available
         CTRLOPT_GPS =           0x02,    //!< Include "gps" controls if supported
         CTRLOPT_SnapGrid =      0x04,    //!< Include "snap to grid" toggle if supported
         CTRLOPT_NoManualProj =  0x08     //!< Don't allow manual projection / distance controls
         };

      //! sequence
      enum CHANGESEQ {
         CHANGESEQ_None =     0,
         CHANGESEQ_Begin =    1,
         CHANGESEQ_Continue = 2,
         CHANGESEQ_End =      3,
         CHANGESEQ_Cancel =   4
         };

      enum CHANGETYPE {
         CHANGETYPE_None =    0,
         CHANGETYPE_Shift =   1,
         CHANGETYPE_Resize =  2,
         CHANGETYPE_Rotate =  3,
         CHANGETYPE_Shear =   4,
         CHANGETYPE_Edit =    5,
         CHANGETYPE_Create =  6,
         CHANGETYPE_Clear =   7
         };

      //! Marker types, not all types are supported by all tools.
      enum MARKER {
         MARKER_X =           0,    //!< Diagonal cross
         MARKER_Plus =        1,    //!< Orthogonal cross
         MARKER_ArrowIn =     2,    //!< Arrow pointing in for line endpoint
         MARKER_ArrowOut =    3,    //!< Arrow pointing out for line endpoint
         MARKER_None =        4,    //!< No marker
         MARKER_Circle =      5,    //!< Circle
         MARKER_Flat =        6,    //!< Flat line endpoint
         MARKER_Square =      7,    //!< Square
         };

      enum PENCOLOR {
         PENCOLOR_Primary,          //!< Primary tool drawing color
         PENCOLOR_Inactive,         //!< Color for inactive elements (eg in POLYLINE tool)
         PENCOLOR_Highlight,        //!< Color for highlighting
         PENCOLOR_COUNT             //!< Number of pens, always last
         };

      //! Snap grid definition.
      class SNAPGRID {
         public:

            //! Default constructor.
            SNAPGRID (
               );

            //! Construct with specified interval.
            explicit SNAPGRID (
               const DPOINT2D& interval
               );

            //! Construct with specified interval and transformation.
            SNAPGRID (
               const DPOINT2D& interval,
               const TRANS2D_AFFINE& trans      //!< Transformation from tool to snap grid coordinates
               );

            //! Adjust specified point to snap grid
            void Adjust (
               DPOINT2D& pt                     //!< Point in "tool" coordinates
               ) const;

            //! Get snap interval.
            const DPOINT2D& GetInterval (
               ) const { return (m_interval); }

            //! Get transformation from tool to snapgrid coordinates.
            const TRANS2D_AFFINE& GetTrans (
               ) const { return (m_trans); }

            //! Determine if snapgrid is valid.
            bool IsValid (
               ) const { return (m_interval.x > 0 && m_interval.y > 0); }

            //! Set snap interval.
            void SetInterval (
               const DPOINT2D& interval
               ) { m_interval = interval; }

            //! Set transformation from tool to snapgrid coordinates.
            void SetTrans (
               const TRANS2D_AFFINE& trans      //!< Transformation from tool to snap grid coordinates
               ) { m_trans = trans; }

         private:
            #ifndef GENERATING_DOXYGEN_OUTPUT
            DPOINT2D m_interval;
            TRANS2D_AFFINE m_trans;
            #endif // GENERATING_DOXYGEN_OUTPUT
         };

      //! Get global tool pen color reference.
      //! @return Color reference.
      static UINT32 GetPenColorRef (
         PENCOLOR pencolor = PENCOLOR_Primary
         );

      //! Set global tool pen color.
      static void SetPenColorRef (
         PENCOLOR pencolor,
         UINT32 ColorRef                        //!< Color reference
         );

      //! Destructor
      virtual ~TOOL_BASE () = 0;

      //! Activate the tool.
      //! If another tool is currently active on the canvas it will be automatically deactivated.
      void Activate (
         );

      //! Clear current tool position, erasing all graphics.
      void ClearPosition (
         );

      //! Create "form" with tool-specific controls.
      //! @return Pointer to FORM or NULL if tool has no "control" form.
      MGUI::FORM* CreateControlForm (
         MGUI::LAYOUT_PANE_BASE& ParentPane, //!< Parent pane
         CTRLOPT ctrlopt                     //!< Control options
         ) { return (v_CreateControlForm(ParentPane,ctrlopt)); }

      //! Create "form" with tool-specific manual-entry controls.
      //! @return Pointer to FORM or NULL if tool has no "manual entry" form.
      MGUI::FORM* CreateManualForm (
         MGUI::LAYOUT_PANE_BASE& ParentPane, //!< Parent pane
         CTRLOPT ctrlopt                     //!< Control options
         ) { return (v_CreateManualForm(ParentPane,ctrlopt)); }

      //! Deactivate this tool.
      void Deactivate (
         );

      //! Generate region from tool.
      ERRVALUE GenerateRegion (
         REGION2D& region                 //!< Region in 'tool' coordinates returned
         ) const { return (v_GenerateRegion(region)); }

      //! Get movement values associated with arrow keys.
      //! @return Values in "tool" coordinates.
      const DPOINT2D& GetArrowKeyDeltas (
         ) const { return (m_ArrowDelta); }

      //! Get current control options settings.
      CTRLOPT GetControlOptions (
         ) const { return (m_ctrlopt); }

      //! Get transformation between "tool" and "window" coordinates.
      const TRANS2D_AFFINE& GetTransToWindow (
         ) const { return (m_ToolToWindow); }

      //! Get "canvas" associated with tool.
      TOOLCANVAS* GetCanvas (
         ) const { return (m_canvas); }

      //! Get extents of canvas.
      void GetCanvasExtents (
         DRECT2D& extents
         ) const;

      //! Determine if tool controls available.
      bool HasControls (
         ) const { return (m_ControlNeed != CONTROLNEED_None); }

      //! Determine if has manual data entry controls.
      bool HasManualControls (
         ) const { return (m_HasManualControls); };

      //! Check if tool is currently "active".
      bool IsActive (
         ) const { return (m_IsActive); }

      //! Determine if tool is "resizable".
      bool IsResizable (
         ) const { return (m_Resizable); }

      //! Determine if tool is "rotatable".
      bool IsRotatable (
         ) const { return (m_Rotatable); }

      //! Check if tool is "suspended"
      bool IsSuspended (
         ) const { return (m_SuspendCount > 0); }

      //! Check if tool has a valid position set
      bool HasPosition (
         ) const { return (m_PosnSet); }

      //! Move the tool by the specified amount.
      void Move (
         double dx,
         double dy,
         ADJUSTFLAGS flags
         );

      //! Resize the tool.
      void Resize (
         double dx,
         double dy,
         ADJUSTFLAGS flags
         );

      //! Resume the tool after performing drawing operation on the canvas.
      void Resume (
         );

      //! Set movement amounts associated with arrow keys.
      void SetArrowKeyDeltas (
         double dx,
         double dy
         );

      //! Set whether user can start drawing a "new" tool.
      void SetCanStartNew (
         bool canstartnew
         ) { m_CanStartNew = canstartnew; }

      //! Set controls to appear on dialog when shown.
      //! If used, this must be called before tool is first activated.
      void SetControlOptions (
         CTRLOPT ctrlopt                        //!< Control settings
         ) { m_ctrlopt = ctrlopt; }

      //! Set whether tool is resizable.
      void SetResizable (
         bool resizable
         ) { m_Resizable = resizable; }

      //! Set whether tool is rotatable.
      void SetRotatable (
         bool rotatable
         ) { m_Rotatable = rotatable; }

      //! Set transformation between "tool" and "window" coordinates.
      void SetTransToWindow (
         const TRANS2D_AFFINE& trans
         );

      //! Determine if snap grid is currently in use.
      bool SnapGridIsActive (
         ) const { return (m_UseSnapGrid); }

      //! Get snap grid settings.
      const SNAPGRID& SnapGridGet (
         ) const { return (m_snapgrid); }

      //! Set snap grid parameters.
      void SnapGridSet (
         SNAPGRID& parms
         );

      //! Set whether to use snap grid or not.
      void SnapGridSetActive (
         bool active
         ) { m_UseSnapGrid = active; }

      //! Suspend tool prior to performing a drawing operation on the canvas.
      void Suspend (
         );

   protected:

      enum CONTROLNEED {
         CONTROLNEED_None,
         CONTROLNEED_Optional,
         CONTROLNEED_Required
         };

      //! Constructor
      explicit TOOL_BASE (
         TOOLCANVAS *canvas,
         CONTROLNEED ControlNeed,         //!< Need for control dialog or form
         bool HasManualControls           //!< Optional manual controls available
         );

      //! Utility methods for use by tool implementation.

      void AdjustBegin (CHANGETYPE changetype, bool redraw = true);

      void AdjustEnd (bool releasecapture = true, bool cancel = false);

      void ApplyMoveDeltas (
         DPOINT2D& point,
         double dx,
         double dy,
         ADJUSTFLAGS flags
         ) const;

      //! Snap point to current snap grid, if no snapping enabled point unchanged.
      void ApplySnap (
         DPOINT2D& point                     //!< Point to adjust
         ) const;

      bool CanStartNew (
         ) const { return (m_CanStartNew); }

      //! Check rectangle against tool limits
      int CheckBounds (const DRECT2D&, DRECT2D*) const;

      //! Draw a marker (MARKER...) in the position and size specified.
      void DrawMarker (MGD::CONTEXT *dc, const LPOINT2D& centerpoint, const LPOINT2D& dirpoint, MARKER marker, UINT16 size) const;

      bool GetArrowDeltas (KEYCODE, double*, double*);

      //! Get drawing context.
      //! Will set PixelFunction to Invert if modifying, Copy if not.
      MGD::CONTEXT* GetDrawingContext (
         );

      CHANGETYPE GetChangeType (
         ) const { return (m_ChangeType); }

      //! Determine if tool's canvas has the mouse "captured".
      bool IsMouseCaptured (
         ) const;

      //! Send notification that "change" action has or will occur.
      void NotifyChange (
         CHANGESEQ changeseq,                //!< Sequence
         CHANGETYPE changetype               //!< Type
         ) { v_OnNotifyChange(changeseq,changetype); }

      //! Restore background for entire tool canvas window.
      void RestoreBackground (
         ) const;

      //! Restore background for specified rectangle.
      void RestoreBackground (
         const LRECT2D& rect,                //!< Rectangle in 'canvas' coordinates to restore
         bool AddLineWidth = true            //!< Expand rectangle by 'LineWidth+1' to allow for wide lines
         ) const;

      void RestoreDrawingContext (
         );

      //! Set mouse cursor.
      void SetCursor (
         CURSORID cursorid
         ) const { m_canvas->SetCursor(cursorid); }

      void SetHasPosition (
         bool HasPosition = true
         ) { m_PosnSet = HasPosition; }

      //! Transform DPOINT2D from "tool" to "window" coordinates.
      LPOINT2D TransToolToWindow (
         const DPOINT2D& point
         ) const;

      //! Transform MGUI::POINT point in "window" to "tool" coordinates.
      DPOINT2D TransWindowToTool (
         MGUI::POINT point
         ) const { return (m_ToolToWindow.ConvertInverse(point.m_x,point.m_y)); }

      //! Transform LPOINT2D point in "window" to "tool" coordinates.
      DPOINT2D TransWindowToTool (
         const LPOINT2D& point
         ) const { return (m_ToolToWindow.ConvertInverse(point.x,point.y)); }

   private:

      #ifndef GENERATING_DOXYGEN_OUTPUT

      class TOOLDLG : public MGUI::DLGSHELL {
         public:
            TOOLDLG (TOOL_BASE& tool);
         private:
            class PAGECONTROLS : public MGUI::LAYOUT_PAGE {
               public:
                  PAGECONTROLS (TOOLDLG& dlg): m_dlg(dlg) { }
                  virtual ~PAGECONTROLS () { }
               private:
                  TOOLDLG& m_dlg;
                  virtual void OnInitPage ();
               };
            class PAGEMANUAL : public MGUI::LAYOUT_PAGE {
               public:
                  PAGEMANUAL (TOOLDLG& dlg): m_dlg(dlg) { }
                  virtual ~PAGEMANUAL () { }
               private:
                  TOOLDLG& m_dlg;
                  virtual void OnInitPage ();
               };
            TOOL_BASE& m_tool;
            MGUI::LAYOUT_BOOK m_TabBook;
            PAGECONTROLS m_PageControls;
            PAGECONTROLS m_PageManual;
            virtual ERRVALUE v_CreateContent ();
            friend class PAGECONTROLS;
            friend class PAGEMANUAL;
         };

      // Static members

      static UINT32 s_PenColor[PENCOLOR_COUNT];

      // Explicitly initialized
      TOOLCANVAS *m_canvas;
      CONTROLNEED m_ControlNeed;          //!< Need for controls
      bool m_HasManualControls;           //!< Tool supports manual controls
      INT8 m_LineWidth;                   //!< Tool line width
      DPOINT2D m_ArrowDelta;              //!< Increments for arrow key movement, tool coords
      INT32 m_SuspendCount;               //!< Number of times that this tool has been suspended
      CHANGETYPE m_ChangeType;            //!< Change type for use with button-up
      bool m_IsActive;                    //!< Tool is in use, Activate() has been called
      bool m_PosnSet;                     //!< Tool graphic has a position and is viewable
      bool m_UseSnapGrid;                 //!< Use snap grid
      bool m_HasArrowDeltas;              //!< Deltas for arrow key movement is set
      bool m_IsUserModifying;             //!< Is user modifying tool position
      mutable bool m_InRestoreBG;
      bool m_InDeactivateFunc;            //!< Deactivate() is called, avoid doing redraws
      bool m_CanStartNew;                 //!< User can start drawing new tool, default=true
      bool m_Resizable;                   //!< Tool is resizable, default=true
      bool m_Rotatable;                   //!< Tool is rotatable, default=true
      CTRLOPT m_ctrlopt;
      TOOLDLG m_ToolDlg;

      // Self-initializing
      TRANS2D_AFFINE m_ToolToWindow;      //!< Tool <--> Window transformation
      SNAPGRID m_snapgrid;          //!< Snap grid information structure

      void CreateToolDlg ();
      void DrawTool (MGD::CONTEXT*);
      void DrawTool (MGD::CONTEXT*, UINT32);
      void DrawTool (UINT32);
      bool OnKey (MGUI::POINT point, MGUI::KEYCODE, KEYSTATE);
      void SetCanvas (TOOLCANVAS *canvas) { m_canvas = canvas; }

      #endif // GENERATING_DOXYGEN_OUTPUT

      // MGUI::TOOL_BASE Overridable virtual methods.

      //! Create "form" with tool-specific controls.
      //! @return Pointer to FORM or NULL if tool has no "control" form.
      virtual MGUI::FORM* v_CreateControlForm (
         MGUI::LAYOUT_PANE_BASE& ParentPane, //!< Parent pane
         CTRLOPT ctrlopt                     //!< Control options
         );

      //! Create "form" with tool-specific manual-entry controls.
      //! @return Pointer to FORM or NULL if tool has no "manual entry" form.
      virtual MGUI::FORM* v_CreateManualForm (
         MGUI::LAYOUT_PANE_BASE& ParentPane, //!< Parent pane
         CTRLOPT ctrlopt                     //!< Control options
         );

      //! Do actual drawing of tool graphic.
      virtual void v_DoDraw (MGD::CONTEXT*) = 0;

      //! Move the tool.
      virtual void v_DoMove (double x, double y, ADJUSTFLAGS);

      //! Size the tool.
      virtual void v_DoSize (double x, double y, ADJUSTFLAGS);

      //! Generate region from tool.
      //! @return TRUE if region generated, FALSE if not, < 0 if error.
      virtual int v_GenerateRegion (
         REGION2D& region                    //!< Generated region in 'tool' coordinates returned
         ) const;

      //! Called to get title of tool control dialog.
      virtual MISTRING v_GetDialogTitle (
         ) const;

      //! Called when tool is "activated".
      virtual void v_OnActivate ();

      //! Called when tool is cleared.
      virtual void v_OnClear ();

      //! Called when tool is deactivated.
      virtual void v_OnDeactivate ();

      //! Called when key pressed/released.
      //! @return 'true' if key handled, 'false' if not.
      //! Should not be called directly, called by OnKey.
      virtual bool v_OnKey (MGUI::POINT point, MGUI::KEYCODE, KEYSTATE);

      //! Called when left mouse button pressed.
      virtual void v_OnLButtonDown (MGUI::POINT point, KEYSTATE keystate) = 0;

      //! Called when left mouse button released.
      virtual void v_OnLButtonUp (MGUI::POINT point, KEYSTATE keystate);

      //! Called when mouse cursor is moved.
      virtual void v_OnMouseMove (MGUI::POINT point, KEYSTATE keystate) = 0;

      //! Called when change made to tool position, shape, size, etc.
      virtual void v_OnNotifyChange (
         CHANGESEQ changeseq,                //!< Sequence
         CHANGETYPE changetype               //!< Type
         );

      //! Called when right mouse button pressed.
      //! Often overridden to show a popup menu.
      virtual void v_OnRButtonDown (MGUI::POINT point, KEYSTATE keystate);

      //! Called when right mouse button released.
      //! Often overridden to perform an 'apply' action.
      virtual void v_OnRButtonUp (MGUI::POINT point, KEYSTATE keystate);

      //! Called when tool is "resumed" after being suspended.
      virtual void v_OnResume ();

      //! Called when tool to window transformation is set.
      virtual void v_OnSetTransToWindow ();

      //! Called when canvas is resized.
      virtual void v_OnSizeCanvas ();

   friend class TOOL_BASE::TOOLDLG;
   friend class TOOLCANVAS;
   };
DEFINE_ENUM_OPERATORS(TOOL_BASE::ADJUSTFLAGS);
DEFINE_ENUM_OPERATORS(TOOL_BASE::CTRLOPT);


//=====================================================================================================================
//! TOOL_LIMITED - Tool with limit support
class TOOL_LIMITED : public TOOL_BASE {
   public:

      //! Destructor
      virtual ~TOOL_LIMITED ();

      //! Set coordinate limits.
      void SetLimits (
         const DRECT2D& rect                    //!< Limits to set
         );

      //! Set whether limits are enforced.
      //! If SetLimits() has not been called then the tool will be limited to the visible canvas extent.
      void SetLimitsEnforced (
         bool enforced = true                   //!< Set if limits are enforced
         );

   protected:

      //! Constructor
      explicit TOOL_LIMITED (
         TOOLCANVAS *canvas,
         CONTROLNEED ControlNeed,         //!< Need for control dialog or form
         bool HasManualControls           //!< Optional manual controls available
         );

      //! Get limits.
      const DRECT2D& GetLimits (
         ) const { return (m_Limits); }

      //! Determine if limits are enforced.
      bool IsLimitsEnforced (
         ) const { return (m_LimitsEnforced); }

      //! Called when tool is "activated".
      //! Derived class must call base class method BEFORE performing own processing.
      virtual void v_OnActivate ();

      //! Called when tool to window transformation is set.
      //! Derived class must call base class method BEFORE performing own processing.
      virtual void v_OnSetTransToWindow ();

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      bool m_LimitsEnforced;              //!< Limits are enforced
      bool m_LimitsSet;                   //!< Limits have been set, otherwise defaults to window extents
      DRECT2D m_Limits;                   //!< Position ranges, default to entire parent window range
      //! TOOL_BASE overrides.
      virtual void v_OnSizeCanvas ();
      //! Methods

      //! Called when limits are changed.
      virtual void v_OnChangeLimits ();

      void UpdateLimits ();
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

//=====================================================================================================================

}  // End namespace MGUI

#endif   // INC_MGUI_TOOLBASE_H

---