Varázslók létrehozása

A varázsló olyan tulajdonságlaptípus, amely egyszerű és hatékony módszert kínál a felhasználók számára egy eljárás végigvezetésére.

A varázslók a felhasználói élmény egyszerűsítésének egyik kulcsai. Lehetővé teszik, hogy összetett műveletet hajtson végre, például egy alkalmazás konfigurációját, és egyszerű lépések sorozatára bontsa azt. A folyamat minden pontján megadhatja a szükséges információkat, és megjelenítheti azokat a vezérlőket, amelyek lehetővé teszik a felhasználó számára a kijelöléseket és a szöveg beírását.

A varázsló valójában egy tulajdonságlaptípus. A tulajdonságlap lényegében egy tároló lapokgyűjteménye számára, ahol minden lap egy önálló párbeszédpanel. Míg a normál tulajdonságlapok lehetővé teszik, hogy a felhasználó bármikor hozzáférjen bármelyik laphoz, a varázslók egymás után jelenítik meg a lapokat. A tabulátorok helyett a gombok segítségével navigálhat előre és hátra. A lapok megjelenítésének sorrendjét az alkalmazás szabályozza, és a felhasználói bevitel alapján módosítható.

A varázslónak két fő stílusa van: a régebbi Wizard97 stílus és a Windows Vista rendszerben bevezetett Aero stílus. Az ábrákért lásd A tulajdonságlapokcímű témakört. (A harmadik stílus, amely csak a PSH_WIZARD vagy PSH_WIZARD_LITE jelzőt használja, egyszerű tulajdonságlapok sorozatát mutatja be fejlécek és vízjelek nélkül.)

A dokumentum nagy részének tárgyalása feltételezi, hogy a közös vezérlők 5.80-as vagy újabb verziójával rendelkező rendszer varázslóját implementálja. Ha a wizard97 stílust a közös vezérlők korábbi verzióival próbálja használni, előfordulhat, hogy az alkalmazás lefordítja, de nem jelenik meg megfelelően. A varázsló97-kompatibilis varázsló korábbi rendszereken való létrehozásáról a jelen témakör későbbi, Visszamenőlegesen kompatibilis varázslói című szakaszában olvashat.

Amit tudnia kell

Technológiák

• Windows-vezérlők

Előfeltételek

• C/C++
• Windows felhasználói felület programozása

Előírás

Varázsló implementációja

A varázsló implementálása hasonló a normál tulajdonságlap implementálásához. A legalapvetőbb szinten a tulajdonságlapot meghatározó PROPSHEETHEADER struktúrában az alábbi jelölők vagy jelölőkombinációk egyikét kell beállítani.

A varázsló implementálásának alapvető eljárása a következő:

1. Hozzon létre egy párbeszédpanelsablont az egyes lapokhoz.
2. A lapok definiálásához hozzon létre egy PROPSHEETPAGE struktúrát az egyes lapokhoz. Ez a struktúra határozza meg a lapot, és a párbeszédpanel-sablonra mutató mutatókat, valamint bitképeket vagy egyéb erőforrásokat tartalmaz.
3. Adja át az előző lépésben létrehozott PROPSHEETPAGE struktúrát a CreatePropertySheetPage függvénynek a lap HPROPSHEETPAGE leírójának létrehozásához.
4. A varázsló definiálásához hozzon létre egy PROPSHEETHEADER struktúrát.
5. A varázsló megjelenítéséhez adja át a PROPSHEETHEADER struktúrát a PropertySheet függvénynek.
6. Az egyes lapok párbeszédpanel-eljárásainak implementálása az oldal vezérlőinek és a varázsló gombjainak értesítési üzeneteinek kezelésére, valamint a Windows egyéb üzenetkezelésének feldolgozására.

A párbeszédpanelsablonok létrehozása

A varázslólapnak két alapvető típusa van: külső és belső. A külső oldalak a bevezetési (üdvözlő) és a befejezési oldalak. Minden további oldal belső.

Külső lap párbeszédpanelsablonjai

A bevezetési és befejezési lapok alapszintű elrendezése megegyezik. Az alábbi ábrán egy "Wizard97" minta bevezetőoldal látható helyőrző vízjellel.

