Class Documentation

Name:Clock
Version:1.0
ID:ID_CLOCK
Status:Incomplete
Category:GUI
Date:August 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1999-2001. All rights reserved.
Short:  This class creates a real-time clock/time display.



Description

The Clock class draws text-based information that always reflects the current time. It is typically used as a digital clock positioned on the desktop so that the user has quick access to the current time.

There are no compulsory settings for creating a Clock object, but in most cases you will want to set the position and its graphical style, which can be altered by accessing the Font field. Here is a DML based example:

   <clock font.colour="#ffffff" x="100" y="5"/>

Like all graphical objects, the Clock should be contained by a drawable area such as a Render object, or you can set the Drawable field to point to the graphics area.

Actions

The Clock class supports the following actions:

Activate  Activates a Clock by drawing it to its associated display.
ClosingTag  Activates a Clock.
Hide  Hides a Clock display.
Show  Shows a Clock display.

Structure

The Clock object consists of the following public fields:

Align  This field allows you to align the Clock's text within its container.
Drawable  This field can be set to define the drawable area for Clock graphics.
Font  Points to a Font that controls the drawing of text for a Clock object.
Format  The display format for a Clock's time can be defined in this field.
XCoord  The horizontal coordinate of a Clock graphic.
YCoord  The vertical coordinate of a Clock graphic.
Field:Align
Short:This field allows you to align the Clock's text within its container.
Type:LONG/FLAGS
Prefix:ALIGN_
Status:Write

If you would like to set an abstract position for the Clock, you can give it an alignment. Note that setting the alignment overrides any settings in related coordinate fields. Valid alignment flags are as follows:

FlagDescription
BOTTOMAligns the Clock to the bottom of the drawable area.
CENTERCenters the Clock on both the vertical and horizontal axis.
LEFTAligns the Clock to the left (horizontal coordinate 0).
MIDDLESynonym for the CENTER flag.
RIGHTAligns the Clock so that the last character is positioned flush against the right.
TOPAligns the Clock to the top (vertical coordinate 0).
HORIZONTALCenters the Clock on the horizontal axis.
VERTICALCenters the Clock on the vertical axis.

 

Field:Drawable
Short:This field can be set to define the drawable area for Clock graphics.
Type:OBJECTID
Status:Read/Write

In most cases, when you create a new Clock it should be contained by a drawable area, such as a Render object. If you do this correctly then the Clock will detect the drawable area and set the Drawable field to the correct object. However, there may be occasions where you want to initialise a Clock object to a non-graphical container. If this is the case then you must set the Drawable field to point to a valid drawable area, such as a Render object.

 

Field:Font
Short:Points to a Font that controls the drawing of text for a Clock object.
Type:struct Font *
Status:Read

To set the face, colour and other attributes of a Clocks's graphics, you need to read the Font field and write your settings to the Font object prior to initialisation. For a list of all the fields that can be set, please refer to the documentation for the Font class.

You are strongly discouraged from writing information to a Font object after the initialistion of a Clock, although you may read information from the Font after initialisation.

 

Field:Format
Short:The display format for a Clock's time can be defined in this field.
Type:STRING
Status:Read/Write

This field is reserved for future use.

 

Field:XCoord
Synonyms:X
Short:The horizontal coordinate of a Clock graphic.
Type:LONG
Status:Read/Write

The horizontal position of a Clock object can be set through this field.

 

Field:YCoord
Synonyms:Y
Short:The vertical coordinate of a Clock graphic.
Type:LONG
Status:Read/Write

The vertical position of a Clock object can be set through this field.