×
Namespaces

Variants
Actions

Text input with RGA

From Nokia Developer Wiki
Jump to: navigation, search

Archived.pngArchived: This article is archived because it is not considered relevant for third-party developers creating commercial solutions today. If you think this article is still relevant, let us know by adding the template {{ReviewForRemovalFromArchive|user=~~~~|write your reason here}}.

The article is believed to be still valid for the original topic scope.


Article Metadata
Tested with
Devices(s): Nokia N93, Nokia N95
Compatibility
Platform(s): S60 3rd Edition
Article
Created: stolik (25 Sep 2008)
Last edited: lpvalente (18 Sep 2012)

Contents

Overview

This code snippet shows how to get and draw entered text. This is done by initializing the IKeypadCapabilities and ITextInput objects and inheriting the page class from ITextInputObserver.


Note: In order to use this code, you need to install the Open C plug-in.

Preconditions

This example relies on the RGA API ngi and examplefw frameworks.

Initialization of the keyboard should be done in the CApplicationBase::Initialize() function (it is usually called in the CApplication::Initialize() function of examplefw) and the mKeypadDevice should be passed to this class before using it here.

To run this snippet you need to use the ngi and examplefw frameworks provided with Open C/C++ Plug-ins for S60 3rd Edition. Examplefw sources are located in the "\nokia_plugin\rga\s60rgaex\common\gameexfw\src\" folder after the plug-in has been installed.

MMP file

The following capabilities and libraries are required:

CAPABILITY SwEvent
STATICLIBRARY libcrt0.lib
LIBRARY euser.lib
LIBRARY runtime.lib
LIBRARY libc.lib
LIBRARY libm.lib
LIBRARY libpthread.lib

Note: The snippet itself doesn't require any special capabilities, but due to the use of RGA API ngi framework, the resulting application requires SwEvent capability. (See also Open C/C++ DLL.)

Header file

#include "page.h"     //examplefw
#include <input.h> // ngi
using namespace ngi;
 
