This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 05b0b7c9f30557cc5a9ebff37951de357823bff4
Author: raiden00pl <raide...@railab.me>
AuthorDate: Tue Oct 24 12:22:19 2023 +0200
Documentaion: migrate graphics/readme
---
Documentation/applications/graphics/index.rst | 4 -
Documentation/applications/graphics/lvgl/index.rst | 6 +-
.../applications/graphics/nxwidgets/index.rst | 368 +++++++++++++++++++
Documentation/applications/graphics/nxwm/index.rst | 85 +++++
.../applications/graphics/pdcurs34/index.rst | 5 +
Documentation/applications/graphics/tiff/index.rst | 15 +
.../applications/graphics/twm4nx/index.rst | 396 +++++++++++++++++++++
7 files changed, 872 insertions(+), 7 deletions(-)
diff --git a/Documentation/applications/graphics/index.rst
b/Documentation/applications/graphics/index.rst
index 48494352c5..92779321fc 100644
--- a/Documentation/applications/graphics/index.rst
+++ b/Documentation/applications/graphics/index.rst
@@ -12,10 +12,6 @@ Graphics Support
- ft80x - FTDI/BridgeTek FT80x library
- libjpeg - libjpeg JPEG image encoding
- libyuv - libyuv
-- nxwidgets - NxWidgets
-- nxwm - NuttX Tiny Window Manager (NxWM)
-- pdcurs34 - pdcurses Text User Interface (TUI)
- screenshot - TIFF screenshot utility
- slcd - Segment LCD Emulaton
-- tiff - TIFF file generation library
- twm4nx - Minimal Tom's Window Manager (TWM) for NuttX (Twm4Nx)
diff --git a/Documentation/applications/graphics/lvgl/index.rst
b/Documentation/applications/graphics/lvgl/index.rst
index 0a18e1251c..0b0f1385ff 100644
--- a/Documentation/applications/graphics/lvgl/index.rst
+++ b/Documentation/applications/graphics/lvgl/index.rst
@@ -1,6 +1,6 @@
-====
-LVGL
-====
+=============
+``lvgl`` LVGL
+=============
Usage
-----
diff --git a/Documentation/applications/graphics/nxwidgets/index.rst
b/Documentation/applications/graphics/nxwidgets/index.rst
new file mode 100644
index 0000000000..ef9bd79f20
--- /dev/null
+++ b/Documentation/applications/graphics/nxwidgets/index.rst
@@ -0,0 +1,368 @@
+=======================
+``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``.
+
+Doxygen
+-------
+
+Installing the necessary packages in Ubuntu
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Install the following packages::
+
+ $ 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]::
+
+ $ 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::
+
+ trunk/NXWidgets/Doxygen/gendoc.sh
+
+ The script only needs the argument to the absolute path where to place the
+ generated documentation. I.e.::
+
+ $ 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::
+
+ $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/
+ $ doxygen Doxyfile
+
+References
+~~~~~~~~~~
+
+[1] http://www.stack.nl/~dimitri/doxygen/download.html
+
+
+Unit Tests
+----------
+
+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::
+
+ cd <nuttx-directory-path>
+ make distclean
+ tools/configure.sh sim:nsh2
+
+ Where:
+
+ ``<nuttx-directory-path>`` 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::
+
+ 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::
+
+ 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::
+
+ 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)::
+
+ 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::
+
+ 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::
+
+ CONFIG_INIT_ENTRYPOINT="cbutton_main"
+
+ And the correct entry point for ``UnitTests/nxwm`` would be::
+
+ 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``)::
+
+ 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::
+
+ cd <nuttx-directory-path>
+ . ./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``::
+
+ 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::
+
+ 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 Directories
+~~~~~~~~~~~~~~~~~~~~~~
+
+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/Documentation/applications/graphics/nxwm/index.rst
b/Documentation/applications/graphics/nxwm/index.rst
new file mode 100644
index 0000000000..910a9ea256
--- /dev/null
+++ b/Documentation/applications/graphics/nxwm/index.rst
@@ -0,0 +1,85 @@
+=========================================
+``nxwm`` NuttX Tiny Window Manager (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.
+
+
+Doxygen
+-------
+
+Installing the necessary packages in Ubuntu
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Install the following packages::
+
+ $ 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]::
+
+ $ 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::
+
+ trunk/NXWidgets/Doxygen/gendoc.sh
+
+ The script only needs the argument to the absolute path where to place the
+ generated documentation. I.e.::
+
+ $ 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::
+
+ $ cd /path/to/nuttx/trunk/NXWidgets/Doxygen/
+ $ doxygen Doxyfile
+
+References
+~~~~~~~~~~
+
+[1] http://www.stack.nl/~dimitri/doxygen/download.html
diff --git a/Documentation/applications/graphics/pdcurs34/index.rst
b/Documentation/applications/graphics/pdcurs34/index.rst
new file mode 100644
index 0000000000..70afef3cf1
--- /dev/null
+++ b/Documentation/applications/graphics/pdcurs34/index.rst
@@ -0,0 +1,5 @@
+===============================================
+``pdcurs34`` pdcurses Text User Interface (TUI)
+===============================================
+
+TODO
diff --git a/Documentation/applications/graphics/tiff/index.rst
b/Documentation/applications/graphics/tiff/index.rst
new file mode 100644
index 0000000000..39ed96345a
--- /dev/null
+++ b/Documentation/applications/graphics/tiff/index.rst
@@ -0,0 +1,15 @@
+==============================
+``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/Documentation/applications/graphics/twm4nx/index.rst
b/Documentation/applications/graphics/twm4nx/index.rst
new file mode 100644
index 0000000000..52668b0a35
--- /dev/null
+++ b/Documentation/applications/graphics/twm4nx/index.rst
@@ -0,0 +1,396 @@
+===================================
+``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::
+
+ 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::
+
+ 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``::
+
+ 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::
+
+ 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::
+
+ 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::
+
+ 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.
