Editors API Specification

Changes in Editors API documentation

1.0 12.10.2006 Approved

Changes in Editors API

1.0 First release



Nearly every application involves displaying and processing data in text form. Many of these applications also allow the user to modify or produce new data as well. The family of editor controls provides the application designer a way to handle these needs in a uniform and efficient way. This document describes the API set to editor controls available for S60 on Symbian platform.

Because the limited input capabilities of smartphones, there are many aspects to be considered when compared to the usual editor components in modern desktop environments. The editor controls have been designed to be applied and customized to meet the specific text display and input needs of the application.

The document does not cover the full functionality of the powerful editor class CEikEdwin , which is the base to almost all editors. The API usage will be demonstrated through the most common use cases.



Classification and release information

Editors API is an SDK API and part of S60 3rd Edition, Feature Pack 1.

Editor types

The family of editor controls available is divided into four main categories, which represent different needs for text input, display, and manipulation. The categories are:

  • Text editors

  • Numeric editors

  • Secret editors

  • Multi-field numeric editors

These categories are described in more detail in the following sections.

Text editors

Text editors are editor controls containing text. They may allow only one or multiple lines of text to be entered. The most basic text editor controls support only unformatted text, but more specialized controls allow text to be formatted or — with the rich text editor — even object embedding.

Text editors can be further divided into three subcategories: plain text editors, global text editors, and rich text editors. A plain text editor (Figure 1) is the most basic text editor control with no formatting capabilities. A global text editor (Figure 2) allows the formatting to be defined for the whole contents of the editor, but does not allow formatting of individual paragraphs or chapters. A rich text editor (Figure 3) provides a full variety of formatting options for its contents as well as embedding non-text objects.

Plain text editor

Plain text editor

Global text editor

Global text editor

Rich text editor

Rich text editor

Numeric editors

Numeric editors restrict the user input to numeric values. They allow the user to enter only one line of text because numeric values do not span between lines. The numeric editors (Figure 4) can be divided into three subcategories based on the type of numeric values they are designed to accept: integer editors, floating-point editors, and fixed-point editors.

Numeric editors

Numeric editors

Secret editors

Secret editors (Figure 5) are basically plain text editors designed to allow secure input of secret data, such as passwords or PIN codes. The secret editor will not show its contents as plain text but displays a sequence of asterisks instead. There are two types of secret editors, one for alphanumeric input and one for numeric input. The alphanumeric variant displays the last character of user input for a short period of time to help the user produce the desired input on the keypad.

Secret editor

Secret editor

Multi-field numeric editors

The multi-field numeric editor (MFNE) is an editor composed of several numeric fields. They are used to display and enter related numeric values, such as time or date. The functionality of the fields is similar to numeric editors; however, the MFNE context may impose more limitations to the values accepted for a field — for example, because the number of days in a month varies between months.

There are eight MFNE controls available: number editor, range editor, time editor, date editor, time and date editor, duration editor, time offset editor, and IP address editor.

Multi-field numeric editors

Multi-field numeric editors

Related APIs
  • CEikEdwin

API description

The API exposes the functionality through which user can create, configure and manipulate editors. The API description will be covered through the main use cases of various editor types.

Use cases

  • Constructing plain text editors

    • Constructing plain text editors from resource file

    • Constructing plain text editors from resource file

  • Performing basic plain text manipulation through CEikEdwin based editors

  • Constructing global text editors and rich text editors

    • Constructing global text editors and rich text editor from resource file

    • Constructing global text editors and rich text editor from resource file from code

  • Performing advanced text manipulation

    • Using selection

    • Specifying global format

    • Specifying local format

    • Inserting embedded objects

  • Setting and getting the cursor position in CEikEdwin based editors

  • Manipulating editing properties of CEikEdwin based editors

    • Input mode and case

    • Special character tables

    • Numeric key maps

    • Miscellaneous properties

  • Using clipboard in CEikEdwin based editors

  • Observing events from CEikEdwin based editors

  • Constructing numeric editors

    • Constructing numeric editors from resource file

    • Constructing numeric editors from code

  • Retrieving the content of a numeric editor

  • Constructing secret editors

  • Retrieving the content of a secret editor

  • Constructing MFNE editors

    • Constructing from resource file

    • Constructing from code

  • Retrieving the content of a MFNE editor

Related APIs
  • CEikEdwin

API class structure

All editors are either derived from CEikEdwin or CEikMfne . Text editors, numeric editors belong to the firs category and multi-field numeric editors belong to the latter.

CEikEdwin is the generic Symbian platform editor for text. It supports scrollable windows, embedded objects, FEP interactions, clipboard operations. CEikEdwin can handle plain text, global text and rich text. They are represented by CPlainText , CGobalText and CRichText classes respectively. They form a derivation chain in this order. CPlainText is used for storing unformatted text. CGlobalText facilitates the use of one global format that is valid throughout the full length of the text whereas with CRichText user can add format modifiers at any position of the text flow. Rich text also supports object embedding. Embedded objects are represented in rich text by CPicture -derived objects.

Note that CEikEdwin itself is capable of handling global text or rich text however it is advised that developers use derived CEikGlobalTextEditor and CEikRichTextEditor classes respectively when dealing with such contents. When discussing the Plain Text Editor we actually mean discussing all functionality of CEikEdwin that is relevant for creating and manipulating plain text. CEikEdwin ’s capabilities go much beyond that those will be covered when discussing its two subclasses CEikGlobalTextEditor and CEikRichTextEditor .

Relevant constituents of Text Editors

Relevant constituents of Text Editors

Relevant constituents of  Numeric Editor...

Relevant constituents of Numeric Editors

Relevant constituents of MFNE Editors

Relevant constituents of MFNE Editors

Related APIs
  • CEikEdwin
  • CEikGlobalTextEditor
  • CEikMfne
  • CEikRichTextEditor
  • CGlobalText
  • CGobalText
  • CPicture
  • CPlainText
  • CRichText

Using the Editors API

This section advises on how to utilize the Editors API to implement the use cases that were listed earlier. The examples above will use some common assumptions. CMyContainer is an imaginary container control which has an iEditor member which is declared as required by the editor type being discussed. E.g. in the next section it is declared as CEikEdwin* and when describing numeric editors it is declared as CAknIntegerEdwin* .

