O listech vlastností

Seznam vlastností je okno, které umožňuje uživateli zobrazit a upravit vlastnosti položky. Například aplikace tabulky může použít seznam vlastností, aby uživatel mohl nastavit vlastnosti písma a ohraničení buňky nebo zobrazit a nastavit vlastnosti zařízení, například diskovou jednotku, tiskárnu nebo myš.

Tato část popisuje následující témata.

• Základy seznamu vlastností
• dialogová okna seznam vlastností
• stránky
• vytvoření seznamu vlastností
• přidávání a odebírání stránek
• název seznamu vlastností a popisky stránek
• aktivace stránky
• Tlačítko nápovědy
  • odebrání tlačítka nápovědy na panelu titulků
• Tlačítka OK, Zrušit a Použít
• Čarodějové

Základy seznamu vlastností

Chcete-li implementovat seznamy vlastností v aplikaci, zahrňte do projektu soubor hlaviček Prsht.h. Prsht.h obsahuje všechny identifikátory použité v listech vlastností.

Seznam vlastností obsahuje jedno nebo více překrývajících se podřízených oken nazývaných stránky, z nichž každá obsahuje ovládací okna pro nastavení skupiny souvisejících vlastností. Stránka může například obsahovat ovládací prvky pro nastavení vlastností písma položky, včetně stylu typu, velikosti bodu, barvy atd. Každá stránka má kartu, kterou uživatel může vybrat, aby stránku přenesl do popředí seznamu vlastností. Například aplikace Date-Time ovládacích panelů zobrazí následující seznam vlastností.

Standardní seznam vlastností s více stránkami s kartami umožňuje uživateli náhodný přístup ke všem vlastnostem. Pokud je vhodnější nastavit vlastnosti v posloupnosti, můžete použít průvodce .

Dialogová okna vlastností

Seznam vlastností a stránky, které obsahuje, jsou ve skutečnosti dialogová okna. Seznam vlastností je systémově definované dialogové okno, které spravuje stránky a poskytuje pro ně společný kontejner. Dialogové okno vlastností může být modální nebo nemodální. Obsahuje rámeček, titulní lištu a čtyři tlačítka: OK, Zrušit, Použíta (volitelně) Nápověda. Postupy dialogového okna pro stránky přijímají kódy oznámení ve formě WM_NOTIFY zpráv, když uživatel klikne na tlačítka.

Poznámka

Ne všechny informace v této části platí pro průvodce, kteří mají poněkud odlišný vzhled a chování. Například, průvodci mají odlišnou sadu tlačítek a nemají žádné karty. Další informace naleznete v tématu Vytváření průvodců.

Každá stránka v seznamu vlastností je bezmodální dialogové okno definované aplikací, které spravuje ovládací okna používaná k zobrazení a úpravě vlastností položky. Zadáte šablonu dialogového okna použitou k vytvoření každé stránky a také procedura dialogového okna, která spravuje ovládací prvky a nastaví vlastnosti odpovídající položky.

Vlastnostní list odešle kódy oznámení do procedury dialogového okna pro stránku, když stránka získává nebo ztrácí aktivaci, a když uživatel klikne na tlačítko OK, Zrušit, Použítnebo Nápověda. Oznámení se odesílají ve formě WM_NOTIFY zpráv. Parametr lParam je adresa struktury NMHDR, která obsahuje popisovač okna pro dialogové okno karty vlastností.

Některé kódy oznámení vyžadují, aby stránka v reakci na zprávu WM_NOTIFY vrátila buď TRUE, nebo FALSE. Chcete-li to provést, stránka musí použít funkci SetWindowLong nastavit hodnotu DWL_MSGRESULT pro dialogové okno stránky na hodnotu TRUE nebo FALSE.

Stránky

Seznam vlastností musí obsahovat alespoň jednu stránku, ale nesmí obsahovat více než hodnotu MAXPROPPAGES, jak je definováno v souborech hlaviček systému Windows. Každá stránka má index založený na nule, který seznam vlastností přiřadí podle pořadí, ve kterém je stránka přidána do seznamu vlastností. Indexy se používají ve zprávách, které odesíláte do seznamu vlastností.

Stránka vlastností může obsahovat vnořené dialogové okno. Pokud ano, musíte zahrnout styl WS_EX_CONTROLPARENT pro dialogové okno nejvyšší úrovně a použít funkci IsDialogMessage s popisovačem nadřazeného dialogového okna. Tím se zajistí, že uživatel může používat mnemoniky a navigační klávesy dialogového okna k přesunutí zaměření na ovládací prvky ve vnořeném dialogovém okně.