using examplefw::CPage;
class CExamplePage : public CPage, public ITextInputObserver
{
public:
/**
* Constructor.
*
* Creates a page to retrieve and display the input by polling.
*
* @param aInputDevice Pointer to the input device.
* @param aLeftString Left soft button text.
* @param aRightString Right soft button text.
* @param aHeadingString Heading text for menu page.
* @param aStatusString Status text for menu page.
*/

CExamplePage( IInputDevice* aInputDevice,
const char16* aLeftString,
const char16* aRightString,
const char16* aHeadingString = NULL,
const char16* aStatusString = NULL );
 
virtual void Draw( IGraphicsContext& aGraphicsContext );
/// ...
 
public: //for ITextInputObserver
/**
* This method is called when the input from the user causes the
* already typed in text to change.
*
* The method informs about the
* new text string encoded as 16-bit unicode, the current cursor
* position and errors that might occur because the maximum text
* length is going to be exceeded.
*
* @param aCursorPosition The new position of the cursor. In
* multitapping input mode the cursor is changed after the
* multitapping timeout. In this case, the cursor position
* is not changed. After the timeout occurred
* @ref CursorPositionChanged is called.
* @param aError
* @li @ref OK, if no error occurred.
* @li @ref ERROR_BUFFER_TOO_SHORT, if the text length
* would have exceeded the maximum text length. In
* this case, the typed in character is ignored.
*/

virtual void TextChanged( uint32 aCursorPosition,
ReturnCode aError ) NO_THROW;
 
/**
* This method is called when the input from the user causes the
* cursor position to change.
*
* This case happens after the multitapping timeout expired,
* or a navigation left or right key have been pressed. It is not
* called if the cursor position changed due to a text change.
* In this case @ref TextChanged is called.
*
* @param aCursorPosition The new cursor position. Navigation with
* the navigation left or right keys works in a modulo ring
* i.e. having a current cursor position of 0 and navigating
* to previous character lead to the new cursor position of
* the current text length.
*/

virtual void CursorPositionChanged( uint32 aCursorPosition ) NO_THROW;
 
/**
* This method is called when the keys defined with the commands
* @ref TEXT_INPUT_ACCEPT and @ref TEXT_INPUT_CANCEL have been
* pressed by the user.
*
*/

virtual void TextInputFinished() NO_THROW;
 
/**
* This method is called when the keys defined with the commands
* @ref TEXT_INPUT_SHIFT causes the @ref TextInputMode to change by
* key press by the user in the appropriate input mode.
*
* @param aMode The new @ref TextInputMode which is used for
* all following typed in characters.
*/

virtual void TextInputModeChanged( TextInputMode aMode ) NO_THROW;
 
/**
* This method is called when the keys defined with the commands
* @ref TEXT_INPUT_SHIFT causes the @ref TextInputCase to change by
* key press by the user in the appropriate input mode.
*
* @param aMode The new @ref TextInputCase which is used for
* all following typed in characters.
*/

virtual void TextInputCaseChanged( TextInputCase aMode ) NO_THROW;
 
/**
* This method is called when the keys defined with the command
* @ref SYMBOL_MATRIX_CALL have been pressed in the appropriate input
* mode by the user to cause the symbol matrix to be used.
*/

virtual void SymbolMatrixOpened() NO_THROW;
 
/**
* This method is called when the keys defined with the commands
* @ref SYMBOL_MATRIX_NAVIGATION_PREVIOUS,
* @ref SYMBOL_MATRIX_NAVIGATION_NEXT,
* @ref SYMBOL_MATRIX_NAVIGATION_PREVIOUS_ROW,
* @ref SYMBOL_MATRIX_NAVIGATION_NEXT_ROW
* have been pressed in the
* appropriate input mode by the user to cause the symbol matrix to be
* used.
*
* If history has been set on in @ref ISymbolMatrix::SetHistory
* it is automatically used in the first row.
*
* @param aEntryIndex The index of the currently selected entry.
* @param aRow The row of the currently selected symbol matrix entry.
* @param aColumn The column of the currently selected symbol matrix
* entry.
* @param aEntry The currently selected symbol. It consists of a
* a set of 16-bit unicode characters, which are NULL-terminated.
*/

virtual void SymbolMatrixEntrySelected( uint32 aEntryIndex,
uint32 aRow,
uint32 aColumn,
const char16* aEntry ) NO_THROW;
 
/**
* This method is called when the keys defined with the commands
* @ref SYMBOL_MATRIX_SELECT and
* @ref SYMBOL_MATRIX_CANCEL have been pressed in the appropriate input
* mode by the user to cause the symbol matrix to be closed.
*/

virtual void SymbolMatrixClosed() NO_THROW;
 
//...
 
public:
 
/// Pointer to the keypad device object from the Input API.
IInputDevice* mKeypadDevice;
 
/// Pointer to text input interface.
ITextInput* mTextInterface;
 
/// Pointer to text input configuration interface.
ITextInputControl* mTextConfig;
 
/// Pointer to the new character string.
const char16* mEnteredText;
 
/// Position of the cursor in the UI.
int32 mCursorPosition;
 
/// Currently used input case type.
TextInputCase mCaseType;
 
/// Currently used input mode type.
TextInputMode mInputType;
 
/**
* Checks if the Input Case type has to be changed back after
* starting text input.
*/

bool32 mChangeCaseBack;
}
// ...

Source file

#include <errorcodes.h>         // ngi
#include <graphics.h> // ngi
#include <graphicscontext.h> // ngi
#include <ngibitmap.h> // ngi
#include <runtime.h> // ngi
#include <standardtypes.h> // ngi
 
const char16* const ENTER_TEXT_INVITATION = L"Please, enter text:";
const uint16 TEXT_LENGTH = 32;
 
CExamplePage::CExamplePage( IInputDevice* aInputDevice,
const char16* aLeftString,
const char16* aRightString,
const char16* aHeadingString,
const char16* aStatusString ) :
CPage( aLeftString, aRightString, aHeadingString, aStatusString ),
mKeypadDevice( aInputDevice ),
mTextInterface( NULL ),
mTextConfig( NULL ),
mNewLine( NULL ),
mCursorPosition( 0 ),
mCaseType( TEXT_INPUT_CASE_LOWER_NEXT_UPPER ),
mInputType( TEXT_INPUT_MODE_MULTITAPPING ),
mChangeCaseBack( FALSE )
{
}
 
// ---------------------------------------------------------
// This method initializes the highscore page.
// ---------------------------------------------------------
bool32 CExamplePage::Initialize()
{
// ...
 
if( CRuntime::CreateInstance( mTextInterface ) == OK )
{
mTextInterface->Attach( mKeypadDevice );
mTextInterface->SetObserver( this );
}
else
{
return FALSE;
}
 
mTextInterface->GetTextInputControl( mTextConfig );
if( !mTextConfig )
{
return FALSE;
}
 
//setting limit of entered text
mEnteredText = mTextInterface->TextBuffer();
mTextConfig->SetMaximumTextLength(TEXT_LENGTH, mEnteredText);
 
return TRUE;
}
 
