Função SetWindowLongPtrA (winuser.h)

Artigo
07/21/2023

Altera um atributo da janela especificada. A função também define um valor no deslocamento especificado na memória de janela extra.

Nota Para escrever código compatível com versões de 32 bits e 64 bits do Windows, use SetWindowLongPtr. Ao compilar para Windows de 32 bits, SetWindowLongPtr é definido como uma chamada para a função SetWindowLong .

Sintaxe

LONG_PTR SetWindowLongPtrA(
  [in] HWND     hWnd,
  [in] int      nIndex,
  [in] LONG_PTR dwNewLong
);

Parâmetros

[in] hWnd

Digite: HWND

Um identificador para a janela e, indiretamente, a classe à qual a janela pertence. A função SetWindowLongPtr falhará se o processo que possui a janela especificada pelo parâmetro hWnd estiver em um privilégio de processo mais alto na hierarquia de UIPI do que o processo em que o thread de chamada reside.

Windows XP/2000: A função SetWindowLongPtr falhará se a janela especificada pelo parâmetro hWnd não pertencer ao mesmo processo que o thread de chamada.

[in] nIndex

Tipo: int

O deslocamento baseado em zero para o valor a ser definido. Os valores válidos estão no intervalo zero até o número de bytes de memória de janela extra, menos o tamanho de um LONG_PTR. Para definir qualquer outro valor, especifique um dos valores a seguir.

Valor	Significado
GWL_EXSTYLE -20	Define um novo estilo de janela estendida.
GWLP_HINSTANCE -6	Define um novo identificador de instância de aplicativo.
GWLP_ID -12	Define um novo identificador da janela filho. A janela não pode ser uma janela de nível superior.
GWL_STYLE -16	Define um novo estilo de janela.
GWLP_USERDATA -21	Define os dados do usuário associados à janela. Esses dados são destinados ao uso pelo aplicativo que criou a janela. Seu valor é inicialmente zero.
GWLP_WNDPROC -4	Define um novo endereço para o procedimento de janela.

Os valores a seguir também estão disponíveis quando o parâmetro hWnd identifica uma caixa de diálogo.

Valor	Significado
DWLP_DLGPROC DWLP_MSGRESULT + sizeof(LRESULT)	Define o novo ponteiro para o procedimento da caixa de diálogo.
DWLP_MSGRESULT 0	Define o valor retornado de uma mensagem processada no procedimento da caixa de diálogo.
DWLP_USER DWLP_DLGPROC + sizeof(DLGPROC)	Define novas informações extras que são privadas para o aplicativo, como identificadores ou ponteiros.

[in] dwNewLong

Tipo: LONG_PTR

O valor de substituição.

Valor retornado

Tipo: LONG_PTR

Se a função for bem-sucedida, o valor retornado será o valor anterior do deslocamento especificado.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Se o valor anterior for zero e a função for bem-sucedida, o valor retornado será zero, mas a função não limpará as últimas informações de erro. Para determinar o êxito ou a falha, desmarque as últimas informações de erro chamando SetLastError com 0 e, em seguida, chame SetWindowLongPtr. A falha de função será indicada por um valor retornado igual a zero e um resultado GetLastError diferente de zero.

Comentários

Determinados dados de janela são armazenados em cache, portanto, as alterações feitas usando SetWindowLongPtr não entrarão em vigor até que você chame a função SetWindowPos .

Se você usar SetWindowLongPtr com o índice GWLP_WNDPROC para substituir o procedimento de janela, o procedimento de janela deverá estar em conformidade com as diretrizes especificadas na descrição da função de retorno de chamada WindowProc .

Se você usar SetWindowLongPtr com o índice DWLP_MSGRESULT para definir o valor retornado de uma mensagem processada por um procedimento de caixa de diálogo, o procedimento da caixa de diálogo deverá retornar TRUE diretamente posteriormente. Caso contrário, se você chamar qualquer função que resulte no procedimento da caixa de diálogo recebendo uma mensagem de janela, a mensagem de janela aninhada poderá substituir o valor retornado definido usando DWLP_MSGRESULT.

Chamar SetWindowLongPtr com o índice GWLP_WNDPROC cria uma subclasse da classe de janela usada para criar a janela. Um aplicativo pode subclasse de uma classe do sistema, mas não deve subclasse uma classe de janela criada por outro processo. A função SetWindowLongPtr cria a subclasse de janela alterando o procedimento de janela associado a uma classe de janela específica, fazendo com que o sistema chame o novo procedimento de janela em vez do anterior. Um aplicativo deve passar todas as mensagens não processadas pelo novo procedimento de janela para o procedimento de janela anterior chamando CallWindowProc. Isso permite que o aplicativo crie uma cadeia de procedimentos de janela.

Reserve memória de janela extra especificando um valor diferente de zero no membro cbWndExtra da estrutura WNDCLASSEX usada com a função RegisterClassEx .

Não chame SetWindowLongPtr com o índice GWLP_HWNDPARENT para alterar o pai de uma janela filho. Em vez disso, use a função SetParent .

Se a janela tiver um estilo de classe de CS_CLASSDC ou CS_PARENTDC, não defina os estilos de janela estendidos WS_EX_COMPOSITED ou WS_EX_LAYERED.

Chamar SetWindowLongPtr para definir o estilo em uma barra de progresso redefinirá sua posição.

Observação

O cabeçalho winuser.h define SetWindowLongPtr 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 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	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-windowclass-l1-1-0 (introduzido no Windows 8)