This Wiki page is edited by participants of the HTML Accessibility Task Force. It does not necessarily represent consensus and it may have incorrect information or information that is not supported by other Task Force participants, WAI, or W3C. It may also have some very useful information.
Hit Regions
1.1.15 Hit regions
A hit region list is a list of <a data-anolis-xref="hit region" href="#hit-region">hit regions</a> for a bitmap.
Each hit region consists of the following information:
-
A set of pixels on the bitmap for which this region is responsible.
-
A bounding circumference on the bitmap that surrounds the <a href="#hit-region%27s-set-of-pixels">hit region's set of pixels</a> as they stood when it was created.
-
Optionally, a non-empty string representing an ID for distinguishing the region from others.
-
Optionally, a reference to another region that acts as the parent for this one.
-
A count of regions that have this one as their <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a>, known as the hit region's child count.
-
A cursor specification, in the form of either a CSS cursor value, or the string "
inherit
" meaning that the cursor of the <a href="#hit-region%27s-parent">hit region's parent</a>, if any, or of thecanvas
element, if not, is to be used instead. -
Optionally, either a <a data-anolis-xref="hit region's control" href="#hit-region%27s-control">control</a>, or an <a data-anolis-xref="hit region's unbacked region description" href="#hit-region%27s-unbacked-region-description">unbacked region description</a>.
A control is just a reference to an
Element
node, to which, in certain conditions, the user agent will route events, and from which the user agent will determine the state of the hit region for the purposes of accessibility tools. (The control is ignored when it is not a descendant of thecanvas
element.)An unbacked region description consists of the following:
-
Optionally, a label.
-
An ARIA role, which, if the <a data-anolis-xref="hit region's unbacked region description" href="#hit-region%27s-unbacked-region-description">unbacked region description</a> also has a label, could be the empty string.
-
- context .
<a href="#dom-context-2d-addhitregion">addHitRegion</a>
(options) -
Adds a hit region to the bitmap. The argument is an object with the following members:
path
(default null)- A
<a href="#path">Path</a>
object that describes the pixels that form part of the region. If this member is not provided or is set to null, the <a href="#current-default-path">current default path</a> is used instead. id
(default empty string)- The ID to use for this region. This is used in
MouseEvent
events on thecanvas
(<a href="#dom-mouseevent-region">event.region</a>
) and as a way to reference this region in later calls to<a href="#dom-context-2d-addhitregion">addHitRegion()</a>
. parentID
(default null)- The ID of the parent region, for purposes of navigation by accessibility tools and for cursor fallback.
cursor
(default "inherit
")- The cursor to use when the mouse is over this region. The value "
inherit
" means to use the cursor for the parent region (as specified by theparentID
member), if any, or to use thecanvas
element's cursor if the region has no parent. control
(default null)- An element (that is a descendant of the
canvas
) to which events are to be routed, and which accessibility tools are to use as a surrogate for describing and interacting with this region. label
(default null)- A text label for accessibility tools to use as a description of this region, if there is no control.
role
(default null)- An ARIA role for accessibility tools to use to determine how to represent this region, if there is no control.
Hit regions can be used for a variety of purposes:
- With an ID, they can make hit detection easier by having the user agent check which region the mouse is over and include the ID in the mouse events.
- With a control, they can make routing events to DOM elements
automatic, allowing e.g. clicks on a
canvas
to automatically submit a form via abutton
element. - With a label, they can make it easier for users to explore a
canvas
without seeing it, e.g. by touch on a mobile device. - With a cursor, they can make it easier for different regions of
the
canvas
to have different cursors, with the user agent automatically switching between them.
- context .
<a href="#dom-context-2d-removehitregion">removeHitRegion</a>
(id) -
Removes a hit region (and all its descendants) from the canvas bitmap. The argument is the ID of a region added using
<a href="#dom-context-2d-addhitregion">addHitRegion()</a>
.The pixels that were covered by this region and its descendants are effectively cleared by this operation, leaving the regions non-interactive. In particular, regions that occupied the same pixels before the removed regions were added, overlapping them, do not resume their previous role.
A <a href="#hit-region">hit region</a> A is an ancestor region of a <a href="#hit-region">hit region</a> B if B has a <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a> and its <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a> is either A or another <a href="#hit-region">hit region</a> for which A is an <a href="#ancestor-region">ancestor region</a>.
The region identified by the ID ID in a bitmap bitmap is the value returned by the following algorithm (which can return a <a href="#hit-region">hit region</a> or nothing):
-
If ID is null, return nothing and abort these steps.
-
Let list be the <a href="#hit-region-list">hit region list</a> associated with bitmap.
-
If there is a <a href="#hit-region">hit region</a> in list whose <a data-anolis-xref="hit region's ID" href="#hit-region%27s-id">ID</a> is a case-sensitive match for ID, then return that <a href="#hit-region">hit region</a> and abort these steps.
-
Otherwise, return nothing.
The region representing the control control for a bitmap bitmap is the value returned by the following algorithm (which can return a <a href="#hit-region">hit region</a> or nothing):
-
Let list be the <a href="#hit-region-list">hit region list</a> associated with bitmap.
-
If there is a <a href="#hit-region">hit region</a> in list whose <a data-anolis-xref="hit region's control" href="#hit-region%27s-control">control</a> is control, then return that <a href="#hit-region">hit region</a> and abort these steps.
-
Otherwise, return nothing.
The control represented
by a region region for a canvas
element ancestor is the value returned
by the following algorithm (which can return an element or nothing):
-
If region has no <a data-anolis-xref="hit region's control" href="#hit-region%27s-control">control</a>, return nothing and abort these steps.
-
Let control be region's <a data-anolis-xref="hit region's control" href="#hit-region%27s-control">control</a>.
-
If control is not a descendant of ancestor, then return nothing and abort these steps.
-
Otherwise, return control.
The cursor for a hit region
region of a canvas
element
ancestor is the value returned by the
following algorithm:
-
Loop: If region has a <a data-anolis-xref="hit region's cursor specification" href="#hit-region%27s-cursor-specification">cursor specification</a> other than "
inherit
", then return that <a href="#hit-region%27s-cursor-specification">hit region's cursor specification</a> and abort these steps. -
If region has a <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a>, then let region be that <a href="#hit-region%27s-parent">hit region's parent</a>, and return to the step labeled loop.
-
Otherwise, return the used value of the 'cursor' property for the
canvas
element, if any; if there isn't one, return 'auto'. <a href="#refsCSSUI">[CSSUI]</a>
The region for a pixel pixel on a bitmap bitmap is the value returned by the following algorithm (which can return a <a href="#hit-region">hit region</a> or nothing):
-
Let list be the <a href="#hit-region-list">hit region list</a> associated with bitmap.
-
If there is a <a href="#hit-region">hit region</a> in list whose <a data-anolis-xref="hit region's set of pixels" href="#hit-region%27s-set-of-pixels">set of pixels</a> contains pixel, then return that <a href="#hit-region">hit region</a> and abort these steps.
-
Otherwise, return nothing.
To clear regions that cover the pixels pixels on a bitmap bitmap, the user agent must run the following steps:
-
Let list be the <a href="#hit-region-list">hit region list</a> associated with bitmap.
-
Remove all pixels in pixels from the <a data-anolis-xref="hit region's set of pixels" href="#hit-region%27s-set-of-pixels">set of pixels</a> of each <a href="#hit-region">hit region</a> in list.
-
<a href="#garbage-collect-the-regions">Garbage-collect the regions</a> of bitmap.
To garbage-collect the regions of a bitmap bitmap, the user agent must run the following steps:
-
Let list be the <a href="#hit-region-list">hit region list</a> associated with bitmap.
-
Loop: Let victim be the first <a href="#hit-region">hit region</a> in list to have an empty <a data-anolis-xref="hit region's set of pixels" href="#hit-region%27s-set-of-pixels">set of pixels</a> and a zero <a data-anolis-xref="hit region's child count" href="#hit-region%27s-child-count">child count</a>, if any. If there is no such <a href="#hit-region">hit region</a>, abort these steps.
-
If victim has a <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a>, then decrement that <a href="#hit-region%27s-child-count">hit region's child count</a> by one.
-
Remove victim from list.
-
Jump back to the step labeled loop.
Adding a new region and calling <a
href="#dom-context-2d-clearrect">clearRect()</a>
are the two
ways this clearing algorithm can be invoked. The <a href="#hit-region-list">hit
region list</a> itself is also reset when the rendering context is
reset, e.g. when a <a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a>
object is bound to or unbound from a canvas
, or when the
dimensions of the bitmap are changed.
When the addHitRegion()
method is invoked, the user agent must run the following steps:
-
Let arguments be the dictionary object provided as the method's argument.
-
If the arguments object's
path
member is not null, let source path be thepath
member's value. Otherwise, let it be the<a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a>
object's <a href="#current-default-path">current default path</a>. -
Transform all the coordinates and lines in source path by the current transform matrix, if the arguments object's
path
member is not null. -
Let specified pixels be the pixels contained in source path, using the <a href="#fill-rule">fill rule</a> indicated by the
fillRule
member. -
If the arguments object's
id
member is the empty string, let it be null instead. -
If the arguments object's
id
member is not null, then let previous region for this ID be <a href="#the-region-identified-by-the-id">the region identified by the ID</a> given by theid
member's value in this <a href="#scratch-bitmap">scratch bitmap</a>, if any. If theid
member is null or no such region currently exists, let previous region for this ID be null. -
If the arguments object's
parent
member is the empty string, let it be null instead. -
If the arguments object's
parent
member is not null, then let parent region be <a href="#the-region-identified-by-the-id">the region identified by the ID</a> given by theparent
member's value in the <a href="#scratch-bitmap">scratch bitmap</a>, if any. If theparent
member is null or no such region currently exists, let parent region be null. -
If the arguments object's
label
member is the empty string, let it be null instead. -
If any of the following conditions are met, throw a
NotSupportedError
exception and abort these steps.- The arguments object's
control
andlabel
members are both non-null. - The arguments object's
control
androle
members are both non-null. - The arguments object's
role
member's value is the empty string, and thelabel
member's value is either null or the empty string. - The specified pixels has no pixels.
- The arguments object's
control
member is not null but is neither ana
element that represents a hyperlink, abutton
element, aninput
element whosetype
attribute is in one of the Checkbox or Radio Button states, nor aninput
element that is a button. - The parent region is not null but has a <a data-anolis-xref="hit region's control" href="#hit-region%27s-control">control</a>.
- The previous region for this ID is the same <a href="#hit-region">hit region</a> as the parent region.
- The previous region for this ID is an <a href="#ancestor-region">ancestor region</a> of the parent region.
- The arguments object's
-
If the
parent
member is not null but parent region is null, then throw aNotFoundError
exception and abort these steps. -
If any of the following conditions are met, throw a
SyntaxError
exception and abort these steps.- The arguments object's
cursor
member is not null but is neither an ASCII case-insensitive match for the string "inherit
", nor a valid CSS 'cursor' property value. <a href="#refsCSSUI">[CSSUI]</a> - The arguments object's
role
member is not null but its value is not an ordered set of unique space-separated tokens whose tokens are all case-sensitive matches for names of non-abstract WAI-ARIA roles. <a href="#refsARIA">[ARIA]</a>
- The arguments object's
-
Let region be a newly created <a href="#hit-region">hit region</a>, with its information configured as follows:
- <a href="#hit-region%27s-set-of-pixels">Hit region's set of pixels</a>
-
The specified pixels
- <a href="#hit-region%27s-bounding-circumference">Hit region's bounding circumference</a>
-
A user-agent-defined shape that wraps the pixels contained in source path. (In the simplest case, this can just be the bounding rectangle; this specification allows it to be any shape in order to allow other interfaces.)
- <a href="#hit-region%27s-id">Hit region's ID</a>
-
If the arguments object's
id
member is not null: the value of theid
member. Otherwise, region has no <a data-anolis-xref="hit region's id" href="#hit-region%27s-id">id</a>. - <a href="#hit-region%27s-parent">Hit region's parent</a>
-
If parent region is not null: parent region. Otherwise, region has no <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a>.
- <a href="#hit-region%27s-child-count">Hit region's child count</a>
-
Initially zero.
- <a href="#hit-region%27s-cursor-specification">Hit region's cursor specification</a>
-
If parent region is not null: parent region. Otherwise, region has no <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a>.
- <a href="#hit-region%27s-control">Hit region's control</a>
-
If the arguments object's
control
member is not null: the value of thecontrol
member. Otherwise, region has no <a data-anolis-xref="hit region's control" href="#hit-region%27s-control">control</a>. - <a href="#hit-region%27s-label">Hit region's label</a>
-
If the arguments object's
label
member is not null: the value of thelabel
member. Otherwise, region has no <a data-anolis-xref="hit region's label" href="#hit-region%27s-label">label</a>. - <a href="#hit-region%27s-aria-role">Hit region's ARIA role</a>
-
If the arguments object's
role
member is not null: the value of therole
member (which might be the empty string). Otherwise, if the arguments object'slabel
member is not null: the empty string. Otherwise, region has no <a data-anolis-xref="hit region's ARIA role" href="#hit-region%27s-aria-role">ARIA role</a>.
-
If the arguments object's
cursor
member is not null, then act as if a CSS rule for thecanvas
element setting its 'cursor' property had been seen, whose value was the <a href="#hit-region%27s-cursor-specification">hit region's cursor specification</a>.For example, if the user agent prefetches cursor values, this would cause that to happen in response to an appropriately-formed
<a href="#dom-context-2d-addhitregion">addHitRegion()</a>
call. -
If the arguments object's
control
member is not null, then let previous region for the control be <a href="#the-region-representing-the-control">the region representing the control</a> given by thecontrol
member's value for this <a href="#scratch-bitmap">scratch bitmap</a>, if any. If thecontrol
member is null or no such region currently exists, let previous region for the control be null. -
If there is a previous region with this control, remove it from the <a href="#scratch-bitmap">scratch bitmap</a>'s <a href="#hit-region-list">hit region list</a>; then, if it had a <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a> region, decrement that <a href="#hit-region%27s-child-count">hit region's child count</a> by one.
-
If there is a previous region with this ID, remove it, and all <a data-anolis-xref="hit region" href="#hit-region">hit regions</a> for which it is an <a href="#ancestor-region">ancestor region</a>, from the <a href="#scratch-bitmap">scratch bitmap</a>'s <a href="#hit-region-list">hit region list</a>; then, if it had a <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a> region, decrement that <a href="#hit-region%27s-child-count">hit region's child count</a> by one.
-
If there is a parent region, increment its <a href="#hit-region%27s-child-count">hit region's child count</a> by one.
-
<a href="#clear-regions-that-cover-the-pixels">Clear regions that cover the pixels</a> in region's <a data-anolis-xref="hit region's set of pixels" href="#hit-region%27s-set-of-pixels">set of pixels</a> on this <a href="#scratch-bitmap">scratch bitmap</a>.
-
Add region to the <a href="#scratch-bitmap">scratch bitmap</a>'s element's <a href="#hit-region-list">hit region list</a>.
When the removeHitRegion()
method is invoked, the user agent must run the following steps:
-
Let region be <a href="#the-region-identified-by-the-id">the region identified by the ID</a> given by the method's argument in the rendering context's <a href="#scratch-bitmap">scratch bitmap</a>. If no such region currently exists, abort these steps.
If the method's argument is the empty string, then no region will match.
-
Remove region, and all <a data-anolis-xref="hit region" href="#hit-region">hit regions</a> for which it is an <a href="#ancestor-region">ancestor region</a>, from the rendering context's <a href="#scratch-bitmap">scratch bitmap</a>'s <a href="#hit-region-list">hit region list</a>; then, if it had a <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a> region, decrement that <a href="#hit-region%27s-child-count">hit region's child count</a> by one.
-
<a href="#garbage-collect-the-regions">Garbage-collect the regions</a> of the rendering context's <a href="#scratch-bitmap">scratch bitmap</a>.
The MouseEvent
interface is extended to support hit
regions:
partial interface <span id="MouseEvent-partial">MouseEvent</span> { readonly attribute DOMString? <a data-anolis-xref="dom-MouseEvent-region" href="#dom-mouseevent-region">region</a>; }; partial dictionary <span>MouseEventInit</span> { DOMString? region; };
- event .
<a href="#dom-mouseevent-region">region</a>
-
If the mouse was over a <a href="#hit-region">hit region</a>, then this returns the <a href="#hit-region%27s-id">hit region's ID</a>, if it has one.
Otherwise, returns null.
The region
attribute on MouseEvent
objects must return the value it
was initialized to. When the object is created, this attribute must be
initialized to null. It represents the <a href="#hit-region%27s-id">hit
region's ID</a> if the mouse was over a hit region when the event was
fired.
When a MouseEvent
is to be fired at a canvas
element by the user agent in response to a pointing device action, if
the canvas
element has a <a href="#hit-region-list">hit
region list</a>, the user agent must instead follow these steps. If
these steps say to act as normal, that means that the event must
be fired as it would have had these requirements not been applied.
-
If the pointing device is not indicating a pixel on the
canvas
, act as normal and abort these steps. -
Let pixel be the pixel indicated by the pointing device.
-
Let region be the <a href="#hit-region">hit region</a> that is <a data-anolis-xref="the region for a pixel" href="#the-region-for-a-pixel">the region for the pixel</a> pixel on this
canvas
element's bitmap, if any. -
If there is no region, then act as normal and abort these steps.
-
Let id be the region's <a data-anolis-xref="hit region's ID" href="#hit-region%27s-id">ID</a>, if any.
-
If there is an id, then initialize the event object's
<a href="#dom-mouseevent-region">region</a>
attribute to id. -
Let control be the <a data-anolis-xref="the control represented by a region" href="#the-control-represented-by-a-region">control represented by</a> region for this
canvas
element, if any. -
If there is a control, then target the event object at control instead of the
canvas
element. -
Continue dispatching the event, but with the updated event object and target as given in the above steps.
When a user's pointing device cursor is positioned over a canvas
element, user agents should render the pointing device cursor according
to the cursor specification described by <a data-anolis-xref="the cursor for a hit region"
href="#the-cursor-for-a-hit-region">the cursor for the hit region</a>
that is <a data-anolis-xref="the region for a pixel" href="#the-region-for-a-pixel">the
region for the pixel</a> that the pointing device designates on the canvas
element's bitmap.
User agents are encouraged to make use of the information present in a
canvas
element's <a href="#hit-region-list">hit region
list</a> to improve the accessibility of canvas
elements.
Each <a href="#hit-region">hit region</a> should be handled in a
fashion equivalent to a node in a virtual DOM tree rooted at the canvas
element. The hierarchy of this virtual DOM tree must match the hierarchy
of the <a data-anolis-xref="hit region" href="#hit-region">hit regions</a>,
as described by the <a data-anolis-xref="hit region's parent" href="#hit-region%27s-parent">parent</a>
of each region. Regions without a <a data-anolis-xref="hit
region's parent" href="#hit-region%27s-parent">parent</a> must be treated as
children of the canvas
element for the purpose of this
virtual DOM tree. For each node in such a DOM tree, the <a href="#hit-region%27s-bounding-circumference">hit
region's bounding circumference</a> gives the region of the screen to
use when representing the node (if appropriate).
The semantics of a <a href="#hit-region">hit region</a> for the purposes of this virtual DOM tree are those of the <a data-anolis-xref="the control represented by a region" href="#the-control-represented-by-a-region">the control represented by the region</a>, if it has one, or else of a non-interactive element whose ARIA role, if any, is that given by the <a href="#hit-region%27s-aria-role">hit region's ARIA role</a>, and whose textual representation, if any, is given by the <a href="#hit-region%27s-label">hit region's label</a>.
For the purposes of accessibility tools, when an element C
is a descendant of a canvas
element and there is <a data-anolis-xref="the region representing the control"
href="#the-region-representing-the-control">a region representing the
control</a> C for that canvas
element's bitmap, then the element's position relative to the document
should be presented as if it was that region in the canvas
element's virtual DOM tree.
The semantics of a <a href="#hit-region">hit region</a> for the purposes of this virtual DOM tree are those of the <a data-anolis-xref="the control represented by a region" href="#the-control-represented-by-a-region">the control represented by the region</a>, if it has one, or else of a non-interactive element whose ARIA role, if any, is that given by the <a href="#hit-region%27s-aria-role">hit region's ARIA role</a>, and whose textual representation, if any, is given by the <a href="#hit-region%27s-label">hit region's label</a>.
Thus, for instance, a user agent on a touch-screen device
could provide haptic feedback when the user croses over a <a href="#hit-region%27s-bounding-circumference">hit
region's bounding circumference</a>, and then read the <a href="#hit-region%27s-label">hit
region's label</a> to the user. Similarly, a desktop user agent with a
virtual accessibility focus separate from the keyboard input focus could
allow the user to navigate through the hit regions, using the virtual
DOM tree described above to enable hierarchical navigation. When an
interactive control inside the canvas
element is focused,
if the control has a corresponding region, then that <a href="#hit-region%27s-bounding-circumference">hit
region's bounding circumference</a> could be used to determine what
area of the display to magnify.