home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / KoView.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-30  |  14.8 KB  |  503 lines
  1. /* This file is part of the KDE project
  2.    Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License as published by the Free Software Foundation; either
  7.    version 2 of the License, or (at your option) any later version.
  8.  
  9.    This library is distributed in the hope that it will be useful,
  10.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.    Library General Public License for more details.
  13.  
  14.    You should have received a copy of the GNU Library General Public License
  15.    along with this library; see the file COPYING.LIB.  If not, write to
  16.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.  * Boston, MA 02110-1301, USA.
  18. */
  19. #ifndef __koView_h__
  20. #define __koView_h__
  21.  
  22. #include <qwidget.h>
  23. #include <qguardedptr.h>
  24.  
  25. #include <kparts/part.h>
  26.  
  27. #include <KoChild.h>
  28. #include <koffice_export.h>
  29.  
  30. class KAction;
  31. class KActionCollection;
  32. class QCustomEvent;
  33. class KoDocument;
  34. class KoMainWindow;
  35. class KMainWindow;
  36. class KoViewPrivate;
  37. class KoViewChild;
  38. class KoFrame;
  39. class KStatusBar;
  40. class KInstance;
  41. class KPrinter;
  42. class KoDocumentChild;
  43. class DCOPObject;
  44.  
  45. namespace KParts
  46. {
  47.   class PartManager;
  48.   class PartActivateEvent;
  49.   class PartSelectEvent;
  50. }
  51.  
  52. /**
  53.  * This class is used to display a @ref KoDocument.
  54.  *
  55.  * Multiple views can be attached to one document at a time.
  56.  */
  57. class KOFFICECORE_EXPORT KoView : public QWidget, public KParts::PartBase
  58. {
  59.   Q_OBJECT
  60. public:
  61.   /**
  62.    * Creates a new view for the document. Usually you don't create views yourself
  63.    * since the KOffice components come with their own view classes which inherit
  64.    * KoView.
  65.    *
  66.    * The standard way to retrieve a KoView is to call @ref KoDocument::createView.
  67.    *
  68.    * @param document is the document which should be displayed in this view. This pointer
  69.    *                 must not be zero.
  70.    * @param parent   parent widget for this view.
  71.    * @param name     Name of the view. The name is used in DCOP, so the name should
  72.    *                 match the pattern [A-Za-z_][A-Za-z_0-9]*.
  73.    *
  74.    */
  75.   KoView( KoDocument *document, QWidget *parent = 0, const char *name = 0 );
  76.   /**
  77.    * Destroys the view and unregisters at the document.
  78.    */
  79.   virtual ~KoView();
  80.  
  81.   /**
  82.    *  Retrieves the document object of this view.
  83.    */
  84.   KoDocument *koDocument() const;
  85.  
  86.   /**
  87.    * Tells this view that its document has got deleted (called internally)
  88.    */
  89.   void setDocumentDeleted();
  90.   /**
  91.    * @return true if the document has already got deleted.
  92.    * This can be useful for the view destructor to know if it can
  93.    * access the document or not.
  94.    */
  95.   bool documentDeleted() const;
  96.  
  97.   virtual void setPartManager( KParts::PartManager *manager );
  98.   virtual KParts::PartManager *partManager() const;
  99.  
  100.   /**
  101.    * Returns the action described action object. In fact only the "name" attribute
  102.    * of @p element is of interest here. The method searches in the
  103.    * KActionCollection of this view.
  104.    *
  105.    * Please notice that KoView indirectly inherits KXMLGUIClient.
  106.    *
  107.    * @see KXMLGUIClient
  108.    * @see KXMLGUIClient::actionCollection
  109.    * @see KoDocument::action
  110.    */
  111.   virtual KAction *action( const QDomElement &element ) const;
  112.  
  113.   /**
  114.    *  Retrieves the document that is hit. This can be an embedded document.
  115.    *
  116.    *  The default implementation asks @ref KoDocument::hitTest. This
  117.    *  will iterate over all child documents to detect a hit.
  118.    *
  119.    *  If your koffice component has multiple pages, like for example KSpread, then the hittest
  120.    *  may not succeed for a child that is not on the visible page. In those
  121.    *  cases you need to reimplement this method.
  122.    */
  123.   virtual KoDocument *hitTest( const QPoint &pos );
  124.  
  125.   /**
  126.    * Retrieves the left border width that is displayed around the content if
  127.    * the view is active.
  128.    *
  129.    * In a spread sheet this border is for example used to display the
  130.    * rows, while a top border is used to display the names of the cells
  131.    * and a right and bottom border is used to display scrollbars. If the view
  132.    * becomes inactive, then this stuff is not displayed anymore.
  133.    *
  134.    * @ref KoFrame uses this border information. If an embedded document becomes active
  135.    * then it is resized so that it has enough space to display the borders and to
  136.    * display the same content as before the activation.
  137.    * So if for example all of your borders are 20 pixels, then activating the embedded
  138.    * document causes the KoView to move 20 pixels up/left and the size and width increases
  139.    * by 20+20 pixels each.
  140.    *
  141.    * The default border is 0.
  142.    */
  143.   virtual int leftBorder() const;
  144.   /**
  145.    * @see #leftBorder
  146.    */
  147.   virtual int rightBorder() const;
  148.   /**
  149.    * @see #leftBorder
  150.    */
  151.   virtual int topBorder() const;
  152.   /**
  153.    * @see #leftBorder
  154.    */
  155.   virtual int bottomBorder() const;
  156.  
  157.   /**
  158.    * Scales the view on the content. This does not affect the contents
  159.    * data structures. You can use this mechanism to implement a zoom
  160.    * for example.
  161.    *
  162.    * The method calls QWidget::update so that the scaled content
  163.    * is automatically displayed.
  164.    *
  165.    * The default scaling is 1.0 in both orientations.
  166.    */
  167.   virtual void setZoom( double zoom );
  168.   /**
  169.    * @return the current scaling factor (zoom level)
  170.    *
  171.    * @see #setZoom
  172.    */
  173.   virtual double zoom() const;
  174.  
  175.   /**
  176.    * Overload this function if the content will be displayed
  177.    * on some child widget instead of the view directly.
  178.    *
  179.    * By default this function returns a pointer to the view.
  180.    */
  181.   virtual QWidget *canvas() const;
  182.  
  183.   /**
  184.    * Overload this function if the content will be displayed
  185.    * with an offset relative to the upper left corner
  186.    * of the canvas widget.
  187.    *
  188.    * By default this function returns 0.
  189.    */
  190.   virtual int canvasXOffset() const;
  191.  
  192.   /**
  193.    * Overload this function if the content will be displayed
  194.    * with an offset relative to the upper left corner
  195.    * of the canvas widget.
  196.    *
  197.    * By default this function returns 0.
  198.    */
  199.   virtual int canvasYOffset() const;
  200.  
  201.   /**
  202.    * Overload this function if you need to perform some actions
  203.    * after KoView (the part widget) is inserted into canvas.
  204.    * You should call for example addChild(QWidget*) method
  205.    * of QScrollView here, if canvas is a viewport of QScrollView.
  206.    *
  207.    * By default this function does nothing.
  208.    */
  209.   virtual void canvasAddChild( KoViewChild *child );
  210.  
  211.   /**
  212.    * @return the selected child. The function returns 0 if
  213.    *         no direct child is currently selected.
  214.    */
  215.    virtual KoDocumentChild *selectedChild();
  216.  
  217.   /**
  218.    * @return the active child. The function returns 0 if
  219.    *         no direct child is currently active.
  220.    */
  221.   virtual KoDocumentChild *activeChild();
  222.  
  223.   /**
  224.    * Sets up so that autoScroll signals are emitted when the mouse pointer is outside the view
  225.    */
  226.   void enableAutoScroll();
  227.  
  228.   /**
  229.    * Stops the emitting of autoScroll signals
  230.    */
  231.   void disableAutoScroll();
  232.  
  233.   /**
  234.    * calls KoDocument::paintEverything()
  235.    */
  236.   virtual void paintEverything( QPainter &painter, const QRect &rect, bool transparent = false );
  237.  
  238.   /**
  239.    * @return TRUE if the document @p doc is represented in this view by
  240.    *         some KoViewChild.
  241.    *
  242.    * This is just a convenience function for @ref #child.
  243.    */
  244.   bool hasDocumentInWindow( KoDocument *doc );
  245.  
  246.   /**
  247.    * Returns the matrix which is used by the view to transform the content.
  248.    * Currently only scaling is supported.
  249.    *
  250.    * The matrix changes when calling @ref #setZoom.
  251.    *
  252.    * @deprecated, use applyViewTransformations / reverseViewTransformations instead.
  253.    */
  254.   virtual QWMatrix matrix() const KDE_DEPRECATED;
  255.  
  256.   /**
  257.    * Apply the transformations that the view makes to its contents.
  258.    * This is used for embedded objects.
  259.    * By default this simply applies the zoom().
  260.    * Reimplement to add some translation if needed (e.g. to center the page)
  261.    */
  262.   virtual QPoint applyViewTransformations( const QPoint& ) const;
  263.  
  264.   /**
  265.    * Reverse the transformations that the view makes to its contents,
  266.    * i.e. undo the transformations done by applyViewTransformations().
  267.    * This is used for embedded objects.
  268.    * By default this simply unzooms the point.
  269.    * Reimplement to add some translation if needed (e.g. to center the page)
  270.    */
  271.   virtual QPoint reverseViewTransformations( const QPoint& ) const;
  272.  
  273.   /**
  274.    * Overload for QRect, usually it's not needed to reimplement this one.
  275.    */
  276.   virtual QRect applyViewTransformations( const QRect& ) const;
  277.  
  278.   /**
  279.    * Overload for QRect, usually it's not needed to reimplement this one.
  280.    */
  281.   virtual QRect reverseViewTransformations( const QRect& ) const;
  282.  
  283.   /**
  284.    * @return the KoViewChild which is responsible for the @p view or 0.
  285.    *
  286.    * This method does no recursion.
  287.    */
  288.   KoViewChild *child( KoView *view );
  289.   /**
  290.    * A convenience function which returns the KoViewChild which in turn holds the
  291.    * @ref KoView that in turn holds the @p document.
  292.    */
  293.   KoViewChild *child( KoDocument *document );
  294.  
  295.   /**
  296.    * Return a DCOP interface for this view
  297.    * KOffice Applications are strongly recommended to reimplement this method,
  298.    * so that their dcop interface provides more functionality than the basic KoViewIface
  299.    */
  300.   virtual DCOPObject * dcopObject();
  301.  
  302.   /**
  303.    * Overload this method to setup KPrinter before the actual printing.
  304.    *
  305.    * @see #print
  306.    */
  307.   virtual void setupPrinter( KPrinter &printer );
  308.  
  309.   // BCI: make it return a bool, so that aborting doesn't still fire up the print preview afterwards
  310.   /**
  311.    * Overload this method with your own printing code.
  312.    */
  313.   virtual void print( KPrinter &printer );
  314.  
  315.   /**
  316.    * @return the KoMainWindow in which this view is currently.
  317.    * WARNING: this could be 0L, if the main window isn't a koffice main window.
  318.    * (e.g. it can be any KParts application).
  319.    */
  320.   KoMainWindow * shell() const;
  321.  
  322.   /**
  323.    * @return the KMainWindow in which this view is currently.
  324.    * This one should never return 0L, in a KDE app.
  325.    */
  326.   KMainWindow* mainWindow() const;
  327.  
  328.   /**
  329.    * @return the statusbar of the KoMainWindow in which this view is currently.
  330.    * WARNING: this could be 0L, if the main window isn't a koffice main window.
  331.    * (e.g. it can be any KParts application).
  332.    */
  333.   KStatusBar * statusBar() const;
  334.  
  335.   /**
  336.    * This adds a widget to the statusbar for this view.
  337.    * If you use this method instead of using statusBar() directly,
  338.    * KoView will take care of removing the items when the view GUI is deactivated
  339.    * and readding them when it is reactivated.
  340.    * The parameters are the same as QStatusBar::addWidget().
  341.    *
  342.    * Note that you can't use KStatusBar methods (inserting text items by id).
  343.    * But you can create a KStatusBarLabel with a dummy id instead, and use
  344.    * it directly, to get the same look and feel.
  345.    */
  346.   void addStatusBarItem( QWidget * widget, int stretch = 0, bool permanent = false );
  347.  
  348.   /**
  349.    * Remove a widget from the statusbar for this view.
  350.    */
  351.   void removeStatusBarItem( QWidget * widget );
  352.  
  353.   /**
  354.    * Show or hide all statusbar items. Used by KoMainWindow during saving.
  355.    */
  356.   void showAllStatusBarItems( bool show );
  357.  
  358.   /**
  359.    * You have to implement this method and disable/enable certain functionality (actions for example) in
  360.    * your view to allow/disallow editing of the document.
  361.    */
  362.   virtual void updateReadWrite( bool readwrite ) = 0;
  363.  
  364.    /**
  365.     * Check to see if the view is currently in the middle of an operation which means
  366.     * that there will be no screen refreshes until a signal from the document hits
  367.     * the @ref #endOperation slot
  368.     */
  369.   bool isInOperation() const;
  370.  
  371. public slots:
  372.     /**
  373.      * Slot to create a new view around the contained @ref #koDocument.
  374.      */
  375.     virtual void newView();
  376.  
  377.     /**
  378.      * Slot to allow code to signal the beginning of an operation where the screen should
  379.      * not update until it is done.
  380.      *
  381.      * @see #endOperation
  382.      */
  383.     virtual void beginOperation();
  384.  
  385.     /**
  386.      * Slot to allow code to signal the end of an operation where the screen should
  387.      * not have been updating. So now it will update.
  388.      *
  389.      * @see #beginOperation
  390.      */
  391.     virtual void endOperation();
  392.  
  393.     /**
  394.      * Display a message in the status bar (calls QStatusBar::message())
  395.      * @todo rename to something more generic
  396.      */
  397.     void slotActionStatusText( const QString &text );
  398.  
  399.     /**
  400.      * End of the message in the status bar (calls QStatusBar::clear())
  401.      * @todo rename to something more generic
  402.      */
  403.     void slotClearStatusText();
  404.  
  405. protected:
  406.   /**
  407.    * This method handles three events: KParts::PartActivateEvent, KParts::PartSelectEvent
  408.    * and KParts::GUIActivateEvent.
  409.    * The respective handlers are called if such an event is found.
  410.    */
  411.   virtual void customEvent( QCustomEvent *ev );
  412.  
  413.   /**
  414.    * Handles the event KParts::PartActivateEvent.
  415.    */
  416.   virtual void partActivateEvent( KParts::PartActivateEvent *event );
  417.   /**
  418.    * Handles the event KParts::PartSelectEvent.
  419.    */
  420.   virtual void partSelectEvent( KParts::PartSelectEvent *event );
  421.   /**
  422.    * Handles the event KParts::GUIActivateEvent.
  423.    */
  424.   virtual void guiActivateEvent( KParts::GUIActivateEvent * );
  425.  
  426. signals:
  427.   void activated( bool active );
  428.   void selected( bool select );
  429.  
  430.   void autoScroll(const QPoint &scrollDistance);
  431.  
  432.   void childSelected( KoDocumentChild *child );
  433.   void childUnselected( KoDocumentChild *child );
  434.  
  435.   void childActivated( KoDocumentChild *child );
  436.   void childDeactivated( KoDocumentChild *child );
  437.  
  438.   void regionInvalidated( const QRegion ®ion, bool erase );
  439.  
  440.   void invalidated();
  441.  
  442. // KDE invents public signals :)
  443. #undef signals
  444. #define signals public
  445. signals:
  446.  
  447.   /**
  448.     * Make it possible for plugins to request
  449.     * the embedding of an image into the current
  450.     * document. Used e.g. by the scan-plugin
  451.   */
  452.   void embeddImage(const QString &filename);
  453.  
  454. #undef signals
  455. #define signals protected
  456.  
  457. protected slots:
  458.   virtual void slotChildActivated( bool a );
  459.   virtual void slotChildChanged( KoDocumentChild *child );
  460.   virtual void slotAutoScroll( );
  461.  
  462. private:
  463.   KAction *actionNewView;
  464.   virtual void setupGlobalActions( void );
  465.   KoViewPrivate *d;
  466.   int autoScrollAcceleration( int offset ) const;
  467. };
  468.  
  469. /**
  470.  * This class represents an active embedded document.
  471.  */
  472. class KoViewChild : public KoChild
  473. {
  474.   Q_OBJECT
  475. public:
  476.   KoViewChild( KoDocumentChild *child, KoView *_parentView );
  477.   virtual ~KoViewChild();
  478.  
  479.   KoDocumentChild *documentChild() const { return m_child; }
  480.   KoView *parentView() const { return m_parentView; }
  481.   KoFrame *frame() const { return m_frame; }
  482.  
  483.   void setInitialFrameGeometry();
  484.  
  485. public slots:
  486.  
  487.   // Call this when the view transformations change
  488.   void reposition() { slotDocGeometryChanged(); }
  489.  
  490. private slots:
  491.   void slotFrameGeometryChanged();
  492.   void slotDocGeometryChanged();
  493.  
  494. private:
  495.   QGuardedPtr<KoDocumentChild> m_child;
  496.   QGuardedPtr<KoFrame> m_frame;
  497.   QGuardedPtr<KoView> m_parentView;
  498.   class KoViewChildPrivate;
  499.   KoViewChildPrivate *d;
  500. };
  501.  
  502. #endif
  503.