Informazioni sulle finestre delle proprietà

Una finestra delle proprietà consente all'utente di visualizzare e modificare le proprietà di un elemento. Ad esempio, un'applicazione foglio di calcolo può utilizzare una finestra delle proprietà per consentire all'utente di impostare le proprietà del tipo di carattere e del bordo di una cella o di visualizzare e impostare le proprietà di un dispositivo, ad esempio un'unità disco, una stampante o un mouse.

In questa sezione vengono illustrati gli argomenti seguenti.

• Nozioni di base sulla finestra delle proprietà
• Finestre di dialogo Finestra di dialogo finestra delle proprietà
• Pagine
• Creazione della finestra delle proprietà
• Aggiunta e rimozione di pagine
• Etichette del titolo e della pagina della finestra delle proprietà
• Attivazione pagina
• Pulsante ?
  • Rimozione del pulsante Della Guida della barra della didascalia
• Pulsanti OK, Annulla e Applica
• Procedure guidate

Nozioni di base sulla finestra delle proprietà

Per implementare le finestre delle proprietà nell'applicazione, includere il file di intestazione Prsht.h nel progetto. Prsht.h contiene tutti gli identificatori usati con le finestre delle proprietà.

Una finestra delle proprietà contiene una o più finestre figlio sovrapposte denominate pagine, ognuna delle quali contiene finestre di controllo per impostare un gruppo di proprietà correlate. Ad esempio, una pagina può contenere i controlli per impostare le proprietà del carattere di un elemento, inclusi lo stile del tipo, le dimensioni del punto, il colore e così via. Ogni pagina ha una scheda che l'utente può selezionare per portare la pagina in primo piano della finestra delle proprietà. Ad esempio, l'applicazione pannello di controllo Data e ora visualizza la finestra delle proprietà seguente.

Una finestra delle proprietà standard con più pagine a schede consente all'utente l'accesso casuale a tutte le proprietà. Se è più appropriato impostare le proprietà in sequenza, è possibile usare una procedura guidata.

Finestre di dialogo Finestra di dialogo finestra delle proprietà

Una finestra delle proprietà e le pagine che contiene sono effettivamente finestre di dialogo. La finestra delle proprietà è una finestra di dialogo definita dal sistema che gestisce le pagine e fornisce un contenitore comune. Una finestra di dialogo della finestra di dialogo delle proprietà può essere modale o non modale. Include un frame, una barra del titolo e quattro pulsanti: OK, Annulla, Applica e (facoltativamente) Guida. Le procedure della finestra di dialogo per le pagine ricevono codici di notifica sotto forma di WM_NOTIFY messaggi quando l'utente fa clic sui pulsanti.

Nota

Non tutte le informazioni contenute in questa sezione si applicano alle procedure guidate, con un aspetto e un comportamento leggermente diversi. Ad esempio, le procedure guidate hanno un set diverso di pulsanti e nessuna scheda. Per altre informazioni, vedere Creazione di procedure guidate.

Ogni pagina di una finestra delle proprietà è una finestra di dialogo senza modalità definita dall'applicazione che gestisce le finestre di controllo utilizzate per visualizzare e modificare le proprietà di un elemento. Specificare il modello di finestra di dialogo utilizzato per creare ogni pagina, nonché la routine della finestra di dialogo che gestisce i controlli e imposta le proprietà dell'elemento corrispondente.

Una finestra delle proprietà invia i codici di notifica alla routine della finestra di dialogo per una pagina quando la pagina ottiene o perde l'attivazione e quando l'utente fa clic sul pulsante OK, Annulla, Applica o Guida. Le notifiche vengono inviate sotto forma di messaggi WM_NOTIFY. Il parametro lParam è l'indirizzo di una struttura NMHDR che include l'handle di finestra di dialogo della finestra di dialogo della finestra di dialogo.

Alcuni codici di notifica richiedono che una pagina restituisca TRUE o FAL edizione Standard in risposta al messaggio di WM_NOTIFY. A tale scopo, la pagina deve usare la funzione SetWindowLong per impostare il valore DWL_MSGRESULT per la finestra di dialogo della pagina su TRUE o FAL edizione Standard.

Pagine

