== NX == Overview ======== NX provides a tiny windowing system in the spirit of X, but greatly scaled down and appropriate for most resource-limited embedded environments. The current NX implementation supports the general following, high-level features: * **Virtual Vertical Graphics Space** Windows that reside in a virtual, vertical space so that it makes sense to talk about one window being on top of another and obscuring the window below it. * **Client/Server Model** A standard client server/model was adopted. NX may be considered a server and other logic that presents the windows are NX clients. * **Multi-User Support** NX includes front-end logic to an NX server daemon that can serve multiple NX client threads. The NX sever thread/daemon serializes graphics operations from multiple clients. * **Minimal Graphics Toolset** The actual implementation of the graphics operations is performed by common, back-end logic. This back-end supports only a primitive set of graphic and rendering operations. * **Device Interface** NX supports any graphics device either of two device interfaces: #. Any device with random access video memory using the NuttX framebuffer driver interface (see include/nuttx/video/fb.h). #. Any LCD-like device than can accept raster line runs through a parallel or serial interface (see include/nuttx/lcd/lcd.h). By default, NX is configured to use the frame buffer driver unless CONFIG_NX_LCDDRIVER is defined =y in your NuttX configuration file. * **Transparent to NX Client** The window client on "sees" the sub-window that is operates in and does not need to be concerned with the virtual, vertical space (other that to respond to redraw requests from NX when needed). * **Framed Windows and Toolbars** NX also adds the capability to support windows with frames and toolbars on top of the basic windowing support. These are windows such as those shown in the screenshot above. These framed windows sub-divide one one window into three relatively independent subwindows: A frame, the contained window and an (optional) toolbar window. * **Mouse Support** NX provides support for a mouse or other X/Y pointing devices. APIs are provided to allow external devices to give X/Y position information and mouse button presses to NX. NX will then provide the mouse input to the relevant window clients via callbacks. Client windows only receive the mouse input callback if the mouse is positioned over a visible portion of the client window; X/Y position is provided to the client in the relative coordinate system of the client window. * **Keyboard input** NX also supports keyboard/keypad devices. APIs are provided to allow external devices to give keypad information to NX. NX will then provide the mouse input to the top window on the display (the window that has the focus) via a callback function. Pre-Processor Definitions ========================= The default server message queue name used by the :c:macro:`nx_run` macro: .. code-block:: c #define NX_DEFAULT_SERVER_MQNAME "/dev/nxs" Mouse button bits: .. code-block:: c #define NX_MOUSE_NOBUTTONS 0x00 #define NX_MOUSE_LEFTBUTTON 0x01 #define NX_MOUSE_CENTERBUTTON 0x02 #define NX_MOUSE_RIGHTBUTTON 0x04 NX Types ======== The interface to the NX server is managed using a opaque handle: .. c:type:: FAR void *NXHANDLE The interface to a specific window is managed using an opaque handle: .. c:type:: FAR void *NXWINDOW These define callbacks that must be provided to :c:func:`nx_openwindow`. These callbacks will be invoked as part of the processing performed by :c:func:`nx_eventhandler`. .. c:struct:: nx_callback_s .. code-block:: c struct nx_callback_s { void (*redraw)(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, bool more, FAR void *arg); void (*position)(NXWINDOW hwnd, FAR const struct nxgl_size_s *size, FAR const struct nxgl_point_s *pos, FAR const struct nxgl_rect_s *bounds, FAR void *arg); #ifdef CONFIG_NX_XYINPUT void (*mousein)(NXWINDOW hwnd, FAR const struct nxgl_point_s *pos, uint8_t buttons, FAR void *arg); #endif #ifdef CONFIG_NX_KBD void (*kbdin)(NXWINDOW hwnd, uint8_t nch, FAR const uint8_t *ch, FAR void *arg); #endif }; Starting the NX Server ====================== The *NX Server* is a kernel daemon that receives and serializes graphic commands. Before you can use the NX graphics system, you must first start this daemon. There are two ways that this can be done: #. The NX server may be started in your board startup logic by simply calling the function ``nxmu_start()``. The board startup logic usually resides the the ``boards/arch/chip/board/src`` directory. The board startup logic can run automatically during the early system if ``CONFIG_BOARD_LATE_INITIALIZE`` is defined in the configuration. Or, the board startup logic can execute under control of the application by calling :c:func:`boardctl` as: .. code-block:: c boardctl(BOARDIOC_INIT, arg) The board initialization logic will run in either case and the simple call to ``nxmu_start()`` will start the NX server. #. The NX server may also be started later by the application via :c:func:`boardctl` as: .. code-block:: c boardctl(BOARDIOC_NX_START, arg) .. c:function:: int nxmu_start(int display, int plane); Provides a wrapper function to simplify and standardize the starting of the NX server. :param display: The display number to be served by this new NXMU instance. :param plane: The plane number to use to get information about the display geometry and color format. :return: Zero (``OK``) is returned on success. This indicates that the NX server has been successfully started, is running, and waiting to accept connections from NX clients. A negated ``errno`` value is returned on failure. The ``errno`` value indicates the nature of the failure. NX Server Callbacks =================== .. c:function:: void redraw(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, bool more, FAR void *arg); NX requests that the client re-draw the portion of the window within with rectangle. :param hwnd: The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :param rect: The rectangle that needs to be re-drawn (in window relative coordinates) :param more: true: More re-draw requests will follow :param arg: User provided argument (see :c:func:`nx_openwindow`) .. c:function:: void position(NXWINDOW hwnd, FAR const struct nxgl_size_s *size, \ FAR const struct nxgl_point_s *pos, \ FAR const struct nxgl_rect_s *bounds, \ FAR void *arg); The size or position of the window has changed (or the window was just created with zero size. :param hwnd: The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :param size: The size of the window :param pos: The position of the upper left hand corner of the window on the overall display :param bounds: The bounding rectangle that the describes the entire display :param arg: User provided argument (see :c:func:`nx_openwindow`) .. c:function:: void mousein(NXWINDOW hwnd, FAR const struct nxgl_point_s *pos, \ uint8_t buttons, FAR void *arg); New mouse data is available for the window :param hwnd: The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :param pos: The (x,y) position of the mouse :param buttons: See ``NX_MOUSE_*`` definitions :param arg: User provided argument (see :c:func:`nx_openwindow`) .. c:var:: void (*kbdin)(NXWINDOW hwnd, uint8_t nch, FAR const uint8_t *ch, FAR void *arg); New keyboard/keypad data is available for the window. :param hwnd: The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :param nch: The number of characters that are available in ch[] :param ch: The array of characters :param arg: User provided argument (see :c:func:`nx_openwindow`) .. c:var:: void (*event)(NXWINDOW hwnd, enum nx_event_e event, FAR void *arg1, FAR void *arg2); This callback is used to communicate server events to the window listener. - ``NXEVENT_BLOCKED``: Window messages are blocked. This callback is the response from :c:func:`nx_block`, :c:func:`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 :c:func:`nx_synch`, or :c:func:`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. :param hwnd: TWindow handle of window receiving the event :param event: The server event :param arg1: User provided argument (see :c:func:`nx_openwindow`, :c:func:`nx_requestbkgd`, or :c:func:`nxtk_opentoolbar`) :param arg2: TUser provided argument (see :c:func:`nx_block`, :c:func:`nxtk_block`, :c:func:`nx_synch`, or :c:func:`nxtk_synch`) .. c:macro:: nx_run(fb) .. code-block:: c #define nx_run(fb) nx_runinstance(NX_DEFAULT_SERVER_MQNAME, dev) .. c:function:: int nx_runinstance(FAR const char *mqname, FAR struct fb_vtable_s *fb) This is the server entry point. It does not return; the calling thread is dedicated to supporting NX server. NOTE that multiple instances of the NX server may run at the same time, with different callback and message queue names. ``nx_run()`` is simply a macro that can be used when only one server instance is required. In that case, a default server name is used. :param mqname: The name for the server incoming message queue :param dev: Framebuffer or LCD driver "object" to be used :return: This function usually does not return. If it does return, it will return ``ERROR`` and ``errno`` will be set appropriately. .. c:macro:: nx_connect(cb) .. code-block:: c #define nx_connect(cb) nx_connectinstance(NX_DEFAULT_SERVER_MQNAME) .. c:function:: NXHANDLE nx_connectinstance(FAR const char *svrmqname); Open a connection from a client to the NX server. One one client connection is normally needed per thread as each connection can host multiple windows. NOTES: - This function returns before the connection is fully instantiated. it is necessary to wait for the connection event before using the returned handle. - Multiple instances of the NX server may run at the same time, each with different message queue names. - ``nx_connect()`` is simply a macro that can be used when only one server instance is required. In that case, a default server name is used. :param svrmqname: The name for the server incoming message queue :return: Success: A non-NULL handle used with subsequent NX accesses Failure: NULL is returned and errno is set appropriately. .. c:function:: void nx_disconnect(NXHANDLE handle) Disconnect a client from the NX server and/or free resources reserved by :c:func:`nx_connect`/c:func:`nx_connectinstance`. :param handle: The handle returned by :c:func:`nx_connectinstance`. .. c:function:: int nx_eventhandler(NXHANDLE handle); The client code must call this function periodically to process incoming messages from the server. If ``CONFIG_NX_BLOCKING`` is defined, then this function not return until a server message is received. When ``CONFIG_NX_BLOCKING`` 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. ```nx_eventnotify()`` <#nxeventnotify>`__ may be called to get a signal event whenever a new incoming server event is available. :param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__. :return: - ``OK``: No errors occurred. If ``CONFIG_NX_BLOCKING`` is defined, then one or more server messages were processed. - ``ERROR``: An error occurred and ``errno`` has been set appropriately. Of particular interest, it will return ``errno == EHOSTDOWN`` when the server is disconnected. After that event, the handle can no longer be used. .. c:function:: int nx_eventnotify(NXHANDLE handle, int signo); Rather than calling :c:func:`nx_eventhandler` periodically, the client may register to receive a signal when a server event is available. The client can then call :c:func:nx_eventhandler` only when incoming events are available. The underlying implementation used ``mq_notifiy()`` and, as a result, the client must observe the rules for using ``mq_notifiy()``: - Only one event is signalled. Upon receipt of the signal, if the client wishes further notifications, it must call ``nx_eventnotify()`` again. - The signal will only be issued when the message queue transitions from empty to not empty. :param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__. :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_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 ``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. :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 nx_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 = 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. :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:: NXWINDOW nx_openwindow(NXHANDLE handle, uint8_t flags, \ FAR const struct nx_callback_s *cb, \ FAR void *arg); Create a new 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 ``nx_setvisibility()``. :param cb: Callbacks used to process window events :param arg: User provided value that will be returned with NX callbacks. :return: Success: A non-NULL handle used with subsequent NX accesses Failure: NULL is returned and errno is set appropriately. .. c:function:: int nx_closewindow(NXWINDOW hwnd) Destroy a window created by :c:func:`nx_openwindow` window. :param hwnd: The handle returned by ```nx_openwindow()`` <#nxopenwindow>`__ that identifies the window to be destroyed. This handle must not have been one returned by ```nx_requestbkgd()`` <#nxrequestbkgd>`__. :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_requestbkgd(NXHANDLE handle, \ FAR const struct nx_callback_s *cb, \ FAR void *arg); 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: - If you want to implement a windowless solution. The single screen can be used to create a truly simple graphic environment. - 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. This API only requests the handle of the background window. That handle will be returned asynchronously in a subsequent position and redraw callbacks. Cautions: - The following should never be called using the background window. They are guaranteed to cause severe crashes: :c:func:`nx_setposition`, :c:func:`nx_setsize`, :c:func:`nx_raise`, or :c:func:`nx_lower`, :c:func:`nx_modal`, :c:func:`nx_setvisibility`. - Neither :c:func:`nx_requestbkgd` nor :c:func:`nx_releasebkgd` should be called more than once. Multiple instances of the background window are not supported. :param handle: The handle returned by ```nx_connect()`` <#nxconnectinstance>`__. :param cb: Callbacks to use for processing background window events :param arg: User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__) :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_releasebkgd(NXWINDOW hwnd) Release the background window previously acquired using :c:func:`nx_requestbkgd` and return control of the background to NX. :param handle: The handle returned indirectly by :c:func:`nx_requestbkgd`. This handle must not have been one created by :c:func:`nx_openwindow`. :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_getposition(NXWINDOW hwnd) Request the position and size information for the selected window. The values will be return asynchronously through the client callback function pointer. :param hwnd: The handle returned by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd`. :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_setposition(NXWINDOW hwnd, FAR struct nxgl_point_s *pos) Set the position and size for the selected window. :param hwnd: The handle returned by :c:func:`nx_openwindow`. This handle must not have been created by :c:func:`nx_requestbkgd`. :param pos: The new position of the window :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_setsize(NXWINDOW hwnd, FAR struct nxgl_size_s *size) Set the size of the selected window. :param hwnd: The handle returned by :c:func:`nx_openwindow`. This handle must not have been created by :c:func:`nx_requestbkgd`. :param size: The new size of the window (in pixels). :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_raise(NXWINDOW hwnd) Bring the specified window to the top of the display. :param hwnd: The handle returned by :c:func:`nx_openwindow`. This handle must not have been created by :c:func:`nx_requestbkgd`. :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_lower(NXWINDOW hwnd); Lower the specified window to the bottom of the display. :param hwnd: The handle returned by :c:func:`nx_openwindow`. This handle must not have been created by :c:func:`nx_requestbkgd`. :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_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 :c:func:`nx_openwindow`. This handle must not have been created by :c:func:`nx_requestbkgd`. :param modal: True: enter modal state; False: leave modal state :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_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 :c:func:`nx_openwindow`. This handle must not have been created by :c:func:`nx_requestbkgd`. :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 nx_ishidden(NXWINDOW hwnd); 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 :c:func:`nx_setvisibily` before that new setting is reported by :c:func:`nx_ishidden`. ``nx_synch()`` may be used if temporal synchronization is required. :param hwnd: The handle returned by :c:func:`nx_openwindow` that identifies the window to be queried. :return: *True*: the window is hidden, *false*: the window is visible .. c:function:: int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, \ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); Fill the specified rectangle in the window with the specified color. :param hwnd: The handle returned by ```nx_openwindow()`` <#nxopenwindow>`__ or ```nx_requestbkgd()`` <#nxrequestbkgd>`__ :param rect: The location 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 nx_getrectangle(NXWINDOW hwnd, 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 hwnd: The handle returned by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :param rect: The location to be copied :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 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]); Fill the specified trapezoidal region in the window with the specified color. :param hwnd: The handle returned by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :param clip: Clipping rectangle relative to window (may be null) :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 nx_drawline(NXWINDOW hwnd, 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 :c:func:`nxgl_splitline` to break the line into trapezoids and then calls :c:func:`nx_filltrapezoid` to render the line. :param hwnd: The handle returned by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :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:: /* 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 nx_drawcircle(NXWINDOW hwnd, 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 hwnd: The handle returned by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :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 nx_fillcircle(NXWINDOW hwnd, 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 hwnd: The handle returned by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :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 nx_setbgcolor(NXHANDLE handle, \ nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); Set the color of the background. :param handle: The handle created by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` :param color: The color to use in the background :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_move(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, \ FAR const struct nxgl_point_s *offset); Move a rectangular region within the window. :param hwnd: The handle returned by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` that specifies the window within which the move is to be done :param rect: Describes the (source) rectangular region to move :param offset: The offset to move the region :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: 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); Copy a rectangular region of a larger image into the rectangle in the specified window. :param hwnd: The handle returned by :c:func:`nx_openwindow` or :c:func:`nx_requestbkgd` that specifies the window that will receive the bitmap image. :param dest: Describes the rectangular on the display that will receive the bit map. :param src: The start of the source image. 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 window coordinates, however, the origin may lie outside of the display. :param stride: The width of the full source image in bytes. :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_kbdchin(NXHANDLE handle, uint8_t ch); .. c:function:: int nx_kbdin(NXHANDLE handle, uint8_t nch, FAR const uint8_t *ch); 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. :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. c:function:: int nx_mousein(NXHANDLE handle, nxgl_coord_t x, nxgl_coord_t y, uint8_t buttons) 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. :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately .. _nx-tool-kit-nxtk-1: