WidgetBase.h

Go to the documentation of this file.

//------------------------------------------------------------------------
//
//   Joe Kniss
//     6-20-03
//                   ________    ____   ___ 
//                  |        \  /    | /  /
//                  +---+     \/     |/  /
//                  +--+|  |\    /|     < 
//                  |  ||  | \  / |  |\  \ 
//                  |      |  \/  |  | \  \ 
//                   \_____|      |__|  \__\
//                       Copyright  2003 
//                      Joe Michael Kniss
//                   <<< jmk@cs.utah.edu >>>
//               "All Your Base are Belong to Us"
//-------------------------------------------------------------------------

// WidgetBase.h


#ifndef __WIDGET_BASE_DOT_H
#define __WIDGET_BASE_DOT_H

#include <smartptr.h>
#include <mathGutz.h>
#include <arrayGutz.h>
#include <eventGutz.h>
#include <signalGutz.h>
#include <vector>
#include <list>
#include "Constraint.h"
#include "WidgetState.h"
#include "../renderable/Renderable.h"

#include <iostream>


///////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////
/// The widget item base class, virtual, needs a concrete sub-class to
///  do anything.  We are using the Renderable interface for mouse events,
///  so the name & cast for gl style picking is: #RENDERABLE_NAME and 
///  "(unsigned int)(Renderable*)this", respectively. See: Renderable.h.
///
/// The widget framework is divided into 2 layers.  
///  - Behavior
///  - Appearance
///
/// The Behavior layer defines how widgets interact and are constrained 
///  to one another.  This level describes how the widgets move, but now how
///  they look.
///
/// The Appearance layer defines how they look.  For instance, we are most
///  likely using minimal OpenGL widget geometry, like GLU quadric objects.
///  These are balls, tubes, cones, etc...  We might also like to use widgets
///  in 2D without opengl, or maybe develop a custom "skin" to make our 
///  widgets look different than everyone else's.  Whatever the reason, we can 
///  easly customize the appearance of the widgets by creating new concrete
///  basic widgets that simply draw the geometry we want, with any shader,
///  colors etc.  This only requires the implementation of a few functions,
///  for instance:
/// \code
///   float draw( const gutz::RenderEvent &re );
///   WidgetItem *clone();
///   // and possibly these if applicable:
///   void _invalidate();
///   void _update();
/// \endcode
/// See how GLUNodeWidget implements the NodeWidget with only a few 
///   functions.  
///
/// The actions described by widgets are very general, for the most part
///   they contain information about spatial position or some parameter 
///   that they represent.  There is realy no need to create a new widget
///   everytime you need some new action, nearly all widgets contain
///   signals, see gutz::Signal.  These signals are called whenever the 
///   parameter of interest changes, which can be captured by your class
///   that implements the action associated with that parameter.  For 
///   instance, you may want some kind of clipping plane for opengl.  Your
///   instinct might say, subclass FrameWiget and have it handle the clipping
///   action.  That would lead to a mas-proliferation of "special" widgets that
///   differ from their base class only in how they implement the symantics
///   of the widget.  It is far better to create a "ClipObject" that gets
///   "connected", see gutz::connect(), to the FrameWidget::planeChanged signal.
///   Whenever the user modifies the position/orientation of the FrameWidget,
///   the ClipObject will recieve the planeChanged signal and update the 
///   clipping plane.   This kind of sepparation is important since it could
///   become difficult to maintain and improve the widget framework if there are
///   many classes that "know" about how the widget is implemented.
///
/// Of course you will want to build custom widgets with a slider here, another bar 
///   there, whatever.  You should.  But remember to keep the behavior implentation
///   higher in the hierarchy, the appearance lower (most derived), and little 
///   or no built in symantics, just signals to communicate parameter changes. \n
///   TODO: need more examples here...
///
/// The divison between NodeWidget and GLUNodeWidget illustrates the 
///   sepparation between behavior and appearance: NodeWidget handles the
///   behavior, and GLUNodeWidget handles the specific appearance for 
///   GLU spheres.  Behavior implementation should always reside above any
///   and all apperance implementation in the class hierarchy.
///
/// All parameters, such as position and orientation should be delivered
///   in "WORLD" space; see gutz::BaseManip
///   for a definition of this.   By delivered, I mean when you call 
///   getPoint, getPos, getOrient, etc... or recieve a signal such as 
///   pointChanged etc.. these positions and orientations should always be
///   in "WORLD" space, not the local frame that the widget may live in.
///   It is very likely that widgets store these parameters in a Manip, so
///   as you might expect, this means that we are using 
///   gutz::BaseManip::getWorldPos() when you ask for a widget's position.
///   This also means that any setPos functions should use positions/orientations
///   that are defined in "WORLD" space.  The widget is responsible for 
///   transforming these parameters into their local frame. 
///
/// See also WidgetFactory, gutz::Signal, gutz::connect, gutz::disconnect.
///////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////
class WidgetItem : public Renderable {
public:

