HypernovaDesktop Components · docs
Binarymission
WinForms › Clock Control › Clock

Clock

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WinForms.Controls.TimeControls

An analogue clock face for Windows Forms – a live wall clock, a world clock for another time zone, or a fixed time shown as a picture – drawn entirely in code, so it is sharp at any size and display scale.

public class Clock : DoubleBufferedControlBase

Inherits from / implements: DoubleBufferedControlBase

Remarks

What it shows

By default the clock shows the computer's time and redraws once a second. Set TimeZoneId to show the time in another zone, daylight saving included, or StaticTime to stop the hands at a given time – for an appointment, a time stamp or a "next collection" notice. Time says which time is on the face.

The hands are drawn from the time at each redraw and do not sweep: the second hand moves once per RefreshInterval, the minute hand moves on the minute, and the hour hand moves half a degree a minute.

The parts of the face

Size and scale

Keep the control square: the face fills the client area, and the minute marks are drawn only when it is a circle. Widths and thicknesses are in logical pixels (1/96 inch) and are scaled for the display the clock is on. The control's corners are transparent, so the parent's background shows round the face.

Examples

A world clock for the London office beside the local one, with Roman numerals and a glass face.

using System.Drawing;
using System.Windows.Forms;
using Binarymission.WinForms.Controls.TimeControls;

var london = new Clock
{
    Location = new Point(16, 16),
    Size = new Size(200, 200),
    TimeZoneId = "GMT Standard Time",
    TimeRepresentationMode = TimeRepresentationMode.RomanNumeral,
    BackgroundStartColor = Color.MidnightBlue,
    BackgroundEndColor = Color.SteelBlue,
    BorderThickness = 10,
    ShouldDrawGlassEffect = true,
    SecondHandStartColor = Color.OrangeRed,
    SecondHandEndColor = Color.Gold
};

var caption = new Label { Location = new Point(16, 222), AutoSize = true, Text = "London" };
london.DoubleClick += (sender, e) => caption.Text = "London: " + london.Time.ToString("HH:mm");

form.Controls.Add(london);
form.Controls.Add(caption);

Members at a glance

Constructors
ClockInitialises a clock that shows the computer's time, redrawn every second, with a brown face, a black 16-pixel border, white Arabic numerals and a drop shadow.
Properties
BackgroundEndColorGets or sets the colour the face's gradient ends in.
BackgroundStartColorGets or sets the colour the face's gradient starts from.
BorderEndColorGets or sets the colour the border ring's gradient ends in.
BorderGlassEndColorGets or sets the colour the border's glass highlight fades to.
BorderGlassRenderingAlphaComponentGets or sets how strong the border's glass highlight is.
BorderGlassStartColorGets or sets the colour of the border's glass highlight where it is strongest.
BorderStartColorGets or sets the colour the border ring's gradient starts from.
BorderThicknessGets or sets the width of the ring round the face.
DropShadowColorGets or sets the colour of the shadow under the clock, which fades out from it.
GlassEndColorGets or sets the colour the face's glass shine fades to at the bottom.
GlassRenderingAlphaComponentGets or sets how strong the face's glass shine is.
GlassStartColorGets or sets the colour at the top of the face's glass shine.
GradientDrawingAngleForCircularArtefactsGets or sets the direction of the colour gradients on the border, the face and the hub disc.
GradientDrawingAngleForTimeNeedlesGets or sets the direction of the colour gradients on the three hands.
HourHandEndColorGets or sets the colour the hour hand's gradient ends in.
HourHandStartColorGets or sets the colour the hour hand's gradient starts from.
HourNeedleWidthGets or sets how thick the hour hand is.
InnerRingEndColorGets or sets the colour the hub disc's gradient ends in.
InnerRingShapeBoundsGets or sets the size and position of the hub disc at the centre of the face, measured from the centre.
InnerRingStartColorGets or sets the colour the hub disc's gradient starts from.
MaxBorderThicknessGets or sets the largest value BorderThickness accepts.
MinuteHandEndColorGets or sets the colour the minute hand's gradient ends in.
MinuteHandStartColorGets or sets the colour the minute hand's gradient starts from.
MinuteIndicatorVisualGets or sets the text drawn as each minute mark.
MinuteIndicatorVisualColorGets or sets the colour of the minute marks.
MinuteIndicatorVisualFontGets or sets the font the minute marks are drawn in.
MinuteNeedleWidthGets or sets how thick the minute hand is.
NumeralsColorGets or sets the colour of the hour labels.
NumeralsFontGets or sets the font of the hour labels.
RefreshIntervalGets or sets how often the clock redraws itself, which is how often the second hand moves.
SecondHandEndColorGets or sets the colour the second hand's gradient ends in.
SecondHandStartColorGets or sets the colour the second hand's gradient starts from.
SecondNeedleWidthGets or sets how thick the second hand is.
ShouldDrawBorderGets or sets whether the ring round the face is drawn.
ShouldDrawDropShadowForTimeHandlesGets or sets whether each hand casts a shadow onto the face, offset down and to the right.
ShouldDrawGlassEffectGets or sets whether a glass shine is drawn across the upper part of the face.
ShouldDrawGlassEffectOnBorderGets or sets whether a thin glass highlight is drawn on the border ring.
ShouldDrawInnerRingGets or sets whether a hub disc is drawn at the centre of the face, under the hands.
ShouldDrawMinuteIndicatorVisualGets or sets whether a mark is drawn at each minute between the hour labels.
ShouldDrawNumeralsGets or sets whether the twelve hour labels are drawn round the face.
ShouldDropShadowBeEnabledGets or sets whether a soft shadow is drawn under the clock, down and to the right.
StaticTimeGets or sets a fixed time for the hands to show instead of the running time.
TimeGets the time the clock shows: StaticTime when it is set, otherwise the time now in TimeZoneId's zone, or on this computer when that is empty.
TimeRepresentationModeGets or sets how the twelve hour labels are written: numbers, Roman numerals or labels of your own.
TimeZoneIdGets or sets the Windows time zone whose time the clock shows, such as "Eastern Standard Time" or "Tokyo Standard Time".
Methods
DisposeStops the redraw timer and releases it and the label brushes.
OnPaintDraws the clock: shadow, border, face, labels, hub and hands, for Time.
RestartReplaces the timer that redraws the clock with a new one, so the next redraw is one RefreshInterval from now.

