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 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 nxtk_openwindow(); Separate toolbar sub-window callbacks are reigistered when the toolbar is added using 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.

typedef FAR void *NXTKWINDOW: This is the handle that can be used to access the window data region.

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.

Parameters:

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

Returns:

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

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:

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.

Parameters:

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

Returns:

OK on success; ERROR on failure with errno set appropriately

NXTKWINDOW nxtk_openwindow(NXHANDLE handle, uint8_t flags, FAR const struct nx_callback_s *cb, FAR void *arg);

Create a new, framed window.

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>`__)

Returns:

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

int nxtk_closewindow(NXTKWINDOW hfwnd);

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

Parameters:

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

Parameters:

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

Parameters:

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

Parameters:

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

Returns:

OK on success; ERROR on failure with errno set appropriately

int nxtk_raise(NXTKWINDOW hfwnd);

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

Parameters:

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

Returns:

OK on success; ERROR on failure with errno set appropriately

int nxtk_lower(NXTKWINDOW hfwnd);

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

Parameters:

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

Parameters:

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

Parameters:

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

Returns:

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

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.

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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

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.

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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:

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

Parameters:

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.

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

Parameters:

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.

Returns:

OK on success; ERROR on failure with errno set appropriately

int nxtk_closetoolbar(NXTKWINDOW hfwnd);

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

Parameters:

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

Parameters:

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.

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

Parameters:

hfwnd – A handle previously returned by `nxtk_openwindow() <#nxtkopenwindow>`__.
rect – The location within the toolbar 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.

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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:

/* 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 */

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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

Returns:

OK on success; ERROR on failure with errno set appropriately

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.

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.

Returns:

OK on success; ERROR on failure with errno set appropriately

NX Tool Kit (NXTK)

NX Tool Kit (`NXTK`)