implement modality in ALFApplication

1 files changed, 43 insertions, 5 deletions

diff --git a/alf/alf.h b/alf/alf.h
index cc1d936..2399569 100644
--- a/alf/alf.h
+++ b/alf/alf.h
@@ -302,13 +302,21 @@ ALF_FillRect(HDC dc, const RECT *rc, ALFColor color);
 void
 ALF_DestroyWidget(HWND win, WORD id);
 
+// wrapper for MessageBox() that handles modality for multiple toplevels with ALFApplication
+int
+ALF_MessageBox(HWND hwnd, const TCHAR *text, const TCHAR *caption, UINT type);
+
 
 // application
 
-// an application is a container for multiple top-level windows
+// ALFApplication is a container for multiple top-level windows.
+//
+// Having an ALFApplication is not required, but it enables you to get modality
+// right in the face of multiple top-level windows.
+//
 // NOTE: ALFApplication is not thread-safe. It must be accessed only from the
 // thread that created it, and all toplevels associated with the application
-// must live on that same thread.
+// must live on that same thread. There must be at most one application per thread.
 
 typedef struct tagALFApplication ALFApplication;
 
@@ -335,12 +343,41 @@ ALF_Application_SetPreTranslateMessageHandler(ALFApplication *app, BOOL(*handler
 BOOL
 ALF_Application_PreTranslateMessage(ALFApplication *app, MSG *msg, HWND modalToplevel);
 
-// TODO: implement modal stuff
-/*void
+// Modality with multiple toplevels
+// --------------------------------
+//
+// How it works:
+// * A "modal disable" counter is managed for each ALF toplevel
+// * Calling ALF_Application_DisableWindowsForModal() will increase the counter
+//   for each toplevel of the application, except for the HWND skip
+// * Calling ALF_Application_ReenableWindowsForModal() will decrease the counter
+//   for each toplevel of the application, except for the HWND skip
+//
+// How to show a modal ALF toplevel:
+// (1) It is assumed that we're running on the thread that owns the modal toplevel
+// (2) Show the modal toplevel
+// (3) If the modal has an ALFApplication:
+//      (3.1) Call DisableWindowsForModal on that app with skip=modal
+// (4) Additionally, disable the owner with EnableWindow()
+//      The owner might be a non-ALF window or live on another thread, in which
+//      case it is not being disabled in step 3.1.
+// (5) Run the modal message loop
+// (6) Undo (4) via EnableWindow
+// (7) Undo (3.1) via EnableWindowsForModal with skip=modal
+// (8) Hide the modal window
+// --> see ALF_Toplevel_ShowModal() for an example of how to do this
+//
+// How to show a modal window that adheres to Win32 modality conventions:
+// (1) If the owner window lives on the same thread and has an ALFApplication:
+//      (1.1) Call DisableWindowsForModal on that app with skip=owner
+// (2) Run the modal window
+// (3) undo 1.1 via EnableWindowsForModal with skip=owner
+// --> see ALF_MessageBox() for an example of how to do this
+void
 ALF_Application_DisableWindowsForModal(ALFApplication *app, HWND skip);
 
 void
-ALF_Application_ReenableWindowsForModal(ALFApplication *app, HWND skip);*/
+ALF_Application_ReenableWindowsForModal(ALFApplication *app, HWND skip);
 
 // also destroys all toplevels associated with the application
 void
@@ -349,6 +386,7 @@ ALF_DestroyApplication(ALFApplication *app);
 
 // toplevel window
 
+// NOTE about app: If app==NULL, the owner's app will be copied if the owner lives on the same thread
 HWND
 ALF_CreateToplevelWindow(DWORD exstyle, DWORD style, HWND hwndOwner, ALFApplication *app, ALFToplevelVTable *vtbl, void *closure);