From 13c6254f1b3db304426d6fe6ce4e6ccc6aa963e1 Mon Sep 17 00:00:00 2001 From: Gregory Nutt Date: Thu, 11 Apr 2019 16:20:22 -0600 Subject: [PATCH] Documentation/NXGraphicsSubsystem.html: Update documentation to describe block, synchronization, and cursor interfaces. --- Documentation/NXGraphicsSubsystem.html | 521 ++++++++++++++++++++----- include/nuttx/nx/nx.h | 13 +- include/nuttx/nx/nxcursor.h | 10 +- include/nuttx/nx/nxtk.h | 5 +- 4 files changed, 442 insertions(+), 107 deletions(-) diff --git a/Documentation/NXGraphicsSubsystem.html b/Documentation/NXGraphicsSubsystem.html index 1cfa3a63c94..056bb595eff 100644 --- a/Documentation/NXGraphicsSubsystem.html +++ b/Documentation/NXGraphicsSubsystem.html @@ -12,7 +12,7 @@

NX Graphics Subsystem

-

Last Updated: March 13, 2019

+

Last Updated: April 11, 2019

@@ -103,7 +103,8 @@ 2.3.4.1 redraw()
2.3.4.2 position()
2.3.4.3 mousein()
- 2.3.4.4 kbdin() + 2.3.4.4 kbdin()
+ 2.3.4.5 event()

2.3.5 nx_runinstance() (and nx_run() macro)
@@ -111,26 +112,28 @@ 2.3.7 nx_disconnect()
2.3.8 nx_eventhandler()
2.3.9 nx_eventnotify()
- 2.3.10 nx_openwindow()
- 2.3.11 nx_closewindow()
- 2.3.12 nx_requestbkgd()
- 2.3.13 nx_releasebkgd()
- 2.3.14 nx_getposition()
- 2.3.15 nx_setposition()
- 2.3.16 nx_setsize()
- 2.3.17 nx_raise()
- 2.3.18 nx_lower()
- 2.3.19 nx_fill()
- 2.3.20 nx_getrectangle()
- 2.3.21 nx_filltrapezoid()
- 2.3.22 nx_drawline()
- 2.3.23 nx_drawcircle()
- 2.3.24 nx_fillcircle()
- 2.3.25 nx_setbgcolor()
- 2.3.26 nx_move()
- 2.3.27 nx_bitmap()
- 2.3.28 nx_kbdin()
- 2.3.29 nx_mousein()
+ 2.3.10 nx_block()
+ 2.3.11 nx_synch()
+ 2.3.12 nx_openwindow()
+ 2.3.13 nx_closewindow()
+ 2.3.14 nx_requestbkgd()
+ 2.3.15 nx_releasebkgd()
+ 2.3.16 nx_getposition()
+ 2.3.17 nx_setposition()
+ 2.3.18 nx_setsize()
+ 2.3.19 nx_raise()
+ 2.3.20 nx_lower()
+ 2.3.21 nx_fill()
+ 2.3.22 nx_getrectangle()
+ 2.3.23 nx_filltrapezoid()
+ 2.3.24 nx_drawline()
+ 2.3.25 nx_drawcircle()
+ 2.3.26 nx_fillcircle()
+ 2.3.27 nx_setbgcolor()
+ 2.3.28 nx_move()
+ 2.3.29 nx_bitmap()
+ 2.3.30 nx_kbdin()
+ 2.3.31 nx_mousein()

@@ -141,31 +144,33 @@

@@ -181,7 +186,17 @@

- 2.6 Sample Code + 2.6 NX Cursor Support (NXCURSOR) +

+

+

+

+

+ 2.7 Sample Code

@@ -1142,6 +1157,44 @@ void (*kbdin)(NXWINDOW hwnd, uint8_t nch, FAR const uint8_t *ch, FAR void *arg); Returned Value: None

+ 2.3.4.5 event() +

2.3.4.5 event()

+

Callback Function Prototype:

+
    +void (*event)(NXWINDOW hwnd, enum nx_event_e event, FAR void *arg1, FAR void *arg2);
+
+

+ Description: + This callback is used to communicate server events to the window listener. +

+
+
NXEVENT_BLOCKED - Window messages are blocked. +
This callback is the response from nx_block(), nxtk_block(). Those blocking interfaces are used to assure that no further messages are directed to the window. Receipt of the blocked callback signifies that (1) there are no further pending callbacks and (2) that the window is now defunct and will receive no further callbacks. + + This callback supports coordinated destruction of a window. In the multi-user mode, the client window logic must stay intact until all of the queued callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed. +
NXEVENT_SYNCHED - Synchronization handshake +
This completes the handshake started by nx_synch(), or nxtk_synch(). Those interfaces send a synchronization messages to the NX server which responds with this event. The sleeping client is awakened and continues graphics processing, completing the handshake. + + Due to the highly asynchronous nature of client-server communications, synchronization is sometimes necessary to assure that the client and server are working together properly. +
+

