Improved comments in implementation of button, checkbox, numupdown, tft, touch and screen modules/submodules.

common/tft/tft.c

@@ -5,6 +5,16 @@
 #include <stdio.h>
 #include "filesystem.h"
 
+/* The idea is as follows:
+ * Most of the tft_* functions can be forwarded to the lowlevel implementation.
+ * The exceptions are commented below.
+ * Make sure to have a look at the doxygen comments for the lowlevel functions and for the tft_* functions
+ */
+
+/* Possible improvements:
+ * For formatted printing implement putchar, instead of writing into a buffer and drawing that buffer afterwards
+ */
+
 bool tft_init() {
 	return ll_tft_init();
 
@@ -52,35 +62,41 @@ uint8_t tft_font_width(uint8_t fontnum) {
 	return ll_tft_font_width(fontnum); 
 }
 
+//Print line can be done with multiple calls to draw_char
 void tft_print_line(uint16_t x, uint16_t y, uint16_t color, uint16_t bgcolor, uint8_t font, const char* text) {
-	if(font>=ll_tft_num_fonts()) return;
-	for(int i=0; i<strlen(text); i++) {
-		ll_tft_draw_char(x,y,color,bgcolor, font, text[i]);
-		x+=ll_tft_font_width(font);	
+	if(font>=ll_tft_num_fonts()) return; //invalid font index
+	for(int i=0; i<strlen(text); i++) { //for each char in the line
+		ll_tft_draw_char(x,y,color,bgcolor, font, text[i]); //draw the char
+		x+=ll_tft_font_width(font);	//and increase the x position
 	}
 }
 
+//Printing a formatted line can be done by printing the line in a buffer using "sprintf" and then calling print_line
 void tft_print_formatted(uint16_t x, uint16_t y, uint16_t color, uint16_t bgcolor, uint8_t font, const char* format, ...) {
-	static char buffer[256]; //not sure if that's the best solution. It would propbably better to implement putchar and use vprintf
+	static char buffer[128]; //buffer to save the formatted text into
+
+	//Since we have variable arguments, we need to forward them. We have to use vsprintf instead of sprintf for that.
 	va_list args;
-	va_start (args, format);
-	vsprintf(buffer,format,args);
-	tft_print_line(x,y,color,bgcolor,font,buffer);
-	va_end(args);
+	va_start (args, format); //start the varg-list
+	vsprintf(buffer,format,args); //let vsprintf render the formatted string
+	tft_print_line(x,y,color,bgcolor,font,buffer); //print the string as normal text
+	va_end(args); //end the varg-list
 }
 
 bool tft_draw_bitmap_file_unscaled(uint16_t x, uint16_t y, const char* filename) {
-	//Copied and modified from: http://stackoverflow.com/a/17040962/2606757
+	//This method reads a .bmp file from the filesystem and tries to draw it.
+	//Note: The bmp implementation is not complete, it has some limitations and it makes assumptions. See doxygen comment for this method.
+	//Source Copied and adapted from: http://stackoverflow.com/a/17040962/2606757
 
-	FILE_HANDLE* file = filesystem_file_open(filename);
-	if(file==NULL) {
+	FILE_HANDLE* file = filesystem_file_open(filename); //try to open the file
+	if(file==NULL) { //file opening failed
 		return false;
 	}
 
 	unsigned char info[54];
-	if(filesystem_file_read(file,info,54)!=F_OK) {
+	if(filesystem_file_read(file,info,54)!=F_OK) { //try to read the 54 byte header
 		filesystem_file_close(file);
-		return false;
+		return false; //reading the header failed
 	}
 
 	// extract image height and width from header
@@ -91,22 +107,22 @@ bool tft_draw_bitmap_file_unscaled(uint16_t x, uint16_t y, const char* filename)
 
 	filesystem_file_seek(file,*(uint32_t*)&info[10]); //seek to the place where img data begins
 
-	uint32_t row_padded = (width*depth + 3) & (~3); //row size aligned to 4 bytes
+	uint32_t row_padded = (width*depth + 3) & (~3); //row size must be aligned to 4 bytes
 
-	unsigned char data [row_padded];
+	unsigned char data [row_padded]; //allocate space for one row (incl. padding)
 
-	for(int i = 0; i < height; i++)
+	for(int i = 0; i < height; i++) //for each row
 	{
-		filesystem_file_read(file,data,row_padded);
-		for(int j = 0; j < width*depth; j += depth)
+		filesystem_file_read(file,data,row_padded); //read row into buffer
+		for(int j = 0; j < width*depth; j += depth) //for each pixel
 		{
 			unsigned char a,r,g,b;
-			if(depth==4) {
+			if(depth==4) { //a,r,g,b 8bit each
 				a = data[j];
 				r = data[j+1];
 				g = data[j+2];
 				b = data[j+3];
-			} else if (depth==3) {
+			} else if (depth==3) { // b,g,r, 8bit each
 				a = 255;
 				r = data[j+2];
 				g = data[j+1];
@@ -114,6 +130,7 @@ bool tft_draw_bitmap_file_unscaled(uint16_t x, uint16_t y, const char* filename)
 			}
 
 			if(a!=0) {
+				//bmp's are stored "bottom-up", so we start drawing at the bottom
 				tft_draw_pixel(x+j/depth,y+height-1-i,RGB(r,g,b));
 			}
 		}