Help button on "DISPLAY COLOR", "DISPLAY OPENFILE" and "DISPLAY SAVEFILE"

[Stuart McLachlan]

Openfile,Savefile and Color common dialogs have flags to display a Help button.
(%OFN_SHOWHELP and %CC_SHOWHELP)

How to implement a Common Dialog Help button is not specifically documented in PB Help (it's not unique to PB and is well documented by Microsoft) and some people are not aware of how to do this.

For anything to happen when this button is clicked, you need to set up your application to respond to it in accordance with Microsoft's documentation for these dialogs.

When clicked, the button sends a specific "Registered Message" to the parent of the common dialog. This message should be trapped and responded to in the parent's CALLBACK function.

The registered message sent by the button must be for the string "commdlg_help". This string is an API defined equate: HELPMSGSTRING

To implement the Help you need to do three things:
1. In your application get a message ID using RegisterWindowMessageA(HELPMSGSTRING) or RegisterWindowMessageA("commdlg_help")
3. Ensure that your main dialog handle is designated as the parent in the call to "DISPLAY ..."
2. Trap that message in your main dialog's callback and define the action to take when it is received (e.g. display a messagebox, open a Help file, display a popup dialog or whatever you choose)

A simple demonstration using DISPLAY COLOR

#COMPILE EXE
#DIM ALL
%UNICODE = 1
#INCLUDE ONCE "WIN32API.INC"
ENUM ctrls SINGULAR
    IDC_btnColours = 1001
END ENUM
TYPE CustCols
  c(1 TO 16) AS DWORD
END TYPE
GLOBAL cColours AS CustCols

FUNCTION PBMAIN() AS LONG
   LOCAL lRslt AS LONG
   LOCAL hDlg  AS DWORD
    DIALOG NEW 0, "Colour Help", , , 200, 100, %WS_SYSMENU, TO hDlg
    CONTROL ADD BUTTON , hDlg,%IDC_btnColours,"Colours",60,50,80,20
    DIALOG SHOW MODAL hDlg, CALL MainDlgCB TO lRslt
END FUNCTION

CALLBACK FUNCTION MainDlgCB()
    LOCAL lngColour AS LONG
    STATIC lngColHelp AS LONG
     SELECT CASE AS LONG CB.MSG
        CASE %WM_INITDIALOG
             lngColHelp = RegisterWindowMessageA(HELPMSGSTRING) 'Get the Message ID for the registered message
        CASE %WM_NCACTIVATE

        CASE lngColHelp ' Respond to message sent by the DISPLAY COLOR dialog when Help is clicked
            ? "You clicked Help in the Colour Picker!"
        CASE %WM_COMMAND
            SELECT CASE AS LONG CB.CTL
                CASE %IDC_btnColours
                    IF CB.CTLMSG = %BN_CLICKED OR CB.CTLMSG = 1 THEN
                          'make sure to specify this dialog handle so that the Help message is received by this dialog callback
                          DISPLAY COLOR CB.HNDL,0,0,RGB(120,120,250),cColours,%CC_SHOWHELP  TO lngColour
                    END IF
            END SELECT
    END SELECT
END FUNCTION

N.B. Since the same message is sent by all three common dialogs, if you use more than one type in your application, you will need to keep track of which dialog you are responding to.
One way would be:

CALLBACK FUNCTION MainDlgCB()
    LOCAL lngColour AS LONG
    STATIC lngDlgHelp AS LONG
    STATIC flgWhichCommDLg AS LONG  ' 1 = Openfile, 2 = SaveFile, 4 = Color
     SELECT CASE AS LONG CB.MSG

            CASE %WM_INITDIALOG
             lngDlgHelp = RegisterWindowMessageA(HELPMSGSTRING) 'Get the Message ID for the registered message

        CASE lngDlgHelp ' Respond to message sent by the DISPLAY COLOR dialog when Help is clicked
            SELECT CASE flgWhichCommDLg
                CASE 1: ? "You clicked Help in the Openfile dialog!"
                CASE 2: ? "You clicked Help in the Savefile dialog!"
                CASE 4: ? "You clicked Help in the Colour Picker!"
            END SELECT
        CASE %WM_COMMAND
            SELECT CASE AS LONG CB.CTL
                CASE %IDC_btnColours
                    IF CB.CTLMSG = %BN_CLICKED OR CB.CTLMSG = 1 THEN
                          'make sure to specify this dialog handle so that the Help message is received by this dialog callback
                          flgWhichCommDLg = 4 ' We are calling the color picker
                          DISPLAY COLOR CB.HNDL,0,0,RGB(120,120,250),cColours,%CC_SHOWHELP  TO lngColou
                    END IF
               '...
               '...
               '...
            END SELECT
    END SELECT
END FUNCTION