events.h

Go to the documentation of this file.

/*! \file
  \brief  The standard Mouse and keyboard events and event structures

  \par Copyright Information

  Copyright (c) 2015 by The DiSTI Corporation.<br />
  11301 Corporate Blvd., Suite 100<br />
  Orlando, FL 32817<br />
  USA<br />
  <br />
  All rights reserved.<br />

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America. Use, distribution,
duplication, or disclosure by the U. S. Government is subject to
"Restricted Rights" as set forth in DFARS 252.227-7014(c)(1)(ii).
*/
#ifndef INCLUDED_DISTI_EVENTS_H
#define INCLUDED_DISTI_EVENTS_H

#include "component_base.h"
#include "display.h"
#include "gls_include.h"
#include "group.h"
#include "timer.h"
#include <string>

#ifdef __VXWORKS__
#    include <cctype> //tolower
#endif

namespace disti
{
/** Enumeration for event types */
typedef enum
{
    EVENT_MOUSE,      /**< A Mouse (or touch screen) event */
    EVENT_KEYBOARD,   /**< A Keyboard event */
    EVENT_TIMER,      /**< Unused */
    EVENT_OBJECT,     /**< An event emitted by an object */
    EVENT_KEYBOARD_UP /**< A Keyboard up event (uses KeyboardEvent class) */
} EventType_e;

/** Enumeration for mouse event types */
typedef enum
{
    MOUSE_DOWN,               /**< A Mouse button was pushed down */
    MOUSE_UP,                 /**< A Mouse button was released */
    MOUSE_MOVE,               /**< The mouse moved */
    MOUSE_DRAG,               /**< The mouse moved while a button was held down */
    MOUSE_LEAVE,              /**< The mouse exited the object */
    MOUSE_ENTER,              /**< The mouse entered the object */
    MOUSE_WHEEL_MINUS,        /**< The mouse wheel was turned in the negative direction */
    MOUSE_WHEEL_PLUS,         /**< The mouse wheel was turned in the positive direction */
    MOUSE_RECEIVE_MULTITOUCH, /**< Handle this event to receive input from multiple touches at the same time */
    MOUSE_CANCEL              /**< Handle this event to interrupt the current mouse event */
} MouseEventType_e;

/** Enumeration for mouse buttons */
typedef enum
{
    MOUSE_LBUTTON    = 1, /**< Mask that matches only left mouse button */
    MOUSE_MBUTTON    = 2, /**< Mask that matches only middle mouse button */
    MOUSE_RBUTTON    = 4, /**< Mask that matches only right mouse button */
    MOUSE_BUTTON_ANY = 7  /**< Mask that matches any mouse button */
} MouseButtonType_e;

/** Enumeration for keyboard modifiers */
typedef enum
{
    NONE_STATE        = 0,
    SHIFT_STATE       = 0x00010000,
    CAPS_LOCK_STATE   = 0x00020000,
    CTRL_STATE        = 0x00040000,
    ALT_STATE         = 0x00080000,
    NUM_LOCK_STATE    = 0x00100000,
    META_STATE        = 0x00400000,
    SCROLL_LOCK_STATE = 0x00800000,
    BUTTON1_STATE     = 0x01000000,
    BUTTON2_STATE     = 0x02000000,
    BUTTON3_STATE     = 0x04000000
} SpecialKeyState_e;

/** The base class for all user defined events.
  * Each new class of event is assigned an event type.
  * Each new event is assigned an event subtype
  */
class DisplayEvent
{
public:
    unsigned short eventType;    /**< Major event code. e.g., EVENT_MOUSE */
    unsigned short eventSubtype; /**< Minor event code. e.g., MOUSE_DOWN */

    /** Default constructor */
    DisplayEvent()
        : eventType( 0u )
        , eventSubtype( 0u )
    {
    }

    /** Copy constructor */
    DisplayEvent( const DisplayEvent& source )
        : eventType( source.eventType )
        , eventSubtype( source.eventSubtype )
    {
    }

