Developers' Reference

The Clock control was written using the ActiveX Template Library in Visual C++. It is designed for professional use under Windows NT (Service Pack 3 required), but will happily run in a home environment under Windows 95/98.

It has a Properties Dialog, and supports many Events, Methods and Properties including most of the standard ATL ones.

This page documents version 1.0.2 of the control.

Properties Dialog

A number of properties can be set using the control's Properties Dialog, but not all of them. For complete management of the control's appearence, use your programming language to set the Properties, to use the Methods, and respond to various Events.

The property sheet dialogue supports the standard Font and Colour pages, as well as some to manage the clock's Hands, Face, Miscellaneous details, and to set the default Time.

Hands

image: screenshot

If Hidden is selected, the hand is not drawn. If Decorative, an border is drawn around the hand in the control's fill colour, to help it stand out against the background. The Size and Thickness determine the length and width of the hand respectively.

Return to the Properties Dialog, the Developer's Reference, or the top of this document.

Clock Face

image: screenshot

You can control whether each type of graduation is visible by selecting, or otherwise, the Drawn check box. The Size and Thickness determine the length of the graduation, and its width, respectively. You can also control the appearence of the clock's outer circle.

Return to the Properties Dialog, the Developer's Reference, or the top of this document.

Time

image: screenshot

This rather simple page allows you to set the default time.

Return to the Properties Dialog, the Developer's Reference, or the top of this document.

Miscellaneous

image: screenshot

You can determine whether to hide or show the AM/PM switch, and whether to display it as text or as a symbol. If you decide the show a small circle in the Centre, you can also control its size.

