diff --git a/graphics/lvgl/README.md b/graphics/lvgl/README.md deleted file mode 100644 index a3c846a8d..000000000 --- a/graphics/lvgl/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# Graphics / `lvgl` LVGL - -## Usage - -Import with `#include ` or `#include `. - -Upstream example ported to NuttX is present at `examples/lvgldemo`. - -LVGL can be used with framebuffer device. To find example boards with this -preconfigured, search for `CONFIG_GRAPHICS_LVGL=y` in `defconfig` files. All of -them have also `CONFIG_VIDEO_FB=y` present. - -As a second option, LVGL can talk to a display driver and explicitly draw line -by line. For this case, there is no preconfigured board present. Go to _Porting_ -section of upstream documentation for more hints. - -## Resources - -- [API documentation with examples](https://docs.lvgl.io/latest/en/html/index.html) -- [GitHub / LVGL / LVGL library](https://github.com/lvgl/lvgl) -- [GitHub / LVGL / Examples, tutorials, applications](https://github.com/lvgl/lv_examples) -- [GitHub / LVGL / Desktop simulator](https://github.com/lvgl/lv_sim_eclipse_sdl) -- [GitHub / LVGL / Web simulator](https://github.com/lvgl/lv_sim_emscripten) diff --git a/graphics/nxwidgets/Doxygen/README.md b/graphics/nxwidgets/Doxygen/README.md deleted file mode 100644 index dc38ed5da..000000000 --- a/graphics/nxwidgets/Doxygen/README.md +++ /dev/null @@ -1,68 +0,0 @@ -# Graphics / `nxwidgets` NXWidgets / Doxygen - -This directory contains the documentation automatically generated by Doxygen. - -## Contents - -- Installing the necessary packages in Ubuntu -- Generating documentation -- References - -## Installing the Necessary Packages in Ubuntu - -1. Install the following packages. - - ```bash - $ sudo aptitude install doxygen doxygen-doc doxygen-gui dot2tex graphviz - ``` - -2. (Optional) Install Doxygen from the latest sourcode. - - The Ubuntu package is outdated. The newer the version of Doxygen, the better - the documentation looks. - - Place yourself in some temporary folder where you can download the source, - and run [1]: - - ```bash - $ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn - $ cd doxygen-svn - $ ./configure - $ make - $ make install - ``` - -## Generating Documentation - -Two ways described here: - -1. Use the provided `gendoc.sh` script. - - ```bash - trunk/NXWidgets/Doxygen/gendoc.sh - ``` - - The script only needs the argument to the absolute path where to place the - generated documentation. I.e.: - - ```bash - $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ - $ mkdir doc - $ ./gendoc.sh $PWD/doc - ``` - -2. Using the `Doxyfile` directly: - - The file `Doxyfile` contains the configuration of the Doxygen settings for - the run, edit only if necessary. - - To generate the documentation type: - - ```bash - $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ - $ doxygen Doxyfile - ``` - -## References - -[1] http://www.stack.nl/~dimitri/doxygen/download.html diff --git a/graphics/nxwidgets/README.md b/graphics/nxwidgets/README.md deleted file mode 100644 index 5fc93f371..000000000 --- a/graphics/nxwidgets/README.md +++ /dev/null @@ -1,68 +0,0 @@ -# Graphics / `nxwidgets` NXWidgets - -In order to better support NuttX based platforms, a special graphical user -interface has been created called NXWidgets. NXWidgets is written in C++ and -integrates seamlessly with the NuttX NX graphics subsystem in order to provide -graphic objects, or _widgets_, in the NX Graphics Subsystem - -Some of the features of NXWidgets include: - -- Conservative C++ - - NXWidgets is written entirely in C++ but using only selected _embedded - friendly_ C++ constructs that are fully supported under NuttX. No additional - C++ support libraries are required. - -- NX Integration - - NXWidgets integrate seamlessly with the NX graphics system. Think of the X - server under Linux – the NX graphics system is like a tiny X server that - provides windowing under NuttX. By adding NXWidgets, you can support graphics - objects like buttons and text boxes in the NX windows and toolbars. - -- Small Footprint - - NXWidgets is tailored for use MCUs in embedded applications. It is ideally - suited for mid- and upper-range of most MCU families. A complete NXWidgets is - possible in as little as 40Kb of FLASH and maybe 4Kb of SRAM. - -- Output Devices - - NXWidgets will work on the high-end frame buffer devices as well as on LCDs - connected via serial or parallel ports to a small MCU. - -- Input Devices - - NXWidgets will accept position and selection inputs from a mouse or a - touchscreen. It will also support character input from a keyboard such as a - USB keyboard. NXWidgets supports on very special widget called `CKeypad` that - will provide keyboard input via an on-screen keypad that can be operated via - mouse or touchscreen inputs. - -- Many Graphic Objects - - Some of the graphic objects supported by NXWidgets include labels, buttons, - text boxes, button arrays, check boxes, cycle buttons, images, sliders, - scrollable list boxes, progress bars, and more. - -**Note**: Many of the fundamental classed in NxWidgets derive from the Antony -Dzeryn's _Woopsi_ project: http://woopsi.org/ which also has a BSD style -license. See the `COPYING` file for details. - -## Directory Structure - -- `Kconfig` - - This is a `Kconfig` file that should be provided at `apps/NxWidgets/Kconfig`. - When copied to that location, it will be used by the NuttX configuration - systems to configure settings for NxWidgets and NxWM - -- `nxwidgets` - - The source code, header files, and build environment for NxWidgets is provided - in this directory. - -- `UnitTests` - - Provides a collection of unit-level tests for many of the individual widgets - provided by `nxwidgets`. diff --git a/graphics/nxwidgets/UnitTests/README.md b/graphics/nxwidgets/UnitTests/README.md deleted file mode 100644 index b96875485..000000000 --- a/graphics/nxwidgets/UnitTests/README.md +++ /dev/null @@ -1,259 +0,0 @@ -# Graphics / NXWidgets / Unit Tests - -This directory contains a collection of Unit Tests that can be used to verify -NXWidgets.: - -## Contents - -**Installing and Building the Unit Tests** - -1. Setup NuttX - 1. Configure NuttX - 2. Enable C++ Support - 3. Enable Debug Options - 4. Special configuration requirements for the nxwm unit test - 5. Other `.config` file changes – NSH configurations only - 6. Other `.config` file changes – NON-NSH configurations only -2. Adjust the Stack Size -3. Build NuttX including the unit test and the NXWidgets library - -**Work-Arounds** - -1. Build Issues - -**Unit Test Directories** - -## Installing and Building the Unit Tests - -1. Setup NuttX - - 1. Configure NuttX - - Configure NuttX to run one of the target configurations. For example, - let's assume that you are using the `sim/nsh2` configuration. The - `sim/nsh2` configuration was specially created for use NXWidgets on the - simulation platform. A similar, special configuration `stm3210e-eval/nsh2` - is also for the `STM3210E-EVAL` available. However, the unit test can be - run on other configurations (see steps d and e below). - - **Note**: There are some other special configurationsrecommended for - unit-leveling testing of NxWM because the configuration is more complex in - that case. These are: - - 1) `sim/nxwmm`, or the simulated platform (no touchscreen), and - 2) `stm3240g-evel`, for the `STM3240G-EVAL` board (with the STMPE11 - touchscreen) - - We will assume the `sim/nsh2` configuration in this discussion. The - `sim/nsh2` configuration is installed as follows: - - ```bash - cd - make distclean - tools/configure.sh sim:nsh2 - ``` - - Where: - - `` is the full, absolute path to the NuttX build - directory - - If you are using the `sim/nsh2` or `stm3210e-eval` configurations, then - skip to step 2 (Hmmm.. better check 1d) too). - - There may be certain requirements for the configuration that you select... - for example, certain widget tests may require touchscreen support or - special font selections. These test-specific requirements are addressed - below under _Unit Test Directories_ - - 2. Enable C++ Support - - If you are not using the `sim/nsh2` or `stm3210e-eval`, you will need to - add the following definitions to the NuttX configuration at - `nuttx/.config` to enable C++ support: - - ```conf - CONFIG_HAVE_CXX=y - ``` - - Check first, some configurations already have C++ support enabled (As of - this writing **ONLY** the `sim/nsh2` and `stm321-e-eval` configurations - have C++ support pre-enabled). - - 3. Enable Debug Options - - If you are running on a simulated target, then you might also want to - enable debug symbols: - - ```conf - CONFIG_DEBUG_SYMBOLS=y - ``` - - Then you can run the simulation using GDB or DDD which is a very powerful - debugging environment! - - 4. Special configuration requirements for the nxwm unit test. - - ```conf - CONFIG_NXTERM=y - ``` - - 5. Other `.config` file changes – NSH configurations only. - - If the configuration that you are using supports NSH and NSH built-in - tasks then all is well. If it is an NSH configuration, then you will have - to define the following in your `nuttx/.config` file as well (if it is not - already defined): - - ```conf - CONFIG_NSH_BUILTIN_APPS=y - ``` - - `sim/nsh2` and `stm3210e-eval/nsh2` already has this setting. You do not - need to change anything further in the `nuttx/.config` file if you are - using either of these configurations. - - 6. Other `.config` file changes – NON-NSH configurations only. - - Entry Point. You will need to set the entry point in the .config file. For - NSH configurations, the entry point will always be `nsh_main` and you will - see that setting like: - - ```conf - CONFIG_INIT_ENTRYPOINT="nsh_main" - ``` - - If you are not using in NSH, then each unit test has a unique entry point. - That entry point is the name of the unit test directory in all lower case - plus the suffix `_main`. So, for example, the correct entry for the - `UnitTests/CButton` would be: - - ```conf - CONFIG_INIT_ENTRYPOINT="cbutton_main" - ``` - - And the correct entry point for `UnitTests/nxwm` would be: - - ```conf - CONFIG_INIT_ENTRYPOINT="nxwm_main" - ``` - - etc. - - For non-NSH configurations (such as the `sim/touchscreen`) you will have - to remove the configuration setting that provided the `main` function so - that you use the `main` in the unit test code instead. So, for example, - with the `sim/touchscreen` configuration you need to remove the following - from the NuttX configuration file (`.config`): - - ```conf - CONFIG_EXAMPLES_TOUSCHCREEN=y ## REMOVE (provided "tc_main") - ``` - -2. Adjust the Stack Size - - If using an simulation configuration (like `sim/nsh2`) and your unit test - uses X11 as its display device, then you would have to increase the size of - unit test stack as described below under _Stack Size Issues with the X11 - Simulation_. - -3. Build NuttX including the unit test and the NXWidgets library - - ```bash - cd - . ./setenv.sh - make - ``` - -## Work-Arounds - -### Build Issues - -1. I have seen this error on Cygwin building C++ code: - - ``` - LD: nuttx.rel - ld: skipping incompatible /home/patacongo/projects/nuttx/nuttx/trunk/nuttx/libxx//liblibxx.a when searching for -llibxx - ld: cannot find -llibxx - ``` - - The problem seems to be caused because `gcc` build code for 32-bit mode and - `g++` builds code for 64-bit mode. Add the `-m32` option to the `g++` command - line seems to fix the problem. In `Make.defs`: - - ```makefile - CXXFLAGS = -m32 $(ARCHWARNINGSXX) $(ARCHOPTIMIZATION) \ - $(ARCHCXXFLAGS) $(ARCHINCLUDESXX) $(ARCHDEFINES) $(EXTRADEFINES) -pipe - ``` - -2. Stack Size Issues with the X11 Simulation - - When you run the NuttX simulation, it uses stacks allocated by NuttX from the - NuttX heap. The memory management model is exactly the same in the simulation - as it is real, target system. This is good because this produces a higher - fidelity simulation. - - However, when the simulation calls into Linux/Cygwin libraries, it will still - use these small simulation stacks. This happens, for example, when you call - into the system to get and put characters to the console window or when you - make x11 calls into the system. The programming model within those libraries - will assume a Linux/Cygwin environment where the stack size grows dynamically - - As a consequence, those system libraries may allocate large data structures - on the stack and overflow the small NuttX stacks. X11, in particular, - requires large stacks. If you are using X11 in the simulation, make sure that - you set aside a "lot" of stack for the X11 system calls (maybe 8 or 16Kb). - The stack size for the thread that begins with user start is controlled by - the configuration setting `CONFIG_INIT_STACKSIZE`; you may need to - increase this value to larger number to survive the X11 system calls. - - If you are running X11 applications as NSH add-on programs, then the stack - size of the add-on program is controlled in another way. Here are the steps - for increasing the stack size in that case: - - ```bash - cd ../apps/namedapps # Go to the namedapps directory - vi namedapps_list.h # Edit this file and increase the stack size of the add-on - rm .built *.o # This will force the namedapps logic to rebuild - ``` - -## Unit Tests - -The following provide simple unit tests for each of the NXWidgets. In addition, -these unit tests provide examples for the use of each widget type. - -- `CButton` - - Exercises the `CButton` widget. - - Depends on `CLabel`. -- `CButtonArray` - - Exercises the `CButtonArray` widget. -- `CCheckBox` - - Exercises the `CCheckBox` widget. - - Depends on `CLabel` and `CButton`. -- `CGlyphButton` - - Exercises the `CGlyphButton` widget. - - Depends on `CLabel` and `CButton`. -- `CImage` - - Exercises the `CImage` widget. -- `CLabel` - - Exercises the `CLabel` widget. -- `CProgressBar` - - Exercises the `CProgressBar` widget. -- `CRadioButton` - - Exercises the `CRadioButton` and `CRadioButtonGroup` widgets. - - Depends on `CLabel` and `CButton`. -- `CScrollBarHorizontal` - - Exercises the `ScrollbarHorizontal`. - - Depends on `CSliderHorizontal` and `CGlyphButton`. -- `CScrollBarVertical` - - Exercises the `ScrollbarHorizontal`. - - Depends on `CSliderVertical` and `CGlyphButton`. -- `CSliderHorizontal` - - Exercises the `CSliderHorizontal`. - - Depends on `CSliderHorizontalGrip`. -- `CSliderVertical` - - Exercises the `CSliderVertical`. - - Depends on `CSliderVerticalGrip`. -- `CTextBox` - - Exercises the `CTextBox` widget. - - Depends on `CLabel`. diff --git a/graphics/nxwm/Doxygen/README.md b/graphics/nxwm/Doxygen/README.md deleted file mode 100644 index cf4436347..000000000 --- a/graphics/nxwm/Doxygen/README.md +++ /dev/null @@ -1,68 +0,0 @@ -# Graphics / `nxwm` NxWM / Doxygen - -This directory contains the documentation automatically generated by Doxygen. - -## Contents - -- Installing the necessary packages in Ubuntu -- Generating documentation -- References - -## Installing the necessary packages in Ubuntu - -1. Install the following packages. - - ```bash - $ sudo aptitude install doxygen doxygen-doc doxygen-gui dot2tex graphviz - ``` - -2. (Optional) Install Doxygen from the latest sourcode. - - The Ubuntu package is outdated. The newer the version of Doxygen, the better - the documentation looks. - - Place yourself in some temporary folder where you can download the source, - and run [1]: - - ```bash - $ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn - $ cd doxygen-svn - $ ./configure - $ make - $ make install - ``` - -## Generating documentation - -Two ways described here: - -1. Use the provided `gendoc.sh` script. - - ```bash - trunk/NXWidgets/Doxygen/gendoc.sh - ``` - - The script only needs the argument to the absolute path where to place the - generated documentation. I.e.: - - ```bash - $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ - $ mkdir doc - $ ./gendoc.sh $PWD/doc - ``` - -2. Using the `Doxyfile` directly: - - The file `Doxyfile` contains the configuration of the Doxygen settings for - the run, edit only if necessary. - - To generate the documentation type: - - ```bash - $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/ - $ doxygen Doxyfile - ``` - -## References - -[1] http://www.stack.nl/~dimitri/doxygen/download.html diff --git a/graphics/nxwm/README.md b/graphics/nxwm/README.md deleted file mode 100644 index 2578a46f2..000000000 --- a/graphics/nxwm/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# Graphics / `nxwm` NxWM - -This directory holds a tiny desktop for small embedded devices with a -touchscreen,. NxWM. NxWM is true multiple window manager but only one window is -displayed at a time. This simplification helps performance on LCD based products -(in the same way that a tiled window manager helps) and also makes the best use -of small displays. It is awkward from a human factors point-of-view trying to -manage multiple windows on a small display. - -The window manager consists of a task bar with icons representing the running -tasks. If you touch the task's icon, it comes to the top. Each window has a -toolbar with (1) a title, (2) a minimize button, and (3) a stop application -button using the standard icons for these things. - -There is always a start window that is available in the task bar. When you touch -the start window icon, it brings up the start window containing icons -representing all of the available applications. If you touch an icon in the -start window, it will be started and added to the task bar. - -There is a base class that defines an add-on application and an interface that -supports incorporation of new application. The only application that is provided -is NxTerm. This is an NSH session running in a window. You should be able to -select the NX icon in the start menu and create as many NSH sessions in windows -as you want. (keybard input still comes through serial). - -Note 1: NwWM requires `NuttX-7.19` or above to work with the current -`NxWidgets-1.18` release. diff --git a/graphics/tiff/README.md b/graphics/tiff/README.md deleted file mode 100644 index dd4620715..000000000 --- a/graphics/tiff/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Graphics / `tiff` TIFF Creation Library - -This directory contains a library that can be used to create TIFF image files. -This file was created for the purpose of supporting screen dumps from an LCD. -Howeve, the logic is general and could be used for most any purpose. - -The only usage documentation is in the (rather extensive) comments in the file -`apps/include/tiff.h`. - -## Unit Test - -See `apps/examples/tiff`. diff --git a/graphics/twm4nx/README.md b/graphics/twm4nx/README.md deleted file mode 100644 index 5c594b94d..000000000 --- a/graphics/twm4nx/README.md +++ /dev/null @@ -1,386 +0,0 @@ -# Graphics / `twm4nx` Tab Window Manager (TWM) - -Twm4Nx is a port of twm, Tab Window Manager (or Tom's Window Manager) version -`1.0.10` to NuttX NX windows server. No, a port is not the right word. It is a -re-design of TWM from the inside out to work with the NuttX NX server. The name -Twm4Nx reflects this legacy. But Twm4Nx is more a homage to TWM than a port of -TWM. - -The original TWM was based on X11 which provides a rich set of features. TWM -provided titlebars, shaped windows, several forms of icon management, -user-defined macro functions, click-to-type and pointer-driven keyboard focus, -graphic contexts, and user-specified key and pointer button bindings, etc. - -Twm4Nx, on the other hand is based on the NuttX NX server which provides -comparatively minimal support. Additional drawing support comes from the NuttX -NxWidgets library (which necessitated the change to C++). - -Twm4Nx is greatly stripped down and targeted on small embedded systems with -minimal resources. For example, no assumption is made about the availability of -a file system; no `.twmrc` file is used. Bitmaps are not used (other than for -fonts). - -The TWM license is, I believe compatible with the BSD license used by NuttX. The -origin TWM license required notice of copyrights within each file and a full -copy of the original license which you can find in the `COPYING` file. within -this directory. - -## Status - -### Progress - -- `2019-04-28` This port was brutal. Much TWM logic was removed because it - depended on X11 features (or just because I could not understand how to use - it). The replacement logic is only mostly in place but more needs to be done - to have a complete system (hence, it is marked `EXPERIMENTAL`). The kinds of - things that need to done are: - - 1. Right click should bring up a window list (like the icon manager???) - 2. For TWM-like behavior, a window frame and toolbar should be highlighted - when the window has focus. - 3. A right click on the toolbar should bring up a window-specific menu. - -- `2019-05-02` Some testing progress. The system comes up, connects to and - initializes the VNC window. For some reason, the VNC client breaks the - connection. The server is no longer connected so Twm4Nx constipates and and - eventually hangs. - -- `2019-05-08` I abandoned the VNC interface and found that things are much - better using a direct, hardware framebuffer. The background comes up properly - and the Icon Manager appears properly in the upper right hand corner. The Icon - Manager Window can be iconified or de-iconified. The Icon Manager window can - be grabbed by the toolbar title and moved about on the window (the movement is - not very smooth on the particular hardware that I am working with). - -- `2019-05-10` A left click on the background brings up the main menu. At - present there are only two options: _Desktop_ which will iconify all windows - and _Twm4Nx Icon Manager_ which will de-iconify and/or raise the Icon Manager - window to the top of the hierarchy. That latter option is only meaningful when - the desktop is very crowded. - -- `2019-05-13` Added the NxTerm application. If enabled via - `CONFIG_TWM4XN_NXTERM`, there will now be a _NuttShell_ entry in the Main - Menu. When pressed, this will bring up an NSH session in a Twm4Nx window. - -- `2019-05-14` We can now move an icon on the desktop. Includes logic to avoid - collisions with other icons and with the background image. That later is an - issue. The background image image widget needs to be removed; it can occlude a - desktop icon. We need to paint the image directly on the background without - the use of a widget. - -- `2019-05-15` Resizing now seems to work correctly in Twm4Nx. - -- `2019-05-20` Calibration screen is now in place. - -- `2019-05-21` A `CONTEMPORARY` theme was added. Still has a few glitches. - -- `2019-06-01` A retro, emulated segment LCD clock is now in place. - -## How To - -### Icon Manager - -- At start up, only the Icon Manager window is shown. The Icon Manager is a TWM - alternative to more common desktop icons. Currently Twm4Nx supports both - desktop icons and the Icon Manager. - - Whenever a new application is started from the Main Menu, its name shows up in - the Icon Manager. Selecting the name will either de-iconify the window, or - just raise it to the top of the display. - -### Main Menu: - -- A touch/click at any open location on the background (except the image at the - center or on another icon) will bring up the Main Menu. Options: - - Desktop. Iconify all windows and show the desktop - - Twm4Nx Icom Manager. De-iconify and/or raise the Icon Manager to the top of - the display. - - Calibration. Perform touchscreen re-calibration. - - Clock. Start and instance of clock in the window. The uses the the retro, - LCD emulation of `apps/graphics/slcd`. - - NuttShell. Start and instance of NSH running in an NxTerm. -- All windows close after the terminal menu option is selected. - -### Window Toolbar - -- Most windows have a toolbar at the top. It is optional but used in most - windows. -- The toolbar contains window title and from zero to 4 buttons: - - Right side: A menu button may be presented. The menu button is not used by - anything in the current implementation and is always suppressed - - Left side: The far left is (1) the terminate button (if present). If - present, it will close window when selected. Not all windows can be closed. - You can't close the Icon Manager or menu windows, for example. Then (2) a - resize button. If presented and is selected, then the resize sequence - described below it started. This may the be preceded by a minimize button - that iconifies the window. - -### Moving a Window: - -- Grab the title in the toolbar and move the window to the desired position. - -### Resizing a Window: - -- A window must have the green resize button with the square or it cannot be - resized. -- Press resize button. A small window should pop-up in the upper left hand - corner showing the current window size. -- Touch anywhere in window (not the toolbar) and slide your finger. The resize - window will show the new size but there will be no other update to the - display. It is thought that continuous size updates would overwhelm lower end - MCUs. Movements support include: - - Move toward the right increases the width of the window - - Move toward the left decreases the width of the window - - Move toward the bottom increases the height of the window - - Move toward the top decreases the height of the Window - - Other moves will affect both the height and width of the window. -- **Note**: While resizing, non-critical events from all other windows are - ignored. - -### Themes - -- There are two themes support by the configuration system: - - `CONFIG_TWM4NX_CLASSIC` – Strong bordered windows with dark primary colors. - Reminiscent of Windows 98. - - `CONFIG_TWM4NX_CONTEMPORARY` – Border-less windows in pastel shades for a - more contemporary look. - -## Issues: - -`2019-05-16` Twm4Nx is in a very complete state but only at perhaps _alpha_ in -its maturity. You should expect to see some undocumented problems. If you see -such problems and can describe a sequence to actions to reproduce the problem, -let me know and I will try to resolve the problems. - -Here are all known issues and features that are missing: - -TWM Compatibilities Issues: -1. Resizing works a little differently in Twm4Nx. -2. Right click should bring up a window list -3. For TWM-like behavior, a window frame and toolbar should be highlighted when - the window has focus. -4. A right click on the toolbar should bring up a window-specific menu. - -There are no near-term plans to address these compatibility issues. - -Other issues/bugs. All-in-all, I would say that Twm4Nx is maturing well and is -attaining stability. That being said, there are some issues and untested -functionality that should be addressed: - -1. Icon drag movement includes logic to avoid collisions with other icons and - with the background image. That later is an issue. We need to paint the image - directly on the background without the use of a widget. -2. There are a few color artifacts in the toolbar of the `CONTEMPORARY` theme. - These look like borders are being drawn around the toolbar widgets (even - though the are configured to be borderless). -3. Most Twm4Nx configuration settings are hard-coded in `*_config.hxx` header - files. These all need to be brought out and made accessible via Kconfig files -4. I have seen some odd behavior when many NxTerm windows have been opened - (around 15). Specifically, I see failures to start NSH in the windows so they - come up blank. All other behaviors seem normal. Most likely, some NxTerm - resource allocation is failing silently and leaving things in an unusable - state. The board I am using has 128Mb of SDRAM so I can't believe that memory - is the limiting factor. These are, however, RAM-backed windows and will use - significant amounts of memory. The primary issue is that the number of - windows should probably be managed in some way to assure that the end-user - does not experience odd behaviors when resource usage is high. -5. Menus with sub-menus have not been verified. There is no use of sub- menus in - the current code base so I expect that there are issues when, for example, - and item from a sub-menu item: That menu and all of its antecedent menus - should be closed. -6. There is an optional MENU button that may appear at the far left on the - toolbar. It is not used by any window in the current code base and, hence, is - unverified. I would expect some issues with generating and routing the MENU - button events to applications. There are likely other unverified features. -7. X/Y input may be either via a touchscreen or a mouse. Only touchscreen input - has been verified. There is, however, very little difference. The primary - issue is in cursor support: Cursors are needed with a mouse. Cursor images - also change depending on the state (like grabbing and dragging or resizing). - There is also a possibility of using auto-raise with a mouse as well. All of - this logic is in place, but none has been verified. -8. NxTerm windows really need to be scrollable. They are difficult to use with - only a few lines on a small display. A related usability issue is the font - height: The fonts report a maximum font height that results in a large line - spacing on the display and, hence, fewer lines visible in the small window. - This is latter issues is a problem with the fonts not Twm4Nx, however. -9. There is a trivial rounding error in the calculation of the LCD width in - `SLcd::CSLcd::getWidth()`. It currently truncates down. It needs to round up. - This sometimes leaves a small, one-pixel- wide sliver on the clock display. - This display always recovers and this only cosmetic. - -## Adding Twm4Nx Applications - -### Application Factories and the Main Menu - -The original TWM supported a .twmrc in which you could describe application -programs supported on the desktop. Currently no such start-up file is available -for Twm4Nx. Rather, all applications must be added via run-time interfaces. And -overview of these interfaces is provided in this paragraph. - -Currently, there are only two applications developed for Twm4Nx: (1) An NxTerm -hosting NSH that is analogous to an XTerm hosting the Bash shell in a Unix -environment, and (2) a touchscreen calibration application. Let's focus instead -on the NxTerm application as an example because the touchscreen calibration is a -rather unusual beast. - -These example applications can be found at: `apps/graphics/twm4nx/apps` and -`apps/include/graphics/twm4nx/apps` - -In short, adding an application involves a _Factory Object_ that is hooked into -the Main Menu. A Factory Object is an object that is used to create other object -instances. The way in which the Factory Object is represented is purely a -decision of the application developer. One option, however, is to use the pure -virtual base class `IApplicationFactory` as defined in -`apps/include/graphics/twm4nx/iapplication.hxx`. This base class provides only a -single method: - -```cpp -bool initialize(FAR CTwm4Nx *twm4nx); -``` - -where CTwm4Nx is the Twm4NX session instance that allows the class -implementation to interact with session specific resources. Multiple sessions -would be required, for example, if the platform supported multiple displays. - -In practice, the application factory implementation class inherits from the -following base classes: - -1. `IApplicationFactory`. Provides the common `initialize()` method. -2. `IApplication`. Provides the information for the application's entry in the - Main Menu -3. `CTwm4NxEvent`. Hooks the application factory into the Twm4Nx event - notification system. - -Initialization consists of instantiating the application factory instance and -calling its `IApplicationFactory::initialize()` method. The application factory -instance is a singleton that must persist for the life of the session. For the -NxTerm application factory, this is done in -`apps/graphics/twm4nx/src/twm4nx_main.c` like: - -```cpp -CNxTermFactory nxtermFactory; -success = nxtermFactory.initialize(twm4nx); -``` - -In addition to general initialization, the `IApplicationFactory::initialize()` -method must register a new entry with the main menu. You can see an example of -this in `apps/graphics/twm4nx/apps/cnxterm.c`: - -```cpp -FAR CMainMenu *cmain = twm4nx->getMainMenu(); -return cmain->addApplication(this); -``` - -The argument to the `CMainMenu::addApplication()` method is of type -`IApplication *`. Remember, however, that our application implementation `class` -inherited from `IApplication`. - -The IApplication pure virtual base class is also defined in -`apps/include/graphics/twm4nx/iapplication.hxx`. It essentially describes what -the Main Menu logic should do when the menu item is selected. It includes these -methods: - -1. `getName()`. Provides the name string that will be shown in the Main Menu for - this selection. -2. `getSubMenu()`. One possibility is that selecting the Main Menu item is that - it may bring up yet another sub-menu of options. -3. `getEventHandler()`. Returns an instance of `CTwm4NxEvent` that is used to - route menu selection events. Remember that our application factory inherits - from `CTwm4NxEvent` so this function only needs to return the 'this' - pointer. -4. `getEvent()`. Provides the event ID that will be used in the event - notification. The returned value must conform to the description in - `apps/include/graphics/twm4nx/twm4nx_events.hxx`. In particular, the - recipient of the event must be `EVENT_RECIPIENT_APP`. - -The Twm4Nx application is then started when the application factory's -`CTwm4NxEvent::event()` method is called with the specified event. - -### Application Windows - -How the application factory starts an application instance is purely up to the -application designer. Typically this would include starting a new application -task. General characteristics of an application include: - -1. It probably should inherit from `CTwm4NxEvent` so that it can receive events - from the system. -2. To create the window, it must instantiate and initialize an instance of - `CWindow`. -3. It must configure application events to receive notifications from Twm4Nx. - -To create an application window, the application must call the -`CWindowFactory::createWindow()` method. For the NxTerm example, this looks -like: - -```cpp -NXWidgets::CNxString name("NuttShell"); - -uint8_t wflags = (WFLAGS_NO_MENU_BUTTON | WFLAGS_HIDDEN); - -FAR CWindowFactory *factory = m_twm4nx->getWindowFactory(); -m_nxtermWindow = factory->createWindow(name, &CONFIG_TWM4NX_NXTERM_ICON, - (FAR CIconMgr *)0, wflags); -``` - -The window factory is another factory that creates and manages window instance. -The `createWindow()` method requires four parameters: - -1. The name of the window. This is the name that is show in the window toolbar - and may be the same name as was used in the Main Menu entry. -2. A reference to the the Icon image associated with the window. This is the - image that is show on the desktop when the window is iconified. It is of - type `NXWidgets::SRlePaletteBitmap`. -3. A pointer to the Icon Manager instance that this window belongs with. This - can be NULL to use the default Twm4Nx Icon Manager. -4. A set of flags that describe properties of the windows. - - The flag values are defined byte `WFLAGS_*` definitions provided in - `apps/include/graphics/twm4nx/cwindow.hxx`: - - - `WFLAGS_NO_MENU_BUTTON` – Omit the menu button from the toolbar. - - `WFLAGS_NO_DELETE_BUTTON` – Omit the delete button from the toolbar. - - `WFLAGS_NO_RESIZE_BUTTON` – Omit the resize button from the toolbar. - - `WFLAGS_NO_MINIMIZE_BUTTON` – Omit the minimize button from the toolbar. - - `WFLAGS_NO_TOOLBAR` – Omit the toolbar altogether. - - `WFLAGS_ICONMGR` – This window is an icon manager. - - `WFLAGS_MENU` – This window is a menu window. - - `WFLAGS_HIDDEN` – Start with the window hidden. - -Once the `CWindow` is instantiated, events needed by the application can be -configured as is done in the NxTerm application: - -```cpp -struct SAppEvents events; -events.eventObj = (FAR void *)this; -events.redrawEvent = EVENT_NXTERM_REDRAW; -events.resizeEvent = EVENT_NXTERM_RESIZE; -events.mouseEvent = EVENT_NXTERM_XYINPUT; -events.kbdEvent = EVENT_NXTERM_KBDINPUT; -events.closeEvent = EVENT_NXTERM_CLOSE; -events.deleteEvent = EVENT_NXTERM_DELETE; - -bool success = m_nxtermWindow->configureEvents(events); -``` - -Again, recall that the application inherits from `CTwm4NxEvent`. So passing -`this` as the event object above assures that the specific events are routed to -the application instance. - -Drawing in the application window can be performed using that facilities of -NXWidgets using the `NXWidgets::CGraphicsPort` associated with the window. The -NxTerm application does not perform any drawing, however; that drawing is -performed by the NxTerm driver. - -The `NXWidgets::CGraphicsPort` can be obtained from a `CWindow` instance, say -`m_window`, like: - -```cpp -FAR NXWidgets::CWidgetControl *control = m_window->getWidgetControl(); -NXWidgets::CGraphicsPort *port = control->getGraphicsPort(); -``` - -That `CGraphicsPort` is then passed to the widget constructor, binding the -widget to that window and forcing all widget drawing to occur within the window. - -Obviously, a lot more could be written about drawing, much more than can be -addressed in this README file.