#include <helpers/layout.h>

Description

Widely-used helper file with base implementation of interfaces, requied for implementing ZModeler tools. Since tools implementation for ZModeler is quite comprehensive task and requires implementation of several interfaces, some base robust work is already done in supplied classes.

Each tool in ZModeler is presented with core::tools:ITool interface and must transparetnly inherit core::INamed interface. Additionally it have to provide properly initialized core::layou:ILayou-derived interface with tools layout information. Some layout interfaces supply an extended version which allows tool to have custom icons in menu.

For simplicity of this task, helper file layout.h provides implementation classes for all zmodeler layout types. Also, it merges implementation of tool's interface with it's layout, providing an almost ready to use tool-with-layout base class. Thus, you need to consider helper class to derive your tool from to have a working tool. Of cause you'll need to overload some methods and initialize tool's title and layout information, while the rest of implementation is available.

Helper base (partitial functionality support) classes.

class CZMToolHelper Default implementation of core::tools:ITool and core::INamed interfaces in one class. This common "tool" is merged with implementations of layout classes to make a base for your tools.
class CCursorSupport Extension class adds custom cursors support to your tool by implementing core::ui::ICursorSupport interface.
class CZMCommandBarLayoutEx Extended implementation of class for layout in commands bar: core::layout::ICommandBarLayout. This class is expected to provide child dialogs extensions which are implemented by class CZMChildDialog.
class CZMChildDialog Base implementation of core::layout::IChildDialog interface. This class is extended in a ready-to-use class core::layout::CChildDialog.
class CChildDialog Native ZModeler implementation of ready-to-use core::layout::IChildDialog interface. This implementation is derived from CDialog class too, and supports error reporting. You can use this class as a base for your child dialogs whereever it's required. For example, filter's import configuration dialog or export configuration dialog are usually implemeted by deriving from CChildDialog.
class CNotifyChildDialog This class is very similar to CChildDialog, but it has core::layout::INotifyChildDialog interface in declaration and implements child dialog which is notified when it's shown, hidden or when parent dialog closes (by Ok, or Cancel button).
class CZMMenuLayoutEx Implementation class for customizeable core::layout::IMenuLayout. This layout is used by CMenuToolEx class.
class CZMContextMenuLayoutEx Implementation class for customizeable core::layout::IContextMenuLayout. This layout is similar to CZMMenuLayoutEx, but intended to lay tools in dynamically-created context menu. This class is inherited by CContextMenuToolEx class.
class CZMToolBarLayoutEx Implementation class for customizeable core::layout::IToolBarLayout. This layout supports custom images for toolbar and inherited by CToolBarToolEx class.
class CZMFloaterLayoutEx Implementation class for customizeable core::layout::IFloaterLayout. This class is directly inherited from CZMChildDialog and supports error-reporting. CFloaterToolEx class directly inherited from this layout class.
class CZMViewLayout Implementation class for core::layout::IViewLayout. This could be either a viewport layer or custom control class. CViewTool class directly inherited from this layout class.

Complete classes for deriving tools from.

class CStartupToolHelper Derive your classes from this class to implement a tool that supports startup layout. These startup tools are mostly used for configuration and establishing relations with some services: e.g. "hanging" a tool in some event handling system.
class CCommandBarToolEx Extended commands bar-based class for derivation of your tools. It supports dialogs with extra options, custom cursors and error reporting.
class CMenuToolEx Extended main menu-based class for derivation of your tools. It supports custom images for menu items and error reporting.
class CContextMenuToolEx Extended context menu-based class for derivation of your tools. It supports custom images for menu items and error reporting.
class CToolBarToolEx Extended toolbar-based class for derivation of your tools. It supports custom images, allows layout in a "variations group" (when single button with drop-arrow is created for several items) and error reporting.
class CFloaterToolEx Floater-based tool class can be used for creation of custom floaters or dockers. In current ZModeler implementation an extended version of this class CFloaterMenuTool is used.
class CFloaterMenuTool Directly derived from CFloaterToolEx and CZMMenuLayoutEx classes, this class provides a floater-based tool which also creates a menu item in main menu that allows to show/hide according floater box.
class CViewTool Directly derived from CZMViewLayout this class helper provides a viewport-based tool. For example, viewport layers and all viewport controls use this class as a base.
class CViewMenuTool Directly inherited from CViewTool and CZMMenuLayoutEx classes, this class presents you a viewport menu-based tool.
class CViewMenuOnlyTool Currentluy unused.

Helper macros declaration.

