/*
* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  A listener interface to handle Joystick events
*
*/


package com.nokia.mid.ui;

/**
 * <p>
 *  A listener interface to learn when the state of a Joystick changes.
 * <p>
 * This API is an optional feature in Nokia UI API, and depending on the device
 * capabilities there may be implementations that do not support joystick
 * events. The System.getProperty("com.nokia.mid.ui.joystick_event") will
 * return "true" if this feature is available in the device.
 * <p>
 * A device may support analogue joystick which detects 360 directions and
 * force instead of standard 5 way key navigation.
 * (Up, Down, Left, Right and Centre).
 * <p>
 * The joystick sends events every time its position or force changes.
 * This events are represented by x (horizontal) and y (vertical) vector
 * components. In its original position (centre), the value for (x, y)
 * are (0,0). As an example, suppose that the (-5,5) event was received.
 * It means that the joystick is held in the left and up diagonal.
 * Now, if the (-25,25) event is sent, it means that the Joystick is still
 * in the same direction of (-5,5), however more force were applied.
 * <p>
 * The maximum and minimum values of x and y are -127 and 127.
 * <p>
 * If the MIDlet needs to receive joystick events, it must provide
 * an implementation of this interface from a Canvas class or subclass thereof.
 * The Canvas will still receive standard key / game key events too.
 * The Joystick events are sent only if the Canvas is in visible state.
 */
public interface JoystickEventListener
{

    /**
     * Called when the Joystick sends an event.
     * <p>
     * The events are relative to its original position (0,0)
     *
     * @param x the horizontal component. The value is negative if the
     *      joystick is moved to the left direction and positive if moved
     *      to right direction.
     * @param y the vertical component. The value is negative if the joystick
     *      is moved to the down direction and positive if moved
     *      to up direction.
     */
    void joystickEvent(int x, int y);
}