labelplacement.h

Go to the documentation of this file.

/******************************************************************************
 *
 * \file gre/labelplacement.h
 * \brief GRE::LABELPLACEMENT class definition
 *
 * \if NODOC
 * $Log: labelplacement.h_v $
 * Revision 1.20  2004/09/20 19:09:57  dglasser
 * *** empty log message ***
 *
 * Revision 1.19  2004/09/17 17:40:09  dwilliss
 * Added a couple private methods
 * Added a Detach method
 *
 * Revision 1.18  2004/09/09 20:06:03  dwilliss
 * Added Zoom
 *
 * Revision 1.17  2004/09/08 22:47:26  dwilliss
 * Implement CopyOnWrite and ComputeLabelExtents
 *
 * Revision 1.16  2004/09/08 16:50:44  dwilliss
 * Added SetPointSymbol version that takes RVC::STYLE::SYMBOLPATTERN
 *
 * Revision 1.15  2004/09/03 22:49:39  dwilliss
 * Added Draw methods
 *
 * Revision 1.14  2004/09/03 13:57:35  dwilliss
 * forward declare a class
 *
 * Revision 1.13  2004/09/03 13:44:48  dwilliss
 * *** empty log message ***
 *
 * Revision 1.12  2004/08/17 14:01:30  dwilliss
 * *** empty log message ***
 *
 * Revision 1.11  2004/08/06 22:26:30  dwilliss
 * Added a few methods
 *
 * Revision 1.10  2004/07/22 22:16:54  dwilliss
 * Keep track of the layer
 * Allow labels to be deleted
 *
 * Revision 1.9  2004/07/21 20:33:32  dwilliss
 * *** empty log message ***
 *
 * Revision 1.8  2004/07/20 22:21:31  dwilliss
 * *** empty log message ***
 *
 * Revision 1.7  2004/07/20 17:43:29  dwilliss
 * Fixed End() to compile with gcc
 *
 * Revision 1.6  2004/07/20 16:06:52  dwilliss
 * still implementing
 *
 * Revision 1.5  2004/07/19 22:55:38  dwilliss
 * LABELPLACEMENT change
 *
 * Revision 1.4  2004/07/19 17:13:42  dwilliss
 * Still designing and implementing
 *
 * Revision 1.3  2004/04/30 22:19:43  dwilliss
 * *** empty log message ***
 *
 * Revision 1.2  2004/04/15 20:51:44  dwilliss
 * LABELPLACE's data is now kept in a refcounted private data structure so
 * copy and assignment are faster.
 *
 * Revision 1.1  2004/04/14 22:47:08  dwilliss
 * Initial revision
 *
 * \endif
 *
 *****************************************************************************/

#ifndef INC_GRE_LABELPLACEMENT_H
#define INC_GRE_LABELPLACEMENT_H


#ifndef INC_RVC_ELEMENT_H
#include <rvc/element.h>
#endif

#ifndef INC_MI32_REGION2D_H
#include <mi32/region2d.h>
#endif

#ifndef INC_MI32_ELEMSTYL_H
#include <mi32/elemstyl.h>
#endif

#ifndef INC_MI32_TEXTBASE_H
#include <mi32/textbase.h>
#endif

#ifndef INC_MI32_QTREE_H
#include <mi32/qtree.h>
#endif

#ifndef INC_RVC_STYLE_H
#include <rvc/style.h>  // for RVC::STYLE::SYMBOLPATTERN
#endif


class LABELSTYLE;
class GRE_LAYER;
class GRE_LAYERDC;
class GRE_VIEW;
class QUADTREE;
struct LINESTYLE;

namespace MGD {
   class CONTEXT;
   }

namespace GRE {
   class LABELPLACEMENT;

   class LABELATTACHMENT {
      public:
         //! Default Constructor
         LABELATTACHMENT (
            ) { }

         //! Constructor to attach to a given element
         LABELATTACHMENT (
            const RVC::ELEMENT& elem
            ) :
            m_elem(elem)
            {
            }

         //! Copy Ctor
         LABELATTACHMENT (
            const LABELATTACHMENT& rhs
            ) :
            m_elem(rhs.m_elem),
            m_leader(rhs.m_leader)
            {
            }

