ACMFILTERCHOOSE
The ACMFILTERCHOOSE
structure contains information the ACM uses to initialize the system-defined
waveform-audio filter selection dialog box. After the user closes the dialog
box, the system returns information about the user s selection in this
structure.
typedef struct {
DWORD cbStruct;
DWORD fdwStyle;
HWND hwndOwner;
LPWAVEFILTER pwfltr;
DWORD cbwfltr;
LPCSTR pszTitle;
char
szFilterTag[ACMFILTERTAGDETAILS_FILTERTAG_CHARS];
char
szFilter[ACMFILTERDETAILS_FILTER_CHARS];
LPSTR pszName;
DWORD cchName;
DWORD fdwEnum;
LPWAVEFILTER
pwfltrEnum;
HINSTANCE hInstance;
LPCSTR
pszTemplateName;
LPARAM lCustData;
ACMFILTERCHOOSEHOOKPROC pfnHook;
} ACMFILTERCHOOSE;
Members
cbStruct
Size, in
bytes, of the ACMFILTERCHOOSE structure. This member must be initialized
before an application calls the acmFilterChoose function. The size specified
in this member must be large enough to contain the base ACMFILTERCHOOSE
structure.
fdwStyle
Optional
style flags for the acmFilterChoose function. This member must be
initialized to a valid combination of the following flags before an application
calls the acmFilterChoose function. The following values are defined:
ACMFILTERCHOOSE_STYLEF_CONTEXTHELP
Context-sensitive
help will be available in the dialog box. To use this feature, an application
must register the ACMHELPMSGCONTEXTMENU and ACMHELPMSGCONTEXTHELP constants,
using the RegisterWindowMessage function. When the user invokes help, the registered
message will be posted to the owning window. The message will contain the wParam
and lParam parameters from the original WM_CONTEXTMENU or WM_CONTEXTHELP
message.
ACMFILTERCHOOSE_STYLEF_ENABLEHOOK
Enables the
hook function specified in the pfnHook member. An application can use
hook functions for a variety of customizations, including answering the MM_ACM_FILTERCHOOSE message.
ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE
Causes the
ACM to create the dialog box template identified by the hInstance and pszTemplateName
members.
ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATEHANDLE
The hInstance
member identifies a data block that contains a preloaded dialog box template.
If this flag is specified, the ACM ignores the pszTemplateName member.
ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT
The buffer
pointed to by pwfltr contains a valid WAVEFILTER structure that the dialog
box will use as the initial selection.
ACMFILTERCHOOSE_STYLEF_SHOWHELP
A help button
will appear in the dialog box. To use a custom Help file, an application must
register the ACMHELPMSGSTRING value with the RegisterWindowMessage function. When the user
presses the help button, the registered message is posted to the owner.
hwndOwner
Handle of the
window that owns the dialog box. This member can be any valid window handle or
NULL if the dialog box has no owner. This member must be initialized before
calling the acmFilterChoose
function.
pwfltr
Address of a WAVEFILTER structure. If the
ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT flag is specified in the fdwStyle
member, this structure must be initialized to a valid filter. When the acmFilterChoose
function returns, this buffer contains the selected filter. If the user cancels
the dialog box, no changes will be made to this buffer.
cbwfltr
Size, in
bytes, of the buffer pointed to by the pwfltr member. The acmFilterChoose function returns
ACMERR_NOTPOSSIBLE if the buffer is too small to contain the filter
information; the ACM also copies the required size into this member. An application
can use the acmMetrics
and acmFilterTagDetails
functions to determine the largest size required for this buffer.
pszTitle
Address of a
string to be placed in the title bar of the dialog box. If this member is NULL,
the ACM uses the default title (that is, Filter Selection ).
szFilterTag
Buffer
containing a null-terminated string describing the filter tag of the filter
selection when the acmFilterChoose function returns. This string is equivalent to
the szFilterTag member of the ACMFILTERTAGDETAILS structure returned by acmFilterTagDetails. If the user cancels the
dialog box, this member will contain a null-terminated string.
szFilter
Buffer
containing a null-terminated string describing the filter attributes of the
filter selection when the acmFilterChoose function returns. This string
is equivalent to the szFilter member of the ACMFILTERDETAILS structure returned by acmFilterDetails. If the user cancels the
dialog box, this member will contain a null-terminated string.
pszName
Address of a
string for a user-defined filter name. If this is a non-null-terminated string,
the ACM attempts to match the name with a previously saved user-defined filter
name. If a match is found, the dialog box is initialized to that filter. If a
match is not found or this member is a null-terminated string, this member is
ignored for input. When the acmFilterChoose function returns, this buffer contains a null-terminated
string describing the user-defined filter. If the filter name is untitled (that
is, the user has not given a name for the filter), this member will be a
null-terminated string on return. If the user cancels the dialog box, no
changes will be made to this buffer.
If the
ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT flag is specified by the fdwStyle
member, the pszName member is ignored as an input member.
cchName
Size, in
characters, of the buffer identified by the pszName member. This buffer
should be at least 128 characters long. If pszName is NULL, this member
is ignored.
fdwEnum
Optional
flags for restricting the type of filters listed in the dialog box. These flags
are identical to the fdwEnum flags for the acmFilterEnum function. If pwfltrEnum
is NULL, this member should be zero.
ACM_FILTERENUMF_DWFILTERTAG
The dwFilterTag
member of the WAVEFILTER
structure pointed to by the pwfltrEnum member is valid. The enumerator
will only enumerate a filter that conforms to this attribute.
pwfltrEnum
Address of a WAVEFILTER
structure that will be used to restrict the filters listed in the dialog box.
The fdwEnum member defines which members of this structure should be
used for the enumeration restrictions. The cbStruct member of this WAVEFILTER
structure must be initialized to the size of the WAVEFILTER structure.
If no special restrictions are desired, this member can be NULL.
hInstance
Handle of a
data block that contains a dialog box template specified by the pszTemplateName
member. This member is used only if the fdwStyle member specifies the
ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE or ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATEHANDLE
flag; otherwise, this member should be NULL on input.
pszTemplateName
Address of a
null-terminated string that specifies the name of the resource file for the
dialog box template that is to be substituted for the dialog box template in
the ACM. An application can use the MAKEINTRESOURCE macro for numbered dialog
box resources. This member is used only if the fdwStyle member specifies
the ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE flag; otherwise, this member should
be NULL on input.
lCustData
Application-defined
data that the ACM passes to the hook function identified by the pfnHook
member. The system passes the data in the lParam parameter of the WM_INITDIALOG message.
pfnHook
Address of a
hook function that processes messages intended for the dialog box. An
application must specify the ACMFILTERCHOOSE_STYLEF_ENABLEHOOK flag in the fdwStyle
member to enable the hook; otherwise, this member should be NULL. The hook
function should return FALSE to pass a message to the standard dialog box
procedure or TRUE to discard the message.
See Also