diff --git a/11ty/CustomLiquid.ts b/11ty/CustomLiquid.ts index 9f8da18338..2e0bd17f4b 100644 --- a/11ty/CustomLiquid.ts +++ b/11ty/CustomLiquid.ts @@ -130,9 +130,6 @@ export class CustomLiquid extends Liquid { }); if (isTechniques) { - // Remove any effectively-empty techniques/resources sections (from template) - $("section#related:not(:has(a))").remove(); - $("section#resources:not(:has(a, li))").remove(); // Expand related technique links to include full title // (the XSLT process didn't handle this in this particular context) const siblingCode = basename(filepath).replace(/^([A-Z]+).*$/, "$1"); @@ -304,9 +301,22 @@ export class CustomLiquid extends Liquid { const $ = load(html); - if (!indexPattern.test(scope.page.inputPath)) { + if (indexPattern.test(scope.page.inputPath)) { + // Remove empty list items due to obsolete technique link removal + if (scope.isTechniques) $("ul.toc-wcag-docs li:empty").remove(); + } else { + const $title = $("title"); + if (scope.isTechniques) { - $("title").text(`${scope.technique.id}: ${scope.technique.title}${titleSuffix}`); + const isObsolete = + scope.technique.obsoleteSince && scope.technique.obsoleteSince <= scope.version; + if (isObsolete) $("body").addClass("obsolete"); + + $title.text( + (isObsolete ? "[Obsolete] " : "") + + `${scope.technique.id}: ${scope.technique.title}${titleSuffix}` + ); + const aboutBoxSelector = "section#technique .box-i"; // Strip applicability paragraphs with metadata IDs (e.g. H99) @@ -358,17 +368,10 @@ export class CustomLiquid extends Liquid { } $("section#applicability").remove(); - if (scope.technique.technology === "flash") { - $(aboutBoxSelector).append( - "

Note: Adobe has plans to stop updating and distributing the Flash Player at the end of 2020, " + - "and encourages authors interested in creating accessible web content to use HTML.

" - ); - } else if (scope.technique.technology === "silverlight") { - $(aboutBoxSelector).append( - "

Note: Microsoft has stopped updating and distributing Silverlight, " + - "and authors are encouraged to use HTML for accessible web content.

" - ); - } + // Remove any effectively-empty techniques/resources sections, + // due to template boilerplate or obsolete technique removal + $("section#related:not(:has(a))").remove(); + $("section#resources:not(:has(a, li))").remove(); // Update understanding links to always use base URL // (mainly to avoid any case-sensitivity issues) @@ -376,7 +379,6 @@ export class CustomLiquid extends Liquid { el.attribs.href = el.attribs.href.replace(/^.*\//, scope.understandingUrl); }); } else if (scope.isUnderstanding) { - const $title = $("title"); if (scope.guideline) { const type = scope.guideline.type === "SC" ? "Success Criterion" : scope.guideline.type; $title.text( @@ -387,13 +389,20 @@ export class CustomLiquid extends Liquid { $title.text().replace(/WCAG 2( |$)/, `WCAG ${scope.versionDecimal}$1`) + titleSuffix ); } + + // Remove Techniques section from obsolete SCs (e.g. Parsing in 2.2) + if (scope.guideline?.level === "") $("section#techniques").remove(); } // Process defined terms within #render, // where we have access to global data and the about box's HTML const $termLinks = $(termLinkSelector); const extractTermName = ($el: Cheerio) => { - const name = $el.text().toLowerCase().trim().replace(/\s*\n+\s*/, " "); + const name = $el + .text() + .toLowerCase() + .trim() + .replace(/\s*\n+\s*/, " "); const term = termsMap[name]; if (!term) { console.warn(`${scope.page.inputPath}: Term not found: ${name}`); @@ -525,7 +534,7 @@ export class CustomLiquid extends Liquid { // Allow autogenerating missing top-level section IDs in understanding docs, // but don't pick up incorrectly-nested sections in some techniques pages (e.g. H91) - const sectionSelector = scope.isUnderstanding ? "section" : "section[id]"; + const sectionSelector = scope.isUnderstanding ? "section" : "section[id]:not(.obsolete)"; const sectionH2Selector = "h2:first-child"; const $h2Sections = $(`${sectionSelector}:has(${sectionH2Selector})`); if ($h2Sections.length) { diff --git a/11ty/README.md b/11ty/README.md index cc5df18287..f94066e229 100644 --- a/11ty/README.md +++ b/11ty/README.md @@ -38,6 +38,15 @@ Indicates top-level path of W3C CVS checkout, for WAI site updates (via `publish **Default:** `../../../w3ccvs` (same as in Ant/XSLT build process) +### `WCAG_VERBOSE` + +**Usage context:** Local development, debugging + +Prints more log messages that are typically noisy and uninteresting, +but may be useful if you're not seeing what you expect in the output files. + +**Default:** Unset (set to any non-empty value to enable) + ### `WCAG_VERSION` **Usage context:** currently this should not be changed, pending future improvements to `21` support diff --git a/11ty/guidelines.ts b/11ty/guidelines.ts index def71cc02f..08c4ec1c3e 100644 --- a/11ty/guidelines.ts +++ b/11ty/guidelines.ts @@ -81,6 +81,7 @@ export interface Principle extends DocNode { num: `${number}`; // typed as string for consistency with guidelines/SC version: "WCAG20"; guidelines: Guideline[]; + type: "Principle"; } export interface Guideline extends DocNode { @@ -88,6 +89,7 @@ export interface Guideline extends DocNode { num: `${Principle["num"]}.${number}`; version: `WCAG${"20" | "21"}`; successCriteria: SuccessCriterion[]; + type: "Guideline"; } export interface SuccessCriterion extends DocNode { @@ -96,6 +98,7 @@ export interface SuccessCriterion extends DocNode { /** Level may be empty for obsolete criteria */ level: "A" | "AA" | "AAA" | ""; version: `WCAG${WcagVersion}`; + type: "SC"; } export function isSuccessCriterion(criterion: any): criterion is SuccessCriterion { diff --git a/11ty/techniques.ts b/11ty/techniques.ts index afa87ec3d7..94820e7784 100644 --- a/11ty/techniques.ts +++ b/11ty/techniques.ts @@ -1,5 +1,6 @@ import type { Cheerio } from "cheerio"; import { glob } from "glob"; +import matter from "gray-matter"; import capitalize from "lodash-es/capitalize"; import uniqBy from "lodash-es/uniqBy"; @@ -7,7 +8,13 @@ import { readFile } from "fs/promises"; import { basename } from "path"; import { load, loadFromFile } from "./cheerio"; -import { isSuccessCriterion, type FlatGuidelinesMap, type SuccessCriterion } from "./guidelines"; +import { + assertIsWcagVersion, + isSuccessCriterion, + type FlatGuidelinesMap, + type SuccessCriterion, + type WcagVersion, +} from "./guidelines"; import { wcagSort } from "./common"; /** Maps each technology to its title for index.html */ @@ -25,7 +32,7 @@ export const technologyTitles = { silverlight: "Silverlight Techniques", // Deprecated in 2020 text: "Plain-Text Techniques", }; -type Technology = keyof typeof technologyTitles; +export type Technology = keyof typeof technologyTitles; export const technologies = Object.keys(technologyTitles) as Technology[]; function assertIsTechnology( @@ -163,7 +170,14 @@ export async function getTechniqueAssociations(guidelines: FlatGuidelinesMap) { return associations; } -interface Technique { +interface TechniqueFrontMatter { + /** May be specified via front-matter; message to display RE a technique's obsolescence. */ + obsoleteMessage?: string; + /** May be specified via front-matter to indicate a technique is obsolete as of this version. */ + obsoleteSince?: WcagVersion; +} + +export interface Technique extends TechniqueFrontMatter { /** Letter(s)-then-number technique code; corresponds to source HTML filename */ id: string; /** Technology this technique is filed under */ @@ -195,17 +209,37 @@ export async function getTechniquesByTechnology() { {} as Record ); + // Check directory data files (we don't have direct access to 11ty's data cascade here) + const technologyData: Partial> = {}; + for (const technology of technologies) { + try { + const data = JSON.parse( + await readFile(`techniques/${technology}/${technology}.11tydata.json`, "utf8") + ); + if (data) technologyData[technology] = data; + } catch {} + } + for (const path of paths) { const [technology, filename] = path.split("/"); assertIsTechnology(technology); + // Support front-matter within HTML files + const { content, data: frontMatterData } = matter(await readFile(`techniques/${path}`, "utf8")); + const data = { ...technologyData[technology], ...frontMatterData }; + + if (data.obsoleteSince) { + data.obsoleteSince = "" + data.obsoleteSince; + assertIsWcagVersion(data.obsoleteSince); + } // Isolate h1 from each file before feeding into Cheerio to save ~300ms total - const match = (await readFile(`techniques/${path}`, "utf8")).match(/]*>([\s\S]+?)<\/h1>/); - if (!match || !match[1]) throw new Error(`No h1 found in techniques/${path}`); - const $h1 = load(match[1], null, false); + const h1Match = content.match(/]*>([\s\S]+?)<\/h1>/); + if (!h1Match || !h1Match[1]) throw new Error(`No h1 found in techniques/${path}`); + const $h1 = load(h1Match[1], null, false); const title = $h1.text(); techniques[technology].push({ + ...data, // Include front-matter id: basename(filename, ".html"), technology, title, diff --git a/_includes/techniques/about.html b/_includes/techniques/about.html index c1f4392431..a21e7c6107 100644 --- a/_includes/techniques/about.html +++ b/_includes/techniques/about.html @@ -1,3 +1,9 @@ +{% if technique.obsoleteSince <= version %} +
+

Obsolete

+ {% if technique.obsoleteMessage %}
{{ technique.obsoleteMessage }}
{% endif %} +
+{% endif %} {% sectionbox "technique" "About this Technique" %} {% include "techniques/applicability.html" %} {% case technique.technology %} diff --git a/css/base.css b/css/base.css index 5de96e6267..c91ddb1a47 100644 --- a/css/base.css +++ b/css/base.css @@ -155,6 +155,21 @@ dt div { margin-top: 0; } +.obsolete { + border-left: solid 5px var(--faded-red); +} + +.obsolete-message { + background-color: var(--red-subtle); + border-color: var(--faded-red); +} + +.obsolete-message h2 { + color: #fff; + background-color: var(--faded-red); + margin: 0; +} + /* import inline styles from https://www.w3.org/WAI/drafts/WCAG-understanding-redesign-hack.html */ .nav a:link { text-decoration: none; @@ -442,4 +457,4 @@ margin-right:.8em; .minimal-header-logo svg { margin: 1em 0 0 0; } -} \ No newline at end of file +} diff --git a/eleventy.config.ts b/eleventy.config.ts index c7b6818ce8..e146eb728f 100644 --- a/eleventy.config.ts +++ b/eleventy.config.ts @@ -3,13 +3,23 @@ import compact from "lodash-es/compact"; import { copyFile } from "fs/promises"; import { CustomLiquid } from "11ty/CustomLiquid"; -import { actRules, assertIsWcagVersion, getFlatGuidelines, getPrinciples } from "11ty/guidelines"; +import { + actRules, + assertIsWcagVersion, + getFlatGuidelines, + getPrinciples, + type Guideline, + type Principle, + type SuccessCriterion, +} from "11ty/guidelines"; import { getFlatTechniques, getTechniqueAssociations, getTechniquesByTechnology, technologies, technologyTitles, + type Technique, + type Technology, } from "11ty/techniques"; import { generateUnderstandingNavMap, getUnderstandingDocs } from "11ty/understanding"; import type { EleventyContext, EleventyData, EleventyEvent } from "11ty/types"; @@ -18,11 +28,40 @@ import type { EleventyContext, EleventyData, EleventyEvent } from "11ty/types"; const version = process.env.WCAG_VERSION || "22"; assertIsWcagVersion(version); +/** + * Returns boolean indicating whether a technique is obsolete for the given version. + * Tolerates undefined for use with hash lookups. + */ +const isTechniqueObsolete = (technique: Technique | undefined) => + !!technique?.obsoleteSince && technique.obsoleteSince <= version; + +/** + * Returns boolean indicating whether an SC is obsolete for the given version. + * Tolerates other types for use with hash lookups. + */ +const isGuidelineObsolete = (guideline: Principle | Guideline | SuccessCriterion | undefined) => + guideline?.type === "SC" && guideline.level === ""; + const principles = await getPrinciples(); const flatGuidelines = getFlatGuidelines(principles); const techniques = await getTechniquesByTechnology(); const flatTechniques = getFlatTechniques(techniques); + +for (const [technology, list] of Object.entries(techniques)) { + // Prune obsolete techniques from ToC + techniques[technology as Technology] = list.filter( + (technique) => !technique.obsoleteSince || technique.obsoleteSince > version + ); +} + const techniqueAssociations = await getTechniqueAssociations(flatGuidelines); +for (const [id, associations] of Object.entries(techniqueAssociations)) { + // Prune associations from non-obsolete techniques to obsolete SCs + techniqueAssociations[id] = associations.filter( + ({ criterion }) => criterion.level !== "" || isTechniqueObsolete(flatTechniques[id]) + ); +} + const understandingDocs = await getUnderstandingDocs(version); const understandingNav = await generateUnderstandingNavMap(principles, understandingDocs); @@ -164,6 +203,23 @@ export default function (eleventyConfig: any) { ); return; } + + // Omit links to obsolete techniques, when not also linked from one + if ( + isTechniqueObsolete(technique) && + !isTechniqueObsolete(flatTechniques[this.page.fileSlug]) && + !isGuidelineObsolete(flatGuidelines[this.page.fileSlug]) + ) { + if (process.env.WCAG_VERBOSE) { + const since = technique.obsoleteSince!.split("").join("."); + console.warn( + `linkTechniques in ${this.page.inputPath}: ` + + `skipping obsolete technique ${id} (as of ${since})` + ); + } + return; + } + // Support relative technique links from other techniques or from techniques/index.html, // otherwise path-absolute when cross-linked from understanding/* const urlBase = /^\/techniques\/.*\//.test(this.page.filePathStem) @@ -191,7 +247,24 @@ export default function (eleventyConfig: any) { `linkUnderstanding in ${this.page.inputPath}: ` + `skipping unresolvable guideline shortname ${id}` ); + return; } + + // Warn of links to obsolete SCs, when not also linked from one. + // This is intentionally not behind WCAG_VERBOSE, and does not remove, + // as links to Understanding docs are more likely to be in the middle + // of prose requiring manual adjustments + if ( + isGuidelineObsolete(guideline) && + !isGuidelineObsolete(flatGuidelines[this.page.fileSlug]) && + !isTechniqueObsolete(flatTechniques[this.page.fileSlug]) + ) { + console.warn( + `linkUnderstanding in ${this.page.inputPath}: ` + + `reference to obsolete ${guideline.type} ${id}` + ); + } + const urlBase = this.page.filePathStem.startsWith("/understanding/") ? "" : baseUrls.understanding; diff --git a/package-lock.json b/package-lock.json index 65e3275add..54bc11eff8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,6 +12,7 @@ "@11ty/eleventy": "^3.0.0-alpha.14", "cheerio": "^1.0.0-rc.12", "glob": "^10.3.16", + "gray-matter": "^4.0.3", "liquidjs": "^10.14.0", "lodash-es": "^4.17.21", "mkdirp": "^3.0.1", diff --git a/package.json b/package.json index 526fdc94f3..24492fb7e3 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "@11ty/eleventy": "^3.0.0-alpha.14", "cheerio": "^1.0.0-rc.12", "glob": "^10.3.16", + "gray-matter": "^4.0.3", "liquidjs": "^10.14.0", "lodash-es": "^4.17.21", "mkdirp": "^3.0.1", diff --git a/techniques/client-side-script/SCR37.html b/techniques/client-side-script/SCR37.html new file mode 100644 index 0000000000..e99c08cc66 --- /dev/null +++ b/techniques/client-side-script/SCR37.html @@ -0,0 +1,134 @@ +--- +obsoleteMessage: | + See H102: Creating modal dialogs with the HTML dialog element for a standards-based approach instead. +obsoleteSince: 20 +--- +Creating Custom Dialogs in a Device Independent Way

Creating Custom Dialogs in a Device Independent Way

ID: SCR37

Technology: client-side-script

Type: Technique

When to Use

+

HTML and XHTML used with script.

+

Description

+

Site designers often want to create dialogs that do not use the pop-up windows supplied by the browser. This is typically accomplished by enclosing the dialog contents in a div and placing the div above the page content using z-order and absolute positioning in CSS.

+

To be accessible, these dialogs must follow a few simple rules.

+
    +
  1. Trigger the script that launches the dialog from the onclick event of a link or button.
  2. +
  3. Place the dialog div into the Document Object Model (DOM) immediately after the element that triggered it. The triggering element will maintain focus, and inserting the dialog content after that element will make the content inside the dialog next in the screen-reader reading order and next in the tab order. The dialog can still be absolutely positioned to be elsewhere on the page visually. This can be done either by creating the dialog in the HTML and hiding it with CSS, as in the example below, or by inserting it immediately after the triggering element with script.
  4. +
  5. Ensure that the HTML inside the dialog div meets the same accessibility standard as other content.
  6. +
+

It is also nice, but not always necessary, to make the launching link toggle the dialog open and closed, and to close the dialog when the keyboard focus leaves it.

+

Examples

+
+

An options button that opens a dialog

+ +

The HTML for this example includes a triggering Element, in this case a button, and a div that acts as the frame for the dialog.

+

The triggering element is a button and the script is triggered from the onclick event. This sends the appropriate events to the operating system so that assistive technology is aware of the change in the DOM.

+

In this example, the Submit and Reset buttons inside the dialog simply hide the div.

+ +
...
+<button onclick="TogglePopup(event,true)"
+  name="pop0001">Options</button>
+
+<div class="popover" id="pop0001">
+  <h3>Edit Sort Information</h3>
+  <form action="default.htm" onsubmit="this.parentNode.style.display='none'; return false;" onreset="this.parentNode.style.display='none'; return false;">
+    <fieldset>
+      <legend>Sort Order</legend> 
+      <input type="radio" name="order" id="order_alpha" /><label for="order_alpha">Alphabetical</label>
+      <input type="radio" name="order" id="order_default" checked="true" /><label for="order_default">Default</label>
+    </fieldset>
+<div class="buttons">
+  <input type="submit" value="OK" />
+  <input type="reset" value="Cancel" />
+</div>
+</form>
+
+</div>
+...
+
+ +

The div, heading and form elements are styled with CSS to look like a dialog.

+ +
...
+a { color:blue; }
+a.clickPopup img { border:none; width:0; }
+
+div.popover { position:absolute; display:none; border:1px outset; background-color:beige; font-size:80%; background-color:#eeeeee; color:black; }
+div.popover h3 { margin:0; padding:0.1em 0.5em; background-color:navy; color:white; }
+#pop0001 { width:20em; }
+#pop0001 form { margin:0; padding:0.5em; }
+#pop0001 fieldset { margin-bottom:0.3em; padding-bottom:0.5em; }
+#pop0001 input, #pop0001 label { vertical-align:middle; }
+#pop0001 div.buttons { text-align:right; }
+#pop0001 div.buttons input { width:6em; }
+...
+
+ +

The script toggles the display of the popup div, showing it and hiding it.

+ +
...
+function TogglePopup(evt,show) {
+  HarmonizeEvent(evt);
+  var src = evt.target;
+  if ("click" == evt.type) {
+    evt.returnValue = false;
+  }
+  var popID = src.getAttribute("name");
+  if (popID) {
+    var popup = document.getElementById(popID);
+    if (popup) {
+      if (true == show) {
+        popup.style.display = "block";
+      }
+      else if (false == show) {
+        popup.style.display = "none";
+      }
+      else {
+        popup.style.display = "block" == popup.style.display ? "none" : "block";
+      }
+      if ("block" == popup.style.display) {
+        //window.alert(document.documentElement.scrollHeight);
+        popup.style.top = ((document.documentElement.offsetHeight - popup.offsetHeight) / 2 ) + 'px';
+        popup.style.left = ((document.documentElement.offsetWidth - popup.offsetWidth) / 2) + 'px';
+      }
+    }
+  }
+}
+
+function SubmitForm(elem) {
+  elem.parentNode.style.display='none'; 
+  return false;
+}
+
+function ResetForm(elem) {
+  elem.parentNode.style.display='none'; 
+  return false;
+}
+...
+
+ +
+

Tests

+

Procedure

+
    +
  1. Find all areas of the page that trigger dialogs that are not pop-up windows.
  2. +
  3. Check that the dialogs can be opened by tabbing to the area and hitting enter.
  4. +
  5. Check that, once opened, the dialog is next in the tab order.
  6. +
  7. Check that the dialogs are triggered from the click event of a button or a link.
  8. +
  9. Using a tool that allows you to inspect the DOM generated by script, check that the dialog is next in the DOM.
  10. +
+
+

Expected Results

+
    +
  • Checks #2, #3, #4 and #5 are true.
  • +
+
+

Resources

+ + + +
diff --git a/techniques/failures/F70.html b/techniques/failures/F70.html index 9543d09ace..417c383ba2 100644 --- a/techniques/failures/F70.html +++ b/techniques/failures/F70.html @@ -1,3 +1,8 @@ +--- +obsoleteMessage: | + This failure relates to 4.1.1: Parsing, which was removed as of WCAG 2.2. +obsoleteSince: 22 +--- Failure of Success Criterion 4.1.1 due to incorrect use of start and end tags or attribute markup

Failure of Success Criterion 4.1.1 due to incorrect use of start and end tags or attribute markup

ID: F70

Technology: failures

Type: Failure

When to Use

Markup languages: HTML, XHTML, and other SGML or XML-based technologies.

Description

@@ -68,4 +73,4 @@

Missing end tags

- \ No newline at end of file + diff --git a/techniques/failures/F77.html b/techniques/failures/F77.html index d289c236b9..39bfdab7fa 100644 --- a/techniques/failures/F77.html +++ b/techniques/failures/F77.html @@ -1,3 +1,8 @@ +--- +obsoleteMessage: | + This failure relates to 4.1.1: Parsing, which was removed as of WCAG 2.2. +obsoleteSince: 22 +--- Failure of Success Criterion 4.1.1 due to duplicate values of type ID

Failure of Success Criterion 4.1.1 due to duplicate values of type ID

ID: F77

Technology: failures

Type: Failure

When to Use

HTML, and any XML-based markup languages including XHTML and SVG

Description

@@ -31,6 +36,7 @@

Resources

    @@ -43,4 +49,4 @@
- \ No newline at end of file + diff --git a/techniques/failures/F87.html b/techniques/failures/F87.html new file mode 100644 index 0000000000..fd303d1d24 --- /dev/null +++ b/techniques/failures/F87.html @@ -0,0 +1,67 @@ +--- +obsoleteMessage: CSS-generated content does not always constitute a failure, as support for it has improved in user agents and screen readers. It may still present other usability issues, such as unselectable text. +obsoleteSince: 20 +--- +Failure of Success Criterion 1.3.1 due to inserting non-decorative content by using ::before and ::after pseudo-elements and the 'content' property in CSS

Failure of Success Criterion 1.3.1 due to inserting non-decorative content by using ::before and ::after pseudo-elements and the 'content' property in CSS

ID: F87

Technology: failures

Type: Failure

When to Use

+

All technologies that support CSS.

+

Description

+

The CSS ::before and ::after pseudo-elements specify the location of content before and after an element's document tree content. The content property, in conjunction with these pseudo-elements, specifies what is inserted. For users who need to customize style information in order to view content according to their needs, they may not be able to access the information that is inserted using CSS. Therefore, it is a failure to use these properties to insert non-decorative content.

+

A common way to test this critieria is to disable CSS styles to view whether content added using pseudo-elements remains visible.

+ +

Examples

+
+ +

In the following example, ::before and ::after are used to indicate speaker changes and to insert quotation marks in a screenplay.

+

The CSS contains:

+ +
p.jim::before {	content: "Jim: " }
+p.mary::before { content: "Mary: " }
+q::before { content: open-quote }
+q::after  { content: close-quote }
+ +

It is used in this excerpt:

+ +
<p class="jim">
+  <q>Do you think he's going to make it?</q>
+</p>
+<p class="mary">
+  <q>It's not looking good.</q>
+</p>
+
+
+ +

In this example, ::before is used to differentiate facts from opinions.

+

The CSS contains:

+ +
p.fact::before { content: "Fact: "; font-weight: bold; }
+p.opinion::before { content: "Opinion: "; font-weight: bold; }
+ +

It is used in this excerpt:

+ +
<p class="fact">The defendant was at the scene of the crime when it occurred.</p>
+<p class="opinion">The defendant committed the crime.</p>
+
+

Tests

+

Procedure

+

For each instance of content inserted through use of the ::before and ::after pseudo-elements and the content property:

+
    +
  1. Check that non-decorative information presented by the generated content is available when styles are overridden.
  2. +
+
+

Expected Results

+
    +
  • If check #1 is false, then this failure condition applies and the content fails this Success Criterion.
  • +
+
+

Resources

+ + + +
+ diff --git a/techniques/flash/FLASH1.html b/techniques/flash/FLASH1.html new file mode 100644 index 0000000000..daa2aa48c1 --- /dev/null +++ b/techniques/flash/FLASH1.html @@ -0,0 +1,63 @@ +Setting the name property for a non-text object

Setting the name property for a non-text object

ID: FLASH1

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to show how non-text objects in Flash can be marked so that they can be read by assistive technology.

+

The Flash Player supports text alternatives to non-text objects using the name property in the accessibility object, which can be defined in ActionScript or within Flash authoring tools.

+

When an object contains words that are important to understanding the content, the name property should include those words. This will allow the name property to play the same function on the page as the object. Note that it does not necessarily describe the visual characteristics of the object itself but must convey the same meaning as the object.

+

Examples

+
+

Applying a textual alternative for a symbol (graphic, button or movieclip)

+ +

The Flash Professional authoring tool's Accessibility panel lets authors provide accessibility information to assistive technology and set accessibility options for individual Flash objects or entire Flash applications.

+
    +
  1. For a text alternative to be applied to a non-text object, it must be saved as a symbol in the movie's library. Note: Flash does not support text alternatives for graphic symbols. Instead, the graphic must be converted to or stored in a movie clip or button symbol.
  2. +
  3. Bring up the Accessibility panel by selecting "Window > Other Panels > Accessibility" in the application menu, or through the shortcut ALT + F11. Ensure that the 'Make object accessible' checkbox is checked.
  4. +
  5. Select the non-text instance on the movie stage, the fields in the Accessibility panel become editable.
  6. +
  7. Enter a meaningful text alternative in the 'name' field, properly describing the purpose of the symbol.
  8. +
+
+ + +
The Accessibility panel in the Flash authoring environment.
+ +
+ +
+
+

Applying textual alternatives programmatically in ActionScript 2.0

+ +

To manage an object's text equivalent programmatically using ActionScript 2, the _accProps object must be used. This references an object containing accessibility related properties set for the object. The code example below shows a simple example of how the _accProps object is used to set an objects name in ActionScript.

+ +
// 'print_btn' is an instance placed on the movie's main timeline
+_root.print_btn._accProps = new Object();
+_root.print_btn._accProps.name = "Print";
+
+
+

Applying textual alternatives programmatically in ActionScript 3.0

+ +

To manage an object's text equivalents programmatically using ActionScript 3, the AccessibilityProperties object and name property must be used. The code example below shows a simple example of how the name property is used to set an objects name in ActionScript.

+ +
// 'print_btn' is an instance placed on the movie's main timeline
+print_btn.accessibilityProperties = new AccessibilityProperties();
+print_btn.accessibilityProperties.name = "Print";
+
+

Tests

+

Procedure

+
    +
  1. Publish the SWF file
  2. +
  3. Open the SWF file in Internet Explorer 6 or higher (using Flash Player 6 or higher), or Firefox 3 or higher (using Flash Player 9 or higher)
  4. +
  5. Use a tool which is capable of showing an object's name text alternative, such as ACTF aDesigner 1.0 to open the Flash movie.
  6. +
  7. In the GUI summary panel, loop over each object which is contained by the Flash movie and ensure the object that was provided a name has a proper name attribute appearing in the tool's display.
  8. +
  9. Authors may also test with a screen reader, by reading the Flash content and listening to hear that the equivalent text is read when tabbing to the non-text object (if it is tabbable) or hearing the alternative text read when reading the content line-by-line.
  10. +
  11. All non-text objects have text equivalents that can serve the same purpose and convey the same information as the non-text object
  12. +
+
+

Expected Results

+

Check #6 is true.

+
+
diff --git a/techniques/flash/FLASH10.html b/techniques/flash/FLASH10.html new file mode 100644 index 0000000000..c9e63b22df --- /dev/null +++ b/techniques/flash/FLASH10.html @@ -0,0 +1,40 @@ +Indicating required form controls in Flash

Indicating required form controls in Flash

ID: FLASH10

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to provide a clear indication that a specific form control in a Web application or form is required for successful data submission. The word "required" is added to the form control's accessible name, and a visual indicator is placed next to the label.

+

Examples

+
+

Adding the word "required" to the control's accessible name

+ +

This example shows how to use the Accessibility panel to indicate a field as being 'required' to users:

+
    +
  1. Visually, place asterisk character or some other indication adjacent to the form control's label.
  2. +
  3. Use the Accessibility panel to combine the word "required" with the control's label in the "Name" field.
  4. +
+

This approach is illustrated in the screenshot below:

+
+ + +
Using the Accessibility panel to indicate a form control as being required
+ +
+

This is demonstrated in the working example of Adding the word "required" to the control's accessible name. The source of Adding the word "required" to the control's accessible name is available.

+ +
+

Tests

+

Procedure

+

For each required form control within a Flash movie, confirm that:

+
    +
  • The required state is indicated visually
  • +
  • The required state is indicated textually using the 'Name' field in the Accessibility panel
  • +
+
+

Expected Results

+
    +
  • Each of the above is true
  • +
+
+
diff --git a/techniques/flash/FLASH11.html b/techniques/flash/FLASH11.html new file mode 100644 index 0000000000..e06bec85f9 --- /dev/null +++ b/techniques/flash/FLASH11.html @@ -0,0 +1,90 @@ +Providing a longer text description of an object

Providing a longer text description of an object

ID: FLASH11

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to a provide longer, more detailed textual information for an image than would be suitable for the image's accessible name. An accessible button is provided adjacent to the image that displays a new panel containing the image's long description text.

+

Examples

+
+

Making a hidden description visible on request

+ +

In this example, an image containing statistical data is shown. The image is provided a short textual alternative ("Graph of percentage of total U.S. noninsitutionalized population age 16-64 declaring one or more disabilities"). Below the image, the user can click a button that will overlay a long textual description of the statistical information itself. When the button is clicked, the following actions are taken:

+
    +
  • The MovieClip containing the long text description is made visible, and its AccessibilityProperties.silent property is set to false to make it visible to assistive technology. Its contents are placed in the tab order.
  • +
  • The original image and button are temporarily hidden from assistive technology and the tab order.
  • +
+

The image and descriptive text were taken from a previously published HTML example for long image descriptions on WebAIM.org +

+

The results for this technique are shown in the working version of Making a hidden description visible on request. The source of Making a hidden description visible on request is available.

+ +
import flash.accessibility. *;
+import fl.accessibility.ButtonAccImpl;
+import flash.system.Capabilities;
+
+ButtonAccImpl.enableAccessibility();
+
+//set accessibility properties
+graph_mc.accessibilityProperties = new AccessibilityProperties();
+graph_mc.accessibilityProperties.name = "Graph of percentage of total U.S. \ 
+  noninsitutionalized population age 16-64 declaring one or more disabilities";
+longDescBtn.accessibilityProperties = new AccessibilityProperties();
+longDesc_mc.accessibilityProperties = new AccessibilityProperties();
+longDesc_mc.accessibilityProperties.forceSimple = false;
+hideLongDesc();
+
+//set click handlers for button
+longDescBtn.addEventListener("click", function () {
+  showLongDesc()
+});
+longDesc_mc.longDescCloseBtn.addEventListener("click", function () {
+  hideLongDesc()
+});
+
+function showLongDesc() {
+  // hide the original content from screen readers
+  graph_mc.accessibilityProperties.silent = true;
+  graph_mc.tabEnabled = false;
+  graph_mc.alpha = 0.2;
+  longDescBtn.enabled = false;
+  longDescBtn.accessibilityProperties.silent = true;
+  longDesc_mc.accessibilityProperties.silent = false;
+  // make the long description panel visible, both visually and to screen readers
+  longDesc_mc.visible = true;
+  longDesc_mc.tabEnabled = true;
+  longDesc_mc.longDescTitle.stage.focus = longDesc_mc.longDescTitle;
+  if (Capabilities.hasAccessibility)
+  Accessibility.updateProperties();
+}
+
+function hideLongDesc() {
+  //do the opposite to what showLongDesc does
+  graph_mc.accessibilityProperties.silent = false;
+  graph_mc.tabEnabled = true;
+  graph_mc.alpha = 1;
+  longDescBtn.enabled = true;
+  longDescBtn.accessibilityProperties.silent = false;
+  longDesc_mc.visible = false;
+  longDesc_mc.accessibilityProperties.silent = true;
+  longDesc_mc.tabEnabled = false;
+  longDescBtn.stage.focus = longDescBtn;
+  if (Capabilities.hasAccessibility)
+  Accessibility.updateProperties();
+}
+
+
+

Tests

+

Procedure

+

When a Flash movie contains images that require long descriptions, confirm that a longer description is made available through a separate button.

+
+

Expected Results

+
    +
  • The above is true
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH12.html b/techniques/flash/FLASH12.html new file mode 100644 index 0000000000..de380e4294 --- /dev/null +++ b/techniques/flash/FLASH12.html @@ -0,0 +1,113 @@ +Providing client-side validation and adding error text via the accessible description

Providing client-side validation and adding error text via the accessible description

ID: FLASH12

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to validate user input as values are entered for each field, by means of client-side scripting. If errors are found, a description is added to the controls that have invalid data. Visually, the description will be placed adjacent to the control. Additionally, the error message text is added to the control's accessible description so that it is readable by assistive technology when the control receives focus.

+ +

Examples

+
+

Validating a text field

+ +

In this example, a sample form is shown with two text fields ('name' and 'zip code'). Both fields are required. When the form's submit button is pressed, the values of the text fields will be validated. If a textfield contains an invalid value, an _accProps object is created for the textfield, and its description property is set the error message.

+
+

Instead of using the accessible description, the error text can also be added to the accessible name (_accProps.name), which is supported by a wider range of assistive technology than the _accProps.description property.

+
+

ActionScript 2.0 Code

+ +
import flash.accessibility. *;
+import mx.accessibilty.ButtonAccImpl;
+import mx.controls.Alert;
+import mx.accessibility.AlertAccImpl;
+
+AlertAccImpl.enableAccessibility();
+ButtonAccImpl.enableAccessibility;
+
+resetTextFieldAccNames();
+Accessibility.updateProperties();
+
+submit_btn.addEventListener("click", handleClick);
+function handleClick(e) {
+  //reset values
+  resetTextFieldAccNames();
+  resetTextFieldAccDescriptions();
+  resetErrorLabels();
+  //perform validation
+  var errors =[];
+  if (name_txt.text == '')
+    errors.push([name_txt, "You must enter your name", name_error_lbl]);
+  if (zipcode_txt.text == '')
+    errors.push([zipcode_txt, "You must enter your zip code", zipcode_error_lbl]);
+  else if (zipcode_txt.text.length != 5 || isNaN(zipcode_txt.text))
+    errors.push([zipcode_txt, "Zip code must be 5 digits", zipcode_error_lbl]);
+  
+  //add validation error messages, if any
+  var field, errorMsg, errorLabel;
+  if (errors.length > 0) {
+    //loop over encountered errors
+    for (var i = 0; i < errors.length; i++) {
+      field = errors[i][0];
+      errorMsg = errors[i][1];
+      errorLabel = errors[i][2];
+      
+      updateAccDescription(field, "Warning: " + errorMsg);
+      errorLabel.text = errorMsg;
+    }
+  } else {
+    Alert.show("Form field values were entered correctly");
+  }
+  Accessibility.updateProperties();
+}
+
+function updateAccName(obj, newName: String) {
+  if (! obj._accProps)
+  obj._accProps = new Object();
+  obj._accProps.name = newName;
+}
+
+function updateAccDescription(obj, newDescription: String) {
+  if (! obj._accProps)
+  obj._accProps = new Object();
+  obj._accProps.description = newDescription;
+}
+
+function getAccName(obj) {
+  return obj._accProps? obj._accProps.name: "";
+}
+
+function resetTextFieldAccNames() {
+  updateAccName(name_txt, "name, required");
+  updateAccName(zipcode_txt, "zip code, required");
+}
+
+function resetTextFieldAccDescriptions() {
+  updateAccDescription(name_txt, "");
+  updateAccDesciption(zipcode_txt, "");
+}
+
+function resetErrorLabels() {
+  name_error_lbl.text = "";
+  zipcode_error_lbl.text = "";
+}
+ +

This approach is demonstrated in working version of Validating a text field. The source of Validating a text field is available.

+ + +
+

Tests

+

Procedure

+

When a Flash movie provides interactive forms that can be submitted, confirm that:

+
    +
  1. The validation warnings are placed next to the control visually.
  2. +
  3. The validation warnings are added to the accessible name or description of each control.
  4. +
+
+

Expected Results

+
    +
  • #1 and #2 are true
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH13.html b/techniques/flash/FLASH13.html new file mode 100644 index 0000000000..520a7db452 --- /dev/null +++ b/techniques/flash/FLASH13.html @@ -0,0 +1,92 @@ +Using HTML language attributes to specify language in Flash content

Using HTML language attributes to specify language in Flash content

ID: FLASH13

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to identify the default language of the Flash content by providing the lang and/or xml:lang attribute on the HTML or object elements for the page containing the Flash. The embedded Flash content will inherit the language specified. If the entire web page uses the same language, the lang and/or xml:lang attribute can be placed on the page's HTML element, as described in H57: Using language attributes on the html element.

+

Since Flash inherits the language from the HTML or object element, all text within the Flash content is expected to be in that inherited language. This means that it is possible to have a Flash object in the French language on a page that is primarily in another language, or to have a page with multiple Flash objects, each in a different language. It is not possible, however, to indicate changes in the human language of content within a single Flash object using this technique.

+

Examples

+
+

Using the language of the page as whole in the embedded Flash

+ +

This example defined the content of the entire web page to be in the French language. The Flash content will inherit the specified language from the HTML container.

+ +
<?xml version="1.0" encoding="UTF-8"?>
+<html lang="fr" xml:lang="fr" xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta content="text/html; charset=iso-8859-1"
+      http-equiv="Content-Type"/>
+    <title>Flash Languages Examples - French</title>
+    <script src="swfobject.js" type="text/javascript"/>
+    <script type="text/javascript">
+    swfobject.registerObject("myMovie", "9.0.115", "expressInstall.swf");
+</script>
+  </head>
+  <body>
+    <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
+      height="420" id="myMovie" width="780">
+      <param name="movie" value="myMovie.swf"/>
+      <!--[if !IE]>-->
+      <object data="languages.swf" height="420"
+        type="application/x-shockwave-flash" width="780">
+        <!--<![endif]-->
+        <!--[if !IE]>-->
+      </object>
+      <!--<![endif]-->
+    </object>
+  </body>
+</html>
+
+ +

This is demonstrated in the working example of Using the language of the page as whole in the embedded Flash. The source of Using the language of the page as whole in the embedded Flash is available.

+ +
+
+

Applying a language just to the embedded Flash

+ +

This example defines the content of a Flash movie to be in the French language. The Flash movie is embedded using SWFObject's static publishing method. This means that there are two nested object elements, the outer to target Internet Explorer, the Inner to target other browsers. For this reason the lang and xml:lang attributes must be added twice.

+ +
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
+  height="420" id="myMovie" lang="fr" width="780" xml:lang="fr">
+  <param name="movie" value="myMovie.swf"/>
+  <!--[if !IE]>-->
+  <object data="languages.swf" height="420" lang="fr"
+    type="application/x-shockwave-flash" width="780" xml:lang="fr">
+    <!--<![endif]-->
+    <!--[if !IE]>-->
+  </object>
+  <!--<![endif]-->
+</object>
+
+
+

Tests

+

Procedure

+
    +
  1. Examine the html element and the object element of the HTML document containing the reference to the SWF.
  2. +
  3. Check that the human language of the Flash content is the same as the inherited language for the object element as specified in HTML 4.01, Inheritance of language codes
  4. +
  5. Check that the value of the lang attribute conforms to BCP 47: Tags for the Identification of Languages or its successor and reflects the primary language used by the Flash content.
  6. +
  7. Check that no changes in human language occur within the Flash content
  8. +
+
+

Expected Results

+
    +
  • For Success Criterion 3.1.1: Checks 1-3 are all true.
  • +
  • For Success Criterion 3.1.2: Checks 1-4 are all true.
  • +
+
+

Resources

+ + + +
\ No newline at end of file diff --git a/techniques/flash/FLASH14.html b/techniques/flash/FLASH14.html new file mode 100644 index 0000000000..3476ab6f49 --- /dev/null +++ b/techniques/flash/FLASH14.html @@ -0,0 +1,87 @@ +Using redundant keyboard and mouse event handlers in Flash

Using redundant keyboard and mouse event handlers in Flash

ID: FLASH14

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to demonstrate how to provide device independence by providing equivalent event handlers in response to a mouse or focus event. Supporting both mouse and keyboard events ensures that users will be able to perceive the same information, regardless of the input device they used. If the event changes the state of the control, it may be important to change the descriptive name of the control in the event handlers.

+

Examples

+
+

Updating button text with multiple event handlers

+ +

In this example, a group of buttons is assigned the same event handlers for the flash.events.FocusEvent.FOCUS_IN and flash.events.MouseEvent.MOUSE_OVER events. When a button receives focus or is hovered over using a mouse, text describing the button will be updated.

+ +
import fl.accessibility.ButtonAccImpl;
+import fl.controls.Button;
+import flash.accessibility. *
+import flash.events.FocusEvent;
+import flash.events.MouseEvent;
+import flash.net.navigateToURL;
+import flash.net.URLRequest;
+
+ButtonAccImpl.enableAccessibility();
+var states: Object = {
+  "Alabama": "Alabama is a state located in the southeastern region of the \
+    United States of America.",
+  "California": "California is the most populous state in the United States",
+  "New York": "New York is a state in the Mid-Atlantic and Northeastern \
+    regions of the United States"
+};
+
+var buttons: Array =[];
+var button: Button;
+var accProps: AccessibilityProperties;
+var count = 0;
+for (var i in states) {
+  button = new Button();
+  button.label = i;
+  button.addEventListener(MouseEvent.CLICK, clickHandler);
+  button.addEventListener(MouseEvent.MOUSE_OVER, highlightHandler);
+  button.addEventListener(MouseEvent.MOUSE_OUT, unHighlightHandler);
+  button.addEventListener(FocusEvent.FOCUS_IN, highlightHandler);
+  button.addEventListener(FocusEvent.FOCUS_OUT, unHighlightHandler);
+  accProps = new AccessibilityProperties();
+  accProps.description = states[i];
+  button.accessibilityProperties = accProps;
+  addChild(button);
+  button.x = 30
+  button.y = 30 + count * 30;
+  buttons[i] = button;
+  count++;
+}
+
+function highlightHandler(e) {
+  descText.text = states[e.target.label];
+}
+
+function unHighlightHandler(e) {
+  descText.text = "";
+}
+
+
+function clickHandler(e) {
+  var url: URLRequest = new URLRequest("http://www.wikipedia.org/wiki/" + e.target.label);
+  navigateToURL(url, "_self");
+}
+ +
+

To improve accessibility for screen reader users, the descriptive text is also attached to the buttons themselves as an accessible description. Also note that for button components, the MouseEvent.CLICK event will fire on mouse clicks as well as when the Enter key is pressed.

+
+

This technique is illustrated in the working version of Updating button text with multiple event handlers. The source of Updating button text with multiple event handlers is available.

+ +
+

Tests

+

Procedure

+

For all scripted event handlers in a Flash Movie,

+
    +
  1. Confirm that event handlers are assigned for both mouse and keyboard events
  2. +
+
+

Expected Results

+
    +
  • The above is true
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH15.html b/techniques/flash/FLASH15.html new file mode 100644 index 0000000000..03838d76e8 --- /dev/null +++ b/techniques/flash/FLASH15.html @@ -0,0 +1,88 @@ +Using the tabIndex property to specify a logical reading order and a logical tab order in Flash

Using the tabIndex property to specify a logical reading order and a logical tab order in Flash

ID: FLASH15

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to control the Flash Movie's reading order and tab order by assigning tabIndex values to its elements.

+

The tab order is the order in which objects receive input focus when users press the Tab key. The tab order does not necessarily contain the same elements as the reading order does, as the reading order can also contain elements that are not focusable. However, both the reading order and tab order can be controlled using tab index values.

+

Flash Player uses a default tab index order from left to right and top to bottom.

+

To create a custom reading order, assign a tab index value to every instance on the stage, either through ActionScript or through the Accessibility panel. Create a tabIndex value for every accessible object, not just the focusable objects. For example, dynamic text must have tab indexes, even though a user cannot tab to dynamic text.

+

You can create a custom tab-order index in the Accessibility panel for keyboard navigation for the following objects:

+
    +
  • Dynamic text
  • +
  • Input text
  • +
  • Buttons
  • +
  • Movie clips, including compiled movie clips
  • +
  • Components
  • +
  • Screens
  • +
+

Tab focus occurs in numerical order, starting from the lowest index number. After tab focus reaches the highest tab index, focus returns to the lowest index number. When you move tab-indexed objects that are user-defined in your document, or to another document, Flash retains the index attributes. Check for and resolve index conflicts (for example, two different objects on the Stage with the same tab-index number). If two or more objects have the same tab index in any given frame, Flash follows the order in which the objects were placed on the Stage.

+

To add a tabIndex value using the Accessibility panel, perform the following steps for every accessible object on the stage:

+
    +
  1. Select the element by clicking on it.
  2. +
  3. In the Accessibility panel, enter a numeric value in the "Tab index" field. The value must be a positive integer (up to 65535) that reflects the order in which the selected object should be read. Elements with higher tab index values will be read after elements with lower values. If two or more objects have the same tab index in any given frame, Flash follows the order in which the objects were placed on the Stage.
  4. +
  5. To visualize the currently defined tab order, select View > Show Tab Order. Tab index numbers for individual objects appear in the upper-left corner of the object.
  6. +
+
+

You can also use ActionScript code to create a tab-order index for keyboard navigation.

+
+

These steps are illustrated in the screenshots below

+
+ + +
visualizing the tab order
+ +
+
+ + +
Setting a tab index value in the Accessibility panel
+ +
+
+

Flash Player no longer requires that you add all of the objects in a FLA file to a list of tab index values. Even if you do not specify a tab index for all objects, a screen reader reads each object correctly.

+
+

Examples

+
+

Using tabIndex to navigate a column structure

+ +

This example contains dynamic TextField instances that are grouped into columns. To ensure the reading order follows the column structure. The TextField instances are given a tab index value that corresponds to their textual content (for example, the TextField containing the text "Sample Text 3" has a tabindex value of 3. Additionally, a single TextField is added that has no tabindex value set. This field contains the text "Not in tab order". Even though this field is visually placed between sample text 2 and 3, it is placed at the end of the custom tab order because it is not assigned a tabindex value.

+

The results can be found in the working version of Using tabindex to navigate a column structure. The source of Using tabindex to navigate a column structure is available.

+ +
+
+

Controlling tab order in a two-column layout

+ +

This example contains a Flash based form that is laid out over two + columns. To make the tab order follow the column structure, each form + control is assigned a tab index value in the Accessibility panel.

+

The results are shown in the working version of Controlling tab order in a two-column layout. The source of Controlling tab order in a two-column layout is available.

+ +
+

Tests

+

Procedure

+
    +
  1. Use a screen reader to navigate through the Flash movie, one element at a time.
  2. +
  3. Check that the order in which the screen reader announces the content, matches the logical visual order.
  4. +
  5. When focus has been placed inside the Flash movie, press the Tab key repeatedly to traverse its contents by keyboard.
  6. +
  7. Verify that all interactive and focusable elements are reachable by keyboard, in a logical order.
  8. +
+
+

Expected Results

+
    +
  • Checks #2 and #4 are true.
  • +
+
+

Resources

+ + + +
diff --git a/techniques/flash/FLASH16.html b/techniques/flash/FLASH16.html new file mode 100644 index 0000000000..5dea2aee33 --- /dev/null +++ b/techniques/flash/FLASH16.html @@ -0,0 +1,55 @@ +Making actions keyboard accessible by using the click event on standard components

Making actions keyboard accessible by using the click event on standard components

ID: FLASH16

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to demonstrate how to invoke a scripting function in a way that is keyboard accessible by attaching it to keyboard-accessible, standard Flash components provided by the Adobe Flash Professional authoring tool. In order to ensure that scripted actions can be invoked from the keyboard, they are associated with standard Flash components such as the Button component. The click event of these components is device independent. While the "CLICK" event is a mouse event, it is actually mapped to the default action of a button. The default action occurs when the user clicks the element with a mouse, but it also occurs when the user focuses the element and hits the space key, and when the element is triggered via the accessibility API.

+

Examples

+
+

Click event on a button

+ +

This example shows a button that uses the MouseEvent.CLICK event to change its label. This event will fire both on mouse click and when the space key is pressed

+ +
import fl.controls.Button;
+import fl.accessibility.ButtonAccImpl;
+
+ButtonAccImpl.enableAccessibility();
+
+var testBtn = new Button();
+testBtn.label = "click me";
+testBtn.addEventListener(MouseEvent.CLICK, clickHandler, false);
+addChild(testBtn);
+testBtn.x = testBtn.y = 10;
+
+function clickHandler(e) {
+  e.target.label = "Thanks";
+}
+ +

This approach is demonstrated in the working version of click event on a button. The source of click event on a button is available.

+ +
+
+

Pending example

+ + + The wiki source for FLASH16 indicated there was an action to add a second example. + + +
+

Tests

+

Procedure

+

When a Flash Movie contains interactive controls, confirm that:

+
    +
  1. Standard Flash components are used for the controls
  2. +
  3. The controls use the "click" event
  4. +
+
+

Expected Results

+
    +
  • #1 and #2 are true
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH17.html b/techniques/flash/FLASH17.html new file mode 100644 index 0000000000..d60164c759 --- /dev/null +++ b/techniques/flash/FLASH17.html @@ -0,0 +1,190 @@ +Providing keyboard access to a Flash object and avoiding a keyboard trap

Providing keyboard access to a Flash object and avoiding a keyboard trap

ID: FLASH17

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to allow keyboard focus to move to and from Flash content embedded in a web page. In browsers other than Internet Explorer, there is a problem related to keyboard accessibility of embedded Flash content. The problem is that, while both the Flash content and the HTML content around it may be keyboard accessible, many browsers do not support moving keyboard focus between the Flash content and HTML content without using a mouse. Once focus is placed inside the Flash content, a keyboard user will be trapped there. Similarly, when focus is placed somewhere else on the HTML content (outside the Flash content), it will be impossible to move focus into the content. This technique is designed to let the Flash author address this issue and provide support for moving focus between the Flash content and the HTML content via the keyboard.

+

This issue has been around for a long time, and is related to the way browsers implement embedded plug-ins. Until this problem is fixed, it is up to the Flash developer to come up with a work around. This technique is one of those workarounds. The approach behind this technique is the following:

+
    +
  • Two 'neighbor' focusable HTML objects are identified for each Flash content in the document (one before and one after the content). These elements can be any HTML elements that are part of the web page's tab order (such as links and form controls).
  • +
  • The Flash content object itself is added to the document tab order as well, making it possible to tab into the content.
  • +
  • Inside the Flash content, the Flash Player maintains its own tab order. Normally, when the start or end of the Flash tab order is reached (when tabbing through the content), focus will wrap to the beginning or end of the content's tab order, and it will not be possible to (shift) tab out of it. With this technique however, when a 'focus wrap' is detected focus will instead be moved to the neighboring element in the HTML tab order (allowing a keyboard user to 'break out' of the Flash tab order).
  • +
+

When the SWFFocus class is imported into a Flash project, the following will happen:

+
    +
  • +

    A JavaScript <script> tag will be generated and added to the HTML document containing the Flash content. This JavaScript code will:

    +
      +
    • Set a tabIndex value of "0" on the <object> element of each Flash content found in the page. This causes the Flash objects to become part of the tab order.
    • +
    • Optionally, create a hidden anchor element before and after the Flash content, which is used by the SWFFocus class to move focus out of the Flash content back into the HTML page. Alternatively, the developer can specify existing focusable HTML elements as adjacent tab stops for the Flash content.
    • +
    • Set event handlers for the Flash content object, so that when it receives focus, the SWFFocus class is notified to manage the content's internal tab order.
    • +
    +
  • +
  • The SWFFocus class monitors changes in focus within the Flash content. When a focus wrap is detected in the content, a JavaScript function will be called to instead move focus back to the neighboring HTML content.
  • +
+

As indicated above, there are two ways in which this technique can be used:

+
    +
  1. +

    Letting the SWFFocus class generate neighboring focusable elements in the HTML tab order for each Flash content (demonstrated in example 1 below)

    +

    By default, the SWFFocus class will create a hidden link element before and after an embedded Flash content. These elements are needed as 'anchor' to move focus to when (shift) tabbing out of the Flash content. This approach is the easiest to implement, as it does not require any additional work by the developer. The downside is that the hidden links will clutter the HTML tab order with meaningless elements (although these elements are only used as tab stops when tabbing _out of_ the Flash content, not when tabbing _into_ it). Because of this, it is recommended to use the following approach instead:

    +
  2. +
  3. +

    Explicitly identifying focusable HTML elements that come before and after the a Flash content in the HTML tab order (demonstrated in example 2 below)

    +

    With this approach, the developer can use ID values to identify the elements that come before and after the Flash content in the HTML tab order. This is done by setting special class names on the Flash content's <object> element. This is the preferred approach, as it does not cause an unnecessary cluttering of the tab order. However, it does require more work and awareness by the developer (who has to manually set ID values). Also, in some scenarios there simply may not be a next or previous focusable element for a Flash content.

    +
  4. +
+

Examples

+

The two examples below are shown in the working example of Preventing a keyboard trap in Flash content. The example html file has two Flash contents embedded in it. The first Flash content is embedded with the approach described in example 1. The second example is embedded with the approach described in example 2. The source of Preventing a keyboard trap in Flash content is available. The source zip file contains the SWFFocus class.

+
+

To run the example from a local drive (as opposed to running it from a web server), the local directory needs to be added to Flash Player's security settings.

+
+
+

Using automatically generated links

+ +

In this example, the SWFFocus class is used without explicitly identifying focusable HTML elements. This will cause SWFFocus to dynamically insert hidden links before and after the Flash content.

+

Loading the Flash Content

+

The Flash object in this example is added using SWFObject's dynamic publishing method, which means that the object tag is created dynamically by JavaScript in a way that the browser supports. While this is the recommended approach, it is not a requirement for using this technique. The SWFFocus class will also work when the object tag is hardcoded into the HTML document.

+

The sample code below shows how to load the content dynamically with SWFObject.

+

HTML and Javascript Code Sample for Example 1

+ +
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
+  "https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Keyboard Trap Fix Example</title>
+    <meta content="text/html; charset=utf-8" http-equiv="Content-Type"/>
+    <script src="swfobject_2_1.js" type="text/javascript"/>
+    <script type="text/javascript">
+      var flashvars = {};
+      var params = {};
+      params.scale = "noscale";
+      var attributes = {};
+      attributes.id = "FlashSample1SWF";
+      attributes.name = "FlashSample1SWF";
+      swfobject.embedSWF("keyboard_trap_fix_custom_as3.swf", "flashSample1", \
+          "150", "200", "9.0.0", "expressInstall.swf", flashvars, params, attributes);
+</script>
+  </head>
+  <body>
+    <p>The following Flash content automatically generates invisible
+      links before and after the flash content, allowing keyboard focus
+      to move out of the Flash content.</p>
+    <div id="flashSample1">
+      <a href="http://www.adobe.com/go/getflashplayer">
+        <img alt="Get Adobe Flash player"
+          src="http://www.adobe.com/images/shared/download_buttons/get_flash_player.gif"
+        />
+      </a>
+    </div>
+  </body>
+</html>
+ +

Importing and Initializing the SWFFocus class in Flash

+

The SWFFocus class needs to be added to a Flash or Flex project's source path. The easiest way to achieve this is to import the SWFFocus.swc into Library path for your project or to copy the com/swffocus/SWFFocus.as file (including the nested directory structure) to the project's root directory.

+

When the SWFFocus class is added to the content's source path, it needs to be initialized with the following code:

+ +
import com.adobe.swffocus.SWFFocus;
+SWFFocus.init(stage);
+ +

The code for the class itself can be found in the source files.

+ +
+
+

Explicitly identifying existing focusable html element

+ +

For a large part, this technique is the same as example 1 :

+
    +
  • The dynamic loading approach by SWFObject is used to load the Flash content
  • +
  • The SWFFocus class needs to be added to the content's sourcepath and initialized in the Flash content
  • +
+

For more details about these steps, see example 1.

+

In this case however, special class names are added to the Flash content object. These class names indicate the ID values of the elements previous and next of the content in the HTML tab order. The class names are:

+
    +
  • 'swfPref-<previous ID>', where '<previous element>' should be the ID value of the previous element in the tab order.
  • +
  • 'swfNext-<next ID>', where '<next element>' should be the ID value of the next element in the tab order.
  • +
+

For example, the HTML code could look like this (notice the added class names on the object tag):

+ +
<a href="http://www.lipsum.com/" id="focus1">test 1</a>
+<object class="swfPrev-focus1 swfNext-focus2"
+  data="keyboard_trap_fix_as3.swf" tabindex="0"
+  type="application/x-shockwave-flash"/>
+<a href="http://www.lipsum.com/" id="focus2">test 2</a>
+ +

Since this example uses SWFObject's dynamic loading, the class names will have to be specified as attribute when SWFObject is initialized. This is demonstrated in the code example below.

+

HTML and Javascript Code Sample for Example 2

+ +
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
+  "https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Keyboard Trap Fix Example </title>
+    <meta content="text/html; charset=utf-8" http-equiv="Content-Type"/>
+    <script src="swfobject_2_1.js" type="text/javascript"/>
+
+    <script type="text/javascript">
+      var flashvars = {};
+      var params = {};
+      params.scale = "noscale";
+      var attributes = {};
+      attributes.id = "FlashSample2SWF";
+      attributes.name = "FlashSample2SWF";
+      attributes["class"] = "swfPrev-focus1 swfNext-focus2";
+      swfobject.embedSWF("keyboard_trap_fix_as3.swf", "flashSample1", "150", 
+        "200", "9.0.0", "expressInstall.swf", flashvars, params, attributes);
+    </script>
+  </head>
+  <body>
+    <a href="http://www.lipsum.com/" id="focus1">lorem</a>
+    <p>The following Flash content uses existing links in the document
+      to move focus to when (shift) tabbing out of the Flash content.
+      The existing links are defined by placing special classnames on
+      the Flash object.</p>
+    <div id="flashSample2">
+      <a href="http://www.adobe.com/go/getflashplayer">
+        <img alt="Get Adobe Flash player"
+          src="http://www.adobe.com/images/shared/download_buttons/get_flash_player.gif"
+        />
+      </a>
+    </div>
+    <a href="http://www.lipsum.com/">lorem</a>
+  </body>
+</html>
+ +

Note: this example assumes that the focusable HTML elements exist and have an ID value at the time SWFObject is called to insert the Flash content. However, in some situations it is also possible that these elements do not yet exist when the Flash content is created, or that the elements will be deleted dynamically at a later point. If this happens, it is possible to reassign ID values for previous and next focusable elements. To do this, call the SWFsetFocusIds() method on the Flash content object, like so:

+ +
var o = document.getElementById("FlashSample1SWF");
+o.SWFsetFocusIds('prevId', 'nextId');
+ +

From that point on the updated IDs will be used to move focus to when tabbing out of the Flash content.

+ +
+

Tests

+

Procedure

+

For a Flash content on a web page:

+
    +
  1. If possible, confirm that the source of the Flash content imports and initializes the SWFFocus class
  2. +
  3. Press the tab key to move through tabbable items on the page
  4. +
  5. Confirm that it is possible to tab into the Flash content
  6. +
  7. Continue tabbing and confirm that it is possible to tab out of the flash content
  8. +
+
+

Expected Results

+
    +
  • Checks 3 and 4 are true
  • +
+
+

Resources

+ + + +
\ No newline at end of file diff --git a/techniques/flash/FLASH18.html b/techniques/flash/FLASH18.html new file mode 100644 index 0000000000..c247576485 --- /dev/null +++ b/techniques/flash/FLASH18.html @@ -0,0 +1,158 @@ +Providing a control to turn off sounds that play automatically in Flash

Providing a control to turn off sounds that play automatically in Flash

ID: FLASH18

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The intent of this technique is to allow a user to turn off sounds that start automatically when a Flash movie loads. The control to turn off the sounds should be located near the beginning of the page to allow the control to be easily and quickly discovered by users . This is useful for those who utilize assistive technologies (such as screen readers, screen magnifiers, switch mechanisms, etc.) and those who may not (such as those with cognitive, learning and language disabilities).

+

In this technique, an author includes a control that makes it possible for users to turn off any sounds that are played automatically. For maximum accessibility, the control can be added to the HTML document rather than to the Flash movie. The HTML control will communicate with the Flash movie through the ExternalInterface class. This means that the user can control the sound playback without having to interact with Flash content. If this is not practical, the control can be provided within the Flash content, provided that the control is keyboard operable, located early in the tab and reading order, and clearly labeled to indicate that it will turn off the sounds that are playing.

+

Examples

+
+

Providing a button in the Flash to stop sound

+ +

This example demonstrates the addition of a button within the Flash movie to allow the user to stop sounds from playing. A class called SoundHandler is created which automatically starts playing an mp3 file when the movie loads.

+ +
package wcagSamples {
+  import flash.display.Sprite;
+  import flash.net.URLRequest;
+  import flash.media.Sound;
+  import flash.media.SoundChannel;
+  
+  import fl.controls.Button;
+  import fl.accessibility.ButtonAccImpl;
+  
+  import flash.events.MouseEvent;
+  public class SoundHandler extends Sprite {
+    private var snd: Sound = new Sound();
+    private var button: Button = new Button();
+    private var req: URLRequest = new URLRequest("http://av.adobe.com/podcast\
+      /csbu_dev_podcast_epi_2.mp3");
+    private var channel: SoundChannel = new SoundChannel();
+    
+    public function SoundHandler() {
+      ButtonAccImpl.enableAccessibility();
+      button.label = "Stop Sound";
+      button.x = 10;
+      button.y = 10;
+      button.addEventListener(MouseEvent.CLICK, clickHandler);
+      this.addChild(button);
+      snd.load(req);
+      channel = snd.play();
+    }
+    private function clickHandler(e: MouseEvent): void {
+      if (button.label == "Stop Sound") {
+        button.label = "Start Sound";
+        channel.stop();
+      } else {
+        channel = snd.play();
+        button.label = "Stop Sound";
+      }
+    }
+  }
+}
+ +

This is demonstrated in the working example of Providing a button in the Flash to stop sound. The source of Providing a button in the Flash to stop sound is available.

+ +
+
+

Providing a button in the HTML before the Flash object to stop sound

+ +

A class called SoundHandler is created which automatically starts playing an mp3 file when the movie loads. An HTML button is placed in the HTML document containing the Flash movie. When the button is clicked the action is communicated between the HTML page and the Flash movie via the Flash Player JavaScript API, resulting in the toggleSound method being called on the SoundHandler class.

+

ActionScript 3.0 code for Example 2

+ +
package wcagSamples {
+  import flash.display.Sprite;
+  import flash.external.ExternalInterface;
+  import flash.net.URLRequest;
+  import flash.media.Sound;
+  import flash.media.SoundChannel;
+  
+  import flash.events.MouseEvent;
+  public class SoundHandler extends Sprite {
+    private var snd: Sound = new Sound();
+    private var soundOn: Boolean = true;
+    private var req: URLRequest = new URLRequest("http://av.adobe.com/podcast/\
+      csbu_dev_podcast_epi_2.mp3");
+    private var channel: SoundChannel = new SoundChannel();
+    
+    public function SoundHandler() {
+      if (ExternalInterface.available)
+      ExternalInterface.addCallback("toggleSound", this.toggleSound);
+      snd.load(req);
+      channel = snd.play();
+    }
+    
+    private function toggleSound(enable: Boolean): void {
+      if (! enable) {
+        channel.stop();
+        soundOn = true;
+      } else {
+        channel = snd.play();
+        soundOn = true
+      }
+    }
+  }
+}
+ +

HTML code for Example 2

+ +
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
+  "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
+    <title>Flash Sound Toggle example</title>
+    <script src="swfobject.js" type="text/javascript"/>
+    <script type="text/javascript">
+    function $(id) {
+        return document.getElementById(id);
+    }
+    
+    swfobject.embedSWF("html_control_to_toggle_audio_as3.swf", 
+      "flashPlaceHolder", "0", "0", "8");
+    function init() {
+            var soundOn = true;
+            $("soundToggle").onclick = function(event){
+                soundOn = !soundOn;
+                $("flashPlaceHolder").toggleSound(soundOn);
+                event.target.value = soundOn ? "Stop Sound" : "Start Sound";
+            };
+    }
+    window.onload = init;
+</script>
+
+  </head>
+  <body id="header">
+    <h1>Flash Automatic Sound Demo</h1>
+    <p>This page contains a Flash movie that automatically starts
+      playing sound. Use the button below to stop or start the
+      sound</p>
+    <input id="soundToggle" type="button" value="Stop Sound"/>
+    <p id="flashPlaceHolder">Flash needs to be installed for this
+      example to work</p>
+  </body>
+</html>
+
+ +

This is demonstrated in the working example of Providing a button in the HTML before the Flash object to stop sound. The source of source of Providing a button in the HTML before the Flash object to stop sound is available.

+ +
+

Tests

+

Procedure

+

For Flash movies that automatically start playing sound after loading:

+
    +
  1. Confirm that an HTML control that conforms to WCAG 2.0 is placed at the beginning of the document's tab order
  2. +
  3. If there is no HTML-based control, confirm that an accessible control is placed at the beginning of the Flash movie's tab order.
  4. +
  5. Activate the HTML or Flash-based control
  6. +
  7. Verify that audio playback stops
  8. +
+
+

Expected Results

+
    +
  • Check #1 or #2 is true, and #4 is true.
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH19.html b/techniques/flash/FLASH19.html new file mode 100644 index 0000000000..4efe3e1528 --- /dev/null +++ b/techniques/flash/FLASH19.html @@ -0,0 +1,67 @@ +Providing a script that warns the user a time limit is about to expire and provides a way to extend it

Providing a script that warns the user a time limit is about to expire and provides a way to extend it

ID: FLASH19

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to notify users that they are almost out of time to complete an interaction. When scripts provide functionality that has time limits, the script can include functionality to warn the user of imminent time limits and provide a mechanism to request more time. 20 seconds or more before the time limit occurs, the script provides a confirm dialog that states that a time limit is imminent and asks if the user needs more time. If the user answers "yes" then the time limit is reset. If the user answers "no" or does not respond, the time limit is allowed to expire.

+

This technique involves time limits set with the setTimeout() method. If, for example, the time limit should be 60 seconds, you can set the time limit for 40 seconds (20 seconds less than the desired timeout) and show a confirm dialog. The confirm dialog sets a new timeout for the remaining 20 seconds. If the user requests more time, a new timeout is set. However, if the 20-second "grace period time limit" expires (meaning 60 seconds have now elapsed), the action appropriate for the expiry of the 60 second time limit in the original design is taken.

+

Examples

+
+

Using ActionScript to offer a time limit extension before the timeout expires

+ +

This is a basic AS2 example of a time limit that can be extended by the user. An alert is shown after 40 seconds of inactivity, warning that the session is about to expire. The user is given 20 seconds to press the space bar or click on the "Yes" button. Note that the 40 second duration would be insufficient for most tasks and is artificially short for ease of demonstration.

+ +
import mx.controls.Alert;
+import flash.accessibility.Accessibility;
+
+mx.accessibility.AlertAccImpl.enableAccessibility();
+
+var sessionTimeout;
+var sessionNotificationTimeout;
+var timeLimit: Number = 60000;
+var sessionAlert: Alert;
+resetTimeout();
+
+testField.addEventListener("change", resetTimeout);
+
+function resetTimeout() {
+  clearTimeout(sessionTimeout);
+  clearTimeout(sessionNotificationTimeout);
+  sessionTimeout = setTimeout(endSession, timeLimit);
+  sessionNotificationTimeout = setTimeout(showTimeoutAlert, timeLimit - 20000);
+}
+
+function showTimeoutAlert() {
+  sessionAlert = Alert.show("Click the YES button to extend your session",
+  "Your login session is about to expire, do you need more time?",
+  Alert.YES | Alert.NO, null, handleAlertClick);
+}
+
+function endSession() {
+  sessionAlert.deletePopUp();
+  Alert.show("please log in again",
+  "Your session has expired");
+}
+
+function handleAlertClick(e) {
+  if (e && e.detail && e.detail == Alert.YES)
+  resetTimeout();
+}
+ +

For a demonstration, see a working example of Using ActionScript to offer a time limit extension before the timeout expires. The source of Using ActionScript to offer a time limit extension before the timeout expires is available.

+ +
+

Tests

+

Procedure

+
    +
  1. load the page and start a timer that is 20 seconds less than the time limit.
  2. +
  3. when the timer expires, check that a confirmation dialog is displayed warning of the impending time limit and allows the user to extend the limit within 20 seconds.
  4. +
+
+

Expected Results

+

Check #2 is true

+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH2.html b/techniques/flash/FLASH2.html new file mode 100644 index 0000000000..ac403e3412 --- /dev/null +++ b/techniques/flash/FLASH2.html @@ -0,0 +1,92 @@ +Setting the description property for a non-text object in Flash

Setting the description property for a non-text object in Flash

ID: FLASH2

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to provide a long text alternative that serves the same purpose and presents the same information as the original non-text content when a short text alternative is not sufficient.

+

The Flash Player supports long text alternatives to non-text objects, which can be defined in ActionScript or within Flash authoring tools using the description property, as indicated in the examples below.

+

Examples

+
+

Applying a Description for a symbol (graphic, button or movieclip)

+ +

The Flash Professional authoring tool's Accessibility panel lets authors provide accessibility information to assistive technology and set accessibility options for individual Flash objects or entire Flash applications.

+
    +
  1. For a text alternative to be applied to a non-text object, it must be saved as a symbol in the movie's library. Note: Flash does not support text alternatives for graphic symbols. Instead, the graphic must be converted to or stored in a movie clip or button symbol.
  2. +
  3. Bring up the Accessibility panel by selecting "Window > Other Panels > Accessibility" in the application menu, or through the shortcut ALT + F11. Ensure that the 'Make object accessible' checkbox is checked.
  4. +
  5. Select the non-text instance on the movie stage, the fields in the Accessibility panel become editable.
  6. +
  7. Enter a description describing the non-text object's contents concisely. For example, a diagram could have a 'name' identifying what information the diagram conveys, while the 'Description' field lists this information in full detail. Alternatively, for an animation which is part of an instructional movie about car repairs the name could be: 'how to replace a flat tire', while the long description describes each step of the process in greater detail.
  8. +
+

+ Important: Only use the 'Description' field if a short text alternative is not sufficient to describe the objects purpose. Otherwise, leave the 'Description' field empty.

+
+ + +
The Accessibility panel in the Flash authoring environment.
+ +
+ + +
+
+

Applying Description programmatically in ActionScript 2.0

+ +

To manage an object's text equivalents programmatically using ActionScript, the _accProps object must be used. This references an object containing accessibility related properties set for the object. The code example below shows a simple example of how the _accProps object is used to set an objects name and description in ActionScript.

+

A chart showing sales for October has a short text alternative of "October sales chart". The long description would provide more information, as shown in the code below.

+ +
// 'chart_mc' is an instance placed on the movie's main timeline
+_root.chart_mc._accProps = new Object();
+_root.chart_mc._accProps.name = "October Sales Chart";
+_root.chart_mc._accProps.description = "Bar Chart showing sales for October.\
+  There are 6 salespersons.Maria is highest with 349 units.Frances is next\
+  with 301.Then comes Juan with 256, Sue with 250, Li with 200 and Max\
+  with 195.The primary use of the chart is to show leaders, so the description\
+  is in sales order.";
+
+
+

Applying Description programmatically in ActionScript 3.0

+ +

To manage an object's text equivalents programmatically using ActionScript, the AccessibilityProperties object must be used. The code example below shows a simple example of how the AccessibilityProperties object used to set an objects name and description in ActionScript.

+

A chart showing sales for October has a short text alternative of "October sales chart". The long description would provide more information, as shown in the code below.

+ +
// 'chart_mc' is an instance placed on the movie's main timeline
+chart_mc.accessibilityProperties = new AccessibilityProperties();
+chart_mc.accessibilityProperties.name = "October Sales Chart";
+chart_mc.accessibilityProperties.description = "Bar Chart showing sales for October.\
+  There are 6 salespersons.Maria is highest with 349 units.Frances is next\
+  with 301.Then comes Juan with 256, Sue with 250, Li with 200 and Max\
+  with 195.The primary use of the chart is to show leaders, so the description\
+  is in sales order.";
+
+

Tests

+

Procedure

+
    +
  1. Publish the SWF file
  2. +
  3. Open the SWF file in Internet Explorer 6 or higher (using Flash Player 6 or higher), or Firefox 3 or higher (using Flash Player 9 or higher)
  4. +
  5. Use a tool which is capable of showing an object's long description, such as ACTF aDesigner 1.0 to open the Flash movie.
  6. +
  7. In the GUI summary panel, loop over each object which is contained by the Flash movie and ensure the object that was provided a description has a proper description value appearing in the tool's display.
  8. +
  9. Authors may also test with a screen reader, by reading the Flash content and listening to hear that the description is read when tabbing to the non-text object (if it is tabbable) or hearing the alternative text read when reading the content line-by-line.
  10. +
  11. All non-text objects have text equivalents that can serve the same purpose and convey the same information as the non-text object.
  12. +
+
+

Expected Results

+

#6 is true.

+
+

Resources

+ + + +
diff --git a/techniques/flash/FLASH20.html b/techniques/flash/FLASH20.html new file mode 100644 index 0000000000..edb1aa23d5 --- /dev/null +++ b/techniques/flash/FLASH20.html @@ -0,0 +1,148 @@ +Reskinning Flash components to provide highly visible focus indication

Reskinning Flash components to provide highly visible focus indication

ID: FLASH20

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The purpose of this technique is to allow the author to use ActionScript and component skins to apply a strong visual indication when a component receives focus. In this particular technique, both the component's background color and border will change. When the component loses focus, it returns to its normal styling.

+

The visual highlights will be applied by switching some of the component's skin parts. The Standard Flash components each have their own set of skins that make up the component's visual appearance. Each part is represented by a MovieClip which can be edited or replaced in order to customize how the component looks. The most relevant skin for this technique is the focusRectSkin skin, which is shared by all components. By default this skin applies a subtle visual highlight when the component receives focus.

+

This technique can be applied through the following steps:

+
    +
  1. Create a customized version of focusRectSkin.
  2. +
  3. Use scripting to associate the component with the customized skin.
  4. +
+

There are two ways to customize a skin:

+ +
    +
  1. +

    Duplicating Existing Skin

    +

    With this approach you create a copy of the existing focusRect skin for modification. You will manually have to apply the skin for each individual component instance (as indicated in step 5 below).

    +
      +
    1. Drag the components you want to style to the stage. This will ensure the appropriate component related skins are added to the movie's library.
    2. +
    3. Open the Library panel, and navigate to the "Component Assets > Shared" folder.
    4. +
    5. Right-click (or Ctrl-click on a Mac) on the focusRectSkin MovieClip, and choose "Duplicate" from the context menu.
    6. +
    7. Edit the visual border in the skin's MovieClip. For example, the focus rectangle can be made thicker to stand out more (This step is illustrated in the screenshot below this list).
    8. +
    9. Using ActionScript, associate form component instances with your customized version of focusRectSkin. This can be achieved using the setStyle method.
    10. +
    +
    + + +
    Editing a duplicate of focusRectSkin
    + +
    +
  2. +
  3. +

    Modifying Existing Skin

    +

    With this approach, the original focusRect skin is modified. This means that the changes you make will be applied to the visual focus indication of _every_ focusable component.

    +
      +
    1. Drag the components you want to style to the stage. This will ensure the appropriate component related skins are added to the movie's library.
    2. +
    3. Open the Library panel, and navigate to the "Component Assets > Shared" folder.
    4. +
    5. Open the focusRectSkin MovieClip for editing by double clicking on it.
    6. +
    7. Edit the visual border in the skin's MovieClip. For example, the focus rectangle can be made thicker to stand out more.
    8. +
    +
    +

    With this approach you will override the existing skin. If you don't want this, follow the "Duplicate Existing Skin" approach instead.

    +
    +
  4. +
+

The focusRect skin applies to all focusable Flash components. If you want to modify other highlights (for example highlights that occur when hovering over a component with the mouse), you will have to edit component specific skins individually. For example, to edit the mouseover highlights for the checkbox component, you will have to modify or duplicate both Checkbox_overIcon and Checkbox_selectedOverIcon. Similarly, for the Button component you will have to modify the Button_over skin.

+

Also, keep in mind that the existing skins are automatically applied on certain events (focus, mouseover, etc.). It is however also possible to manually switch a skin at a moment of your own choosing (e.g. to indicate invalid content for a text field). this can also be achieved this by calling the setStyle method.

+

Examples

+
+

A thick blue border to indicate focus

+ +

The code below shows an example where form component instances are associated with a modified version of the focusRectSkin MovieClip. The result is that the components receive a thick blue border rather than the default thin border Flash provides. The code makes a reference to a modified skin called Focus_custom, which has been added to the movie's library in advance.

+

Note that the custom version of focusRectSkin also sets a transparent yellow background to increase the visual highlight further. Components such as Buttons and checkboxes will show this background, but TextInput components will not. To ensure the yellow background will still be applied to the TextInput instance, the following workaround is applied:

+
    +
  1. A duplicate version of the TextInput "normal" skin (which can be found in the library at "Component Asssets > TextInputSkins > TextInput_upSkin") is created and edited to show a yellow background.
  2. +
  3. FocusIn, FocusOut, MouseOver and MouseOut handlers are assigned to the TextInput instance, which temporarily swap the default "normal" skin with the custom "normal" skin while the component is focused or hovered over.
  4. +
+

Additionally, the button_over skin is duplicated and modified to change the default mouseover highlights for the button component instance. The checkbox_overIcon and checkbox_selectedOverIcon skins are directly modified, which means those changes will be applied to all checkbox instances.

+

The result of this technique can be found in the working version of A thick blue border to indicate focus.

+

Code for Example 1 (ActionScript 3.0)

+ +
package wcagSamples {
+  import fl.accessibility.ButtonAccImpl;
+  import fl.accessibility.CheckBoxAccImpl;
+  import fl.controls.CheckBox;
+  import fl.controls.Button;
+  import fl.controls.Label;
+  import fl.controls.TextInput;
+  import flash.display.Sprite;
+  import flash.events.FocusEvent;
+  import flash.events.MouseEvent;
+  
+  public class FocusStyler extends Sprite {
+    public function FocusStyler() {
+      ButtonAccImpl.enableAccessibility()
+      CheckBoxAccImpl.enableAccessibility()
+      
+      var lbl1: Label = new Label();
+      lbl1.text = "name";
+      lbl1.x = lbl1.y = 20;
+      addChild(lbl1);
+      
+      var txt1: TextInput = new TextInput();
+      txt1.x = 60;
+      txt1.y = 20;
+      txt1.width = 200;
+      txt1.addEventListener(FocusEvent.FOCUS_IN, handleFocusIn);
+      txt1.addEventListener(FocusEvent.FOCUS_OUT, handleFocusOut);
+      txt1.addEventListener(MouseEvent.MOUSE_OVER, handleFocusIn);
+      txt1.addEventListener(MouseEvent.MOUSE_OUT, handleFocusOut);
+      txt1.setStyle("focusRectSkin", "focus_custom");
+      addChild(txt1);
+      
+      var chk1: CheckBox = new CheckBox();
+      chk1.label = "Check Me";
+      chk1.x = 60;
+      chk1.y = 70;
+      chk1.setStyle("focusRectSkin", "focus_custom");
+      addChild(chk1);
+      
+      var btn1: Button = new Button();
+      btn1.label = "Click Me";
+      btn1.x = 60;
+      btn1.y = 110;
+      btn1.setStyle("focusRectSkin", "focus_custom");
+      btn1.setStyle("overSkin", "Button_over_custom");
+      addChild(btn1);
+    }
+    
+    private function handleFocusIn(event) {
+      event.currentTarget.setStyle("upSkin", "TextInput_upSkin_custom");
+    }
+    
+    private function handleFocusOut(event) {
+      event.currentTarget.setStyle("upSkin", "TextInput_upSkin");
+    }
+  }
+}
+ +

This is demonstrated in working version of A thick blue border to indicate focus. The source of working version of A thick blue border to indicate focus is available.

+ +
+

Tests

+

Procedure

+

When a Flash movie contains focusable components, confirm that:

+
    +
  1. The visual highlight is applied by modifying the component's skins
  2. +
  3. A visual highlight is shown when the components receive focus
  4. +
+
+

Expected Results

+
    +
  • #1 and #2 are true
  • +
+
+

Resources

+ + + +
diff --git a/techniques/flash/FLASH21.html b/techniques/flash/FLASH21.html new file mode 100644 index 0000000000..14a60e6b40 --- /dev/null +++ b/techniques/flash/FLASH21.html @@ -0,0 +1,78 @@ +Using the DataGrid component to associate column headers with cells

Using the DataGrid component to associate column headers with cells

ID: FLASH21

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The intent of this Technique is to ensure that information and relationships that are implied visually by data tables are also made available programmatically. Specifically, the association between table column headers and their corresponding cells must be exposed to assistive technology. In Flash, the DataGrid component can be used to achieve this. When accessibility is enabled for the DataGrid component, Flash will automatically prepend the column name in front of each cell value when exposing the grid row's accessible name to assistive technology. For example, the row in the screenshot below would be announced by a screen reader as "Row 6 of 13 Name Patty Crawford Bats L Throws L Year Jr Home Whittier, CA".

+
+

The DataGrid component in Flash only supports column headings, not row headings.

+
+
+ + + +
screenshot of highlighted row in grid component
+ +
+

Examples

+
+

A statistical data table

+ +

In this example, statistical data is used as data provider for a dynamically created DataGrid component. The lines import fl.accessibility.DataGridAccImpl; DataGridAccImpl.enableAccessibility(); are required to enable accessibility for the Datagrid Component.

+ +
import fl.accessibility.DataGridAccImpl;
+DataGridAccImpl.enableAccessibility();
+
+import fl.data.DataProvider;
+bldRosterGrid(aDg);
+var aRoster: Array = new Array();
+aRoster = [ {
+  Name: "Wilma Carter", Bats: "R", Throws: "R", Year: "So", Home: "Redlands, CA"}, {
+  Name: "Sue Pennypacker", Bats: "L", Throws: "R", Year: "Fr", Home: "Athens, GA"}, {
+  Name: "Jill Smithfield", Bats: "R", Throws: "L", Year: "Sr", Home: "Spokane, WA"}, {
+  Name: "Shirley Goth", Bats: "R", Throws: "R", Year: "Sr", Home: "Carson, NV"}, {
+  Name: "Jennifer Dunbar", Bats: "R", Throws: "R", Year: "Fr", Home: "Seaside, CA"}, {
+  Name: "Patty Crawford", Bats: "L", Throws: "L", Year: "Jr", Home: "Whittier, CA"}, {
+  Name: "Angelina Davis", Bats: "R", Throws: "R", Year: "So", Home: "Odessa, TX"}, {
+  Name: "Maria Santiago", Bats: "L", Throws: "L", Year: "Sr", Home: "Tacoma, WA"}, {
+  Name: "Debbie Ferguson", Bats: "R", Throws: "R", Year: "Jr", Home: "Bend, OR"}, {
+  Name: "Karen Bronson", Bats: "R", Throws: "R", Year: "Sr", Home: "Billings, MO"}, {
+  Name: "Sylvia Munson", Bats: "R", Throws: "R", Year: "Jr", Home: "Pasadena, CA"}, {
+  Name: "Carla Gomez", Bats: "R", Throws: "L", Year: "Sr", Home: "Corona, CA"}, {
+  Name: "Betty Kay", Bats: "R", Throws: "R", Year: "Fr", Home: "Palo Alto, CA"}
+];
+aDg.dataProvider = new DataProvider(aRoster);
+aDg.rowCount = aDg.length;
+
+function bldRosterGrid(dg: DataGrid) {
+  dg.setSize(400, 300);
+  dg.columns =[ "Name", "Bats", "Throws", "Year", "Home"];
+  dg.columns[0].width = 120;
+  dg.columns[1].width = 50;
+  dg.columns[2].width = 50;
+  dg.columns[3].width = 40;
+  dg.columns[4].width = 120;
+  dg.move(50, 50);
+};
+ +

This is demonstrated in the working version of A statistical data table. The source of A statistical data table is available.

+ +
+

Tests

+

Procedure

+

For Flash content that contains tabular data:

+
    +
  1. Open the SWF file in Internet Explorer 6 or higher (using Flash Player 6 or higher), or Firefox 3 or higher (using Flash Player 9 or higher)
  2. +
  3. Use a tool which is capable of showing an object's accessibility name, such as ACTF aDesigner 1.0 to open the Flash movie.
  4. +
  5. In the GUI summary panel, inspect the accessibility name for the DataGrid rows and cells to ensure that the heading data is presented in conjunction with the data cell data.
  6. +
  7. Authors may also test with a screen reader, by reading the Flash content and listening to hear that the heading and data cell data are read when reading the DataGrid.
  8. +
  9. Authors may also verify in the Flash authoring tool that the DataGrid component is used to structure the data and that the DataGrid has been made accessible using the DataGridAccImpl.enableAccessibility method.
  10. +
+
+

Expected Results

+
    +
  • Check 3, 4, or 5 is true
  • +
+
+
diff --git a/techniques/flash/FLASH22.html b/techniques/flash/FLASH22.html new file mode 100644 index 0000000000..ff0b94522b --- /dev/null +++ b/techniques/flash/FLASH22.html @@ -0,0 +1,80 @@ +Adding keyboard-accessible actions to static elements

Adding keyboard-accessible actions to static elements

ID: FLASH22

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to demonstrate how to provide keyboard + access to a Flash MovieClip that is not keyboard accessible by default. + This technique ensures that the element is focusable by setting the + tabEnabled property, and it ensures that the action can be triggered + from the keyboard by providing a keydown handler in addition to a click + handler.

+

Examples

+
+

MovieClip used as a button

+ +

In this example, a custom MovieClip is used as a button. To make it + keyboard accessible, the MovieClip is placed in the tab order using + the tabEnabled. Additionally, redundant event handlers are added so + that the custom button responds to both a mouse click and a space bar + keypress. Finally, the custom button is provided an accessible name + using the MovieClip's AccessibilityProperties object. This makes the + button's label perceivable by assistive technology.

+

This result can be viewed in the working + version of MovieClip used as a button. The source of MovieClip used as a button is available.

+
+

Using a generic MovieClip is generally not recommended, since + the custom button will be perceived as a focusable graphic rather than + a button. Instead, a better approach would be to use the standard Flash + Button component, or create a new symbol with a type of "button".

+
+ +
import flash.accessibility. *
+import flash.events.KeyboardEvent;
+import flash.events.MouseEvent;
+import flash.net.navigateToURL;
+import flash.net.URLRequest;
+
+testMC.tabEnabled = true;
+updateAccName(testMC);
+testMC.addEventListener(MouseEvent.CLICK, clickHandler, false);
+testMC.addEventListener(KeyboardEvent.KEY_DOWN, keyDownHandler);
+
+updateAccName(testMC);
+
+function clickHandler(e) {
+  testMC.labelText.text = "THANKS";
+  updateAccName(testMC);
+}
+
+function keyDownHandler(e) {
+  if (e.keyCode == 32)
+  clickHandler(e);
+}
+
+function updateAccName(mc: MovieClip) {
+  if (! mc.accessibilityProperties)
+  mc.accessibilityProperties = new AccessibilityProperties();
+  mc.accessibilityProperties.name = mc.labelText.text;
+  Accessibility.updateProperties();
+}
+
+

Tests

+

Procedure

+

When a Flash Movie contains generic MovieClip instances that are used + as interactive controls, confirm that:

+
    +
  1. The MovieClip instance has its tabEnabled property set to true
  2. +
  3. The MovieClip instance has event handlers for both mouse and keyboard events
  4. +
+
+

Expected Results

+
    +
  • #1 and #2 are true
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH23.html b/techniques/flash/FLASH23.html new file mode 100644 index 0000000000..1b9ad2d59c --- /dev/null +++ b/techniques/flash/FLASH23.html @@ -0,0 +1,110 @@ +Adding summary information to a DataGrid

Adding summary information to a DataGrid

ID: FLASH23

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to provide a brief overview of + how data has been organized into a DataGrid or a brief explanation + of how to navigate the grid.

+

As Flash does not provide a summary attribute, this descriptive text + will be added to the DataGrid's accessible desription instead. This + approach will make the summary information available to people who + use screen readers; the information is not displayed visually.

+

The summary is useful when the table has a complex structure (for + example, when there are several sets of row or column headers, or when + there are multiple groups of columns or rows). The summary may also + be helpful for simple data tables that contain many columns or rows + of data.

+

Examples

+
+

Adding a summary to a DataGrid in the Accessibility control panel

+ +

This is an example of a DataGrid being added to the stage in Flash + Professional from the Components panel. The description field is used + in the Accessibility control panel in Flash to serve as the summary + information for the DataGrid.

+
    +
  1. Create a new Flash file (.fla) or open an existing one to put + a DataGrid into.
  2. +
  3. Open the Flash components panel from the Window menu
  4. +
  5. Drag a DataGrid component onto the stage and position as desired.
  6. +
  7. Select the DataGrid component and add the summary information + to the description field for DataGrid, using the Accessibility control + panel.
  8. +
+ +
+
+

Adding a summary to a DataGrid with ActionScript 3

+ +

This is a basic AS3 example of a DataGrid component that has summary + text added as its accessible description.

+ +
import fl.accessibility.DataGridAccImpl;
+import fl.controls.DataGrid;
+import fl.controls.Label;
+import fl.data.DataProvider;
+import flash.accessibility.Accessibility;
+import flash.accessibility.AccessibilityProperties;
+import flash.system.Capabilities;
+
+DataGridAccImpl.enableAccessibility();
+
+createGrid();
+
+//set the summary text as accessible description
+var accProps: AccessibilityProperties = new AccessibilityProperties();
+accProps.description = "The first column shows the player's name," +
+  "the second and third column shows the player's gaming statistics." +
+  "the fourth column shows the player's year as FR (Freshman), JR (junior) or SO (Sophomore)." +
+  "The fifth column shows the player's home city and state";
+aDg.accessibilityProperties = accProps;
+if (Capabilities.hasAccessibility)
+Accessibility.updateProperties();
+
+function createGrid() {
+  
+  //create and add the components
+  var aDg: DataGrid = new DataGrid();
+  addChild(aDg);
+  aDg.move(50, 50);
+  bldRosterGrid(aDg);
+  
+  var aRoster: Array = new Array();
+  aRoster =[ {
+    Name: "Wilma Carter", Bats: "R", Throws: "R", Year: "So", Home: "Redlands, CA"
+  }, {
+    Name: "Sue Pennypacker", Bats: "L", Throws: "R", Year: "Fr", Home: "Athens, GA"
+  }, {
+    Name: "Jill Smithfield", Bats: "R", Throws: "L", Year: "Sr", Home: "Spokane, WA"
+  }, {
+    Name: "Betty Kay", Bats: "R", Throws: "R", Year: "Fr", Home: "Palo Alto, CA"
+  },];
+  aDg.dataProvider = new DataProvider(aRoster);
+  aDg.rowCount = aDg.length;
+}
+
+function bldRosterGrid(dg: DataGrid) {
+  dg.setSize(400, 300);
+  dg.columns =[ "Name", "Bats", "Throws", "Year", "Home"];
+  dg.columns[0].width = 120;
+  dg.columns[1].width = 50;
+  dg.columns[2].width = 50;
+  dg.columns[3].width = 40;
+  dg.columns[4].width = 120;
+};
+ +

For a demonstration, see the working version of Adding a summary to a DataGrid with ActionScript 3. The source of Adding a summary to a DataGrid with ActionScript 3 is available.

+ +
+

Tests

+

Procedure

+

If the Flash movie contains a DataGrid component, confirm that summary + text has been added to it through the corresponding accessible description + property.

+
+

Expected Results

+

The above is true.

+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH24.html b/techniques/flash/FLASH24.html new file mode 100644 index 0000000000..04e6f469c4 --- /dev/null +++ b/techniques/flash/FLASH24.html @@ -0,0 +1,89 @@ +Allowing the user to extend the default time limit

Allowing the user to extend the default time limit

ID: FLASH24

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to allow the user to extend the + default time limit by providing a mechanism to extend the time when + scripts provide functionality that has default time limits. In order + to allow the user to request a longer time limit, the script can provide + a form (for example) allowing the user to enter a larger time limit + or indicating that more time is needed.

+

Examples

+
+

Changing timeout with a dropdown list

+ +

This is a basic AS2 example where the timeout duration can be changed + by the user through a dropdown list. In this example there is a combobox + with the instance name sessionLimitDuration.

+ +
import mx.controls.Alert;
+import mx.accessibility.AlertAccImpl;
+import mx.accessibility.ComboBoxAccImpl;
+
+ComboBoxAccImpl.enableAccessibility();
+AlertAccImpl.enableAccessibility();
+
+var sessionTimeout;
+var sessionNotificationTimeout;
+var timeLimit: Number;
+var sessionAlert: Alert;
+
+adjustTimeoutDuration();
+// reset the timeout when interaction occurs
+testField.addEventListener("change", resetTimeout);
+
+//
+//update limit duration when the combobox value changes
+//
+sessionLimitDuration.addEventListener("change", adjustTimeoutDuration);
+
+function adjustTimeoutDuration(e) {
+  timeLimit = sessionLimitDuration.value * 1000;
+  resetTimeout();
+  timeoutDescription.text = "A session timeout will be simulated after " + 
+    sessionLimitDuration.selectedLabel + " without interaction in the form field below."
+}
+
+function resetTimeout() {
+  clearTimeout(sessionTimeout);
+  sessionTimeout = setTimeout(endSession, timeLimit);
+}
+
+function endSession() {
+  sessionAlert.deletePopUp();
+  Alert.show("please log in again",
+  "Your session has expired");
+}
+ +

For a demonstration, see the working + version of Changing timeout with a dropdown list. The source of Changing timeout with a dropdown list is available. Please note that the session times are + purposefully short for demonstration purposes, developers will + want to provide durations that are sufficient to meet the requirements + of Success + Criterion 2.2.1 (Timing Adjustable) .

+ + +
+

Tests

+

Procedure

+

For Flash content that include a time limit:

+
    +
  1. Check that there is a control to adjust the time limit near the + top of the page that allows the user to adjust the time to at least + ten times longer than the default.
  2. +
  3. Verify that the default time limit for the page is long enough + that a user can easily navigate to the control even if they are 10 + times slower than most users.
  4. +
+
+

Expected Results

+

The above is true

+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH25.html b/techniques/flash/FLASH25.html new file mode 100644 index 0000000000..c75e5887c7 --- /dev/null +++ b/techniques/flash/FLASH25.html @@ -0,0 +1,150 @@ +Labeling a form control by setting its accessible name

Labeling a form control by setting its accessible name

ID: FLASH25

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to provide an accessible name to + the built in form components provided by Flash. Some components, such + as radio buttons, checkboxes and buttons, have their own label property. + For other components, the developer needs to specify the component's + label text as accessible name. This can be either be achieved through + the Accessibility panel (for components placed on the stage during + authoring) or through scripting (for components that are dynamically + created at runtime).

+ +

ActionScript 2

+

In ActionScript 2 the accessible name needs to be set on a component's + _accProps property. This property must be an object. If the property + has not been set yet, the developer needs to create a custom object + and assign it to the _accProps property. The object itself can have + several accessibility related properties, one of them being _accProps.name, + which specifies the accessible name. When an _accProps property is + updated, the developer must call Accessibility.UpdateProperties() for + the changes to take effect. Before calling Accessibility.UpdateProperties(), + it is recommended to check the System.capabilities.hasAccessibility + flag. this will prevent an error on environments that do not support + MSAA.

+

ActionScript 2 provides the following accessible components:

+
    +
  • SimpleButton
  • +
  • CheckBox
  • +
  • RadioButton
  • +
  • Label
  • +
  • TextInput
  • +
  • TextArea
  • +
  • ComboBox
  • +
  • ListBox
  • +
  • Window
  • +
  • Alert
  • +
  • DataGrid
  • +
+ +

ActionScript 3

+

In ActionScript 3 the accessible name needs to be set on a component's + accessibilityProperties property. This property must be an instance + of flash.accessibility.AccessibilityProperties. If the property has + not been set yet, the developer needs to create the a new AccessibilityProperties + instance and assign it to the accessibilityProperties property. The + object itself can have several accessibility related properties, one + of them being accessibilityProperties.name which specifies the accessible + name. When an accessibilityProperties property is updated, the developer + must call flash.accessibility.Accessibility.UpdateProperties() for the + changes to take effect. Before calling Accessibility.UpdateProperties(), + it is recommended to check the flash.system.capabilities.hasAccessibility + flag. this will prevent an error on environments that do not support + MSAA.

+

ActionScript 3 provides the following accessible components.

+
    +
  • Button
  • +
  • CheckBox
  • +
  • ComboBox
  • +
  • List
  • +
  • RadioButton
  • +
  • TileList
  • +
+

Examples

+
+

Setting a component's accessible name using the Accessibility panel

+ +

To add and label a component control, follow these steps:

+
    +
  1. From the 'Components' panel, drag the component on to the stage, + or use scripting to create a new instance.
  2. +
  3. With the newly created component instance selected, enter its + label text in the Accessibility Panel's Name field.
  4. +
+ +
+
+

Setting the accessible name through ActionScript 2.0

+ +

The code example below shows how a ListBox component is created and assigned an accessible name.

+ +
mx.accessibility.ListAccImpl.enableAccessibility();
+
+this.createClassObject(mx.controls.List, "my_list", 1);
+my_list.addItem({label: "R. Davis", data: 1});
+my_list.addItem({label: "V. Mann", data: 2});
+my_list.addItem({label: "L. Heart", data: 3});
+my_list.addItem({label: "P. Hill", data: dt4});
+my_list.addItem({label: "D. Gribble", data: 5});
+my_list.move(10, 10);
+
+if (System.capabilities.hasAccessibility) {
+  my_list._accProps = new Object();
+  my_list._accProps.name = "Staff Members";
+  Accessibility.updateProperties();
+}
+ +

This result can be viewed in the working version of Setting the accessible name through ActionScript 2.0. The source of Setting the accessible name through ActionScript 2.0 is available.

+ +
+
+

Setting the accessible name through ActionScript 3.0

+ +

The code example below shows how a ListBox component is created and assigned an accessible name.

+ +
import fl.controls.List;
+import fl.accessibility.ListAccImpl;
+import flash.system.Capabilities;
+import flash.accessibility.*;
+
+ListAccImpl.enableAccessibility();
+var my_list:List = new List();
+my_list.addItem({label:"R. Davis", data:1});
+my_list.addItem({label:"V. Mann", data:2});
+my_list.addItem({label:"L. Heart", data:3});
+my_list.addItem({label:"P. Hill", data:4});
+my_list.addItem({label:"D. Gribble", data:5});
+my_list.x = my_list.y = 10;
+
+if (Capabilities.hasAccessibility) {
+  var accProps:AccessibilityProperties = new AccessibilityProperties();
+  accProps.name = "Staff Members";
+  my_list.accessibilityProperties = accProps;
+  Accessibility.updateProperties();
+}
+addChild(my_list);
+ +

This result can be viewed in the working version of Setting the accessible name through ActionScript 3.0. The source of Setting the accessible name through ActionScript 3.0 is available.

+ +
+

Tests

+

Procedure

+

For Flash movies that contain form components, confirm that either:

+
    +
  1. The selected component's label text is specified in the Accessibility + Panel's "name" field.
  2. +
  3. In ActionScript 2.0: Scripting is used to dynamically set the + component's _accProps.name property
  4. +
  5. In ActionScript 3.0: Scripting is used to dynamically set the + component's accessibilityProperties.name property
  6. +
+
+

Expected Results

+

One of the above is true

+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH26.html b/techniques/flash/FLASH26.html new file mode 100644 index 0000000000..3f89961887 --- /dev/null +++ b/techniques/flash/FLASH26.html @@ -0,0 +1,143 @@ +Applying audio descriptions to Flash video

Applying audio descriptions to Flash video

ID: FLASH26

Technology: flash

Type: Technique

When to Use

+
    +
  • Flash CS3 and higher
  • +
  • ActionScript 3.0 and higher
  • +
+

Description

+

The objective of this technique is to provide a way for people + who are blind or otherwise have trouble seeing the video in + audio-visual material to be able to access the material. With + this technique a description of the video is provided via audio + description that will fit into the gaps in the dialogue in + the audio-visual material.

+

Examples

+
+

Playing descriptions when cue points are reached

+ +

In this example, the FLVPlayback component is used to create + a video player. A custom class called "AudioDescriptions" is + added to manage the playback of extended audio descriptions. + This class provides event listeners to listen for cue points + in the media that have been identified by the audio description + provider. When these cuepoints are reached, an mp3 file containing + the corresponding description will start playing. The recorded + descriptions have been timed to fit with in the gaps in the + movie's dialog.

+

By default, audio descriptions will be enabled. A button (which + must itself be accessible to meet other success criteria) is + provided below the video player that allows the user to turn + audio descriptions on or off.

+ +
package {
+  import fl.video. *;
+  import flash.events. *;
+  import flash.media.Sound;
+  import flash.media.SoundChannel;
+  import flash.net.URLRequest;
+  import flash.display.Sprite;
+  
+  public class AudioDescriptions extends Sprite {
+    private var channel: SoundChannel = new SoundChannel;
+    private var myPlayer: FLVPlayback;
+    private var _enabled: Boolean = true;
+    private var _toggleBtn: Button;
+    private var snd: Sound = new Sound();
+    public function AudioDescriptions() {
+      // point myPlayer to the FLVPlayback component instance on the stage, 
+      // which should be loaded with a valid video source.
+      myPlayer = my_FLVPlybk;
+      // add cue points. When any of these are reached, the 
+      // MetadataEvent.CUE_POINT event will fire
+      myPlayer.addASCuePoint(8.35, "ASpt1");
+      myPlayer.addASCuePoint(23.23, "ASpt2");
+      
+      enable();
+      
+      enable_AD_btn.addEventListener(MouseEvent.CLICK, handleBtnClick);
+    }
+    
+    private function handleBtnClick(e) {
+      _enabled = ! _enabled;
+      if (! _enabled) {
+        disable();
+        enable_AD_btn.label = "Enable Audio Descriptions";
+      } else {
+        enable();
+        enable_AD_btn.label = "Disable Audio Descriptions";
+      }
+    }
+    
+    public function enable() {
+      // set up an event handler which will be called each time a cue point is reached
+      myPlayer.addEventListener(MetadataEvent.CUE_POINT, cp_listener);
+    }
+    
+    public function disable() {
+      // remove the event handler called each time a cue point is reached, so 
+      // that audio description is disabled.
+      myPlayer.removeEventListener(MetadataEvent.CUE_POINT, cp_listener);
+    }
+    
+    private function cp_listener(eventObject: MetadataEvent): void {
+      snd = new Sound();
+      //recreate sound object as it can only load one mp3 file
+      //check to see which cue point was reached
+      switch (eventObject.info.name) {
+        case "ASpt1":
+        snd.load(new URLRequest("sphere.mp3"));
+        //create a new Sound object, and load the appropriate mp3
+        channel = snd.play();
+        // play the audio description, and assign it to the SoundChannel object
+        break;
+        case "ASpt2":
+        snd.load(new URLRequest("transfrm.mp3"));
+        channel = snd.play();
+        break;
+      }
+    }
+  }
+}
+ +

The result can be viewed in the working version of Playing descriptions when cue points are reached. The source of Playing descriptions when cue points are reached is available.

+ +
+
+

Providing an additional audio track for descriptions

+ +

Audio description can also be provided via an additional audio + track that is the same length and plays simultaneously as the + primary media, but that only includes sound for the segments + when audio description needs to be played and silence at other + times. A Flash author can provide a toggle to turn this additional + audio track on or off, based on the listener's preference. + When the additional track is enabled, there are two parallel + audio tracks, one being the primary audio, and the second being + the one containing only audio description. It is still necessary + to ensure that the audio description and primary audio do not + overlap in ways that make comprehension difficult. This method + will achieve the same result as the method used in Example + 1, but may be chosen because of the type of audio description + files that are provided to the Flash author.

+ +
+

Tests

+

Procedure

+

When Flash content contains video with an audio soundtrack, + confirm that:

+
    +
  1. Audio descriptions have been made available using separate + sound files.
  2. +
  3. A button is provided that allows users to enable or disable + the audio descriptions
  4. +
+
+

Expected Results

+
    +
  • #1 and #2 are true
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH27.html b/techniques/flash/FLASH27.html new file mode 100644 index 0000000000..90a43e8ad3 --- /dev/null +++ b/techniques/flash/FLASH27.html @@ -0,0 +1,91 @@ +Providing button labels that describe the purpose of a button

Providing button labels that describe the purpose of a button

ID: FLASH27

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to describe the purpose + of a button by providing descriptive text as the button's accessible + name. The description lets a user distinguish this button from + other buttons in the Flash movie and helps the user determine + whether to activate the button. An empty string is not sufficient + as a button's accessible name.

+

For buttons with text labels, the label text will be used + as a buttons accessible name. If a button is image based and + does not have a text label, the button's accessible name will + have to be set separately using the Accessibility panel or + through scripting.

+

Examples

+
+

Using the label property to describe the button's purpose

+
import fl.controls.Button;
+import fl.accessibility.ButtonAccImpl;
+
+ButtonAccImpl.enableAccessibility();
+
+var myButton:Button = new Button();
+myButton.label = "View Items in Cart";
+
+
+
+

Using scripting to set the accessible name for an image button using Actionscript 3.0

+ +

In this example, the button's label property is deliberately set to an empty string. To be perceivable to assistive technology, the button's accessibilityProperties.name property is set.

+ +
import fl.controls.Button;
+import fl.accessibility.ButtonAccImpl;
+import flash.accessibility.*;
+import flash.system.Capabilities;
+ButtonAccImpl.enableAccessibility();
+
+var soundIsMuted = false;
+var myButton:Button = new Button();
+myButton.setStyle("icon", unmuted);
+myButton.label = "";
+myButton.x = myButton.y = 10;
+myButton.width = myButton.height = 50;
+updateAccName(myButton, "mute sound");
+myButton.setStyle("icon", unmuted);
+myButton.addEventListener(MouseEvent.CLICK, handleBtnClick);
+addChild(myButton);
+
+function handleBtnClick(e) {
+  soundIsMuted = !soundIsMuted;
+  myButton.setStyle("icon", soundIsMuted ? muted : unmuted);
+  updateAccName(myButton, soundIsMuted ? "unmute sound" : "mute sound");
+}
+
+function updateAccName(obj, newName:String) {
+  if (!obj.accessibilityProperties)
+    obj.accessibilityProperties = new AccessibilityProperties();
+  obj.accessibilityProperties.name = newName;
+  if (Capabilities.hasAccessibility)
+    Accessibility.updateProperties();
+}
+
+

Tests

+

Procedure

+

For each button in the Flash movie that uses this technique:

+
    +
  1. Check that the button's label text correctly describes + the button's purpose
  2. +
  3. If a button does not have a text label, confirm that descriptive + text has been added as the button's accessible name.
  4. +
  5. If a button contains both label text and an accessible + name, confirm that the combination of the two makes sense + as a description for the button's purpose.
  6. +
+
+

Expected Results

+
    +
  • Checks #1, #2, and #3 are true.
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH28.html b/techniques/flash/FLASH28.html new file mode 100644 index 0000000000..e290e1a540 --- /dev/null +++ b/techniques/flash/FLASH28.html @@ -0,0 +1,89 @@ +Providing text alternatives for ASCII art, emoticons, and leetspeak in Flash

Providing text alternatives for ASCII art, emoticons, and leetspeak in Flash

ID: FLASH28

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

ASCII characters, emoticons, and leetspeek are sometimes used + and present accessibility challenges since the meaning is conveyed + through the visual appearance of groupings of individual characters.

+

In Flash, such groupings of characters can be made accessible + by wrapping them in a MovieClip, and providing an accessible + name. It is crucial that the forceSimple property for the + MovieClip is set to true also. This will hide the actual ASCII + characters from assistive technology.

+

Examples

+
+

Providing a text alternative for ASCII art in the Accessibility control panel

+ +

This example contains words written in ASCII art using leetspeek + (the text says "WCAG 2 rulez"). To make this text + accessible, the following steps are followed:

+
    +
  1. Place the ASCII characters in a MovieClip instance
  2. +
  3. +

    Select the MovieClip instance containing the text, and + make the following changes in the Accessibility panel:

    +
      +
    • Add a meaningful text alternative for the ASCII art, + without leetspeak (such as "WCAG 2 RULEZ").
    • +
    • Uncheck the "Make child objects accessible" checkbox, + so that the ASCII characters will not be read by screen + readers
    • +
    +
  4. +
+

These steps are ilustrated in the screenshot below:

+
+ + +
Adding text alternative for ASCII art using the Accessibility panel
+ +
+ +
+
+

Providing a text alternative for ASCII art using ActionScript

+ +

This example is the same as example 1, except using ActionScript + instead of the Accessibility control panel in the Flash Professional + authoring tool.

+
    +
  1. Place the ASCII characters in a MovieClip instance
  2. +
  3. Provide an instance name for the MovieClip instance (e.g. myASCII)
  4. +
  5. Set the accessible name for the MovieClip and set the + forceSimple property to true to hide the text inside the + MovieClip.
  6. +
+ +
// 'myASCII' is a MovieClip instance placed on the movie's main timeline
+myASCII.accessibilityProperties = new AccessibilityProperties();
+myASCII.accessibilityProperties.name = "WCAG 2 Rulez";
+myASCII.accessibilityProperties.forceSimple = true;
+
+ +

This technique is demonstrated in the working version of Providing a text alternative for ASCII art using ActionScript. The source of Providing a text alternative for ASCII art using ActionScript is available.

+ +
+

Tests

+

Procedure

+
    +
  1. Publish the SWF file
  2. +
  3. Use a tool which is capable of showing an object's name + to open the Flash movie.
  4. +
  5. Locate the ASCII grouping, leet speak, or emoticon and + verify in the tool that the accessibility name represents + the same information.
  6. +
  7. Authors may also test with a screen reader, by reading + the Flash content and listening to hear that the equivalent + text is read when tabbing to the non-text object (if it is + tabbable) or hearing the alternative text read when reading + the content line-by-line.
  8. +
+
+

Expected Results

+
    +
  • #3 or #4 above is true
  • +
+
+
diff --git a/techniques/flash/FLASH29.html b/techniques/flash/FLASH29.html new file mode 100644 index 0000000000..aaa8841ae4 --- /dev/null +++ b/techniques/flash/FLASH29.html @@ -0,0 +1,122 @@ +Setting the label property for form components

Setting the label property for form components

ID: FLASH29

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to explicitly associate a form + component with its label text by setting the component's label property. + Setting this property will visually place a label next to the component, + and exposes the label text to assistive technology.

+

Components that support the label property are:

+ +

For other components, the label text has to placed adjacent to the + form component manually. For these components, the label text can be + associated with the form component using one of these approaches:

+
    +
  • + +
  • +
  • + +
  • +
+

Examples

+

In order for these form controls to be accessible to assistive + technology, the following lines of code will have to be added once + to the movie's script:

+

When the Button component is used:

+

+ import fl.accessibility.ButtonAccImpl; +ButtonAccImpl.enableAccessibility(); +

+

When the RadioButton component is used:

+

+ import fl.accessibility.RadioButtonAccImpl; +RadioButtonAccImpl.enableAccessibility(); +

+

When the CheckBox component is used:

+

+ import fl.accessibility.CheckBoxAccImpl; +CheckBoxAccImpl.enableAccessibility(); +

+
+

Setting the label using the Component Inspector panel

+ +
    +
  1. Add the Button, CheckBox or RadioButton component to the movie + by dragging it on the stage from the 'Components' panel.
  2. +
  3. With the component selected, open the 'Component Inspector' panel + by selecting it in the 'Window' menu or using the Shift + F7 shortcut.
  4. +
  5. In the Component Inspector, under the 'Parameters' tab, enter + the label text for the 'label' parameter.
  6. +
+

The screenshot below illustrates this technique.

+
+ + +
Setting a component's label in the Component Inspector Panel
+ +
+ +
+
+

Setting the label on a Button, CheckBox and RadioButton component using ActionScript 3.0

+
import fl.accessibility.ButtonAccImpl
+import fl.accessibility.CheckBoxAccImpl
+import fl.accessibility.RadioButtonAccImpl
+import fl.controls.Button;
+import fl.controls.CheckBox;
+import fl.controls.RadioButton;
+
+ButtonAccImpl.enableAccessibility();
+var myButton: Button = new Button();
+myButton.label = "Submit Details";
+myButton.x = 10;
+myButton.y = 10
+addChild(myButton);
+
+CheckBoxAccImpl.enableAccessibility();
+var myCheckBox: CheckBox = new CheckBox();
+myCheckBox.label = "notify me";
+myCheckBox.x = 10;
+myCheckBox.y = 40
+addChild(myCheckBox);
+
+RadioButtonAccImpl.enableAccessibility();
+var myRadioButton: RadioButton = new RadioButton();
+myRadioButton.label = "Male";
+myRadioButton.x = 10;
+myRadioButton.y = 60;
+addChild(myRadioButton);
+ +

This technique is demonstrated in the working example of Setting the label on a Button, CheckBox and RadioButton component using ActionScript 3.0. The source of Setting the label on a Button, CheckBox and RadioButton component using ActionScript 3.0 is available.

+ +
+

Tests

+

Procedure

+

When the Button, CheckBox or RadioButton components are used:

+
    +
  1. confirm that labels describing the purpose of the button have + been provided through the component's label property.
  2. +
+
+

Expected Results

+
    +
  1. #1 is true
  2. +
+
+
diff --git a/techniques/flash/FLASH3.html b/techniques/flash/FLASH3.html new file mode 100644 index 0000000000..4d29cfff38 --- /dev/null +++ b/techniques/flash/FLASH3.html @@ -0,0 +1,58 @@ +Marking objects in Flash so that they can be ignored by AT

Marking objects in Flash so that they can be ignored by AT

ID: FLASH3

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The purpose of this technique is to show how images can be marked so that they can be ignored by Assistive Technology.

+

The Flash Player supports the ability for authors to control which graphics appear to assistive technologies using the silent property of the accessibility object, as indicated in the examples below.

+

Examples

+
+

Hiding a graphic in the Flash Professional authoring tool

+ +

The Flash Professional authoring tool's Accessibility panel lets authors provide accessibility information to assistive technology and set accessibility options for individual Flash objects or entire Flash applications.

+
    +
  1. To apply changes to accessibility properties for a graphic, it must be saved as a symbol in the movie's library. Note: Flash does not support text alternatives for graphic symbols. Instead, the graphic must be converted to or stored in a movie clip or button symbol.
  2. +
  3. Bring up the Accessibility panel by selecting "Window > Other Panels > Accessibility" in the application menu, or through the shortcut ALT + F11.
  4. +
  5. Select the graphic object
  6. +
  7. If the 'Make object accessible' checkbox in the Accessibility control panel is checked, uncheck this option to remove the graphic from the accessiblity information conveyed to assistive technologies.
  8. +
+ +
+
+

Applying textual alternatives programmatically in ActionScript 2.0

+ +

To manage an object's text equivalents programmatically using ActionScript, the _accProps property must be used. This references an object containing accessibility related properties set for the object. The code example below shows a simple example of how the _accProps property is used to remove an object from the accessibility information for the movie using ActionScript.

+ +
// 'decorative_mc' is an instance placed on the movie's main timeline
+_root.decorative_mc._accProps = new Object();
+_root.decorative_mc._accProps.silent = true; 
+
+

Tests

+

Procedure

+
    +
  1. Publish the SWF file
  2. +
  3. Open the SWF file in Internet Explorer 6 or higher (using Flash Player 6 or higher), or Firefox 3 or higher (using Flash Player 9 or higher)
  4. +
  5. Use a tool which is capable of showing an object's accessibility information, such as ACTF aDesigner 1.0 to open the Flash movie.
  6. +
  7. In the GUI summary panel, loop over each object which is contained by the Flash movie and ensure the object that was designed to be hidden does not appear in the tool's display.
  8. +
  9. Authors may also test with a screen reader, by reading the Flash content and listening to hear that object is not mentioned when the page is read.
  10. +
  11. Non-text objects that are coded to be hidden from assistive technologies are not available to assistive technology.
  12. +
+
+

Expected Results

+

Check #6 is true.

+
+

Resources

+ + + +
\ No newline at end of file diff --git a/techniques/flash/FLASH30.html b/techniques/flash/FLASH30.html new file mode 100644 index 0000000000..99173fbdcb --- /dev/null +++ b/techniques/flash/FLASH30.html @@ -0,0 +1,91 @@ +Specifying accessible names for image buttons

Specifying accessible names for image buttons

ID: FLASH30

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

For image based Button components the accessible name needs to be + set to provide a functional label. This label indicates the button's + function, but does not attempt to describe the image. The label is + especially important if there are multiple buttons on the page that + each lead to different results.

+

The accessible name for a button may need to be updated if the button + changes during the use of the Flash movie.

+

Examples

+
+

Accessible name for a simple image button

+ +

In this example, an icon based button is given an accessible name + through scripting. When the button is clicked a web page is opened.

+ +
//provide text equivalent for image button
+this.check_btn.accessibilityProperties = new AccessibilityProperties();
+this.check_btn.accessibilityProperties.name = "Check page validation";
+
+//set up event listener and function to navigate to URL
+
+this.check_btn.addEventListener(MouseEvent.CLICK, onClickHandler);
+
+function onClickHandler(e: MouseEvent): void {
+  var btn = e.target;
+  var url: String = "http://validator.w3.org";
+  var request: URLRequest = new URLRequest(url);
+  navigateToURL(request, '_blank');
+}
+ +

The result is demonstrated in the working version of Accessible name for a simple image button. The source of Accessible name for a simple image button is available.

+ +
+
+

Accessible name for a dynamic image button

+ +
import fl.controls.Button;
+import fl.accessibility.ButtonAccImpl;
+
+ButtonAccImpl.enableAccessibility();
+
+var soundIsMuted = false;
+var myButton: Button = new Button();
+myButton.label = "";
+myButton.x = myButton.y = 10;
+myButton.width = myButton.height = 50;
+updateAccName(myButton, "mute sound");
+myButton.setStyle("icon", unmuted);
+myButton.addEventListener(MouseEvent.CLICK, handleBtnClick);
+addChild(myButton);
+
+function handleBtnClick(e) {
+  soundIsMuted = ! soundIsMuted;
+  myButton.setStyle("icon", soundIsMuted? muted: unmuted);
+  updateAccName(myButton, soundIsMuted? "unmute sound": "mute sound");
+}
+
+function updateAccName(obj, newName: String) {
+  if (! obj.accessibilityProperties)
+  obj.accessibilityProperties = new AccessibilityProperties();
+  obj.accessibilityProperties.name = newName;
+  if (Capabilities.hasAccessibility)
+  Accessibility.updateProperties();
+}
+ +

The result is demonstrated in the working version of Accessible name for a dynamic image button. The source of Accessible name for a dynamic image button is available.

+ +
+

Tests

+

Procedure

+

When a Flash Movie contains image based buttons, confirm that:

+
    +
  1. An accessible name is provided for the button that describes the + button's action
  2. +
  3. If the button's action changes (for example when it is clicked) + the accessible name changes correspondingly
  4. +
+
+

Expected Results

+
    +
  • #1 and #2 are true
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH31.html b/techniques/flash/FLASH31.html new file mode 100644 index 0000000000..8de5e70d97 --- /dev/null +++ b/techniques/flash/FLASH31.html @@ -0,0 +1,136 @@ +Specifying caption text for a DataGrid

Specifying caption text for a DataGrid

ID: FLASH31

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to programmatically associate captions + for DataGrids where captions are provided in the presentation. Normally, + the caption for a table is a table identifier and acts like a title + or heading for the table.

+

Flash does not have a caption element for the DataGrid component, + but the same effect can be achieved through the following approach:

+
    +
  1. Place a label component or textfield above the DataGrid, containing + the grid's caption text.
  2. +
  3. Duplicate the caption text and add it as the grid's accessible + name. This can either be achieved by setting a value to the grid's "name" field + in the Accessibility panel or by setting the grid's AccessibilityProperties.name + property.
  4. +
+

Examples

+
+

Associating a label with a DataGrid

+ +

This is an example of a DataGrid being added to the stage in Flash + Professional from the Components panel. A label element is also added + from the Components panel to contain the caption text and the caption + text is used in the Accessibility control panel in Flash to serve as + the accessibility name for the DataGrid.

+
    +
  • Create a new Flash file (.fla) or open an existing one to put + a DataGrid into.
  • +
  • Open the Flash components panel from the Window menu
  • +
  • Drag a DataGrid component onto the stage and position as desired.
  • +
  • Drag a label component onto the stage and position as desired.
  • +
  • Add text to the label component.
  • +
  • Select the DataGrid component and add the same text as is used + in the label component to the name field for DataGrid, using the + Accessibility control panel.
  • +
+ +
+
+

Associating a caption with a DataGrid using ActiveScript 3

+ +

This is a basic AS3 example of a DataGrid generated through scripting. + Additionally a label element is created, containing the caption text, + and the caption text is added to the grid as an accessible name.

+ +
import fl.accessibility.DataGridAccImpl;
+import fl.controls.DataGrid;
+import fl.controls.Label;
+import fl.data.DataProvider;
+import flash.accessibility.Accessibility;
+import flash.accessibility.AccessibilityProperties;
+import flash.system.Capabilities;
+
+// enable accessibility for the DataGrid
+DataGridAccImpl.enableAccessibility();
+
+createGrid();
+
+// set the data grid caption text
+var gridCaptionText: String = "Game Results";
+gridCaption.text = gridCaptionText;
+//add the caption text as the DataGrid's accessible name
+var accProps: AccessibilityProperties = new AccessibilityProperties();
+accProps.name = gridCaptionText;
+aDg.accessibilityProperties = accProps;
+if (Capabilities.hasAccessibility)
+Accessibility.updateProperties();
+
+function createGrid() {
+  
+  //create and add the components
+  var aDg: DataGrid = new DataGrid();
+  var gridCaption: Label = new Label();
+  addChild(aDg);
+  addChild(gridCaption);
+  aDg.move(50, 50);
+  gridCaption.move(50, 20);
+  
+  var captionFormat: TextFormat = new TextFormat();
+  captionFormat.size = 24;
+  gridCaption.setStyle("textFormat", captionFormat);
+  gridCaption.width = 300;
+  gridCaption.height = 100;
+  bldRosterGrid(aDg);
+  //prepare the data
+  var aRoster: Array = new Array();
+  aRoster =[ 
+    {Name: "Wilma Carter", Bats: "R", Throws: "R", Year: "So", Home: "Redlands, CA"},
+    {Name: "Sylvia Munson", Bats: "R", Throws: "R", Year: "Jr", Home: "Pasadena, CA"}, 
+    {Name: "Carla Gomez", Bats: "R", Throws: "L", Year: "Sr", Home: "Corona, CA"}, 
+    {Name: "Betty Kay", Bats: "R", Throws: "R", Year: "Fr", Home: "Palo Alto, CA"},
+  ];
+  aDg.dataProvider = new DataProvider(aRoster);
+  aDg.rowCount = aDg.length;
+};
+
+function bldRosterGrid(dg: DataGrid) {
+  dg.setSize(400, 300);
+  dg.columns =[ "Name", "Bats", "Throws", "Year", "Home"];
+  dg.columns[0].width = 120;
+  dg.columns[1].width = 50;
+  dg.columns[2].width = 50;
+  dg.columns[3].width = 40;
+  dg.columns[4].width = 120;
+};
+ +

Notes on this code sample:

+ + +
+

Tests

+

Procedure

+
    +
  1. Check whether the Flash movie contains a DataGrid component.
  2. +
  3. Confirm that each DataGrid's caption text has been added to the component as an accessible name.
  4. +
+
+

Expected Results

+

Step 2 is true.

+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH32.html b/techniques/flash/FLASH32.html new file mode 100644 index 0000000000..a4503ab68e --- /dev/null +++ b/techniques/flash/FLASH32.html @@ -0,0 +1,86 @@ +Using auto labeling to associate text labels with form controls

Using auto labeling to associate text labels with form controls

ID: FLASH32

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

Except for the CheckBox and RadioButton component, the built in Flash + components are not automatically provided an associated label. For + these components, label text has to be placed adjacent to their control + manually, using the Label component. If the 'auto-label' feature is + enabled in the Accessibility panel, then the Flash Player will automatically + associate the label text for the TextInput and TextArea components. + This means that for these components, it is not necessary to duplicate + the label text for the control using the Accessibility panel. The auto + label feature is enabled by default.

+

Additionally, the auto label feature will enable the Flash Player + to automatically add text contained by Button symbols as the symbol's + accessible name. This will only work if the Button symbol only consists + of one layer, containing the text label.

+
+

Since auto-labeling associates labels without human intervention + the accuracy of the association should be verified. For more predictable + results authors are encouraged to explicitly add labels to all controls.

+
+

To auto labeling, perform the following steps:

+
    +
  1. Ensure that the textual descriptions for each form control within + the flash application are placed adjacent to the control itself. Text + eligible to be used for auto-labeling must not be set to be hidden + from assistive technology.
  2. +
  3. Select the movie stage, and open the Accessibility panel.
  4. +
  5. Ensure that the 'Auto Label' option is checked. This will automatically + associate labels with their TextInput and TextArea controls, and + add text inside custom button symbols as their accessible name.
  6. +
  7. If the auto label behavior is inappropriate to your Flash content, + uncheck the 'Auto label' option, and ensure that each control receives + a meaningful 'name' value in the Accessibility panel.
  8. +
  9. To disable auto labeling for a particular object but not the whole + movie, convert the text to the 'dynamic text' type using the 'Property + inspector'. Then select it, and uncheck its 'Make object accessible' + option in the Accessibility panel.
  10. +
+
+

As an alternative to using the Accessibility panel, the auto + label feature can also be turned off by setting the AccessibilityProperties.noAutoLabel + to true for the stage object.

+
+

Examples

+
+

Using the "Auto Label" option in the Accessibility panel

+ +

This example shows two TextInput components, a TextArea component + and a custom button symbol instance. For the TextInput components, + a separate label element has been placed to the left of the control. + For the TextArea component, the label has been placed above the control. + For the custom button, the label text is placed inside the button symbol. + Because the "Auto Label" option is enabled in the Accessibility + panel, all these controls will be provided an accessible name based + on their label.

+

The screenshot below illustrates the example:

+
+ +
Using the Auto Label feature in the Flash Authoring Environment
+
+

The results of this technique can be viewed in the working version of Using the "Auto Label" option in the Accessibility panel. The source of Using the "Auto Label" option in the Accessibility panel is available.

+ +
+

Tests

+

Procedure

+

If a Flash form contains TextInput or TextArea components, or custom + button symbols with text labels, confirm that:

+
    +
  1. The Auto Label option is enabled in the movie's Accessibility + panel
  2. +
  3. Use a screen reader or MSAA checker to ensure that the label text + is indeed exposed as the control's accessible name
  4. +
+
+

Expected Results

+
    +
  • #1 and #2 are true
  • +
+
+
diff --git a/techniques/flash/FLASH33.html b/techniques/flash/FLASH33.html new file mode 100644 index 0000000000..a719779174 --- /dev/null +++ b/techniques/flash/FLASH33.html @@ -0,0 +1,84 @@ +Using relative values for Flash object dimensions

Using relative values for Flash object dimensions

ID: FLASH33

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to specify the width and/or height + of an embedded Flash object using relative units such as em values. + The size of the Flash object is allowed to expand to fill the size + of its container (a parent element) by setting the movie width and + height to 100%. The container's width and height is set with relative + units. This will allow user agents that support text resizing to resize + the Flash object in line with changes in text size settings. When the + Flash object's dimensions are adjusted its contents will be scaled, + making it easier to read for low vision users.

+
+

This technique is not necessary to support users who use zoom + functionality in their browsers.

+
+

Examples

+
+

Scaling text while keeping a minimum size

+ +

In this example, a Flash object is loaded into an HTML document using SWFObject's + dynamic publishing method. The Flash object's container element + is given a class name of "flashPlaceHolder". This class + name is then targeted using CSS to set its width and height using + relative em values. When the user increases or decreases the browser's + text size, the Flash object will scale accordingly. To ensure that + the object does not become too small when text size is decreased, + the min-width and min-height properties are set to the default dimensions.

+ +
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
+  "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
+    <title>Flash Resize example</title>
+    <script src="swfobject/swfobject.js" type="text/javascript"/>
+    <script type="text/javascript">
+    swfobject.embedSWF("scale_movie_dimensions_on_text_resize_as3.swf", 
+    "flashPlaceHolder", "100%", "100%", "8")      
+</script>
+
+    <style type="text/css">
+  #flashPlaceHolder {
+    width: 20em;
+    height: 15em;
+    min-width: 320px;
+    min-height: 240px;
+  }
+</style>
+  </head>
+  <body id="header">
+    <h1>Flash Resize Demonstration</h1>
+    <p>When the browser's text size is changed, the Flash movie will be
+      resized accordingly.</p>
+    <p id="flashPlaceHolder">Flash needs to be installed for this
+      example to work</p>
+  </body>
+</html>
+
+ +

The result of this technique can be viewed in the working version of Scaling text while keeping a minimum size. The source of Scaling text while keeping a minimum size is available.

+ + +
+

Tests

+

Procedure

+
    +
  1. Open a web page containing an embedded flash object
  2. +
  3. View the HTML to confirm that the width and height dimensions + for the object containing the Flash object are specified using relative + units such as em or percent (%).
  4. +
+
+

Expected Results

+
    +
  • Check #2 is true.
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH34.html b/techniques/flash/FLASH34.html new file mode 100644 index 0000000000..147a5b57f4 --- /dev/null +++ b/techniques/flash/FLASH34.html @@ -0,0 +1,125 @@ +Turning off sounds that play automatically when an assistive technology is detected

Turning off sounds that play automatically when an assistive technology is detected

ID: FLASH34

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The intent of this technique is to prevent sounds from playing when + the Flash movie loads. This is useful for those who utilize assistive + technologies (such as screen readers, screen magnifiers, switch mechanisms, + etc.) and those who may not (such as those with cognitive, learning + and language disabilities). By default, the sound will be played automatically. + When a screen reader such as JAWS is detected however, the sound will + have to be started manually.

+

To perform screen reader detection, Flash provides the flash.accessibility.Accessibility.active + property. If this property is set to true, it means that the Flash + player has detected running assistive technology. Based on this flag, + the Flash developer can choose to run different functionality.

+
+

The Flash Player requires some time to detect active assistive + technology and set the Accessibility.active property. To get accurate + results, do not check for this property immediately on the first frame + of the movie. Instead, perform the check 5 frames in or based on a + timed event.

+

Not every screen reader will be detected using this mechanism. + In general, the property will be set to true when any MSAA client + is running.

+

Other assistive technology tools, including screen magnifiers, + or tools not used as assistive technologies may also utilize MSAA in + ways that result in Accessibility.active being set to true.

+
+

Examples

+
+

A SoundHandler class

+ +

A class called SoundHandler is created which automatically starts + playing an MP3 file only when Accessibility.active is set to false. + Note that this example also checks the flash.system.Capabilities.hasAccessibility + property. This property does not check whether a screen reader is running, + but instead indicates whether the Flash Player is running in an environment + that supports MSAA (which basically means the Windows operating system).

+ +
package wcagSamples {
+  import flash.accessibility.Accessibility;
+  import flash.display.Sprite;
+  import flash.net.URLRequest;
+  import flash.media.Sound;
+  import flash.media.SoundChannel;
+  import flash.system.Capabilities;
+  import fl.controls.Button;
+  import fl.accessibility.ButtonAccImpl;
+  import fl.controls.Label;
+  import flash.events.MouseEvent;
+  
+  public class SoundHandler extends Sprite {
+    private var snd: Sound = new Sound();
+    private var button: Button = new Button();
+    private var req: URLRequest = new URLRequest(
+      "http://av.adobe.com/podcast/csbu_dev_podcast_epi_2.mp3");
+    private var channel: SoundChannel = new SoundChannel();
+    private var statusLbl: Label = new Label();
+    public function SoundHandler() {
+      snd.load(req);
+      ButtonAccImpl.enableAccessibility();
+      button.x = 10;
+      button.y = 10;
+      statusLbl.autoSize = "left";
+      statusLbl.x = 10;
+      statusLbl.y = 40;
+      addChild(statusLbl);
+      button.addEventListener(MouseEvent.CLICK, clickHandler);
+      this.addChild(button);
+      if (! Capabilities.hasAccessibility || ! Accessibility.active) {
+        channel = snd.play();
+        button.label = "Stop Sound";
+        statusLbl.text = "No Assistive technology detected. \
+          Sound will play automatically";
+      } else {
+        button.label = "Start Sound";
+        statusLbl.text = "Assistive technology detected. \
+          Sound will not play automatically";
+      }
+    }
+    private function clickHandler(e: MouseEvent): void {
+      if (button.label == "Stop Sound") {
+        button.label = "Start Sound";
+        channel.stop();
+      } else {
+        channel = snd.play();
+        button.label = "Stop Sound";
+      }
+    }
+  }
+}
+ +

This technique can be viewed in the working version of A SoundHandler class. The source of A SoundHandler class is available.

+ +
+

Tests

+

Procedure

+
    +
  1. Start a screen reader that supports MSAA.
  2. +
  3. Open a page containing a Flash movie that starts playing audio + automatically when a screen reader is not running
  4. +
  5. Confirm that the audio is stopped.
  6. +
+
+

Expected Results

+
    +
  1. #3 is true
  2. +
+
+

Resources

+ + + +
\ No newline at end of file diff --git a/techniques/flash/FLASH35.html b/techniques/flash/FLASH35.html new file mode 100644 index 0000000000..5c0facdd01 --- /dev/null +++ b/techniques/flash/FLASH35.html @@ -0,0 +1,98 @@ +Using script to scroll Flash content, and providing a mechanism to pause it

Using script to scroll Flash content, and providing a mechanism to pause it

ID: FLASH35

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to provide a way for users to stop + scrolling content when the scrolling is created by a script. Scrolling + content can be difficult or impossible to read by users with low vision + or with cognitive disabilities. The movement can also be distracting + for some people making it difficult for them to concentrate on other + parts of the Web page.

+

Examples

+
+

A toggle button to pause and resume scrolling

+ +

In this example, text scrolls from left to right. A toggle button + is provided that allows the user to pause and resume the scrolling + behavior. Additionally, a checkbox is provided which can be used to + slow down the scrolling speed.

+
+

Users may prefer a greater variety of scrolling speed options + than are offered in this example. Developers might choose to provide + several speed choices with a slider or drop down list control in order + to accomplish this.

+
+ +
import fl.accessibility.ButtonAccImpl;
+import fl.accessibility.CheckBoxAccImpl;
+
+ButtonAccImpl.enableAccessibility();
+CheckBoxAccImpl.enableAccessibility();
+
+var scrollInterval: int;
+var intervalLength: int = 15;
+
+var expandedViewer: MovieClip = exampleScroller.expandedViewer;
+var scrollText: MovieClip = exampleScroller.scrollText;
+var scrollViewer: MovieClip = exampleScroller.scrollViewer;
+
+var scrollingPaused: Boolean = true;
+
+scrollStopper.addEventListener(MouseEvent.CLICK, handleBtnClick, false);
+slowDown_chk.addEventListener(MouseEvent.CLICK, handleChkClick, false);
+
+function handleBtnClick(e) {
+  toggleScroll(false);
+  e.target.label = scrollingPaused? "Resume Scrolling": "Stop Scrolling";
+}
+
+//slow down scrolling speed
+function handleChkClick(e) {
+  intervalLength = e.target.selected? 50: 15;
+  if (! scrollingPaused) {
+    clearTimeout(scrollInterval);
+    toggleScroll(true);
+  }
+}
+
+//pause or resume scrolling
+function toggleScroll(noToggle: Boolean) {
+  if (noToggle || scrollingPaused)
+  scrollInterval = setInterval(moveText, intervalLength); else
+  clearTimeout(scrollInterval);
+  if (! noToggle)
+  scrollingPaused = ! scrollingPaused;
+}
+
+function moveText() {
+  if (scrollText.x + scrollText.width < scrollViewer.x)
+  scrollText.x = scrollViewer.x + scrollViewer.width;
+  scrollText.x -= 1;
+}
+
+//initiate scrolling
+toggleScroll(false);
+
+ +

The technique is demonstrated in the working version of A toggle button to pause and resume scrolling. The source of A toggle button to pause and resume scrolling is available.

+ +
+

Tests

+

Procedure

+

When a Flash Movie contains scrolling content:

+
    +
  1. Confirm that a button is provided that allows users to pause and resume the scrolling behavior
  2. +
  3. Confirm that pressing the button stops the scrolling
  4. +
  5. Confirm that pressing the button again restarts the scrolling
  6. +
+
+

Expected Results

+
    +
  • Checks #1, #2, and #3 are true.
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH36.html b/techniques/flash/FLASH36.html new file mode 100644 index 0000000000..d29af992b7 --- /dev/null +++ b/techniques/flash/FLASH36.html @@ -0,0 +1,42 @@ +Using scripts to control blinking and stop it in five seconds or less

Using scripts to control blinking and stop it in five seconds or less

ID: FLASH36

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to control blinking with script + so it can be set to stop in less than five seconds by the script. The + ActionScript setTimeout() method is used to stop the MovieClip's blinking + behavior in less than 5 seconds.

+

Examples

+
+

Stopping blinking after a timeout

+ +

In this example a MovieClip (blinkingTextMC) uses its timeline to + generate a blinking effect. Before 5 seconds has passed, the MovieClip's + gotoAndStop() method is called, which stops the blinking effect.

+ +
setTimeout(stopBlinking, 4500);
+function stopBlinking() {
+  var blinkingTextMC = getChildByName('blinkingTextMC');
+  blinkingTextMC.gotoAndStop(1);
+}
+
+ +

For a demonstration, view the working version of Stopping blinking after a timeout. The source of Stopping blinking after a timeout is available.

+ +
+

Tests

+

Procedure

+

For each instance of blinking content:

+
    +
  1. Start a timer for 5 seconds at the start of the blink effect.
  2. +
  3. When the timer expires, determine if the blinking has stopped.
  4. +
+
+

Expected Results

+
    +
  • For each instance of blinking content, #2 is true.
  • +
+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH4.html b/techniques/flash/FLASH4.html new file mode 100644 index 0000000000..75288a3132 --- /dev/null +++ b/techniques/flash/FLASH4.html @@ -0,0 +1,49 @@ +Providing submit buttons in Flash

Providing submit buttons in Flash

ID: FLASH4

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to use submit buttons to allow users to take actions that cause changes of context rather than allowing changes in context to occur when the value or state of a non-submit button control is modified. The intended use of a submit button in this technique is to generate an HTTP request that submits data entered in a form or to perform an action that triggers a change in context, so it is an appropriate control to use to initiate this change.

+

Examples

+
+

ActionScript 3 combobox with submit button

+ +

This is a basic ActionScript 3 example of a combobox component with a submit button to redirect the user to a different resource.

+ +
import fl.accessibility.ComboBoxAccImpl;
+import flash.net.navigateToURL;
+import flash.net.URLRequest;
+ComboBoxAccImpl.enableAccessibility();
+state_submit.addEventListener(MouseEvent.CLICK, submitHandler);
+function submitHandler(e) {
+  var url: URLRequest = new URLRequest("http://www.wikipedia.org/wiki/" + 
+    state_combo.selectedLabel);
+  navigateToURL(url, "_self");
+}
+
+
+

ActionScript 2 combobox with submit button

+ +

This is a basic ActionScript 2 example of a combobox component with a submit button to redirect the user to a different resource - the same example as in example 1 except in ActionScript 2:

+ +
import fl.accessibility.ComboBoxAccImpl;
+ComboBoxAccImpl.enableAccessibility();
+state_submit.addEventListener("click", submitHandler);
+function submitHandler(e) {
+  getURL("http://www.wikipedia.org/wiki/" + state_combo.selectedLabel, "_self");
+}
+
+

Tests

+

Procedure

+
    +
  1. Find all interactive control instances (that are not submit buttons) in the flash movie that can initiate a change of context, e.g. a combobox, radio button or checkbox.
  2. +
  3. For each instance, confirm that the event handler(s) responsible for the change of context are not associated with the controls themselves, but with a separate button instead.
  4. +
+
+

Expected Results

+

#2 is true

+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH5.html b/techniques/flash/FLASH5.html new file mode 100644 index 0000000000..9db89a95e4 --- /dev/null +++ b/techniques/flash/FLASH5.html @@ -0,0 +1,67 @@ +Combining adjacent image and text buttons for the same resource

Combining adjacent image and text buttons for the same resource

ID: FLASH5

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to avoid unnecessary duplication that occurs when adjacent text and iconic versions of a button are contained in a Flash movie.

+

Many kinds of buttons have both a text and iconic button adjacent to each other. Often the text and the icon button are rendered in separate buttons, in part to create a slight visual separation from each other. Although the sighted user can see this slight visual separation, a blind or low vision user may not be able to recognize the separation, and be confused by the redundant buttons. To avoid this, some authors omit specifying the accessible name for the image, but this would fail Success Criterion 1.1.1 because the text alternative would not serve the same purpose as the graphical button. The preferred method to address this is to put the text and image together in one button symbol instance, and provide a single accessible name for the button to eliminate duplication of text.

+

Examples

+

The following examples are for a situation where a button instance comprised of both an image and text is on the stage. The combined button in this example uses the instance name 'flashLink1'.

+

To create the combined button in Flash Professional:

+
    +
  1. Add a graphic object and text to the stage
  2. +
  3. Select both objects
  4. +
  5. Select 'New Symbol' from the Insert menu or hit Ctrl+F8 to create a new button object
  6. +
  7. Click on the button object on the stage and enter an instance name in the Properties panel.
  8. +
  9. Continue under example 1, 2, or 3 below.
  10. +
+
+ + +
screen shot showing the combined button with an instance name 'flashLink1'
+ +
+
+

Using the Accessibility panel to specify the accessible name

+ +

The Accessibility panel is used to specify the accessible name (which in this case is the same as the visual text).

+
+ + +
screen shot showing use of the Accessibility control panel to provide a name for the combined button
+ +
+ +
+
+

Using ActionScript to specify the accessible name

+ +

ActionScript 3 can be used instead of the Accessibility control panel to define the accessibility name for the combined button, as follows:

+ +
// 'flashLink1' is an instance placed on the movie's main timeline
+flashLink1.accessibilityProperties = new AccessibilityProperties();
+flashLink1.accessibilityProperties.name = "Learn more about Flash";
+ +

ActionScript 2 can be used instead of the Accessibility control panel to define the accessibility name for the combined button, as follows

+ +
// 'flashLink1' is an instance placed on the movie's main timeline
+flashLink1._accProps = new Object();
+flashLink1._accProps.name = "Learn more about Flash";
+
+

Tests

+

Procedure

+
    +
  1. Publish the SWF file
  2. +
  3. Open the SWF file in Internet Explorer 6 or higher (using Flash Player 6 or higher), or Firefox 3 or higher (using Flash Player 9 or higher)
  4. +
  5. Use a tool which is capable of showing an object's name text alternative, such as ACTF aDesigner 1.0 to open the Flash movie.
  6. +
  7. If you are using ACTF aDesigner 1.0, use the GUI Summary panel to check each image button in the Flash movie and ensure that there is no separate, redundant text control adjacent to the image that performs the same action.
  8. +
+
+

Expected Results

+

#4 is true.

+
+
diff --git a/techniques/flash/FLASH6.html b/techniques/flash/FLASH6.html new file mode 100644 index 0000000000..3458eee243 --- /dev/null +++ b/techniques/flash/FLASH6.html @@ -0,0 +1,65 @@ +Creating accessible hotspots using invisible buttons

Creating accessible hotspots using invisible buttons

ID: FLASH6

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to provide text alternatives that serve the same purpose as the clickable hotspots of an image. Each hotspot serves as a clickable region for a part of the image which can trigger an action (such as opening a web page corresponding to the hotspot). The hotspots are implemented as invisible Flash buttons, which are each given an accessible name that describes the hotspot's target.

+

Examples

+
+

Graphic with accessible clickable regions

+ +
    +
  1. Add the original graphic that needs to have clickable hotspots to the stage.
  2. +
  3. +

    For each hotspot, do the following:

    +
      +
    1. Create a new button symbol by choosing "New Symbol" from the Flash Professional 'Insert' menu or by using the Ctrl + F8 shortcut.
    2. +
    3. Inside the button symbol, create a shape that matches the clickable surface.
    4. +
    5. Place the newly created button on top of the original graphic.
    6. +
    7. Open the button's properties panel, and choose "Alpha" from the "Style" dropdown list under "Color Effect". Change the value of the "Alpha" slider that appears to zero so that the button becomes invisible.
    8. +
    9. Using the Accessibility panel, specify a value for the "tabindex" field to give the button a logical position in the tab order.
    10. +
    11. Using the Accessibility panel, specify an accessible name that describes the purpose of the hotspot.
    12. +
    +
  4. +
+
+ + +
adding the graphic to the Flash authoring stage
+ +
+
+ + +
making a button invisible using the Properties panel
+ +
+
+ + +
setting the button's name using the Accessibility panel
+ +
+ + +

The result can be seen in the working example of creating accessible hotspots using invisible buttons. The source of creating accessible hotspots using invisible buttons is available.

+ +
+

Tests

+

Procedure

+

Find all images with hotspots. For each hotspot, confirm that:

+
    +
  1. The hotspot is implemented as an invisible button
  2. +
  3. The hotspot is provided with an accessible name, either through the Accessibility panel or through ActionScript
  4. +
+
+

Expected Results

+
    +
  • #1 and #2 are true
  • +
+
+
diff --git a/techniques/flash/FLASH7.html b/techniques/flash/FLASH7.html new file mode 100644 index 0000000000..7425c666c4 --- /dev/null +++ b/techniques/flash/FLASH7.html @@ -0,0 +1,42 @@ +Using scripting to change control labels

Using scripting to change control labels

ID: FLASH7

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The purpose of this technique is to allow users to choose to have additional information added to the label of a button or other control so that it can be understood out of context.

+

Some users prefer to have control labels that are self-contained, where there is no need to explore the context of the control. Other users find including the context information in each button to be repetitive and to reduce their ability to use a site. Among users of assistive technology, the feedback to the working group on which is preferable has been divided. This technique allows users to pick the approach that works best for them.

+

A control is provided near the beginning of the page that will expand the labels for controls on the page so that no additional context is needed to understand the purpose of those controls. It must always be possible to understand purpose of the control directly from its label.

+

This technique expands the control labels only for the current page view. It is also possible, and in some cases would be advisable, to save this preference in a cookie or server-side user profile, so that users would only have to make the selection once per site.

+

Examples

+
+

Using ActionScript to add contextual information directly to the label of a button

+ +

This example uses ActionScript to add contextual information directly to the label of a button. When the "Expand Button Labels" button is toggled, each button on the page has its label property modified.

+ +
import fl.accessibility.ButtonAccImpl;
+ButtonAccImpl.enableAccessibility();
+btn1.addEventListener(MouseEvent.CLICK, clickHandler);
+
+function clickHandler(e) {
+  btn2.label = btn1.selected? "PDF version of 2010 brochure": "PDF";
+  btn2.width = btn1.selected? 200: 100;
+  btn3.label = btn1.selected? "Text version of 2010 brochure": "Text";
+  btn3.width = btn1.selected? 200: 100;
+  btn4.label = btn1.selected? "Word version of 2010 brochure": "Word";
+  btn4.width = btn1.selected? 200: 100;
+}
+ +

The result can be seen in the working example of adding contextual information to a button label. The source of adding contextual information to a button label is available.

+ +
+

Tests

+

Procedure

+

When a Flash Movie contains content with context dependent labels, confirm that a separate toggle control is provided that allows the user to expand the labels so that they are no longer context dependent.

+
+

Expected Results

+

The above is true.

+
+
\ No newline at end of file diff --git a/techniques/flash/FLASH8.html b/techniques/flash/FLASH8.html new file mode 100644 index 0000000000..3ebb6e8745 --- /dev/null +++ b/techniques/flash/FLASH8.html @@ -0,0 +1,219 @@ +Adding a group name to the accessible name of a form control

Adding a group name to the accessible name of a form control

ID: FLASH8

Technology: flash

Type: Technique

When to Use

+
    +
  • Adobe Flash Professional version MX and higher
  • +
  • Adobe Flex
  • +
+

Description

+

The objective of this technique is to provide a semantic grouping for related form controls. This allows users to understand the relationship of the controls and interact with the form more quickly and effectively.

+

In Flash, when related form controls are grouped, this grouping can be indicated by adding the group's name to each form control's accessible name.

+

Grouping controls is most important for related radio buttons and checkboxes. A set of radio buttons or checkboxes is related when they all submit values for a single named field. They work in the same way as selection lists, allowing the user to choose from a set of options, except selection lists are single controls while radio buttons and checkboxes are multiple controls. Because they are multiple controls, it is particularly important that they be grouped semantically so they can be more easily treated as a single control. Often, user agents will present the value of the legend before the label of each control, to remind users that they are part of the same group.

+

It can also be useful to group other sets of controls that are not as tightly related as sets of radio buttons and checkboxes. For instance, several fields that collect a user's address might be grouped together with a legend of "Address".

+

Examples

+
+

Adding a group name to the accessible name of radio buttons

+ +

This example shows how the group name for radio buttons in a group can be made accessible by adding it to each button's accessible name:

+
    +
  1. Add radio button components to the stage:
  2. +
  3. Enter each button's label using its label property
  4. +
  5. Add the visual group label to the left or above the buttons added in step 1
  6. +
  7. Select each radio button. In the Accessibility panel, add the group name to the "Name" field;
  8. +
+

Flash will concatenate the group name with each button's individual name, such as "gender male".

+

This approach is illustrated in the screenshot below:

+
+ + +
Using the Accessibility panel to add a group name to a form control
+ +
+
+

To make the radio buttons in this example accessible, the following two lines need to be added to the movie's script: import fl.accessibility.RadioButtonAccImpl; +RadioButtonAccImpl.enableAccessibility(); +

+
+

For an illustration of this approach, see the working version of Adding a group name to the accessible name of radio buttons. The source of Adding a group name to the accessible name of radio buttons is available.

+ +
+
+

Programmatically adding a group name with the accessible name of radio buttons

+ +

The code example below shows a basic proof of concept of a class that automatically places a set of form controls inside a fieldset like rectangle, including a legend. For each added control an AccessibilityProperties object is created, and its name property is set to a combination of the legend text and the actual form control label.

+ +
+package wcagSamples {
+  import flash.display. *;
+  import flash.text. *;
+  import fl.controls. *
+  import flash.accessibility. *;
+  import fl.accessibility. *;
+  
+  
+  /**
+  *  Basic example that demonstrates how to simulate a fieldset, as provided
+  *  in HTML. The FieldSet class takes a group of controls and places them 
+  *  inside a fieldset rectangle with the legend text at the top. For each form 
+  *  control, the legend text is prepended to the control's accessible name
+  *
+  *  Note: This is only a proof of concept, not a fully functional class
+  *
+  *  @langversion 3.0
+  *  @playerversion Flash 10
+  *
+  */
+  public class FieldSet extends Sprite {
+    private var legend: String;
+    private var bBox: Shape;
+    private var currentY: int = 20;
+    
+    public static var LABEL_OFFSET_X: int = 20;
+    public static var CONTROL_OFFSET_X: int = 110;
+    
+    /**
+    *  CONSTRUCTOR
+    *  Legend specifies the FieldSet's legend text, items is an array 
+    *  describing the controls to be added to the FieldSet
+    */
+    
+    public function FieldSet(legend: String, items: Array) {
+      // enable accessibility for components used in this example
+      RadioButtonAccImpl.enableAccessibility();
+      CheckBoxAccImpl.enableAccessibility();
+      
+      //create FieldSet rectangle and legend
+      legend = legend;
+      bBox = new Shape();
+      bBox.graphics.lineStyle(1);
+      bBox.graphics.drawRect(10, 10, 300, 250);
+      bBox.graphics.beginFill(0x0000FF, 1);
+      addChild(bBox);
+      
+      var fieldSetLegend: TextField = new TextField();
+      fieldSetLegend.text = legend;
+      fieldSetLegend.x = 20;
+      fieldSetLegend.y = 3;
+      fieldSetLegend.background = true;
+      fieldSetLegend.backgroundColor = 0xFFFFFF;
+      fieldSetLegend.border = true;
+      fieldSetLegend.borderColor = 0x000000;
+      fieldSetLegend.autoSize = TextFieldAutoSize.LEFT;
+      addChild(fieldSetLegend);
+      
+      // add controls
+      for (var i = 0; i < items.length; i++) {
+        processItem(items[i]);
+      }
+    }
+    
+    /**
+    * Adds the control to the Fieldset and sets its accessible name. A 
+    * control is represented as an array, containing the following values:
+    * [0] : A string describing the component type 
+    *   (can be "TextInput", TextArea", Checkbox" or "RadioGroup").
+    * [1] : The label used to identify the control
+    * [2] : If [0] is "RadioGroup", then [2] needs to contain an array of the 
+    *    labels for each individual radio button. if [0] is "CheckBox", then 
+    *    [1] can either be empty or a question (e.g. "Do you smoke?"), and 
+    *    [2] the CheckBox label (e.g. "Yes").
+    *
+    */
+    function processItem(item: Array) {
+      if (item.length < 2)
+      return;
+      currentY += 30;
+      var newControl;
+      //create visual label
+      var lbl: Label;
+      lbl = new Label();
+      lbl.text = item[1] + ": ";
+      lbl.x = FieldSet.LABEL_OFFSET_X;
+      lbl.y = currentY;
+      lbl.width = FieldSet.CONTROL_OFFSET_X;
+      lbl.autoSize = TextFieldAutoSize.RIGHT;
+      lbl.wordWrap = true;
+      addChild(lbl);
+      
+      switch (item[0]) {
+        case "TextInput":
+        case "TextArea":
+        newControl = item[0] == "TextInput"? new TextInput(): new TextArea();
+        newControl.x = FieldSet.CONTROL_OFFSET_X;
+        //concatenate accessible name, combining legend and label
+        setAccName(newControl, legend + " " + item[1]);
+        break;
+        case "CheckBox":
+        newControl = new CheckBox();
+        newControl.label = item[2];
+        newControl.x = FieldSet.CONTROL_OFFSET_X;
+        setAccName(newControl, legend + " " + item[1] + " " + item[2]);
+        break;
+        case "RadioGroup":
+        if (item[2] && item[2].length > 0) {
+          var radioGroup: RadioButtonGroup = new RadioButtonGroup(item[0]);
+          var newBtn: RadioButton;;
+          for (var i = 0; i < item[2].length; i++) {
+            newBtn = new RadioButton();
+            // concatenate the legend, the group label, and the button label
+            setAccName(newBtn, legend + " " + item[1] + " " + item[2][i]);
+            newBtn.label = item[2][i];
+            newBtn.group = radioGroup;
+            newBtn.x = FieldSet.CONTROL_OFFSET_X;
+            newBtn.y = currentY;
+            addChild(newBtn);
+            if (i < item[2].length - 1)
+            currentY += 30;
+          }
+        }
+        break;
+      }
+      
+      if (newControl) {
+        newControl.y = currentY;
+        addChild(newControl);
+      }
+    }
+    
+    /**
+    * Creates an AccessibilityProperties object for an object and sets its name property
+    */
+    public function setAccName(obj, accName) {
+      var accProps: AccessibilityProperties = new AccessibilityProperties();
+      accProps.name = accName;
+      obj.accessibilityProperties = accProps;
+    }
+  }
+}
+ +

This example class can be initialized as follows:

+ +
var myFieldSet = new FieldSet("Personal Details",  // the legend 
+  [["TextInput", "Name"],                          // text field
+  ["RadioGroup", "Gender", ["Male", "Female"]],    // radio button group
+  ["CheckBox", "Do you smoke", "yes"],             // checkbox
+  ["TextArea", "Comments"],                        // text area
+]);
+addChild(myFieldSet);
+
+ +

For an illustration of this approach, see the working version of Programmatically adding a group name with the accessible name of radio buttons. The source of Programmatically adding a group name with the accessible name of radio buttons is available.

+
+

Adobe Flex allows you to perform this type of behavior by using the <form>, <formitem> and <formheading> elements

+
+ +
+

Tests

+

Procedure

+

When a Flash Movie contains grouped form controls, confirm that either :

+
    +
  • The group's name is included in the Accessibility panel's "name" field for each control.
  • +
  • Each control has an AccessibilityProperties.name property, which contains both the group's name and the control's label text
  • +
+
+

Expected Results

+
    +
  • One of the above is true
  • +
+
+
diff --git a/techniques/flash/FLASH9.html b/techniques/flash/FLASH9.html new file mode 100644 index 0000000000..57c45165e1 --- /dev/null +++ b/techniques/flash/FLASH9.html @@ -0,0 +1,94 @@ +Applying captions to prerecorded synchronized media

Applying captions to prerecorded synchronized media

ID: FLASH9

Technology: flash

Type: Technique

When to Use

+

Adobe Flash-based Content

+
    +
  • Adobe Flash CS3 and later
  • +
+

Description

+

The objective of this technique is to provide an option for people who have hearing impairments or otherwise have trouble hearing the sound and dialogue in synchronized media to be able to choose to view captions as an alternative to audio information. With this technique all of the dialogue and important sounds are provided as text in a fashion that allows the text to be hidden unless the user requests it. As a result they are visible only when needed. This can be achieved using the FLVPlayback and FLVPlaybackCaptioning components. Note: when using FLVPlayback skins the closed caption button is accessible by default, but if implementing custom skins authors need to test to verify that the button is accessible.

+

Examples

+
+

Adding a timed text caption file to Flash

+ +
    +
  1. Use an external tool (such as Magpie or a simple text editor) to create a timed Text captions xml file. Stop and play the video content, and for each relevant part of audio information (including speech, important background noises and event sounds) include the start and end time code as well as the textual alternative. Tools like Magpie have advanced features to make this process easier, whereas a text editor requires you to read the timecodes from your media player and include them in the XML as illustrated in the sample captions document below
  2. +
  3. In Flash, create a new instance of the FLVPlayback component on your stage, and set its contentPath value to your flv video file using the 'Component inspector' or 'Parameters' panel.
  4. +
  5. Set the 'Skin' parameter to use a skin which includes the CC (closed captions) button.
  6. +
  7. From the components list also create an instance of the FLVPlayback captioning component. In the 'Component inspector' panel set its 'Source' parameter to the name of your timed text xml file. The captions will automatically placed at the bottom of the player's frame.
  8. +
+ +
<?xml version="1.0" encoding="UTF-8"?>
+<tt xml:lang="en" xmlns="https://www.w3.org/2006/04/ttaf1"
+  xmlns:tts="https://www.w3.org/2006/04/ttaf1#styling">
+  <head>
+    <styling>
+      <style id="defaultSpeaker" tts:backgroundColor="black"
+        tts:color="white" tts:fontFamily="SansSerif" tts:fontSize="12"
+        tts:fontStyle="normal" tts:fontWeight="normal"
+        tts:textAlign="left" tts:textDecoration="none"/>
+      <style id="defaultCaption" tts:backgroundColor="black"
+        tts:color="white" tts:fontFamily="Arial" tts:fontSize="12"
+        tts:fontStyle="normal" tts:fontWeight="normal"
+        tts:textAlign="center" tts:textDecoration="none"/>
+    </styling>
+  </head>
+  <body id="thebody" style="defaultCaption">
+    <div xml:lang="en">
+      <p begin="0:00:00.20" end="0:00:02.20">If there were nothing in
+        our universe</p>
+      <p begin="0:00:02.20" end="0:00:05.65">the fabric of space-time
+        would be flat.</p>
+      <p begin="0:00:05.65" end="0:00:08.88">But add a mass, and
+        dimples form within it.</p>
+      <p begin="0:00:16.61" end="0:00:19.84">Smaller objects that
+        approach that large mass</p>
+      <p begin="0:00:19.84" end="0:00:23.41">will follow the curve in
+        space-time around it.</p>
+      <p begin="0:00:32.64" end="0:00:36.84">Our nearest star, the
+        sun, has formed such a dimple</p>
+      <p begin="0:00:36.84" end="0:00:38.00">and our tiny planet
+        Earth</p>
+      <p begin="0:00:38.00" end="0:00:41.50">goes along for the ride
+        in the curve of its dimple</p>
+      <p begin="0:00:41.50" end="0:00:43.80">staying in orbit around
+        the sun.</p>
+      <p begin="0:00:45.67" end="0:01:55.00"/>
+    </div>
+  </body>
+</tt>
+
+ +

This is demonstrated in working example of Adding a timed text caption file to Flash. The working example of Adding a timed text caption file to Flash is available.

+ +
+

Tests

+

Procedure

+

Watch all video content displayed by your Flash movie. Ensure that:

+
    +
  1. Captions are available for all audio content, either turned on by default or as a user preference.
  2. +
  3. The captions properly describe all audio information contained in the video.
  4. +
+
+

Expected Results

+
    +
  • #1 and #2 are true
  • +
+
+

Resources

+ +

+ http://ncam.wgbh.org/invent_build/web_multimedia/tools-guidelines +

+ + +

+ http://www.buraks.com/captionate/ +

+ + +

+ https://www.w3.org/AudioVideo/TT/ +

+ +
\ No newline at end of file diff --git a/techniques/flash/flash.11tydata.json b/techniques/flash/flash.11tydata.json new file mode 100644 index 0000000000..73eb5cd234 --- /dev/null +++ b/techniques/flash/flash.11tydata.json @@ -0,0 +1,4 @@ +{ + "obsoleteSince": "20", + "obsoleteMessage": "Adobe stopped updating and distributing the Flash Player at the end of 2020, and encourages authors interested in creating accessible web content to use HTML." +} diff --git a/techniques/flash/img/ac_show_tab_order_view.png b/techniques/flash/img/ac_show_tab_order_view.png new file mode 100644 index 0000000000..deb383f886 Binary files /dev/null and b/techniques/flash/img/ac_show_tab_order_view.png differ diff --git a/techniques/flash/img/acc_name_scrn.jpg b/techniques/flash/img/acc_name_scrn.jpg new file mode 100644 index 0000000000..39cc324d02 Binary files /dev/null and b/techniques/flash/img/acc_name_scrn.jpg differ diff --git a/techniques/flash/img/adjacentbtns.jpg b/techniques/flash/img/adjacentbtns.jpg new file mode 100644 index 0000000000..dd8d43c099 Binary files /dev/null and b/techniques/flash/img/adjacentbtns.jpg differ diff --git a/techniques/flash/img/ascii_art_alternative.png b/techniques/flash/img/ascii_art_alternative.png new file mode 100644 index 0000000000..e41d58eb72 Binary files /dev/null and b/techniques/flash/img/ascii_art_alternative.png differ diff --git a/techniques/flash/img/component_inspector_label.png b/techniques/flash/img/component_inspector_label.png new file mode 100644 index 0000000000..03dc6e1d3d Binary files /dev/null and b/techniques/flash/img/component_inspector_label.png differ diff --git a/techniques/flash/img/editing_focusrect.png b/techniques/flash/img/editing_focusrect.png new file mode 100644 index 0000000000..e09d5bba37 Binary files /dev/null and b/techniques/flash/img/editing_focusrect.png differ diff --git a/techniques/flash/img/findoutmore.jpg b/techniques/flash/img/findoutmore.jpg new file mode 100644 index 0000000000..8c2d178b33 Binary files /dev/null and b/techniques/flash/img/findoutmore.jpg differ diff --git a/techniques/flash/img/flash_hotspot_accessibleName.png b/techniques/flash/img/flash_hotspot_accessibleName.png new file mode 100644 index 0000000000..276f9aa941 Binary files /dev/null and b/techniques/flash/img/flash_hotspot_accessibleName.png differ diff --git a/techniques/flash/img/flash_hotspot_graphic.png b/techniques/flash/img/flash_hotspot_graphic.png new file mode 100644 index 0000000000..37d8e35e7a Binary files /dev/null and b/techniques/flash/img/flash_hotspot_graphic.png differ diff --git a/techniques/flash/img/flash_hotspot_invisible.png b/techniques/flash/img/flash_hotspot_invisible.png new file mode 100644 index 0000000000..ad277dfaf4 Binary files /dev/null and b/techniques/flash/img/flash_hotspot_invisible.png differ diff --git a/techniques/flash/img/groupname.png b/techniques/flash/img/groupname.png new file mode 100644 index 0000000000..527e1613f8 Binary files /dev/null and b/techniques/flash/img/groupname.png differ diff --git a/techniques/flash/img/required_flash_control.png b/techniques/flash/img/required_flash_control.png new file mode 100644 index 0000000000..d8d5e999a8 Binary files /dev/null and b/techniques/flash/img/required_flash_control.png differ diff --git a/techniques/flash/img/setting_tabindex_in_accessibility_panel.png b/techniques/flash/img/setting_tabindex_in_accessibility_panel.png new file mode 100644 index 0000000000..694ff027eb Binary files /dev/null and b/techniques/flash/img/setting_tabindex_in_accessibility_panel.png differ diff --git a/techniques/flash/img/using_auto_label.png b/techniques/flash/img/using_auto_label.png new file mode 100644 index 0000000000..4752de65a1 Binary files /dev/null and b/techniques/flash/img/using_auto_label.png differ diff --git a/techniques/general/G134.html b/techniques/general/G134.html index 3500b62c77..2fd722ef3f 100644 --- a/techniques/general/G134.html +++ b/techniques/general/G134.html @@ -1,3 +1,8 @@ +--- +obsoleteMessage: | + This technique relates to 4.1.1: Parsing, which was removed as of WCAG 2.2. +obsoleteSince: 22 +--- diff --git a/techniques/general/G187.html b/techniques/general/G187.html new file mode 100644 index 0000000000..1df33d06fb --- /dev/null +++ b/techniques/general/G187.html @@ -0,0 +1,32 @@ +--- +obsoleteMessage: Most user agents do not implement a stop animation command as described in this technique. +obsoleteSince: 20 +--- +Using a technology to include blinking content that can be turned off via the user agent

Using a technology to include blinking content that can be turned off via the user agent

ID: G187

Technology: general

Type: Technique

When to Use

+

All technologies.

+

Description

+

The objective of this technique is to ensure that blinking content can be turned off using user agent features. User agents allow users to stop animation of content in certain technologies. When the user activates this feature, all animation, including blinking, is stopped. This feature can be provided either through interactive controls that conform to WCAG or through documented keyboard shortcuts.

+

The most common way for users to stop animation is to press the "escape" key. As long as there are no processes that take precedence in the event queue for a press of that key, this is taken as a command to stop animation of moving or blinking content.

+

Technologies for which this is known generally to work include:

+
    +
  • Graphics Interchange Format (GIF)
  • +
  • Animated Portable Network Graphics (APNG)
  • +
+

Examples

+
    +
  • A page contains a blinking banner intended to draw the user's attention to it. The banner is an animated gif image which repeats indefinitely. The user presses the "escape" key, which causes the user agent to stop the animation of all animated gif images on the page.
  • +
+

Tests

+

Procedure

+
    +
  1. Load a page that includes blinking content.
  2. +
  3. Activate the browser's stop animation command (usually the Escape key).
  4. +
  5. Check to see if the blinking stops.
  6. +
+
+

Expected Results

+
    +
  • Check #3 is true.
  • +
+
+
diff --git a/techniques/general/G192.html b/techniques/general/G192.html index 746b7cb3c5..5c8670065c 100644 --- a/techniques/general/G192.html +++ b/techniques/general/G192.html @@ -1,3 +1,8 @@ +--- +obsoleteMessage: | + This technique relates to 4.1.1: Parsing, which was removed as of WCAG 2.2. +obsoleteSince: 22 +--- Fully conforming to specifications

Fully conforming to specifications

ID: G192

Technology: general

Type: Technique

When to Use

This technique relates to all markup languages with specifications.

Description

@@ -25,4 +30,4 @@
  • H74
  • H75
  • H88
  • -
    \ No newline at end of file + diff --git a/techniques/html/H35.html b/techniques/html/H35.html new file mode 100644 index 0000000000..ac1365cabb --- /dev/null +++ b/techniques/html/H35.html @@ -0,0 +1,37 @@ +--- +obsoleteMessage: The Java-specific applet element is obsolete. +obsoleteSince: 20 +--- + Providing text alternatives on applet elements

    Providing text alternatives on applet elements

    ID: H35

    Technology: html

    Type: Technique

    When to Use

    +

    HTML and XHTML Documents that load Java applets where applet is not deprecated. +

    +

    Description

    +

    Provide a text alternative for an applet by using the alt attribute to label an applet + and providing the text alternative in the body of the applet element. In this technique, both mechanisms + are required due to the varying support of the alt attribute and applet body text by + user agents.

    +

    Examples

    +
    +

    An applet to play the tic-tac-toe game.

    +
    <applet code="tictactoe.class" width="250" height="250" alt="tic-tac-toe game">
    +   tic-tac-toe game
    +</applet>  
    +
    +

    Tests

    +

    Procedure

    +
      +
    1. View the source code of the applet element
    2. +
    3. Check that the applet element contains an alt attribute with a text alternative + for the applet
    4. +
    5. Check that the applet element contains a text alternative for the applet in the + body of the applet element
    6. +
    +
    +

    Expected Results

    +
      +
    • Checks #2 and #3 are true.
    • +
    +
    +
    diff --git a/techniques/html/H4.html b/techniques/html/H4.html new file mode 100644 index 0000000000..8000f5ec8b --- /dev/null +++ b/techniques/html/H4.html @@ -0,0 +1,126 @@ +--- +obsoleteMessage: Manipulating focus order is discouraged, as it frequently introduces new accessibility issues. +obsoleteSince: 20 +--- +Creating a logical tab order through links, form controls, and objects

    Creating a logical tab order through links, form controls, and objects

    ID: H4

    Technology: html

    Type: Technique

    When to Use

    +

    HTML and XHTML

    +

    Description

    +

    The objective of this technique is to provide a logical tab order when the default tab + order does not suffice. Often, placing the + interactive elements in an order that follows sequences and relationships within the + content is sufficient and this technique is not necessary. It can be very easy + to introduce usability bugs when setting the tab order explicitly.

    +

    In some cases, the author may want to specify a tab order that follows relationships in + the content without following the order of the interactive elements in the code. In + these cases, an alternative order can be specified using the tabindex + attribute of the interactive element. The tabindex is given a value between + 0 and 32767.

    +

    When the interactive elements are navigated using the tab key, the elements are given + focus in increasing order of the value of their tabindex attribute. + Elements that have a tabindex value higher than zero will receive focus + before elements without a tabindex or a tabindex of 0. After + all of the elements with a tabindex higher than 0 have received focus, the rest of the + interactive elements are given focus in the order in which they appear in the Web + page.

    +

    Examples

    +
    + +

    A genealogical search form searches for marriage records. The search form includes + several input fields for the bride and the groom. The form is marked up using a data + table that includes the fields of the groom in the first column and the fields of + the bride in the second column. The order in the content is row by row but the + author feels it is more logical to navigate the form column by column. This way, all + the groom's criteria can be filled in before moving on to the bride's criteria. The + tabindex attributes of the input fields are used to specify a tab + order that navigates column by column.

    + +
    <form action="#" method="post">
    + <table summary="the first column contains the search criteria 
    +  of the groom, the second column the search criteria of 
    +  of the bride">
    + <caption>Search for marriage records</caption>
    + <tr>
    +   <th>Search criteria</th>
    +   <th>Groom</th>
    +   <th>Bride</th>
    + </tr>
    + <tr>
    +  <th>First name</th>
    +  <td><input type="text" size="30" value="" name="groomfirst" 
    +      title="First name of the groom" tabindex="1"></td>
    +  <td><input type="text" size="30" value="" name="bridefirst" 
    +       title="First name of the bride" tabindex="4"></td>
    + </tr>
    + <tr>
    +  <th>Last name</th>
    +  <td><input type="text" size="30" value="" name="groomlast" 
    +      title="Last name of the groom" tabindex="2"></td>
    +  <td><input type="text" size="30" value="" name="bridelast" 
    +      title="Last name of the bride" tabindex="5"></td>
    + </tr>
    + <tr>
    +  <th>Place of birth</th>
    +  <td><input type="text" size="30" value="" name="groombirth" 
    +      title="Place of birth of the groom" tabindex="3"></td>
    +  <td><input type="text" size="30" value="" name="bridebirth" 
    +      title="Place of birth of the bride" tabindex="6"></td>
    + </tr>
    +</table>
    +</form>      
    +
    +
    + +

    A Web page contains a search field in the upper right corner. The field is given + tabindex="1" so that it will occur first in the tab order, even though it is not + first in the content order.

    + +
    +
    + +

    + Tabindex values need not be sequential nor must they begin with any + particular value. The values do not have to be unique. Elements that have identical + tabindex values are navigated in the order they appear in the + character stream.

    + + +

    In sections of the content where the tab order follows the content order, it can be + less error prone to give all elements the same tabindex value rather than specifying + a different number for each element. Then it is easy to rearrange those elements or + add new elements and maintain a logical tab order.

    + +
     <a href="xxx" tabindex = "1">First link in list</a>
    +<a href="xxx" tabindex = "1">Second link in list</a>
    +<a href="xxx" tabindex = "1">Link that was added long 
    +  after the original list was created</a>
    +<a href="xxx" tabindex = "1">Third link in list</a>
    +  ...
    +<a href="xxx" tabindex = "1">Twentieth link in list</a>      
    +
    +

    Tests

    +

    Procedure

    +
      +
    1. Check if tabindex is used
    2. +
    3. If tabindex is used, check that the tab order specified by the + tabindex attributes follows relationships in the content.
    4. +
    +
    +

    Expected Results

    +
      +
    • Check #2 is true.
    • +
    +
    +

    Resources

    + + + +
    diff --git a/techniques/html/H45.html b/techniques/html/H45.html new file mode 100644 index 0000000000..d1a5710b77 --- /dev/null +++ b/techniques/html/H45.html @@ -0,0 +1,54 @@ +--- +obsoleteMessage: The longdesc attribute is obsolete and not widely supported. +obsoleteSince: 20 +--- +Using longdesc

    Using longdesc

    ID: H45

    Technology: html

    Type: Technique

    When to Use

    +

    HTML documents that include images that cannot be + described in a short text alternative.

    +

    Description

    +

    The objective of this technique is to provide information in a file designated by the + longdesc attribute when a short text alternative does not adequately convey the function + or information provided in the image. The longdesc attribute is a URI, the target of + which contains a long description of the non-text content.

    +

    Authors can provide a description for an image by including text in a separate resource or within the text of the page containing the image. An advantage of using a separate resource for the description is that it is easily reusable for multiple instances of the same image, it does not add on-page visual clutter to the original document, and the description's end-point is apparent to the user. An advantage of providing the description within the same page as the image is that all users can access the description. A limitation of the on-page method, as well as in providing multiple descriptions on a single separate page, is that current implementations supporting longdesc do not identify the long description's end-point. Authors can solve this by providing a well-formed description, which identifies the where the description ends.

    +

    Examples

    +
    +

    Using longdesc to refer to a long description contained on a separate resource.

    +
    <p><img src="chart.gif" alt="a complex chart" longdesc="chartdesc.html"/></p>
    +
    +
    +

    Using longdesc to refer to a long description within the same page.

    +
    <img longdesc="thispage.html#desc" alt="Line graph of the number of subscribers" src="http://www.company/images/graph.png">
    +<div id="desc">
    +<h3>Long Description: Line graph of the number of subscribers</h3>
    +<!-- Full Description of Graph -->
    +<p>Long description ends.</p>
    +<div>
    +
    +

    Tests

    +

    Procedure

    +
      +
    1. Check that the img element has a longdesc attribute.
    2. +
    3. Check that the value of the longdesc attribute is a valid URI of an existing resource.
    4. +
    5. Check that the content at the target of that URI contains a long description describing the original non-text content associated with it.
    6. +
    +
    +

    Expected Results

    +
      +
    • #1 through #3 are all true
    • +
    +
    +

    Resources

    + + + +
    diff --git a/techniques/html/H46.html b/techniques/html/H46.html new file mode 100644 index 0000000000..63e9ce92df --- /dev/null +++ b/techniques/html/H46.html @@ -0,0 +1,52 @@ +--- +obsoleteMessage: noembed is obsolete. Use object instead when fallback is necessary. +obsoleteSince: 20 +--- +Using noembed with embed +

    Using noembed with embed +

    ID: H46

    Technology: html

    Type: Technique

    When to Use

    +

    Documents that load plugins with the embed element.

    +

    Description

    +

    The objective of this technique is to provide alternative content for the + embed element in a noembed element. The noembed is rendered + only if the embed is not supported. While it can be positioned anywhere on the + page, it is a good idea to include it as a child element of embed so that it is + clear to assistive technologies that a text alternative is associated with the + embed element it describes.

    +

    Examples

    +
    +

    + noembed is provided inside an embed +

    +
    <embed src="../movies/history_of_rome.mov"
    +  height="60" width="144" autostart="false">
    +  <noembed>
    +    <a href="../transcripts/transcript_history_rome.htm">Transcript of "The history of Rome"</a>
    +  </noembed>
    +</embed>
    +
    +
    +

    + noembed is provided beside an embed +

    +
    <embed src="moviename.swf" width="100" height="80"
    +  pluginspage="http://example.com/shockwave/download/" />
    +<noembed>
    +  <img alt="Still from Movie" src="moviename.gif" 
    +    width="100" height="80" />
    +</noembed>;
    +
    +

    Tests

    +

    Procedure

    +
      +
    1. Check if embed element has a child noembed element
    2. +
    3. Check if embed element has a noembed element that + immediately follows it.
    4. +
    +
    +

    Expected Results

    +
      +
    • #1 is true or #2 is true
    • +
    +
    +

    Resources

    diff --git a/techniques/html/H59.html b/techniques/html/H59.html new file mode 100644 index 0000000000..ac82bda502 --- /dev/null +++ b/techniques/html/H59.html @@ -0,0 +1,89 @@ +--- +obsoleteMessage: prev and next typically have no effect on browser navigation controls. +obsoleteSince: 20 +--- + + + + Using the link element and navigation tools + + + +

    Using the link element and navigation tools

    +
    +

    ID: H59

    +

    Technology: html

    +

    Type: Technique

    +
    +
    +

    When to Use

    +

    HTML

    +
    +
    +

    Description

    +

    The objective of this technique is to describe how the link element can + provide metadata about the position of an HTML page within a set of Web pages or can + assist in locating content with a set of Web pages. The value of the rel + attributes indicates what type of relation is being described, and the href + attribute provides a link to the document having that relation. Different link element rel values are used to create relationships:

    +
      +
    • next: Refers to the next document in a linear sequence of documents.
    • +
    • prev: Refers to the previous document in an ordered series of documents.
    • +
    +
    +
    +

    Examples

    +
    + +

    A Web page for Chapter 2 of an on-line book might contain the following links + within the head section.

    + +
    <link rel="prev" href="Chapter01.html" title="01. Why Volunteer?">
    +<link rel="next" href="Chapter03.html" title="03. Who Volunteers?" />
    +
    +
    +
    +

    Tests

    +
    +

    Procedure

    +

    For a Web page that is within a sequence or collection of Web pages:

    +
      +
    1. Check that all link elements pertaining to navigation occur in the head section of the document.
    2. +
    3. +

      For each link element in the head section of the document which pertains to navigation, check that it contains at least:

      +
        +
      1. a rel attribute identifying the link type
      2. +
      3. a valid href attribute to locate the appropriate resource
      4. +
      +
    4. +
    +
    +
    +

    Expected Results

    +
      +
    • All of the checks above are true.
    • +
    +
    +
    + +
    +

    Resources

    + + + +
    diff --git a/techniques/html/H60.html b/techniques/html/H60.html new file mode 100644 index 0000000000..3ec4ca9586 --- /dev/null +++ b/techniques/html/H60.html @@ -0,0 +1,62 @@ +--- +obsoleteMessage: The glossary link type is obsolete. +obsoleteSince: 20 +--- +Using the link element to link to a glossary

    Using the link element to link to a glossary

    ID: H60

    Technology: html

    Type: Technique

    When to Use

    +

    HTML and XHTML

    +

    Description

    +

    The objective of this technique is to provide a mechanism for locating a glossary. When + terms in the content are defined on a separate glossary page, the glossary is referenced + using a link element in the head element of the document that + uses the glossary. The rel attribute of the link element is + set to "glossary", and the href attribute contains the URI of the glossary + page. User agents can then assist users in accessing the glossary quickly and + easily.

    +

    Examples

    +
    +

    The WCAG 2.0 Glossary.

    +
     <link rel="glossary" href="https://www.w3.org/TR/WCAG20/#glossary">
    +
    +

    Tests

    +

    Procedure

    +

    For any set of words and their definitions that are meant to serve as a glossary:

    +
      +
    1. Check that the head section of the Web page that contains words, + phrases or abbreviations defined in a glossary contains a link + element
    2. +
    3. Check that the link element has attribute + + rel="glossary" +
    4. +
    5. Check that the href attribute of the link element + refers to the glossary page.
    6. +
    +
    +

    Expected Results

    +
      +
    • All checks above are true.
    • +
    +

    Note: The definition of abbreviation used in WCAG is : "shortened form of a word, + phrase, or name where the original expansion has not been rejected by the organization + that it refers to and where the abbreviation has not become part of the language."

    +
    +

    Resources

    + + + +
    diff --git a/techniques/html/H70.html b/techniques/html/H70.html new file mode 100644 index 0000000000..b8ca99df01 --- /dev/null +++ b/techniques/html/H70.html @@ -0,0 +1,69 @@ +--- +obsoleteMessage: The frameset and frame elements are obsolete. +obsoleteSince: 20 +--- +Using frame elements to group blocks of repeated material

    Using frame elements to group blocks of repeated material

    ID: H70

    Technology: html

    Type: Technique

    When to Use

    +

    HTML and XHTML documents that use frames

    +

    Description

    +

    The objective of this technique is to demonstrate how framesets can be used to group + blocks of repeated material. Since most user agents and assistive technology provide a + way to navigate from frame to frame, using frames to organize elements can provide a + mechanism for easily bypassing blocks of repeated content. If the site uses framesets, + organize the blocks of content into separate frames. Make certain that the repeated + blocks of content appear in the same frame within the frameset of each Web page. In + addition, each frame element must have a title attribute to describe the content of the + frame. When frames are properly titled, users can use frame navigation to easily + navigate between blocks of content.

    +

    This technique is appropriate when framesets are already used to organize the content + of the page; other techniques are preferred for pages that are not already using + framesets, because many people using assistive technology have trouble with frames . An + advisory technique about using noframes is available in Success Criterion 1.1.1.

    +

    In HTML5 the frame element is marked as obsolete.

    +

    Examples

    +
    + +

    The following example shows the use of two frames to organize content. The source + of the first frame is the Web page, navigation.html, which contains the HTML for the + navigation. This frame has a title attribute which identifies it as a navigation + bar. The second frame contains the main content of the site as indicated by the + source parameter of main.html and the title attribute, "Main News Content" which + identifies its function.

    + +
    <frameset cols="20%, *">
    +  <frame src="navigation.html" name="navbar" title="Navigation Bar" />
    +  <frame src="main.html" name="maincontent" title="Main News Content" />
    +  <noframes>
    +    <p>View <a href="noframe.html">no frame version</a>.</p>
    +  </noframes>
    +</frameset>   
    +
    +

    Tests

    +

    Procedure

    +

    If the Web page uses frames to organize content:

    +
      +
    1. Check if repeated blocks of content are organized into separate frames.
    2. +
    3. Check that the frames with repeated content appear in the same location within + each frameset.
    4. +
    +
    +

    Expected Results

    +
      +
    • Checks #1 and #2 are true.
    • +
    +
    +

    Resources

    + + + +
    diff --git a/techniques/html/H73.html b/techniques/html/H73.html new file mode 100644 index 0000000000..7f8aeb9626 --- /dev/null +++ b/techniques/html/H73.html @@ -0,0 +1,102 @@ +--- +obsoleteMessage: The summary attribute is obsolete as of HTML5. +obsoleteSince: 20 +--- +Using the summary attribute of the table element to give an overview of data + tables

    Using the summary attribute of the table element to give an overview of data + tables

    ID: H73

    Technology: html

    Type: Technique

    When to Use

    +

    HTML 4.01, XHTML 1.x

    +

    Description

    +

    The objective of this technique is to provide a brief overview of how data has been organized into a table or a brief explanation of how to navigate the table. The summary attribute of the table element makes this information available to people who use screen readers; the information is not displayed visually.

    +

    The summary is useful when the table has a complex structure (for example, + when there are several sets of row or column headers, or when there are multiple groups + of columns or rows). The summary may also be helpful for simple data tables + that contain many columns or rows of data.

    +

    The summary attribute may be used whether or not the table includes a + caption element. If both are used, the summary should not + duplicate the caption.

    +

    In HTML5 the summary attribute is obsolete. Assistive technologies may or may not continue to support the attribute. Authors should consider alternatives and only use with caution.

    +
    +

    Although WCAG 2 does not prohibit the use of layout tables, CSS-based layouts are + recommended in order to retain the defined semantic meaning of the HTML table + elements and to conform to the coding practice of separating presentation from content. + However, if a layout table is used, then the summary attribute is not used or + is null. The purpose of a layout table is simply to control the placement of content; + the table itself is “transparent" to the user. A summary would “break" this + transparency by calling attention to the table. A null summary + (summary="") on layout tables is acceptable. See F46 for details.

    +
    +

    Examples

    +
    +

    A data table with a summary but no caption

    + +

    This example shows a bus schedule. The route number and direction are included in + the summary along with information on how to use the schedule.

    + +
    <table summary="Schedule for Route 7 going downtown. Service begins 
    +at 4:00 AM and ends at midnight. Intersections are listed in the top row. 
    +Find the intersection closest to your starting point or destination, then read 
    +down that column to find out what time the bus leaves that intersection.">
    +  <tr>
    +    <th scope="col">State & First</th>
    +    <th scope="col">State & Sixth</th>
    +    <th scope="col">State & Fifteenth</th>
    +    <th scope="col">Fifteenth & Morrison</th>
    +  </tr>
    +  <tr>
    +    <td>4:00</td>
    +    <td>4:05</td>
    +    <td>4:11</td>
    +    <td>4:19</td>
    +  </tr>
    +  …
    +</table>  
    +
    +
    +

    A data table with both a summary and a caption +

    + +

    In this example both a summary attribute and a caption + element are used. The caption identifies the bus route. The + summary helps users who are blind understand how to use the schedule. + Screen readers read the caption, followed by the + summary.

    + +
    <table summary="Intersections are listed in row 1. 
    +Find the intersection closest to your starting point 
    +or destination, then read down that column to find 
    +out what time the bus leaves that intersection.  
    +Service begins at 4:00 AM and ends at midnight.">
    +  <caption>Route 7 Downtown (Weekdays)</caption>
    +…
    +</table>
    +
    +

    Tests

    +

    Procedure

    +

    For each data table:

    +
      +
    1. If a summary is present, check that the summary + attribute describes the table's organization or explains how + to use the table
    2. +
    3. If both a summary attribute and a caption element are present + for the data table, check that the summary does not + duplicate the caption.
    4. +
    +
    +

    Expected Results

    +
      +
    • #1 and #2 are true.
    • +
    +
    +

    Resources

    + + + +
    diff --git a/techniques/html/H74.html b/techniques/html/H74.html index cd4493aa4c..ba7131f17a 100644 --- a/techniques/html/H74.html +++ b/techniques/html/H74.html @@ -1,3 +1,8 @@ +--- +obsoleteMessage: | + This technique relates to 4.1.1: Parsing, which was removed as of WCAG 2.2. +obsoleteSince: 22 +--- @@ -62,18 +67,6 @@

    Resources

  • The W3C's Nu HTML Checker.
  • -
  • - Recommended DTDs to use in your Web document. -
  • -
  • - HTML - The doctype. -
  • -
  • - Validating Web pages. -
  • -
  • - The W3C's Nu HTML Checker. -
  • diff --git a/techniques/html/H75.html b/techniques/html/H75.html new file mode 100644 index 0000000000..ee44be3efe --- /dev/null +++ b/techniques/html/H75.html @@ -0,0 +1,81 @@ +--- +obsoleteMessage: | + This technique relates to 4.1.1: Parsing, which was removed as of WCAG 2.2. +obsoleteSince: 22 +--- +Ensuring that Web pages are well-formed

    Ensuring that Web pages are well-formed

    ID: H75

    Technology: html

    Type: Technique

    When to Use

    +

    Any XML-based markup languages.

    +

    Description

    +

    The objective of this technique is to avoid key errors that are known to cause + problems for assistive technologies when they are trying to parse contents. + Well-formedness is checked by parsing the document with a conforming XML parser and + checking if the validation report mentions well-formedness errors. Every conforming XML + parser is required to check well-formedness and stop normal processing when a + well-formedness error is found (a conforming XML parser does not need to support + validation).

    +

    Examples

    +
    +

    + +

    XML files include a document type declaration, a xsi:schemaLocation attribute or + other type of reference to a schema. The developer can use off-line or online + validators, an XML editor or an IDE with XML support (see Resources below) to check + well-formedness.

    + +
    +
    +

    + +

    When XML files do not include a document type declaration, a xsi:schemaLocation + attribute or a processing instruction referencing a schema even though there is a + schema for them, the relevant schema is specified by a command line instruction, a + user dialog or a configuration file, and the XML files are checked against the + schema.

    + +
    +
    +

    + +

    When XML files do not include a document type declaration, a xsi:schemaLocation + attribute or a processing instruction referencing a schema even though there is a + schema for them, the namespace is dereferenced to retrieve a schema document or + resource directory (Resource Directory Description Language: RDDL), and the XML files are checked against the + schema.

    + +
    +
    +

    + +

    When a Website generates XML dynamically instead of serving only static documents, + a developer can use XMLUnit, XML Test Suite or a similar + framework to test the generated XML code.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Load each file into a validating XML parser.
    2. +
    3. Check that there are no well-formedness errors.
    4. +
    +
    +

    Expected Results

    +

    Step 2 is true.

    +
    +

    Resources

    + + +

    For other resources, see Validating Web + pages.

    + +
    diff --git a/techniques/html/H88.html b/techniques/html/H88.html index 89fc224611..09c123d88d 100644 --- a/techniques/html/H88.html +++ b/techniques/html/H88.html @@ -53,6 +53,7 @@

    Expected Results

    Related Techniques

    Resources

    Refer to the resources section of Validating Web diff --git a/techniques/html/H93.html b/techniques/html/H93.html index 8f0ef17a09..0a5b9d8cb3 100644 --- a/techniques/html/H93.html +++ b/techniques/html/H93.html @@ -1,3 +1,8 @@ +--- +obsoleteMessage: | + This technique relates to 4.1.1: Parsing, which was removed as of WCAG 2.2. +obsoleteSince: 22 +--- diff --git a/techniques/html/H94.html b/techniques/html/H94.html index 68dc177cd5..d028da4554 100644 --- a/techniques/html/H94.html +++ b/techniques/html/H94.html @@ -1,3 +1,8 @@ +--- +obsoleteMessage: | + This technique relates to 4.1.1: Parsing, which was removed as of WCAG 2.2. +obsoleteSince: 22 +--- diff --git a/techniques/silverlight/SL1.html b/techniques/silverlight/SL1.html new file mode 100644 index 0000000000..383da1c4b7 --- /dev/null +++ b/techniques/silverlight/SL1.html @@ -0,0 +1,147 @@ +Accessing Alternate Audio Tracks in Silverlight Media

    Accessing Alternate Audio Tracks in Silverlight Media

    ID: SL1

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to show how to access an alternate + audio channel in a prepared media file that is played in a Silverlight MediaElement.

    +

    Silverlight supports media file formats that contains additional audio + channels in synchronization, beyond the two tracks for stereo audio + that are used by typical media player defaults. Silverlight provides + a dedicated AudioStreamIndex API on MediaElement, + so that the Silverlight application author can use Silverlight programming + techniques to select which audio channel to play for the user. Silverlight + control authors might label a UI control with text such as "Activate + this button to listen to an audio-only version of the media presentation" so + that the purpose of the media element control interface is clear to + the user. That way the same media control can be used to present the + media either as audio-video or as audio-only with alternate track depending + on user preference at run time.

    +

    The media formats that are supported by Silverlight are documented + on MSDN.

    +
    +

    Media encoding

    +

    The process of encoding the media with additional audio channels is + not described in this technique because configuring and encoding audio + channels for media formats is a technique for any usage of media in + a computer application, not just a Silverlight-specific technique or + a Web technology technique. For more information on one possible procedure + for encoding the media in WMV format, see Microsoft Expression Encoder Overview. + Often, Silverlight authors will receive the media from a third party, + such as a video production facility, and are not directly involved + with the encoding process. Silverlight authors should verify that the + media they are using has alternate audio tracks encoded in it. If such + tracks exist, Silverlight authors will need a track listing from the + media producer to know which of the audio tracks is intended as the + alternate audio. Other tracks might exist in the encoded media that + provide language translations of the default audio, or that serve other + purposes.

    +
    +

    Examples

    +
    +

    Changing AudioStreamIndex

    + +

    This example has a UI definition in XAML and interaction logic in + C#. In addition to the typical Play/Pause/Stop controls, this interface + includes a Play Full-Description Audio button. Activating the button + invokes a function that swaps the audio channels and plays an alternative + synchronized audio channel that contains a composite full-description audio track.

    +

    The following is the basic UI in XAML. This example is deliberately + simple and does not include AutomationProperties. + Audio streams are identified by an index in a collection.

    +
          <Grid x:Name="LayoutRoot" Background="White">
    +        <Grid.ColumnDefinitions>
    +            <ColumnDefinition Width="*" />
    +            <ColumnDefinition Width="*" />
    +            <ColumnDefinition Width="*"/>
    +        </Grid.ColumnDefinitions>
    +        <Grid.RowDefinitions>
    +            <RowDefinition Height="*" />
    +            <RowDefinition Height="Auto" />
    +            <RowDefinition Height="20" />
    +        </Grid.RowDefinitions>
    +        <MediaElement x:Name="media" Source="/combined.wmv"
    +           Width="300" Height="300" 
    +           Grid.Column="0" Grid.Row="0" Grid.ColumnSpan="3"
    +           AutoPlay="false"
    +        />
    +        <Button Click="StopMedia" 
    +     Grid.Column="0" Grid.Row="1" Content="Stop" />
    +        <Button Click="PauseMedia" 
    +     Grid.Column="1" Grid.Row="1" Content="Pause" />
    +        <Button Click="PlayMedia" 
    +     Grid.Column="2" Grid.Row="1" Content="Play" />
    +        <Button Name="AltAudioBtn" Grid.Row="2" HorizontalAlignment="Left" Grid.ColumnSpan="2" 
    +        Click="AltAudioBtn_Click">Play Full-Description Audio</Button>
    +    </Grid>
    +
    +

    The following is the C# logic.

    +
            private void AltAudioBtn_Click(object sender, RoutedEventArgs e)
    +        {
    +            if (media.AudioStreamCount > 1)
    +            {
    +                if (media.AudioStreamIndex == 1)
    +                {
    +                    media.AudioStreamIndex = 0;
    +                    (sender as Button).Content = "Play full-description audio";
    +                } else {
    +                    media.AudioStreamIndex = 1;
    +                   (sender as Button).Content = "Play default audio";
    +                }
    +            }
    +            else
    +            {
    +                (sender as Control).IsEnabled = false;
    +            }
    +        }
    +        private void StopMedia(object sender, RoutedEventArgs e)
    +        {
    +            media.Stop();
    +        }
    +        private void PauseMedia(object sender, RoutedEventArgs e)
    +        {
    +            media.Pause();
    +        }
    +        private void PlayMedia(object sender, RoutedEventArgs e)
    +        {
    +            media.Play();
    +        }
    +

    This example is shown in operation in the working example of Alternative Audio Channel. If using the test file, the test contains test audio tones rather than actual audio description, but the pitch of the tones is indicative of which of the channels is selected and played.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Open the HTML page for a Silverlight application, where that application + plays media and the media is expected to support an alternate audio + track for the video.
    2. +
    3. Verify that the application user interface presents a control + that enables the user to cause the media to play with an alternate + audio track.
    4. +
    5. Activate that control. Verify that the audio portion of the media + player output as played through the computer's audio system is now + playing the alternate audio track.
    6. +
    +
    +

    Expected Results

    +

    #2 and #3 are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL10.html b/techniques/silverlight/SL10.html new file mode 100644 index 0000000000..339f6587d5 --- /dev/null +++ b/techniques/silverlight/SL10.html @@ -0,0 +1,142 @@ +Implementing a Submit-Form Pattern in Silverlight

    Implementing a Submit-Form Pattern in Silverlight

    ID: SL10

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to declare Silverlight user interface + elements related to user input and use the Silverlight two-way data + binding techniques to provide a Submit button and opt-in forms submission + logic pattern for forms. The Submit button serves as the final deliberate + step of a form submission scenario. Silverlight programming techniques + do not provide a "Submit button as a distinct object. Rather, + application authors design their user input workflow such that it is + a single user action that initiates change of context that is related + to a data input scenario. The key to doing this in Silverlight is to + use a data binding mode that sets UpdateSourceTrigger of + all individual databound fields in that form or transaction. For any + data binding where the UpdateSourceTrigger is Explicit, + no real-time change is made to the data, until the UpdateSource method + is called on each of these bindings. The application-specific Submit + button is connected to an event handler that calls UpdateSource on + all of the databound UI elements that comprise that form.

    +
    +

    Validation of data

    +

    The Submit button itself can also be the UI element that provides + warnings, instructions, etc. in a way that assistive technologies can + report to users, through the AutomationProperties techniques. + Using a Submit model for Silverlight form input to databound data sources + relies on a particular data binding mode. The Submit model can be used + either along with client-side or server-side validation techniques. + The example does not explicitly include either validation technique.

    +
    +

    Examples

    +
    +

    Two form fields with Submit

    + +

    In this example, the form fields correspond to a data object that + implements a view model. Silverlight uses the view model and data annotations + to generate some of its UI, notably the names of the fields are bound + to the original view model names from the data. This example has a + UI defined in XAML and logic defined in C#. The following is the XAML + UI , which also includes the binding definitions. Note the Mode=TwoWay, + UpdateSourceTrigger=Explicit attributes in the bindings. This is the + binding mode to use for the Submit button scenario.

    +
    <UserControl x:Class="BasicSubmitButton.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +   xmlns:sdk="http://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk">
    + <StackPanel x:Name="LayoutRoot" Background="White" Margin="10">
    +   <Grid>
    +   <Grid.RowDefinitions>
    +       <RowDefinition Height="Auto"/>
    +       <RowDefinition Height="Auto"/>
    +       <RowDefinition Height="Auto"/>
    +       <RowDefinition Height="Auto"/>
    +       <RowDefinition Height="Auto"/>
    +   </Grid.RowDefinitions>
    +   <Grid.ColumnDefinitions>
    +       <ColumnDefinition Width="Auto"/>
    +       <ColumnDefinition Width="200"/>
    +       <ColumnDefinition Width="Auto"/>
    +   </Grid.ColumnDefinitions>
    +   <TextBlock Text="Form Input" FontSize="16" FontWeight="Bold"
    +     Grid.Column="1" HorizontalAlignment="Center" />
    +       <sdk:Label x:Name="NameLabel" Grid.Row="2" Margin="3"
    +   HorizontalAlignment="Right"
    +   Target="{Binding ElementName=NameTextBox}"/>
    +   <TextBox x:Name="NameTextBox" 
    +     AutomationProperties.Name="{Binding Content, ElementName=NameLabel}"
    +     Text="{Binding Name, Mode=TwoWay, UpdateSourceTrigger=Explicit}"
    +     Grid.Column="1" Grid.Row="2" Margin="3" />
    +       <sdk:Label x:Name="AgeLabel" Grid.Row="3" Margin="3"
    +   HorizontalAlignment="Right"
    +   Target="{Binding ElementName=AgeTextBox}"/>
    +   <TextBox x:Name="AgeTextBox" 
    +     AutomationProperties.Name="{Binding Content, ElementName=AgeLabel}" 
    +     Text="{Binding Age, Mode=TwoWay, UpdateSourceTrigger=Explicit}"  
    +     Grid.Column="1" Grid.Row="3" Margin="3" />
    +   <Button x:Name="SubmitButton" Content="Submit" Click="SubmitButton_Click"
    +     Grid.Column="1" Grid.Row="4" Width="50" Margin="3"
    +   AutomationProperties.HelpText="Activate this button to submit form."/>
    +   </Grid>
    + </StackPanel>
    +</UserControl>
    +
    +

    The following is the C# logic for the page. Note the SubmitButton_Click handler. + This implementation disables the Submit button (representative of + a change of context, because now the form cannot be submitted again) + and provides user feedback without performing any validation. The + test file included in this technique sets up its data object as a + purely client side entity and does no validation, so that no service/server + is necessary to use the test file. Each element with a binding calls + the UpdateSource method, such that the act of pressing + the Submit button commits all the form's information all at once. + A full implementation might replace this with a server side data + object infrastructure. A full implementation might also provide a "Reset" or "Edit" button + to enable form submission again if there were issues.

    +
    private void SubmitButton_Click(object sender, RoutedEventArgs e)
    +{
    +   (sender as Button).IsEnabled = false;
    +   NameTextBox.GetBindingExpression(TextBox.TextProperty).UpdateSource();
    +   AgeTextBox.GetBindingExpression(TextBox.TextProperty).UpdateSource();
    +   TextBlock tb = new TextBlock();
    +   tb.Text="Thank you, your form information was submitted.";
    +   LayoutRoot.Children.Add(tb);
    +}
    +
    +

    This example is shown in operation in the working example of Basic Submit Button.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. To test + UI Automation based behavior such as reading AutomationProperties.HelpText, + use Microsoft Windows as platform.
    2. +
    3. Verify that the user interface design of the form includes a clearly + indicated Submit button (a control that adequately communicates to + users that activating it will cause input to be submitted and might + cause a change of context).
    4. +
    5. Provide values for the various input fields of the form, and verify + that doing so does not in and of itself change the context.
    6. +
    7. Verify that if change of context occurs at all, that action is + delayed until after the Submit button is activated.
    8. +
    +
    +

    Expected Results

    +

    #2, #3, and #4 are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL11.html b/techniques/silverlight/SL11.html new file mode 100644 index 0000000000..00254639af --- /dev/null +++ b/techniques/silverlight/SL11.html @@ -0,0 +1,121 @@ +Pausing or Stopping A Decorative Silverlight Animation

    Pausing or Stopping A Decorative Silverlight Animation

    ID: SL11

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to associate a "Pause" or "Stop" action + for a Silverlight animation with a user interface control. This enables + a user to pause or stop an animation in Silverlight content.

    +

    The Silverlight animation system is generalized such that nearly any + Silverlight property of type Double, Point or Color can + be animated, or a property can cycle through discrete object values. + Thus the possibilities for which properties in the user interface can + be animated are quite broad. The general technique shown can be used + to pause or stop any Silverlight animation, including those that are + purely decorative.

    +
    +

    Pause versus Stop

    +

    Silverlight has two discrete methods for animation control: a Pause method + and a Stop method. The difference in behavior is that Pause uses + whatever the last value was while the animation was still running, + and holds that value permanenently (unless the animation is restarted). Stop sets + the value to be whatever value existed before the animation was started. + However, calling Stop on an animation often results + in a behavior that looks like a "reset" to the user; this + is particularly true if the animation is animating an element's position + on screen. In many cases, what might be a conceptual "stop" for + the user is better accomplished by a "permanent Pause" in + the Silverlight animation API. Whether to call Pause or Stop is + an aesthetic decision and application authors can experiment to see + which behavior has the best appearance. If application authors choose + to use Stop, authors can simply replace the call to + .Pause() with a call to .Stop() for any code that is based on this + technique's example.

    +
    +

    Examples

    +
    +

    Pausing a decorative animation

    + +

    The following is the XAML UI. The animated object and the animation + behavior are both described in XAML, as is the control that users can + activate to pause the animation.

    +
    <UserControl x:Class="PauseBouncyBall.MainPage"
    +xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    + <UserControl.Resources>
    +   <Storyboard x:Key="anim" RepeatBehavior="Forever" >
    +       <DoubleAnimationUsingKeyFrames Storyboard.TargetName="Ball"
    +          Storyboard.TargetProperty="(Canvas.Top)"
    +        FillBehavior="HoldEnd" AutoReverse="True">
    +               <EasingDoubleKeyFrame Value="100" KeyTime="00:00:01">
    +                   <EasingDoubleKeyFrame.EasingFunction>
    +                       <BounceEase Bounces="-1" EasingMode="EaseIn"/>
    +                   </EasingDoubleKeyFrame.EasingFunction>
    +               </EasingDoubleKeyFrame>
    +           </DoubleAnimationUsingKeyFrames>
    +   </Storyboard>
    + </UserControl.Resources>
    + <Canvas x:Name="LayoutRoot" Background="White" Height="600" Width="800">
    +   <Ellipse Name="Ball" Fill="Red" Width="20" Height="20" Canvas.Top="200">
    +       <Ellipse.RenderTransform>
    +           <TransformGroup>
    +               <TranslateTransform/>
    +           </TransformGroup>
    +       </Ellipse.RenderTransform>
    +   </Ellipse>
    +   <Button HorizontalAlignment="Left" Width="200" Click="Button_Click">Stop the bouncy ball please!</Button>
    + </Canvas>
    +</UserControl>
    +
    +

    The following is the C# logic. One function is the "page" constructor, + which is what starts and loops the animation. The other function + is the event handler for the UI control (a button). The event handler + retrieves the animation definition from the page resources, and calls + the Pause method on the animation.

    +
           public MainPage()
    +       {
    +           InitializeComponent();
    +           (this.Resources["anim"] as Storyboard).Begin();
    +       }
    +       private void Button_Click(object sender, RoutedEventArgs e)
    +       {
    +           (this.Resources["anim"] as Storyboard).Pause();
    +       }
    +
    +

    This example is shown in operation in the working example of Pause Bouncy Ball.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. For Silverlight + content with moving, blinking, scrolling or auto-updating content + that is the result of a running Silverlight animation:
    2. +
    3. Check for a mechanism to stop the movement, blinking, scrolling + or auto-updating.
    4. +
    5. Check that the movement, blinking, scrolling or auto-updating + stops when the mechanism is activated and does not restart by itself.
    6. +
    7. For pause, check that the animation can be restarted using a start + mechanism.
    8. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL12.html b/techniques/silverlight/SL12.html new file mode 100644 index 0000000000..6b10614a9f --- /dev/null +++ b/techniques/silverlight/SL12.html @@ -0,0 +1,142 @@ +Pausing, Stopping, or Playing Media in Silverlight MediaElements

    Pausing, Stopping, or Playing Media in Silverlight MediaElements

    ID: SL12

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to create a control user interface + for the Silverlight MediaElement object. The controls + enable users to pause or stop the video to prevent the video images + on the MediaElement surface from moving, and stop + video-associated audio. These UI controls enable an interaction defined + in code event handlers. Each handler calls one of the following MediaElement methods:

    + +

    Note that by default, a MediaElement will start playing + its media as soon as the UI loads completely AND the media source file + is downloaded (or a certain buffer size is reached, in the case of + streaming media). Use the AutoPlay property to change + this default.

    +

    Examples

    +
    +

    Providing MediaElement controls in the UI

    + +

    This example has a UI definition in XAML and interaction logic in + C#.

    +
    <UserControl x:Class="MediaElementControls.MainPage"
    +  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    + >
    +  <Grid x:Name="LayoutRoot">
    +      <StackPanel>
    +          <MediaElement x:Name="media" Source="/xbox.wmv"
    +         Width="300" Height="300" 
    +         AutomationProperties.Name="Video of new Fable game for XBox"           
    +      />
    +          <Grid Name="UIControls">
    +              <Grid.ColumnDefinitions>
    +                  <ColumnDefinition Width="*" />
    +                  <ColumnDefinition Width="*" />
    +                  <ColumnDefinition Width="*"/>
    +              </Grid.ColumnDefinitions>
    +              <Grid.RowDefinitions>
    +                  <RowDefinition Height="*" />
    +                  <RowDefinition Height="Auto" />
    +                  <RowDefinition Height="20" />
    +              </Grid.RowDefinitions>
    +              <Button Click="StopMedia" 
    +   Grid.Column="0" Grid.Row="1" Content="Stop" />
    +              <Button Click="PauseMedia" 
    +   Grid.Column="1" Grid.Row="1" Content="Pause" />
    +              <Button Click="PlayMedia" 
    +   Grid.Column="2" Grid.Row="1" Content="Play" />
    +              <Button Click="MuteMedia" 
    +  Grid.Row="2" Grid.Column="0" Content="Mute" />
    +              <TextBlock Name="VolumeLabel" Grid.Row="2" Grid.Column="1" HorizontalAlignment="Right">Volume</TextBlock>
    +              <Slider Height="20"
    +          Value="{Binding Volume, Mode=TwoWay, ElementName=media}"
    +          Minimum="0" Maximum="1"
    +          Grid.Row="2" Grid.Column="2" Grid.ColumnSpan="2"
    +              AutomationProperties.LabeledBy="{Binding ElementName=VolumeLabel}"/>
    +          </Grid>
    +      </StackPanel>
    +  </Grid>
    +</UserControl>
    +
    +private void StopMedia(object sender, RoutedEventArgs e)
    +{
    +    media.Stop();
    +}
    +private void PauseMedia(object sender, RoutedEventArgs e)
    +{
    +    media.Pause();
    +}
    +private void PlayMedia(object sender, RoutedEventArgs e)
    +{
    +    media.Play();
    +}
    +private void MuteMedia(object sender, RoutedEventArgs e)
    +{
    +    Button target = sender as Button;
    +    // mute if not muted, unmute if already muted, in either case make sure the button content for text and accessibility info is updated
    +    if (!media.IsMuted)
    +    {
    +        media.IsMuted = true;
    +        target.Content = "Unmute";
    +    }
    +    else
    +    {
    +         media.IsMuted = false;
    +         target.Content = "Mute";
    +     }
    +}
    +
    +

    This example is shown in operation in the working example of Media Element Controls.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. The application + is expected to incorporate a MediaElement in the + user interface.
    2. +
    3. Check that interactive controls are available so that users can + pause or stop the media.
    4. +
    5. Check that when activated, the controls stop or pause the media.
    6. +
    +
    +

    Expected Results

    +

    #2 and #3 are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL13.html b/techniques/silverlight/SL13.html new file mode 100644 index 0000000000..a15c5c0ef5 --- /dev/null +++ b/techniques/silverlight/SL13.html @@ -0,0 +1,299 @@ +Providing A Style Switcher To Switch To High Contrast

    Providing A Style Switcher To Switch To High Contrast

    ID: SL13

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to incorporate high contrast color + choices into a user interface visual design for Silverlight, by changing + the values of styles or templates, or changing values of individual + resources such as brushes or colors.

    +

    Silverlight styles and templates are produced in XAML. Silverlight + event handlers (such as the ones that engage the style switch) are + written in code, but are often wired through a method name reference + in the XAML. For more information on how to use templates, styles and + resources to change the appearance of Silverlight controls, see Control + Customization topic on MSDN.

    +

    Silverlight provides a built-in property that can determine whether + the hosting operating system is using a high contrast theme. This is + a Boolean value only; Silverlight API cannot determine any further + specifics about the theme choice, such as the colors being used or + the contrast ratio between the colors. Querying this property at application + startup is one possible trigger mechanism for applying high contrast + themes to Silverlight content. Another mechanism is to expose a control + (such as a button or text link) to the user, so that the user can engage + high contrast for a Silverlight application's content by activating + a control within the Silverlight application.

    +
    +

    Silverlight Toolkit themes and System Colors

    +

    An extension to the Silverlight core deliverables known as the Silverlight + Toolkit provides theming APIs and various themed styles for Silverlight + controls, including the core controls. Most of these themes are intended + for design purposes, but the Silverlight Toolkit also provides a System + Colors theme. The System Colors theme aligns the Silverlight theme + brushes or colors with those of the settings applied to the Microsoft + Windows operating system display options. When the user switches the + system themes to use a theme that is typically used for high contrast, + the underlying system brushes are redefined. A Silverlight application + that uses the System Colors theme also uses the now-redefined colors + in its UI, and will effectively use the same High Contrast colors that + are user-selected for all other display. How to use the Silverlight + Toolkit system themes is not described in this technique. However, + the Silverlight Toolkit theme system is a viable option for providing + high contrast as well as other more aesthetics-oriented UI experiences. + For more information about the Silverlight Toolkit, see Toolkit + site. The themes feature of Silverlight Toolkit is best explained + by Silverlight + Toolkit release notes (from a Microsoft-related blog).

    +
    +
    +

    Real-time changes not supported

    +

    + SystemParameters.HighContrast is an adequate trigger + for cases where high contrast is already engaged before the Silverlight + plugin is loaded into a host. However, a limitation of using SystemParameters.HighContrast as + a trigger mechanism is that Silverlight does not detect the change + if it happens after the Silverlight plugin is loaded by the host HTML. + If Silverlight authors want to support real-time changes, they should provide a user-initiated + control option for changing to high contrast in Silverlight UI rather + than solely relying on SystemParameters.HighContrast.

    +
    +
    +

    Silverlight and CSS

    +

    Silverlight content does not use information that comes from a CSS + style as applied to the hosting HTML page. Therefore, techniques as + implemented by browser user agents and described by G148: + Not specifying background color, not specifying text color, and not + using technology features that change those defaults or G156: + Using a technology that has commonly-available user agents that can + change the foreground and background of blocks of text do not work + for Silverlight content, and C29 does + not directly apply. For example, the Internet Explorer settings under + Options / Appearance do not affect the fonts or contrast in the Silverlight + content area.

    +
    +

    Examples

    +
    +

    Silverlight application designed with brush resources + and template resources that enable a high contrast switch

    + +

    The example "application" for illustration is just text, + a button and border. The concepts shown in the example can scale to + any complexity of UI, including to applications that have thousands + of lines of XAML. Note that the visual appearance of the button is + already using a high contrast theme choice for its default state, to + assure that the control is visible to anyone that requires a high contrast + theme to see parts of the user interface per G174. + To keep the example simple, the visual states (behaviors) associated + with mouse-over, click, etc. have not been restyled for high contrast. + Only the base appearance is changed. The example also shows a technique + of storing original theme information and restoring it in response + to user request.

    +
    <UserControl x:Class="HighContrast.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +   xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    +   xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    +   mc:Ignorable="d"
    +   d:DesignHeight="300" d:DesignWidth="400">
    +   <UserControl.Resources>
    +       <SolidColorBrush x:Key="ArtsyBrush1" Color="Salmon"/>
    +       <SolidColorBrush x:Key="ArtsyBrush2" Color="Bisque"/>
    +       <SolidColorBrush x:Key="ArtsyBrush3" Color="DarkSalmon"/>
    +       <SolidColorBrush x:Key="ArtsyBrush4" Color="Blue"/>
    +       <Color x:Key="ArtsyBrush1Restore">Salmon</Color>
    +       <Color x:Key="ArtsyBrush2Restore">Bisque</Color>
    +       <Color x:Key="ArtsyBrush3Restore">DarkSalmon</Color>
    +       <Color x:Key="ArtsyBrush4Restore">Blue</Color>
    +       <RadialGradientBrush x:Key="ArtsyGradient">
    +           <GradientStop Color="AliceBlue" Offset="0"/>
    +           <GradientStop Color="LightBlue" Offset="0.4"/>
    +           <GradientStop Color="#D00000EE" Offset="1"/>
    +       </RadialGradientBrush>
    +       <Style x:Key="ArtsyButton" TargetType="Button">
    +           <Setter Property="Template">
    +               <Setter.Value>
    +                   <ControlTemplate TargetType="Button">
    +                       <Border CornerRadius="4"
    +                          BorderBrush="{StaticResource ArtsyBrush4}" BorderThickness="4">
    +                           <Grid>
    +                               <Rectangle Fill="{StaticResource ArtsyGradient}"
    +                                 RadiusX="2" RadiusY="2"/>
    +                               <ContentPresenter Content="{TemplateBinding Content}"
    +                               ContentTemplate="{TemplateBinding ContentTemplate}"/>
    +                           </Grid>
    +                           
    +                       </Border>
    +                   </ControlTemplate>
    +               </Setter.Value>
    +           </Setter>
    +       </Style>
    +       <Style x:Key="HighConButton" TargetType="Button">
    +           <Setter Property="Control.Background" Value="White"/>
    +           <Setter Property="BorderBrush" Value="Black"/>
    +           <Setter Property="Foreground" Value="Black"/>
    +       </Style>
    +   </UserControl.Resources>
    +   <Border BorderBrush="{StaticResource ArtsyBrush1}" BorderThickness="4">
    +       <StackPanel x:Name="LayoutRoot" Background="{StaticResource ArtsyBrush2}">
    +           <TextBlock
    +             Foreground="{StaticResource ArtsyBrush3}">High contrast demo</TextBlock>
    +           <Button Name="Switcher" Click="Switcher_Click"
    +             Width="160" Style="{StaticResource HighConButton}">
    +              <TextBlock Text="Switch to high contrast"/>
    +           </Button>
    +           <Button Name="Switchback" Click="Switchback_Click"
    +             Width="160" Style="{StaticResource HighConButton}" IsEnabled="False">
    +               <TextBlock Text="Switch to regular theme"/>
    +           </Button>
    +       </StackPanel>
    +   </Border>
    +</UserControl>
    +
    +

    The second listing is the C# code for the event handlers.

    +
           private void Switcher_Click(object sender, RoutedEventArgs e)
    +       {
    +           ChangeToHighCon();
    +       }
    +       private void ChangeToHighCon()
    +       {
    +           (this.Resources["ArtsyBrush1"] as SolidColorBrush).Color = Colors.Black;
    +           (this.Resources["ArtsyBrush2"] as SolidColorBrush).Color = Colors.White;
    +           (this.Resources["ArtsyBrush3"] as SolidColorBrush).Color = Colors.Black;
    +           (this.Resources["ArtsyBrush4"] as SolidColorBrush).Color = Colors.Black;
    +           Switcher.IsEnabled = false;
    +           Switchback.IsEnabled = true;
    +       }
    +       private void RestoreRegularCon()
    +       {
    +           (this.Resources["ArtsyBrush1"] as SolidColorBrush).Color =
    +             (Color)this.Resources["ArtsyBrush1Restore"];
    +           (this.Resources["ArtsyBrush2"] as SolidColorBrush).Color =
    +             (Color)this.Resources["ArtsyBrush2Restore"];
    +           (this.Resources["ArtsyBrush3"] as SolidColorBrush).Color =
    +           (Color)this.Resources["ArtsyBrush3Restore"];
    +           (this.Resources["ArtsyBrush4"] as SolidColorBrush).Color =
    +             (Color)this.Resources["ArtsyBrush4Restore"];
    +           Switcher.IsEnabled = true;
    +           Switchback.IsEnabled = false;
    +       }
    +       private void Switchback_Click(object sender, RoutedEventArgs e)
    +       {
    +           RestoreRegularCon();
    +       }
    +   }
    +
    +

    The following images show the original, and the applied high contrast + settings.

    +
    + + +
    Low contrast image with "switch to high contrast" button enabled
    + +
    +
    + + +
    High contrast image with "switch to regular theme" button enabled
    + +
    +

    This example is shown in operation in the working example of High Contrast.

    + +
    +
    +

    Use SystemParameters.HighContrast to detect system high + contrast settings at application startup

    + +

    This example uses the same UI and style definitions as the previous + example. The sole addition a case statement that is added to the primary + page constructor of the UI (defined in C#). The added code is everything + other than the InitializeComponent() call (which is part of Silverlight + infrastructure). Note that the added code calls a user-defined function + ChangeToHighCon(), which is the same function and behavior as shown + in Example 1 for the user-initiated high contrast switch.

    +
           public MainPage()
    +       {
    +           InitializeComponent();
    +           if (SystemParameters.HighContrast)
    +           {
    +               ChangeToHighCon();
    +           }
    +       }
    +
    + +
    +

    Tests

    +
    +

    UI option for style switching

    +

    Procedure

    +

    To test a Silverlight UI option for style switching (Example 1):

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Check for a control that indicates it will change the application's + appearance to use a high-contrast theme.
    4. +
    5. Activate the control. Check that the Silverlight application's + user interface color themes change to an appearance that uses at + least a 4.5:1 contrast ratio per Success + Criterion 1.4.3 (Contrast (Minimum)).
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +
    +

    HighContrast API

    +

    Procedure

    +

    To test the HighContrast API (Example 2):

    +
      +
    1. Use operating system settings (such as Ctrl+LeftShift+PrtScn shortcut + on Windows 7) to enter high contrast mode prior to opening the test + page.
    2. +
    3. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    4. +
    5. Check that the Silverlight application's user interface color + themes change to an appearance that uses at least a 4.5:1 contrast + ratio per Success + Criterion 1.4.3 (Contrast (Minimum)).
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +
    +

    UI option for enhanced contrast

    +

    Procedure

    +

    To test a Silverlight UI option for style switching for enhanced contrast:

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Check for a control that indicates it will change the application's + appearance to use an enhanced contrast theme.
    4. +
    5. Activate the control. Check that the Silverlight application's + user interface color themes change to an appearance that uses at + least a 7:1 contrast ratio per Success + Criterion 1.4.6 Contrast (Enhanced).
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    diff --git a/techniques/silverlight/SL14.html b/techniques/silverlight/SL14.html new file mode 100644 index 0000000000..44eeb14973 --- /dev/null +++ b/techniques/silverlight/SL14.html @@ -0,0 +1,278 @@ +Providing Custom Control Key Handling for Keyboard Functionality + in Silverlight

    Providing Custom Control Key Handling for Keyboard Functionality + in Silverlight

    ID: SL14

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to implement built-in handling + of key events in a custom control. If a custom control is correctly + implemented, then any Silverlight applications that include the control + can rely on the built-in key handling for some or all of the desired + keyboard equivalence of a control's functionality.

    +

    Defining a custom control requires that the control author write a + default template for the control and also the initialization logic, + including the default implementations for built-in keyboard equivalence. + Typically, control authors provide keyboard equivalence for any actions + that can be activated by a mouse click on the control surface, and + that are not already providing a keyboard equivalence through the implementation + of a composite part.

    +

    All input events report a specific source that is communicated to + handler code as an event parameter, so that the application author + can identify which element in their Silverlight UI was being interacted + with, and the application can perform an action that is relevant to + that user input. In the case of mouse events, the event source is the + element that the mouse pointer is over at the time. In the case of + key events, the event source is the element that has focus. The element + that has focus is visually indicated so that the user knows which element + they are interacting with (see ). Assistive technologies + often have parallel conventions whereby the user is made aware of which + element is visually focused and is the current input scope presented + by the assistive technology.

    +
    +

    Browser hosts and keyboard events

    +

    Silverlight is hosted as a plug-in inside a browser host. The Silverlight + runtime only receives the input events that the browser host forwards + to hosted plug-ins through a browser-specific program access layer. + Occasionally the browser host receives input that the browser host + itself handles in some way, and does not forward the keyboard event. + An example is that a Silverlight application hosted by an Internet + Explorer browser host on Windows operating system cannot detect a press + of the ALT key, because Internet Explorer processes this input and + performs the action of bringing keyboard focus to the Internet Explorer + menu bar. Silverlight authors might need to be aware of browser-specific + input handling models and not rely on key events for keys that are + essentially reserved for use by a browser host. For more information, + see Keyboard + Support.

    +

    Application authors should choose keys that avoid browser conflicts, + but still are a natural choice for an accelerator. Using the CTRL key + as a modifier is a convention that is frequently used in existing Silverlight + applications.

    +
    +
    +

    Informing users of which keys to use for keyboard equivalence

    +

    If a control supports user interaction, which key to use to engage + the keyboard equivalent behavior is not always obvious. One way to + inform users of the possible key options that a control supports is + to author an AutomationProperties.HelpText value in + the application UI that gives instructions such as "Press the + plus key to increment value". This is up to the application author + to do; the control definitions do not provide a means to set HelpText + by default, because any display technique for end user help is potentially + too application-specific to be encapsulated in control definitions. + Application authors might also consider using tooltips, providing a + menu framework that visually indicates the key associations (perhaps + with the Windows key-underlined convention), providing a generalized + application Help, or displaying plain text in the user interface.

    +
    +
    +

    The On* method pattern in Silverlight

    +

    Silverlight classes often have methods that follow the naming pattern On* where + the star is a string that also identifies an event. These On* methods + are prewired event handlers, defined as virtual methods so that subclasses + can override them. A consumer of a control class can change or augment + the default behavior associated with that event by overriding the method, + and typically also calls the base implementation so that the base functionality + is preserved. This principle is illustrated in Example 1 by the overrides + of OnGotFocus and OnLostFocus. Controls that introduce new events should + consider also exposing a virtual On* method that pairs with the event, + so that consumers of the custom control can use the same pattern.

    +
    +

    Examples

    +
    +

    KeyNumericUpDown Control That Handles Arrow Key Equivalence + for + and - Buttons

    + +

    This example implements a custom Silverlight control that displays + an integer value, and can increment or decrement the integer value + based on user actions. When a user interacts with the control, the + user can click the "+" and "-" buttons that are + component parts of the control. The "+" and "-" button + parts are deliberately not in the Silverlight tab sequence, because + this is intended to be a complete control, where only the control itself + (and not its constituent parts) are focusable and are reported as an + element to the accessibility framework. To provide keyboard equivalence, + the control defines a KeyUp handler. The design of + the control treats an Up Arrow key press as equivalent to activating + the "+" button, and the Down Arrow key as equivalent to activating + the "-" button. The control implementation reinforces this + behavior by having the button Click event handlers + and the cases of the KeyUp handler call the same underlying + helper functions (Increment() and Decrement()).

    +

    Handling the + and - keys as alternate or additional keyboard equivalents + for the actions is also possible (if that is desired, handler would + check for Key.Add or Key.Subtract values).

    +

    The following is the XAML-defined control template for this control.

    +
       <Style TargetType="local:KeysNumericUpDown">
    +       <Setter Property="BorderThickness" Value="1"/>
    +       <Setter Property="Height" Value="22"/>
    +       <Setter Property="BorderBrush">
    +           <Setter.Value>
    +               <LinearGradientBrush EndPoint="0.5,1" StartPoint="0.5,0">
    +                   <GradientStop Color="#FFA3AEB9" Offset="0"/>
    +                   <GradientStop Color="#FF8399A9" Offset="0.375"/>
    +                   <GradientStop Color="#FF718597" Offset="0.375"/>
    +                   <GradientStop Color="#FF617584" Offset="1"/>
    +               </LinearGradientBrush>
    +           </Setter.Value>
    +       </Setter>
    +       <Setter Property="Template">
    +           <Setter.Value>
    +               <ControlTemplate TargetType="local:KeysNumericUpDown">
    +                   <Grid x:Name="CompositionRoot">
    +                       <Grid.ColumnDefinitions>
    +                           <ColumnDefinition/>
    +                           <ColumnDefinition/>
    +                       </Grid.ColumnDefinitions>
    +                       <TextBox x:Name="Text" IsTabStop="False" AcceptsReturn="False"
    + BorderThickness="0" Foreground="{TemplateBinding Foreground}" FontWeight="{TemplateBinding FontWeight}"
    + FontStyle="{TemplateBinding FontStyle}" FontStretch="{TemplateBinding FontStretch}"
    + FontSize="{TemplateBinding FontSize}" FontFamily="{TemplateBinding FontFamily}" MinWidth="20"
    + TextAlignment="Right" VerticalAlignment="Center"  TextWrapping="NoWrap" Text="{TemplateBinding Value}">
    +                               <TextBox.Style>
    +                                   <Style TargetType="TextBox">
    +                                       <Setter Property="Template">
    +                                           <Setter.Value>
    +                                               <ControlTemplate TargetType="TextBox">
    +                                                   <ScrollViewer x:Name="ContentElement" BorderThickness="0" Padding="0"/>
    +                                               </ControlTemplate>
    +                                           </Setter.Value>
    +                                       </Setter>
    +                                   </Style>
    +                               </TextBox.Style>
    +                           </TextBox>
    +                       <StackPanel Orientation="Vertical" Grid.Column="1">
    +                       <Button Width="18" Height="18" IsTabStop="False" x:Name="plusButton">+</Button>
    +                       <Button Width="18" Height="18" IsTabStop="False" x:Name="minusButton">-</Button>
    +                       </StackPanel>
    +                       <Border x:Name="FocusVisualElement" BorderBrush="#FF45D6FA" BorderThickness="{TemplateBinding BorderThickness}" 
    +                       CornerRadius="1,1,1,1" IsHitTestVisible="False" Opacity="0"/>
    +                   </Grid>
    +               </ControlTemplate>
    +           </Setter.Value>
    +       </Setter>
    +   </Style>
    +   
    +

    The following is the implementation of the control class. Overrides + of the base class are omitted for clarity, as is automation support. + Note the event wiring in OnApplyTemplate; this is + a common pattern for custom control definitions.

    +
       public class KeysNumericUpDown : UpDownBase<double>
    +   {
    +       Grid root;
    +       Button plusButton;
    +       Button minusButton;
    +       Border focusRect;
    +       public KeysNumericUpDown()
    +       {
    +           this.DefaultStyleKey = typeof(KeysNumericUpDown);
    +       }
    +       public override void OnApplyTemplate()
    +       {
    +           base.OnApplyTemplate();
    +           root = this.GetTemplateChild("CompositionRoot") as Grid;
    +           root.KeyUp += new KeyEventHandler(Handle_Accelerators);
    +           plusButton = this.GetTemplateChild("plusButton") as Button;
    +           minusButton = this.GetTemplateChild("minusButton") as Button;
    +           plusButton.Click += new RoutedEventHandler(plusButton_Click);
    +           minusButton.Click += new RoutedEventHandler(minusButton_Click);
    +           focusRect = this.GetTemplateChild("FocusVisualElement") as Border;
    +       }
    +       void plusButton_Click(object sender, EventArgs e)
    +       {
    +           Increment();
    +       }
    +       void minusButton_Click(object sender, EventArgs e)
    +       {
    +           Decrement();
    +       }
    +       private void Increment()
    +       {
    +           this.Value += 1;
    +       }
    +       private void Decrement()
    +       {
    +           this.Value -= 1;
    +       }
    +       private void Handle_Accelerators(object sender, KeyEventArgs e)
    +       {
    +           switch (e.Key)
    +           {
    +               case (Key.Up):
    +                   this.Value -= 1;
    +                   e.Handled = true;
    +                   break;
    +               case (Key.Down):
    +                   this.Value += 1;
    +                   e.Handled = true;
    +                   break;
    +               default: break;
    +           }
    +       }
    +       protected override void OnGotFocus(RoutedEventArgs e)
    +       {
    +           base.OnGotFocus(e);
    +           if (focusRect != null)
    +           {
    +               focusRect.Opacity = 1;
    +           }
    +       }
    +       protected override void OnLostFocus(RoutedEventArgs e)
    +       {
    +           base.OnLostFocus(e);
    +           focusRect.Opacity = 0;
    +       }
    +   }
    +   
    +

    When this control is included in application UI, the usage is very + simple. Note that there are no key handlers on this instance; the + necessary key handling to wire up the increment/decrement logic is + already built-in to all instances of the control.

    +
    <local:KeysNumericUpDown Width="100" Height="45"/>
    +
    +

    This example is shown in operation in the working example of Numeric Up / Down control.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Press TAB key to move keyboard focus to various element parts + of the user interface, and in particular to areas that are known + to be custom control implementations.
    4. +
    5. Check that custom key commands exist for all these user interface + actions and that these key commands are made known to the user.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL15.html b/techniques/silverlight/SL15.html new file mode 100644 index 0000000000..2038402bca --- /dev/null +++ b/techniques/silverlight/SL15.html @@ -0,0 +1,226 @@ +Providing Keyboard Shortcuts that Work Across the Entire Silverlight + Application

    Providing Keyboard Shortcuts that Work Across the Entire Silverlight + Application

    ID: SL15

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to introduce key handling that + exists at the application root level of a Silverlight application, + rather than per-element key handling. Event handling at the application + level as opposed to at the element level is one way to address key + equivalence. The key events provide key equivalence for particular + user interface elements that a user might otherwise interact with using + a mouse. This technique is related to events in the Silverlight programming + model, as opposed to in the HTML DOM.

    +

    Handling key events at the root level of an application rather than + only on the element that was the "source" of a key event + is possible because of a Silverlight programming model feature known + as event routing. For more information on event routing and how it + works, see Events + Overview for Silverlight.

    +

    This technique demonstrates a "menu" approach to key handling + and user interaction. This technique is presented as a companion to , which + can be thought of as an "accelerator key/hotkey" approach. + The "menu" approach towards keyboard equivalence is perhaps + just as common as the "hotkey" approach. It is often simpler + to document a menu's key equivalence in a user interface than it is + to document key equivalents of particular regions of an application, + or to communicate to users that where the current focus is placed is + relevant to how keyboard keys are interpreted by the application, even + if the key action is relevant to only one of the controls in an interface. + If all keys are handled at the top level, the specific focused element + is no longer relevant.

    +

    In order to originate a key event that Silverlight application code + can detect, some element in the Silverlight application must have keyboard + focus. One way to assure keyboard focus is to focus the Silverlight + plug-in as a whole, as called from within an event handler for Application.Startup. + This is shown in the examples.

    +

    If an application does handle keys at top level, care should be taken + to not interfere with specific text entry control behavior, such as + typing into a TextBox. To avoid interactions, the + design of key equivalence at the top level of an application typically + relies on combinations with key modifiers. The Control/CTRL key is + a key that is often used for this purpose. Application authors should + also be aware of the implications of browser hosts that might handle + the key event at HTML DOM level without making that event available + to the Silverlight programming surface. For more information on this + concept, see "Keyboard Events and Browser Hosts" section + of Keyboard + Support Overview for Silverlight on MSDN.

    +

    Application authors are responsible for correctly documenting the + accelerator keys that are pertinent for their application. There are + a variety of techniques for documenting user interface actions that + are not described here. One possible suggestion is to include a generalized "Help" button + that appears early in the application's reading order, which is focusable + and has an AutomationProperties.Name value available as the text content + or equivalent. Such a button can be activated without knowing any of + the application's accelerator keys, and the activation result could + be a new text element that enumerates the possible keys. For example, + the application could display a Silverlight Popup with + the following content:

    +
    + + +
    A screen shot of a sample Popup control that documents specific accelerator keys
    + +
    +

    Examples

    +
    +

    Key handling by application root UserControl

    + +

    This example has only one interactive control for simplicity, but + with two possible key combinations for that control being handled as + actions. The purpose and explanation of the control is reported through + a TextBlock that is associated with the labeled control + through use of AutomationProperties.LabeledBy in + XAML. The control being illustrated is MultiScaleImage, + which supports a zoom-in metaphor for examining an image that redraws + at increasingly fine resolutions. For more information on MultiScaleImage, + see Deep + Zoom on MSDN.

    +

    The following is the startup logic at application level that sends + focus to Silverlight in the HTML DOM.

    +
           private void Application_Startup(object sender, StartupEventArgs e)
    +       {
    +           this.RootVisual = new MainPage();
    +           //bring overall DOM focus to Silverlight area, so that keys are captured by Silverlight
    +           System.Windows.Browser.HtmlPage.Plugin.Focus();
    +       }
    +       
    +

    The following is XAML UI for the main page.

    +
     <UserControl xmlns:sdk="http://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk"
    +    x:Class="ApplicationLevelKeyHandling.MainPage"
    +    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    +    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    +    mc:Ignorable="d"
    +    d:DesignHeight="300" d:DesignWidth="400" KeyUp="UserControl_KeyUp">
    +
    +    <StackPanel x:Name="LayoutRoot" Background="White">
    +        <Button Name="bInstructions" Click="bInstructions_Click">Get Help</Button>
    +        <Popup Name="p">
    +            <Grid>
    +                <Grid.RowDefinitions>
    +                    <RowDefinition/>
    +                    <RowDefinition/>
    +                    <RowDefinition/>
    +                    <RowDefinition/>
    +                </Grid.RowDefinitions>
    +                <Grid.ColumnDefinitions>
    +                    <ColumnDefinition/>
    +                    <ColumnDefinition/>
    +                </Grid.ColumnDefinitions>
    +                <TextBlock FontWeight="Bold">Key</TextBlock>
    +                <TextBlock FontWeight="Bold" Grid.Column="1">Action</TextBlock>
    +                <TextBlock Grid.Row="1">Ctrl + Alt + Plus</TextBlock>
    +                <TextBlock Grid.Row="1" Grid.Column="1">Zooms in on the image</TextBlock>
    +                <TextBlock Grid.Row="2">Ctrl + Alt + Minus</TextBlock>
    +                <TextBlock Grid.Row="2" Grid.Column="1">Zooms out of the image</TextBlock>
    +                <Button Grid.Row="3" Click="button1_Click">Close this Help</Button>
    +            </Grid>
    +        </Popup>
    +        <MultiScaleImage x:Name="deepZoomObject"
    +         Source="source/dzc_output.xml" 
    +         MouseLeftButtonDown="DeepZoomObject_MouseLeftButtonDown"
    +         MouseRightButtonDown="DeepZoomObject_MouseRightButtonDown"
    +         AutomationProperties.LabeledBy="{Binding ElementName=lblInstructions}"/>
    +    </StackPanel>
    + </UserControl>
    +

    The following is the C# logic. Note how the key handlers and mouse + handlers reference the same logic function.

    +
            private void UserControl_KeyUp(object sender, KeyEventArgs e)
    +        {
    +            if ((Keyboard.Modifiers & ModifierKeys.Control) == ModifierKeys.Control &&
    +                (Keyboard.Modifiers & ModifierKeys.Alt) == ModifierKeys.Alt &&
    +                e.Key == Key.Add)
    +            {
    +                DZIn();
    +            }
    +            if ((Keyboard.Modifiers & ModifierKeys.Control) == ModifierKeys.Control &&
    +                (Keyboard.Modifiers & ModifierKeys.Alt) == ModifierKeys.Alt &&
    +                e.Key == Key.Subtract)
    +            {
    +                DZOut();
    +            }
    +        }
    +        private void DeepZoomObject_MouseLeftButtonDown(object sender, MouseButtonEventArgs e)
    +        {
    +            DZIn();
    +        }
    +        private void DeepZoomObject_MouseRightButtonDown(object sender, MouseButtonEventArgs e)
    +        {
    +            e.Handled = true;
    +            DZOut();
    +        }
    +        private void DZIn()
    +        {
    +            this.deepZoomObject.ZoomAboutLogicalPoint(3, .5, .5);
    +        }
    +        private void DZOut()
    +        {
    +            this.deepZoomObject.ZoomAboutLogicalPoint(.333, .5, .5);
    +        }
    +        private void bInstructions_Click(object sender, RoutedEventArgs e)
    +        {
    +
    +            // Set where the popup will show up on the screen.
    +            p.VerticalOffset = 25;
    +            p.HorizontalOffset = 25;
    +            // Open the popup.
    +            p.IsOpen = true;
    +        }
    +        void button1_Click(object sender, RoutedEventArgs e)
    +        {
    +            // Close the popup.
    +            p.IsOpen = false;
    +
    +        }
    +

    This example is shown in operation in the working example of Application Level Key Handling.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Verify that keyboard focus is somewhere within the Silverlight + content area, and not elsewhere in the hosting HTML or hosting browser + user interface. If necessary, use TAB key to traverse the overall + HTML tab sequence until an interface element within Silverlight displays + a visual focus indicator.
    4. +
    5. Verify that the keys to be used as keyboard equivalent action + triggers for the application as a whole are documented for users. + For example, text or long text alternative documents key / key combinations + and short descriptions of actions.
    6. +
    7. Verify that pressing the application-specific keys results in + the action as expected in the application.
    8. +
    9. Move keyboard focus throughout other areas of the Silverlight + application, and verify that the same keys continue to function application-wide.
    10. +
    +
    +

    Expected Results

    +

    #3, #4 and #5 are true.

    +
    +

    Resources

    + + + +
    diff --git a/techniques/silverlight/SL16.html b/techniques/silverlight/SL16.html new file mode 100644 index 0000000000..241b64595f --- /dev/null +++ b/techniques/silverlight/SL16.html @@ -0,0 +1,120 @@ +Providing Script-Embedded Text Captions for MediaElement Content

    Providing Script-Embedded Text Captions for MediaElement Content

    ID: SL16

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use text captioning that is + embedded in the stream with media displayed in a Silverlight MediaElement, + and present that text captioning in a separate Silverlight control + or text element.

    +

    This particular technique uses scripting files with a TimelineMarkers collection + that are embedded directly within the media file. When text captioning + is embedded directly in the streams, synchonization of the scripting + stream versus the video content stream is done automatically by the MediaElement component. + Each time the MarkerReached event fires, that is an + indication that a synch point in the video that corresponds to a script + marker entry has been reached. Silverlight application authors can + obtain the text from the relevant timeline marker entry through their + event handler implementations, and can display captions in the user + interface area where the text captions are displayed. Typical Silverlight + controls that can be used for displaying text captions include TextBlock (nonfocusable), TextBox, + or RichTextBox. A typical interface design would place + the caption-display control in close proximity to the MediaElement control + that is being captioned, for example might place the captions directly + underneath the MediaElement "screen".

    +

    Script-embedded captions are captions that are stored directly in + the media file as metadata, rather than as a separate file. For information + about techniques for captions in separate files, see .

    +
    +

    Tools

    +

    Producing the media file with TimelineMarkers captions + directly in embedded scripting can be accomplished using the Microsoft + Expression Encoder tool. Online help for the procedure of encoding + scripting with text captions in the stream are available in the offline + Help file that installs with the Microsoft Expression 4 Encoder products. + For more information, see Expression + Encoder Pro Overview.

    +

    There is a public + API for introducing Markers into a WMV file, as part of the Windows + Media Format SDK. Using Expression Encoder is the way that the task + of directly embedding TimelineMarkers is presented + and taught in Microsoft's available instructional material on Silverlight. + However, because the mechanism is public, it is possible that other + tools exist or will exist that can also produce media with script-encoded TimelineMarkers.

    +
    +

    Examples

    +
    +

    MediaElement handles MarkerReached, displays marker text + in existing TextBox

    + +

    This example has a UI definition in XAML and interaction logic in + C#. The following is the basic UI in XAML. This example is deliberately + simple and does not include AutomationProperties for + identification or user instructions. The most relevant part of this + example is that the Silverlight author declares a handler for the event MarkerReached. + This event fires potentially hundreds of times, once for each caption + in the stream. Each time the event fires, the event handler runs and + adds the text to the dedicated TextBox in the user + interface.

    +
    <UserControl x:Class="MediaTimelineMarkers.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    +   <StackPanel x:Name="LayoutRoot" Background="White">
    +       <MediaElement MarkerReached="OnMarkerReached"
    +       HorizontalAlignment="Left"
    +       Source="/spacetime.wmv"
    +       Width="300" Height="200" />
    +       <ScrollViewer>
    +           <TextBox Name="captionText" Height="40"
    +           IsReadOnly="true" AcceptsReturn="true"/>
    +       </ScrollViewer>
    +   </StackPanel>
    + </UserControl>
    +
    +private void OnMarkerReached(object sender, TimelineMarkerRoutedEventArgs e)
    +{
    +   captionText.Focus();
    +   captionText.SelectedText = e.Marker.Text.ToString() + "\n";
    +}
    +
    +

    This example is shown in operation in the working example of Media Timeline Markers.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. The application + plays media that is expected to have text captioning.
    2. +
    3. Check that a text area in the user interface shows captions for + the media.
    4. +
    +
    +

    Expected Results

    +

    # 2 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL17.html b/techniques/silverlight/SL17.html new file mode 100644 index 0000000000..1fb9871206 --- /dev/null +++ b/techniques/silverlight/SL17.html @@ -0,0 +1,144 @@ +Providing Static Alternative Content for Silverlight Media Playing + in a MediaElement

    Providing Static Alternative Content for Silverlight Media Playing + in a MediaElement

    ID: SL17

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to replace a Silverlight MediaElement with + static alternative non-media content that is not time-based. The static + alternative content replaces the media in the same or a nearby user + interface region of the Silverlight application.

    + +

    A Silverlight application user interface can be adjusted at run time + by removing elements from the visual tree, and adding new elements + to the visual tree. In this case, the user interface is designed to + provide a control that the user activates to display the static alternative + content, which is often a control that displays text, or a text element.

    +

    Examples

    +
    +

    MediaElement playing audio, replace with transcript

    + +

    This example has a UI definition in XAML and interaction logic in C#. In this case the MediaElement + has no visual representation itself and is 0x0 size because it plays audio only. As a simple placeholder, this + example displays the text "Library of Congress Audio" to represent the media element as something visible in the + UI. In addition to Play/Stop controls, this interface includes a Display Transcript button. Activating the + button displays static text that represents the transcript of the audio. The following is the basic UI in XAML.

    +
    <UserControl x:Class="ReplaceAudioWithTranscriptText.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +   xmlns:sys="clr-namespace:System;assembly=mscorlib">
    +   <UserControl.Resources>
    +       <sys:String x:Key="transSpeakerName">Matt Raymond: </sys:String>
    +       <sys:String x:Key="transText">This is Matt Raymond at the Library of Congress.
    +Each year thousands of book lovers of all ages visit the nation's capital to celebrate the joys 
    +of reading and lifelong literacy, at the Library of Congress National Book Festival. 
    +For the first time in the festival's nine year history, President Barack Obama and 
    +First Lady Michelle Obama will serve as honorary chairs of this free event. </sys:String>
    +   </UserControl.Resources>
    +   <StackPanel x:Name="LayoutRoot" Background="White" >
    +       <TextBlock FontSize="30" Foreground="Blue">Library of Congress Audio</TextBlock>
    +       <MediaElement Source="/locintro.wma" AutoPlay="False" Name="player" Height="0" />
    +       <StackPanel Orientation="Horizontal" Name="ControlBar">
    +           <Button Name="Play" Click="Play_Click">Play</Button>
    +           <Button Name="Stop" Click="Stop_Click">Stop</Button>
    +           <Button Name="TextAlt" Click="TextAlt_Click">Display Transcript</Button>
    +       </StackPanel>
    +   </StackPanel>
    +</UserControl>
    +
    +

    The following is the C# logic.

    +
       public partial class MainPage : UserControl
    +   {
    +       RichTextBox rtb;
    +       bool transDisplayed=false;
    +       public MainPage()
    +       {
    +           InitializeComponent();
    +           rtb = new RichTextBox();
    +           rtb.IsReadOnly = true;
    +           Paragraph p = new Paragraph();
    +           Run speakerName = new Run();
    +           speakerName.Text = this.Resources["transSpeakerName"] as String;
    +           speakerName.FontWeight = FontWeights.Bold;
    +           Run transText = new Run();
    +           transText.Text = this.Resources["transText"] as String;
    +           p.Inlines.Add(speakerName);
    +           p.Inlines.Add(transText);
    +           rtb.Blocks.Add(p);
    +       }
    +       private void Play_Click(object sender, RoutedEventArgs e)
    +       {
    +           player.Play();
    +           Play.IsEnabled = false;
    +       }
    +       private void Stop_Click(object sender, RoutedEventArgs e)
    +       {
    +           player.Stop();
    +           Play.IsEnabled = true;
    +       }
    +       private void TextAlt_Click(object sender, RoutedEventArgs e)
    +       {
    +           Panel parent = (player.Parent as Panel);
    +           if (!transDisplayed)
    +           {
    +               DisplayTranscript();
    +               (sender as Button).Content = "Hide Transcript";
    +               transDisplayed = true;
    +           }
    +           else
    +           {
    +               parent.Children.Remove(rtb);
    +               (sender as Button).Content = "Display Transcript";
    +               transDisplayed = false;
    +           }
    +       }
    +       private void DisplayTranscript()
    +       {
    +           Panel parent = (player.Parent as Panel);
    +           parent.Children.Add(rtb);
    +       }
    +
    +

    This example is shown in operation in the working example of Replace Audio With Transcript.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. That + application has audio-only media content and is expected to supply + a text alternative, or has media that is expected to be replaced + entirely with a transcript or similar text alternative.
    2. +
    3. Check for a control that indicates that activating it will supply + static alternative content for the media. Activate the control.
    4. +
    5. Verify that the media control is replaced with alternate content, + and that assistive technologies represent the change to the user + interface.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL18.html b/techniques/silverlight/SL18.html new file mode 100644 index 0000000000..2197ebbd0e --- /dev/null +++ b/techniques/silverlight/SL18.html @@ -0,0 +1,112 @@ +Providing Text Equivalent for Nontext Silverlight Controls With AutomationProperties.Name

    Providing Text Equivalent for Nontext Silverlight Controls With AutomationProperties.Name

    ID: SL18

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use the Silverlight AutomationProperties.Name property + to provide a short text alternative for controls that do not otherwise + contain text. The text is intended to provide human-readable identifiers + and short-descriptions or user instructions for accessibility frameworks, + which can then be reported to assistive technologies.

    +

    "Control" in this technique refers to any element that is + based on the Silverlight Control class, and is keyboard-focusable + either by user action or calling focus to the control programmatically. + The non-text control in question might be something like a button that + communicates information using only an icon or image. For example, + a triangle image rotated 90 degrees clockwise is commonly used in many + user interfaces to indicate a "Play" button control. This "Play" icon + mimics interface metaphors from many non-software consumer products, + and is often presented in a user interface without any nearby visible + text information that explains the purpose of the control. Another + example is a "thumbnail" metaphor where a small image serves + as a control that can be activated, and where the action results in + the display of a larger version of the same image, or enters an editing + mode that loads the same image.

    +

    For cases of controls such as buttons that invoke actions, the text + alternative also identifies link purpose.

    +

    In Silverlight, a text-only identifier for any control can be set + specifically as AutomationProperties.Name on the parent + control. Silverlight control compositing techniques enable either per-control + images that are specified by the application author, or a general-purpose + image/icon for a control that is part of the control's template and + displays that way by default. The Silverlight API AutomationProperties.Name directly + sets Name in the UI Automation tree. The properties + in the UI Automation tree are reported to assistive technologies, when + the assistive technology implements behavior that acts as a UI Automation + client (or as an MSAA client, which relies on the UIA-MSAA bridge).

    +

    Examples

    +
    +

    Applying a text alternative for an icon Button with + XAML

    + +

    Application authors can specify the AutomationProperties.Name attribute + on the Button element, and leave accessibility information + for the composited Image content unspecified. It is + the button and its action that is relevant to users, not the non-interactive Image component. + The value provided for AutomationProperties.Name is + a meaningful text alternative for the action conveyed by the button's + icon/image, but where the functionality is conceptually embodied in + the button and not its images or other constituent parts in compositing + or visual design.

    +
     <Button
    +   Height="20" Width="50"
    +   AutomationProperties.Name="Pause Media">
    +   <Image Height="12" Width="12" Source="/icon_pause.png"/>
    + </Button>
    +
    +

    This example is shown in operation in the working example of Button Text Alternative.

    + +
    +

    Tests

    +
    +

    Accessibility framework view

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Use a verification tool that is capable of showing the full accessibility + framework tree, and an object’s "Name" text alternative + as part of the tree. Verify that all interactive elements such as + buttons without visible text provide a human-readable text identifier "Name" in + the automation tree.
    4. +
    +
    +

    Expected Results

    +

    #2 is true.

    +
    +
    +

    Screen Reader

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Engage the screen reader. Press TAB to traverse the tab sequence + inside the Silverlight content area to focus to a composite control + that has no visible text, but has an AutomationProperties.Name applied.
    4. +
    5. Check that the "Name" as applied to the control instance, + along with the class name of the named control, is read by the screen + reader.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL19.html b/techniques/silverlight/SL19.html new file mode 100644 index 0000000000..74fa115251 --- /dev/null +++ b/techniques/silverlight/SL19.html @@ -0,0 +1,176 @@ +Providing User Instructions With AutomationProperties.HelpText in + Silverlight

    Providing User Instructions With AutomationProperties.HelpText in + Silverlight

    ID: SL19

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to provide a long text alternative + that serves the same purpose and presents the same information as the + original non-text content when a short text alternative is not sufficient, + and to show the practice of storing that information in a dedicated + property of the Silverlight-supported UI Automation support system. + The technique can also be used on text controls (such as TextBox), + for cases where the control text itself does not provide enough context + to suggest an appropriate user action.

    +

    The relevant UI Automation property is named HelpText, + to connote its possible usage to provide imperative instructions for + interactive elements. However, the same property can instead be used + for long text alternatives for nontext objects. The Silverlight API AutomationProperties.HelpText directly + sets HelpText in the UI Automation tree. The properties + in the UI Automation tree are reported to assistive technologies, when + the assistive technology implements behavior that acts as a UI Automation + client.

    +

    + AutomationProperties.HelpText can be set in code, + but is most typically set as an attribute in XAML that defines a Silverlight + UI.

    +

    The same information as is present in AutomationProperties.HelpText could + also be useful to sighted users. In this case, the same text could + be displayed in a Silverlight ToolTip control. + The reason that application authors should use both AutomationProperties.HelpText AND Tooltip in + conjunction is because the Tooltip information is + not introduced into the runtime accessibility framework information + set. This is because a tooltip is transient and not conventionally + focusable. In Silverlight programming, a useful technique for sharing + the same resource is to combine the Silverlight data binding feature + with the .NET Framework embedded resource feature. For more information + on combining Silverlight data binding and resources for common string + sources, see How + to Make XAML Content Localizable.

    +

    Examples

    +
    +

    Applying a long text alternative for an Image with XAML

    + +

    To introduce the necessary information to Silverlight XAML for an + application UI definition, specify the AutomationProperties.HelpText attribute + on the Image element. The value provided for the attribute + is a meaningful long text alternative for the image content. The value + of AutomationProperties.HelpText should augment rather + than duplicate AutomationProperties.Name, which is + also typically specified to provide accessibility support for an image.

    +
     <Image
    +   Height="400" Width="600"
    +   Source="/office.png"
    +   AutomationProperties.Name="Diagram of standard office layout"
    +   AutomationProperties.HelpText="The standard office layout
    +includes one corner desk unit in the corner farthest from the
    +door, and one file cabinet against the same wall as the door."/>
    +
    + +
    +
    +

    Using HelpText as form instructions

    + +

    This example provides instructions for two form fields by using both Tooltip and AutomationProperties.HelpText. + The strings used for these purposes are shared to both methodologies + by defining the strings as resources and binding to them. In this example, + the form submission does not perform client-side validation (although + server-side validation following a data round trip might still exist).

    +

    The following is the XAML UI:

    +
    <UserControl xmlns:sdk="http://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk" 
    +   x:Class="HelpTextAndToolTip.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    +       <Grid x:Name="LayoutRoot" Background="White" Margin="10">
    +           <Grid.RowDefinitions>
    +               <RowDefinition Height="Auto"/>
    +               <RowDefinition Height="Auto"/>
    +               <RowDefinition Height="Auto"/>
    +               <RowDefinition Height="Auto"/>
    +               <RowDefinition Height="Auto"/>
    +           </Grid.RowDefinitions>
    +           <Grid.ColumnDefinitions>
    +               <ColumnDefinition Width="Auto"/>
    +               <ColumnDefinition Width="200"/>
    +               <ColumnDefinition Width="Auto"/>
    +           </Grid.ColumnDefinitions>
    +           <TextBlock Text="Form With Tooltips" FontSize="16" FontWeight="Bold"
    +     Grid.Column="1" HorizontalAlignment="Center" />
    +           <sdk:Label x:Name="NameLabel" Target="{Binding ElementName=NameTextBox}"
    +     Grid.Row="2" Margin="3"/>
    +           <TextBox x:Name="NameTextBox" 
    +     AutomationProperties.Name="{Binding Content, ElementName=NameLabel}"
    +     Text="{Binding Name, Mode=TwoWay, UpdateSourceTrigger=Explicit}"
    +     Grid.Column="1" Grid.Row="2" Margin="3"
    +     AutomationProperties.HelpText="{Binding
    +       NameTextBoxToolTipString,Source={StaticResource TooltipStrings}}">
    +           <ToolTipService.ToolTip>
    +               <ToolTip Content="{Binding NameTextBoxToolTipString,Source={StaticResource TooltipStrings}}" />
    +           </ToolTipService.ToolTip>
    +           </TextBox>
    +           <sdk:Label x:Name="AgeLabel" Target="{Binding ElementName=AgeTextBox}"
    +     Grid.Row="3" Margin="3" HorizontalAlignment="Right"/>
    +           <TextBox x:Name="AgeTextBox" 
    +     AutomationProperties.Name="{Binding Content, ElementName=AgeLabel}" 
    +     Text="{Binding Age, Mode=TwoWay, UpdateSourceTrigger=Explicit}"  
    +     Grid.Column="1" Grid.Row="3" Margin="3"
    +    AutomationProperties.HelpText="{Binding AgeTextBoxToolTipString,Source={StaticResource TooltipStrings}}">
    +           <ToolTipService.ToolTip>
    +               <ToolTip Content="{Binding AgeTextBoxToolTipString,Source={StaticResource TooltipStrings}}" />
    +           </ToolTipService.ToolTip>
    +       </TextBox>
    +           <Button x:Name="SubmitButton" Content="Submit" Click="SubmitButton_Click"
    +             Grid.Column="1" Grid.Row="4" Width="50" Margin="3" />
    +       </Grid>
    +</UserControl>
    +
    +

    The following is the resource definition in app.xaml:

    +
           <ResourceDictionary>
    +           <resources:Resource1 x:Key="TooltipStrings"/>
    +       </ResourceDictionary>
    +       
    +

    The generated resource code that defines the "Resource1" class + is not shown here because it is mostly infrastructure that is produced + by a generation task in Visual Studio. For more information about + embedded resources in Silverlight, see Resources + Overview on MSDN. The resources here contain just two strings, + each of which would typically be defined in a Visual Studio .resx + file. Resources in a .resx file can be localized or changed separately + from code by the appropriate localization toolsets for Microsoft + localization/development.

    +
      +
    • NameTextBoxToolTipString: Must be 10 characters or less. Required.
    • +
    • AgeTextBoxToolTipString Must be a value between 0 and 120. Required.
    • +
    +

    These examples are shown in operation in the working example of Automation Properties Help Text and working example of HelpText and ToolTip.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. To see + UI Automation, use Microsoft Windows as platform.
    2. +
    3. Use a verification tool that is capable of showing the full automation + tree, and an object’s long text alternative as part of the tree. + (For example, use UIAVerify or Silverlight Spy; see Resources links.)
    4. +
    5. Focus an element that is known to have a long text alternative. + Check that the AutomationProperties.HelpText as applied to + individual UI elements appears as the HelpText or acc_Help value + in the automation tree.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL2.html b/techniques/silverlight/SL2.html new file mode 100644 index 0000000000..0c59e310fb --- /dev/null +++ b/techniques/silverlight/SL2.html @@ -0,0 +1,206 @@ +Changing The Visual Focus Indicator in Silverlight

    Changing The Visual Focus Indicator in Silverlight

    ID: SL2

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use the Silverlight "control + skinning" scenario and feature set to change the visible focus + indication of a control. In particular, the intent is to increase the + visibility of focus indication versus the appearance of a default-styled + control. This technique is useful both for the control sets that are + included in the Silverlight run time or SDK assemblies, as well as + for Toolkit or any third party distributed control.

    +

    The default Silverlight core controls all indicate some type of visible + focus indication, through their default templates. However, Silverlight + application authors can still use the skinning techniques to augment + or replace the visible focus indications for controls as used in their + applications. For more information on how Silverlight controls will + generally supply a default visual focus indicator, see Focus + Overview on MSDN.

    +

    Silverlight control skinning is enabled through a deliberate separation + of UI and logic in the Silverlight control model. Appearance of a control + is largely written in XAML. The logic is largely written in code (for + example C#) and is left unaffected when a Silverlight application author + provides a new control template "skin". The hooks that connect + the appearance and the logic are a Style property of the control (which + the author changes the value of, to refer to their new XAML resource) + and a contract of expected named entities in the XAML. The control + logic invokes the names of the entities/parts whenever control state + changes, and the expectation is that the named part provides the necessary + appearance as defined in XAML. Design tools such as Visual Studio or + Expression Blend generate copies of the default templates and parts, + such that Silverlight authors can modify the parts that they want to + change the appearance of, and still preserve the remainder of default + appearance and behavior of the control.

    +

    For the visible focus indicator technique, the author typically modifies + a single visual element that renders in layout as an overlay on top + of the control when it is focused, and switches the overlay to nonvisible + when the control is not focused. This element is a named element that + is typically referred to from within the XAML named state Focused, + which in turn is hooked up to changes in the visual state.

    +

    Note that this technique assumes that the original control author + provided the necessary logic event hookup, and exposed a named state + associated with keyboard focus to work with. If this is not the case, + or if the scenario is that a Silverlight author is defining their own + control, a different technique is needed. See .

    +
    +

    Focus in Silverlight

    +

    Focus in Silverlight is equivalent to the larger user interface and + application concept of keyboard focus. The element that has focus is + the element within the Silverlight object tree and programming model + that has first chance to process the Silverlight key events. As a more + tangible example that is user-centric, if a TextBox has + keyboard focus, then when the user presses keys on the keyboard, the + characters associated with the user's pressed keys will appear in the + TextBox. A user interface element in Silverlight can obtain keyboard + focus in one of three ways:

    +
      +
    1. The user uses the Silverlight tab sequence to traverse into the + Silverlight content and to focus a specific control.
    2. +
    3. The Silverlight application's logic calls the Focus method + programmatically to force focus to a control.
    4. +
    5. The user performs some other action, for example uses the mouse + to click on a control. That control's specific logic handles the + Silverlight input event and uses that event as stimulus to call Focus on + that control. The difference between this case and the above case + is that the behavior is typically built-in to that control's runtime + behavior, and does not require each application author to call Focus in + application code.
    6. +
    +
    +

    Examples

    +
    +

    Two Button elements, one reskinned to provide new visible + focus indicator

    + +

    XAML templates can be verbose; for clarity, only the parts of the + template that were changed or useful for showing the structure are + shown. Omitted portions are shown as ellipsis (...).

    +
    <UserControl x:Class="VisibleFocusTemplate.MainPage"
    + xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    + xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    + <UserControl.Resources>
    +   <Style x:Key="StrongFocusIndicator" TargetType="Button">
    +...
    +     <Setter Property="Template">
    +       <Setter.Value>
    +         <ControlTemplate TargetType="Button">
    +...
    +             <VisualStateManager.VisualStateGroups>
    +               <VisualStateGroup x:Name="FocusStates">
    +                 <VisualState x:Name="Focused">
    +                   <Storyboard>
    +                     <DoubleAnimation Duration="0" To="1"
    + Storyboard.TargetProperty="Opacity"
    + Storyboard.TargetName="FocusVisualElement"/>
    +                     <DoubleAnimation Duration="0" To="0.5"
    + Storyboard.TargetProperty="(UIElement.Opacity)"
    + Storyboard.TargetName="rectangle" d:IsOptimized="True"/>
    +                   </Storyboard>
    +                 </VisualState>
    +                 <VisualState x:Name="Unfocused"/>
    +               </VisualStateGroup>
    +             </VisualStateManager.VisualStateGroups>
    +...
    +             <Border x:Name="FocusVisualElement"
    + IsHitTestVisible="false" Opacity="0"
    + CornerRadius="2" BorderBrush="#D0FF0000"
    + BorderThickness="4">
    +               <Rectangle x:Name="rectangle"
    + IsHitTestVisible="false" Margin="2"
    + Opacity="0" RadiusY="2" RadiusX="2"
    + Fill="#A0FF0000"/>
    +             </Border>
    +          </ControlTemplate>
    +       </Setter.Value>
    +     </Setter>
    +   </Style>
    + </UserControl.Resources>
    + <StackPanel x:Name="LayoutRoot">
    +   <Button Width="275">Default button</Button>
    +   <Button Width="275"
    + Style="{StaticResource StrongFocusIndicator}"
    + >Button with re-templated focus visible indicator</Button>
    + </StackPanel>
    +</UserControl>
    +
    +

    The most interesting aspect of this example is the change made to + the FocusVisualElement part. Here is the original (default template) + FocusVisualElement:

    +
    <Rectangle x:Name="FocusVisualElement" RadiusX="2" RadiusY="2" Margin="1" Stroke="#FF6DBDD1" StrokeThickness="1" 
    + Opacity="0" IsHitTestVisible="false" />
    +
    +

    Here is the changed FocusVisualElement:

    +
    <Border x:Name="FocusVisualElement" IsHitTestVisible="false"
    + Opacity="0" CornerRadius="2"
    + BorderBrush="#D0FF0000" BorderThickness="4">
    + <Rectangle x:Name="rectangle" IsHitTestVisible="false"
    + Margin="2" Opacity="0"
    + RadiusY="2" RadiusX="2" Fill="#A0FF0000"/>
    +</Border>
    +
    +

    The following images show how each of the two buttons (default and + reskinned) appear when focused.

    +
    + + +
    Default button focus
    + +
    +
    + + +
    Reskinned button focus
    + +
    +

    This example is shown in operation in the working example of Visible Focus Template.

    + +
    +

    Tests

    +

    Procedure

    +

    Note that not all Silverlight applications necessarily will start + with the keyboard focus being somewhere within the Silverlight content + area for purpose of Step #2. It may be necessary to press TAB several + times to traverse the browser's framing user interface. Also, within + the browser's display area that displays the HTML document, there might + also be other HTML elements that are keyboard focusable, which are + representative of HTML that falls lexically before the <object> tag + that instantiates the Silverlight plug-in. So it may also be necessary + to press TAB several times until these HTML elements are traversed.

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Using a keyboard, tab to the element where focus characteristics + are being examined.
    4. +
    5. Check that the background, border, or other noticable visual indicator + of the element changes color.
    6. +
    7. Check that the changes in color for the background, border, or + other noticable visual indicator are removed when the element loses + focus.
    8. +
    +
    +

    Expected Results

    +

    #3 and #4 are true.

    +
    +

    Resources

    + + + +
    diff --git a/techniques/silverlight/SL20.html b/techniques/silverlight/SL20.html new file mode 100644 index 0000000000..e3dd4dd8ee --- /dev/null +++ b/techniques/silverlight/SL20.html @@ -0,0 +1,137 @@ +Relying on Silverlight AutomationPeer Behavior to Set AutomationProperties.Name

    Relying on Silverlight AutomationPeer Behavior to Set AutomationProperties.Name

    ID: SL20

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to illustrate how in certain cases, + the Silverlight automation peer system can provide an accessibility + framework Name based on any simple text strings that + are also presented in the visible user interface as control content.

    +

    The applicability of this technique to SC 1.3.1 is that once promoted, + the Name becomes the primary information item that + describes the user interface element to accessibiity frameworks and + assistive technologies, and the information is thus immune to any further + applications of the Silverlight style system that might change the + appearance of the visual text equivalent (styled with color, uses italic + font for rendering basis, etc.)

    +

    The applicability of this technique to SC 4.1.2 is that the default + peer promotion behavior provides the Name component of Name, Role, + Value. This is related to the description of the term label in + SC4.1.2.

    +

    A default behavior for generating Name for accessibility + frameworks is possible for certain peers of content controls. The content + controls that might support a default automation peer behavior include:

    +
      +
    • + TextBlock +
    • +
    • + ButtonBase derived classes that do not change + the GetNameCore implementation. This includes the Button class. + In order for the default promotion to work, the Content of + the button must be set as a plain string or must contain only a TextBlock; + any compositing such as wrapping in a Border or + other container will disable the default promotion.
    • +
    • Any other ContentControl derived class where + the Content property contains either TextBlock or + a text-content-only ButtonBase implementation as + sole content.
    • +
    +

    In these cases the string that sets either Content (for ContentControl and ButtonBase) + or Text (for TextBlock) is promoted + as the AutomationProperties.Name for the control in + UI Automation, without any further attribution. The properties in the + UI Automation tree are reported to accessibility frameworks (UI Automation, + and MSAA through the bridge). The accessibility frameworks reports + this information to assistive technology clients.

    +

    Relying on default automation peer behavior is the preferred Silverlight + technique for supplying the accessibility framework "Name" information, + so long as the default peer promotion actually does produce a usable + name. Using default behavior is preferred because re-using the strings + that are already used in the general visual presentation is less likely + to result in accessibility-specific strings being forgotten by the + application author, or get decoupled from visible UI in a revision + process.

    +

    For cases where there is control compositing in a control rather than + simple text, the automation peer typically cannot provide a default + simple string, and it may be the application author's responsibility + to set AutomationProperties.Name explicitly as an + attribute in XAML, or as a property in runtime code. For details, see .

    +
    +

    Test-based methodology

    +

    In order to use this technique effectively, application authors are + expected to be following a test-based methodology towards verifying + what information their application is reporting to any pertinent accessibility + framework. Useful tools for this purpose include SilverlightSpy and + UIAVerify. Application authors might examine their running Silverlight + application on a test machine where the accessibility framework test + viewers are also active. Initially, the application author might view + the application at a point in the application development cycle that + is prior to any effort devoted to specifically adding accessibility-related + information to the application. Silverlight applications might be in + this state because the initial user interface design was done in a + visually oriented design tool such as Microsoft Expression Blend. Using + the test-based methodology, application authors might note that certain + accessibility framework properties are already populated, as a result + of the mechanisms that are described in this technique. However, it + is rare that ALL of the necessary accessibility information for an + application can be obtained entirely from the built-in default behaviors + of the automation peers. At this point, the application author may + have to apply additional Silverlight techniques that provide accessibility + framework information, for example .

    +
    +

    Examples

    +
    +

    Button is composed with direct text content only

    + +

    The following example shows XAML UI only. Logic is not shown, but + would typically be added by referencing a Click handler + from the XAML.

    +
     <Button Height="20" Width="200">Fire photon torpedoes!</Button>
    +
    +

    The following illustration shows the UIAVerify tree view of this + simple interface. Note that the internal string "Fire photon + torpedoes!" is being peer-forwarded. This is verified by the + Properties view on the right side: the Name property value is "Fire + Photon Torpedoes", even though no programmatic Name property + or AutomationProperties.Name has been applied to + that button that would otherwise have supplied an acccessibility + framework "Name".

    +
    + + +
    UIAVerify tree view
    + +
    +

    This example is shown in operation in the working example of Simple Peer Forwarding.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. To use + UI AUtomation, use Windows as the platform.
    2. +
    3. Use a verification tool that is capable of showing the full automation + tree, and an object’s name text alternative as part of the tree. + (For example, use UIAVerify or Silverlight Spy; see Resources links.)
    4. +
    5. Check that any element where default automation peer promotion + is expected is supplying a default Name in the automation tree.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL21.html b/techniques/silverlight/SL21.html new file mode 100644 index 0000000000..51cb39692a --- /dev/null +++ b/techniques/silverlight/SL21.html @@ -0,0 +1,121 @@ +Replacing A Silverlight Timed Animation With a Nonanimated Element

    Replacing A Silverlight Timed Animation With a Nonanimated Element

    ID: SL21

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to replace a timed Silverlight + animation with a non-timed user interface element that presents equivalent + information. This is useful in cases where the Silverlight animation + is a timed animation that may contain information that the user wants + to see without a time limit, such as crawling text in a text area. + The animated version of information in the user interface element can + instead be swapped out for an equivalent static element.

    +

    The Silverlight animation system is generalized such that nearly any + Silverlight property of type Double, Point or Color can + be animated, or a property can cycle through discrete object values. + Thus the possibilities for which properties in the user interface can + be animated are quite broad. The general technique shown can be used + to stop any animation.

    +

    Examples

    +
    +

    Stopping an animation that is scrolling text, replacing the animation with a full text alternative

    + +

    This example has a UI definition in XAML and interaction logic in C#. The following is the basic UI in XAML.

    +
    <UserControl x:Class="StopAnimation.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +xmlns:sys="clr-namespace:System;assembly=mscorlib">
    +   <UserControl.Resources>
    +       <ImageBrush x:Key="Stars" ImageSource="/stars.jpg" Stretch="Fill"/>
    +       <Storyboard x:Key="crawl">
    +           <DoubleAnimation From="700" To="-100" Duration="0:0:20"
    +             Storyboard.TargetName="crawltext" Storyboard.TargetProperty="(Canvas.Top)"/> 
    +       </Storyboard>
    +       <sys:String x:Key="crawlText">
    +           Episode IV, A NEW HOPE It is a period of civil war. Rebel spaceships, striking from a hidden base, 
    +           have won their first victory against the evil Galactic Empire. During the battle, Rebel spies managed 
    +           to steal secret plans to the Empire’s ultimate weapon, the DEATH STAR, an armored space station with 
    +           enough power to destroy an entire planet. Pursued by the Empire’s sinister agents, Princess Leia 
    +           races home aboard her starship, custodian of the stolen plans that can save her people and restore 
    +           freedom to the galaxy….
    +       </sys:String>
    +   </UserControl.Resources>
    +   <StackPanel x:Name="LayoutRoot"
    +   Background="{StaticResource Stars}"
    +   Height="600" Width="800">
    +       <Button Width="200"
    +   Click="Button_Click">Stop crawling text, display fixed text</Button>
    +       <Canvas Name="CrawlPanel" Width="605" Height="595" >
    +           <Canvas.Projection>
    +               <PlaneProjection RotationX="-75"/>
    +           </Canvas.Projection>
    +           <Canvas.Clip>
    +               <RectangleGeometry Rect="0 0 600 600"/>
    +           </Canvas.Clip>
    +           <TextBlock Text="{StaticResource crawlText}"
    +   TextWrapping="Wrap" FontSize="20"
    +   Width="300" Canvas.Left="150" Name="crawltext"
    +   Foreground="Goldenrod"/>
    +       </Canvas>
    +   </StackPanel>
    +</UserControl>
    +
    +

    The following is the C# logic. In this example, the animation starts + automatically. When the user activates the control (the Button), + the event handler stops the animation, removes the animated element + from the visual tree, and replaces it with a fixed text element that + presents all text at once. Because it is a TextBox, + assistive technologies could identify the newly introduced text element + and present it, for example read the text in a screen reader.

    +
           public MainPage()
    +       {
    +           InitializeComponent();
    +           (this.Resources["crawl"] as Storyboard).Begin();
    +       }
    +       private void Button_Click(object sender, RoutedEventArgs e)
    +       {
    +           (this.Resources["crawl"] as Storyboard).Stop();
    +           LayoutRoot.Children.Remove(CrawlPanel);
    +           TextBox tb = new TextBox();
    +           tb.IsReadOnly = true;
    +           tb.FontSize = 30;
    +           tb.TextWrapping = TextWrapping.Wrap;
    +           tb.Text = (string)this.Resources["crawlText"];
    +           LayoutRoot.Children.Add(tb);
    +       }
    +
    +

    This example is shown in operation in the working example of Stop Text Animation.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. For a + Silverlight application that has a time limit on interaction due + to an animated user interface element:
    2. +
    3. Check for a mechanism to stop the time limit on interaction.
    4. +
    5. When the mechanism is activated, check that the element that is + animated and resulting in a time limit is removed, and the time-limited + element is replaced with static content that is equivalent and does + not have a time limit.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL22.html b/techniques/silverlight/SL22.html new file mode 100644 index 0000000000..cca8c0403c --- /dev/null +++ b/techniques/silverlight/SL22.html @@ -0,0 +1,132 @@ +Supporting Browser Zoom in Silverlight

    Supporting Browser Zoom in Silverlight

    ID: SL22

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +
      +
    • Silverlight content in a user agent host that supports browser + zoom
    • +
    +

    Description

    +

    The objective of this technique is to support or anticipate existing + browser zoom features effectively when users interact with the Silverlight + application. This technique explains how the Silverlight content area + reacts to the browser zoom feature implemented by some user agent hosts. + Silverlight content and layout properties are based on physical screen + pixel measurements. When the browser zoom is engaged, Silverlight content + scales correctly for the zoom factor, and uses the same zoom factor + as any surrounding HTML content.

    +

    Browser zoom is relevant for accessibility and Silverlight because + it is likely to be the zoom /scaling feature enabled by the browser + host that Web technology users are the most familiar with as a technique + for increasing the text size in Web content.

    +
    +

    Legacy behavior in Silverlight version 2

    +

    Built-in support for browser zoom was introduced as a feature in Silverlight + version 3. Older documents on the Web might describe techniques that + were relevant for Silverlight version 2, where dealing with browser + zoom required JavaScript handling of the Resized event, + and developers manually applied a ScaleTransform to Silverlight + content to scale it up. Silverlight has a "quirks mode" that + detects existing handlers that might still use the older techniques. + Built-in zoom not active in these cases, so that applications can avoid + doubling or otherwise mishandling the user agent's zooming behavior.

    +
    +
    +

    Deliberately disabling browser zoom in Silverlight applications

    +

    Silverlight also provides the ability to disable the built-in browser + zoom handling and rendering behavior. This is sometimes done in order + to suppress some of the aliasing and distortion artifacts that host-level + scaling can introduce, particularly for video content or certain uses + of text. In these cases, application authors might consider other Silverlight + techniques for scaling the user interface, perhaps specifically only + for the text elements on a page. When an application disables the built-in + zoom behavior and rendering for Silverlight content, the browser still + retains its zoom settings, and that setting applies to other content + outside of Silverlight such as the hosting HTML.

    +
    +

    Examples

    +
    +

    Verifying browser zoom, and checking the zoom factor

    + +

    This example has a UI defined in XAML and logic defined in C#. The + UI shows the zoom factor, and also demonstrates what happens when built-in + browser zoom handling is deliberately disabled. Note that the zooming + factor as reported by the API is still retained even when Silverlight + built-in zoom scaling is disabled deliberately. The following is the + XAML UI:

    +
    <UserControl x:Class="BrowserZoom.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    +   <StackPanel x:Name="LayoutRoot" Background="White">
    +       <TextBlock>Some text you can zoom.</TextBlock>
    +       <Button Click="Button_Click">Toggle built-in zoom handling</Button>
    +       <StackPanel Orientation="Horizontal">
    +           <Button Click="Button_Click_1">Query current zoom factor</Button>
    +           <TextBox IsReadOnly="true" Name="zoomf"
    +   Text="{Binding Path=reportZoom}"/>
    +       </StackPanel>
    +   </StackPanel>
    +</UserControl>
    +
    +

    The following is the C# logic:

    +
       public partial class MainPage : UserControl
    +   {
    +       public MainPage()
    +       {
    +           InitializeComponent();
    +       }
    +       private void Button_Click(object sender, RoutedEventArgs e)
    +       {
    +           if (!Application.Current.Host.Settings.EnableAutoZoom == false) {
    +           Application.Current.Host.Settings.EnableAutoZoom = false;
    +           }
    +           else
    +           {
    +               Application.Current.Host.Settings.EnableAutoZoom = true;
    +           }
    +       }
    +       private void Button_Click_1(object sender, RoutedEventArgs e)
    +       {
    +           zoomf.Text = Application.Current.Host.Content.ZoomFactor.ToString();
    +       }
    +   }
    +
    +

    This example is shown in operation in the working example of Browser Zoom.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. The browser + being used for the test must support a browser zoom feature, and + the feature must be turned on as a user preference.
    2. +
    3. Verify that the Silverlight application enables auto zoom (no + Silverlight application-specific code or markup has set EnableAutoZoom + API to false).
    4. +
    5. Test the zooming feature of the user agent. Verify that browser + zoom factors apply to the Silverlight content.
    6. +
    +
    +

    Expected Results

    +

    #2 and #3 are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL23.html b/techniques/silverlight/SL23.html new file mode 100644 index 0000000000..ff283c14a3 --- /dev/null +++ b/techniques/silverlight/SL23.html @@ -0,0 +1,219 @@ +Using A Style Switcher to Increase Font Size of Silverlight Text + Elements

    Using A Style Switcher to Increase Font Size of Silverlight Text + Elements

    ID: SL23

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to define style switching logic + for Silverlight. In particular, the intent is to use the style switcher + to change the font size of text elements. This technique could be used + only for specific elements, or could also be applied to the entire + Silverlight content area and all text elements therein (including elements + such as TextBlock that are technically not controls). + Examples are provided for these two cases.

    +

    The property to style or otherwise change is the FontSize property. + Primarily, this is done using the API Control.FontSize, + but developers can also use similar properties on other objects that do not + derive from Control (examples: TextBlock; DataGridTextColumn).

    +

    Silverlight uses a style system whereby many properties that affect + UI appearance can be referred to and changed through a style resource. + The style resource overrides the default code implementation and the + default XAML template as provided by the Silverlight core implementation(or + a third party control author). A style enables an application author + to make a one-to-many change to property values in an efficient and + reversible way, and also to group multiple related property changes + as one unit of logic. Styles can be applied explicitly by referencing + them by name, or implicitly by associating a style with a class (which + then targets all instances of that class). This is analogous to how + CSS can either define styles globally for tags or uniquely for classids + and names.

    +

    Silverlight styles are always written in XAML. Silverlight event handlers + are most often written in code (there are related techniques that can + react to states with event associations, defined in pure XAML, but + the specific style switching technique is most straightforward in code).

    +
    +

    Using this technique versus relying on browser zoom

    +

    Silverlight supports browser zoom when viewed in browser hosts that + support a browser zoom feature. Specifically, Silverlight scales content + within its content area when the user engages browser zoom, based on + the browser zoom factor. However, not all browser hosts that Silverlight + supports have a browser zoom feature, and/or users might choose not + to use browser zoom. This technique presents an alternative technique + for font scaling in cases when relying on browser zoom is not viable + as a technique. Applications might use HTML DOM based logic to determine + the user agent string of the browser host, and use that as a determinant + of whether the user has browser zoom available as an option. If no + browser zoom feature exists for that user and their user agent, that + user could be served a version of the Silverlight application that + presents a UI and logic for sizing the fonts using the Silverlight + API, as described in this technique.

    +

    For more information about Silverlight and browser zoom, see the technique .

    +
    +
    +

    Sizing by percent

    +

    Generally, sizing Silverlight FontSize values by + percentages is not recommended. Sizing by percentage produces non-integer + font size values, which in turn produce aliasing artifacts. The Silverlight + rendering routines for text work best when dealing with integer numbers. + The entire Silverlight rendering system is based on pixel measurements. + In particular, the behavior for text rendering produces optimized font + shaping and subpixel rendering for text areas, and this behavior is + based on the assumption that font unit measurements will be provided + by applications using whole pixel values.

    +
    +
    +

    Units for font sizing in Silverlight

    +

    Font sizing in Silverlight is always specified by a unit measure of + pixels. Other unit measures such as ems or points that come from a + migrated UI definition in XAML would need to be unit-converted to all + use a purely numeric value, such that attribute values in XAML do not + not include unit identifier suffixes such as "px", "pt", "em", + or "cm". This note is most relevant if the application author + is porting or migrating a Windows Presentation Framework (WPF) application + to Silverlight, or is using a XAML-emitting design tool that is producing + general XAML UI definitions and not targeting a specific framework.

    +
    +

    Examples

    +
    +

    Style applied to all text elements within a RichTextBox + container

    + +

    Variations of this example could be employed to offer more choices. + For example, multiple style switchers could be provided that gave three + or more fontsize choices.

    +
    <UserControl x:Class="StyleSwitcherFontSize.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    +   <UserControl.Resources>
    +       <Style x:Key="BiggerRTBFonts" TargetType="RichTextBox">
    +           <Setter Property="FontSize" Value="24"/>
    +       </Style>
    +   </UserControl.Resources>
    +
    +   <StackPanel x:Name="LayoutRoot" Background="White">
    +       <Button Click="Button_Click">Super size fonts!</Button>
    +       <Button Name="Undo" Click="Undo_Click">Make those big fonts stop!</Button>
    +       <RichTextBox IsReadOnly="True" Name="rtb1">
    +           <RichTextBox.Blocks>
    +               <Paragraph>Various test text</Paragraph>
    +               <Paragraph>
    +                   <Bold>Some bold test text</Bold></Paragraph>
    +               <Paragraph>
    +                   <Italic>Some italic</Italic>
    +               </Paragraph>
    +               <Paragraph FontFamily="Times New Roman">A different font, why not?</Paragraph>
    +           </RichTextBox.Blocks>
    +       </RichTextBox>
    +   </StackPanel>
    +</UserControl>
    +
    +

    The second listing is the C# code for the event handler . Note that + all it does is change a style property, using a value that keys into + the .Resources collection from XAML where the Style is defined. Another + event handler nulls out the style and returns values to defaults.

    +
    private void Button_Click(object sender, RoutedEventArgs e)
    +{
    +  rtb1.Style = this.Resources["BiggerRTBFonts"] as Style;
    +}
    +private void Undo_Click(object sender, RoutedEventArgs e)
    +{
    +   rtb1.Style = null;
    +}
    +
    +

    The following images show the original, and the applied style.

    +
    + + +
    Screen shot with standard fonts and a button to enlarge
    + +
    +
    + + +
    Screen shot with enlarged fonts after activating button to enlarge
    + +
    +

    This example is shown in operation in the working example of Style Switcher Font Size.

    + +
    +
    +

    Font size increase applied to all text content by applying + at UserControl level, and by percent increase logic

    + +

    This example uses the inheritance characteristics of the FontSize + property that is available to all Silverlight controls. Rather than + using a style, this example uses a HoldEnd animation, to take advantage + of the "By" behavior of the animation system that can increment + an existing value by 2 (pixels) rather than replacing the value with + a fixed pixel value.

    +

    The following is the XAML UI:

    +
    <UserControl x:Class="StyleSwitcherFontSize.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +   Name="rootcontrol">
    +   <UserControl.Resources>
    +       <Storyboard x:Key="BySize">
    +           <DoubleAnimation Storyboard.TargetName="rootcontrol" Storyboard.TargetProperty="FontSize" By="2" FillBehavior="HoldEnd" Duration="0"/>
    +       </Storyboard>
    +   </UserControl.Resources>
    +   <StackPanel x:Name="LayoutRoot" Background="White">
    +       <Button Click="Button_Click">Super size fonts!</Button>
    +       <Button Name="Undo" Click="Undo_Click">Make those big fonts stop!</Button>
    +       <TextBox Text="Various test text"/>
    +       <TextBox FontWeight="Bold" Text="Some bold test text"/>
    +       <TextBox FontStyle="Italic" Text="Some italic"/>
    +       <TextBox FontFamily="Times New Roman" Text="A different font, why not?"/>
    +   </StackPanel>
    +</UserControl>
    +
    +

    The following are the C# event handlers.

    +
    private void Button_Click(object sender, RoutedEventArgs e)
    +{
    +   (this.Resources["BySize"] as Storyboard).Begin();
    +}
    +private void Undo_Click(object sender, RoutedEventArgs e)
    +{
    +   (this.Resources["BySize"] as Storyboard).Stop();
    +}
    +
    +

    + This example is shown in operation in the working example of By Animation Font Size. +

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Verify that the application provides a control that can increase + font size.
    4. +
    5. Activate the control, and check that the font sizes increase.
    6. +
    +
    +

    Expected Results

    +

    #2 and #3 are true.

    +
    +

    Resources

    + + + +
    diff --git a/techniques/silverlight/SL24.html b/techniques/silverlight/SL24.html new file mode 100644 index 0000000000..53885190e1 --- /dev/null +++ b/techniques/silverlight/SL24.html @@ -0,0 +1,122 @@ +Using AutoPlay to Keep Silverlight Media from Playing Automatically

    Using AutoPlay to Keep Silverlight Media from Playing Automatically

    ID: SL24

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use the AutoPlay property + of MediaElement object, which prevents the MediaElement from + playing its media source automatically.

    +

    By default the value of AutoPlay is true, which causes + any media that is the Source of the MediaElement to + play as soon as either the entire source file is loaded (for nonstreaming + media) or an initial buffer is loaded (for streaming media). To prevent + the possible accessibility issues, developers can instead specifically set AutoPlay to + false, so that the user always controls whether the media plays. This + technique would thus be used in combination with providing user interface + controls that go along with the MediaElement, and + that enable the user to control the media. In particular, the user + interface controls enable the media to play, pause or stop, with event + wiring for those controls associated with the Play, Pause or Stop methods + of the MediaElement object.

    + +

    Examples

    +
    +

    Setting AutoPlay to false, and providing the typical MediaElement controls in the UI

    + +

    This example has a UI definition in XAML and interaction logic in + C#.

    +

    The following is the basic UI in XAML. Note the AutoPlay="false" setting.

    +
    <UserControl x:Class="MediaElementControlsAutoPlay.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +  >
    +   <Grid x:Name="LayoutRoot">
    +       <Grid.ColumnDefinitions>
    +           <ColumnDefinition Width="*" />
    +           <ColumnDefinition Width="*" />
    +           <ColumnDefinition Width="*"/>
    +       </Grid.ColumnDefinitions>
    +       <Grid.RowDefinitions>
    +           <RowDefinition Height="*" />
    +           <RowDefinition Height="Auto" />
    +       </Grid.RowDefinitions>
    +       <MediaElement x:Name="media" Source="/xbox.wmv"
    +          Width="300" Height="300" 
    +          Grid.Column="0" Grid.Row="0" Grid.ColumnSpan="3"
    +          AutoPlay="False"
    +          AutomationProperties.Name="Video of new Fable game for XBox"           
    +       />
    +       <Button Click="StopMedia" 
    +    Grid.Column="0" Grid.Row="1" Content="Stop" />
    +       <Button Click="PauseMedia" 
    +    Grid.Column="1" Grid.Row="1" Content="Pause" />
    +       <Button Click="PlayMedia" 
    +    Grid.Column="2" Grid.Row="1" Content="Play" />
    +   </Grid>
    +</UserControl>
    +
    +

    The following is the C# logic.

    +
     private void StopMedia(object sender, RoutedEventArgs e)
    + {
    +     media.Stop();
    + }
    + private void PauseMedia(object sender, RoutedEventArgs e)
    + {
    +     media.Pause();
    + }
    + private void PlayMedia(object sender, RoutedEventArgs e)
    + {
    +     media.Play();
    + }
    + 
    +
    +

    This example is shown in operation in the working example of Media Element Controls with AutoPlay False.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. The application + is expected to use a MediaElement object to play + prerecorded media.
    2. +
    3. Check that the media does not play automatically as soon as the + application loads and displays. Rather, the user is presented with + a user interface that can start the media per the user's action.
    4. +
    +
    +

    Expected Results

    +

    #2 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL25.html b/techniques/silverlight/SL25.html new file mode 100644 index 0000000000..88bdd46ce4 --- /dev/null +++ b/techniques/silverlight/SL25.html @@ -0,0 +1,87 @@ +Using Controls and Programmatic Focus to Bypass Blocks of Content + in Silverlight

    Using Controls and Programmatic Focus to Bypass Blocks of Content + in Silverlight

    ID: SL25

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use the combination of Silverlight + control activation and programmatic focus to enable the user to skip + regions of content in a Silverlight application user interface.

    +

    The control that the user activates should clearly indicate that its + purpose is to skip content, so that the resulting programmatic focus + shift is not interpreted as an undesired change of context.

    +

    The object to call focus to (the receiver of focus after the user-initiated + action is triggered) has to be a Control in the Silverlight + programming model. This is because the Focus method + must be called on the target, and therefore the target must inherit + the Control class. So, an application author might + call focus to a read-only TextBox, or perhaps a RichTextBox, + depending on the purpose of the Silverlight application and its user + interface design. You can also focus a UserControl, + for cases where the area to call focus to represents a custom control + implementation.

    +
    +

    Setting TabIndex (not recommended)

    +

    Silverlight provides a TabIndex attribute that can + be used to override the default-generated tab sequence. Do not attempt + to adjust tab index as a technique for getting past content blocks. + Doing so will create a focus order that does not match the apparent + visual order, as described in SC + 2.4.3.

    +
    +

    Examples

    +
    +

    User-enabled control that programmatically sets focus

    + +

    The following is the XAML for the user interface.

    +
       <StackPanel Name="LayoutRoot">
    +       <Button Name="bypassbtn1" Click="bypassbtn1_Click">Skip menus, go to main page content</Button>
    +       <!intervening content-->
    +       <StackPanel>
    +           <RichTextBox Name="rtb_MainContent" IsReadOnly="True">
    +           <Paragraph>Here is the main content ....</Paragraph>
    +           </RichTextBox>
    +       </StackPanel>
    +   </StackPanel>
    +   
    +

    The following is the event handler that forces focus.

    +
           private void bypassbtn1_Click(object sender, RoutedEventArgs e)
    +       {
    +           rtb_MainContent.Focus();
    +       }
    +
    +

    This example is shown in operation in the working example of Programmatic Focus.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Open the test HTML page for a Silverlight application.
    2. +
    3. Check for a control that indicates that activating that control + can skip to some particular region of the content.
    4. +
    5. Activate that control. Verify that activating the control causes + focus to go to that region, and that a repeated block or blocks of + content are skipped.
    6. +
    +
    +

    Expected Results

    +

    #2 and #3 are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL26.html b/techniques/silverlight/SL26.html new file mode 100644 index 0000000000..dbe6ad3d95 --- /dev/null +++ b/techniques/silverlight/SL26.html @@ -0,0 +1,86 @@ +Using LabeledBy to Associate Labels and Targets in Silverlight

    Using LabeledBy to Associate Labels and Targets in Silverlight

    ID: SL26

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use the AutomationProperties.LabeledBy property + to associate a non-interactive text label with an interactive field + such as a Silverlight TextBox or RichTextBox. + By using this technique, application authors can use the label text + as the default source for AutomationProperties.Name on + the target, and do not need to specify an explicit AutomationProperties.Name.

    +

    This technique relies on several Silverlight features: the Name property + for identifying specific UI elements, the AutomationProperties API, + and the ElementName variation of Silverlight data binding. AutomationProperties.Name can + be set on and can target any Silverlight UIElement. + The two most common uses of this labeling technique are for labeling + a form field, and for associating an image caption with an image.

    +

    Examples

    +
    +

    Two TextBox form fields, each with a LabeledBy reference + to a text label

    + +

    The following is XAML for the UI (and can be inserted into a UserControl + XAML root or elsewhere). No code-behind is necessary for this example; + the element relationships are established by the {Binding} values in + the XAML and interpreted appropriately by the Silverlight run time.

    +
       <StackPanel x:Name="LayoutRoot" Background="White">
    +       <StackPanel Orientation="Horizontal">
    +           <TextBlock Name="lbl_FirstName">First name</TextBlock>
    +           <TextBox AutomationProperties.LabeledBy="{Binding ElementName=lbl_FirstName}" Name="tbFirstName" Width="100"/>
    +       </StackPanel>
    +       <StackPanel Orientation="Horizontal">
    +           <TextBlock Name="lbl_LastName">Last name</TextBlock>
    +           <TextBox AutomationProperties.LabeledBy="{Binding ElementName=lbl_LastName}" Name="tbLastName" Width="100"/>
    +       </StackPanel>
    +   </StackPanel>
    +
    +

    This example is shown in operation in the working example of Labels.

    + +
    +
    +

    Labeling / captioning an image

    + +
           <Image HorizontalAlignment="Left" Width="480" Name="img_MyPix"
    +                Source="snoqualmie-NF.jpg"
    +                AutomationProperties.LabeledBy="{Binding ElementName=caption_MyPix}"/>
    +       <TextBlock Name="caption_MyPix">Mount Snoqualmie North Bowl Skiing</TextBlock>
    +       
    +
    +

    If the caption is not a usable text alternative, use the technique , or change the caption + text.

    +
    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. To see + UI Automation, use Microsoft Windows as platform.
    2. +
    3. Use a verification tool that is capable of showing the full automation + tree. (For example, use UIAVerify or Silverlight Spy; see Resources + links.)
    4. +
    5. Verify that any element that has a LabeledBy value + has an associated visible label.
    6. +
    7. Verify that any element that has a LabeledBy value + uses the Name value from that label.
    8. +
    +
    +

    Expected Results

    +

    #3 and #4 are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL27.html b/techniques/silverlight/SL27.html new file mode 100644 index 0000000000..e4a3511bfb --- /dev/null +++ b/techniques/silverlight/SL27.html @@ -0,0 +1,287 @@ +Using Language/Culture Properties as Exposed by Silverlight Applications + and Assistive Technologies

    Using Language/Culture Properties as Exposed by Silverlight Applications + and Assistive Technologies

    ID: SL27

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use the combination of HTML + Lang attribute, CultureInfo and Language to + correctly specify the language of the entirety of Silverlight content, + or of parts within the Silverlight content.

    +

    In general, Silverlight does not attempt to repurpose HTML Lang, because + Silverlight is not HTML. Instead, internally within the Silverlight + content area, Silverlight uses language definition concepts that relate + to XML (Language is a remapping of xml:lang) or .NET + Framework programming (CultureInfo). For these reasons, + HTML Lang techniques as described in [H58] + are not useful for Silverlight programming of Silverlight-specific "parts".

    +

    What becomes important in Silverlight application programming then + is to make sure that the HTML language concept of Lang and the Silverlight + language concept of CultureInfo or Lang are not at odds with one another, + or reporting misinformation. In particular, application authors should + avoid situations where an assistive technology has HTML Lang available + for programmatic determination of either page or part, but the effective + runtime language in the Silverlight part is different. The result here + might be that a screen reader that changes functionality such as phonetic + pronunciations would not correctly read the text content from the Silverlight + content. Avoiding this situation is largely a matter of due diligence + on the part of a Silverlight application author, OR on the part of + the Web page author who authors surrounding HTML, in cases where a + Web page is embedding Silverlight content or packages that the Web + page's author did not actively develop and is only consuming/embedding.

    +

    The following is a general recommendation that summarizes the detailed + discussion in subsequent subheadings:

    +
      +
    • If the Silverlight application does not have a strong emphasis + on presenting textual information with a particular language association, + HTML Lang should be left blank. This causes assistive technologies + to defer to either user agent or platform language settings. Silverlight + is able to determine these same language values at run time, and + language behavior of assistive technologies and of Silverlight is + kept synchronized through the use of the same external information + set.
    • +
    • If the Silverlight application DOES have a strong emphasis on + presenting textual information with A SINGLE particular language + association, HTML Lang should be assigned to report that specific + language either for whole page or at least for the Silverlight object + tag. This enables assistive technologies to pick up the value, per H57: + Using language attributes on the html element HTML. Aside from + due diligence during development and deployment, Silverlight application + code might choose to enforce that its runtime CultureInfo is really + the same. This could be addressed with a specific HTML DOM helper + function.
    • +
    • If the Silverlight application has MULTIPLE language associations, + the best option is to separate the Silverlight application into object + parts at the HTML level, to assure that HTML Lang and intended runtime + language do not clash. This is particularly important if the application + is actively resetting CurrentCulture away from the user settings + of platform or user agent. For more information, see .
    • +
    +
    +

    HTML Lang

    +

    When Silverlight is embedded in an HTML document with the <object> element, + the value of the HTML Lang attribute of the surrounding HTML becomes + a factor. Browsers process the outer HTML, and the browser's processing + has possible influence over values reported to any DOM script that + acts, or to any accessibility framework that is reporting the browser + content. The preferred way for a Silverlight application to address SC + 3.1.1 is to correctly specify the HTML Lang value in the hosting + HTML page. This technique should be used in conjunction with H57: + Using language attributes on the html element HTML. By using the + same language values with both techniques as a better practice, H57 + will satisfy 3.1.1 while setting the language value of the Silverlight + content to match will assist authors in meeting SC 3.1.2.

    +

    The Silverlight runtime itself does not attempt to inherit language + settings that come from markup that is outside the Silverlight-specific + content. In particular, the HTML Lang attribute applied to the html + tag, Lang on host object tag, specific parameters of the Silverlight + object tag, all have no affect on the value of any Silverlight Language attribute. + Instead, the Silverlight Language defaults to the CultureInfo of + the Silverlight runtime as instantiated by HTML object tag invocation. + It is expected that if a Silverlight application contains extensive + text where language of text is a factor for assistive technology purposes, + developers will manually set the HTML Lang tag to match the Language value + on the Silverlight root element in XAML. Development tools might or + might not enforce or inform the relationship between HTML Lang and + Silverlight Language; that consideration is outside + the scope of Silverlight as a technology. If language is not a major + factor in the application, application authors should consider leaving + HTML Lang blank on the hosting HTML page.

    +

    You can programatically determine the value of HTML Lang of surrounding + HTML from within the Silverlight API, by using the DOM-bridging method HtmlElement.GetAttribute. + Otherwise, this can be determined by techniques other than Silverlight's + (such as scripting to the HTML DOM of the hosting browser).

    +
    +
    +

    Silverlight Language property

    +

    + Language is an attribute that is available on all + Silverlight objects that directly represent a UI element. Language + can be queried (or set) by Silverlight managed code run time, such + that the Language value can be programatically determined + within the Silverlight programming model.

    +

    The format of the value that is used to set Language is + based on ISO-639-1, and is thus compatible with http://www.rfc-editor.org/rfc/bcp/bcp47.txt.

    +

    + Language has a behavior that parallels the behavior + of xml:lang in an XML document: if Language is set on + a parent element, all child elements inherit that Language value. + An actual xml:lang attribute in XAML is also valid for this purpose.

    +

    + Language can be set at the root of a XAML document, + so that the entire UI shares the same language setting. If Language is + not explicitly set at the root by application markup, Language is + inferred per running instance, based on processing the acting CultureInfo at + run time.

    +

    However, another usage is for application authors to set Language on + a specific child element, to override the root-level or client-environment-inferred Language value. + This enables consciously embedding a content part that is deliberately + in a different language than the remainder of the Silverlight content.

    +

    Exactly what happens when a Language is set on a + part is not always specified, and is largely a matter of implementation + detail of the individual Silverlight classes that might be a "part". + However, as an informative generalization, the value of Language might + affect considerations such as: how white space is processed (in particular + CR or LF); character sets for fonts; string formatting when using APIs + specifically on that part.

    +
    +
    +

    CultureInfo

    +

    + CultureInfo is a concept that is relevant to .NET + Framework programming. This concept applies to Silverlight because + Silverlight uses a specific implementation of a CLR runtime that uses + .NET Framework principles. CultureInfo potentially + specifies both a language and a culture. This distinction becomes relevant + for advanced string formatting concepts that are provided in the .NET + Framework, such as decimal separators, dates, and currency. For example, + an application author might simply specify "en" if the author + did not care about string formatting, but might specify "en-GB" if + the application was using string formatting for currency values with + the intention of displaying Pounds Sterling as currency unit in string + formatting.

    +

    Silverlight applications often run using an inferred CultureInfo based + on the operating system where the user agent browser host exists (in + other words, the culture of the client computer where the Silverlight + application is run). This CultureInfo can be queried + by applications at run time; see CultureInfo.CurrentCulture. + Application authors can deliberately constrain the set of CultureInfo cases + that a Silverlight application can be run under, in order to verify + that necessary string resources for that culture are available in that + application. This is done by setting <SupportedCultures> in the + Silverlight project settings. If a user accesses the application on + a client that is outside the SupportedCultures, the application author + has the following choices:

    +
      +
    • Use a fallback resource set representing a neutral culture; this + is enabled automatically by the Silverlight resources lookup behavior, + so long as the project includes resources identified as being culture-neutral. + This is the preferred approach.
    • +
    • Use client logic to detect the culture, and initiate a client-side + redirect to request either a different XAP or a different hosting + HTML page.
    • +
    • Trap requests at the server level by checking lang request in + the header. This varies between server implementations, is not a + Silverlight-specific technique, and is not discussed here.
    • +
    +

    For more information, see How + to: Create a Build that Targets a Specific Culture.

    +

    + CultureInfo generally applies to the Silverlight + application as a whole. There are advanced techniques whereby worker + threads can be run as separate cultures, but that is not discussed + here and is not relevant because only the main UI thread has relevance + to Web content accessibility. So, if an application author wants to + declare specific language settings for a part (component, region or + control) of the Silverlight application, a different Silverlight-specific + property Language is used.

    +
    +

    Examples

    +

    These examples show Silverlight behaviors that are based on interpreting + the Language property value, as a way of illustrating + the programmatic determination of language values specifically in the + Silverlight application framework. To determine HTML Lang, application + authors should use the HTML DOM as enabled by browser host scripting, + rather than Silverlight APIs. HTML DOM techniques are not shown here + because they are specific to browsers or scripting frameworks, not + to Silverlight.

    +
    +

    Language set at root-level of Silverlight content, inherits

    + +

    This example features a XAML UI and logic that reports information + to demonstrate that the information is programmatically determinable. + This example shows determination of the Language property.

    +
    <UserControl x:Class="LangProperties.MainPage" 
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +   Language="en-gb">
    + <StackPanel x:Name="LayoutRoot" Background="White">
    +       <Border BorderBrush="Red" BorderThickness="2">
    +           <TextBlock Language="zh-cn" Text="(()共" Name="t2" VerticalAlignment="Top" TextWrapping="Wrap" Height="100"/>
    +       </Border>
    +       <Border BorderBrush="Red" BorderThickness="2">
    +           <TextBlock Text="(()共" Name="t3" VerticalAlignment="Top" TextWrapping="Wrap" Height="100"/>
    +       </Border>
    +       <Button Click="button1_Click">IETF Language of this app</Button>
    + </StackPanel>
    +</UserControl
    +
    +private void button1_Click(object sender, RoutedEventArgs e)
    +{
    +   Button b = sender as Button;
    +   MessageBox.Show(b.Language.IetfLanguageTag);
    +   // this will be 'en-gb' because inherits from the root
    +}
    +
    +

    This example is shown in operation in the working example of Language Properties.

    + +
    +
    +

    Determine CurrentCulture; runtime verification that CurrentCulture and the surrounding HTML's current Lang value do not report different language settings

    + +

    The following is an event handler that can be hooked to an object + lifetime event such as UserControl.Loaded on the Silverlight + XAML root. This example demonstrates property access to several of + the relevant language properties that are present in Silverlight and + shows a specific way to compare CultureInfo and Lang by a "not + equals" check after constructing a CultureInfo based on the Lang + string. To apply this test, the hosting HTML page may need to be altered + to declare a specific HTML Lang; default Silverlight aspx or html test + pages do not declare HTML Lang.

    +
           private void RunLanguageDetectLogic(object sender, RoutedEventArgs e)
    +       {
    +           CultureInfo thisAppCC = CultureInfo.CurrentCulture;
    +           CultureInfo thisAppCUIC = CultureInfo.CurrentUICulture;
    +           HtmlDocument thisPage = HtmlPage.Document;
    +           String thisAppHTMLLang = (string) thisPage.DocumentElement.GetProperty("lang");
    +           CultureInfo CCFromLang = new CultureInfo(thisAppHTMLLang);
    +           if (CCFromLang != thisAppCC && CCFromLang.ToString() !=  "")
    +           {
    +               TextBlock tb = new TextBlock();
    +               tb.Text += "Warning: the current culture for the run time (";
    +               tb.Text += thisAppCC.ToString();
    +               tb.Text += ") does not match the culture indicated in hosting HTML's Lang (";
    +               tb.Text += CCFromLang.ToString();
    +               tb.Text += ").";
    +               tb.Inlines.Add(new LineBreak());
    +               tb.Inlines.Add("Typical action here would be to redirect the request to an HTML page
    +                 where the Lang is correct for user's current culture as determined from the OS.");
    +               LayoutRoot.Children.Add(tb); 
    +               //LayoutRoot refers to the default MainPage.xaml element from a VS-template Silverlight Application
    +           }
    +       }
    +
    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Verify that language settings are respected by individual Silverlight + control characteristics. (Exactly what behavior manifests the language + difference varies per Silverlight class implementation. For some + testing ideas, see Creating + Globally Aware Applications).
    4. +
    5. Verify that any interaction between HTML Lang in the HTML and + the Language or CultureInfo from the Silverlight application do not + result in a clash of language information, either in terms of basic + application behavior or in how an assistive technology decides to + process language information.
    6. +
    +
    +

    Expected Results

    +

    #2 and #3 are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL28.html b/techniques/silverlight/SL28.html new file mode 100644 index 0000000000..54721a53b0 --- /dev/null +++ b/techniques/silverlight/SL28.html @@ -0,0 +1,439 @@ +Using Separate Text-Format Text Captions for MediaElement Content

    Using Separate Text-Format Text Captions for MediaElement Content

    ID: SL28

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use text captioning that comes + from a separate text file, synchronize the captions with the media + in a Silverlight MediaElement, and display the captions + in Silverlight.

    +

    There are two variations of the general theme of implementing Silverlight + media player controls to work with external timed text: using built-in + capabilities of the Microsoft Expression Encoder tool, and using parsing + code that consumes caption as a raw file format and converts that format + into the Silverlight API's TimelineMarkers representation. + This technique primarily addresses how to use the Expression Encoder + technique, along with media player templates that are also provided + by Expression Encoder or related Silverlight SDKs such as the Smooth + Streaming SDK.

    +

    At a pure architecture level, Silverlight uses the TimelineMarkers API + to display caption text at synchronized times. The Expression Encoder + and Expression Blend tools provide a front end to drive the TimelineMarkers API + for the supported formats. The intention of the architecture is so + that Silverlight as a run-time has a base architecture that could potentially + use any existing or future timed text format, but the tools for Silverlight + (rather than built-in features of the runtime) provide the optimized + workflow for producing captioned media projects.

    +

    A procedure for using the Expression Encoder and Expression Blend + tools to produce a Silverlight media player application that can consume + timed text in TTML format is provided as Example 1 in this technique. + (Note: prior to the approval of TTML by W3C, DFXP was a format that + used much of the eventual TTML vocabulary. In tools that predate TTML, + this format is often identified as DFXP.)

    +

    A purely code-based parsing technique, with the goal of avoiding Expression + Encoder dependencies, is necessarily more complex. This is because + there are multiple issues to solve:

    +
      +
    • Obtaining and validating the timed text file
    • +
    • Parsing the format into general information items like timings, + text, format etc. that are either consumable directly in a Silverlight + API, or useful as intermediates
    • +
    • Using the timecode information to create TimelineMarker representations + for each timed text entity
    • +
    • Associating the TimelineMarkers with media loaded + by the player
    • +
    • Finding a place to store the additional formatting that is conveyed, + including the text and any formatting
    • +
    • Handling events from TimelineMarkers in the media + player, in such a way that text and formatting behavior can be retrieved + and presented in the Text part of the player UI
    • +
    +
    +

    Text Captioning Formats

    +

    There are several existing text-based formats that are used for text + captioning of prerecorded media. The following are supported as formats + if using the Expression Encoder tool as shown in Example 1 (where the + Expression Encoder generated Silverlight application uses the existing + Silverlight MediaPlayerTemplate and the TimedTextLibrary component.) + For more information on which timed text formats can be referenced + in an Expression Encoder project, see About + Captioning (Expression documentation on MSDN).

    + +

    The following are not supported directly in Expression Encoder templates. + To use these formats, application authors would have to write parsing + logic, as shown in Example 2:

    +
      +
    • MPEG Part 17 / 3GPP Timed Text. For more information, see ISO/IEC + 14496-17:2006 on ISO site.
    • +
    • Other formats that have not realized wide adoption, for example + Universal Subtitle Format.
    • +
    • In addition to these formats, other formats for device-specific + recorded media (such as DVD encoded tracks) could be cross-purposed + for use by streaming/online media.
    • +
    +

    Rather than build the parsing logic for all these formats into the + Silverlight runtime, or choosing just one of these formats to support, + the Silverlight design for text captioning at the core level instead + makes the TimelineMarkers property of a MediaElement writeable, + independently of the value of Source. The format of + each TimelineMarker in the collection is very simple: + a time value expressed in the format, and the text value of the text + for that synchronized caption. The time format for TimelineMarkers is + documented as TimelineMarker + reference on MSDN. Converting timed text formats to TimelineMarkers form + as consumed by the Silverlight core can be done by following any of + the following application design patterns:

    +
      +
    • Authoring the project using Expression Encoder, and using the + Expression MediaPlayerTemplate as the media player UI. In this case, + Expression produces a Silverlight application that includes assemblies + that are generated from code templates. The default build of the + project provides a working library that handles all tasks related + to timed-text format conversion, from the formats as documented at About + Captioning (Expression documentation on MSDN).
    • +
    • The templates of an Expression Encoder project can also be edited, + either editing the XAML for the UI by altering the template, or by + altering the C# code files that define various aspects of the media + player logic, including the timed text format parsers. Then the project + can be rebuilt using the desired customizations. Using this technique, + it is possible to adapt the code to support timed text formats that + are not directly supported in the Expression Encoder project UI.
    • +
    • Using a 3rd party media player implementation that also includes + a codebase for processing timed text formats, producing TimelineMarkers, + and displaying the captions in the player-specific UI.
    • +
    • Including a library that handles just the format parsing, and + using APIs of this library as part of the Silverlight application + code-behind.
    • +
    • Writing all logic that is necessary for timed text parsing AND + application UI display, and including it all in the main Silverlight + application library.
    • +
    +
    +

    Examples

    +
    +

    Using Expression Encoder and Expression Blend to produce + a Silverlight media player project from tool output and templates

    + +

    By far the simplest technique for incorporating existing timed-text + information is to use Microsoft Expression Encoder and the media player + templates that an Expression Encoder project produces by default. You + can use timed text in any of the following formats: DFXP, SAMI, SRT, + SUB, and LRC. Associating a caption file with a media source is done + as an "import" operation in the Expression Encoder tool. + However, the "import" does not necessarily mean that the + timed text file is integrated into the media stream; Silverlight authors have the option + to preserve the file separation. This is useful if the application is obtaining + timed text from a third party source in real-time, or if Silverlight authors have a + production pipeline that makes it difficult to have the captioning + ready in time to be encoded in the stream along with the audio-visual + source files. For third-party timed text files that are served directly + from the third party's HTTP servers, it can be useful to supply a dummy + URL in the initial project encoding. The output of the Expression Encoder + project parameterizes many of the project settings at the HTML level. + This makes it possible to change the URL at any time prior to deployment + without having to rebuild the project. The following code is the HTML + output of a sample Expression Encoder project. Note the CaptionSources + node in the initparams; that is the information item that informs the + Expression Encoder templates where to find the timed text file.

    +
         <object data="data:application/x-silverlight," type="application/x-silverlight" width="100%" height="100%">
    +       <param name="source" value="MediaPlayerTemplate.xap"/>
    +       <param name="onerror" value="onSilverlightError" />
    +       <param name="autoUpgrade" value="true" />
    +       <param name="minRuntimeVersion" value="4.0.50401.0" />
    +       <param name="enableHtmlAccess" value="true" />
    +       <param name="enableGPUAcceleration" value="true" />
    +       <param name="initparams" value='playerSettings = 
    +         <Playlist>
    +           <AutoLoad>true</AutoLoad>
    +           <AutoPlay>true</AutoPlay>
    +           <DisplayTimeCode>false</DisplayTimeCode>
    +           <EnableOffline>false</EnableOffline>
    +           <EnablePopOut>false</EnablePopOut>
    +           <EnableCaptions>true</EnableCaptions>
    +           <EnableCachedComposition>true</EnableCachedComposition>
    +           <StretchNonSquarePixels>NoStretch</StretchNonSquarePixels>
    +           <StartMuted>false</StartMuted>
    +           <StartWithPlaylistShowing>false</StartWithPlaylistShowing>
    +           <Items>
    +             <PlaylistItem>
    +             <AudioCodec></AudioCodec>
    +             <Description></Description>
    +             <FileSize>2797232</FileSize>
    +             <IsAdaptiveStreaming>false</IsAdaptiveStreaming>
    +             <MediaSource>thebutterflyandthebear.wmv</MediaSource>
    +             <ThumbSource></ThumbSource>
    +             <Title>thebutterflyandthebear</Title>
    +             <DRM>false</DRM>
    +             <VideoCodec>VC1</VideoCodec>
    +             <FrameRate>30.00012000048</FrameRate>
    +             <Width>508</Width>
    +             <Height>384</Height>
    +             <AspectRatioWidth>4</AspectRatioWidth>
    +             <AspectRatioHeight>3</AspectRatioHeight>
    +             <CaptionSources>
    +               <CaptionSource Language="English" LanguageId="eng" Type="Captions" Location="thebutterflyandthebear.eng.capt.dfxp"/>
    +             </CaptionSources>
    +           </PlaylistItem>
    +         </Items>
    +      </Playlist>'/>       
    +   </object>
    +   
    +

    The templates include a library that handles any parsing requirements + for the chosen timed text format, both at the level of getting the + basic text and timing into the TimelineMarkers used + by the run-time MediaElement, and for preserving + a subset of format information that can reasonably be crossmapped + from the formatting paradigm of the source (typically HTML/CSS) into + the Silverlight text object model of the text element that displays + the captions in the running Silverlight application.

    +

    The following is a brief description of the procedure for creating + a project that incorporates a separate timed text file.

    +
      +
    1. From the initial Expression Encoder screen, select New Project + from the File menu.
    2. +
    3. In the Load a new project dialog, select Silverlight + Project.
    4. +
    5. From the File menu, select Import. Choose the primary media source + file the project will use.
    6. +
    7. In the Text tab, find the listing for the media source file. Click + the + icon to the right of the file name. This opens + a file dialog.
    8. +
    9. Choose a timed text file to add to the project.
    10. +
    11. Build the project. By default the project produces a complete + output folder. The folder includes the media player template XAP, + the timed text file as a separate file, and additional libraries + and XAPs that support the basic template and/or the timed text capabilities.
    12. +
    13. Optionally, use the features in the Templates tab of Expression + Encoder to generate a template copy. You can edit the template copy + in other tools such as Expression Blend or Visual Studio, to change + the layout or behavior from the default media player template. Template + editing can address requirements such as applying a particular branding + or "look" to the player user interface.
    14. +
    +

    The following is a screenshot of the Expression Encoder (version 4) + interface. The + icon mentioned in Step 4 is highlighted + in this screenshot with a red diamond. The Templates tab + mentioned in Step 7 is on the right side, top-middle. Note that all + tabs of an Expression user interface are dockable; the orientations + shown here are the default, but could be in different locations on + any given computer or configuration.

    +
    + + +
    Expression Encoder screenshot
    + +
    + +
    +
    +

    Code parses timed text; MediaElement handles MarkerReached, + displays marker text in application-defined TextBox

    + +

    This example defines a very simple media player class that includes + a display surface, basic controls, and a text display for captions + as part of its default template. The usage code for this control in + XAML is simple, but only because the majority of the implementation + is present in the definition of the media player class.

    +

    + The following is example usage XAML:

    +
     <local:SimpleMediaPlayerWithTT Width="480" Height="360" CaptionUri="testttml.xml" MediaSourceUri="/xbox.wmv" />
    +    					
    +

    Note the attributes CaptionUri and SimpleMediaPlayerWithTT. Each + of these is a custom property of the media control class TTReader. + CaptionUri in particular references a URL, in this case a local URL + from the same server that serves the Silverlight XAP. The timed text + file could come from a different server also, but comes from a local + server in this example to conform to the behavior of the test file.

    +

    The following is the generic.xaml default template for the media player + control. The template is mainly relevant for showing the named elements + that are shown in the initialization code.

    +
                   <ControlTemplate TargetType="local:SimpleMediaPlayerWithTT">
    +                   <Border Background="{TemplateBinding Background}"
    +                           BorderBrush="{TemplateBinding BorderBrush}"
    +                           BorderThickness="{TemplateBinding BorderThickness}">
    +                       <Grid x:Name="vroot">
    +                           <Grid.RowDefinitions>
    +                               <RowDefinition Height="*"/>
    +                               <RowDefinition Height="50"/>
    +                               <RowDefinition Height="80"/>
    +                           </Grid.RowDefinitions>
    +                           <MediaElement x:Name="player" AutoPlay="False"/>
    +                           <StackPanel Orientation="Horizontal" Height="50" Grid.Row="1">
    +                               <Button x:Name="player_play">Play</Button>
    +                               <Button x:Name="player_pause">Pause</Button>
    +                               <Button x:Name="player_stop">Stop</Button>
    +                           </StackPanel>
    +                           <ScrollViewer x:Name="scroller" Height="50" Grid.Row="2">
    +                           <TextBox IsReadOnly="True" x:Name="captions"/>
    +                           </ScrollViewer>
    +                       </Grid>
    +                   </Border>
    +               </ControlTemplate>
    +               
    +

    The following is the initialization code that is for general infrastructure. OnApplyTemplate represents + the code wiring to the template-generated UI.

    +
       public class SimpleMediaPlayerWithTT : Control
    +   {
    +       MediaElement player;
    +       TextBox captions;
    +       public SimpleMediaPlayerWithTT()
    +       {
    +           this.DefaultStyleKey = typeof(SimpleMediaPlayerWithTT);
    +       }
    +       public override void OnApplyTemplate()
    +       {
    +           base.OnApplyTemplate();
    +           player = this.GetTemplateChild("player") as MediaElement;
    +           captions = this.GetTemplateChild("captions") as TextBox;
    +           scroller = this.GetTemplateChild("scroller") as ScrollViewer;
    +           //event hookups and prop inits
    +           player.MediaOpened += new RoutedEventHandler(OnMediaOpened);
    +           player.MediaFailed += new EventHandler<ExceptionRoutedEventArgs>(OnMediaFailed);
    +           player.Source = this.MediaSourceUri;
    +           player.MarkerReached+=new TimelineMarkerRoutedEventHandler(player_MarkerReached);
    +           Button player_play = this.GetTemplateChild("player_play") as Button;
    +           player_play.Click += new RoutedEventHandler(player_play_click);
    +           Button player_pause = this.GetTemplateChild("player_pause") as Button;
    +           player_pause.Click += new RoutedEventHandler(player_pause_click);
    +           Button player_stop = this.GetTemplateChild("player_stop") as Button;
    +           player_stop.Click += new RoutedEventHandler(player_stop_click);
    +       }
    +       // mediaelement in template events
    +       void OnMediaOpened(object sender, RoutedEventArgs e)
    +       {
    +           LoadCaptions(captionUri);
    +       }
    +       void OnMediaFailed(object sender, ExceptionRoutedEventArgs e)
    +       {
    +       }
    +       void player_MarkerReached(object sender, TimelineMarkerRoutedEventArgs e)
    +       {
    +           captions.SelectedText = e.Marker.Text + "\n";
    +           scroller.ScrollToVerticalOffset(scroller.ScrollableHeight);
    +       }
    +       void player_play_click(object sender, RoutedEventArgs e)
    +       {
    +           player.Play();
    +       }
    +       void player_pause_click(object sender, RoutedEventArgs e)
    +       {
    +           player.Pause();
    +       }
    +       void player_stop_click(object sender, RoutedEventArgs e)
    +       {
    +           player.Stop();
    +       }
    +       // properties
    +       private Uri captionUri;
    +       public Uri CaptionUri
    +       {
    +           get { return captionUri; }
    +           set { captionUri = value; }
    +       }
    +       private Uri msUri;
    +       public Uri MediaSourceUri
    +       {
    +           get { return msUri; }
    +           set { msUri = value; }
    +       }
    +       
    +

    The following is the logic that is particular to obtaining the separate + caption file. Some of this logic is referenced in the preceding template-specific + event handlers. This example uses the asynchronous WebClient technique + to request the file result of the CaptionUri. Make + sure to use AutoPlay=false or some other means to allow + time for the caption file to download before attempting to play the + media file.

    +
           private void LoadCaptions(Uri captionURL)
    +       {
    +           WebClient wc = new WebClient();   // Web Client to download data files
    +           if (captionURL != null)
    +           {
    +               wc.DownloadStringCompleted +=
    +                   new DownloadStringCompletedEventHandler(OnDownloadStringCompleted);
    +               wc.DownloadStringAsync(captionURL);
    +           }
    +       }
    +       private void OnDownloadStringCompleted(object sender, DownloadStringCompletedEventArgs e)
    +       {
    +           if (!e.Cancelled && e.Error == null && e.Result != "")
    +           {
    +               string xml = e.Result.Trim();
    +               ParseCaptionData(new StringReader(xml));
    +           }
    +       }
    +       
    +

    The actual parsing can be done using a combination of the "XML + to Linq" facilities of an optional Silverlight library, and + standard .NET Framework string format APIs from the Silverlight core. + An implementation is NOT provided here, due to length considerations. + TTML supports a number of profiles and capabilities. The basic pattern + to follow in the implementation is to obtain the necessary text and + timing information, and to pass it to a function that might resemble + the following code template. This code template takes the raw information, + generates a new TimelineMarker, and adds it to the + collection assigned to the active MediaElement as + identified by "player" in the application.

    +
           public void AddMediaMarker(string time, string type, string data)
    +       {
    +           TimelineMarker marker = new TimelineMarker();
    +           marker.Time = new TimeSpan(0,0,(Convert.ToInt32(time.Trim())/1000));
    +           // this logic could vary depending on how time is formatted in the input string; this one assumes raw milliseconds
    +           marker.Type = type;
    +           marker.Text = data.Trim();
    +           player.Markers.Add(marker);
    +       }
    +
    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. That + application plays media that is expected to have text captioning.
    2. +
    3. Check that the text area in the textbox shows captions for the + media, and that the captions synchronize with media in an expected + way.
    4. +
    +
    +

    Expected Results

    +

    #2 is true.

    +
    +

    Resources

    + + + +
    diff --git a/techniques/silverlight/SL29.html b/techniques/silverlight/SL29.html new file mode 100644 index 0000000000..50c2b3d939 --- /dev/null +++ b/techniques/silverlight/SL29.html @@ -0,0 +1,181 @@ +Using Silverlight "List" Controls to Define Blocks that + can be Bypassed

    Using Silverlight "List" Controls to Define Blocks that + can be Bypassed

    ID: SL29

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use some of the basic user interface + objects in Silveright to produce blocks of content that are identified + as a "List" to accessibility frameworks and to Silverlight's + own tab sequence navigation behavior.

    +

    Using the "List" technique results in a tab sequence behavior + whereby that element is treated as a single tab stop, even if that + element has consituent elements (the list items) that would otherwise + be considered additional tab stops in the main tab sequence. In the + default key handling, when the user presses the TAB key while focus + is on a List, the focus goes to the next element after the List. To + focus the items of the list, the user would press the Arrow keys rather + than TAB. In the Silverlight programming model for controls, this tab + sequence behavior is expressed by the TabNavigation property + holding the value of Once. The Silverlight ListBox is + a control that reports itself as "List" role, and that has + a default TabNavigation.Once value. + Thus ListBox as + per this technique is a lightweight technique for producing blocks + that can be bypassed. It is specifically a lightweight technique because + it can be accomplished by writing simple application-level XAML and + using only the Silverlight core libraries.

    +

    Silverlight also supports more full-featured techniques for producing + bypass blocks that are based on common user interface features such + as menus or toolbars. However, using toolbars in Silverlight is inherently + not as lightweight because the Silverlight core libraries themselves + do not include a ready-made toolbar. Silverlight provides a ContextMenu as + part of the Silverlight Toolkit extensions, but the behavior of this + particular menu does not easily address the bypass block scenario. + Silverlight includes all the infrastructure and necessary base classes + for defining a toolbar or a menu that could address the bypass block + scenario. Many third-party control implementations of menus and toolbars + exist, either as part of control packages that are sold by control + vendors, or through community mechanisms such as CodePlex or third-party + sites that provide free source code. For some examples, see the following:

    + +

    If application authors use a built-in control such as ListBox where + the accessibility framework reported role is not traditionally associated + with a navigation role, it is a best practice to set AutomationProperties.Name such + that the name informs the user of the purpose of the list control. + Otherwise, the role alone leaves this ambiguous. For example, an author + might name the list control "Navigation control".

    +

    Often the List control itself is focusable. So long as the List control + has a visual focus indicator, that behavior might be acceptable. However, + it might provide a better user experience to deliberately have the + List itself non-focusable, and instead have focus fall to the first + List item when focus reaches that region. Otherwise, the List might + be perceived as an "extra" tab stop to some users. To enable + that behavior, set IsTabStop to + false on the List control. The List itself still provides the intended + tab navigation behavior, and is still reported and identified to accessibility + frameworks and assistive technologies, even when the List container + is not focusable. This is shown in Example 1, by setting IsTabStop as + part of a Style.

    +

    When an accessibility framework presents a List, assistive technologies + are generally expected to continue to support use of the same key behavior + as the default behavior, and to report to users that the item is a + List when it is focused. If assistive technologies use the accessibility + framework APIs for navigation, the items in the list are considered + child elements. Navigating either by spatial direction (e.g. NAVDIR_RIGHT + in MSAA) or sequential direction (e.g. NAVDIR_NEXT in MSAA) skips the + list items and goes to the spatial/next peer.

    +

    Examples

    +
    +

    Customize the behavior and appearance of a ListBox to + construct a navigation control that can be bypassed

    + +

    In this example, several properties that influence the items presentation + behavior of the Silverlight core control ListBox are + adjusted to make it suitable for a navigation control. The behavior + of this control is that when the tab sequence reaches the control, "next" or + spatial navigation continues on to other controls, rather than through + the child controls of the list's items/options. This is enabled and + properly reported because ListBox reports its accessibility + framework role as "List", uses TabNavigation = Once as + default (because it is the default, TabNavigation does not have to + be set explicitly in the markup). ListBox has default + key handling for the arrow keys (to enable traversing the choices in + the menu by keyboard-only). The control could also be visually a menu + or perhaps other user interface control metaphors, depending on how + it is visually templated and composited. Regardless of appearance, + the accessibility framework and any assistive technologies based on + that framework will treat the control as a "List". This example + is templated as a horizontally oriented toolbar-type control. The items + in this example are Button controls, but could be + templated to not appear quite as button-like, or could instead use + another focusable control for the items such as a read-only TextBox.

    +
    <UserControl x:Class="TabNavigation.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    +   <StackPanel x:Name="LayoutRoot" Background="White">
    +       <ListBox AutomationProperties.Name="Navigation Control">
    +           <ListBox.ItemsPanel>
    +               <ItemsPanelTemplate>
    +                   <StackPanel Orientation="Horizontal"/>
    +               </ItemsPanelTemplate>
    +           </ListBox.ItemsPanel>
    +           <ListBox.ItemContainerStyle>
    +               <Style TargetType="Control">
    +                   <Setter Property="IsTabStop" Value="False"/>
    +               </Style>
    +           </ListBox.ItemContainerStyle>
    +           <Button>Home</Button>
    +           <Button>Search</Button>
    +           <Button>Tools</Button>
    +           <Button>Help</Button>
    +       </ListBox>
    +   </StackPanel>
    +   <Button>Button here to show a focusable peer control beyond the list</Button>
    +</UserControl>
    +
    +

    The following is an illustration of what such a control might look + like:

    +
    + + +
    Screen shot of a focusable control beyond a list of buttons
    + +
    +

    This example is shown in operation in the working example of Tab Navigation.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Press TAB key to traverse typical tab sequence within the Silverlight + application. Verify that common areas in the user interface composition + ("blocks") that are reporting the List role per this technique + can be bypassed without having to tab through each constituent part + (the "items/children" of the List).
    4. +
    5. Verify that the list children are still accessible by keyboard, + by using ARROW keys rather than TAB.
    6. +
    7. Engage an accessibility framework test tool such as UIAVerify. + Examine roles in the automation tree, and verify that the List used + for bypass behavior reports a combination of name+role that is consistent + with the behavior.
    8. +
    9. Use a screen reader to verify that name and role are reported + properly.
    10. +
    +
    +

    Expected Results

    +

    #2 and #3 are true, and either #4 OR #5 are true.

    +
    +

    Resources

    + + + +
    diff --git a/techniques/silverlight/SL3.html b/techniques/silverlight/SL3.html new file mode 100644 index 0000000000..18198b8531 --- /dev/null +++ b/techniques/silverlight/SL3.html @@ -0,0 +1,158 @@ +Controlling Silverlight MediaElement Audio Volume

    Controlling Silverlight MediaElement Audio Volume

    ID: SL3

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to adjust the volume for media + that is played in Silverlight applications, as implemented through + incorporating the Silverlight MediaElement object. + By default, a MediaElement will start playing its + media as soon as the UI loads completely AND the media source file + is downloaded. For details, see .

    +

    At any given time, a Silverlight MediaElement is associated + with exactly one media source as specified by the Source property + URI value. That source might be audio-only, or audio-video. The Volume property + of MediaElement affects the audio playback volume + of that particular source when it is playing. The Silverlight plug-in + does not have a user option that adjusts the volume of ALL Silverlight + applications as run within it, or a standardized user interface that + is always present for all uses of MediaElement. Therefore + it is the responsibility of Silverlight application authors to provide + an adequate set of user interface controls, including volume adjustment, + whenever the Silverlight application plays media that has an audio + component.

    +

    Examples

    +
    +

    Providing a volume control and a Mute control as part + of a set of user interface controls that go with a MediaElement

    + +

    In addition to the Play Pause Stop controls, application authors can + also provide a dedicated control that changes the Volume property + of the MediaElement. The typical control for setting + a discrete volume is Slider, because Slider is + designed for input of discrete values from a range. Adjusting Volume with + a data bound Slider changes the volume of any actively + playing media, independent of the system volume or of any other audio + source controlled by Silverlight. For Volume as set with the Slider, + the Binding in XAML declares the interaction between + the control and the MediaElement, without requiring + an event handler. However, not all users will be able to interact quickly + with a Slider, particularly if they are not using + a mouse. To help these users, application authors should also include + a "Mute" control. Rather than setting Volume to + 0, application authors should instead set IsMuted to + true. Note that Volume and IsMuted values + are not directly related; if IsMuted is set to true, + that does not set Volume to 0, nor does setting Volume to + zero cause IsMuted to be set true.

    +
    <UserControl x:Class="MediaElementControls.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +  >
    +   <Grid x:Name="LayoutRoot">
    +       <StackPanel>
    +           <MediaElement x:Name="media" Source="/xbox.wmv"
    +          Width="300" Height="300" 
    +          AutomationProperties.Name="Video of new Fable game for XBox"           
    +       />
    +           <Grid Name="UIControls">
    +               <Grid.ColumnDefinitions>
    +                   <ColumnDefinition Width="*" />
    +                   <ColumnDefinition Width="*" />
    +                   <ColumnDefinition Width="*"/>
    +               </Grid.ColumnDefinitions>
    +               <Grid.RowDefinitions>
    +                   <RowDefinition Height="*" />
    +                   <RowDefinition Height="Auto" />
    +                   <RowDefinition Height="20" />
    +               </Grid.RowDefinitions>
    +               <Button Click="StopMedia" 
    +    Grid.Column="0" Grid.Row="1" Content="Stop" />
    +               <Button Click="PauseMedia" 
    +    Grid.Column="1" Grid.Row="1" Content="Pause" />
    +               <Button Click="PlayMedia" 
    +    Grid.Column="2" Grid.Row="1" Content="Play" />
    +               <Button Click="MuteMedia" 
    +   Grid.Row="2" Grid.Column="0" Content="Mute" />
    +               <TextBlock Name="VolumeLabel" Grid.Row="2" Grid.Column="1" HorizontalAlignment="Right">Volume</TextBlock>
    +               <Slider Height="20"
    +           Value="{Binding Volume, Mode=TwoWay, ElementName=media}"
    +           Minimum="0" Maximum="1"
    +           Grid.Row="2" Grid.Column="2" Grid.ColumnSpan="2"
    +               AutomationProperties.LabeledBy="{Binding ElementName=VolumeLabel}"/>
    +           </Grid>
    +       </StackPanel>
    +   </Grid>
    +</UserControl>
    +
    +

    The following is the C# logic.

    +
     private void StopMedia(object sender, RoutedEventArgs e)
    + {
    +     media.Stop();
    + }
    + private void PauseMedia(object sender, RoutedEventArgs e)
    + {
    +     media.Pause();
    + }
    + private void PlayMedia(object sender, RoutedEventArgs e)
    + {
    +     media.Play();
    + }
    + private void MuteMedia(object sender, RoutedEventArgs e)
    + {
    +    Button target = sender as Button;
    +    // mute if not muted, unmute if already muted, in either case make sure the button content for text and accessibility info is updated
    +    if (!media.IsMuted)
    +    {
    +       media.IsMuted = true;
    +       target.Content = "Unmute";
    +    }
    +    else
    +    {
    +        media.IsMuted = false;
    +        target.Content = "Mute";
    +    }
    + }
    +
    +

    This example is shown in operation in the working example of Media Element Controls.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. It is + expected that the application incorporates a MediaElement.
    2. +
    3. Check that a control is available for controlling volume and that + the Volume control controls the volume of the playing media, independently + from system volume.
    4. +
    5. Check that control is available for muting, and that the Mute + control mutes the volume of the playing media, independently from + system volume.
    6. +
    +
    +

    Expected Results

    +

    #2 OR #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL30.html b/techniques/silverlight/SL30.html new file mode 100644 index 0000000000..a382311253 --- /dev/null +++ b/techniques/silverlight/SL30.html @@ -0,0 +1,162 @@ +Using Silverlight Control Compositing and AutomationProperties.Name

    Using Silverlight Control Compositing and AutomationProperties.Name

    ID: SL30

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to properly apply Silverlight control + composition techniques that can present text and non-text in UI as + part of the same control. This technique explains the consequences + that using control composition has on how that control is reported + to the accessibility frameworks that Silverlight supports.

    +

    Silverlight control composition concepts are relevant either to Silverlight + developers who define and package a Silverlight control for use by + other Silverlight authors, or for Silverlight application authors that + use Silverlight controls in their UI but use the content properties + of such controls to include several other elements in a composite layout.

    +

    In Silverlight programming and UI definition, Silverlight authors can use control + composition to define a parent control that initiates an action. The + control can have component parts, such as text and non-text composition + pieces that display within the control and have equivalent meaning. + Silverlight authors can rely on the text component of the control to + provide any text alternative for purposes other than the accessibility + framework. However, Silverlight authors should declare alternative + text on the control that is specifically consumed by accessibility + frameworks, by setting AutomationProperties.Name as + an attribute in XAML. In most cases, this text can be the same as the + visible text in the control composition, per the definition of 'label' + in SC 4.1.2.

    +

    Note that this technique does not result in a duplication of text, + as explained in H2. + This is because the element parts of control composition are either + inherently not focusable separately, or can be specified by instance-specific + properties to behave as if they cannot be focused. The parts in Silverlight + composition are not promoted to the accessibility frameworks as parts + of an application-specific UI Automation tree, so that control composition + as an implementation detail does not interfere with the usage of controls + by Silverlight application authors. The primary source of accessibility-related + information is the specific AutomationProperties.Name property + as set on the parent control in the composition, which is set by the + application author rather than the control author.

    +

    The control author does specify the information that is reported to + accessibility frameworks as the "ClassName", which is often + used by assistive technologies for identification purposes and is appended + to any "Name" value. For example, if an application author + includes a "Widget" control, and gives it an AutomationProperties.Name value + of "Show Map", an assistive technology might identify the + element as "Show Map widget". The "Show Map" part + comes from the application author code, and the "widget" part + comes from the Widget control implementation code.

    +

    Examples

    +
    +

    Button is composed with a StackPanel that contains nontext + and text content

    + +

    In this example the TextBlock that goes with the + graphic image conveys the text information for non-accessibility purposes. + The Button has internal composition that combines + text from a non-focusable TextBlock part and an image + part. Therefore the "Pause" Text is not promoted to serve + as "Name" through built-in Button automation + peer logic. The Silverlight application author is responsible for explicitly + setting AutomationProperties.Name on the Button so + that the text equivalent is available to the accessibility framework. + This example shows the XAML UI. The logic, which might be attached + to Button with a Click handler, is + not shown.

    +
     <Button
    +   Height="20" Width="50" AutomationProperties.Name="Pause" 
    + >
    +   <StackPanel Orientation="Horizontal" >
    +     <Image Height="12" Width="12" Source="/icon_pause.png"/>
    +     <TextBlock Text="Pause"/>
    +   </StackPanel>
    + </Button>
    +
    +

    This example is shown in operation in the working example of Button Nontext Text Composition.

    + +
    +
    +

    Button composed, using binding and resource references + for strings

    + +

    This example is similar to Example 1 and produces the same result + at run time. This example shows the preferred technique of using the + Silverlight data binding and resource features to ensure that the strings + for text content and accessibility are the same strings. Also, this + gets the strings out of the XAML source and makes them simpler to localize + or edit. For more information on using resource strings through binding, + see Localizing + XAML topic on MSDN.

    +
     <Application.Resources>
    +  <resx:Resources x:Key="UIResourceStrings" />
    + </Application.Resources>
    +  ...
    + <Button
    +   Height="20" Width="50"
    +   AutomationProperties.Name="{Binding PauseUIString, Source=UIResourceStrings}" />
    + >
    +   <StackPanel Orientation="Horizontal" >
    +     <Image Height="12" Width="12" Source="/icon_pause.png"/>
    +     <TextBlock
    +       Text="{Binding PauseUIString, Source=UIResourceStrings}"/>
    +   </StackPanel>
    + </Button>
    +
    + +
    +

    Tests

    +
    +

    Automation tree verifier

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Use a verification tool that is capable of showing the full automation + tree, and an object’s name text alternative as part of the tree. + (For example, use UIAVerify or Silverlight Spy; see Resources links.)
    4. +
    5. Check that the AutomationProperties.Name appears + as the Name value for identification in the automation + tree, whenever a composite control that has both text and non-text + elements is encountered.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +
    +

    Screen reader

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Engage the screen reader. With focus inside the Silverlight content + area, press TAB to focus to a composite control where both text and + non-text elements are present.
    4. +
    5. Check that the Name as applied to the control + instance, along with the class name of the control, is read by the + screen reader.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL31.html b/techniques/silverlight/SL31.html new file mode 100644 index 0000000000..b55a451788 --- /dev/null +++ b/techniques/silverlight/SL31.html @@ -0,0 +1,202 @@ +Using Silverlight Font Properties to Control Text Presentation

    Using Silverlight Font Properties to Control Text Presentation

    ID: SL31

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to change the presentation / visual + appearance of text, by setting several of the font-specific properties + in the Silverlight API. Changing such properties does not change the + semantic meaning of the text, nor does it alter the representation + of the text that is available to assistive technologies through the + Silverlight support of the UIA accessibility framework. By using font + properties, it is possible to introduce a wide variety of presentation + changes to fonts that do not introduce semantic elements that interfere + with an assistive technology's view of text in the Silverlight application. + In particular, adjusting font properties will make it possible to avoid + any need for use of images of text, yet still provide a wide range + of choices for text presentation.

    +

    Silverlight font properties exist on all controls, as well as on other + text elements that are not true controls. For controls, the font properties + apply in any case where the control enables a presentation mode that + has enclosed text areas in its layout. By setting Silverlight font + properties, it is possible to adjust presentation of font features + without changing the structural connotation of that control, or the + value of any control-specific property that contains plain-text. For + example, the FontSize property can be set on a Paragraph (not + a control) or on a Button (a control, and in this + case the font size changes apply to any text displayed in the button + content area). Font properties are also inheriting properties, meaning + that if applying a font property value to a container in a relationship, + those font property values can apply to child elements in the relationship. + For example, if a FontSize is applied to a RichTextBox, + that FontSize value is used by default by all the Paragraph items + displayed in the RichTextBox.

    +

    Similar to CSS, Silverlight font properties can be grouped as a Style. + That Style can be applied to all instances of a text + element type (for example to all cases of Paragraph) + or specifically referenced as a resource that is only used by certain + instances of a text element type. Either way, the Style feature + enables the separation of presentation from semantics for text elements, + and enables workflows where content authors supply the semantic text + and design-oriented authors adjust the related Silverlight styles. + For more information on the Silverlight concept of styles, see Control + Customization on MSDN.

    +

    The following Silverlight font properties are useful to style text + and avoid the need for text in images. Links in this list refer to + the Control class version of these properties.

    +
      +
    • The FontFamily property + is used to display the code aspect in a monospace font family (specifically, + FontFamily="Courier New").
    • +
    • The FontSize property + is used to display the text in a larger size.
    • +
    • The FontStyle property + is used to display text in italics.
    • +
    • The FontWeight property + is used to set how thick or thin characters in text should be displayed.
    • +
    • The FontStretch property + is used to control the spacing of letters in text.
    • +
    • The Foreground property + is used to display the color of text or text containers.
    • +
    • The Background property + can be used to display text on a non-text background.
    • +
    +

    So long as images of text are avoided, the text within a Silverlight + text element can be reported to the UI Automation accessibility framework + that Silverlight supports. That text is reported using the same basic + text content as is used for semantic text display in the UI. In other + words, exposing that text to assistive technologies that use UIA as + a framework does not require the Silverlight application author to + resort to automation-specific override properties such as AutomationProperties.HelpText; + the automation peers for text elements report all necessary text content + to automation as a built-in behavior of the text element controls. + For more information on UI Automation and text containers, see .

    +
    +

    CSS versus Silverlight font properties

    +

    Related CSS techniques mention that users can override any page-declared + CSS styling techniques, by invoking browser-specific features. For + example, using Internet Explorer, a user can use Tools / Internet Options, + Appearance / Accessibility to override certain classifications of CSS-controlled + font properties when displaying HTML documents, or to use a user-specific + style sheet for HTML documents. No browser-level equivalent feature + exists for user alteration of Silverlight text properties in the Silverlight + content area. Instead, application authors could supply controls that + enable similar font-property changing behavior, and include those controls + in the application-specific user interface. For more information on + this technique, see .

    +
    +
    +

    Glyphs

    +

    Silverlight API includes a related text presentation API Glyphs. Glyphs is + intended for specific decorative or niche language-support scenarios. + The Glyphs API does not offer as much UIA exposure + or the ability to programmatically change typical font properties; + the main scenarios for Glyphs are to package migrated + text content from document formats, or for purely decorative text in + a font that is not commonly found on a user system and only the glyphs + actually used in the Unicode string are subsetted into the Glyphs font + payload. If addressing the WCAG criteria, authors should avoid using Glyphs API + and instead use other text containers such as TextBox, + along with a font that is supplied in the application package or known + to exist on the end user system.

    +
    +

    Examples

    +
    +

    Run time applied font properties, style, and template

    + +

    This example illustrates applying runtime changes to a font property.

    +

    This example has UI in XAML, and logic in C#. The following is the + XAML.

    +
    <UserControl x:Class="DocumentStructure.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    +   <UserControl.Resources>
    +       <Style x:Key="NewStyle" TargetType="Control">
    +           <Setter Property="FontFamily" Value="Arial"/>
    +           <Setter Property="FontSize" Value="30"/>
    +           <Setter Property="Height" Value="40"/>
    +       </Style>
    +   </UserControl.Resources>
    +   <StackPanel x:Name="LayoutRoot" Background="White">
    +   <RichTextBox IsReadOnly="True" Name="rtb" FontFamily="Algerian" FontSize="20">
    +           <Paragraph>Call me Ishmael. Some years ago--never mind how long precisely--having little or no money in my purse, 
    +           and nothing particular to interest me on shore, I thought I would sail about a little 
    +and see the watery part of the world. It is a way I have of driving off the spleen and 
    +regulating the circulation. Whenever I find myself growing grim about the mouth; whenever 
    +it is a damp, drizzly November in my soul; whenever I find myself involuntarily pausing before 
    +coffin warehouses, and bringing up the rear of every funeral I meet; and especially whenever my 
    +<Hyperlink NavigateUri="http://en.wiktionary.org/wiki/hypo">hypos</Hyperlink>
    +get such an upper hand of me, that it requires a strong moral principle to prevent me from deliberately stepping into 
    +the street, and methodically knocking people's hats off--then, I account it high time to get to sea as soon as I can. 
    +This is my substitute for pistol and ball. With a philosophical flourish Cato throws himself 
    +upon his sword; I quietly take to the ship. There is nothing surprising in this. If they but knew it, 
    +almost all men in their degree, some time or other, cherish very nearly the same 
    +feelings towards the ocean with me.
    +           </Paragraph>
    +           <Paragraph>There now is your
    +               <Hyperlink 
    +               NavigateUri="https://en.wikipedia.org/wiki/New_York_Harbor">insular city of the Manhattoes</Hyperlink>
    +, belted round by wharves as Indian isles by coral reefs--commerce surrounds it 
    +with her surf. Right and left, the streets take you waterward. Its extreme downtown is the 
    +battery, where that noble mole is washed by waves, and cooled by breezes, which a few hours 
    +previous were out of sight of land. Look at the crowds of water-gazers there.
    +           </Paragraph>
    +           <Paragraph>Circumambulate the city of a dreamy Sabbath afternoon. 
    +Go from Corlears Hook to Coenties Slip, and from thence, by Whitehall, northward. What do you see?
    +--Posted like silent sentinels all around the town, stand thousands upon thousands of mortal men 
    +fixed in ocean reveries. Some leaning against the spiles; some seated upon the pier-heads; 
    +some looking over the bulwarks of ships from China; some high aloft in the rigging, as if striving 
    +to get a still better seaward peep. But these are all landsmen; of week days pent up in lath 
    +and plaster--tied to counters, nailed to benches, clinched to desks. How 
    +then is this? Are the green fields gone? What do they here?
    +           </Paragraph>
    +       </RichTextBox>
    +       <Button Name="swapper" Click="swapper_Click" Width="220">Swap styles</Button>
    +   </StackPanel>
    +</UserControl>
    +
    +

    The following is C# code:

    +
           private void swapper_Click(object sender, RoutedEventArgs e)
    +       {
    +           rtb.Style = this.Resources["NewStyle"] as Style;
    +       }
    +
    +

    This example is shown in operation in the working example of Document Structure.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Test that application of font properties as enabled in application + UI changes presentation, but does not change semantic meaning of + text.
    4. +
    5. Close the browser. Repeat the test with an accessibility framework + test tool running. There should be no difference in the structure + or relationships in the accessibility view beyond the presentation + changes.
    6. +
    +
    +

    Expected Results

    +

    #2 and #3 are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL32.html b/techniques/silverlight/SL32.html new file mode 100644 index 0000000000..97dc7d219c --- /dev/null +++ b/techniques/silverlight/SL32.html @@ -0,0 +1,286 @@ +Using Silverlight Text Elements for Appropriate Accessibility Role

    Using Silverlight Text Elements for Appropriate Accessibility Role

    ID: SL32

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to choose a Silverlight text container + that provides appropriate behavior and accessibility roles for different + types of text content. How those roles interact with existing assistive + technologies that are interpreting Silverlight under the larger concept + of being an "HTML control part" is also a factor in which + Silverlight text container should be used in an application's composition.

    +

    Text containers can identified by role to accessibility frameworks, + and each type of Silverlight text container uses a different role. + Application authors should choose text containers that combine the + desired behavior in the user interface with an accessibility role that + can be consumed by existing assistive technology implementations.

    +

    The Silverlight core libraries define the following classes that are + specifically intended as text containers:

    + +
    +

    UI Automation programmatic access

    +

    For programming information that is relevant for how Silverlight application + authors produce the application, each text container has its own object + model/API. That API is documented on MSDN, specifically for each class TextBox; RichTextBox; TextBlock.) + However, rather than using the Silverlight-specific object models, + most assistive technologies that are capable of reporting on Silverlight + will choose to use UI Automation (or MSAA) to obtain information about + the Silverlight elements in general. Text containers within the Silverlight + content are identified through UIA accessibility roles. This is because + the assistive technologies can use UI Automation to query for ANY relevant + text items from the content (and chrome) of the user agent / browser + host, not just those that come from Silverlight. That can include the + HTML content, items created from scripting, CSS or other plugin-internal + object models and so on. In other words, text from Silverlight is integrated + into the overall UI Automation view of the user agent host as the top-level + application in a platform view. Different types of "text" in + a general sense might appear as different UI Automation patterns, as + is described below.

    +
    +
    +

    TextBox

    +

    A TextBox within the Silverlight content area is + reported to UI Automation as an Edit role (through MSAA, as Editable + Text).

    +

    Edit controls are expected to implement the Value + pattern for UIA, so that the value of the edit area can be queried + or set by a client. Assistive technologies can use this value as + a text-string value for screen readers or other purposes.

    +

    In typical user interface design, a form with an input field also + includes a label or other explanatory text that is proximally close + to the input field. In order to maintain proper reading order, the + label should typically appear immediately before the input field. This + general model should also be used for Silverlight user interface design. + For more information on labeling for TextBox controls, + see .

    +
    +
    +

    RichTextBox

    +

    A RichTextBox within the Silverlight content area + is reported to UI Automation and MSAA as a Document role.

    +

    A RichTextBox can either be set to be a read-only + control, or left as a read-write control. In the latter case, users + can insert a text cursor and make changes to the text. It is more common + in Silverlight programming to set the RichTextBox to + be read-only; in this scenario the reason for using RichTextBox is + because TextBlock did not offer the range of text + formatting options that are possible from a RichTextBox.

    +

    In UIA, a document is generally expected to support the Text + pattern for UI Automation. However, to read the text from a RichTextBox, + the assistive technology does not necessarily have to implement code + that handles the entirety of the information that the Text pattern + reports.

    +
    +
    +

    More about the Text pattern

    +

    The Text pattern provides APIs to iterate over the internal structure + of a document and return text ranges. Each such text range can be queried + for specific properties, and can return its plain text string value + to UI Automation. Ranges can also be programmatically adjusted by the TextPattern/TextRange APIs. + The following is a snippet of a Silverlight-specific UI Automation + tree utility to give a general idea of the APIs involved. Note that + these are not specifically Silverlight APIs; they are .NET Framework + APIs. .NET Framework or Windows Automation APIs are generally what + is used for programming a UI Automation client, which runs on a platform + runtime rather than the Silverlight runtime. Using the Text pattern + is generally what is necessary in order for an assistive technology + to obtain a comprehensive view of the "value" for a document + role object.

    +
    private void FindTheTextPatterns_Click(object sender, RoutedEventArgs e)
    +{
    +   if (allSilverlight != null && allSilverlight.Count>0)
    +   {
    +       //for simplicity just processing item 0, not assuming more than one SL control
    +       //on the page because this app controls the page being loaded
    +       AutomationElementCollection documentsList = allSilverlight[0].FindAll(TreeScope.Descendants,
    +           new PropertyCondition(AutomationElement.ControlTypeProperty,ControlType.Document)
    +   );
    +   for (int j=0; j< documentsList.Count;j++) {
    +       TextPattern targetTextPattern = 
    +         documentsList[j].GetCurrentPattern(TextPattern.Pattern) as TextPattern;
    +       if (targetTextPattern!=null) {
    +           TextPatternRange tr = targetTextPattern.DocumentRange;
    +           MessageBox.Show(tr.GetText(Int16.MaxValue));
    +       }
    +   }
    +}
    +private void GetAllSilverlight()
    +{
    +   allSilverlight = this._clientAppRootInstance.FindAll(TreeScope.Descendants,
    +      new PropertyCondition(AutomationElement.ClassNameProperty, "MicrosoftSilverlight"));
    +}
    +
    +

    MSAA has only limited possibilities for interacting with a Document + role, and MSAA code for attempting to do so is not shown.

    +
    +
    +

    TextBlock

    +

    + TextBlock is reported as a Text role in UI Automation. TextBlock has + several important characteristics:

    +
      +
    • A TextBlock is always read-only; only the application + author can declare the text, users cannot change it.
    • +
    • A TextBlock is not considered to be a true control + in the Silverlight object model (it is not a class derived from Control). + The practical implications of this to accessibility scenarios is + that a TextBlock is not in the default tab sequence, + cannot be manually added to any tab sequence, and cannot be keyboard-focused + either programatically or by the user.
    • +
    • + TextBlock has a deliberately limited range of + block / span formatting options. If the application author desires + a wider range of formatting options, for example supporting a "Paragraph" metaphor + for blocks of text, a read-only RichTextBox should + be used instead.
    • +
    +

    If the user relies solely on navigating a Silverlight application + using the TAB sequence, such navigation will skip over any TextBlock in + the interface. This could have implications for how users who use screen + readers can interact with the Silverlight content. Screen readers typically + read text only from the currently focused element in cases where the + user is moving through the TAB sequence or changing focus within the + application, and thus cannot read the text from a TextBlock in + such a mode. However, most screen readers also have modes for reading + text that is not necessarily focusable. These are generally the same + modes that screen readers use for a conventional non-interactive HTML + document text. For example, some screen readers support a mode that + reads text by line, or by word. These modes can read text from a TextBlock.

    +
    +

    Examples

    +
    +

    Structure from a container that has non-semantic role + in UI Automation, and TextBlock for text

    + +

    If viewed as a UI Automation tree, the StackPanel and Grid do + not exist explicitly in the tree view, because they do not serve a + semantic role (only a presentation role). Rather, the tree consists + of the items that report some kind of semantic control type. The semantic + children of the containers are still reported in the order that they + were declared, when viewed as children of the next semantic container + upwards in the tree, and despite the containers themselves being abstracted + out of the tree. This defines the reading order. This example is a + large block of text with intentionally simple formatting, where the + only formatting is to represent paragraphs as separate TextBlock elements + to support an adaptive layout, but no Run blocks within.

    +

    When viewed with assistive technologies that represent the contents, + each TextBlock is a control type of Text. Screen readers + can use document reading modes such as virtual cursor modes to read + the content from each element and each element's content, following + the same reading order as is declared in the XAML. For example, in + JAWS 12, readers can read out this text container line by line using + (Jaws Key)+DownArrow. It is actually JAWS that determines the line + length, because the line length otherwise is defined only by the adaptive + layout at runtime, which is not reported to UIA.

    +
      <StackPanel x:Name="LayoutRoot" Background="White">
    +          <TextBlock>Call me Ishmael. Some years ago--never mind how long precisely--
    +having little or no money in my purse, and
    +nothing particular to interest me on shore, I thought I would sail about a little 
    +and see the watery part of the world. It is a way I have of driving off the spleen 
    +and regulating the circulation. Whenever I find 
    +myself growing grim about the mouth; whenever it is a damp, drizzly November in 
    +my soul; whenever I find myself involuntarily pausing before coffin warehouses, 
    +and bringing up the rear of every funeral I meet;
    +and especially whenever my hypos get such an upper hand of me, that it requires a strong moral 
    +principle to prevent me from
    +deliberately stepping into the street, and methodically knocking people's hats off--then, 
    +I account it high time to get to sea as
    +soon as I can. This is my substitute for pistol and ball. With a philosophical flourish Cato 
    +throws himself 
    +upon his sword; I quietly take to the ship. There is nothing surprising in this. If they but knew it, 
    +almost all men in their degree, some time or other, cherish very nearly the same feelings towards the 
    +ocean with me.
    +          </TextBlock>
    +          <TextBlock>There now is your insular city of the Manhattoes, belted round by wharves as Indian isles 
    +          by coral reefs--
    +commerce surrounds it with her surf. Right and left, the streets take you waterward. 
    +Its extreme downtown is the battery, where
    +that noble mole is washed by waves, and cooled by breezes, which a few hours previous 
    +were out of sight of land. Look at the crowds of water-gazers there.
    +          </TextBlock>
    +          <TextBlock>Circumambulate the city of a dreamy Sabbath afternoon. Go from Corlears Hook 
    +          to Coenties Slip, and from thence, by Whitehall, northward.
    +What do you see?--Posted like silent sentinels all around the town, stand thousands 
    +upon thousands of mortal men fixed in ocean
    +reveries. Some leaning against the spiles; some seated upon the pier-heads; 
    +some looking over the bulwarks of ships from China; 
    +some high aloft in the rigging, as if striving to get a still better seaward peep. 
    +But these are all landsmen; of week days pent
    +up in lath and plaster--tied to counters, nailed to benches, clinched to desks. 
    +How  then is this? Are the green fields gone? What do they here?
    +          </TextBlock>
    +  </StackPanel>
    +
    + +
    +
    +

    Text containers and their UIA representation

    + +

    The following example is intended as sample XAML to view in an accessibility + framework viewer, to see the various names, roles, and patterns for + obtaining value.

    +
       <StackPanel x:Name="LayoutRoot">
    +       <TextBox Text="This is a TextBox"/>
    +       <RichTextBox>
    +           <Paragraph>This is a RichTextBox.</Paragraph>
    +       </RichTextBox>
    +       <TextBlock Text="This is a TextBlock"/>
    +   </StackPanel>
    +
    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. To see + UI Automation, use Microsoft Windows as platform.
    2. +
    3. Use a verification tool that is capable of showing the full automation + tree. (For example, use UIAVerify or Silverlight Spy; see Resources + links.)
    4. +
    5. Verify that TextBox elements in the Silverlight + user interface have the Edit role, that RichTextBox elements + have the Document role, and TextBlock has Text role + in UI Automation.
    6. +
    7. Verify that the text content can be programmatically determined + by techniques that are appropriate for that role.
    8. +
    +
    +

    Expected Results

    +

    #3 and #4 are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL33.html b/techniques/silverlight/SL33.html new file mode 100644 index 0000000000..cfa2f2fa31 --- /dev/null +++ b/techniques/silverlight/SL33.html @@ -0,0 +1,218 @@ +Using Well-Formed XAML to Define a Silverlight User Interface

    Using Well-Formed XAML to Define a Silverlight User Interface

    ID: SL33

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use the characteristics of the + XAML language to support basic parsing requirements that both applications + and accessibility frameworks rely upon. This technique explains the + role of XAML in the overall Silverlight development and application + architecture, in particular for defining the elements that make up + a Silverlight user interface. This technique also present some basic + facts about XAML as a language; more information of this nature is + also included in .

    +

    XAML is a markup language for object instantiation. XAML can be incorporated + into a technology such as Silverlight. A specific XAML vocabulary can + be defined by a technology such as Silverlight, and the vocabulary + can be extended by anyone that provides suitable backing code. For + example, a Silverlight application author can define a custom class, + and the application author or potentially other Silverlight application + authors can use XAML to instantiate instances of the custom class.

    +

    XAML has a published + language specification.

    +

    XAML does not necessarily declare the entirety of the object tree + that a Silverlight client runtime loads, but XAML typically declares + the majority of the objects/elements that represent the Silverlight + application's user interface. The objects and values that are used + for accessibility scenarios are often closely related to the standard + user interface, and thus accessibility-related properties are typically + declared in XAML rather than in code, even though setting the values + in code is technically possible.

    +

    For more information on XAML in Silverlight, see Silverlight + XAML Overview on MSDN.

    +
    +

    XAML and XML

    +

    XAML is based on XML, and shares many of its language features. Some + of the language features that are directly relevant to the stated intent + of SC4.1.1 and to 4.1.1 related techniques include:

    +
      +
    • Well-formedness: The definition of well-formed XAML is the same + as the XML definition. XAML processors, including the Silverlight + runtime XAML parser, will block loading XAML that is not well formed.
    • +
    • Duplicate attributes: Unless specially configured for scenarios + such as design-time support, XAML processors will block loading XAML + where elements contain duplicate attributes.
    • +
    • Quote matching: mismatched quote matching for attribute values + in XAML constitutes XAML that is not well formed.
    • +
    +

    Some XAML language features that are analogous to XML but have some + technology-specific differences include:

    +
      +
    • Identifiers: XAML defines a Name directive, which + is analogous to xml:id in that Name serves + as the unique identifier of an element. However, XAML defines an + additional concept of a XAML namescope, which permits a XAML document + to contain multiple XAML namescopes as a factoring technique. Thus, + identical Name values are permitted in a XAML document + so long as each is defined in a separate XAML namescope. XAML namescopes + are associated with elements, such that the extent of each XAML namescope + is understood by XAML processors.
    • +
    • Schemas and vocabularies: A notable difference between XAML and + XML is that a XAML vocabulary is not typically represented in existing + XML schema definition formats such as XSD or DTD. XAML includes inheritance + and reference features that cannot adequately be expressed in XSD + or other existing XML schema representation formats. This affects + the "elements are nested according to their specifications" consideration + of SC4.1.1. XAML definitely has the ability to enforce nesting restrictions + as represented by a XAML vocabulary. However, XAML validity for a + vocabulary is deliberately fluid, in order to support extension by + user code. XAML validity is determined by a combination of a XAML + processor, a XAML concept known as a XAML schema context, and the + code that backs the XAML and defines any objects being instantiated + as a parsing result. Typically, design time tools such as Microsoft + Visual Studio can adequately duplicate the runtime validity characteristics + of a XAML vocabulary. Using these tools, application authors can + both verify XAML validity as well as receive design-time information + for how to correct any XAML validity errors.
    • +
    +
    +
    +

    XAML parsing and HTML parsing

    +

    In the Silverlight implementation, XAML is like HTML in that it is + loaded and parsed just-in-time. Silverlight XAML is not precompiled + to binary or MSIL (the language-neutral CLR runtime format). Instead,Silverlight + XAML is transmitted or stored as plain text, either loose or packaged + as resources in a library. Thus Silverlight XAML is human readable + as well as machine readable.

    +

    However, unlike HTML, Silverlight XAML is only intended to be loaded + and interpreted by the Silverlight runtime, rather than multiple possible + user agents that each implement an HTML engine. HTML is a language + where the behavior is also specified. In contrast, XAML is a language + for referencing constructs that are defined in runtime libraries, and + the functional specification of the XAML language itself is minimal + (intrinsics; language rules; primitive types). Layout, appearance, + type-member sets, roles, etc. are all left up to specific frameworks + and vocabularies that use XAML. Behavior associated with a given XAML + construct is based on type definitions made in a runtime library. For + Silverlight XAML, the types are from Silverlight core libraries, but + often the definitions come from libraries that are available to the + Silverlight runtime as part of an application's packaging for distribution.

    +

    XAML is generally speaking strict, and will raise parsing errors if + XAML contains elements that are not recognized. Such parsing errors + generally present the information in the XAML from resulting in any + objects being created, which in turn prevents a Silverlight application + from running. This is different from typical (non-xHTML) HTML, where + implementations are permitted to contain nonrecognized elements or + attributes and ignore them.

    +
    +

    Examples

    +
    +

    XAML in design tools for Silverlight

    + +

    A developer utilizes features in their Silverlight XAML authoring + tool to ensure that:

    +
      +
    • XAML is well formed
    • +
    • XAML is valid according to Silverlight parser and all reference + assemblies
    • +
    • XAML Names are unique in namescope
    • +
    • XAML has no duplicate attributes
    • +
    +
    +

    More about design tools and XAML

    +

    Silverlight XAML is able to be loaded by design tools for Silverlight. + In the design tool, the XAML is interpreted much like the runtime interprets + it, in order to show the visual representation of the Silverlight application. + In addition, the design tool might implement design surfaces in which + the user interface can be changed, and typically provides a way to + save any changes made in the tool back into the loaded XAML.

    +

    At design time, tools such as Microsoft Visual Studio or Microsoft + Expression might provide opportunities to correct any XAML errors before + the Silverlight application is compiled and packaged for deployment. + This might be implemented by performing static analysis of the XAML, + by forwarding the design tool's own parser errors as it renders the + design surface, or by forwarding linking errors that are identified + by a precompile step (for example, missing event handlers raise a XAML + error from precompile). This behavior is sometimes identified as a design + mode behavior in Microsoft documentation and other documentation + about Visual Studio or specific tools.

    +

    Regardless of how a given XAML file behaves while being interacted + with in a design mode, it is the Silverlight runtime XAML parser on + each client installation that is the ultimate determinant of whether + the XAML is valid or invalid.

    +
    + +
    +
    +

    Silverlight application consumer

    + +

    A consumer views a Silverlight application that is hosted in an HTML + page. If the Silverlight application has valid XAML, the Silverlight + content loads, and the fact that the XAML-based UI loaded at all is + assurance that:

    +
      +
    • XAML is well formed
    • +
    • XAML is valid
    • +
    • XAML validity is partially based on correct type mapping of all + elements referenced in XAML, according to Silverlight XAML parser + and all reference assemblies included by that application
    • +
    • XAML Names are unique in namescope
    • +
    • XAML has no duplicate attributes
    • +
    • XAML-defined properties that are relevant for assistive technology + (for example AutomationProperties.Name as described + by other Silverlight techniques) are available
    • +
    + +
    +

    Tests

    +
    +

    Pass case

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. That + application is known to consume Silverlight XAML.
    2. +
    3. Verify that the application runs correctly and displays user interface.
    4. +
    +
    +

    Expected Results

    +

    #2 is true.

    +
    +
    +

    Fail case

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. That + application is known to consume Silverlight XAML, and the XAML is + known to be deliberately invalid.
    2. +
    3. Verify that the application did not run.
    4. +
    +
    +

    Expected Results

    +
      +
    1. #2 is true.
    2. +
    +

    Note that it is common that an error message is displayed to users + in HTML, which is implemented by handling the JavaScript OnError event + emitted by the Silverlight plugin. XAML parse errors are forwarded + to JavaScript errors and can be handled in this way. However, it is + also possible that the application is production-ready, and deliberately + does not expose any JavaScript errors, whether Silverlight managed + code errors or not. If seeing the specific error is important, the + test might need to be run against a preproduction or debug version + of the application.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL34.html b/techniques/silverlight/SL34.html new file mode 100644 index 0000000000..ed4d521e1f --- /dev/null +++ b/techniques/silverlight/SL34.html @@ -0,0 +1,264 @@ +Using the Silverlight Default Tab Sequence and Altering Tab Sequences + With Properties

    Using the Silverlight Default Tab Sequence and Altering Tab Sequences + With Properties

    ID: SL34

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use the default Silverlight + tab sequence, or alternatively to apply the options that Silverlight + application authors can use for altering the tab sequence. Application + authors might alter the tab sequence in cases where the default tab + sequence is not desirable for some reason, and those reasons might + vary per application or application scenario. The tab sequence can + be altered in order to create a meaningful sequence in the tab order, + so that assistive technologies that rely on traversal of focusable + elements can use and determine the meaningful sequence.

    +

    Silverlight uses structured definitions for defining its user interface + presentations, where the declaration order is significant because it + becomes the structure of the run-time visual tree. The structured definitions + also define the layout and presentation structure in most cases. The + structured definition concept is described in more detail in .

    +

    The Silverlight development platform attempts to create an overall + system where the logical order of how elements are defined in XAML + and code, and then presented in a user interface, will also match a + logical tab sequence and logical reading order when presented to the + user. In many cases, a Silverlight application author can write an + application without necessarily worrying about the tab sequence, can + test the tab sequence during a verification and testing phase of development, + and will not need to set any specific properties to adjust the tab + sequence. As a broad generalization, a Silverlight tab sequence will + be constructed so that it traverses elements left to right, and top + to bottom, and will behave similarly to how HTML would behave if the + HTML analogs of Silverlight elements were constructed and presented + in the same way. However, there are specific Silverlight controls that + deliberately alter the tab sequence, or whose elements are made keyboard-accessible + through a keyboard navigation technique other than TAB. For more information, + see Focus + Overview on MSDN.

    +
    +

    How Silverlight implements tab sequence concepts

    +

    The Silverlight programming model defines a Control class + that is a base class of many of the practical controls that produce + a Silverlight application user interface. One of the behaviors of the Control class + is that only a Control can receive keyboard focus + as a discrete element within the Silverlight content area.

    +

    When a Silverlight application user interface is constructed from + the visual tree, a default tab sequence for all Silverlight content + is also constructed, using the same principles of order that were used + by the visible layout. This default tab sequence is usually adequate + as a tab sequence that supports users that press the TAB key to traverse + the UI. The same TAB sequence and/or the focusable state of controls + is also used by many assistive technologies or modes of assistive technologies + to construct the representation of the interface for the Silverlight + content.

    +

    For cases where developers decide that the default tab sequence is + not adequate, the developer can take one of two approaches for changing + the tab sequence:

    +
      +
    • Change other properties of the control where a change to the tab + sequence happens as a secondary effect.
    • +
    • Reorder the tab sequence directly.
    • +
    +
    +
    +

    Changing control properties

    +
      +
    • Setting the Visibility property of a control + to Collapsed causes the control to no longer render + in the UI. As a secondary effect, that control is removed from the + tab sequence.
    • +
    • Setting the IsEnabled property of a control to + false causes the control to no longer be focusable by keyboard or + clickable by the mouse. In many cases, the visual appearance of the + control changes also, through a theme style. For example, the control + may appear as gray rather than black. As a secondary effect, that + control is removed from the tab sequence.
    • +
    +
    +
    +

    Changing specific tab properties

    +
      +
    • Setting the IsTabStop property of a control to + false causes the control to no longer be focusable by keyboard or + programmatic focus, and that control is removed from the tab sequence.
    • +
    • Setting the TabIndex property of a control to + a specific index causes the control to be inserted at that position + in the tab sequence. The default value of TabIndex is + Single.MaxValue, therefore any non-default value promotes that control + to be first in an otherwise default tab sequence. More typically, + authors would specify a TabIndex for any controls + that are involved in a deliberate segment of tab order re-ordering.
    • +
    +
    +
    +

    Tab order and language

    +

    Left-to-right is the default only for languages that use left-to-right + reading order. For languages that use right-to-left reading order, + right-to-left is also the default tab order as implemented by Silverlight + runtime behavior. That language preference is declared by the acting CultureInfo. + For more information on CultureInfo, see .

    +
    +

    Examples

    +
    +

    Default tab order, based on ordering in the StackPanel

    + +

    In this example, a StackPanel has a natural layout + order of top-to-bottom, and that will also be the tab order of each StackPanel child + element (FirstName, then LastName).

    +
       <StackPanel x:Name="LayoutRoot" Background="White">
    +       <StackPanel Orientation="Horizontal">
    +           <TextBlock Name="lbl_FirstName">First name</TextBlock>
    +           <TextBox AutomationProperties.LabeledBy="{Binding ElementName=lbl_FirstName}" Name="tbFirstName" Width="100"/>
    +       </StackPanel>
    +       <StackPanel Orientation="Horizontal">
    +           <TextBlock Name="lbl_LastName">First name</TextBlock>
    +           <TextBox AutomationProperties.LabeledBy="{Binding ElementName=lbl_LastName}" Name="tbLastName" Width="100"/>
    +       </StackPanel>
    +   </StackPanel>
    +
    +

    This example is shown in operation in the working example of Tab Sequence.

    + +
    +
    +

    Tab order, modified by TabIndex

    + +

    A form is marked up using a data table that includes the fields of + the groom in the first column and the fields of the bride in the second + column. The order in the content is row by row but the author feels + it is more logical for users to navigate the form column by column. + This way, all the groom's criteria can be filled in before moving on + to the bride's criteria. The TabIndex attributes of + the Silverlight elements are used to specify a tab order that navigates + column by column. This example specifically illustrates how changing + tab order can change the meaningful sequence.

    +
     <UserControl x:Class="TabSequence.MainPage"
    + xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    + xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    + >
    +   <StackPanel x:Name="LayoutRoot" Background="White">
    +       <TextBlock>he first column contains the search criteria 
    + of the groom, the second column the search criteria of 
    + of the bride</TextBlock>
    +       <Grid>
    +       <Grid.RowDefinitions>
    +         <RowDefinition/>
    +         <RowDefinition/>
    +         <RowDefinition/>
    +         <RowDefinition/>
    +       </Grid.RowDefinitions>
    +       <Grid.ColumnDefinitions>
    +         <ColumnDefinition/>
    +         <ColumnDefinition/>
    +         <ColumnDefinition/>
    +       </Grid.ColumnDefinitions>
    +       <TextBlock>Search criteria</TextBlock>
    +       <TextBlock Grid.Column="1">Groom</TextBlock>
    +       <TextBlock Grid.Column="2">Bride</TextBlock>
    +       <TextBlock Grid.Row="1">First name</TextBlock>
    +       <TextBox Grid.Row="1" Grid.Column="1" TabIndex="1"/>
    +       <TextBox Grid.Row="1" Grid.Column="2" TabIndex="4"/>
    +       <TextBlock Grid.Row="2">Last name</TextBlock>
    +       <TextBox Grid.Row="2" Grid.Column="1" TabIndex="2"/>
    +       <TextBox Grid.Row="2" Grid.Column="2" TabIndex="5"/>
    +       <TextBlock Grid.Row="3" >Place of birth</TextBlock>
    +       <TextBox Grid.Row="3" Grid.Column="1" TabIndex="3"/>
    +       <TextBox Grid.Row="3" Grid.Column="2" TabIndex="6"/>
    +       </Grid>
    +   </StackPanel>
    + </UserControl>
    + 
    +

    This example is shown in operation in the working example of Tab Sequence TabIndex.

    + +
    +
    +

    Tab order, modified by changing runtime Control properties

    + +

    In this example, a radio button choice in a form controls whether + certain other fields in the form are relevant or not relevant. The + current radio button selection toggles the IsEnabled property + in such fields to enable or disable them based on how the user selected + the preceding logical element, which also affects whether the fields + appear in the further tab sequence. The following is UI definition + in XAML.

    +
    <UserControl x:Class="TabSequence.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    +   <StackPanel x:Name="LayoutRoot" Background="White">
    +       <TextBlock>Registration</TextBlock>
    +       <Grid>
    +       <Grid.RowDefinitions>
    +         <RowDefinition/>
    +         <RowDefinition/>
    +         <RowDefinition/>
    +         <RowDefinition/>
    +       </Grid.RowDefinitions>
    +       <Grid.ColumnDefinitions>
    +         <ColumnDefinition/>
    +         <ColumnDefinition/>
    +         <ColumnDefinition/>
    +       </Grid.ColumnDefinitions>
    +           <StackPanel Orientation="Horizontal">
    +               <RadioButton GroupName="Registration" Checked="RadioButton_CheckedG">Guest</RadioButton>
    +               <RadioButton GroupName="Registration" Checked="RadioButton_CheckedC">Custom</RadioButton>
    +           </StackPanel>
    +               <TextBlock Grid.Row="1">First name</TextBlock>
    +           <TextBox x:Name="tb_fn" IsEnabled="false" Grid.Row="1" Grid.Column="1" />
    +           <TextBlock Grid.Row="2">Last name</TextBlock>
    +           <TextBox  x:Name="tb_ln" IsEnabled="false" Grid.Row="2" Grid.Column="1" />
    +       </Grid>
    +   </StackPanel>
    +</UserControl>
    +
    +

    The following is event handler code.

    +
           private void RadioButton_CheckedC(object sender, RoutedEventArgs e)
    +       {
    +           tb_fn.IsEnabled = true;
    +           tb_ln.IsEnabled = true;
    +       }
    +       private void RadioButton_CheckedG(object sender, RoutedEventArgs e)
    +       {
    +           tb_fn.IsEnabled = false;
    +           tb_ln.IsEnabled = false;
    +       }
    +       
    +

    This example is shown in operation in the working example of Tab Sequence Enabled.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Engage the screen reader. Press the TAB key to traverse the sequence + of elements inside the Silverlight content area.
    4. +
    5. Verify that the order in which elements are traversed in a tab + sequence is also the expected order of the elements as they are presented + visually, particularly in such cases where the order of each element + is significant per SC + 1.3.2.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL35.html b/techniques/silverlight/SL35.html new file mode 100644 index 0000000000..c2dfdf3258 --- /dev/null +++ b/techniques/silverlight/SL35.html @@ -0,0 +1,304 @@ +Using the Validation and ValidationSummary APIs to Implement Client + Side Forms Validation in Silverlight

    Using the Validation and ValidationSummary APIs to Implement Client + Side Forms Validation in Silverlight

    ID: SL35

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to use the Silverlight Validation API. + The Validation API associates the validation logic with form input + elements that properly support accessible text both for the initial + entry and for any error identification and suggestion that is displayed + in the user interface.

    +

    Application authors can either associate Validation.Errors output + with specific UI elements, include an initially hidden ValidationSummary user + interface element, or both. The example shown in this technique uses + both ValidationSummary and Validation.Errors. + The ValidationSummary is the most appropriate technique + for providing text feedback after a form submission attempt, because + assistive technologies pick it up as a discrete focusable element in + the interface representation. The Validation.Errors technique + is perhaps a better cognitive user experience for sighted users, because + it presents the specific error suggestions in closer proximity to the + input items that are in error.

    +

    This technique relies on several Silverlight features: AutomationProperties, + the Name property for identifying specific UI elements, + the Validation and ValidationSummary API, + the ElementName variation of Silverlight data binding, and the general + behavior of TextBox elements.

    +
    +

    Contrast for validation states of the Label control

    +

    Silverlight version 4's default visual styles have a bug where the + colors used to indicate an invalid field entry by changing the color + of the foreground text do not satisfy the 4.5:1 contrast ratio per + SC 1.4.1. To correct for this visual bug, application authors should + copy the control template for the Label control, and + adjust the color used for the validation state. This is shown in Example + 1; the resource "LabelStyle1" was generated by copying + the default Label style using Microsoft Expression + Blend. Then, the value was changed in the copied template, and the + changed template was referenced and included in the application. The + specific changed line is indicated by a comment in the Example 1 sample + markup.

    +
    +

    Examples

    +
    +

    Two form fields with validation on Submit, and an error + identification/suggestion system and UI on the client side

    + +

    In this example, the form fields correspond to a data object that + implements a view model. Silverlight uses the view model and data annotations + to generate some of its UI, notably the names of the fields are bound + to the original view model names from the data. The ValidationSummary + API is defined in a "Client SDK" library System.Windows.Controls.Data.Input.dll, + which is included as part of the project and the distributable.

    +

    This example has a UI defined in XAML and logic defined in C#. The + following is the XAML UI.

    +
    <UserControl x:Class="AccessibleValidation.MainPage"
    + xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    + xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    + xmlns:sdk="http://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk">
    +<UserControl.Resources>
    + <Style x:Key="LabelStyle1" TargetType="sdk:Label">
    + <Setter Property="IsTabStop" Value="False"/>
    + <Setter Property="HorizontalContentAlignment" Value="Left"/>
    + <Setter Property="Template">
    +  <Setter.Value>
    +   <ControlTemplate TargetType="sdk:Label">
    +    <Grid>
    +     <VisualStateManager.VisualStateGroups>
    +      <VisualStateGroup x:Name="CommonStates">
    +       <VisualState x:Name="Normal"/>
    +       <VisualState x:Name="Disabled"/>
    +      </VisualStateGroup>
    +      <VisualStateGroup x:Name="ValidationStates">
    +       <VisualState x:Name="Valid"/>
    +       <VisualState x:Name="Invalid">
    +        <Storyboard>
    +         <ColorAnimation Duration="0" To="#FFF00000"
    +         Storyboard.TargetProperty="(Control.Foreground).(SolidColorBrush.Color)"
    +         Storyboard.TargetName="ContentControl" d:IsOptimized="True"/>
    +         //above is the line where color was adjusted from default Red to FFF00000, 
    +         //to satisfy the 4.5:1 contrast requirement
    +        </Storyboard>
    +       </VisualState>
    +      </VisualStateGroup>
    +      <VisualStateGroup x:Name="RequiredStates">
    +       <VisualState x:Name="NotRequired"/>
    +       <VisualState x:Name="Required">
    +         <Storyboard>
    +          <ObjectAnimationUsingKeyFrames Duration="0" 
    +          Storyboard.TargetProperty="FontWeight" 
    +          Storyboard.TargetName="ContentControl">
    +           <DiscreteObjectKeyFrame KeyTime="0" Value="SemiBold"/>
    +          </ObjectAnimationUsingKeyFrames>
    +         </Storyboard>
    +        </VisualState>
    +       </VisualStateGroup>
    +      </VisualStateManager.VisualStateGroups>
    +      <Border BorderBrush="{TemplateBinding BorderBrush}" 
    +      BorderThickness="{TemplateBinding BorderThickness}" Background="{TemplateBinding Background}" 
    +      CornerRadius="2" Padding="{TemplateBinding Padding}">
    +       <ContentControl x:Name="ContentControl" Cursor="{TemplateBinding Cursor}" 
    +         ContentTemplate="{TemplateBinding ContentTemplate}" Content="{TemplateBinding Content}" 
    +         Foreground="{TemplateBinding Foreground}" FontWeight="{TemplateBinding FontWeight}"
    +         FontStretch="{TemplateBinding FontStretch}" FontSize="{TemplateBinding FontSize}" 
    +         FontFamily="{TemplateBinding FontFamily}" HorizontalAlignment="{TemplateBinding HorizontalAlignment}" 
    +         HorizontalContentAlignment="{TemplateBinding HorizontalContentAlignment}"
    +         IsTabStop="False" VerticalAlignment="{TemplateBinding VerticalAlignment}" 
    +         VerticalContentAlignment="{TemplateBinding VerticalContentAlignment}"/>
    +      </Border>
    +     </Grid>
    +    </ControlTemplate>
    +   </Setter.Value>
    +  </Setter>
    + </Style>
    +</UserControl.Resources>
    + <Grid x:Name="LayoutRoot" Background="White" Margin="10">
    +   <Grid.RowDefinitions>
    +     <RowDefinition Height="Auto"/>
    +     <RowDefinition Height="Auto"/>
    +     <RowDefinition Height="Auto"/>
    +     <RowDefinition Height="Auto"/>
    +     <RowDefinition Height="Auto"/>
    +   </Grid.RowDefinitions>
    +   <Grid.ColumnDefinitions>
    +     <ColumnDefinition Width="Auto"/>
    +     <ColumnDefinition Width="200"/>
    +     <ColumnDefinition Width="Auto"/>
    +   </Grid.ColumnDefinitions>
    +   <TextBlock Text="Validating Form" FontSize="16" FontWeight="Bold"
    +     Grid.Column="1" HorizontalAlignment="Center" />
    +   <sdk:ValidationSummary x:Name="ErrorSummary" IsTabStop="True"
    +     Grid.Row="1" Grid.ColumnSpan="2" Margin="3" />
    +   <sdk:Label x:Name="NameLabel" Target="{Binding ElementName=NameTextBox}"
    +     Grid.Row="2" Margin="3" HorizontalAlignment="Right" Style="{StaticResource LabelStyle1}"/>    
    +   <TextBox x:Name="NameTextBox" 
    +     AutomationProperties.Name="{Binding Content, ElementName=NameLabel}"
    +     Text="{Binding Name, Mode=TwoWay, UpdateSourceTrigger=Explicit, 
    +     NotifyOnValidationError=True, ValidatesOnExceptions=True}"
    +     Grid.Column="1" Grid.Row="2" Margin="3" />
    +   <sdk:DescriptionViewer Target="{Binding ElementName=NameTextBox}" 
    +     Grid.Column="2" Grid.Row="2" />
    +   <sdk:Label x:Name="AgeLabel" Target="{Binding ElementName=AgeTextBox}"
    +     Grid.Row="3" Margin="3" HorizontalAlignment="Right" Style="{StaticResource LabelStyle1}"/>
    +   <TextBox x:Name="AgeTextBox" 
    +     AutomationProperties.Name="{Binding Content, ElementName=AgeLabel}" 
    +     Text="{Binding Age, Mode=TwoWay, UpdateSourceTrigger=Explicit, 
    +     NotifyOnValidationError=True, ValidatesOnExceptions=True}"  
    +     Grid.Column="1" Grid.Row="3" Margin="3" />
    +   <sdk:DescriptionViewer Target="{Binding ElementName=AgeTextBox}" 
    +     Grid.Column="2" Grid.Row="3" />
    +   <Button x:Name="SubmitButton" Content="Submit" Click="SubmitButton_Click"
    +     Grid.Column="1" Grid.Row="4" Width="50" Margin="3" />
    + </Grid>
    +</UserControl>
    +
    +

    The following is the C# logic for the page. Note the call to Focus + in the logic; many assistive technologies use focus to determine + what area of the interface to report to the user. If code calls Focus + to reference the error summary once it is completed, the assistive + technology can report the error summary immediately.

    +
           public MainPage()
    +       {
    +           InitializeComponent();
    +           LayoutRoot.DataContext = new Product();
    +       }
    +       // Commits text box values when the user presses ENTER.
    +       private void TextBox_KeyDown(object sender, 
    +           System.Windows.Input.KeyEventArgs e)
    +       {
    +           if (e.Key == System.Windows.Input.Key.Enter) (sender as TextBox)
    +               .GetBindingExpression(TextBox.TextProperty).UpdateSource();
    +       }
    +       private void SubmitButton_Click(object sender, System.Windows.RoutedEventArgs e)
    +       {
    +           NameTextBox.GetBindingExpression(TextBox.TextProperty).UpdateSource();
    +           AgeTextBox.GetBindingExpression(TextBox.TextProperty).UpdateSource();
    +           if (ErrorSummary.Errors.Count > 0) ErrorSummary.Focus();
    +           }
    +

    The following is the data class. Note how much of the validation + logic is defined within this view model, rather than as part of Silverlight + UI logic.

    +
      public class Product 
    +   {
    +       private string nameValue;
    +       private const string nameMessage = "Must be 10 characters or less.";
    +       [Display(Name = "Username", Description = "Required. " + nameMessage)]
    +       [StringLength(10, ErrorMessage = nameMessage)]
    +       [Required(ErrorMessage = "Required.")]
    +       public string Name
    +       {
    +           get { return nameValue; }
    +           set
    +           {
    +               if (nameValue != value)
    +               {
    +                   Validator.ValidateProperty(value, new ValidationContext(
    +                       this, null, null) { MemberName = "Name" });
    +                   nameValue = value;
    +               }
    +           }
    +       }
    +       private string ageValue;
    +       private const string ageMessage = "Must be in the 5 to 120 range.";
    +       [Display(Description = ageMessage)]
    +       [Range(5, 120, ErrorMessage = ageMessage)]
    +       [RegularExpression("\\d*", ErrorMessage = "Must be a number.")]
    +       public string Age
    +       {
    +           get { return ageValue; }
    +           set
    +           {
    +               if (ageValue != value)
    +               {
    +                   Validator.ValidateProperty(value, new ValidationContext(
    +                       this, null, null) { MemberName = "Age" });
    +                   ageValue = value;
    +               }
    +           }
    +       }
    +       
    +

    The following image is a screen shot of this simple UI, after two + invalid values are entered in the form and Submit is activated:

    +
    + + +
    Form with invalid values
    + +
    +

    The following image is a screen shot of the UIAVerify tree view of + this same application. Note the "Text" role items that appear + as adjacent peer elements, which describe the validation errors. This + Text is actually coming from sdk:DescriptionViewer, and in the visible + UI in the screenshot is not currently visible. This text would be visible + if any of the following occurs:

    +
      +
    • the user hovers the mouse over the red triangle in the input field + corner
    • +
    • the user hovers over the "info i" icon
    • +
    • the user clicks (or tabs to) the relevant field, which focuses + it
    • +
    +
    + + +
    UIAVerify tree view of form with invalid values
    + +
    +

    This example is shown in operation in the working example of Accessible Validation.

    +
    +

    Validation style for Label controls

    +

    The default validation style for the Invalid state of Label does + not have adequate contrast by default. Application authors can restyle Label with + a new template that has a 4.5:1 contrast.

    +
    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. The application + is expected to contain form fields, and a Submit pattern for form + interaction as described in .
    2. +
    3. Navigate through the items of a form until an editable field is + read. Enter a value that triggers the validation.
    4. +
    5. Navigate to Submit button and activate it to attempt to submit + the form.
    6. +
    7. Verify that a Validation Summary now appears, and is focusable.
    8. +
    9. Verify that the Validation Summary provides enough information + to correct any error.
    10. +
    11. Navigate back to input elements that have validation issues. Correct + the errors as suggested.
    12. +
    13. Tab to Submit button. Press ENTER to resubmit.
    14. +
    15. Verify that Validation Summary is no longer displayed and that + the screen reader does not focus to/read any further validation information.
    16. +
    +
    +

    Expected Results

    +

    #4, #5, and #8 are true.

    +
    +

    Resources

    + + + +
    diff --git a/techniques/silverlight/SL4.html b/techniques/silverlight/SL4.html new file mode 100644 index 0000000000..a9cbfee90f --- /dev/null +++ b/techniques/silverlight/SL4.html @@ -0,0 +1,186 @@ +Declaring Discrete Silverlight Objects to Specify Language Parts + in the HTML DOM

    Declaring Discrete Silverlight Objects to Specify Language Parts + in the HTML DOM

    ID: SL4

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is use the HTML Lang attribute on + the object tag to describe each Silverlight plug-in instance on the + HTML hosting page as a "part" that has a different language. + Assistive technologies that use HTML Lang as a determinant of language + of parts can thus treat all Silverlight content as using that HTML + Lang-declared language.

    +

    Most assistive technologies that are capable of determining Language + for Web content will use the HTML Lang tag value as the determinant + of the language of the page. Assistive technologies would also use + HTML Lang tag values for the language of parts. HTML Lang is not specifically + reported in accessibility frameworks. Assistive technologies would + typically access the HTML DOM to get this information. This technique + specifically addresses this known situation regarding how ATs obtain + Language information from HTML rather than from accessibility frameworks + that otherwise report other aspects of HTML content.

    +

    In order to support different language parts that each contain Silverlight + content, authors declare one Silverlight object tag per continuous + language part region in the HTML. For example, the following HTML is + a simplication of HTML markup for a page that contains two Silverlight + content areas, the first declaring Lang as English (en), the second + declaring Lang as German (de):

    +
         <body>
    +       <object type="application/x-silverlight-2" lang="en">
    +       </object>
    +       <object type="application/x-silverlight-2" lang="de">
    +       </object>
    +     </body>
    +     
    +

    To support communication between different Silverlight plug-in instances + that are hosted on the same HTML page, application authors can use + various techniques, including the following

    +
      +
    • System.Windows.Messaging APIs: this is the simplest technique, + and this is shown in Example 1
    • +
    • Using a shared business object, and exchanging information by + having each Silverlight instance reference two-way data binding to + that business object's properties.
    • +
    • Exchanging information through the HTML DOM and declaring properties + of one or both instances as Scriptable by the DOM.
    • +
    +
    +

    Silverlight runtime language determination

    +

    Regardless of how HTML Lang is declared on the defining object tags, + many aspects of how Silverlight works with language and culture information + at run time are not determined by HTML Lang, and are instead determined + by the operating system and which culture that operating system is + running. For more information, see Understanding + Language/Culture Properties as Used by Silverlight Applications and + Assistive Technologies.

    +
    +

    Examples

    +
    +

    Two Silverlight object tags, each with different HTML + Lang, to support a simple language-translator application as a Web + page

    + +

    The Visual Studio solution for this example has a total of 4 project + components:

    +
      +
    • The Web project that declares the HTML or ASP page that shows + the framework of how the two Silverlight object tags exist on a page. + This is where the HTML Lang is actually set.
    • +
    • A project for the English user control, a simple TextBox.
    • +
    • A project for a German user control, also a simple TextBox.
    • +
    • A library with a static translation function
    • +
    +

    In this example, the English user control implements a LocalMessageSender, + which sends asynchronous messages to the German user control. The German + user control has a LocalMessageReceiver, which is set to listen as + soon as the control is instantiated. When a message is received, the + German control calls a function of the translation library, and displays + translated text.

    +

    The following is the HTML page (some infrastructure and parameters + omitted for clarity):

    +
    <html xmlns="http://www.w3.org/1999/xhtml" >
    +<body>
    +
    +    <object data="data:application/x-silverlight-2," type="application/x-silverlight-2" width="100%" height="25px" lang="en">
    +      <param name="source" value="ClientBin/SilverFish.xap"/>
    +    </object>
    +
    +    <object data="data:application/x-silverlight-2," type="application/x-silverlight-2" width="100%" height="25px" lang="de">
    +      <param name="source" value="ClientBin/SilverFish_DE.xap"/>
    +    </object>
    +
    +</body>
    +</html>
    +
    +

    The following is the XAML for the English user control:

    +
    <UserControl x:Class="SilverFish.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" Height="20" 
    +>
    +   <Grid x:Name="LayoutRoot" Background="White">
    +       <TextBox AcceptsReturn="False" Language="en-us"
    +       Name="EnglishTranslationBox" 
    +       LostFocus="EnglishTranslationBox_LostFocus"/>
    +   </Grid>
    +</UserControl>
    +
    +

    The following is the code-behind for the English user control:

    +
       public partial class MainPage : UserControl
    +   {
    +       private LocalMessageSender messagesender;
    +       public MainPage()
    +       {
    +           InitializeComponent();
    +       }
    +       private void EnglishTranslationBox_LostFocus(object sender, RoutedEventArgs e)
    +       {
    +           messagesender = new LocalMessageSender("receiver");
    +           messagesender.SendAsync((sender as TextBox).Text);
    +       }
    +   }
    +   
    +

    The following is the code-behind for the German user control (the + XAML is minimal; the main relevant point is that it contains a TextBox target + named GermanTranslationBox). The code invokes the translation function + found in a separate library. The translation function is not shown, + it simply takes an English string and returns a German translation.

    +
       public partial class MainPage : UserControl
    +   {
    +       public MainPage()
    +       {
    +           InitializeComponent();
    +           LocalMessageReceiver lmr = new LocalMessageReceiver("receiver");
    +           lmr.MessageReceived += new EventHandler<MessageReceivedEventArgs>(lmr_MessageReceived);
    +           try
    +           {
    +               lmr.Listen();
    +           }
    +           catch (ListenFailedException) {}
    +       }
    +       void lmr_MessageReceived(object sender, MessageReceivedEventArgs e)
    +       {
    +           if (e.Message!="") {
    +               String translated;
    +               translated = Translator.TranslateThat(e.Message);
    +               GermanTranslationBox.Text = translated;
    +               GermanTranslationBox.Focus();
    +           }
    +       }
    +   }
    +
    +

    This example is shown in operation in the working example of SilverFish.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references multiple Silverlight object tags, each with different + HTML Lang values.
    2. +
    3. Verify that language settings through HTML Lang on object tags + are respected by assistive technologies that can use HTML Lang values + for language of parts determination.
    4. +
    +
    +

    Expected Results

    +

    #2 gives expected results.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL5.html b/techniques/silverlight/SL5.html new file mode 100644 index 0000000000..a40d5966eb --- /dev/null +++ b/techniques/silverlight/SL5.html @@ -0,0 +1,237 @@ +Defining a Focusable Image Class for Silverlight

    Defining a Focusable Image Class for Silverlight

    ID: SL5

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to wrap the Silverlight Image class + inside a UI container class that is focusable. If the image is focusable, + users who use the TAB sequence to navigate content while the assistive + technology is active, and/or assistive technologies that construct + navigation structures that are based on the TAB sequence, can both + detect the image in navigation. The assistive technology can then associate + alternative text for that image within the navigation structure, and + report the information to the user.

    +

    Many existing assistive technologies do not construct initial navigation + views that are derived from UI Automation information if it is coming + from a non-focusable element in a Silverlight user interface. This + is particularly true if the assistive technology is in a navigation + mode that is specifically intended to help users enter information + into a form or similar interactive interface element; an example of + this situation is the Forms Mode of the JAWS screen reader.

    +

    + Image is + an example of a Silverlight element that is not focusable. This technique + and the example therein are intended to circumvent the possible omission + of a nonfocusable Silverlight Image element from certain + navigation views in existing assistive technology implementations. + The Silverlight Image is wrapped with a display/viewer + control class that is focusable. This image-wrapping control is initially + presented in assistive technology representations of a Silverlight + user interface that use only focusable elements when constructing the + assistive technology's representation of the application.

    +

    The image wrapper class uses the AutomationProperties.Name property + to provide a short text alternative for the contained Image, + so that the alternative text can be read or otherwise presented by + assistive technologies. The Silverlight API AutomationProperties.Name directly + sets Name in the UI Automation tree. The properties + in the UI Automation tree are reported to assistive technologies, when + the assistive technology implements behavior that acts as a UI Automation + client. Name is one of the accessibility framework + properties that most assistive technologies present in some way, for + purposes of both name and value information, and setting Name is + the common technique for exposing text alternatives for any other Control class + (for example, for a button with an image, as shown in the technique ).

    +

    This technique is intended for cases where application authors deliberately + do not want a visible image caption for the image to be part of the + user interface, and the image is a part of a larger interactive user + interface control or page. Otherwise, if there is a visible caption, + authors can use .

    +

    Examples

    +

    The two examples are intended to be used together, if an application + is both defining and consuming the focusable image control.

    +
    +

    Defining the FocusableImage XAML template and C# code + behavior

    + +

    Silverlight supports a control development model whereby the visual + appearance of a control is largely defined in XAML, and the behavior + of a control (such as its event handling and hookups to services) are + implemented in a managed code language such as C#. The following is + the XAML template, which includes a visual state that shows visually + when the control is focused in UI.

    +
    <ResourceDictionary
    +xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +xmlns:local="clr-namespace:ImageEquivalent">
    + <Style TargetType="local:FocusableImage">
    +   <Setter Property="Template">
    +    <Setter.Value>
    +      <ControlTemplate TargetType="local:FocusableImage">
    +        <Grid>
    +          <VisualStateManager.VisualStateGroups>
    +            <VisualStateGroup x:Name="FocusStates">
    +              <VisualState x:Name="Focused">
    +                <Storyboard>
    +                  <ColorAnimation  
    + Storyboard.TargetName="focusborder"
    + Storyboard.TargetProperty="(Border.BorderBrush).(SolidColorBrush.Color)"
    + Duration="0" To="Blue"/>
    +                </Storyboard>
    +              </VisualState>
    +              <VisualState x:Name="Unfocused"/>
    +            </VisualStateGroup>
    +          </VisualStateManager.VisualStateGroups>
    +          <Border
    +            x:Name="focusborder"
    +            BorderThickness="4"
    +            BorderBrush="Transparent">
    +            <Image
    +             Margin="2" Opacity="10"
    +             Source="{TemplateBinding Source}"/>
    +         </Border>
    +       </Grid>
    +    </ControlTemplate>
    +    </Setter.Value>
    +   </Setter>
    + </Style>
    +</ResourceDictionary>
    +
    +

    The following is the C# class definition and logic. The logic includes + invoking a default automation peer on creation, and loading the template + as defined in the previous XAML example through the Silverlight "generic.xaml" resource + convention for custom controls.

    +
    namespace ImageEquivalent
    +{
    +   public class FocusableImage : Control
    +   {
    +       protected override System.Windows.Automation.Peers.AutomationPeer OnCreateAutomationPeer()
    +       {
    +           return new FrameworkElementAutomationPeer(this);
    +       }
    +       public FocusableImage()
    +       {
    +           this.DefaultStyleKey = typeof(FocusableImage);
    +       }
    +       public ImageSource Source
    +       {
    +           get { return (ImageSource)this.GetValue(SourceProperty); }
    +           set { this.SetValue(SourceProperty,value); }
    +       }
    +       public static DependencyProperty SourceProperty = DependencyProperty.Register(
    +         "Source",
    +         typeof(ImageSource),
    +         typeof(FocusableImage),
    +         null);
    +       Boolean _Focused;
    +       void ChangeState()
    +       {
    +           if (_Focused)
    +           {
    +               VisualStateManager.GoToState(this,"Focused",false);
    +           }
    +           else
    +           {
    +               VisualStateManager.GoToState(this,"Unfocused",false);
    +           }
    +       }
    +       protected override void OnGotFocus(RoutedEventArgs e)
    +       {
    +           base.OnGotFocus(e);
    +           this._Focused = true;
    +           ChangeState();
    +       }
    +       protected override void OnLostFocus(RoutedEventArgs e)
    +       {
    +           base.OnGotFocus(e);
    +           this._Focused = false;
    +           ChangeState();
    +       }
    +   }
    +}
    +
    +

    This example is shown in operation in the working example of Focusable Image.

    + +
    +
    +

    Using the FocusableImage class in UI and applying AutomationProperties.Name

    + +

    Now that the image is wrapped by a focusable control, you can instantiate + an instance of the wrapper UI inside a Silverlight layout container, + specify AutomationProperties.Name at the level of + the wrapper control’s tag, and have that text serve as the alternative + text for the referenced source image file.

    +
       <StackPanel
    +   xmlns:local="clr-namespace:ImageEquivalent;assembly=FocusableImage"
    +   >
    +   <local:FocusableImage
    +     Height="300" Width="400
    +     AutomationProperties.Name="Diagram of secret lair"
    +     Source="/diagram_lair.png" />
    +   </StackPanel>
    +
    + +
    +

    Tests

    +
    +

    Automation Tree

    +

    Procedure

    +
      +
    1. Open the test HTML page in a Silverlight-supported useragent host; + to use UI Automation, use Microsoft Windows as platform.
    2. +
    3. Use the tab sequence inside the Silverlight content area to focus + the control.
    4. +
    5. Using an accessibility framework verification tool, check that + the string content is promoted as the default Name applied + to the control.
    6. +
    +
    +

    Accessibility framework verification tools typically show the + entirety of an automation tree for a given application, and in fact + will show the tree for all applications running on the Windows client + machine. Focusing the control as in #2 is thus not strictly speaking + necessary. However, manually focusing using the application interface + is often a faster way to step into the automation tree as opposed to + having to open an extensive series of nested nodes starting from the + browser host application root. Whether this functionality exists depends + on which accessibility framework verification tool is being used for + testing.

    +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +
    +

    Screen Reader

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. To use + UI Automation, use Microsoft Windows as platform.
    2. +
    3. Engage the screen reader. Move focus to the control (for example, + use the tab sequence).
    4. +
    5. Check that the Name applied to the image is read + by the screen reader.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL6.html b/techniques/silverlight/SL6.html new file mode 100644 index 0000000000..1b086413b7 --- /dev/null +++ b/techniques/silverlight/SL6.html @@ -0,0 +1,187 @@ +Defining a UI Automation Peer for a Custom Silverlight Control

    Defining a UI Automation Peer for a Custom Silverlight Control

    ID: SL6

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to create an AutomationPeer class + for a custom Silverlight control. The AutomationPeer exposes + accessibility properties of the control in a way that abstracts the + Silverlight technology specifics of the control model and maps information + to UI Automation concepts, so that these properties can be consumed + by the UI Automation accessibility framework.

    +

    The AutomationPeer concept is part of the overall architecture design + of the UI Automation system. The peer represents a deliberate abstraction + of the control, such that a client can obtain pattern-based information + about the specific purpose and capability of a control without knowing + its implementation-specific object model or having to resort to using + a framework-specific object model API. Also, the peers run in a different + process than the controls they represent, which has performance and + security advantages. For more information on UI Automation architecture, + see UI + Automation Overview on MSDN.

    +

    Creating a custom Silverlight control is one way that Silverlight + application authors can create user interface components either for + their own application, or as a packaged redistributable that provides + the control UI for third parties. Creating an automation peer for a + custom control reports control-specific information to the UI Automation + accessibility framework, and enables a custom control to participate + in all of the same techniques involving UI Automation that can be used + for a control that is distributed in the core Silverlight run time. + Assistive technologies can use the UI Automation accessibility framework + to discover the name and role of the user interface component, and + can get and set values by accessing UI Automation patterns. UI Automation + thus supports extensibility, while maintaining a discovery system for + names, roles and values of UI components.

    +

    Control authors associate a peer with a class by implementing a method + override for the class implementation. Control authors declare name + and role through properties that are general to any UI Automation peer. + Control authors expose the means to get and set values by choosing + to support one or more patterns that are usually associated with a + role. For example, a control in the role of "Button" would + typically support an "Invoke" pattern. A consumer of UI Automation + could check whether the pattern was supported and then call the pattern-based + method Invoke, which would activate the button without + any device input events being produced or required.

    +

    By convention, controls and their automation peers share a naming + pattern. For example, if a control is named Spinner, its automation + peer is named SpinnerPeer. However, the actual wiring for the class-peer + association is made in the control code by overriding OnCreateAutomationPeer. + Thus it is necessary to have access to the control code in order to + associate a new peer class implementation with that control.

    +

    In addition to properties, automation peers can also expose methods + as part of the implemented UI Automation control pattern. For example, + a peer implementing the Value pattern can provide an implementation + of the SetValue method. The SetValue method + can be called by a UI Automation client in order to programmatically + set the value of the owner control. The functionality exposed by the + implementation of a control pattern can be accessed either by automation-based + testing, or by assistive technologies.

    +

    Examples

    +
    +

    SimpleNumericUpDown control and its peer

    + +

    The example implements a very simple Silverlight custom control named + SimpleNumericUpDown. The control is a templateable control, meaning + that the UI is defined in a XAML file that serves as the default UI, + but any consumer of the control can change the visual appearance by + applying a new template. Nevertheless, the basic accessibility characteristics + of the control can be shaped by the control author, and can apply even + for cases where the visible UI is noticably different. This separation + between design-implementation and code-behavior is one reason for the + peer-owner design in UI Automation. The majority of the example shows + the C# code, including the following :

    +
      +
    • Associating the peer with the class.
    • +
    • Defining the peer, and basic information such as the class name.
    • +
    • Reporting which patterns the peer supports. In this case the peer + supports a Value pattern.
    • +
    +

    Control definition class:

    +
       public class SimpleNumericUpDown : Control
    +   {
    +       public SimpleNumericUpDown()
    +       {
    +           this.DefaultStyleKey = typeof(SimpleNumericUpDown);
    +       protected override System.Windows.Automation.Peers.AutomationPeer OnCreateAutomationPeer()
    +       {
    +           return new SimpleNumericUpDownAutomationPeer(this);
    +       }
    + // templating and event handlers omitted
    +       public static DependencyProperty NumericValueProperty = DependencyProperty.Register(
    +           "NumericValue",
    +           typeof(Int32),
    +           typeof(SimpleNumericUpDown),
    +           new PropertyMetadata(0)
    +           );
    +       public Int32 NumericValue
    +       {
    +           get { return (Int32)this.GetValue(NumericValueProperty); }
    +           set {this.SetValue(NumericValueProperty,value);}
    +       }
    +   }
    +   
    +

    Automation peer definition:

    +
       public class SimpleNumericUpDownAutomationPeer : FrameworkElementAutomationPeer, IValueProvider
    +   {
    +       private SimpleNumericUpDown OwnerControl { get { return (SimpleNumericUpDown)Owner; } }
    +       public SimpleNumericUpDownAutomationPeer(SimpleNumericUpDown owner)
    +           : base(owner) {}
    +       //peer overrides
    +       protected override string GetClassNameCore()
    +       {
    +           return "SimpleNumericUpDown";
    +       }
    +       protected override AutomationControlType GetAutomationControlTypeCore()
    +       {
    +           return AutomationControlType.Spinner;
    +       }
    +       public override object GetPattern(PatternInterface patternInterface) {
    +           if (patternInterface == PatternInterface.Value)
    +           {
    +               return this;
    +           }
    +           return base.GetPattern(patternInterface);
    +       }
    +       // Value pattern implementation
    +       String IValueProvider.Value
    +       {
    +           get { return OwnerControl.NumericValue.ToString(); }
    +       }
    +       bool IValueProvider.IsReadOnly {get{return false;}}
    +       void IValueProvider.SetValue(string value)
    +       {
    +           OwnerControl.NumericValue = Convert.ToInt32(value);
    +       }
    +
    +

    This example is shown in operation in the working example of Simple Numeric UpDown control.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. To see + UI Automation, use Microsoft Windows as platform.
    2. +
    3. Use a verification tool that is capable of showing the full automation + tree, and an object’s UI Automation properties and patterns as part + of the tree. (For example, use UIAVerify or Silverlight Spy; see + Resources links.) Select the item in the automation tree that is + accessing the relevant custom automation peer implementation.
    4. +
    5. Examine the set of properties exposed in the tree. Check that + name is reported by Name, that the class name is reported as ClassName, + and that there is a role as reported by the value of ControlType.
    6. +
    7. If the control is expected to report a value, check that the value + is reported in the tree somehow. (Exactly which property reports + the value varies depending on the control function and pattern; for + more information, see Windows + Automation API).
    8. +
    9. Check whether a control pattern is reported in the tree. If a + control pattern is reported, test the methods of that pattern using + facilities in the verification tool. Verify that invoking the methods + has changed the corresponding read only property values in the tree.
    10. +
    +
    +

    Expected Results

    +

    #3, #4, and #5 (if applicable) are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL7.html b/techniques/silverlight/SL7.html new file mode 100644 index 0000000000..09c3f167a7 --- /dev/null +++ b/techniques/silverlight/SL7.html @@ -0,0 +1,263 @@ +Designing a Focused Visual State for Custom Silverlight Controls

    Designing a Focused Visual State for Custom Silverlight Controls

    ID: SL7

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to build custom visual states for + custom controls that include visible focus indicators in the templates + and parts.

    +

    The default Silverlight core controls all indicate some type of visible + focus indication, through their default templates. For more information + on how Silverlight controls will generally supply a default visual + focus indicator, see Focus + Overview on MSDN.

    +

    Silverlight control skinning is enabled through a deliberate separation + of visible user interface design and control logic in the Silverlight + control model. Control authors expect that application authors might + reskin their control. But control authors should provide an initial + default set of states, templates, etc. so that application authors + have a good baseline of functionality to compare with their customization. + Defining visible focus states for all control parts is an example of + such baseline functionality. In order to make the visual focus state + customizable, the visual state should be associated with a name. Ideally + that name should have a human-readable meaning that hints at its purpose, + but the real reason for the name is that it connects the XAML-defined + template (which control consumers can change) with the control logic + defined by the control author (which control consumers cannot change). + Also, the visual names and groups in the XAML should be attributed + on the control class, to assist design tools. The best resource for + general information about Silverlight control customization is Silverlight + documentation on MSDN.

    +
    +

    Component Parts

    +

    Some controls are created by assembling various component parts that + are already defined as controls either by the Silverlight run time + libraries or by third parties. That scenario is not really what this + technique is about, because in that case the focus behavior is already + defined by the component's template, and the control author can re-use + that behavior as-is or reskin it but still through the same named state + definition. This technique specifically addresses how to define a control + where the interactive surface has mouse and keyboard handling defined + at a lower level for the control as a whole. The actual focus region + is defined by the control author in that case, and the focus indicator + is also defined to match the behavior visually and functionally.

    +
    +
    +

    Design for Focus Indicators

    +

    The general design principles for visual focus indicators are that + the indicators should apply a visual change to the focus region's exterior + margin. A common pattern is to deliberately define the visuals for + the control with a pre-existing blank margin for its layout slot; that + way when the focus indicator is applied, the focus indicator can fill + that margin.

    +

    The actual graphic for the visual focus indicator is typically a border + or shaped frame of a solid color brush with at least 1 pixel line thickness. + The color used for the border stands out visually from the underlying + control background or other elements of the control. The contrast between + brush for visual focus and the remainder of control should be a contrast + difference that is visible to users who do not distinguish the hue + of colors, but can distinguish the lightness/value. In many cases the + border is rectangular, to go along with the control's layout slot. + However, if the control's basic shape is a non-rectangular shape, sometimes + the focus indicator is designed to make a border around that shape. + An example of a default Silverlight control that is round and applies + an exterior round border as a focus indicator is a RadioButton.

    +

    Most focus indicator designs change only the border and do not change + the main area of the control. One reason for this is that changes to + the main control are typically reserved for other interactive states + that also have a visual indicator. Specifically, controls need a visual + state that indicates that the mouse is over the control (this is termed + either MouseOver or Hover state). Controls that support activation + also have a visual state that provides feedback for activation. For + example, the default Silverlight RepeatButton changes + its Background gradient on the button field to be + darker blue value when the mouse is over the button, and changes to + an even darker value blue when the button is activated (either by clicking + the mouse or by pressing SPACE or ENTER with keyboard focus on the RepeatButton). + To see this behavior in a live sample, see RepeatButton + sample on MSDN.

    +
    +
    +

    Logic for Focus Indicators

    +

    Typical logic is that the border to indicate focus is present in the + default template design, but with an initial value of Visibility=Collapsed. + Then, a visual state for focus is defined with a name that properly + indicates its purpose as text (example: "Focused"). In addition, + a state is needed that undoes whatever changes were applied for focus, + once focus moves to another element (for example, "Unfocused"). + For example, if the "Focused" state sets the value Visibility=Visible + on some element, the "Unfocused" state sets that value to + Collapsed again. Silverlight's visual state system also provides a + way to group related states with a factoring name (for example, "FocusStates"). + For more information on state names and state groups in Silverlight + visual states, as well as learning how these states define a control + contract that any control consumers should follow if they reskin that + control, see Customizing + the Appearance of an Existing Control by Using a ControlTemplate on + MSDN.

    +

    The visual state system is designed to support visual transitions + to states, and for that reason the visual state system is closely coupled + with the Silverlight animation system. By animating the transition, + the visual appearance changes over a time interval. Typically, if transitions + are used, the time interval is short, one second or less. In the case + of focus indicators, it is typical to not use transitions and to instead + make a discrete change; otherwise, the state change might be interpreted + by users as a lag in interface response from their system.

    +

    The states themselves are designed in XAML, but are loaded and unloaded + through logic that the control author defines as part of their control + code. The control author does this by handling the appropriate events + that occur while the event scope applies to their control. For example, + to apply the "Focused" state, the control author handles + the GotFocus + event. Rather than handle the event directly, the more common pattern + is to override a virtual method that acts as a prewired event handler, OnGotFocus. + The centralized logic for visual state changes is the method GoToState, + with one of the parameters to pass representing the XAML name of the + correct state to load from the XAML templates. Examples for all of + the APIs discussed here are available in the MSDN topic Creating + a New Control by Creating a ControlTemplate.

    +
    +
    +

    Focus in Silverlight

    +

    Focus in Silverlight is equivalent to the larger user interface and + application concept of keyboard focus. The element that has focus is + the element within the Silverlight object tree and programming model + that has first chance to process the Silverlight key events. As a more + tangible example that is user-centric, if a TextBox has + keyboard focus, then when the user presses keys on the keyboard, the + characters associated with the user's pressed keys (or possibly input + that is enabled by an assistive technology that can substitute for + key strokes) will appear in the TextBox. A user interface + element in Silverlight can obtain keyboard focus in one of three ways:

    +
      +
    1. The user uses the Silverlight tab sequence to traverse into the + Silverlight content and to focus a specific control.
    2. +
    3. The Silverlight application's logic calls the Focus() method programmatically + to force focus to a control.
    4. +
    5. The user performs some other action, for example uses the mouse + to click on a control. That control's specific logic handles the + Silverlight input event and uses that event as stimulus to call Focus() + on that control. The difference between this case and the above case + is that the behavior is typically built-in to that control's runtime + behavior, and does not require each application author to call Focus() + in application code.
    6. +
    +
    +

    Examples

    +
    +

    Visible focus indicator as a style and state

    + +

    The following is the XAML that defines the basic (normal) control + template. This control is simple: it has a yellow circle graphic, which + overlays a red circle edge when the control is focused. The circle + edge is defined by the "FocusVisual" element in the composition, + and is initially Visibility=Collapsed (the expected visual state prior + to being focused).

    +
    <ResourceDictionary
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +   xmlns:local="clr-namespace:FocusVisualCustomControl"
    +>
    +   <Style TargetType="local:SampleControl">
    +       <Setter Property="Template">
    +           <Setter.Value>
    +               <ControlTemplate TargetType="local:SampleControl">
    +                   <Grid x:Name="ControlRoot">
    +                       <Ellipse x:Name="CoinGraphic"
    +                         Fill="Orange"
    +                         Width="{TemplateBinding Width}"
    +                         Height="{TemplateBinding Height}"
    +                       />
    +                       <Ellipse x:Name="FocusVisual"
    +                         Visibility="Collapsed"
    +                         Stroke="Red"
    +                         StrokeThickness="1"
    +                         Width="{TemplateBinding FrameworkElement.Width}"
    +                         Height="{TemplateBinding FrameworkElement.Height}"
    +                       />
    +                   </Grid>
    +               </ControlTemplate>
    +           </Setter.Value>
    +       </Setter>
    +   </Style>
    +</ResourceDictionary>
    +
    +

    The following is the specific visual state portion. Note how the + visual state includes an ObjectAnimation with discrete + keyframes for hard transition between Visible and Collapsed, targeting + the element "FocusVisual" in the composition shown in the + previous XAML.

    +
                           <VisualStateManager.VisualStateGroups>
    +                           <VisualStateGroup x:Name="FocusStates">
    +                               <VisualState x:Name="Unfocused"/>
    +                               <VisualState x:Name="Focused">
    +                                   <Storyboard>
    +                                       <ObjectAnimationUsingKeyFrames
    +                                         Storyboard.TargetName="FocusVisual" 
    +                                         Storyboard.TargetProperty="Visibility" Duration="0">
    +                                           <DiscreteObjectKeyFrame KeyTime="0">
    +                                               <DiscreteObjectKeyFrame.Value>
    +                                                   <Visibility>Visible</Visibility>
    +                                               </DiscreteObjectKeyFrame.Value>
    +                                           </DiscreteObjectKeyFrame>
    +                                       </ObjectAnimationUsingKeyFrames>
    +                                   </Storyboard>
    +                               </VisualState>
    +                           </VisualStateGroup>
    +                       </VisualStateManager.VisualStateGroups>
    +                       
    +

    The following is control logic in the control class that responds + to the focus-related events and switches visual states in response. + In this particular example, "Unfocused" is a state without + a definition. Switching to the definitionless state has the effect + of reverting to the default state, which in the case of this design + is intentional. Alternatively, authors could make specific template + changes that revert any animation that applied to the focused state.

    +
           protected override void OnGotFocus(RoutedEventArgs e)
    +       {
    +           base.OnGotFocus(e);
    +           VisualStateManager.GoToState(this, "Focused", false);
    +       }
    +       protected override void OnLostFocus(RoutedEventArgs e)
    +       {
    +           base.OnLostFocus(e);
    +           VisualStateManager.GoToState(this, "Unfocused", false);
    +       }
    +
    +

    This example is shown in operation in the working example of Visual Focus Indicator.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Using a keyboard, tab to the element where focus characteristics + are being examined.
    4. +
    5. Check that the background, border, or other noticable visual indicator + of the element changes color.
    6. +
    7. Check that the changes in color for the background, border, or + other noticable visual indicator are removed when the element loses + focus.
    8. +
    +
    +

    Expected Results

    +

    #3 and #4 are true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/SL8.html b/techniques/silverlight/SL8.html new file mode 100644 index 0000000000..fb59ece8b1 --- /dev/null +++ b/techniques/silverlight/SL8.html @@ -0,0 +1,241 @@ +Displaying HelpText in Silverlight User Interfaces

    Displaying HelpText in Silverlight User Interfaces

    ID: SL8

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to provide a long text alternative + that replaces content when a short text alternative is not sufficient + for a given user, and the user specifically requests that the application + should provide more context or more information through the application + user interface. The technique could also apply for providing a long + text alternative for a nontext object, for example for an image that + contains a level of detail that is difficult to capture in a standard + visible-in-UI image caption.

    +

    Silverlight supports a UI Automation property named HelpText, + to connote its possible usage to provide imperative instructions for + interactive elements. HelpText is not always forwarded + to users by existing assistive technologies, which is an issue discussed + in the technique . + Rather than relying on a particular assistive technology's support + for enabling users to access the UIA HelpText, application + authors can introduce user interface elements into their design that + databind directly to the HelpText property, but where + the interface element is not necessarily displayed by default. An interface + update might be designed to occur if the application user specifically + activates a "Get Help" action that is presented in the initial + user interface.

    +

    This technique emphasises a "HelpText" model as a factoring + practice. Silverlight application authors can use the HelpText as + a data source that centralizes such information, because it already + exists and has that intended purpose in accessibility frameworks. For + example, the HelpText could be shown in a tooltip, + a popup, a separate user interface element that is deliberately rendered + in close proximity, etc. For accessibility support, a recommended display + option for HelpText is to add or dynamically alter + a Silverlight text element in the primary user interface. Silverlight + supports an adaptive layout metaphor. Adding text to the runtime elements + in the application generally causes an interface redraw, which in turn + informs assistive technologies (through UIA properties and events) + that content might have changed.

    +

    To set the UIA HelpText in Silverlight, you set the + attached property AutomationProperties.HelpText. AutomationProperties.HelpText can + be set in code, but is typically set in XAML that defines a Silverlight + UI.

    +
    +

    HelpText and Tooltip

    +

    The same information that is used for AutomationProperties.HelpText long + text alternatives could also be useful to sighted users. In this case, + the same text could be displayed in a Silverlight ToolTip control. + The reason that application authors should use both AutomationProperties.HelpText AND Tooltip in + conjunction is because the Tooltip information is + not introduced into the runtime accessibility framework information + set by UI Automation, because that information set does not anticipate + the mouse action triggers that cause tooltips to display. In Silverlight + programming, a useful technique for sharing the same resource is to + combine the Silverlight data binding feature with the .NET Framework + embedded resource feature. For more information on combining Silverlight + data binding and resources for common string sources, see How + to Make XAML Content Localizable.

    +
    +

    Examples

    +
    +

    Displaying a long text alternative for an Image with + XAML

    + +

    Application authors can specify the AutomationProperties.HelpText attribute + on the Image element. The value provided for the attribute + should be a meaningful long text alternative for the image content. + The value of AutomationProperties.HelpText should + augment rather than duplicate any AutomationProperties.Name or + an associated Label or LabeledBy caption. + One or both of these is also typically specified to provide the basic + (short-text) accessibility support for an image.

    +
    <StackPanel x:Name="imgContainer">
    + <Image
    +   Height="400" Width="600"
    +   Source="/office.png"
    +   x:Name="imgOffice"
    +   AutomationProperties.HelpText=”The standard office layout
    +includes one corner desk unit in the corner farthest from the
    +door, and one file cabinet against the same wall as the door.”/>
    + <sdk:Label x:Name="lblimgOffice" Target="{Binding ElementName=imgOffice}">Diagram of standard office layout</sdk:Label>
    + <Button x:Name="HelpButton" Click="HelpButton_Click">Provide text-only alternative description of the previous image</Button>
    +</StackPanel>
    +
    +

    The following event handler removes the Help button and replaces + it in UI with a TextBox that displays the long text + alternative.

    +
           private void HelpButton_Click(object sender, RoutedEventArgs e)
    +       {
    +           imgContainer.Children.Remove(HelpButton);
    +           TextBox tb = new TextBox();
    +           tb.IsReadOnly=true;
    +           tb.Text = AutomationProperties.GetHelpText(imgOffice);
    +           imgContainer.Children.Add(tb);
    +           tb.Focus();
    +       }
    +
    + +
    +
    +

    Using HelpText to augment existing form labels, to provide + long text instructions

    + +

    This example provides instructions for two form fields. The same text + is also displayed for mouse users as a Tooltip and + the AutomationProperties.HelpText string is used as + a common source for both display options. In this example, the form + submission does not perform client-side validation (although server-side + validation following a data round trip might still exist, or validation + could be added similar to the technique shown in ).

    +

    The following is the XAML UI:

    +
    <UserControl xmlns:sdk="http://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk" 
    +   x:Class="HelpTextAndToolTip.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    +       <Grid x:Name="LayoutRoot" Background="White" Margin="10">
    +           <Grid.RowDefinitions>
    +               <RowDefinition Height="Auto"/>
    +               <RowDefinition Height="Auto"/>
    +               <RowDefinition Height="Auto"/>
    +               <RowDefinition Height="Auto"/>
    +               <RowDefinition Height="Auto"/>
    +           </Grid.RowDefinitions>
    +           <Grid.ColumnDefinitions>
    +               <ColumnDefinition Width="Auto"/>
    +               <ColumnDefinition Width="200"/>
    +               <ColumnDefinition Width="Auto"/>
    +           </Grid.ColumnDefinitions>
    +           <TextBlock Text="Form With Tooltips" FontSize="16" FontWeight="Bold"
    +     Grid.Column="1" HorizontalAlignment="Center" />
    +           <sdk:Label x:Name="NameLabel" Target="{Binding ElementName=NameTextBox}"
    +     Grid.Row="2" Margin="3"/>
    +           <TextBox x:Name="NameTextBox" 
    +     AutomationProperties.Name="{Binding Content, ElementName=NameLabel}"
    +     Text="{Binding Name, Mode=TwoWay, UpdateSourceTrigger=Explicit}"
    +     Grid.Column="1" Grid.Row="2" Margin="3"
    +                    AutomationProperties.HelpText="{Binding NameTextBoxToolTipString,Source={StaticResource TooltipStrings}}">
    +           <ToolTipService.ToolTip>
    +               <ToolTip Content="{Binding NameTextBoxToolTipString,Source={StaticResource TooltipStrings}}" />
    +           </ToolTipService.ToolTip>
    +           </TextBox>
    +           <sdk:Label x:Name="AgeLabel" Target="{Binding ElementName=AgeTextBox}"
    +     Grid.Row="3" Margin="3" HorizontalAlignment="Right"/>
    +           <TextBox x:Name="AgeTextBox" 
    +     AutomationProperties.Name="{Binding Content, ElementName=AgeLabel}" 
    +     Text="{Binding Age, Mode=TwoWay, UpdateSourceTrigger=Explicit}"  
    +     Grid.Column="1" Grid.Row="3" Margin="3"
    +    AutomationProperties.HelpText="{Binding AgeTextBoxToolTipString,Source={StaticResource TooltipStrings}}">
    +           <ToolTipService.ToolTip>
    +               <ToolTip Content="{Binding AgeTextBoxToolTipString,Source={StaticResource TooltipStrings}}" />
    +           </ToolTipService.ToolTip>
    +       </TextBox>
    +       <StackPanel Orientation="Horizontal">
    +           <Button x:Name="SubmitButton" Content="Submit" Click="SubmitButton_Click" Grid.Column="1" Grid.Row="4" Width="50" Margin="3" />
    +           <Button x:Name="HelpButton" Click="HelpButton_Click">Get Help</Button>
    +       </StackPanel>
    +       </Grid>
    +</UserControl>
    +
    +

    The following is the resource definition in app.xaml:

    +
           <ResourceDictionary>
    +           <resources:Resource1 x:Key="TooltipStrings"/>
    +       </ResourceDictionary>
    +       
    +

    The generated resource code that defines the "Resource1" class + is not shown here because it is mostly infrastructure that is produced + by a generation task in Visual Studio. For more information about + embedded resources in Silverlight, see Resources + Overview on MSDN. The resources here contain just two strings:

    +
      +
    • NameTextBoxToolTipString: Must be 10 characters or less. Required.
    • +
    • AgeTextBoxToolTipString Must be a value between 0 and 120. Required.
    • +
    +

    The following is the event handler code, which changes the interface.

    +
           private void HelpButton_Click(object sender, RoutedEventArgs e)
    +       {
    +           AgeLabel.Content = AgeLabel.Content + ": " + AutomationProperties.GetHelpText(AgeTextBox);
    +           NameLabel.Content = NameLabel.Content + ": " + AutomationProperties.GetHelpText(NameTextBox);
    +           NameTextBox.Focus();
    +       }
    +       
    +

    Note the call to Focus() - this puts the screen reader focus on + the first form element so that the added text can be read. The very + same text source as used for the Tooltip is added + programmatically to the existing Label controls.

    +

    After the Get Help button is clicked, the visual appearance of the + application is modified:

    +
    + + +
    Before activating Get Help
    + +
    +
    + + +
    After activating Get Help
    + +
    +

    This example is shown in operation in the working example of HelpText and Tooltip.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag. To see + UI Automation, use Microsoft Windows as platform.
    2. +
    3. For a control where this technique is used to provide a long text + alternative, verify that an identifiable and usable "Get Help" control + is present in the initial user interface or assistive technology + representation of that interface.
    4. +
    5. Verify that activating the "Get Help" control changes + the user interface, and the changed user interface now displays or + reports long text alternatives that better address the user's information + needs.
    6. +
    7. If using a screen reader, verify that the long text alternative + can be read aloud.
    8. +
    +
    +

    Expected Results

    +

    #2 and #3 are true. If testing with a screen reader, #4 is true.

    +
    +

    Resources

    + + + +
    diff --git a/techniques/silverlight/SL9.html b/techniques/silverlight/SL9.html new file mode 100644 index 0000000000..d8751d4337 --- /dev/null +++ b/techniques/silverlight/SL9.html @@ -0,0 +1,307 @@ +Handling Key Events to Enable Keyboard Functionality in Silverlight

    Handling Key Events to Enable Keyboard Functionality in Silverlight

    ID: SL9

    Technology: silverlight

    Type: Technique

    When to Use

    +
      +
    • Microsoft Silverlight, versions 3 and greater
    • +
    • Silverlight managed programming model and Silverlight XAML
    • +
    +

    Description

    +

    The objective of this technique is to handle key events in a Silverlight + application and enable application-specific keyboard functionality + in a Silverlight application. The keyboard functionality might relate + to a particular element of the Silverlight application user interface, + or might be a handler for global key events within the application, + such as an application-wide access key.

    +

    In Silverlight, application authors handle user input by attaching + event handlers for input events. The input events are implemented on + a class that is a base element in the Silverlight class hierarchy, + such that all Silverlight UI elements can be the source of an input + event if the user interacts with them. Typically, the event handler + names are specified in XAML, although it is also possible to wire events + in code. The implementation of the handlers for the Silverlight managed + code programming model is always done in C# or Visual Basic code.

    +

    The most commonly used input events are the following:

    +
      +
    • + KeyUp, KeyDown - these are the + key events. Which key is pressed is determined by event parameters + passed to the handler.
    • +
    • + MouseEnter, MouseOver, MouseLeave +
    • +
    • + MouseLeftButtonDown, MouseLeftButtonUp, MouseRightButtonDown, MouseRightButtonUp +
    • +
    +

    Other forms of input that Silverlight supports include touch devices + (with mouse promotion for cases where the application runs on devices + that do not have touch input modes) and a related inking mode. For + any UI interaction that uses mouse input or these other input modes, + Silverlight application authors can write a parallel key event handler + to provide users the keyboard equivalent.

    +

    Also, the Silverlight event system and control model combine to enable + behavior whereby a mouse event and a keyboard event can be treated + as the same event and can be handled by a common event handler. Using + this technique, Silverlight authors can facilitate keyboard functionality + in custom controls or as override behavior to existing Silverlight-supplied + controls, and provide equivalence for mouse events or events that are + specific to other input devices. Silverlight authors can also use controls + that already have a keyboard equivalence as a built-in behavior.

    +

    The parallel key event handler case, and the built-in behavior case, + are each shown in one of the examples.

    +

    All input events report a specific source that is communicated to + handler code as an event parameter, so that the application author + can identify which element in their Silverlight UI was being interacted + with, and the application can perform an action that is relevant to + that user input. In the case of mouse events, the event source is the + element that the mouse pointer is over at the time. In the case of + key events, the event source is the element that has focus. The element + that has focus is visually indicated so that the user knows which element + they are interacting with (see ). Assistive technologies + often have parallel conventions whereby the user is made aware of which + element is visually focused and is the current input scope presented + by the assistive technology,

    +
    +

    Silverlight core control built-in keyboard functionality

    +

    The following is a list of the Silverlight-supplied controls that + have some level of key equivalence as a built-in behavior. In these + cases, it is not necessary to add a specific Key event handler; you + can handle the event and/or rely on the built-in key handling as listed.

    +
      +
    • + Button (SPACE and ENTER) - raises Click event.
    • +
    • Other ButtonBase classes eg RepeatButton, HyperlinkButton (SPACE + and ENTER) - raises Click event.
    • +
    • + TextBox (ENTER, unless in a mode where the TextBox + accepts multiple lines) - moves focus to next control, treated like + a TAB
    • +
    • + ListBox (various keys) - see OnKeyDown + Method.
    • +
    • + ComboBox (arrow keys ) - traverse list choices + as control UI if popup area displayed.
    • +
    • + RichTextBox (various keys ) - enable edit mode + operations; see RichTextBox + Overview.
    • +
    • + Slider (arrow keys ) - increment/decrement values.
    • +
    +
    +
    +

    Browser hosts and keyboard events

    +

    Silverlight is hosted as a plug-in inside a browser host. The Silverlight + run-time only receives the input events that the browser host forwards + to hosted plug-ins through a browser-specific program access layer. + Occasionally the browser host receives input that the browser host + itself handles in some way, and does not forward the keyboard event. + An example is that a Silverlight application hosted by an Internet + Explorer browser host on Windows operating system cannot detect a press + of the ALT key, because Internet Explorer processes this input and + performs the action of bringing keyboard focus to the Internet Explorer + menu bar. Silverlight authors might need to be aware of browser-specific + input handling models and not rely on key events for keys that are + essentially reserved for use by a browser host. For more information, + see Keyboard + Support.

    +
    +
    +

    Other event models

    +

    This technique specifically discusses event handling for the Silverlight + managed programming model. However, Silverlight also supports parallel + models for event handling, either through a Silverlight run-time feature + or due to Silverlight's role as a plug-in within a script-capable browser + host. For example, events from the HTML DOM can be handled by JavaScript + at HTML scope for the overall Silverlight plug-in; this uses the browser + host as script processor and the Silverlight run-time is not directly + involved. Or, HTML DOM events can be handled through an HTML bridge + that calls into Silverlight application code. These event models can + potentially be used to provide keyboard equivalence, but it is generally + more convenient to use the managed code model as described in this + technique. For more information on other event models in Silverlight, + see Events + Overview for Silverlight.

    +
    +

    Examples

    +

    Two examples are given. The first example is for the scenario of a + Silverlight application author that is simply incorporating an existing + control into their application design, and is taking advantage of mouse-keyboard + equivalence that is already defined by certain Silverlight core controls. + The second example is from the perspective of a control author, or + at least that of a Silverlight application author that intends to encapsulate + behavior in a custom Silverlight control and use it in their own application. + For this second example, the control will handle the general Silverlight + input event KeyUp, in order to check for input from + key(s) that are designated to have a specific input meaning for that + control.

    +
    +

    Built-in keyboard equivalence for core Silverlight controls

    + +

    This example pertains to cases where the control that handles key + events is focusable (through the tab sequence, etc.) and where an existing + Silverlight control behavior provides the keyboard equivalence In this + example, a Silverlight UI includes a Button element. + For sighted users, or users that generally use the mouse to interact + with UI, a typical way to interact with the button is to position the + mouse pointer over the element, and click the left mouse button. However, + the Button also supports a built-in key handling behavior, + whereby either the SPACE or ENTER keys are treated as an equivalent + action to clicking the button with a mouse. The requirement for this + interaction is that the Button must have keyboard + focus at the point in time that SPACE or ENTER are pressed. The Button might + gain focus because the user pressed the TAB key to move through the + tab sequence, or some equivalent action enabled by assistive technology. + In terms of the programming experience, the Silverlight application + author does not have to separately handle KeyDown for + this case. Within the Button control built-in code, + the special case of SPACE or ENTER keys pressed while a Button has + focus invokes the button’s Click event. Then the Silverlight + application author can simply handle Click without + differentiating whether the input action was a mouse click or a keyboard + equivalent. The following is the entire XAML UI.

    +
    <UserControl x:Class="BuiltInKeyEquivalence.MainPage"
    +   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    +   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    +>
    +   <Grid x:Name="LayoutRoot" Background="White" Loaded="LayoutRoot_Loaded">
    +       <Button Name="button1"
    +   AutomationProperties.Name="Equivalence test"
    +   Height="20" Width="150"
    +   Click="button1_Click">Click me, or press SPACE!</Button>
    +   </Grid>
    +</UserControl>
    +
    +

    The following is the C# logic.

    +
       private void button1_Click(object sender, RoutedEventArgs e)
    +   {
    +       MessageBox.Show("You clicked a button ... or maybe you hit the space bar ... or ENTER ... it's all the same to me.");
    +   }
    +   private void LayoutRoot_Loaded(object sender, RoutedEventArgs e)
    +   {
    +       System.Windows.Browser.HtmlPage.Plugin.Focus();
    +    }
    +
    +

    This example is shown in operation in the working example of built-in keyboard equivalents.

    + +
    +
    +

    Keyboard events for a custom control, keyboard equivalence

    + +

    In this example, a new Silverlight custom control named SimpleNumericUpDown + uses a control template that includes two buttons. To provide keyboard + equivalence for the buttons, an event handler is defined by the control + class code. The event handler invokes the action in response to certain + accelerator keys, where these actions are equivalent to clicking the + button composition parts of the control with a mouse. The following + is the default XAML template.

    +
    <ControlTemplate TargetType="local:SimpleNumericUpDown">
    +  <Border Background="{TemplateBinding Background}"
    +          BorderBrush="{TemplateBinding BorderBrush}"
    +          BorderThickness="{TemplateBinding BorderThickness}" Name="controlFrame">
    +      <Grid>
    +          <Grid.ColumnDefinitions>
    +              <ColumnDefinition Width="*"/>
    +              <ColumnDefinition Width="30"/>
    +          </Grid.ColumnDefinitions>
    +          <TextBox x:Name="valueBox" Text="{Binding NumericValue, RelativeSource={RelativeSource TemplatedParent}}"/>
    +          <StackPanel Grid.Column="1">
    +              <Button Name="minusButton">-</Button>
    +              <Button Name="plusButton">+</Button>
    +          </StackPanel>
    +      </Grid>
    +  </Border>
    +</ControlTemplate>
    +
    +

    The following C# code shows the event handlers. Also, the code includes + the event-wiring technique that is used whenever a Silverlight control + author implements a templateable control. This technique enables + the separation of UI appearance (which can be overridden) from the + input event-handling behavior (which is implemented by the control + author).

    +
       public class SimpleNumericUpDown : Control
    +   {
    +       public SimpleNumericUpDown()
    +       {
    +           this.DefaultStyleKey = typeof(SimpleNumericUpDown);
    +       }
    +       
    +       public override void OnApplyTemplate()
    +       {
    +           base.OnApplyTemplate();
    +           Button plusButton = GetTemplateChild("plusButton") as Button;
    +           Button minusButton = GetTemplateChild("minusButton") as Button;
    +           Border controlFrame = GetTemplateChild("controlFrame") as Border;
    +           plusButton.Click += new RoutedEventHandler(Increment);
    +           minusButton.Click += new RoutedEventHandler(Decrement);
    +           controlFrame.KeyUp += new KeyEventHandler(Handle_Accelerators);
    +       }
    +       private void Increment(object sender, RoutedEventArgs e)
    +       {
    +           this.NumericValue += 1;
    +       }
    +       private void Decrement(object sender, RoutedEventArgs e)
    +       {
    +           this.NumericValue -= 1;
    +       }
    +       private void Handle_Accelerators(object sender, KeyEventArgs e)
    +       {
    +           switch (e.Key)
    +           {
    +               case (Key.Left):
    +                   this.NumericValue -= 1; 
    +                   e.Handled=true;
    +                   break;
    +               case (Key.Right):
    +                   this.NumericValue += 1; 
    +                   e.Handled=true;
    +                   break;
    +               default: break;
    +           }
    +       }
    +       public Int32 NumericValue //definition omitted in this example
    +   }
    +
    +

    This example is shown in operation in the working example of custom keyboard events.

    + +
    +

    Tests

    +

    Procedure

    +
      +
    1. Using a browser that supports Silverlight, open an HTML page that + references a Silverlight application through an object tag.
    2. +
    3. Press TAB key to move keyboard focus to various element parts + of the user interface.
    4. +
    5. Verify that any user interface actions that exist for a given + element part each have a keyboard equivalent.
    6. +
    +
    +

    Expected Results

    +

    #3 is true.

    +
    +

    Resources

    + + + +
    \ No newline at end of file diff --git a/techniques/silverlight/img/AfterTooltipForm.png b/techniques/silverlight/img/AfterTooltipForm.png new file mode 100644 index 0000000000..df701dca31 Binary files /dev/null and b/techniques/silverlight/img/AfterTooltipForm.png differ diff --git a/techniques/silverlight/img/BeforeTooltipForm.png b/techniques/silverlight/img/BeforeTooltipForm.png new file mode 100644 index 0000000000..fafdb228d5 Binary files /dev/null and b/techniques/silverlight/img/BeforeTooltipForm.png differ diff --git a/techniques/silverlight/img/default_button_focus.png b/techniques/silverlight/img/default_button_focus.png new file mode 100644 index 0000000000..c02c82b85e Binary files /dev/null and b/techniques/silverlight/img/default_button_focus.png differ diff --git a/techniques/silverlight/img/encoder_scr.png b/techniques/silverlight/img/encoder_scr.png new file mode 100644 index 0000000000..72257bc4a1 Binary files /dev/null and b/techniques/silverlight/img/encoder_scr.png differ diff --git a/techniques/silverlight/img/highconafter.png b/techniques/silverlight/img/highconafter.png new file mode 100644 index 0000000000..a727566d38 Binary files /dev/null and b/techniques/silverlight/img/highconafter.png differ diff --git a/techniques/silverlight/img/highconbefore.png b/techniques/silverlight/img/highconbefore.png new file mode 100644 index 0000000000..fbc2f7a135 Binary files /dev/null and b/techniques/silverlight/img/highconbefore.png differ diff --git a/techniques/silverlight/img/listboxbar.png b/techniques/silverlight/img/listboxbar.png new file mode 100644 index 0000000000..5195535866 Binary files /dev/null and b/techniques/silverlight/img/listboxbar.png differ diff --git a/techniques/silverlight/img/newfontsize.png b/techniques/silverlight/img/newfontsize.png new file mode 100644 index 0000000000..e6a45fcb24 Binary files /dev/null and b/techniques/silverlight/img/newfontsize.png differ diff --git a/techniques/silverlight/img/originalfontsize.png b/techniques/silverlight/img/originalfontsize.png new file mode 100644 index 0000000000..5e1dee9f58 Binary files /dev/null and b/techniques/silverlight/img/originalfontsize.png differ diff --git a/techniques/silverlight/img/popup_keys.png b/techniques/silverlight/img/popup_keys.png new file mode 100644 index 0000000000..ecd4299c70 Binary files /dev/null and b/techniques/silverlight/img/popup_keys.png differ diff --git a/techniques/silverlight/img/reskinned_button_focus.png b/techniques/silverlight/img/reskinned_button_focus.png new file mode 100644 index 0000000000..30acbb40f4 Binary files /dev/null and b/techniques/silverlight/img/reskinned_button_focus.png differ diff --git a/techniques/silverlight/img/uiatree_simplepeerforwarding.png b/techniques/silverlight/img/uiatree_simplepeerforwarding.png new file mode 100644 index 0000000000..da01718d35 Binary files /dev/null and b/techniques/silverlight/img/uiatree_simplepeerforwarding.png differ diff --git a/techniques/silverlight/img/validating_screenshot.png b/techniques/silverlight/img/validating_screenshot.png new file mode 100644 index 0000000000..9a11136556 Binary files /dev/null and b/techniques/silverlight/img/validating_screenshot.png differ diff --git a/techniques/silverlight/img/validating_uia.png b/techniques/silverlight/img/validating_uia.png new file mode 100644 index 0000000000..a9327f32cd Binary files /dev/null and b/techniques/silverlight/img/validating_uia.png differ diff --git a/techniques/silverlight/silverlight.11tydata.json b/techniques/silverlight/silverlight.11tydata.json new file mode 100644 index 0000000000..0b02bf5531 --- /dev/null +++ b/techniques/silverlight/silverlight.11tydata.json @@ -0,0 +1,5 @@ +{ + "obsoleteSince": "20", + "obsoleteMessage": + "Microsoft ended support for Silverlight in 2021, and authors are encouraged to use HTML for accessible web content." +} diff --git a/tsconfig.json b/tsconfig.json index 2045da47d9..ada8090aeb 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,5 +1,6 @@ { "compilerOptions": { + "allowSyntheticDefaultImports": true, "baseUrl": ".", "module": "ES2022", "moduleResolution": "Node", diff --git a/understanding/20/parsing.html b/understanding/20/parsing.html index 3f83699b1f..ae72ef4d58 100644 --- a/understanding/20/parsing.html +++ b/understanding/20/parsing.html @@ -158,6 +158,14 @@

    Sufficient Techniques for Parsing

    +
  • + + Ensuring that + Web pages are well-formed + + +
  • +