/*

* 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