TDuino
Convenient functionality for Arduino
Public Member Functions | Protected Member Functions | Protected Attributes
TTimeline Class Reference

Used to track actions on a virtual time line. More...

#include <TTimeline.h>

Public Member Functions

 TTimeline (void(*callback)(byte, float), byte numSlots=1)
 The constructor for a TTimeline. More...
 
 ~TTimeline ()
 The destuctor for a TTimeline. More...
 
int firstActive ()
 Find index of the first active slot. More...
 
int firstInactive ()
 Find index of the first inactive slot. More...
 
byte getSize ()
 Get number of timeline slots. More...
 
char hasOverlap (byte index1, byte index2, bool remove=false)
 Check if two slots has an overlap. More...
 
bool isActive (byte index)
 Check if a slot is active. More...
 
bool isStarted (byte index)
 Check if a slot is started. More...
 
void restart (byte index)
 Used to restart a slot. More...
 
void restartAll ()
 Used to restart all slots. More...
 
void set (byte index, unsigned long duration, unsigned long startAfter=0)
 Set a slot in the time line. More...
 
void stop (byte index)
 Stop a slot. More...
 
void stopAll ()
 Stop all slots. More...
 
virtual void loop ()
 The TTimeline's loop phase. More...
 
- Public Member Functions inherited from TBase
 TBase ()
 Constructor for class TBase. More...
 
virtual ~TBase ()
 Destructor for class TBase. More...
 

Protected Member Functions

bool badIndex (byte i, const char *token)
 
void checkMemError (const char *token)
 
- Protected Member Functions inherited from TBase
virtual void defaults ()
 Method used to reset all class internal variables. More...
 

Protected Attributes

const byte numSlots = TDUINO_TIMELINE_SIZE
 
TTIMELINE_SLOT slots [TDUINO_TIMELINE_SIZE]
 
byte numSlots
 
TTIMELINE_SLOT * slots
 
TTIMELINE_SLOT * current
 
byte dummy
 
byte memError
 
- Protected Attributes inherited from TBase
unsigned long loopMillis
 The value of millis() to be used within loop()
 

Detailed Description

Used to track actions on a virtual time line.

TTimeline is usefull when you need to have sort of a virtual time line where different things are happening gradually in a period of time which can be postponed.

void TimelineCallback(byte slot, float progress)
{
// "slot" is the index of the slot in the time line.
// "progress" is the amount of progress from 0.0f (start) to 1.0f (end).
}
TTimeline tline(TimelineCallback, 2); //Two slots
//Set first slot to start after 5 seconds with a duration of 1 second
tline.set(0, 1000, 5000);
//Set the second slot to start after 10 seconds with a duration of 5 seconds
tline.set(1, 5000, 10000);

See Timeline helpers for a list of helpers for handling the progres value.

IMPORTANT NOTE! For most situations you would use the template class TTimelineT because it is more efficient (no floating points). You should only use TTimeline in situations where you need to translate the progress to multiple different values.

See also
TTimelineT

Constructor & Destructor Documentation

◆ TTimeline()

TTimeline::TTimeline ( void(*)(byte, float)  callback,
byte  numSlots = 1 
)

The constructor for a TTimeline.

Parameters
callbackThe callback which handles time line events.
numSlotsThe number of slots used by this instance.

The callback will be called for each active slot and to it will be passed an index of the slot being handled and the amount of progress for the slot.

numSlots must be in the range 1..255, memory usage (in bytes) is: (13 * numSlots) + 2.

Static allocation of object memory

◆ ~TTimeline()

TTimeline::~TTimeline ( )

The destuctor for a TTimeline.

The destructor will release any memory used for slots

Member Function Documentation

◆ firstActive()

int TTimeline::firstActive ( )

Find index of the first active slot.

Returns
The index of the first active slot.

If no slots are active, -1 will be returned.

◆ firstInactive()

int TTimeline::firstInactive ( )

Find index of the first inactive slot.

Returns
The index of the first inactive slot.

If no slots are inactive, -1 will be returned.

◆ getSize()

byte TTimeline::getSize ( )

Get number of timeline slots.

Returns
The number of timeline slots.

Used to get the number of timeline slots used with this instance of TTimeline.

See also
TTimeline()

◆ hasOverlap()

char TTimeline::hasOverlap ( byte  index1,
byte  index2,
bool  remove = false 
)

Check if two slots has an overlap.

Parameters
index1The index of the first slot to check.
index2The index of the second slot to check.
removeIf true, the overlapping slot will be postponet until the overlap is removed.
Returns
0 if there is no overlap, 1 if index1 overlaps index2 and 2 if index2 overlaps index1. If the return value is negative, the operation could not be performed due to a 32 bit rollover in the slot. Eg. if the return value is -2 the slot at index2 causes a rollover.

This method is used to examine wheter or not the actual transition of two slots are overlapping in a way that they may interfere with eachother. The overlapping slot is the slot that starts later and if both slots starts at the same time, the first slot will be returned.

TTimeline tl(tlHandler, 2);
tl.set(0, 1000, 500);
tl.set(1, 1000, 1000);
byte ol = tl.hasOverlap(0, 1, true);

In the example above, "ol" will be 2 because the second slot will start when the first slot is half done. Since "remove" is set to true, the second slot will be postponet with an additional 500 ms and this means that the code above will do exactely the same as the next example:

TTimeline tl(tlHandler, 2);
tl.set(0, 1000, 500);
tl.set(1, 1000, 1500);

NOTE: By default hasOverlap() uses 32 bit integers for calculation and this will only work if the time line does not exceed ~24 days (or ~35 seconds if using micros() for timing) from start to end. This behaviour may be tweaked, read more about it in Tweaking TDuino.

◆ isActive()

bool TTimeline::isActive ( byte  index)

Check if a slot is active.

Parameters
indexThe index of the slot to check.
Returns
true if the slot is active.

Used to check if a slot is active or postponed (waiting to become active).

◆ isStarted()

bool TTimeline::isStarted ( byte  index)

Check if a slot is started.

Parameters
indexThe index of the slot to check.
Returns
true if the slot is started.

Used to check if a slot is started (transition in progress).

◆ loop()

void TTimeline::loop ( )
virtual

The TTimeline's loop phase.

Must be called for each loop in the sketch.

See also
TBase::loop()

Reimplemented from TBase.

Reimplemented in TTimelineT< DATATYPE >.

◆ restart()

void TTimeline::restart ( byte  index)

Used to restart a slot.

Parameters
indexThe index of the slot to restart.

This method will restart the slot at index with the values previously set with set().

◆ restartAll()

void TTimeline::restartAll ( )

Used to restart all slots.

This method will restart all slots in the time line.

◆ set()

void TTimeline::set ( byte  index,
unsigned long  duration,
unsigned long  startAfter = 0 
)

Set a slot in the time line.

Parameters
indexIndex of the slot to set.
durationThe duration of the slot.
startAfterThe amount of time (milliseconds) to wait before starting the slot.

Sets the slot at index to start after startAfter milliseconds with duration milliseconds. By default startAfter is set to 0, which means that the slot will start emmediately.

If duration is zero, the slot will act as a one-shot timer.

◆ stop()

void TTimeline::stop ( byte  index)

Stop a slot.

Parameters
indexIndex of the slot to stop.

This will deactivate the slot at the specified index.

◆ stopAll()

void TTimeline::stopAll ( )

Stop all slots.

This will deactivate all slots in the time line.