Vytváření průvodců

Průvodce je typ seznamu vlastností, který poskytuje jednoduchý a účinný způsob, jak uživatele vést postupem.

Průvodci jsou jedním z klíčů pro zjednodušení uživatelského prostředí. Umožňují provést složitou operaci, například konfiguraci aplikace, a rozdělit ji do řady jednoduchých kroků. V každém okamžiku procesu můžete poskytnout vysvětlení toho, co je potřeba, a zobrazit ovládací prvky, které uživateli umožňují vybrat a zadat text.

Průvodce je ve skutečnosti typem seznamu vlastností. Seznam vlastností je v podstatě kontejner pro kolekci stránek, kde každá stránka je samostatné dialogové okno. Zatímco běžné seznamy vlastností umožňují uživateli kdykoli přistupovat k libovolné stránce, průvodci prezentují stránky v sekvenci. Místo karet se tlačítka používají k navigaci dopředu a dozadu. Pořadí zobrazení stránek je řízeno aplikací a lze je upravit na základě uživatelského vstupu.

Existují dva hlavní styly průvodce: starší styl Průvodce97 a styl Aero představený v systému Windows Vista. Ilustrace najdete v tématu O listech vlastností. (Třetí styl, který používá jenom příznak PSH_WIZARD nebo PSH_WIZARD_LITE, představuje jednoduchou posloupnost listů vlastností bez záhlaví nebo vodoznaků.)

Poznámka

Vodoznak v kontextu průvodců je rastrový obrázek, který se zobrazí na levém okraji některých stránek.

 

Diskuze ve většině tohoto dokumentu předpokládá, že implementujete průvodce pro systém s verze 5.80 nebo novějšími běžnými ovládacími prvky. Pokud se pokusíte použít styl Wizard97 se staršími verzemi běžných ovládacích prvků, aplikace se může zkompilovat, ale nezobrazí se správně. Diskuzi o tom, jak vytvořit průvodce kompatibilní s Průvodce97 v dřívějších systémech, naleznete v části Zpětně kompatibilní průvodci dále v tomto tématu.

Co potřebujete vědět

Technologie

• ovládací prvky Windows

Požadavky

• C/C++
• Programování uživatelského rozhraní systému Windows

Instrukce

Implementace průvodce

Implementace průvodce je podobná implementaci seznamu běžných vlastností. Na nejzásadnější úrovni je potřeba nastavit jeden z následujících příznaků nebo kombinací příznaků ve struktuře PROPSHEETHEADER, která definuje seznam vlastností.

Vlajka	Styl
PSH_WIZARD	Jednoduchý průvodce bez záhlaví nebo rastrových obrázků.
PSH_WIZARD_LITE	Podobně jako PSH_WIZARD, s některými drobnými rozdíly ve vzhledu; Například oddělovač nad tlačítky je nastaven na plnou šířku okna.
PSH_WIZARD97	Průvodce Wizard97 s (volitelnými) záhlavími, bitmapovými obrázky záhlaví a s vodoznaky.
PSH_WIZARD | PSH_AEROWIZARD	Průvodce Aero. Průvodci Aero nepoužívají vodoznaky ani rastrové obrázky záhlaví. Vyžadují model jedno-vláknového apartmánu (STA).

 

Základní postup implementace průvodce je následující:

1. Vytvořte šablonu dialogového okna pro každou stránku.
2. Definujte stránky vytvořením struktury PROPSHEETPAGE pro každou stránku. Tato struktura definuje stránku a obsahuje ukazatele na šablonu dialogového okna a všechny rastrové obrázky nebo jiné prostředky.
3. Předejte strukturu PROPSHEETPAGE, která byla vytvořena v předchozím kroku, do funkce CreatePropertySheetPage pro vytvoření popisovače HPROPSHEETPAGE stránky.
4. Definujte průvodce vytvořením struktury PROPSHEETHEADER.
5. Předejte strukturu PROPSHEETHEADER funkci PropertySheet k zobrazení průvodce.
6. Implementujte procedury dialogového okna pro každou stránku pro zpracování zpráv oznámení z ovládacích prvků stránky a tlačítek průvodce a zpracování dalších zpráv systému Windows.

