The Input Server: BInputServerMethod

The Input Server Table of Contents | The Input Server Index

# BInputServerMethod

Derived from: BInputServerFilter

Declared in: be/add-ons/input_server/InputServerMethod.h

Library: libbe.so

Allocation: By the Input Server only

###### Summary

BInputServerMethod is a base class for input methods; these are instances of BInputServerMethod that act as an interface between the user and languages using character sets that can>t be easily represented on standard keyboards, such as the Japanese input method that comes with BeOS.

Input methods generally handle `B_KEY_DOWN` messages in their `Filter()` function (see BInputServerFilter), keeping some sort of state around to translate these standard keyboard messages into new `B_KEY_DOWN` messages representing another character set. An input method can handle any input event, they>re not limited to keyboard events.

Writing an input method is an involved process, even though the BInputMethod protocol is relatively simple. If you>re working on an input method, please feel free to contact Be Developer Technical Support (devsupport@be.com) for additional information.

### Input Method Events

Input methods insert `B_INPUT_METHOD_EVENT` messages (using their `EnqueueMessage()` function) into the Input Server>s event stream. These messages let BView subclasses work together with your input method to create a seamless experience for the user.

Each `B_INPUT_METHOD_EVENT` message contains a be:opcode field (an int32 value) indicating the kind of event:

- `B_INPUT_METHOD_STARTED

  `
- `B_INPUT_METHOD_STOPPED

  `
- `B_INPUT_METHOD_CHANGED

  `
- `B_INPUT_METHOD_LOCATION_REQUEST

  `

`B_INPUT_METHOD_STARTED` indicates that a new input transaction has begun. Add a BMessenger in the be:reply_to field; the receiver of the message will use this messenger to communicate with you during the transaction.

`B_INPUT_METHOD_STOPPED` indicates that the transaction is over.

In between the `B_INPUT_METHOD_STARTED` and `B_INPUT_METHOD_STOPPED` messages, you>ll send `B_INPUT_METHOD_CHANGED` and `B_INPUT_METHOD_LOCATION_REQUEST` messages as the transaction proceeds.

`B_INPUT_METHOD_CHANGED` does most of the work in an input transaction; add the following important fields:

Entry | Type | Description
--- | --- | ---
be:string | `B_STRING_TYPE` | The text the user is currently entering; the receiver will display it at the current insertion point. BTextView also highlights the text in blue to show that it>s part of a transitory transaction.
be:selection | `B_INT32_TYPE` | A pair of `B_INT32_TYPE` offsets into the be:string if part of be:string is current selected. BTextView highlights this selection in red instead of drawing it in blue.
be:clause_start | `B_INT32_TYPE` | Zero or more offsets into the be:string for handling languages (such as Japanese) that separate a sentence or phrase into numerous clauses. An equal number of be:clause_start and be:clause_end pairs delimit these clauses; BTextView separates the blue/red highlighting wherever there is a clause boundary.
be:clause_end | `B_INT32_TYPE` | Zero or more offsets into be:string; there must be as many be:clause_end entries as there are be:clause_start.
be:confirmed | `B_BOOL_TYPE` | True when the user has entered and "confirmed" the current string and wishes to end the transaction. BTextView unhighlights the blue/red text and waits for a `B_INPUT_METHOD_STOPPED` (to close the transaction) or another `B_INPUT_METHOD_CHANGED` (to start a new transaction immediately).

`B_INPUT_METHOD_LOCATION_REQUEST` is the input method>s way of asking for the on-screen location of each character in be:string. This information can be used by the input method to pop up additional windows giving the user an opportunity to select characters from a list or anything else that makes sense. When you send a `B_INPUT_METHOD_LOCATION_REQUEST`, the receiver will reply to the be:reply_to messenger (that you sent in your `B_INPUT_METHOD_STARTED` message) with a `B_INPUT_METHOD_EVENT` message, filling in the following fields:

