This is the second time that I have forgotten how NxTerm keyboard input is handled and was inspired to write a Wiki page.  The first was when I analyzed CNxConsole Keyboard Input.  This time, I am focused on the NxTerm example at apps/examples/nxterm.

Initialization

NX Server

The NxTerm example initializes the NX Server through the following steps:

• Calls boardctl(BOARDIOC_NX_START, 0) to start the NX server, then
• Calls nx_connect() to connect to the NX server.
• It also creates a separate thread at entry nxterm_listener() to listen for NX server events.

Window Creation

The Nxterm Example then initializes the Windows:

• Calls nxtk_openwindow() to create a bordered window,
• Calls nxtk_setposition() and nxtk_setsize() to position the window in the display,
• Calls nxtk_opentoolbar() to create a toolbar sub-window on the main window (This toolbar window is not used by the example, it is just for illustration).

NxTerm Driver

And binds the Nxterm driver to the permit drawing in the window. This is done when it:

• Calls boardctl(BOARDIOC_NXTERM, (uintptr_t)&nxcreate)

Console Task

Finally, it sets up the NxTerm and starts the console task:

• Opens the NxTerm driver,
• It then re-directs stdout and stderr to the NxTerm driver. This will cause all standard output to be rendered into the main windows, and
• It then starts a separate console daemon that inherits the re-directed output and exits.

Character I/O

...

Normal

...

Keyboard Input

Keyboard and mouse inputs are received by the application through window callbacks, just like with the Xorg X server.  Some listener needs to inject the keyboard input via nx_kbdin() (libs/libnx/nx_kbdin.c) which sends a message containing the keyboard input to the NX server.  The NX server will forward that keyboard input to the window that has focus.

...

In apps/examples/nxterm, nxterm_listener.c is the thread that drives nx_eventhandler(). The normal window NX keyboard callback is the function nxwndo_kbdin() in nxterm_wndo.c.  That callback function is just a stub that writes the keyboard data to stdout.  It is a stub because keyboard input is not received from the NxTerm in this example.

The apps/examples/nxterm/ Kludge

apps/examples/nxterm does not do things in the normal way, however.  NSH does not receive keyboard input from NX; it gets keyboard input directly from the default stdin which is probably not a keyboard at all but more likely the host PC serial console. This is okay because only the background window is used and that example does not need the help of NX to select the window that has focus.

Re-direction of stdout and stderr

stdin in and stderr are re-directed to the NxTerm character driver in nxterm_main.c:

...

Note that stdin is not re-directed in this example.

What Is BOARDIOC_NXTERM_IOCTL and Where Is It Used?

The boardctl() command BOARDIOC_NXTERM_IOCTL allows an application to inject keyboard data into NX for forwarding to the window with focus. In apps/examples/nxterm, the BOARDIOC_NXTERM_IOCTL is only called for the case of a redraw event.  A redraw event may happen when a window above the current window is moved and the text is exposed.

If you use only the background window for NxTerm, then the background window will always have focus. It will always have focus and will never be redrawn and the BOARDIOC_NXTERM_IOCTL will never be used (Unless, perhaps, you choose to implement pop-up error messages or menus on top of the NxTerm background).

Keyboard Data Flow

Keyboard Data Flow in apps/examples/nxterm

• Character input driver receives input
• NSH receives input on stdin and processes it (stdin is not redirected)
• Data is output to stdout (redirected to the NxTerm driver)

In this simple, background-window-only case, BOARDIOC_NXTERM_IOCTL will never be used.

Keyboard Data Flow in the Generic Window Case

See, for an example, apps/graphics/nxwm/src/cnxterm.cxx.  In this case, the behavior will change, depending on the selection of CONFIG_NXTERM_NXKBDIN:  If CONFIG_NXTERM_NXKBDIN is not selected, then the behavior will be similar to apps/examples/nxterm; stdin will not be redirected an keyboard input will come directly from the the system console.

...