You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
koffice/lib/kofficecore/KoView.h

505 lines
15 KiB

/* 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 __koView_h__
#define __koView_h__
#include <tqwidget.h>
#include <tqguardedptr.h>
#include <kparts/part.h>
#include <KoChild.h>
#include <koffice_export.h>
class KAction;
class KActionCollection;
class TQCustomEvent;
class KoDocument;
class KoMainWindow;
class KMainWindow;
class KoViewPrivate;
class KoViewChild;
class KoFrame;
class KStatusBar;
class KInstance;
class KPrinter;
class KoDocumentChild;
class DCOPObject;
namespace KParts
{
class PartManager;
class PartActivateEvent;
class PartSelectEvent;
}
/**
* This class is used to display a @ref KoDocument.
*
* Multiple views can be attached to one document at a time.
*/
class KOFFICECORE_EXPORT KoView : public TQWidget, public KParts::PartBase
{
Q_OBJECT
public:
/**
* Creates a new view for the document. Usually you don't create views yourself
* since the KOffice components come with their own view classes which inherit
* KoView.
*
* The standard way to retrieve a KoView is to call @ref KoDocument::createView.
*
* @param document is the document which should be displayed in this view. This pointer
* must not be zero.
* @param parent parent widget for this view.
* @param name Name of the view. The name is used in DCOP, so the name should
* match the pattern [A-Za-z_][A-Za-z_0-9]*.
*
*/
KoView( KoDocument *document, TQWidget *parent = 0, const char *name = 0 );
/**
* Destroys the view and unregisters at the document.
*/
virtual ~KoView();
/**
* Retrieves the document object of this view.
*/
KoDocument *koDocument() const;
/**
* Tells this view that its document has got deleted (called internally)
*/
void setDocumentDeleted();
/**
* @return true if the document has already got deleted.
* This can be useful for the view destructor to know if it can
* access the document or not.
*/
bool documentDeleted() const;
virtual void setPartManager( KParts::PartManager *manager );
virtual KParts::PartManager *partManager() const;
/**
* Returns the action described action object. In fact only the "name" attribute
* of @p element is of interest here. The method searches in the
* KActionCollection of this view.
*
* Please notice that KoView indirectly inherits KXMLGUIClient.
*
* @see KXMLGUIClient
* @see KXMLGUIClient::actionCollection
* @see KoDocument::action
*/
virtual KAction *action( const TQDomElement &element ) const;
/**
* Retrieves the document that is hit. This can be an embedded document.
*
* The default implementation asks @ref KoDocument::hitTest. This
* will iterate over all child documents to detect a hit.
*
* If your koffice component has multiple pages, like for example KSpread, then the hittest
* may not succeed for a child that is not on the visible page. In those
* cases you need to reimplement this method.
*/
virtual KoDocument *hitTest( const TQPoint &pos );
/**
* Retrieves the left border width that is displayed around the content if
* the view is active.
*
* In a spread sheet this border is for example used to display the
* rows, while a top border is used to display the names of the cells
* and a right and bottom border is used to display scrollbars. If the view
* becomes inactive, then this stuff is not displayed anymore.
*
* @ref KoFrame uses this border information. If an embedded document becomes active
* then it is resized so that it has enough space to display the borders and to
* display the same content as before the activation.
* So if for example all of your borders are 20 pixels, then activating the embedded
* document causes the KoView to move 20 pixels up/left and the size and width increases
* by 20+20 pixels each.
*
* The default border is 0.
*/
virtual int leftBorder() const;
/**
* @see #leftBorder
*/
virtual int rightBorder() const;
/**
* @see #leftBorder
*/
virtual int topBorder() const;
/**
* @see #leftBorder
*/
virtual int bottomBorder() const;
/**
* Scales the view on the content. This does not affect the contents
* data structures. You can use this mechanism to implement a zoom
* for example.
*
* The method calls TQWidget::update so that the scaled content
* is automatically displayed.
*
* The default scaling is 1.0 in both orientations.
*/
virtual void setZoom( double zoom );
/**
* @return the current scaling factor (zoom level)
*
* @see #setZoom
*/
virtual double zoom() const;
/**
* Overload this function if the content will be displayed
* on some child widget instead of the view directly.
*
* By default this function returns a pointer to the view.
*/
virtual TQWidget *canvas() const;
/**
* Overload this function if the content will be displayed
* with an offset relative to the upper left corner
* of the canvas widget.
*
* By default this function returns 0.
*/
virtual int canvasXOffset() const;
/**
* Overload this function if the content will be displayed
* with an offset relative to the upper left corner
* of the canvas widget.
*
* By default this function returns 0.
*/
virtual int canvasYOffset() const;
/**
* Overload this function if you need to perform some actions
* after KoView (the part widget) is inserted into canvas.
* You should call for example addChild(TQWidget*) method
* of TQScrollView here, if canvas is a viewport of TQScrollView.
*
* By default this function does nothing.
*/
virtual void canvasAddChild( KoViewChild *child );
/**
* @return the selected child. The function returns 0 if
* no direct child is currently selected.
*/
virtual KoDocumentChild *selectedChild();
/**
* @return the active child. The function returns 0 if
* no direct child is currently active.
*/
virtual KoDocumentChild *activeChild();
/**
* Sets up so that autoScroll signals are emitted when the mouse pointer is outside the view
*/
void enableAutoScroll();
/**
* Stops the emitting of autoScroll signals
*/
void disableAutoScroll();
/**
* calls KoDocument::paintEverything()
*/
virtual void paintEverything( TQPainter &painter, const TQRect &rect, bool transparent = false );
/**
* @return TRUE if the document @p doc is represented in this view by
* some KoViewChild.
*
* This is just a convenience function for @ref #child.
*/
bool hasDocumentInWindow( KoDocument *doc );
/**
* Returns the matrix which is used by the view to transform the content.
* Currently only scaling is supported.
*
* The matrix changes when calling @ref #setZoom.
*
* @deprecated, use applyViewTransformations / reverseViewTransformations instead.
*/
virtual TQWMatrix matrix() const KDE_DEPRECATED;
/**
* Apply the transformations that the view makes to its contents.
* This is used for embedded objects.
* By default this simply applies the zoom().
* Reimplement to add some translation if needed (e.g. to center the page)
*/
virtual TQPoint applyViewTransformations( const TQPoint& ) const;
/**
* Reverse the transformations that the view makes to its contents,
* i.e. undo the transformations done by applyViewTransformations().
* This is used for embedded objects.
* By default this simply unzooms the point.
* Reimplement to add some translation if needed (e.g. to center the page)
*/
virtual TQPoint reverseViewTransformations( const TQPoint& ) const;
/**
* Overload for TQRect, usually it's not needed to reimplement this one.
*/
virtual TQRect applyViewTransformations( const TQRect& ) const;
/**
* Overload for TQRect, usually it's not needed to reimplement this one.
*/
virtual TQRect reverseViewTransformations( const TQRect& ) const;
/**
* @return the KoViewChild which is responsible for the @p view or 0.
*
* This method does no recursion.
*/
KoViewChild *child( KoView *view );
/**
* A convenience function which returns the KoViewChild which in turn holds the
* @ref KoView that in turn holds the @p document.
*/
KoViewChild *child( KoDocument *document );
/**
* Return a DCOP interface for this view
* KOffice Applications are strongly recommended to reimplement this method,
* so that their dcop interface provides more functionality than the basic KoViewIface
*/
virtual DCOPObject * dcopObject();
/**
* Overload this method to setup KPrinter before the actual printing.
*
* @see #print
*/
virtual void setupPrinter( KPrinter &printer );
// BCI: make it return a bool, so that aborting doesn't still fire up the print preview afterwards
/**
* Overload this method with your own printing code.
*/
virtual void print( KPrinter &printer );
/**
* @return the KoMainWindow in which this view is currently.
* WARNING: this could be 0L, if the main window isn't a koffice main window.
* (e.g. it can be any KParts application).
*/
KoMainWindow * shell() const;
/**
* @return the KMainWindow in which this view is currently.
* This one should never return 0L, in a KDE app.
*/
KMainWindow* mainWindow() const;
/**
* @return the statusbar of the KoMainWindow in which this view is currently.
* WARNING: this could be 0L, if the main window isn't a koffice main window.
* (e.g. it can be any KParts application).
*/
KStatusBar * statusBar() const;
/**
* This adds a widget to the statusbar for this view.
* If you use this method instead of using statusBar() directly,
* KoView will take care of removing the items when the view GUI is deactivated
* and readding them when it is reactivated.
* The parameters are the same as TQStatusBar::addWidget().
*
* Note that you can't use KStatusBar methods (inserting text items by id).
* But you can create a KStatusBarLabel with a dummy id instead, and use
* it directly, to get the same look and feel.
*/
void addStatusBarItem( TQWidget * widget, int stretch = 0, bool permanent = false );
/**
* Remove a widget from the statusbar for this view.
*/
void removeStatusBarItem( TQWidget * widget );
/**
* Show or hide all statusbar items. Used by KoMainWindow during saving.
*/
void showAllStatusBarItems( bool show );
/**
* You have to implement this method and disable/enable certain functionality (actions for example) in
* your view to allow/disallow editing of the document.
*/
virtual void updateReadWrite( bool readwrite ) = 0;
/**
* Check to see if the view is currently in the middle of an operation which means
* that there will be no screen refreshes until a signal from the document hits
* the @ref #endOperation slot
*/
bool isInOperation() const;
public slots:
/**
* Slot to create a new view around the contained @ref #koDocument.
*/
virtual void newView();
/**
* Slot to allow code to signal the beginning of an operation where the screen should
* not update until it is done.
*
* @see #endOperation
*/
virtual void beginOperation();
/**
* Slot to allow code to signal the end of an operation where the screen should
* not have been updating. So now it will update.
*
* @see #beginOperation
*/
virtual void endOperation();
/**
* Display a message in the status bar (calls TQStatusBar::message())
* @todo rename to something more generic
*/
void slotActionStatusText( const TQString &text );
/**
* End of the message in the status bar (calls TQStatusBar::clear())
* @todo rename to something more generic
*/
void slotClearStatusText();
protected:
/**
* This method handles three events: KParts::PartActivateEvent, KParts::PartSelectEvent
* and KParts::GUIActivateEvent.
* The respective handlers are called if such an event is found.
*/
virtual void customEvent( TQCustomEvent *ev );
/**
* Handles the event KParts::PartActivateEvent.
*/
virtual void partActivateEvent( KParts::PartActivateEvent *event );
/**
* Handles the event KParts::PartSelectEvent.
*/
virtual void partSelectEvent( KParts::PartSelectEvent *event );
/**
* Handles the event KParts::GUIActivateEvent.
*/
virtual void guiActivateEvent( KParts::GUIActivateEvent * );
signals:
void activated( bool active );
void selected( bool select );
void autoScroll(const TQPoint &scrollDistance);
void childSelected( KoDocumentChild *child );
void childUnselected( KoDocumentChild *child );
void childActivated( KoDocumentChild *child );
void childDeactivated( KoDocumentChild *child );
void regionInvalidated( const TQRegion &region, bool erase );
void invalidated();
// KDE invents public signals :)
#undef signals
#define signals public
signals:
/**
* Make it possible for plugins to request
* the embedding of an image into the current
* document. Used e.g. by the scan-plugin
*/
void embeddImage(const TQString &filename);
#undef signals
#define signals protected
protected slots:
virtual void slotChildActivated( bool a );
virtual void slotChildChanged( KoDocumentChild *child );
virtual void slotAutoScroll( );
private:
KAction *actionNewView;
virtual void setupGlobalActions( void );
KoViewPrivate *d;
int autoScrollAcceleration( int offset ) const;
};
/**
* This class represents an active embedded document.
*/
class KoViewChild : public KoChild
{
Q_OBJECT
public:
KoViewChild( KoDocumentChild *child, KoView *_parentView );
virtual ~KoViewChild();
KoDocumentChild *documentChild() const { return m_child; }
KoView *parentView() const { return m_parentView; }
KoFrame *frame() const { return m_frame; }
void setInitialFrameGeometry();
public slots:
// Call this when the view transformations change
void reposition() { slotDocGeometryChanged(); }
private slots:
void slotFrameGeometryChanged();
void slotDocGeometryChanged();
private:
TQGuardedPtr<KoDocumentChild> m_child;
TQGuardedPtr<KoFrame> m_frame;
TQGuardedPtr<KoView> m_parentView;
class KoViewChildPrivate;
KoViewChildPrivate *d;
};
#endif