MultiWCTool.h

Classes

MultiWCTool -- Base class for MultiWorldCanvas event-based tools. (full description)

class MultiWCTool : public DisplayTool, public WCPositionEH, public WCMotionEH, public WCRefreshEH

Interface

Public Members
MultiWCTool(const Display::KeySym &keysym = Display::K_Pointer_Button1)
virtual ~MultiWCTool()
virtual void addWorldCanvas(WorldCanvas &worldcanvas)
virtual void removeWorldCanvas(WorldCanvas &worldcanvas)
virtual void addWorldCanvases(PanelDisplay* pdisp)
virtual void removeWorldCanvases(PanelDisplay* pdisp)
virtual void enable()
virtual void disable()
virtual void operator()(const WCPositionEvent& ev)
virtual void operator()(const WCMotionEvent& ev)
virtual void operator()(const WCRefreshEvent& ev)
virtual void reset(Bool skipRefresh=False)
Protected Members
virtual void keyPressed(const WCPositionEvent &ev)
virtual void keyReleased(const WCPositionEvent &ev)
virtual void otherKeyPressed(const WCPositionEvent &ev)
virtual void otherKeyReleased(const WCPositionEvent &ev)
virtual void moved(const WCMotionEvent &ev)
virtual void draw(const WCRefreshEvent &ev)
virtual void refresh()
virtual void setClipToDrawArea()
virtual void setClipToWC()
virtual void resetClip()
Private Members
MultiWCTool()
MultiWCTool(const MultiWCTool &other)
MultiWCTool &operator=(const MultiWCTool &other)

Description

Review Status

Date Reviewed:
yyyy/mm/dd

  • WCPositionEH
  • WCMotionEH
  • WCRefreshEH

    Etymology

    MultiWCTool stands for MultiWorldCanvas Tool

    Synopsis

    This class is a base class upon which tools which respond to various events on a WorldCanvas can be built. It wraps up the position, motion and refresh events so that the programmer sees them all coming into one class, where they can be dealt with in a unified manner. MultiWCTool is not actually abstract, so the programmer need only write handlers for the events in which they are interested.

    Example

    Motivation

    The majority of tools written for the WorldCanvas will fall into the category that this class serves: they respond to a single key or mouse button, and they potentially need to respond to position, motion and refresh events.

    To Do

    Member Description

    MultiWCTool(const Display::KeySym &keysym = Display::K_Pointer_Button1)

    Constructor taking the primary key to which this tool will respond.

    virtual ~MultiWCTool()

    Destructor.

    virtual void addWorldCanvas(WorldCanvas &worldcanvas)
    virtual void removeWorldCanvas(WorldCanvas &worldcanvas)

    Add/remove a WorldCanvas from the control of this tool.

    virtual void addWorldCanvases(PanelDisplay* pdisp)
    virtual void removeWorldCanvases(PanelDisplay* pdisp)

    Add/Remove a list of WorldCanvases from PanelDisplay

    virtual void enable()
    virtual void disable()

    Switch the tool on/off - this simply registers or unregisters the event handlers on the WorldCanvases.

    virtual void operator()(const WCPositionEvent& ev)
    virtual void operator()(const WCMotionEvent& ev)
    virtual void operator()(const WCRefreshEvent& ev)

    Required operators for event handling - these are called when events occur, and distribute the events to the "user-level" methods

    virtual void reset(Bool skipRefresh=False)

    Derived classes should implement this to return to the non-showing, non-active state. It should not unregister the tool from WCs or disable event handling. If skipRefresh is false and the tool was showing, it also calls refresh() to erase. (The caller should set skipRefresh=True (only) if it will handle refresh itself).

    virtual void keyPressed(const WCPositionEvent &ev)
    virtual void keyReleased(const WCPositionEvent &ev)
    virtual void otherKeyPressed(const WCPositionEvent &ev)
    virtual void otherKeyReleased(const WCPositionEvent &ev)
    virtual void moved(const WCMotionEvent &ev)

    Functions called by the local event handling operators - by default they do nothing, so a derived class needs only implement the events it cares about

    virtual void draw(const WCRefreshEvent &ev)

    Draw whatever should be drawn (if anything) on current WC. Should only be called by refresh event handler.

    virtual void refresh()

    Copy back-to-front buffer (erasing all MWCTool drawings), then cause this (and all MWCTools on current WC's PC) to draw (or not draw) themselves, according to their current state. Mouse and kbd event handlers within the tools now call this in response to drawing state changes, rather than calling draw() directly, so that only valid tool drawings are displayed, even when more than one is active. NB: the meaning of this routine has changed to be more in line with the rest of the DL (i.e., it now causes, rather than responds to, refresh events).

    virtual void setClipToDrawArea()
    virtual void setClipToWC()
    virtual void resetClip()

    Cause subsequent drawing commands to be clipped to the current WC (or its drawing area). Be sure to reset when finished drawing; clipping will apply to drawing on entire PC.

    MultiWCTool()
    MultiWCTool(const MultiWCTool &other)
    MultiWCTool &operator=(const MultiWCTool &other)

    copy, default constructors (do not use)