PropertyPage 类

PropertyPage是一个容器，支撑COM属性页对话框的单个标签页——从ActiveX控件属性浏览器上的**(Custom)条目调用的弹出窗口。它暴露IPropertyPage2** COM接口，以便任何支持ActiveX属性页的主机（twinBASIC IDE、经典VB6、Office等）可以将其放置在自己的属性表框架内，将要编辑的控件传递给它，并将页面的更改应用回它们。

设计属性页与设计小型对话框Form非常相似：将子控件放到上面，编写事件处理程序，自由使用其绘图表面。它与众不同之处在于生命周期，由主机而非应用程序控制：

1. 主机每个对话框实例化一次属性页类。
2. 主机调用IPropertyPage2.SetObjects传递选定的ActiveX控件。框架将其存储在SelectedControls中并引发SelectionChanged。
3. 当用户编辑值时，页面处理程序设置Changed = True以启用对话框的Apply按钮。
4. 当用户点击OK或Apply时，主机引发ApplyChanges，以便页面可以将新值写回到SelectedControls。
5. 对话框关闭时，框架引发Terminate并释放类实例。

默认属性为Controls；默认设计器事件为SelectionChanged。

Private Sub PropertyPage_SelectionChanged()
    ' 将第一个选定控件的属性镜像到编辑器控件中。
    txtCaption.Text = SelectedControls(0).Caption
End Sub

Private Sub txtCaption_Change()
    ' 任何用户编辑都将页面标记为脏，使主机启用Apply。
    Me.Changed = True
End Sub

Private Sub PropertyPage_ApplyChanges()
    ' 将编辑器值写回到每个选定控件。
    Dim ctl As Object
    For Each ctl In SelectedControls
        ctl.Caption = txtCaption.Text
    Next
End Sub

与主机通信

SelectedControls是主机希望此标签页编辑的控件的只读集合。主机在引发SelectionChanged之前填充它；页面在其存活期间保持这些引用。集合支持索引访问（SelectedControls(0)）、枚举（For Each ctl In SelectedControls）和Count成员。

Changed是页面用于与主机通信的双向标志。设置为True启用主机的Apply按钮；框架通过IPropertyPageSite.OnStatusChange立即通知主机。设置为False清除标志——框架在引发ApplyChanges之后自动执行此操作。

EditProperty声明用于VB6兼容性，但运行时当前未引发；希望对来自主机的按属性编辑请求做出反应的页面需要等待该连接实现。

ValidateControls从代码显式触发焦点子控件的Validate事件；如果验证失败，会引发运行时错误380。在ApplyChanges中用于在编辑器值格式错误时拒绝应用时很有用。

标准大小

VB6属性页对话框框架以两种标准大小之一绘制每个标签页——小型（250 × 62对话框单位）或大型（250 × 110对话框单位）——由主机根据属性表中最大页面的StandardSize选择。在设计时赋值StandardSize告诉主机请求哪种大小；在运行时读取它返回页面实际绘制的大小，当Width和Height已从任一预设更改时返回StandardSizeCustom。值以EnumStandardSize单位表示：StandardSizeCustom (0)、StandardSizeSmall (1)或StandardSizeLarge (2)。

绘图表面

PropertyPage本身就是一个图形表面。完整的VB6绘图原语集——Cls、Circle、Line、PSet、PaintPicture和Print语句——写入其设备上下文，使用ForeColor、FillColor/FillStyle、DrawWidth、DrawMode和DrawStyle设置画笔和填充，使用Font设置文本。当前画笔位置由CurrentX和CurrentY跟踪；TextWidth和TextHeight以当前字体测量字符串；ScaleX和ScaleY在比例模式之间转换单个坐标。

坐标系由ScaleMode、ScaleLeft、ScaleTop、ScaleWidth和ScaleHeight控制，与Form上的方式完全相同。AutoRedraw控制绘制输出是否在重绘之间持久保存——当False（默认）时，Paint事件必须在每次失效时重绘；当True时，页面保持一个在失效期间存活的离屏缓冲区，Paint事件被禁止。

控件和容器

Controls是此页面上每个子控件的集合，可通过名称或从零开始的索引访问。页面可直接枚举（For Each ctrl In Me）——Count和_Default成员转发给它。