Vytvoření šablon dialogového okna

Existují dva základní typy stránky průvodce: exteriér a interiér. Vnější stránky jsou úvodní (vítací) a závěrečné stránky. Všechny ostatní jsou vnitřní stránky.

Šablony dialogového okna pro vnější stranu stránky

Základní rozložení úvodních a dokončených stránek je stejné. Následující obrázek znázorňuje úvodní stránku Průvodce97 se zástupným vodoznakem.

Pro externí stránky Průvodce97 je šablona dialogového okna 317x193 dialogové jednotky. Vyplní všechny části průvodce kromě titulku a pruhu v dolní části, který obsahuje tlačítka Zpět, Dalšía Zrušit. Levá strana šablony, která je vyhrazená pro rastrový obrázek vodoznaku, by neměla obsahovat žádné ovládací prvky. Vodoznak je zadán ve struktuře průvodce PROPSHEETHEADER a automaticky se přidá na stránku. Při návrhu šablony zdroje musíte pro to nechat místo.

Při vytváření rastrového obrázku vodoznaku mějte na paměti, že dialogové okno se může zvětšit, pokud například uživatel zvolí velké systémové písmo. Různé jazyky mají také tendenci mít různé metriky písma. Když se stránka zvětší, oblast vyhrazená pro vodoznak se úměrně zvětší. Nemůžete ale změnit rastrový obrázek vodoznaku a rastrový obrázek není roztažený tak, aby vyplnil větší oblast. Místo toho je rastrový obrázek ponechán v původní velikosti v levé horní části vyhrazené oblasti. Část větší vyhrazené oblasti, kterou vodoznak nepokrývá, se automaticky vyplní barvou levého pixelu rastrového obrázku.

Pokud potřebujete mít rastrové obrázky vodoznaků s různou velikostí pro různé metriky písma, existují dvě možná řešení:

• Před vytvořením průvodce získejte metriky písma a zadejte rastrový obrázek vodoznaku s odpovídající velikostí.
• Při vytváření průvodce nezadávejte rastrový obrázek vodoznaku. Průvodce 97 ponechá oblast vodoznaku prázdnou. Potom nakreslete rastrový obrázek s odpovídající velikostí na oblast vyhrazenou pro vodoznak.

Ovládací prvky můžete umístit do oblasti napravo od vodoznaku stejně jako u běžného dialogového okna. Barva pozadí této oblasti je určena systémem a nevyžaduje žádnou akci na vaší straně. Do této oblasti obvykle umístíte dva statické ovládací prvky. Horní část obsahuje název a používá velké tučné písmo (12 bodů Verdana Bold pro Průvodce97). Druhý, který je určen pro vysvětlující text, používá standardní písmo dialogového okna.

Hlavním rozdílem mezi úvodními a doplňovacími stránkami jsou tlačítka průvodce a text ve statických ovládacích prvcích. Úvodní stránky mají obvykle tlačítko Další a tlačítko Zpět, přičemž povoleno je pouze tlačítko Další. Stránky dokončení mají povolené tlačítko Zpět a tlačítko Další je nahrazeno tlačítkem Dokončit.

Poznámka

V Průvodcích Aero je tlačítko Zpět nahrazeno tlačítkem se šipkou na panelu titulků.

 

Text na tlačítku Dokončit můžete upravit tak, že průvodci pošlete zprávu PSM_SETFINISHTEXT. Ve výchozím nastavení tlačítko Dokončit neobsahuje akcelerátor klávesnice. Pokud chcete definovat akcelerátor klávesnice, vložte ampersand do textového řetězce, který předáte do PSM_SETFINISHTEXT. Například "&Finish" definuje "F" jako akcelerátor klávesnice.

