S60平台UI资源——编辑框

此文摘译自SDK 3rd MR中：/9.1/S60_3rd_MR/S60Doc/s60_platform_avkon_ui_resources_editors_v1_1_en.pdf

 

S60平台的编辑框主要可以分为以下四类：
① Text editors
② Number editors
③ Secret editors
④ Multi-field numberic editors

① Text editors
文本编辑框可以允许一行或多行文本输入，有的编辑框不支持格式化文本，有的支持。可以把文本编辑框细分为三类：无格式编辑框(plain texteditors)、全局编辑框(global text editors)和富足(囧)编辑框(rich texteditors)。其中，plain不支持格式化文本；global支持所有文本的格式化，但不支持只格式化部分文本或段落；rich对格式化提供了全面的支持，并支持嵌入的非文本对象。

 

 

② Numberic eidtors
数字编辑框只允许用户输入单行数字，因数字不能跨越多行。数字编辑框可以细分为三类：整数编辑框(integer editors)、浮点数编辑框(floating-point editors)和定宽小数位数编辑框(fixed-point editors)。

③ Secret eidtors
密码编辑框是不支持格式化文本的，用于输入密码、PIN码等。有两种密码编辑框，一种支持输入文本和数字，另一种只支持输入数字。其中前者会短暂显示用户输入的字符，然后转变成(*)星号。

 

④ 多域数字编辑框
多域数字编辑框(MFNE)是多个数字编辑域的组合。用来输入时间、日期和IP地址等。按用途可将其分为八类：数字编辑框、范围编辑框、时间编辑框、日期编辑框、时间和日期编辑框、持续时间编辑框、时间偏差编辑框和IP地址编辑框。

 

下面着重介绍如何创建使用这些编辑框：

创建编辑框控件跟创建其他控件相似。可以通过加载资源定义创建或运行时动态创建，下面将介绍这两种方式。
Plain Text Editor资源结构
文本编辑框资源是作为EDWIN结构定义的，EDWIN在eikon.rh中定义，如下：
STRUCT EDWIN
{
        LONG flags=0;
        WORD width=0;
        WORD lines=1;
        WORD maxlength=0;
        AKN_EDITOR_EXTENSIONS
}

下面介绍结构详情：
flags标示了编辑框的属性，它在CEikEdwin::TFlags中定义，这里赘述一下：
EZeroEnumValue  
EKeepDocument If set, CEikEdwin does not destroy its content on destruction.
ESegmentedStorage If set, the content buffer uses segmented storage (see CEditableText::ESegmentedStorage).
EWidthInPixels The size specified in the resource used to construct the object is given in pixels, not character widths.
ENoAutoSelection No automatic selection takes place.
Normally the entire text is selected whenever the Edwin is created, resized or has its text set as one operation.

EJustAutoCurEnd If set, then whenever the control is activated the cursor is moved to the end of the text.
ENoWrap Does not wrap the text being edited.
ELineCursor Uses a line cursor instead of a block cursor.
ENoHorizScrolling Does not perform horizontal scrolling.
EInclusiveSizeFixed If set, scroll bars required to edit long documents appear inside the Edwin.
This reduces the area used to display the Edwin.

If not set, scroll bars appear outside the Edwin.

EUserSuppliedText Sets the Edwin’s height according to the number of lines of text supplied by the user.
EOwnsWindow The Edwin is a window-owning control.
EDisplayOnly The Edwin does not respond to input at all.
EAlwaysShowSelection Does not hide the selection if the Edwin loses focus.
EReadOnly The Edwin is read-only so users cannot add text to any document it displays.
A user attempt to add text results in a message to notify them that the Edwin is read-only.

EAllowPictures If set, no special attempt to delete embedded pictures cleanly will be made.
This flag does not apply to Edwins which do not edit rich text.

EAllowUndo The Edwin supports undo operations.
ENoLineOrParaBreaks Does not allow line or paragraph breaks in the text being edited.
EOnlyASCIIChars Allows only ASCII characters.
EResizable The Edwin is resizable.
EIgnoreVirtualCursor The Edwin ignores 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 Avkon wrapping rules ON.

Width标识了控件的宽度。宽度可由字符或像素标识，这取决于flags中是否指定了EWidthInPixels属性，如果是按字符定宽度，那选定字体中的最宽字符决定了控件宽度(就是最宽字符的宽度*Width)。

Lines标识了编辑框的文本行数。
maxlength标识了编辑框允许存储的最大字符个数。

AKN_EDITOR_EXTENSIONS定义了更多的属性，其中的细节可以参照eikon.hrh中的介绍，属性列举如下：
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;

