Hi All, In the current Widgets 1.0: Packaging and Configuration specification [1], the window modes feature is identified as being at risk. Vodafone believes that window modes are an important feature and should be supported in Widgets 1.0. This email provides a proposal for how modes could be specified and why we think this would be of value. Our proposal is based on our experiences with current and prototype widget implementations, however, we welcome any suggestions on how this proposal could be improved.
Thanks, Mark ------------------------------- Proposal ------------------------------- Vodafone has identified the need for floating, fullscreen and docked modes. We have not identified a need for an application mode, although we recognise that this may not be aimed at mobile devices. We would therefore support the addition of the following attribute definition to [1]: --------Start of addition---------- Mode Attribute A keyword attribute whose value is one of the following valid modes: floating, fullscreen, docked. The default value, which is used when the attribute is omitted or has a value other than one of the valid modes, is floating. --------End of addition---------- Vodafone has also identifed the need to allow a widget author to declare a preferred mode of operation in the configuration document. This value would be used by the widget user agent to determine which mode to start the widget in. If a widget user agent does not support the indicated mode it should open the widget in floating mode. Vodafone also believes that it should be possible for a widget to be able to indicate which modes it has been designed to support. We therefore propose the introduction of a mode element, i.e. --------Start of addition---------- The mode Element The mode element represents the modes that a widget has been designed to operate in. Context in which this element may be used: In the widget element. Content model: Empty. Occurrences: Zero or one. Attributes default Optional. A mode attribute that indicates the default mode of operation for a widget. fullscreen Optional. A boolean attribute that indicates whether the widget has been designed to run in fullscreen mode. dockable Optional. A boolean attribute that indicates whether the widget has been designed to run in dockable mode. Usage Example This section is non-normative. This example shows the expected usage of the mode element. <widget xmlns="http://www.w3.org/ns/widgets";> <mode default="floating" dockable="true" fullscreen="false"/> </widget> --------End of addition---------- The fullscreen and dockable attributes would be used by the widget user agent to determine whether it should support transition to the indicated mode. For example, if a widget declared dockable="false" the widget user agent should not try and render the widget within a dock and might instead choose to display the widget's icon. It is expected that all widgets will be capable of running in floating mode. There is therefore no need to indicate support for floating mode, i.e. using a floating attribute. ------------------------------- Background ------------------------------- The following text is provided as background information to support the proposal above. It defines the supported widget modes, their expected behavioural differences and the relationship to configuration elements. It is not our expectation that any of this text should be included in the Packaging or Configuration specification but we hope it will be useful in explaining our proposal and as input to the drafting of the APIs and Events specification. A widget mode is a visual and behavioural state of a widget instance. As such, each widget instance can only be in a single mode at any one given time. Transition from one mode to another may be triggered by user interaction and potentially by the widget itself, although this is for further study. Widget user agents may support the ability to open multiple instances of the same Widget Resource, in which case each instance will have its own independent mode. Only one widget instance can ever operate in fullscreen mode at any one time. A widget user agent may display icons as shortcuts to instantiated widgets, however an icon is not considered to be a widget mode. The widget user agent is expected to provide the APIs, events and properties to support modes, e.g.: a.)onModeChange - an event triggered when the widget transitions to a new mode; b.)getMode - an API that returns the current mode of the widget, alternatively this could be a property of the widget object; c.)onBlur - an event triggered when the widget loses focus; d.)onFocus - an event triggered when the widget gets focus; e.)resize(height, width) - an API for changing the size of a floating widget; f.)onResize - an event triggered when the widget is re-sized in floating mode; g.)getDockSize() - an API that returns the size of the dock(s) supported by the widget user agent. Note: lots of this is already hinted at in the APIs and Events draft [2] For all of the modes defined below it is expected that the widget user agent will use the start file, as defined in [1], to instantiate the widget. ------------------------------- Floating mode It is expected that all widget user agents will support floating mode. In floating mode the size of the widget window is determined by width and height attributes of the widget element. If no width and height values are declared, then the defaults are height=300px and width=150px in portrait orientation and height=150 and width=300px for landscape orientation. Behavioural characteristics: a.) Only one floating mode widget can have focus. The widget with focus must have the highest z-index; b.) Widgets in floating mode can overlap each other; c.) Depending on the capabilities of the widget user agent, it should be possible to drag and drop a floating mode widget instance to any place on the screen, allowing both the widget to overlap with other widgets and to disappear over the edge of the screen (as long as the user is not able to lose the widget completely); ------------------------------- Docked mode It should be optional for a widget user agent to support docked mode. In docked mode, the size of the widget is determined by the drawing area of a parent window container - the dock - which is a feature of the widget user agent. The widget element's width and height attributes are ignored. To support docked mode across a range of devices with different resolutions, whilst not requiring a standard dock size, we suggest that the widget user agent should provide a means for a widget to query the size of the docks provided by the widget user agent, e.g. using a getDockSize() API. As a result of this query, the widget user agent must return the inner dimensions of the available dock. Behavioural characteristics: a.) A widget in docked mode cannot have focus, i.e. it is not possible for a user to interact with a widget in docked mode directly; b.) When a docked widget is "opened", e.g. via user interaction with the dock / widget user agent, the docked widget should return to the mode it was in previous to being docked. If there was no previous mode, the widget should be opened in floating mode. If a widget user agent supports a widget dock, the dock must display all instantiated widgets. If the widget does not support docked mode, i.e. dockable="false", the widget user agent must display the widget's icon. If no icon is provided by the widget, the widget user agent should display a default icon in combination with the widget's name. ------------------------------- Fullscreen It is recommended that a widget user agent should support fullscreen mode. In fullscreen mode, the size of the widget is equal to the size of drawable screen area as determined by the widget user agent. The widget element's width and height attributes are ignored. The drawable screen area provided by the widget user agent should be constrained by the dimensions of the screen. Behaviour characteristics: a.) A widget in fullscreen mode always has focus; b.) System menus or status bars may be hidden by a widget in fullscreen mode. If a widget is in fullscreen mode, the widget user agent should provide a way for the user to quit the fullscreen mode (e.g. soft key click) and/or return to a different mode. c.) If the widget user agent supports the ability to detect a change in screen orientation, the widget user agent should provide an indication that the orientation of the screen has changed, e.g. through an onOrientationChange event. It is for further study whether this need could be met by the onResolutionChange event. d.) If the widget user agent is queried for the widget's width and height, it must return the inner dimensions of the available drawing area. e.) When a widget is moved into fullscreen mode, the widget user agent must move all other active widgets into the hidden state; f.) When moving a widget out of fullscreen mode, the widget user agent must return all other widgets to the displayed state. ------------------------------- Hidden and displayed states In addition to the modes defined above it is expected that widgets operate in one of two states; hidden and displayed. A widget instance will always have a mode and a state. The widget user agent moves the widget into a hidden state when it determines that the widget is hidden from view. The widget is moved back into a displayed state when the widget is once again visible. Moving into a hidden state triggers the onHide event. Moving into the displayed state triggers the onDisplay event. These events may be used by the widget to suspend and restart ongoing activities. ------------------------------- Controlling what is displayed in widget modes Vodafone would like to see support for CSS media queries to select styles applicable to the above window modes as per the following example: /* this media query matches if widget runs in docked mode */ @media all and (widget-mode:docked) { #myDockedView { display: block; /* shows the docked mode content */ } #myFullscreenView { display: none; } } /* this media query matches if widget runs in fullscreen mode */ @media all and (widget-mode:fullscreen) { #myDockedView { display: none; /* hides docked mode */ } #myFullscreenView { display: block; /* shows the fullscreen mode content */ } } [1] http://www.w3.org/TR/2008/WD-widgets-20081222/ [2] http://dev.w3.org/2006/waf/widgets-api/
