<refentry id="timerref">
  <refmeta>
    <refentrytitle>SandUhr::Timer</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>SandUhr CORBA interface</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>SandUhr::Timer</refname>
    <refpurpose>CORBA interface for SandUhr timer objects</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>SYNOPSIS</title>
    <synopsis>
module SandUhr {
  interface Timer {
    exception NotRunning { };

    enum TimerState { TSPrepare, TSRunning, TSDone };
    readonly attribute TimerState State;

    attribute string TimeSpec;
    attribute string Message;
    attribute AlarmAction Alarm;

    struct Color {
      unsigned short Red, Green, Blue;
    };
    attribute Color SandColor;

    attribute boolean WindowDecorations;

    enum Layer { LayerDesktop, LayerBelow, LayerNormal, LayerOntop };
    attribute Layer WindowLayer;

    void Destroy ();
    unsigned long TimeLeft () raises (NotRunning);
  };
};
    </synopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      The central part of &sanduhr; is the
      <classname>SandUhr::Timer</classname> interface.  It represents the
      sand-glass-shaped window and every piece of information associated to
      it.
    </para>

    <itemizedlist>
      <listitem>
        <para>The state of the timer:</para>

        <synopsis>
enum TimerState { TSPrepare, TSRunning, TSDone };
readonly attribute TimerState State;
        </synopsis>

        <para>
          This is <literal>TSPrepare</literal> if the timer is not
          yet running (e.g. while the initial setup window is
          showing), <literal>TSRunning</literal> during normal
          operation, and <literal>TSDone</literal> after the
          timer elapsed (i.e. while the alarm is delivered).
        </para>
      </listitem>

      <listitem>
        <para>The alarm time:</para>

        <synopsis>
attribute string TimeSpec;
        </synopsis>

        <para>
          The format of this string is explained in the manual section
	  called <link linkend="timespec">the alarm time</link>.
        </para>
      </listitem>

      <listitem>
        <para>The alarm message:</para>

        <synopsis>
attribute string Message;
        </synopsis>

        <para>
          This is passed to the alarm action for delivery.
        </para>
      </listitem>

      <listitem>
        <para>The alarm action:</para>

        <synopsis>
attribute AlarmAction Alarm;
        </synopsis>

        <para>
          There are several predefined subclasses of
          <classname>SandUhr::AlarmAction</classname> available.
          These are described in <xref
          linkend="alarmref">.
        </para>
      </listitem>

      <listitem>
        <para>The fill color of the sand glass:</para>

        <synopsis>
struct Color {
  unsigned short Red, Green, Blue;
};
attribute Color SandColor;
        </synopsis>

        <para>
          The Red, Green, and Blue values may lay in the range from 0
          to 255 inclusive.  <literal>(0,0,0)</literal> gives black
          sand, <literal>(255, 255, 255)</literal> gives white sand.
        </para>
      </listitem>

      <listitem>
        <para>The destroy function:</para>

        <synopsis>
void Destroy ();
        </synopsis>

        <para>
          Destroy the currently running timer without delivering
          the alarm.
        </para>
      </listitem>

      <listitem>
        <para>The remaining time:</para>

        <synopsis>
unsigned long TimeLeft () raises (NotRunning);
        </synopsis>

        <para>
          Return the number of seconds left until the alarm is
          delivered.  The <literal>NotRunning</literal> exception
          is raised if the timer's state is not
          <literal>TSRunning</literal>.
        </para>
      </listitem>

    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>

    <para>
      <xref linkend="factoryref">,
      <xref linkend="alarmref">
    </para>
  </refsect1>

</refentry>