Šablony dialogových oken pro vnitřní stránky

Vnitřní stránky mají poněkud jiný vzhled než vnější stránky. Následující obrázek znázorňuje ukázkovou vnitřní stránku Průvodce97 se zástupným rastrovým obrázkem záhlaví.

Oblast záhlaví v horní části stránky je zpracována seznamem vlastností, takže není součástí šablony. Obsah záhlaví je určen ve struktuře PROPSHEETPAGE stránky a ve struktuře PROPSHEETHEADER průvodce. Protože se vnitřní stránka musí vejít mezi záhlavím a tlačítky, šablona dialogového okna Průvodce97 je 317x143 dialogových jednotek, poněkud menší než šablona pro vnější stránky.

Následující obrázek znázorňuje Průvodce aero, který byl vytvořen ze stejné šablony.

Definování stránek průvodce

Po vytvoření šablon dialogového okna a souvisejících prostředků, jako jsou rastrové obrázky a tabulky řetězců, můžete vytvořit stránky seznamu vlastností. Postup je podobný postupu pro standardní seznamy vlastností. Nejprve vyplňte příslušné členy struktury PROPSHEETPAGE. (Někteří členové jsou specifičtí pro průvodce.) Potom zavolejte funkci CreatePropertySheetPage pro vytvoření HPROPSHEETPAGE stránky.

Následující příznaky průvodce lze nastavit v členu struktury dwFlagsPROPSHEETPAGE.

Vlajka	Popis
PSP_HIDEHEADER	Nastavte tento příznak pro vnější stránky v Průvodci97. Záhlaví se nezobrazuje a vodoznak se dá zobrazit.
PSP_USEHEADERTITLE	Nastavte tento příznak pro vnitřní stránky tak, aby se nadpis umístil do oblasti záhlaví v Průvodci97 nebo v horní části klientské oblasti v Průvodci Aero.
PSP_USEHEADERSUBTITLE	Nastavte tento příznak pro vnitřní stránky tak, aby se podnadpis vložil do oblasti záhlaví v Průvodci97.

 

Pokud jste nastavili PSP_USEHEADERTITLE nebo PSP_USEHEADERSUBTITLE, přiřaďte nadpis a text titulku pszHeaderTitle a pszHeaderSubtitle členy. Když přiřadíte textové řetězce členům PROPSHEETPAGE a propsheetheader, můžete buď přiřadit ukazatel řetězce, nebo použít makro MAKEINTRESOURCE k přiřazení hodnoty ze zdroje řetězce. Prostředek řetězce se načte z modulu zadaného v členu hInstance struktury PROPSHEETHEADER průvodce.

Při volání CreatePropertySheetPage pro vytvoření stránky přiřaďte výsledek prvku pole popisovačů HPROPSHEETPAGE. Toto pole se používá při vytváření seznamu vlastností. Index pole ukazatele stránky určuje výchozí pořadí, ve kterém se zobrazí. Po vytvoření popisovače HPROPSHEETPAGE stránky můžete znovu použít stejnou strukturu propSHEETPAGE vytvořit další stránku přiřazením nových hodnot příslušným členům.

Alternativní způsob, jak vytvořit stránky, je použít samostatné PROPSHEETPAGE struktury pro každou stránku a vytvořit pole struktur. Toto pole se používá místo pole popisovačů HPROPSHEETPAGE při vytváření seznamu vlastností. Použití samostatných struktur PROPSHEETPAGE eliminuje potřebu volat CreatePropertySheetPage, ale používá více paměti. Jinak mezi těmito dvěma přístupy není žádný významný rozdíl.

Následující příklad definuje interní stránku Wizard97 přiřazením hodnot ve struktuře PROPSHEETPAGE. V tomto příkladu se název stránky, podnadpis a šablona dialogového okna identifikují podle ID prostředků. Funkce CreatePropertySheetPage je pak volána k vytvoření popisovače HPROPSHEETPAGE stránky. Vzhledem k tomu, že se zobrazí druhá stránka, je popisovač přiřazen k poli popisovačů, ahpsp, s indexem 1.

