koffice/lib/kofficecore/KoChild.h

/* This file is part of the KDE project
   Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
*/
#ifndef __koChild_h__
#define __koChild_h__

#include <tqobject.h>
#include <tqwmatrix.h>
#include <koffice_export.h>

/**
 * KoChild is an abstract base class that represents the geometry
 * associated with an embedded document. In general it handles its position
 * relative to the embedded document's parent.
 *
 * In detail it handles size, matrix operations and can give you
 * a clip region. It can deal with scaling, rotation etc. because it
 * makes heavy usage of TQWMatrix.
 *
 * After applying the matrix, viewGeometry() applies zooming, but can be
 * reimplemented to also apply e.g. some translation by the application
 * (e.g. for centering the page).
 *
 * @see KoDocumentChild KoViewChild
 */
class KOFFICECORE_EXPORT KoChild : public TQObject
{
  Q_OBJECT
  
public:

  /**
   * The gadget generally identifies where a child has been hit (generally
   * by the mouse pointer).
   * Based on this information different actions can be taken, for example
   * moving the child or opening a context menu. NoGadget means that
   * this child has not been hit.
   *
   * @see #gadgetHitTest
   */
  enum Gadget { NoGadget, TopLeft, TopMid, TopRight, MidLeft, MidRight,
		BottomLeft, BottomMid, BottomRight, Move };

  KoChild( TQObject *parent = 0, const char *name = 0 );
  virtual ~KoChild();

  /**
   *  Sets a new geometry for this child document.
   *  Use noEmit = true if you do not want the 'changed'-signal to be emitted
   */
  void setGeometry( const TQRect &rect, bool noEmit = false );

  /**
   * @return the rectangle that would be used to display this
   *         child document if the child is not rotated or
   *         subject to some other geometric transformation.
   *         The rectangle is in the coordinate system of the parent,
   *         using unzoomed coordinates in points.
   *
   * @see #setGeometry
   */
  TQRect geometry() const;

  /**
   * @return the region of this child part relative to the
   *         coordinate system of the parent.
   *         The region is transformed with the passed
   *         matrix.
   */
  virtual TQRegion region( const TQWMatrix& = TQWMatrix() ) const;

  /**
   * @return the polygon which surrounds the child part. The points
   *         are in coordinates of the parent.
   *         The points are transformed with the
   *         passed matrix.
   */
  virtual TQPointArray pointArray( const TQWMatrix &matrix = TQWMatrix() ) const;

  /**
   * Tests whether the part contains a certain point. The point is
   * in the coordinate system of the parent.
   */
  //virtual bool contains( const TQPoint& ) const;

  /**
   * @return the effective bounding rect after all transformations.
   *         The coordinates of the rectangle are in the coordinate system
   *         of the parent.
   */
  TQRect boundingRect() const;

  /**
   * Scales the content of the child part. However, that does not
   * affect the size of the child part.
   */
  virtual void setScaling( double x, double y );

  /**
   * @return the x axis scaling of the child part
   */
  virtual double xScaling() const;

  /**
   * @return the y axis scaling of the child part
   */
  virtual double yScaling() const;

  /**
   * Shears the content of the child part.
   */
  virtual void setShearing( double x, double y );

  /**
   * @return the x axis shearing of the child part
   */
  virtual double xShearing() const;

  /**
   * @return the y axis shearing of the child part
   */
  virtual double yShearing() const;

  /**
   * Sets the angle of rotation.
   */
  virtual void setRotation( double );

  /**
   * @return the angle of rotation
   */
  virtual double rotation() const;

  /**
   * Sets the center of the rotation to the point @p pos.
   */
  virtual void setRotationPoint( const TQPoint& pos );

  /**
   * @return the center of the rotation
   */
  virtual TQPoint rotationPoint() const;

  /**
   * @return true if the child part is an orthogonal rectangle relative
   *         to its parents coordinate system.
   */
  bool isRectangle() const;