This helper file also provides some macros related to layout and tools. The first one is IMPLEMENT_TREE_NAVIGATOR(_class) which implements methods of core::layout::ITreeNavigator interface. You place this macro with full class name as an argument right in declaration of your class. See an example below: 

//
// example code fragment for implementation of
// core::layout::IUndoTreeNavigator
//
#include <zmodeler.h>
#include <core/layout/IUndoTreeNavigator.h>
#include <helpers/layout.h>

namespace core
{
  namespace layout
  {
    //-----------------------------------------------------
    // The Undo-tree navigator service class
    //-----------------------------------------------------
    class CUndoTreeNavigator : public IUndoTreeNavigator
    {
    public:
      INTERFACE_DECLAREMAP(CUndoTreeNavigator)
    public:
      CUndoTreeNavigator();
      virtual ~CUndoTreeNavigator();

      IMPLEMENT_TREE_NAVIGATOR(CUndoTreeNavigator)

    public:
    //-----------------------
    // IUndoTreeNavigator
    //-----------------------
      virtual ZRESULT getUndoBlock(core::undo::IUndoBlock** ppBlock);
      virtual ZRESULT getName(ZString& strName);
      virtual ZRESULT setName(ZString strName);

    public:
    //-----------------------
    // data members:
    //-----------------------
      ZString                       m_strName;
      ZPtr<core::undo::IUndoBlock<  m_pBlock;
      ZStdPtr<CUndoTreeNavigator<   m_pPrev;
      bool                          m_bBranchCommit;
    };//class CUndoTreeNavigator
  };//layout
};//core

Another macro is INTERACTIVE_TOOL_DELEGATE(_base) which can be used when additionally deriving from core::tools::IInteractiveTool interface. When you derivce from helper classes (which implement core::tools::ITool interface) and from IInteractiveTool, you can place this macro in declaration of your class to deligate some overlapping methods of IInteractiveTool to pre-implemented methods of ITool. See an example below: 

//-------------------------------------------------------------------------
// @Name        : class CMoveTool
// @Purpose     : Implements Modify\Move tool
// @Description : Moves ITransformable of nodes and Meshes nodes
//-------------------------------------------------------------------------
class CMoveTool : public CCommandBarToolEx,
                  public core::tools::IInteractiveTool,
                  public core::IProfileable
                  
{
public:
  INTERFACE_DECLAREMAP(CMoveTool)
  CMoveTool();
  virtual ~CMoveTool();

public:
  //---------------------------------------
  //    IInteractiveTool
  //---------------------------------------
  INTERACTIVE_TOOL_DELEGATE(CCommandBarToolEx)
  virtual ZRESULT mouseDown(core::IProcParams* pProcParams, DWORD nFlags, DWORD& nRetFlags);
  virtual ZRESULT mouseMove(core::IProcParams* pProcParams, ZPoint ptOffset, DWORD nFlags, DWORD& nRetFlags);
  virtual ZRESULT mouseUp(core::IProcParams* pProcParams, DWORD nFlags, DWORD& nRetFlags);
  virtual ZRESULT mouseWheel(core::IProcParams* pProcParams, DWORD nFlags, short zDelta, DWORD& nRetFlags);
  virtual ZRESULT interrupt(core::IProcParams* pProcParams, DWORD& nRetFlags) { return ZRESULT_OK; }

  //
  // ...
  //

};//class

A pair of macros related to CChildDialog class. They are CHILDDIALOG_IMPLEMENT(_class, _resource) and CHILDDIALOG_IMPLEMENTONLY(_resource). The second version implements initialization of CChildDialog-derived class's init method by creation of dialog based on _resource template ID. The first macro implements this method and overloads instance creation routine coming from CChildDialog. Instead, when internal implementatino of CChildDialog will need to create an instace, an instance of _class will be created, instead of CChildDialog. 

//---------------------------------------------------------
// @Name        : class CConvoyDialog
// @Purpose     : Import/Export dialog for CConvoyPMG
//---------------------------------------------------------
class CConvoyPMG;
class CConvoyDialog : public core::tools::CChildDialog
{
public:
  CConvoyDialog() : core::tools::CChildDialog() 
  {
    m_bExport = false;
    m_strDialogTitle  = _T("18 Wheels of Steel : Convoy");
  }
  DECLARE_MESSAGE_MAP()
public:
  CHILDDIALOG_IMPLEMENT(CConvoyDialog, IDD_CONVOY)
  virtual ~CConvoyDialog();

  //
  //...
  //

public:
  ZStdPtr<CConvoyPMG>       m_pOwner;
  bool                      m_bExport;
};
See Also:
References overview
Helpers overview