Editors API Specification

Changes in Editors API documentation

1.0 12.10.2006 Approved

Changes in Editors API

1.0 First release

Contents

Purpose

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.

Constraints

None.

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;
    AKN_EDITOR_EXTENSIONS
    }

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

Flags

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 .

Width

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.

Lines

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

maxlength

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

default_case

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

allowed_case_modes

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

numeric_keymap

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

                  
                   allowed_input_modes
                  
                 

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.

default_input_mode

The default input mode.

special_character_table

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

Avkon_flags

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

max_view_height_in_lines

Editor's maximum height in lines

base_line_delta

Unused

Spare

Unused

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
               
    {
    width=30;
    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
    CreateWindowL();
    // 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 );
    CleanupStack::PopAndDestroy();
    // Set the focus on editor
    iEditor->SetFocus( ETrue );
    // Layout the container
    SetRect( aRect );
    // Activate container and its children (this time only the editor)
    ActivateL();
    }
Related APIs
  • AKN_EDITOR_EXTENSIONS
  • Avkon_flags
  • CEikEdwin*
  • CEikEdwin::TFlags
  • EDWIN
  • 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
    CreateWindowL();
    // 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)
    ActivateL();
    }

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;
        default:
            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;
    AKN_EDITOR_EXTENSIONS
    }

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;
    AKN_EDITOR_EXTENSIONS
   }

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

fontcontrolflags

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.

fontnameflags

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
    CreateWindowL();
    // 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 );
    CleanupStack::PopAndDestroy();
    // Set the focus on editor
    iEditor->SetFocus( ETrue );
    // Layout the container
    SetRect( aRect );
    // Activate container and its children (this time only the editor)
    ActivateL();
    }

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

              
               RESOURCE RTXTED r_editapp_ptx_edit
               
    {
    width=30;
    maxlength = 200;
    lines = 2;
    }
Related APIs
  • EDWIN
  • EGulAllFonts
  • EGulFontControlAll
  • EGulFontControlXxx
  • GTXTED
  • R_EDITAPP_RTX_EDIT
  • 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
    CreateWindowL();
    // 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)
    ActivateL();
    }

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

iBorderMarginInTwips

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

iBullet

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

iDefaultTabWidthInTwips

The default tab stop width in twips.

iFillColor

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

iHorizontalAlignment

The horizontal alignment of the paragraph.

iIndentInTwips

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

iKeepTogether

Flag for preventing page breaks inside the paragraph.

iKeepWithNext

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

iLanguage

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

iLeftMarginInTwips

The width of the left margin in twips.

iLineSpacingInTwips

The inter-line spacing within the paragraph.

iLineSpacingControl

Whether iLineSpacingInTwips means 'at least' or 'exactly'

iRightMarginInTwips

The width of the right margin in twips.

iSpaceAfterInTwips

The height of space below the paragraph in twips.

iSpaceBeforeInTwips

The height of space above the paragraph in twips.

iStartNewPage

Flag for inserting a page break immediately before this paragraph.

iVerticalAlignment

The vertical alignment of the paragraph.

iWidowOrphan

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).

iWrap

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

iTextColor

The text color.

iHighlightColor

The text color used for selected text.

iHighlightStyle

The highlighting style.

iStrikethrough

The value of the strikethrough attribute.

iUnderline

The value of the underline attribute.

iHiddenText

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 .

iPictureAlignment

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();
    CleanupStack::PushL(pf);
    // Set the alignment
    pf->iHorizontalAlignment = CParaFormat::ECenterAlign;
    // Create paragraph formatting mask
    TParaFormatMask mask;
    // This alignment needs to be changed
    mask.SetAttrib(EAttAlignment);
    // 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
    cmask.SetAttrib(EAttColor);
    cmask.SetAttrib(EAttFontStrikethrough);
    // 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
    iEditor->HandleTextChangedL();
    }

The code will result in the following formatted text:

Auto-inserted


Auto-inserted

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
    {
    public:          
        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;
    
    protected:  
        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
    aGc.SetBrushColor(KRgbRed);
    aGc.SetBrushStyle(CGraphicsContext::ESolidBrush);
    aGc.DrawEllipse(area);
    }

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 ) );
    CleanupStack::PushL(picture);
    //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

EAknEditorTextInputMode

Text input.

EAknEditorNumericInputMode

Numeric input.

EAknEditorSecretAlphaInputMode

Secret text input.

EAknEditorAllInputModes

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

EAknEditorUpperCase

All text input is upper case.

EAknEditorLowerCase

All text input is lower case.

