kig/objects/object_imp.h

   1 // Copyright (C)  2002  Dominique Devriese <devriese@kde.org>
   2
   3 // This program is free software; you can redistribute it and/or
   4 // modify it under the terms of the GNU General Public License
   5 // as published by the Free Software Foundation; either version 2
   6 // of the License, or (at your option) any later version.
   7
   8 // This program is distributed in the hope that it will be useful,
   9 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 // GNU General Public License for more details.
  12
  13 // You should have received a copy of the GNU General Public License
  14 // along with this program; if not, write to the Free Software
  15 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  16 // 02111-1307, USA.
  17
  18 #ifndef KIG_OBJECTS_OBJECT_IMP_H
  19 #define KIG_OBJECTS_OBJECT_IMP_H
  20
  21 #include "common.h"
  22
  23 class IntImp;
  24 class DoubleImp;
  25 class StringImp;
  26 class InvalidImp;
  27 class HierarchyImp;
  28 class TransformationImp;
  29 class TestResultImp;
  30 class CurveImp;
  31 class LineImp;
  32 class PointImp;
  33 class TextImp;
  34 class AngleImp;
  35 class VectorImp;
  36 class LocusImp;
  37 class CircleImp;
  38 class ConicImp;
  39 class CubicImp;
  40 class SegmentImp;
  41 class RayImp;
  42 class ArcImp;
  43 class PolygonImp;
  44
  45 /**
  46  * \internal This is some OO magic commonly referred to as "double
  47  * dispatch". If you need to do some action on an ObjectImp, and you
  48  * need to do something different dependent on the type of o, then
  49  * make a Visitor class that inherits this interface, and implements
  50  * the appropriate functions properly, and call "o->visit( my_visitor
  51  * );".
  52  */
  53 class ObjectImpVisitor
  54 {
  55 public:
  56   virtual ~ObjectImpVisitor();
  57   void visit( const ObjectImp* imp );
  58   virtual void visit( const IntImp* imp );
  59   virtual void visit( const DoubleImp* imp );
  60   virtual void visit( const StringImp* imp );
  61   virtual void visit( const InvalidImp* imp );
  62   virtual void visit( const HierarchyImp* imp );
  63   virtual void visit( const TransformationImp* imp );
  64   virtual void visit( const TestResultImp* imp );
  65   virtual void visit( const LineImp* imp );
  66   virtual void visit( const PointImp* imp );
  67   virtual void visit( const TextImp* imp );
  68   virtual void visit( const AngleImp* imp );
  69   virtual void visit( const VectorImp* imp );
  70   virtual void visit( const LocusImp* imp );
  71   virtual void visit( const CircleImp* imp );
  72   virtual void visit( const ConicImp* imp );
  73   virtual void visit( const CubicImp* imp );
  74   virtual void visit( const SegmentImp* imp );
  75   virtual void visit( const RayImp* imp );
  76   virtual void visit( const ArcImp* imp );
  77   virtual void visit( const PolygonImp* imp );
  78 };
  79
  80 typedef unsigned int uint;
  81
  82 /**
  83  * Instances of this class represent a certain ObjectImp type.  Every
  84  * ObjectImp type has a static ObjectImpType member, that it returns a
  85  * reference to in its type() function..  Think of it as a nice enum,
  86  * that you can also get some data from..
  87  */
  88 class ObjectImpType
  89 {
  90   const ObjectImpType* mparent;
  91   const char* minternalname;
  92   const char* mtranslatedname;
  93   const char* mselectstatement;
  94   const char* mselectnamestatement;
  95   const char* mremoveastatement;
  96   const char* maddastatement;
  97   const char* mmoveastatement;
  98   const char* mattachtothisstatement;
  99   const char* mshowastatement;
 100   const char* mhideastatement;
 101   class StaticPrivate;
 102   static StaticPrivate* sd();
 103 public:
 104   /**
 105    * Returns the type with name n.
 106    *
 107    * \internal Do *not* call this from functions that can be called at
 108    * static initializer time !  It depends on information that is only
 109    * available after that stage and will crash if used too early..
 110    */
 111   static const ObjectImpType* typeFromInternalName( const char* n );
 112
 113   /**
 114    * \internal Construct an ObjectImpType, with a lot of data about
 115    * your ObjectImp type.
 116    *
 117    * translatedname is a translatable string like "segment"
 118    * selectstatement is a translatable string like "Select this segment"
 119    * selectnamestatement is a translatable string like "Select segment %1"
 120    * removeastatement is a translatable string like "Remove a Segment"
 121    * addastatement is a translatable string like "Add a Segment"
 122    * moveastatement is a translatable string like "Move a Segment"
 123    * attachtothisstatement is a translatable string like "Attach to
 124    *     this segment"
 125    * showastatement is a translatable string like "Show a Segment"
 126    * hideastatement is a translatable string like "Hide a Segment"
 127    *
 128    * All translatable strings should have
 129    * I18N_NOOP around them !  @param parent is the ObjectImpType of
 130    * your parent ObjectImp type.  Never give 0 as parent, except for
 131    * the top ObjectImp ObjectImpType..
 132    */
 133   ObjectImpType(
 134     const ObjectImpType* parent, const char* internalname,
 135     const char* translatedname,
 136     const char* selectstatement,
 137     const char* selectnamestatement,
 138     const char* removeastatement,
 139     const char* addastatement,
 140     const char* moveastatement,
 141     const char* attachtothisstatement,
 142     const char* showastatement,
 143     const char* hideastatement );
 144   ~ObjectImpType();
 145
 146   /**
 147    * Does the ObjectImp type represented by this instance inherit the
 148    * ObjectImp type represented by t ?
 149    */
 150   bool inherits( const ObjectImpType* t ) const;
 151
 152   /**
 153    * Returns an internal name for this ObjectImp type.  This name is
 154    * guaranteed unique, and mostly corresponds with the class name of
 155    * the corresponding ObjectImp..
 156    */
 157   const char* internalName() const;
 158   /**
 159    * The name of this type, translated to the currently used language.
 160    */
 161   QString translatedName() const;
 162   /**
 163    * Returns a translatable string of the form "Select this %1".
 164    * E.g. "Select this segment".  Note that users of this function
 165    * should use i18n on the returned string before using it.
 166    */
 167   const char* selectStatement() const;
 168
 169   /**
 170    * Returns a translatable string of the form "Select point %1".  %1
 171    * will be filled in by whomever calls this function with the name
 172    * of the object in question.  This function should be used as
 173    * follows: i18n( x->selectNameStatement() ).arg( xname ).
 174    */
 175   const char* selectNameStatement() const;
 176
 177   /**
 178    * Returns a translated string of the form "Remove a xxx".
 179    * E.g. "Remove a Segment".
 180    */
 181   QString removeAStatement() const;
 182   /**
 183    * Returns a translated string of the form "Add a xxx".
 184    * E.g. "Add a Segment".
 185    */
 186   QString addAStatement() const;
 187   /**
 188    * Returns a translated string of the form "Move a xxx".
 189    * E.g. "Move a Segment".
 190    */
 191   QString moveAStatement() const;
 192   /**
 193    * Returns a translated string of the form "Attach to this xxx".
 194    * E.g. "Attach to this segment".
 195    * \internal This is used by the text label construction mode
 196    */
 197   QString attachToThisStatement() const;
 198
 199   /**
 200    * Returns a translated string of the form "Show a xxx".
 201    * E.g. "Show a Segment".
 202    */
 203   QString showAStatement() const;
 204
 205   /**
 206    * Returns a translated string of the form "Hide a xxx".
 207    * E.g. "Hide a Segment".
 208    */
 209   QString hideAStatement() const;
 210 };
 211
 212 /**
 213  * The ObjectImp class represents the behaviour of an object after it
 214  * is calculated.   This means how to draw() it, whether it claims to
 215  * contain a certain point etc.  It is also the class where the
 216  * ObjectType's get their information from..
 217  */
 218 class ObjectImp
 219 {
 220 protected:
 221   ObjectImp();
 222 public:
 223   /**
 224    * The ObjectImpType representing the base ObjectImp class.  All
 225    * other ObjectImp's inherit from this type.
 226    */
 227   static const ObjectImpType* stype();
 228
 229   virtual ~ObjectImp();
 230
 231   /**
 232    * Returns true if this ObjectImp inherits the ObjectImp type
 233    * represented by t.
 234    * E.g. you can check whether an ObjectImp is a LineImp by doing:
 235    * \if creating-python-scripting-doc
 236    * \code
 237    * if object.inherits( LineImp.stype() ):
 238    * \endcode
 239    * \else
 240    * \code
 241    * if( object.inherits( LineImp::stype() )
 242    * \endcode
 243    * \endif
 244    */
 245   bool inherits( const ObjectImpType* t ) const;
 246
 247   /**
 248    * Returns a reference point where to attach labels; when this
 249    * returns an invalidCoord then the attachment is either not
 250    * done at all, or done in a specific way (like for curves,
 251    * or for points) The treatment of points could also take
 252    * advantage of this attachment mechanism.
 253    *
 254    * If this method returns a valid Coordinate, then this is
 255    * interpreted as a pivot point for the label, which can still
 256    * be moved relative to that point, but follows the object when
 257    * the object changes.
 258    * In practice a new RelativePointType is created (position of
 259    * the string), this type in turn depends on the object (to get
 260    * its attachPoint) and two DoubleImp that are interpreted as
 261    * relative displacement (x and y)
 262    */
 263   virtual Coordinate attachPoint( ) const = 0;
 264
 265   /**
 266    * Return this ObjectImp, transformed by the transformation t.
 267    */
 268   virtual ObjectImp* transform( const Transformation& t ) const = 0;
 269
 270   virtual void draw( KigPainter& p ) const = 0;
 271   virtual bool contains( const Coordinate& p, int width,
 272                          const KigWidget& si ) const = 0;
 273   virtual bool inRect( const Rect& r, int width,
 274                        const KigWidget& si ) const = 0;
 275   virtual Rect surroundingRect() const = 0;
 276
 277   /**
 278    * Returns true if this is a valid ObjectImp.
 279    * If you want to return an invalid ObjectImp, you should return an
 280    * InvalidImp instance.
 281    */
 282   bool valid() const;
 283
 284   virtual const uint numberOfProperties() const;
 285   // the names of the properties as perceived by the user..  put
 286   // I18N_NOOP's around them here..
 287   virtual const QCStringList properties() const;
 288   // the names of the properties as known only by kig internally.  No
 289   // need for I18N_NOOP.  Preferably choose some lowercase name with
 290   // only letters and dashes, no spaces..
 291   virtual const QCStringList propertiesInternalNames() const;
 292   virtual ObjectImp* property( uint which, const KigDocument& d ) const;
 293   // Sometimes we need to know which type an imp needs to be at least
 294   // in order to have the imp with number which.  Macro's need it
 295   // foremost.  This function answers that question..
 296   virtual const ObjectImpType* impRequirementForProperty( uint which ) const;
 297   // Return whether the property with number which is by construction
 298   // always a point on this curve ( if this is a curve ), or always a
 299   // curve through this point ( if this is a curve ).
 300   virtual bool isPropertyDefinedOnOrThroughThisImp( uint which ) const;
 301   // What icon should be shown when talking about this property ?
 302   virtual const char* iconForProperty( uint which ) const;
 303
 304   /**
 305    * Returns the lowermost ObjectImpType that this object is an
 306    * instantiation of.
 307    * E.g. if you want to get a string containing the internal name of
 308    * the type of an object, you can do:
 309    * \if creating-python-scripting-doc
 310    * \code
 311    * tn = object.type().internalName()
 312    * \endcode
 313    * \else
 314    * \code
 315    * std::string typename = object.type()->internalName();
 316    * \endcode
 317    * \endif
 318    */
 319   virtual const ObjectImpType* type() const = 0;
 320   virtual void visit( ObjectImpVisitor* vtor ) const = 0;
 321
 322   /**
 323    * Returns a copy of this ObjectImp.
 324    * The copy is an exact copy.  Changes to the copy don't affect the
 325    * original.
 326    */
 327   virtual ObjectImp* copy() const = 0;
 328
 329   // s is a string with at least one escape ( "%N" where N is a
 330   // number ) somewhere.  This function replaces the first escape it
 331   // sees with the "value" of this imp ( using the QString::arg
 332   // functions ).  This is e.g. used by TextType to turn its variable
 333   // args into strings..
 334   // if you implement this, then you should return true in
 335   // canFillInEscape() ( standard implementation returns false ), and
 336   // override fillInNextEscape() ( standard implementation does an
 337   // assert( false ) )..
 338   virtual bool canFillInNextEscape() const;
 339   virtual void fillInNextEscape( QString& s, const KigDocument& ) const;
 340
 341   /**
 342    * Returns true if this ObjectImp is equal to rhs.
 343    * This function checks whether rhs is of the same ObjectImp type,
 344    * and whether it contains the same data as this ObjectImp.
 345    * \internal It is used e.g. by the KigCommand stuff to see what the
 346    * user has changed during a move..
 347    */
 348   virtual bool equals( const ObjectImp& rhs ) const = 0;
 349
 350   /**
 351    * \internal Return true if this imp is just a cache imp.  This
 352    * means that it will never be considered to be stored in a file or
 353    * in an ObjectHierarchy.  This is useful for objects which cannot
 354    * (easily and usefully) be (de)serialized, like e.g.
 355    * PythonCompiledScriptImp..  For normal objects, the default
 356    * implementation returns false, which is fine.
 357    */
 358   virtual bool isCache() const;
 359 };
 360 #endif