    /** Virtual deconstructor to enable RTTI */
    virtual ~DisplayEvent()
    {
    }
};

/** An event with location fields */
class LocationEvent : public DisplayEvent
{
public:
    /** Location of the event in window coordinates
      * x and y window coordinates in pixels.
      * z is from 0.0 -> 1.0 and represents the depth.
      * z == 0 is at the near cliping plane.
      * z == 0.5 represents half way between near
      * and far cliping planes.
      */
    Vector winLoc;

    /** x,y,z of event in logical design coordinates */
    Vector lCoords;

    /** x,y,z of event in object DCS coordinates */
    Vector oCoords;

    // These references are included for backwards compatibility with GL Studio 2.1.
    // They are simply references into the above vectors.  New code should not use these!
    float& x; /**< Reference to winLoc.x */
    float& y; /**< Reference to winLoc.y */
    float& z; /**< Reference to winLoc.z */

    float& lx; /**< Reference to lCoords.x */
    float& ly; /**< Reference to lCoords.y */
    float& lz; /**< Reference to lCoords.z */

    float& ox; /**< Reference to oCoords.x */
    float& oy; /**< Reference to oCoords.y */
    float& oz; /**< Reference to oCoords.z */

    /** Because of the use of the references, all automatically generated methods
      * must be defined to allow for copying. */

    /** Default constructor */
    LocationEvent()
        : DisplayEvent()
        , x( winLoc.x )
        , y( winLoc.y )
        , z( winLoc.z )
        , lx( lCoords.x )
        , ly( lCoords.y )
        , lz( lCoords.z )
        , ox( oCoords.x )
        , oy( oCoords.y )
        , oz( oCoords.z )
    {
    }

    /** Copy Constructor */
    LocationEvent( const LocationEvent& source )
        : DisplayEvent( source )
        , winLoc( source.winLoc )
        , lCoords( source.lCoords )
        , oCoords( source.oCoords )
        , x( winLoc.x )
        , y( winLoc.y )
        , z( winLoc.z )
        , lx( lCoords.x )
        , ly( lCoords.y )
        , lz( lCoords.z )
        , ox( oCoords.x )
        , oy( oCoords.y )
        , oz( oCoords.z )
    {
    }

    /** Assignment operator */
    LocationEvent operator=( const LocationEvent& source )
    {
        eventType    = source.eventType;
        eventSubtype = source.eventSubtype;
        winLoc       = source.winLoc;
        lCoords      = source.lCoords;
        oCoords      = source.oCoords;
        return *this;
    }
};

/** A mouse event */
class MouseEvent : public LocationEvent
{
public:
    /** Default Constructor */
    MouseEvent()
        : LocationEvent()
        , buttonMask( 0u )
        , clicks( 0u )
        , modifiers( 0 )
        , cursorID( 0u )
    {
        eventType = EVENT_MOUSE;
    }

    /** Copy Constructor */
    MouseEvent( const MouseEvent& source )
        : LocationEvent( source )
        , buttonMask( source.buttonMask )
        , clicks( source.clicks )
        , modifiers( source.modifiers )
        , cursorID( source.cursorID )
    {
    }

    /** Copy Constructor from LocationEvent */
    MouseEvent( const LocationEvent& source )
        : LocationEvent( source )
        , buttonMask( 0u )
        , clicks( 0u )
        , modifiers( 0 )
        , cursorID( 0u )
    {
        eventType = EVENT_MOUSE;
    }

    /** Assignment operator */
    MouseEvent operator=( const MouseEvent& source )
    {
        LocationEvent::operator=( source );
        buttonMask             = source.buttonMask;
        clicks                 = source.clicks;
        modifiers              = source.modifiers;
        cursorID               = source.cursorID;
        return *this;
    }

