Home · All Classes · Grouped Classes · Annotated · Functions

QtopiaInputMethod Class Reference

The QtopiaInputMethod class describes the minimum interface that an input method plug-in must provide. More...

    #include <QtopiaInputMethod>

Inherits QObject.

Public Types

Public Functions

Public Slots

Signals

Additional Inherited Members


Detailed Description

The QtopiaInputMethod class describes the minimum interface that an input method plug-in must provide.

Input Methods may be added to Qtopia via plug-ins. In order to write an input method plug-in you must create an interface for your plug-in by deriving from the QtopiaInputMethod class.

At a minimum you will need to implement the methods name(), identifier(), version(), state(), properties(), icon() and reset().

Pop-up input methods that need to show a widget on the screen can do so by overriding inputWidget().

Filtering input methods that need to filter application pen or keyboard events can do so by overriding inputModifier()

See also Tutorial: Create an Input method Plug-in that Modifies Keyboard Input and QWSInputMethod().


Member Type Documentation

enum QtopiaInputMethod::Properties

The Properties flags describe how the input method behaves and under what conditions it should be loaded.

ConstantValueDescription
QtopiaInputMethod::RequireMouse0x0001The input method should not be loaded if no pen input is available.
QtopiaInputMethod::RequireKeypad0x0002The input method should not be loaded if no phone keypad is available. A phone keypad consists of 0-9, * and # keys.
QtopiaInputMethod::InputModifier0x0004The input method can filter device pen and key events.
QtopiaInputMethod::InputWidget0x0010The input method provides a popup widget that receives input
QtopiaInputMethod::DockedInputWidget0x0030The input method's popup widget should be docked to the bottom of the screen, and other windows should be resized to allow for it's space when it is visible. Note that DockedInputWidget implies InputWidget, and that the input method's input widget should be defined if this property is set (Setting the InputWidget property as well will not do any harm, but is not necessary)
QtopiaInputMethod::InteractiveIcon0x0008The icon representing the input method is interactive. It can be clicked or will animate to show the mode of the input method.
QtopiaInputMethod::MenuItem0x0040The input method menu adds an item to the softkey context menu. If this value is set, the input method must also implement the menuActionToDuplicate() function that returns a QAction that is to copied for the menu. Additionally, the input method must respond to the menuActionActivated, as the supplied action will not receive events (it is only used as a model to copy). The input method can respond by either by implementing menuActionActivated in a subclass, or by connecting it somewhere else for processing.

enum QtopiaInputMethod::State

This enum describe the state of the input method.

ConstantValueDescription
QtopiaInputMethod::Sleeping0The input method is not able to provide input for the current input method hint.
QtopiaInputMethod::Ready1The input method is able to provide input for the current input method hint.


Member Function Documentation

QtopiaInputMethod::QtopiaInputMethod ( QObject * parent = 0 )

Constructs an input method with the parent set to parent.

QtopiaInputMethod::~QtopiaInputMethod ()   [virtual]

Destroys the input method.

void QtopiaInputMethod::clicked ()   [virtual slot]

This function is called when the user clicks on the status icon of the input method. It is only called doesn't provide its own status widget.

See also statusWidget().

void QtopiaInputMethod::focusChanged ()   [virtual slot]

This function is called by the system to notify it that focus has changed. Focus changes will usually trigger a new hint as well.

See also setHint().

QIcon QtopiaInputMethod::icon () const   [pure virtual]

Returns the icon associated with this input method.

QString QtopiaInputMethod::identifier () const   [pure virtual]

Returns the indentifier of the input method. This is used to identify the input method in code.

QWSInputMethod * QtopiaInputMethod::inputModifier ()   [virtual]

Returns the input modifier for the input method.

The input modifer is installed as the current input method for the QWSServer when selected. This allows the input method to work by filtering pen movements on the screen or filtering device keys. Returning 0 indicates no input modifier is provided and that the input method uses some other method for the user to generated text.

The base class returns 0.

QWidget * QtopiaInputMethod::inputWidget ( QWidget * parent = 0 )   [virtual]

Returns the input widget for the input method. On the first call of this function it should create the widget with the given parent.

The widget is used for input methods that have the InputWidget property. It is shown when the user requests it to provide input or even simply provide additional keys. Returning 0 indicates no input widget is provided and that the input method uses some other method for the user to generate text.

