Funzione SetWindowLongPtrW (winuser.h)

Articolo
11/20/2024

Modifica un attributo della finestra specificata. La funzione imposta anche un valore in corrispondenza dell'offset specificato nella memoria aggiuntiva della finestra.

Nota Per scrivere codice compatibile con entrambe le versioni a 32 bit e a 64 bit di Windows, usare SetWindowLongPtr. Durante la compilazione per Windows a 32 bit, SetWindowLongPtr viene definita come chiamata alla funzione SetWindowLong.

Sintassi

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

Parametri

[in] hWnd

Tipo: HWND

Handle per la finestra e, indirettamente, la classe a cui appartiene la finestra. La funzione setWindowLongPtr ha esito negativo se il processo proprietario della finestra specificata dal parametro hWnd si trova a un privilegio di processo superiore nella gerarchia UIPI rispetto al processo in cui risiede il thread chiamante.

Windows XP/2000: La funzione SetWindowLongPtr ha esito negativo se la finestra specificata dal parametro hWnd non appartiene allo stesso processo del thread chiamante.

[in] nIndex

Tipo: int

Offset in base zero sul valore da impostare. I valori validi sono compresi nell'intervallo zero fino al numero di byte di memoria finestra aggiuntiva, meno le dimensioni di un LONG_PTR. Per impostare qualsiasi altro valore, specificare uno dei valori seguenti.

Valore	Significato
GWL_EXSTYLE -20	Imposta un nuovo stile finestra estesa.
GWLP_HINSTANCE -6	Imposta un nuovo handle di istanza dell'applicazione.
GWLP_ID -12	Imposta un nuovo identificatore della finestra figlio. La finestra non può essere una finestra di primo livello.
GWL_STYLE -16	Imposta un nuovo stile di finestra .
GWLP_USERDATA -21	Imposta i dati utente associati alla finestra. Questi dati sono destinati all'uso da parte dell'applicazione che ha creato la finestra. Il valore è inizialmente zero.
GWLP_WNDPROC -4	Imposta un nuovo indirizzo per la routine della finestra.

I valori seguenti sono disponibili anche quando il parametro hWnd identifica una finestra di dialogo.

Valore	Significato
DWLP_DLGPROC DWLP_MSGRESULT + sizeof(LRESULT)	Imposta il nuovo puntatore alla routine della finestra di dialogo.
DWLP_MSGRESULT 0	Imposta il valore restituito di un messaggio elaborato nella routine della finestra di dialogo.
DWLP_USER DWLP_DLGPROC + sizeof(DLGPROC)	Imposta nuove informazioni aggiuntive private sull'applicazione, ad esempio handle o puntatori.

[in] dwNewLong

Tipo: LONG_PTR

Valore di sostituzione.

Valore restituito

Tipo: LONG_PTR

Se la funzione ha esito positivo, il valore restituito è il valore precedente dell'offset specificato.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Se il valore precedente è zero e la funzione ha esito positivo, il valore restituito è zero, ma la funzione non cancella le ultime informazioni sull'errore. Per determinare l'esito positivo o negativo, cancellare le ultime informazioni sull'errore chiamando SetLastError con 0, quindi chiamare SetWindowLongPtr. L'errore della funzione verrà indicato da un valore restituito pari a zero e da un GetLastError risultato diverso da zero.

Osservazioni

Alcuni dati della finestra vengono memorizzati nella cache, pertanto le modifiche apportate tramite SetWindowLongPtr non avranno effetto finché non si chiama la funzione SetWindowPos .

Se si utilizza SetWindowLongPtr con l'indice GWLP_WNDPROC per sostituire la routine della finestra, la routine della finestra deve essere conforme alle linee guida specificate nella descrizione della WindowProc funzione di callback.

Se si utilizza SetWindowLongPtr con l'indice DWLP_MSGRESULT per impostare il valore restituito per un messaggio elaborato da una routine di finestra di dialogo, la routine della finestra di dialogo deve restituire TRUE immediatamente dopo. In caso contrario, se si chiama una funzione che restituisce la routine della finestra di dialogo che riceve un messaggio di finestra, il messaggio della finestra nidificata potrebbe sovrascrivere il valore restituito impostato usando DWLP_MSGRESULT.

La chiamata SetWindowLongPtr con l'indice GWLP_WNDPROC crea una sottoclasse della classe finestra usata per creare la finestra. Un'applicazione può sottoclasse una classe di sistema, ma non deve sottoclasse una classe finestra creata da un altro processo. La funzione SetWindowLongPtr crea la sottoclasse della finestra modificando la routine finestra associata a una determinata classe di finestra, causando al sistema di chiamare la nuova routine della finestra anziché quella precedente. Un'applicazione deve passare tutti i messaggi non elaborati dalla nuova routine finestra alla routine finestra precedente chiamando CallWindowProc. Ciò consente all'applicazione di creare una catena di routine finestra.

Riservare memoria aggiuntiva della finestra specificando un valore diverso da zero nella membro cbWndExtra della struttura WNDCLASSEX utilizzata con la funzione RegisterClassEx.

Non chiamare SetWindowLongPtr con l'indice GWLP_HWNDPARENT per modificare l'elemento padre di una finestra figlio. Usare invece la funzione SetParent.

Se la finestra ha uno stile di classe di CS_CLASSDC o CS_PARENTDC, non impostare gli stili della finestra estesa WS_EX_COMPOSITED o WS_EX_LAYERED.

Chiamando SetWindowLongPtr per impostare lo stile su una barra di avanzamento, la posizione verrà reimpostata.

Nota

L'intestazione winuser.h definisce SetWindowLongPtr come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winuser.h (include Windows.h)
libreria	User32.lib
dll	User32.dll
set di API	ext-ms-win-ntuser-windowclass-l1-1-0 (introdotto in Windows 8)