Constructing Plain Text editors

Constructing Plain Text editors from resource file

A text editor resource is defined as an EDWIN structure in a resource file. The EDWIN structure is defined in eikon.rh as follows:

               STRUCT EDWIN
    LONG flags=0;
    WORD width=0;
    WORD lines=1;
    WORD maxlength=0;

Note: Symbian OS versions older than v9.1 specify the text editor resource in the uikon.rh file.

The meaning of the fields in the EDWIN structure is described in Table 1.

Text editor resource structure fields


Bit field of flags describing properties of the editor control to be created. These flags are defined in CEikEdwin::TFlags . The properties are listed and described in Miscellaneous Properties .


The width of the control; can be specified either by the number of characters or by pixels depending on whether the flag EEikEdwinWidthInPixels is specified; if specified by the number of characters, the widest character of the chosen font is used to determine the actual width of the control.


The number of text lines that the editor will display at once.


The maximum number of characters that can be stored in the editor control.

AKN_EDITOR_EXTENSIONS defines more fields to the resource. These fields are specific to the S60 on Symbian platform. The extensions contain the following fields:

  • WORD default_case=EAknEditorTextCase;

  • WORD allowed_case_modes=EAknEditorAllCaseModes;

  • WORD numeric_keymap=EAknEditorStandardNumberModeKeymap;

  • WORD allowed_input_modes=EAknEditorAllInputModes;

  • WORD default_input_mode=EAknEditorTextInputMode;

  • LLINK special_character_table=-1;

  • WORD avkon_flags=EAknEditorFlagDefault;

  • WORD max_view_height_in_lines=0;

  • WORD base_line_delta=0;

  • WORD spare=0;

The roles of the AKN_EDITOR_EXTENSIONS fields are summarized in Table 2.

S60 on Symbian platform-specific text editor resource structure fields


The default case to apply when receiving user input (input modes and cases are described in Input Mode and Case ).


The allowed case modes; the value set for default_case must be included in this field.


The numeric key map to be used when the editor is in numeric entry mode.


The allowed input modes (input modes and cases are described in Input Mode and Case ); as in case modes, the value set for default_input_mode must be included in this field.


The default input mode.


The special character table to be displayed on user request. Special character tables are described in Special Character Tables .


Bit field of editor flags specific to the S60 on Symbian platform.


Editor's maximum height in lines





The code snippets below demonstrate how to construct a plain text editor. The following example resource structure will be used:

               RESOURCE EDWIN r_editapp_ptx_edit
    maxlength = 200;
    lines = 2;

Notice that the default resource field values are being utilized.

In case of plain text editor iEditor is declared as a CEikEdwin* member.

               void CMyContainer::ConstructL(const TRect& aRect)
    // Create a window for the container
    // Allocate the editor object in memory
    iEditor = new ( ELeave )CEikEdwin;
    // Share container’s window with editor
    iEditor->SetContainerWindowL( *this );
    TResourceReader reader;
    // Set up the resource reader
    iCoeEnv->CreateResourceReaderLC( reader, R_EDITAPP_PTX_EDIT );
    // Construct the editor
    iEditor->ConstructFromResourceL( reader );
    // Set the focus on editor
    iEditor->SetFocus( ETrue );
    // Layout the container
    SetRect( aRect );
    // Activate container and its children (this time only the editor)
Related APIs
  • Avkon_flags
  • CEikEdwin*
  • CEikEdwin::TFlags
  • EEikEdwinWidthInPixels
  • Flags
  • Lines
  • Spare
  • Width
  • allowed_case_modes
  • base_line_delta
  • default_case
  • default_input_mode
  • iEditor
  • max_view_height_in_lines
  • maxlength
  • numeric_keymap
  • special_character_table

Constructing Plain Text editors from code

Another alternative is to call the editor’s second phase constructor and create the CEikEdwin object fully programmatically. Below in CEikEdiwn::ConstructL() the parameters match the fields specified in the r_editapp_ptx_edit resource above this leading to an editor with the same properties.

               void CMyContainer::ConstructL(const TRect& aRect)
    // Create a window for the container
    // Allocate the editor object in memory
    iEditor = new ( ELeave )CEikEdwin;
    // Share container’s window with editor
    iEditor->SetContainerWindowL( *this );
    // Construct the editor with the parameters as from resource
    iEditor->ConstructL( 0, 30, 200, 2);
    // Set the focus on editor
    iEditor->SetFocus( ETrue );
    // Layout the container
    SetRect( aRect );
    // Activate container and its children (this time only the editor)

Specific settings, which correspond to resource fields described in Table 2, can be set from code directly as described in Setting and Getting the Cursor Position of CEikEdwin based editors .

Related APIs
  • CEikEdiwn::ConstructL()
  • CEikEdwin
  • r_editapp_ptx_edit

Common practices

The standard control mechanisms should be applied also in case of editors irrespective of how they were constructed.

               void CMyContainer::SizeChanged()
    // Set the size of the editor
    // Use AknLayouUtils for a real-life app
    iEditor->SetExtent( TPoint (10,50), TSize(156,45) );

TInt CMyContainer::CountComponentControls() const
    // Number of child controls (this time the iEditor only)
    return 1;

CCoeControl* CMyContainer::ComponentControl(TInt aIndex) const
    switch (aIndex)
        case 0:
            return iEditor;
            return NULL;

TKeyResponse CEditappView1Container::OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType)
    // Forward key events to editor. In real life only do this if editor is focused
    return iEditor->OfferKeyEventL(aKeyEvent, aType);

Performing basic Plain Text manipulation through CEikEdwin based editors

When using CEikEdwin class as Plain Text Editor then setting the text content and retrieving it can be considered the main operations of manipulation. When dealing with plain text it is unnecessary to deal with the content model CEikEdwin uses instead use the convenience methods that hide the complexity of the actual document object.

It is fairly intuitive to get hold of the text stored in the editor:

              HBufC* CMyContainer::EditorTextLC() const
    HBufC* text = iEditor->GetTextInHBufL();
    // Push it on cleanup stack as indicated by LC
    CleanupStack::PushL( text );

If there is an already pre-allocated buffer into which you want to load the text then use the GetText() function instead and pass it the descriptor associated with the buffer.

