gls_knob.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsKnob class.
 
  \par Copyright Information
 
  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 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.
 
*/
#ifndef _GLS_KNOB_H
#define _GLS_KNOB_H
 
#include "gls_cpp_lang_support.h"
#include "group.h"
 
/// Provides support for creating DLLs.
#if( defined( GLSGEN_EXPORT_GlsKnob ) || defined( GLSGEN_IMPORT_GlsKnob ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GlsKnob ) || defined( GLS_EXPORT_GENERATED )
#        define GLSGEN_GlsKnob_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GlsKnob_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GlsKnob_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////
 
/// Automatically link the runtime library plugin (on Windows).
#define LIB_BASE_NAME "gls_knob"
#include "gls_auto_lib.h"
#undef LIB_BASE_NAME
 
namespace disti
{
enum
{
    GLS_GLSKNOB_CHANGE_CALLBACK = GLS_LAST_INITIALIZER + 1,
    GLS_GLSKNOB_ANGLERANGE,
    GLS_GLSKNOB_CONTINUOUS,
    GLS_GLSKNOB_POSITIONVAL,
    GLS_GLSKNOB_DETENTPOSITIONS,
    GLS_GLSKNOB_WHICHOBJECT,
    GLS_GLSKNOB_STARTANGLE,
    GLS_GLSKNOB_EMITDETENTVALEVENT,
    GLS_GLSKNOB_EMITPOSITIONVALEVENT,
    GLS_GLSKNOB_EMITLIMITEVENT,
    GLS_GLSKNOB_EMITRELEASEEVENT,
    GLS_GLSKNOB_SHOWDETENTSONLY,
    GLS_GLSKNOB_CLICKSELECTSDETENT
};
 
/** Runtime implementation of a knob */
class GlsKnob : public Group
{
public:
    friend class GlsKnobEditor;
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef Group _BaseClass; ///< Deprecated typedef for the base class.
    typedef Group BaseClass;  ///< Typedef for the base class.
 
    float               _angleRange;           ///< In degrees.
    int                 _numDetents;           ///< Number of detents, snap points of the knob.
    DynamicArray<float> _detentPositions;      ///< Range 0-100.
    float               _positionVal;          ///< Current knob position.
    bool                _continuous;           ///< If true, the knob can spin all the way around.
    int                 _whichObject;          ///< The object index in the group to be the knob.
    float               _startAngle;           ///< An angle offset from the begining position.
    bool                _emitDetentValEvent;   ///< If true, will emit an event when snapping to a detent.
    bool                _emitPositionValEvent; ///< If true, will emit an event when the position is changed.
 
    /// Set if object should emit the DeventVal event.
    /// \param value The new flag to set.
    inline void EmitDetentValEvent( const bool& value );
 
    /// \return Whether object should emit the DeventVal event.
    inline bool EmitDetentValEvent() { return _emitDetentValEvent; }
 
    /// Set if object should emit the PositionVal event.
    /// \param value The new flag to set.
    inline void EmitPositionValEvent( const bool& value );
 
    /// \return Whether object should emit the PositionVal event.
    inline bool EmitPositionValEvent() { return _emitPositionValEvent; }
 
    /// Set if object should emit the Limit event.
    /// \param value The new flag to set.
    inline void EmitLimitEvent( const bool& value );
 
    /// \return Whether object should emit the Limit event.
    inline bool EmitLimitEvent() { return _emitLimitEvent; }
 
    /// Set if object should emit the Release event.
    /// \param value The new flag to set.
    inline void EmitReleaseEvent( const bool& value );
 
    /// \return Whether object should emit the Release event.
    inline bool EmitReleaseEvent() { return _emitReleaseEvent; }
 
    /** Create a new GlsKnob.
      * \param generateInstance  Whether or not to generate an instance name
      * for this inputdevice */
    GLSGEN_GlsKnob_EXPORT GlsKnob( bool generateInstance = false );
 
    /// Copy constructor
    /// \param that The object to copy from.
    /// \param generateNames Whether or not to generate an instance name.
    GLSGEN_GlsKnob_EXPORT GlsKnob( const GlsKnob& that, const bool generateNames );
 
    /** Destroy a GlsKnob object */
    virtual GLSGEN_GlsKnob_EXPORT ~GlsKnob();
 
    /// \return A pointer to a new GlsKnob object.
    static GLSGEN_GlsKnob_EXPORT DisplayObject* CreateInstance();
 