         //! Constructor to attach to a given element, with a leader
         LABELATTACHMENT (
            const RVC::ELEMENT& elem,
            const POLYLINE& leader
            ) :
            m_elem(elem),
            m_leader(leader)
            {
            }

         ~LABELATTACHMENT() {}

         const RVC::ELEMENT& GetElement (
            ) const {
            return (m_elem);
            }

         const POLYLINE& GetLeader (
            ) const {
            return (m_leader);
            }

         void SetElement (
            const RVC::ELEMENT& elem
            ) {
            m_elem = elem;
            }

         void SetLeader (
            const POLYLINE& leader
            ) {
            m_leader = leader;
            }

      private:
         RVC::ELEMENT m_elem;
         POLYLINE m_leader;

      };

   //! Class for keeping track of where a label is on the screen
   //! 
   //! Other things we may need in this class:
   //!   Flag to disallow moving - script for stacking label flags would want
   //!      to prevent the optimizer from moving labels.
   //!   
   class LABELPLACE {
      public:
         //! Default constructor
         LABELPLACE();

         //! Copy constructor
         LABELPLACE (
            const LABELPLACE& rhs
            );

         // dtor
         ~LABELPLACE();

         //! Assignment operator
         LABELPLACE& operator=(
            const LABELPLACE& rhs
            );

         // Compute the extents region of the label for a given GC
         // This computes the text label region (including frame) for a
         // given graphics context.
         void ComputeLabelExtents (
            MGD::CONTEXT* gc,
            REGION2D& region,
            bool bIgnoreLeaders = false
            ) const;

         //! Remove the attachment information for a given element
         void DeleteAttachment (
            const RVC::ELEMENT& element
            );

         // Detach the LABELPLACE from the LABELPLACEMENT.
         // Normally, a LABELPLACE is only a pointer to data owned by the
         // LABELPLACEMENT that's managing it.  Detach() copies the data
         // so that any changes made do not effect the master copy.
         void Detach (
            );

         //! Draw a label into a view
         ERRVALUE Draw (
            GRE_LAYERDC* pDC,   //!< layer DC to use (if NULL, will create a temporary one - not very efficient, but ok for datatips and such)
            const COLOR* ForegroundColor = 0 //!< Overrides Foreground color if not NULL
            ) const;

         //! Draw a label into an arbitrary device
         ERRVALUE DrawSample (
            MGD::CONTEXT& gc,
            const COLOR* ForegroundColor = 0, //!< Overrides Foreground color if not NULL
            bool bDrawLeaders = true
            ) const;

         //! Get the list of attachments
         const MILIST<LABELATTACHMENT>& GetAttachments (
            ) const;

         double GetBaseAngle (
            ) const;

         const POLYLINE& GetBaseLine (
            ) const;

         TEXTBASEORIGIN GetBaseOrigin (
            ) const;

         const DPOINT2D& GetBasePoint (
            ) const;

         bool GetDrawBaseLine (
            ) const;
         
         //! Get the line style for drawing the baseline
         //! @return true if line style has been set, false if not
         bool GetBaseLineStyle (
            LINESTYLE&
            ) const;

         //! Get the layer for this label.
         //! Note: you don't have to set the layer because LABLEPLACEMENT::Add
         //! does it for you.
         GRE_LAYER* GetLayer (
            ) const;

         //! Get the offset from the original location.
         //! If the optimizer is not run, this will return a (0,0)
         const DPOINT2D& GetOffset (
            ) const;
         
         //! Get the location of the point symbol (if any)
         //! in screen coordinates
         const DPOINT2D& GetSymbolPoint (
            ) const;

         //! Get the POINTSTYLE to use for the symbol
         const POINTSTYLE& GetPointStyle (
            ) const;

         //! Get the symbol data for the point symbol
         const SIMPLE_ARRAY<UINT8>& GetPointSymbol (
            ) const;

         //! Get the priority used in label optimization
         //! Higher numbers are higher priority
         double GetPriority (
            ) const;

         //! Return the region of the actual label.
         const REGION2D& GetRegion (
            ) const;

