command.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: command.hpp,v $
 * PRODUCTION Revision 1000.4  2004/06/01 19:50:57  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.10
 * PRODUCTION
 * ===========================================================================
 */

#ifndef GUI_UTILS___COMMAND__HPP
#define GUI_UTILS___COMMAND__HPP

/*  $Id: command.hpp,v 1000.4 2004/06/01 19:50:57 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Authors:  Andrey Yazhuk
 *
 */

/// @file command.hpp
/// GUI command routing and handling framework.
///
/// This frameworks extends FLTK capabilities of handling menu commands by
/// providing a generic command routing mechanism based on command maps.
/// The following are parts of the framework:
/// CCommandTarget class - represents a class capable of handling commands
/// using command maps. 
/// Command map - structure mapping command IDs to handler funtion pointers.
/// IMenu - interface for CCommandTraget compatible menus.
 
#include <corelib/ncbistl.hpp>
#include <corelib/ncbistd.hpp>
#include <gui/gui.hpp>

#include <FL/Fl_Menu_.H>


/** @addtogroup GUI_UTILS
 *
 * @{
 */


BEGIN_NCBI_SCOPE

/// Command ID type
typedef int TCmdID;

/// Definitions for generic commands.
///
/// Subsytems of GUI should define they own command enumerations, preferable
/// with non-overlapping ranges.

enum EBaseCommands   {
    eCmdInvalid = -1, /// not a valid command
    eCmdNone = 0, /// empty command

    eCmdZoomIn,    
    eCmdZoomOut,
    eCmdZoomAll,
    eCmdZoomInX,
    eCmdZoomOutX,
    eCmdZoomAllX,
    eCmdZoomInY,
    eCmdZoomOutY,
    eCmdZoomAllY,
    eCmdZoomSel, /// Zoom to Selection
    eCmdZoomSeq, /// Zoom to Sequence
    eCmdZoomObjects,
    eCmdZoomSelObjects,

    // insert new command here    
    eBaseCmdLast
};

////////////////////////////////////////////////////////////////////////////////
/// ICmdUI - interface for updating command GUI elements such as menu itms and
/// tool bar buttons.
class ICmdUI
{
public:
    virtual ~ICmdUI()    {}

    virtual TCmdID  GetCommand() const = 0;

    virtual void    Enable(bool en) = 0;
    virtual void    SetCheck(bool set) = 0;
    virtual void    SetRadio(bool set) = 0;
    virtual void    SetLabel(const string& label) = 0;
};

class CCommandTarget;

/// pointer to a command handler
typedef     void (CCommandTarget::*FCmdHandler) (void);

/// pointer to a command handler
typedef     void (CCommandTarget::*FCmdHandler_ID) (TCmdID);

/// pointer to a command update handler
typedef     void (CCommandTarget::*FUpdateCmdHandler) (ICmdUI*);


/// Command map entry.
///
/// Used as building block for creating command maps mapping command IDs to handlers.
struct SCmdMapEntry
{
    enum    EHandlerType    {
        eInvalid = 0, 
        eCmd,       // for FCmdHandler or FCmdHandler_ID
        eUpdateCmd  // for FUpdateCmdHandler
    };

    TCmdID          m_CmdID; /// Command ID 
    TCmdID          m_LastCmdID; /// Last Command ID, used to specify ranges
    EHandlerType    m_HandlerType;
    FCmdHandler     m_Handler; /// pointer to command handler mapped to the Command ID
};

/// Command Map.
///
/// Command Map is used for mapping command IDs to pointers on member functions
/// of CCommandTarget derived classes.  
struct SCmdMap
{
    const SCmdMap*        m_BaseMap; /// pointer to command map of the base class
    const SCmdMapEntry*   m_Entries; /// pointer to array of map entries   
};

// MACRO for declaring and defining command maps

/// Declares Command Map facilities for CCommandTarget-derived class.
/// This macro should be used in the scope of class declaration.
#define DECLARE_CMD_MAP() \
private: \
	static const SCmdMapEntry sm_CmdMapEntries[]; \
protected: \
	static const SCmdMap    sm_CmdMap; \
	virtual const SCmdMap*  GetCommandMap() const; \

/// Begins definition of Command Map for CCommandTarget-derived class.
/// The first parameter is a name of class owning map, the second - 
/// name of the base class (that should also be CCommandTarget-derived).
/// This macro can be followed by multiple ON_COMMAND() macros and 
/// finaly - by the END_CMD_MAP() macro.
#define BEGIN_CMD_MAP(thisClass, baseClass) \
	const SCmdMap* thisClass::GetCommandMap() const \
		{ return &thisClass::sm_CmdMap; } \
	const SCmdMap thisClass::sm_CmdMap = \
	    { &baseClass::sm_CmdMap, &thisClass::sm_CmdMapEntries[0] }; \
	const SCmdMapEntry thisClass::sm_CmdMapEntries[] = \
	    { \

/// Ends definition of Command Map.
#define END_CMD_MAP() \
		{0, 0, SCmdMapEntry::eInvalid, 0} \
	}; \

