ProgressBar

A ProgressBar gives dynamic feedback on the progress of a long-running operation. The progress can be updated by JavaScript function calls. This method works best for long-running JavaScript operations, or a series of JavaScript XHR calls to the server.

Examples

This progress meter is updated using JavaScript

See the API docs for more information on update().

Suppose you do not know the maximum up front. ProgressMeter has an indeterminate version, which does not display a percentage bar. Instead, an animation indicates that something is happening.

This code fragment displays the indeterminate progress meter while performing an XHR call. The time spent for the call is used to estimate the length of 10 calls, which will then be used as the maximum value. (Note: you will need to provide your own XHR url here.)

dojo.addOnLoad(function() {
	    // This starts the indeterminate bar
	    dijit.byId("setTestBar").update({indeterminate: true});
	    // Do a call to see what the average response time is
            timeStart = new Date();
	    var d = dojo.xhrGet({
	    	url: "../services/waste_time.jsp",
	        handleAs: "text"
	    });
	    d.addCallback(function() {
		    // Stop the indeterminate bar
		    dijit.byId("setTestBar").update({indeterminate: false});
		    avgTime = new Date() - timeStart;
		    //Now you can estimate the time for 10 calls
		    avgTime10 = avgTime * 10;
		    dijit.byId("setTestBar").update({maximum: avgTime10});
		});
	});

Accessibility

The progress bar is made accessible by providing a solid border around the visual progress indicator. This border is visible in high contrast mode as well as when images are turned off.

The internalProgress div is assigned the ARIA role of progressbar The valuenow attribute is updated as the progress is updated. No valuemin and valuemax values are provided since the valuenow attribute may be a string provided by the Web developer.

Note: The hot key for the Window-Eyes screen reader to speak progress bar information is ctrl-ins-b. JAWS provides the hot key ins-tab for announcing progress bar name and status.JAWS also has a setting to select the frequency of progress bar announcements. Go to the Configuration Manager, Select Set Options, then User Options and select the desired announcement frequency.

Changes to accessibility for version 1.0 of the ProgressBar

The ARIA valuenow property is set to the ProgressBar's progress value. The valuemin and valuemax properties are set to 0 and the ProgressBar's maximum, respectively.

Tooltip

Tooltip is similar to the title="" attribute in regular HTML, but is much more flexible. You can control the display timing, and specify arbitrary HTML for the tooltip text.

Example

Longanimity

Accessibility - updated for 1.0

General Issues

Tooltips are displayed when the associated item receives focus or a mouseover event. Be careful when assigning tooltips to arbitrary elements such as spans of text which may not receive keyboard focus because users of assistive technology or keyboard only users will not benefit from the tooltip. If the tooltip information is important, make certain that the item which triggers display of the tooltip can receive focus via the keyboard. This can be accomplished by adding a tabindex="0" attribute onto the trigger element to put it into the tab order of the page.

Dialog and TooltipDialog

Dijit's modal Dialog Box simulates a regular GUI dialog box. The contents can be arbitrary HTML, but are most often a form or a short paragraph. The user can close the dialog box without acting by clicking on the X button in the top-right corner.

Example

The following dialog box shows a simple Change Password form:

Change Password |

Old Password:
New Password:
Confirm New Password:
OK

Everything in the dialog box is wrapped in an implicit form. The code in the execute() attribute is executed when the dialog is submitted normally.

Auto-focusing The First Text Box (For 1.0)

Dialog, like most forms, does not automatically set the focus on the first form field. To do this with Dijit Dialog or TooltopDialog, simply define this code snippet once:

var focusFirstInput = function(e) { 
   dijit.focus(dojo.query('input', this.domNode)[0]); 
}

Then use dojo.connect to hook it to each dialog's onOpen event:

var c = dojo.connect(someDialogWidget, 'onOpen', dojo.hitch(someDialogWidget, focusFirstInput));

In 1.1 the Dialog has been updated to find and set focus to the first focusable element within the dialog. Thus, the above code snippet is no longer necessary in 1.1. See additional information in the 1.1 Accessibility section below.

TooltipDialog

A variant on Dialog Box is dijit.TooltipDialog. This displays the dialog box contents in a Tooltip

Although both Dialog and TooltipDialog are modal, TooltipDialog can be closed by clicking anywhere on the screen, whereas for Dialog you must click on the [x] mark of the Dialog.

A TooltipDialog appears as a drop down from a button, similar to a drop down button.

Example

Change Password

Old Password:
New Password:
Confirm New Password:
OK

Accessibility (added for 1.0)

General

