nuttx/Documentation/components/nxgraphics/nxtk.rst

======================
NX Tool Kit (``NXTK``)
======================

NXTK implements where the *framed window*. NX framed windows consist of
three components within one NX window:

  #. The window *border*,
  #. The main *client window* area, and
  #. A *toolbar* area

Each sub-window represents a region within one window. `Figure
1 <#screenshot>`__ shows some simple NX framed windows. NXTK allows
these sub-windows to be managed more-or-less independently:

  -  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
     :c:func:`nxtk_openwindow`; Separate toolbar
     sub-window callbacks are reigistered when the toolbar is added using
     :c:func:`nxtk_opentoolbar`. (NOTES: (1) only the
     client sub-window receives keyboard input and, (2) border callbacks
     are not currently accessible by the user).
  -  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.

.. c:type:: FAR void *NXTKWINDOW

  This is the handle that can be used to access the window data region.

.. c:function:: int nxtk_block(NXWINDOW hwnd, FAR void *arg)

  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.

  :param wnd: The window to be blocked
  :param arg: An argument that will accompany the block messages (This is ``arg2`` in
    the event callback).

  :return: OK on success; ERROR on failure with errno set
    appropriately.

.. c:function:: int nxtk_synch(NXWINDOW hwnd, FAR void *arg);

  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:

  .. code-block:: c

    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.

  :param wnd:
     The window to be synched
  :param arg:
     An argument that will accompany the synch messages (This is ``arg2``
     in the event callback).

  :return: OK on success; ERROR on failure with errno set
    appropriately

.. c:function:: NXTKWINDOW nxtk_openwindow(NXHANDLE handle, uint8_t flags, \
                           FAR const struct nx_callback_s *cb, \
                           FAR void *arg);

  Create a new, framed window.

  :param handle:
     The handle returned by ```nx_connect()`` <#nxconnectinstance>`__.
  :param flags:
     Optional flags. These include:

     -  ``NXBE_WINDOW_RAMBACKED``: Creates a RAM backed window. This
        option is only valid if ``CONFIG_NX_RAMBACKED`` is enabled.
     -  ``NXBE_WINDOW_HIDDEN``: The window is create in the HIDDEN state
        and can be made visible later with ``nxtk_setvisibility()``.

  :param cb:
     Callbacks used to process window events
  :param arg:
     User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__)

  :return: Success: A non-NULL handle used with subsequent NXTK window accesses
    Failure: NULL is returned and errno is set appropriately.

.. c:function:: int nxtk_closewindow(NXTKWINDOW hfwnd);

  Close the window opened by
  ```nxtk_openwindow()`` <#nxtkopenwindow>`__.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_getposition(NXTKWINDOW hfwnd);

  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.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_setposition(NXTKWINDOW hfwnd, FAR struct nxgl_point_s *pos);

  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.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param pos:
     The new position of the client sub-window

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_setsize(NXTKWINDOW hfwnd, FAR struct nxgl_size_s *size);

  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.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param size:
     The new size of the client sub-window.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_raise(NXTKWINDOW hfwnd);

  Bring the window containing the specified client
  sub-window to the top of the display.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to
     be raised.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_lower(NXTKWINDOW hfwnd);

  Lower the window containing the specified client
  sub-window to the bottom of the display.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to
     be lowered.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_modal(NXWINDOW hwnd, bool modal);

  May be used to either (1) raise a window to the top of
  the display and select modal behavior, or (2) disable modal behavior.

  :param hwnd:
     The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
     specifying the window to be modified.
  :param modal:
     True: enter modal state; False: leave modal state

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_setvisibility(NXWINDOW hwnd, bool hide);

  Select if the window is visible or hidden. A hidden
  window is still present and will update normally, but will not be
  visible on the display until it is unhidden.

  :param hwnd:
     The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
     specifying the window to be modified.
  :param hide:
     True: Window will be hidden; false: Window will be visible

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: bool nxtk_ishidden(NXTKWINDOW hfwnd);

  Return true if the window is hidden.

  **NOTE**: There will be a delay between the time that the visibility of
  the window is changed via
  ```nxtk_setvisibily()`` <#nxtksetvisibility>`__ before that new setting
  is reported by ``nxtk_ishidden()``. ``nxtk_synch()`` may be used if
  temporal synchronization is required.

  :param hfwnd:
     The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__
     that identifies the window to be queried.

  :return: *True*: the window is hidden, *false*: the window is
    visible

