Time

You may create various applications such as stopwatches, appointment calendars, and action games that need to keep track of time. There are three component types to make this possible. You will use one or more of them depending on what you need:

  1. Alarm provides a real-time alarm timer. Applications that act like alarm clocks will use this component. The timer is usually only accurate to the minute.
  2. TimeDate keeps track of the system time. At any time, you may query a component of this type to find out the current system date or time. You may ask the component to let you know when the system time or date changes. Applications that need to keep track of the current time or date, will use this component.
  3. Timer generates periodic events at short intervals. They are useful when polling. Applications that need a clock with granularity finer than one minute will use this component type.

STRUCT TimeOfDay and STRUCT Date

Structures are types made from other types. The following structures are used to represent dates and times of day:

STRUCT TimeOfDay
DIM hour AS integer
DIM minute AS integer
DIM second AS integer
END STRUCT

STRUCT Date
DIM year AS integer
DIM months AS integer
DIM day AS integer
END STRUCT

The components that use these structures require that they represent valid times/dates. For example, if you tell an Alarm to set its alarm for 25:00, it raises an error.

Utility Actions

Use a TimeDate component for utility actions when dealing with dates. The GetDaysInMonth() action is useful for validating dates. The GetDayOfWeek() action returns a number corresponding to the day of week for a date.

The CALENDAR.BAS sample application shows how you might use these utility actions to complete a simple calendar application.

A Clock with Second Accuracy

A TimeDate component returns the system time whenever you ask; and that time will be accurate to the second. It lets you know when the system time changes, but the most often it does this is once a minute. If you wish to provide a clock that is accurate to the second, you need two components:

For an example of this, see the ACLOCK.BAS sample application. This application is a clock with a second hand, minute hand, and hour hand. The minute and hour hands are re-drawn in handlers of a TimeDate's _timeChanged() event, while the second hand is re-drawn in the Timer's _ring() event handler.

Excerpts from the program are shown here.

sub timedate1_timeChanged(self as timedate)
gadget1!Redraw() REM Redraw hour, minute hand--
REM this is handled by the Gadget's
REM _draw() event handler.
end sub

sub timer1_ring(self as timer)
DIM angle AS float
DIM x1 AS integer
DIM x2 AS integer
DIM y1 AS integer
DIM y2 AS integer

REM Not shown in this code excerpt: we erase
REM the old second hand.

REM Draw the second hand.
SecondsCount = SecondsCount + 1
angle = ( 15- SecondsCount) * 0.104720
x1 = 72 + ( 52 * Cos( angle ))
y1 = 80 - (52 * Sin( angle ))
x2 = 72 + ( 57 * Cos( angle ))
y2 = 80 - (57 * Sin( angle ))

gadget1!DrawLine(x1, y1, x2, y2, BLACK)

end sub