The text can be changed anytime as shown in the following code snippet.

              void CMyContainer::AddMytextL()
    _LIT( KMyText, "This is my text" );
    // () operator will return a TDesC reference
    iEditor->SetTextL( &KMyText() );

SetTextL() will perform all the necessary steps needed to update the editor on screen. As a consequence there is no need to call the editor’s HandleTextChangedL() or DrawNow() .

Related APIs
  • CEikEdwin
  • DrawNow()
  • GetText()
  • HandleTextChangedL()
  • SetTextL()

Constructing Global Text editors and Rich Text editors

Constructing Global Text editors and Rich Text editors from resource file

Global and Rich text editor resource structures are identical even if they are defined separately. This section will cover them both.

The global text editor resource is defined by the GTXTED resource structure. The GTXTED structure is defined in eikon.rh as follows:

               STRUCT GTXTED
    WORD width=0;
    WORD height=0;
    WORD numlines=1;
    WORD textlimit=0;
    LONG flags=0;
    WORD fontcontrolflags=1;
    WORD fontnameflags=EGulNoSymbolFonts;

And the very same fields for the Rich Text Editor:

               STRUCT RTXTED
    WORD width=0;
    WORD height=0;
    WORD numlines=1;
    WORD textlimit=0;
    LONG flags=0;
    WORD fontcontrolflags=1;
    WORD fontnameflags=EGulNoSymbolFonts;

The global and the rich text editor resource definitions contain some extra fields when compared to the EDWIN resource structure. These fields are described in Table 3.

Global and rich text editor resource structure field


Bit field of flags describing font control properties of the global or rich text control. These flags are defined in gulftflg.hrh and follow the naming convention of EGulFontControlXxx . The default value 1 ( EGulFontControlAll ) provides all font controls to the editor control.


Bit field describing the font types available to the editor control. These flags are defined in gulftflg.hrh beginning with EGulAllFonts .

The initialization of the Global and Rich Text Editors is done in the same way as with Plain Text editors.

               void CMyContainer::ConstructL(const TRect& aRect)
    // Create a window for the container
    // Allocate the editor object in memory
    iEditor = new ( ELeave )CEikRichTextEditor;
    // Share container’s window with editor
    iEditor->SetContainerWindowL( *this );
    TResourceReader reader;
    // Set up the resource reader
    iCoeEnv->CreateResourceReaderLC( reader, R_EDITAPP_RTX_EDIT );
    // Construct the editor
    iEditor->ConstructFromResourceL( reader );
    // Set the focus on editor
    iEditor->SetFocus( ETrue );
    // Layout the container
    SetRect( aRect );
    // Activate container and its children (this time only the editor)

Here R_EDITAPP_RTX_EDIT refers to a rich text resource. Here is an example:

               RESOURCE RTXTED r_editapp_ptx_edit
    maxlength = 200;
    lines = 2;
Related APIs
  • EGulAllFonts
  • EGulFontControlAll
  • EGulFontControlXxx
  • eikon.rh
  • fontcontrolflags
  • fontnameflags

Constructing Global Text editors and Rich Text editors from code

When creation happens purely from code use the second phase constructor instead of ConstructFromResourceL() .

               void CMyContainer::ConstructL(const TRect& aRect)
    // Create a window for the container
    // Allocate the editor object in memory
    iEditor = new ( ELeave )CEikRichTextEditor;
    //Construct the editor
    iEditor->ConstructL( this, 2, 200, 0 );
    // Set the focus on editor
    iEditor->SetFocus( ETrue );
    // Layout the container
    SetRect( aRect );
    // Activate container and its children (this time only the editor)

Note that here there is no need to call SetContainerWindowL() as the ConstructL() will do it. (The first parameter is the parent which will provide the window for it).

Related APIs
  • ConstructFromResourceL()
  • ConstructL()
  • SetContainerWindowL()

Performing Advanced Text manipulation

The text contained in editor controls is stored in a text object instantiated from class CEditableText or from a class derived from it. The following sections describe its usage in manipulating the contents and formatting the text editor controls.

Using selection

Text editor controls allow the user to select some or all of the contents of the editor. The application can then provide functionality concerning only the selection, such as clipboard operations or text formatting.

The API for manipulating the current selection of text editor is straightforward. It consists of five methods provided by the class CEikEdwin : getting the length ( SelectionLength() ) and position ( Selection() ) of the current selection, clearing the selection ( ClearSelectionL() ), and selecting some ( SetSelectionL() ) or all ( SelectAllL() ) of the contents.

The following sample code removes the selected text area:

               // Get selection position
TCursorSelection pos = iEditor->Selection();
// Get text contents
CPlainText* text = iEditor->Text();
// Remove the selected text
text->DeleteL(pos.LowerPos(), pos.Length());
Related APIs
  • CEikEdwin
  • ClearSelectionL()
  • SelectAllL()
  • Selection()
  • SelectionLength()
  • SetSelectionL()

Specifying global format

The global text editor control and the rich text editor control provide support for text formatting. This section describes the classes responsible for storing the formats and the methods to apply global format to the editor (i.e. A format that is in effect for all the content of the editor).

Text formatting is performed in two levels: at the paragraph level and at the character level. The paragraph formatting is performed through the class CParaFormat . With the global text editor, all paragraphs assume the same paragraph formatting style. With the rich text editor, the paragraph formatting style can be specified individually to each paragraph of the text. The character formatting is accomplished with class TCharFormat .

The properties available for paragraph formatting are listed in Table 4. These properties are accessible through public members in instances of class CParaFormat .

Paragraph formatting properties


The distance between the paragraph border and the paragraph text in twips.


The bullet point used in the paragraph. A NULL value indicates no bullet point.


The default tab stop width in twips.


The background color of the paragraph. The default is the system background color.


The horizontal alignment of the paragraph.


The indent of the first line of a paragraph in twips relative to the left margin.


Flag for preventing page breaks inside the paragraph.


Flag for preventing page break between this and the next paragraph.


The language of the paragraph. Used in, for example, spell checking purposes.


The width of the left margin in twips.


The inter-line spacing within the paragraph.


Whether iLineSpacingInTwips means 'at least' or 'exactly'


The width of the right margin in twips.