Každá stránka má odpovídající ikonu a popisek. Karta vlastností vytvoří pro každou stránku kartu a zobrazí ikonu a popisek na kartě. Očekává se, že všechny stránky karty vlastností budou používat netučné písmo. Pokud chcete zajistit, aby písmo nebylo tučné, zadejte v šabloně dialogového okna styl DS_3DLOOK.

Procedura dialogového okna pro stránku nesmí volat funkci EndDialog. Tímto způsobem zničíte celý seznam vlastností, nejen stránku.

Minimální velikost stránky seznamu vlastností je 212 jednotek dialogového okna vodorovně a 114 jednotek svisle. Pokud je dialogové okno stránky menší, stránka se zvětší, dokud nebude odpovídat minimální velikosti. Soubor záhlaví Prsht.h obsahuje tři sady doporučených velikostí pro stránky seznamu vlastností, jak je znázorněno v následující tabulce.

Velikost	Popis
PROP_SM_CXDLG	Šířka v dialogových jednotkách na malé stránce vlastností.
PROP_SM_CYDLG	Výška, v dialogových jednotkách, stránky malého panelu vlastností.
PROP_MED_CXDLG	Šířka v jednotkách dialogového okna stránky se středně velkou stránkou seznamu vlastností
PROP_MED_CYDLG	Výška v dialogových jednotkách středně velké stránky listu vlastností.
PROP_LG_CXDLG	Šířka v jednotkách dialogového okna na stránce s velkými vlastnostmi.
PROP_LG_CYDLG	Výška stránky velkého listu vlastností v jednotkách dialogového okna.

Použití těchto doporučených velikostí pomůže zajistit vizuální konzistenci mezi vaší aplikací a jinými aplikacemi systému Microsoft Windows.

V editoru prostředků sady Microsoft Visual Studio můžete vytvořit stránku odpovídající velikosti v dialogovém okně Přidat prostředek. Rozbalte uzel Dialogové okno a vyberte IDD_PROPPAGE_LARGE, IDD_PROPPAGE_MEDIUMnebo IDD_PROPPAGE_SMALL.

Karta vlastností se automaticky přizpůsobí největší straně.

Vytvoření seznamu vlastností

Před vytvořením seznamu vlastností musíte definovat jednu nebo více stránek. To zahrnuje vyplnění struktury PROPSHEETPAGE informacemi o stránce – její ikona, popisek, šablona dialogového okna, procedura dialogového okna atd. A pak zadejte adresu struktury ve volání CreatePropertySheetPage funkce. Funkce vrátí popisovač typu HPROPSHEETPAGE, který jednoznačně identifikuje stránku.

Chcete-li vytvořit seznam vlastností, zadáte adresu struktury PROPSHEETHEADER při volání funkce PropertySheet. Struktura definuje ikonu a název seznamu vlastností a také obsahuje adresu pole popisovačů HPROPSHEETPAGE, které získáte pomocí CreatePropertySheetPage. Když PropertySheet vytvoří seznam vlastností, obsahuje stránky identifikované v poli. Stránky se zobrazí v seznamu vlastností ve stejném pořadí, v jakém jsou obsaženy v poli.

Dalším způsobem, jak přiřadit stránky k seznamu vlastností, je zadat pole PROPSHEETPAGE struktury namísto pole HPROPSHEETPAGE úchyty. V tomto případě PropertySheet vytvoří úchyty pro stránky před jejich přidáním do panelu vlastností.

Po vytvoření stránky obdrží procedura dialogového okna zprávu WM_INITDIALOG. Parametr lParam zprávy je ukazatel na kopii PROPSHEETPAGE struktury, která je definována při vytváření stránky. Konkrétně při vytvoření stránky lze k předání informací definovaných aplikací do procedury dialogového okna použít člena lParam struktury. S výjimkou člena lParam musí být tato struktura považována za pouze pro čtení. Změna čehokoli jiného než lParam bude mít nepředvídatelné důsledky.

Když systém následně předá kopii struktury PROPSHEETPAGE vaší aplikaci, použije stejný ukazatel. Všechny změny struktury budou předány. Vzhledem k tomu, že člen lParam je ignorován systémem, lze jej upravit tak, aby odesílal informace do jiných částí vaší aplikace. Můžete například použít lParam k předání informací funkci zpětného volání stránky PropSheetPageProc.