// g_hInstance is the global HINSTANCE of the application.
// IntPage1DlgProc is the dialog procedure for this page.
// ahpsp is an array of HPROPSHEETPAGE handles.

PROPSHEETPAGE psp = { sizeof(psp) };

psp.hInstance         = g_hInstance;
psp.dwFlags           = PSP_USEHEADERTITLE | PSP_USEHEADERSUBTITLE;
psp.lParam            = (LPARAM) &wizdata;
psp.pszHeaderTitle    = MAKEINTRESOURCE(IDS_TITLE1);
psp.pszHeaderSubTitle = MAKEINTRESOURCE(IDS_SUBTITLE1);
psp.pszTemplate       = MAKEINTRESOURCE(IDD_INTERIOR1);
psp.pfnDlgProc        = IntPage1DlgProc;

ahpsp[1] = CreatePropertySheetPage(&psp);

Vlastní data stránky

Když vytváříte stránku, můžete k ní přiřadit vlastní data pomocí člena lParam ve struktuře PROPSHEETPAGE, a to obvykle přiřazením ukazatele na uživatelsky definovanou strukturu.

Při prvním výběru stránky obdrží procedura dialogového okna zprávu WM_INITDIALOG. Hodnota lParam zprávy odkazuje na kopii struktury PROPSHEETPAGE stránky, ze které můžete načíst vlastní data. Tato data pak můžete uložit pro použití v dalších zprávách pomocí SetWindowLongPtr s GWL_USERDATA jako parametr indexu. Více stránek může mít ukazatel na stejná data a všechny změny dat provedených jednou stránkou jsou k dispozici pro ostatní stránky v jejich dialogových postupech.

Definování seznamu vlastností Průvodce

Stejně jako u běžných seznamů vlastností definujete seznam vlastností průvodce vyplněním členů PROPSHEETHEADER struktury. Tato struktura umožňuje určit stránky, které tvoří průvodce, a výchozí pořadí, ve kterém jsou zobrazeny, spolu s několika souvisejícími parametry. Průvodce pak spustíte voláním funkce PropertySheet.

Ve stylu Wizard97 je pszCaption člen PROPSHEETHEADER struktura ignorována. Místo toho průvodce zobrazí titulek zadaný v šabloně dialogového okna aktuální stránky. Pokud šablona nemá titulek, zobrazí se titulek z předchozí stránky. Chcete-li tedy zobrazit stejný titulek na všech stránkách, zadejte titulek v šabloně úvodní stránky.

Ve stylu Průvodce Aero je titulek dialogového okna převzat z pszCaption.

Pokud jste pro své stránky vytvořili pole popisovačů HPROPSHEETPAGE, přiřaďte pole členu struktury phpage. Pokud jste místo toho vytvořili pole struktury PROPSHEETPAGE, přiřaďte pole ppsp členu a nastavte příznak PSH_PROPSHEETPAGE v dwFlags členu.

Následující příklad přiřadí hodnoty psh, do struktury PROPSHEETHEADER a zavolá funkci PropertySheet ke spuštění průvodce. Průvodce ve stylu Wizard97 má grafiku vodoznaku i záhlaví, specifikovanou jejich ID prostředků. Pole ahpsp obsahuje všechny úchyty HPROPSHEETPAGE a definuje výchozí pořadí, ve kterém jsou zobrazeny.

// g_hInstance is the global HINSTANCE of the application.
// ahpsp is an array of HPROPSHEETPAGE handles.

PROPSHEETHEADER psh = { sizeof(psh) };

psh.hInstance      = g_hInstance;
psh.hwndParent     = NULL;
psh.phpage         = ahpsp;
psh.dwFlags        = PSH_WIZARD97 | PSH_WATERMARK | PSH_HEADER;
psh.pszbmWatermark = MAKEINTRESOURCE(IDB_WATERMARK);
psh.pszbmHeader    = MAKEINTRESOURCE(IDB_BANNER);
psh.nStartPage     = 0;
psh.nPages         = 4;

