Handling Joystick Events

The wxJoystick class gives your application control over one or two joysticks on Windows or Linux. Typically, you'll create a wxJoystick object passing wxJOYSTICK1 or wxJOYSTICK2 and keep the object on the heap while it's needed. When you need input, call SetCapture passing a window pointer for receiving the joystick events, and then call ReleaseCapture when you no longer need the events. You might set the capture for the lifetime of the application instance (that is, calling SetCapture on initialization and ReleaseCapture on exit).

Before describing the events and functions in more detail, let's take a look at samples/joystick from the wxWidgets distribution. The user can control the joystick to draw a sequence of lines on a canvas by clicking on one of the joystick's buttons. Pressing the button also plays a sound.

The following is a snippet of the initialization code. First, the application checks whether a joystick is installed by creating a temporary joystick object, terminating if a joystick isn't found. The buttonpress.wav sound file is loaded into the wxSound object stored in the application object, and the minimum and maximum joystick positions are stored to permit scaling input to the size of the drawing window.

 #include "wx/wx.h" #include "wx/sound.h" #include "wx/joystick.h" bool MyApp::OnInit() {     wxJoystick stick(wxJOYSTICK1);     if (!stick.IsOk())     {         wxMessageBox(wxT("No joystick detected!"));         return false;     }     m_fire.Create(wxT("buttonpress.wav"));     m_minX = stick.GetXMin();     m_minY = stick.GetYMin();     m_maxX = stick.GetXMax();     m_maxY = stick.GetYMax();     // Create the main frame window     ...     return true; } 

MyCanvas is a window that stores the joystick object and also receives the joystick events. Here's the implementation of MyCanvas.

 BEGIN_EVENT_TABLE(MyCanvas, wxScrolledWindow)     EVT_JOYSTICK_EVENTS(MyCanvas::OnJoystickEvent) END_EVENT_TABLE() MyCanvas::MyCanvas(wxWindow *parent, const wxPoint& pos,     const wxSize& size):     wxScrolledWindow(parent, wxID_ANY, pos, size, wxSUNKEN_BORDER) {     m_stick = new wxJoystick(wxJOYSTICK1);     m_stick->SetCapture(this, 10); } MyCanvas::~MyCanvas() {     m_stick->ReleaseCapture();     delete m_stick; } void MyCanvas::OnJoystickEvent(wxJoystickEvent& event) {     static long xpos = -1;     static long ypos = -1;     wxClientDC dc(this);     wxPoint pt(event.GetPosition());     // if negative positions are possible then shift everything up     int xmin = wxGetApp().m_minX;     int xmax = wxGetApp().m_maxX;     int ymin = wxGetApp().m_minY;     int ymax = wxGetApp().m_maxY;     if (xmin < 0) {         xmax += abs(xmin);         pt.x += abs(xmin);     }     if (ymin < 0) {         ymax += abs(ymin);         pt.y += abs(ymin);     }     // Scale to canvas size     int cw, ch;     GetSize(&cw, &ch);     pt.x = (long) (((double)pt.x/(double)xmax) * cw);     pt.y = (long) (((double)pt.y/(double)ymax) * ch);     if (xpos > -1 && ypos > -1 && event.IsMove() && event.ButtonIsDown())     {         dc.SetPen(*wxBLACK_PEN);         dc.DrawLine(xpos, ypos, pt.x, pt.y);     }     xpos = pt.x;     ypos = pt.y;     wxString buf;     if (event.ButtonDown())         buf.Printf(wxT("Joystick (%d, %d) Fire!"), pt.x, pt.y);     else         buf.Printf(wxT("Joystick (%d, %d)"), pt.x, pt.y);     frame->SetStatusText(buf);     if (event.ButtonDown() && wxGetApp().m_fire.IsOk())     {         wxGetApp().m_fire.Play();     } } 

wxJoystick Events

wxJoystick generates events of type wxJoystickEvent, and the relevant event table macros are listed in Table 6-5. Each event table macro takes a single argument: the event handler function.

Table 6-5. Joystick Event Table Macros

EVT_JOY_BUTTON(func)	Handles a wxEVT_JOY_BUTTON_DOWN event, generated when a button is pressed.
EVT_JOY_BUTTON(func)	Handles a wxEVT_JOY_BUTTON_UP event, generated when a button is released.
EVT_JOY_MOVE(func)	Handles a wxEVT_JOY_MOVE event, generated when the joystick is moved in the X-Y plane.
EVT_JOY_ZMOVE(func)	Handles a wxEVT_JOY_ZMOVE event, generated when the joystick is moved in the z-axis.
EVT_JOYSTICK_EVENTS(func)	Handles all joystick events.

wxJoystickEvent Member Functions

These are the wxJoystickEvent functions you can call to retrieve more information about the event. As usual, you can call GetEventType to get the type, which is useful if you are using EVT_JOYSTICK_EVENTS to catch all joystick events.

Call ButtonDown to check if the event was a button press event; you can optionally pass a button identifier wxJOY_BUTTONn (where n is 1, 2, 3, or 4) to test which button was pressed, or wxJOY_BUTTON_ANY if you don't care which button was pressed. ButtonUp is similar but tests for a button up event. The function IsButton is equivalent to ButtonDown() || ButtonUp().

To test whether a button is down at the time of an event (not whether the event itself was a button press), call ButtonIsDown with the same arguments as for ButtonDown. Alternatively, use GetButtonState with the same arguments to return a bit-list of wxJOY_BUTTONn identifiers.

Call IsMove to test whether the event was a move event in the X-Y plane and IsZMove for a move in the z-axis.

GetPosition returns a wxPoint for the current joystick position in the X-Y plane, while GetZPosition returns an integer representing the Z position, if supported.

Finally, you can determine which joystick controller generated the event (wxJOYSTICK1 or wxJOYSTICK2) by calling GetJoystick.

wxJoystick Member Functions

We won't list the joystick functions exhaustivelyyou can refer to the wxJoystick class reference for thatbut the following are the more interesting ones.

As we've seen in the example, SetCapture needs to be called to direct joystick input to a specified window, with a matching ReleaseCapture to release it and enable other applications to take control of the joystick. In case another application has captured the joystick, or the joystick is not functioning, call IsOK before trying to capture input. You can also determine the capabilities of the joystick with GetNumberButtons, GetNumberJoysticks, GetNumberAxes, HasRudder, and other functions.

You can get the state of the joystick from outside an event handler with functions such as GetPosition and GetButtonState.

Your application will almost always need to call GetXMin, GetXMax, and similar functions in order to determine the range supported by the joystick.