1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/textandloc/textrendering/textformatting/inc/unified_editor.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,314 @@
1.4 +/*
1.5 +* Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +
1.23 +
1.24 +#ifndef __UNIFIED_EDITOR_H__
1.25 +#define __UNIFIED_EDITOR_H__ 1
1.26 +
1.27 +#include <tagma.h>
1.28 +
1.29 +#ifdef SYMBIAN_ENABLE_SPLIT_HEADERS
1.30 +#include <tagma_internal.h>
1.31 +#endif
1.32 +
1.33 +/*
1.34 +The header file for MUnifiedEditor, an interface that unifies editing operations on backing text and layout,
1.35 +which are traditionally separated between ETEXT (backing text) and FORM (layout). It is not dependent
1.36 +on FORM or ETEXT, although there is an implementation (TFormAndTextEditor) using those components.
1.37 +*/
1.38 +
1.39 +/**
1.40 +Base class for optional interfaces
1.41 +@internalComponent
1.42 +*/
1.43 +class MTmOptionalInterface
1.44 +
1.45 + {
1.46 + };
1.47 +
1.48 +/**
1.49 +UIDs for standard optional interfaces
1.50 +@internalComponent
1.51 +*/
1.52 +const TUint KUidMUnifiedEditorStyleSupport = 0x100092B6;
1.53 +const TUint KUidMUnifiedEditorPictureSupport = 0x100092B7;
1.54 +const TUint KUidMUnifiedEditorFieldSupport = 0x100092B8;
1.55 +const TUint KUidMUnifiedEditorClipboardSupport = 0x100095EF;
1.56 +
1.57 +/**
1.58 +An interface class for text editing.
1.59 +
1.60 +An object that supports text editing has some backing text - zero or more Unicode characters - and
1.61 +character and paragraph formats applicable to ranges of these characters. A paragraph is a sequence of characters
1.62 +terminating either at the end of the document or after the next paragraph separator, whichever comes first.
1.63 +
1.64 +The format for a given position is derived from up to three formatting layers. The base layer is the lowest and
1.65 +provides default attributes. These may be optionally overridden by attributes from a named style, and these in
1.66 +turn may be overridden by specific formatting. Text editing objects may support any or none of these layers; they
1.67 +may in fact ignore all attempts to set format attributes.
1.68 +@internalComponent
1.69 +*/
1.70 +class MUnifiedEditor
1.71 +
1.72 + {
1.73 +public:
1.74 + /**
1.75 + * constants used when getting formats
1.76 + */
1.77 + enum TFormatLevel
1.78 + {
1.79 + ESpecific, // format applied by the user
1.80 + EEffective // the actual format: a combination of base and specific formats
1.81 + };
1.82 + class MStyleSupport : public MTmOptionalInterface
1.83 + /**
1.84 + An optional interface to support styles
1.85 + @internalComponent
1.86 + */
1.87 + {
1.88 + public:
1.89 + /**
1.90 + * Creates a style.
1.91 + */
1.92 + virtual TInt CreateStyleL(const RTmStyle& /*aStyle*/) { return KErrNotSupported; }
1.93 + /**
1.94 + * Sets the attributes of a style.
1.95 + */
1.96 + virtual TInt ChangeStyleL(const RTmStyle& /*aStyle*/) { return KErrNotSupported; }
1.97 + /**
1.98 + * Applies the named style to the specified run of text.
1.99 + */
1.100 + virtual TInt SetStyleL(TInt aPos, TInt aLength, const TDesC& aName) = 0;
1.101 + /**
1.102 + * Renames a style.
1.103 + */
1.104 + virtual TInt RenameStyleL(const TDesC& /*aOldName*/,const TDesC& /*aNewName*/) { return KErrNotSupported; }
1.105 + /**
1.106 + * Deletes the named style.
1.107 + */
1.108 + virtual TInt DeleteStyleL(const TDesC& /*aName*/) { return KErrNotSupported; }
1.109 + /**
1.110 + * Get the number of named styles.
1.111 + */
1.112 + virtual TInt StyleCount() const = 0;
1.113 + /**
1.114 + * Gets the style set at the document position aPos. If no style is set
1.115 + * there return an empty string and the run length over which no style
1.116 + * applies.
1.117 + */
1.118 + virtual void GetStyle(TInt aPos, TPtrC& aName, TInt& aRunLength) const = 0;
1.119 + /**
1.120 + * Gets the attributes of a named style by completing aStyle from its
1.121 + * name.
1.122 + */
1.123 + virtual TInt GetStyleByNameL(const TDesC& aName, RTmStyle& aStyle) const = 0;
1.124 + /**
1.125 + * Gets the name and attributes of a style by index; use this in
1.126 + * conjunction with StyleCount to enumerate existing styles.
1.127 + */
1.128 + virtual TInt GetStyleByIndexL(TInt aIndex, RTmStyle& aStyle) const = 0;
1.129 + };
1.130 +
1.131 + /**
1.132 + An optional interface to support embedded pictures
1.133 + @internalComponent
1.134 + */
1.135 + class MPictureSupport : public MTmOptionalInterface
1.136 +
1.137 + {
1.138 + public:
1.139 + /**
1.140 + * Inserts a picture, passing ownership in.
1.141 + */
1.142 + virtual void InsertPictureL(TInt aPos, const TPictureHeader& aPictureIn) = 0;
1.143 + /**
1.144 + * Deletes picture character in the text at aPos, if any. Ownership of
1.145 + * any picture is passed to the caller, therefore Picture(aPos,
1.146 + * aPictureOut) must have been called previously, and
1.147 + * aPictureOut.DeletePicture() must be called in the future to avoid a
1.148 + * memory leak.
1.149 + * If the character at aPos is a picture character, it will be deleted,
1.150 + * regardless of whether or not a picture was actually attatched.
1.151 + */
1.152 + virtual void DropPictureL(TInt aPos) = 0;
1.153 + /**
1.154 + * Gets the picture if any at aPos. No picture is indicated by
1.155 + * aPictureOut.iPictureType containing KUidNull.
1.156 + * Ownership of the picture is retained. Note that aPictureOut is
1.157 + * merely overwritten by this function: aPictureOut.DeletePicture() is
1.158 + * NOT called!
1.159 + */
1.160 + virtual void Picture(TInt aPos, TPictureHeader& aPictureOut) const = 0;
1.161 + };
1.162 +
1.163 + /**
1.164 + An optional interface to support clipboard operations
1.165 + @internalComponent
1.166 + */
1.167 + class MClipboardSupport : public MTmOptionalInterface
1.168 +
1.169 + {
1.170 + public:
1.171 + /**
1.172 + * Copy the text and formatting specified to the stream, updating
1.173 + * the dictionary as appropriate.
1.174 + */
1.175 + virtual void CopyToStoreL(CStreamStore& aStore, CStreamDictionary& aDictionary,
1.176 + TInt aPos, TInt aLength) const = 0;
1.177 + /**
1.178 + * Insert text and formatting from the stream at aPos.
1.179 + */
1.180 + virtual void PasteFromStoreL(const CStreamStore& aStore,
1.181 + const CStreamDictionary& aDictionary, TInt aPos) = 0;
1.182 + };
1.183 +
1.184 + // VIRTUAL FUNCTIONS
1.185 +
1.186 + // getters
1.187 +
1.188 + /**
1.189 + * Returns the optional interface with the specified UID, or 0 if it is not
1.190 + * supported.
1.191 + */
1.192 + virtual MTmOptionalInterface* Interface(TUint /*aId*/) { return NULL; }
1.193 + /**
1.194 + * Returns the length of the document in characters, not including any
1.195 + * notional final paragraph separator.
1.196 + */
1.197 + virtual TInt DocumentLength() const = 0;
1.198 + /**
1.199 + * Gets some text starting at aPos. The amount of text returned may be as
1.200 + * much or as little as is convenient to the implementation, but must be
1.201 + * at least one character. The text is raw Unicode text including any
1.202 + * paragraph separators.
1.203 + */
1.204 + virtual void GetText(TInt aPos,TPtrC& aText) const = 0;
1.205 + /**
1.206 + * Gets the base character and paragraph formats
1.207 + */
1.208 + virtual void GetBaseFormatL(TTmCharFormat& aCharFormat,RTmParFormat& aParFormat) const = 0;
1.209 + /**
1.210 + * Gets the specific or effective character format and the run over which
1.211 + * that format applies.
1.212 + */
1.213 + virtual void GetCharFormat(TInt aPos,TFormatLevel aLevel,
1.214 + TTmCharFormatLayer& aFormat,TInt& aRunLength) const = 0;
1.215 + /**
1.216 + * Gets the specific or effective paragraph format and the run over which
1.217 + * that format applies.
1.218 + */
1.219 + virtual void GetParFormatL(TInt aPos,TFormatLevel aLevel,
1.220 + RTmParFormatLayer& aFormat,TInt& aRunLength) const = 0;
1.221 +
1.222 + // setters
1.223 +
1.224 + /**
1.225 + * Inserts text at aPos, optionally applying the specified character and
1.226 + * paragraph formats. Unspecified attributes take the format at the
1.227 + * insertion point; what this means in detail is implementation-dependent.
1.228 + */
1.229 + virtual void InsertTextL(TInt aPos,const TDesC& aText,
1.230 + const TDesC* aStyle = NULL,
1.231 + const TTmCharFormatLayer* aCharFormat = NULL,
1.232 + const RTmParFormatLayer* aParFormat = NULL) = 0;
1.233 + /**
1.234 + * Deletes aLength characters starting at aPos.
1.235 + */
1.236 + virtual void DeleteTextL(TInt aPos,TInt aLength) = 0;
1.237 + /**
1.238 + * Sets the base character and paragraph formats
1.239 + */
1.240 + virtual void SetBaseFormatL(const TTmCharFormat& aCharFormat,const RTmParFormat& aParFormat) = 0;
1.241 + /**
1.242 + * Sets specific character attributes beginning at aPos for aLength characters.
1.243 + */
1.244 + virtual void SetCharFormatL(TInt aPos,TInt aLength,const TTmCharFormatLayer& aFormat) = 0;
1.245 + /**
1.246 + * Sets specific paragraph attributes beginning at aPos for aLength characters.
1.247 + */
1.248 + virtual void SetParFormatL(TInt aPos,TInt aLength,const RTmParFormatLayer& aFormat) = 0;
1.249 + /**
1.250 + * Deletes specific character attributes beginning at aPos for aLength characters.
1.251 + */
1.252 + virtual void DeleteCharFormatL(TInt aPos,TInt aLength) = 0;
1.253 + /**
1.254 + * Deletes specific paragraph attributes beginning at aPos for aLength characters.
1.255 + */
1.256 + virtual void DeleteParFormatL(TInt aPos,TInt aLength) = 0;
1.257 +
1.258 + // NON-VIRTUAL FUNCTIONS
1.259 + /**
1.260 + * Reads text into a writable descriptor.
1.261 + *
1.262 + * @see GetText(TInt, TPtrC) const
1.263 + */
1.264 + IMPORT_C void GetText(TInt aPos, TDes& aText) const;
1.265 + /**
1.266 + * Returns the interface for manipulating styles, if applicable.
1.267 + */
1.268 + inline MStyleSupport* StyleSupport();
1.269 + inline const MStyleSupport* StyleSupport() const;
1.270 + /**
1.271 + * Returns the interface for manipulating pictures, if applicable.
1.272 + */
1.273 + inline MPictureSupport* PictureSupport();
1.274 + inline const MPictureSupport* PictureSupport() const;
1.275 + /**
1.276 + * Returns the interface for clipboard operations, if applicable.
1.277 + */
1.278 + inline MClipboardSupport* ClipboardSupport();
1.279 + inline const MClipboardSupport* ClipboardSupport() const;
1.280 + };
1.281 +
1.282 +// inline functions
1.283 +
1.284 +MUnifiedEditor::MStyleSupport* MUnifiedEditor::StyleSupport()
1.285 + {
1.286 + return static_cast<MStyleSupport*>(Interface(KUidMUnifiedEditorStyleSupport));
1.287 + }
1.288 +
1.289 +const MUnifiedEditor::MStyleSupport* MUnifiedEditor::StyleSupport() const
1.290 + {
1.291 + return static_cast<MStyleSupport*>(
1.292 + const_cast<MUnifiedEditor*>(this)->Interface(KUidMUnifiedEditorStyleSupport));
1.293 + }
1.294 +
1.295 +MUnifiedEditor::MPictureSupport* MUnifiedEditor::PictureSupport()
1.296 + {
1.297 + return static_cast<MPictureSupport*>(Interface(KUidMUnifiedEditorPictureSupport));
1.298 + }
1.299 +
1.300 +const MUnifiedEditor::MPictureSupport* MUnifiedEditor::PictureSupport() const
1.301 + {
1.302 + return static_cast<MPictureSupport*>(
1.303 + const_cast<MUnifiedEditor*>(this)->Interface(KUidMUnifiedEditorPictureSupport));
1.304 + }
1.305 +
1.306 +MUnifiedEditor::MClipboardSupport* MUnifiedEditor::ClipboardSupport()
1.307 + {
1.308 + return static_cast<MClipboardSupport*>(Interface(KUidMUnifiedEditorClipboardSupport));
1.309 + }
1.310 +
1.311 +const MUnifiedEditor::MClipboardSupport* MUnifiedEditor::ClipboardSupport() const
1.312 + {
1.313 + return static_cast<MClipboardSupport*>(
1.314 + const_cast<MUnifiedEditor*>(this)->Interface(KUidMUnifiedEditorClipboardSupport));
1.315 + }
1.316 +
1.317 +#endif // __UNIFIED_EDITOR_H__