#ifndef AEETEXT_H
#define AEETEXT_H
/*=====================================================================
FILE:  AEEText.h

SERVICES:  AEE Text Control Interface

DESCRIPTION: Base level definitions, typedefs, etc. for AEE Text Control

PUBLIC CLASSES: Not Applicable

INITIALIZATION AND SEQUENCING REQUIREMENTS: Not Applicable
        
        Copyright © 1999-2002 QUALCOMM Incorporated.
               All Rights Reserved.
            QUALCOMM Proprietary/GTDR
=====================================================================*/

//---------------------------------------------------------------------
// Include Files
//---------------------------------------------------------------------

#include "AEE.h"
#include "AEEMenu.h"

//---------------------------------------------------------------------
// Type Declarations
//---------------------------------------------------------------------

typedef struct _ITextCtl ITextCtl;

#define TP_FRAME           0x00010000
#define TP_MULTILINE       0x00020000
#define TP_RAPID_MODE      0x00080000  // Supports Rapid Entry and uses as default
#define TP_NODRAW          0x00100000  // Disables all drawing by the control
#define TP_NOUPDATE        0x00200000  // Disables wasteful IDISPLAY_Update calls
#define TP_PASSWORD        0x00400000  // Displays ***, manages correct buffer chars
#define TP_INTEGRALHEIGHT  0x00800000
#define TP_FIXSETRECT      0x80000000  // Actual height more closely represents requested height.
#define TP_FIXOEM          0x40000000  // Fixes control content bugs related to OEM implementation

#define TP_T9_MODE      (TP_RAPID_MODE)

#define MAX_TEXT_MODE_SIZE 15       // Maximum text mode name size


// Pre-Defined Text Modes - For use with ITEXTCTL_SetMode

#define AEE_TM_NONE           0x0000
#define AEE_TM_CURRENT        0x0001
#define AEE_TM_SYMBOLS        0x0002
#define AEE_TM_LETTERS        0x0003
#define AEE_TM_RAPID          0x0004
#define AEE_TM_NUMBERS        0x0005

#define AEE_TM_MAX            AEE_TM_NUMBERS
#define AEE_TM_USER           AEE_TM_MAX + 1
#define AEE_TM_FIRST_OEM      AEE_TM_USER     // OEM added modes should start at this value
// Add for ATOK [S]
#define AEE_TM_KANJI          AEE_TM_FIRST_OEM + 0
#if 1 /* FOR_PTX_633 */
#define AEE_TM_HANKAKU_KANA   (AEE_TM_KANJI + 1)
#endif /* FOR_PTX_633 */

#define AEE_TM_RESERVED       0x7000          // 0x7000 and up are reserved for BREW
#define AEE_TM_RESERVE_LAST   AEE_TM_RESERVED

typedef int AEETextInputMode;

typedef struct _AEETextInputModeInfo
{
   AEETextInputMode  tmMode;
   AECHAR            modeString[MAX_TEXT_MODE_SIZE];
} AEETextInputModeInfo;


// Defines for cursor position
#define TC_CURSOREND    0x7FFFFFFF
#define TC_CURSORSTART  0

//---------------------------------------------------------------------
// Global Constant Declarations
//---------------------------------------------------------------------
//---------------------------------------------------------------------
// Global Data Declarations
//---------------------------------------------------------------------

//=====================================================================
// FUNCTION DECLARATIONS AND INLINE FUNCTION DEFINITIONS
//=====================================================================
//---------------------------------------------------------------------
// ITextCtl Interface
//---------------------------------------------------------------------

QINTERFACE(ITextCtl)
{
   DECLARE_IBASE(ITextCtl)

   DECLARE_ICONTROL(ITextCtl)

   boolean           (*SetTitle)(ITextCtl * pITextCtl, const char * pszResFile, uint16 wResID, AECHAR * pText);
   boolean           (*SetText)(ITextCtl * pITextCtl, const AECHAR * psz, int cch);
   boolean           (*GetText)(ITextCtl * pITextCtl, AECHAR * pBuffer, int nMaxChars);
   AECHAR *          (*GetTextPtr)(ITextCtl * pITextCtl);
   void              (*EnableCommand)(ITextCtl * pITextCtl, boolean bEnable, uint16 nCmdId);
   void              (*SetMaxSize)(ITextCtl * pITextCtl, uint16 nMaxSize);
   void              (*SetSoftKeyMenu)(ITextCtl * pITextCtl, IMenuCtl * pm);
   AEETextInputMode  (*SetInputMode)(ITextCtl * po, AEETextInputMode m);
   int32             (*GetCursorPos)(ITextCtl *po);
   void              (*SetCursorPos)(ITextCtl *po, int32 nOffset);
   AEETextInputMode  (*GetInputMode)(ITextCtl *po, AEETextInputModeInfo * pmInfo);
   void              (*EnumModeInit)(ITextCtl *po);
   AEETextInputMode  (*EnumNextMode)(ITextCtl *po, AEETextInputModeInfo * pmInfo);
};