    unsigned char buttonMask; /**< bitfield: which button was pressed for this event */
    unsigned char clicks;     /**< Number of times a button was pressed */
    int           modifiers;  /**< bitfield: which buttons or modifiers were depressed before event \sa SpecialKeyState_e */
    unsigned int  cursorID;   /**< cursor id for multi-touch support */
};

/** A keyboard event */
class KeyboardEvent : public LocationEvent
{
public:
    /** Default Constructor */
    KeyboardEvent()
        : LocationEvent()
        , keysym( 0 )
        , event_text( 0 )
        , modifiers( 0 )
    {
    }

    /** Copy Constructor */
    KeyboardEvent( const KeyboardEvent& source )
        : LocationEvent( source )
        , keysym( source.keysym )
        , event_text( source.event_text )
        , modifiers( source.modifiers )
    {
    }

    /** Copy Constructor from LocationEvent*/
    KeyboardEvent( const LocationEvent& source )
        : LocationEvent( source )
        , keysym( 0 )
        , event_text( 0 )
        , modifiers( 0 )
    {
    }

    /** Assignment operator */
    KeyboardEvent operator=( const KeyboardEvent& source )
    {
        LocationEvent::operator=( source );
        keysym                 = source.keysym;
        event_text             = source.event_text;
        modifiers              = source.modifiers;
        return *this;
    }

    int keysym;     /**< FLTK code for key that was pressed */
    int event_text; /**< FLTK event text code for key that was pressed */
    int modifiers;  /**< bitfield: which modifiers or buttons were pressed \sa SpecialKeyState_e */
};

/** The ObjectEvent class
  * This event is intended to be emitted by objects, rather than by a mouse or keyboard.
  */
class ObjectEvent : public DisplayEvent
{
    DisplayObject* _initiator; /**< The display object that initiated the event */
    char*          _eventName; /**< String event name */
    char*          _eventData; /**< Any additional data for this event.  A NULL terminated string */

public:
    ObjectEvent()
        : DisplayEvent()
        , _initiator( NULL )
        , _eventName( NULL )
        , _eventData( NULL )
    {
        eventType = EVENT_OBJECT;
    }

    /** Create an ObjectEvent, setting the initator and event name
      * \param initiator  Pointer to the object that initated the event
      * \param eventName  Name of the event
      * \param eventData  Data of the event
      */
    ObjectEvent( DisplayObject* initiator, const char* eventName, const char* eventData = NULL )
        : DisplayEvent()
        , _initiator( initiator )
        , _eventName( NULL )
        , _eventData( NULL )
    {
        int size   = (int)strlen( eventName ) + 1;
        _eventName = new char[ size ];
#if defined( _WIN32 )
        strcpy_s( _eventName, size, eventName );
#else
        strcpy( _eventName, eventName );
#endif
        if( eventData )
        {
            size       = (int)strlen( eventData ) + 1;
            _eventData = new char[ size ];
#if defined( _WIN32 )
            strcpy_s( _eventData, size, eventData );
#else
            strcpy( _eventData, eventData );
#endif
        }

        eventType = EVENT_OBJECT;
    }

    /** Create an ObjectEvent, setting the initator and event subtype
      * \param initiator Pointer to the object that initated the event
      * \param eventSubtypeArg The arbitrary event subtype
      */
    ObjectEvent( DisplayObject* initiator, unsigned short eventSubtypeArg )
        : DisplayEvent()
        , _initiator( initiator )
        , _eventName( NULL )
        , _eventData( NULL )
    {
        eventType    = EVENT_OBJECT;
        eventSubtype = eventSubtypeArg;
    }

    virtual ~ObjectEvent()
    {
        delete[] _eventName;
        _eventName = NULL;

        delete[] _eventData;
        _eventData = NULL;
    }

    /** \return Pointer to the object that initiated the event (may be NULL)
      */
    DisplayObject* Initiator() const { return _initiator; }

