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/KoDocument.h

1160 lines
40 KiB

// -*- c-basic-offset: 4 -*-
/* This file is part of the KDE project
Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>
Copyright (C) 2000-2005 David Faure <faure@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 __ko_document_h__
#define __ko_document_h__
class KoTextDocument;
namespace std { }
using namespace std;
#include <tqwmatrix.h>
#include <kparts/part.h>
#include <kurl.h>
#include <kservice.h>
#include <KoGlobal.h>
#include <KoUnit.h>
#include <KoPageLayout.h>
#include <koffice_export.h>
class TQDomElement;
class TQDomDocument;
class TQXmlSimpleReader;
class KoStore;
class KoMainWindow;
class KoChild;
class KoDocumentChild;
class KoView;
class KoDocumentInfo;
class DCOPObject;
class KoOasisStyles;
class KoXmlWriter;
class KoOpenPane;
/**
* The %KOffice document class
*
* This class provides some functionality each %KOffice document should have.
*
* @short The %KOffice document class
*/
class KOFFICECORE_EXPORT KoDocument : public KParts::ReadWritePart
{
Q_OBJECT
TQ_PROPERTY( TQCString dcopObjectId READ dcopObjectId)
TQ_PROPERTY( bool backupFile READ backupFile WRITE setBackupFile )
public:
/**
* Constructor.
* The first 4 arguments are the same as the ones passed to KParts::Factory::createPart.
*
* @param parentWidget the parent widget, in case we create a wrapper widget
* (in single view mode).
* Usually the first argument passed by KParts::Factory::createPart.
* @param widgetName name of the widget.
* @param parent may be another KoDocument, or anything else.
* Usually the third argument of KParts::Factory::createPart.
* @param name is used to identify this document via DCOP so you may want to
* pass a meaningful name here which matches the pattern [A-Za-z_][A-Za-z_0-9]*.
* @param singleViewMode determines whether the document may only have one view. In this case
* the @p parent must be a TQWidget derived class. KoDocument will then create a wrapper widget
* (KoViewWrapperWidget) which is a child of @p parentWidget.
* This widget can be retrieved by calling widget().
*
* @todo explain what the purpose of widgetName is.
*/
KoDocument( TQWidget* parentWidget,
const char* widgetName,
TQObject* parent,
const char* name,
bool singleViewMode = false );
/**
* Destructor.
*
* The destructor does not delete any attached KoView objects and it does not
* delete the attached widget as returned by widget().
*/
virtual ~KoDocument();
/**
* Tells whether this document is in singleview mode. This mode can only be set
* in the constructor.
*/
bool isSingleViewMode() const;
/**
* Is the document embedded?
*/
bool isEmbedded() const;
/**
* Returns the action described action object. In fact only the "name" attribute
* of @p element is of interest here. The method searches first in the
* KActionCollection of the first view and then in the KActionCollection of this
* document.
* This allows %KOffice applications to define actions in both the view and the document.
* They should only define view-actions (like zooming and stuff) in the view.
* Every action which changes the document should be defined in the document.
*
* Please notice that KoDocument indirectly inherits KXMLGUIClient.
*
* @see KXMLGUIClient
* @see KXMLGUIClient::actionCollection
* @see KoView::action
*/
virtual KAction *action( const TQDomElement &element ) const;
/**
* Returns the DOM document which describes the GUI of the
* first view.
*/
virtual TQDomDocument domDocument() const;
/**
* @internal
*/
virtual void setManager( KParts::PartManager *manager );
/**
* Reimplemented from KParts::ReadWritePart for internal reasons
* (for the autosave functionality)
*/
virtual bool openURL( const KURL & url );
/**
* Opens the document given by @p url, without storing the URL
* in the KoDocument.
* Call this instead of openURL() to implement KoMainWindow's
* File --> Import feature.
*
* @note This will call openURL(). To differentiate this from an ordinary
* Open operation (in any reimplementation of openURL() or openFile())
* call isImporting().
*/
bool import( const KURL &url );
/**
* Saves the document as @p url without changing the state of the
* KoDocument (URL, modified flag etc.). Call this instead of
* KParts::ReadWritePart::saveAs() to implement KoMainWindow's
* File --> Export feature.
*
* @note This will call KoDocument::saveAs(). To differentiate this
* from an ordinary Save operation (in any reimplementation of
* saveFile()) call isExporting().
*/
bool exp0rt( const KURL &url );
/**
* @brief Sets whether the document can be edited or is read only.
*
* This recursively applied to all child documents and
* KoView::updateReadWrite is called for every attached
* view.
*/
virtual void setReadWrite( bool readwrite = true );
/**
* @brief Used by KoApplication, and by KoMainWindow, when no document exists yet.
*
* With the help of @p instance or KApplication::instance() this
* method figures out which .desktop file matches this application. In this
* file it searches for the "X-TDE-NativeMimeType" entry and returns it.
*
* @see KService
* @see KDesktopFile
*/
static TQCString readNativeFormatMimeType( KInstance *instance = 0 );
/**
* Used by KoMainWindow, when no document exists yet.
*
* With the help of @p instance or KApplication::instance() this
* method figures out which .desktop file matches this application. In this
* file it searches for the "X-TDE-ExtraNativeMimeTypes" entry and returns it.
*
* @see KService
* @see KDesktopFile
*/
static TQStringList readExtraNativeMimeTypes( KInstance *instance = 0 );
/**
* With the help of @p instance or KApplication::instance() this
* method figures out which .desktop file matches this application,
* and returns the KService instance for it.
*/
static KService::Ptr readNativeService( KInstance *instance = 0 );
/**
* setup the XML reader, so that we don't have to duplicate the code.
*/
static void setupXmlReader( TQXmlSimpleReader& reader, bool namespaceProcessing = false );
/**
* To be preferred when a document exists. It is fast when calling
* it multiple times since it caches the result that readNativeFormatMimeType()
* delivers.
* This comes from the X-TDE-NativeMimeType key in the .desktop file
* You do NOT have to reimplement this (it is only virtual for kounavail).
*/
virtual TQCString nativeFormatMimeType() const;
/**
* Returns the OASIS OpenDocument mimetype of the document, if supported
* This comes from the X-TDE-NativeOasisMimeType key in the .desktop file
*/
TQCString nativeOasisMimeType() const;
/// Checks whether a given mimetype can be handled natively.
bool isNativeFormat( const TQCString& mimetype ) const;
/// Returns a list of the mimetypes considered "native", i.e. which can
/// be saved by KoDocument without a filter, in *addition* to the main one
virtual TQStringList extraNativeMimeTypes() const;
/// Enum values used by specialOutputFlag - note that it's a bitfield for supportedSpecialFormats
enum { /*SaveAsKOffice1dot1 = 1,*/ // old and removed
SaveAsDirectoryStore = 2,
SaveAsFlatXML = 4
// bitfield! next value is 8
};
/**
* Return the set of SupportedSpecialFormats that the application wants to
* offer in the "Save" file dialog.
*/
virtual int supportedSpecialFormats() const;
/**
* Returns the actual mimetype of the document
*/
TQCString mimeType() const;
/**
* @brief Sets the mime type for the document.
*
* When choosing "save as" this is also the mime type
* selected by default.
*/
void setMimeType( const TQCString & mimeType );
/**
* @brief Set the format in which the document should be saved.
*
* This is called on loading, and in "save as", so you shouldn't
* have to call it.
*
* @param mimeType the mime type (format) to use.
* @param specialOutputFlag is for "save as older version" etc.
*/
void setOutputMimeType( const TQCString & mimeType, int specialOutputFlag = 0 );
TQCString outputMimeType() const;
int specialOutputFlag() const;
/**
* Returns true if this document was the result of opening a foreign
* file format and if the user hasn't yet saved the document (in any
* format).
*
* Used by KoMainWindow to warn the user when s/he lazily presses
* CTRL+S to save in the same foreign format, putting all his/her
* formatting at risk (normally an export confirmation only comes up
* with Save As).
*
* @param exporting specifies whether this is the setting for a
* File --> Export or File --> Save/Save As operation.
*/
bool confirmNonNativeSave( const bool exporting ) const;
void setConfirmNonNativeSave( const bool exporting, const bool on );
virtual bool wantExportConfirmation() const;
/**
* Sets the error message to be shown to the user (use i18n()!)
* when loading or saving fails.
* If you asked the user about something and he chose "Cancel",
* set the message to the magic string "USER_CANCELED", to skip the error dialog.
*/
void setErrorMessage( const TQString& errMsg );
/**
* Return the last error message. Usually KoDocument takes care of
* showing it; this method is mostly provided for non-interactive use.
* @since 1.4
*/
TQString errorMessage() const;
/**
* Show the last error message in a message box.
* The dialog box will mention a saving problem.
* Note that save/saveFile takes care of doing it.
* @since 1.4
*/
void showSavingErrorDialog();
/**
* Show the last error message in a message box.
* The dialog box will mention a loading problem.
* openURL/openFile takes care of doing it, but not loadNativeFormat itself,
* so this is often called after loadNativeFormat returned false.
* @since 1.4
*/
void showLoadingErrorDialog();
/**
* Create a new view for the document.
*/
KoView *createView( TQWidget *parent = 0, const char *name = 0 );
/**
* Adds a view to the document.
*
* This calls KoView::updateReadWrite to tell the new view
* whether the document is readonly or not.
*/
virtual void addView( KoView *view );
/**
* Removes a view of the document.
*/
virtual void removeView( KoView *view );
/**
* @return a list of views this document is displayed in
*/
const TQPtrList<KoView> & views() const;
/**
* @return number of views this document is displayed in
*/
int viewCount() const;
/**
* Reimplemented from KParts::Part
*/
virtual KParts::Part *hitTest( TQWidget *widget, const TQPoint &globalPos );
/**
* Find the most nested child document which contains the
* requested point. The point is in the coordinate system
* of this part. If no child document contains this point, then
* a pointer to this document is returned.
*
* This function has to be overloaded if the document features child documents.
*
* @param pos is in (unzoomed) document coordinates
* @param matrix transforms points from the documents coordinate system
* to the coordinate system of the requested point. This is used by
* transformed child documents, see KoDocumentChild/KoChild.
*
* @return Pointer to the document under the mouse at that position
*/
virtual KoDocument *hitTest( const TQPoint &pos, const TQWMatrix& matrix = TQWMatrix() );
/// Temporary API for accessing the view that calls hitTest.
/// Will be passed to hitTest() in 2.x.
/// Only call this from within hitTest()!
KoView* hitTestView();
/**
* Paints the whole document into the given painter object.
*
* @param painter The painter object onto which will be drawn.
* @param rect The rect that should be used in the painter object.
* @param transparent If true then the entire rectangle is erased before painting.
* @param view The KoView is needed to fiddle about with the active widget, when painting children.
* @param zoomX The zoom value to be applied to X coordinates when painting.
* @param zoomY The zoom value to be applied to Y coordinates when painting.
*/
virtual void paintEverything( TQPainter &painter, const TQRect &rect, bool transparent = false,
KoView *view = 0L, double zoomX = 1.0, double zoomY = 1.0 );
/**
* @brief Generates a preview picture of the document
* @note The preview is used in the File Dialog and also to create the Thumbnail
*/
virtual TQPixmap generatePreview( const TQSize& size );
/**
* Paints all of the documents children into the given painter object.
*
* @param painter The painter object onto which will be drawn.
* @param rect The rect that should be used in the painter object.
* @param view The KoView is needed to fiddle about with the active widget.
* @param zoomX The zoom value to be applied to X coordinates when painting.
* @param zoomY The zoom value to be applied to Y coordinates when painting.
*
* @see #paintChild #paintEverything #paintContent
*/
virtual void paintChildren( TQPainter &painter, const TQRect &rect, KoView *view, double zoomX = 1.0, double zoomY = 1.0 );
/**
* Paint a given child. Normally called by paintChildren().
*
* @param child The child to be painted.
* @param painter The painter object onto which will be drawn.
* @param view The KoView is needed to fiddle about with the active widget.
* @param zoomX The zoom value to be applied to X coordinates when painting.
* @param zoomY The zoom value to be applied to Y coordinates when painting.
*
* @see #paintEverything #paintChildren #paintContent
*/
virtual void paintChild( KoDocumentChild *child, TQPainter &painter, KoView *view,
double zoomX = 1.0, double zoomY = 1.0 );
/**
* Paints the data itself. Normally called by paintEverything(). It does not
* paint the children.
* It's this method that %KOffice Parts have to implement.
*
* @param painter The painter object onto which will be drawn.
* @param rect The rect that should be used in the painter object.
* @param transparent If false the implementing method should fill the background.
* @param zoomX The zoom value to be applied to X coordinates when painting.
* @param zoomY The zoom value to be applied to Y coordinates when painting.
*
* @see #paintEverything
*/
virtual void paintContent( TQPainter &painter, const TQRect &rect, bool transparent = false,
double zoomX = 1.0, double zoomY = 1.0 ) = 0;
/**
* Called by koApplication to check for an autosave file in $HOME
*/
bool checkAutoSaveFile();
/**
* This setting indicates who is calling initDoc.
* Usually the app will want to
* - show the template dialog with 'everything' if InitDocAppStarting, InitDocFileClose or InitDocEmbedded
* - show the template dialog with 'templates only' if InitDocFileNew
* - create an empty document with default settings if InitDocEmpty
*/
enum InitDocFlags { InitDocAppStarting, InitDocFileNew, InitDocFileClose, InitDocEmbedded, InitDocEmpty };
/**
* Initializes an empty document (display the template dialog!).
* You have to overload this method to initialize all your document variables.
* @param flags see InitDocFlags
* @param parentWidget the widget this document belongs with
*/
virtual bool initDoc(InitDocFlags flags, TQWidget* parentWidget=0) = 0;
/**
* Creates and shows the start up widget.
* @param parent the KoMainWindow used as parent for the widget.
* @param alwaysShow always show the widget even if the user has configured it to not show.
* @since 1.5
*/
virtual void showStartUpWidget(KoMainWindow* parent, bool alwaysShow = false);
/**
* Sets the modified flag on the document. This means that it has
* to be saved or not before deleting it.
*/
virtual void setModified( bool _mod );
/**
* Tells the document that its title has been modified, either because
* the modified status changes (this is done by setModified() ) or
* because the URL or the document-info's title changed.
*/
virtual void setTitleModified();
/**
* @return true if the document is empty.
*/
virtual bool isEmpty() const { return m_bEmpty; }
/**
* @brief Sets the document to empty.
*
* Used after loading a template
* (which is not empty, but not the user's input).
*
* @see isEmpty()
*/
virtual void setEmpty() { m_bEmpty = true; }
/**
* @brief Loads a document from a store.
*
* You should never have to reimplement.
*
* @param store The store to load from
* @param url An internal url, like tar:/1/2
*/
virtual bool loadFromStore( KoStore* store, const TQString& url );
/**
* @brief Loads an OASIS document from a store.
* This is used for both the main document and embedded objects.
*/
virtual bool loadOasisFromStore( KoStore* store );
/**
* @brief Saves a document to a store.
*
* You should not have to reimplement this - but call it in saveChildren().
*/
virtual bool saveToStore( KoStore* store, const TQString& path );
/**
* Reimplement this method to load the contents of your %KOffice document,
* from the XML document. This is for the pre-Oasis file format (maindoc.xml).
*
* You are supposed to use the TQDomDocument. The TQIODevice is provided only
* for the cases where some pre-processing is needed, like kpresenter's kprconverter.
* Note that the TQIODevice could be 0L, when called from an import filter.
*/
virtual bool loadXML( TQIODevice *, const TQDomDocument & doc ) = 0;
/**
* Reimplement this method to load the contents of your %KOffice document,
* from the XML document ("content.xml"). The styles have been parsed already,
* you can find them in the oasisStyles parameter. The store can be used
* to load images and embedded documents.
*/
virtual bool loadOasis( const TQDomDocument & doc, KoOasisStyles& oasisStyles,
const TQDomDocument & settings, KoStore* store ) = 0;
/**
* Reimplement this method to save the contents of your %KOffice document,
* using the OASIS format.
*/
virtual bool saveOasis( KoStore* store, KoXmlWriter* manifestWriter ) = 0;
/**
* Reimplement this to save the contents of the %KOffice document into
* a TQDomDocument. The framework takes care of saving it to the store.
*/
virtual TQDomDocument saveXML();
/**
* Return a correctly created TQDomDocument for this KoDocument,
* including processing instruction, complete DOCTYPE tag (with systemId and publicId), and root element.
* @param tagName the name of the tag for the root element
* @param version the DTD version (usually the application's version).
* @deprecated use createOasisXmlWriter instead
*/
TQDomDocument createDomDocument( const TQString& tagName, const TQString& version ) const;
/**
* Return an XML writer for saving Oasis XML into the device @p dev,
* including the XML processing instruction,
* and the root element with all its namespaces.
* You can add more namespaces afterwards with addAttribute.
*
* @param dev the device into which the XML will be written.
* @param rootElementName the tag name of the root element.
* This is either office:document, office:document-content,
* office:document-styles, office:document-meta or office:document-settings
* @return the KoXmlWriter instance. It becomes owned by the caller, which
* must delete it at some point.
*
* Once done with writing the contents of the root element, you
* will need to call endElement(); endDocument(); before destroying the KoXmlWriter.
* @note OASIS-specific
*/
static KoXmlWriter* createOasisXmlWriter( TQIODevice* dev, const char* rootElementName );
/**
* Return a correctly created TQDomDocument for an old (1.3-style) %KOffice document,
* including processing instruction, complete DOCTYPE tag (with systemId and publicId), and root element.
* This static method can be used e.g. by filters.
* @param appName the app's instance name, e.g. kword, kspread, kpresenter etc.
* @param tagName the name of the tag for the root element, e.g. DOC for kword/kpresenter.
* @param version the DTD version (usually the application's version).
*/
static TQDomDocument createDomDocument( const TQString& appName, const TQString& tagName, const TQString& version );
/**
* The first thing to do in loadOasis is get hold of the office:body tag, then its child.
* If the child isn't the expected one, the error message can indicate what it is instead.
* This method returns a translated name for the type of document,
* e.g. i18n("Word Processing") for office:text.
*/
static TQString tagNameToDocumentType( const TQString& localName );
/**
* Save the document. The default implementation is to call
* saveXML(). This method exists only for applications that
* don't use TQDomDocument for saving, i.e. kword and kpresenter.
*/
virtual bool saveToStream( TQIODevice * dev );
/**
* Loads a document in the native format from a given URL.
* Reimplement if your native format isn't XML.
*
* @param file the file to load - usually KReadOnlyPart::m_file or the result of a filter
*/
virtual bool loadNativeFormat( const TQString & file );
/**
* Saves the document in native format, to a given file
* You should never have to reimplement.
* Made public for writing templates.
*/
virtual bool saveNativeFormat( const TQString & file );
/**
* Activate/deactivate/configure the autosave feature.
* @param delay in seconds, 0 to disable
*/
void setAutoSave( int delay );
/**
* Checks whether the document is currently in the process of autosaving
*/
bool isAutosaving() const;
/**
* Set whether the next openURL call should check for an auto-saved file
* and offer to open it. This is usually true, but can be turned off
* (e.g. for the preview module).
*/
void setCheckAutoSaveFile( bool b );
/**
* Set whether the next openURL call should show error message boxes in case
* of errors. This is usually the case, but e.g. not when generating thumbnail
* previews.
*/
void setAutoErrorHandlingEnabled( bool b );
/**
* Checks whether error message boxes should be shown.
* @since 1.3.1
*/
bool isAutoErrorHandlingEnabled() const;
/**
* Retrieve the default value for autosave in seconds.
* Called by the applications to use the correct default in their config
*/
static int defaultAutoSave() { return s_defaultAutoSave; }
/**
* @return the list of all children. Do not modify the
* returned list.
*/
const TQPtrList<KoDocumentChild>& children() const;
/**
* @return the KoDocumentChild associated with the given Document, but only if
* @p doc is a direct child of this document.
*
* This is a convenience function. You could get the same result
* by traversing the list returned by children().
*/
KoDocumentChild *child( KoDocument *doc );
/**
* @return the information concerning this document.
* @see KoDocumentInfo
*/
KoDocumentInfo *documentInfo() const;
void setViewBuildDocument( KoView *view, const TQDomDocument &doc );
TQDomDocument viewBuildDocument( KoView *view );
/**
* Appends the shell to the list of shells which show this
* document as their root document.
*
* This method is automatically called from KoMainWindow::setRootDocument,
* so you dont need to call it.
*/
virtual void addShell( KoMainWindow *shell );
/**
* Removes the shell from the list. That happens automatically if the shell changes its
* root document. Usually you dont need to call this method.
*/
virtual void removeShell( KoMainWindow *shell );
/**
* @return the list of shells for the main window
*/
const TQPtrList<KoMainWindow>& shells() const;
/**
* @return the number of shells for the main window
*/
int shellCount() const;
/**
* @return the list of all the currently opened documents
*/
static TQPtrList<KoDocument> *documentList() { return s_documentList; }
/**
* @brief Return a DCOP interface for this document
*
* %KOffice parts are strongly recommended to reimplement this method,
* so that their DCOP interface provides more functionality than the basic KoDocumentIface
*/
virtual DCOPObject * dcopObject();
/**
* @return the ID of the DCOP interface for this document.
**/
TQCString dcopObjectId() const;
/**
* Signal the progress of operations such as loading or saving.
*/
void emitProgress( int value ) { emit sigProgress( value ); }
bool isInOperation() const;
virtual void emitBeginOperation();
virtual void emitEndOperation();
/**
* Return true if url() is a real filename, false if url() is
* an internal url in the store, like "tar:/..."
*/
virtual bool isStoredExtern() const;
/**
* @return the page layout associated with this document (margins, pageSize, etc).
* Override this if you want to provide different sized pages.
*
* @see KoPageLayout
*/
virtual KoPageLayout pageLayout(int pageNumber = 0) const;
/**
* Performs a cleanup of unneeded backup files
*/
void removeAutoSaveFiles();
void setBackupFile( bool _b );
bool backupFile()const;
/**
* Returns true if this document or any of its internal child documents are modified.
*/
bool isModified() const;
/**
* Returns true during loading (openURL can be asynchronous)
*/
bool isLoading() const;
int queryCloseExternalChildren();
int queryCloseDia();
/**
* @brief Set when we do not want to save external children when saving our 'main' doc.
*
* This makes it possible to save 'main' doc + all its internal children first, then
* go on to save external children. Typically used by query close.
* Use:
* @code
* doc->setDoNotSaveExtDoc();
* doc->save(); // saves doc and its internal children,
* //also calls saveExternalChildren() which sets setDoNotSaveExtDoc(false)
* doc->saveExternalChildren();
* @endcode
*/
void setDoNotSaveExtDoc( bool on = true );
/**
* Sets the backup path of the document
*/
void setBackupPath( const TQString & _path );
/**
* @return path to the backup document
*/
TQString backupPath()const;
/**
* Indicates that this document is currently viewed
* and thus should control the title caption.
* Also resets current flag for all parents.
*/
void setCurrent( bool on = true );
/**
* Sets current flag for this document and all its parents
*/
void forceCurrent( bool on );
bool isCurrent() const;
void setTitleModified( const TQString caption, bool mod );
/**
* Sets the document URL to empty URL
* KParts doesn't allow this, but %KOffice apps have e.g. templates
* After using loadNativeFormat on a template, one wants
* to set the url to KURL()
*/
void resetURL() { m_url = KURL(); m_file = TQString(); }
/**
* Set when you want an external embedded document to be stored internally
*/
void setStoreInternal( bool i );
/**
* @return true when external embedded documents are stored internally
*/
bool storeInternal() const;
bool hasExternURL() const;
/**
* Sets the document URL to @p url
* KParts doesn't really allow this, but it is needed for undo of setStoreInternal()
*/
void setURL( const KURL& url ) { m_url = url; }
/**
* _Only_ use these functions to restore m_file (in KoMainWindow) after a
* failed save (remember to use setURL() to restore the URL as well).
*
* @warning Do _not_ use these functions for any other purpose.
*
* @internal
*/
TQString &file() { return m_file; }
/**
* _Only_ use these functions to restore m_file (in KoMainWindow) after a
* failed save (remember to use setURL() to restore the URL as well).
*
* @warning Do _not_ use these functions for any other purpose.
*
* @internal
*/
void setFile( const TQString &file ) { m_file = file; }
/**
* @internal (public for KoMainWindow)
*/
void setMimeTypeAfterLoading( const TQString& mimeType );
/**
* @return returns the number of pages in the document.
*/
virtual int pageCount() const { return 1; }
/**
* @return all kotext-based text objects in the document
* This is used by some text-analyzer plugins.
* @since 1.5
*/
virtual TQValueList<KoTextDocument *> allTextDocuments() const;
/**
* Returns the unit used to display all measures/distances.
* @since 1.5
*/
KoUnit::Unit unit() const;
/**
* Sets the unit used to display all measures/distances.
* @since 1.5
*/
void setUnit( KoUnit::Unit u );
/**
* Returns the name of the unit used to display all measures/distances.
* Use this method for displaying it in the user interface, but use
* unit() for everything else (conversions etc.)
* @since 1.5
*/
TQString unitName() const;
/**
* Set the template type used. This is used by the start up widget to show
* the correct templates.
* @since 1.5
*/
void setTemplateType(const TQString& _templateType);
/**
* Template type used. This is used by the start up widget to show
* the correct templates.
* @since 1.5
*/
TQString templateType() const;
/**
* Shows the init dialog when embeding
* @param parent the parent widget
* @since 1.5
*/
virtual bool showEmbedInitDialog(TQWidget* parent);
public slots:
/**
* Initialize an empty document using default values
* @since 1.5
*/
virtual void initEmpty();
signals:
/**
* This signal is emitted when the unit is changed by setUnit()
* It is common to connect views to it, in order to change the displayed units
* (e.g. in the rulers)
*/
void unitChanged(KoUnit::Unit);
/**
* This signal is emitted when a direct or indirect child document changes
* and needs to be updated in all views.
*
* If one of your child documents emits the childChanged signal, then you may
* usually just want to redraw this child. In this case you can ignore the parameter
* passed by the signal.
*/
void childChanged( KoDocumentChild *child );
/**
* Progress info while loading or saving. The value is in percents (i.e. a number between 0 and 100)
* Your KoDocument-derived class should emit the signal now and then during load/save.
* KoMainWindow will take care of displaying a progress bar automatically.
*/
void sigProgress( int value );
/**
* Emitted e.g. at the beginning of a save operation
* This is emitted by KoDocument and used by KoView to display a statusbar message
*/
void sigStatusBarMessage( const TQString& text );
/**
* Emitted e.g. at the end of a save operation
* This is emitted by KoDocument and used by KoView to clear the statusbar message
*/
void sigClearStatusBarMessage();
void sigBeginOperation();
void sigEndOperation();
/**
* Emitted when the document is modified
*/
void modified( bool );
void closeEmbedInitDialog();
protected slots:
/**
* This slot loads an existing file and deletes the start up widget.
* @param file the file to load (including path)
* @since 1.5
*/
virtual void openExistingFile( const TQString& file );
/**
* This slot loads a template and deletes the start up widget.
* @param file the template to load
* @since 1.5
*/
virtual void openTemplate( const TQString& file );
void deleteOpenPaneDelayed();
protected:
TQString autoSaveFile( const TQString & path ) const;
virtual KoView *createViewInstance( TQWidget *parent, const char *name ) = 0;
/**
* Loads a document from KReadOnlyPart::m_file (KParts takes care of downloading
* remote documents).
* Applies a filter if necessary, and calls loadNativeFormat in any case
* You should not have to reimplement, except for very special cases.
*
* This method is called from the KReadOnlyPart::openURL method.
*/
virtual bool openFile();
/**
* Saves a document to KReadOnlyPart::m_file (KParts takes care of uploading
* remote documents)
* Applies a filter if necessary, and calls saveNativeFormat in any case
* You should not have to reimplement, except for very special cases.
*/
virtual bool saveFile();
/**
* Override this method in your derived class to show a widget in the startup 'dialog'.
* This widget should allow the user to set settings for a custom document (i.e. one
* not based on a template).
* The returned widget should provide its own button (preferrably 'Create') and
* implement the logic to implement the document instance correctly.
* After initializing the widget should emit a signal called 'documentSelected()' which
* will remove the startupWidget and show the document.
* @param parent the parent of the to be created widget.
*/
virtual TQWidget* createCustomDocumentWidget(TQWidget *parent);
/**
* OLD XML method. For OASIS just call KoDocumentChild::loadOasisDocument
* after KoDocumentChild::loadOasis.
*
* You need to overload this function if your document may contain
* embedded documents. This function is called to load embedded documents.
*
* An example implementation may look like this:
* @code
* TQPtrListIterator<KoDocumentChild> it( children() );
* for( ; it.current(); ++it )
* {
* if ( !it.current()->loadDocument( _store ) )
* {
* return false;
* }
* }
* return true;
* @endcode
*/
virtual bool loadChildren( KoStore* );
/**
* Saves all internal children (only!).
* @see saveExternalChildren if you have external children.
* Returns true on success.
*/
virtual bool saveChildren( KoStore* store );
/**
* Saves all internal children (only!), to the store, using the OASIS format.
* This is called automatically during saveNativeFormat.
* @see saveExternalChildren if you have external children.
* Returns true on success.
*/
virtual bool saveChildrenOasis( KoStore* store, KoXmlWriter* manifestWriter );
/**
* Overload this function if you have to load additional files
* from a store. This function is called after loadXML()
* and after loadChildren() have been called.
*/
virtual bool completeLoading( KoStore* store );
/**
* If you want to write additional files to a store,
* then you must do it here.
* In the implementation, you should prepend the document
* url (using url().url()) before the filename, so that everything is kept relative
* to this document. For instance it will produce urls such as
* tar:/1/pictures/picture0.png, if the doc url is tar:/1
* But do this ONLY if the document is not stored extern (see isStoredExtern() ).
* If it is, then the pictures should be saved to tar:/pictures.
*/
virtual bool completeSaving( KoStore* store );
/**
* Inserts the new child in the list of children and emits the
* childChanged() signal.
*
* At the same time this method marks this document as modified.
*
* To remove a child, just delete it. KoDocument will detect this
* and remove the child from its lists.
*
* @see #isModified
*/
virtual void insertChild( KoDocumentChild *child );
/** @internal */
virtual void setModified() { KParts::ReadWritePart::setModified(); }
/** @internal */
virtual void insertChild(TQObject *o) { TQObject::insertChild(o); }
KoPageLayout m_pageLayout;
/**
* Saves all externally stored children.
* Returns true on success.
* @see #saveChildren for internal children
*/
virtual bool saveExternalChildren();
/**
* Returns whether or not the current openURL() or openFile() call is
* actually an import operation (like File --> Import).
* This is for informational purposes only.
*/
bool isImporting() const;
/**
* Returns whether or not the current saveFile() call is actually an export
* operation (like File --> Export).
* If this function returns true during saveFile() and you are changing
* some sort of state, you _must_ restore it before the end of saveFile();
* otherwise, File --> Export will not work properly.
*/
bool isExporting() const;
/**
* Creates the open widget showed at application start up.
* @param parent the parent widget
* @param instance the KInstance to be used for KConfig data
* @param templateType the template-type (group) that should be selected on creation.
* @since 1.5
*/
KoOpenPane* createOpenPane( TQWidget* parent, KInstance* instance,
const TQString& templateType = TQString());
private slots:
void slotChildChanged( KoChild *c );
void slotChildDestroyed();
void slotAutoSave();
void slotStarted( KIO::Job* );
void startCustomDocument();
/**
* Removes the open widget showed at application start up.
* @since 1.5
*/
void deleteOpenPane();
private:
KService::Ptr nativeService();
bool oldLoadAndParse( KoStore* store, const TQString& filename, TQDomDocument& doc );
bool loadNativeFormatFromStore( const TQString& file );
bool savePreview( KoStore* store );
bool saveOasisPreview( KoStore* store, KoXmlWriter* manifestWriter );
class Private;
Private *d;
KService::Ptr m_nativeService;
bool m_bEmpty;
static TQPtrList<KoDocument> *s_documentList;
static const int s_defaultAutoSave;
};
#endif