   typedef gutz::SmartPtr<WidgetItem>    WidgetItemSP;
   
   typedef gutz::vec2f                Point2;      ///<2D point
   typedef gutz::arrayOwn1<Point2>    Point2Array; ///<2D point array

   typedef gutz::vec3f                Point3;      ///<3D point
   typedef gutz::arrayOwn1<Point3>    Point3Array; ///<3D point array

   virtual ~WidgetItem() 
   { 
      if(_parent) _parent->delChild(this);
      _parent = 0;
      _eventMap = gutz::EventKeyMap();
      _constraintMap = ConstraintMap();
   }

   ///////////////////////////////////////////////////////////////////
   ///@name clone/factory function.
   ///   Should only be implemented by concrete widget class.  
   ///   It is also nice if you have a clone{subWidgetType}() function. 
   ///   so that we can
   ///   use this for generic WidgetFactory objects.  If you have a 
   ///   specific clone function, you can define the WidgetItem::clone 
   ///   function to call the specific one, to eliminate potentially 
   ///   redundant code at the "appearance level" of the hierarchy.
   ///   for instance 
   ///   \code
   ///      WidgetItem *clone() const { return cloneNode(); }
   ///      virtual NodeWidget *cloneNode() const =0; 
   ///   \endcode
   ///   In this case, any concrete subclass of NodeWidget only needs to 
   ///   implement cloneNode(), not clone().  
   ///
   ///   This is a very important function, it replaces the copy 
   ///   constructor since it is protected at this level of the hierarchy.
   ///   This is nessesary since we are sepparating behavior and appearance,
   ///   and therefore can't copy at the behavior (this) level of the hierarchy.
   ///   Any widget that can be publically constructed MUST implement a clone
   ///   function, but it should be left virtual. 
   ///  
   ///   Here is an example of a clone definition in SomeWidget, 
   ///    a concrete (appearance) widget class.
   /// \code
   ///   virtual WidgetItem *SomeWidget::clone() const
   ///   {  
   ///       return new SomeWidget(*this); 
   ///   }
   /// \endcode
   ///@{
   virtual WidgetItem *clone() const = 0;
   ///@}
   ///////////////////////////////////////////////////////////////////

   ///////////////////////////////////////////////////////////////////
   ///@name Modified
   ///   When this is called the widget knows it has been changed
   ///   and will emmit update events.  This is used mostly for 
   ///   composite widgets that handle some events using their
   ///   own manipulator; when this happens they have to notify 
   ///   their child widgets that they changed, so that they can
   ///   update their children and anybody recieving attached signals.
   ///   
   ///   As a user of widgets, you can IGNORE this function, doesn't apply
   ///   to you.  When you are building new widgets, however, this function
   ///   comes in handy.  Composite widgets should always forward this 
   ///   "event" onto children and emmit any relevant signals.  
   ///@{
   virtual void setChanged() = 0;
   ///@}

   ///////////////////////////////////////////////////////////////////
   /// apply a 4x4 transformation matrix, must be defined by a
   ///  sub-class.
   virtual void    applyXform(gutz::mat4f xf) = 0;

   ///////////////////////////////////////////////////////////////////
   ///@name Events duplicated from <Renderable>. 
   ///   These are duplicated
   ///      to insure/ease framework issues, notice that mouse and 
   ///      move handle the "check with parent" and mouseDef(), moveDef()
   ///      are what actually implement the behavior.
   ///@{

   ///////////////////
   /// main draw event...
   ///   Framework only, do not override,
   ///   Might need to add functionality here later. \n
   void draw(const gutz::RenderEvent &r)
   { drawDef(r); }
   /// PURE VIRTUAL draw defintion, must be implemented
   ///   by concrete base class, be sure to apply the
   ///   matrix associated with this widget (_mat)
   virtual void drawDef(const gutz::RenderEvent &r) = 0;
   
