This directory contains the CORBA IDL file for SandUhr


In the following I will describe the semantics for
the various attributes and methods of the SandUhr
CORBA interface.  The directory remote/ of the SandUhr
source code distribution contains example code, which
illustrates the use of this interface.


The central part of SandUhr is the 'Timer' interface.
It represents the sand-glass-shaped window and every piece
of information associated to it.

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

	The state of the timer.  This is 'TSPrepare' if the timer is
	not yet running (e.g. while the initial setup window is
	showing), 'TSRunning' during normal operation, and 'TSDone'
	after the timer elapsed (i.e. while the alarm is delivered).

* attribute string TimeSpec;

	The alarm time as a time specification string.  The format of
	this string is explained in the SandUhr Manual.

* attribute string Message;

	The alarm message.  This is passed to the alarm action
	for delivery.

* attribute AlarmAction Alarm;

	The alarm action.  There are several subclasses of AlarmAction
	available.  These are described below.

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

	The fill color of the sand glass.  The Red, Green, and Blue
	values may lay in the range 0 to 255 inclusive.

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

	These fields describe the interaction with the window manager.
	They control the corresponding GNOME window manager hints.

* void Destroy ();

	Destroy the currently running timer without delivering the
	alarm.

* unsigned long TimeLeft () raises (NotRunning);

	Return the number of seconds left until the alarm is
	delivered.  The NotRunning exception is raised if
	the timer's state is not TSRunning.


The Alarm action is described by Objects of type AlarmAction.

* readonly attribute boolean NeedsPopup;

	If this is true, the Timer will display the alarm message in a
	popup window in addition to the Deliver() call.

* void Attach (in Timer T);

	This is called by a Timer object, before it accesses the
	AlarmAction object in any other way.  It may be used to
	implement reference counting for alarm actions.

* void Detach (in Timer T);

	This is called by the Timer object when the Timer is no longer
	interested in this AlarmAction.  This occurs after the Deliver()
	call or after the AlarmAction is replaced with another one.
	This method may be used to implement reference counting for
	alarm actions.

* void Deliver (in string TimeSpec, in string Message);

	This method is called by the timer to actually deliver the
	alarm.  The function is responsible for delivering the alarm
	to the user.  If the delivery fails it must raise the
	DeliveryFailed exception.  Note that the TimeSpec contains a
	normalized form of the alarm time, not the originial time
	specification.


SandUhr implements three subclasses of AlarmAction:

* interface AlarmBeep: AlarmAction {
    attribute unsigned short Count;
  };

	Ring the keybord bell repeatedly.  Count is the number of beeps.
	It is decreased while the alarm is delivered until the value
	reaches 0.

* interface AlarmSound: AlarmAction {
    attribute string SoundFile;
  };

	Playes a sound file via the enlightened sound daemon esd.
	The file name 'SoundFile' must denote a file on the host
	the AlarmSound object lives on.

* interface AlarmCommand: AlarmAction {
    attribute string CommandString;
  };

	Execute an arbitrary shell command.  This command is executed
	via 'gnome_execute_shell' on the host the AlarmCommand object
	lives on.


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

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

	Create an AlarmAction object.  This may be assigned to
	a timer's Alarm attribute.

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

	Create a new Timer object.  The alarm time is described by
	TimeSpec.  The format of this string is explained in the
	SandUhr Manual.  If TimeSpec is the empty string, open a
	window to query the user for an alarm time.  If TimeSpec is not
	a valid alarm time specification, the InvalidTime exception is
	raised.

* typedef sequence<Timer> TimerVec;
  readonly attribute TimerVec Timers;

	This is the list of timers, which are under control of the
	factory object.

* void ShowControl (in boolean Show);

	Show or hide the Control window, which is associated with the
	timer factory.
