Merge pull request #3 from ncmreynolds/dev

Release 0.1.2

README.md

@@ -57,13 +57,13 @@ This project was originally created to help with making a fake 'mainframe' that
 
 Creation and management of GUI-esque objects
 
-* Buttons
-* Checkboxes
-* Radio buttons
-* List boxes
-* Text boxes (editable text) single line editing of text, with support for 'expected' behaviour like home/end/insert/delete and the arrow keys
-* Text boxes (fixed text) with scrollbars, word wrapping and basic markdown support
-* Text boxes (changing text) for 'logging' windows that scroll content
+* [Buttons](examples/Example04_singleButton/README.md)
+* [Checkboxes](examples/Example05_singleCheckbox/README.md)
+* [Radio buttons](examples/Example06_twoRadioButtons/README.md)
+* [List boxes](examples/Example07_oneListBoxSixOptions/README.md)
+* [Text boxes](examples/Example08_oneTextInput/README.md) (editable text) single line editing of text, with support for 'expected' behaviour like home/end/insert/delete and the arrow keys
+* [Text boxes](examples/Example09_oneTextDisplay/README.md) (fixed text) with scrollbars, word wrapping and basic markdown support
+* [Text boxes](examples/Example10_oneTextLog/README.md) (changing text) for 'logging' windows that scroll content
 * Keyboard shortcuts for use without a mouse
 * Basic styling for widget outlines/labels
 
@@ -73,7 +73,7 @@ As you might expect, this library can use a lot of working memory. There is expl
 
 ## Project Status
 