Una finestra delle proprietà deve contenere almeno una pagina, ma non può contenere più del valore di MAXPROPPAGES come definito nei file di intestazione di Windows. Ogni pagina ha un indice in base zero assegnato dalla finestra delle proprietà in base all'ordine in cui la pagina viene aggiunta alla finestra delle proprietà. Gli indici vengono utilizzati nei messaggi inviati alla finestra delle proprietà.

Una pagina delle proprietà può contenere una finestra di dialogo annidata. In caso affermativo, è necessario includere lo stile WS_EX_CONTROLPARENT per la finestra di dialogo di primo livello e chiamare la funzione IsDialogMessage con l'handle alla finestra di dialogo padre. In questo modo si garantisce che l'utente possa usare mnemonic e i tasti di spostamento della finestra di dialogo per spostare lo stato attivo sui controlli nella finestra di dialogo nidificata.

Ogni pagina ha un'icona e un'etichetta corrispondenti. La finestra delle proprietà crea una scheda per ogni pagina e visualizza l'icona e l'etichetta nella scheda. È previsto che tutte le pagine della finestra delle proprietà usino un tipo di carattere nonbold. Per assicurarsi che il tipo di carattere non sia in grassetto, specificare lo stile DS_3DLOOK nel modello della finestra di dialogo.

La procedura della finestra di dialogo per una pagina non deve chiamare la funzione EndDialog. In questo modo verrà eliminata l'intera finestra delle proprietà, non solo la pagina.

La dimensione minima per una pagina della finestra delle proprietà è di 212 unità di dialogo orizzontalmente e 114 unità di dialogo verticalmente. Se una finestra di dialogo di pagina è inferiore a questa, la pagina verrà ingrandita fino a quando non soddisfa le dimensioni minime. Il file di intestazione Prsht.h contiene tre set di dimensioni consigliate per le pagine delle finestre delle proprietà, come illustrato nella tabella seguente.

Dimensione	Descrizione
PROP_SM_CXDLG	Larghezza, in unità di dialogo, di una piccola pagina della finestra delle proprietà.
PROP_SM_CYDLG	Altezza, in unità di dialogo, di una piccola pagina della finestra delle proprietà.
PROP_MED_CXDLG	Larghezza, in unità di dialogo, di una pagina della finestra delle proprietà di medie dimensioni.
PROP_MED_CYDLG	Altezza, in unità di dialogo, di una pagina della finestra delle proprietà di medie dimensioni.
PROP_LG_CXDLG	Larghezza, in unità di dialogo, di una pagina della finestra delle proprietà di grandi dimensioni.
PROP_LG_CYDLG	Altezza, in unità di dialogo, di una pagina della finestra delle proprietà di grandi dimensioni.

L'uso di queste dimensioni consigliate consente di garantire la coerenza visiva tra l'applicazione e altre applicazioni Microsoft Windows.

Nell'editor di risorse di Microsoft Visual Studio è possibile creare una pagina delle dimensioni appropriate nella finestra di dialogo Aggiungi risorsa . Espandere il nodo Finestra di dialogo e selezionare IDD_PROPPAGE_LARGE, IDD_PROPPAGE_MEDIUM o IDD_PROPPAGE_SMALL.

La finestra delle proprietà viene ridimensionata automaticamente in modo da contenere la pagina più grande.

Creazione della finestra delle proprietà

Prima di creare una finestra delle proprietà, è necessario definire una o più pagine. Ciò comporta la compilazione di una struttura PROPSH edizione Enterprise TPAGE con informazioni sulla pagina, ovvero l'icona, l'etichetta, il modello di finestra di dialogo, la routine della finestra di dialogo e così via, e quindi specificando l'indirizzo della struttura in una chiamata alla funzione CreatePropertySheetPage. La funzione restituisce un handle al tipo HPROPSH edizione Enterprise TPAGE che identifica in modo univoco la pagina.

Per creare una finestra delle proprietà, specificare l'indirizzo di una struttura PROPSH edizione Enterprise THEADER in una chiamata alla funzione PropertySheet. La struttura definisce l'icona e il titolo per la finestra delle proprietà e include anche l'indirizzo di una matrice di handle HPROPSH edizione Enterprise TPAGE ottenuti utilizzando CreatePropertySheetPage. Quando PropertySheet crea la finestra delle proprietà, include le pagine identificate nella matrice. Le pagine vengono visualizzate nella finestra delle proprietà nello stesso ordine in cui sono contenute nella matrice.