ActiveControl返回获得焦点的子控件，如果此页面上没有控件获得焦点则为Nothing。SetFocus将焦点给予页面本身，然后转发到页面的Tab顺序。KeyPreview将按键通过页面的KeyDown、KeyUp和KeyPress事件路由，在焦点控件看到它们之前——适用于处理Escape或页面级快捷键。

属性

ActiveControl

此页面上当前具有输入焦点的控件，作为Control对象，当此页面上没有控件获得焦点时为Nothing。只读。

Appearance

AppearanceConstants的成员：vbAppearFlat或vbAppear3d（默认）。

INFO

保留用于VB6兼容性；此属性对属性页没有可观察效果。

AutoRedraw

在页面上执行的绘制是否在失效之间持久保存。Boolean，默认False。

当False时，绘图原语——Cls、Circle、Line、PSet、PaintPicture和Print——直接绘制到屏幕，页面必须在其Paint事件中在受影响区域失效时重绘它们。当True时，页面保持一个离屏位图，绘图原语绘制到其中（并同时到屏幕），位图在失效期间存活，Paint事件被禁止。

BackColor

页面客户区的背景颜色，作为OLE_COLOR。默认为系统3-D表面颜色。

Caption

主机在属性表框架中此页面标签上显示的文本。String。

语法：object.Caption [ = string ]

框架在主机调用IPropertyPage2.GetPageInfo时读取当前值，因此在页面激活之前所做的更改会生效；之后所做的更改被大多数主机忽略。

Changed

页面是否有未应用的编辑。Boolean，默认False。

将Changed设置为True通过IPropertyPageSite.OnStatusChange通知主机页面为脏——主机通常会启用其Apply按钮。框架在引发ApplyChanges之前自动将标志清除回False，因此处理程序无需自行重置。

ClipControls

在绘制期间是否将子控件从页面的绘图区域中裁剪出来。Boolean，默认True。运行时只读——在设计时设置。

Controls

此页面承载的每个控件的集合，可通过控件名或从零开始的索引访问。**默认属性。**只读——控件由运行时添加到集合中，而非用户代码。

Dim ctrl As Control
For Each ctrl In Me.Controls
    ctrl.Enabled = False
Next

ControlType

标识此控件为属性页的只读ControlTypeConstants值。始终为vbPropertyPage。

Count

Controls中的控件数量，作为Long。只读。等同于Me.Controls.Count。

CurrentX

水平画笔位置，以ScaleMode单位，用于省略起始坐标的绘图原语（例如Print和Line的矩形形式）。Double。

CurrentY

垂直画笔位置，以ScaleMode单位，用于省略起始坐标的绘图原语。Double。

DpiScaleFactorX

页面当前所在显示器的水平DPI缩放因子，作为Double。96 DPI时为1.0，120 DPI时为1.25，144 DPI时为1.5，依此类推。只读。

DpiScaleFactorY

页面当前所在显示器的垂直DPI缩放因子。当前始终等于DpiScaleFactorX。只读。

DrawMode

绘图原语在将画笔与目标组合时应用的光栅操作。DrawModeConstants的成员，默认vbCopyPen。

DrawStyle

绘图原语使用的画笔线型。DrawStyleConstants的成员：vbSolid（默认）、vbDash、vbDot、vbDashDot、vbDashDotDot、vbInvisible或vbInsideSolid。

DrawWidth

绘图原语的画笔宽度（以像素为单位）。Long，默认1。宽度大于1时强制DrawStyle回到vbSolid（Win32 GDI限制）。

FillColor

由Circle和Line的矩形形式绘制的闭合形状的填充颜色。OLE_COLOR，默认0（黑色）。仅在FillStyle不为vbFSTransparent时使用。

FillStyle

闭合形状的填充图案。FillStyleConstants的成员：vbFSSolid、vbFSTransparent（默认）、vbHorizontalLine、vbVerticalLine、vbUpwardDiagonal、vbDownwardDiagonal、vbCross或vbDiagonalCross。

Font

