This is an automated email from the ASF dual-hosted git repository. btashton pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 04d31a17248417736a2d925b67eae4cd1e159679 Author: Matias N <[email protected]> AuthorDate: Fri Aug 14 15:25:50 2020 -0300 finished NX document migration --- doc/components/nxgraphics/nx.rst | 8 +- doc/components/nxgraphics/nxtk.rst | 1175 +++++++++++++++++------------------- 2 files changed, 551 insertions(+), 632 deletions(-) diff --git a/doc/components/nxgraphics/nx.rst b/doc/components/nxgraphics/nx.rst index c21ed18..49f33c7 100644 --- a/doc/components/nxgraphics/nx.rst +++ b/doc/components/nxgraphics/nx.rst @@ -402,10 +402,8 @@ NX Server Callbacks :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()``. + - ``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. @@ -510,7 +508,7 @@ NX Server Callbacks 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`_. + handle must not have been created by :c:func:`nx_requestbkgd`. :return: ``OK`` on success; ``ERROR`` on failure with ``errno`` set appropriately diff --git a/doc/components/nxgraphics/nxtk.rst b/doc/components/nxgraphics/nxtk.rst index 89642a4..52a80cc 100644 --- a/doc/components/nxgraphics/nxtk.rst +++ b/doc/components/nxgraphics/nxtk.rst @@ -58,674 +58,595 @@ these sub-windows to be managed more-or-less independently: :return: OK on success; ERROR on failure with errno set appropriately. -2.4.3 ``nxtk_synch()`` -~~~~~~~~~~~~~~~~~~~~~~ +.. c:function:: int nxtk_synch(NXWINDOW hwnd, FAR void *arg); -**Function Prototype:** + 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. -**Description:** This interface can be used to synchronize the window -client with the NX server. It really just implements an *echo*: A synch -message is sent from the window client to the server which then responds -immediately by sending the ``NXEVENT_SYNCHED`` back to the windows -client. + Due to the highly asynchronous nature of client-server communications, + ``nx_synch()`` is sometimes necessary to assure that the client and + server are fully synchronized in time. -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: - -When the window listener thread receives the ``NXEVENT_SYNCHED`` event, -it would set ``g_synched`` to ``true`` and post ``g_synch_sem``, waking -up the above loop. - -**Input Parameters:** - -``wnd`` - The window to be synched -``arg`` - An argument that will accompany the synch messages (This is ``arg2`` - in the event callback). - -**Returned Value:** OK on success; ERROR on failure with errno set -appropriately - -2.4.4 ``nxtk_openwindow()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Create a new, framed window. - -**Input Parameters:** - -``handle`` - The handle returned by ```nx_connect()`` <#nxconnectinstance>`__. -``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()``. - -``cb`` - Callbacks used to process window events -``arg`` - User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__) - -**Returned Value:** - -2.4.5 ``nxtk_closewindow()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Close the window opened by -```nxtk_openwindow()`` <#nxtkopenwindow>`__. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.6 ``nxtk_getposition()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** 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. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.7 ``nxtk_setposition()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** 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. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``pos`` - The new position of the client sub-window - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.8 ``nxtk_setsize()`` -~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** 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. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``size`` - The new size of the client sub-window. - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.9 ``nxtk_raise()`` -~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Bring the window containing the specified client -sub-window to the top of the display. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to - be raised. -```` - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.10 ``nxtk_lower()`` -~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Lower the window containing the specified client -sub-window to the bottom of the display. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to - be lowered. -```` - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.11 ``nxtk_modal()`` -~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** May be used to either (1) raise a window to the top of -the display and select modal behavior, or (2) disable modal behavior. - -**Input Parameters:** - -``hwnd`` - The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__ - specifying the window to be modified. -``modal`` - True: enter modal state; False: leave modal state - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.12 ``nxtk_setvisibility()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** 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. - -**Input Parameters:** - -``hwnd`` - The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__ - specifying the window to be modified. -``hide`` - True: Window will be hidden; false: Window will be visible - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.13 ``nxtk_ishidden()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** 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. - -**Input Parameters:** - -``hfwnd`` - The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__ - that identifies the window to be queried. - -**Returned Value:** *True*: the window is hidden, *false*: the window is -visible - -2.4.14 ``nxtk_fillwindow()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Fill the specified rectangle in the client window with -the specified color. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``rect`` - The location within the client window to be filled -``color`` - The color to use in the fill - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.15 ``nxtk_getwindow()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** 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. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``rect`` - The location within the client window to be retrieved. -``plane`` - Specifies the color plane to get from. -``dest`` - The location to copy the memory region -``deststride`` - The width, in bytes, of the dest memory - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.16 ``nxtk_filltrapwindow()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Fill the specified trapezoid in the client window with -the specified color - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``trap`` - The trapezoidal region to be filled. -``color`` - The color to use in the fill. - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.17 ``nxtk_drawlinewindow()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** 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. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``vector`` - Describes the line to be drawn. -``width`` - The width of the line -``color`` - The color to use to fill the line -``caps`` - Draw a circular cap on the ends of the line to support better line - joins. One of: - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.18 ``nxtk_drawcirclewindow()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Draw a circular outline using the specified line -thickness and color. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``center`` - A pointer to the point that is the center of the circle. -``radius`` - The radius of the circle in pixels. -``width`` - The width of the line -``color`` - The color to use to fill the line - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.19 ``nxtk_fillcirclewindow()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Fill a circular region using the specified color. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``center`` - A pointer to the point that is the center of the circle. -``radius`` - The width of the line -``color`` - The color to use to fill the circle - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.20 ``nxtk_movewindow()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Move a rectangular region within the client sub-window -of a framed window. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the client - sub-window within which the move is to be done. -``rect`` - Describes the rectangular region relative to the client sub-window to - move. -``offset`` - The offset to move the region - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.21 ``nxtk_bitmapwindow()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 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). -**Function Prototype:** + :return: OK on success; ERROR on failure with errno set + appropriately -**Description:** Copy a rectangular region of a larger image into the -rectangle in the specified client sub-window. +.. c:function:: NXTKWINDOW nxtk_openwindow(NXHANDLE handle, uint8_t flags, \ + FAR const struct nx_callback_s *cb, \ + FAR void *arg); -**Input Parameters:** + Create a new, framed window. -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the client - sub-window that will receive the bitmap. -``dest`` - Describes the rectangular region on in the client sub-window will - receive the bit map. -``src`` - The start of the source image(s). This is an array source images of - size ``CONFIG_NX_NPLANES`` (probably 1). -``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. -``stride`` - The width of the full source image in pixels. + :param handle: + The handle returned by ```nx_connect()`` <#nxconnectinstance>`__. + :param flags: + Optional flags. These include: -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately + - ``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()``. -2.4.22 ``nxtk_opentoolbar()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + :param cb: + Callbacks used to process window events + :param arg: + User provided argument (see ```nx_openwindow()`` <#nxopenwindow>`__) -**Function Prototype:** + :return: Success: A non-NULL handle used with subsequent NXTK window accesses + Failure: NULL is returned and errno is set appropriately. -**Description:** Create a tool bar at the top of the specified framed -window. +.. c:function:: int nxtk_closewindow(NXTKWINDOW hfwnd); -**Input Parameters:** + Close the window opened by + ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``height`` - The requested height of the toolbar in pixels. -``cb`` - Callbacks used to process toolbar events. -``arg`` - User provided value that will be returned with toolbar callbacks. + :param hfwnd: + A handle previously returned by + ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately + :return: ``OK`` on success; ``ERROR`` on failure with + ``errno`` set appropriately -2.4.23 ``nxtk_closetoolbar()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. c:function:: int nxtk_getposition(NXTKWINDOW hfwnd); -**Function Prototype:** + 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. -**Description:** Remove the tool bar at the top of the specified framed -window. + :param hfwnd: + A handle previously returned by + ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -```` - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately + :return: ``OK`` on success; ``ERROR`` on failure with + ``errno`` set appropriately -2.4.24 ``nxtk_filltoolbar()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. c:function:: int nxtk_setposition(NXTKWINDOW hfwnd, FAR struct nxgl_point_s *pos); -**Function Prototype:** + 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. -**Description:** Fill the specified rectangle in the toolbar sub-window -with the specified color. + :param hfwnd: + A handle previously returned by + ```nxtk_openwindow()`` <#nxtkopenwindow>`__. + :param pos: + The new position of the client sub-window -**Input Parameters:** + :return: ``OK`` on success; ``ERROR`` on failure with + ``errno`` set appropriately -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``rect`` - The location within the toolbar window to be filled. -``color`` - The color to use in the fill. - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.25 ``nxtk_gettoolbar()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. c:function:: int nxtk_setsize(NXTKWINDOW hfwnd, FAR struct nxgl_size_s *size); -**Function Prototype:** + 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. -**Description:** 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 size: + The new size of the client sub-window. -**Input Parameters:** + :return: ``OK`` on success; ``ERROR`` on failure with + ``errno`` set appropriately -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``rect`` - The location within the toolbar window to be retrieved. -``plane`` - TSpecifies the color plane to get from. -``dest`` - TThe location to copy the memory region. -``deststride`` - The width, in bytes, of the dest memory. +.. c:function:: int nxtk_raise(NXTKWINDOW hfwnd); -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately + Bring the window containing the specified client + sub-window to the top of the display. -2.4.26 ``nxtk_filltraptoolbar()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + :param hfwnd: + A handle previously returned by + ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to + be raised. -**Function Prototype:** + :return: ``OK`` on success; ``ERROR`` on failure with + ``errno`` set appropriately -**Description:** Fill the specified trapezoid in the toolbar sub-window -with the specified color. +.. c:function:: int nxtk_lower(NXTKWINDOW hfwnd); -**Input Parameters:** + Lower the window containing the specified client + sub-window to the bottom of the display. -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``trap`` - The trapezoidal region to be filled -``color`` - The color to use in the fill + :param hfwnd: + A handle previously returned by + ```nxtk_openwindow()`` <#nxtkopenwindow>`__ specifying the window to + be lowered. -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately + :return: ``OK`` on success; ``ERROR`` on failure with + ``errno`` set appropriately -2.4.27 ``nxtk_drawlinetoolbar()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. c:function:: int nxtk_modal(NXWINDOW hwnd, bool modal); -**Function Prototype:** + May be used to either (1) raise a window to the top of + the display and select modal behavior, or (2) disable modal behavior. -**Description:** 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 hwnd: + The handle returned by ```nxtk_openwindow()`` <#nxtkopenwindow>`__ + specifying the window to be modified. + :param modal: + True: enter modal state; False: leave modal state -**Input Parameters:** + :return: ``OK`` on success; ``ERROR`` on failure with + ``errno`` set appropriately -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``vector`` - Describes the line to be drawn. -``width`` - The width of the line -``color`` - The color to use to fill the line -``caps`` - Draw a circular cap on the ends of the line to support better line - joins. One of: - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.28 ``nxtk_drawcircletoolbar()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Draw a circular outline using the specified line -thickness and color. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``center`` - A pointer to the point that is the center of the circle. -``radius`` - The radius of the circle in pixels. -``width`` - The width of the line -``color`` - The color to use to fill the line - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.29 ``nxtk_fillcircletoolbar()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Fill a circular region using the specified color. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``center`` - A pointer to the point that is the center of the circle. -``radius`` - The width of the line -``color`` - The color to use to fill the circle - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately +.. c:function:: int nxtk_setvisibility(NXWINDOW hwnd, bool hide); -2.4.30 ``nxtk_movetoolbar()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Move a rectangular region within the toolbar sub-window -of a framed window. - -**Input Parameters:** - -``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>`__. -``rect`` - Describes the rectangular region relative to the toolbar sub-window - to move. -``offset`` - The offset to move the region - -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately - -2.4.31 ``nxtk_bitmaptoolbar()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Function Prototype:** - -**Description:** Copy a rectangular region of a larger image into the -rectangle in the specified toolbar sub-window. - -**Input Parameters:** - -``hfwnd`` - A handle previously returned by - ```nxtk_openwindow()`` <#nxtkopenwindow>`__. -``dest`` - Describes the rectangular region on in the toolbar sub-window will - receive the bit map. -``src`` - The start of the source image. -``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. -``stride`` - The width of the full source image in bytes. + 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. -**Returned Value:** ``OK`` on success; ``ERROR`` on failure with -``errno`` set appropriately + :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: + TSpecifies the color plane to get from. + :param dest: + TThe 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:
