BInputDevice

Derived from: none
Declared in:  be/interface/Input.h
Library: libbe.so
Allocation: By the system only. See find_input_device().
more...

A BInputDevice object is a "downstream" representation of an Input Server device, such as a mouse or a keyboard, within a "regular" application. The BInputDevice can Start() and Stop() the device it represents, and can send it input device control messages through its Control() function.

You never create BInputDevice objects yourself; instead, you ask the system to return one or more instances to you through the find_input_device() or get_input_devices() functions. Alternatively, you can work without an object by invoking the static versions of Start(), Stop(), and Control(). Note, however, that the static functions control all devices of a given type, whereas a BInputDevice instance can talk to a specific device.

BInputDevice objects don't live in the Input Server—they're used in "normal" applications as a means to control an Input Server device add-on.

The BInputDevice object is provided, primarily, to let an application talk to a custom input device.

You never subclass BInputDevice.

Constructor and Destructor

BInputDevice()

The constructor is private. Use find_input_device() or get_input_devices() to retrieve a BInputDevice instance.

~BInputDevice()

~BInputDevice()

Deletes the BInputDevice object. Deleting this object doesn't affect the device that it represents.

Member Functions

Control()

status_t Control(uint32 code, BMessage *message) static status_t Control(input_device_type type,       uint32 code,       BMessage *message)

Sends an input device control message to the object's input device or, in the static version, to all devices of the given type, where, type can be B_POINTING_DEVICE, B_KEYBOARD_DEVICE, or B_UNDEFINED_DEVICE. Input devices receive these messages in their Control() function.

The control message is described by the code value; it can be supplemented or refined by message. For example, code can indicate that a certain parameter should be set, and message can supply the requested value.

In general, you only use this function to send custom messages to a (custom) device. You never use it to send messages to a Be-defined input device since the messages that these devices respond to are covered by Be-defined functions. See "Input Device Control Messages" for a list of the messages that the Be-defined devices respond to, the functions that cover them, and the German women who love them.

Start()

Name() , Type()

const char *Name(void) const input_device_type Type(void) const

Name()Start() returns a pointer to the input device's name. The name, which is set when the device is registered, is meant to be human-readable and appropriate for use as the label of a UI element (such as a menu field). Device names are not unique.

Type() returns the input device's type, one of B_POINTING_DEVICE, B_KEYBOARD_DEVICE, and B_UNDEFINED_DEVICE.

Start() , Stop() , IsRunning()

status_t Start(void) status_t Start(void) bool IsRunning(void) const static status_t Start(input_device_type type) static status_t Stop(input_device_type type)

Start() tells the object's input device to start generating events; Stop() tells it to stop generating events. IsRunning() returns true if the device is currently generating events (i.e. if it has been started and hasn't been stopped).

The static versions of Start() and Stop() start and stop all devices of the given type.

RETURN CODES

• B_OK. The device is now started (Start()) or stopped (Stop())—even if the device was already started or stopped.

• B_ERROR. The device couldn't be found.

The Input Server tells a device to start and stop without asking the device if the operation was successful. This means, for example, that Start() can return B_OK (and IsRunning() can return true) even if the device isn't really running. For the Be-provided devices this isn't an issue—starting and stopping always succeeds (as long as the device exists).

	Start()
	Type()  see Name()

C Functions

find_input_device() , get_input_devices()

BInputDevice* find_input_device(const char *name) status_t get_input_devices(BList *list)

These functions get BInputDevice objects for you.

find_input_device() creates and hands you a BInputDevice object that represents the Input Server device registered as name. If name is invalid, the function returns NULL. The caller is responsible for deleting the object. Note that find_input_device() returns a new BInputDevice object for each (valid) call, even if you ask for the same device more than once.

get_input_devices() creates a new BInputDevice object for each registered device, and puts the objects in your list argument. list must already be allocated, and is automatically emptied by the function (even if the function fails). If the function succeeds, the caller owns the contents, and needs to delete the items in the list:

#include <interface/Input.h> #include <support/List.h> ... static bool del_InputDevice( void *ptr ) {    if( ptr ) {       BInputDevice *dev = (BInputDevice *)ptr;       delete dev;       return false;    }    return true; } ... void SomeFunc( void ) {    // Get a list of all input devices.    BList list_o_devices;    status_t retval = get_input_devices( &list_o_devices );    if( retval != B_OK ) return;    // Do something with the input devices.    ...    // Dispose of the device list.    list_o_devices.DoForEach( del_InputDevice );    list_o_devices.MakeEmpty(); }

RETURN CODES

get_input_devices() returns:

• B_OK. Success.

• B_ERROR. General failure.

• B_BAD_PORT_ID. Couldn't talk to the Input Server.

• B_TIMED_OUT. The Input Server is no longer on speaking terms with your application.

• B_WOULD_BLOCK. More trouble communicating with the Input Server.

watch_input_devices()

status_t watch_input_devices(BMessenger target, bool start)

Tells the Input Server to start or stop watching (as start is true or false) for changes to the set of registered devices. Change notifications are sent to target. The set of messages that the Server may send are listed in Input Server Messages.

watch_input_devices() is not currently implemented.