此页面上Print语句和其他文本绘制使用的StdFont。便捷属性FontName、FontSize、FontBold、FontItalic、FontStrikethru和FontUnderline读写此对象的相应成员。

FontBold

Font.Bold的快捷方式。Boolean。

FontItalic

Font.Italic的快捷方式。Boolean。

FontName

Font.Name的快捷方式。String。

FontSize

Font.Size的快捷方式——点大小。Single。

FontStrikethru

Font.Strikethrough的快捷方式。Boolean。

FontTransparent

当True（默认）时，页面上绘制的文本具有透明背景，使底层绘制在文本后面可见。当False时，文本绘制在由BackColor填充的 opaque 矩形上。Boolean。

FontUnderline

Font.Underline的快捷方式。Boolean。

ForeColor

Circle、Line、PSet以及Print绘制的文本使用的画笔颜色。OLE_COLOR。

HasDC

页面是否为其绘图表面保持私有设备上下文（CS_OWNDC）。Boolean，在属性页上始终为True。只读。

hDC

页面的Win32设备上下文句柄，作为LongPtr。只读。当底层窗口尚未创建时返回0。适用于传递给GDI API调用。

Height

页面的外部高度，默认以缇为单位（或以调用代码的ScaleMode单位）。Double。主机通常根据StandardSize设置页面大小；显式赋值Height切换到自定义大小。

HelpContextID

标识应用程序帮助文件中主题的Long，当用户在页面具有焦点时按F1时检索。

hWnd

页面的Win32窗口句柄，作为LongPtr。只读。适用于传递给API函数。

KeyPreview

当True时，页面的KeyDown、KeyUp和KeyPress事件在焦点控件收到相同按键之前触发。Boolean，默认False。适用于页面级快捷键；事件之后仍在焦点控件上触发。

Left

页面外部矩形在主机属性表框架中的水平位置，以缇为单位。Double。由主机通过IPropertyPage2.Activate和Move设置；很少从用户代码赋值。

MouseIcon

当MousePointer为vbCustom且指针位于页面上（且不在有自己设置的子控件上）时用作鼠标光标的StdPicture。

MousePointer

当指针位于页面上（且不在有自己设置的子控件上）时显示的鼠标光标。MousePointerConstants的成员。

Name

属性页类的唯一设计时名称。运行时只读。也是生成的属性页类的类名。

OLEDropMode

页面如何响应OLE放置。OLEDropConstants的受限成员：vbOLEDropNone或vbOLEDropManual。属性页上不支持自动放置模式。

Palette

INFO

保留用于VB6的256色调色板功能的兼容性；twinBASIC中当前未实现。

PaletteMode

INFO

保留用于VB6的256色调色板功能的兼容性；twinBASIC中当前未实现。

Picture

作为页面背景绘制的StdPicture。在任何绘图原语或子控件之前绘制。赋值Nothing移除背景。

PictureDpiScaling

当True时，Picture在绘制前按当前DPI因子缩放。Boolean，默认False。

RightToLeft

INFO

保留用于VB6兼容性；twinBASIC中当前未实现。

ScaleHeight

逻辑绘图矩形的高度，以ScaleMode单位。Double。设置它（或ScaleWidth、ScaleLeft或ScaleTop）会隐式将ScaleMode切换为vbUser。

ScaleLeft

页面客户区左边缘的逻辑水平坐标，以ScaleMode单位。Double。默认0。

ScaleMode

CurrentX、CurrentY、绘图原语、TextWidth和TextHeight使用的度量单位。ScaleModeConstants的成员：vbTwips（默认）、vbPoints、vbPixels、vbCharacters、vbInches、vbMillimeters、vbCentimeters或vbUser（由四个**Scale***属性定义矩形）。

ScaleTop

页面客户区顶边缘的逻辑垂直坐标，以ScaleMode单位。Double。默认0。

ScaleWidth

逻辑绘图矩形的宽度，以ScaleMode单位。Double。设置它会隐式将ScaleMode切换为vbUser。

SelectedControls

主机要求此页面编辑的对象集合，作为SelectedControls实例。只读。框架在引发SelectionChanged之前填充集合，并在Terminate时清除它。

返回的对象暴露三个成员：

