com.labymedia.ultralight.input.UltralightKeyEvent Maven / Gradle / Ivy

Go to download
/*
 * Ultralight Java - Java wrapper for the Ultralight web engine
 * Copyright (C) 2020 - 2021 LabyMedia and contributors
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 3 of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

package com.labymedia.ultralight.input;

import com.labymedia.ultralight.UltralightView;
import com.labymedia.ultralight.annotation.NativeType;
import com.labymedia.ultralight.annotation.Unsigned;

import java.lang.annotation.Native;

/**
 * A generic keyboard event.
 *
 * @see UltralightView#fireKeyEvent(UltralightKeyEvent)
 */
@NativeType("ultralight::KeyEvent")
public class UltralightKeyEvent {
    /**
     * The type of this {@link UltralightKeyEvent}.
     */
    @Native
    private UltralightKeyEventType type;

    /**
     * The current state of the keyboard. Modifiers may be OR'd together to
     * represent multiple values.
     *
     * @see UltralightInputModifier
     */
    @NativeType("unsigned")
    @Unsigned
    @Native
    private int modifiers;

    /**
     * The virtual key-code associated with this keyboard event.
     */
    @Native
    private UltralightKey virtualKeyCode;

    /**
     * The actual key-code generated by the platform. The DOM spec primarily
     * uses Windows-equivalent codes (hence virtualKeyCode above) but it helps to
     * also specify the platform-specific key-code as well.
     */
    @Native
    private int nativeKeyCode;

    /**
     * This is a string identifying the key that was pressed. This can be
     * generated from the {@link #virtualKeyCode} via the {@link #getKeyIdentifierFromVirtualKeyCode(UltralightKey)}
     * utility function. You can find the full list of key identifiers at:
     * http://www.w3.org/TR/DOM-Level-3-Events/keyset.html
     */
    @NativeType("ultralight::String")
    @Native
    private String keyIdentifier;

    /**
     * The actual text generated by this keyboard event. This is usually only a
     * single character.
     */
    @NativeType("ultralight::String")
    @Native
    private String text;

    /**
     * The text generated by this keyboard event before all modifiers except
     * shift are applied. This is used internally for working out shortcut keys.
     * This is usually only a single character.
     */
    @NativeType("ultralight::String")
    @Native
    private String unmodifiedText;

    /**
     * Whether or not this is a keypad event.
     */
    @Native
    private boolean isKeypad;

    /**
     * Whether or not this was generated as the result of an auto-repeat
     * (eg, holding down a key).
     */
    @Native
    private boolean isAutoRepeat;

    /**
     * Whether or not the pressed key is a "system key". This is a Windows-only
     * concept and should be "false" for all non-Windows platforms. For more
     * information, see the following link:
     * http://msdn.microsoft.com/en-us/library/ms646286(VS.85).aspx
     */
    @Native
    private boolean isSystemKey;

    /**
     * Sets the type field of this instance.
     *
     * @param type The new value of the field
     * @return this
     * @see #type
     */
    public UltralightKeyEvent type(UltralightKeyEventType type) {
        this.type = type;
        return this;
    }

    /**
     * Sets the modifiers field of this instance.
     *
     * @param modifiers The new value of the field
     * @return this
     * @see #modifiers
     */
    public UltralightKeyEvent modifiers(@NativeType("unsigned") @Unsigned int modifiers) {
        this.modifiers = modifiers;
        return this;
    }

    /**
     * Sets the virtualKeyCode field of this instance.
     *
     * @param virtualKeyCode The new value of the field
     * @return this
     * @see #virtualKeyCode
     */
    public UltralightKeyEvent virtualKeyCode(UltralightKey virtualKeyCode) {
        this.virtualKeyCode = virtualKeyCode;
        return this;
    }

    /**
     * Sets the nativeKeyCode field of this instance.
     *
     * @param nativeKeyCode The new value of the field
     * @return this
     * @see #nativeKeyCode
     */
    public UltralightKeyEvent nativeKeyCode(int nativeKeyCode) {
        this.nativeKeyCode = nativeKeyCode;
        return this;
    }

    /**
     * Sets the keyIdentifier field of this instance.
     *
     * @param keyIdentifier The new value of the field
     * @return this
     * @see #keyIdentifier
     */
    public UltralightKeyEvent keyIdentifier(@NativeType("ultralight::String") String keyIdentifier) {
        this.keyIdentifier = keyIdentifier;
        return this;
    }

    /**
     * Sets the text field of this instance.
     *
     * @param text The new value of the field
     * @return this
     * @see #text
     */
    public UltralightKeyEvent text(@NativeType("ultralight::String") String text) {
        this.text = text;
        return this;
    }

    /**
     * Sets the unmodifiedText field of this instance.
     *
     * @param unmodifiedText The new value of the field
     * @return this
     * @see #unmodifiedText
     */
    public UltralightKeyEvent unmodifiedText(@NativeType("ultralight::String") String unmodifiedText) {
        this.unmodifiedText = unmodifiedText;
        return this;
    }

    /**
     * Sets the isKeypad field of this instance.
     *
     * @param keypad The new value of the field
     * @return this
     * @see #isKeypad
     */
    public UltralightKeyEvent keypad(boolean keypad) {
        isKeypad = keypad;
        return this;
    }

    /**
     * Sets the isAutoRepeat field of this instance.
     *
     * @param autoRepeat The new value of the field
     * @return this
     * @see #isAutoRepeat
     */
    public UltralightKeyEvent autoRepeat(boolean autoRepeat) {
        isAutoRepeat = autoRepeat;
        return this;
    }

    /**
     * Sets the isSystemKey field of this instance.
     *
     * @param systemKey The new value of the field
     * @return this
     * @see #isSystemKey
     */
    public UltralightKeyEvent systemKey(boolean systemKey) {
        isSystemKey = systemKey;
        return this;
    }

    /**
     * Utility function for generating a key identifier string from a virtual
     * key-code.
     *
     * @param virtualKeyCode The virtual key-code to generate the key
     *                       identifier from.
     * @return The key identifier
     */
    public static native @NativeType("ultralight::String")
    String getKeyIdentifierFromVirtualKeyCode(
            UltralightKey virtualKeyCode);
}