aeetext.h

BREW SDK 3.1。BREW应用程序的开发包。

See Also:
    AEETextInputModeInfo

=============================================================================

ITEXTCTL_GetProperties()

Description:
    This function returns the text control-specific properties or flags.

Prototype:
    uint32 ITEXTCTL_GetProperties(ITextCtl * pITextCtl)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.

Return Value:
    32-bit properties for the text control.
    Following properties are returned by the text control object:~
~
    TP_MULTILINE, if set, text control object is multiple line control.~
    TP_FRAME, if set, text control object has a frame.~
    TP_T9_MODE, if set, text control object is in T9 mode.~
    TP_FIXSETRECT, if set, the actual height more closely represents requested height.~
*

Comments:
    None

Version:
   Introduced BREW Client 1.0

See Also:
    ITEXTCTL_SetProperties()

=============================================================================

ITEXTCTL_GetPropertiesEx()

Description:
    This function returns the extended text control-specific properties or flags.

Prototype:
    uint32 ITEXTCTL_GetPropertiesEx(ITextCtl * pITextCtl)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.

Return Value:
    32-bit properties for the text control.
    Following properties are returned by the text control object:~
~
    Placeholder, No Extended Properties at this time.
*

Comments:
    None

Version:
   Introduced BREW Client 3.1.3

See Also:
    ITEXTCTL_SetPropertiesEx()
    ITEXTCTL_SetProperties()
    ITEXTCTL_GetProperties()

=============================================================================

ITEXTCTL_GetRect()

Description:
    This function fills given pointer to AEERect with the coordinates of the current
bounding rectangle size only for text, not title. This is particularly useful after
a control is created to determine its optimal/default size and position.
    NOTE:
    If the property TP_FIXSETRECT is set, this function fills the AEERect with the
actual bounding rectangle of the control, which is not necessarily the rectangle
passed in ITEXTCTL_SetRect().
    If the property TP_FIXSETRECT is NOT set, this function returns the rectangle
that was passed in to ITEXTCTL_SetRect().

Prototype:
    void ITEXTCTL_GetRect(ITextCtl * pITextCtl, AEERect * prc)

Parameters:
    pITextCtl :  Pointer to the ITextCtl Interface object.
    prc  :  Rectangle to be filled with the coordinates of the text control object.

Return Value:
    None

Comments:
    None

Version:
   Introduced BREW Client 1.0

See Also:
    AEERect
    ITEXTCTL_SetRect()

=============================================================================

ITEXTCTL_GetSelection()

Description:
    This function gets the selected text.

Prototype:
    uint32 ITEXTCTL_GetSelection(ITextCtl * pITextCtl, uint32 dwSel)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.

Return Value:
    Double word indicating the selection positions. ~
	The lower word is for selection start. ~
    The upper word is for selection end.

Comments:
    If there is no selection the start position will equal the end position where the cursor
    currently is. The start and end will have a value equal to ITEXTCTL_GetCursorPos(). 
    
    The selection takes the cursor position into consideration, the selection start value
    will be less than the selection end when the cursor is at the beginning of the selection. 
    If a key that is handled by the current input mode is handled by the text control a 
    selection will be erased and replaced by the character chosen by that input mode. 
    A call to ITEXTCTL_SetCursorPos() will unselect the selection without removing characters. 
    A call to ITEXTCTL_SetSelection() will change the selection and will not remove the 
    characters of an existing selection.

    You can use the helper macros to get the selection values: .
    TC_SEL_GET_START(dw) - Gets the Selection Start Value
    TC_SEL_GET_END(dw) - Gets the Selection End Value

Version:
   Introduced BREW Client 3.1.3
   Text Control 2

See Also:
    ITEXTCTL_SetSelection()
    ITEXTCTL_SetCursorPos()
    ITEXTCTL_GetCursorPos()

=============================================================================

ITEXTCTL_GetText()

Description:
    This function is used to read text associated with the ITextCtl Interface object
in the given buffer subject to the maximum of nMaxChars.

Prototype:
    boolean ITEXTCTL_GetText
    (
    ITextCtl * pITextCtl,
    AECHAR * pBuffer,
    unsigned int nMaxChars
    )

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    pBuffer  :  Placeholder for the text.
    nMaxChars  :  Maximum number of characters to be read.

Return Value:
    TRUE: if successful.
    FALSE: if unsuccessful.