   ///////////////////
   /// a mouse event... 
   ///   checks with parent, then calls mouseDef() \n
   ///   Framework only, do not override.
   bool mouse(const gutz::MouseEvent &me)  
   {
      if(_parent && _parent->mouseChild(this,me)) return true;
      return mouseDef(me);
   }
   ///////////////////
   /// override this one to implement mouse behavior
   virtual bool mouseDef(const gutz::MouseEvent &me)     
   {
      std::cerr << " event id = " << getEvent(me) << std::endl;
      return _manip->mouse(me);
      return getEvent(me) != NO_EVENT; 
   }

   ///////////////////
   /// a child was moused, called before their mouseDef.
   ///  return true if & only if parent will be handling the mouse event \n
   ///  return false if the child handles it's own mouse event \n
   virtual bool mouseChild(WidgetItem *child, const gutz::MouseEvent &me)
   { return false; }

   ///////////////////
   /// a move event, 
   ///   checks with parent, then calls moveDef().
   ///   Framework only, do not override.
   bool move(const gutz::MouseMoveEvent &mme) 
   { 
      if(_parent && _parent->moveChild(this,mme)) return true;
      return moveDef(mme); 
   }

   ///////////////////
   /// override this one to implement move behavior
   virtual bool moveDef(const gutz::MouseMoveEvent &mme) 
   {
      if(_manip->move(mme))
      {
         setChanged();
         return true;
      }
      return false;
   }
   
   ///////////////////
   /// a child wants to be moved. 
   /// if true, child does nothing (parent moves them)
   /// if false, child moves self
   virtual bool moveChild(WidgetItem *child, const gutz::MouseMoveEvent &mme)
   { return false; }

   ///@}
   ///////////////////////////////////////////////////////////////////

   ///////////////////////////////////////////////////////////////////
   ///@name Parent/Child management
   ///@{

   /// a child was added
   virtual void addChild(WidgetItem *child) {}
   /// a child was deleted/ changed parent
   virtual void delChild(WidgetItem *child) {}
   
   /// a (new?) parent now owns you :)
   virtual void setParent(WidgetItem *parent)
   {   if(_parent)
       {
          _parent->delChild(this); 
          _manip->setParent(0);
       }
       _parent = parent; 
       if(_parent)
       {
          _manip->setParent( _parent->getManip() );
          _parent->addChild(this); 
       }
   }

   ///@}
   ///////////////////////////////////////////////////////////////////

   ///////////////////////////////////////////////////////////////////
   /// get the "tightest 2D bounding polygon" in screen space
   virtual Point2Array  getValidArea() const {return Point2Array(0,Point2(0));}

   ///////////////////////////////////////////////////////////////////
   ///@name Event & constraint mapper. 
   ///     All widgets have the default
   ///     event of: gutz::GUTZ_LEFT_MOUSE -> MOVE 
   ///     you may want to nuke this event if it isn't applicable:
   ///     delEvent(gutz::GUTZ_LEFT_MOUSE);
   ///     event keys are defined in: gutzKeyMouse.h
   ///@{

   enum WIGET_BEHAVIORS {
      NO_EVENT =0,   ///< widget does nothing (by itself, but maybe parent does)
      MOVE,          ///< move according to world space deltas (default left mouse)
      ROTATE,        ///< rotate around center of widget 
      WB_LAST        ///< sub classes add events starting here (not an event)
   };

   /// addEvent. constraint defaults to "Free Move" constraint
   void              addEvent(const unsigned int key, 
                              const unsigned int event,
                              const ConstraintSP cnst = new Constraint())
   { _eventMap[key] = event; _constraintMap[key] = cnst; }
   
   /// getEvent, returns the event if one is defined, returns
   /// NO_EVENT if the mouse is up
   ///  works for both: gutz::MouseEvent and gutz::MouseMoveEvent
   /// This function is usefull in implementation, externally
   /// use getEvent(unsigned int).
   unsigned int getEvent(const gutz::MouseEvent &me) const
   {
      if(!me.isButtonDown()) return NO_EVENT;
      return _eventMap[me.getButton()];
   }

   /// what is the event assigned to a key
   unsigned int getEvent(unsigned int key) const
   {
      return _eventMap[key];
   }

   /// delete an event from the event map
   void              delEvent(const unsigned int key)
   { _eventMap.erase(key); _constraintMap.erase(key);  }
   /// delete all events from the event map
   void              nukeEvents()
   {
      _eventMap = gutz::EventKeyMap();
      _constraintMap = ConstraintMap();
   }