The height of space below the paragraph in twips.


The height of space above the paragraph in twips.


Flag for inserting a page break immediately before this paragraph.


The vertical alignment of the paragraph.


Flag for preventing the printing of the last line of this paragraph at the top of the page (widow) or the first line of this paragraph at the bottom of the page (orphan).


Flag for line wrapping at the right margin.

In addition to these formatting properties, the paragraph formatting object also allows specification of tab stops and paragraph borders.

The formatting properties at the character level are listed in Table 5. These properties are accessible through public members of the iFontPresentation structure in instances of class TCharFormat .

Character formatting properties


The text color.


The text color used for selected text.


The highlighting style.


The value of the strikethrough attribute.


The value of the underline attribute.


Specifies whether the text is hidden. Note that hidden text is not currently supported by the text layout engine. This attribute is provided to preserve information when copying from and to devices that support hidden text. By default EFalse .


The vertical alignment of a picture character.

Applying paragraph and character formatting involves the format mask variable. The format mask variable specifies which formatting properties are to be applied in the given formatting object. There are separate format mask types for paragraph ( TParaFormatMask ) and character ( TCharFormatMask ) formatting. The mask variable is essentially a bit field, and the properties are set using the SetAttrib() method and reset with the ClearAttrib() method. The values passed to these methods are of type TTextFormatAttribute . When setting many or all formatting properties, it may be useful to call the SetAll() method.

The following code example demonstrates applying paragraph formatting to a global text editor:

               void CMyContainer::SetMyFormatL()
    // Create paragraph formatting object
    CParaFormat* pf = new (ELeave) CParaFormat();
    // Set the alignment
    pf->iHorizontalAlignment = CParaFormat::ECenterAlign;
    // Create paragraph formatting mask
    TParaFormatMask mask;
    // This alignment needs to be changed
    // Apply formatting to global text editor control
    iEditor->ApplyParaFormatL(pf, mask);
    CleanupStack::PopAndDestroy(); // pf

Adding the following code demonstrates applying character formatting to a global text editor:

               void CMyContainer::SetMyFormatL()
    // Create character format
    TCharFormat cf;
    // Set up the text color and strikethrough properties
    cf.iFontPresentation.iTextColor = KRgbBlue;
    cf.iFontPresentation.iStrikethrough = EStrikethroughOn;
    // Create character format mask 
    TCharFormatMask cmask;
    // The text color and strikethrough need to be changed
    // Apply formatting to global text editor control    
    iEditor->ApplyCharFormatL(cf, cmask);
Related APIs
  • CParaFormat
  • ClearAttrib()
  • EFalse
  • SetAll()
  • SetAttrib()
  • TCharFormat
  • TCharFormatMask
  • TParaFormatMask
  • TTextFormatAttribute
  • iBorderMarginInTwips
  • iBullet
  • iDefaultTabWidthInTwips
  • iFillColor
  • iFontPresentation
  • iHiddenText
  • iHighlightColor
  • iHighlightStyle
  • iHorizontalAlignment
  • iIndentInTwips
  • iKeepTogether
  • iKeepWithNext
  • iLanguage
  • iLeftMarginInTwips
  • iLineSpacingControl
  • iLineSpacingInTwips
  • iPictureAlignment
  • iRightMarginInTwips
  • iSpaceAfterInTwips
  • iSpaceBeforeInTwips
  • iStartNewPage
  • iStrikethrough
  • iTextColor
  • iUnderline
  • iVerticalAlignment
  • iWidowOrphan
  • iWrap

Specifying local formats

In rich text editors it is possible to specify individual paragraph format for each paragraph and character format for any arbitrary section of characters.

All formatting in a rich text object is based on a global character layer and paragraph format layer, and a chain of layers on which they may be based. In case of conflict, upper layers override lower layers. These two format layers are specified on construction, and are not owned by the text object.

Additional formatting may then be added to any portion of the text. This is called specific formatting and in case of conflict, it overrides the formatting in the global layers.

Specific formatting is owned by the text object. So, the effective formatting of a rich text object may be composed of specific formatting and formatting specified in a chain of format layers.

Local formats are based on specific formatting applied at the various positions and with various length of the text content.

The following example demonstrates this with character formats:

               void CMyContainer::SetMyTextAndCharFormatPatternL()
    _LIT ( KMyText, "OOOOOOOO");
    // Set the initial text of the editor
    iEditor->SetTextL( &KMyText() );
    CRichText* rtx = iEditor->RichText();
    TCharFormat cf;
    // Set up the text color and strikethrough properties
    cf.iFontPresentation.iTextColor = KRgbBlue;
    cf.iFontPresentation.iStrikethrough = EStrikethroughOn;
    // Create character format mask 
    TCharFormatMask cmask;
    // The text color and strikethrough need to be changed
    cmask.SetAttrib( EAttColor );
    cmask.SetAttrib( EAttFontStrikethrough );
    // Apply strikethrough to the whole text
    rtx->ApplyCharFormatL( cf, cmask, 0, rtx->DocumentLength() );
    // Apply underline and disable strikethrough for chars for positions 3 to 6
    cmask.SetAttrib( EAttFontUnderline );
    cf.iFontPresentation.iUnderline = EUnderlineOn;
    cf.iFontPresentation.iStrikethrough = EStrikethroughOff;  
    rtx->ApplyCharFormatL( cf, cmask, 2, 4 );
    // Apply strikethrough and disable underline on char positions 4 and 5    
    cf.iFontPresentation.iUnderline = EUnderlineOff;
    cf.iFontPresentation.iStrikethrough = EStrikethroughOn;
    rtx->ApplyCharFormatL( cf, cmask, 3, 2 );
    // Notify the editor about the changed text

The code will result in the following formatted text:



CRichText::SetInsertCharFormatL() will prepare the insertion with the specified format and at the specified position. CRichText::CancelInsertCharFormatL() needs to be called after the insertion.

Related APIs
  • CRichText::CancelInsertCharFormatL()
  • CRichText::SetInsertCharFormatL()

Inserting embedded objects

The rich text editor controls provide support for object embedding. The embedded objects are divided into two types in the rich text API: generic embedded objects and picture objects. The generic embedded objects are objects managed by other applications. Depending on the capabilities of these applications, the objects may be represented as a glass door or as an icon. The use of these external embeddable objects is beyond the scope of this document.

