Package limn.accessibility

Class AccessibleEvent

java.lang.Object
limn.accessibility.AccessibleEvent
public final class AccessibleEvent extends Object
One thing an assistive technology has to be told: a property that moved, a node that appeared or went away, a window that opened, or something the application said out loud.

An event carries its own values. It is handed to a bridge on the user-interface thread immediately after the tree it describes, and raised later, from a bounded queue on a thread of the bridge's own: raising inline would spend the frame budget in cross-process calls, which is exactly the stall that makes a window unreadable. By the time it is raised, the tree it came from may be two publishes old, so a bridge that raised the event and then read "the current value" would report the newest value under an older event. The values are therefore here.

The one thing an event may never carry is a widget, for the reason no node carries one.

  • Method Details

    • of

      public static AccessibleEvent of(AccessibleEvent.Type type, long nodeId)
      An event that names a node and carries nothing else: a focus move, a structure change, a destruction, a window opening.
      Parameters:
      type - what happened
      nodeId - the node it happened to, or 0 for a window-level event
      Returns:
      the event
      Throws:
      NullPointerException - if type is null

    • property

      public static AccessibleEvent property(AccessibleEvent.Type type, long nodeId, @Nullable Object oldValue, @Nullable Object newValue)
      A property that moved, carrying what it was and what it is.
      Parameters:
      type - which property; a name, a description, a value, a selection or a box
      nodeId - the node it moved on
      oldValue - what it was, or null when there was nothing
      newValue - what it is now, or null
      Returns:
      the event
      Throws:
      NullPointerException - if type is null

    • state

      public static AccessibleEvent state(long nodeId, Accessible.State state, boolean now)
      One state bit that flipped.
      Parameters:
      nodeId - the node it flipped on
      state - which bit
      now - what it is now
      Returns:
      the event
      Throws:
      NullPointerException - if state is null

    • text

      public static AccessibleEvent text(long nodeId, int offset, int removed, int inserted, String oldText, String newText)
      A text edit, with the range it replaced.

      The offsets are computed by comparing the two published strings rather than reported by the editing model, so two edits landing in one frame yield one contiguous replaced range covering both — which every platform can carry and none can distinguish from the truth.

      Parameters:
      nodeId - the node whose text changed
      offset - where the replaced range begins, in UTF-16 code units
      removed - how many units it removed
      inserted - how many it inserted
      oldText - the text as it was
      newText - the text as it is
      Returns:
      the event

    • selection

      public static AccessibleEvent selection(long containerId, boolean multiSelectable, long[] added, long[] removed)
      A container's selection moved.
      Parameters:
      containerId - the container the members belong to
      multiSelectable - whether it selects more than one member at once
      added - the members that entered its selection in this publish, in reading order; a member new in this publish included
      removed - the members that left it, in the previous publish's reading order; a member that left the tree included
      Returns:
      the event
      Throws:
      NullPointerException - if either array is null

    • structure

      public static AccessibleEvent structure(long parentId, List<AccessibleEvent.Child> added, List<AccessibleEvent.Child> removed, List<AccessibleEvent.Child> reordered)
      A parent's children moved.
      Parameters:
      parentId - the surviving parent whose children changed
      added - the children now under it that were not, in reading order
      removed - the children that were under it and are not, in their former order
      reordered - the surviving children whose place among their surviving siblings moved, in reading order
      Returns:
      the event
      Throws:
      NullPointerException - if any list is null

    • announcement

      public static AccessibleEvent announcement(String text, Accessible.Politeness politeness)
      Something the application said out loud.
      Parameters:
      text - what to say, already resolved in the scene's language
      politeness - whether it waits for the assistive technology to finish, or interrupts it
      Returns:
      the event
      Throws:
      NullPointerException - if either argument is null

    • type

      public AccessibleEvent.Type type()
      Returns:
      what happened; never null

    • nodeId

      public long nodeId()
      Returns:
      the node this happened to, or 0 for an event whose subject is the window itself or the application speaking

    • state

      public @Nullable Accessible.State state()
      Returns:
      which state flipped, for a AccessibleEvent.Type.STATE_CHANGED; null for every other kind

    • politeness

      public @Nullable Accessible.Politeness politeness()
      Returns:
      whether an announcement interrupts, for a AccessibleEvent.Type.ANNOUNCEMENT; null for every other kind

    • oldValue

      public @Nullable Object oldValue()
      Returns:
      what the property was before, or null when the event carries no before. A Boolean for a state, a String for a name, a description or a text, a Double for a value, a Rect for a box.

    • newValue

      public @Nullable Object newValue()
      Returns:
      what the property is now, in the same types oldValue() lists

    • offset

      public int offset()
      Returns:
      where a text change begins, in UTF-16 code units; 0 for every other kind

    • removed

      public int removed()
      Returns:
      how many code units a text change removed

    • inserted

      public int inserted()
      Returns:
      how many it inserted

    • addedMembers

      public List<Long> addedMembers()
      Returns:
      for a AccessibleEvent.Type.SELECTION_CHANGED, the members that entered the container's selection in this publish, in reading order; empty for every other kind. Never modifiable.

    • removedMembers

      public List<Long> removedMembers()
      Returns:
      for a AccessibleEvent.Type.SELECTION_CHANGED, the members that left the container's selection in this publish, a member that left the tree included; empty for every other kind. Never modifiable.

    • multiSelectable

      public boolean multiSelectable()
      Returns:
      for a AccessibleEvent.Type.SELECTION_CHANGED, whether the container selects more than one member at once, which is what decides between a platform's single-selection and add-to/remove-from-selection events; false for every other kind

    • addedChildren

      public List<AccessibleEvent.Child> addedChildren()
      Returns:
      for a AccessibleEvent.Type.STRUCTURE_CHANGED, the children now under the node that were not under it in the previous publish — new in the tree, or moved here from the parent each names — in reading order; empty for every other kind. Never modifiable.

    • removedChildren

      public List<AccessibleEvent.Child> removedChildren()
      Returns:
      for a AccessibleEvent.Type.STRUCTURE_CHANGED, the children that were under the node in the previous publish and are not now — gone from the tree, or moved to the parent each names — in their former order; empty for every other kind. Never modifiable.

    • reorderedChildren

      public List<AccessibleEvent.Child> reorderedChildren()
      Returns:
      for a AccessibleEvent.Type.STRUCTURE_CHANGED, the surviving children whose place among their surviving siblings moved, in reading order, each with its index now; empty for every other kind, and for a publish that only added or removed. Never modifiable.

    • toString

      public String toString()
      Overrides:
      toString in class Object