aeetext.h

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

Version:
   Introduced BREW Client 1.0

See Also:
    ITEXTCTL_SetProperties()

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

ITEXTCTL_SetCursorPos()

Description:
    This function is used to set the position of a cursor in a text control object.
You can use the following defines for nOffset to place the text at the start or
end.

Prototype:
    void ITEXTCTL_SetCursorPos(ITextCtl * pITextCtl, int32 nOffset)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object
    nOffset  :  Placement of the text object
    TC_CURSOREND - Place the cursor at the end of the text.
    TC_CURSORSTART - Place the cursor at the beginning of the text.

Return Value:
    None

Comments:
    If nOffset is < 0 the cursor is placed at the beginning of the text.
    If nOffset is > the Length of the text, the cursor is placed at the end of the
text

  If you set the character position between an element of a grapheme, the position
  will be updated such that it is in the next available character position after the 
  complete grapheme. This means that a subsequent call to ITEXTCTL_GetCursorPos() will not 
  necessarily match the value passed to this function. A grapheme is all the characters 
  that compose a complete symbol in a language such as Thai.

Version:
   Introduced BREW Client 2.0

See Also:
    ITEXTCTL_GetCursorPos()

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

ITEXTCTL_SetInputMode()

Description:
    This function allows the caller to set the selected text input mode.

Prototype:
    AEETextInputMode ITEXTCTL_SetInputMode
    (
    ITextCtl * pITextCtl,
    AEETextInputMode wMode
    )

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    wMode :  Text input mode.

Return Value:
    An enum of type AEETextInputMode to indicate the input mode set.

Comments:
    None

Version:
   Introduced BREW Client 1.0

See Also:
    AEETextInputMode

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

ITEXTCTL_SetMaxSize()

Description:
    This function is used to set the maximum text size supported by the text control
object. If the size being set is more than the size already set, this leads to the
freeing up of the memory associated with the previous size and allocation of the
memory per the new size.

Prototype:
    void ITEXTCTL_SetMaxSize (ITextCtl * pITextCtl, uint16 nMaxSize)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    nMaxSize  :  Maximum text size in AECHAR characters excluding NULL and if 0
(zero) then no effect.

Return Value:
    None

Comments:
    The implementation of this function may vary between devices. Some devices may
allow text to be entered beyond the maximum size set by this function.

Version:
   Introduced BREW Client 1.0

See Also:
    None

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

ITEXTCTL_SetProperties()

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

Prototype:
    void ITEXTCTL_SetProperties(ITextCtl * pITextCtl, uint32 dwProps)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    dwProps  :  32-bit set of flags/properties.

    Following properties are used for 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.


Return Value:
    None

Comments:
    None

Side Effects:
    It deactivates the text control.

Version:
   Introduced BREW Client 1.0

See Also:
    ITEXTCTL_GetProperties()

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

ITEXTCTL_SetPropertiesEx()

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

Prototype:
    void ITEXTCTL_SetPropertiesEx(ITextCtl * pITextCtl, uint32 dwProps)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    dwProps  :  32-bit set of flags/properties.
    PlaceHolder: No Extended Properties at this time.

Return Value:
    None

Comments:
    None

Side Effects:
    None

Version:
   Introduced BREW Client 3.1.3

See Also:
    ITEXTCTL_GetPropertiesEx()
    ITEXTCTL_SetProperties()
    ITEXTCTL_GetProperties()

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

ITEXTCTL_SetRect()

Description:
    This function fills the AEERect data structure with the coordinates of the current
bounding rectangle to determining the size of the text, not the 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 data structure
with the actual bounding rectangle of the control, which may not be the rectangle
set using ITEXTCTL_SetRect().
    If the property TP_FIXSETRECT is NOT set, this function returns the AEERect
data structure which contains the coordinates of rectangle set using ITEXTCTL_SetRect().

Prototype:
    void ITEXTCTL_SetRect(ITextCtl * pITextCtl, const AEERect * prc)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    prc  :  Bounding rectangle for the text control object.

Return Value:
    None

Comments:
    By default, the control rectangle of the text control object has a device screen
width as width and (device screen height - text height) as height starting from
the upper left corner.

Version:
   Introduced BREW Client 1.0

See Also:
    AEERect
    ITEXTCTL_GetRect()

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

ITEXTCTL_SetSelection()

Description:
    This function sets a selection over the given character positions. 
    The selection will be an inverse of the foreground and background colors.

Prototype:
    void ITEXTCTL_SetSelection(ITextCtl * pITextCtl, uint32 dwSel)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    dwSel  :  Lower word is for selection start. Upper word for selection end.

Return Value:
    None

Comments:
    The selection is bound by the start and end of the text string. Any region
    beyond the end of the text string will be ended at the end of the string. The
    cursor will be placed at the selection end position. When the start position is equal
    to the ending position, there will be no selection it will take a similar action to 
    ITEXTCTL_SetCursorPos(). 
    
    If you want the cursor to be at the beginning of the selection, the selection start value
    should be less than the selection end. 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.

    If you set the selection position between an element of a grapheme, the position
    will be updated such that it is in the next available character position after the 
    complete grapheme.

    You can use the helper macros to set the selection: .
    TC_SEL_START - Macro to use the start of the text string
    TC_SEL_END - Macro to use the end of the text String
    TC_MAKE_SEL(s,e):
       s - Selection Start
       e - Selection End

Version:
   Introduced BREW Client 3.1.3
   Text Control 2

See Also:
    ITEXTCTL_GetSelection()
    ITEXTCTL_SetCursorPos()
    ITEXTCTL_GetCursorPos()

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

ITEXTCTL_SetSoftKeyMenu()

Description:
    This function replaces the existing Soft Key menu of the text control object
with the specified menu control object.

Prototype:
    void ITEXTCTL_SetSoftKeyMenu(ITextCtl * pITextCtl, IMenuCtl * pm)

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    pm  :  New menu control object for the soft key menu.

Return Value:
    None

Comments:
    None

Side Effects:
    IMenuCtl抯 reference count is bumped up and a new menu item is added to the
menu if an entry mode string is maintained by the text manager.

Version:
   Introduced BREW Client 1.0

See Also:
    None

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

ITEXTCTL_SetText()

Description:
    This function is used to assign given string as text of the text control object.

Prototype:
    boolean ITEXTCTL_SetText
    (
    ITextCtl * pITextCtl, 
    const AECHAR * psz,
    int cch
    )

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    psz  :  Text string to be set.
    cch  :  Number of AECHAR characters to be assigned from the string to the text
of the text control object. If cch is negative or greater than the length of psz
string, then the length of string is used. 

Return Value
    None

Comments:
    None

Version:
   Introduced BREW Client 1.0

See Also:
    None

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

ITEXTCTL_SetTitle()

Description:
    This function is used to set title of a text control object. If pText is not
NULL, it sets the string specified by pText as the title of the text control object.
If pText is NULL, it reads title string corresponding to the given resource identifier
from resource file and sets it as the title of the text control object.

Prototype:
    boolean ITEXTCTL_SetTitle
    (
    ITextCtl * pITextCtl,
    const char * pszResFile,
    uint16 wResID,
    AECHAR * pText
    )

Parameters:
    pITextCtl  :  Pointer to the ITextCtl Interface object.
    pszResFile  :  File containing resource string.
    wResID  :  Resource identifier.
    pText  :  NULL-terminated title string.

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

Comments:
    None

Side Effects:
    If pText is NULL and pszResFile, WResID are valid, this function assigns the
text control object title string to pText.

Version:
   Introduced BREW Client 1.0

See Also:
    None

===========================================================================*/