  /**
   * Sets the clip region of the painter, so that only pixels of the
   * child part can be drawn.
   *
   * @param painter the painter do modify.
   * @param combine tells whether the new clip region is an intersection
   *        of the current region with the childs region or whether only
   *        the childs region is set.
   */
  virtual void setClipRegion( TQPainter& painter, bool combine = true );

  /**
   * Transforms the painter (its worldmatrix and the clipping)
   * in such a way that the painter can be passed to the child part
   * for drawing.
   */
  virtual void transform( TQPainter& painter );

  /**
   * Sets the position of the content relative to the child frame.
   * This can be used to create a border between the frame border
   * and the actual content.
   */
  virtual void setContentsPos( int x, int y );

  /**
   * @return the contents rectangle that is visible.
   *         This value depends on the scaling and the geometry.
   *         This is the value that is passed to KoDocument::paintContent.
   *
   * @see #xScaling #geometry
   */
  virtual TQRect contentRect() const;

  /**
   * @return the region of the child frame.
   *         If solid is set to true the complete area of the child region
   *         is returned, otherwise only the child border is returned.
   */
  virtual TQRegion frameRegion( const TQWMatrix& matrix = TQWMatrix(), bool solid = false ) const;

  /**
   * @return the frame geometry including a border (6 pixels) as a point
   *         array with 4 points, one for each corner, transformed by given matrix.
   */
  virtual TQPointArray framePointArray( const TQWMatrix &matrix = TQWMatrix() ) const;

  /**
   * @return the current transformation of this child as matrix.
   *         This includes translation, scale, rotation, shearing.
   *
   * @see #updateMatrix
   */
  virtual TQWMatrix matrix() const;

  /**
   * Locks this child and stores the current transformation.
   * A locked child does not emit changed signals.
   *
   * This is useful if a series of changes are done on this
   * child and only the final result is of interest (GUI updating,...).
   *
   * @see #locked #unlock
   */
  void lock();

  /**
   * Unlocks this child and emits a changed signal.
   */
  void unlock();

  /**
   * If the child is locked, geometry changes
   * (including scaling, rotation, ...) are not backed up.
   *
   * As long as this child is locked, the backed up
   * geometry state can be recovered with oldPointArray.
   *
   * @return true when this child is locked.
   *
   * @see #locked #unlock #oldPointArray
   */
  bool locked() const;

  /**
   * @return the backed up geometry transformed by given matrix.
   */
  virtual TQPointArray oldPointArray( const TQWMatrix &matrix );

  /**
   * Marks this child as either transparent or not.
   * @param transparent set this child to transparent (true)
   *           or opaque (false).
   *
   * @see #isTransparent
   */
  virtual void setTransparent( bool transparent );

  /**
   * It might be interesting for view updates and repainting in general
   * whether a child is transparent or not.
   * @return true when this child is marked as transparent.
   */
  virtual bool isTransparent() const;

  /**
   * Different actions are taken depending on where a child frame is
   * hit. Two gadgets are known: one for the border (5 pixels) and one
   * for the inner area.
   * @return the gadget identification for the hit area.
   * @param p the hit position.
   *
   * @see #Gadget
   */
  virtual Gadget gadgetHitTest( const TQPoint& p );

signals:

  /**
   * Emitted every time this child changes, but only if this child is not
   * locked.
   * @see #locked
   */
  void changed( KoChild *thisChild );

protected:

  /**
   * @return point array with the 4 corners of given rectangle, which is
   *         transformed by given matrix.
   *
   *  @param matrix the transformation of r.
   *  @param r the rectangle for which the point array should be created.
   */
  virtual TQPointArray pointArray( const TQRect& r, const TQWMatrix& matrix = TQWMatrix() ) const;

  /**
   * Stores the current transformation of this child into a matrix.
   *
   * @see #matrix
   */
  virtual void updateMatrix();
private:

  class KoChildPrivate;
  KoChildPrivate *d;
};

#endif