NXGraphicsSubsystem.html

    <dd>The name for the server incoming message queue
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
</p>
<ul>
    Success: A non-NULL handle used with subsequent NX accesses<br>
    Failure:  NULL is returned and <code>errno</code> is set appropriately.
</ul>

<h3>2.3.6 <a name="nxopen"><code>nx_open()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

#ifndef CONFIG_NX_MULTIUSER
NXHANDLE nx_open(FAR struct fb_vtable_s *fb);
#endif
</pre></ul>
<p>
  <b>Description:</b>
    Create, initialize and return an NX handle for use in subsequent
    NX API calls.  <code>nx_open()</code> is the single user equivalent of
    <a href="#nxconnectinstance"><code>nx_connect()</code></a> plus
    <a href="#nxruninstance"><code>nx_run()</code></a>.
</p>
<p>
    Single user mode only!
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>fb</code>
    <dd>Vtable &quot;object&quot; of the framebuffer &quot;driver&quot; to use
    <dt><code>cb</code>
    <dd>Callbacks used to process received NX server messages
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
</p>
<ul>
    Success: A non-NULL handle used with subsequent NX accesses<br>
    Failure:  NULL is returned and <code>errno</code> is set appropriately.
</ul>

<h3>2.3.7 <a name="nxdisconnect"><code>nx_disconnect()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

#ifdef CONFIG_NX_MULTIUSER
void nx_disconnect(NXHANDLE handle);
#endif
</pre></ul>
<p>
  <b>Description:</b>
  Disconnect a client from the NX server and/or free resources reserved
  by <a href="#nxconnectinstance"><code>nx_connect()</code>/<code>nx_connectinstance()</code></a>.
  <code>nx_disconnect()</code> is muliti-user equivalent of
  <a href="#nxclose"><code>nx_close()</code></a>.
</p>
<p>
  Multiple user mode only!
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>handle</code>
    <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b> None.
</p>

<h3>2.3.8 <a name="nxclose"><code>nx_close()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

#ifndef CONFIG_NX_MULTIUSER
void nx_close(NXHANDLE handle);
#endif
</pre></ul>
<p>
  <b>Description:</b>
  Close the single user NX interface.  nx_close is single-user equivalent
  of <a href="#nxdisconnect"><code>nx_disconnect()</code></a>.
</p>
<p>
  Single user mode only!
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>handle</code>
    <dd>The handle returned by <a href="#nxopen"><code>nx_open()</code></a>.
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b> None
</p>

<h3>2.3.9 <a name="nxeventhandler"><code>nx_eventhandler()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

#ifdef CONFIG_NX_MULTIUSER
int nx_eventhandler(NXHANDLE handle);
#else
#  define nx_eventhandler(handle) (OK)
#endif
</pre></ul>
<p>
  <b>Description:</b>
  The client code must call this function periodically to process
  incoming messages from the server.  If <code>CONFIG_NX_BLOCKING</code> is defined,
  then this function not return until a server message is received.
</p>
<p>
  When <code>CONFIG_NX_BLOCKING</code> is not defined, the client must exercise
  caution in the looping to assure that it does not eat up all of
  the CPU bandwidth calling nx_eventhandler repeatedly.
  <a href="#nxeventnotify"><code>nx_eventnotify()</code></a>
  may be called to get a signal event whenever a new incoming server
  event is avaiable.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>handle</code>
    <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
</p>
<ul>
  <li>
    <code>OK</code>: No errors occurred.  If <code>CONFIG_NX_BLOCKING</code> is defined,
    then one or more server messages were processed.
  </li>
  <li>
    <code>ERROR</code>: An error occurred and <code>errno</code> has been set appropriately.
    Of particular interest, it will return <code>errno == EHOSTDOWN</code> when the
    server is disconnected.  After that event, the handle can no longer be used.
  </li>
</ul>

<h3>2.3.10 <a name="nxeventnotify"><code>nx_eventnotify()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