Comments:
    None

Version:
   Introduced BREW Client 1.0

See Also:
    ITEXTCTL_GetTextPtr()

=============================================================================

ITEXTCTL_GetTextPtr()

Description:
    It returns the pointer to the text maintained by the ITextCtl object. The difference
between this function and GetText is that latter copies the content to a destination
buffer, and the former just returns the pointer to the text inside the ITextCtl
object.

Prototype:
    AECHAR * ITEXTCTL_GetTextPtr(ITextCtl * pITextCtl)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.

Return Value:
    Pointer to the text buffer of the test control object

Comments:
    None

Version:
   Introduced BREW Client 1.0

See Also:
    ITEXTCTL_GetText()

=============================================================================

ITEXTCTL_HandleEvent()

Description:
    This function is used to handle the events received by text control object.
If the text control object is in non edit mode, it processes only set title, set
text, and the pressing the UP and DOWN key events. In text edit mode, it processes
various events like key up, key down, key held, set title, set text, command event
from the soft key menu.

Prototype:
    boolean ITEXTCTL_HandleEvent
    (
    ITextCtl * pITextCtl,
    AEEEvent evt,
    uint16 wp,
    uint32 dwp
    )

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    evt  :  Event code.
    wp  :  16-bit event data.
    dwp  :  32-bit event data.

Return Value:
    TRUE: if the event was processed by the text control.~
    FALSE: if otherwise.

Comments:
    If a grapheme is present in the text a key navigation event may cause the cursor to 
    move more than one position to align itself per grapheme boundary.

    If your app is compiled with BREW 3.1.3, the symbols that appear when AVK_1 is pressed
    may differ from the prior implementation. If you wish to preserve the older symbol list
    while using the new text control, you may use TP_OLD_MT_CHARS with ITEXTCTL_SetProperties().

Version:
   Introduced BREW Client 1.0

See Also:
    ITEXTCTL_SetProperties()

=============================================================================

ITEXTCTL_IsActive()

Description:
    This function returns the active state of the text control object.

Prototype:
    boolean ITEXTCTL_IsActive(ITextCtl * pITextCtl)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.

Return Value:
    TRUE: if the text control is active.~
    FALSE: if otherwise.

Comments:
    None

Version:
   Introduced BREW Client 1.0

See Also:
    None

=============================================================================

ITEXTCTL_Redraw()

Description:
    This function instructs the text control object to redraw its contents. The
ITextCtl Interface object does not redraw its contents every time the underlying
data behind the text control changes. This allows several data updates to occur
while minimizing screen flashes. For example, several changes can be made to the
contents of the text control object with no visible effect until ITEXTCTL_Redraw()
function is called.

Prototype:
    boolean ITEXTCTL_Redraw(ITextCtl * pITextCtl)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.

Return Value:
    TRUE: if the text control was redrawn.
    FALSE: if otherwise.

Comments:
    None

Version:
   Introduced BREW Client 1.0

See Also:
    None

=============================================================================

ITEXTCTL_Release()

Description:
    This function is inherited from IBASE_Release(). 

Version:
   Introduced BREW Client 1.0

See Also:
   ITEXTCTL_AddRef()

=============================================================================

ITEXTCTL_Reset()

Description:
    This function instructs the text control to reset (free/delete) its contents
and to immediately leave active/focus mode.

Prototype:
    void ITEXTCTL_Reset(ITextCtl * pITextCtl)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.

Return Value:
    None

Comments:
    None

Version:
   Introduced BREW Client 1.0

See Also:
    ITEXTCTL_SetActive()

=============================================================================

ITEXTCTL_SetActive()

Description:
    This function is used to make a text control object active. Only an active text
control object handles the event sent to it. Inactive text control object just ignores
the events. Also an inactive text control object does not draw its frame.

Prototype:
    void ITEXTCTL_SetActive(ITextCtl * pITextCtl, boolean bActive)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    bActive  :  Boolean flag that specifies:
    TRUE: to activate the text control object.
    FALSE: to deactivate the text control object.

Return Value:
    None

Comments:
    If your applet is compiled with BREW 3.1.3 or later, a call to activating the control
    will set a selection over the entire text. This will occur whether the control had been 
    active or not prior to the call. To preserve the older behavior of not selecting the text
    you may set the TP_FOCUS_NOSEL property with ITEXTCTL_SetProperties().