    virtual GLSGEN_GlsKnob_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsKnob_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsKnob_EXPORT void           PreDraw( const OpenGLMatrices& parentMatrices, Culler& culler ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsKnob_EXPORT void           Draw() DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsKnob_EXPORT void           CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
 
#ifndef GLES
    virtual GLSGEN_GlsKnob_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GlsKnob_EXPORT void               GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
#endif
 
    virtual GLSGEN_GlsKnob_EXPORT void SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;
    GLSGEN_GlsKnob_EXPORT DisplayObject* handle( DisplayEvent* ev ) DISTI_METHOD_OVERRIDE;
 
    //////////////////////////////////////////////////
    // Knob specific operations
    //////////////////////////////////////////////////
 
    /// Set the value of the ShowDetentsOnly property.
    /// \param value The new value to set.
    GLSGEN_GlsKnob_EXPORT void ShowDetentsOnly( const bool& value );
 
    /// \return The value of the ShowDetentsOnly property.
    inline bool ShowDetentsOnly() { return _showDetentsOnly; }
 
    /// Sets the value of the ClickSelectsDetent property.
    /// \param value The new value to set.
    inline void ClickSelectsDetent( const bool& value ) { _clickSelectsDetent = value; }
 
    /// \return The value of the ClickSelectsDetent property.
    inline bool ClickSelectsDetent() { return _clickSelectsDetent; }
 
    /** Moves the knob to the specified detent
      * Sets the detent value 
      * \param value Desired detent, first detent == 1
      */
    virtual GLSGEN_GlsKnob_EXPORT void DetentVal( const int& value );
 
    /** Returns the nearest detent for the knob's current poistion.
      * \return Nearest detent, first detent == 1
      */
    virtual GLSGEN_GlsKnob_EXPORT int DetentVal();
 
    /** Sets current position of the knob (0.0 - 100.0)
      * \param value New position of the knob (0.0 - 100.0)
      */
    virtual GLSGEN_GlsKnob_EXPORT void PositionVal( const float& value );
 
    /** Returns the current position of the knob (0.0 - 100.0)
      * \return Current knob position (0.0 - 100.0)
      */
    virtual GLSGEN_GlsKnob_EXPORT float PositionVal();
 
    /** Sets the current knob geometry index value
      * \param value Knob geometry index value
      */
    virtual GLSGEN_GlsKnob_EXPORT void WhichObject( const int& value );
 
    /** Returns the current knob geometry index value
      * \return Knob geometry index value
      */
    virtual GLSGEN_GlsKnob_EXPORT int WhichObject();
 
protected:
    bool _showDetentsOnly;    ///< If true, knob will only rotate to exact detents, nothing in between.
    bool _clickSelectsDetent; ///< If true, clicking on a detent will snap the knob to that detent.
 
    bool _emitLimitEvent;   ///< If true, an event will be emitted when the knob reaches its upper or lower limit.
    bool _emitReleaseEvent; ///< If true, an event will be emitted when the knob is released (mouse up).
 
    // Some private data for internal calculations
    int    _initialDetentVal;         ///< Stores the initial detent position based on the starting rotation.
    float  _mouseDownoX;              ///< X position of the last mouse down in logical coordinates.
    float  _mouseDownoY;              ///< Y position of the last mouse down in logical coordinates.
    float  _mouseDownoZ;              ///< Z position of the last mouse down in logical coordinates.
    Vector _mouseDownDirectionVector; ///< Unused, kept for backward compatibility.
    float  _mouseDownAngle;           ///< Rotation angle of the knob when the mouse was pressed.
    float  _mouseLastAngle;           ///< The rotation angle of the knob on the previous frame.
    bool   _atCwStop;                 ///< If true, the knob has reached its clockwise most position.
    bool   _atCcwStop;                ///< If true, the knob has reached its counter clockwise most position.
 
    bool _sideMode; ///< If true, the knob is being viewed at or almost side on.
 
    /// \return The current rotation of the knob in degrees.
    GLSGEN_GlsKnob_EXPORT float CalcRotationAngle();
 
    bool         _mouseWasDown;  ///< If true, the mouse was clicked on a previous frame.
    unsigned int _currentCursor; ///< The current cursor used for interaction.  Any other cursors are ignored while interacting.
 
#ifdef GLES
    /** Set a single attribute from the GLO file.
     * \param data The attribute to set and its associated data.
     */
    virtual GLS_EXPORT void SetFromGloData( GlsGloFileAttribute& data ) DISTI_METHOD_OVERRIDE;
#endif
 
private:
    // disallow implicit assignments and copy constructor
    GlsKnob& operator=( const GlsKnob& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    GlsKnob( const GlsKnob& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};
 
} // namespace disti
 
#endif