         const LABELSTYLE& GetStyle (
            ) const;

         const MISTRING& GetText (
            ) const;

         //! Returns true if the place holds point symbol information
         bool HasPoint (
            ) const;

         //! Returns true if the place holds text label information
         bool HasText (
            ) const;

         //! Returns true if the label is attached to the given element
         bool IsAttached (
            ELEMTYPE ElemType,
            INT32 ElemNum
            ) const;

         //! Returns true if the label is attached to the given element
         bool IsAttached (
            const RVC::ELEMENT& elem
            ) const;

         //! Return true if label is locked.
         //! When deconflicting labels, locked labels are not allowed to move.
         bool IsLocked (
            ) const;

         //! Lock a label in place.
         //! This prevents deconflicting from being able to move the label.
         void LockPosition (
            bool locked = true
            );

         //! Move a label a given ammount.
         void Move (
            const DPOINT2D& delta
            );

         //! Add an element attachment for this label
         void AddAttachment (
            const LABELATTACHMENT& attachment
            );

         //! Add an element attachment for this label (no leader line)
         void AddAttachment (
            const RVC::ELEMENT& element
            );

         void SetBaseLine (
            const POLYLINE& baseline
            );

         void SetBaseLine (
            const DPOINT2D& pt,
            double angle,
            TEXTBASEORIGIN origin
            );

         // Set CopyOnWrite for this instance.
         // LABELPLACE is implemented as a refcounted private data pointer
         // but by default does not do Copy-On-Write.  If you get a
         // label place through an iterator and mofify it, you usually want
         // to modify the original anyway.  In the rare case that you don't
         // call this method first.
         // Note that the CONST_ITERATOR sets CopyOnWrite to true, The
         // non-const ITERATOR sets it to false
         void SetCopyOnWrite (
            bool bCopyOnWrite = true
            ) {
            m_bCopyOnWrite = bCopyOnWrite;
            }

         void SetDrawBaseLine (
            bool draw = true
            );

         //! Set the style for drawing the baseline
         void SetBaseLineStyle (
            const LINESTYLE& style
            );

         //! Set the location of the point symbol (if any)
         //! in screen coordinates.
         void SetPoint (
            const DPOINT2D& location
            );

         //! Set the POINTSTYLE to use for the symbol
         void SetPointStyle (
            const POINTSTYLE& style
            );

         //! Set the symbol data for the point symbol
         void SetPointSymbol (
            const SIMPLE_ARRAY<UINT8>& symbol
            );

         //! Set the symbol data for the point symbol
         void SetPointSymbol (
            const RVC::STYLE::SYMBOLPATTERN& symbol
            );

         //! Set the priority used in label optimization
         //! Higher numbers are higher priority
         void SetPriority (
            double priority
            );

         //! Set the extents region of the label
         void SetRegion (
            const REGION2D& region
            );

         void SetStyle (
            const LABELSTYLE& style
            );

         void SetText (
            const MISTRING& str
            );

#if !defined(GENERATING_DOXYGEN_OUTPUT)
         // Used by LABELPLACEMENT::Add()
         void SetParent (
            GRE::LABELPLACEMENT* parent
            );

         GRE::LABELPLACEMENT* GetParent (
            ) const;
         
         // For SML script access.
         // Retrieves the string attached by SetUserString.
         // note, returning const UNICODE* instead of MISTRING& for SML
         // implemention convenience.  SML has to construct an SMLSTRING
         // out of it anyway
         const UNICODE* GetUserString (
            ) const;
      
         //! For SML script access.
         //! This allows an SML Control Script to attach any string data
         //! to the label.  The only thing it's useful for is for the 
         //! script to retrieve later.
         void SetUserString (
            const MISTRING& str
            );

         void Zoom (
            double scale
            );
      
         //! Sets the ID in the qtree.
         //! used internally by Move and LABELPLACEMENT Add and Remove
         void SetID (
            INT32 id
            );
#endif

      private:

         class PRIV;    // Actual data is a refcounted private structure
         PRIV *m_priv;  // so that copy constructor and assignment are fast
         bool m_bCopyOnWrite;
      };




