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. More...

	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. More...

int	dispatch (int event)
	Dispatches event via this field. More...

void	enterField (bool reverse)
	Enters the field due to form navigation. More...

void	exitField ()
	Exits the field due to form navigation. More...

unsigned long	value () const
	Returns the current value of this time field, in seconds. More...

void	setValue (unsigned long value)
	Sets the value of this time field, in seconds. More...

int	maxHours () const
	Returns the maximum number of hours before the field wraps around. More...

void	setMaxHours (int maxHours)
	Sets the maximum number of hours before the field wraps around to maxHours. More...

bool	readOnly () const
	Returns TIMEFIELD_READ_ONLY (true) or TIMEFIELD_READ_WRITE (false). More...

void	setReadOnly (bool value)
	Sets the read-only state of this field to value. More...

Public Member Functions inherited from Field
	Field (const String &label)
	Constructs a new field with a specific label. More...

	Field (Form &form, const String &label)
	Constructs a new field with a specific label and attaches it to a form.

	~Field ()
	Destroys this field and removes it from its owning Form. More...

Form *	form () const
	Returns the Form that owns this field; null if not associated with a Form.

const String &	label () const
	Returns the label to display in the first line of this field. More...

void	setLabel (const String &label)
	Sets the label to display in the first line of this field. More...

bool	isCurrent () const
	Returns true if this field is the currently-displayed field in its owning form; false otherwise. More...

Additional Inherited Members
Protected Member Functions inherited from Field
LiquidCrystal *	lcd () const
	Returns the LCD that this field is being drawn on.

virtual void	updateCursor ()
	Updates the cursor position after the label has been drawn by setLabel(). More...

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().