The Input Server: BInputDevice

The Input Server Table of Contents | The Input Server Index

# BInputDevice

Derived from: none

Declared in: be/interface/InputDevice.h

Library: libbe.so

Allocation: By the system only. See

###### Summary

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.

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..