Un altro modo per assegnare pagine a una finestra delle proprietà consiste nel specificare una matrice di strutture PROPSH edizione Enterprise TPAGE anziché una matrice di handle HPROPSH edizione Enterprise TPAGE. In questo caso, PropertySheet crea handle per le pagine prima di aggiungerli alla finestra delle proprietà.

Quando viene creata una pagina, la relativa routine della finestra di dialogo riceve un messaggio WM_INITDIALOG. Il parametro lParam del messaggio è un puntatore a una copia della struttura PROPSH edizione Enterprise TPAGE definita al momento della creazione della pagina. In particolare, quando viene creata una pagina, il membro lParam della struttura può essere usato per passare le informazioni definite dall'applicazione alla routine della finestra di dialogo. Ad eccezione del membro lParam , questa struttura deve essere considerata di sola lettura. La modifica di qualsiasi elemento diverso da lParam avrà conseguenze imprevedibili.

Quando il sistema passa successivamente una copia della struttura PROPSH edizione Enterprise TPAGE della pagina all'applicazione, usa lo stesso puntatore. Tutte le modifiche apportate alla struttura verranno passate. Poiché il membro lParam viene ignorato dal sistema, può essere modificato per inviare informazioni ad altre parti dell'applicazione. È possibile, ad esempio, utilizzare lParam per passare informazioni alla funzione di callback PropSheetPageProc della pagina.

PropertySheet imposta automaticamente le dimensioni e la posizione iniziale di una finestra delle proprietà. La posizione si basa sulla posizione della finestra del proprietario e la dimensione si basa sulla pagina più grande specificata nella matrice di pagine al momento della creazione della finestra delle proprietà. Se si desidera che le pagine corrispondano alla larghezza dei quattro pulsanti nella parte inferiore della finestra delle proprietà, impostare la larghezza della pagina più ampia su 190 unità di dialogo.

Le dimensioni di una finestra delle proprietà vengono calcolate dalle proprietà width e height del modello di finestra di dialogo nel file di risorse. Per altri dettagli, vedere La risorsa DIALOG o la risorsa DIALOGEX. Si noti, tuttavia, che per motivi di compatibilità, le dimensioni vengono calcolate in relazione al tipo di carattere Dlg della shell MS anziché al tipo di carattere utilizzato dalla pagina. Se si progetta una pagina che utilizza un altro tipo di carattere, è possibile utilizzare uno dei suggerimenti seguenti.

• Regolare le dimensioni del modello di finestra di dialogo per compensare la differenza di dimensione tra il tipo di carattere MS Shell Dlg e il tipo di carattere effettivamente utilizzato dalla pagina. Ad esempio, se si sceglie un tipo di carattere che è due volte più ampio di MS Shell Dlg, impostare la proprietà width del modello di dialogo su due volte l'uso normale.
• Usare un modello DIALOGEX e impostare lo stile del dialogo DS_SHELLFONT . In tal caso, il gestore della finestra delle proprietà interpreta le dimensioni del modello di finestra di dialogo relative al tipo di carattere utilizzato dal modello di finestra di dialogo.

Aggiunta e rimozione di pagine

Dopo aver creato una finestra delle proprietà, un'applicazione può aggiungere una pagina alla fine del set di pagine esistente inviando un messaggio di PSM_ADDPAGE. Per inserire una pagina tra le pagine esistenti, inviare un messaggio di PropSheet_InsertPage . Si noti che le dimensioni della finestra delle proprietà non possono essere modificate dopo la creazione. Tutte le pagine aggiunte o inserite non devono essere maggiori della pagina più grande attualmente presente nella finestra delle proprietà. Per rimuovere una pagina, inviare un messaggio di PSM_REMOVEPAGE.

Quando si definisce una pagina, è possibile specificare l'indirizzo di una funzione di callback PropSheetPageProc chiamata dalla finestra delle proprietà durante la creazione o la rimozione della pagina. L'uso di PropSheetPageProc consente di eseguire operazioni di inizializzazione e pulizia per singole pagine.

Nota

