Editors API Specification
Changes in Editors API documentation
Changes in Editors API
PurposeNearly 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 informationEditors API is an SDK API and part of S60 3rd Edition, Feature Pack 1.
Editor typesThe family of editor controls available is divided into four
main categories, which represent different needs for text input, display,
and manipulation. The categories are:
These categories are described in more detail in the following sections.
Text editorsText 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.
Numeric editorsNumeric 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.
Secret editorsSecret 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.
Multi-field numeric editorsThe 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.
Related APIs
API descriptionThe 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
-
Performing basic plain text manipulation through
CEikEdwin based
editors
-
Constructing global text editors and rich text editors
-
Performing advanced text manipulation
-
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
-
Retrieving the content of a numeric editor
-
Constructing secret editors
-
Retrieving the content of a secret editor
-
Constructing MFNE editors
-
Retrieving the content of a MFNE editor
Related APIs
API class structureAll 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 .
Related APIs
CEikEdwin CEikGlobalTextEditor CEikMfne CEikRichTextEditor CGlobalText CGobalText CPicture CPlainText CRichText
Using the Editors APIThis 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 fileA 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 codeAnother 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 practicesThe 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 editorsWhen 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
fileGlobal 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 codeWhen 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 manipulationThe 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 selectionText 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 formatThe 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 formatsIn 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:
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 objectsThe 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
Related APIs
Setting and getting the cursor position of CEikEdwin -based editorsAnother 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 caseText 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 tablesMany 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 mapsNumeric 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 propertiesThere 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 editorsThe 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
Observing events from CEikEdwin -based editorsTo 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 filesThe 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 10decimalplaces 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 codeA 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
Retrieving the content of a Numeric editorThe 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 editorsSecret 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 editorUse 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 editorsMFNE 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 resourceThe 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 codeNow 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 editorThe 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
Error handlingEditors 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 overheadMemory 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 APIThis 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
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|