Função de retorno de chamada LPOFNHOOKPROC (commdlg.h)

Artigo
08/22/2023

[A partir do Windows Vista, as caixas de diálogo abrir e salvar como comuns foram substituídas pela caixa de diálogo Item Comum. Recomendamos que você use a API de Caixa de Diálogo de Item Comum em vez dessas caixas de diálogo da Biblioteca de Caixas de Diálogo Comuns.]

Recebe mensagens de notificação enviadas da caixa de diálogo. A função também recebe mensagens para quaisquer controles adicionais que você definiu especificando um modelo de caixa de diálogo filho. O procedimento de gancho OFNHookProc é uma função de retorno de chamada definida pelo aplicativo ou definida pela biblioteca que é usada com as caixas de diálogo Abrir e Salvar como no estilo Explorer.

O tipo LPOFNHOOKPROC define um ponteiro para essa função de retorno de chamada. OFNHookProc é um espaço reservado para o nome da função definida pelo aplicativo.

Sintaxe

LPOFNHOOKPROC Lpofnhookproc;

UINT_PTR Lpofnhookproc(
  HWND unnamedParam1,
  UINT unnamedParam2,
  WPARAM unnamedParam3,
  LPARAM unnamedParam4
)
{...}

Parâmetros

unnamedParam1

Um identificador para a caixa de diálogo filho da caixa de diálogo Abrir ou Salvar como . Use a função GetParent para obter o identificador na caixa de diálogo Abrir ou Salvar como .

unnamedParam2

O identificador da mensagem que está sendo recebida.

unnamedParam3

Informações adicionais sobre a mensagem. O significado exato depende do valor do parâmetro unnamedParam2 .

unnamedParam4

Informações adicionais sobre a mensagem. O significado exato depende do valor do parâmetro unnamedParam2 . Se o parâmetro unnamedParam2 indicar a mensagem WM_INITDIALOG , unnamedParam4 será um ponteiro para uma estrutura OPENFILENAME que contém os valores especificados quando a caixa de diálogo foi criada.

Valor retornado

Se o procedimento de gancho retornar zero, o procedimento da caixa de diálogo padrão processará a mensagem.

Se o procedimento de gancho retornar um valor diferente de zero, o procedimento da caixa de diálogo padrão ignorará a mensagem.

Para as mensagens de notificação CDN_SHAREVIOLATION e CDN_FILEOK , o procedimento de gancho deve retornar um valor diferente de zero para indicar que ele usou a função SetWindowLong para definir um valor diferente de zero DWL_MSGRESULT .

Comentários

Se você não especificar o sinalizador OFN_EXPLORER ao criar uma caixa de diálogo Abrir ou Salvar como e quiser um procedimento de gancho, deverá usar um procedimento de gancho OFNHookProcOldStyle de estilo antigo. Nesse caso, a caixa de diálogo terá a interface do usuário de estilo antigo.

Ao usar as funções GetOpenFileName ou GetSaveFileName para criar uma caixa de diálogo Abrir ou Salvar como no estilo Explorer, você pode fornecer um procedimento de gancho OFNHookProc. Para habilitar o procedimento de gancho, use a estrutura OPENFILENAME que você passou para a função de criação da caixa de diálogo. Especifique o ponteiro para o procedimento de gancho no membro lpfnHook e especifique o sinalizador OFN_ENABLEHOOK no membro Flags .

Se você fornecer um procedimento de gancho para uma caixa de diálogo comum no estilo Explorer, o sistema criará uma caixa de diálogo que é um filho da caixa de diálogo padrão. O procedimento de gancho atua como o procedimento de caixa de diálogo para a caixa de diálogo filho. Essa caixa de diálogo filho é baseada no modelo especificado na estrutura OPENFILENAME ou é uma caixa de diálogo filho padrão se nenhum modelo for especificado. A caixa de diálogo filho é criada quando o procedimento de caixa de diálogo padrão está processando sua mensagem WM_INITDIALOG . Depois que a caixa de diálogo filho processa sua própria mensagem de WM_INITDIALOG , o procedimento de diálogo padrão move os controles padrão, se necessário, para abrir espaço para quaisquer controles adicionais da caixa de diálogo filho. Em seguida, o sistema envia a mensagem de notificação CDN_INITDONE para o procedimento de gancho.

O procedimento de gancho não recebe mensagens destinadas aos controles padrão da caixa de diálogo padrão. Você pode subclasse os controles padrão, mas isso é desencorajado porque pode tornar seu aplicativo incompatível com versões posteriores. No entanto, as caixas de diálogo comuns no estilo Explorer fornecem um conjunto de mensagens que o procedimento de gancho pode usar para monitorar e controlar a caixa de diálogo. Elas incluem um conjunto de mensagens de notificação enviadas da caixa de diálogo, bem como mensagens que você pode enviar para recuperar informações da caixa de diálogo. Para obter uma lista completa dessas mensagens, consulte Explorer-Style Hook Procedures.

Se o procedimento de gancho processar a mensagem WM_CTLCOLORDLG , ele deverá retornar um identificador de pincel válido para pintar a tela de fundo da caixa de diálogo. Em geral, se processar qualquer mensagem WM_CTLCOLOR* , ele deverá retornar um identificador de pincel válido para pintar a tela de fundo do controle especificado.

Não chame a função EndDialog do procedimento de gancho. Em vez disso, o procedimento de gancho pode chamar a função PostMessage para postar uma mensagem WM_COMMAND com o valor IDCANCEL no procedimento da caixa de diálogo. A postagem de IDCANCEL fecha a caixa de diálogo e faz com que a função da caixa de diálogo retorne FALSE. Se você precisar saber por que o procedimento de gancho fechou a caixa de diálogo, você deve fornecer seu próprio mecanismo de comunicação entre o procedimento de gancho e seu aplicativo.

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]
Plataforma de Destino	Windows
Cabeçalho	commdlg.h (inclua Windows.h)