Entry | Type | Description
--- | --- | ---
be:opcode | `B_INT32_TYPE` | Set to `B_INPUT_METHOD_LOCATION_REQUEST`.
be:location_reply | `B_POINT_TYPE` | The co-ordinates of each character (there should be one be:location_reply for every character in be:string) relative to the display (not your view or your window).
be:height_reply | `B_FLOAT_TYPE` | The height of each character in be:string.

## Creating

To create a new input method, you must:

- create a subclass of BInputServerMethod

- implement the `instantiate_input_method()` C function to create an instance of your BInputServerMethod subclass

- compile the class and function as an add-on

- install the add-on in one of the input method directories

At boot time (or whenever the Input Server is restarted; see "Dynamic Loading"), the Input Server loads the add-ons it finds in the input method directories. For each add-on it finds, the Server invokes `instantiate_input_method()` to get a pointer to the add-on>s BInputServerMethod object. After constructing the object, the Server calls `InitCheck()` to give the add-on a chance to bail out if the constructor failed.

## Installing an Input Method

The input server looks for input methods in the "input_server/methods" subdirectories of `B_BEOS_ADDONS_DIRECTORY`, `B_COMMON_ADDONS_DIRECTORY,` and `B_USER_ADDONS_DIRECTORY`.

- You can install your input devices in the latter two directories—i.e. those under `B_COMMON_ADDONS_DIRECTORY`, and `B_USER_ADDONS_DIRECTORY`.

- The `B_BEOS_ADDONS_DIRECTORY` is reserved for add-ons that are supplied by the BeOS.

## Hook Functions

- `MethodActivated()

  `

## Constructor and Destructor

### BInputServerMethod()

`BInputServerMethod(`const char *name, const uchar *icon`) `

Creates a new BInputServerMethod object. You can initialize the object—set initial values, spawn threads, etc.—either here or in the `InitCheck()` function, which is called immediately after the constructor.

name is a textual name describing the input method, and icon is the raw data for a 16x16 8-bit icon built from the standard BeOS palette. This name and icon will be displayed in the input method menu (the little keyboard icon in the Deskbar). When the user selects your input method from the menu, your `MethodActivated()` function is called.

### ~BInputServerMethod()

`~BInputServerMethod() `

Deletes the BInputServerMethod object. The destructor is invoked by the Input Server only—you never delete a BInputServerMethod object from your own code. If this object has spawned its own threads or allocated memory on the heap, it must clean up after itself here.

## Member Functions

### EnqueueMessage()

`status_t` `EnqueueMessage(` BMessage *message`) `

Inserts the specified message into the Input Server>s event queue; the message continues down-stream from this point, passing through additional active input methods and input filters on its way to the App Server.

### MethodActivated()

virtual status_t MethodActivated(bool active)

The MethodActivated() hook function is invoked by the Input Server when the user activates your input method (active is true) or deactivates it (active is false). This is your chance to activate any helper threads or loopers to the fact that you>ll be handling input events soon.

Return `B_OK` if that>s OK, or something else if it>s not. The default implementation returns `B_OK`.

### SetName()

status_t SetName(const char *name)

Changes your input method>s name, as found in the input method menu of the Deskbar.

The Input Server makes a copy of name.

### SetIcon()

status_t SetIcon(const uchar *icon)

Changes your input method>s icon, as found in the input method menu of the Deskbar. icon should be raw data for a 16x16 8-bit icon built from the standard BeOS palette.

The Input Server makes a copy of icon.

### SetMenu()

status_t SetMenu(const BMenu *menu, const BMessenger target)

Lets you assign a menu to your input method>s entry in the input method menu of the Deskbar. Messages generated by the menu are sent to target.

Passing a `NULL` menu disables your input method>s menu.

You retain ownership of menu; be careful not to delete it while the Input Server is still using it.

The Input Server Table of Contents | The Input Server Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..