The embedded picture objects are represented within the rich text by objects derived from class CPicture . CPicture is an abstract class that encapsulates the drawing and serialization of picture objects. The following code example demonstrates how to create and use a simple CPicture derived class to draw an embedded picture in rich text:

               // CMyPicture is a minimal picture class (derived from CPicture)
class CMyPicture : public CPicture
        CMyPicture( TSize aSize);
        void Draw( CGraphicsContext& aGc,
                   const TPoint& aTopLeft,
                   const TRect& aClipRect,
                   MGraphicsDeviceMap* aMap ) const;
        void ExternalizeL( RWriteStream& aStream ) const;
        void GetOriginalSizeInTwips( TSize& aSize ) const;
        TSize iSize;

               CMyPicture::CMyPicture(TSize aSize) : iSize(aSize) {}
void CMyPicture::ExternalizeL(RWriteStream& ) const {}

void CMyPicture::GetOriginalSizeInTwips(TSize& aSize) const 
    { aSize = iSize; }

// The actual drawing code
void CMyPicture::Draw(CGraphicsContext& aGc, 
                      const TPoint& aTopLeft,
                      const TRect& aClipRect,
                      MGraphicsDeviceMap* aMap) const
    TSize pixelsize;
    pixelsize.iWidth = aMap->HorizontalTwipsToPixels(iSize.iWidth);
    pixelsize.iHeight = aMap->VerticalTwipsToPixels(iSize.iHeight);
    TRect area = TRect(aTopLeft, pixelsize);
    // Draw a red ellipse

An instance of CMyPicture can then be embedded into a rich text editor by using the following code:

               void CMyContainer::AddPictureL()
    // Instantiate CMyPicture object 300x300 twips in size
    CPicture* picture = new( ELeave )CMyPicture( TSize( 300, 300 ) );
    //Prepare the picture header, which will be inserted into the rich text
    TPictureHeader header;
    header.iPicture = TSwizzle<CPicture>(picture);
    // Insert the picture into the beginning of the rich text editor
    iEditor->RichText()->InsertL(0, header);
    CleanupStack::Pop(); // picture
Related APIs
  • CMyPicture
  • CPicture
Related APIs
  • CEditableText

Setting and getting the cursor position of CEikEdwin -based editors

Another important although not too common use case is when editor client wants to move the cursor in the editor presented to the user to the right text position. This is usually but not exclusively done right after construction.

The following code snippet gained with a slight modification of the AddMyTextL() function implementation in Performing Basic Plain Text Manipulation through CEikEdwin based editors .

               void CMyContainer::AddMyTextL()
    _LIT( KMyText, "This is my text" );
    // () operator will return a TDesC reference
    iEditor->SetTextL( &KMyText() );
    //Place the cursor after ‘This’ w/o selection 
    iEditor->SetCursorPosL( 4, EFalse );

CEikEdwin::SetCursorPosL() will place the cursor to the specified position. The second parameter is used for putting selection between the zero position and the specified position.

The editor will move the text view so that the cursor is visible.

Related APIs
  • AddMyTextL()
  • CEikEdwin::SetCursorPosL()

Manipulating the editing properties of CEikEdwin -based editors

Input mode and case

Text editor controls have modifiable properties that aid the user to enter data into the editor with the limited input capabilities of a keypad-based device. These properties include input mode and input case.

There are three distinct input mode options available: text input mode, numeric input mode, and secret text input mode. The text input mode allows the user to input text data using the keypad. Depending on the other properties, text input can be further accelerated with the predictive text input feature. The numeric input mode enables the user to input numeric data directly with the keypad. The secret text input mode is used in conjunction of secret text editors. The defined symbols and their meanings are listed in Table 6.

Input modes


Text input.


Numeric input.


Secret text input.


All of the above.

Input case is used in conjunction with text input mode. It gives more fine-grained control of the actual text input process as it specifies the desired case of the text to be entered. There are three options available: all text may be upper case or lower case, or the text is formatted so that the first character is upper case and the rest is lower case. The symbols and their meaning are listed in Table 7.

Input cases


All text input is upper case.


All text input is lower case.


The first character is upper case, the others are lower case.


All of the above.

The input mode and case properties of a text editor can be specified in the editor resource structure or they can be set at run time. The usage of resource structures is described in Constructing Plain Text Editors from Resource File . The following code example shows how to manipulate these options at run time:

               // Set allowed input modes

// Set the default input mode
// Set allowed case modes
// Set the default case mode

The example code sets all input modes to be allowed for the user to choose, setting text input mode to be the default. Within the text input mode, only upper case mode is allowed.

Related APIs
  • EAknEditorAllCaseModes
  • EAknEditorAllInputModes
  • EAknEditorLowerCase
  • EAknEditorNumericInputMode
  • EAknEditorSecretAlphaInputMode
  • EAknEditorTextCase
  • EAknEditorTextInputMode
  • EAknEditorUpperCase

Special character tables

Many applications based on S60 for Symbian platform also require symbols other than alphanumeric ones to be entered. The most common example is e-mail composition: every valid e-mail address contains the ‘@’ symbol. This enables users to enter these special characters into text editor controls through special character tables. A special character table is a pop-up dialog containing a grid of special characters to choose from. Because there are different needs for special characters, the platform provides different special character tables as well.

The special character tables available for text editors are listed in Table 8.

Special character tables




URL addresses.


E-mail addresses.



The special character table for an editor control can be specified either in a resource file or with the CEikEdwin::SetAknEditorSpecialCharacterTable() method.

Related APIs
  • CEikEdwin::SetAknEditorSpecialCharacterTable()

Numeric key maps

