graphics/nxmu, include/nuttx/nx/nxmu.h, libs/libnx: Add new server->client callback to notify the window client of server events. Remove the old 'blocked' callback and just make it one case of an 'event' callback.

include/nuttx/nx/nx.h

@@ -96,6 +96,14 @@ typedef FAR void *NXWINDOW;
 
 /* NX server callbacks ******************************************************/
 
+/* Event callbacks */
+
+enum nx_event_e
+{
+  NXEVENT_BLOCKED = 0,   /* Window messages are blocked */
+  NXEVENT_SYCNCHED,      /* Synchronization handshake */
+};
+
 /* These define callbacks that must be provided to nx_openwindow.  These
  * callbacks will be invoked as part of the processing performed by
  * nx_eventhandler()
@@ -199,33 +207,51 @@ struct nx_callback_s
 #endif
 
   /**************************************************************************
-   * Name: blocked
+   * Name: event
    *
    * Description:
-   *   This callback is the response from nx_block (or 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 is used to communicate server events to the window
+   *   listener.
    *
-   *   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_BLOCKED - Window messages are blocked.
+   *
+   *     This callback is the response from nx_block (or 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_SYCNCHED - Synchronization handshake
+   *
+   *     This completes the handshake started by nx_synch().  nx_synch()
+   *     sends a syncrhonization 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, nx_synch() is sometimes necessary to assure that
+   *     the client and server are fully synchronized.
    *
    * Input Parameters:
-   *   hwnd - Window handle of the blocked window
-   *   arg1 - User provided argument (see nx_openwindow, nx_requestbkgd,
-   *          nxtk_openwindow, or nxtk_opentoolbar)
-   *   arg2 - User provided argument (see nx_block or nxtk_block)
+   *   hwnd  - Window handle of the blocked window
+   *   event - The server event
+   *   arg1  - User provided argument (see nx_openwindow, nx_requestbkgd,
+   *           nxtk_openwindow, or nxtk_opentoolbar)
+   *   arg2  - User provided argument (see nx_block or nxtk_block)
    *
    * Returned Value:
    *   None
    *
    **************************************************************************/
 
-  void (*blocked)(NXWINDOW hwnd, FAR void *arg1, FAR void *arg2);
+  void (*event)(NXWINDOW hwnd, enum nx_event_e event, FAR void *arg1,
+                FAR void *arg2);
 };
 
 /****************************************************************************

include/nuttx/nx/nxmu.h

@@ -130,7 +130,7 @@ enum nxmsg_e
   NX_CLIMSG_NEWPOSITION,      /* New window size/position */
   NX_CLIMSG_MOUSEIN,          /* New mouse positional data available for window */
   NX_CLIMSG_KBDIN,            /* New keypad input available for window */
-  NX_CLIMSG_BLOCKED,          /* The window is blocked */
+  NX_CLIMSG_EVENT,            /* Server->client event */
 
   /* Client-to-Server Messages **********************************************/
 
@@ -229,15 +229,14 @@ struct nxclimsg_kbdin_s
 };
 #endif
 
-/* This message confirms that that all queued window messages have been
- * flushed and that the all further window messages are blocked.
- */
+/* This message provides server event notifications to the client. */
 
-struct nxclimsg_blocked_s
+struct nxclimsg_event_s
 {
   uint32_t msgid;                /* NX_CLIMSG_BLOCKED */
   FAR struct nxbe_window_s *wnd; /* The window that is blocked */
   FAR void *arg;                 /* User argument */
+  enum nx_event_e event;         /* Server event */
 };
 
 /* Client-to-Server Message Structures **************************************/