Un numero di messaggi e una chiamata di funzione si verificano mentre la finestra delle proprietà modifica l'elenco di pagine. Durante l'esecuzione di questa azione, il tentativo di modificare l'elenco di pagine avrà risultati imprevedibili. Non aggiungere, inserire o rimuovere pagine nell'implementazione di PropSheetPageProc o durante la gestione delle notifiche e dei messaggi di Windows seguenti.

• PSN_APPLY
• PSN_KILLACTIVE
• PSN_REedizione Standard T
• PSN_edizione Standard TACTIVE
• PSN_WIZBACK
• PSN_WIZNEXT
• WM_INITDIALOG
• WM_DESTROY

Se è necessario modificare una pagina della finestra delle proprietà mentre si gestisce uno di questi messaggi o mentre PropSheetPageProc è in funzione, pubblicare un messaggio di Windows privato. L'applicazione non riceverà tale messaggio fino al termine delle attività da parte del gestore della finestra delle proprietà, a quel punto sarà sicuro modificare l'elenco delle pagine.

Quando una finestra delle proprietà viene eliminata definitivamente, elimina automaticamente tutte le pagine aggiunte. Le pagine vengono eliminate definitivamente in ordine inverso da quello specificato nella matrice usata per creare le pagine. Per eliminare definitivamente una pagina creata dalla funzione CreatePropertySheetPage ma non aggiunta alla finestra delle proprietà, utilizzare la funzione DestroyPropertySheetPage.

Etichette del titolo e della pagina della finestra delle proprietà

Specificare il titolo di una finestra delle proprietà nella struttura PROPSH edizione Enterprise THEADER utilizzata per creare la finestra delle proprietà. Se il membro dwFlags include il valore PSH_PROPTITLE , la finestra delle proprietà aggiunge il suffisso "Properties" o il prefisso "Properties for", a seconda della versione. È possibile modificare il titolo dopo la creazione di una finestra delle proprietà usando il messaggio PSM_edizione Standard TTITLE. In un Aero Wizard, questo messaggio può essere usato per modificare dinamicamente il titolo di una pagina interna.

Per impostazione predefinita, una finestra delle proprietà usa la stringa del nome specificata nel modello della finestra di dialogo come etichetta per una pagina. È possibile eseguire l'override della stringa del nome includendo il valore PSP_Uedizione Standard TITLE nel membro dwFlags della struttura PROPSH edizione Enterprise TPAGE che definisce la pagina. Quando si specifica PSP_Uedizione Standard TITLE, il membro pszTitle deve contenere l'indirizzo della stringa di etichetta per la pagina.

Attivazione pagina

Una finestra delle proprietà può avere una sola pagina attiva alla volta. La pagina con l'attivazione si trova in primo piano dello stack di pagine sovrapposte. L'utente attiva una pagina selezionandone la scheda; un'applicazione attiva una pagina usando il messaggio PSM_edizione Standard TCUR edizione Standard L.

La finestra delle proprietà invia il codice di notifica PSN_KILLACTIVE alla pagina che sta per perdere l'attivazione. In risposta, la pagina deve convalidare tutte le modifiche apportate dall'utente alla pagina. Se la pagina richiede input utente aggiuntivo prima di perdere l'attivazione, usare la funzione SetWindowLong per impostare il valore DWL_MSGRESULT della pagina su TRUE. Inoltre, la pagina deve visualizzare una finestra di messaggio che descrive il problema e fornisce l'azione consigliata. Impostare DWL_MSGRESULT su FAL edizione Standard quando va bene perdere l'attivazione.

Prima che la pagina che acquisisca l'attivazione sia visibile, la finestra delle proprietà invia il codice di notifica PSN_edizione Standard TACTIVE alla pagina. La pagina deve rispondere inizializzando le finestre di controllo.

Pulsante ?

Le finestre delle proprietà possono visualizzare due pulsanti della Guida: un pulsante della Guida della finestra delle proprietà visualizzato nella parte inferiore della cornice, accanto ai pulsanti OK/Annulla/applica e un pulsante standard della barra didascalia che fornisce la Guida sensibile al contesto.

Il pulsante Della Guida della finestra delle proprietà è facoltativo e può essere abilitato in base alla pagina. Per visualizzare il pulsante Della Guida della finestra delle proprietà per una o più pagine:

