Stopwatch and timer

The Stopwatch and Timer widgets can be used to measure time. The Stopwatch widget allows the user to record lap times, while the Timer widget may count time in a predefined range, for example time remaining to the end of the auction. In addition, it can invoke a specified action when the time limit is reached.

Both stopwatch and timer use the same display mechanism as the Clock widget. They also share some XDIME elements and style properties. See Showing current time for more information.

Visual appearance

Time is displayed in a form of a digital clock, similar to that described in Showing current time. A stopwatch as well as a timer can be placed within other data containing widgets, for example carousel, popup, tabs or ticker tape.

User interactions

The user can start, stop, and reset both stopwatch and timer using the provided controls.

The Stopwatch widget may record the lap times in two modes. In lap mode, when the user captures a lap time, it is following example the stopwatch display, with the same styles as the main clock. After recording the lap time the stopwatch is reset, and starts counting time again until the next lap time is recorded. When the stop button is pressed, the list of all the lap times and the total time are displayed. In split mode recording a lap time does not reset the stopwatch.

XDIME 2 elements

The Stopwatch widget is defined by widget:stopwatch. The widget:button elements associated with the appropriate actions allow the user to control it.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:widget="http://www.volantis.com/xmlns/2006/05/widget">
  <head>
    <title>widget:stopwatch</title>
  </head>
  <body>
    <widget:stopwatch id="myStopwatch"/>
    <div>
      <widget:button action="myStopwatch#start">Start</widget:button>
      <widget:button action="myStopwatch#stop">Stop</widget:button>
      <widget:button action="myStopwatch#reset">Reset</widget:button>
      <widget:button action="myStopwatch#split">Split</widget:button>
    </div>
  </body>
</html>

The widget:timer element defines a timer. The optional start-time and stop-time attributes specify a range in which time will be measured. Values of those two attributes must be given in milliseconds. Depending on the values you set, the timer will count either up or down.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:widget="http://www.volantis.com/xmlns/2006/05/widget">
  <head>
    <title>widget:timer</title>
    <style type="text/css">
      #myTimer {
        mcs-datetime-format: '%d%18/7/121%i%1%s';
      }
    </style>
  </head>
  <body>
    <widget:timer id="myTimer" start-time="180000" stop-time="0"/> 
    <div>
      <widget:button action="myTimer#start">Start</widget:button>
      <widget:button action="myTimer#stop">Stop</widget:button>
      <widget:button action="myTimer#reset">Reset</widget:button>
    </div>
    <div>
      <span>Start time:</span>
      <widget:input property="myTimer#start-time"/>
      <span>Stop time:</span>
      <widget:input property="myTimer#stop-time"/>
    </div>
  </body>
</html>

The finished event can invoke an action when the time limit is reached.

<widget:popup id="popupOnFinish">Your time is up!</widget:popup>
<widget:handler event="myTimer#finished" action="popupOnFinish#show"/>

The load action can be used to set the start-time and stop-time attributes with AJAX.

<widget:timer id="myTimer">
  <widget:load src="service/timer"/>
</widget:timer>

The widget response should have the following structure.

<?xml version="1.0" encoding="UTF-8"?>
<response:response xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:mcs="http://www.volantis.com/xmlns/2006/01/xdime/mcs"
  xmlns:response="http://www.volantis.com/xmlns/2006/05/widget/response">
  <response:head>
    <response:link rel="mcs:theme" href="/main.mthm"/>
  </response:head>
  <response:body>
    <response:timer start-time="0" stop-time="600000"/>
  </response:body>
</response:response>

Both widgets may contain the widget:clock-content elements which can specify custom markup, for example text or image policies, for the parts of the clock. See Showing current time for details.

Styling the widget

The mcs-count-mode property is used to set the stopwatch mode. Possible values are: 'split' (default) and 'lap'.

The mcs-datetime-format property defines a time format. The following table lists the property values applicable to the Timer and Stopwatch widgets.

Parameter	Description
%d	Days from 01 to 31, i.e. 2 digits with a leading zero
%H	Hours with a leading zero
%i	Minutes with a leading zero
%s	Seconds with a leading zero
%S	Milliseconds with a leading zero
%1, %[n]	First and n-th separator

Non-client fallback

If a device does not support those widgets then they are ignored and do not produce any markup.