Arduino openGLCD Library Version v1.0rc2 |

All Classes Functions Variables Enumerations Enumerator Groups Pages
Sketch Migration

Warning
  openGLCD is not backward compatible with GLCDv3.

While many of the API functions are the same names, there are differences that will prevent existing code from compiling or working properly.

The primary library include header file name used by GLCDv3 is a different name which will keep existing GLCDv3 code from compiling.
More importantly, width and height parameters to all API functions in openGLCD are exact pixels for the drawn object whereas this was not the case in GLCDv3.
Examples:

- If a width of 6 is specified, the width of the drawn object will be exactly 6 pixels
- If a height of 6 is specified, the height of the drawn object will be exactly 6 pixels

The main include header file for sketches is

#include <openGLCD.h>

If any of the following library functions are used, the code must be modified to use the new function names.
Also, the length parameter will have to be adjusted for the height/width parameters.

- DrawVertLine(x, y, length, color) is now: DrawVLine(x, y, height, color)
- DrawHoriLine(x, y, length, color) is now : DrawHLine(x, y, width, color)
- ClearSysTextLine(row) is now EraseTextLine(row)
- SetTextMode() is now SetAreaMode(mode)

If any of the following GLCDv3 functions are used:

- DrawVLine()
- DrawHLine()
- DrawRect()
- DrawRroundRect()
- FillRect()
- InvertRect()

height and width parameters will will have to be adjusted since openGLCD specifies exact pixels for height and width parameters.

All versions of the function DefineArea() return 0 on sucess or an error code on failure vs GLCDv3 DefineArea() returned a status of true on success and false on failure.

# GLCDv3 Compatibility Header

openGLCD provides a header file to temporarily aid in transitioning existing GLCDv3 sketches to openGLCD. Sketches may include the GLCDv3 compatibility header file just after the main openGLCD header to automatically map the sketches use of GLCDv3 functions and parameters to openGLCD.

#include <openGLCD.h>
#include <include/openGLCD_GLCDv3.h> // header to provide GLCDv3 compatibility

Notable exceptions are the following functions:

- DefineArea()for which there is no backward compatibilty.
  The returns status from this funtion has changed.

Warning
  While using this compatibility header should allow most existing GLCDv3 sketches to compile and work as if they were still using GLCDv3, it is not recommended as a permanent solution.
  Also, it should be noted that when using this backward compability capability, the documention no longer matches the API functions and parameters the sketch is actually using. For example:
  GLCD.DrawRect(0,0, 8, 16); // draw a rectangle 8 pixels wide 16 pixels tall with openGLCD
  GLCD.DrawRect(0,0, 8, 16); // draw a rectangle 9 pixels wide 17 pixels tall with GLCDv3
  The documenation will state that width and height are an exact number of pixels; however, when the sketch is running in GLCDv3 compability mode, the compatibilty header will modify the parameters to be GLCDv3 compatible parameters which draws the objects 1 pixel bigger than the width and height parameters. While this makes the existing sketch code backward compability with GLCDv3, this difference can easily create confusion when looking at results obtained vs parameters passed, vs the documenation.

Note
  For even greater temporary GLCDv3 compatibility, a dummy glcd.h file can be created with the following contents:
  #include <openGLCD.h>
  #include <include/openGLCD_GLCDv3.h>
  which should allow most existing GLCDv3 sketches to work "as is". However, if this is done, GLCDv3 and openGLCD cannot both be installed at the same time since the sketch cannot be assured to get the glcd.h from the openGLCD library.

Warning
  While creating a glcd.h compatibility file can provide instant backward compatiblity to most existing GLCDv3 sketches, it should be cautioned, as mentioned above, that those sketches will be using the functions and parameters as defined in GLCDv3 vs openGLCD. The results obtained from the functions will not match the openGLCD documenation. Therefore, as stated above, this method of backward compability is not recommeded as a permanent solution.