/// Adds a Command Map entry mapping given command id to given command handler.
#define ON_COMMAND(id, handler) \
    { id, id, SCmdMapEntry::eCmd, (FCmdHandler) handler },

/// Adds a Command Map entry mapping given command range to given command handler.
#define ON_COMMAND_RANGE(id, id_last, handler) \
    { id, id_last, SCmdMapEntry::eCmd, (FCmdHandler) ((FCmdHandler_ID) handler) },

/// Adds a Command Map entry mapping given command id to given command update handler.
#define ON_UPDATE_COMMAND_UI(id, handler) \
    { id, id, SCmdMapEntry::eUpdateCmd, (FCmdHandler) ((FUpdateCmdHandler) handler) },

#define ON_UPDATE_COMMAND_UI_RANGE(id, id_last, handler) \
    { id, id_last, SCmdMapEntry::eUpdateCmd, (FCmdHandler) ((FUpdateCmdHandler) handler) },

////////////////////////////////////////////////////////////////////////////////
/// Class CCommandTarget - the base class for all classes handling commands.
/// This class provides virtual functions that can be overridden in derived classes.
/// However, in most cases this is not necessary. Derived classes can customize 
/// command handling by defining a Command Map.

class NCBI_GUIUTILS_EXPORT CCommandTarget
{
public:
    virtual ~CCommandTarget() { }

    /// Callback to be used by FLTK menu mechanism.
    static void     OnFlMenuCommand(Fl_Menu_* menu, void* user_data);

    virtual bool    OnCommand(const TCmdID cmd);
    virtual bool    OnUpdateCommand(const TCmdID cmd, ICmdUI* pCmdUI);

    virtual bool    AddChildCmdTarget(CCommandTarget* target);
    virtual bool    RemoveChildCmdTarget(CCommandTarget* target);

protected:
    /// Default command handler.
    /// Tries to processes given command and returns "true" if command has been
    /// processed. Can be overriden in derived classes. Default implementation 
    /// uses command map to locate appropriate command handler by given command
    /// ID and calls the handler. If handler cannot be found - function returns
    /// "false".
    virtual bool    x_HandleCommand(const TCmdID cmd);

    virtual bool    x_UpdateCommand(const TCmdID cmd, ICmdUI* pCmdUI);

    /// Passes command to children, returns "true" if command has been handled
    /// by one of the children.
    virtual bool    x_ChildrenHandleCommand(const TCmdID cmd);

    virtual bool    x_ChildrenUpdateCommand(const TCmdID cmd, ICmdUI* pCmdUI);

    DECLARE_CMD_MAP();

protected:
    typedef list<CCommandTarget*>   TChildTargets;

    TChildTargets   m_ChildTargets;
};

/// Default callback for use FLTK menus
#define CMD_TARGET_FL_CALLBACK() \
    (Fl_Callback*) CCommandTarget::OnFlMenuCommand 


////////////////////////////////////////////////////////////////////////////////
// Interface IMenu

/// Interface for CCommandTarget-aware menus.

class NCBI_GUIUTILS_EXPORT IMenu
{
public:
    virtual ~IMenu()    {};

    virtual void    SetCmdTarget(CCommandTarget* target) = 0;
    virtual CCommandTarget*    GetCmdTarget() = 0;
};

END_NCBI_SCOPE

/* @} */


/*
 * ===========================================================================
 * $Log: command.hpp,v $
 * Revision 1000.4  2004/06/01 19:50:57  gouriano
 * PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.10
 *
 * Revision 1.10  2004/05/03 19:40:39  yazhuk
 * Extended command handling to support command updates
 *
 * Revision 1.9  2004/05/03 12:41:09  dicuccio
 * Split library into gui_utils and gui_objutils.  Added #include for gui/gui.hpp
 *
 * Revision 1.8  2004/04/16 14:27:17  dicuccio
 * Added doxygen module tag
 *
 * Revision 1.7  2004/02/12 21:48:19  yazhuk
 * Added new and reordered existing commands
 *
 * Revision 1.6  2004/01/21 12:34:21  dicuccio
 * Added virtual dtor
 *
 * Revision 1.5  2004/01/15 20:07:15  yazhuk
 * Moved most menu-related code to gui/widgets/gl/menu.hpp, changed IMenu
 *
 * Revision 1.4  2004/01/08 19:35:56  yazhuk
 * Added to CCommandTarget support for child targets. Added MENU_SEPARATOR macro.
 * Added comments.
 *
 * revision 1.3  2003/11/17 22:51:23  yazhuk
 * Added new Zoom commands
 *
 * revision 1.2  2003/10/15 21:11:54  yazhuk
 * Added eBaseCmdLast to EBaseCommands
 *
 * revision 1.1  2003/10/03 16:01:23  yazhuk
 * Initial revision
 *
 * ===========================================================================
 */

#endif  // GUI_UTILS___COMMAND__HPP