   class LABELPLACEMENT {
      public:
         class ITERATOR;
         class CONST_ITERATOR;
         friend class CONST_ITERATOR;

         class CONST_ITERATOR {
            public:

               //! Default constructor
               CONST_ITERATOR (
                  ) :
                  m_placement(0),
                  m_num(-1)
                  { }

               //! Destructor
               virtual ~CONST_ITERATOR() {};

               //! Copy constructor
               CONST_ITERATOR (
                  const CONST_ITERATOR& rhs
                  ) :
                  m_placement(rhs.m_placement),
                  m_place(rhs.m_place),
                  m_num(rhs.m_num)
                  {}

               
               //! Internal ctor
               CONST_ITERATOR (
                  LABELPLACEMENT* placement
                  ) :
                  m_placement(placement),
                  m_num(-1)
                  { 
                     ReadNext(true);   // Incrementes to first non-deleted element
                  }

               //! Dereference operator
               const LABELPLACE& operator* (
                  ) const { return (m_place); }

               //! Dereference operator
               const LABELPLACE* operator-> (
                  ) const { return (&**this); }

               //! Pre-increment operator
               CONST_ITERATOR& operator++(
                  ) {
                  ReadNext(true);
                  return *this;
                  }  

               //! Post-increment operator
               CONST_ITERATOR operator++(int
                  ) {
                  CONST_ITERATOR temp = *this;
                  ++*this;
                  return(temp);
                  }

               //! Pre-decrement operator
               CONST_ITERATOR& operator--(
                  ) {
                  ReadPrev(true);
                  return *this;
                  }

               //! Post-decrement operator
               CONST_ITERATOR operator--(int
                  ) {
                  CONST_ITERATOR temp = *this;
                  --*this;
                  return(temp);
                  }

               //! Equality operator
               bool operator== (
                  const CONST_ITERATOR& rhs
                  ) const {
                  if (m_num == -1 && rhs.m_num == -1) return (true);
                  return (m_num == rhs.m_num && m_placement == rhs.m_placement);
                  }

               //! Inequality operator
               bool operator!= (
                  const CONST_ITERATOR& rhs
                  ) const { return (!(*this == rhs)); }

#if !defined(GENERATING_DOXYGEN_OUTPUT)
            protected:  // non-const iterator can access all this
               LABELPLACEMENT* m_placement;
               LABELPLACE m_place;
               int m_num;
               void ReadPrev (bool bIsConst);
               void ReadNext (bool bIsConst);
#endif
            };

         friend class ITERATOR;
         class ITERATOR : public CONST_ITERATOR {
            public:
               ITERATOR();
               
               //! Internal constructor
               ITERATOR(LABELPLACEMENT* placement) :
                  CONST_ITERATOR(placement) 
                  { }

               //! Dereference operator
               LABELPLACE& operator* (
                  ) { return (m_place); }

               //! Dereference operator
               LABELPLACE* operator-> (
                  ) { return (&**this); }

               //! Pre-increment operator
               ITERATOR& operator++() {
                  ReadNext(false);
                  return (*this);
                  }

               //! Post-increment operator
               ITERATOR operator++(int
                  ) {
                  ITERATOR temp = *this;
                  ++*this;
                  return(temp);
                  }

               //! Pre-decrement operator
               ITERATOR& operator--() {
                  ReadPrev(false);
                  return (*this);
                  };

               //! Post-decrement operator
               ITERATOR operator--(int
                  ) {
                  ITERATOR temp = *this;
                  --*this;
                  return(temp);
                  }

               //! Equality operator
               bool operator== (
                  const ITERATOR& rhs
                  ) const;

               //! Inequality operator
               bool operator!= (
                  const ITERATOR& rhs
                  ) const { return (!(*this == rhs)); }
            };

         //! Shuffle labels around so they don't overlap
         //! (note: not actually implemented yet)
         static ERRVALUE Deconflict (
            SIMPLE_ARRAY<LABELPLACEMENT*>& LabelSets
            );

         //! Default constructor
         LABELPLACEMENT (
            GRE_LAYER* layer,
            GRE_VIEW* view
            );

