--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/uiaccelerator_plat/alf_visual_api/inc/alf/alfplaintexteditorcontrol.h Tue Feb 02 07:56:43 2010 +0200
@@ -0,0 +1,443 @@
+/*
+* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Concrete editor control for plain (descriptor content) text
+*
+*/
+
+
+
+#ifndef C_ALFPLAINTEXTEDITORCONTROL_H
+#define C_ALFPLAINTEXTEDITORCONTROL_H
+
+#include <e32base.h>
+#include <alf/alfcontrol.h>
+#include <alf/alfeditorcontrol.h>
+#include <eikon.hrh> // For Avkon key mappings
+
+/* Forward declarations. */
+class CAlfTextEditorVisualization;
+class CAlfTextSource;
+class CAlfEditorPlainTextModifier;
+class CRichText;
+class CAlfTextEditorFunctionalState;
+
+/**
+ * CAlfPlainTextEditorControl provides un-marked up text editing
+ *
+ * Usage:
+ * @code
+ * //Create editor control
+ * CAlfPlainTextEditorControl* control = new (ELeave) CAlfPlainTextEditorControl;
+ * control->ConstructL( *iEnv );
+ * control->SetMaximumTextLength( KTestMaximumTextLength );
+ *
+ * //Read entered text
+ * HBufC* readText = control->GetTextInHBufL();
+ *
+ * //Access plain text buffer
+ * CPlainText& text = control->Text();
+ * TPtrC readText = text.Read(control->TextLength());
+ *
+ * @endcode
+ * @lib alfclient.lib
+ * @since S60 3.2
+ */
+NONSHARABLE_CLASS(CAlfPlainTextEditorControl) : public CAlfEditorControl
+ {
+
+public:
+
+ /** @beginAPI */
+
+ /**
+ * Statically creates in instance of this class
+ *
+ * @param aEnv Alfred environment object
+ * @return a fully-constructed instance
+ */
+ IMPORT_C static CAlfPlainTextEditorControl* NewL(CAlfEnv& aEnv);
+
+ /**
+ * Constructor.
+ *
+ */
+ CAlfPlainTextEditorControl();
+
+ /**
+ * 2nd stage constructor
+ *
+ * @param aEnv The Alf Environment
+ */
+ void ConstructL(CAlfEnv& aEnv);
+
+ /**
+ * Destructor.
+ */
+ virtual ~CAlfPlainTextEditorControl();
+
+public: // From CAlfControl
+
+ /**
+ * Called when the control's focus state changes.
+ *
+ * @param aDisplay The display where this control is changing focus
+ * @param aFocused EFalse iff losing focus.
+ */
+ void FocusChanged( CAlfDisplay& aDisplay, TBool aFocused );
+
+ /**
+ * Called when an input event is being offered to the control.
+ *
+ * @param aEvent Event to be handled.
+ *
+ * @return <code>ETrue</code>, if the event was handled.
+ * Otherwise <code>EFalse</code>.
+ */
+ virtual TBool OfferEventL( const TAlfEvent& aEvent );
+
+ /**
+ * Notifies the control that its visible has been changed on a display.
+ * This is the earliest time when the control knows the dimensions of
+ * the display it is being shown on.
+ *
+ * @param aIsVisible ETrue, if the control is now visible on the display.
+ * EFalse, if the control is about to the hidden on the display.
+ * @param aDisplay The display on which the control's visibility is changing.
+ */
+ virtual void NotifyControlVisibility(
+ TBool aIsVisible,
+ CAlfDisplay& aDisplay );
+
+public: // From MVisualOwner:
+
+ virtual void VisualLayoutUpdated(CAlfVisual& aVisual);
+
+public: // From CAlfEditorControl
+
+ virtual void VisualizeL( CAlfLayout* aParentLayout );
+
+ public: // New Methods
+
+ /**
+ * Copy a descriptor into the editor as the current text.
+ * Note this method is not suitable for long texts since a copy of the text is made.
+ *
+ * @param aText Text descriptor to be copied in
+ */
+ IMPORT_C void SetTextL( const TDesC& aText );
+
+ /**
+ * Transfer to the caller ownership of newly constructed copy of the text.
+ * Note that this method is not recommended for long texts.
+ *
+ * The returned buffer will have have length TextLength() and will not have an appended paragraph marker.
+ *
+ * @return A newly instantiated copy of the text in the editor. Owned by the caller.
+ */
+ IMPORT_C HBufC* GetTextInHBufL() const;
+
+ /**
+ * Access the plain text buffer
+ *
+ * The CPlainText object will always have an end of paragraph mark (0x2029) appended. This will be at character index
+ * TextLength().
+ * @see TextLength()
+ *
+ * @return a reference to a CPlainText object containing the document.. No ownership is transferred.
+ */
+ IMPORT_C CPlainText& Text() const;
+
+ /**
+ * Access the current text length.
+ *
+ * The returned value does not count the end of paragraph mark ( 0x2029 ) which is found ad the end of the CPlainText object.
+ *
+ * @return The length of the text
+ */
+ IMPORT_C TInt TextLength() const;
+
+ /**
+ * Sets the maximum text length.
+ *
+ * This method will panic if the passed-in value is greater than the current TextLength()
+ *
+ * @param maximum allowed length of text
+ */
+ IMPORT_C void SetMaximumTextLength( TInt aMaxTextLength );
+
+ /**
+ * Access the maximum text length
+ *
+ * @return maximum allowed length of text
+ */
+ IMPORT_C TInt MaximumTextLength() const;
+
+ /**
+ * Set the current input position within the document. It is possible to set both the pending input position (cursor position)
+ * in logical order, and to set to which run of text that cursor should be associated with.
+ *
+ * In the following, the terms "next", "previous", "after" and "before" all refer to the logical ordering of characters in the text
+ * buffer. The terms "left" and "right" refer to visual positioning.
+ *
+ * The valid range for the position is 0 to TextLength(), inclusive. A value of TextLength() indicates the cursor is positioned after
+ * the last character. The value of the cursor position can be though of as a "gap number", where the first gap is that before
+ * character 0, and the last gap is that after TextLength(). Another way of thinking of this is the cursor position represents
+ * the 0-based index of a character that would be input at that point. More simply, it can be thought of as sharing an
+ * index value with the next character in the buffer.
+ *
+ * The leading flag can be used to associate the cursor visually with the next character in logical order (aLeading = ETrue)
+ * or with the previous character in logical order. This has an effect visually, if the previous and next characters are in runs of
+ * text with different directionality. If a cursor is at ( N, Trailing ), and character at index N-1 is in a left-to-right (L-R) run of text,
+ * then the cursor will be displayed to the right of character N-1. This would be the default for a cursor at the end of a run of
+ * L-R text. However, if the cursor is set to ( N, Leading ) and the character at index N is in a right-to-left (R-L) text run, then
+ * the cursor will adhere to that block and be positioned to the right side of character N. Note that this cursor position could
+ * potentially be at some distance to the right from the (N, Trailing) visual position.
+ *
+ * Conversely if there is a run of R-L text followed (logically) by L-R text, and the curosr is positioned at N. (i.e. N is in the
+ * L-R text and N-1 is in the R-L). In this case, if the cursor is trailing, it trails character N-1, and therefore is
+ * positioned at the end (left side) of the R-L text - which is positioned visually between the runs of text. If the cursor is
+ * set to leading, then it leads character N, and is therefore at the left end of the L-R text, probably at the left end of the whole text.
+ *
+ * Note that the values of ( 0, Trailing ), and ( TextLength(), Leading ) are both legal, and behave as they are specified.
+ * SetCursorPos(0) is generally what one wants. It will cause the cursor to adhere to the end of text that is entered/pasted.
+ * SetCursorPos( MaxLength(), ETrue ) will generally behave the same as SetCursorPos( MaxLength(), EFalse) since there
+ * will still be no "next run" of text after input.
+ *
+ * @param a "gap number" in the document.
+ * @param aLeading = EFalse iff the cursor is to be associated visually to the previous character's run of text.
+ */
+ IMPORT_C void SetCursorPos( TInt aNewPosition, TBool aLeading = EFalse );
+
+ /**
+ * Gets the current input position within the document.
+ * @see SetCursorPos( TInt, TBool );
+ *
+ * @param returns the logical position of the cursor
+ * @param returns the leading/trailing flag
+ */
+ IMPORT_C void GetCursorPos( TInt& aPosition, TBool& aLeading );
+
+ /**
+ * Obtain the simple cursor position without leading/trailing information.
+ * This API is appropriate in many cases that the visual positioning of the cursor is not a concern.
+ * @see SetCursorPos( TInt, TBool );
+ *
+ * @return the gap number that the cursor is presently located in
+ */
+ IMPORT_C TInt CursorPos() const;
+
+ /**
+ * Set a selection on the editor contents. The selection is single contiguous range of indices with a
+ * starting cursor position (the "Anchor") and an end position (the "Cursor"). It thus has a directionality.
+ * The semantics of the selection is that it indicates what set of characters the next user input is going
+ * to affect. It is usually indicated to the user with a selection highlight. The ends of the selection may or
+ * may not be differentiated visually to the user.
+ *
+ * Both anchor and cursor follow the conventions of the the cursor in SetCursorPos.
+ * @see SetCursorPos( TInt, TBool )
+ * Note however, that the selected set of characters comprises those characters between the anchor and cursor.
+ * So if a selection is set at (M,N), and then the selection is deleted, the characters at indices M, M+1...N-1 will be deleted.
+ *
+ * The Set/GetCursorPos APIs interoperate with the selection-oriented APIs. The cursor position is merely the
+ * end point of the selection.
+ *
+ * Setting a zero length selection is the same as setting a (non-selection) cursor position. This action leaves the
+ * leading/trailing flag state of the cursor unchanged. If the editor client needs to zero the selection and also change the
+ * leading/trailing flag, he must first call SetSelection with zero length, and then call SetCursorPos, explicitly setting the
+ * leading/trailing flag.
+ *
+ * Setting a non-zero length selection does affect the leading trailing flag, according to the following rules:
+ * If aCursorPosition > aAnchorPosition, then the flag is set to Trailing.
+ * If aCursorPosition < aAnchorPosition, then the flag is set to Leading.
+ *
+ * Deletion or replacing the selection (by user activity or via the Text() interface leaves the leading trailing state
+ * unchanged
+ *
+ * @param aAnchorPosition Starting gap position of the selection
+ * @param aCursorPosition End gap position of the selection
+ */
+ IMPORT_C void SetSelection( TInt aAnchorPosition, TInt aCursorPosition );
+
+ /**
+ * Moves only the cursor position of the selection. The anchor position remains unchanged.
+ *
+ * @param the cursor position to move the end of the selection to.
+ */
+ IMPORT_C void ExtendSelection( TInt aNewCursorPosition );
+
+ /**
+ * Obtain the current selection.
+ * @see SetSelection( TInt, TInt );
+ *
+ * @param aAnchorPosition Returns the anchor gap number
+ * @param aCursorPosition Returns the cursor gap number
+ */
+ IMPORT_C void GetSelection( TInt& aAnchorPosition, TInt& aCursorPosition )const;
+
+ /**
+ * Sets permitted cases for the editor.
+ * Possible flags from @c uikon.hrh are @c EAknEditorAllCaseModes,
+ * @c EAknEditorUpperCase, @c EAknEditorLowerCase and
+ * @c EAknEditorTextCase.
+ * @c EAknEditorAllCaseModes is default.
+ *
+ * @param aPermittedCaseModes Case modes that are available in the editor.
+ */
+ IMPORT_C void SetPermittedCaseModes(TInt aPermittedCaseModes);
+
+ /**
+ * Sets default case for the editor. The case is used when the editor
+ * is focused first time. Available case flags from @c uikon.hrh
+ * are @c EAknEditorUpperCase, @c EAknEditorLowerCase and
+ * @c EAknEditorTextCase. @c EAknEditorTextCase is used if the initial
+ * case by default.
+ *
+ * @param aCase Initial case to be used in the editor.
+ */
+ IMPORT_C void SetDefaultCase(TInt aDefaultCase);
+
+ /**
+ * Updates editor case. FEP is automatically notified of the
+ * case change in editor state and FEP takes new case to use immediately.
+ * Available case flags from @c uikon.hrh are @c EAknEditorUpperCase,
+ * @c EAknEditorLowerCase and @c EAknEditorTextCase.
+ * This method should not be used to set initial case for the editor.
+ * Use @c SetAknEditorCase() method instead for setting initial case.
+ *
+ * @param aCase New case for the editor.
+ */
+ IMPORT_C void SetCurrentCase(TInt aCase);
+
+ /**
+ * Sets default input mode for the editor. The input mode is used when
+ * the editor is focused first time.
+ * @c EAknEditorTextInputMode is used if the initial input mode by default.
+ *
+ * @param aInputMode Initial input mode to be used in the editor.
+ */
+ IMPORT_C void SetDefaultInputMode( TInt aInputMode );
+
+ /**
+ * Updates editor input mode. FEP is automatically notified of the
+ * new input mode in editor state and FEP takes new input mode to use
+ * immediatelly. Current inline editing is reset.
+ * This method should not be used for setting initial input mode for the
+ * editor. Use @c SetAknEditorInputMode() method instead for setting
+ * initial input mode.
+ *
+ * @param aInputMode New input mode for the editor.
+ */
+ IMPORT_C void SetCurrentInputMode( TInt aInputMode );
+
+ /**
+ * Sets allowed input modes for the editor.
+ * All input modes are allowed (@c EAknEditorAllInputModes) if the value
+ * is not set from EDWIN resource @c allowed_input_modes or with this API.
+ *
+ * @param aInputModes Input modes that are allowed in the editor.
+ */
+ IMPORT_C void SetPermittedInputModes( TInt aInputModes );
+
+ /**
+ * Sets number mode key mapping for '*' and '#' keys. The key mapping is
+ * used in editors when numeric input mode is used. Key mapping characters
+ * for '*' key are shown on special character table if also text input
+ * modes are allowed in the editor but the current input mode is numeric
+ * mode. @c EAknEditorStandardNumberModeKeymap is used in editors that
+ * allow only numeric input if the mapping is not set from EDWIN resource
+ * @c numeric_keymap or with this API.
+ * @c EAknEditorAlphanumericNumberModeKeymap is used as default if the
+ * editor allows also text input mode.
+ *
+ * @param aNumericKeymap Key mapping used in an editor with number input
+ * mode.
+ */
+ IMPORT_C void SetNumericKeymap(
+ TAknEditorNumericKeymap aNumericKeymap);
+
+ /**
+ * Sets the @c EOnlyASCIIChars flag.
+ *
+ * @param aASCIIOnly If @c ETrue the EOnlyASCIIChars flag will be set. If
+ * @c EFalse the EOnlyASCIIChars flag will be removed.
+ */
+ IMPORT_C void SetOnlyASCIIChars( TBool aASCIIOnly );
+
+ /**
+ * Autoselection of text. When set, this initially sets the editor to have the cursor position
+ * at the end of the document with the selection's anchor at the beginning.
+ * That is, the whole text is selected.
+ *
+ * If cursor positioning at the end is desired, but with no auto-selection, then the flag
+ * EAutoCursorAtEndIndex should be used. But if selection is desired, then this flag only
+ * is needed.
+ *
+ * This setting is looked at whenever SetTextL is called and not just at initial display of the editor.
+ *
+ * @param aAutoSelection iff not EFalse, will cause autoselection
+ */
+ IMPORT_C void SetAutoSelection( TBool aAutoSelection );
+
+ /**
+ * Automatic setting of the cursor at the end of the document.
+ * If set, this initially sets the editor to have the cursor position at the end of the document,
+ * but with no selection.
+ *
+ * This setting is looked at whenever SetTextL is called and not just at initial display of the editor.
+ *
+ * @param aCursorAtEnd iff not EFalse, will cause auto-positioning of the cursor at the end of the document
+ */
+ IMPORT_C void SetInitialCursorAtEnd( TBool aCursorAtEnd );
+
+ /**
+ * Access method for visualizations to get at the non editor content state
+ * @return A pointer to a CAknEditorState object
+ */
+ CAlfTextEditorFunctionalState& State() const;
+
+ /**
+ * Set the text style for the text. The Id passed in is either a pre-allocated
+ * Alf text style ID or a derived ID using the TextStyleManager.
+ *
+ * @param aTextStyleId Alf platform-specifc text id
+ */
+ IMPORT_C void SetTextStyleId( TInt aTextStyleId );
+
+protected:
+
+private:
+
+ /**
+ * Create visuals for this editor in the given parent
+ */
+ void CreateVisualizationL( CAlfLayout* aParentLayout );
+
+ void SetSingleAknEditorFlagAndReportIfChanged( TInt aSingleFlag, TBool aNewValue );
+
+private:
+ // @todo Not properly BC-proofed
+ CAlfTextSource* iTextSource; // Owned
+ CAlfEditorPlainTextModifier* iTextModifier; // Owned
+ TInt iMaximumTextLength;
+ CAlfTextEditorVisualization* iTextVisualization; // Not Owned
+
+ // Functional flags:
+ CAlfTextEditorFunctionalState* iState;
+ // textStyleId to be passed to the visualization
+ TInt iTextStyleId;
+
+ TInt iSpare;
+ };
+
+#endif // C_ALFPLAINTEXTEDITORCONTROL_H