Constructors

Clock

public Clock()

Initialises a clock that shows the computer's time, redrawn every second, with a brown face, a black 16-pixel border, white Arabic numerals and a drop shadow.

Remarks

The redraw timer starts here, so the clock is live as soon as it is on a form.

Properties

BackgroundEndColor

public Color BackgroundEndColor

Gets or sets the colour the face's gradient ends in.

Value
The default is Color.RosyBrown.
See also

BackgroundStartColor

public Color BackgroundStartColor

Gets or sets the colour the face's gradient starts from.

Value
The default is Color.Brown.
Remarks

The face blends from this colour to BackgroundEndColor at GradientDrawingAngleForCircularArtefacts. Set both to one colour for a plain face.

BorderEndColor

public Color BorderEndColor

Gets or sets the colour the border ring's gradient ends in.

Value
The default is Color.Black.

BorderGlassEndColor

public Color BorderGlassEndColor

Gets or sets the colour the border's glass highlight fades to.

Value
The default is Color.Transparent.

BorderGlassRenderingAlphaComponent

public int BorderGlassRenderingAlphaComponent

Gets or sets how strong the border's glass highlight is.

Value
The opacity of BorderGlassStartColor, from 28 (faint) to 128 (strong); a value set outside that range is replaced by 60. The default is 60.
See also

BorderGlassStartColor

public Color BorderGlassStartColor

Gets or sets the colour of the border's glass highlight where it is strongest.

Value
The default is Color.White. Its alpha is replaced by BorderGlassRenderingAlphaComponent.

BorderStartColor

public Color BorderStartColor

Gets or sets the colour the border ring's gradient starts from.

Value
The default is Color.Black.
Remarks

The ring blends to BorderEndColor at GradientDrawingAngleForCircularArtefacts; two shades of one metal colour give a bezel.

BorderThickness

public int BorderThickness

Gets or sets the width of the ring round the face.

Value
In logical pixels. The default is 16. A value above MaxBorderThickness is reduced to it.
Remarks

The face, numerals and hands are fitted inside the ring, so a thicker border makes them smaller rather than covering them. Has no effect while ShouldDrawBorder is false.

DropShadowColor

public Color DropShadowColor

Gets or sets the colour of the shadow under the clock, which fades out from it.

Value
The default is Color.Gray. Used while ShouldDropShadowBeEnabled is true.

GlassEndColor

public Color GlassEndColor

Gets or sets the colour the face's glass shine fades to at the bottom.

Value
The default is Color.Transparent.

GlassRenderingAlphaComponent

public int GlassRenderingAlphaComponent

Gets or sets how strong the face's glass shine is.

Value
The opacity of GlassStartColor, from 28 (faint) to 128 (strong). The default is 72. A value outside that range is replaced by 60.

GlassStartColor

public Color GlassStartColor

Gets or sets the colour at the top of the face's glass shine.