+ Input Parameters: +

+

+

+ Returned Value: None +

+ +

2.3.5 nx_runinstance() (and nx_run() macro)

Function Prototype:

    @@ -1342,7 +1395,93 @@ int nx_eventnotify(NXHANDLE handle, int signo);
   ERROR on failure with errno set appropriately
 
    
 
-
    2.3.10 nx_openwindow()
    
+
    2.3.10 nx_block()
    
+
    Function Prototype:
    
+
      +#include <nuttx/nx/nx.h>
+
+int nx_block(NXWINDOW hwnd, FAR void *arg);
+
    
+
    
+  Description:
+   The response to this function call is two things:  (1) any queued callback messages to the window are 'blocked' and then (2) also subsequent window messaging is blocked.
+
    
+
    
+   The event callback with the NXEVENT_BLOCKED event is the response from nx_block().  This blocking interface is used to assure that no further messages are are directed to the window. Receipt of the NXEVENT_BLOCKED event signifies that (1) there are no further pending callbacks and (2) that the window is now defunct and will receive no further callbacks.
+
    
+
    
+   This callback supports coordinated destruction of a window.  The client window logic must stay intact until all of the queued callbacks are processed.  Then the window may be safely closed.  Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed.
+
    
+
    
+  Input Parameters:
+  
      
+  
      
+    
      wnd
+    
      The window to be blocked
+    
      arg
+    
      An argument that will accompany the block messages (This is arg2 in the event callback).
+  
    
+
    
+
    
+  Returned Value:
+  OK on success; ERROR on failure with errno set appropriately.
+
    
+
+
    2.3.11 nx_synch()
    
+
    Function Prototype:
    
+
      +#include <nuttx/nx/nx.h>
+
+int nx_synch(NXWINDOW hwnd, FAR void *arg);
+
    
+
    
+  Description:
+  This interface can be used to synchronize the window client with the NX server.  It really just implements an echo:  A synch message is sent from the window client to the server which then responds immediately by sending the NXEVENT_SYNCHED back to the windows client.
+
    
+
    
+  Due to the highly asynchronous nature of client-server communications, nx_synch() is sometimes necessary to assure that the client and server are fully synchronized in time.
+
    
+
    
+  Usage by the window client might be something like this:
+
    
+
      +  extern bool g_synched;
+  extern sem_t g_synch_sem;
+
+  g_synched = false;
+  ret = nx_synch(hwnd, handle);
+  if (ret < 0)
+    {
+       -- Handle the error --
+    }
+
+  while (!g_synched)
+    {
+      ret = sem_wait(&g_sync_sem);
+      if (ret < 0)
+        {
+           -- Handle the error --
+        }
+    }
+
    
+
    
+   When the window listener thread receives the NXEVENT_SYNCHED event, it would set g_synched to true and post g_synch_sem, waking up the above loop.
+
    
+
    
+  Input Parameters:
+  
      
+    
      wnd
+    
      The window to be synched
+    
      arg
+    
      An argument that will accompany the synch messages (This is arg2 in the event callback).
+  
    
+
    
+
    
+  Returned Value:
+  OK on success; ERROR on failure with errno set appropriately
+
    
+
+
    2.3.12 nx_openwindow()
    
 
    Function Prototype:
    
 
       #include <nuttx/nx/nxglib.h>
@@ -1378,7 +1517,7 @@ NXWINDOW nx_openwindow(NXHANDLE handle, uint8_t flags,
     Failure:  NULL is returned and errno is set appropriately.
 
    
 
-
    2.3.11 nx_closewindow()
    
+
    2.3.13 nx_closewindow()
    
 
    Function Prototype:
    
 
       #include <nuttx/nx/nxglib.h>
@@ -1406,7 +1545,7 @@ int nx_closewindow(NXWINDOW hwnd);
   ERROR on failure with errno set appropriately
 
      
 
-
      2.3.12 nx_requestbkgd()
      
+
      2.3.14 nx_requestbkgd()
      
 
      Function Prototype:
      
 
         #include <nuttx/nx/nxglib.h>
@@ -1476,7 +1615,7 @@ int nx_requestbkgd(NXHANDLE handle,
   ERROR on failure with errno set appropriately
 
        
 
-
        2.3.13 nx_releasebkgd()
        
+
        2.3.15 nx_releasebkgd()
        
 
        Function Prototype:
        
 
           #include <nuttx/nx/nxglib.h>
@@ -1506,7 +1645,7 @@ int nx_releasebkgd(NXWINDOW hwnd);
   ERROR on failure with errno set appropriately
 
          
 
-
          2.3.14 nx_getposition()
          
+
          2.3.16 nx_getposition()
          
 
          Function Prototype:
          
 
             #include <nuttx/nx/nxglib.h>
@@ -1534,7 +1673,7 @@ int nx_getposition(NXWINDOW hwnd);
   ERROR on failure with errno set appropriately
 
            
 
-
            2.3.15 nx_setposition()
            
+
            2.3.17 nx_setposition()
            
 
            Function Prototype:
            
 
               #include <nuttx/nx/nxglib.h>
@@ -1563,7 +1702,7 @@ int nx_setposition(NXWINDOW hwnd, FAR struct nxgl_point_s *pos);
   ERROR on failure with errno set appropriately
 
              
 
-
              2.3.16 nx_setsize()
              
+
              2.3.18 nx_setsize()
              
 
              Function Prototype:
              
 
                 #include <nuttx/nx/nxglib.h>
@@ -1591,7 +1730,7 @@ int nx_setsize(NXWINDOW hwnd, FAR struct nxgl_size_s *size);
   ERROR on failure with errno set appropriately
 
                
 
-
                2.3.17 nx_raise()
                
+
                2.3.19 nx_raise()
                
 
                Function Prototype:
                
 
                   #include <nuttx/nx/nxglib.h>
@@ -1619,7 +1758,7 @@ int nx_raise(NXWINDOW hwnd);
   ERROR on failure with errno set appropriately
 
                  
 
-
                  2.3.18 nx_lower()
                  
+
                  2.3.20 nx_lower()
                  
 
                  Function Prototype:
                  
 
                     #include <nuttx/nx/nxglib.h>
@@ -1647,7 +1786,7 @@ int nx_lower(NXWINDOW hwnd);
   ERROR on failure with errno set appropriately
 
                    
 
-
                    2.3.19 nx_fill()
                    
+
                    2.3.21 nx_fill()
                    
 
                    Function Prototype:
                    
 
                       #include <nuttx/nx/nxglib.h>
@@ -1678,7 +1817,7 @@ int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                      
 
-
                      2.3.20 nx_getrectangle()
                      
+
                      2.3.22 nx_getrectangle()
                      
 
                      Function Prototype:
                      
 
                         #include <nuttx/nx/nxglib.h>
@@ -1718,7 +1857,7 @@ void nx_getrectangle(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                        
 
-
                        2.3.21 nx_filltrapezoid()
                        
+
                        2.3.23 nx_filltrapezoid()
                        
 
                        Function Prototype:
                        
 
                           #include <nuttx/nx/nxglib.h>
@@ -1752,7 +1891,7 @@ int nx_filltrapezoid(NXWINDOW hwnd, FAR const struct nxgl_rect_s *clip,
   ERROR on failure with errno set appropriately
 
                          
 
-
                          2.3.22 nx_drawline()
                          
+
                          2.3.24 nx_drawline()
                          
 
                          Function Prototype:
                          
 
                             #include <nuttx/nx/nxglib.h>
@@ -1800,7 +1939,7 @@ int nx_drawline(NXWINDOW hwnd, FAR struct nxgl_vector_s *vector,
   ERROR on failure with errno set appropriately
 
                            
 
-
                            2.3.23 nx_drawcircle()
                            
+
                            2.3.25 nx_drawcircle()
                            
 
                            Function Prototype:
                            
 
                               #include <nuttx/nx/nxglib.h>
@@ -1836,7 +1975,7 @@ int nx_drawcircle(NXWINDOW hwnd, FAR const struct nxgl_point_s *center,
   ERROR on failure with errno set appropriately
 
                              
 
-
                              2.3.24 nx_fillcircle()
                              
+
                              2.3.26 nx_fillcircle()
                              
 
                              Function Prototype:
                              
 
                                 #include <nuttx/nx/nxglib.h>
@@ -1869,7 +2008,7 @@ int nx_fillcircle(NXWINDOW hwnd, FAR const struct nxgl_point_s *center,
   ERROR on failure with errno set appropriately
 
                                
 
-
                                2.3.25 nx_setbgcolor()
                                
+
                                2.3.27 nx_setbgcolor()
                                
 
                                Function Prototype:
                                
 
                                   #include <nuttx/nx/nxglib.h>
@@ -1897,7 +2036,7 @@ int nx_setbgcolor(NXHANDLE handle,
   ERROR on failure with errno set appropriately
 
                                  
 
-
                                  2.3.26 nx_move()
                                  
+
                                  2.3.28 nx_move()
                                  
 
                                  Function Prototype:
                                  
 
                                     #include <nuttx/nx/nxglib.h>
@@ -1928,7 +2067,7 @@ int nx_move(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                                    
 
-
                                    2.3.27 nx_bitmap()
                                    
+
                                    2.3.29 nx_bitmap()
                                    
 
                                    Function Prototype:
                                    
 
                                       #include <nuttx/nx/nxglib.h>
@@ -1970,7 +2109,7 @@ int nx_bitmap(NXWINDOW hwnd, FAR const struct nxgl_rect_s *dest,
   ERROR on failure with errno set appropriately
 
                                      
 
-
                                      2.3.28 nx_kbdin()
                                      
+
                                      2.3.30 nx_kbdin()
                                      
 
                                      Function Prototype:
                                      
 
                                         #include <nuttx/nx/nxglib.h>
@@ -1993,7 +2132,7 @@ int nx_kbdin(NXHANDLE handle, uint8_t nch, FAR const uint8_t *ch);
   ERROR on failure with errno set appropriately
 
                                        
 
-
                                        2.3.29 nx_mousein()
                                        
+
                                        2.3.31 nx_mousein()
                                        
 
                                        Function Prototype:
                                        
 
                                           #include <nuttx/nx/nxglib.h>
@@ -2070,7 +2209,93 @@ int nx_mousein(NXHANDLE handle, nxgl_coord_t x, nxgl_coord_t y, uint8_t buttons)
 typedef FAR void *NXTKWINDOW;
 
                                        
 
-
                                        2.4.2 nxtk_openwindow()
                                        
+
                                        2.4.2 nxtk_block()
                                        
+
                                        Function Prototype:
                                        
+
                                          +#include <nuttx/nx/nxtk.h>
+
+int nxtk_block(NXWINDOW hwnd, FAR void *arg);
+
                                        
+
                                        
+  Description:
+   The response to this function call is two things:  (1) any queued callback messages to the window are 'blocked' and then (2) also subsequent window messaging is blocked.
+
                                        
+
                                        
+   The event callback with the NXEVENT_BLOCKED event is the response from nxtk_block().  This blocking interface is used to assure that no further messages are are directed to the window. Receipt of the NXEVENT_BLOCKED event signifies that (1) there are no further pending callbacks and (2) that the window is now defunct and will receive no further callbacks.
+
                                        
+
                                        
+   This callback supports coordinated destruction of a window.  The client window logic must stay intact until all of the queued callbacks are processed.  Then the window may be safely closed.  Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed.
+
                                        
+
                                        
+  Input Parameters:
+  
                                          
+  
                                          
+    
                                          wnd
+    
                                          The window to be blocked
+    
                                          arg
+    
                                          An argument that will accompany the block messages (This is arg2 in the event callback).
+  
                                        
+
                                        
+
                                        
+  Returned Value:
+  OK on success; ERROR on failure with errno set appropriately.
+
                                        
+
+
                                        2.4.3 nxtk_synch()
                                        
+
                                        Function Prototype:
                                        
+
                                          +#include <nuttx/nx/nxtk.h>
+
+int nxtk_synch(NXWINDOW hwnd, FAR void *arg);
+
                                        
+
                                        
+  Description:
+  This interface can be used to synchronize the window client with the NX server.  It really just implements an echo:  A synch message is sent from the window client to the server which then responds immediately by sending the NXEVENT_SYNCHED back to the windows client.
+
                                        
+
                                        
+  Due to the highly asynchronous nature of client-server communications, nx_synch() is sometimes necessary to assure that the client and server are fully synchronized in time.
+
                                        
+
                                        
+  Usage by the window client might be something like this:
+
                                        
+
                                          +  extern bool g_synched;
+  extern sem_t g_synch_sem;
+
+  g_synched = false;
+  ret = nxtk_synch(hfwnd, handle);
+  if (ret < 0)
+    {
+       -- Handle the error --
+    }
+
+  while (!g_synched)
+    {
+      ret = sem_wait(&g_sync_sem);
+      if (ret < 0)
+        {
+           -- Handle the error --
+        }
+    }
+
                                        
+
                                        
+   When the window listener thread receives the NXEVENT_SYNCHED event, it would set g_synched to true and post g_synch_sem, waking up the above loop.
+
                                        
+
                                        
+  Input Parameters:
+  
                                          
+    
                                          wnd
+    
                                          The window to be synched
+    
                                          arg
+    
                                          An argument that will accompany the synch messages (This is arg2 in the event callback).
+  
                                        
+
                                        
+
                                        
+  Returned Value:
+  OK on success; ERROR on failure with errno set appropriately
+
                                        
+
+
                                        2.4.4 nxtk_openwindow()
                                        
 
                                        Function Prototype:
                                        
 
                                           #include <nuttx/nx/nxglib.h>
@@ -2107,7 +2332,7 @@ NXTKWINDOW nxtk_openwindow(NXHANDLE handle, uint8_t flags,
     Failure:  NULL is returned and errno is set appropriately.
 
                                        
 
-
                                        2.4.3 nxtk_closewindow()
                                        
+
                                        2.4.5 nxtk_closewindow()
                                        
 
                                        Function Prototype:
                                        
 
                                           #include <nuttx/nx/nxglib.h>
@@ -2134,7 +2359,7 @@ int nxtk_closewindow(NXTKWINDOW hfwnd);
   ERROR on failure with errno set appropriately
 
                                          
 
-
                                          2.4.4 nxtk_getposition()
                                          
+
                                          2.4.6 nxtk_getposition()
                                          
 
                                          Function Prototype:
                                          
 
                                             #include <nuttx/nx/nxglib.h>
@@ -2163,7 +2388,7 @@ int nxtk_getposition(NXTKWINDOW hfwnd);
   ERROR on failure with errno set appropriately
 
                                            
 
-
                                            2.4.5 nxtk_setposition()
                                            
+
                                            2.4.7 nxtk_setposition()
                                            
 
                                            Function Prototype:
                                            
 
                                               #include <nuttx/nx/nxglib.h>
@@ -2194,7 +2419,7 @@ int nxtk_setposition(NXTKWINDOW hfwnd, FAR struct nxgl_point_s *pos);
   ERROR on failure with errno set appropriately
 
                                              
 
-
                                              2.4.6 nxtk_setsize()
                                              
+
                                              2.4.8 nxtk_setsize()
                                              
 
                                              Function Prototype:
                                              
 
                                                 #include <nuttx/nx/nxglib.h>
@@ -2225,7 +2450,7 @@ int nxtk_setsize(NXTKWINDOW hfwnd, FAR struct nxgl_size_s *size);
   ERROR on failure with errno set appropriately
 
                                                
 
-
                                                2.4.7 nxtk_raise()
                                                
+
                                                2.4.9 nxtk_raise()
                                                
 
                                                Function Prototype:
                                                
 
                                                   #include <nuttx/nx/nxglib.h>
@@ -2256,7 +2481,7 @@ int nxtk_raise(NXTKWINDOW hfwnd);
   ERROR on failure with errno set appropriately
 
                                                  
 
-
                                                  2.4.8 nxtk_lower()
                                                  
+
                                                  2.4.10 nxtk_lower()
                                                  
 
                                                  Function Prototype:
                                                  
 
                                                     #include <nuttx/nx/nxglib.h>
@@ -2287,7 +2512,7 @@ int nxtk_lower(NXTKWINDOW hfwnd);
   ERROR on failure with errno set appropriately
 
                                                    
 
-
                                                    2.4.9 nxtk_fillwindow()
                                                    
+
                                                    2.4.11 nxtk_fillwindow()
                                                    
 
                                                    Function Prototype:
                                                    
 
                                                       #include <nuttx/nx/nxglib.h>
@@ -2319,7 +2544,7 @@ int nxtk_fillwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                                                      
 
-
                                                      2.4.10 nxtk_getwindow()
                                                      
+
                                                      2.4.12 nxtk_getwindow()
                                                      
 
                                                      Function Prototype:
                                                      
 
                                                         #include <nuttx/nx/nxglib.h>
@@ -2359,7 +2584,7 @@ void nxtk_getwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                                                        
 
-
                                                        2.4.11 nxtk_filltrapwindow()
                                                        
+
                                                        2.4.13 nxtk_filltrapwindow()
                                                        
 
                                                        Function Prototype:
                                                        
 
                                                           #include <nuttx/nx/nxglib.h>
@@ -2392,7 +2617,7 @@ int nxtk_filltrapwindow(NXTKWINDOW hfwnd,
   ERROR on failure with errno set appropriately
 
                                                          
 
-
                                                          2.4.12 nxtk_drawlinewindow()
                                                          
+
                                                          2.4.14 nxtk_drawlinewindow()
                                                          
 
                                                          Function Prototype:
                                                          
 
                                                             #include <nuttx/nx/nxglib.h>
@@ -2441,7 +2666,7 @@ int nxtk_drawlinewindow(NXTKWINDOW hfwnd, FAR struct nxgl_vector_s *vector,
   ERROR on failure with errno set appropriately
 
                                                            
 
-
                                                            2.4.13 nxtk_drawcirclewindow()
                                                            
+
                                                            2.4.15 nxtk_drawcirclewindow()
                                                            
 
                                                            Function Prototype:
                                                            
 
                                                               #include <nuttx/nx/nxglib.h>
@@ -2477,7 +2702,7 @@ int nxtk_drawcirclewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_point_s *cente
   ERROR on failure with errno set appropriately
 
                                                              
 
-
                                                              2.4.14 nxtk_fillcirclewindow()
                                                              
+
                                                              2.4.16 nxtk_fillcirclewindow()
                                                              
 
                                                              Function Prototype:
                                                              
 
                                                                 #include <nuttx/nx/nxglib.h>
@@ -2510,7 +2735,7 @@ int nxtk_fillcirclewindow(NXWINDOW hfwnd, FAR const struct nxgl_point_s *center,
   ERROR on failure with errno set appropriately
 
                                                                
 
-
                                                                2.4.15 nxtk_movewindow()
                                                                
+
                                                                2.4.17 nxtk_movewindow()
                                                                
 
                                                                Function Prototype:
                                                                
 
                                                                   #include <nuttx/nx/nxglib.h>
@@ -2543,7 +2768,7 @@ int nxtk_movewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                                                                  
 
-
                                                                  2.4.16 nxtk_bitmapwindow()
                                                                  
+
                                                                  2.4.18 nxtk_bitmapwindow()
                                                                  
 
                                                                  Function Prototype:
                                                                  
 
                                                                     #include <nuttx/nx/nxglib.h>
@@ -2588,7 +2813,7 @@ int nxtk_bitmapwindow(NXTKWINDOW hfwnd,
   ERROR on failure with errno set appropriately
 
                                                                    
 
-
                                                                    2.4.17 nxtk_opentoolbar()
                                                                    
+
                                                                    2.4.19 nxtk_opentoolbar()
                                                                    
 
                                                                    Function Prototype:
                                                                    
 
                                                                       #include <nuttx/nx/nxglib.h>
@@ -2623,7 +2848,7 @@ int nxtk_opentoolbar(NXTKWINDOW hfwnd, nxgl_coord_t height,
   ERROR on failure with errno set appropriately
 
                                                                      
 
-
                                                                      2.4.18 nxtk_closetoolbar()
                                                                      
+
                                                                      2.4.20 nxtk_closetoolbar()
                                                                      
 
                                                                      Function Prototype:
                                                                      
 
                                                                         #include <nuttx/nx/nxglib.h>
@@ -2652,7 +2877,7 @@ int nxtk_closetoolbar(NXTKWINDOW hfwnd);
   ERROR on failure with errno set appropriately
 
                                                                        
 
-
                                                                        2.4.19 nxtk_filltoolbar()
                                                                        
+
                                                                        2.4.21 nxtk_filltoolbar()
                                                                        
 
                                                                        Function Prototype:
                                                                        
 
                                                                           #include <nuttx/nx/nxglib.h>
@@ -2684,7 +2909,7 @@ int nxtk_filltoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                                                                          
 
-
                                                                          2.4.19 nxtk_gettoolbar()
                                                                          
+
                                                                          2.4.22 nxtk_gettoolbar()
                                                                          
 
                                                                          Function Prototype:
                                                                          
 
                                                                             #include <nuttx/nx/nxglib.h>
@@ -2725,7 +2950,7 @@ int nxtk_gettoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                                                                            
 
-
                                                                            2.4.21 nxtk_filltraptoolbar()
                                                                            
+
                                                                            2.4.23 nxtk_filltraptoolbar()
                                                                            
 
                                                                            Function Prototype:
                                                                            
 
                                                                               #include <nuttx/nx/nxglib.h>
@@ -2757,7 +2982,7 @@ int nxtk_filltraptoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_trapezoid_s *tr
   ERROR on failure with errno set appropriately
 
                                                                              
 
-
                                                                              2.4.22 nxtk_drawlinetoolbar()
                                                                              
+
                                                                              2.4.24 nxtk_drawlinetoolbar()
                                                                              
 
                                                                              Function Prototype:
                                                                              
 
                                                                                 #include <nuttx/nx/nxglib.h>
@@ -2806,7 +3031,7 @@ int nxtk_drawlinetoolbar(NXTKWINDOW hfwnd, FAR struct nxgl_vector_s *vector,
   ERROR on failure with errno set appropriately
 
                                                                                
 
-
                                                                                2.4.23 nxtk_drawcircletoolbar()
                                                                                
+
                                                                                2.4.25 nxtk_drawcircletoolbar()
                                                                                
 
                                                                                Function Prototype:
                                                                                
 
                                                                                   #include <nuttx/nx/nxglib.h>
@@ -2842,7 +3067,7 @@ int nxtk_drawcircletoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_point_s *cent
   ERROR on failure with errno set appropriately
 
                                                                                  
 
-
                                                                                  2.4.24 nxtk_fillcircletoolbar()
                                                                                  
+
                                                                                  2.4.26 nxtk_fillcircletoolbar()
                                                                                  
 
                                                                                  Function Prototype:
                                                                                  
 
                                                                                     #include <nuttx/nx/nxglib.h>
@@ -2875,7 +3100,7 @@ int nxtk_fillcircletoolbar(NXWINDOW hfwnd, FAR const struct nxgl_point_s *center
   ERROR on failure with errno set appropriately
 
                                                                                    
 
-
                                                                                    2.4.25 nxtk_movetoolbar()
                                                                                    
+
                                                                                    2.4.27 nxtk_movetoolbar()
                                                                                    
 
                                                                                    Function Prototype:
                                                                                    
 
                                                                                       #include <nuttx/nx/nxglib.h>
@@ -2909,7 +3134,7 @@ int nxtk_movetoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                                                                                      
 
-
                                                                                      2.4.26 nxtk_bitmaptoolbar()
                                                                                      
+
                                                                                      2.4.28 nxtk_bitmaptoolbar()
                                                                                      
 
                                                                                      Function Prototype:
                                                                                      
 
                                                                                         #include <nuttx/nx/nxglib.h>
@@ -3138,7 +3363,115 @@ int nxf_convert_32bpp(FAR uint32_t *dest, uint16_t height,
   ERROR on failure with errno set appropriately.
 
                                                                                        
 
-
                                                                                        2.6 Sample Code
                                                                                        
+
+
+   
                                                                                        
+     2.6 
+   
                                                                                        
+   
                                                                                        
+     
                                                                                        
+   
                                                                                        
+
+
                                                                                        2.6 NX Cursor Support (NXCURSOR)
                                                                                        
+
+
                                                                                        2.6.1 nxcursor_enable()
                                                                                        
+
                                                                                        Function Prototype:
                                                                                        
+
                                                                                          +#include <nuttx/nx/nxcursor.h>
+
+#ifdef CONFIG_NX_SWCURSOR
+int nxcursor_enable(NXHANDLE hnd, bool enable);
+#endif
+
                                                                                        
+
                                                                                        
+  Description:
+  Enable/disable presentation of the cursor.  The disabled cursor still exits and still may be controlled, but is not visible on the display.
+
                                                                                        
+
                                                                                        
+  Input Parameters:
+  
                                                                                          
+    
                                                                                          hnd
+    
                                                                                          The server handle returned by nx_connect().
+    
                                                                                          enable
+    
                                                                                          The new cursor position
+  
                                                                                        
+
                                                                                        
+
                                                                                        
+  Returned Value:
+  OK on success; ERROR on failure with errno set appropriately.
+
                                                                                        
+
+
                                                                                        2.6.2 nxcursor_setimage()
                                                                                        
+
                                                                                        Function Prototype:
                                                                                        
+
                                                                                          +#include <nuttx/nx/nxcursor.h>
+
+#ifdef CONFIG_NX_SWCURSOR
+int nxcursor_setimage(NXHANDLE hnd, FAR const struct nx_cursorimage_s *image);
+#endif
+
                                                                                        
+
                                                                                        
+  Description:
+  Set the cursor image.
+
                                                                                        
+
                                                                                        
+  The image is provided a a 2-bits-per-pixel image.  The two bit incoding is as followings:
+
                                                                                        
+
                                                                                          
+  00 - The transparent background.
                                                                                          
+  01 - Color1:  The main color of the cursor.
                                                                                          
+  10 - Color2:  The color of any border.
                                                                                          
+  11 - Color3:  A blend color for better imaging (fake anti-aliasing).
                                                                                          
+
                                                                                        
+
                                                                                        
+  NOTE: The NX logic will reference the user image buffer repeatedly.  That image buffer must persist for as long as the NX server connection persists.
+
                                                                                        
+
                                                                                        
+  Input Parameters:
+  
                                                                                          
+    
                                                                                          hnd
+    
                                                                                          The server handle returned by nx_connect().
+    
                                                                                          image
+    
                                                                                          An instance of struct struct nx_cursorimage_s that describes the cursor image.  See  <nuttx/nx/nxcursor.h> for the full description of this structure.
+  
                                                                                        
+
                                                                                        
+
                                                                                        
+  Returned Value:
+  OK on success; ERROR on failure with errno set appropriately.
+
                                                                                        
+
+
                                                                                        2.6.3 nxcursor_setposition()
                                                                                        
+
                                                                                        Function Prototype:
                                                                                        
+
                                                                                          +#include <nuttx/nx/nxcursor.h>
+
+#ifdef CONFIG_NX_SWCURSOR
+int nxcursor_setposition(NXHANDLE hnd, FAR const struct nxgl_point_s *pos);
+#endif
+
                                                                                        
+
                                                                                        
+  Description:
+  Move the cursor to the specified position.
+
                                                                                        
+
                                                                                        
+  Input Parameters:
+  
                                                                                          
+    
                                                                                          hnd
+    
                                                                                          The server handle returned by nx_connect().
+    
                                                                                          pos
+    
                                                                                          The new cursor position
+  
                                                                                        
+
                                                                                        
+
                                                                                        
+  Returned Value:
+  OK on success; ERROR on failure with errno set appropriately.
+
                                                                                        
+
+
                                                                                        2.7 Sample Code
                                                                                        
 
 
                                                                                        apps/examples/nx*.
   No sample code is provided in this document.
diff --git a/include/nuttx/nx/nx.h b/include/nuttx/nx/nx.h
index 4ed0fcb21e9..86d3f397654 100644
--- a/include/nuttx/nx/nx.h
+++ b/include/nuttx/nx/nx.h
@@ -239,7 +239,7 @@ struct nx_callback_s
    *     the client and server are fully synchronized.
    *
    * Input Parameters:
-   *   hwnd  - Window handle of the blocked window
+   *   hwnd  - Window handle of window receiving the event
    *   event - The server event
    *   arg1  - User provided argument (see nx_openwindow, nx_requestbkgd,
    *           nxtk_openwindow, or nxtk_opentoolbar)
@@ -441,8 +441,9 @@ int nx_closewindow(NXWINDOW hwnd);
  * Name: nx_block
  *
  * Description:
- *   This is callback will do to things:  (1) any queue a 'blocked' callback
- *   to the window and then (2) block any further window messaging.
+ *   The response to this function call is two things:  (1) any queued
+ *   callback messages to the window are 'blocked' and then (2) also
+ *   subsequent window messaging is blocked.
  *
  *   The 'event' callback with the NXEVENT_BLOCKED event is the response
  *   from nx_block (or nxtk_block).  Those blocking interfaces are used to
@@ -473,7 +474,7 @@ int nx_block(NXWINDOW hwnd, FAR void *arg);
  * Name: nx_synch
  *
  * Description:
- *   This interface can be used to syncrhonize the window client with the
+ *   This interface can be used to synchronize the window client with the
  *   NX server.  It really just implements an 'echo':  A synch message is
  *   sent from the window client to the server which then responds
  *   immediately by sending the NXEVENT_SYNCHED back to the windows client.
@@ -503,13 +504,13 @@ int nx_block(NXWINDOW hwnd, FAR void *arg);
  *           }
  *       }
  *
- *   When the windwo listener thread receives the NXEVENT_SYNCHED event, it
+ *   When the window listener thread receives the NXEVENT_SYNCHED event, it
  *   would set g_synched to true and post g_synch_sem, waking up the above
  *   loop.
  *
  * Input Parameters:
  *   wnd - The window to be synched
- *   arg - An argument that will accompany the block messages (This is arg2
+ *   arg - An argument that will accompany the synch messages (This is arg2
  *         in the event callback).
  *
  * Returned Value:
diff --git a/include/nuttx/nx/nxcursor.h b/include/nuttx/nx/nxcursor.h
index ef2dede5bfa..023cdaadc26 100644
--- a/include/nuttx/nx/nxcursor.h
+++ b/include/nuttx/nx/nxcursor.h
@@ -124,7 +124,7 @@ struct nx_cursorimage_s
  * Name: nxcursor_enable
  *
  * Description:
- *   Enable/disable presentation of the cursor
+ *   Enable/disable presentation of the cursor.
  *
  * Input Parameters:
  *   hnd    - The server handle returned by nx_connect()
@@ -146,9 +146,9 @@ int nxcursor_enable(NXHANDLE hnd, bool enable);
  *   The image is provided a a 2-bits-per-pixel image.  The two bit incoding
  *   is as followings:
  *
- *   00 - The transparent background
- *   01 - Color1:  The main color of the cursor
- *   10 - Color2:  The color of any border
+ *   00 - The transparent background.
+ *   01 - Color1:  The main color of the cursor.
+ *   10 - Color2:  The color of any border.
  *   11 - Color3:  A blend color for better imaging (fake anti-aliasing).
  *
  *   NOTE: The NX logic will reference the user image buffer repeatedly.
@@ -179,7 +179,7 @@ int nxcursor_setimage(NXHANDLE hnd, FAR const struct nx_cursorimage_s *image);
  *   pos - The new cursor position
  *
  * Returned Value:
- *   OK on success; ERROR on failure with errno set appropriately
+ *   OK on success; ERROR on failure with errno set appropriately.
  *
  ****************************************************************************/
 
diff --git a/include/nuttx/nx/nxtk.h b/include/nuttx/nx/nxtk.h
index 415b9de5d02..0ec3918b148 100644
--- a/include/nuttx/nx/nxtk.h
+++ b/include/nuttx/nx/nxtk.h
@@ -158,8 +158,9 @@ int nxtk_closewindow(NXTKWINDOW hfwnd);
  * Name: nxtk_block
  *
  * Description:
- *   This is callback will do to things:  (1) any queue a 'blocked' callback
- *   to the window and then (2) block any further window messaging.
+ *   The response to this function call is two things:  (1) any queued
+ *   callback messages to the window are 'blocked' and then (2) also
+ *   subsequent window messaging is blocked.
  *
  *   The 'event' callback with the NXEVENT_BLOCKED event is the response
  *   from nx_block (or nxtk_block).  Those blocking interfaces are used to