CB Callback functions

Purpose

In a Callback Function, return information about a message.

Syntax

CtlID = CB.CTL

CtlMsg = CB.CTLMSG

WinHndl = CB.HNDL

Value = CB.LPARAM

Msg = CB.MSG

Value = CB.WPARAM

CodeMsg = CB.NMCODE

NmPtr = CB.NMHDR

NmStruc = CB.NMHDR$

NmHndl = CB.NMHWND

NmID = CB.NMID

Remarks

When an event occurs (like a user clicking on a button, a character typed into a text box, etc.) Windows sends a message to the Control Callback Function, or the Dialog Callback Function. The CB functions are used to easily retrieve information about the message. These CB functions can only be used within a callback function.

Callback functions in Windows have a standard set of four parameters. For this reason, PowerBASIC allows you to ignore them and save some typing in your source code. The implied parameters are:

FUNCTION DlgCallback(BYVAL hDlg AS DWORD _
  BYVAL wMsg AS LONG   _
  BYVAL wParam AS LONG _
  BYVAL lParam AS LONG)

Generic Callback Functions

CB.HNDL	This function returns the window handle of the parent dialog. This is the value specified by the hDlg parameter above.
CB.MSG	Each type of message sent to your callback function has a unique numeric value, such as %WM_COMMAND, %WM_NOTIFY, etc. CB.MSG will return the actual numeric message value of the message being processed. The definitions of the numeric values in other CB functions (CB.LPARAM, CB.WPARAM, CB.CTL, etc.) can only be ascertained once CB.MSG is identified. Therefore, callback functions usually test the value of CB.MSG first.
CB.WPARAM	When Windows sends a message to a callback function, the wParam value contains different values, depending on the nature of the particular message (CB.MSG). In other words, CB.WPARAM returns a message-dependent value.
CB.LPARAM	When Windows sends a message to a callback function, the lParam value contains different values, depending on the nature of the particular message (CB.MSG). In other words, CB.LPARAM returns a message-dependent value.

%WM_COMMAND Specific Callback Functions

CB.CTL

If CB.MSG = %WM_COMMAND, this function returns the ID number assigned to the control with the CONTROL ADD statement. For other values of CB.MSG, it returns message-dependent values. This value is sent as the low-order word of the wParam parameter. It's functionally equivalent to LO(WORD, wParam&) in a conventional function, or LO(WORD, CB.WPARAM) in a DDT Callback Function.

CB.CTLMSG

If CB.MSG = %WM_COMMAND, this function returns the specific control message describing the event which occurred. For example, CB.CTLMSG returns %BN_CLICKED when the user clicks a button. For other values of CB.MSG, it returns message-dependent values. This value is sent as the high-order word of the wParam parameter. It's functionally equivalent to HI(WORD, wParam&) in a conventional function, or HI(WORD, CB.WPARAM) in a DDT Callback Function.

%WM_NOTIFY Specific Callback Functions

CB.NMCODE

If CB.MSG = %WM_NOTIFY, this function returns the specific notification message describing the event which occurred. For example, CB.NMCODE returns %NM_SETFOCUS when the described control gains the focus. For other values of CB.MSG, the value returned is meaningless.

CB.NMHDR

If CB.MSG = %WM_NOTIFY, this function returns the address (a pointer ) to the NMHDR UDT for this notification message. NMHDR is defined as:

Type NMHDR
  hwndFrom as DWord ' Handle of the control sending the message
  idfrom    as DWord ' Identifier of the control sending the message
  code      as Long   ' Notification code
End Type

Some notification messages (%NM_CHAR, %NM_CLICK, etc.) require an extended version of the NM structure. However, all NM structures begin with an NMHDR UDT, so the pointer returned here is always accurate. For other values of CB.MSG, the pointer returned by CB.NMHDR is meaningless.

CB.NMHDR$

If CB.MSG = %WM_NOTIFY, this function returns the contents of the NMHDR UDT as a dynamic string. If the notification message is one which requires an extended version of the NM structure, the string returned contains all of the data for the extended UDT. However, in all cases, the first 12 bytes of the returned string will be the contents of NMHDR. You can use TYPE SET to assign the string data to an appropriate user-defined type. For other values of CB.MSG, the string returned by CB.NMHDR$ is meaningless.

The following notification messages use the extended NM structures as listed, so an appropriately longer string is returned:

Message	UDT
%NM_CLICK	NMMOUSE
%NM_RCLICK	NMMOUSE
%NM_NCHITTEST	NMMOUSE
%NM_KEYDOWN	NMKEY
%NM_SETCURSOR	NMMOUSE
%NM_CHAR	NMCHAR
%NM_TOOLTIPSCREATED	NMTOOLTIPSCREATED

Other special notify messages may use a different extended NM structure than those listed above. To ensure compatibility, you can include an optional numeric parameter to specify the size of the special UDT you are using:

TYPE SET NotifyUDT = CB.NMHDR$(sizeof(NotifyUDT))

CB.NMHWND

If CB.MSG = %WM_NOTIFY, this function returns the handle of the control which sent this message. For other values of CB.MSG, the value returned is meaningless.

CB.NMID

If CB.MSG = %WM_NOTIFY, this function returns the ID number assigned to this control. For other values of CB.MSG, the value returned is meaningless.

Restrictions

These functions are only valid inside a Callback Function. The CB Callback functions replace CBMSG, CBHNDL, CBLPARAM, CBWPARAM, CBCTL, and CBCTLMSG . Note these functions are no longer supported, so update your code to use the new syntax.