• Count As Long——选定对象的数量（当主机尚未调用SetObjects或已清除选择时为0）。
• Item(Index) As Object——从零开始的索引访问。默认成员，因此SelectedControls(0)返回第一个对象。
• _NewEnum——支持For Each ctl In SelectedControls。

项目以Object形式返回，因此使用CallByName或后期绑定成员访问来读写其属性。

For Each ctl In SelectedControls
    ctl.Caption = txtCaption.Text
Next

StandardSize

页面在主机属性表框架中的标准大小。EnumStandardSize的成员：StandardSizeCustom (0)、StandardSizeSmall (1——250 × 62对话框单位)或StandardSizeLarge (2——250 × 110对话框单位)。

语法：object.StandardSize [ = value ]

读取StandardSize将页面的当前像素大小与小型/大型预设进行比较，当两者都不匹配时返回StandardSizeCustom。赋值StandardSizeSmall或StandardSizeLarge相应地调整页面大小；赋值StandardSizeCustom是空操作（保持大小不变）。此属性仅在代码中暴露——VB6在设计时属性表上暴露了它，但从未在运行时对象模型中暴露。

Tag

应用程序可用于将自定义数据与页面关联的自由格式String。框架忽略此属性。

Top

页面外部矩形在主机属性表框架中的垂直位置，以缇为单位。Double。由主机设置；很少从用户代码赋值。

Width

页面的外部宽度，默认以缇为单位（或以调用代码的ScaleMode单位）。Double。主机通常根据StandardSize设置页面大小；显式赋值Width切换到自定义大小。

方法

Circle

使用ForeColor绘制轮廓，FillColor/FillStyle填充内部，在页面上绘制圆、椭圆或弧。

语法：object.Circle [ Step ] ( X, Y ), Radius [, [ Color ] [, [ Start ] [, [ End ] [, Aspect ] ] ] ]

X, Y

必需 圆心，以ScaleMode单位。Step使圆心相对于(CurrentX, CurrentY)。

Radius

必需 以ScaleMode单位给出半径的Single。

Color

可选 轮廓的OLE_COLOR；默认为ForeColor。

Start, End

可选 以弧度为单位的角，用于绘制弧而非完整圆。

Aspect

可选 垂直半径与水平半径的比率。1.0为圆形；偏离1.0的值产生椭圆。

Cls

清除由Circle、Line、PSet、PaintPicture和Print执行的任何绘制，重新绘制BackColor，并将CurrentX / CurrentY重置为0。不影响Picture背景或子控件。

语法：object.Cls

Line

使用ForeColor（或显式颜色）和DrawWidth/DrawStyle在页面上绘制直线或矩形。

语法：object.Line [ [ Step ] ( X1, Y1 ) ] -[ Step ] ( X2, Y2 ) [, [ Color ] [, B [ F ] ] ]

X1, Y1

可选 起始点，以ScaleMode单位。Step使点相对于(CurrentX, CurrentY)。省略时，从当前画笔位置开始绘制。

X2, Y2

必需 终止点，以ScaleMode单位。Step使点相对于(X1, Y1)。

Color

可选 线条的OLE_COLOR；默认为ForeColor。

B

可选 绘制一个以(X1, Y1)和(X2, Y2)为对角的矩形，而非线条。

F

可选 与B组合时，用ForeColor而非FillColor/FillStyle填充矩形。

OLEDrag

从页面发起OLE拖动操作，触发OLEStartDrag事件以便应用程序填充DataObject。

语法：object.OLEDrag

PaintPicture

将StdPicture绘制到页面上，支持可选的缩放和光栅操作。

语法：object.PaintPicture Picture, X1, Y1 [, Width1 [, Height1 [, X2 [, Y2 [, Width2 [, Height2 [, Opcode [, StretchQuality ] ] ] ] ] ] ] ]

Picture

必需 要绘制的StdPicture。

X1, Y1

必需 目标左上角，以ScaleMode单位。

Width1, Height1

可选 目标大小；默认为图片的自然大小。

X2, Y2, Width2, Height2

可选 图片内的源矩形；默认为整个图片。

Opcode

可选 光栅操作代码（RasterOpConstants的成员）。默认为vbSrcCopy。

StretchQuality