• Impostare il flag PSH_HASHELP nel membro dwFlags della struttura PROPSH edizione Enterprise THEADER della finestra delle proprietà.
• Per ogni pagina che visualizzerà un pulsante ? impostare il flag PSP_HASHELP nel membro dwFlags della struttura PROPSH edizione Enterprise TPAGE della pagina.

Quando l'utente fa clic sul pulsante ?, la pagina attiva riceve un codice di notifica PSN_HELP . La pagina deve rispondere visualizzando le informazioni della Guida, in genere chiamando la funzione WinHelp.

Rimozione del pulsante Della Guida della barra della didascalia

Il pulsante della Guida della barra di didascalia viene visualizzato per impostazione predefinita, in modo che la Guida sensibile al contesto sia sempre disponibile per i pulsanti OK/Annulla/Applica. Tuttavia, questo pulsante può essere rimosso, se necessario. Per rimuovere il pulsante Della Guida della didascalia della finestra delle proprietà:

• Per le versioni dei controlli comuni precedenti alla versione 5.80, è necessario implementare una funzione di callback della finestra delle proprietà.
• Per la versione 5.80 e successive dei controlli comuni, è sufficiente impostare il flag PSH_NOCONTEXTHELP nel membro dwFlags della struttura PROPSH edizione Enterprise THEADER della finestra delle proprietà. Tuttavia, se è necessaria la compatibilità con le versioni precedenti del controllo comune, è necessario implementare la funzione di callback.

Per implementare una funzione di callback della finestra delle proprietà che rimuove il pulsante della Guida della barra didascalia:

• Impostare il flag PSH_Uedizione Standard CALLBACK nel membro dwFlags della struttura PROPSH edizione Enterprise THEADER della finestra delle proprietà.
• Impostare il membro pfnCallBack della struttura PROPSH edizione Enterprise THEADER in modo che punti alla funzione di callback.
• Implementare la funzione di callback. Quando questa funzione riceve il messaggio PSCB_PRECREATE , riceverà anche un puntatore al modello della finestra di dialogo della finestra di proprietà. Rimuovere lo stile DS_CONTEXTHELP da questo modello.

L'esempio seguente illustra come implementare una funzione di callback di questo tipo:

int CALLBACK RemoveContextHelpProc(HWND hwnd, UINT message, LPARAM lParam)
{
    switch (message) 
    {
    case PSCB_PRECREATE:
        // Remove the DS_CONTEXTHELP style from the
        // dialog box template
        if (((LPDLGTEMPLATEEX)lParam)->signature ==    
           0xFFFF)
           {
            ((LPDLGTEMPLATEEX)lParam)->style 
            &= ~DS_CONTEXTHELP;
        }
        else {
            ((LPDLGTEMPLATE)lParam)->style 
            &= ~DS_CONTEXTHELP;
        }
        return TRUE;
    }
    return TRUE;
}

Se la struttura DLGTEMPLAT edizione Enterprise X non è definita, includere la dichiarazione seguente:

#include <pshpack1.h>

typedef struct DLGTEMPLATEEX
{
    WORD dlgVer;
    WORD signature;
    DWORD helpID;
    DWORD exStyle;
    DWORD style;
    WORD cDlgItems;
    short x;
    short y;
    short cx;
    short cy;
} DLGTEMPLATEEX, *LPDLGTEMPLATEEX;

#include <poppack.h>

Pulsanti OK, Annulla e Applica

I pulsanti OK e Applica sono simili. Entrambe indirizzano le pagine di una finestra delle proprietà per convalidare e applicare le modifiche alle proprietà apportate dall'utente. L'unica differenza è che facendo clic sul pulsante OK , la finestra delle proprietà viene eliminata definitivamente dopo l'applicazione delle modifiche.

Quando l'utente fa clic sul pulsante OK o Applica , la finestra delle proprietà invia una notifica PSN_KILLACTIVE alla pagina attiva, dandogli la possibilità di convalidare le modifiche dell'utente. Se le modifiche sono valide, la pagina deve chiamare la funzione SetWindowLong con il valore DWL_MSGRESULT impostato su FAL edizione Standard. Se le modifiche dell'utente non sono valide, la pagina deve impostare DWL_MSGRESULT su TRUE e visualizzare una finestra di dialogo che informa l'utente del problema. La pagina rimane attiva finché non imposta DWL_MSGRESULT su FAL edizione Standard in risposta a un messaggio di PSN_KILLACTIVE.