A Wizard97 külső oldalai esetében a párbeszédpanel-sablon 317x193 párbeszédegység. Kitölti az összes varázslót, kivéve a feliratot és az alsó sávot, amely tartalmazza a Back, Nextés Mégse gombot. A sablon bal oldala, amely el van különítve egy "vízjel" bitkép számára, nem tartalmazhat vezérlőket. A vízjel a varázsló PROPSHEETHEADER szerkezetében van megadva, és automatikusan hozzá lesz adva a laphoz. Az erőforrássablon tervezésekor helyet kell hagynia a számára.

A vízjel bitképének létrehozásakor vegye figyelembe, hogy a párbeszédpanel mérete növekedhet, ha például a felhasználó nagy rendszer betűtípust választ. A különböző nyelvek általában eltérő betűmetrikákkal rendelkeznek. Amikor az oldal növekszik, a vízjel számára fenntartott terület arányosan nagyobb lesz. A vízjel bitképét azonban nem módosíthatja, és a nagyobb terület kitöltéséhez sem nyújtja a bitképet. Ehelyett a bitkép eredeti méretében marad a fenntartott terület bal felső részén. A vízjel által nem lefedett nagyobb fenntartott terület része automatikusan megtelik a bitkép bal felső képpontjának színével.

Ha különböző méretű vízjel bitképekkel kell rendelkeznie a különböző betűmetrikákhoz, két lehetséges megoldás lehet:

• A varázsló létrehozása előtt kérje le a betűmetrikákat, és adjon meg egy megfelelő méretű vízjel bitképet.
• A varázsló létrehozásakor ne adjon meg vízjel bitképet. A Wizard97 üresen hagyja a vízjel területét. Ezután rajzoljon egy megfelelő méretű bitképet a vízjel számára fenntartott területre.

A vezérlőket a vízjel jobb oldalán helyezheti el, ahogyan egy normál párbeszédpanel esetében tenné. Ennek a területnek a háttérszínét a rendszer határozza meg, és nem igényel semmilyen műveletet. Általában két statikus vezérlőt helyez el ezen a területen. A felső tartalmazza a címet, és nagy félkövér betűtípust használ (12 pontos Verdana Bold for Wizard97). A másik, amely magyarázó szöveg, a szokásos párbeszédpanel betűtípust használja.

A bevezető és a befejező oldalak között a fő különbség a varázslógombok és a statikus vezérlők szövege. A bevezető lapok általában egy Next és egy Back gombbal rendelkeznek, és csak a Tovább gomb van engedélyezve. A befejezési oldalakon engedélyezve van a Vissza gomb, a Következő gombot pedig egy Befejezés gomb váltja fel.

A Befejezés gomb szövegét úgy módosíthatja, hogy PSM_SETFINISHTEXT üzenetet küld a varázslónak. Alapértelmezés szerint a Befejezés gomb nem tartalmaz billentyűzetgyorsítót. A billentyűzetgyorsító definiálásához adjon meg egy és-jelet a PSM_SETFINISHTEXT szövegében. A "&Finish" kifejezés például az "F" billentyűt határozza meg gyorsbillentyűként.

belső oldal párbeszédpanel-sablonjai

A belső oldalak megjelenése némileg eltér a külső lapoktól. Az alábbi ábrán egy minta Wizard97 belső oldal látható helyőrző fejlécbitképével.

A lap tetején található fejlécterületet a tulajdonságlap kezeli, így az nem szerepel a sablonban. A fejléc tartalma a lap PROPSHEETPAGE szerkezetében, valamint a varázsló PROPSHEETHEADER szerkezetében van megadva. Mivel a belső oldalnak el kell férnie a fejléc és a gombok között, a Wizard97 párbeszédpanelsablon 317x143 párbeszédpanel-egység, valamivel kisebb, mint a külső lapok sablonja.

Az alábbi ábrán egy Aero varázsló látható, amely ugyanabból a sablonból lett létrehozva.

A varázsló lapjainak definiálása

