Estrutura ACMFILTERCHOOSE (msacm.h)

Artigo
03/15/2023

A estrutura ACMFILTERCHOOSE contém informações que o ACM usa para inicializar a caixa de diálogo de seleção de filtro waveform-audio definida pelo sistema. Depois que o usuário fecha a caixa de diálogo, o sistema retorna informações sobre a seleção do usuário nessa estrutura.

Sintaxe

typedef struct tACMFILTERCHOOSE {
  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, *PACMFILTERCHOOSE, *LPACMFILTERCHOOSE;

Membros

cbStruct

Tamanho, em bytes, da estrutura ACMFILTERCHOOSE . Esse membro deve ser inicializado antes que um aplicativo chame a função acmFilterChoose . O tamanho especificado neste membro deve ser grande o suficiente para conter a estrutura ACMFILTERCHOOSE base.

fdwStyle

Sinalizadores de estilo opcionais para a função acmFilterChoose . Esse membro deve ser inicializado para uma combinação válida dos sinalizadores a seguir antes que um aplicativo chame a função acmFilterChoose . Os seguintes valores são definidos:

Nome	Descrição
ACMFILTERCHOOSE_STYLEF_CONTEXTHELP	A ajuda contextual estará disponível na caixa de diálogo. Para usar esse recurso, um aplicativo deve registrar as constantes ACMHELPMSGCONTEXTMENU e ACMHELPMSGCONTEXTHELP, usando a função RegisterWindowMessage . Quando o usuário invocar ajuda, a mensagem registrada será postada na janela proprietária. A mensagem conterá os parâmetros wParam e lParam da mensagem de WM_CONTEXTMENU ou WM_CONTEXTHELP original.
ACMFILTERCHOOSE_STYLEF_ENABLEHOOK	Habilita a função de gancho especificada no membro pfnHook . Um aplicativo pode usar funções de gancho para uma variedade de personalizações, incluindo responder à mensagem de MM_ACM_FILTERCHOOSE .
ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE	Faz com que o ACM crie o modelo da caixa de diálogo identificado pelos membros hInstance e pszTemplateName .
ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATEHANDLE	O membro hInstance identifica um bloco de dados que contém um modelo de caixa de diálogo pré-carregado. Se esse sinalizador for especificado, o ACM ignorará o membro pszTemplateName .
ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT	O buffer apontado por pwfltr contém uma estrutura WAVEFILTER válida que a caixa de diálogo usará como a seleção inicial.
ACMFILTERCHOOSE_STYLEF_SHOWHELP	Um botão de ajuda será exibido na caixa de diálogo. Para usar um arquivo de Ajuda personalizado, um aplicativo deve registrar o valor ACMHELPMSGSTRING com a função RegisterWindowMessage . Quando o usuário pressiona o botão de ajuda, a mensagem registrada é postada no proprietário.

hwndOwner

Identificador da janela à qual a caixa de diálogo pertence. Esse membro poderá ser qualquer identificador de janela válido ou NULL se a caixa de diálogo não tiver proprietário. Esse membro deve ser inicializado antes de chamar a função acmFilterChoose .

pwfltr

Ponteiro para uma estrutura WAVEFILTER . Se o sinalizador ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT for especificado no membro fdwStyle , essa estrutura deverá ser inicializada para um filtro válido. Quando a função acmFilterChoose retorna, esse buffer contém o filtro selecionado. Se o usuário cancelar a caixa de diálogo, nenhuma alteração será feita nesse buffer.

cbwfltr

Tamanho, em bytes, do buffer apontado pelo membro pwfltr . A função acmFilterChoose retornará ACMERR_NOTPOSSIBLE se o buffer for muito pequeno para conter as informações de filtro; o ACM também copia o tamanho necessário para esse membro. Um aplicativo pode usar as funções acmMetrics e acmFilterTagDetails para determinar o maior tamanho necessário para esse buffer.

pszTitle

Ponteiro para uma cadeia de caracteres a ser colocada na barra de título da caixa de diálogo. Se esse membro for NULL, o ACM usará o título padrão (ou seja, "Seleção de Filtro").

szFilterTag[ACMFILTERTAGDETAILS_FILTERTAG_CHARS]

Buffer que contém uma cadeia de caracteres terminada em nulo que descreve a marca de filtro da seleção de filtro quando a estrutura ACMFILTERTAGDETAILS retornada por acmFilterTagDetails. Se o usuário cancelar a caixa de diálogo, esse membro conterá uma cadeia de caracteres terminada em nulo.

szFilter[ACMFILTERDETAILS_FILTER_CHARS]

Buffer que contém uma cadeia de caracteres terminada em nulo que descreve os atributos de filtro da seleção de filtro quando a estrutura ACMFILTERDETAILS retornada por acmFilterDetails. Se o usuário cancelar a caixa de diálogo, esse membro conterá uma cadeia de caracteres terminada em nulo.

pszName

Ponteiro para uma cadeia de caracteres para um nome de filtro definido pelo usuário. Se essa for uma cadeia de caracteres não terminada em nulo, o ACM tentará corresponder o nome com um nome de filtro definido pelo usuário salvo anteriormente. Se uma correspondência for encontrada, a caixa de diálogo será inicializada para esse filtro. Se uma correspondência não for encontrada ou esse membro for uma cadeia de caracteres terminada em nulo, esse membro será ignorado para entrada. Quando a função acmFilterChoose retorna, esse buffer contém uma cadeia de caracteres terminada em nulo que descreve o filtro definido pelo usuário. Se o nome do filtro não for definido (ou seja, o usuário não deu um nome para o filtro), esse membro será uma cadeia de caracteres terminada em nulo no retorno. Se o usuário cancelar a caixa de diálogo, nenhuma alteração será feita nesse buffer.

Se o sinalizador ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT for especificado pelo membro fdwStyle , o membro pszName será ignorado como um membro de entrada.

cchName

Tamanho, em caracteres, do buffer identificado pelo membro pszName . Esse buffer deve ter pelo menos 128 caracteres. Se pszName for NULL, esse membro será ignorado.

fdwEnum

Sinalizadores opcionais para restringir o tipo de filtros listados na caixa de diálogo. Esses sinalizadores são idênticos aos sinalizadores fdwEnum para a função acmFilterEnum . Se pwfltrEnum for NULL, esse membro deverá ser zero.

Nome	Descrição
ACM_FILTERENUMF_DWFILTERTAG	O membro dwFilterTag da estrutura WAVEFILTER apontada pelo membro pwfltrEnum é válido. O enumerador só enumerará um filtro que esteja em conformidade com esse atributo.

pwfltrEnum

Ponteiro para uma estrutura WAVEFILTER que será usada para restringir os filtros listados na caixa de diálogo. O membro fdwEnum define quais membros dessa estrutura devem ser usados para as restrições de enumeração. O membro cbStruct dessa estrutura WAVEFILTER deve ser inicializado para o tamanho da estrutura WAVEFILTER . Se nenhuma restrição especial for desejada, esse membro poderá ser NULL.

hInstance

Manipule para um bloco de dados que contém um modelo de caixa de diálogo especificado pelo membro pszTemplateName . Esse membro será usado somente se o membro fdwStyle especificar o sinalizador ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE ou ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATEHANDLE; caso contrário, esse membro deve ser NULL na entrada.

pszTemplateName

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do arquivo de recurso para o modelo de caixa de diálogo que deve ser substituído pelo modelo de caixa de diálogo no ACM. Um aplicativo pode usar a macro MAKEINTRESOURCE para recursos numerados da caixa de diálogo. Esse membro será usado somente se o membro fdwStyle especificar o sinalizador ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE; caso contrário, esse membro deve ser NULL na entrada.

lCustData

Dados definidos pelo aplicativo que o ACM passa para a função de gancho identificada pelo membro pfnHook . O sistema passa os dados no parâmetro lParam da mensagem WM_INITDIALOG .

pfnHook

Ponteiro para uma função de retorno de chamada que processa mensagens destinadas à caixa de diálogo. Um aplicativo deve especificar o sinalizador ACMFILTERCHOOSE_STYLEF_ENABLEHOOK no membro fdwStyle para habilitar o gancho; caso contrário, esse membro deve ser NULL. A função hook deve retornar FALSE para passar uma mensagem para o procedimento da caixa de diálogo padrão ou TRUE para descartar a mensagem. O tipo de função de retorno de chamada é acmFilterChooseHookProc.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	msacm.h