From b67722d64a74ac49abe702e1964a3ddb75f87691 Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Sat, 26 Apr 2014 02:02:36 +0200 Subject: movig docs to /docs --- docs/codingstyle.txt | 162 +++++++++++++++++++++++++++++++++++++++++++++ docs/releases.txt | 182 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 344 insertions(+) create mode 100644 docs/codingstyle.txt create mode 100644 docs/releases.txt (limited to 'docs') diff --git a/docs/codingstyle.txt b/docs/codingstyle.txt new file mode 100644 index 00000000..5a397aeb --- /dev/null +++ b/docs/codingstyle.txt @@ -0,0 +1,162 @@ + uGFX coding style + + +This is a short document describing the preferred coding style for uGFX. + + Chapter 1: Indentation + +Tabs are 4 characters, and thus indentations are also 4 characters. + +Rationale: We like 4 character tabs much better than 8 character tabs. +It is more readable. + + Chapter 2: Placing Braces + +The preferred way, as shown to us by the prophets Kernighan and Ritchie, +is to put the opening brace last on the line, and put the closing brace first, +thusly: + + if (x is true) { + we do y + } + +However, there is one special case, namely functions: they have the +opening brace at the beginning of the next line, thus: + + int function(int x) + { + body of function + } + +We will however accept braces in the general block style for functions +but not the other way around. General blocks MUST have their opening brace +on the same line as the conditional statement. + +Note that the closing brace is empty on a line of its own, _except_ in +the cases where it is followed by a continuation of the same statement, +ie a "while" in a do-statement or an "else" in an if-statement, like +this: + + do { + body of do-loop + } while (condition); + +and + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +Note that closing brace is indented to the level of the start of the block. +Structure definitions are an optional exception. Both of the below style are +acceptable: + + typedef struct { + int a; + ... + } mytype; + + struct mystruct { + int a; + ... + } + + Chapter 3: Naming + +C is a Spartan language, and so should your naming be. Unlike Modula-2 +and Pascal programmers, C programmers do not use cute names like +ThisVariableIsATemporaryCounter. A C programmer would call that +variable "tmp", which is much easier to write, and a lot less +difficult to understand. + +HOWEVER, while long mixed-case names are frowned upon, descriptive names for +global variables are a must. To call a global function "foo" is a +shooting offense. + +GLOBAL variables (to be used only if you _really_ need them) need to +have descriptive names, as do global functions. If you have a function +that counts the number of active users, you should call that +"countActiveUsers()" or similar, you should _not_ call it "cntusr()". + +WHERE long names are required as described above, we prefer the use of +capitalisation on subsequent words (but not the first) rather than underscores +to seperate the words. For example "countActiveUsers()" is preferred to +"count_active_users()" as it is at least as readable and is shorter. + +Encoding the type of a function into the name (so-called Hungarian +notation) is brain damaged - the compiler knows the types anyway and can +check those, and it only confuses the programmer. + +LOCAL variable names should be short, and to the point. If you have +some random integer loop counter, it should probably be called "i". +Calling it "loopCounter" is non-productive, if there is no chance of it +being mis-understood. Similarly, "tmp" can be just about any type of +variable that is used to hold a temporary value. + + Chapter 4: Functions + +Functions should be short and sweet, and do just one thing. + +The maximum length of a function is inversely proportional to the +complexity and indentation level of that function. So, if you have a +conceptually simple function that is just one long (but simple) +case-statement, where you have to do lots of small things for a lot of +different cases, it's OK to have a longer function. + +However, if you have a complex function, and you suspect that a +less-than-gifted first-year high-school student might not even +understand what the function is all about, you should adhere to the +maximum limits all the more closely. Use helper functions with +descriptive names (you can ask the compiler to in-line them if you think +it's performance-critical, and it will probably do a better job of it +that you would have done). + +Another measure of the function is the number of local variables. They +shouldn't exceed 5-10, or you're possibly doing something wrong. Re-think the +function, and split it into smaller pieces. A human brain can +generally easily keep track of about 7 different things, anything more +and it gets confused. You need to understand what you did 2 weeks from now. + +Because uGFX is intended for embedded platforms there are other considerations +that may cause exceptions or emphasise the above. For example, stack space is +a premium. This means that the number of local variables should be minimised as +should the number of parameters. Passing through multiple levels of functions +with lots of parameters is very bad indeed and this can override the desire to +keep functions short and sweet. Clarity however is still essential. + + + Chapter 5: Commenting + +Comments are good, but there is also a danger of over-commenting. NEVER +try to explain HOW your code works in a comment: it's much better to +write the code so that the _working_ is obvious, and it's a waste of +time to explain badly written code. Generally, you want your comments to tell +WHAT your code does, not HOW. + +We use doxygen to document the system. That means that most public functions +are documented in the header defintion file. We do not put doxygen comments in +the source file itself. + +Within the source file, comments should be used to seperate blocks of functions +or definitions within the file. This is to provide clarity to the structure of +the source file itself. An example could be: + /*************************** + * Drawing Functions + ***************************/ + +Single line comments using "//" to start the comment should be used for just that +purpose, to assist in the understanding of that single line. Mutliple single line +comments should never be used to create a block comment. For example, + // This is a very long + // comment spanning several + // lines +is a very bad use of comments. + +Comments within function bodies should be small comments to note or warn +about something particularly clever (or ugly), but try to avoid excess. +Instead, put the comments at the head of a block of code to explain the block +rather than a comment on each line. diff --git a/docs/releases.txt b/docs/releases.txt new file mode 100644 index 00000000..95bda6b1 --- /dev/null +++ b/docs/releases.txt @@ -0,0 +1,182 @@ +***************************************************************************** +*** Releases *** +***************************************************************************** + +current release: 2.0 +FIX: Significant improvements to the way the MCU touch driver works. +FEATURE: Add support for edge to edge touch calibration. +FEATURE: Added progressbar widget +FEATURE: Added gdispGDrawThickLine() by user jpa- +DEPRECATE: TDISP module removed +FIX: Console does not execute gwinPrintf() anymore if not visible +FEATURE: Added gwinGetColor() and gwinGetBgColor() +FEATURE: Console does now have an optional buffer (GWIN_CONSOLE_USE_HISTORY) +FEATURE: Added smooth scrolling to list widget +FEATURE: Increased performance of gwinListAddItem() +FEATURE: Added gfxDeinit() +FEATURE: Allow touch screen calibration in any display orientation +FEATURE: New GFILE module to abstract File IO. +FEATURE: Image file handling changed to use new GFILE module. +DEPRECTATE: Old image opening functions deprecated. +FEATURE: Restructure and simplify the include path for GFX +FEATURE: Added LGDP4532 driver by user shilow +FEATURE: Support for ChibiOS/RT 3.x +FEATURE: Added gwinProgressbarStop() and gwinProgressbarReset() +FEATURE: Added generic ILI93xx driver by xlh1460 + + +*** changes after 1.9 *** +FEATURE: GDISP Streaming API and demos. +DEPRECATE: GDISP_NEED_ASYNC is now deprecated. +DEPRECATE: 3rd party boing demo is now deprecated (replaced by GDISP Streaming demo) +FIX: Remove GOS definitions from demo conf files so that it can be supplied by a makefile. +FEATURE: Repair GDISP low level driver interfaces so they can now be included in the doxygen documentation. +FEATURE: New driver interface for GDISP +FEATURE: Multiple display support +FEATURE: Multiple controller support +FEATURE: Application pixel format no longer has to match the low level driver pixel format. +FEATURE: Many more pixel formats are now supported. +FEATURE: Many performance optimisations +FEATURE: Vertical scrolling is now supported if the low level driver supports read_pixel. +FEATURE: Add gdispFlush() for those controllers that need it +FEATURE: Add GDISP_NEED_AUTOFLUSH and GDISP_NEED_TIMERFLUSH to automatically flush when required. +FEATURE: Add support for generic portrait and landscape orientation modes +FEATURE: Add macro GDISP_DEFAULT_ORIENTATION so an application can specify a default orientation. +FEATURE: Driver files renamed to allow compiles when all object files go in the same directory +FEATURE: New directory structure for board files. Predefined boards have all the hardware definitions predefined. +FEATURE: Board definotions, example projects and makefiles for Win32. +FEATURE: Board definitions, example projects and makefiles for X. +FEATURE: Board definitions, example projects and makefiles for the Olimex SAM7-EX256 board. +Feature: Board definitions, example projects and makefiles for the Olimex STM32-LCD board. +FEATURE: Board definitions, example projects and makefiles for the Mikromedia STM32-M4 board. +FEATURE: Board definitions, example projects and makefiles for the Marlin board. +FEATURE: New invsqrt() routine added to GMISC + + +*** changes after 1.8 *** +FEATURE: GWIN list boxes. +FIX: POSIX port removed, now dedicated OS-X and Linux ports +FIX: Several bugfixes +FEATURE: mcufont integration +FEATURE: SSD1306 driver by user goeck +FEATURE: ST7565 driver by user sam0737 +FEATURE: ED060SC4 driver by user jpa- +FIX: SSD1289 area filling bug fix by user samofab +FEATURE: Added gwinListGetSelectedText() +FEATURE: Added gwinListSetScroll() +FEATURE: Added gwinLabelSetBorder() + + +*** changes after 1.7 *** +FEATURE: Rename of the project from ChibiOS/GFX to uGFX +FEATURE: Moved from github.com to bitbucket.org +FEATURE: New website with a lot more of documentation +FEATURE: Introduced dedicated discussion forum +FEATURE: Complete rework of the widget manager (GWIN) +FEATURE: Added a lot of new widgets +FEATURE: Added gfxRealloc() to the GOS module +FIX: gfxHalt() fix for the Win32 port +FIX: Cleaned up board file mess + + +*** changes after 1.6 *** +FEATURE: Added RA8875 GDISP driver +FEATURE: Added FT5x06 GINPUT/touch driver +FIX: Several bugfixes + + +*** changes after 1.5 *** +FEATURE: Added ILI9325 driver - Thanks to Chris van Dongen aka _Sjaak +FEATURE: Added TDISP module +FIX: tdispGotoXY() renamed to tdispSetCursor() +FEATURE: Addition of GADC, GMISC, GAUDIN, GAUDOUT subsystems +FIX: Removal of the GDISP_LLD() macro +DEPRECATE: Removal of the GDISP VMT +FEATURE: Added SSD2119 GDISP driver +FEATURE: Added GWIN_BUTTON_LAZY_RELEASE macro to disable cancel feature of buttons +FEATURE: Implemented all four orientation modes for the ILI9320 GDISP driver +FIX: Renamed every '__inline' macro to 'inline' for compiler compatibilities +FEATURE: Supporting all standard functions in GDISP Nokia6610GE8 driver +FEATURE: Added STMPE811 GINPUT driver +FEATURE: Added gdispDrawPoly() and gdispFillConvexPoly() +FEATURE: Added arrow button style to GWIN buttons +FEATURE: Added the ability to specify a custom button drawing routine +FEATURE: SSD1963 rework by username 'fred' +FEATURE: Added Picture converter tool +FEATURE: Added slider widget +FEATURE: First MIPS32 (PIC32) board files contributed by user 'Dmytro' +FEATURE: Added gwinDraw() routine +FEATURE: Added GINPUT Dial support and driver using GADC +FEATURE: Simplified assigning inputs to buttons and sliders +FIX: Some fixes for the HD44780 TDISP driver by the user 'Frysk' +FEATURE: Added ILI9481 by user 'Abhishek' +FEATURE: Added enable/disable functions for widgets (Buttons) +FEATURE: Added HX8347D driver by user 'Eddie' +FEATURE: Added enhanced notepad demo by user 'Abhishek' +FEATURE: Added GOS module (including sub modules such as GQUEUE) +FEATURE: Added some functionalities to the TDISP module by user 'Frysk' + + +*** changes after 1.4 *** +FEATURE: GEVENT - for passing event structures from Sources to Listeners +FEATURE: GTIMER - thread context based once-off and periodic timers. +FEATURE: GINPUT - extensible, multiple device-type, input sub-system. +FEATURE: GWIN - full button, console and graph support +FEATURE: Numerous touch calibration improvements +FEATURE: Win32 driver - now support gdisp & ginput mouse/touch/toggle +FEATURE: Win32 driver - full gdisp orientation support +FEATURE: ILI9320 GDISP driver +FEATURE: Nokia6610 GDISP driver split in to GE8 and GE12 variants +FEATURE: Many GDISP drivers changed to use a board interface definition +FEATURE: GFX source restructure with new gfx.h include file. +DEPRECATE: console deprecated - replaced with gwin functionality +DEPRECATE: graph deprecated - replaced with gwin functionality +DEPRECATE: touchscreen deprecated - replaced with ginput functionality +FEATURE: Numerous documentation improvements +FEATURE: Added a number of module demo and test programs +DEPRECATE: Remove of XPT2046 since full compatibility with ADS7843 + + +*** changes after 1.3 *** +FIX: Nokia 6610 fix +FEATURE: New driver: Win32 +FEATURE: implementation of gdispFillArc() +FIX: Hardware accelerate Arc routines +FIX: Fix axis orientation for Arc routines +FEATURE: new gdisp rounded box routines +FEATURE: new gdispDrawStringBox() +FEATURE: GWIN infrastructure +FEATURE: now we fully support doxygen + + +*** changes after 1.2 *** +FEATURE: added FSMC for SSD1289 / F4 +FEATURE: added calibration storage interface +FIX: bugfix in filling functions for SSD1289 +FEATURE: added point_t struct in gdisp.h +FEATURE: added graph module + + +*** changer after 1.1 *** +FIX: orientation macros changed +FIX: huge internal bugfix in orientation stuff (big thanks to Abhishek) +FEATURE: added TOUCHPAD_XY_INVERTED macro +FIX: struct cal renamed to struct cal_t +FIX: SCREEN_WIDTH and SCREEN_HEIGHT renamed to GDISP_SCREEN_WIDTH and GDISP_SCREEN_HEIGHT +FIX: struct TOUCHPAD_t renamed to struct TOUCHPADDriver_t +FIX: struct GConsole renamed to struct GConsole_t +FIX: lcdConsoleXXX() functions have been renamed to gfxConsoleXXX() +FEATURE: FSMC for SSD1289 F2/F4 + + +*** changes after 1.0 *** +FIX: removed gdisp and touchpad prefix of driver directories +UPDATE: added SSD1963 driver +FIX: fixed Validation, VMT driver, console and BitBlit +FEATURE: added clipping support +FEATURE: addad gdispDrawArc() +FEATURE: added SSD1963 DMA support +FEATURE: added touchpad interface for storing calibration values (#define TOUCHPAD_STORE_CALIBRATION) +CHANGE: replaced every GDISP_XXX macro with GDISP_XXX +CHANGE: removed last digit of version number + -- cgit v1.2.3 From 237658f052c64679f2aad223ee6ae839c2ec2b88 Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Sat, 26 Apr 2014 02:08:48 +0200 Subject: Added docs/roadmap.txt --- docs/roadmap.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 docs/roadmap.txt (limited to 'docs') diff --git a/docs/roadmap.txt b/docs/roadmap.txt new file mode 100644 index 00000000..18797487 --- /dev/null +++ b/docs/roadmap.txt @@ -0,0 +1,15 @@ +Things to include in 2.1 (Q2 2014) + - VS1053 audio driver + - FreeRTOS port (finalize) + - GWIN children support (finalize) + - Rreplace the console printf with the one from GFILE + + +Things to include in 2.2 (unknown) + - Support Mikromedia STM32+ board + - Virtual keyboard widget + - LineEdit widget + - RAM file system for GFILE + - FatFS file system for GFILE + - Improve visual aspects of widgets (use gfxBlend()) + - Linux frame buffer support -- cgit v1.2.3 From 8b4ca720369d790ea330bc2189efa05cc557c2f7 Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Sat, 26 Apr 2014 03:27:19 +0200 Subject: Added gwinListEnableRender() --- docs/releases.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/releases.txt b/docs/releases.txt index 95bda6b1..3edfbf4c 100644 --- a/docs/releases.txt +++ b/docs/releases.txt @@ -23,6 +23,7 @@ FEATURE: Added LGDP4532 driver by user shilow FEATURE: Support for ChibiOS/RT 3.x FEATURE: Added gwinProgressbarStop() and gwinProgressbarReset() FEATURE: Added generic ILI93xx driver by xlh1460 +FEATURE: Added gwinListEnableRender() *** changes after 1.9 *** -- cgit v1.2.3 From 135f8f5ecac5bc04bc18438bf78fd7ba82c40816 Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Mon, 28 Apr 2014 23:20:51 +0200 Subject: Added gwinLabelSetAttribute() --- docs/releases.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/releases.txt b/docs/releases.txt index 3edfbf4c..6e234536 100644 --- a/docs/releases.txt +++ b/docs/releases.txt @@ -24,6 +24,7 @@ FEATURE: Support for ChibiOS/RT 3.x FEATURE: Added gwinProgressbarStop() and gwinProgressbarReset() FEATURE: Added generic ILI93xx driver by xlh1460 FEATURE: Added gwinListEnableRender() +FEATURE: Added gwinLabelSetAttribute() *** changes after 1.9 *** -- cgit v1.2.3 From ba1b649fcdd6dbea3af40e263a637b50f6b20242 Mon Sep 17 00:00:00 2001 From: inmarket Date: Tue, 29 Apr 2014 16:53:27 +1000 Subject: Update releases.txt --- docs/releases.txt | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/releases.txt b/docs/releases.txt index 6e234536..ce6b3c9e 100644 --- a/docs/releases.txt +++ b/docs/releases.txt @@ -10,7 +10,7 @@ FEATURE: Added gdispGDrawThickLine() by user jpa- DEPRECATE: TDISP module removed FIX: Console does not execute gwinPrintf() anymore if not visible FEATURE: Added gwinGetColor() and gwinGetBgColor() -FEATURE: Console does now have an optional buffer (GWIN_CONSOLE_USE_HISTORY) +FEATURE: Console now has an optional backing store buffer (GWIN_CONSOLE_USE_HISTORY) FEATURE: Added smooth scrolling to list widget FEATURE: Increased performance of gwinListAddItem() FEATURE: Added gfxDeinit() @@ -20,11 +20,18 @@ FEATURE: Image file handling changed to use new GFILE module. DEPRECTATE: Old image opening functions deprecated. FEATURE: Restructure and simplify the include path for GFX FEATURE: Added LGDP4532 driver by user shilow +FIX: Updated board files to support api changes in ChibiOS/RT 2.6.4 FEATURE: Support for ChibiOS/RT 3.x FEATURE: Added gwinProgressbarStop() and gwinProgressbarReset() FEATURE: Added generic ILI93xx driver by xlh1460 FEATURE: Added gwinListEnableRender() FEATURE: Added gwinLabelSetAttribute() +FEATURE: Complete restructure of the GAUDIN and GAUDOUT into a common GAUDIO module +FEATURE: Added a PWM audio play driver +FEATURE: Update GADC audio recording driver to new GAUDIO format +FEATURE: Added vs1053 audio play driver +FEATURE: Added GAUDIO wave-play demo +FEATURE: Added many GWIN simple demo's and updated the combined widget demo *** changes after 1.9 *** -- cgit v1.2.3 From f4b0eb68f60495cc5e2d883746675ebd29614807 Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Tue, 29 Apr 2014 17:28:14 +0200 Subject: doxygen --- docs/rsc/ugfx_logo_doxygen.png | Bin 0 -> 12725 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/rsc/ugfx_logo_doxygen.png (limited to 'docs') diff --git a/docs/rsc/ugfx_logo_doxygen.png b/docs/rsc/ugfx_logo_doxygen.png new file mode 100644 index 00000000..666ee2ec Binary files /dev/null and b/docs/rsc/ugfx_logo_doxygen.png differ -- cgit v1.2.3