@ -1,14 +1,6 @@
# ifndef MICROBIT_DISPLAY_H
# define MICROBIT_DISPLAY_H
/**
* User definable constants
*/
# define MICROBIT_DISPLAY_ROTATION_0 0
# define MICROBIT_DISPLAY_ROTATION_90 1
# define MICROBIT_DISPLAY_ROTATION_180 2
# define MICROBIT_DISPLAY_ROTATION_270 3
/**
* Core Configuration settings .
@ -82,6 +74,13 @@ enum DisplayMode {
DISPLAY_MODE_GREYSCALE
} ;
enum DisplayRotation {
MICROBIT_DISPLAY_ROTATION_0 ,
MICROBIT_DISPLAY_ROTATION_90 ,
MICROBIT_DISPLAY_ROTATION_180 ,
MICROBIT_DISPLAY_ROTATION_270
} ;
struct MatrixPoint {
uint8_t x ;
uint8_t y ;
@ -115,10 +114,10 @@ class MicroBitDisplay : public MicroBitComponent
// The animation mode that's currently running (if any)
AnimationMode animationMode ;
// The time (in ticks) between each frame update.
// The time in milliseconds between each frame update.
uint16_t animationDelay ;
// The time (in ticks) since the frame update.
// The time in milliseconds since the frame update.
uint16_t animationTick ;
// Stop playback of any animations
@ -243,9 +242,10 @@ public:
/**
* Resets the current given animation .
* @ param delay the delay after which the animation is reset .
* @ param delay the delay after which the animation is reset . Must be > 0.
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*/
void resetAnimation ( uint16_t delay ) ;
int resetAnimation ( uint16_t delay ) ;
/**
* Frame update method , invoked periodically to strobe the display .
@ -258,26 +258,29 @@ public:
* Returns immediately , and executes the animation asynchronously .
*
* @ param s The string to display .
* @ param delay The time to delay between characters , in timer ticks .
* @ param delay The time to delay between characters , in milliseconds . Must be > 0.
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*
* Example :
* @ code
* uBit . display . printAsync ( " abc123 " , 400 ) ;
* @ endcode
*/
void printAsync ( ManagedString s , int delay = MICROBIT_DEFAULT_PRINT_SPEED ) ;
int printAsync ( ManagedString s , int delay = MICROBIT_DEFAULT_PRINT_SPEED ) ;
/**
* Prints the given character to the display .
*
* @ param c The character to display .
* @ param delay The time to delay between characters , in milliseconds . Must be > 0.
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*
* Example :
* @ code
* uBit . display . print ( ' p ' ) ;
* @ endcode
*/
void print ( char c , int delay = 0 ) ;
int print ( char c , int delay = 0 ) ;
/**
* Prints the given string to the display , one character at a time .
@ -285,21 +288,23 @@ public:
* Blocks the calling thread until all the text has been displayed .
*
* @ param s The string to display .
* @ param delay The time to delay between characters , in timer ticks .
* @ param delay The time to delay between characters , in milliseconds . Must be > 0.
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*
* Example :
* @ code
* uBit . display . print ( " abc123 " , 400 ) ;
* @ endcode
*/
void print ( ManagedString s , int delay = MICROBIT_DEFAULT_PRINT_SPEED ) ;
int print ( ManagedString s , int delay = MICROBIT_DEFAULT_PRINT_SPEED ) ;
/**
* Prints the given image to the display .
* Blocks the calling thread until all the text has been displayed .
*
* @ param i The image to display .
* @ param delay The time to delay between characters , in timer ticks .
* @ param delay The time to display the image for , or zero to show the image forever . Must be > = 0.
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*
* Example :
* @ code
@ -307,7 +312,7 @@ public:
* uBit . display . print ( i , 400 ) ;
* @ endcode
*/
void print ( MicroBitImage i , int x , int y , int alpha , int delay = MICROBIT_DEFAULT_PRINT_SPEED ) ;
int print ( MicroBitImage i , int x , int y , int alpha , int delay = MICROBIT_DEFAULT_PRINT_SPEED ) ;
/**
* Scrolls the given string to the display , from right to left .
@ -315,21 +320,24 @@ public:
* Returns immediately , and executes the animation asynchronously .
*
* @ param s The string to display .
* @ param delay The time to delay between characters , in timer ticks .
* @ param delay The time to delay between each update to the display , in milliseconds . Must be > 0.
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*
* Example :
* @ code
* uBit . display . scrollAsync ( " abc123 " , 100 ) ;
* @ endcode
*/
void scrollAsync ( ManagedString s , int delay = MICROBIT_DEFAULT_SCROLL_SPEED ) ;
int scrollAsync ( ManagedString s , int delay = MICROBIT_DEFAULT_SCROLL_SPEED ) ;
/**
* Scrolls the given image across the display , from right to left .
* Returns immediately , and executes the animation asynchronously .
*
* @ param image The image to display .
* @ param delay The time to delay between each scroll update , in timer ticks . Has a default .
* @ param stride The number of pixels to move in each quantum . Has a default .
* @ param delay The time to delay between each update to the display , in milliseconds . Must be > 0.
* @ param stride The number of pixels to move in each update . Default value is the screen width .
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*
* Example :
* @ code
@ -337,7 +345,7 @@ public:
* uBit . display . scrollAsync ( i , 100 , 1 ) ;
* @ endcode
*/
void scrollAsync ( MicroBitImage image , int delay = MICROBIT_DEFAULT_SCROLL_SPEED , int stride = MICROBIT_DEFAULT_SCROLL_STRIDE ) ;
int scrollAsync ( MicroBitImage image , int delay = MICROBIT_DEFAULT_SCROLL_SPEED , int stride = MICROBIT_DEFAULT_SCROLL_STRIDE ) ;
/**
* Scrolls the given string to the display , from right to left .
@ -345,22 +353,24 @@ public:
* Blocks the calling thread until all the text has been displayed .
*
* @ param s The string to display .
* @ param delay The time to delay between characters , in timer ticks .
* @ param delay The time to delay between each update to the display , in milliseconds . Must be > 0.
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*
* Example :
* @ code
* uBit . display . scroll ( " abc123 " , 100 ) ;
* @ endcode
*/
void scroll ( ManagedString s , int delay = MICROBIT_DEFAULT_SCROLL_SPEED ) ;
int scroll ( ManagedString s , int delay = MICROBIT_DEFAULT_SCROLL_SPEED ) ;
/**
* Scrolls the given image across the display , from right to left .
* Blocks the calling thread until all the text has been displayed .
*
* @ param image The image to display .
* @ param delay The time to delay between each scroll update , in timer ticks . Has a default .
* @ param stride The number of pixels to move in each quantum . Has a default .
* @ param delay The time to delay between each update to the display , in milliseconds . Must be > 0.
* @ param stride The number of pixels to move in each update . Default value is the screen width .
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*
* Example :
* @ code
@ -368,15 +378,16 @@ public:
* uBit . display . scroll ( i , 100 , 1 ) ;
* @ endcode
*/
void scroll ( MicroBitImage image , int delay = MICROBIT_DEFAULT_SCROLL_SPEED , int stride = MICROBIT_DEFAULT_SCROLL_STRIDE ) ;
int scroll ( MicroBitImage image , int delay = MICROBIT_DEFAULT_SCROLL_SPEED , int stride = MICROBIT_DEFAULT_SCROLL_STRIDE ) ;
/**
* " Animates " the current image across the display with a given stride , finishing on the last frame of the animation .
* Returns immediately .
*
* @ param image The image to display .
* @ param delay The time to delay between each animation update , in timer ticks . Has a default .
* @ param stride The number of pixels to move in each quantum . Has a default .
* @ param delay The time to delay between each update to the display , in milliseconds . Must be > 0.
* @ param stride The number of pixels to move in each update . Default value is the screen width .
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*
* Example :
* @ code
@ -388,15 +399,16 @@ public:
* uBit . display . animateAsync ( i , 100 , 5 ) ;
* @ endcode
*/
void animateAsync ( MicroBitImage image , int delay , int stride , int startingPosition = MICROBIT_DISPLAY_ANIMATE_DEFAULT_POS ) ;
int animateAsync ( MicroBitImage image , int delay , int stride , int startingPosition = MICROBIT_DISPLAY_ANIMATE_DEFAULT_POS ) ;
/**
* " Animates " the current image across the display with a given stride , finishing on the last frame of the animation .
* Blocks the calling thread until the animation is complete .
*
* @ param image The image to display .
* @ param delay The time to delay between each animation update , in timer ticks . Has a default .
* @ param stride The number of pixels to move in each quantum . Has a default .
* @ param delay The time to delay between each update to the display , in milliseconds . Must be > 0.
* @ param stride The number of pixels to move in each update . Default value is the screen width .
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER .
*
* Example :
* @ code
@ -408,19 +420,19 @@ public:
* uBit . display . animate ( i , 100 , 5 ) ;
* @ endcode
*/
void animate ( MicroBitImage image , int delay , int stride , int startingPosition = MICROBIT_DISPLAY_ANIMATE_DEFAULT_POS ) ;
int animate ( MicroBitImage image , int delay , int stride , int startingPosition = MICROBIT_DISPLAY_ANIMATE_DEFAULT_POS ) ;
/**
* Sets the display brightness to the specified level .
* @ param b The brightness to set the brightness to , in the range 0. .255 .
* @ return MICROBIT_OK , or MICROBIT_INVALID_PARAMETER
*
* Example :
* @ code
* uBit . display . setBrightness ( 255 ) ; //max brightness
* @ endcode
*/
void setBrightness ( int b ) ;
int setBrightness ( int b ) ;
/**
* Sets the mode of the display .
@ -453,7 +465,7 @@ public:
* uBit . display . rotateTo ( MICROBIT_DISPLAY_ROTATION_180 ) ; //rotates 180 degrees from original orientation
* @ endcode
*/
void rotateTo ( uint8_t position ) ;
void rotateTo ( DisplayRotation position ) ;
/**
* Enables the display , should only be called if the display is disabled .