         //! Destructor
         virtual ~LABELPLACEMENT (
            );

         //! Add a place
         ERRVALUE Add (
            const LABELPLACE& place
            );

         //! LABELPLACE Iterator constructor
         CONST_ITERATOR Begin (
            ) const { return (CONST_ITERATOR(const_cast<LABELPLACEMENT*>(this))); }

         //! Clear all places
         void Clear (
            );

         //! Deletes placement information for all labels attached
         //! to a given element.  Note, if a label is associated with more
         //! than one element, only the leader line will be deleted.
         void DeleteLabels (
            const RVC::ELEMENT& element
            );

         //! LABELPLACE Iterator End condition
         CONST_ITERATOR End (
            ) const { return (CONST_ITERATOR(0)); }

         //! Given a screen coordinate, find the label (topmost in case of 
         //! multiples) at that location.
         //! pt is in screen coordinates.
         //! This version is for finding the label for data tips and things.
         //! The LABELPLACE returned is a copy, so changing it won't do
         //! anthing.
         //! 
         //! \return Number of items found or error if < 0
         INT32 Find (
            const DPOINT2D& pt,
            GRE::LABELPLACE& place,
            int maxdist = 0
            ) const;

         //! Given a screen coordinate, find all labels at that location.
         //! List will be sorted front to back.
         //! pt is in screen coordinates.
         //! \return Number of items found or error if < 0
         INT32 Find (
            const DPOINT2D& pt,
            MILIST<GRE::LABELPLACE*>& list,
            int maxdist = 0
            ) const;

         //! Find all labels intersecting a rectangle in screen coordinates.
         //! List will be sorted front to back.
         //! pt is in screen coordinates.
         //! \return Number of items found or error if < 0
         INT32 Find (
            const DRECT2D& rect,
            MILIST<GRE::LABELPLACE*>& list
            ) const;


         //! Find all labels intersecting a rectangle in screen coordinates.
         //! List will be sorted front to back.
         //! pt is in screen coordinates.
         //! \return Number of items found or error if < 0
         INT32 Find (
            const REGION2D& region,
            MILIST<GRE::LABELPLACE*>& list
            ) const;


         //! Get the union of of all label place regions. 
         //! This may be used for clip-under support, but then again, maybe not.
         //! If the actual labels will be drawn with balloon tips, this won't
         //! know about it.
         //! By default, the region passed in will be cleared of any previous
         //! value.  If you pass false for the bClear parameter, it will combine
         //! the label regions with the region passed in.
         ERRVALUE GetCombinedRegion (
            REGION2D& region,
            bool bClear = true      //!< Clear the region first
            ) const;

         //! Return the LABELPLACE for a given element.
         //! Will return true if the label is found, false if not.
         bool GetLabelPlace (
            const RVC::ELEMENT& elem,
            GRE::LABELPLACE& place
            ) const;

         //! Return the LABELPLACEs for all labels for given element.
         //! Will return true if the label is found, false if not.
         bool GetLabelPlaces (
            const RVC::ELEMENT& elem,
            MILIST<GRE::LABELPLACE>& places
            ) const;

         GRE_LAYER* GetLayer (
            ) const;

         int GetNumItems (
            ) const;

         GRE_VIEW* GetView (
            ) const;

      private:

         //! Compare the labels for two elements.
         //! Function should return true if the labels are the same, false if
         //! not.  The optimizer may use this (based on an option flag) to
         //! determine if one label could be used for two elements.
         //! There is a default implementation which returns false, preventing
         //! lable combining.
         virtual bool v_CompareLabels (
            const RVC::ELEMENT& elem1,
            const RVC::ELEMENT& elem2
            ) const;

#if !defined(GENERATING_DOXYGEN_OUTPUT)
         class PRIV;
         PRIV* m_priv;

      protected:
         // Used by the iterator and by SML implementation
         GRE::LABELPLACE* GetItem (
            int num
            );
      public:
         // Used by LABELPLACE::Move
         QUADTREE& GetQuadTree();

#endif
      };


   }


#endif // INC_GRE_LABELPLACEMENT_H

---