Parola for Arduino  2.0
Text effects for Parola modular hardware
 All Classes Files Functions Enumerations Enumerator Macros Pages
MD_Parola Class Reference

#include <MD_Parola.h>

Public Member Functions

 MD_Parola (uint8_t dataPin, uint8_t clkPin, uint8_t csPin, uint8_t numDevices=1)
 
 MD_Parola (uint8_t csPin, uint8_t numDevices=1)
 
void begin (void)
 
void begin (uint8_t numZones)
 
 ~MD_Parola (void)
 
Methods for core object control.
bool displayAnimate (void)
 
bool getZoneStatus (uint8_t z)
 
void displayClear (void)
 
void displayReset (void)
 
void displayReset (uint8_t z)
 
void displaySuspend (bool b)
 
bool setZone (uint8_t z, uint8_t moduleStart, uint8_t moduleEnd)
 
Methods for quick start displays.
void displayScroll (char *pText, textPosition_t align, textEffect_t effect, uint16_t speed)
 
void displayText (char *pText, textPosition_t align, uint16_t speed, uint16_t pause, textEffect_t effectIn, textEffect_t effectOut=NO_EFFECT)
 
void displayZoneText (uint8_t z, char *pText, textPosition_t align, uint16_t speed, uint16_t pause, textEffect_t effectIn, textEffect_t effectOut=NO_EFFECT)
 
Support methods for visually adjusting the display.
uint8_t getCharSpacing (void)
 
uint8_t getCharSpacing (uint8_t z)
 
bool getInvert (void)
 
bool getInvert (uint8_t z)
 
uint16_t getPause (void)
 
uint16_t getPause (uint8_t z)
 
uint16_t getSpeed (void)
 
uint16_t getSpeed (uint8_t z)
 
textPosition_t getTextAlignment (void)
 
textPosition_t getTextAlignment (uint8_t z)
 
void setCharSpacing (uint8_t cs)
 
void setCharSpacing (uint8_t z, uint8_t cs)
 
void setIntensity (uint8_t intensity)
 
void setIntensity (uint8_t z, uint8_t intensity)
 
void setInvert (uint8_t invert)
 
void setInvert (uint8_t z, uint8_t invert)
 
void setPause (uint16_t pause)
 
void setPause (uint8_t z, uint16_t pause)
 
void setSpeed (uint16_t speed)
 
void setSpeed (uint8_t z, uint16_t speed)
 
void setTextAlignment (textPosition_t ta)
 
void setTextAlignment (uint8_t z, textPosition_t ta)
 
void setTextBuffer (char *pb)
 
void setTextBuffer (uint8_t z, char *pb)
 
void setTextEffect (textEffect_t effectIn, textEffect_t effectOut)
 
void setTextEffect (uint8_t z, textEffect_t effectIn, textEffect_t effectOut)
 
Support methods for fonts and characters.
void addChar (uint8_t code, uint8_t *data)
 
bool addChar (uint8_t z, uint8_t code, uint8_t *data)
 
void delChar (uint8_t code)
 
bool delChar (uint8_t z, uint8_t code)
 
void setFont (MD_MAX72XX::fontType_t fontDef)
 
void setFont (uint8_t z, MD_MAX72XX::fontType_t fontDef)
 

Detailed Description

Core object for the Parola library. This class contains one or more zones for display.

Constructor & Destructor Documentation

MD_Parola::MD_Parola ( uint8_t  dataPin,
uint8_t  clkPin,
uint8_t  csPin,
uint8_t  numDevices = 1 
)

Class Constructor - arbitrary output pins.

Instantiate a new instance of the class. The parameters passed are used to connect the software to the hardware using the MD_MAX72XX class.

See documentation for the MD_MAX72XX library for detailed explanation of parameters.

Parameters
dataPinoutput on the Arduino where data gets shifted out.
clkPinoutput for the clock signal.
csPinoutput for selecting the device.
numDevicesnumber of devices connected. Default is 1 if not supplied.
MD_Parola::MD_Parola ( uint8_t  csPin,
uint8_t  numDevices = 1 
)

Class Constructor - SPI hardware interface.

Instantiate a new instance of the class. The parameters passed are used to connect the software to the hardware using the MD_MAX72XX class.

See documentation for the MD_MAX72XX library for detailed explanation of parameters.

Parameters
csPinoutput for selecting the device.
numDevicesnumber of devices connected. Default is 1 if not supplied.
MD_Parola::~MD_Parola ( void  )

Class Destructor.

Release allocated memory and does the necessary to clean up once the object is no longer required.

Member Function Documentation

void MD_Parola::addChar ( uint8_t  code,
uint8_t *  data 
)

Add a user defined character to the replacement list for all zones.