.. c:function:: int nxtk_fillwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
                    nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);

  Fill the specified rectangle in the client window with
  the specified color.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param rect:
     The location within the client window to be filled
  :param color:
     The color to use in the fill

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: void nxtk_getwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
                    unsigned int plane, FAR uint8_t *dest, \
                    unsigned int deststride);

  Get the raw contents of graphic memory within a
  rectangular region. NOTE: Since raw graphic memory is returned, the
  returned memory content may be the memory of windows above this one and
  may not necessarily belong to this window unless you assure that this is
  the top window.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param rect:
     The location within the client window to be retrieved.
  :param plane:
     Specifies the color plane to get from.
  :param dest:
     The location to copy the memory region
  :param deststride:
     The width, in bytes, of the dest memory

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_filltrapwindow(NXTKWINDOW hfwnd, \
                        FAR const struct nxgl_trapezoid_s *trap, \
                        nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);

  Fill the specified trapezoid in the client window with
  the specified color

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param trap:
     The trapezoidal region to be filled.
  :param color:
     The color to use in the fill.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_drawlinewindow(NXTKWINDOW hfwnd, FAR struct nxgl_vector_s *vector, \
                        nxgl_coord_t width, nxgl_mxpixel_t color[CONFIG_NX_NPLANES], \
                        uint8_t caps);

  Fill the specified trapezoidal region in the window
  with the specified color. Fill the specified line in the window with the
  specified color. This is simply a wrapper that uses ``nxgl_splitline()``
  to break the line into trapezoids and then calls
  ``nxtk_filltrapwindow()`` to render the line.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param vector:
     Describes the line to be drawn.
  :param width:
     The width of the line
  :param color:
     The color to use to fill the line
  :param caps:
     Draw a circular cap on the ends of the line to support better line
     joins. One of:

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_drawcirclewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_point_s *center, \
                          nxgl_coord_t radius, nxgl_coord_t width, \
                          nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);

  Draw a circular outline using the specified line
  thickness and color.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param center:
     A pointer to the point that is the center of the circle.
  :param radius:
     The radius of the circle in pixels.
  :param width:
     The width of the line
  :param color:
     The color to use to fill the line

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_fillcirclewindow(NXWINDOW hfwnd, FAR const struct nxgl_point_s *center, \
                          nxgl_coord_t radius, nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);

  Fill a circular region using the specified color.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param center:
     A pointer to the point that is the center of the circle.
  :param radius:
     The width of the line
  :param color:
     The color to use to fill the circle

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_movewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
                    FAR const struct nxgl_point_s *offset);

  Move a rectangular region within the client sub-window
  of a framed window.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the client
     sub-window within which the move is to be done.
  :param rect:
     Describes the rectangular region relative to the client sub-window to
     move.
  :param offset:
     The offset to move the region

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_bitmapwindow(NXTKWINDOW hfwnd, \
                      FAR const struct nxgl_rect_s *dest, \
                      FAR const void *src[CONFIG_NX_NPLANES], \
                      FAR const struct nxgl_point_s *origin, \
                      unsigned int stride);

  Copy a rectangular region of a larger image into the
  rectangle in the specified client sub-window.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the client
     sub-window that will receive the bitmap.
  :param dest:
     Describes the rectangular region on in the client sub-window will
     receive the bit map.
  :param src:
     The start of the source image(s). This is an array source images of
     size ``CONFIG_NX_NPLANES`` (probably 1).
  :param origin:
     The origin of the upper, left-most corner of the full bitmap. Both
     dest and origin are in sub-window coordinates, however, the origin
     may lie outside of the sub-window display.
  :param stride:
     The width of the full source image in pixels.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_opentoolbar(NXTKWINDOW hfwnd, nxgl_coord_t height, \
                     FAR const struct nx_callback_s *cb, \
                     FAR void *arg);

  Create a tool bar at the top of the specified framed
  window.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param height:
     The requested height of the toolbar in pixels.
  :param cb:
     Callbacks used to process toolbar events.
  :param arg:
     User provided value that will be returned with toolbar callbacks.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_closetoolbar(NXTKWINDOW hfwnd);

  Remove the tool bar at the top of the specified framed
  window.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_filltoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
                     nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);

  Fill the specified rectangle in the toolbar sub-window
  with the specified color.

  :param hfwnd:
    A handle previously returned by
    ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param rect:
    The location within the toolbar window to be filled.
  :param color:
    The color to use in the fill.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_gettoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
                    unsigned int plane, FAR uint8_t *dest, \
                    unsigned int deststride);

  Get the raw contents of graphic memory within a
  rectangular region. NOTE: Since raw graphic memory is returned, the
  returned memory content may be the memory of windows above this one and
  may not necessarily belong to this window unless you assure that this is
  the top window.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param rect:
     The location within the toolbar window to be retrieved.
  :param plane:
     Specifies the color plane to get from.
  :param dest:
     The location to copy the memory region.
  :param deststride:
     The width, in bytes, of the dest memory.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_filltraptoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_trapezoid_s *trap, \
                         nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);

  Fill the specified trapezoid in the toolbar sub-window
  with the specified color.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param trap:
     The trapezoidal region to be filled
  :param color:
     The color to use in the fill

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_drawlinetoolbar(NXTKWINDOW hfwnd, FAR struct nxgl_vector_s *vector, \
                         nxgl_coord_t width, nxgl_mxpixel_t color[CONFIG_NX_NPLANES], \
                         uint8_t caps);

  Fill the specified line in the toolbar sub-window with
  the specified color. This is simply a wrapper that uses
  ``nxgl_splitline()`` to break the line into trapezoids and then calls
  ``nxtk_filltraptoolbar()`` to render the line.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param vector:
     Describes the line to be drawn.
  :param width:
     The width of the line
  :param color:
     The color to use to fill the line
  :param caps:
     Draw a circular cap on the ends of the line to support better line
     joins. One of:

     .. code-block:: c

      /* Line caps */

      #define NX_LINECAP_NONE  0x00, /* No line caps */
      #define NX_LINECAP_PT1   0x01  /* Line cap on pt1 on of the vector only */
      #define NX_LINECAP_PT2   0x02  /* Line cap on pt2 on of the vector only */
      #define NX_LINECAP_BOTH  0x03  /* Line cap on both ends of the vector only */

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_drawcircletoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_point_s *center, \
                           nxgl_coord_t radius, nxgl_coord_t width, \
                           nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);

  Draw a circular outline using the specified line
  thickness and color.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param center:
     A pointer to the point that is the center of the circle.
  :param radius:
     The radius of the circle in pixels.
  :param width:
     The width of the line
  :param color:
     The color to use to fill the line

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_fillcircletoolbar(NXWINDOW hfwnd, FAR const struct nxgl_point_s *center, \
                           nxgl_coord_t radius, nxgl_mxpixel_t color[CONFIG_NX_NPLANES]);

  Fill a circular region using the specified color.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param center:
     A pointer to the point that is the center of the circle.
  :param radius:
     The width of the line
  :param color:
     The color to use to fill the circle

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_movetoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, \
                     FAR const struct nxgl_point_s *offset);

  Move a rectangular region within the toolbar sub-window
  of a framed window.

  :param hfwnd:
     A handle identifying sub-window containing the toolbar within which
     the move is to be done. This handle must have previously been
     returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param rect:
     Describes the rectangular region relative to the toolbar sub-window
     to move.
  :param offset:
     The offset to move the region

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. c:function:: int nxtk_bitmaptoolbar(NXTKWINDOW hfwnd, \
                       FAR const struct nxgl_rect_s *dest, \
                       FAR const void *src[CONFIG_NX_NPLANES], \
                       FAR const struct nxgl_point_s *origin, \
                       unsigned int stride);

  Copy a rectangular region of a larger image into the
  rectangle in the specified toolbar sub-window.

  :param hfwnd:
     A handle previously returned by
     ```nxtk_openwindow()`` <#nxtkopenwindow>`__.
  :param dest:
     Describes the rectangular region on in the toolbar sub-window will
     receive the bit map.
  :param src:
     The start of the source image.
  :param origin:
     The origin of the upper, left-most corner of the full bitmap. Both
     dest and origin are in sub-window coordinates, however, the origin
     may lie outside of the sub-window display.
  :param stride:
     The width of the full source image in bytes.

  :return: ``OK`` on success; ``ERROR`` on failure with
    ``errno`` set appropriately

.. _nx-fonts-support-nxfonts-1: