fluid.io.hover

• interface HoverIO: fluid.io.io.IO;
  

  HoverIO is an input handler system that reads events off devices with the ability to point at the screen, like mouses, touchpads or pens.

  Most of the time, HoverIO systems will pass the events they receive to an ActionIO system, and then send these actions to a hovered node.

  Multiple different HoverIO instances can coexist in the same tree, allowing for multiple different nodes to be hovered at the same time, as long as they belong in different branches of the node tree. That means two different nodes can be hovered by two different HoverIO systems, but a single HoverIO system can only hover a single node.

  • abstract @safe int load(HoverPointer pointer);
    

    Load a hover pointer (mouse cursor, finger) and place it at the position currently indicated in the struct. Update the pointer's position if already loaded.

    It is expected load will be called after every pointer motion in order to keep its position up to date.

    A pointer is considered loaded until the next resize. If the load call for a pointer isn't repeated during a resize, the pointer is invalidated. Pointers do not have to be loaded while resizing; they can also be loaded while drawing.

    An example implementation of a pointer device, from inside of a node, could look like:

    HoverIO hoverIO;
    HoverPointer pointer;
    
    override void resizeImpl(Vector2) {
        require(hoverIO);
        minSize = Vector2();
    }
    
    override void drawImpl(Rectangle, Rectangle) {
        pointer.device = this;
        pointer.number = 0;
        pointer.position = mousePosition();
        load(mouseIO, pointer);
        if (clicked) {
            mouseIO.emitEvent(pointer, MouseIO.createEvent(MouseIO.Button.left, true));
        }
    }
    

    Parameters

    HoverPointer pointer

    Pointer to prepare. The pointer's device field should be set to whatever node represents this device, and the number field should be set to whatever number the device can associate with the pointer, if multiple pointers are to be used.

    Return value

    An ID the HoverIO system will use to recognize the pointer.

  • abstract @safe inout(HoverPointer) fetchPointer(int number) inout;
    

    Fetch a pointer from a number assigned to it by this I/O. This is used by Actionable nodes to find HoverPointer data corresponding to fired input action events.

    The pointer, and the matching number, must be valid.

    Parameters

    int number

    Number assigned to the pointer by this I/O.

    Return value

    The pointer.

  • abstract @safe void emitEvent(HoverPointer pointer, InputEvent event);
    

    Read an input event from an input device. Input devices will call this function every frame if an input event (such as a button press) occurs. Moving a mouse does not qualify as an input event.

    The hover pointer emitting the event must have been loaded earlier (using load) during the same frame for the action to work.

    HoverIO will usually pass these down to an ActionIO system. It is up to HoverIO to decide how the input and the resulting input actions is handled, though the node hovered by the pointer will most often receive them.

    Parameters

    HoverPointer pointer	Pointer that emitted the event.
    InputEvent event	Input event the system should emit. The event is usually considered "active" during the frame the action is "released". For example, user stops holding a mouse button, or a finger stops touching the screen.

  • abstract @safe inout(Hoverable) hoverOf(HoverPointer pointer) inout;
    

    Parameters

    HoverPointer pointer

    Pointer to query. The pointer must be loaded.

    Return value

    Node hovered by the hover pointer.

    See also

    scrollOf to get the current scrollable node.

  • abstract @safe inout(HoverScrollable) scrollOf(HoverPointer pointer) inout;
    

    Parameters

    HoverPointer pointer

    Pointer to query. The pointer must be loaded.

    Return value

    Scrollable ancestor for the currently hovered node.

    See also

    hoverOf to get the currently hovered node.

  • abstract @safe bool isHovered(const Hoverable hoverable) const;
    

    Return value

    True if the node is hovered.

    Parameters

    Hoverable hoverable

    True if this node is hovered.

  • abstract @safe int opApply(int delegate(HoverPointer) @safe yield);
    

    List all active hover pointer, namely all pointers that have been loaded since the last resize.

    Pointers do not need to be sorted.

    Parameters

    int delegate(HoverPointer) @safe yield

    A delegate to be called for every active node. Disabled nodes should be included. If the delegate returns a non-zero value, it should immediately break out of the loop and return this value.

    Return value

    If yield returned a non-zero value, it should be returned; if yield wasn't called, or has only returned zeroes, a zero is returned.

  • abstract @safe int opApply(int delegate(Hoverable) @safe yield);
    

    List all currently hovered nodes.

    Nodes do not need to be sorted.

    Parameters

    int delegate(Hoverable) @safe yield

    A delegate to be called for every hovered node. This should include nodes that block input, but are hovered. If the delegate returns a non-zero value, the value should be immediately returned.

    Return value

    If yield returned a non-zero value, this is the value it returned; if yield wasn't called, or has only returned zeroes, a zero is returned.

