Class Documentation
Clock |
1.0 |
ID_CLOCK |
Stable |
GUI |
February 2003 |
Rocklyte Systems |
Rocklyte Systems (c) 1999-2003. All rights reserved. |
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:
BOTTOM | Aligns the Clock to the bottom of the drawable area. |
CENTER | Centers the Clock on both the vertical and horizontal axis. |
LEFT | Aligns the Clock to the left (horizontal coordinate 0). |
MIDDLE | Synonym for the CENTER flag. |
RIGHT | Aligns the Clock so that the last character is positioned flush against the right. |
TOP | Aligns the Clock to the top (vertical coordinate 0). |
HORIZONTAL | Centers the Clock on the horizontal axis. |
VERTICAL | Centers 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:
h | 24-Hour: 9 |
hh | 24-Hour: 09 |
H | 12-Hour: 9 |
HH | 12-Hour: 09 |
n | Minute: 7 |
nn | Minute: 07 |
s | Second: 42 |
ss | Second: 42 |
d | Day: 3 |
dd | Day: 03 |
D | Day of week: T |
ddd | Day of week: sat |
dddd | Day of week: saturday |
m | Month: 11 |
mm | Month: 11 |
mmm | Month: nov |
mmmm | Month: november |
yy | Year: 03 |
yyyy | Year: 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.
|
|