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.
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:
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.
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.
apps/graphics/slcd
.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.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:
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:
CONTEMPORARY
theme. These look like borders are being drawn around the toolbar widgets (even though the are configured to be borderless).*_config.hxx
header files. These all need to be brought out and made accessible via Kconfig filesSLcd::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.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:
IApplicationFactory
. Provides the common initialize()
method.IApplication
. Provides the information for the application's entry in the Main MenuCTwm4NxEvent
. 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:
getName()
. Provides the name string that will be shown in the Main Menu for this selection.getSubMenu()
. One possibility is that selecting the Main Menu item is that it may bring up yet another sub-menu of options.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.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.
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:
CTwm4NxEvent
so that it can receive events from the system.CWindow
.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:
NXWidgets::SRlePaletteBitmap
.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.