这里简单介绍下各个属性的意义。
default_case 编辑框默认输入大小写
allowed_case_modes 允许的输入大小写
numeric_keymap 数字输入法下，允许的映射(主要是指按*键弹出哪些字符)。
allowed_input_modes 允许的输入法
default_input_mode 默认的输入法
special_character_table 特殊字符表
avkon_flags 其他属性标志

Global和Rich编辑框资源结构
Global编辑框是由资源结构GTXTED定义的，GTXTED结构在eikon.rh中定义，如下：
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
}

Rich编辑框是由资源结构RTXTED定义的，RTXTED结构在eikon.rh中定义，如下：
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
}
跟EDWIN相比，Global和Rich编辑框多了一些属性，它们的含义如下：
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.

 

数字编辑框资源结构
整数编辑框资源是由AVKON_INTEGER_EDWIN定义的，AVKON_INTEGER_EDWIN定义如下：
STRUCT AVKON_INTEGER_EDWIN
{
        WORD maxlength = 0;
        LONG min = -99999999;
        LONG max = 99999999;
        LONG unset_value= -100000000;
        LLINK extension1 = 0;
        LLINK extension2 = 0;
}
结构中域的含义很容易理解，其中unset_value是默认值。

Fixed-Point编辑框资源是由FIXPTED定义的，FIXPTED定义如下：
STRUCT FIXPTED
{
        WORD decimalplaces=2;
        LONG min;
        LONG max;
        LONG default=0;
}
其中，decimalplaces指定了允许的小数位数。

Floating-Point编辑框资源是由FLPTED定义的，FLPTED定义如下：
STRUCT FLPTED
{
        WORD maxlength=18;
        DOUBLE min=-9.9e99;
        DOUBLE max=9.9e99;
        DOUBLE default=0;
}

Multiple-Field Numeric编辑框资源结构

下面以日期编辑框示例资源定义：
RESOURCE DATE_EDITOR r_date_editor
{
        minDate = DATE
        {
                day = 1;
                month = 7;
                year = 2004;
        };
        maxDate = DATE
        {
                day = 31;
                month = 12;
                year = 2004;
        };
}

密码编辑框
数字密码编辑框由资源NUMSECRETED定义，数字文本密码编辑框由资源SECRETED资源定义

。
RESOURCE NUMSECRETED r_my_num_secret_editor
{
        num_code_chars = 4;
}
RESOURCE SECRETED r_my_secret_editor
{
        num_letters = 10;
}
文本数字编辑框对应的类为CEikSecretEditor， 数字密码编辑框对应的类为

CAknNumericSecretEditor(继承自CEikSecretEditor)。

下面介绍如何使用资源创建编辑框：
下面的代码示例了如何使用资源创建一个Plain文本编辑框：
// Create an instance of CEikEdwin
iEditor = new (ELeave) CEikEdwin;

// Set the container window
iEditor->SetContainerWindowL(*this);

// Set up the resource reader
TResourceReader reader;
CCoeEnv::Static()->CreateResourceReaderLC(reader, R_PLAINTEXTEDITOR);

// Call second phase constructor
iEditor->ConstructFromResourceL(reader);
CleanupStack::PopAndDestroy();

// Activate editor control
iEditor->ActivateL();

下面介绍如何不使用资源创建编辑框：
下面的代码示例了如何不使用资源创建一个Plain文本编辑框：
// Create an instance of CEikEdwin
iEditor = new (ELeave) CEikEdwin;

// Set the container window
iEditor->SetContainerWindowL(*this);

// Call second phase constructor
iEditor->ConstructL();

// Activate editor control
iEditor->ActivateL();

文本和文本属性

编辑框的文本存储在一个CEditableText对象或它的子类对象中。下面介绍如何操作编辑框内容和如何格式化编辑框文本。

选中的文本
API中处理选中文本很简单，CEikEdwin中有五个相关方法：
SelectionLength() ： 获取选中文本长度
Selection()： 获取选中文本的位置
ClearSelectionL()： 清除选中文本
SetSelectionL()： 选中部分文本
SelectAllL()： 选中全部文本

下面代码示例如何删除选中文本：
// Get selection position
TCursorSelection pos = iEditor->Selection();

// Get text contents
CPlainText* text = iEditor->Text();

// Remove the selected text
text->DeleteL(pos.LowerPos(), pos.Length());

格式化
格式化有两种级别：段落格式化和字符格式化。段落格式化是通过类CParaFormat操作的，对Global编辑框而言，所有段落都假设使用同一种格式化风格；对Rich编辑框而言，可以对每个段落使用格式化风格。字符格式化使用类TCharFormat。

段落格式化CParaFormat中的属性如下：

 

字符格式化可以通过TCharFormat中的iFontPresentation来指定

CParaFormat和TCharFormat必须分别配合TParaFormatMask和TCharFormatMask这两个类才能起作用。
下面示例段落格式化用法：
// 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::Pop(); // pf

下面示例字符格式化用法：
// 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);