The Device Kit: BJoystick

Derived from: public BObject

Declared in: <device/Joystick.h>


Overview

A BJoystick object provides an interface to a joystick connected to the BeBox. There are two joystick ports on the back of the machine, one above the other. With the aid of a simple Y connector, each of them can support two joysticks for a total of four ports.

Unlike the event and message-driven interface to the mouse and keyboard, the interface to a joystick is strictly demand-driven. An application must repeatedly poll the state of the joystick by calling the BJoystick object's Update() function. Update() queries the port and updates the object's data members to reflect the current state of the joystick.


Data Members

double timestamp The time of the most recent update, as measured in microseconds from the time the machine was last booted.
short horizontal The horizontal position of the joystick at the time of the last update.
short vertical The vertical position of the joystick at the time of the last update.
bool button1 TRUE if the first button was pressed at the time of the last update, and FALSE if not.
bool button2 TRUE if the second button was pressed at the time of the last update, and FALSE if not.

horizontal and vertical values can range from 0 through 4,095, but joysticks typically don't use the full range and some don't register all values within the range that is used. The scale is not linear--identical increments in different parts of the range can reflect differing amounts of horizontal and vertical movement. The exact variance from linearity and the extent of the usable range are partly characteristics of the individual joystick and partly functions of the BeBox hardware < which will be more fully documented in a later release >.


Constructor and Destructor


BJoystick()

      BJoystick(void)

Initializes the BJoystick object so that all values are set to 0. Before using the object, you must call Open() to open a particular joystick port. For the object to register any meaningful values, you must call Update() to query the open port.

See also: Open(), Update()


~BJoystick()

      virtual ~BJoystick(void)

Closes the port, if it was not closed already.


Member Functions


Open(), Close()

      long Open(const char *name)
      void Close(void)

These functions open the name joystick port and close it again. There are two ports on the back panel of the BeBox, and they have names that correspond to their labels on the machine (and in The Be User's Guide diagram):

"joystick1" (on the top)
"joystick2" (on the bottom)

By attaching a Y cable to a machine port, you can make it support two joysticks. Cables, therefore, add two additional ports:

"joystick3" (on the top)
"joystick4" (on the bottom)

The cable maps the bottom row of pins on a machine port to the top row on a cable port. Therefore, the first two names listed above correspond to the top row of pins on a machine port; the last two names correspond to the bottom row of pins.

If it's able to open the port, Open() returns a positive integer. If unable or if the name isn't valid, it returns B_ERROR. If the name port is already open, Open() tries to close it first, then open it again.

To be able to obtain joystick data, a BJoystick object must have a port open.


Update()

      long Update(void)

Updates the data members of the object so that they reflect the current state of the joystick. An application would typically call Update() periodically to poll the condition of the device, then read the values of the data members.

This function returns B_ERROR if the BJoystick object doesn't have a port open, and B_NO_ERROR if it does.






The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.

Copyright © 1996 Be, Inc. All rights reserved.

Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.

Last modified September 6, 1996.