-This is the very first public release, which is working for the specific project I wrote it for. However I'm aware my naming of methods, approaches to passing arguments and so on are messy and inconsistent so some of this may change frequently. This is reflected in the version numbering, which is currently 0.1.0.
+This is the very first public release, which is working for the specific project I wrote it for. However I'm aware my naming of methods, approaches to passing arguments and so on are messy and inconsistent so some of this may change frequently. This is reflected in the version numbering, which is currently 0.1.2.
 
 **[Back to top](#table-of-contents)**
 
@@ -186,7 +186,7 @@ This project uses [Semantic Versioning](http://semver.org/) to be compatible wit
 
 ### Version history
 
-#### 0.1.0
+#### 0.1.2
 
 First public release.
 

documentation/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Change Log
 
+## Version 0.1.2
+
+- Markdown formatting changes
+  - H1 is now inverse
+  - H2 is now bold + underline
+  - H3 is now underline
+  - H4+ is now underline + faint
+- Fixed a bug where omitting the space after # character for a Markdown heading would cause an infinite loop, watchdog error and exception
+- Improvements to overloading/templating of widget functions
+- Scrollbar added to textLog widget
+- `newWidget` and `setWidgetContent` now record the size of the content and ONLY reallocate memory on heap if the new content is larger. This should reduce heap fragmentation if your application makes small changes to content frequently.
+- Internal refactoring
+
 ## Version 0.1.1
 
 - Single key shortcuts would cause a crash. They are now also case-insensitive when typed, but display as set.

documentation/README.md

@@ -35,6 +35,7 @@ This documentation is not absolutely complete, there are a lot of legacy or very
 	1. [Show and hide widgets](#show-and-hide-widgets)
 	1. [Moving and resizing](#moving-and-resizing)
 	1. [Content](#content)
+	1. [Markdown support](#markdown-support)
 	1. [Shortcuts](#shortcuts)
 	1. [Values](#values)
 	1. [Events](#values)
@@ -493,7 +494,7 @@ Due to the limited memory of most microcontrollers, text widgets should be used
 - Radio button (all visible ones for one group)
 - List box
 - Text input (A single line editing field for free form text entry)
-- Text display (Display of static unchanging text information. This widget handles basic MarkDown for styling the content)
+- Text display (Display of static unchanging text information. This widget handles basic [MarkDown](#markdown-support) for styling the content)
 - Text log (Regularly updating text information like a 'log' or 'chat' window. New text can be added at the top or bottom, scrolling the existing text)
 
 You should try the example code on your hardware to see how each type of widget behaves.
@@ -716,17 +717,29 @@ bool deleteWidgetLabel(uint8_t widgetId);
 
 ## Content
 
-The text widgets usually show content as well as the title/label. This is set with the functions below, which will accept most text types.
+The text widgets usually show content as well as the title/label. This is set with the function below, which will accept most text types. There is no specific limit to content length, beyond exhausting the memory of the device.
 
-Content in a `textDisplay` is not expected to change often, if at all. If the content will not change you are strongly advised to use the `F()` macro so it is stored in flash memory.
+```c++
+bool setWidgetContent(uint8_t widgetId, variableType content);
+```
+
+### Text displays
+
+Content in a `textDisplay` is not expected to change dynamically. If the content will not change you are strongly advised to use the `F()` macro so it is stored in flash memory. You can switch between different blocks of content each stored with the `F()` macro and this works quite nicely. So for example setting the content to `F("Offline")` then later `F("Online")` works well.
+
+If you have large ever-changing content, for example something generated with `sprintf`, or read from a file this can cause heap memory fragmentation.
+
+If you do change the content, the library will only free and re-allocate memory once the content is larger than any previously used in the same widget. This is to try and avoid heap memory fragmentation. You can proactively force freeing up memory with `deleteWidgetContent` before setting the new content.
+
+`textDisplay` widgets have limited support for [Markdown](#markdown) formatting when being displayed.
+
+### Text inputs
 
 Content in a `textInput` is expected to change and be read once the user is 'finished editing' and any content you supply will be copied into heap memory and expected to change. The maximum length of the edited text is the space visible onscreen.
 
-Content in a `textLog` is expected to change constantly. Any content you supply will be lost once it scrolls off the top or bottom of the widget, which reserves just enough heap memory for what is currently visible. This can still be quite a lot of memory so in many cases it is worth considering careful use of `setScrollWindow()` and `scroll()` although this requires careful placement of widgets around it.
+### Text logs
 
-```c++
-bool setWidgetContent(uint8_t widgetId, variableType content);
-```
+Content in a `textLog` is expected to change constantly. Any content you supply will be lost once it scrolls off the top or bottom of the widget, which reserves just enough heap memory for what is currently visible. This can still be quite a lot of memory so in many cases it is worth considering careful use of `setScrollWindow()` and `scroll()` although this requires careful placement of widgets around it.
 
 For the `textLog` widget **only**, you can append and prepend content at the top/bottom of the widget scrolling the existing content.
 
@@ -735,6 +748,14 @@ bool appendWidgetContent(uint8_t widgetId, variableType content);
 bool prependWidgetContent(uint8_t widgetId, variableType content);
 ```
 
+### List boxes
+
+The list of options in a list box is added as content like a `textDisplay` and all the other warnings about memory are the same, but each option is separated by a `\r` or `\n`.
+
+So to set the options "One", "Two" and "Three" in a list box you could use `setWidgetContent(widgetId, F("One\rTwo\rThree"));`.
+
+### Other content functions
+
 If you need to clear the content and free up memory you can use this function. If the widget ID exists and had content to delete it returns true.
 
 ```c++
@@ -750,6 +771,22 @@ bool contentOffset(uint8_t widgetId, uint32_t offset);
 
 **[Back to top](#table-of-contents)**
 
+## Markdown support
+
+There is some very limited support for Markdown formatting in some widgets to make the content more visually appealing.
+
+- Four levels of headings prefixed with '# ', '## ', '### ', '#### ' at the start of the line
+- Italic, surrounding the bold text with '_' or '*'
+- Bold, surrounding the italic text with '__' or **'
+- Bold italic, surround the text with '___' or '***'
+- Unordered list, '-' at the start of a line before the list text
+- Horizontal rules, '___' on its own at the start of a line
+- Block quotes, prefixing the block text with '>'
+
+As there are no different character sets available easily in the terminal, these are displayed as mixes of `ATTRIBUTE_BRIGHT`, `ATTRIBUTE_FAINT`, `ATTRIBUTE_UNDERLINE` and `ATTRIBUTE_INVERSE` but help break up a wall of text.
+
+**[Back to top](#table-of-contents)**
+
 ## Shortcuts
 
 The library can attach a keyboard shortcut to a widget that allows it to be selected or 'clicked' with the keyboard. The placement and look of the shortcut is affected by the widget's [style](#styles). It is recommended you try the example code to see how they look.

library.properties

@@ -1,5 +1,5 @@
 name=retroTerm
-version=0.1.1
+version=0.1.2
 author=Nick Reynolds,[email protected]
 maintainer=Nick Reynolds,[email protected]
 sentence=A library for creating user interfaces on an ANSI/VTxxx terminal with a microcontroller