DPF/dgl/Events.hpp

/*
 * DISTRHO Plugin Framework (DPF)
 * Copyright (C) 2012-2021 Filipe Coelho <falktx@falktx.com>
 *
 * Permission to use, copy, modify, and/or distribute this software for any purpose with
 * or without fee is hereby granted, provided that the above copyright notice and this
 * permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
 * TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
 * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
 * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

#ifndef DGL_EVENTS_HPP_INCLUDED
#define DGL_EVENTS_HPP_INCLUDED

#include "Geometry.hpp"

START_NAMESPACE_DGL

// --------------------------------------------------------------------------------------------------------------------

namespace Events
{
   /**
      Base event data.
      These are the fields present on all Widget events.

      @a mod  Currently active keyboard modifiers, @see Modifier.
      @a mod  Event flags, @see Flag.
      @a time Event timestamp (if any).
    */
    struct BaseEvent {
        uint mod;
        uint flags;
        uint time;

        /** Constuctor */
        BaseEvent() noexcept : mod(0x0), flags(0x0), time(0) {}
        /** Destuctor */
        virtual ~BaseEvent() noexcept {}
    };

   /**
      Keyboard event.

      This event represents low-level key presses and releases.
      This can be used for "direct" keyboard handing like key bindings, but must not be interpreted as text input.

      Keys are represented portably as Unicode code points, using the "natural" code point for the key.
      The @a key field is the code for the pressed key, without any modifiers applied.
      For example, a press or release of the 'A' key will have `key` 97 ('a')
      regardless of whether shift or control are being held.

      Alternatively, the raw @a keycode can be used to work directly with physical keys,
      but note that this value is not portable and differs between platforms and hardware.

      @a press   True if the key was pressed, false if released.
      @a key     Unicode point of the key pressed.
      @a keycode Raw keycode.
      @see onKeyboard
    */
    struct KeyboardEvent : BaseEvent {
        bool press;
        uint key;
        uint keycode;

        /** Constuctor */
        KeyboardEvent() noexcept
            : BaseEvent(),
              press(false),
              key(0),
              keycode(0) {}
    };

   /**
      Special keyboard event.

      This event allows the use of keys that do not have unicode points.
      Note that some are non-printable keys.

      @a press True if the key was pressed, false if released.
      @a key   The key pressed.
      @see onSpecial
    */
    struct SpecialEvent : BaseEvent {
        bool press;
        Key  key;

        /** Constuctor */
        SpecialEvent() noexcept
            : BaseEvent(),
              press(false),
              key(Key(0)) {}
    };

   /**
      Character input event.

      This event represents text input, usually as the result of a key press.
      The text is given both as a Unicode character code and a UTF-8 string.

      Note that this event is generated by the platform's input system,
      so there is not necessarily a direct correspondence between text events and physical key presses.
      For example, with some input methods a sequence of several key presses will generate a single character.

      @a keycode   Raw key code.
      @a character Unicode character code.
      @a string    UTF-8 string.
      @see onCharacterInput
    */
    struct CharacterInputEvent : BaseEvent {
        uint keycode;
        uint character;
        char string[8];

        /** Constuctor */
        CharacterInputEvent() noexcept
            : BaseEvent(),
              keycode(0),
              character(0),
              string{'\0','\0','\0','\0','\0','\0','\0','\0'} {}
    };

   /**
      Mouse press or release event.

      @a button The button number starting from 1 (1 = left, 2 = middle, 3 = right).
      @a press  True if the button was pressed, false if released.
      @a pos    The widget-relative coordinates of the pointer.
      @see onMouse
    */
    struct MouseEvent : BaseEvent {
        uint button;
        bool press;
        Point<double> pos;

        /** Constuctor */
        MouseEvent() noexcept
            : BaseEvent(),
              button(0),
              press(false),
              pos(0.0, 0.0) {}
    };

   /**
      Mouse motion event.

      @a pos The widget-relative coordinates of the pointer.
      @see onMotion
    */
    struct MotionEvent : BaseEvent {
        Point<double> pos;

        /** Constuctor */
        MotionEvent() noexcept
            : BaseEvent(),
              pos(0.0, 0.0) {}
    };

   /**
      Mouse scroll event.

      The scroll distance is expressed in "lines",
      an arbitrary unit that corresponds to a single tick of a detented mouse wheel.
      For example, `delta.y` = 1.0 scrolls 1 line up.
      Some systems and devices support finer resolution and/or higher values for fast scrolls,
      so programs should handle any value gracefully.

      @a pos       The widget-relative coordinates of the pointer.
      @a delta     The scroll distance.
      @a direction The direction of the scroll or "smooth".
      @see onScroll
    */
    struct ScrollEvent : BaseEvent {
        Point<double> pos;
        Point<double> delta;
        ScrollDirection direction;

        /** Constuctor */
        ScrollEvent() noexcept
            : BaseEvent(),
              pos(0.0, 0.0),
              delta(0.0, 0.0),
              direction(kScrollSmooth) {}
    };

   /**
      Resize event.
      @a size    The new widget size.
      @a oldSize The previous size, may be null.
      @see onResize
    */
    struct ResizeEvent {
        Size<uint> size;
        Size<uint> oldSize;

        /** Constuctor */
        ResizeEvent() noexcept
            : size(0, 0),
              oldSize(0, 0) {}
    };

   /**
      Widget position changed event.
      @a pos    The new absolute position of the widget.
      @a oldPos The previous absolute position of the widget.
      @see onPositionChanged
    */
    struct PositionChangedEvent {
        Point<int> pos;
        Point<int> oldPos;

        /** Constuctor */
        PositionChangedEvent() noexcept
            : pos(0, 0),
              oldPos(0, 0) {}
    };
}

// --------------------------------------------------------------------------------------------------------------------

END_NAMESPACE_DGL

#endif // DGL_EVENTS_HPP_INCLUDED