PropertySheet automaticky nastaví velikost a počáteční pozici dialogového okna vlastností. Pozice je založena na pozici okna vlastníka a velikost je založena na největší stránce zadané v poli stránek při vytvoření seznamu vlastností. Pokud chcete, aby stránky odpovídaly šířce čtyř tlačítek v dolní části seznamu vlastností, nastavte šířku nejširší stránky na 190 jednotek dialogového okna.

Velikost karty vlastností se vypočítá z šířky a výšky vlastností dialogové šablony ve zdrojovém souboru. Pro podrobnosti viz DIALOG zdroj nebo DIALOGEX zdroj. Mějte však na paměti, že z důvodu kompatibility se rozměry počítají vzhledem k písmu MS Shell Dlg, nikoli k písmu používanému stránkou. Pokud navrhujete stránku, která používá jiné písmo, můžete použít jeden z následujících návrhů.

• Upravte rozměry šablony dialogového okna tak, aby se kompenzuje rozdíl mezi písmem MS Shell Dlg a písmem, které stránka skutečně používá. Pokud například zvolíte písmo, které je dvakrát tak široké jako MS Shell Dlg, nastavte vlastnost šířky šablony dialogového okna na dvojnásobek normálního použití.
• Použijte šablonu DIALOGEX a nastavte styl dialogového okna DS_SHELLFONT. V takovém případě správce seznamu vlastností interpretuje rozměry šablony dialogového okna vzhledem k písmu použitému šablonou dialogového okna.

Přidávání a odebírání stránek

Po vytvoření seznamu vlastností může aplikace přidat stránku na konec existující sady stránek odesláním PSM_ADDPAGE zprávy. Pokud chcete vložit stránku mezi existující stránky, odešlete PropSheet_InsertPage zprávu. Všimněte si, že velikost seznamu vlastností se po vytvoření nemůže změnit. Všechny přidané nebo vložené stránky nesmí být větší než největší stránka, která je aktuálně v seznamu vlastností. Pokud chcete stránku odebrat, odešlete zprávu PSM_REMOVEPAGE.

Když definujete stránku, můžete zadat adresu do funkce zpětného volání PropSheetPageProc, kterou seznam vlastností volá při vytváření nebo odebírání stránky. Pomocí PropSheetPageProc získáte možnost provádět inicializační a čisticí operace pro jednotlivé stránky.

Poznámka

Během manipulace se seznamem stránek dojde k několika zprávám a jednomu volání funkce. Během této akce může pokus o změnu seznamu stránek vést k nepředvídatelným výsledkům. Nepřidávejte, vkládejte nebo neodebívejte stránky v implementaci PropSheetPageProcnebo při zpracování následujících oznámení a zpráv systému Windows.

• PSN_APPLY
• PSN_KILLACTIVE
• PSN_RESET
• PSN_SETACTIVE
• PSN_WIZBACK
• PSN_WIZNEXT
• WM_INITDIALOG
• WM_DESTROY

Pokud je potřeba upravit stránku seznamu vlastností během zpracování jedné z těchto zpráv nebo když PropSheetPageProc je v provozu, publikujte soukromou zprávu systému Windows. Aplikace tuto zprávu neobdrží, dokud správce seznamu vlastností nedokončí své úkoly. V tomto okamžiku bude bezpečné upravit seznam stránek.

Když je seznam vlastností zničen, automaticky zničí všechny stránky, které byly do něj přidány. Stránky jsou zničeny v obráceném pořadí od toho, co je zadáno v poli použitém k vytvoření stránek. Chcete-li zničit stránku vytvořenou funkcí CreatePropertySheetPage, ale nebyla přidána do seznamu vlastností, použijte funkci DestroyPropertySheetPage.

Název seznamu vlastností a popisky stránek

Název karty vlastností zadáte ve struktuře PROPSHEETHEADER použité k vytvoření karty vlastností. Pokud člen dwFlags obsahuje hodnotu PSH_PROPTITLE, list vlastností přidá buď příponu „Vlastnosti“, nebo předponu „Pro vlastnosti“, v závislosti na verzi. Název můžete změnit po vytvoření seznamu vlastností pomocí PSM_SETTITLE zprávy. V Průvodci aero se tato zpráva dá použít k dynamické změně názvu vnitřní stránky.

Ve výchozím nastavení panel vlastností používá řetězec názvu zadaný v šabloně dialogového okna jako popisek stránky. Řetězec názvu můžete přepsat zahrnutím hodnoty PSP_USETITLE do členu dwFlags struktury PROPSHEETPAGE, která definuje stránku. Pokud je zadán PSP_USETITLE, člen pszTitle musí obsahovat adresu řetězce označení pro stránku.

Aktivace stránky

Seznam vlastností může mít současně jenom jednu aktivní stránku. Stránka, která má aktivaci, je v popředí překrývající se hromady stránek. Uživatel aktivuje stránku výběrem karty; aplikace aktivuje stránku pomocí zprávy PSM_SETCURSEL.

List vlastností posílá oznamovací kód PSN_KILLACTIVE stránce, která má ztratit aktivaci. V odpovědi musí stránka ověřit všechny změny, které uživatel provedl na stránce. Pokud stránka před ztrátou aktivace vyžaduje další uživatelský vstup, pomocí funkce SetWindowLong nastavte DWL_MSGRESULT hodnotu stránky na TRUE. Stránka také musí zobrazit okno se zprávou, které popisuje problém a poskytuje doporučenou akci. Nastavte DWL_MSGRESULT na FALSE, pokud je přijatelné ztratit aktivaci.

Před zobrazením stránky, která získává aktivaci, odešle seznam vlastností na stránku kód oznámení PSN_SETACTIVE. Stránka musí reagovat inicializací jeho ovládacích oken.

Tlačítko Nápověda

Seznamy vlastností můžou zobrazovat dvě tlačítka nápovědy: tlačítko nápovědy seznamu vlastností, které se zobrazí v dolní části rámečku, vedle OK/Zrušit/Použít tlačítka a standardní tlačítko řádku titulků, které poskytuje kontextovou nápovědu.

Tlačítko Nápověda seznamu vlastností je volitelné a lze ho povolit na stránce podle stránky. Zobrazení tlačítka nápovědy seznamu vlastností pro jednu nebo více stránek:

• Nastavte příznak PSH_HASHELP v členu dwFlags struktury PROPSHEETHEADER stránky vlastností.
• Pro každou stránku, která má zobrazit tlačítko Nápověda, nastavte ve struktuře PROPSHEETPAGE příznak PSP_HASHELP v členu dwFlags.

Když uživatel klikne na tlačítko Nápověda, aktivní stránka obdrží PSN_HELP kód oznámení. Stránka musí odpovídat zobrazením informací nápovědy, obvykle voláním funkce WinHelp.

Odebrání tlačítka nápovědy na panelu titulků

Ve výchozím nastavení se zobrazí tlačítko Nápovědy na řádku titulků, takže kontextová nápověda je vždy dostupná pro tlačítka OK/Zrušit/Použít. Toto tlačítko ale můžete v případě potřeby odebrat. Odebrání tlačítka nápovědy na panelu titulků seznamu vlastností:

• Pro verze běžných ovládacích prvků před verze 5.80je nutné implementovat funkci zpětného volání seznamu vlastností .
• U verze 5.80 a novějších běžných ovládacích prvků můžete jednoduše nastavit příznak PSH_NOCONTEXTHELP v dwFlags člen struktury PROPSHEETHEADER seznamu vlastností. Pokud však potřebujete zpětnou kompatibilitu s dřívějšími běžnými verzemi ovládacích prvků, musíte implementovat funkci zpětného volání.

Implementace funkce zpětného volání seznamu vlastností, která odebere tlačítko nápovědy na řádku titulků:

• Nastavte příznak PSH_USECALLBACK v členu dwFlags struktury PROPSHEETHEADER listu vlastností.
• Nastavte člena pfnCallBack ve struktuře PROPSHEETHEADER tak, aby odkazoval na funkci zpětného volání.
• Implementujte funkci zpětného volání. Když tato funkce obdrží PSCB_PRECREATE zprávu, obdrží také ukazatel na šablonu dialogového okna seznamu vlastností. Odeberte ze šablony styl DS_CONTEXTHELP.

Následující ukázka ukazuje, jak implementovat takovou funkci zpětného volání:

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;
}

Pokud není definována struktura DLGTEMPLATEEX, uveďte následující deklaraci:

#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>

Tlačítka OK, Zrušit a Použít

Tlačítka OK a Použít jsou podobná; obě stránkám panelu vlastností nařizují ověřit a aplikovat změny vlastností, které uživatel provedl. Jediným rozdílem je, že kliknutí na tlačítko OK způsobí zničení seznamu vlastností po použití změn.

