TouchShield data types and function wiki

This is a little wiki to describe all the major data types and functions that are available on the TouchShield (www.liquidware.com).

 

 

Data types

Point

This is the data type the TouchShield uses to provide x and y coordinates of a touchscreen press (like with a finger or stylus).

 

typedef struct Point

{

    unsigned char x; /*!< X coordinate, 8-bit */

    unsigned char y; /*!< X coordinate, 8-bit */

} POINT;

 

An example of using this in the Arduino code is:

 

POINT my_point; //defined anywhere in global memory space, or in loop, for instance

 

while (1) {

    if (touch_get_cursor(&my_point)) {

//touch_get_cursor stores the value of the touchscreen touch, and then you can read my_point.x and my_point.y below

     my_point.x; //x coordinates

     my_point.y; //y coordinates

     }

} 

 

COLOR

This data type is how you define a color, which can then be used by a drawing function to make colored lines. It takes a standard RGB value, which can be hex or decimal, just as long as it's typed correctly, like the example below.

 

typedef struct Color

    {

    unsigned char red;

    unsigned char green;

    unsigned char blue;

    } COLOR;

 

An example of using this in the Arduino code is:

 

COLOR blue =  {40, 153, 224}; //each one is passed as Red, then Green, then Blue (hence RGB!)

COLOR red = {255, 0, 0};

COLOR black = {0, 0, 0};

COLOR white = {255, 255, 255};

COLOR gray = {200, 200, 200};

COLOR orange = {255, 153, 0};

COLOR green = {102, 153, 0};

COLOR dimred = {201, 84, 84};

 

lcd_line(8, 10, 50, 10, blue); //then you can use the colors in drawing functions

lcd_pixel(40, 40, red); //or pixel functions

 

Lcd_rect

A lot of graphics functions, and GUI programs use rectangles, so I thought it would be convenient to create a simple "rect" data type and use it throughout the functions (hopefully to simplify code a little bit).

 

typedef struct Lcd_rect   

{

    unsigned char left;     /*!< The left side of the rectangle */

    unsigned char top;         /*!< The top position of the rectangle */

    unsigned char right;     /*!< The right side of the rectangle */

    unsigned char bottom;     /*!< The bottom position of the rectangle */

}LCD_RECT;

 

You could use this data type with functions like:

 

char pointInRect(POINT p, LCD_RECT r);

 

Bmp

Probably you won't need to use this data type directly, but if you're really adventurous, it's here. This is the way pictures are stored on the TouchShield, as bitmaps.

 

typedef struct Bmp

    {

    unsigned char     width;

    unsigned char     height;

    unsigned int     length;

    COLOR            pixels[];

    } BMP;

 

I'll need to expand the how-to-use this section, but for the most part, it's all accessible through the functions below, and it's pretty simple to use pictures if you follow the instructions over here.

 

Most of the time, the Bmp data structure is handled behind the scenes, and you just work with bitmaps by calling a function like:

 

bmp_draw(“burn005”,0,0);

 

---

 

Commonly used functions

char touch_get_cursor(POINT* p)

This function checks to see if a press has happened on the touchscreen, and if so, it stores the value of the x and y coordinates to a POINT variable. You have to pass the address of the POINT variable, by calling the function like this:

touch_get_cursor(&my_point)

 

 

An example of using this in the Arduino code is:

 

POINT my_point; //defined anywhere in global memory space, or in loop, for instance

 

while (1) {

    if (touch_get_cursor(&my_point)) {

//touch_get_cursor stores the value of the touchscreen touch, and then you can read my_point.x and my_point.y below

     my_point.x; //x coordinates

     my_point.y; //y coordinates

     }

}

 

void lcd_clear(unsigned char x1,unsigned char y1,unsigned char x2,unsigned char y2, COLOR * color)

This function takes the x and y coordinates of the upper left hand corner of a rectangle (x1, y1), and the lower right hand corner of a rectangle (x2, y2), and fills it with colored pixels.

 

An example of using this function in an Arduino progam is:

 

COLOR white = {255, 255, 255}; //define the color to fill the rectangular space with

lcd_clear(10,10,20,20,white); //fill the space

  

 

void lcd_clearScreen(COLOR c)

This function just clears the screen and fills it all up with a single color.

 

It's really simple to use, for instance:

 

COLOR white = {255, 255, 255}; //define the color to fill the screen with

lcd_clearScreen(white); //fill the screen with that color! 

 

 

void lcd_setBrightness(unsigned char brightnessLevel)

This is a simple function that takes a number between 1 and 10, and sets the brightness of the screen accordingly. This was one of the first things I ever did when I got a computer,... turn the brightness of the screen up and down with a software control panel, rather than those retro controls on the front of the screen.

 

Here's an example of how you'd use it in the Arduino code:

 

int brightness = 5;

 

void BrightUp ( void) {

  if (brightness < 10) {

    brightness++;

  }

  lcd_setBrightness(brightness);

}

void BrightDown ( void) {

  if (brightness > 1) {

    brightness--;

  }

  lcd_setBrightness(brightness);

}

 

 

void lcd_pixel(unsigned char x, unsigned char y, COLOR pixel_color)

This function draws a single (lonesome) pixel on the TouchShield. As the variables suggest, it takes the x and y coordinates, and a color for the pixel. This function gets exponentially more interesting when you use it multiple times, or when it's put inside a for loop to draw several different pixels at once.

 

Here's some sample code using the function:

 

COLOR red = {255, 0, 0};

lcd_pixel( 10, 10, red);

 

 

 

void lcd_circle(unsigned char x, unsigned char y, unsigned char radius, COLOR outline_color, COLOR fill_color)