PropertySheet(&psh);

Procedura dialogového okna

Každá stránka průvodce potřebuje proceduru dialogového okna pro zpracování zpráv systému Windows, zejména oznámení z jeho ovládacích prvků a průvodce. Tři zprávy, které musí být téměř všichni průvodci schopni zpracovat, jsou WM_INITDIALOG, WM_DESTROYa WM_NOTIFY.

Zpráva WM_NOTIFY se přijme před zobrazením stránky a po kliknutí na některá z tlačítek průvodce. Parametr lParam zprávy je ukazatel na strukturu hlaviček NMHDR. ID oznámení je obsaženo ve členu kódu struktury. Čtyři oznámení, která většina průvodců potřebuje zpracovat, jsou následující.

Kód	Popis
PSN_SETACTIVE	Odesláno před zobrazením stránky.
PSN_WIZBACK	Odesláno po kliknutí na tlačítko Zpět.
PSN_WIZNEXT	Odesláno po kliknutí na tlačítko Další.
PSN_WIZFINISH	Odesláno po kliknutí na tlačítko Dokončit.

 

Zpracování WM_INITDIALOG a WM_DESTROY

Když se stránka bude zobrazovat poprvé, její dialogové okno zobrazí zprávu WM_INITDIALOG. Zpracování této zprávy umožňuje průvodci provádět všechny potřebné úlohy inicializace, jako je ukládání vlastních dat nebo nastavení písem.

Když je zničena karta vlastností, obdržíte zprávu WM_DESTROY. Průvodce je systémem automaticky zničen, ale zpracování této zprávy umožňuje provést potřebné vyčištění.

Manipulátor PSN_SETACTIVE

Kód oznámení PSN_SETACTIVE se odešle při každém okamžiku, kdy se chystá stránka být zobrazena. Při první návštěvě stránky následuje PSN_SETACTIVE zprávu WM_INITDIALOG. Pokud je stránka následně znovu zobrazena, obdrží pouze oznámení PSN_SETACTIVE. Toto oznámení se obvykle zpracovává za účelem inicializace dat pro stránku a povolení příslušných tlačítek.

Ve výchozím nastavení průvodce zobrazí tlačítka Zpět, Dalšía Zrušit se všemi tlačítky povolenými. Pokud chcete zakázat tlačítko nebo zobrazit Dokončit místo Další, musíte odeslat PSM_SETWIZBUTTONS zprávu. Po odeslání této zprávy se stav tlačítek zachová, dokud ji nezmění jiná PSM_SETWIZBUTTONS zpráva, a to i v případě, že je vybrána nová stránka. Obvykle všechny obslužné rutiny PSN_SETACTIVE odesílají tuto zprávu, aby se zajistilo, že každá stránka má správný stav tlačítka.

Stav tlačítka s touto zprávou můžete kdykoli změnit. Můžete například chtít, aby se tlačítko Další na začátku zakázalo. Jakmile uživatel zadá všechny potřebné informace, můžete odeslat další PSM_SETWIZBUTTONS zprávu, která povolí tlačítko Další a umožní uživateli přejít na další stránku.

Následující fragment kódu používá makro PropSheet_SetWizButtons k povolení tlačítek Zpět a Další na vnitřní stránce před jejím zobrazením.

case WM_NOTIFY :
    {
        LPNMHDR pnmh = (LPNMHDR)lParam;
        
        switch(pnmh->code)
        {
        
        ...
        
        case PSN_SETACTIVE :
        
            ...
            
            // This is an interior page.
            PropSheet_SetWizButtons(hwnd, PSWIZB_NEXT | PSWIZB_BACK);
            
            ...
        }
    ...
    
    }

Zpracování PSN_WIZNEXT, PSNWIZBACK a PSN_WIZFINISH