When a dialog is opened focus goes to the title section of the dialog. This was implemented to provide screen reader support to speak the title of the dialog when it is opened. Likewise, when a tooltip dialog is opened, focus is placed on the container of the tooltip dialog. In future versions of the dialog and tooltip dialog widgets, focus will go to the first item in the dialog or tooltip dialog.

When focus is in a dialog, pressing the tab key will move focus forward to each focusable element within the dialog. When focus reaches the last focusable element in the dialog, pressing tab will cycle focus back to the dialog title. Pressing shift-tab will move focus backwards through focusable elements within the dialog until the dialog title is reached. If focus has previous cycled forward through all of the elements, pressing shift-tab with focus on the dialog title will move focus to the last element in the dialog. If focus has not previously been cycled through all of the focusable elements in the dialog using the tab key, pressing shift-tab with focus on the dialog title will leave focus in the title. The same focus cycling applies to the tooltip dialog as well with focus being set to the tooltip dialog container since there is no dialog title.

Known Issue: On Windows, In Firefox 2, when in High Contrast mode, the dialog with display correctly, but the underlying page will not be seen.

Keyboard

Accessibility (Updated for 1.1 and 1.2)

General

When a dialog is opened focus goes to the first focusable element within the dialog. The first focusable element may be an element which appears in the tab order by default such as a form field or link, an element with a tabindex attribute value of 0 or an element with a tabindex value greater than 0. Elements with a tabindex value greater than 0 will appear in the tab order before elements with a tabindex of 0 or those in the tab order by default. If the dialog does not contain a focusable item, focus will be set to the dialog container element when the dialog is opened. The same focus behavior has been implemented for tooltip dialog

When focus is in a dialog, pressing the tab key will move focus forward to each focusable element within the dialog. When focus reaches the last focusable element in the dialog, pressing tab will cycle focus back to the first focusable item. Pressing shift-tab will move focus backwards through focusable elements within the dialog. When the first focusable item is reached, pressing shift-tab will move focus to the last focusable item in the dialog.

Known Issues:

• On Windows, In Firefox 2, when in High Contrast mode, the dialog with display correctly, but the underlying page will not be seen.
• Special behavior for Input type=file elements as the first or only focusable element in a dialog.
• Dialogs with an input type=file as the only focusable element will not work with the keyboard. This is because input type=file elements require two tab stops - one in the textbox and the other on the "Browse" button. Rather than clutter the dialog box widget with code to special case for this one condition, dialog boxes with an input type=file as the only focusable element are not supported.
• Dialogss with an input type=file element as the first focusable element in Firefox (and there are additional focusable elements). Programmatically setting focus to an input type=file element behaves oddly in Firefox. In this case the focus is set onto the textbox field and then immediately moved onto the browse button of the input type=file field. This causes problems in Firefox when setting focus to an input type=file element as the first element as a dialog or tooltip dialog. For this reason, in Firefox if the first focusable item in a dialog or tooltip dialog is an input type=file, focus will be set onto the dialog container rather than the input element. For these reasons it is recommended that input type=file elements not be added as the only or first focusable item within a dialog or tooltip dialog in Firefox.
• Even though the dialog is marked with the proper ARIA role of dialog, JAWS 9 does not speak "dialog" when the dialog is opened. In Firefox 2 even though the focus is on the first focusable item in the dialog, the information about that item is also not spoken. Thus, it is important that the instructions or label for a trigger element that opens a dialog to indicate via text that a dialog will be opened. In Firefox 3 the dialog is also not announced but the information about the item in the dialog which gets focus is spoken. This will hopefully be corrected in a future release of JAWS.
• There are focus issues when the dialog is created via an href. Due to timing issues focus may not be properly set nor properly trapped in the dialog. For accessibility reasons, dialogs created via href are not recommended. This issue will be looked at for Dojo 1.2.

Keyboard

TitlePane

A TitlePane is a pane with a title on top that can be opened or collapsed. The visibility of the container is toggled by activating an arrow "button" on the title bar via the mouse or keyboard.

Examples

The rain in Spain falls mainly on the New York Stock Exchange.

Accessibility (updated for 1.0)

Keyboard

Each title pane title is included in the tab order of the document.

Screen Reader Information

The title pane container will have an ARIA labelledby property which points to the id of the title pane title. The title pane title has the ARIA role of button and property of haspopup=true to indicate that it controls the display of the pane. The role of button is used to indicate to the user that an action will occur when the button is activated. The tilte pane container will have an ARIA role of region which will be supported in Firefox 3 and identified by future versions of the screen readers.