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á tiver optado 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

Digite: 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 for definido como NULL, o título será definido como Error!.

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 do 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 os botões OK e Cancelar .

MB_YESNO

Exibir uma caixa de mensagem com botões Sim e Não .

MB_OK

Exibir uma caixa de mensagem com um botão OK .

Você pode exibir um ícone opcional definindo um e apenas um dos sinalizadores a seguir.

MB_ICONHAND

Exibir um ícone de sinal de parada.

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 retornado

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, Sim ou Não , a função retornará IDOK, IDCANCEL, IDYES ou IDNO, respectivamente.

Se o usuário fechar a caixa de mensagem clicando no botão X no legenda, a função retornará IDCANCEL. Esse valor é retornado nesse caso, mesmo que o sinalizador MB_OKCANCEL não tenha sido definido.

Se ocorrer um erro, o valor retornado normalmente será –1. No entanto, sob determinadas condições de baixa memória, a função pode retornar iDefault.

Comentários

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 desta resposta". SHMessageBoxCheck não fornece a funcionalidade "Lembre-se desta 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 tenha selecionado Sim originalmente. Em vez disso, ele retorna IDNO, porque esse é o valor especificado por iDefault.

O botão padrão exibido pela caixa de mensagem deve concordar com o valor iDefault . A falta de suporte para o sinalizador MB_DEFBUTTON2 significa que iDefault deve ser definido como IDOK se você tiver especificado o sinalizador MB_OK ou MB_OKCANCEL. O valor iDefault deve ser definido como IDYES se você tiver definido o sinalizador MB_YESNO.

SHMessageBoxCheck registra as caixas de mensagem que o usuário optou por suprimir sob a seguinte chave do Registro:

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  DontShowMeThisDialogAgain

Observação

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 de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shlwapi.h
DLL	Shlwapi.dll (versão 5.0 ou posterior)