Miután létrehozta a párbeszédpanelsablonokat és a kapcsolódó erőforrásokat, például bitképeket és sztringtáblákat, létrehozhatja a tulajdonságlaplapokat. Az eljárás hasonló a standard tulajdonságlapokhoz. Először adja meg a PROPSHEETPAGE struktúrájának megfelelő tagjait. (Egyes tagok kifejezetten a varázslókra vonatkoznak.) Ezután hívja meg a CreatePropertySheetPage függvényt a lap HPROPSHEETPAGE kezelőjének létrehozásához.

A varázslóval kapcsolatos következő jelölők beállíthatók a PROPSHEETPAGE struktúrában található dwFlags tagban.

Ha beállította a PSP_USEHEADERTITLE vagy a PSP_USEHEADERSUBTITLE, rendelje hozzá a címet és a felirat szövegét a pszHeaderTitle és pszHeaderSubtitle tagokhoz. Ha a PROPSHEETPAGE és PROPSHEETHEADER struktúrák tagjaihoz rendel szöveges sztringeket, hozzárendelhet egy sztringmutatót, vagy a MAKEINTRESOURCE makróval hozzárendelhet egy értéket egy sztringerőforrásból. A szövegerőforrás a varázsló hInstance tagjában található modulból töltődik be a PROPSHEETHEADER struktúrában.

Amikor meghívja CreatePropertySheetPage egy lap létrehozásához, rendelje hozzá az eredményt a HPROPSHEETPAGE-leírók tömbjének egyik eleméhez. Ez a tömb a tulajdonságlap létrehozásakor használatos. A lap leírójának tömbindexe határozza meg a megjelenítés alapértelmezett sorrendjét. Miután létrehozta a lap HPROPSHEETPAGE leíróját, ugyanazt a PROPSHEETPAGE struktúrát használhatja fel a következő lap létrehozásához új értékek hozzárendelésével a megfelelő tagokhoz.

A lapok létrehozásának másik módja, ha külön PROPSHEETPAGE struktúrákat használnak az egyes lapokhoz, és létrehoznak egy struktúrákból álló tömböt. Ez a tömb a HPROPSHEETPAGE leírók tömbje helyett használatos a tulajdonságlap létrehozásakor. Ha különálló PROPSHEETPAGE struktúrákat használ, nem szükséges meghívni CreatePropertySheetPage, de több memóriát használ. Ellenkező esetben nincs jelentős különbség a két megközelítés között.

Az alábbi példa egy belső Wizard97 lapot határoz meg azáltal, hogy értékeket rendel hozzá egy PROPSHEETPAGE struktúrához. Ebben a példában a lap címét, alcímét és párbeszédpanel-sablonját az erőforrásazonosítók azonosítják. A CreatePropertySheetPage függvény meghívásra kerül, hogy létrehozza a lap HPROPSHEETPAGE leíróját. Mivel ez lesz a második megjelenítendő oldal, a fogópont a fogópontok tömbjének lesz hozzárendelve, ahpsp, 1 indexkel.

// 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);

Egyéni oldaladatok

Amikor létrehoz egy lapot, az lParamPROPSHEETPAGE struktúra tagjának használatával rendelhet hozzá egyéni adatokat, általában úgy, hogy egy mutatót rendel hozzá egy felhasználó által definiált struktúrához.

A lap első kijelölésekor a párbeszédpanel eljárása egy WM_INITDIALOG üzenetet kap. Az üzenet lParam értéke a lap PROPSHEETPAGE szerkezetének másolatára mutat, amelyből lekérheti az egyéni adatokat. Ezeket az adatokat ezután a következő üzenetekhez tárolhatja azáltal, hogy SetWindowLongPtr parancsot használja az index paraméterként megadott GWL_USERDATA-val. Több oldal is rendelkezhet ugyanahhoz az adathoz mutató mutatóval, és az egyik oldal adatainak bármilyen módosítása elérhető a többi lap számára a párbeszédpanel-eljárásaikban.

A varázsló tulajdonságlapjának definiálása

A szokásos tulajdonságlapokhoz hasonlóan a varázsló tulajdonságlapját is egy PROPSHEETHEADER szerkezet tagjainak kitöltésével határozhatja meg. Ez a struktúra lehetővé teszi a varázslót alkotó lapok és az alapértelmezett megjelenítési sorrend megadását, valamint számos kapcsolódó paramétert. Ezután indítsa el a varázslót a PropertySheet függvény meghívásával.