EAknEditorTextCase

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

EAknEditorAllCaseModes

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
               
iEditor->SetAknEditorAllowedInputModes(EAknEditorAllInputModes);

// Set the default input mode
iEditor->SetAknEditorInputMode(EAknEditorTextInputMode);
// Set allowed case modes
iEditor->SetAknEditorPermittedCaseModes(EAknEditorUpperCase);
// Set the default case mode
iEditor->SetAknEditorCase(EAknEditorUpperCase);

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

R_AVKON_SPECIAL_CHARACTER_TABLE_DIALOG

Default.

R_AVKON_URL_SPECIAL_CHARACTER_TABLE_DIALOG

URL addresses.

R_AVKON_EMAIL_ADDR_SPECIAL_CHARACTER_TABLE_DIALOG

E-mail addresses.

R_AVKON_CURRENCY_NAME_SPECIAL_CHARACTER_TABLE_DIALOG

Currency.

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()
  • R_AVKON_CURRENCY_NAME_SPECIAL_CHARACTER_TABLE_DIALOG
  • R_AVKON_EMAIL_ADDR_SPECIAL_CHARACTER_TABLE_DIALOG
  • R_AVKON_SPECIAL_CHARACTER_TABLE_DIALOG
  • R_AVKON_URL_SPECIAL_CHARACTER_TABLE_DIALOG

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

EAknEditorStandardNumberModeKeyMap

*, +, p, w

#

EAknEditorPlainNumberModeKeymap

EAknEditorCalculatorNumberModeKeymap

+, -, *, /

.

EAknEditorConverterNumberModeKeymap

+, -, E

.

EAknEditorToFieldNumberModeKeymap

+

;

EAknEditorFixedDiallingNumberModeKeymap

*, +, p, w

#

EAknEditorSATNumberModeKeymap

*, +

#

EAknEditorSATHiddenNumberModeKeymap

*

#

EAknEditorAlphanumericNumberModeKeymap

#

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

EkeepDocument

The EDWIN does not destroy its content on destruction.

ESegmentedStorage

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.

EWidthInPixels

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

ENoAutoSelection

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.

EJustAutoCurEnd

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

ENoWrap

Do not wrap the text being edited.

ELineCursor

Use a line cursor instead of a block cursor.

ENoHorizScrolling

Horizontal scrolling is disabled.

EInclusiveSizeFixed

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() .

EUserSuppliedText

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

EOwnsWindow

The EDWIN is a window-owning control.

EDisplayOnly

The EDWIN does not respond to user input.

EAlwaysShowSelection

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

EReadOnly

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

EAllowPictures

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.

EAllowUndo

Enable undo operations.

ENoLineOrParaBreaks

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

EOnlyASCIIChars

Allow only ASCII characters.

EResizable

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.

EIgnoreVirtualCursor

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

ENoCustomDraw

No custom draw is done.

EAvkonEditor

Changes layout to AVKON style.

EAvkonDisableCursor

Hides cursor.

EAvkonNotEditable

Changes text editor to non-editable mode.

EEdwinAlternativeWrapping

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

EAknEditorFlagFixedCase

Case changes are not allowed.

EAknEditorFlagNoT9

Predictive text entry is not allowed.

EAknEditorFlagNoEditIndicators

Editor indicators are not shown.

EAknEditorFlagNoLRNavigation

The cursor cannot be moved horizontally.

EAknEditorFlagSupressShiftMenu

Edit menu cannot be opened from edit key.

EAknEditorFlagEnableScrollBar

Enables scroll bars.

EAknEditorFlagMTAutoOverwrite

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

EAknEditorFlagUseSCTNumericCharmap

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.

EAknEditorFlagLatinInputModesOnly

Input language is changed to English locally in the editor.

EAknEditorFlagForceTransparentFepModes

Chinese find mode input.

EAknEditorFlagAllowEntersWithScrollDown

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.

EAknEditorFlagEnablePictographInput

Enables pictograph input.

EAknEditorFlagFindPane

Used internally by CAknSearchField.

Related APIs
  • AKN_EDITOR_EXTENSIONS
  • CEditableText::ESegmentedStorage
  • ConstructL()
  • EAknEditorFlagAllowEntersWithScrollDown
  • EAknEditorFlagEnablePictographInput
  • EAknEditorFlagEnableScrollBar
  • EAknEditorFlagFindPane
  • EAknEditorFlagFixedCase
  • EAknEditorFlagForceTransparentFepModes
  • EAknEditorFlagLatinInputModesOnly
  • EAknEditorFlagMTAutoOverwrite
  • EAknEditorFlagNoEditIndicators
  • EAknEditorFlagNoLRNavigation
  • EAknEditorFlagNoT9
  • EAknEditorFlagSupressShiftMenu
  • EAknEditorFlagUseSCTNumericCharmap
  • EAllowPictures
  • EAllowUndo
  • EAlwaysShowSelection
  • EAvkonDisableCursor
  • EAvkonEditor
  • EAvkonNotEditable
  • EDWIN
  • 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
              
