Função SHMessageBoxCheckA (shlwapi.h)
[SHMessageBoxCheck está disponível para uso nos sistemas operacionais especificados na seção Requisitos. Ele pode estar alterado ou indisponível em versões subsequentes.]
Exibe uma caixa de mensagem que dá ao usuário a opção de suprimir outras ocorrências. Se o usuário já optou por suprimir a caixa de mensagem, a função não exibirá uma caixa de diálogo e, em vez disso, simplesmente retornará o valor padrão.
Sintaxe
int SHMessageBoxCheckA(
[in, optional] HWND hwnd,
[in] LPCSTR pszText,
[in] LPCSTR pszCaption,
UINT uType,
int iDefault,
[in] LPCSTR pszRegVal
);
Parâmetros
[in, optional] hwnd
Tipo: HWND
O identificador da janela para o proprietário da caixa de mensagem. Esse valor pode ser NULL.
[in] pszText
Tipo: LPCTSTR
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém a mensagem a ser exibida.
[in] pszCaption
Tipo: LPCTSTR
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o título da caixa de mensagem. Se esse parâmetro estiver definido como NULL, o título será definido como Erro!.
uType
Tipo: UINT
Os sinalizadores que especificam o conteúdo e o comportamento da caixa de mensagem. Essa função dá suporte apenas a um subconjunto dos sinalizadores com suporte MessageBox. Se você usar sinalizadores que não estão listados abaixo, o comportamento da função será indefinido.
Você deve especificar os botões a serem exibidos definindo um e apenas um dos sinalizadores a seguir.
MB_OKCANCEL
Exibir uma caixa de mensagem com botões OK
MB_YESNO
Exibir uma caixa de mensagem com botões Sim e Sem.
MB_OK
Exibir uma caixa de mensagem com um botão
Você pode exibir um ícone opcional definindo um e apenas um dos sinalizadores a seguir.
MB_ICONHAND
Exibir um ícone de sinal de interrupção.
MB_ICONQUESTION
Exibir um ícone de ponto de interrogação.
MB_ICONEXCLAMATION
Exibir um ícone de ponto de exclamação.
MB_ICONINFORMATION
Exibir um ícone com um "i" minúsculo em um círculo.
iDefault
Tipo: int
O valor que a função retorna quando o usuário optou por não ter a caixa de mensagem exibida novamente. Se o usuário não tiver optado por suprimir a caixa de mensagem, a caixa de mensagem será exibida e a função ignorará iDefault.
[in] pszRegVal
Tipo: LPCTSTR
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém um valor de cadeia de caracteres exclusivo a ser associado a essa mensagem. Para evitar colisões com valores usados pela Microsoft, essa cadeia de caracteres deve incluir um GUID. Essa cadeia de caracteres não deve exceder REGSTR_MAX_VALUE_LENGTH caracteres de comprimento, incluindo o caractere nulo de terminação.
Valor de retorno
Tipo: int
Se o usuário já tiver escolhido suprimir a caixa de mensagem, a função retornará imediatamente o valor atribuído a iDefault.
Se o usuário clicar no botão OK, Cancelar, Simou Sem, a função retornará IDOK, IDCANCEL, IDYES ou IDNO, respectivamente.
Se o usuário fechar a caixa de mensagem clicando no botão X na legenda, a função retornará IDCANCEL. Esse valor é retornado nesse caso mesmo que o sinalizador de MB_OKCANCEL não tenha sido definido.
Se ocorrer um erro, o valor retornado normalmente será –1. No entanto, em determinadas condições de memória baixa, a função pode retornar iDefault.
Observações
Aviso de Segurança: Não execute nenhuma ação perigosa se a função retornar –1 ou iDefault. Se ocorrer um erro ao tentar exibir a caixa de mensagem, SHMessageBoxCheck retornará –1 ou, em alguns casos, iDefault. Esses erros podem ser causados por memória ou recursos insuficientes. Se você receber um desses valores retornados, deverá estar ciente de que o usuário não viu necessariamente a caixa de diálogo e, consequentemente, não concordou positivamente com nenhuma ação.
Não confunda "Não mostrar esta caixa de diálogo" com "Lembre-se dessa resposta". SHMessageBoxCheck não fornece a funcionalidade "Lembre-se dessa resposta". Se o usuário optar por suprimir a caixa de mensagem novamente, a função não preservará qual botão ele clicou. Em vez disso, as invocações subsequentes de SHMessageBoxCheck simplesmente retornam o valor especificado por iDefault. Considere o exemplo a seguir.
int iResult = SHMessageBoxCheck(hwnd,
TEXT("Do you want to exit without saving?"),
TEXT("Warning"),
MB_YESNO,
IDNO,
TEXT("{d9108ba3-9a61-4398-bfbc-b02102c77e8a}");
Se o usuário selecionar no futuro, não me mostre essa caixa de diálogo e clique no botão Sim, SHMessageBoxCheck retornará IDYES. No entanto, na próxima vez que esse código for executado, SHMessageBoxCheck não retornará IDYES, mesmo que o usuário selecionado Sim originalmente. Em vez disso, retorna IDNO, pois esse é o valor especificado por iDefault.
O botão padrão exibido pela caixa de mensagem deve concordar com seu valor de iDefault
SHMessageBoxCheck registra as caixas de mensagem que o usuário optou por suprimir na seguinte chave do Registro:
HKEY_CURRENT_USER Software Microsoft Windows CurrentVersion Explorer DontShowMeThisDialogAgain
Nota
O cabeçalho shlwapi.h define SHMessageBoxCheck como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2003 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | shlwapi.h |
| de DLL |
Shlwapi.dll (versão 5.0 ou posterior) |