//---------------------------------------------------------------------
// Access Macros
//---------------------------------------------------------------------

#define ITEXTCTL_AddRef(p)                            GET_PVTBL(p,ITextCtl)->AddRef(p)
#define ITEXTCTL_Release(p)                           GET_PVTBL(p,ITextCtl)->Release(p)
#define ITEXTCTL_HandleEvent(p,ec,wp,dw)              GET_PVTBL(p,ITextCtl)->HandleEvent(p,ec,wp,dw)
#define ITEXTCTL_Redraw(p)                            GET_PVTBL(p,ITextCtl)->Redraw(p)
#define ITEXTCTL_SetActive(p,b)                       GET_PVTBL(p,ITextCtl)->SetActive(p,b)
#define ITEXTCTL_IsActive(p)                          GET_PVTBL(p,ITextCtl)->IsActive(p)
#define ITEXTCTL_SetRect(p,prc)                       GET_PVTBL(p,ITextCtl)->SetRect(p,prc)
#define ITEXTCTL_GetRect(p,prc)                       GET_PVTBL(p,ITextCtl)->GetRect(p,prc)
#define ITEXTCTL_SetProperties(p,props)               GET_PVTBL(p,ITextCtl)->SetProperties(p,props)
#define ITEXTCTL_GetProperties(p)                     GET_PVTBL(p,ITextCtl)->GetProperties(p)
#define ITEXTCTL_Reset(p)                             GET_PVTBL(p,ITextCtl)->Reset(p)
#define ITEXTCTL_SetTitle(p,pr,rid,pt)                GET_PVTBL(p,ITextCtl)->SetTitle(p,pr,rid,pt)
#define ITEXTCTL_SetText(p,psz,cch)                   GET_PVTBL(p,ITextCtl)->SetText(p,psz,cch)
#define ITEXTCTL_GetText(p,pbuf,max)                  GET_PVTBL(p,ITextCtl)->GetText(p,pbuf,max)
#define ITEXTCTL_GetTextPtr(p)                        GET_PVTBL(p,ITextCtl)->GetTextPtr(p)
#define ITEXTCTL_EnableCommand(p,ben,id)              GET_PVTBL(p,ITextCtl)->EnableCommand(p,ben,id)
#define ITEXTCTL_SetMaxSize(p,s)                      GET_PVTBL(p,ITextCtl)->SetMaxSize(p,s)
#define ITEXTCTL_SetSoftKeyMenu(p,pm)                 GET_PVTBL(p,ITextCtl)->SetSoftKeyMenu(p,pm)
#define ITEXTCTL_SetInputMode(p,m)                    GET_PVTBL(p,ITextCtl)->SetInputMode(p,m)
#define ITEXTCTL_GetCursorPos(p)                      GET_PVTBL(p,ITextCtl)->GetCursorPos(p)
#define ITEXTCTL_SetCursorPos(p,n)                    GET_PVTBL(p,ITextCtl)->SetCursorPos(p,n)
#define ITEXTCTL_GetInputMode(p,m)                    GET_PVTBL(p,ITextCtl)->GetInputMode(p,m)
#define ITEXTCTL_EnumModeInit(p)                      GET_PVTBL(p,ITextCtl)->EnumModeInit(p)
#define ITEXTCTL_EnumNextMode(p,i)                    GET_PVTBL(p,ITextCtl)->EnumNextMode(p,i)

