About Property Sheets

                                                                                                                PropertySheet介绍

         综述：propertySheet窗口允许你们编辑其中单元的属性。举个自己就是电子表格，它允许用户编辑单元的字体和边框，查看和设置设备的属性。例如驱动器设置、打印或鼠标

         目录：

                   PropertySheet基础

                   PropertySheet对话框

                   Pages

                   创建PropertySheet

                   添加删除Pages

                   PropertySheet标题和页标签

                   页激活

                   帮助Button

                   OK，Cancel和Apply 按钮

                   Wizards（向导）

一、PropertySheet基础

                   需要PropertySheet的程序，包含Prsh.h头文件，Prsh.h包含PropertySheet用到的所有变量。

                   一个PropertyShett包含一个或多个重叠的子窗口，称为Page。每个页。例如，一个页能包含一个设置字体设置的控件，包括类型风格，点大小

                   ，颜色等等。例如Date-Time控件面板程序，在Xp中显示如下的界面。一个标准的PropertySheet带有多个选项卡式，允许用户动态的访问所有属性。

                   如果属性的设置有顺序，那么适合使用wizard。

二、PropertySheetDialogBox

         PropertySheet以及其包含的page实际上是对话框。PropertySheet是系统定义的对话框，它管理页面并且提供一个通用的控件的容器。一个PropertySheet对话框能是模态的或者非模态的。它包含frame,标题栏和四个按钮：OK，Cancel，Apply和Help。一个对话框的页面处理函数接受WM_NOTIFY形式的消息，当用户单击按钮。

         注意：这里所说的信息并不都适用于Wizard型，Wizard在表现和行为上有些不同。例如，Wizard有不同的按钮集合并且没有属性页。更多信息查看Creating Wizards。

         在PropertySheet中的每一个Page都是应用定义的非模态对话框，PropertySheet管理这些控件窗口（查看和编辑项的属性)。使用对话框模板创建每一个Page，并且对话框处理函数管理控件和设置相关项目的属性。

         PropertySheet发送通知代码到每一个对话框处理函数，当page正在获得或者失去激活状态，或者单击OK、Cancel、Apply或者Help按钮。通知消息以WM_NOTIFY的形式被发送出来。lParam参数是NMHDR结构的地址（这个结构包含PropertySheet对话框的窗口句柄）。

         一些通知代码需要一个页面返回TRUE和FALSE，在相应的WM_NOTIFY消息中。做到这些，页面必须使用SetWindowLong为对话框设置DWL_MSGRESULT消息，或者是TRUE或者是FALSE。

三、Pages

         一个PropertySheet必须至少包含一个Page，但是不能大于MAXPROPPAGES中定义的值（WindowsHeader.h中）。每一个页面都包含一个以0开头的索引，这个索引的生成是基于PropertySheet添加页面的顺序。索引主要用在消息中（用来消息发送到PropertySheet）。

         一个属性页面能包含一个嵌套对话框，如果这样做，你必须在顶层对话框中包含WS_EX_CONTROLPARENT风格，并且调用IsDialogMessage函数到父对话框。这个确保用户能使用记忆和对话框导航键来移动焦点到嵌套的对话框中的控件上。

         每一个Page有一个图标和标签。PropertySheet为每个Page创建标签，并且显示图标和标签。所有的PropertySheet页面被期望为非加粗字体。确认字体一定不能使加粗的，同时在对话框模板中指定DS_3DLOOK风格。

         每一个对话框处理函数必须不能调用EndDialog函数。因为这样做会破坏整个PropertySheet，而不仅仅是Page。

         PropertySheet的Page的最小值是水平212对话框单元、垂直114对话框单元。如果最小值达不到这个要求，那么该Page将被自动扩大至最小值。Prsht.h头文件包含3个推举的PropertySheet的大小值。如下：

                   PROP_SM_CXDLG   Width, in dialog units, of a small propertysheet page.

                   PROP_SM_CYDLG   Height, in dialog units, of a small propertysheet page.

                   PROP_MED_CXDLG         Width, in dialog units, of amedium-sized property sheet page.

                   PROP_MED_CYDLG         Height, in dialog units, of amedium-sized property sheet page.

                   PROP_LG_CXDLG    Width, in dialog units, of a large propertysheet page.

                   PROP_LG_CYDLG    Height, in dialog units, of a large propertysheet page.

         使用推举大小，可以保证同其他Microsoft应用程序外观的一致性。在微软的资源编辑器中，你可以通过Add Resource对话框，创建一个适合大小的Page。扩展对话框节点，选择IDD_PROPPAGE_LARGE, IDD_PROPPAGE_MEDIUM, or IDD_PROPPAGE_SMALL。

         PropertySheet将自动被调整为适合大页面。