Value
The default is Color.White. Its alpha is replaced by GlassRenderingAlphaComponent.

GradientDrawingAngleForCircularArtefacts

public float GradientDrawingAngleForCircularArtefacts

Gets or sets the direction of the colour gradients on the border, the face and the hub disc.

Value
In degrees, clockwise from left to right. The default is 45: from the top left to the bottom right.

GradientDrawingAngleForTimeNeedles

public float GradientDrawingAngleForTimeNeedles

Gets or sets the direction of the colour gradients on the three hands.

Value
In degrees, clockwise from left to right. The default is 90: start colour at the top, end colour at the bottom.

HourHandEndColor

public Color HourHandEndColor

Gets or sets the colour the hour hand's gradient ends in.

Value
The default is Color.Black.
See also

HourHandStartColor

public Color HourHandStartColor

Gets or sets the colour the hour hand's gradient starts from.

Value
The default is Color.Black.
Remarks

Each hand blends between its start and end colours at GradientDrawingAngleForTimeNeedles, across the whole dial – so the colour a hand shows depends on where it points.

HourNeedleWidth

public int HourNeedleWidth

Gets or sets how thick the hour hand is.

Value
In logical pixels. The default is 9.
Remarks

The hour and minute hands have rounded ends; the second hand has square ends. The lengths are fixed fractions of the dial's radius – about a half, seven tenths and four fifths for the hour, minute and second hands – so a clock of any size, on any display, has the same proportions.

InnerRingEndColor

public Color InnerRingEndColor

Gets or sets the colour the hub disc's gradient ends in.

Value
The default is Color.Black.

InnerRingShapeBounds

public Rectangle InnerRingShapeBounds

Gets or sets the size and position of the hub disc at the centre of the face, measured from the centre.

Value
In logical pixels, with (0, 0) at the centre of the face. The default is (-25, -25, 50, 50): a disc 50 pixels across, centred.
Remarks

Drawn only while ShouldDrawInnerRing is true, under the hands.

InnerRingStartColor

public Color InnerRingStartColor

Gets or sets the colour the hub disc's gradient starts from.

Value
The default is Color.Black.
See also

MaxBorderThickness

public int MaxBorderThickness

Gets or sets the largest value BorderThickness accepts.

Value
In logical pixels, from 0 to 100. The default is 32. A value outside that range is replaced by 32.
Remarks

The limit is applied when BorderThickness is set: lowering it afterwards does not thin a border that is already thicker.

MinuteHandEndColor

public Color MinuteHandEndColor

Gets or sets the colour the minute hand's gradient ends in.

Value
The default is Color.Black.

MinuteHandStartColor

public Color MinuteHandStartColor

Gets or sets the colour the minute hand's gradient starts from.

Value
The default is Color.Black.
See also

MinuteIndicatorVisual

public string MinuteIndicatorVisual

Gets or sets the text drawn as each minute mark.

Value
Usually one character, such as ".", "·" or "|". The default is "."; null or empty also draws ".".
See also

MinuteIndicatorVisualColor

public Color MinuteIndicatorVisualColor

Gets or sets the colour of the minute marks.

Value
The default is Color.White.

MinuteIndicatorVisualFont

public Font MinuteIndicatorVisualFont

Gets or sets the font the minute marks are drawn in.

Value
The default is null, which uses the control's Control.Font. A larger font gives a larger mark.

MinuteNeedleWidth

public int MinuteNeedleWidth

Gets or sets how thick the minute hand is.

Value
In logical pixels. The default is 6.
See also

NumeralsColor

public Color NumeralsColor

Gets or sets the colour of the hour labels.

Value
The default is Color.White.

NumeralsFont

public Font NumeralsFont

Gets or sets the font of the hour labels.

Value
The default is null, which draws them in the control's Control.Font.
See also

RefreshInterval

public int RefreshInterval

Gets or sets how often the clock redraws itself, which is how often the second hand moves.

Value
In milliseconds. The default is 1000, one second.
Remarks

Setting it restarts the timer. The value must be at least 1: a smaller one throws ArgumentOutOfRangeException from the timer. A clock with a StaticTime, or one with no second hand to show, can use a longer interval to save work.

SecondHandEndColor

public Color SecondHandEndColor

Gets or sets the colour the second hand's gradient ends in.

Value
The default is Color.DarkRed.

SecondHandStartColor

public Color SecondHandStartColor

Gets or sets the colour the second hand's gradient starts from.

Value
The default is Color.DarkRed.
See also

SecondNeedleWidth

public int SecondNeedleWidth

Gets or sets how thick the second hand is.

Value
In logical pixels. The default is 2.
See also

ShouldDrawBorder

public bool ShouldDrawBorder