A Varázsló97 stílusban a PROPSHEETHEADER struktúrájának pszCaption tagja figyelmen kívül lesz hagyva. Ehelyett a varázsló megjeleníti az aktuális lap párbeszédpanelsablonjában megadott feliratot. Ha a sablon nem tartalmaz feliratot, az előző oldal felirata jelenik meg. Így ha minden oldalon ugyanazt a feliratot szeretné megjeleníteni, adja meg a bevezető oldal sablonjában lévő feliratot.

Az Aero varázsló stílusában a párbeszédpanel felirata pszCaption.

Ha létrehozott egy HPROPSHEETPAGE-leírókból álló tömböt a lapokhoz, rendelje hozzá a tömböt a phpage taghoz. Ha ehelyett PROPSHEETPAGE struktúrákból álló tömböt hozott létre, rendelje hozzá a tömböt a ppsp taghoz, és állítsa be a PSH_PROPSHEETPAGE jelölőt a dwFlags tagban.

Az alábbi példa értékeket rendel psh, PROPSHEETHEADER struktúrához, és meghívja a PropertySheet függvényt a varázsló elindításához. A Wizard97-stílusú varázsló vízjelet és fejlécgrafikát is tartalmaz, amelyeket erőforrásazonosítóik alapján adnak meg. A ahpsp tömb tartalmazza az összes HPROPSHEETPAGE leírót, és meghatározza az alapértelmezett sorrendet, amelyben azok megjelennek.

// 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);

A párbeszédpanel eljárása

A varázsló minden oldalának párbeszédpaneles eljárásra van szüksége a Windows-üzenetek feldolgozásához, különösen a vezérlőktől és a varázslótól érkező értesítésekhez. A három üzenet, amelyet szinte minden varázslónak kezelnie kell, WM_INITDIALOG, WM_DESTROYés WM_NOTIFY.

A WM_NOTIFY üzenet a lap megjelenése és a varázsló bármelyik gombjának kattintása előtt érkezik. Az üzenet lParam paramétere egy NMHDR fejlécstruktúrára mutató mutató. Az értesítés azonosítóját a struktúra kód tag tartalmazza. A legtöbb varázsló által kezelt négy értesítés a következő.

WM_INITDIALOG és WM_DESTROY kezelése

Amikor egy lap első alkalommal jelenik meg, a párbeszédpanel eljárása egy WM_INITDIALOG üzenetet kap. Az üzenet kezelése lehetővé teszi, hogy a varázsló végrehajtsa a szükséges inicializálási feladatokat, például az egyéni adatok tárolását vagy a betűtípusok beállítását.

Ha a tulajdonságlap megsemmisül, egy WM_DESTROY üzenetet kap. A rendszer automatikusan megsemmisíti a varázslót, de az üzenet kezelése lehetővé teszi a szükséges törlést.

PSN_SETACTIVE kezelése

A PSN_SETACTIVE értesítési kód minden alkalommal el lesz küldve, amikor egy oldal láthatóvá válik. A lap első megnyitásakor PSN_SETACTIVE a WM_INITDIALOG üzenetet követi. Ha a lapot később újra meg kell látogatni, csak PSN_SETACTIVE értesítést kap. Ezt az értesítést általában az oldal adatainak inicializálására és a megfelelő gombok engedélyezésére kezelik.

Alapértelmezés szerint a varázsló megjeleníti Vissza, Következőés Mégse gombot, és az összes gomb engedélyezve van. Ha le szeretne tiltani egy gombot, vagy Befejezés szeretne megjeleníteni a Következő helyett, PSM_SETWIZBUTTONS üzenetet kell küldenie. Az üzenet elküldése után a gombok állapota megmarad, amíg egy másik PSM_SETWIZBUTTONS üzenet nem módosítja, még akkor is, ha új lap van kijelölve. Általában minden PSN_SETACTIVE kezelő elküldi ezt az üzenetet, hogy minden oldal megfelelő gombállapotú legyen.

Ezzel az üzenettel bármikor módosíthatja a gomb állapotát. Előfordulhat például, hogy a Következő gomb kezdetben le van tiltva. Miután egy felhasználó megadta az összes szükséges információt, elküldhet egy másik PSM_SETWIZBUTTONS üzenetet, amely engedélyezi a Tovább gombot, és hagyja, hogy a felhasználó továbblépjen a következő oldalra.