The Winder is drawn, when so desired, on the right hand side of the clock face. The Time can be shown as text on the clock face (you can control the format of that text using the DigitalFormat property). The Legend (equivalent to the standard window's Caption property) text is shown here using Cyberspace Service's Ltd. home page.

The Gravity setting determines how close the mouse has to be to a hot spot - such as the end of a hand - for the user to be able to manipulate it.

Return to the Properties Dialog, the Developer's Reference, r the top of this document.

Events

Introduction

Standard events supported by this control are LButtonDown, LButtonUp, MButtonDown, MButtonUp, MouseMove, RButtonDown and RButtonUp.

The control also supports the following additional events:

Change - indicates the time has been changed;
NewDay - indicates that the time has been changed past midnight;
Update - indicates the time is being changed;

See Methods, Properties, Properties Dialog, return to Developer's Reference, or the top of this document.

Change Event

The Change event occurs when the time is changed in the control.



void Change([in]int nHour, [in] int nMinute, [in] int nSecond);

The parameters reflect the new time set in the control for a 24-hour clock.

This event does not fire until the user completes a change. For example, if (s)he changes the time by moving the clock's hands, the event fires when the user releases the mouse button.

See the Update Event, return to Events, Developer's Reference, or the top of this document.

NewDay Event

The NewDay event occurs when the user moves the clock hands past midnight.



void NewDay([in]int bTomorrow);

If bTomorrow is zero, then the user is going back to the previous day, otherwise the user is going forward to the next day.

This event does not occur when the user drags the hour hand across midnight. It fires if the user uses the winder or the arrow keys so that the hour hand passes midnight.

Return to Events, Developer's Reference, or the top of this document.

Update Event

The Update event occurs when the time is being changed in the control.



void Update([in]int nHour, [in] int nMinute, [in] int nSecond);

The parameters reflect the new time set in the control for a 24-hour clock.

This event fires as the user carries out a change in the control. For example, if (s)he changes the time by moving the clock's hands, the event fires every time the hand is moved.

See the Change Event, return to Events, Developer's Reference, or the top of this document.

Methods

The following methods are supported by the component:

About displays an about dialog;
CanPaste informs whether the control can paste the content of the clipboard;
CanUndo informs whether the control can complete the Undo method;
Copy copies the control's time to the clipboard;
GetVersion returns the control's version;
Paste sets the control's time from the clipboard;
SetCurrentTime sets the control to the computer's current time;
SetTime sets the control to a specific time;
Undo resets the control's time to the previous value.

See Events, Properties, Properties Dialog, return to Developer's Reference, or the top of this document.

About Method

The About method dispays a copyright dialog.



HRESULT About ();

Return to Methods, Developer's Reference, or the top of this document.

CanPaste Method

The CanPaste method indicates whether the control can paste the current content of the clipboard.



HRESULT CanPaste([out, retval] int *bCanPaste);

The only parameter is a pointer to an integer, which is set to zero if the control cannot paste from the clipboard, and is set to a non-zero value if it can. The control expects the time to be a string in the format produced by the Copy method.

See the Copy and Paste methods, return to Methods, Developer's Reference, or the top of this document.

CanUndo Method

The CanUndo method indicates whether the control can carry out an Undo command.



HRESULT CanUndo([out, retval] int *bCanUndo);

The only parameter is a pointer to an integer, which is set to zero if the control cannot carry out an undo command, and is set to a non-zero value if it can.

See the Undo method, return to Methods, Developer's Reference, or the top of this document.

Copy Method

The Copy method copies the current time to the clipboard.



HRESULT Copy();

The control puts a string on the clipboard, in the format of three numbers (hour, minute, second) separated by colons.

See the CanPaste and Paste methods, return to Methods, Developer's Reference, or the top of this document.

GetVersion Method

The GetVersion returns the control's version.



HRESULT GetVersion([out] int* pMajor, [out] int* pMinor, [out] int* pRelease, [out] int* pBuild);

The control assigns the variable referenced by each pointer with the corresponding version number.

See Methods, Developer's Reference, or the top of this document.

Paste Method

The Paste pastes the current content of the clipboard into the control.



HRESULT Paste ();

The control expects the time to be a string in the same format as that produced by the Copy method.

See the Copy and canPaste methods, return to Methods, Developer's Reference, or the top of this document.

SetCurrentTime Method

The SetCurrentTime method sets the control to the computer's current time.



HRESULT SetCurrentTime ();

See the SetTime method, the Time property, return to Methods, Developer's Reference, or the top of this document.

SetTime Method

The SetTime method sets the control to the specified time.



HRESULT SetTime([in] int nHour, [in] int nMinute, [in] int nSecond);

Set the three parameters to appropriate values for the time you wish to assign, recalling if necessary to use the 24-hour clock to set the hour.

See the SetCurrentTime method, the Time property, return to Methods, Developer's Reference, or the top of this document.

Undo Method

The Undo method undoes the last change made to the control.



HRESULT Undo();

If the control has been changed, this method reverts to the previous value. You can determine whether the control can complete this method by using the CanUndo method.

See the CanUndo method, return to Methods, Developer's Reference, or the top of this document.

Properties

The standard properties supported by this control are Appearance, AutoSize, BackColor, BackStyle, BorderColor, BorderStyle, BorderVisible, BorderWidth, Caption, DrawMode, DrawStyle, DrawWidth, Enabled, FillColor, FillStyle, Font, ForeColor, MouseIcon, MousePointer, TabStop, Text and Valid.

This control's additional properties are:

Colour - sets the colour of individual components in the clock face;
DigitalFormat - sets the format of the time when displayed as a string;
Drawn - determines which components of the clock are shown;
GravityWellX and GravityWellY determine how close the mouse has to be to a particular part of the clock for the user to be able to drag it;
LegendIPAddress - changes the control's Internet link address;
Size sets the size of particular components on the clock face;
Thickness sets the thickness of certain clock face components;
Time sets the time shown by the control;

See Events, Methods, Properties Dialog, return to Developer's Reference, or the top of this document.

Colour Property

The Colour property controls the colour of particular parts of the clock face.



HRESULT Colour ([in] int nPart, [in] int nState, [out, retval] OLE_COLOR *pVal);


HRESULT Colour ([in] int nPart, [in] int nState, [in] OLE_COLOR newVal);

nPart may be any of the following values:

1 the hour hand;
2 the minute hand;
3 the second hand;
4 the up part of the winder;
5 the down part of the winder;
6 the AM/PM symbol or text;
7 the clock face's outer circle;
8 quarter-hour graduations;
9 five-minute graduations
10 single-minute graduations;
11 the arm of the winder;
12 the centre of the clock face;
13 the caption;
14 the time text;
16 the background (equivalent to the standard FillColor property).

nState may be any of the following values:

0 gets or sets the colour control is neither selected nor disabled;
1 gets or sets the colour when the control is selected;
2 gets or sets the colour when the control is disabled;
3 sets normal, selected and disabled colours.

pVal is a pointer to a variable to receive the part's current colour.

newVal is the part's new current colour.

See the Drawn, Size, or Thickness properties, return to Properties, Developer's Reference, or the top of this document.

DigitalFormat Property

The DigitalFormat property determines exactly how the time should be prepared when it is displayed as text.



HRESULT DigitalFormat([out, retval] BSTR *pVal);


HRESULT DigitalFormat([in] BSTR newVal);

pVal is a pointer to a variable to receive the control's current format.

newVal is the control's new format.

The DigitalFormat string uses the format specification associated with the standard C function strftime. The format argument consists of one or more codes; as in printf, the formatting codes are preceded by a percent sign (%). Characters that do not begin with % are copied unchanged. The effect of using any of the strftime date specifiers is undefined. The time formatting codes are:

%H Hour in 24-hour format (00 – 23)
%I Hour in 12-hour format (01 – 12)
%M Minute as decimal number (00 – 59)
%p Current locale's A.M./P.M. indicator for 12-hour clock
%S Second as decimal number (00 – 59)
%X Time representation for current locale (the default)
%z, %Z Time-zone name or abbreviation; no characters if time zone is unknown
%% Percent sign

As in the printf function, the # flag may prefix any formatting code. In that case, the meaning of the format code is changed as follows:

%#p, %#X, %#z, %#% : # flag is ignored.
%#H, %#I, %#M, %#S : Remove leading zeros (if any).

See the Drawn property, return to Properties, Developer's Reference, or the top of this document.

Drawn Property

The Drawn property controls whether particular parts of the clock face are shown.



HRESULT Drawn([in] int nPart, [out, retval] short *pVal);


HRESULT Drawn([in] int nPart, [in] short newVal);

nPart may be any of the following values:

1 the hour hand;
2 the minute hand;
3 the second hand;
4 the up part of the winder;
5 the down part of the winder;
6 the AM/PM symbol or text;
7 the clock face's outer circle;
8 quarter-hour graduations;
9 five-minute graduations
10 single-minute graduations;
11 the arm of the winder;
12 the centre of the clock face;
13 the caption;
14 the time text;
15 the focus ring;

pVal is a pointer to a variable to receive the part's status.

newVal is the part's new drawn status.

The number referred to by pVal, and set by newVal, can have the following values:

0 the part is not drawn;
1 the part is drawn in a normal manner;
2 the part is drawn in an alternative manner, if applicable.

The following parts have different appearences when drawn in a normal or an alternative manner:

1 the hour hand is normally drawn in a plain style, but alternatively, can be drawn with a shadow;
2 the minute hand is normally drawn in a plain style, but alternatively, can be drawn with a shadow;
3 the second hand is normally drawn in a plain style, but alternatively, can be drawn with a shadow;
6 AM/PM is normally drawn as text, but alternatively, can be drawn as a symbol;

See the Colour, DigitalFormat, Size, or Thickness properties, return to Properties, Developer's Reference, or the top of this document.

GravityWell Properties

The GravityWellX and GravityWellY properties control how close the mouse has to be to a part of the control for the user to be able to start dragging it.




HRESULT GravityWellX([out, retval] long *pVal);


HRESULT GravityWellX([in] long newVal);


HRESULT GravityWellY([out, retval] long *pVal);


HRESULT GravityWellY([in] long newVal);

pVal is a pointer to a variable to receive the distance in pixels, from the centre of a part.

newVal is the new distance in pixels, from the centre of a part.

Rreturn to Properties, Developer's Reference, or the top of this document.

LegendIPAddress Property

The LegendIPAddress property sets control's Internet link address.



HRESULT LegendIPAddress([out, retval] BSTR *pVal);


HRESULT LegendIPAddress([in] BSTR newVal);

pVal is a pointer to a variable to receive the current IP Address, from the centre of a part.

newVal is the new current IP Address, from the centre of a part.

The text displayed on the clock for the legend defaults to www.cyberspace.co.uk, but this can be changed by setting the standard Caption property.

Rreturn to Properties, Developer's Reference, or the top of this document.

Size Property

The Size property controls the relative size of particular parts of the clock face.



HRESULT Size([in] int nPart, [out, retval] double *pVal);


HRESULT Size([in] int nPart, [in] double newVal);

nPart may be any of the following values:

1 the hour hand;
2 the minute hand;
3 the second hand;
7 the clock face's outer circle;
8 quarter-hour graduations;
9 five-minute graduations
10 single-minute graduations;
12 the centre of the clock face;
15 the focus ring;

pVal is a pointer to a variable to receive the part's relative size.

newVal is the part's new relative size. This should be a value between 0.0 (not drawn) and 1.0 (the full breadth of the control).

See the Colour, Drawn, or Thickness properties, return to Properties, Developer's Reference, or the top of this document.

Thickness Property

The Thickness property controls the width, in pixels, of particular parts of the clock face.



HRESULT Thickness([in] int nPart, [out, retval] short *pVal);


HRESULT Thickness([in] int nPart, [in] short newVal);

nPart may be any of the following values:

1 the hour hand;
2 the minute hand;
3 the second hand;
4 the up part of the winder;
5 the down part of the winder;
6 the AM/PM symbol;
7 the clock face's outer circle;
8 quarter-hour graduations;
9 five-minute graduations
10 single-minute graduations;
11 the arm of the winder;
12 the centre of the clock face;
15 the focus ring;

pVal is a pointer to a variable to receive the part's thickness, in pixels.

newVal is the part's new thickness, in pixels.

See the Colour, Drawn, or Size properties, return to Properties, Developer's Reference, or the top of this document.

Time Property

The Time property sets the control to the specified time.



HRESULT Time([out, retval] DATE *pVal);


HRESULT Time([in] DATE newVal);

pVal is a pointer to a variable to receive the control's current time.

newVal is the control's new time.

See the SetTime, SetCurrentTime methods, return to Properties, Developer's Reference, or the top of this document.

Index

About Method
CanPaste Method
CanUnd Method
Change Event
Colour Property
Copy Method
DigitalFormat Property
Download Questionnaire
Drawn Property
Events
Graduations Property Page
GetVersion Method
GravityWell Properties
Hands Property Page
Introduction
LegendIPAddress Property
Methods
Miscellaneous Property Page
NewDay Event
Paste Method
Properties
Properties Dialogue
Questionnaire
Registration
Requirements
SetCurrentTime Method
SetTime Method
Size Property
Thickness Property
Time Property
Time Property Page
Top
Undo Method
Update Event
User Interface