This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx-apps.git
commit d313bbad9c7093ca24c0fe0d856f05c0dd3aa0a7
Author: raiden00pl <raide...@railab.me>
AuthorDate: Tue Oct 24 14:06:31 2023 +0200
remove graphics/xxx/README.md. Migrated to
Documentation/applications/graphics
---
graphics/lvgl/README.md | 23 --
graphics/nxwidgets/Doxygen/README.md | 68 ------
graphics/nxwidgets/README.md | 68 ------
graphics/nxwidgets/UnitTests/README.md | 259 ----------------------
graphics/nxwm/Doxygen/README.md | 68 ------
graphics/nxwm/README.md | 27 ---
graphics/tiff/README.md | 12 -
graphics/twm4nx/README.md | 386 ---------------------------------
8 files changed, 911 deletions(-)
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 <lvgl/lvgl.h>` or `#include <lvgl.h>`.
-
-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 <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:
-
- ```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 <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`:
-
- ```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.