#if defined(CONFIG_NX_MULTIUSER) && !defined(CONFIG_DISABLE_SIGNALS)
int nx_eventnotify(NXHANDLE handle, int signo);
#else
#  define nx_eventnotify(handle, signo) (OK)
#endif
</pre></ul>
<p>
  <b>Description:</b>
  Rather than calling <a href="#nxeventhandler"><code>nx_eventhandler()</code></a> periodically,
  the client may register to receive a signal when a server event is available.
  The client can then call <a href="#nxeventhandler"><code>nv_eventhandler()</code></a> only when
  incoming events are available.
</p>
<p>
  The underlying implementation used <code>mq_notifiy()</code> and, as a result,
  the client must observe the rules for using <code>mq_notifiy()</code>:
  <ul>
    <li>
      Only one event is signaled.  Upon receipt of the signal, if the client
      wishes further notifications, it must call <code>nx_eventnotify()</code> again.
    </li>
    <li>
      The signal will only be issued when the message queue transitions from empty to
      not empty.
    </li>
  </ul>
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>handle</code>
    <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>.
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.11 <a name="nxopenwindow"><code>nx_openwindow()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

NXWINDOW nx_openwindow(NXHANDLE handle,
                       FAR const struct nx_callback_s *cb,
                       FAR void *arg);
</pre></ul>
<p>
  <b>Description:</b> Create a new window.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>handle</code>
    <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>
       or <a href="#nxopen"><code>nx_open()</code></a>.
    <dt><code>cb</code>
    <dd>Callbacks used to process window events
    <dt><code>arg</code>
    <dd>User provided value that will be returned with NX callbacks.
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
</p>
<ul>
    Success: A non-NULL handle used with subsequent NX accesses<br>
    Failure:  NULL is returned and <code>errno</code> is set appropriately.
</ul>

<h3>2.3.12 <a name="nxclosewindow"><code>nx_closewindow()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_closewindow(NXWINDOW hwnd);
</pre></ul>
<p>
  <b>Description:</b>
  Destroy a window created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> window.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>hwnd</code>
    <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
       that identifies the window to be  destroyed.
       This handle must not have been one returned by
       <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.13 <a name="nxrequestbkgd"><code>nx_requestbkgd()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_requestbkgd(NXHANDLE handle,
                   FAR const struct nx_callback_s *cb,
                   FAR void *arg);
</pre></ul>
<p>
  <b>Description:</b>
  NX normally controls a separate window called the background window.
  It repaints the window as necessary using only a solid color fill.  The
  background window always represents the entire screen and is always
  below other windows.  It is useful for an application to control the
  background window in the following conditions:
</p>
<ul>
  <li>
    If you want to implement a windowless solution.  The single screen
    can be used to creat a truly simple graphic environment.  In this
    case, you should probably also de-select <code>CONFIG_NX_MULTIUSER</code> as well.
  </li>
  <li>
    When you want more on the background than a solid color.  For
    example, if you want an image in the background, or animations in the
    background, or live video, etc.
  </li>
</ul>
<p>
  This API only requests the handle of the background window.  That
  handle will be returned asynchronously in a subsequent position and
  redraw callbacks.
</p>
<p>
  Cautions:
</p>
<ul>
  <li>
    The following should never be called using the background window.
    They are guaranteed to cause severe crashes:
    <a href="#nxsetposition"><code>nx_setposition()</code></a>,
    <a href="#nxsetsize"><code>nx_setsize()</code></a>,
    <a href="#nxraise"><code>nx_raise()</code></a>, or
    <a href="#nxlower"><code>nx_lower()</code></a>.
  </li>
  <li>
    Neither <code>nx_requestbkgd()</code> nor
    <a href="#nxreleasebkgd"><code>nx_releasebkgd ()</code></a> should be called more than once.
    Multiple instances of the background window are not supported.
  </li>
</ul>
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>handle</code>
    <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>
       or <a href="#nxopen"><code>nx_open()</code></a>.
    <dt><code>cb</code>
    <dd>Callbacks to use for processing background window events
    <dt><code>arg</code>
    <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>)
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.14 <a name="nxreleasebkgd"><code>nx_releasebkgd()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_releasebkgd(NXWINDOW hwnd);
</pre></ul>
<p>
  <b>Description:</b>
  Release the background window previously acquired using
  <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
  and return control of the background to NX.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>handle</code>
    <dd>The handle returned indirectly by
      <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
      This handle must not have been one created by
      <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.15 <a name="nxgetposition"><code>nx_getposition()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_getposition(NXWINDOW hwnd);