Add a replacement characters to the user defined list. The character data must be the same as for a single character in the font definition file. If a character is specified with a code the same as an existing character the existing data will be substituted for the new data. A character code of 0 ('\0') is illegal as this denotes the end of string character for C++ and cannot be used in an actual string.

The library does not copy the data definition but only retains a pointer to the data, so any changes to the data storage in the calling program will be reflected into the library. The data must also remain in scope while it is being used.

Parameters
codeASCII code for the character data.
datapointer to the character data.
Returns
No return value.
bool MD_Parola::addChar ( uint8_t  z,
uint8_t  code,
uint8_t *  data 
)

Add a user defined character to the replacement specified zone.

See the comments for the 'all zones' variant of this method

Parameters
zzone specified
codeASCII code for the character data.
datapointer to the character data.
Returns
true of the character was inserted in the substitution list.
void MD_Parola::begin ( void  )

Initialize the object.

Initialise the object data. This needs to be called during setup() to initialise new data for the class that cannot be done during the object creation. This form of the method is for backward compatibility and creates one zone for the entire display.

void MD_Parola::begin ( uint8_t  numZones)

Initialize the object.

Initialise the object data. This needs to be called during setup() to initialise new data for the class that cannot be done during the object creation. This form of the method allows specifying the maximum number of zones. The limits for these need to be initialized separately using setZone().

Parameters
numZonesmaximum number of zones [0..numZones]
void MD_Parola::delChar ( uint8_t  code)

Delete a user defined character to the replacement list for all zones.

Delete a reference to a replacement character in the user defined list.

Parameters
codeASCII code for the character data.
Returns
No return value.
bool MD_Parola::delChar ( uint8_t  z,
uint8_t  code 
)

Delete a user defined character to the replacement list for the specified zone.

See the comments for the 'all zones' variant of this method.

Parameters
zzone specified
codeASCII code for the character data.
Returns
true of the character was found in the substitution list.
bool MD_Parola::displayAnimate ( void  )

Animate the display.

Animate all the zones in the display using the currently specified text and animation parameters. This method needs to be invoked as often as possible to ensure smooth animation. The animation is governed by a time tick that is set by the setSpeed() method and it will pause between entry and exit using the time set by the setPause() method.

The calling program should monitor the return value for 'true' in order to either reset the zone animation or supply another string for display. A 'true' return value means that one or more zones have completed their animation.

Returns
bool true if at least one zone animation has completed, false otherwise.
void MD_Parola::displayClear ( void  )

Clear the display.

Clear all the from all the zones in the current display.

Returns
No return value.
void MD_Parola::displayReset ( void  )

Reset the current animation to restart for all zones.

This method is used to reset all the zone animations an animation back to the start of their cycle current cycle. It is normally invoked after all the parameters for a display are set and the animation needs to be started (or restarted).

Returns
No return value.
void MD_Parola::displayReset ( uint8_t  z)

Reset the current animation to restart for the specified zone.

See the comments for the 'all zones' variant of this method.

Parameters
zspecified zone
Returns
No return value.
void MD_Parola::displayScroll ( char *  pText,
textPosition_t  align,
textEffect_t  effect,
uint16_t  speed 
)

Easy start for a scrolling text display.

This method is a convenient way to set up a scrolling display. All the data necessary for setup is passed through as parameters and the display animation is started. Assumes one zone only (zone 0).

Parameters
pTextparameter suitable for the setTextBuffer() method.
alignparameter suitable for the the setTextAlignment() method.
effectparameter suitable for the the setTextEffect() method.
speedparameter suitable for the setSpeed() method.
Returns
No return value.
void MD_Parola::displaySuspend ( bool  b)

Suspend or resume display updates.

Stop the current display animation. When pausing it leaves the display showing the current text. Resuming will restart the animation where it left off. To reset the animation back to the beginning, use the displayReset() method.

Parameters
bboolean value to suspend (true) or resume (false).
Returns
No return value.
void MD_Parola::displayText ( char *  pText,
textPosition_t  align,
uint16_t  speed,
uint16_t  pause,
textEffect_t  effectIn,
textEffect_t  effectOut = NO_EFFECT 
)

Easy start for a non-scrolling text display.

This method is a convenient way to set up a static text display. All the data necessary for setup is passed through as parameters and the display animation is started. Assumes one zone only.

Parameters
pTextparameter suitable for the setTextBuffer() method.
alignparameter suitable for the the setTextAlignment() method.
speedparameter suitable for the setSpeed() method.
pauseparameter suitable for the setPause() method.
effectInparameter suitable for the setTextEffect() method.
effectOutparameter suitable for the setTextEffect() method.
Returns
No return value.
void MD_Parola::displayZoneText ( uint8_t  z,
char *  pText,
textPosition_t  align,
uint16_t  speed,
uint16_t  pause,
textEffect_t  effectIn,
textEffect_t  effectOut = NO_EFFECT 
)

