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

  <refnamediv>
    <refname>SandUhr::TimerFactory</refname>
    <refpurpose>CORBA interface for the SandUhr factory objects</refpurpose>
  </refnamediv>

  <refsynopsisdiv><title>SYNOPSIS</title>
    <synopsis>
module SandUhr {
  interface TimerFactory {
    exception InvalidTime { };

    AlarmBeep CreateAlarmBeep (in unsigned short Count);
    AlarmSound CreateAlarmSound (in string SoundFile);
    AlarmCommand CreateAlarmCommand (in string CommandString);

    Timer CreateTimer (in string TimeSpec, in string Message)
                                                raises (InvalidTime);

    typedef sequence&lt;Timer&gt; TimerVec;
    readonly attribute TimerVec Timers;

    void ShowControl (in boolean Show);
  };
};
    </synopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      To create Alarm and Timer objects you should use the
      <classname>TimerFactory</classname> interface.  It is
      derived from <classname>GNOME::ObjectFactory</classname>.
      The <classname>TimerFactory</classname> represents the
      control window and all resources associated to it.
      <classname>TimerFactory</classname> objects are registered
      with the GNOME object activation framework OAF.
    </para>

    <itemizedlist>
      <listitem>
        <para>Create alarm actions:</para>
        <synopsis>
AlarmBeep CreateAlarmBeep (in unsigned short Count);
AlarmSound CreateAlarmSound (in string SoundFile);
AlarmCommand CreateAlarmCommand (in string CommandString);
        </synopsis>
        
        <para>
          Create an <classname>AlarmAction</classname> object.
          This may be assigned to a timer's
          <literal>Alarm</literal> attribute.
        </para>
      </listitem>

      <listitem>
        <para>Create timers:</para>
        <synopsis>
Timer CreateTimer (in string TimeSpec, in string Message)
                                                raises (InvalidTime);
        </synopsis>

        <para>
          Create a new timer object.  The alarm time is described
          by <literal>TimeSpec</literal>.  The format of this
          string is explained in the manual section
	  called <link linkend="timespec">the alarm time</link>.  If
          <literal>TimeSpec</literal> is the empty string, open a
          window to query the user for an alarm time.  If
          <literal>TimeSpec</literal> is not a valid alarm time
          specification, the <literal>InvalidTime</literal>
          exception is raised.
        </para>
      </listitem>

      <listitem>
        <para>Access existing timers:</para>
        <synopsis>
typedef sequence&lt;Timer&gt; TimerVec;
readonly attribute TimerVec Timers;
        </synopsis>

        <para>
          This is the list of timers, which are under control of
          the factory object.
        </para>
      </listitem>

      <listitem>
        <para>Display the associated window:</para>
        <synopsis>
void ShowControl (in boolean Show);
        </synopsis>

        <para>
          Show or hide the control window, which is associated
          with the timer factory.
        </para>
      </listitem>

    </itemizedlist>
  </refsect1>

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

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

</refentry>