The base class returns 0.

void QtopiaInputMethod::menuActionActivated ( int data )   [virtual slot]

This slot is triggered when the input methods action has been activated from the softkey menu. Implement in a subclass, or connect the slot to react to menu activation.

Note: This is the only way to receive notification of menu action activations, as the Softkey Menu has separate copies of the QAction, often in a separate process to the input method. However, connecting this slot to other slots in the input method or server will work normally.

The data is the id from the id field of the QIMActionDescription used to create the QAction that was triggered. Be sure to assign a unique id to each menu action, so as to be able to tell them apart here.

0 is the default value returned if the server was not able to determine which action was triggered for some reason.

See also: QIMActionDescription

QList<QIMActionDescription *> QtopiaInputMethod::menuDescription ()   [virtual]

Implement this function in a derived class to return a description of the menu that should be installed on the input methods behalf.

This function is called by Qtopia when the input methods menu is shown, or when the inputmethod emits stateChanged(), in order to construct the softkey menu entries for the input method.

If the list contains only a single item, the server interprets this as a single menu item, and softkey puts it in its top-level menu, and returns its id when it is activated.

If the list contains more than one item, the server interprests the first as the icon and label for a menu item in the top level softkey menu, and subsequent items as members of that submenu. Note that in this case the first item will become a menu, and will not be triggerable, so its id will never be sent back to the IM.

Each IMAction description includes an id to identify the action, a user-visible label, and the filename of the icon used for the action. Note that the icon will usually be instantiated from a different process that could have a different environment from the inputmethod, so the file name must be fully qualified.

The default implementation returns an empty list, which will result in no menu actions being added on behalf of the input method.

see also: QIMActionDescription

QString QtopiaInputMethod::name () const   [pure virtual]

Returns the name of the input method. This is a end user visible string and should be translated to the users locale.

bool QtopiaInputMethod::passwordHint () const   [virtual]

Returns true if the current input method is restricted to providing input suitable for a password field.

int QtopiaInputMethod::properties () const   [pure virtual]

Returns the capability property flags for the input method.

See also Properties.

void QtopiaInputMethod::reset ()   [pure virtual]

Resets the input method to its initial state.

bool QtopiaInputMethod::restrictedToHint () const   [virtual]

Returns true if the current input method is restricted to providing input suitable for the current hint.

void QtopiaInputMethod::setHint ( const QString & hint, bool restricted )   [pure virtual]

This is the primary communication channel from the server to the Input Method, and sets the hint describing the sort of input the current input widget requires to hint. It must be implemented in Input Method plugins.

If restricted is true the widget only accepts one kind of input and input method should disable any mode switching. For example, the home screen Qtopia might set the hint to be restricted to phone numbers.

an empty hint is used to indicate that input is not needed for the current focused widget- the Input Method should deactivate.

Common hints are words - Dictonary words such as some notes text - Names, passwords etc. extended - text with extensions for additional character sets number - 0-9 phone - Phone numbers, 0-9 plus phone control codes such as 'p' 'x' or 'w'.

Application may also define custom hints, such as email to describe an email address. Input methods should provide reasonable default behavior for hints they do not recognize.

State QtopiaInputMethod::state () const   [pure virtual]

Returns the current state of the input method.

void QtopiaInputMethod::stateChanged ()   [signal]

This signal is emitted when the input method state changes. Causes the server to update the menus for the input method.

See also state().

QWidget * QtopiaInputMethod::statusWidget ( QWidget * parent = 0 )   [virtual]

Returns the status widget for the input method. On the first call of this function it should create the widget with the given parent.

The status widget is displayed when the input method is selected and not in the Sleeping state. If no status widget is provided a label with the icon returned from icon() will be used instead.

The base class returns 0.

bool QtopiaInputMethod::testProperty ( int p ) const

Returns true if the property flag p is set to true for this input method. Otherwise returns false.

void QtopiaInputMethod::updateMenuAction ( bool showMenuAction )   [signal]

This signal is not currently used, but reserved for future use. It is anticipated that this signal will be used to signal to the server that the input method menu has changed, with showMenuAction being used to indicate whether or not the new menu should be displayed. Note: Currently the server updates the menu on a stateChanged() signal.

QString QtopiaInputMethod::version () const   [pure virtual]

Returns the version string of the input method.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3