Field that manages the display and editing of a time value. More...

#include <TimeField.h>

Inheritance diagram for TimeField:

Public Member Functions
	TimeField (const String &label)
	Constructs a new time field with a specific label.
	TimeField (Form &form, const String &label, int maxHours, bool readOnly)
	Constructs a new boolean field with a specific label and attaches it to a form.
int	dispatch (int event)
	Dispatches event via this field.
void	enterField (bool reverse)
	Enters the field due to form navigation.
void	exitField ()
	Exits the field due to form navigation.
unsigned long	value () const
	Returns the current value of this time field, in seconds.
void	setValue (unsigned long value)
	Sets the value of this time field, in seconds.
int	maxHours () const
	Returns the maximum number of hours before the field wraps around.
void	setMaxHours (int maxHours)
	Sets the maximum number of hours before the field wraps around to maxHours.
bool	readOnly () const
	Returns TIMEFIELD_READ_ONLY (true) or TIMEFIELD_READ_WRITE (false).
void	setReadOnly (bool value)
	Sets the read-only state of this field to value.

Detailed Description

Field that manages the display and editing of a time value.

TimeField is suitable for displaying wall clock time in 24-hour format, or for displaying timeouts and durations in seconds. Times are specified in seconds as an unsigned long value. They are displayed as HH:MM:SS, for hours, minutes, and seconds.

The time field can be either read-only or read-write. When read-write, the Up, Down, Left, and Right buttons can be used to modify the hour, minute, and second components of the time value.

The following example displays the number of hours, minutes, and seconds since the device was reset, wrapping around after 24 hours:

 Form mainForm(lcd);
 TimeField timeField(mainForm, "Time since reset", 24, TIMEFIELD_READ_ONLY);

 void loop() {
     timeField.setValue(millis() / 1000);
     mainForm.dispatch(lcd.getButton());
 }

A read-write field can be used to ask the user for the duration of an application count-down timer:

 TimeField durationField(mainForm, "Timer duration", 24, TIMEFIELD_READ_WRITE);

See also:: Field

Definition at line 31 of file TimeField.h.

Constructor & Destructor Documentation

TimeField::TimeField ( const String & label ) [explicit]

Constructs a new time field with a specific label.

The field is initially not associated with a Form. The field can be added to a form later using Form::addField().

Initially value() is 0, maxHours() is 24, and isReadOnly() is TIMEFIELD_READ_WRITE.

See also:: Form::addField()

Definition at line 82 of file TimeField.cpp.

TimeField::TimeField	(	Form &	form,
		const String &	label,
		int	maxHours,
		bool	readOnly
	)

Constructs a new boolean field with a specific label and attaches it to a form.

The initial value() of the field will be 0. The value() will be limited to be less than maxHours * 60 * 60 seconds.

If readOnly is TIMEFIELD_READ_ONLY, then the field will display times but not allow them to be modified by the user. If readOnly is TIMEFIELD_READ_WRITE, then the field will modifiable by the user.

See also:: value()

Definition at line 105 of file TimeField.cpp.

Member Function Documentation

int TimeField::dispatch ( int event ) [virtual]

Dispatches event via this field.

The event is usually obtained from LCD::getButton().

Returns zero if the event has been handled and no further action is required.

Returns FORM_CHANGED if the event has changed the value of this field in a manner that may require the application to take further action based on the new field value.

Returns -1 if the event is not handled by this field, and should be handled by the Form itself (particularly for Left and Right buttons). The default implementation returns -1 for all events.

See also:: Form::dispatch(), LCD::getButton()

Reimplemented from Field.

Definition at line 115 of file TimeField.cpp.

void TimeField::enterField ( bool reverse ) [virtual]

Enters the field due to form navigation.

This function is typically called when the user presses Left and Right buttons to navigate to the field. If reverse is true, then navigation was due to the Left button being pressed.

This function can assume that the display has been cleared and the cursor is positioned at (0, 0).

The default implementation prints the label().

See also:: exitField()

Reimplemented from Field.

Definition at line 193 of file TimeField.cpp.

void TimeField::exitField ( ) [virtual]

Exits the field due to form navigation.

This function is typically called when the user presses Left and Right buttons to navigate from the field.

See also:: enterField()

Reimplemented from Field.

Definition at line 205 of file TimeField.cpp.

int TimeField::maxHours ( ) const [inline]

Returns the maximum number of hours before the field wraps around.

See also:: setMaxHours(), setValue()

Definition at line 44 of file TimeField.h.

bool TimeField::readOnly ( ) const [inline]

Returns TIMEFIELD_READ_ONLY (true) or TIMEFIELD_READ_WRITE (false).

See also:: setReadOnly()

Definition at line 47 of file TimeField.h.

void TimeField::setMaxHours ( int maxHours ) [inline]

Sets the maximum number of hours before the field wraps around to maxHours.

See also:: maxHours(), setValue()

Definition at line 45 of file TimeField.h.

void TimeField::setReadOnly ( bool value )

Sets the read-only state of this field to value.

The value should be one of TIMEFIELD_READ_ONLY (true) or TIMEFIELD_READ_WRITE (false). Use of the named constants is recommended.

See also:: readOnly()

Definition at line 268 of file TimeField.cpp.

void TimeField::setValue ( unsigned long value )

Sets the value of this time field, in seconds.

If value is greater than or equal to maxHours() * 60 * 60, then it will be wrapped around to fall within the valid range.

See also:: value(), maxHours()

Definition at line 227 of file TimeField.cpp.

unsigned long TimeField::value ( ) const [inline]

Returns the current value of this time field, in seconds.

See also:: setValue()

Definition at line 41 of file TimeField.h.

The documentation for this class was generated from the following files:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation