Informazioni sulle finestre delle proprietà

Una foglio delle proprietà è una finestra che 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.

• Fondamenti del Foglio Proprietà
• finestre di dialogo Scheda Proprietà
• pagine
• creazione finestra delle proprietà
• Aggiunta e rimozione di pagine
• Titolo del foglio delle proprietà e etichette della pagina
• Attivazione della pagina
• Pulsante di aiuto
  • Rimozione del pulsante Guida della barra del titolo
• OK, Annulla e Applica pulsanti
• Assistenti

Nozioni di base sulla finestra delle proprietà

Per implementare le finestre delle proprietà nell'applicazione, includere il file header Prsht.h nel progetto. Prsht.h contiene tutti gli identificatori usati con le schede 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 del pannello di controllo Date-Time 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, si può utilizzare una procedura guidata .

Finestre di dialogo 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 delle proprietà può essere modale o non modale. Include una cornice, una barra del titolo e quattro pulsanti: OK, Annulla, Applicae (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.

Ogni pagina di una finestra delle proprietà è una finestra di dialogo non modale, definita dall'applicazione, che gestisce i controlli utilizzati 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 procedura della finestra di dialogo per una pagina quando la pagina acquista o perde l'attivazione e quando l'utente fa clic sul pulsante OK, Annulla, Applicao Guida. Le notifiche vengono inviate sotto forma di messaggi WM_NOTIFY. Il parametro lParam è l'indirizzo di una struttura NMHDR che include l'handle della finestra della finestra di dialogo del foglio delle proprietà.

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

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 scheda 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 i tasti mnemonici e i tasti di navigazione 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 routine della finestra di dialogo per una pagina non deve chiamare la funzione EndDialog. In questo modo verrà eliminato l'intero foglio 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 dei fogli delle proprietà, come mostrato nella tabella seguente.

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_MEDIUMo IDD_PROPPAGE_SMALL.

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

Creazione della scheda delle proprietà

Prima di creare una scheda proprietà, è necessario definire una o più pagine. Ciò comporta la compilazione di una struttura PROPSHEETPAGE 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 HPROPSHEETPAGE che identifica in modo univoco la pagina.

Per creare una finestra delle proprietà, è necessario specificare l'indirizzo di una struttura PROPSHEETHEADER in una chiamata alla funzione PropertySheet. La struttura definisce l'icona e il titolo per la scheda delle proprietà e include anche l'indirizzo di un array di handle HPROPSHEETPAGE che si ottengono 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 nello specificare una matrice di strutture PROPSHEETPAGE anziché una matrice di handle HPROPSHEETPAGE. In questo caso, PropertySheet crea gli handle per le pagine prima di aggiungerli alla scheda proprietà.

Quando viene creata una pagina, la relativa routine della finestra di dialogo riceve un messaggio WM_INITDIALOG. Il parametro del messaggio è un puntatore a una copia della struttura PROPSHEETPAGE 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 successivamente il sistema passa una copia della struttura della PROPSHEETPAGE alla tua applicazione, utilizza lo stesso puntatore. Le modifiche apportate alla struttura verranno trasmesse. 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 scheda di proprietà. La posizione si basa sulla posizione della finestra del proprietario e la dimensione si basa sulla pagina più grande specificata nell'array di pagine al momento della creazione della scheda 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 dalla larghezza e altezza proprietà del modello di finestra di dialogo nel file di risorse. Per altri dettagli, vedereresourceDIALOGEX o DIALOGEX Resource. 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 di DIALOGEX e impostare lo stile della finestra di 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 un PropSheetPageProc funzione di callback che la finestra delle proprietà chiama durante la creazione o la rimozione della pagina. L'uso di PropSheetPageProc consente di eseguire operazioni di inizializzazione e pulizia per singole pagine.

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à quel messaggio fino a quando il gestore della scheda delle proprietà non avrà terminato le sue attività; a quel punto sarà possibile 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 funzioneCreatePropertySheetPagema non è stata aggiunta alla finestra delle proprietà, utilizzare la funzioneDestroyPropertySheetPage.

Titolo della scheda delle proprietà e etichette della pagina

Devi specificare il titolo di una scheda delle proprietà nella struttura PROPSHEETHEADER utilizzata per creare la scheda 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 di PSM_SETTITLE. 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_USETITLE nel dwFlags membro della strutturaPROPSHEETPAGE che definisce la pagina. Quando si specifica PSP_USETITLE, 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 di PSM_SETCURSEL.

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 funzioneSetWindowLongper 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 FALSE quando va bene perdere l'attivazione.

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

Pulsante di aiuto

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

Il pulsante della Guida nella finestra delle proprietà è facoltativo e può essere abilitato su base pagina per 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 PROPSHEETHEADER del foglio delle proprietà.
• Per ogni pagina che visualizzerà un pulsante di aiuto, impostare il flag PSP_HASHELP nel membro dwFlags della struttura PROPSHEETPAGE della pagina.

Quando l'utente fa clic sul pulsante Aiuto, 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 Guida della barra del titolo

Il pulsante Guida della barra del titolo è 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 Guida dalla barra del titolo della finestra delle proprietà:

• Per le versioni dei controlli comuni precedenti a versione 5.80, è necessario implementare una funzione di callback della finestra delle proprietà .
• Per versione 5.80 e versioni successive dei controlli comuni, è sufficiente impostare il flag PSH_NOCONTEXTHELP nel dwFlags membro della struttura PROPSHEETHEADER del fascicolo 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 della didascalia:

• Impostare il flag PSH_USECALLBACK nel membro dwFlags della struttura PROPSHEETHEADER del foglio delle proprietà.
• Impostare il membro pfnCallBack della struttura PROPSHEETHEADER affinché 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 delle 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 strutturaDLGTEMPLATEEXnon è 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; entrambi indirizzano le pagine di un pannello delle proprietà a 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 di dialogo delle proprietà invia una notifica PSN_KILLACTIVE alla pagina attiva, dandole 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 FALSE. 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 a FALSE in risposta a un messaggio PSN_KILLACTIVE.

Dopo che una pagina risponde a una notifica di PSN_KILLACTIVE impostando DWL_MSGRESULT su FALSE, la scheda delle proprietà invierà quindi 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, chiamare 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 e viene restituito il focus alla pagina che ha ricevuto la notifica di PSN_APPLY o alla pagina che aveva il focus quando è stato premuto il pulsante Applica. Per restituire un errore e indicare a quale pagina verrà dato lo stato attivo, impostate DWL_MSGRESULT su uno dei valori seguenti.

• PSNRET_INVALID. La finestra delle proprietà non verrà distrutta, e l'attenzione verrà restituita 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 di PSM_APPLY per simulare la selezione del pulsante Applica .

Il pulsante Applica è inizialmente disabilitato quando una pagina diventa attiva, per indicare che non sono ancora state apportate modifiche alle proprietà da applicare. 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 nuovamente il messaggio PSM_UNCHANGED per disabilitare di nuovo il pulsante Applica.

A volte il pulsante Applica provoca una modifica a una scheda delle proprietà, e la modifica non può essere annullata. In questo caso, la pagina deve inviare il messaggio di PSM_CANCELTOCLOSE alla scheda 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 messaggio PSM_RESTARTWINDOWS o PSM_REBOOTSYSTEM alla finestra delle proprietà. Questi messaggi fanno sì che la funzione PropertySheet restituisca il valore ID_PSRESTARTWINDOWS o ID_PSREBOOTSYSTEM dopo che la finestra delle proprietà è stata distrutta.

Quando un utente fa clic sul pulsante annulla , la finestra delle proprietà invia il codice di notifica PSN_RESET 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.

Assistenti

Una procedura guidata è un tipo speciale di scheda 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.

Vedere Creazione di procedure guidate per una descrizione completa delle procedure guidate.