Move scriptui.environment into own page; add fuller, clearer documentation on keyboardState incl. examples

Author: zlovatt

docs/index.rst

@@ -58,6 +58,7 @@ Welcome to The Javascript Tools Guide
     user-interface-tools/localization-in-scriptui-objects
     user-interface-tools/scriptui-object-reference
     user-interface-tools/scriptui-class
+    user-interface-tools/environment
     user-interface-tools/common-properties
     user-interface-tools/window-class
     user-interface-tools/window-object

docs/user-interface-tools/environment.rst

@@ -0,0 +1,101 @@
+.. _environment-object:
+
+Environment object
+==================
+
+This global object is available through the :ref:`scriptui-environment` property.
+
+It defines attributes of the ScriptUI environment, and only contains one property.
+
+Due to this object including only a single property (that is itself an object), all of the relevant documentation will be contained in this page.
+
+--------------------------------------------------------------------------------
+
+.. _environment-object-properties:
+
+Environment object properties
+-----------------------------
+
+The following element properties apply specifically to Environment elements:
+
+.. _environment-keyboard-state:
+
+Keyboard state object
+---------------------
+
+This JavaScript object reports the active state of the keyboard at any time; that is, the current key that is down and any modifiers that are pressed.
+
+This is independent of the event-handling system, which means that at any time in your script, you can use this object to check whether specific keys (such as keyboard modifiers) are pressed, and trigger alternative actions as a result.
+
+It is available through the :ref:`ScriptUI-environment` object::
+
+  var myKeyState = ScriptUI.environment.keyboardState;
+
+The Keyboard State object contains the following properties:
+
+--------------------------------------------------------------------------------
+
+.. _keyboard-state-keyName:
+
+keyName
+*******
+Type: ``String``
+
+The name of the key currently pressed. This is the JavaScript name, a string such as ``"A"`` or ``"a"``.
+
+.. note::
+
+  - This only works for single keys being pressed; holding multiple will report ``undefined``.
+  - Modifier keys will report ``undefined``; to get those, see :ref:`keyboard-state-metaKeys`
+
+For example, with 'a' pressed::
+
+  var currentPressedKey = ScriptUI.environment.keyboardState.keyName;
+
+  alert(currentPressedKey); // "A"
+
+--------------------------------------------------------------------------------
+
+.. _keyboard-state-metaKeys:
+
+shiftKey, ctrlKey, altKey, metaKey
+**********************************
+Type: ``Boolean``
+
+``true`` if the named modifier key is currently active.
+
+.. note::
+
+  ``metaKey`` captures both the ``META`` and ``COMMAND`` keys.
+
+Examples
+++++++++
+
+For example, checking whether a modifier key is held during script execution::
+
+  var shiftHeld = ScriptUI.environment.keyboardState.shiftKey;
+
+  if (shiftHeld) {
+    alert("User is holding shift!");
+  }
+
+Or to check for keyboard modifier combinations::
+
+  var keyboardState = ScriptUI.environment.keyboardState;
+
+  if (keyboardState.shiftKey && keyboardState.altKey) {
+    alert("Shift and alt held!");
+  }
+
+This can also be used within interface buttons as alternative to :ref:`checking the modifiers via keyboard events <keyboardevent-object-getModifierState>`, which can be more confusing and less user-intuitive, unless you're confident you're handling event states properly.
+
+For example::
+
+  button.onClick = function () {
+    if (ScriptUI.environment.keyboardState.shiftKey) {
+      // Special functionality for 'shift' key here
+      return;
+    }
+
+    // normal button behaviour here
+  }

docs/user-interface-tools/event-handling.rst

@@ -7,7 +7,7 @@ Several helper classes provide low-level event-handling capabilities.
 - Event objects are normally created by ScriptUI and passed to your event handler. However, you can
   simulate a user action by constructing an event object using :ref:`ScriptUI-events-createEvent`,
   and sending it to a target object's `controlobj-dispatchEvent` function.
-- A helper object, :ref:`Keyboard-state-object`, provides global access to the keyboard state during function
+- A helper object, :ref:`environment-keyboard-state`, provides global access to the keyboard state during function
   execution, outside the event-handling framework.
 
 --------------------------------------------------------------------------------
@@ -300,6 +300,10 @@ getModifierState()
 
 Returns true if the given modifier was active when the event occurred, false otherwise.
 
+.. note::
+
+  If you're trying to check whether keyboard modifier keys (alt/ctrl/meta/shift) are held down at any time in your script, not just in an event, see :ref:`environment-keyboard-state`.
+
 --------------------------------------------------------------------------------
 
 .. _keyboardevent-object-initKeyboardEvent:
@@ -528,33 +532,3 @@ Reinitializes the object, allowing you to change the event properties after cons
 set the corresponding properties.
 
 Returns ``undefined``.
-
---------------------------------------------------------------------------------
-
-.. _keyboard-state-object:
-
-Keyboard state object
----------------------
-This JavaScript object reports the active state of the keyboard at any time; that is, the current key that is
-down and any modifiers that are pressed. It is independent of the event-handling system, and is available
-through the :ref:`ScriptUI-environment` object::
-
-  myKeyState = ScriptUI.environment.keyboardState;
-
-The object has the following properties:
-
-keyName
-*******
-Type: ``String``
-
-The name of the key currently pressed. This is the JavaScript name, a
-string such as ``"A"`` or ``"a"``.
-
---------------------------------------------------------------------------------
-
-shiftKey, ctrlKey, altKey, metaKey
-**********************************
-Type: ``Boolean``
-
-True if the named modifier key is currently active.
-

docs/user-interface-tools/scriptui-class.rst

@@ -85,6 +85,8 @@ environment; contains a Keyboard state object that reports the active
 state of the keyboard at any time, independent of the event-handling
 framework.
 
+See: :ref:`environment-object` for more information.
+
 --------------------------------------------------------------------------------
 
 .. _scriptui-events:
@@ -226,19 +228,3 @@ Creates a new image object for use in controls that can display images, loading
 images from the specified resources or image files.
 
 Returns a :ref:`ScriptUIImage-object`.
-
---------------------------------------------------------------------------------
-
-.. _environment-object:
-
-Environment object
-------------------
-This global object is available through the :ref:`ScriptUI.environment <scriptui-environment>` property. It defines attributes of the
-ScriptUI environment. In the current release, it contains one property:
-
-keyboardState
-*************
-``Object``
-
-A :ref:`Keyboard-state-object` that reports the active state of the keyboard at
-any time, independent of the event-handling framework.