New API to read Caps-Lock and Num-Lock state

[Kevin Rushforth]

Let's separate out the questions of  what to do if we can't reliably get 
the state of a key on a particular platform versus what to do if the key 
isn't present (on a system where we could get the state if it were there).

The latter case seems clear: returning false is the right answer, since 
it is an accurate representation of the state. This is somewhat similar 
to reporting the state of the 5th button on a 3-button mouse (it's not a 
perfect analogy, since we're talking about sticky state here, not 
transient state that is part of the event in question, but close enough).

The former case is the more interesting one, since we could report 
inaccurate information, so simply returning false seems wrong. I think 
we have three choices: 1) throw an exception; 2) provide a separate 
query method; or 3) return a three-value enum rather than a boolean 
(e.g., OFF, ON, UNKNOWN). My current thinking is to throw a exception, 
but I'd like to hear other opinions as well.

One other question is whether we should include SCROLL_LOCK along with 
CAPS_LOCK and NUM_LOCK. I included it below, but I'm leaning towards 
removing it, since it is not a common key state these days (and it isn't 
clear what an app would do with the information).

Here is the currently proposed javadoc for comment:

     /**
      * Returns a flag indicating whether the key corresponding to 
{@code keyCode}
      * is in the locked or "on" state.
      * {@code keyCode} must be one of: {@link KeyCode#CAPS},
      * {@link KeyCode#NUM_LOCK}, or {@link KeyCode#SCROLL_LOCK}.
      * If the underlying system is not able to determine the state of the
      * specified {@code keyCode}, an UnsupportedOperationException is 
thrown.
      * If the keyboard attached to the system doesn't have the 
specified key,
      * {@code false} is returned.
      * This method must be called on the JavaFX Application thread.
      *
      * @param keyCode the KeyCode of the lock state to query
      *
      * @throws IllegalArgumentException if {@code keyCode} is not one 
of the
      * valid KeyCode values.
      *
      * @throws UnsupportedOperationException if the underlying system 
is not
      * able to determine the state of the specified  {@code keyCode}
      *
      * @throws IllegalStateException if this method is called on a thread
      * other than the JavaFX Application Thread.
      *
      * @return {@code true} if the key corresponding to {@code keyCode}
      * is in the locked or "on" state; {@code false} otherwise
      *
      * @since 17
      */
     public static boolean isKeyLocked(KeyCode keyCode);


-- Kevin


On 1/15/2021 8:34 PM, Nir Lisker wrote:
> What do the methods that check if a mouse button is pressed, but the 
> button does not exist on the mouse, do?
> Maybe it's a hint for consistency.
>
> On Sat, Jan 16, 2021 at 5:09 AM Dan Howard <sproket at videotron.ca 
> <mailto:sproket at videotron.ca>> wrote:
>
>     Please no additional exceptions. It only makes me think in a platform
>     specific way. Better would be an extra method that can I can check if
>     key exists. But if the key exists or is not pressed it should simply
>     return false. IMO
>
>     On 1/15/2021 12:39 PM, Kevin Rushforth wrote:
>     > For JavaFX 17, I am planning to add a minor enhancement to read the
>     > state of the keyboard lock keys, specifically, Caps-Lock, Num-Lock,
>     > and maybe Scroll-Lock (although I might defer the latter to a
>     future
>     > version since it will be more difficult to test, and doesn't
>     seem as
>     > useful).
>     >
>     > This is currently tracked by JDK-8259680 [1].
>     >
>     > The proposed API would be something like:
>     >
>     >         public static boolean Platform::isKeyLocked(KeyCode
>     keyCode);
>     >
>     > One question is whether we should throw an exception if the key
>     state
>     > cannot be read on a particular system (e.g., Num Lock on macOS),
>     which
>     > is what the similar AWT API does. I don't have a strong opinion on
>     > that poont, although I wouldn't want to throw an exception if the
>     > keyboard doesn't have the key in question, as long the system is
>     able
>     > to read the state accurately.
>     >
>     > Comments are welcome.
>     >
>     > -- Kevin
>     >
>     > [1] https://bugs.openjdk.java.net/browse/JDK-8259680
>     <https://bugs.openjdk.java.net/browse/JDK-8259680>
>     >
>