| ====================== |
| 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: |
| |