</pre></ul>
<p>
  <b>Description:</b>
   Request the position and size information for the selected window.  The
   values will be return asynchronously through the client callback function
   pointer.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>hwnd</code>
    <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> or
      <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.16 <a name="nxsetposition"><code>nx_setposition()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_setposition(NXWINDOW hwnd, FAR struct nxgl_point_s *pos);
</pre></ul>
<p>
  <b>Description:</b>
  Set the position and size for the selected window.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>hwnd</code>
    <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
      This handle must not have been created by 
      <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
    <dt><code>pos</code>
    <dd>The new position of the window
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.17 <a name="nxsetsize"><code>nx_setsize()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_setsize(NXWINDOW hwnd, FAR struct nxgl_size_s *size);
</pre></ul>
<p>
  <b>Description:</b> Set the size of the selected window.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>hwnd</code>
    <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
      This handle must not have been created by 
      <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
    <dt><code>size</code>
    <dd>The new size of the window (in pixels).
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.18 <a name="nxraise"><code>nx_raise()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_raise(NXWINDOW hwnd);
</pre></ul>
<p>
  <b>Description:</b> Bring the specified window to the top of the display.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>hwnd</code>
    <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
      This handle must not have been created by 
      <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
    <dt><code></code>
    <dd>
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.19 <a name="nxlower"><code>nx_lower()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_lower(NXWINDOW hwnd);
</pre></ul>
<p>
  <b>Description:</b> Lower the specified window to the bottom of the display.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>hwnd</code>
    <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>.
      This handle must not have been created by 
      <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>.
    <dt><code></code>
    <dd>
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.20 <a name="nxfill"><code>nx_fill()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
                   nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
</pre></ul>
<p>
  <b>Description:</b>
   Fill the specified rectangle in the window with the specified color.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>hwnd</code>
    <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
      or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
    <dt><code>rect</code>
    <dd>The location to be filled
    <dt><code>color</code>
    <dd>The color to use in the fill
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.21 <a name="nxfilltrapezoid"><code>nx_filltrapezoid()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_filltrapezoid(NXWINDOW hwnd, FAR const struct nxgl_rect_s *clip,
                            FAR const struct nxgl_trapezoid_s *trap,
                            nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
</pre></ul>
<p>
  <b>Description:</b>
  Fill the specified trapezoidal region in the window with the specified color.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>hwnd</code>
    <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
      or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
    <dt><code>clip</code>
    <dd>Clipping rectangle relative to window (may be null)
    <dt><code>trap</code>
    <dd>The trapezoidal region to be filled
    <dt><code>color</code>
    <dd>The color to use in the fill
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.22 <a name="nxglrgb2yuv"><code>nx_setbgcolor()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_setbgcolor(NXHANDLE handle,
                  nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
</pre></ul>
<p>
  <b>Description:</b> Set the color of the background.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>handle</code>
    <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
      or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>
    <dt><code>color</code>
    <dd>The color to use in the background
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.23 <a name="nxmove"><code>nx_move()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_move(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
                   FAR const struct nxgl_point_s *offset);
</pre></ul>
<p>
  <b>Description:</b> Move a rectangular region within the window.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>hwnd</code>
    <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
      or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> that specifies
      the window within which the move is to be done
    <dt><code>rect</code>
    <dd>Describes the (source) rectangular region to move
    <dt><code>offset</code>
    <dd>The offset to move the region
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.24 <a name="nxbitmap"><code>nx_bitmap()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

int nx_bitmap(NXWINDOW hwnd, FAR const struct nxgl_rect_s *dest,
                     FAR const void *src[CONFIG_NX_NPLANES],
                     FAR const struct nxgl_point_s *origin,
                     unsigned int stride);
</pre></ul>
<p>
  <b>Description:</b>
  Copy a rectangular region of a larger image into the rectangle in the
  specified window.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code>hwnd</code>
    <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>
      or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> that specifies the
      window that will receive the bitmap image.
    <dt><code>dest</code>
    <dd> Describes the rectangular on the display that will receive the the bit map.
    <dt><code>src</code>
    <dd>The start of the source image.  This is an array source images of size
      <code>CONFIG_NX_NPLANES</code> (probably 1).
    <dt><code>origin</code>
    <dd>The origin of the upper, left-most corner of the full bitmap.
     Both dest and origin are in window coordinates, however, the origin
     may lie outside of the display.
    <dt><code>stride</code>
    <dd>The width of the full source image in bytes.
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.25 <a name="nxkbdin"><code>nx_kbdin()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

#ifdef CONFIG_NX_KBD
int nx_kbdchin(NXHANDLE handle, ubyte ch);
int nx_kbdin(NXHANDLE handle, ubyte nch, FAR const ubyte *ch);
#endif
</pre></ul>
<p>
  <b>Description:</b>
  Used by a thread or interrupt handler that manages some kind of keypad
  hardware to report text information to the NX server.  That text
  data will be routed by the NX server to the appropriate window client.
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.3.26 <a name="nxmousein"><code>nx_mousein()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;

#ifdef CONFIG_NX_MOUSE
int nx_mousein(NXHANDLE handle, nxgl_coord_t x, nxgl_coord_t y, ubyte buttons);
#endif
</pre></ul>
<p>
  <b>Description:</b>
  Used by a thread or interrupt handler that manages some kind of pointing
  hardware to report new positional data to the NX server.  That positional
  data will be routed by the NX server to the appropriate window client.
</p>
<p>
  <b>Input Parameters:</b>
  <ul><dl>
    <dt><code></code>
    <dd>
  </dl></ul>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h2>2.4 <a name="nxtk2">NX Tool Kit (<code>NXTK</code>)</a></h2>

<p>
  NXTK implements  where the <i>framed window</i>.
  NX framed windows consist of three components within one NX window:
</p>
<ol>
  <li>The window <i>border</i>,</li>
  <li>The main <i>client window</i> area, and</li>
  <li>A <i>toolbar</i> area</li>
</ol>

<p>
  Each sub-window represents a region within one window.
  <a href="#screenshot">Figure 1</a> shows some simple NX framed windows.
  NXTK allows these sub-windows to be managed more-or-less independently:
</p>
<ul>
  <li>
    Each component has its own callbacks for redraw and position events
    as well as mouse and keyboard inputs.
    The client sub-window callbacks are registered when the framed window is
    created with a call to <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>;
    Separate toolbar sub-window callbakcs are reigistered when the toolbar
    is added using <a href="#nxtkopentoolbar"><code>nxtk_opentoolbar()</code></a>.
    (NOTES: (1) only the client sub-window receives keyboard input and,
    (2) border callbacks are not currently accessible by the user).
  <li>
  </li>
    All position informational provided within the callback is relative
    to the specific sub-window.
    That is, the origin (0,0) of the coordinate system for each sub-window
    begins at the top left corner of the subwindow.
    This means that toolbar logic need not be concerned about client window
    geometry (and vice versa) and, for example, common toolbar logic can
    be used with different windows.
  </li>
</ul>

<h3>2.4.1 <a name="nxtktypes"><code>NXTK Types()</code></a></h3>

<p>
  This is the handle that can be used to access the window data region.
</p>
<ul><pre>
typedef FAR void *NXTKWINDOW;
</pre></ul>

<h3>2.4.2 <a name="nxtkopenwindow"><code>nxtk_openwindow()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;
#include &lt;nuttx/nxtk.h&gt;

NXTKWINDOW nxtk_openwindow(NXHANDLE handle,
                           FAR const struct nx_callback_s *cb,
                           FAR void *arg);
</pre></ul>
<p>
  <b>Description:</b> Create a new, framed window.
</p>
<p>
  <b>Input Parameters:</b>
  <dl>
    <dt><code>handle</code>
    <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>
       or <a href="#nxopen"><code>nx_open()</code></a>.
    <dt><code>cb</code>
    <dd>Callbacks used to process window events
    <dt><code>arg</code>
    <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>)
  </dl>
</p>
<p>
  <b>Returned Value:</b>
</p>
<ul>
    Success: A non-NULL handle used with subsequent NXTK window accesses<br>
    Failure:  NULL is returned and <code>errno</code> is set appropriately.
</ul>

<h3>2.4.3 <a name="nxtkclosewindow"><code>nxtk_closewindow()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;
#include &lt;nuttx/nxtk.h&gt;

int nxtk_closewindow(NXTKWINDOW hfwnd);
</pre></ul>
<p>
  <b>Description:</b>
  Close the window opened by <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
</p>
<p>
  <b>Input Parameters:</b>
  <dl>
    <dt><code>hfwnd</code>
    <dd>A handle previously returned by
      <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
  </dl>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.4.4 <a name="nxtkgetposition"><code>nxtk_getposition()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;
#include &lt;nuttx/nxtk.h&gt;

int nxtk_getposition(NXTKWINDOW hfwnd);
</pre></ul>
<p>
  <b>Description:</b>
  Request the position and size information for the selected framed window.
  The size/position for the client window and toolbar will be return
  asynchronously through the client callback function pointer.
</p>
<p>
  <b>Input Parameters:</b>
  <dl>
    <dt><code>hfwnd</code>
    <dd>A handle previously returned by
      <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
  </dl>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.4.5 <a name="nxtksetposition"><code>nxtk_setposition()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;
#include &lt;nuttx/nxtk.h&gt;

int nxtk_setposition(NXTKWINDOW hfwnd, FAR struct nxgl_point_s *pos);
</pre></ul>
<p>
  <b>Description:</b>
  Set the position for the selected client window.  This position does not
  include the offsets for the borders nor for any toolbar.  Those offsets
  will be added in to set the full window position.
</p>
<p>
  <b>Input Parameters:</b>
  <dl>
    <dt><code>hfwnd</code>
    <dd>A handle previously returned by
      <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
    <dt><code>pos</code>
    <dd>The new position of the client sub-window
  </dl>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.4.6 <a name="nxtksetsize"><code>nxtk_setsize()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;
#include &lt;nuttx/nxtk.h&gt;

int nxtk_setsize(NXTKWINDOW hfwnd, FAR struct nxgl_size_s *size);
</pre></ul>
<p>
  <b>Description:</b>
  Set the size for the selected client window.  This size does not
  include the sizes of the borders nor for any toolbar.  Those sizes
  will be added in to set the full window size.
</p>
<p>
  <b>Input Parameters:</b>
  <dl>
    <dt><code>hfwnd</code>
    <dd>A handle previously returned by
      <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>.
    <dt><code>size</code>
    <dd>The new size of the client sub-window.
  </dl>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.4.7 <a name="nxtkraise"><code>nxtk_raise()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;
#include &lt;nuttx/nxtk.h&gt;

int nxtk_raise(NXTKWINDOW hfwnd);
</pre></ul>
<p>
  <b>Description:</b>
  Bring the window containing the specified client sub-window to the top
  of the display.
</p>
<p>
  <b>Input Parameters:</b>
  <dl>
    <dt><code>hfwnd</code>
    <dd>A handle previously returned by
      <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>
      specifying the window to be raised.
    <dt><code></code>
    <dd>
  </dl>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.4.8 <a name="nxtklower"><code>nxtk_lower()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;
#include &lt;nuttx/nxtk.h&gt;

int nxtk_lower(NXTKWINDOW hfwnd);
</pre></ul>
<p>
  <b>Description:</b>
  Lower the window containing the specified client sub-window to the
  bottom of the display.
</p>
<p>
  <b>Input Parameters:</b>
  <dl>
     <dt><code>hfwnd</code>
    <dd>A handle previously returned by
      <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>
      specifying the window to be lowered.
   <dt><code></code>
    <dd>
  </dl>
</p>
<p>
  <b>Returned Value:</b>
  <code>OK</code> on success;
  <code>ERROR</code> on failure with <code>errno</code> set appropriately
</p>

<h3>2.4.9 <a name="nxtkfillwindow"><code>nxtk_fillwindow()</code></a></h3>
<p><b>Function Prototype:</b></p>
<ul><pre>
#include &lt;nuttx/nxglib.h&gt;
#include &lt;nuttx/nx.h&gt;
#include &lt;nuttx/nxtk.h&gt;

int nxtk_fillwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect,
                    nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);
</pre></ul>
<p>
  <b>Description:</b>
  Fill the specified rectangle in the client window with the specified color.
</p>