content/docs/12.9.0/applications/graphics/twm4nx/index.html - nuttx-website - Git at Google

 <!--
  Documentation/_templates/layout.html

  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.  The
  ASF licenses this file to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance with the
  License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
  License for the specific language governing permissions and limitations
  under the License.
 -->


 <!DOCTYPE html>
 <html class="writer-html5" lang="en">
 <head>
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>twm4nx Tab Window Manager (TWM) &mdash; NuttX latest documentation</title>
       <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css" />
       <link rel="stylesheet" type="text/css" href="../../../_static/css/theme.css" />
       <link rel="stylesheet" type="text/css" href="../../../_static/copybutton.css" />
       <link rel="stylesheet" type="text/css" href="../../../_static/custom.css" />


     <link rel="shortcut icon" href="../../../_static/favicon.ico"/>
       <script src="../../../_static/jquery.js"></script>
       <script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script>
       <script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script>
       <script src="../../../_static/doctools.js"></script>
       <script src="../../../_static/sphinx_highlight.js"></script>
       <script src="../../../_static/clipboard.min.js"></script>
       <script src="../../../_static/copybutton.js"></script>
     <script src="../../../_static/js/theme.js"></script>
     <link rel="index" title="Index" href="../../../genindex.html" />
     <link rel="search" title="Search" href="../../../search.html" />
     <link rel="next" title="Industrial Applications" href="../../industry/index.html" />
     <link rel="prev" title="tiff TIFF Creation Library" href="../tiff/index.html" />
 </head>

 <body class="wy-body-for-nav">
   <div class="wy-grid-for-nav">
     <nav data-toggle="wy-nav-shift" class="wy-nav-side">
       <div class="wy-side-scroll">
         <div class="wy-side-nav-search" >

     <a href="../../../index.html" class="icon icon-home"> NuttX


   </a>

   <!-- this version selector is quite ugly, should be probably replaced by something
        more modern -->

   <div class="version-selector">
     <select onchange="javascript:location.href = this.value;">

     <option value="../../../../latest" selected="selected">latest</option>

     <option value="../../../../10.0.0" >10.0.0</option>

     <option value="../../../../10.0.1" >10.0.1</option>

     <option value="../../../../10.1.0" >10.1.0</option>

     <option value="../../../../10.2.0" >10.2.0</option>

     <option value="../../../../10.3.0" >10.3.0</option>

     <option value="../../../../11.0.0" >11.0.0</option>

     <option value="../../../../12.0.0" >12.0.0</option>

     <option value="../../../../12.1.0" >12.1.0</option>

     <option value="../../../../12.2.0" >12.2.0</option>

     <option value="../../../../12.2.1" >12.2.1</option>

     <option value="../../../../12.3.0" >12.3.0</option>

     <option value="../../../../12.4.0" >12.4.0</option>

     <option value="../../../../12.5.0" >12.5.0</option>

     <option value="../../../../12.5.1" >12.5.1</option>

     <option value="../../../../12.6.0" >12.6.0</option>

     <option value="../../../../12.7.0" >12.7.0</option>

     <option value="../../../../12.8.0" >12.8.0</option>

     <option value="../../../../12.9.0" >12.9.0</option>

     <option value="../../../../12.10.0" >12.10.0</option>

     <option value="../../../../12.11.0" >12.11.0</option>

     </select>
   </div>


 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
     <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
     <input type="hidden" name="check_keywords" value="yes" />
     <input type="hidden" name="area" value="default" />
   </form>
 </div>

         </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
               <p class="caption" role="heading"><span class="caption-text">Table of Contents</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="../../../index.html">Home</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../introduction/index.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../quickstart/index.html">Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../contributing/index.html">Contributing</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../platforms/index.html">Supported Platforms</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../components/index.html">OS Components</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Applications</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="../../audioutils/index.html">Audio Utility libraries</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../boot/index.html">Bootloader Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../benchmarks/index.html">Benchmark Applications</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../canutils/index.html">CAN Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../crypto/index.html">Cryptography Library Support</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../fsutils/index.html">File System Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../games/index.html">Games</a></li>
 <li class="toctree-l2 current"><a class="reference internal" href="../index.html">Graphics Support</a><ul class="current">
 <li class="toctree-l3"><a class="reference internal" href="../ft80x/index.html"><code class="docutils literal notranslate"><span class="pre">ft80x</span></code> FTDI/BridgeTek FT80x library</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../libjpeg/index.html"><code class="docutils literal notranslate"><span class="pre">libjpeg</span></code> libjpeg JPEG image encoding</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../libyuv/index.html"><code class="docutils literal notranslate"><span class="pre">libyuv</span></code> libyuv</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../lvgl/index.html"><code class="docutils literal notranslate"><span class="pre">lvgl</span></code> LVGL</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../nxwidgets/index.html"><code class="docutils literal notranslate"><span class="pre">nxwidgets</span></code> NXWidgets</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../nxwm/index.html"><code class="docutils literal notranslate"><span class="pre">nxwm</span></code> NuttX Tiny Window Manager (NxWM)</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../pdcurs34/index.html"><code class="docutils literal notranslate"><span class="pre">pdcurs34</span></code> pdcurses Text User Interface (TUI)</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../screenshot/index.html"><code class="docutils literal notranslate"><span class="pre">screenshot</span></code> TIFF screenshot utility</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../slcd/index.html"><code class="docutils literal notranslate"><span class="pre">slcd</span></code> Segment LCD Emulaton</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../tiff/index.html"><code class="docutils literal notranslate"><span class="pre">tiff</span></code> TIFF Creation Library</a></li>
 <li class="toctree-l3 current"><a class="current reference internal" href="#"><code class="docutils literal notranslate"><span class="pre">twm4nx</span></code> Tab Window Manager (TWM)</a><ul>
 <li class="toctree-l4"><a class="reference internal" href="#status">Status</a><ul>
 <li class="toctree-l5"><a class="reference internal" href="#progress">Progress</a></li>
 </ul>
 </li>
 <li class="toctree-l4"><a class="reference internal" href="#how-to">How To</a><ul>
 <li class="toctree-l5"><a class="reference internal" href="#icon-manager">Icon Manager</a></li>
 <li class="toctree-l5"><a class="reference internal" href="#main-menu">Main Menu</a></li>
 <li class="toctree-l5"><a class="reference internal" href="#window-toolbar">Window Toolbar</a></li>
 <li class="toctree-l5"><a class="reference internal" href="#moving-a-window">Moving a Window</a></li>
 <li class="toctree-l5"><a class="reference internal" href="#resizing-a-window">Resizing a Window</a></li>
 <li class="toctree-l5"><a class="reference internal" href="#themes">Themes</a></li>
 <li class="toctree-l5"><a class="reference internal" href="#issues">Issues</a></li>
 </ul>
 </li>
 <li class="toctree-l4"><a class="reference internal" href="#adding-twm4nx-applications">Adding Twm4Nx Applications</a><ul>
 <li class="toctree-l5"><a class="reference internal" href="#application-factories-and-the-main-menu">Application Factories and the Main Menu</a></li>
 <li class="toctree-l5"><a class="reference internal" href="#application-windows">Application Windows</a></li>
 </ul>
 </li>
 </ul>
 </li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="../../industry/index.html">Industrial Applications</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../inertial/index.html">Inertial Libraries Support</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../interpreters/index.html">Interpreters</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../logging/index.html">Logging Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../lte/index.html">LTE Libraries and NSH Add-Ons</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../math/index.html">Math Library Support</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../mlearing/index.html">Machine Learning Support</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../netutils/index.html">Network Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../nsh/index.html">NuttShell (NSH)</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../sdr/index.html">Software Define Radio Libraries</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../system/index.html">System Libraries and NSH Add-Ons</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../testing/index.html">Testing</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../tools/index.html">Host Side Tools</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../wireless/index.html">Wireless Libraries and NSH Add-Ons</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/index.html">Examples</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../../../implementation/index.html">Implementation Details</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../reference/index.html">API Reference</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../faq/index.html">FAQ</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../guides/index.html">Guides</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../glossary.html">Glossary</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../logos/index.html">NuttX Logos</a></li>
 </ul>

         </div>
       </div>
     </nav>

     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
           <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
           <a href="../../../index.html">NuttX</a>
       </nav>

       <div class="wy-nav-content">
         <div class="rst-content">
           <div role="navigation" aria-label="Page navigation">
   <ul class="wy-breadcrumbs">
       <li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
           <li class="breadcrumb-item"><a href="../../index.html">Applications</a></li>
           <li class="breadcrumb-item"><a href="../index.html">Graphics Support</a></li>
       <li class="breadcrumb-item active"><code class="docutils literal notranslate"><span class="pre">twm4nx</span></code> Tab Window Manager (TWM)</li>
       <li class="wy-breadcrumbs-aside">
             <a href="../../../_sources/applications/graphics/twm4nx/index.rst.txt" rel="nofollow"> View page source</a>
       </li>
   </ul>
   <hr/>
 </div>
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div itemprop="articleBody">

   <section id="twm4nx-tab-window-manager-twm">
 <h1><code class="docutils literal notranslate"><span class="pre">twm4nx</span></code> Tab Window Manager (TWM)<a class="headerlink" href="#twm4nx-tab-window-manager-twm" title="Permalink to this heading"></a></h1>
 <p>Twm4Nx is a port of twm, Tab Window Manager (or Tom’s Window Manager) version
 <code class="docutils literal notranslate"><span class="pre">1.0.10</span></code> 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.</p>
 <p>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.</p>
 <p>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++).</p>
 <p>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 <code class="docutils literal notranslate"><span class="pre">.twmrc</span></code> file is used. Bitmaps are not used (other than for
 fonts).</p>
 <p>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 <code class="docutils literal notranslate"><span class="pre">COPYING</span></code> file. within
 this directory.</p>
 <section id="status">
 <h2>Status<a class="headerlink" href="#status" title="Permalink to this heading"></a></h2>
 <section id="progress">
 <h3>Progress<a class="headerlink" href="#progress" title="Permalink to this heading"></a></h3>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">2019-04-28</span></code> 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 <code class="docutils literal notranslate"><span class="pre">EXPERIMENTAL</span></code>). The kinds of
 things that need to done are:</p>
 <ol class="arabic simple">
 <li><p>Right click should bring up a window list (like the icon manager???)</p></li>
 <li><dl class="simple">
 <dt>For TWM-like behavior, a window frame and toolbar should be highlighted</dt><dd><p>when the window has focus.</p>
 </dd>
 </dl>
 </li>
 <li><p>A right click on the toolbar should bring up a window-specific menu.</p></li>
 </ol>
 </li>
 <li><p><code class="docutils literal notranslate"><span class="pre">2019-05-02</span></code> 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.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">2019-05-08</span></code> 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).</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">2019-05-10</span></code> 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.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">2019-05-13</span></code> Added the NxTerm application. If enabled via
 <code class="docutils literal notranslate"><span class="pre">CONFIG_TWM4XN_NXTERM</span></code>, there will now be a _NuttShell_ entry in the Main
 Menu. When pressed, this will bring up an NSH session in a Twm4Nx window.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">2019-05-14</span></code> 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.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">2019-05-15</span></code> Resizing now seems to work correctly in Twm4Nx.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">2019-05-20</span></code> Calibration screen is now in place.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">2019-05-21</span></code> A <code class="docutils literal notranslate"><span class="pre">CONTEMPORARY</span></code> theme was added. Still has a few glitches.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">2019-06-01</span></code> A retro, emulated segment LCD clock is now in place.</p></li>
 </ul>
 </section>
 </section>
 <section id="how-to">
 <h2>How To<a class="headerlink" href="#how-to" title="Permalink to this heading"></a></h2>
 <section id="icon-manager">
 <h3>Icon Manager<a class="headerlink" href="#icon-manager" title="Permalink to this heading"></a></h3>
 <ul>
 <li><p>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.</p>
 <p>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.</p>
 </li>
 </ul>
 </section>
 <section id="main-menu">
 <h3>Main Menu<a class="headerlink" href="#main-menu" title="Permalink to this heading"></a></h3>
 <ul class="simple">
 <li><p>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:</p>
 <ul>
 <li><p>Desktop. Iconify all windows and show the desktop</p></li>
 <li><p>Twm4Nx Icom Manager. De-iconify and/or raise the Icon Manager to the top of
 the display.</p></li>
 <li><p>Calibration. Perform touchscreen re-calibration.</p></li>
 <li><p>Clock. Start and instance of clock in the window. The uses the the retro,
 LCD emulation of <code class="docutils literal notranslate"><span class="pre">apps/graphics/slcd</span></code>.</p></li>
 <li><p>NuttShell. Start and instance of NSH running in an NxTerm.</p></li>
 </ul>
 </li>
 <li><p>All windows close after the terminal menu option is selected.</p></li>
 </ul>
 </section>
 <section id="window-toolbar">
 <h3>Window Toolbar<a class="headerlink" href="#window-toolbar" title="Permalink to this heading"></a></h3>
 <ul class="simple">
 <li><p>Most windows have a toolbar at the top. It is optional but used in most
 windows.</p></li>
 <li><p>The toolbar contains window title and from zero to 4 buttons:</p>
 <ul>
 <li><p>Right side: A menu button may be presented. The menu button is not used by
 anything in the current implementation and is always suppressed</p></li>
 <li><p>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.</p></li>
 </ul>
 </li>
 </ul>
 </section>
 <section id="moving-a-window">
 <h3>Moving a Window<a class="headerlink" href="#moving-a-window" title="Permalink to this heading"></a></h3>
 <ul class="simple">
 <li><p>Grab the title in the toolbar and move the window to the desired position.</p></li>
 </ul>
 </section>
 <section id="resizing-a-window">
 <h3>Resizing a Window<a class="headerlink" href="#resizing-a-window" title="Permalink to this heading"></a></h3>
 <ul class="simple">
 <li><p>A window must have the green resize button with the square or it cannot be
 resized.</p></li>
 <li><p>Press resize button. A small window should pop-up in the upper left hand
 corner showing the current window size.</p></li>
 <li><p>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:</p>
 <ul>
 <li><p>Move toward the right increases the width of the window</p></li>
 <li><p>Move toward the left decreases the width of the window</p></li>
 <li><p>Move toward the bottom increases the height of the window</p></li>
 <li><p>Move toward the top decreases the height of the Window</p></li>
 <li><p>Other moves will affect both the height and width of the window.</p></li>
 </ul>
 </li>
 <li><p><strong>Note</strong>: While resizing, non-critical events from all other windows are
 ignored.</p></li>
 </ul>
 </section>
 <section id="themes">
 <h3>Themes<a class="headerlink" href="#themes" title="Permalink to this heading"></a></h3>
 <ul class="simple">
 <li><p>There are two themes support by the configuration system:</p>
 <ul>
 <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_TWM4NX_CLASSIC</span></code> – Strong bordered windows with dark primary colors.
 Reminiscent of Windows 98.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_TWM4NX_CONTEMPORARY</span></code> – Border-less windows in pastel shades for a
 more contemporary look.</p></li>
 </ul>
 </li>
 </ul>
 </section>
 <section id="issues">
 <h3>Issues<a class="headerlink" href="#issues" title="Permalink to this heading"></a></h3>
 <p><code class="docutils literal notranslate"><span class="pre">2019-05-16</span></code> 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.</p>
 <p>Here are all known issues and features that are missing:</p>
 <p>TWM Compatibilities Issues:</p>
 <ol class="arabic simple">
 <li><p>Resizing works a little differently in Twm4Nx.</p></li>
 <li><p>Right click should bring up a window list</p></li>
 <li><p>For TWM-like behavior, a window frame and toolbar should be highlighted when
 the window has focus.</p></li>
 <li><p>A right click on the toolbar should bring up a window-specific menu.</p></li>
 </ol>
 <p>There are no near-term plans to address these compatibility issues.</p>
 <p>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:</p>
 <ol class="arabic simple">
 <li><p>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.</p></li>
 <li><p>There are a few color artifacts in the toolbar of the <code class="docutils literal notranslate"><span class="pre">CONTEMPORARY</span></code> theme.
 These look like borders are being drawn around the toolbar widgets (even
 though the are configured to be borderless).</p></li>
 <li><p>Most Twm4Nx configuration settings are hard-coded in <code class="docutils literal notranslate"><span class="pre">*_config.hxx</span></code> header
 files. These all need to be brought out and made accessible via Kconfig files</p></li>
 <li><p>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.</p></li>
 <li><p>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.</p></li>
 <li><p>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.</p></li>
 <li><p>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.</p></li>
 <li><p>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.</p></li>
 <li><p>There is a trivial rounding error in the calculation of the LCD width in
 <code class="docutils literal notranslate"><span class="pre">SLcd::CSLcd::getWidth()</span></code>. 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.</p></li>
 </ol>
 </section>
 </section>
 <section id="adding-twm4nx-applications">
 <h2>Adding Twm4Nx Applications<a class="headerlink" href="#adding-twm4nx-applications" title="Permalink to this heading"></a></h2>
 <section id="application-factories-and-the-main-menu">
 <h3>Application Factories and the Main Menu<a class="headerlink" href="#application-factories-and-the-main-menu" title="Permalink to this heading"></a></h3>
 <p>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.</p>
 <p>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.</p>
 <p>These example applications can be found at: <code class="docutils literal notranslate"><span class="pre">apps/graphics/twm4nx/apps</span></code> and
 <code class="docutils literal notranslate"><span class="pre">apps/include/graphics/twm4nx/apps</span></code></p>
 <p>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 <code class="docutils literal notranslate"><span class="pre">IApplicationFactory</span></code> as defined in
 <code class="docutils literal notranslate"><span class="pre">apps/include/graphics/twm4nx/iapplication.hxx</span></code>. This base class provides only a
 single method:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>bool initialize(FAR CTwm4Nx *twm4nx);
 </pre></div>
 </div>
 <p>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.</p>
 <p>In practice, the application factory implementation class inherits from the
 following base classes:</p>
 <ol class="arabic simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">IApplicationFactory</span></code>. Provides the common <code class="docutils literal notranslate"><span class="pre">initialize()</span></code> method.</p></li>
 <li><dl class="simple">
 <dt><code class="docutils literal notranslate"><span class="pre">IApplication</span></code>. Provides the information for the application’s entry in the</dt><dd><p>Main Menu</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt><code class="docutils literal notranslate"><span class="pre">CTwm4NxEvent</span></code>. Hooks the application factory into the Twm4Nx event</dt><dd><p>notification system.</p>
 </dd>
 </dl>
 </li>
 </ol>
 <p>Initialization consists of instantiating the application factory instance and
 calling its <code class="docutils literal notranslate"><span class="pre">IApplicationFactory::initialize()</span></code> 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
 <code class="docutils literal notranslate"><span class="pre">apps/graphics/twm4nx/src/twm4nx_main.c</span></code> like:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>CNxTermFactory nxtermFactory;
 success = nxtermFactory.initialize(twm4nx);
 </pre></div>
 </div>
 <p>In addition to general initialization, the <code class="docutils literal notranslate"><span class="pre">IApplicationFactory::initialize()</span></code>
 method must register a new entry with the main menu. You can see an example of
 this in <code class="docutils literal notranslate"><span class="pre">apps/graphics/twm4nx/apps/cnxterm.c</span></code>:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>FAR CMainMenu *cmain = twm4nx-&gt;getMainMenu();
 return cmain-&gt;addApplication(this);
 </pre></div>
 </div>
 <p>The argument to the <code class="docutils literal notranslate"><span class="pre">CMainMenu::addApplication()</span></code> method is of type
 <code class="docutils literal notranslate"><span class="pre">IApplication</span> <span class="pre">*</span></code>. Remember, however, that our application implementation <code class="docutils literal notranslate"><span class="pre">class</span></code>
 inherited from <code class="docutils literal notranslate"><span class="pre">IApplication</span></code>.</p>
 <p>The IApplication pure virtual base class is also defined in
 <code class="docutils literal notranslate"><span class="pre">apps/include/graphics/twm4nx/iapplication.hxx</span></code>. It essentially describes what
 the Main Menu logic should do when the menu item is selected. It includes these
 methods:</p>
 <ol class="arabic simple">
 <li><dl class="simple">
 <dt><code class="docutils literal notranslate"><span class="pre">getName()</span></code>. Provides the name string that will be shown in the Main Menu for</dt><dd><p>this selection.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt><code class="docutils literal notranslate"><span class="pre">getSubMenu()</span></code>. One possibility is that selecting the Main Menu item is that</dt><dd><p>it may bring up yet another sub-menu of options.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt><code class="docutils literal notranslate"><span class="pre">getEventHandler()</span></code>. Returns an instance of <code class="docutils literal notranslate"><span class="pre">CTwm4NxEvent</span></code> that is used to</dt><dd><p>route menu selection events. Remember that our application factory inherits
 from <code class="docutils literal notranslate"><span class="pre">CTwm4NxEvent</span></code> so this function only needs to return the ‘this’
 pointer.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt><code class="docutils literal notranslate"><span class="pre">getEvent()</span></code>. Provides the event ID that will be used in the event</dt><dd><p>notification. The returned value must conform to the description in
 <code class="docutils literal notranslate"><span class="pre">apps/include/graphics/twm4nx/twm4nx_events.hxx</span></code>. In particular, the
 recipient of the event must be <code class="docutils literal notranslate"><span class="pre">EVENT_RECIPIENT_APP</span></code>.</p>
 </dd>
 </dl>
 </li>
 </ol>
 <p>The Twm4Nx application is then started when the application factory’s
 <code class="docutils literal notranslate"><span class="pre">CTwm4NxEvent::event()</span></code> method is called with the specified event.</p>
 </section>
 <section id="application-windows">
 <h3>Application Windows<a class="headerlink" href="#application-windows" title="Permalink to this heading"></a></h3>
 <p>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:</p>
 <ol class="arabic simple">
 <li><dl class="simple">
 <dt>It probably should inherit from <code class="docutils literal notranslate"><span class="pre">CTwm4NxEvent</span></code> so that it can receive events</dt><dd><p>from the system.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt>To create the window, it must instantiate and initialize an instance of</dt><dd><p><code class="docutils literal notranslate"><span class="pre">CWindow</span></code>.</p>
 </dd>
 </dl>
 </li>
 <li><p>It must configure application events to receive notifications from Twm4Nx.</p></li>
 </ol>
 <p>To create an application window, the application must call the
 <code class="docutils literal notranslate"><span class="pre">CWindowFactory::createWindow()</span></code> method. For the NxTerm example, this looks
 like:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>NXWidgets::CNxString name(&quot;NuttShell&quot;);

 uint8_t wflags = (WFLAGS_NO_MENU_BUTTON | WFLAGS_HIDDEN);

 FAR CWindowFactory *factory = m_twm4nx-&gt;getWindowFactory();
 m_nxtermWindow = factory-&gt;createWindow(name, &amp;CONFIG_TWM4NX_NXTERM_ICON,
                                         (FAR CIconMgr *)0, wflags);
 </pre></div>
 </div>
 <p>The window factory is another factory that creates and manages window instance.
 The <code class="docutils literal notranslate"><span class="pre">createWindow()</span></code> method requires four parameters:</p>
 <ol class="arabic simple">
 <li><dl class="simple">
 <dt>The name of the window. This is the name that is show in the window toolbar</dt><dd><p>and may be the same name as was used in the Main Menu entry.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt>A reference to the the Icon image associated with the window. This is the</dt><dd><p>image that is show on the desktop when the window is iconified. It is of
 type <code class="docutils literal notranslate"><span class="pre">NXWidgets::SRlePaletteBitmap</span></code>.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt>A pointer to the Icon Manager instance that this window belongs with. This</dt><dd><p>can be NULL to use the default Twm4Nx Icon Manager.</p>
 </dd>
 </dl>
 </li>
 <li><p>A set of flags that describe properties of the windows.</p></li>
 </ol>
 <blockquote>
 <div><p>The flag values are defined byte <code class="docutils literal notranslate"><span class="pre">WFLAGS_*</span></code> definitions provided in
 <code class="docutils literal notranslate"><span class="pre">apps/include/graphics/twm4nx/cwindow.hxx</span></code>:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">WFLAGS_NO_MENU_BUTTON</span></code> – Omit the menu button from the toolbar.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">WFLAGS_NO_DELETE_BUTTON</span></code> – Omit the delete button from the toolbar.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">WFLAGS_NO_RESIZE_BUTTON</span></code> – Omit the resize button from the toolbar.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">WFLAGS_NO_MINIMIZE_BUTTON</span></code> – Omit the minimize button from the toolbar.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">WFLAGS_NO_TOOLBAR</span></code> – Omit the toolbar altogether.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">WFLAGS_ICONMGR</span></code> – This window is an icon manager.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">WFLAGS_MENU</span></code> – This window is a menu window.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">WFLAGS_HIDDEN</span></code> – Start with the window hidden.</p></li>
 </ul>
 </div></blockquote>
 <p>Once the <code class="docutils literal notranslate"><span class="pre">CWindow</span></code> is instantiated, events needed by the application can be
 configured as is done in the NxTerm application:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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-&gt;configureEvents(events);
 </pre></div>
 </div>
 <p>Again, recall that the application inherits from <code class="docutils literal notranslate"><span class="pre">CTwm4NxEvent</span></code>. So passing
 <code class="docutils literal notranslate"><span class="pre">this</span></code> as the event object above assures that the specific events are routed to
 the application instance.</p>
 <p>Drawing in the application window can be performed using that facilities of
 NXWidgets using the <code class="docutils literal notranslate"><span class="pre">NXWidgets::CGraphicsPort</span></code> associated with the window. The
 NxTerm application does not perform any drawing, however; that drawing is
 performed by the NxTerm driver.</p>
 <p>The <code class="docutils literal notranslate"><span class="pre">NXWidgets::CGraphicsPort</span></code> can be obtained from a <code class="docutils literal notranslate"><span class="pre">CWindow</span></code> instance, say
 <code class="docutils literal notranslate"><span class="pre">m_window</span></code>, like:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>FAR NXWidgets::CWidgetControl *control = m_window-&gt;getWidgetControl();
 NXWidgets::CGraphicsPort *port = control-&gt;getGraphicsPort();
 </pre></div>
 </div>
 <p>That <code class="docutils literal notranslate"><span class="pre">CGraphicsPort</span></code> is then passed to the widget constructor, binding the
 widget to that window and forcing all widget drawing to occur within the window.</p>
 <p>Obviously, a lot more could be written about drawing, much more than can be
 addressed in this README file.</p>
 </section>
 </section>
 </section>


            </div>
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
         <a href="../tiff/index.html" class="btn btn-neutral float-left" title="tiff TIFF Creation Library" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
         <a href="../../industry/index.html" class="btn btn-neutral float-right" title="Industrial Applications" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>

   <hr/>

   <div role="contentinfo">
     <p>&#169; Copyright 2023, The Apache Software Foundation.</p>
   </div>


 </footer>
         </div>
       </div>
     </section>
   </div>
   <script>
       jQuery(function () {
           SphinxRtdTheme.Navigation.enable(true);
       });
   </script>

 </body>
 </html>