Po kliknutí na tlačítko Další nebo Zpět obdržíte kód oznámení PSN_WIZNEXT nebo PSN_WIZBACK. Ve výchozím nastavení průvodce automaticky přejde na další nebo předchozí stránku v pořadí definovaném při vytvoření seznamu vlastností. Běžným důvodem pro zpracování těchto oznámení je zabránit uživateli v přepínání stránek nebo přepsání výchozího pořadí stránek.

Chcete-li zabránit uživateli v přepínání stránek, zpracujte oznámení tlačítka, volejte funkci SetWindowLong s hodnotou DWL_MSGRESULT nastavenou na -1 a vraťte TRUE. Například:

case PSN_WIZNEXT :

        ...
        
        // Do not go to the next page yet.
        SetWindowLong(hwnd, DWL_MSGRESULT, -1);
        
        return TRUE;
        
        ...

Chcete-li přepsat standardní pořadí a přejít na konkrétní stránku, zavolejte SetWindowLong s hodnotou DWL_MSGRESULT nastavenou na ID prostředku dialogového okna dané stránky a vraťte TRUE. Například:

case PSN_WIZNEXT :

        ...
        
        // Go straight to the completion page.
        SetWindowLong(hwnd, DWL_MSGRESULT, IDD_FINISH);
        
        return TRUE;
        
        ...

Po kliknutí na tlačítko Dokončit nebo Zrušit obdržíte PSN_WIZFINISH nebo PSN_RESET kód oznámení. Když kliknete na některé z těchto tlačítek, systém automaticky zničí průvodce. Tato oznámení však můžete zpracovat, pokud potřebujete před zničením průvodce provádět úlohy čištění. Chcete-li zabránit zničení průvodce při obdržení oznámení PSN_WIZFINISH, zavolejte SetWindowLong s hodnotou DWL_MSGRESULT nastavenou na TRUE, a vraťte TRUE. Například:

case PSN_WIZFINISH :

        ...
        
        // Not finished yet.
        SetWindowLong(hwnd, DWL_MSGRESULT, TRUE);
        
        return TRUE;
        
        ...

Zpětně kompatibilní průvodci

Předchozí část předpokládá, že implementujete průvodce pro systém s verze 5 nebo novějšími běžnými ovládacími prvky.

Pokud píšete průvodce pro systémy se staršími verzemi běžných ovládacích prvků, nebude mnoho funkcí probíraných v předchozí části k dispozici. Některé členy struktur PROPSHEETHEADER a PROPSHEETPAGE, které používá styl Wizard97, jsou podporovány pouze společnými ovládacími prvky ve verzi 5 a novějších. Přesto je však možné implementovat zpětně kompatibilního průvodce s podobným vzhledem jako ve stylu Wizard97. Pokud to chcete provést, musíte explicitně implementovat následující:

• Přidejte obrázek vodoznaku do šablony dialogového okna pro úvodní a doplňovací stránky.
• Nastavte všechny šablony tak, aby byly stejné velikosti. Pro vnitřní stránky neexistuje žádná samostatná systémově definovaná oblast záhlaví.
• V šablonách můžete explicitně vytvořit oblast záhlaví vnitřní stránky.
• Nepoužívejte grafiku záhlaví, protože může být v konfliktu s názvem nebo podnadpisem, pokud průvodce změní velikost.

Další informace o průvodcích, které jsou zpětně kompatibilní, naleznete v tématu Zpětně kompatibilní průvodce 97.

Poznámky

Pro úplnou diskusi o problémech s návrhem pro Průvodce97 viz specifikaci Wizard97, která je k dispozici jinde v sadě Windows SDK. Tento dokument obsahuje pokyny pro takové věci, jako jsou rozměry dialogových oken, rastrové rozměry a barvy a umístění ovládacích prvků.

Související témata

použití seznamů vlastností

ukázka běžných ovládacích prvků Windows (CppWindowsCommonControls)