focus and default button handling: fixes and some documenting comments

1 files changed, 18 insertions, 1 deletions

diff --git a/alf/alf.h b/alf/alf.h
index 2e07736..e1ad26e 100644
--- a/alf/alf.h
+++ b/alf/alf.h
@@ -8,7 +8,7 @@ extern "C" {
 #endif
 
 typedef struct {
-    void (*create)(void * /*closure*/, HWND /*window*/);
+    BOOL (*initialize)(void * /*closure*/, HWND /*window*/); // return FALSE if you set the focus, TRUE if you want default initial focus
     void (*destroy)(void * /*closure*/, HWND /*window*/);
     BOOL (*close)(void * /*closure*/, HWND /*window*/);
     void (*postdestroy)(void * /*closure*/);
@@ -189,6 +189,23 @@ ALF_AddEdit(HWND win, WORD id, int x, int y, const TCHAR *text);
 HWND
 ALF_AddButton(HWND win, WORD id, int x, int y, const TCHAR *text);
 
+// NOTE about default buttons:
+//
+// - If no default button is specified, the default button will be the button
+//   with the id IDOK. A WM_COMMAND message on pressing the return key will be
+//   sent even if no widget with the default id can be found.
+// - In NT 3.51, the default button must be a direct child of the window. Otherwise
+//   the default button effect will not work.
+// - In Win32s on Win3.1, the default button should be a direct child of the window.
+//   Otherwise the default button effect will be buggy when setting the focus
+//   via WM_NEXTDLGCTL or ALF_SetFocus(), but it will work correctly when using
+//   the TAB key.
+// - Changing the default button will only fully take effect after a focus change.
+//   It might temporarily lead to artifacts such as having two or no default buttons.
+//
+// Recommendation: Set the default button during window initialization, and then
+// immediately set the focus via ALF_SetFocus(). If you want to support NT 3.51
+// or Win32s, ensure that the default button is a direct child of the toplevel window.
 void
 ALF_SetDefaultButton(HWND win, WORD id);