iEditor1->SelectAllL();
// Cut the selected text
iEditor1->ClipboardL(CEikEdwin::ECut);
// Paste the contents of clipboard to the second text editor
iEditor2->ClipboardL(CEikEdwin::EPaste);
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
              
    {
    EEventFormatChanged,
    EEventNavigation,
    EEventTextUpdate
    };

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

Related APIs
  • CEikEdwin::SetEdwinObserver()
  • EDWIN
  • 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:

              
               STRUCT AVKON_INTEGER_EDWIN
               
    {   
    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;
    min=0;
    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 );
    CleanupStack::PopAndDestroy();
    iEditor->SetFocus( ETrue );
    SetRect( aRect );
    ActivateL();
    }

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
  • AVKON_INTEGER_EDWIN
  • CAknIntegerEdwin*
  • FIXPTED
  • FLPTED
  • 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
    CreateWindowL();
    // 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
    ActivateL();
    }

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
    CreateWindowL();
    // 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 );
    CleanupStack::PopAndDestroy();
    // Set focus
    iEditor->SetFocus( ETrue );
    SetRect( aRect );
    // Activate the container    
    ActivateL();
    }

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
  • NUMSECRETED
  • R_MY_NUMERIC_SECRET_EDITOR
  • SECRETED

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

NUMBER_EDITOR

CEikNumberEditor

Range editor

RANGE_EDITOR

CEikRangeEditor

Time editor

TIME_EDITOR

CEikTimeEditor

Date editor

DATE_EDITOR

CEikDateEditor

Time and date editor

TIME_AND_DATE_EDITOR

CEikTimeAndDateEditor

Duration editor

DURATION_EDITOR

CEikDurationEditor

Time offset editor

TIME_OFFSET_EDITOR

CEikTimeOffsetEditor

IP address editor

IP_FIELD_EDITOR

CAknIpFieldEditor

Location editor

LATITUDE_EDITOR/LONGITUDE_EDITOR

CAknLocationEditor

Unit editor

AVKON_UNIT_EDITOR

CAknUnitEditor

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
    CreateWindowL();
    // 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 );
    CleanupStack::PopAndDestroy();
    // Set focus
    iEditor->SetFocus( ETrue );
    SetRect( aRect );
    // Activate the container    
    ActivateL();
    }

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
  • AVKON_UNIT_EDITOR
  • CAknIpFieldEditor
  • CAknLocationEditor
  • CAknUnitEditor
  • CEikDateEditor
  • CEikDurationEditor
  • CEikNumberEditor
  • CEikRangeEditor
  • CEikTimeAndDateEditor
  • CEikTimeEditor
  • CEikTimeOffsetEditor
  • DATE_EDITOR
  • DURATION_EDITOR
  • IP_FIELD_EDITOR
  • LATITUDE_EDITOR/LONGITUDE_EDITOR
  • NUMBER_EDITOR
  • RANGE_EDITOR
  • TIME_AND_DATE_EDITOR
  • TIME_EDITOR
  • TIME_OFFSET_EDITOR

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
    CreateWindowL();
    // Call first phase constructor
    iEditor = new (ELeave)CEikDateEditor;
    // Set parent
    iEditor->SetContainerWindowL( *this );
    
    TDateTime dateTime;
    
    // Set the from date
    dateTime.SetYear(2006);
    dateTime.SetMonth( EJuly );//July
    dateTime.SetDay( 0 ); //1st day
    
    TTime fromTime( dateTime );
    
    // Set the to date
    dateTime.SetYear(2006);
    dateTime.SetMonth( EDecember );//July
    dateTime.SetDay( 30 ); //31st day
    
    TTime toTime( dateTime );
    
   //Set default date to current date
    
    TTime now;
    now.HomeTime();
    // 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    
    ActivateL();
    }

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

Glossary

Abbreviations

Editors API abbreviations

API Application Programming Interface

EDWIN

CEikEdwin based editor

ID

Identifier

MFNE

Multi-field Numeric Editor

OS

Operating System

Twip

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

Related APIs
  • CEikEdwin