四、PropertySheet Creation

                   在创建PropertySheet之前，必须定义一个或多个Page。创建Page需要填充PROPSHEETPAGE结构，需要填充的信息包括图标、标签、对话框模板、对话框处理函数等等。然后将PROPSHEETPAGE结构的地址传递给CreatePropertySheetPage（）函数。这个函数返回HPROPSHEETPAGE句柄，该句柄唯一标识每一个Page。

                   创建PropertySheet，将PROPSHEETHEADER结构的地址传递给PropertySheet（）函数。PROPSHEETHEADER结构包含PropertySheet的标题和图标，同时包括一个HPROPSHEETPAGE句柄数组（从CreatePropertySheetPage获得）

。使用PropertySheet()函数创建PropertySheet的时候，也会同时创建内部的Page。这些Page的顺序根据HPROPSHEETPAGE数组中的顺序决定。

                   另外一种给PropertySheet添加Page的方法是指定一个PROPSHEETPAGE数组，而不是HPROPSHEETPAGE句柄数组。在这种情况下，PropertySheet（）函数将会自动为每个页面创建句柄，然后加入PropertySheet。

                   注释：每个Page创建PROPSHEETPAGE结构，然后存入PROPSHEETHEADER结构中。再使用PropertySheet()创建PropertySheet。PROPSHEETHEADER提供了两种加入也的方法即PROPSHEETPAGE结构法和HPROPSHEETPAGE句柄法。关键在PROPSHEETHEADER结构中，这两个是共同体。

                   当一个Page被创建后，PropertySheet的对话框处理函数会收到WM_INITDIALOG消息。消息的lParam参数是一个指向PROPSHEETPAGE结构拷贝的指针，该结构是刚才创建的页面的信息。        在特殊情况下，当页面创建时，lParam结构能传递应用定义的信息给对话框处理函数。作为lParam的这种特殊情况，lParam必须被处理为只读模式，任何对lParam指定信息的编辑，将导致不可预知的结果。

         当系统后续给你传递一个Page的PROPSHEETPAGE结构的拷贝时，它将使用相同的指针。任何针对该结构的更改将会传递。因为lParam会被系统忽略，所以lParam能被修改并给程序的其他部分传递信息。例如，使用lParam给Page的PropSheetPageProc回调函数传递消息。

                   （关于页面初始大小问题）

         PropertySheet函数能自动设置PropertySheet的大小和位置。该位置是基于父窗口的坐标系。该大小是基于Page数组中最大的Page的大小。如果你想让Page的宽度匹配PropertySheet底部四个按钮的宽度，那么设置最宽页面的宽度为190对话框单位（dialog units）。

         PropertySheet的大小是由PropertySheet对话框模板资源中的width和height两者计算而来的。更详细的信息参见DIALOG Resource 或者 DIALOGEX Resource。注意，出于兼容性的考虑，被计算的尺寸是基于MS Shell Dialog字体，而不是用户对话框中使用的字体。如果你设计的页面中使用到了其他字体，那么一下建议是可以参考的。

1.      调整对话框模板的尺寸，补偿MS Shell Dialog字体到页面实际字体的差别。例如选择两倍于MS Shell Dialog的字体，将对话框模板设置为平时的两倍。

2.      如果在Win2000以及以后的系统上运行，你可以使用DIALOGEX模板并且设置DS_SHELLFONT对话框样式，这种情况下，PropertySheet管理者解释根据对话框模板使用的字体来解释对话框的尺寸。