Easy start for a non-scrolling zone text display.

This method is a convenient way to set up a static text display within the specified zone. All the data necessary for setup is passed through as parameters and the display animation is started.

Parameters
zzone specified.
pTextparameter suitable for the setTextBuffer() method.
alignparameter suitable for the the setTextAlignment() method.
speedparameter suitable for the setSpeed() method.
pauseparameter suitable for the setPause() method.
effectInparameter suitable for the setTextEffect() method.
effectOutparameter suitable for the setTextEffect() method.
Returns
No return value.
uint8_t MD_Parola::getCharSpacing ( void  )

Get the inter-character spacing in columns.

Returns
the current setting for the space between characters in columns. Assumes one zone only.
uint8_t MD_Parola::getCharSpacing ( uint8_t  z)

Get the inter-character spacing in columns for a specific zone.

Parameters
zzone number.
Returns
the current setting for the space between characters in columns.
bool MD_Parola::getInvert ( void  )

Get the current display invert state.

See the setInvert() method.

Returns
true if the display is inverted. Assumes one zone only.
bool MD_Parola::getInvert ( uint8_t  z)

Get the current display invert state for a specific zone.

See the setInvert() method.

Parameters
zzone number.
Returns
the inverted boolean value for the specified zone.
uint16_t MD_Parola::getPause ( void  )

Get the current pause time.

See the setPause() method. Assumes one zone only.

Returns
the pause value in milliseconds.
uint16_t MD_Parola::getPause ( uint8_t  z)

Get the current pause time for a specific zone.

See the setPause() method.

Parameters
zzone number.
Returns
the pause value in milliseconds for the specified zone.
uint16_t MD_Parola::getSpeed ( void  )

Get the current animation speed.

See the setSpeed() method. Assumes one zone only

Returns
the speed value.
uint16_t MD_Parola::getSpeed ( uint8_t  z)

Get the current animation speed for the specified zone.

See the setSpeed() method.

Parameters
zzone number.
Returns
the speed value for the specified zone.
textPosition_t MD_Parola::getTextAlignment ( void  )

Get the current text alignment specification.

Assumes one zone only.

Returns
the current text alignment setting.
textPosition_t MD_Parola::getTextAlignment ( uint8_t  z)

Get the current text alignment specification for the specified zone.

Parameters
zzone number.
Returns
the current text alignment setting for the specified zone.
bool MD_Parola::getZoneStatus ( uint8_t  z)

Get the completion status for a zone.

This method is to determine which zone has completed when displayAnimate() has returned a completion status.

The calling program should monitor the return value for 'true' in order to either reset the zone animation or supply another string for display. A 'true' return value means that the zone has completed its animation cycle.

Parameters
zspecified zone
Returns
bool true if at least one zone animation has completed, false otherwise.
void MD_Parola::setCharSpacing ( uint8_t  cs)

Set the inter-character spacing in columns for all zones.

Set the number of blank columns between characters when they are displayed.

Parameters
csspace between characters in columns.
Returns
No return value.
void MD_Parola::setCharSpacing ( uint8_t  z,
uint8_t  cs 
)

Set the inter-character spacing in columns for the specified zone.

See comments for the 'all zones' variant of this method.

Parameters
zzone number.
csspace between characters in columns.
Returns
No return value.
void MD_Parola::setFont ( MD_MAX72XX::fontType_t  fontDef)

Set the display font for all zones.

Set the display font to a user defined font table. This can be created using the MD_MAX72xx font builder (refer to documentation for the tool and the MD_MAX72xx library). Passing NULL resets to the library default font.

Parameters
fontDefPointer to the font definition to be used.
Returns
No return value.
void MD_Parola::setFont ( uint8_t  z,
MD_MAX72XX::fontType_t  fontDef 
)

Set the display font for a specific zone.

Set the display font to a user defined font table. This can be created using the MD_MAX72xx font builder (refer to documentation for the tool and the MD_MAX72xx library). Passing NULL resets to the library default font.

Parameters
zspecified zone.
fontDefPointer to the font definition to be used.
Returns
No return value.
void MD_Parola::setIntensity ( uint8_t  intensity)

Set the display brightness for all the zones.

Set the intensity (brightness) of the display.

Parameters
intensitythe intensity to set the display (0-15).
Returns
No return value.
void MD_Parola::setIntensity ( uint8_t  z,
uint8_t  intensity 
)

Set the display brightness for the specified zone.

See comments for the 'all zones' variant of this method.

Parameters
zzone number.
intensitythe intensity to set the display (0-15).
Returns
No return value.
void MD_Parola::setInvert ( uint8_t  invert)