Numeric key maps enable users to enter other symbols to the numeric editor: for example, in a calculator application it is useful to have the primary input mode as numeric, but occasionally there is a need to insert other symbols as well (for example, operators and decimal separator). The numeric key map allows the programmer to define this functionality to the two non-numeric keys of the keypad, the asterisk (‘*’) and the hash (‘#’) keys.

Table 9 lists the available options for numeric key maps. The Asterisk key column lists symbols available by pressing the asterisk key (‘*’), and the Hash key column shows the symbol input when pressing the hash key (‘#’).

Numeric key maps


*, +, p, w




+, -, *, /



+, -, E






*, +, p, w



*, +







The numeric key map for an editor control can be specified either in a resource file or by using the CEikEdwin::SetAknEditorNumericKeymap() method.

Related APIs
  • CEikEdwin::SetAknEditorNumericKeymap()
  • EAknEditorAlphanumericNumberModeKeymap
  • EAknEditorCalculatorNumberModeKeymap
  • EAknEditorConverterNumberModeKeymap
  • EAknEditorFixedDiallingNumberModeKeymap
  • EAknEditorPlainNumberModeKeymap
  • EAknEditorSATHiddenNumberModeKeymap
  • EAknEditorSATNumberModeKeymap
  • EAknEditorStandardNumberModeKeyMap
  • EAknEditorToFieldNumberModeKeymap

Miscellaneous properties

There are a great number of properties that can be specified for the editor controls. Some of these properties affect the editing properties directly (such as the read-only property) and some of them are purely controlling the implementation of the text editor controls (such as the flag whether to use segmented storage for the contents or not). These properties must be specified when creating the editor control — either by passing them as an argument to the ConstructL() method or by providing them in the flags field in the resource definition. Typically, the properties cannot be altered afterwards.

Some of these properties can, however, be changed at run time: the read-only flag can be set by the SetReadOnly() method and word wrapping can be controlled by, for example, the SetWordWrap() method.

Editor flags


The EDWIN does not destroy its content on destruction.


The content buffer uses segmented storage (see CEditableText::ESegmentedStorage ). Segmented storage places the data in more than one heap location. Each forms a part of the buffer. When this flag is not used, the content buffer is stored in one memory location (referred to as a flat buffer). Segmented memory tends to be more flexible in memory allocation, but is slower in operation than flat buffering.


The size specified in the resource used to construct the object is given in pixels, not characters.


No automatic selection takes place. Typically, the entire text is selected as one operation whenever the EDWIN is created, resized, or has its text set.


When the control is activated, the cursor is moved to the end of the text.


Do not wrap the text being edited.


Use a line cursor instead of a block cursor.


Horizontal scrolling is disabled.


If set, scrollbars for long documents appear inside the EDWIN , reducing the area available to the EDWIN . If not set, scrollbars appear outside the EDWIN . This does not affect the TSize values returned by the method MinimumSize() .


Sets the height of the EDWIN in lines, according to text supplied by the user.


The EDWIN is a window-owning control.


The EDWIN does not respond to user input.


If the EDWIN loses focus, do not hide the selection.


The EDWIN is read-only. Attempting to add text displays a message to say it is read-only.


No special attempt to delete embedded pictures cleanly will be made. This flag does not apply to EDWIN s that do not edit rich text.


Enable undo operations.


Do not allow line or paragraph breaks in the text being edited.


Allow only ASCII characters.


The EDWIN control is resizable, for example, when contained in a parent control. Should the parent control be required to resize itself, the image of the EDWIN control that is displayed can be resized to fit within the parent control. This does not affect the maximum width of the EDWIN control.


The EDWIN ignores the virtual cursor. Note: Touchscreen devices do not use the virtual cursor.


No custom draw is done.


Changes layout to AVKON style.


Hides cursor.


Changes text editor to non-editable mode.


Sets the style wrapping on.

Below are the flags specific to the S60 on Symbian platform, settable either from SetAknEditorFlags() or from the avkon_flags field in an AKN_EDITOR_EXTENSIONS resource.

Avkon editor flags


Case changes are not allowed.


Predictive text entry is not allowed.


Editor indicators are not shown.


The cursor cannot be moved horizontally.


Edit menu cannot be opened from edit key.


Enables scroll bars.


The character next to the cursor (if exists) is replaced by a new entered character. This flag has effect only in latin multitap input.


The number input mode uses same special character table character set as alpha input mode if the flag is set. The flag overrides number mode keymapping if they are in conflict. This flag can be used also with number input mode only editors.


Input language is changed to English locally in the editor.


Chinese find mode input.


Line feed character is added with scroll down key event if the cursor is at the end of the buffer. The functionality is available only in certain variants.


Enables pictograph input.


Used internally by CAknSearchField.

Related APIs
  • CEditableText::ESegmentedStorage
  • ConstructL()
  • EAknEditorFlagAllowEntersWithScrollDown
  • EAknEditorFlagEnablePictographInput
  • EAknEditorFlagEnableScrollBar
  • EAknEditorFlagFindPane
  • EAknEditorFlagFixedCase
  • EAknEditorFlagForceTransparentFepModes
  • EAknEditorFlagLatinInputModesOnly
  • EAknEditorFlagMTAutoOverwrite
  • EAknEditorFlagNoEditIndicators
  • EAknEditorFlagNoLRNavigation
  • EAknEditorFlagNoT9
  • EAknEditorFlagSupressShiftMenu
  • EAknEditorFlagUseSCTNumericCharmap
  • EAllowPictures
  • EAllowUndo
  • EAlwaysShowSelection
  • EAvkonDisableCursor
  • EAvkonEditor
  • EAvkonNotEditable
  • EDisplayOnly
  • EEdwinAlternativeWrapping
  • EIgnoreVirtualCursor
  • EInclusiveSizeFixed
  • EJustAutoCurEnd
  • ELineCursor
  • ENoAutoSelection
  • ENoCustomDraw
  • ENoHorizScrolling
  • ENoLineOrParaBreaks
  • ENoWrap
  • EOnlyASCIIChars
  • EOwnsWindow
  • EReadOnly
  • EResizable
  • ESegmentedStorage
  • EUserSuppliedText
  • EWidthInPixels
  • EkeepDocument
  • MinimumSize()
  • SetAknEditorFlags()
  • SetReadOnly()
  • SetWordWrap()
  • TSize
  • avkon_flags

Using the clipboard in CEikEdwin -based editors

The clipboard is used to transfer data between the text editors in same or different applications. The clipboard is implemented as a direct file store in Symbian platform, and it may contain any serializable object.

The text editor base class CEikEdwin provides, however, the utility method ClipboardL() to handle cut, copy, and paste operations. The cut and copy operations target the selected text. The paste operation will replace the currently selected text with the contents of clipboard. If there is no selection, the clipboard contents will be inserted at the current cursor position.

The following code demonstrates the use of these operations:

              // Select all in the first editor
// Cut the selected text
// Paste the contents of clipboard to the second text editor
Related APIs
  • CEikEdwin
  • ClipboardL()

Observing events from CEikEdwin -based editors

To observe EDWIN based events client needs to register an MEikEdwinObserver derived observer to the editor.

The registration is done by CEikEdwin::SetEdwinObserver() . The observer will get the notification from the editor through the HandleEdwinEventL(CEikEdwin* aEdwin, TEdwinEvent aEventType) . The first parameter is a pointer to the EDWIN that generated the event and the second one is the event type, which is defined this way:

              enum TEdwinEvent

It is quite obvious that the enum values correspond to format change, cursor movement and text update events respectively.

Related APIs
  • CEikEdwin::SetEdwinObserver()
  • MEikEdwinObserver
  • enum

Constructing Numeric editors

Constructing Numeric editors from resource files

The integer editor control resource is defined by the AVKON_INTEGER_EDWIN resource structure defined in avkon.rh . The AVKON_INTEGER_EDWIN resource structure is defined as follows:

    WORD maxlength = 0;
    LONG min = -99999999;
    LONG max = 99999999;
    LONG unset_value= -100000000;
    LLINK extension1 = 0;
    LLINK extension2 = 0;

The semantics of the fields in the numeric editor control resource structure are self-explanatory: the min field contains the smallest allowed value, the max field contains the largest allowed value, maxlength dictates the maximum content length in characters, and unset_value is the default value of the integer editor control.

The fixed-point editor control resource is defined by the FIXPTED resource structure. The FIXPTED resource structure is defined in eikon.rh as follows:

               STRUCT FIXPTED
    WORD decimalplaces=2;
    LONG min;
    LONG max;
    LONG default=0;

The decimalplaces field describes the number of decimals allowed in the edited value. Note that the fixed point editor control presents the value as an integer; the actual value is 10 decimalplaces the integer value must be divided by 100).

The floating-point editor control resource is defined by the FLPTED resource structure. The FLPTED resource structure is defined in eikon.rh as follows:

               STRUCT FLPTED
    WORD maxlength=18;
    DOUBLE min=-9.9e99;
    DOUBLE max=9.9e99;
    DOUBLE default=0;

The code snippets in this section will demonstrate how to construct an integer editor (floating point editors and fixed point editors can be constructed similarly but using the associated resource structure). The following example resource structure will be used:

               RESOURCE AVKON_INTEGER_EDWIN r_myapp_int_edit
    maxlength = 7;
    max= 1000000;
    unset_value = -1;

iEditor now is declared as CAknIntegerEdwin* .

               void CMyContainer::ConstructL(const TRect& aRect)
    CreateWindowL();//Create a window for the container
    iEditor = new ( ELeave )CAknIntegerEdwin;
    iEditor->SetContainerWindowL( *this );
    TResourceReader reader;
    iCoeEnv->CreateResourceReaderLC( reader, R_MYAPP_INT_EDIT );
    iEditor->ConstructFromResourceL( reader );
    iEditor->SetFocus( ETrue );
    SetRect( aRect );

The code above is not complete it is also required to include the newly created editor in the control hierarchy, forward it the key events and to set its extent when needed. The pattern shown previously in Common Practices can be followed.

Related APIs
  • CAknIntegerEdwin*
  • decimalplaces
  • iEditor
  • max
  • maxlength
  • min
  • unset_value

Construction from code

A viable alternative to constructing from resource file is to construct the editor purely from code.

               void CMyContainer::ConstructL(const TRect& aRect)
    //Create a window for the container
    // min, max, max length
    iEditor = CAknIntegerEdwin::NewL( 0, 1000000, 7 );
    // Set parent
    iEditor->SetContainerWindowL( *this );
    // Specify unset value
    iEditor->SetUnsetValue( -1 );
    // Set focus
    iEditor->SetFocus( ETrue );
    // Let container take the specified rect
    SetRect( aRect );
    // Activate the container

Notice that now that most parameters will be fed into the NewL() factory function instead of reading them from resource file. However the ‘unset value’ has to be set separately through the SetUnsetValue() function.

There is a way to change the initial configuration through the right setter functions. More details on that can be found in the class documentations.

Related APIs
  • NewL()
  • SetUnsetValue()

Retrieving the content of a Numeric editor

The following code shows how you can get the content of the Integer Editor. The GetInt() function will return EFalse if the user supplied data was not acceptable (e.g. editor was empty, number was too high or too low). Note that the editor will take care of not letting the user enter longer number than specified as maxlength .

              TBool CMyContainer::GetInt( TInt& aNumber )
    TValidationStatus stat = iEditor->GetTextAsInteger( aNumber );
    return (EValueValid == stat);

In case of a Floating Point Editor the GetValueAsReal() provides the same functionality.

Related APIs
  • EFalse
  • GetInt()
  • GetValueAsReal()
  • maxlength

Constructing Secret editors

Secret editors can be instantiated using any of the standard methods either from resource file or from code. The alphanumeric secret editor class is CEikSecretEditor and the numeric secret editor class is CAknNumericSecretEditor , which is derived from CEikSecretEditor . Alphanumeric secret editors are defined using a SECRETED resource structure and numeric secret editors are defined using a NUMSECRETED structure as follows:

              RESOURCE SECRETED r_my_secret_editor
    num_letters = 10;
RESOURCE NUMSECRETED r_my_num_secret_editor
    num_code_chars = 4;

The SECRETED resource definition can be found in Eikon.rh whereas the NUMSECRETED definition is in Avkon.rh .

              void CMyContainer::ConstructL(const TRect& aRect)
    // Create a window for the container
    // Call first phase constructor
    iEditor = new (ELeave)CEikSecretEditor;
    // Set parent
    iEditor->SetContainerWindowL( *this );
    // Initialize a resource reader
    TResourceReader reader;
    iCoeEnv->CreateResourceReaderLC( reader, R_MY_SECRET_EDITOR );
    // Second phase constructor from resource
    iEditor->ConstructFromResourceL( reader );
    // Set focus
    iEditor->SetFocus( ETrue );
    SetRect( aRect );
    // Activate the container    

And in case of a numeric secret editor you would do practically the same except for creating a CAknNumericSecretEditor and using the R_MY_NUMERIC_SECRET_EDITOR .

Related APIs
  • CAknNumericSecretEditor
  • CEikSecretEditor
  • Eikon.rh

Retrieving the content of a Secret editor

Use the CEikSecretEditor::GetText() function to retrieve the user provided secret data in a preallocated buffer. Bear in mind that maximum length of the secret text cannot be bigger than CEikSecretEditor::EMaxSecEdBufLength therefore allocating a buffer of this size is sufficient.

Related APIs
  • CEikSecretEditor::EMaxSecEdBufLength
  • CEikSecretEditor::GetText()

Constructing MFNE editors

MFNE editors can be constructed from resource as well as from code. In this document we will not cover all MFNE editors as their usage is very similar.

Constructing MFNE editors from resource

The resource structures for MFNE controls are also defined in eikon.rh . These resource structures generally contain the minimum and maximum value of the fields and — depending on the type of the MFNE control — some additional fields.

The resource structure names used in creating the MFNEs are listed in Table 11. For more information, see the Symbian SDK documentation and the eikon.rh file.

Multi-field numeric editor resource definition structures

Number editor



Range editor



Time editor



Date editor



Time and date editor



Duration editor



Time offset editor



IP address editor



Location editor



Unit editor



As an example let’s see how a date editor is constructed from this example resource:

               RESOURCE DATE_EDITOR r_my_date_editor
    minDate = DATE
        day = 0;
        month = 6;
        year = 2006;
    maxDate = DATE
        day = 30;
        month = 11;
        year = 2006;

Note that the days and months start from 0 meaning that 1 day = 0; month = 0; .

And here is the code snippet for create the editor (very similar to previous ones).

               void CMyContainer::ConstructL(const TRect& aRect)
    // Create a window for the container
    // Call first phase constructor
    iEditor = new (ELeave)CEikDateEditor;
    // Set parent
    iEditor->SetContainerWindowL( *this );
    // Initialize a resource reader
    TResourceReader reader;
    iCoeEnv->CreateResourceReaderLC( reader, R_MY_DATE_EDITOR );
    // Second phase constructor from resource
    iEditor->ConstructFromResourceL( reader );
    // Set focus
    iEditor->SetFocus( ETrue );
    SetRect( aRect );
    // Activate the container    

Construction of other MFNE based editors from resource file could be done according to the above code scheme with the right resource structure.

Related APIs
  • CAknIpFieldEditor
  • CAknLocationEditor
  • CAknUnitEditor
  • CEikDateEditor
  • CEikDurationEditor
  • CEikNumberEditor
  • CEikRangeEditor
  • CEikTimeAndDateEditor
  • CEikTimeEditor
  • CEikTimeOffsetEditor

Constructing MFNE editors from code

Now let’s see how the construction goes from code. We do have a little bit more control over the default value of the editor this way (which can be achieved with adding a SetDate() call to the code snippet in the previous section).

               void CMyContainer::ConstructL(const TRect& aRect)
    // Create a window for the container
    // Call first phase constructor
    iEditor = new (ELeave)CEikDateEditor;
    // Set parent
    iEditor->SetContainerWindowL( *this );
    TDateTime dateTime;
    // Set the from date
    dateTime.SetMonth( EJuly );//July
    dateTime.SetDay( 0 ); //1st day
    TTime fromTime( dateTime );
    // Set the to date
    dateTime.SetMonth( EDecember );//July
    dateTime.SetDay( 30 ); //31st day
    TTime toTime( dateTime );
   //Set default date to current date
    TTime now;
    // Now call second phase constructor with the right params
    // EFalse is for disabling the popup to select the date from
    // there is no S60 support for this
    iEditor->ConstructL( fromTime, toTime, now, EFalse );
    // Set focus
    iEditor->SetFocus( ETrue );
    SetRect( aRect );
    // Activate the container    

Note that the last TBool parameter of ConstructL() is ignored.

Related APIs
  • ConstructL()
  • SetDate()
  • TBool

Retrieving the content of a MFNE editor

The way of getting the user supply data from an MFNE editor can usually be done with a single function call. The return type and the name of the function however vary according to the type of the editor.

To demonstrate this use case we complete the previous date editor example with one more function.

              TBool CMyContainer::BirthDay( TTime& aDate ) const
    //Check if the editor is initialized
    TBool valid  = !iEditor->IsUninitialised();
    // if initialized
    if ( valid )
        // Get the Date user provided
        aTime = iEditor->Date();
    return valid;

The code will return false if the editor is not initialised. (It can only happen if SetUninitialised( ETrue ) had been called earlier.)

Retrieving the content of other MFNE Editors can be done in a similar way. E.g. in case of an IP address editor the function Address() need to be used to get the user input in a TInetAddres object.

Related APIs
  • Address()
  • TInetAddres

Error handling

Editors API uses standard Symbian platform error reporting mechanism. It does not define any panic codes of its own. Leaves and system wide error codes as function return values are used if the error is recoverable. A client application can handle these errors similarly as a normal Symbian platform.

Memory overhead

Memory consumption of various Editors is largely dependent on their content. It is worth considering disabling undo buffer in case of CEikEdwin based editors. CEikEdwin through its underlying components do also store formatting information along with the text. Formatting of large texts result in the editor switching to a band formatting mode, in which the editor will format as little text as needed to be able to display the visible part of the text. User can explicitly change the document length limit from which the editor applies band formatting by calling CEikEdwin::SetUpperFullFormattingLength() function.

Related APIs
  • CEikEdwin
  • CEikEdwin::SetUpperFullFormattingLength()

Limitations of the API

This API cannot be used without a UI environment (e.g. a Symbian OS sever process cannot use the API).

Related APIs
  • CAknIntegerEdwin*
  • CEikEdwin*
  • CMyContainer
  • iEditor



Editors API abbreviations

API Application Programming Interface


CEikEdwin based editor




Multi-field Numeric Editor


Operating System


Twentieth of a point. A twip is 1/1440th of an inch or 1/567th of a centimeter.

Related APIs
  • CEikEdwin