Když uživatel klikne na tlačítko OK nebo Použít, dialogové okno odešle na aktivní stránku oznámení PSN_KILLACTIVE, čímž jí poskytne příležitost ověřit změny provedené uživatelem. Pokud jsou změny platné, stránka musí zavolat funkci SetWindowLong s hodnotou DWL_MSGRESULT nastavenou na hodnotu FALSE. Pokud změny uživatele nejsou platné, stránka musí nastavit DWL_MSGRESULT na TRUE a zobrazit dialogové okno s informací o problému uživatele. Stránka zůstane aktivní, dokud nenastaví DWL_MSGRESULT na FALSE v reakci na zprávu PSN_KILLACTIVE.

Jakmile stránka odpoví na oznámení PSN_KILLACTIVE nastavením DWL_MSGRESULT na FALSE, karta vlastností pošle každé stránce oznámení PSN_APPLY. Když stránka obdrží toto oznámení, musí použít nové vlastnosti na odpovídající položku. Chcete-li označit na seznam vlastností, že změny jsou platné pro stránku, zavolejte SetWindowLong s DWL_MSGRESULT nastavenou na PSNRET_NOERROR. Pokud jsou změny pro stránku neplatné, vraťte chybu. Tím zabráníte zničení seznamu vlastností a vrátí fokus na stránku, která obdržela oznámení PSN_APPLY, nebo na stránku, která měla fokus při stisknutí tlačítka Použít. Pokud chcete vrátit chybu a určit, na které stránce se fokus zobrazí, nastavte DWL_MSGRESULT na jednu z následujících hodnot.

• PSNRET_INVALID. Okno vlastností nebude zničeno a focus se vrátí na tuto stránku.
• PSNRET_INVALID_NOCHANGEPAGE. Seznam vlastností nebude zničen a fokus se vrátí na stránku, která měla fokus při stisknutí tlačítka.

Aplikace může pomocí zprávy PSM_APPLY simulovat výběr tlačítka Použít.

Tlačítko Použít je zpočátku zakázáno, když se stránka aktivuje, což znamená, že ještě nejsou k dispozici žádné změny vlastností, které se mají použít. Když stránka obdrží vstup prostřednictvím jednoho z jeho ovládacích prvků označujících, že uživatel upravil vlastnost, musí stránka odeslat PSM_CHANGED zprávu do seznamu vlastností. Zpráva způsobí, že seznam vlastností povolí tlačítko Použít. Pokud uživatel následně klikne na tlačítko Použít nebo Zrušit, musí stránka znovu inicializovat ovládací prvky a pak odeslat zprávu PSM_UNCHANGED, aby se tlačítko Použít znovu zakázalo.

Někdy tlačítko Použít způsobí, že stránka provede změnu na listu vlastností, a tuto změnu nelze vrátit zpět. V takovém případě musí stránka odeslat zprávu PSM_CANCELTOCLOSE na list vlastností. Zpráva způsobí, že seznam vlastností změní text tlačítka OK na Zavřít, což znamená, že použité změny nelze zrušit.

Stránka někdy provede změnu konfigurace systému, která vyžaduje restart operačního systému Windows nebo restart systému, aby se změna projevila. Po provedení takové změny musí stránka odeslat buď PSM_RESTARTWINDOWS, nebo PSM_REBOOTSYSTEM zprávu do seznamu vlastností. Tyto zprávy způsobí, že funkce PropertySheet vrátí ID_PSRESTARTWINDOWS nebo ID_PSREBOOTSYSTEM hodnotu po zničení seznamu vlastností.

Když uživatel klikne na tlačítko Zrušit, panel vlastností odešle kód oznámení PSN_RESET na všechny stránky, což znamená, že panel vlastností má být uzavřen. Stránka musí k provádění operací čištění použít oznámení.

Kouzelníci

Průvodce je speciální typ seznamu vlastností. Průvodci jsou navrženi tak, aby najednou prezentovali stránky v posloupnosti, která je řízena aplikací. Místo toho, abyste vybrali ze skupiny stránek kliknutím na kartu, přechází uživatelé postupně dopředu a dozadu, a to jedním kliknutím na tlačítka. Například následující snímek obrazovky ukazuje úvodní stránku průvodce přidáním hardwaru:

Následující snímek obrazovky ukazuje první stránku Průvodce aero, nový styl představený v systému Windows Vista.

Kompletní diskuzi o průvodcích najdete v tématu Vytváření průvodců.