可选 缩放时的插值方法。默认为普通质量。

Point

INFO

保留用于VB6兼容性；twinBASIC中当前未实现。在VB6中，此方法返回绘图表面单个像素的OLE_COLOR。

语法：object.Point( X, Y )

Print

使用Font将文本写入页面的绘图表面，从CurrentX / CurrentY开始并随之推进。通过VB6 Print语句分派，因此多个表达式可以用;（无间距）或,（跳到下一个打印区域）分隔。**Spc(n)**插入n个空格，Tab(n)移到打印列n。输出遵循Font、ForeColor和FontTransparent，当AutoRedraw为True时记录到持久离屏位图，从而在失效期间存活。

语法：object.Print [ expressionlist ] [ ; | , ]

末尾的;或,抑制换行，使下一次Print调用在同一行继续。

PSet

将页面上的单个像素设置为指定颜色。

语法：object.PSet [ Step ] ( X, Y ) [, Color ]

X, Y

必需 像素位置，以ScaleMode单位。Step使位置相对于(CurrentX, CurrentY)。

Color

可选 OLE_COLOR；默认为ForeColor。

Refresh

强制页面立即重绘，当AutoRedraw为False时触发Paint。

语法：object.Refresh

Scale

通过一次调用设置页面的逻辑绘图矩形——赋值ScaleLeft、ScaleTop、ScaleWidth和ScaleHeight。将ScaleMode切换为vbUser。不带参数调用Scale会将矩形重置为与客户区1:1映射（以像素为单位）。

语法：object.Scale [ ( X1, Y1 )-( X2, Y2 ) ]

X1, Y1

可选 左上角的逻辑坐标。

X2, Y2

可选 右下角的逻辑坐标。

ScaleX

将水平长度从一种ScaleMode转换为另一种。

语法：object.ScaleX( Width [, FromScale [, ToScale ] ] )

Width

必需 给出源长度的Single。

FromScale, ToScale

可选 ScaleModeConstants的成员。省略时默认为当前ScaleMode。

ScaleY

将垂直长度从一种ScaleMode转换为另一种。

语法：object.ScaleY( Height [, FromScale [, ToScale ] ] )

Height

必需 给出源长度的Single。

FromScale, ToScale

可选 ScaleModeConstants的成员。省略时默认为当前ScaleMode。

SetFocus

激活页面并将输入焦点给予其第一个可获得焦点的子控件（或此页面上最后持有焦点的控件）。

语法：object.SetFocus

TextHeight

返回给定字符串使用页面当前Font绘制时将占用的 height，以ScaleMode单位。嵌入式换行会被遵循。

语法：object.TextHeight( Str )

Str

必需 要测量的String。

TextWidth

返回给定字符串使用页面当前Font绘制时将占用的 width，以ScaleMode单位。当Str包含嵌入式换行时返回最长行的宽度。

语法：object.TextWidth( Str )

Str

必需 要测量的String。

ValidateControls

触发此页面上当前活动控件的Validate事件。如果处理程序将Cancel设置为True，ValidateControls会引发运行时错误380（Invalid property value）；调用者可以用On Error包装此调用以检测失败的验证。在ApplyChanges中用于在编辑器值格式错误时拒绝应用时很有用。

语法：object.ValidateControls

事件

ApplyChanges

当主机调用IPropertyPage2.Apply时引发——通常是因为用户在属性表对话框上点击了OK或Apply。处理程序应将页面当前的编辑器值写回到SelectedControls中的每个对象。框架在处理程序运行之前将Changed清除为False。当应用时Changed已经为False时不引发。

语法：object_ApplyChanges( )

Click

当用户单击页面的客户区时引发（即不在任何子控件上）。

语法：object_Click( )

DblClick

当用户双击页面的客户区时引发。

语法：object_DblClick( )

DPIChange

当页面移动到具有不同DPI缩放的显示器时引发，但仅当应用程序是按显示器DPI感知的（PROCESS_PER_MONITOR_DPI_AWARE）。事件的NewDPI参数给出新的有效DPI；子控件会自动重新缩放。

语法：object_DPIChange( NewDPI As Long )

DragDrop