五、    Adding and Removing Pages

         在PropertySheet创建后，可以通过发送PSM_ADDPAGE消息，在已有Page的后面添加Page。通过发送PSM_INSERTPAGE消息，可以在已有的Page中间添加Page。注意，PropertySheet创建后，其大小将不能改变。任何新添加的Page的大小不能大于已经存在的最大Page。发送PSM_REMOVE消息，删除已有页面。

         当你定义一个页面的时候，你需要指定PropSheetPageProc()回调函数的地址。这个函数会在页面创建和删除时被PropertySheet调用。这个回调函数能提供给每一个页面一个初始化和清理的机会。

         注意：当PropertySheet维护Page列表时，一些消息和一个函数调用会发生。当这种情况发生时，试图修改Page列表的行为将导致不可预期的结果。所以，在你的PropSheetPageProc()实现中不要添加、删除或插入Page，或者处理以下Windows消息和通知消息。

                            PSN_APPLY

                            PSN_KILLACTIVE

                            PSN_RESET

                            PSN_SETACTIVE

                            PSN_WIZBACK

                            PSN_WIZNEXT

                            WM_INITDIALOG

                            WM_DESTROY

         如果当我们正在处理以上消息或者PropSheetProc正在处理当中时，你确实需要修改Page，那么传递一个私有的Windows消息。这样你的应用程序将不会接受这个消息，而直到PropertySheet管理者完成自己的任务，在这种安全状况下，你就可以编辑页面了。

         当PropertySheet销毁时，它将销毁内部的所有页面。它将按照页面创建的反向顺序来销毁每个页面。销毁由CreatePropertySheet（）创建但却没有加入PropertySheet中的页面，使用DestroyPropertySheet（）函数。

六、PropertySheet Title and Page Labels

         在创建PropertySheet的时候，通过在PROPSHEETHEADER结构中指定title来创建。如果该结构的dwFlags成员包含PSH_PROPTITLE值，那么PropertySheet将加入Properties后缀或者Properiesfor后缀（根据版本决定）。在PropertySheet创建后，可以通过PSM_SETTITLE消息改变Title。在Aero Wizard中，你可以通过该消息动态的改变内部的Page标题。（PropertySheet Title）

         默认情况下，PropertySheet使用对话框模板中的名字字符串来作为Page的标签。你可以通过PROPSHEETPAGE的dwFlags，包含PSP_USETITLE值来重写该名称字符串。如果dwFlags包含PSP_USETITLE,那么pszTitle就必须为Page的Label。（Page Label）

七、PageActivation

         一个PropertySheet在同一时间只有一个活动Page。这个活动的Page就是在所有重叠的Page的前台。用户通过选择某个Tab来激活某个Page。应用程序通过PSM_SETCURSEL消息来激活某个Page。

         PropertySheet通过发送PSN_KILLACTIVE通知消息，通知一个页面即将失去激活状态。作为回应，Page必须使用户对该页面的改变生效。如果在失去激活前，Page需要额外的用户输入，那么使用SetWindowLong（）函数来设置一个Page的DWL_MSGRESULT=TRUE。同时Page必须显示消息框来描述问题以及提供推举动作。设置DWL_MSGRESULT=FALSE，如果准备好了失去激活状态。

         在某个Page获得激活状态并显示前，PropertySheet发送PSN_SETACTIVE通知消息到这个Page。该页面必须初始化它内部的控件窗口。

八、HelpButton

         PropertySheet能显示两个帮助按钮，一个是显示在PropertySheet底部且在OK/Cancel/Apply按钮旁边的PropertySheet帮助按钮。一个是标准的标题栏帮助按钮，提供上下文帮助。

         PropertySheet帮助按钮 是可选的，能被显示在每个页面的底部。为一个或者多个Page显示该按钮，你需要：

1.      设置PROPSHEETHEADER的dwFlags包含PSH_HASHELP。