#endif    // AEETEXT_H
/*============================================================================
   DATA STRUCTURE DOCUMENTATION
==============================================================================
AEETextInputMode

Description:
This enumerated type specifies the text-entry modes that can be used to enter text
into a text control. The function ITEXTCTL_SetInputMode() is used to select the
input mode that is used for a particular text control instance.

Definition:
typedef enum 
{
   AEE_TM_NONE,
   AEE_TM_CURRENT,
   AEE_TM_SYMBOLS,
   AEE_TM_LETTERS,
   AEE_TM_RAPID,
   AEE_TM_NUMBERS
} AEETextInputMode;

Members:
 
AEE_TM_NONE: No input mode is currently specified. The default mode is Multitap.
AEE_TM_CURRENT: Designates the currently active input mode.
AEE_TM_SYMBOLS: Key presses will enter the special symbol (if any) associated with
each key.
AEE_TM_LETTERS: Key presses will enter the letter of the alphabet associated with
each key.
AEE_TM_RAPID: Rapid (T9) mode will be used.
AEE_TM_NUMBERS: Key presses will enter the number associated with each key.


Comments:
The available text entry modes differ with each BREW-enabled device.

See Also:
ITEXTCTL_SetInputMode()

=====================================================================
AEETextInputModeInfo

Description:
This structure contains the an AEETextInputMode and a buffer to hold the 
string that is associated with that mode to be filled when using the 
ITEXTCTL_GetInputMode API.

Definition:
typedef struct _AEETextInputModeInfo
{
   AEETextInputMode  tmMode;
   AECHAR            modeString[MAX_TEXT_MODE_SIZE];
} AEETextInputModeInfo;

Members:
 
Members:
 
   tmMode;	            Text Mode enum entry
   modeString;	         String that is associated with the mode

Comments:
The available text entry modes differ with each BREW-enabled device.

See Also:
ITEXTCTL_GetInputMode(), AEETextInputMode

=====================================================================
AEE ITextCtl Properties

Description:: These are the properties defined for ITextCtl Interface .

Definition::  
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_NODRAW:     If set, text control object does not draw itself
TP_NOUPDATE:   If set, text control object does not call IDIPLAY_Update when not needed
TP_PASSWORD:   If set, text control will display * characters in place of real characters

Members:
None

Comments
When using TP_PASSWORD and using standard Text methods, you will get actual inputted text
and not the *** used to hide actual text.

See Also:
ITEXTCTL_SetProperties(), ITEXTCTL_GetProperties() 

=====================================================================
   INTERFACE DOCUMENTATION
=======================================================================

Interface Name: ITextCtl

Description: 
    A text control enables the device user to enter a string of text 
using the keys on the device. The text control consists of an optional 
title and a rectangular window containing one or more lines in which 
the entered text is displayed to the user. The text control handles 
the translation of user key presses into characters, so your application 
only needs to pass keypress events to the text control while it is 
active and retrieve the text from the control when user text entry 
has completed. The translation process depends on the text entry 
modes the device supports (for example, the standard multi-tap mode 
in which the user selects from the characters mapped to each key, 
and Tegic's T9 predictive text input mode). If more than one text 
entry mode is supported, your application should make it possible 
for the user to select the desired mode while the text control is 
active. The text control allows you to specify a softkey menu that 
is used for this purpose. While the text control is active, your 
application should send all keypress events to it by calling 
ITEXTCTL_HandleEvent() .

Text controls support the following properties, which can be set with 
ITEXTCTL_SetProperties() (the property names are the names of the bit-mask 
constants used to set and test the property values):

TP_MULTILINE allows multiple lines of text to appear in the text entry 
window (by default, only a single line appears).
TP_FRAME draws a frame around the text control.
TP_T9_MODE specifies that T9 is the default text entry mode for the device 
(if this property is not set, multi-tap is the default mode). This mode is 
not supported on the BREW Emulator.

Text controls provide several functions in addition to those in the 
IControl Interface . ITEXTCTL_SetTitle() and ITEXTCTL_SetText() specify 
values for the control's title and for the text string that appears in 
the text entry window (the latter function can be used to provide an 
initial value for the window's contents that the user can edit). 

ITEXTCTL_GetText() retrieves the current value of the control's text 
string and copies it into a buffer. ITEXTCTL_GetTextPtr() is similar, except 
that it returns a pointer to the character string in the text control that 
is used to store the text, without making a copy of it. 

ITEXTCTL_SetMaxSize() determines the maximum number of characters that can 
be entered into the text control. ITEXTCTL_EnableCommand() enables the sending 
of an EVT_COMMAND to your application when the user presses the SELECT key 
(this function is not supported at present).

ITEXTCTL_SetSoftKeyMenu() associates a SoftKey menu control with the text 
control. This is typically a SoftKey menu that you have created and that 
appears on the screen while the text control is displayed. 
ITEXTCTL_SetSoftKeyMenu() adds an item to the SoftKey menu that allows the 
user to change the text entry mode (the text string for this item indicates 
the currently selected mode). When the user selects this SoftKey menu item, 
an EVT_COMMAND event with command ID IDC_TEXT_MODE is sent to your application, 
and you should call ITEXTCTL_HandleEvent() to pass this command to the text 
control. When it receives this command, the text control displays a menu 
allowing the user to select the new text entry mode. After the user selects 
the new mode, the text control is reactivated and the user continues entering 
text. While entering text, the user can press the SELECT key to leave text-edit 
mode and activate the SoftKey menu. While the SoftKey menu is active, the user 
can press the UP key to return to edit mode without making a menu selection.

To use a text control in your application
Call ISHELL_CreateInstance() to create an instance of the text control.
Call ITEXTCTL_SetRect() to specify the screen rectangle that will contain 
the text control.
If desired, call ITEXTCTL_SetTitle() and/or ITEXTCTL_SetText() to specify 
the control's title and the initial value of its text string.
Call ITEXTCTL_SetProperties() to set any text control properties.
Call Call ITEXTCTL_SetSoftKeyMenu() to specify the SoftKey menu that is 
associated with the text control, if any.
Call ITEXTCTL_SetActive() to activate the text control and draw its 
contents on the screen.
While the text control is active, call ITEXTCTL_HandleEvent() to pass it 
any key events generated by the user. This includes Character events.
This way a text control will be able to accept text inputted fromt he keyboard.
When the user has completed entering text, call ITEXTCTL_GetText() or 
ITEXTCTL_GetTextPtr() to retrieve the text the user has entered. (If you are 
using a SoftKey menu, the user may signal the completion of text entry with a 
"Done" item in the menu, or by pressing the SELECT or other key if no SoftKey 
menu is present).
Call ITEXTCTL_Release() to free the text control when you no longer need it.

The EVT_CTL_TEXT_MODECHANGED event will be sent when the text input mode has changed. This 
may happen as the result of a user changing the input mode via the Softkey, or by the program
changing the input mode with the ITEXTCTL_SetInputMode API.

Functions in this interface include:
ITEXTCTL_AddRef() 
ITEXTCTL_EnableCommand() 
ITEXTCTL_GetProperties() 
ITEXTCTL_GetRect() 
ITEXTCTL_GetText() 
ITEXTCTL_GetTextPtr() 
ITEXTCTL_HandleEvent() 
ITEXTCTL_IsActive() 
ITEXTCTL_Redraw() 
ITEXTCTL_Release() 
ITEXTCTL_Reset() 
ITEXTCTL_SetActive() 
ITEXTCTL_SetInputMode() 
ITEXTCTL_SetMaxSize() 
ITEXTCTL_SetProperties() 
ITEXTCTL_SetRect() 
ITEXTCTL_SetSoftKeyMenu() 
ITEXTCTL_SetText() 
ITEXTCTL_SetTitle() 

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

ITEXTCTL_AddRef()

Description:
    This function increments the reference count for the text control object

Prototype:
    uint32 ITEXTCTL_AddRef(ITextCtl * pITextCtl)

Parameters:
    pITextCtl : Pointer to the ITextCtl Interface object

Return Value:
    Incremented reference count for the object

Comments: 
    None

Side Effects:
    None

See Also:
    ITEXTCTL_Release() 

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

ITEXTCTL_EnableCommand() 

Description:
    This function is used to enable sending of specified command by the 
    text control object to the shell object upon receiving the event 
    generated by pressing the SELECT key.

Prototype:
    void ITEXTCTL_EnableCommand(ITextCtl * pITextCtl, boolean bEnable, uint16 nCmdId) 

Parameters:
    pITextCtl : Pointer to the ITextCtl Interface object
    bEnable : Boolean value for enable/disable flag
    nCmdId : Command id

Return Value: 
    None

Comments: 
    None

Side Effects: 
    None

See Also:
    None

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

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_NODRAW :    If set, text control object does not draw itself
    TP_NOUPDATE :  If set, text control object does not call IDISPLAY_Update when not needed
    TP_PASSWORD :  If set, text control will display * characters in place of real characters

Comments: 
    None

Side Effects: 
    None

See Also:
    ITEXTCTL_SetProperties() 

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

ITEXTCTL_GetRect() 

Description: 
    This function fills given pointer to AEERect with the coordinates of 
    the current bounding rectangle of the text control object. This is 
    particularly useful after a control is created to determine its 
    optimal/default size and position. This function fills the AEERect with
    the actual bounding rectangle of the control, which is not necessarily the 
    rectangle passed in 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

Side Effects: 
    None

See Also:
    ITEXTCTL_SetRect()
 
=======================================================================
 
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

Side Effects: 
    None

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

Side Effects: 
    None

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 processed 
    only set title, set text and press of 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 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: 
    None

Side Effects: 
    None

See Also:
    None

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

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

Side Effects: 
    None

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

Side Effects: 
    None

See Also:
    None

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

ITEXTCTL_Release() 

Description:
    This function decrements the reference count for the ITextCtl Interface 
    object and does appropriate cleanup if the reference count reaches 
    0 (zero).

Prototype:
    uint32 ITEXTCTL_Release(ITextCtl * pITextCtl)
 
Parameters:
    pITextCtl : Pointer to the ITextCtl Interface object whose reference count 
                needs to be decremented

Return Value:
    Updated reference count for the object.

Comments: 
    None

Side Effects: 
    None

See Also:
    ITEXTCTL_AddRef() 

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

ITEXTCTL_Reset() 

Description: 
    This function instructs the text control to reset (free/delete) its 
    contents as well as 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

Side Effects: 
    None

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: 
    None

Side Effects: 
    None

See Also:
    None

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

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

Side Effects: 
    None

See Also: 
    AEETextInputMode 

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

ITEXTCTL_GetInputMode()

Description: 
    This function allows the caller to get the selected text input mode
    and the string associated with it.

Prototype:
   AEETextInputMode  ITEXTCTL_GetInputMode(ITextCtl *po, AEETextInputModeInfo * pmInfo);

Parameters:
    po :       Pointer to the ITextCtl Interface object
    pmInfo :   [in/out]: On input a pointer to a AEETextInputModeInfo structure to 
               be filled OR can be NULL, so as to not fill a structure and return
               current mode. Output: If a valid pointer is given it will be filled with 
               the current mode and the string associated with that mode.

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

Comments: 
    If a AEETextInputModeInfo pointer is given the tmMode field will match the return
    value of this function. The pmInfo field is not required if the callee is just 
    checking the AEETextInputMode and does not need the string associated with it.

Side Effects: 
    None

See Also: 
    AEETextInputModeInfo 

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

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: 
    None

Side Effects: 
    None

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_NODRAW :    If set, text control object does not draw itself
    TP_NOUPDATE :  If set, text control object does not call IDIPLAY_Update when not needed
    TP_PASSWORD :  If set, text control will display * characters in place of real characters

Return Value: 
    None

Comments: 
    None

Side Effects: 
    It deactivates the text control.

See Also:
    ITEXTCTL_GetProperties() 

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

ITEXTCTL_SetRect()
 
Description: 
    This function can be used to set the coordinates specified by prc as 
    control rectangle of the text control object. A call to this function, 
    also leads to calculate control rectangle for text line.

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 device 
    screen width as width and (device screen height - text height) as height 
    starting from upper left corner.

Side Effects: 
    None

See Also:
    ITEXTCTL_GetRect() 

=======================================================================
 
ITEXTCTL_SetSoftKeyMenu() 

Description: 
    It replaces the existing SoftKey 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's 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.

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:
    TRUE : If successful
    FALSE : If otherwise

Comments: 
    None

Side Effects: 
    None

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 .

See Also:
    None

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

ITEXTCTL_GetCursorPos() 

Description: 
    This function is used to get the position of a cursor in a text control object. 

Prototype:
    int32 ITEXTCTL_GetCursorPos(ITextCtl * po) 

Parameters:
    po : Pointer to the ITextCtl Interface object

Return Value:
    Absolute position of cursor in text control

Comments: 
    None

Side Effects:
    None

See Also:
    None

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

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:
    TC_CURSOREND - Place the cursor at the end of the text.
    TC_CURSORSTART - Place the cursor at the beginning of the text.

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

Parameters:
    po : Pointer to the ITextCtl Interface object

Return Value:
    None

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

Side Effects:
    None

See Also:
    None

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

ITEXTCTL_EnumModeInit() 

Description: 
    This function initialises the mode enumeratation mechanism for the
    test control. Any time you want to enumerate the text control, this
    function shoul dbe called first.
      
Prototype:
    void ITEXTCTL_EnumModeInit(ITextCtl * po) 

Parameters:
    po : Pointer to the ITextCtl Interface object

Return Value:
    None

Comments: 
    None

Side Effects:
    None

See Also:
    None

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

ITEXTCTL_EnumNextMode() 

Description: 
    This function is called to enumerate the text control modes. 
    
Prototype:
    AEETextInputMode   ITEXTCTL_EnumNextMode(ITextCtl * po, AEETextInputModeInfo * pmInfo) 

Parameters:
    po : Pointer to the ITextCtl Interface object
    pmInfo: Optional pointer to receive Text Mode Information. If you do not
            wish to receive this information, call this function with a NULL
            value as the second parameter.

Return Value:
    An enum of type AEETextInputMode to indicate the next input mode.
    If the enumeration is complete AEE_TM_NONE will be returned.

Comments: 
    None

Side Effects:
    None

See Also:
    None

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