Função SetWindowLongA (winuser.h)

Artigo
03/15/2023

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

Nota Essa função foi substituída pela função SetWindowLongPtr . Para escrever código compatível com versões de 32 bits e 64 bits do Windows, use a função SetWindowLongPtr .

Sintaxe

LONG SetWindowLongA(
  [in] HWND hWnd,
  [in] int  nIndex,
  [in] LONG dwNewLong
);

Parâmetros

[in] hWnd

Digite: HWND

Um identificador para a janela e, indiretamente, a classe à qual a janela pertence.

[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 inteiro. Para definir qualquer outro valor, especifique um dos valores a seguir.

Valor	Significado
GWL_EXSTYLE -20	Define um novo estilo de janela estendida.
GWL_HINSTANCE -6	Define um novo identificador de instância de aplicativo.
GWL_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.
GWL_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.
GWL_WNDPROC -4	Define um novo endereço para o procedimento de janela. Você não poderá alterar esse atributo se a janela não pertencer ao mesmo processo que o thread de chamada.

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

Valor	Significado
DWL_DLGPROC DWLP_MSGRESULT + sizeof(LRESULT)	Define o novo endereço do procedimento da caixa de diálogo.
DWL_MSGRESULT 0	Define o valor retornado de uma mensagem processada no procedimento da caixa de diálogo.
DWL_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

O valor de substituição.

Retornar valor

Tipo: LONG

Se a função for bem-sucedida, o valor retornado será o valor anterior do inteiro de 32 bits especificado.

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

Se o valor anterior do inteiro de 32 bits especificado 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. Isso dificulta a determinação de êxito ou falha. Para lidar com isso, você deve limpar as últimas informações de erro chamando SetLastError com 0 antes de chamar SetWindowLong. Em seguida, 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 SetWindowLong não entrarão em vigor até que você chame a função SetWindowPos . Especificamente, se você alterar qualquer um dos estilos de quadro, deverá chamar SetWindowPos com o sinalizador SWP_FRAMECHANGED para que o cache seja atualizado corretamente.

Se você usar SetWindowLong com o índice GWL_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 SetWindowLong com o índice DWL_MSGRESULT para definir o valor retornado de uma mensagem processada por um procedimento de caixa de diálogo, deverá retornar TRUE diretamente posteriormente. Caso contrário, se você chamar qualquer função que resulte em seu procedimento de caixa de diálogo recebendo uma mensagem de janela, a mensagem de janela aninhada poderá substituir o valor retornado definido usando DWL_MSGRESULT.

Chamar SetWindowLong com o índice GWL_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 SetWindowLong 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 .

Você não deve chamar SetWindowLong com o índice GWL_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_OWNDC, não defina os estilos de janela estendidos WS_EX_COMPOSITED ou WS_EX_LAYERED.

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

Exemplos

Para obter um exemplo, consulte Subclasse de uma janela.

Observação

O cabeçalho winuser.h define SetWindowLong 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

Requisito	Valor
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 em Windows 8)