Class Documentation

Name:Clock
Version:1.0
ID:ID_CLOCK
Status:Stable
Category:GUI
Date:February 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1999-2003. 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 attributes. You should also set the Format of the font if you want something other than a 24 hour clock display. Here is a DML based example:

   <clock format="d Mmm yyyy hh:nn" 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:

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 a 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.
Height  Defines the height of a clock object's drawable region.
Width  Defines the width of a clock's drawable region.
XCoord  Defines the horizontal position of a clock's graphic.
XOffset  Defines the horziontal offset of a clock's graphic.
YCoord  Defines the vertical position of a clock's graphic.
YOffset  Defines the vertical offset of a clock's graphic.
Field:Align
Short:This field allows you to align a 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 clock'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 Font class manual.

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

Set the Format field to define how the time information is printed to the display. Time formatting follows typical convention, as illustrated in the following format table:

StringExample
h24-Hour: 9
hh24-Hour: 09
H12-Hour: 9
HH12-Hour: 09
nMinute: 7
nnMinute: 07
sSecond: 42
ssSecond: 42
dDay: 3
ddDay: 03
DDay of week: T
dddDay of week: sat
ddddDay of week: saturday
mMonth: 11
mmMonth: 11
mmmMonth: nov
mmmmMonth: november
yyYear: 03
yyyyYear: 2003

By default, strings are printed in lower-case. For example, "ddd" prints "sat". If you want to capitalise the characters, use capitals in the string formatting instead of the default lower case. For example "Ddd" prints "Sat" and "DDD" prints "SAT".

Where the interpreter encounters unrecognised characters, it will print them out unaltered. For example "hh:nn:ss" might print "05:34:19" with the colons intact. If you need to include characters such as 'h' or 'd' and want to prevent them from being translated, preceed them with the backslash character. For instance to print "0800 hours", we would use the format "hh00 \hours".


Field:Height
Short:Defines the height of a clock object's drawable region.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A clock's drawing region can be given a fixed or relative height by setting this field to the desired value. To set a relative height, use the FD_PERCENT flag when setting the field.


Field:Width
Short:Defines the width of a clock's drawable region.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A clock's drawing region can be given a fixed or relative width by setting this field to the desired value. To set a relative width, use the FD_PERCENT flag when setting the field.


Field:XCoord
Short:Defines the horizontal position of a clock's graphic.
Type:DOUBLE/PERCENTAGE
Status:Read/Write

This field determines the horizontal position of a clock's graphic from the left of its container. The value can be set as a fixed pixel coordinate, or as a percentage if the FD_PERCENT field is used.


Field:XOffset
Short:Defines the horziontal offset of a clock's graphic.
Type:DOUBLE/PERCENTAGE
Status:Write

You can have a clock's graphic offset against the right of its container by setting this field. A setting of 0 would place the clock at the right edge, while a setting of 10 would place it 10 pixels off from the right edge. Negative values can move the clock outside of the container's boundaries.

This field may also be set as a percentage if the FD_PERCENT flag is used. Use of a percentage will cause the position of the clock to be calculated relative to the width of the container.

Writing to this field will always turn off any previous setting in the XCoord field.


Field:YCoord
Short:Defines the vertical position of a clock's graphic.
Type:DOUBLE/PERCENTAGE
Status:Read/Write

This field determines the vertical position of a clock's graphic from the top of its container. The value can be set as a fixed pixel coordinate, or as a percentage if the FD_PERCENT field is used.


Field:YOffset
Short:Defines the vertical offset of a clock's graphic.
Type:DOUBLE/PERCENTAGE
Status:Write

You can have a clock's graphic offset against the bottom of its container by setting this field. A setting of 0 would place the clock at the bottom edge, while a setting of 10 would place it 10 pixels off from the bottom edge. Negative values can move the clock outside of the container's boundaries.

This field may also be set as a percentage if the FD_PERCENT flag is used. Use of a percentage will cause the position of the clock to be calculated relative to the height of the container.

Writing to this field will always turn off any previous setting in the YCoord field.