    /** Set which object initiated the event
      * \param initiator  Pointer to the object that initiated the event
      */
    void Initiator( DisplayObject* initiator ) { _initiator = initiator; }

    /** \return The name of the event
      */
    const char* EventName() const
    {
        if( _eventName )
        {
            return _eventName;
        }
        else
        {
            return "";
        }
    }

    /** Set the name of the event
      * For CRT safety, this should only be called by the constructing code
      * \param newName  The name to set
      */
    void EventName( const char* newName )
    {
        delete[] _eventName;
        _eventName = NULL;

        if( newName )
        {
            int size   = (int)strlen( newName ) + 1;
            _eventName = new char[ size ];
#if defined( _WIN32 )
            strcpy_s( _eventName, size, newName );
#else
            strcpy( _eventName, newName );
#endif
        }
    }

    /** \return The data of the event, NULL terminated
      */
    const char* EventData() const
    {
        if( _eventData )
        {
            return _eventData;
        }
        else
        {
            return "";
        }
    }

    /** Set the data of the event, NULL terminated.
      * For CRT safety, this should only be called by the constructing code
      * \param newData The name to set
      */
    void EventData( const char* newData )
    {
        delete[] _eventData;
        _eventData = NULL;

        if( newData )
        {
            int size   = (int)strlen( newData ) + 1;
            _eventData = new char[ size ];
#if defined( _WIN32 )
            strcpy_s( _eventData, size, newData );
#else
            strcpy( _eventData, newData );
#endif
        }
    }

    /** return true if the name of this event matches the given name.
      * \param eventName  The name to compare
      */
    bool EventNameIs( const char* eventName ) const
    {
        if( !_eventName || !eventName )
        {
            return false;
        }

        return ( 0 == strcmp( _eventName, eventName ) );
    }