• interface ActionHoverIO: fluid.io.hover.HoverIO;
  

  An extension of HoverIO that enables support for dispatching and running input actions.

  • abstract @safe bool runInputAction(HoverPointer pointer, immutable InputActionID actionID, bool isActive = true);
    bool runInputAction(alias action)(HoverPointer pointer, bool isActive = true);
    

    Handle an input action associated with a pointer.

    Parameters

    HoverPointer pointer	Pointer to send the input action. It must be loaded. The input action will be loaded by the node the pointer points at.
    InputActionID actionID	ID of the input action.
    bool isActive	If true, the action has been activated during this frame.

    Return value

    True if the input action was handled.

• @safe bool hovers(HoverIO hoverIO);
  @safe bool hovers(HoverIO hoverIO, const Hoverable hoverable);
  

  Return value

  True if the hoverIO is hovering some node.

  Parameters

  HoverIO hoverIO	HoverIO to test.
  Hoverable hoverable	Node that HoverIO is expected to hover.

• bool hoversOnly(Range)(HoverIO hoverIO, Range hoverables)
  if (isForwardRange!Range && is(ElementType!Range : const(Hoverable)));
  

  Test if the hover I/O system hovers all of the nodes and none other.

  Parameters

  HoverIO hoverIO	Hover I/O system to test. Hoverables reported by this system will be checked.
  Range hoverables	A forward range of hoverables.

  Return value

  True if the system considers all of the given ranges as hovered, and it does not find any other nodes hovered.

• struct HoverPointer;
  

  A pointer is a position on the screen chosen by the user using a mouse, touchpad, touchscreen or other device capable of communicating some position.

  While in a typical desktop application there will usually be a single pointer at a time, there can be cases where there may be none (no mouse connected) or more (multitouch-enabled screen, multiple mouses connected, etc.)

  A pointer is associated with an I/O system that represents the device that invoked the pointer. This may be a dedicated mouse node, but it may also be a generic system that abstracts the device away; for example, Raylib provides a singular function for getting the mouse position without distinguishing between multiple devices or touchscreens.

  For a pointer to work, it has to be loaded into a HoverIO system using its load method. This has to be done once a frame for as long as the pointer is active. This will be every frame for a mouse (if one is connected), or only the frames a finger is touching the screen for a touchscreen.

  See also

  HoverIO, HoverIO.load

  • IO device;
    

    I/O system that represents the device controlling the pointer.

  • int number;
    

    If the device can control multiple pointers (like a touchscreen), this number should uniquely identify a pointer.

  • Vector2 position;
    

    Position in the window the pointer is pointing at.

  • Vector2 scroll;
    

    Current scroll value. For a mouse, this indicates mouse wheel movement, for other devices like touchpad or touchscreen, this will be translated from its movement.

    This value indicates the distance and direction in window space that the scroll should result in covering. This means that on the X axis negative values move left and positive values move right, while on the Y axis negative values go upwards and positive values go downwards. For example, a scroll value of (0, 20) scrolls 20 pixels down vertically, while (0, -10) scrolls 10 pixels up.

    While it is possible to read scroll of the HoverPointer data received in an input action handler, it is recommended to implement scroll through Scrollable.scrollImpl.

    Scroll is exposed for both the horizontal and vertical axis. While a basic mouse wheel only supports vertical movement, touchscreens, touchpads, trackpads or more advanced mouses do support horizontal movement. It is also possible for a device to perform both horizontal and vertical movement at once.

  • bool isDisabled;
    

    True if the pointer is not currently pointing, like a finger that stopped touching the screen.

  • int clickCount;
    

    Consecutive click counter. A value of 1 represents a single click, 2 is a double click, 3 is a triple click, and so on. The counter should reset after a small delay, or if a distance threshold is crossed.

    This value is usually provided by the system. If unavailable, you can use fluid.io.preference.MultipleClickCounter to generate this value from data available to Fluid.

  • bool isScrollHeld;
    

    If true, the scroll control is held, like a finger swiping through the screen. This does not apply to mouse wheels.

    If scroll is "held," the scrolling motion should detach from pointer position. Whatever scrollable was selected at the time scroll was pressed should continue to be selected while held even if the pointer moves away from it. This makes it possible to comfortably scroll with a touchscreen without having to mind node boundaries, or to implement features such as autoscroll.

  • static @safe Optional!HoverPointer fetch(IO io, int number);
    

    If the given system is a Hover I/O system, fetch a hover pointer.

    Given data must be valid; the I/O must be a HoverIO instance and the number must be a valid pointer number.

    Parameters

    IO io	I/O system to use.
    int number	Valid pointer number assigned by the I/O system.

    Return value

    Hover pointer under given number.

  • @safe bool opEquals(const HoverPointer other) const;
    

    Compare two pointers. All publicly exposed fields (device, number, position, isDisabled) must be equal. To check if the two pointers have the same origin (device and number), use isSame.

    Parameters

    HoverPointer other

    Pointer to compare against.

    Return value

    True if the pointer is the same as the other pointer and has the same state.

  • @safe bool isSame(const HoverPointer other) const;
    

    Test if the two pointers have the same origin — same device and pointer number.

    Parameters

    HoverPointer other

    Pointer to compare against.

    Return value

    True if the pointers have the same device and pointer number.

  • nothrow @safe int id() const;
    

    Return value

    The ID/index assigned by HoverIO when this pointer was loaded.

  • nothrow @safe inout(HoverIO) system() inout;
    

    Return value

    The I/O system owning the pointer.

  • nothrow @safe void load(HoverIO hoverIO, int id);
    

    Load the pointer into the system.

  • @safe void update(const HoverPointer other);
    

    Update a pointer in place using data of another pointer.

    Parameters

    HoverPointer other

    Pointer to copy data from.

  • @safe void emitEvent(InputEvent event);
    

    Emit an event through the pointer.

    The device should call this every frame an input event associated with the pointer occurs. This will be when a mouse button is pressed, every frame a finger touches the screen, or when a gesture recognized by the device or system is performed.

    Parameters

    InputEvent event

    Event to emit. The event is usually considered "active" during the frame the action is "released". For example, user stops holding a mouse button, or a finger stops touching the screen.

    See also

    HoverIO.emitEvent