Invert the display in all the zones.

Set the display to inverted (ON LED turns OFF and vice versa).

Parameters
inverttrue for inverted display, false for normal display
Returns
No return value.
void MD_Parola::setInvert ( uint8_t  z,
uint8_t  invert 
)

Invert the display in the specified zone.

See comments for the 'all zones' variant of this method.

Parameters
zzone number.
inverttrue for inverted display, false for normal display
Returns
No return value.
void MD_Parola::setPause ( uint16_t  pause)

Set the pause between ENTER and EXIT animations for all zones.

Between each entry and exit, the library will pause by the number of milliseconds specified to allow the viewer to read the message. For continuous scrolling displays this should be set to the same value as the display speed.

Parameters
pausethe time, in milliseconds, between animations.
Returns
No return value.
void MD_Parola::setPause ( uint8_t  z,
uint16_t  pause 
)

Set the pause between ENTER and EXIT animations for the specified zone.

See comments for the 'all zones' variant of this method.

Parameters
zzone number.
pausethe time, in milliseconds, between animations.
Returns
No return value.
void MD_Parola::setSpeed ( uint16_t  speed)

Set the animation frame speed for all zones.

The speed of the display is the 'tick' time between animation frames. The lower this time the faster the animation; set it to zero to run as fast as possible.

Parameters
speedthe time, in milliseconds, between animation frames.
Returns
No return value.
void MD_Parola::setSpeed ( uint8_t  z,
uint16_t  speed 
)

Set the animation frame speed for the specified zone.

See comments for the 'all zones' variant of this method.

Parameters
zzone number.
speedthe time, in milliseconds, between animation frames.
Returns
No return value.
void MD_Parola::setTextAlignment ( textPosition_t  ta)

Set the text alignment for all zones.

Text alignment is specified as one of the values in textPosition_t.

Parameters
tathe required text alignment.
Returns
No return value.
void MD_Parola::setTextAlignment ( uint8_t  z,
textPosition_t  ta 
)

Set the text alignment for the specified zone.

See comments for the 'all zones' variant of this method.

Parameters
zzone number.
tathe required text alignment.
Returns
No return value.
void MD_Parola::setTextBuffer ( char *  pb)

Set the pointer to the text buffer (single zone display).

Sets the text buffer to be a pointer to user data. The library does not allocate any memory for the text message, rather it is the calling program that supplies a pointer to a buffer. This reduces memory requirements and offers the flexibility to keep a single buffer or rotate buffers with different messages, all under calling program control, with no library limit to the size or numbers of buffers. The text placed in the buffer must be properly terminated by the NUL ('\0') character or processing will overrun the end of the message.

This form of the method assumes one zone only.

Parameters
pbpointer to the text buffer to be used.
Returns
No return value.
void MD_Parola::setTextBuffer ( uint8_t  z,
char *  pb 
)

Set the pointer to the text buffer for the specified zone.

See comments for the single zone version of this method.

Parameters
zzone number.
pbpointer to the text buffer to be used.
Returns
No return value.
void MD_Parola::setTextEffect ( textEffect_t  effectIn,
textEffect_t  effectOut 
)

Set the entry and exit text effects for all zones.

The 'in' and 'out' text effects are specified using the textEffect_t enumerated type. If no effect is required, NO_EFFECT should be specified. NO_EFFECT is most useful when no exit effect is required (e.g., when DISSOLVE is used) and the entry effect is sufficient.

Parameters
effectInthe entry effect, one of the textEffect_t enumerated values.
effectOutthe exit effect, one of the textEffect_t enumerated values.
Returns
No return value.
void MD_Parola::setTextEffect ( uint8_t  z,
textEffect_t  effectIn,
textEffect_t  effectOut 
)

Set the entry and exit text effects for a specific zone.

See comments for the 'all zones' variant of this method.

Parameters
zzone number.
effectInthe entry effect, one of the textEffect_t enumerated values.
effectOutthe exit effect, one of the textEffect_t enumerated values.
Returns
No return value.
bool MD_Parola::setZone ( uint8_t  z,
uint8_t  moduleStart,
uint8_t  moduleEnd 
)

Define the module limits for a zone.

When multiple zones are defined, the library needs to know the contiguous module ranges that make up the different zones. If the library has been started with only one zone then it will automatically initialize the zone to be the entire range for the display modules, so calling this function is not required.

A module is a unit of 8x8 LEDs, as defined in the MD_MAX72xx library. Zones should not overlap or unexpected results will occur.

Parameters
zzone number.
moduleStartthe first module number for the zone [0..numZones-1].
moduleEndthe last module number for the zone [0..numZones-1].
Returns
true if set, false otherwise.

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