    /** return true if the name of this event matches the given name.
      * \param eventData  The name to compare
      */
    bool EventDataIs( const char* eventData ) const
    {
        if( !_eventData || !eventData )
        {
            return false;
        }

        return ( 0 == strcmp( _eventData, eventData ) );
    }
};

/** Emits the specfied ObjectEvent */
inline void EmitObjectEvent( DisplayObject* self, ObjectEvent* event )
{
    if( self->ParentGroup() )
    {
        self->ParentGroup()->handle( event );
    }
    else if( dynamic_cast<ComponentBase*>( self ) )
    {
        // Called when our ParentGroup is NULL and we are wrapped by an RSO Interface.
        self->handle( event );
    }
}

/** Creates an ObjectEvent from the given NULL terminated strings and emits it */
inline void EmitObjectEvent( DisplayObject* self, const char* eventName, const char* eventData = NULL )
{
    ObjectEvent temp( self, eventName, eventData );
    EmitObjectEvent( self, &temp );
}

/** \return true if the given DisplayEvent is an ObjectEvent and it's event name matches the given string.
  * \param event  The event to check
  * \param eventName  The eventName to compare
  * \param eventData optional eventData to compare, if NULL, it will not be checked, otherwise, it will.
  */
inline bool ObjectEventIs( DisplayEvent* event, const char* eventName, const char* eventData = NULL )
{
    ObjectEvent* objEvent = dynamic_cast<ObjectEvent*>( event );
    bool         is       = ( objEvent && objEvent->EventNameIs( eventName ) );
    if( is && eventData )
    {
        is = objEvent->EventDataIs( eventData );
    }
    return is;
}

/** Basic on event test, given the event and subevent enums. */
#define ON( event, subevent ) if( ( ev->eventType == ( event ) ) && ( ev->eventSubtype == ( subevent ) ) )

/** On mouse button up event test, given the mouse button enum. */
#define ON_MOUSE_UP( btnMask ) if( ( ev->eventType == EVENT_MOUSE ) && ( ev->eventSubtype == MOUSE_UP ) && ( (btnMask)&mev->buttonMask ) )

/** On mouse button down event test, given the mouse button enum. */
#define ON_MOUSE_DOWN( btnMask ) if( ( ev->eventType == EVENT_MOUSE ) && ( ev->eventSubtype == MOUSE_DOWN ) && ( (btnMask)&mev->buttonMask ) )

/** On mouse button held during a drag event test, given the mouse button enum. */
#define ON_MOUSE_DRAG( btnMask ) if( ( ev->eventType == EVENT_MOUSE ) && ( ev->eventSubtype == MOUSE_DRAG ) && ( (btnMask)&mev->buttonMask ) )

/** On keyboard key down event test, given the alpha numeric key to test. */
#define ON_KEY_DOWN( testKey ) if( ( ev->eventType == EVENT_KEYBOARD ) && OnKeyEvent( kev, true, int( testKey ) ) )

/** On keyboard key up event test, given the alpha numeric key to test. */
#define ON_KEY_UP( testKey ) if( ( ev->eventType == EVENT_KEYBOARD_UP ) && OnKeyEvent( kev, true, int( testKey ) ) )

/** On keyboard key down with modifiers event test, given the alpha numeric key and modifiers to test. */
#define ON_KEY_DOWN_WITH_MODIFIER( testKey, modifierMask ) if( ( ev->eventType == EVENT_KEYBOARD ) && OnKeyEvent( kev, true, int( testKey ), modifierMask ) )

/** On keyboard key up with modifiers event test, given the alpha numeric key and modifiers to test. */
#define ON_KEY_UP_WITH_MODIFIER( testKey, modifierMask ) if( ( ev->eventType == EVENT_KEYBOARD_UP ) && OnKeyEvent( kev, true, int( testKey ), modifierMask ) )

/** On keyboard key down event test, given the special key to test. */
#define ON_SPECIAL_KEY_DOWN( keySym ) if( ( ev->eventType == EVENT_KEYBOARD ) && OnKeyEvent( kev, false, int( keySym ) ) )

/** On keyboard key up event test, given the special key to test. */
#define ON_SPECIAL_KEY_UP( keySym ) if( ( ev->eventType == EVENT_KEYBOARD_UP ) && OnKeyEvent( kev, false, int( keySym ) ) )

/** On keyboard key down with modifiers event test, given the special key and modifiers to test. */
#define ON_SPECIAL_KEY_DOWN_WITH_MODIFIER( keySym, modifierMask ) if( ( ev->eventType == EVENT_KEYBOARD ) && OnKeyEvent( kev, false, int( keySym ), modifierMask ) )

/** On keyboard key up with modifiers event test, given the special key and modifiers to test. */
#define ON_SPECIAL_KEY_UP_WITH_MODIFIER( keySym, modifierMask ) if( ( ev->eventType == EVENT_KEYBOARD_UP ) && OnKeyEvent( kev, false, int( keySym ), modifierMask ) )

/** On keyboard key down event test. */
#define ON_ANY_KEY_DOWN() if( ( ev->eventType == EVENT_KEYBOARD ) )

/** On keyboard key up event test. */
#define ON_ANY_KEY_UP() if( ( ev->eventType == EVENT_KEYBOARD_UP ) )

/** Examples:
  *     ON( EVENT_MOUSE, MOUSE_DOWN )
  *     {
  *     }
  *     ON_MOUSE_DOWN( MOUSE_LBUTTON )
  *     {
  *     }
  *     ON_KEY_DOWN( 'a' )
  *     {
  *     }
  *     ON_KEY_DOWN_WITH_MODIFIER( 'B', FL_SHIFT )
  *     {
  *     }
  *     ON_KEY_DOWN_WITH_MODIFIER( 'c', FL_SHIFT | FL_CTRL )
  *     {
  *     }
  *     ON_SPECIAL_KEY_DOWN( FL_KP+'1' )
  *     {
  *     }
  *     ON_SPECIAL_KEY_DOWN_WITH_MODIFIER( FL_F+1, FL_CTRL )
  *     {
  *     }
  *     For a comprehensive list of keys and modifiers refer to Enumerations.H.
  */

inline bool OnKeyEvent( KeyboardEvent* kev, bool alphaNumeric, int key, int modifierMask = 0 )
{
    bool keySuccess = false;

    if( alphaNumeric )
    {
        /** If CTRL is expected we need to look at keysym instead.
          * Because CTRL changes the output of the key press to something unexpected
          * we need to check against the key press action instead. 
          */
        if( CTRL_STATE & modifierMask )
        {
            /** keysym is always lowercase */
            key        = std::tolower( key );
            keySuccess = ( key == kev->keysym );
        }
        else
        {
            keySuccess = ( key == kev->event_text );
        }
    }
    else
    {
        keySuccess = ( key == kev->keysym );
    }

    /** Compare to zero to avoid performance warnings. 
      * Did we find the modifiers we're looking for (modifierMask) in the modifiers currently pressed (kev->modifiers)?
      * OR Are we not looking for any modifiers AND none of the modifiers are currently pressed?
      * (ignoring the lock state and mouse button modifiers)
      */
    bool modSuccess = ( 0 != ( modifierMask & kev->modifiers ) || ( 0 == modifierMask && 0 == ( int( SHIFT_STATE | CTRL_STATE | ALT_STATE | META_STATE ) & kev->modifiers ) ) );

    return ( keySuccess && modSuccess );
}

template<class T>
/** Event Compressor */
class EventCompressor
{
public:
    typedef DisplayObject* ( T::*EventSenderCbType )( DisplayEvent* ev );

protected:
    MouseEvent        _lastCompressedEvent;
    bool              _lastEventWasCompressed;
    EventSenderCbType _handleCb;
    T*                _objectPtr;
    bool              _sendingCompressed;
    bool              _active;

public:
    void Active( bool val ) { _active = val; }
    bool Active() { return _active; }