Ah, the dreaded circle. If you've ever coded for low-end embedded devices or portable gadgets, then you know that circle drawing algorithms are probably some of the hardest code to write. (In the old days, they had to do this without built in square and multiplication functions). Anyway, this function draws a circle, given the x and y coordinates of the center, the radius in pixels, and then two colors: one for the outline, and one for the fill.

 

Here's some sample code using the function:

 

COLOR red = {255, 0, 0};

COLOR black = {0, 0, 0};

lcd_circle(20,20,10, red, black); //draw a sinister red circle, with black inside

 

 

void lcd_rectangle(unsigned char x1, unsigned char y1, unsigned char x2, unsigned char y2, COLOR outline_color, COLOR fill_color)

Nothing fancy here, just a rectangle drawing function.  It takes the x and y coordinates of the upper left corner of the rectangle, the x and y of the lower right corner, an outline color, and a fill color.

 

Here's some sample code using the function:

 

COLOR red = {255, 0, 0};

COLOR blue = {0, 0, 255};

lcd_rectangle(10,10,50, 50, red, blue);

 

void lcd_rect(LCD_RECT r, COLOR outline_color, COLOR fill_color)

If you want to use the LCD_RECT data type class described above, you could use this function instead of lcd_rectangle. It takes the LCD_RECT class, then the outline color, followed by the fill color.

 

Here's a simple example - though given the simplistic nature of this example, you'd probably be better off using lcd_rectangle:

 

 

COLOR red = {255, 0, 0};

COLOR blue = {0, 0, 255};

LCD_RECT r;

r.left = 10;

r.right = 50;

r.top = 10;

r.bottom = 50;

lcd_rectangle(r, red, blue);

 

 

void lcd_line(unsigned char x1, unsigned char y1, unsigned char x2, unsigned char y2, COLOR line_color)

This function draws a line. The line doesn't need to be straight, mind you, this also draws diagonal and slanted lines (as best it can). It takes the x and y coordinates of the first point, then the x and y coordinates of the second point, and the line color.

 

Here's an example:

 

COLOR blue = {0, 0, 255};

lcd_line(10,10,50, 50, blue); //yep. a line. next :)

 

 

 

void lcd_putc(unsigned char ch, unsigned char x_pos,unsigned char y_pos,COLOR fc, COLOR bc)

If you want to draw a single character at a time, this function can help. You give it a character, x and y coordinates, and the color of the text, and the color of the background. The background is important in case you want to draw white on black or black on white text (or text on colored backgrounds, for instance).

 

Here's a simple example:

 

COLOR black = {0,0,0};

COLOR red = {255,0,0};

lcd_putc('a',30,30,red,black);

 

 

void lcd_puts(char * string,unsigned char x_pos, unsigned char y_pos, COLOR fc, COLOR bc)

This function lets you draw a string of characters on the TouchScreen. It takes a string of text in a char array, the x and y position, and then the foreground and backgroun colors.

 

Here's a simple example:

 

char message[] = "hello";

COLOR black = {0,0,0};

COLOR red = {255,0,0};

lcd_putc(message,30,30,red,black);

 

 

char pointInRect(POINT p, LCD_RECT r)

A lot of user interfaces have buttons, and if you write a simple UI, sometimes you spend a lot of time just checking if a point is inside a rectangle. Instead of having to rewrite code that says, is the x of the point inbetween the left and right side of the rectangle I care about, and is the y of the point inside the top and bottom (which can get to be a long and complex set of if statements), you could just define the LCD_RECT you care about, and then call this function with the POINT variable that you stored the touchscreen press into.

 

That was a really long winded way of saying something that's probably a lot easier to understand just looking at an example:

 

POINT my_point; //defined anywhere in global memory space, or in loop, for instance

COLOR red = {255, 0, 0};

COLOR blue = {0, 0, 255};

LCD_RECT r;

r.left = 10;

r.right = 50;

r.top = 10;

r.bottom = 50;

 

lcd_rectangle(r, red, blue); //draw the rectangle on the screen

 

while (1) {

    if (touch_get_cursor(&my_point)) {

//touch_get_cursor stores the value of the touchscreen touch, and then you can read my_point.x and my_point.y below

     if (pointInRect(my_point,r)) {

          //yay, the point was inside the rectangle

     }

     }

}

 

 

---

Miscellaneous cool functions

Here's some source code for functions that fade the TouchScreen off, kind of like an iPod or some of the more advanced cell phones. This makes a sort of neat effect where the screen fades down to black, and then you can draw some stuff, and then fade the screen back up.

 

int fader=10; //making this number higher makes the fade take longer, whereas small numbers make it speed up

int brightness=5; //when fading back up, this tells the fadeIn function how bright to go before stopping

 

void fadeOut (void) {

  for (int i = brightness; i>0; i--) {

    lcd_setBrightness(i);

    delay(fader);

  }

 

  CLRBIT(PORTE, PE3);

}

void fadeIn(void) {

  SETBIT(PORTE, PE3);

 

  for (int i = 0; i<(brightness+1); i++) {

    lcd_setBrightness(i);

    delay(fader);

  }

}

 

---

Really low end functions

 

void lcd_init()

  

void lcd_setRow(unsigned char start, unsigned char end)

  

void lcd_setColumn(unsigned char start, unsigned char end)

 

void lcd_write_C(unsigned char command)

  

void lcd_write_D(unsigned char data)

  

void lcd_pix()

  

unsigned char lcd_read_status(void)

 

void lcd_dimWindow(unsigned char left, unsigned char top, unsigned char right, unsigned char bottom)

 

void lcd_setContrast(unsigned char red, unsigned char green, unsigned char blue)