• interface Hoverable: fluid.io.action.Actionable;
  

  Nodes implementing this interface can be selected by a HoverIO system.

  • abstract @safe bool hoverImpl(HoverPointer pointer);
    

    Handle input. Called each frame when focused.

    Do not call this method if the blocksInput is true.

    Parameters

    HoverPointer pointer

    Pointer to handle this input.

    Return value

    True if hover was handled, false if it was ignored.

  • abstract @safe bool isHovered() const;
    

    Return value

    True if this node is hovered. This will most of the time be equivalent to hoverIO.isHovered(this), but a node wrapping another hoverable may choose to instead redirect this to the other node.

• interface HoverScrollable;
  

  Nodes implementing this interface can react to scroll motion if selected by a HoverIO system.

  Temporarily called HoverScrollable, this node will be renamed to Scrollable in a future release. https://git.samerion.com/Samerion/Fluid/issues/278

  • abstract @safe bool canScroll(const HoverPointer pointer) const;
    

    Determines whether this node can accept scroll input and if the input can have visible effect. This is usually determined by the node's position; for example a container node already scrolled to the bottom cannot accept further vertical movement down.

    This property is used to determine which node should be used to accept scroll. If there's a scrollable container nested in another scrollable node, it will be chosen for scrolling only if the scroll motion can still be performed. On the other hand, if the intent is specifically to block scroll motion (like in a modal window), this method should always return true.

    Note that a node "can scroll" even if it can only accept part of the motion. If the scroll would have the node scroll beyond its maximum value, but the node is not already at its maximum, it should accept the input and clamp the value.

    Parameters

    HoverPointer pointer

    HoverPointer used to perform the action. Its most important property is the scroll field, but some nodes may also filter based on the pointer's state.

    Return value

    True if the node can accept the scroll value in part or in whole, false if the motion would have no effect.

  • abstract @safe bool scrollImpl(HoverPointer pointer);
    

    Perform a scroll motion, moving the node's contents by the specified distance.

    Parameters

    HoverPointer pointer

    Pointer to use to perform the scroll.

    Return value

    True if the motion was handled, or false if not.

  • abstract @safe Rectangle shallowScrollTo(const Node child, Rectangle parentBox, Rectangle childBox);
    

    Scroll towards a specified child node, trying to get it into view.

    Parameters

    Node child	Target node, a child of this node. Ideally, this node should appear on screen as a consequence of this action.
    Rectangle parentBox	Padding box of this node, the node performing the scroll.
    Rectangle childBox	Known padding box of the target child node.

    Return value

    A new padding box for the child node after applying scroll.