    EventCompressor( T* objectPtr, EventSenderCbType cb )
        : _lastEventWasCompressed( false )
        , _handleCb( cb )
        , _objectPtr( objectPtr )
        , _sendingCompressed( false )
        , _active( true )
    {
    }

    /** Returns true if event was compressed.
      * Caller should stop processing this event if returns true
      * Caller *MUST* call SendAnyCompressedEvents() before
      * drawing to make sure any saved events are processed.
      */
    bool CompressEvent( const DisplayEvent& ev )
    {
        if( !_active || _sendingCompressed )
        {
            return false;
        }

        bool compressed = false;
        if( EVENT_MOUSE == ev.eventType && ( MOUSE_MOVE == ev.eventSubtype || MOUSE_DRAG == ev.eventSubtype ) )
        {
            MouseEvent* mev = (MouseEvent*)&ev;

            if( !_lastEventWasCompressed || ( _lastEventWasCompressed && _lastCompressedEvent.eventType == ev.eventType && _lastCompressedEvent.eventSubtype == ev.eventSubtype && _lastCompressedEvent.cursorID == mev->cursorID ) )
            {
                // Replace with this event, and don't send
                _lastCompressedEvent    = *mev;
                _lastEventWasCompressed = true;
                compressed              = true;
            }
        }

        // If we did not compress the event, send any pending ones.
        if( !compressed )
        {
            SendAnyCompressedEvents();
        }
        return compressed;
    }

    void SendAnyCompressedEvents()
    {
        // Avoids infinite loop
        if( _sendingCompressed )
        {
            return;
        }

        if( _lastEventWasCompressed )
        {
            _sendingCompressed = true;
            // Call the callback
            ( _objectPtr->*( _handleCb ) )( &_lastCompressedEvent );
            // The event is no longer valid
            _sendingCompressed = false;

            _lastEventWasCompressed = false;
        }
    }
};

} // namespace disti

#endif // INCLUDED_DISTI_EVENTS_H