//
// Global event header file for the Fast Light Tool Kit (FLTK).
//
// Copyright 2025 by Bill Spitzak and others.
//
// This library is free software. Distribution and use rights are outlined in
// the file "COPYING" which should have been included with this file.  If this
// file is missing or damaged, see the license at:
//
//     https://www.fltk.org/COPYING.php
//
// Please see the following page on how to report bugs and issues:
//
//     https://www.fltk.org/bugs.php
//

/** \file FL/core/events.H
  \brief Global event handling variables and functions.
*/

#ifndef Fl_core_events_H
#define Fl_core_events_H

#include <FL/fl_config.h>             // build configuration
#include <FL/Fl_Export.H>             // for FL_EXPORT
#include <FL/core/function_types.H>   // widget callbacks and services

class Fl_Widget;

namespace Fl {

//
// Event Variables (Internal)
// Note: These variables should be private, but would harm back compatibility.
//

#ifndef FL_DOXYGEN

// Core event information
FL_EXPORT extern int                e_number;           ///< Current event type
FL_EXPORT extern int                e_state;            ///< Keyboard/mouse button states

// Mouse position and movement
FL_EXPORT extern int                e_x;                ///< Mouse X position (window relative)
FL_EXPORT extern int                e_y;                ///< Mouse Y position (window relative)
FL_EXPORT extern int                e_x_root;           ///< Mouse X position (screen absolute)
FL_EXPORT extern int                e_y_root;           ///< Mouse Y position (screen absolute)
FL_EXPORT extern int                e_dx;               ///< Mouse wheel horizontal delta
FL_EXPORT extern int                e_dy;               ///< Mouse wheel vertical delta

// Mouse click handling
FL_EXPORT extern int                e_clicks;           ///< Number of consecutive clicks
FL_EXPORT extern int                e_is_click;         ///< True if event qualifies as click

// Keyboard event data
FL_EXPORT extern int                e_keysym;           ///< Key symbol for current event
FL_EXPORT extern int                e_original_keysym;  ///< Original key before NumLock translation
FL_EXPORT extern char*              e_text;             ///< Text associated with key event
FL_EXPORT extern int                e_length;           ///< Length of text in e_text

// Clipboard data (for paste events)
FL_EXPORT extern void*              e_clipboard_data;   ///< Pasted data pointer
FL_EXPORT extern const char*        e_clipboard_type;   ///< Type of pasted data

// Event handling infrastructure
FL_EXPORT extern Fl_Event_Dispatch  e_dispatch;         ///< Custom event dispatcher
FL_EXPORT extern Fl_Callback_Reason callback_reason_;   ///< Reason for current callback

// Widget state tracking
FL_EXPORT extern Fl_Widget*         belowmouse_;        ///< Widget under mouse cursor
FL_EXPORT extern Fl_Widget*         pushed_;            ///< Widget receiving drag events
FL_EXPORT extern Fl_Widget*         focus_;             ///< Widget with keyboard focus

// Event variables should be private, but would harm back compatibility.

#endif // FL_DOXYGEN


/** \defgroup fl_events Events handling functions
      Fl class events handling API declared in <FL/Fl.H>
      @{
*/

//
// Event Information Functions
//

/**
  Returns the last event that was processed. This can be used
  to determine if a callback is being done in response to a
  keypress, mouse click, etc.
*/
FL_EXPORT inline int event()                    { return e_number; }

//
// Mouse Position Functions
//

/**
  Returns the mouse position of the event relative to the Fl_Window
  it was passed to.
*/
FL_EXPORT inline int event_x()                  { return e_x; }

/**
  Returns the mouse position of the event relative to the Fl_Window
  it was passed to.
*/
FL_EXPORT inline int event_y()                  { return e_y; }

/**
  Returns the mouse position on the screen of the event.  To find the
  absolute position of an Fl_Window on the screen, use the
  difference between event_x_root(),event_y_root() and
  event_x(),event_y().
*/
FL_EXPORT inline int event_x_root()             { return e_x_root; }

/**
  Returns the mouse position on the screen of the event.  To find the
  absolute position of an Fl_Window on the screen, use the
  difference between event_x_root(),event_y_root() and
  event_x(),event_y().
*/
FL_EXPORT inline int event_y_root()             { return e_y_root; }

//
// Mouse Wheel Functions
//

/**
  Returns the current horizontal mouse scrolling associated with the
  FL_MOUSEWHEEL event. Right is positive.
*/
FL_EXPORT inline int event_dx()                 { return e_dx; }

/**
  Returns the current vertical mouse scrolling associated with the
  FL_MOUSEWHEEL event. Down is positive.
*/
FL_EXPORT inline int event_dy()                 { return e_dy; }

//
// Mouse Query Functions
//

/**
  Return the number of the mouse-containing screen and computes the mouse screen coordinates.
  This requires a round-trip query to the server.  You should use Fl::event_x_root() and
  Fl::event_y_root() if possible, but this is necessary if you are
  not sure if a mouse event has been processed recently (such as to
  position your first window).  If the display is not open, this will
  open it.
 \param X,Y  assigned with the mouse screen coordinates upon return
 \return number of the mouse-containing screen
 \since 1.5 added a function return value
*/
FL_EXPORT extern int get_mouse(int &X,int &Y);

//
// Mouse Click Functions
//

/**
  Returns non zero if we had a double click event.
  \retval Non-zero if the most recent FL_PUSH or FL_KEYBOARD was a "double click".
  \retval  N-1 for  N clicks.
  A double click is counted if the same button is pressed
  again while event_is_click() is true.

 */
FL_EXPORT inline int event_clicks()             { return e_clicks; }

/**
  Manually sets the number returned by Fl::event_clicks().
  This can be used to set it to zero so that
  later code does not think an item was double-clicked.
  \param[in] i corresponds to no double-click if 0, i+1 mouse clicks otherwise
  \see int event_clicks()
*/
FL_EXPORT inline void event_clicks(int i)       { e_clicks = i; }

/**
  Returns non-zero if the mouse has not moved far enough
  and not enough time has passed since the last FL_PUSH or
  FL_KEYBOARD event for it to be considered a "drag" rather than a
  "click".  You can test this on FL_DRAG, FL_RELEASE,
  and FL_MOVE events.
*/
FL_EXPORT inline int event_is_click()           { return e_is_click; }

/**
 Clears the value returned by Fl::event_is_click().
 Useful to prevent the <I>next</I>
 click from being counted as a double-click or to make a popup menu
 pick an item with a single click.  Don't pass non-zero to this.
*/
FL_EXPORT inline void event_is_click(int i)     { e_is_click = i; }

//
// Mouse Button Functions
//

/**
  Gets which particular mouse button caused the current event.

  This returns garbage if the most recent event was not a FL_PUSH or FL_RELEASE event.
  \retval FL_LEFT_MOUSE
  \retval FL_MIDDLE_MOUSE
  \retval FL_RIGHT_MOUSE
  \retval FL_BACK_MOUSE
  \retval FL_FORWARD_MOUSE
  \see Fl::event_buttons(), Fl::event_state()
*/
FL_EXPORT inline int event_button()             { return e_keysym - FL_Button; }

//
// Event State Functions
//

/**
  Returns the keyboard and mouse button states of the last event.

  This is a bitfield of what shift states were on and what mouse buttons
  were held down during the most recent event.

  \note FLTK platforms differ in what Fl::event_state() returns when it is called
    while a modifier key or mouse button is being pressed or released.

  - Under X11 and Wayland, Fl::event_state() indicates the state of the modifier keys and
    mouse buttons just \b prior to the event. Thus, during the \c FL_KEYDOWN event generated
    when pressing the shift key, for example, the \c FL_SHIFT bit of event_state() is 0 and
    becomes 1 only at the next event which can be any other event, including e.g. \c FL_MOVE.
  - Under other platforms the reported state of modifier keys or mouse buttons includes that
    of the key or button being pressed or released.
  - Fl::event_state() returns the same value under all platforms when it's called while a
    non-modifier key (e.g. a letter or function key) is being pressed or released.
  - X servers do not agree on shift states, and \c FL_NUM_LOCK, \c FL_META, and \c FL_SCROLL_LOCK
    may not work.
  - The values were selected to match the XFree86 server on Linux.

  \note This inconsistency \b may be fixed (on X11 and Wayland) in a later release.

  The legal event state bits are:

    | Device   | State Bit      | Key or Button           | Since  |
    |----------|----------------|-------------------------|--------|
    | Keyboard | FL_SHIFT       | Shift                   |        |
    | Keyboard | FL_CAPS_LOCK   | Caps Lock               |        |
    | Keyboard | FL_CTRL        | Ctrl                    |        |
    | Keyboard | FL_ALT         | Alt                     |        |
    | Keyboard | FL_NUM_LOCK    | Num Lock                |        |
    | Keyboard | FL_META        | Meta, e.g. "Windows"    |        |
    | Keyboard | FL_SCROLL_LOCK | Scroll Lock             |        |
    | Mouse    | FL_BUTTON1     | left button             |        |
    | Mouse    | FL_BUTTON2     | middle button           |        |
    | Mouse    | FL_BUTTON3     | right button            |        |
    | Mouse    | FL_BUTTON4     | side button 1 (back)    | 1.3.10 |
    | Mouse    | FL_BUTTON5     | side button 2 (forward) | 1.3.10 |
*/
FL_EXPORT inline int event_state()              { return e_state; }

/** Returns non-zero if any of the passed event state bits are turned on.

  Use \p mask to pass the event states you're interested in.
  The legal event state bits are defined in Fl::event_state().
*/
FL_EXPORT inline int event_state(int mask)      { return e_state & mask; }

//
// Keyboard Event Functions
//

/**
  Gets which key on the keyboard was last pushed.

  The returned integer 'key code' is not necessarily a text
  equivalent for the keystroke. For instance: if someone presses '5' on the
  numeric keypad with numlock on, Fl::event_key() may return the 'key code'
  for this key, and NOT the character '5'. To always get the '5', use Fl::event_text() instead.

  \returns an integer 'key code', or 0 if the last event was not a key press or release.
  \see int event_key(int), event_text(), compose(int&).
*/
FL_EXPORT inline int event_key()                { return e_keysym; }

/**
  Returns the keycode of the last key event, regardless of the NumLock state.

  If NumLock is deactivated, FLTK translates events from the
  numeric keypad into the corresponding arrow key events.
  event_key() returns the translated key code, whereas
  event_original_key() returns the keycode before NumLock translation.
*/
FL_EXPORT inline int event_original_key()       { return e_original_keysym; }

/**
  Returns true if the given \p key was held
  down (or pressed) <I>during</I> the last event.  This is constant until
  the next event is read from the server.

  Fl::get_key(int) returns true if the given key is held down <I>now</I>.
  Under X this requires a round-trip to the server and is <I>much</I>
  slower than Fl::event_key(int).

  Keys are identified by the <I>unshifted</I> values. FLTK defines a
  set of symbols that should work on most modern machines for every key
  on the keyboard:

  \li All keys on the main keyboard producing a printable ASCII
      character use the value of that ASCII character (as though shift,
      ctrl, and caps lock were not on). The space bar is 32.
  \li All keys on the numeric keypad producing a printable ASCII
      character use the value of that ASCII character plus FL_KP
      (e.g., FL_KP + '4', FL_KP + '/').
      The highest possible value is FL_KP_Last so you can
      range-check to see if something is  on the keypad.
  \li All numbered function keys use the number on the function key plus
      FL_F.  The highest possible number is FL_F_Last, so you
      can range-check a value.
  \li Buttons on the mouse are considered keys, and use the button
      number (where the left button is 1) plus FL_Button.
  \li All other keys on the keypad have a symbol: FL_Escape,
      FL_BackSpace, FL_Tab, FL_Enter, FL_Print, FL_Scroll_Lock, FL_Pause,
      FL_Insert, FL_Home, FL_Page_Up, FL_Delete, FL_End, FL_Page_Down,
      FL_Left, FL_Up, FL_Right, FL_Down, FL_Iso_Key, FL_Shift_L, FL_Shift_R,
      FL_Control_L, FL_Control_R, FL_Caps_Lock, FL_Alt_L, FL_Alt_R,
      FL_Meta_L, FL_Meta_R, FL_Menu, FL_Num_Lock, FL_KP_Enter.  Be
      careful not to confuse these with the very similar, but all-caps,
      symbols used by Fl::event_state().

  On X Fl::get_key(FL_Button+n) does not work.

  On Windows Fl::get_key(FL_KP_Enter) and Fl::event_key(FL_KP_Enter) do not work.
*/
FL_EXPORT extern int event_key(int key);

/**
  Returns true if the given \p key is held down <I>now</I>.
  Under X this requires a round-trip to the server and is <I>much</I>
  slower than Fl::event_key(int). \see event_key(int)
*/
FL_EXPORT extern int get_key(int key); // platform dependent

//
// Text and Clipboard Functions
//

/**
  Returns the text associated with the current event, including FL_PASTE or FL_DND_RELEASE events.
  This can be used in response to FL_KEYUP, FL_KEYDOWN, FL_PASTE, and FL_DND_RELEASE.

  When responding to FL_KEYUP/FL_KEYDOWN, use this function instead of Fl::event_key()
  to get the text equivalent of keystrokes suitable for inserting into strings
  and text widgets.

  The returned string is guaranteed to be NULL terminated.
  However, see Fl::event_length() for the actual length of the string,
  in case the string itself contains NULLs that are part of the text data.

  \returns A NULL terminated text string equivalent of the last keystroke.
 */
FL_EXPORT inline const char* event_text()       { return e_text; }

/**
  Returns the length of the text in Fl::event_text(). There
  will always be a nul at this position in the text. However there may
  be a nul before that if the keystroke translates to a nul character or
  you paste a nul character.
*/
FL_EXPORT inline int event_length()             { return e_length; }

/**  Denotes plain textual data
 */
FL_EXPORT extern char const * const clipboard_plain_text;

/**  Denotes image data
 */
FL_EXPORT extern char const * const clipboard_image;

/** During an FL_PASTE event of non-textual data, returns a pointer to the pasted data.
 The returned data is an Fl_RGB_Image * when the result of Fl::event_clipboard_type() is Fl::clipboard_image.
 */
FL_EXPORT inline void *event_clipboard()        { return e_clipboard_data; }

/** Returns the type of the pasted data during an FL_PASTE event.
 This type can be Fl::clipboard_plain_text or Fl::clipboard_image.
 */
FL_EXPORT inline const char *event_clipboard_type() { return e_clipboard_type; }


//
// Advanced Event Functions
//

FL_EXPORT extern int compose(int &del);
FL_EXPORT extern void compose_reset();
FL_EXPORT extern int event_inside(int,int,int,int);
FL_EXPORT extern int event_inside(const Fl_Widget*);
FL_EXPORT extern int test_shortcut(Fl_Shortcut);

FL_EXPORT extern void enable_im();
FL_EXPORT extern void disable_im();

//
// Event Handling and Widget Management
//

FL_EXPORT extern int handle(int, Fl_Window*);
FL_EXPORT extern int handle_(int, Fl_Window*);

/**  Gets the widget that is below the mouse.
     \see  belowmouse(Fl_Widget*) */
FL_EXPORT inline Fl_Widget* belowmouse()        { return belowmouse_; }
FL_EXPORT extern void belowmouse(Fl_Widget*);

/** Gets the widget that is being pushed.
    \see void pushed(Fl_Widget*) */
FL_EXPORT inline Fl_Widget* pushed()            { return pushed_; }
FL_EXPORT extern void pushed(Fl_Widget*);

/** Gets the current Fl::focus() widget. \sa Fl::focus(Fl_Widget*) */
FL_EXPORT inline Fl_Widget* focus()             { return focus_; }
FL_EXPORT extern void focus(Fl_Widget*);

FL_EXPORT extern void add_handler(Fl_Event_Handler ha);
FL_EXPORT extern void add_handler(Fl_Event_Handler ha, Fl_Event_Handler before);
FL_EXPORT extern Fl_Event_Handler last_handler();
FL_EXPORT extern void remove_handler(Fl_Event_Handler h);
FL_EXPORT extern void add_system_handler(Fl_System_Handler h, void *data);
FL_EXPORT extern void remove_system_handler(Fl_System_Handler h);
FL_EXPORT extern void event_dispatch(Fl_Event_Dispatch d);
FL_EXPORT extern Fl_Event_Dispatch event_dispatch();
FL_EXPORT extern Fl_Callback_Reason callback_reason();

//
// Convenience State Check Functions
//

/** Returns non-zero if the Shift key is pressed. */
FL_EXPORT inline int event_shift()              { return e_state & FL_SHIFT; }

/** Returns non-zero if the Control key is pressed. */
FL_EXPORT inline int event_ctrl()               { return e_state & FL_CTRL; }

/** Returns non-zero if the FL_COMMAND key is pressed, either FL_CTRL or on OSX FL_META. */
FL_EXPORT inline int event_command()            { return e_state & FL_COMMAND; }

/** Returns non-zero if the Alt key is pressed. */
FL_EXPORT inline int event_alt()                { return e_state & FL_ALT; }

//
// Mouse Button State Functions
//

/**
  Returns the mouse buttons state bits; if non-zero, then at least one
  button is pressed now.  This function returns the button state at the
  time of the event. During an FL_RELEASE event, the state
  of the released button will be 0. To find out, which button
  caused an FL_RELEASE event, you can use Fl::event_button() instead.
  \return a bit mask value like { [FL_BUTTON1] | [FL_BUTTON2] | ... | [FL_BUTTON5] }
*/
FL_EXPORT inline int event_buttons()            { return e_state & FL_BUTTONS; }

/**
  Returns non-zero if mouse button 1 is currently held down.
  For more details, see Fl::event_buttons().
*/
FL_EXPORT inline int event_button1()            { return e_state & FL_BUTTON1; }

/**
  Returns non-zero if mouse button 2 is currently held down.
  For more details, see Fl::event_buttons().
*/
FL_EXPORT inline int event_button2()            { return e_state & FL_BUTTON2; }

/**
  Returns non-zero if mouse button 3 is currently held down.
  For more details, see Fl::event_buttons().
*/
FL_EXPORT inline int event_button3()            { return e_state & FL_BUTTON3; }

/**
  Returns non-zero if mouse button 4 is currently held down.
  For more details, see Fl::event_buttons().
*/
FL_EXPORT inline int event_button4()            { return e_state & FL_BUTTON4; }

/**
  Returns non-zero if mouse button 5 is currently held down.
  For more details, see Fl::event_buttons().
*/
FL_EXPORT inline int event_button5()            { return e_state & FL_BUTTON5; }

/**   @} */

} // namespace Fl

#endif // !Fl_core_events_H