Az alábbi kódrészlet a PropSheet_SetWizButtons makróval engedélyezi a Vissza és Következő gombot egy belső oldalon a megjelenítés előtt.

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

PSN_WIZNEXT, PSNWIZBACK és PSN_WIZFINISH kezelése

Ha egy Következő vagy Vissza gombra kattint, PSN_WIZNEXT vagy PSN_WIZBACK értesítési kódot kap. Alapértelmezés szerint a varázsló automatikusan a következő vagy az előző lapra kerül a tulajdonságlap létrehozásakor megadott sorrendben. Az értesítések kezelésének gyakori oka, hogy a felhasználó nem válthat oldalakat, vagy felülbírálhatja az alapértelmezett oldalsorrendet.

Ha meg szeretné akadályozni, hogy a felhasználó oldalakat váltson, kezelje a gombértesítést, hívja meg a SetWindowLong függvényt a DWL_MSGRESULT érték -1 értékre állításával, és adja vissza IGAZ. Például:

case PSN_WIZNEXT :

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

Ha felül kívánja írni a szokásos sorrendet, és egy adott oldalra szeretne lépni, hívja meg a SetWindowLong függvényt, a DWL_MSGRESULT értékét állítsa az oldal párbeszédpanel-erőforrás-azonosítójára, és adja vissza a TRUEértéket. Például:

case PSN_WIZNEXT :

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

Ha a Befejezés vagy Mégse gombra kattint, PSN_WIZFINISH vagy PSN_RESET értesítési kódot kap. Ha ezekre a gombokra kattint, a rendszer automatikusan megsemmisíti a varázslót. Ezeket az értesítéseket azonban akkor is kezelheti, ha el kell végeznie a tisztítási feladatokat a varázsló megsemmisítése előtt. Ha meg akarja akadályozni, hogy a varázsló a PSN_WIZFINISH értesítés érkezésekor megsemmisüljön, hívja meg a SetWindowLong függvényt úgy, hogy a DWL_MSGRESULT értéke IGAZlegyen, majd adja vissza IGAZértéket. Például:

case PSN_WIZFINISH :

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

Visszamenőlegesen kompatibilis varázslók

Az előző szakasz feltételezi, hogy a gyakori vezérlők 5- vagy újabb verziójával rendelkező rendszer varázslóját implementálja.

Ha varázslót ír a közös vezérlők korábbi verzióival rendelkező rendszerekhez, az előző szakaszban tárgyalt számos funkció nem lesz elérhető. A PROPSHEETHEADER és a PROPSHEETPAGE struktúrák több tagját, amelyeket a Varázsló97 stílus használ, csak az 5-ös verziójú és annál újabb általános vezérlők támogatják. Azonban továbbra is implementálható egy visszamenőlegesen kompatibilis varázsló a varázsló97 stílusához hasonló megjelenéssel. Ehhez kifejezetten a következőket kell implementálnia:

• Adja hozzá a vízjel ábráját a bevezetési és befejezési lapok párbeszédpanelsablonjához.
• Az összes sablont azonos méretűre alakíthatja. A belső oldalakhoz nincs külön rendszer által definiált fejlécterület.
• Hozza létre a belső oldal fejlécterületét kifejezetten a sablonokon.
• Ne használjon fejlécgrafikát, mivel a varázsló mérete változik, ez ütközhet a címmel vagy az alcímmel.

A visszamenőlegesen kompatibilis varázslókról a Visszamenőlegesen kompatibilis varázsló 97című témakörben olvashat bővebben.

Megjegyzések

A Wizard97 tervezési problémáinak teljes körű ismertetését a Wizard97 Specificationcímű témakörben találja, a Windows SDK más részein. Ez a dokumentum útmutatást biztosít az olyan dolgokhoz, mint a párbeszédpanelek méretei, a bitkép méretei és színei, valamint a vezérlők elhelyezése.

Kapcsolódó témakörök

Tulajdonságlapok használata

Windows általános vezérlők bemutatója (CppWindowsCommonControls)