2.      设置每个需要该按钮的Page的PROPSHEETPAGE的dwFlags包含PSP_HASHELP。

         当用户单击PropertyHelp Button时，处于激活状态的Page接受到PSN_HELP通知消息。该Page必须通过显示帮助信息的方式来相应该消息。典型的是调用WinHELP（）函数。

         Removing the Caption Bar Help Button

                   标题栏帮助按钮是默认显示的。所以上下文帮助对于OK/Cancel/Apply按钮来说是可用的。但是该按钮是可以移除的。如果必要移除该按钮：

                            对于通用控件库的版本小于5.8的，你必须实现propertysheet回调函数。

                            对于通用控件库的版本为5.8或者更高的，你可以设置PROPSHEETHEADER的dwFlags包含PSH_NOCONTEXTHELP。但是如果你想兼容更早的程序，那么必须实现PropertySheet回调函数。

九、OK,Cancel, and Apply Buttons

         OK和Apply按钮很像，这两个按钮都引导PropertySheet页面验证并接受用户所做的修改。唯一的区别就是OK按钮会导致所做改变被接受后，PropertySheet会被关闭。

         当用户单击OK或者Apply按钮后，PropertySheet会给活动Page发送PSN_KILLACTIVE通知消息，使这个页面有机会验证用户的改变。如果改变有效，那么Page必须调用SetWindowLong（）函数设置DWL_MSGRESULT为FALSE。如果改变非法，那么必须设置DWL_MSGRESULT为TRUE，并显示对话框提示处理问题。Page将维持活跃，直到在对PSN_KILLACTIVE的回应中，将DWL_MSGRESULT被设置为FALSE。

         当一个Page通过设置DWL_MSGRESULT为FALSE来相应PSN_KILLACTIVE通知消息时，PropertySheet将发送PSN_APPLY消息到每一个页面。当一个Page接收到这个消息时，它必须接受相关项新的属性。为了向PropertySheet表明修改对该页面有效，那么需要调用setWindowLong（）设置DWL_MSGRESULT 为PSNRET_NOERROR。如果修改对这个Page无效，那么返回错误信息。所做的这些将使PropertySheet免于被销毁 或者 返回焦点到那些要么接受PSN_APPLY通知消息的页面，要么当按下Apply按钮时，有焦点。返回一个错误，指出哪一个Page接收到焦点，设置DWL_MSGRESULT 为以下值之一：

1.      PSNRET_INVALID。 PropertySheet将不会被销毁，焦点将返回该页面。

2.      PSNRET_INVALID_NOCHANGEPAGE。PropertySheet将不会被销毁，焦点将返回到那个按钮按下时有焦点的Page。

         应用程序使用PSM_APPLY消息模拟Apply按钮被选中。

         当一个Page被激活后，Apply按钮默认是disabled。这表示没有任何PropertySheet的修改可以被应用。当页面中的控件接收到用户编辑了一个属性时，Page必须发送PSM_CHANGED消息给PropertySheet。这个消息将会使PropertySheet的Apply按钮处于可用状态。如果用户紧接着按下Apply或者Cancel按钮，那么该Page必须重新初始化其控件，并且发送PSM_UNCHANGED消息再次让Apply按钮处于不可用状态。

         有时候，Apply按钮导致一个Page改变Propertysheet。并且这种改变是不可取消的。这时，该Page必须发送PSM_CANCELTOCLOSE消息到PropertySheet。这个消息导致PropertySheet将OK按钮文字变为CLOSE。通过这种方式指出改变不可回滚。

         有时候，一个页面改变系统的配置，而这个配置改变的生效必须重启系统。在作出这些改变后,Page必须发PSM_RESTARTWINDOWS或者PSM_REBOOTSYSTEM消息给PropertySheet。这个消息导致PropertySheet()函数返回ID_PSRESTARTWINDOWS 或 ID_PSREBOOTSYSTEM值，在PropertySheet被销毁后。

         当用户点击Cancel按钮后，PropertySheet将向所有Page发送PSN_RESET消息，指出Propertysheet将会销毁，每一个Page必须使用这个消息完成清理工作。

十、Wizard

         Wizard是PropertySheet的一个特殊的应用。Wizard被用来显示那些在某个时间只显示一个Page，并且有顺序的显示的情况。Wizard没有Tab标签，而使用了具有导航功能的BackWard和Forward按钮。