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