// ---------------------------------------------------------
// Destructor.
// ---------------------------------------------------------
CExamplePage::~CExamplePage()
{
if( mTextConfig)
{
mTextConfig->Release();
}
 
if( mTextInterface )
{
mTextInterface->Release();
}
}
 
// ---------------------------------------------------------
//This method draws the current page using the given graphics context.
// ---------------------------------------------------------
void CExamplePage::Draw(IGraphicsContext& aGraphicsContext) //const
{
CPage::Draw( aGraphicsContext );
 
uint32 boxHeight = efGetCharacterHeight( FONT_STYLE_TITLE );
 
 
//drawing invitation to enter text
int32 strWidth = efGetStringWidth( ENTER_TEXT_INVITATION, FONT_STYLE_TITLE );
PrintString( ENTER_TEXT_INVITATION, CPoint( int( (mResolution.mX - strWidth) / 2 ),
mResolution.mY - 3*boxHeight ), aGraphicsContext,
COLOR_WHITE, ONT_STYLE_TITLE, false);
 
// Get the width of the whole string before cursor position.
strWidth = efGetStringWidth( mEnteredText, FONT_STYLE_NORMAL );
 
// draw entered string with name
PrintString( mEnteredText, CPoint( int( (mResolution.mX - strWidth) / 2 ),
mResolution.mY - 2* boxHeight ), aGraphicsContext,
COLOR_WHITE, ONT_STYLE_TITLE, false);
}
 
// ---------------------------------------------------------
// This method is called when the input from the user causes the
// already typed in text to change.
//
// The method informs about the
// new text string encoded as 16-bit unicode, the current cursor
// position and errors that might occur because the maximum text length
// is going to be exceeded.
// ---------------------------------------------------------
void CExamplePage::TextChanged( uint32 aCursorPosition,
ReturnCode /* aError */ ) NO_THROW
{
mEnteredText = mTextInterface->TextBuffer();
mCursorPosition = aCursorPosition;
}
 
// ---------------------------------------------------------
// This method is called when the input from the user causes the
// cursor position to change.
//
// This case happens after the multitapping timeout expired,
// or a navigation left or right key have been pressed. It is not called
// if the cursor position changed due to a text change. In this case
// @ref TextChanged is called.
// ---------------------------------------------------------
void CExamplePage::CursorPositionChanged( uint32 aCursorPosition ) NO_THROW
{
mCursorPosition = aCursorPosition;
}
 
// ---------------------------------------------------------
// This method is called when the keys defined with the commands
// @ref TEXT_INPUT_ACCEPT and @ref TEXT_INPUT_CANCEL have been pressed
// by the user.
// ---------------------------------------------------------
void CExamplePage::TextInputFinished() NO_THROW
{
mEnteredText = mTextInterface->TextBuffer();
mCursorPosition++;
}
 
// ---------------------------------------------------------
// This method is called when the keys defined with the commands
// @ref TEXT_INPUT_SHIFT causes the @ref TextInputMode to change by a
// key press by the user in the appropriate input mode.
// ---------------------------------------------------------
void CExamplePage::TextInputModeChanged( TextInputMode aMode ) NO_THROW
{
mInputType = aMode;
}
 
// ---------------------------------------------------------
// This method is called when the keys defined with the commands
// @ref TEXT_INPUT_SHIFT causes the @ref TextInputCase to change by a
// key press by the user in the appropriate input mode.
// ---------------------------------------------------------
void CExamplePage::TextInputCaseChanged( TextInputCase aMode ) NO_THROW
{
if( mChangeCaseBack )
{
mTextConfig->SetInputCase( mCaseType );
mChangeCaseBack = FALSE;
}
else
{
mCaseType = aMode;
}
}
 
// ---------------------------------------------------------
// This method is called when the keys defined with the command
// @ref SYMBOL_MATRIX_CALL have been pressed to open symbol matrix.
// ---------------------------------------------------------
void CExamplePage::SymbolMatrixOpened() NO_THROW
{
 
}
 
// ---------------------------------------------------------
// This method is called when the user navigates through the
// symbol matrix.
// ---------------------------------------------------------
void CExamplePage::SymbolMatrixEntrySelected( uint32 /*aEntryIndex*/,
uint32 /*aRow*/,
uint32 /*aColumn*/,
const char16* /*aEntry*/) NO_THROW
{
 
}
 
// ---------------------------------------------------------
// This method is called when symbol matrix is closed.
// ---------------------------------------------------------
void CExamplePage::SymbolMatrixClosed() NO_THROW
{
}

Postconditions

This example will initialize necessary objects needed to enter text, write an invitation on a page, get the entered text into the mEnteredText string, and print this string.

This page was last modified on 18 September 2012, at 21:09.
41 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×