Gets or sets whether the ring round the face is drawn.

Value
true to draw it. The default is true.
See also

ShouldDrawDropShadowForTimeHandles

public bool ShouldDrawDropShadowForTimeHandles

Gets or sets whether each hand casts a shadow onto the face, offset down and to the right.

Value
true to draw the hands' shadows. The default is false.
See also

ShouldDrawGlassEffect

public bool ShouldDrawGlassEffect

Gets or sets whether a glass shine is drawn across the upper part of the face.

Value
true to draw it. The default is false.
Remarks

The shine fades from GlassStartColor, at GlassRenderingAlphaComponent opacity, down to GlassEndColor.

ShouldDrawGlassEffectOnBorder

public bool ShouldDrawGlassEffectOnBorder

Gets or sets whether a thin glass highlight is drawn on the border ring.

Value
true to draw it. The default is false.
Remarks

Drawn only on a border more than 3 logical pixels thick, in BorderGlassStartColor at BorderGlassRenderingAlphaComponent opacity – which is 0 until it is set, so set that too.

ShouldDrawInnerRing

public bool ShouldDrawInnerRing

Gets or sets whether a hub disc is drawn at the centre of the face, under the hands.

Value
true to draw it. The default is false.
See also

ShouldDrawMinuteIndicatorVisual

public bool ShouldDrawMinuteIndicatorVisual

Gets or sets whether a mark is drawn at each minute between the hour labels.

Value
true to draw the marks. The default is true.
Remarks

The marks are drawn only when the control is square, so the face is a circle. While ShouldDrawNumerals is set the marks at the hours are left out, where the labels are.

See also

ShouldDrawNumerals

public bool ShouldDrawNumerals

Gets or sets whether the twelve hour labels are drawn round the face.

Value
true to draw them. The default is true.
Remarks

Turning it off also hides the minute marks. TimeRepresentationMode says what the labels are.

ShouldDropShadowBeEnabled

public bool ShouldDropShadowBeEnabled

Gets or sets whether a soft shadow is drawn under the clock, down and to the right.

Value
true to draw the shadow. The default is true.
Remarks

The shadow needs room, so while it is on the face is drawn 20 pixels (at 100% scaling) inside each edge of the control and is smaller by that much.

See also

StaticTime

public DateTime? StaticTime

Gets or sets a fixed time for the hands to show instead of the running time.

Value
The time to show, of which only the hour, minute and second are used. The default is null: the clock runs.
Remarks

While it is set the clock does not follow the time, whatever TimeZoneId says. Set it back to null to start the clock again.

Example
// Show when the order was dispatched.
dispatchClock.StaticTime = order.DispatchedAt;

Time

public DateTime Time

Gets the time the clock shows: StaticTime when it is set, otherwise the time now in TimeZoneId's zone, or on this computer when that is empty.

Value
The time on the face, read afresh on each call.
See also

TimeRepresentationMode

public TimeRepresentationMode TimeRepresentationMode

Gets or sets how the twelve hour labels are written: numbers, Roman numerals or labels of your own.

Value
The default is TimeRepresentationMode.Number.
See also
  • HourIndicatorLookupDictionary

TimeZoneId

public string TimeZoneId

Gets or sets the Windows time zone whose time the clock shows, such as "Eastern Standard Time" or "Tokyo Standard Time".

Value
A time zone id as Id gives it. The default is null: the computer's own time zone. An empty string also means the computer's own.
Default
null
Remarks

The clock keeps running in that zone, daylight saving included, which is what a row of world clocks needs. StaticTime still wins while it is set.

An id the computer does not know throws TimeZoneNotFoundException, so a mistyped one is seen at once rather than quietly showing local time. GetSystemTimeZones lists the ids the computer has.

Example
newYorkClock.TimeZoneId = "Eastern Standard Time";
tokyoClock.TimeZoneId = TimeZoneInfo.FindSystemTimeZoneById("Tokyo Standard Time").Id;

Methods

Dispose

protected override void Dispose(bool disposing)

Stops the redraw timer and releases it and the label brushes.

Parameters
disposing
true when called from Dispose().

OnPaint

protected override void OnPaint(PaintEventArgs e)

Draws the clock: shadow, border, face, labels, hub and hands, for Time.

Parameters
e
The surface and clip rectangle to paint.
Remarks

The base class's handling runs first, so Control.Paint handlers draw under the clock.

Restart

public void Restart()

Replaces the timer that redraws the clock with a new one, so the next redraw is one RefreshInterval from now.

Remarks

The control starts its timer itself and setting RefreshInterval restarts it, so this is needed only to bring the redraws into step with something else – the start of a second, say.