Dopo che una pagina risponde a una notifica di PSN_KILLACTIVE impostando DWL_MSGRESULT su FAL edizione Standard, la finestra delle proprietà invierà una notifica PSN_APPLY a ogni pagina. Quando una pagina riceve questa notifica, deve applicare le nuove proprietà all'elemento corrispondente. Per indicare alla finestra delle proprietà che le modifiche sono valide per la pagina, chiama SetWindowLong con DWL_MSGRESULT impostato su PSNRET_NOERROR. Se le modifiche non sono valide per la pagina, restituisce un errore. In questo modo si impedisce che la finestra delle proprietà venga eliminata definitivamente e restituisca lo stato attivo alla pagina che ha ricevuto la notifica PSN_APPLY o alla pagina con stato attivo quando è stato premuto il pulsante Applica . Per restituire un errore e indicare quale pagina riceverà lo stato attivo, impostare DWL_MSGRESULT su uno dei valori seguenti.

• PSNRET_INVALID. La finestra delle proprietà non verrà eliminata definitivamente e lo stato attivo verrà restituito a questa pagina.
• PSNRET_INVALID_NOCHANGEPAGE. La finestra delle proprietà non verrà eliminata definitivamente e lo stato attivo verrà restituito alla pagina con stato attivo quando è stato premuto il pulsante.

Un'applicazione può usare il messaggio PSM_APPLY per simulare la selezione del pulsante Applica.

Il pulsante Applica viene inizialmente disabilitato quando una pagina diventa attiva, a indicare che non sono ancora state applicate modifiche alle proprietà. Quando la pagina riceve l'input tramite uno dei relativi controlli che indica che l'utente ha modificato una proprietà, la pagina deve inviare il messaggio di PSM_CHANGED alla finestra delle proprietà. Il messaggio fa sì che la finestra delle proprietà abiliti il pulsante Applica . Se successivamente l'utente fa clic sul pulsante Applica o Annulla , la pagina deve reinizializzare i controlli e quindi inviare di nuovo il messaggio di PSM_UNCHANGED per disabilitare di nuovo il pulsante Applica .

A volte il pulsante Applica determina l'annullamento di una modifica a una pagina in una finestra delle proprietà e la modifica non può essere annullata. In questo caso, la pagina deve inviare il messaggio di PSM_CANCELTOCLOedizione Standard alla finestra delle proprietà. Il messaggio fa sì che la finestra delle proprietà modifichi il testo del pulsante OK su "Chiudi", a indicare che le modifiche applicate non possono essere annullate.

A volte una pagina apporta una modifica alla configurazione di sistema che richiede il riavvio di Windows o il riavvio del sistema prima che la modifica possa essere applicata. Dopo aver apportato tale modifica, una pagina deve inviare il PSM_RESTARTWINDOWS o PSM_REBOOTSYSTEM messaggio alla finestra delle proprietà. Questi messaggi fanno sì che la funzione PropertySheet restituisca il valore ID_PSRESTARTWINDOWS o ID_PSREBOOTSYSTEM dopo l'eliminazione definitiva della finestra delle proprietà.

Quando un utente fa clic sul pulsante Annulla, la finestra delle proprietà invia il codice di notifica PSN_REedizione Standard T a tutte le pagine, a indicare che la finestra delle proprietà sta per essere eliminata definitivamente. Una pagina deve usare la notifica per eseguire operazioni di pulizia.

Procedure guidate

Una procedura guidata è un tipo speciale di finestra delle proprietà. Le procedure guidate sono progettate per presentare pagine una alla volta in una sequenza controllata dall'applicazione. Invece di selezionare da un gruppo di pagine facendo clic su una scheda, gli utenti passano avanti e indietro attraverso la sequenza, una pagina alla volta, facendo clic sui pulsanti. Ad esempio, la schermata seguente mostra la pagina iniziale della procedura guidata Aggiungi hardware:

La schermata seguente mostra la prima pagina di un Aero Wizard, il nuovo stile introdotto in Windows Vista.

Per una descrizione completa delle procedure guidate, vedere Creazione di procedure guidate .