当手动拖动操作在目标控件上结束时在目标控件上引发。

语法：object_DragDrop( Source As Control, X As Single, Y As Single )

DragOver

当手动拖动操作进行中时在光标下方的控件上引发。

语法：object_DragOver( Source As Control, X As Single, Y As Single, State As Integer )

EditProperty

INFO

声明用于VB6兼容性；twinBASIC中当前未引发。主机的IPropertyPage2.EditProperty请求已被确认但尚未传播到托管事件。

实现后，当主机要求页面将焦点给予与命名属性对应的编辑器时引发——通常是因为用户在属性浏览器中双击了该属性。

语法：object_EditProperty( PropertyName As String )

PropertyName

主机希望编辑的属性名称。

GotFocus

当页面获得输入焦点且页面上没有启用的子控件可以代替获取焦点时引发。

语法：object_GotFocus( )

Initialize

引发一次，在页面的窗口和所有控件创建之后且页面已注册到其主机的框架之后，在SelectionChanged首次引发之前。这是用不依赖于选定对象的静态数据（选择列表、默认值等）填充编辑器控件的经典位置。

语法：object_Initialize( )

KeyDown

当用户按下任意键时引发。默认在焦点控件上触发；KeyPreview为True时，首先在页面上触发。

语法：object_KeyDown( KeyCode As Integer, Shift As Integer )

KeyPress

当用户输入产生ANSI按键的字符时引发。默认在焦点控件上触发；KeyPreview为True时，首先在页面上触发。

语法：object_KeyPress( KeyAscii As Integer )

KeyUp

当用户释放键时引发。默认在焦点控件上触发；KeyPreview为True时，首先在页面上触发。

语法：object_KeyUp( KeyCode As Integer, Shift As Integer )

LostFocus

当页面失去输入焦点时引发。

语法：object_LostFocus( )

MouseDown

当用户在页面的客户区按下任意鼠标按钮时引发。

语法：object_MouseDown( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseMove

当光标在页面的客户区上移动时引发。

语法：object_MouseMove( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseUp

当用户在页面的客户区释放鼠标按钮时引发。

语法：object_MouseUp( Button As Integer, Shift As Integer, X As Single, Y As Single )

OLECompleteDrag

当OLE拖动操作完成时在源控件上引发，指示目标接受了哪种效果（复制、移动、无）。

语法：object_OLECompleteDrag( Effect As Long )

OLEDragDrop

当用户将数据放到目标控件上时在目标控件上引发。

语法：object_OLEDragDrop( Data As DataObject, Effect As Long, Button As Integer, Shift As Integer, X As Single, Y As Single )

OLEDragOver

当OLE拖动经过目标控件时在目标控件上引发。

语法：object_OLEDragOver( Data As DataObject, Effect As Long, Button As Integer, Shift As Integer, X As Single, Y As Single, State As Integer )

OLEGiveFeedback

在拖动期间在源控件上引发，以便应用程序调整光标或其他视觉反馈。

语法：object_OLEGiveFeedback( Effect As Long, DefaultCursors As Boolean )

OLESetData

当目标以已注册但尚未提供的格式请求数据时在源控件上引发。

语法：object_OLESetData( Data As DataObject, DataFormat As Integer )

OLEStartDrag

在OLE拖动开始时在源控件上引发，以便应用程序填充DataObject并选择允许的效果。

语法：object_OLEStartDrag( Data As DataObject, AllowedEffects As Long )

Paint

当页面的失效部分需要重绘时引发。当AutoRedraw为True时被禁止——页面的持久离屏缓冲区被位块传输到屏幕。

语法：object_Paint( )

SelectionChanged

在主机调用IPropertyPage2.SetObjects给页面一组新的编辑对象或清除选择之后引发。处理程序应读取SelectedControls并将这些对象的共同状态镜像到页面的编辑器控件中。默认设计器事件。

语法：object_SelectionChanged( )

Terminate

当页面正在被销毁时引发——一次在其窗口从主机的属性表框架上取消挂钩时，另一次在类实例的最后一个引用被释放时。处理程序在SelectedControls仍然填充时运行，给它最后的机会在被编辑对象释放之前从中读取状态。

语法：object_Terminate( )