Copyright © 2009 W3C^® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

The Media Query API describes a DOM interface, including interfaces and events, for querying the CSS media type and features that are applied to any particular document in any particular state. This specificaiton also defines a means for detecting when the media type applied to a document view changes.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is produced by the Web Applications WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

You can find the latest Editor's Draft of this document in the W3C's CVS repository, which is updated on a very regular basis. The public is encouraged to send comments to the WebApps Working Group's public mailing list public-Webapps@w3.org (archive). See W3C mailing list and archive usage guidelines. A detailed list of changes from the previous version is also available from the W3C's CVS server.

Implementers should be aware that this document is not stable. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.

User agents that wish to extend this specification in any way are encouraged to discuss their extensions on a public forum, such as public-Webapps so their extensions can be considered for standardization.

Table of Contents

Introduction

This document describes extensions to CSS Media Queries, and a DOM interface for querying the media features and types that apply to a document at a given instance in time, including events to detect when said features change.

Chrome: means the user agent providing controls for resizing, closing, other window management (e.g., native controls provided by the operating system or window manager). unshaped window.

Transparency: the user agent renders the view port with (CSS-equivelent) opacity zero with respect to the background or application environment.

overflow: CSS overflow property for the viewport.

Control: the viewport of the widget is controlled by application by default (e.g., movable or non-selectable), but with certain element being interactive (e.g., input elements).

User agent resizable: ultimate sizing is left up to the user agent or widget.

Size matters: if the size is controlled by the user agent or if it controlled by the widget.

application

stuff

floating

42

fullscreen

 

docked

little and stuff

Example usage

@media handheld and (widget-mode: widget) and (orientation: landscape) {
	
}

@media tv and (widget-mode: docked) {
	
}

@media handheld and (widget-mode: docked) {
	
}

@media handheld and (widget-mode: docked) {
	
}

Conformance requirements

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

Diagrams, examples, and notes are non-normative. All other content in this specification is normative.

3. Media Queries

widget-mode media feature

The widget-mode feature describes the current rendering context for a Widget. The feature has one of the following values:

The floating feature

The widget value describes a widget currently using a chromeless window, and is the default presentation mode for a widget. How this is presented to the end-user is dependant on the User Agent and media type: Typically, on handheld devices, this widget will have a size equal to the screen size, or other rendering area assigned by the User Agent, while on desktop-like devices, it may only occupy part of the display.

The docked feature

The docked mode describes a widget running in a docked mode, which is typically an area with limited available area into which to render content.

Typically, when the media type is handheld, and the widget mode is docked, content is not expected to be interactive, e.g. no input events are dispatched to the document. In the case of screen-type media, content in docked mode is expected to be interactive.

The application feature

The application value represents a widget that runs in an application-like mode, where the widget is, if applicable, given regular chrome constructs, such as minimize, restore/maximize, and close buttons in addition to adjacent chrome, such as title bars and resize handlers. When running in this mode, widgets are typically not expected to try to explicitly control window sizes.

On platforms that do normally not render application chrome, this mode can be considered equivalent to the widget mode.

The fullscreen feature

4. Scripting Interfaces

4.1. The Media interface

interface Media {
  readonly attribute  MediaFeatureList        feature;
  readonly attribute  DOMString               type;
           attribute  MediaTypeChangeEvent    ontypechange;
}  

The Media interface is implemented as a media attribute on the WindowLayout interface, which is implemented by all objects implementing the Window interface:

interface ViewCSS : AbstractView {
  readonly attribute Media           media;  
  CSSStyleDeclaration getComputedStyle(in Element elt,
                                       in DOMString pseudoElt);
};

4.1.1. The MediaFeatureList interface

The MediaFeatureList exposes a queryable list of Media Features that apply to the current view of the document.

interface MediaFeatureList {
  readonly attribute unsigned long    length;
  CSSPropertyValue                    item(in unsigned long index);
};

4.2. The MediaTypeChangeEvent interface

When the current media type of the page is about to change, a mediatypechange event is dispatched on the Document, the Window object and on the document body. It must not bubble, must not be cancelable and must implement the Event interface [DOM3Events]. The event has no namespace (Event.namespaceURI is null)

The mediaType attribute on the event object signals the new media type to be applied.

interface MediaTypeChangeEvent : Event {
  // The new media type
  readonly attribute DOMString mediaType;
  void initMediaTypeChangeEvent(in DOMString typeArg, 
                                in boolean canBubbleArg,
                                in boolean cancelableArg, 
                                in DOMString mediaTypeArg);

  // For DOM Level 3 support
  void initMediaTypeChangeEventNS(in DOMString namespaceURI,
                                  in DOMString typeArg, 
                                  in boolean canBubbleArg, 
                                  in boolean cancelableArg, 
                                  in DOMString mediaTypeArg);
}

4.3. The WidgetModeChangeEvent interface

When the value of the widget-mode attribute in the MediaFeatureList list changes, the widgetmodechange is dispatched on the Widget object. It must not bubble, must not be cancelable and must implement the Event interface [DOM3Events]. The event has no namespace (Event.namespaceURI is null

interface WidgetModeChangeEvent : Event {
  readonly attribute DOMString widgetMode;
  void initMediaTypeChangeEvent(in DOMString typeArg, 
                                in boolean canBubbleArg, 
                                in boolean cancelableArg, 
                                in DOMString widgetModeArg);

  // For DOM Level 3 support
  void initMediaTypeChangeEventNS(in DOMString namespaceURI,
                                  in DOMString typeArg, 
                                  in boolean canBubbleArg, 
                                  in boolean cancelableArg, 
}

4.4. The ResolutionEvent interface

The resolution is dispatched on the document, Window objects and the body element when the value of the width or height attributes on the Screen object changes. It must not bubble, must not be cancelable and must implement the Event interface [DOM3Events]. The event has no namespace (Event.namespaceURI is null).

The width and height attributes in the event object is the new display width and height respectively.

interface ResolutionEvent : Event {
  readonly attribute int width;
  readonly attribute int height;
  void initMediaTypeChangeEvent(in DOMString typeArg, 
                                in boolean canBubbleArg, 
                                in boolean cancelableArg, 
                                in int widthArg,
                                in int heightArg);

  // For DOM Level 3 support
  void WidgetModeChangeEventNS(in DOMString namespaceURI,
                               in DOMString typeArg, 
                               in boolean canBubbleArg, 
                               in boolean cancelableArg, 
                               in int widthArg,
                               in int heightArg);
}