sergiotarxz/nuttx
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Documentaion: migrate graphics/readme

Browse Source
This commit is contained in:
raiden00pl 2023-10-24 12:22:19 +02:00 committed by Alan Carvalho de Assis
parent 454e3a210b
commit 05b0b7c9f3
7 changed files with 872 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Documentation/applications/graphics/index.rst
View File

@ -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)

6
Documentation/applications/graphics/lvgl/index.rst
View File

@ -1,6 +1,6 @@
====
LVGL
====
=============
``lvgl`` LVGL
=============
Usage
-----

368
Documentation/applications/graphics/nxwidgets/index.rst Normal file
View File

@ -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``.

85
Documentation/applications/graphics/nxwm/index.rst Normal file
View File

@ -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

5
Documentation/applications/graphics/pdcurs34/index.rst Normal file
View File

@ -0,0 +1,5 @@
===============================================
``pdcurs34`` pdcurses Text User Interface (TUI)
===============================================
TODO

15
Documentation/applications/graphics/tiff/index.rst Normal file
View File

@ -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``.

396
Documentation/applications/graphics/twm4nx/index.rst Normal file
View File

@ -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.