   gutz::EventKeyMap getEvents() const { return _eventMap; }
   void              setEvents(const gutz::EventKeyMap &eventMap)
   { _eventMap = eventMap;   }

   ConstraintMap     getConstraints() const { return _constraintMap; }
   void              setConstraints(const ConstraintMap &cnstMap)
   { _constraintMap = cnstMap; }
   ///@}
   ///////////////////////////////////////////////////////////////////

   ///////////////////////////////////////////////////////////////////
   ///@name Some appearance management
   ///@{
   ColorWStateSP getColor() const                    { return _color; }
   void          setColor(ColorWState * const color) { _color = color; }
   ///@}
   ///////////////////////////////////////////////////////////////////


protected:

   /// called before widget changes, see also _update()
   /// some window systems need these calls before and 
   /// after something changes, respectively,
   /// you'll have to specify them in your concrete class, if you need them.
   ///  They are quite usefull, if you need to update when a widget changes, 
   ///  but you don't (nescessarily) care what changed
   virtual void _invalidate() 
   {}
   /// called after widget is changed
   virtual void _update() 
   {}
   /// called if something about how it looks changes, does not include 
   /// changes to the transform, just things like radius and color.
   virtual void appearanceChanged() {}


   /// protected constructor, object cannot be publically created
   WidgetItem(WidgetItem *parent = 0) 
      : Renderable(), _parent(parent), _color(0) 
   {
      if(parent) parent->addChild(this);
      addEvent(gutz::GUTZ_LEFT_MOUSE,MOVE);
   }
   
   /// copies everything associated with the widget, see detailed comments.
   /// You should always implement the copy constructor and assignment 
   ///    operator of every widget.  If the widget can't be publicly constructed,
   ///    like this or many other "behavioral" widget specs, you should declare
   ///    the copy constructor as protected.  A subclassed widget should always
   ///    call it's base class's copy constructor, like this
   /// \code
   ///   /// definition of MyWidget's copy constructor
   ///   MyWidget::MyWidget(const MyWidget &mw)
   ///   : MyBaseClass(mw) // , ... init my member attribs
   ///   { /* other initiallization ... */ }
   /// \endcode
   /// checkout the copy constructors: WidgetItem <- NodeWidget <- GLUNodeWidget 
   ///
   /// Note that the assignment operator's ( operator= ) behavior is quite 
   ///   different from the copy constructor's.
   WidgetItem(const WidgetItem &wi)
      : Renderable(wi),
        _parent(wi._parent), 
        _eventMap(wi._eventMap),
        _constraintMap(wi._constraintMap),
        _color(0)
   {
      if( wi._color ) setColor( wi._color->cloneColor() );
   }

   /// CAREFULL, this ONLY copies data associated with the widget!
   ///   It does not copy things like the parent, space,
   ///   behavior, Event & Constraint maps, etc.. right now it just copies
   ///   the transform (_mat). The assignment operator is treated differently
   ///   than the copy constructor, in that it doesn't change the 
   ///   behavior (events) or appearance of a widget, it just sets the
   ///   data to be equal.  However, like the copy constructor, you 
   ///   should always call your base classes assignment operator:
   /// \code
   ///   /// definition of MyWidget's assignment op
   ///   MyWidget &MyWidget::operator=(const MyWidget &mw)
   ///   {
   ///      MyBaseClass::operator=(mw);
   ///      /// ... member attrib copy
   ///      return *this;
   ///   }
   /// \endcode
   WidgetItem &operator=(const WidgetItem &wi)
   {
      Renderable::operator =(wi);
      return *this;
   }

   WidgetItemSP       _parent;
   gutz::EventKeyMap  _eventMap;
   ConstraintMap      _constraintMap;
   /// carefull, you need to check if this is a NULL pointer
   ColorWStateSP      _color;
};

typedef gutz::SmartPtr<WidgetItem> WidgetItemSP;
typedef std::vector<WidgetItemSP>  WidgetItemSPVec;
typedef WidgetItemSPVec::iterator  WidgetItemSPVecIter;

typedef std::list<WidgetItemSP>          WidgetItemSPList;
typedef WidgetItemSPList::iterator       WidgetItemSPListIter;
typedef WidgetItemSPList::const_iterator WidgetItemSPListCIter;



#endif

---

Send questions, comments, and bug reports to: