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

  <refnamediv>
    <refname>SandUhr::Timer</refname>
    <refpurpose>CORBA-Schnittstelle für SandUhr-Timer-Objekte</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>ÜBERSICHT</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>BESCHREIBUNG</title>

    <para>
      Die zentrale Komponente von &sanduhr; ist die
      <classname>SandUhr::Timer</classname>-Schnittstelle.  Sie
      repräsentiert das sanduhrförmige Fenster und alle damit
      verbundenen Informationen.
    </para>

    <itemizedlist>
      <listitem>
        <para>Der Zustand des Timers:</para>

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

        <para>
	  Dieser Wert ist <literal>TSPrepare</literal> falls die Uhr
	  noch nicht gestartet ist (z.B. während das Anfangsfenster
	  noch offen ist), <literal>TSRunning</literal> während die
	  Uhr läuft und <literal>TSDone</literal> nachdem die Uhr
	  abgelaufen ist (z.B. während der Alarm gerade ausgeliefert
	  wird).
        </para>
      </listitem>

      <listitem>
        <para>Die Alarmzeit:</para>

        <synopsis>
attribute string TimeSpec;
        </synopsis>

        <para>
	  Das Format dieses Strings wird in der Anleitung im Abschnitt
	  <link linkend="timespec">Die Alarmzeit</link> erklärt.
        </para>
      </listitem>

      <listitem>
        <para>Die Alarmmeldung:</para>

        <synopsis>
attribute string Message;
        </synopsis>

        <para>
	  Dieser Text wird der Alarmmethode zur Zustellung übergeben.
        </para>
      </listitem>

      <listitem>
        <para>Die Alarmmethode:</para>

        <synopsis>
attribute AlarmAction Alarm;
        </synopsis>

        <para>
	  Es stehen mehrere vordefinierte Subklassen von
          <classname>SandUhr::AlarmAction</classname> zur Verfügung.
          Diese werden in <xref linkend="alarmref"> beschrieben.
        </para>
      </listitem>

      <listitem>
        <para>Die Sandfarbe:</para>

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

        <para>
	  Gültige Werte für die Farbkomponenten liegen im Bereich von
	  0 bis 255, beide Werte inklusive.
	  <literal>(0,0,0)</literal> steht für weiß und
	  <literal>(255,255,255)</literal> steht für schwarz.
        </para>
      </listitem>

      <listitem>
        <para>Die Destroy-Funktion:</para>

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

        <para>
	  Dies zerstört den Timer ohne den Alarm auszuliefern.
        </para>
      </listitem>

      <listitem>
        <para>Die verbleibende Zeit:</para>

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

        <para>
	  Dies liefert die verbleibende Zeit, die die Uhr noch läuft,
	  in Sekunden.  Falls der Zustand der Uhr nicht
	  <literal>TSRunning</literal> ist, wird eine
	  <literal>NotRunning</literal>-Ausnahme ausgelöst.
        </para>
      </listitem>

    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>SIEHE AUCH</title>

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

</refentry>
