[widgets] A proposal on widget modes

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/

Received on Tuesday, 20 January 2009 19:59:27 UTC