Image 类

Image是无窗口轻量级控件，用于显示图片——位图、JPEG、GIF、PNG、图标、光标或Windows图元文件。它是PictureBox的小巧高效替代：没有底层Win32窗口、没有绘图表面、没有子控件、没有焦点——只有父级上的一个矩形，绘制Picture中的内容。Image控件非常适合logo、装饰图、自定义绘制按钮、字形行以及任何使用重量级PictureBox显得过重的地方。

默认属性是Picture，默认事件是Click。

Private Sub Form_Load()
    Set imgLogo.Picture  = LoadPicture(App.Path & "\logo.png")
    imgLogo.Stretch      = True
    imgLogo.BorderStyle  = vbFixedSingleBorder
End Sub

Private Sub imgLogo_Click()
    MsgBox "Logo clicked"
End Sub

无窗口渲染

Image没有hWnd。框架在父级的绘制周期中将其直接绘制到父级的绘图表面上，因此控件比PictureBox开销小得多，不添加自己的Win32窗口。其权衡与任何无窗口控件相同：

• 无焦点、无键盘输入、无KeyDown / KeyPress / KeyUp / GotFocus / LostFocus / Validate。
• 没有可传递给API函数的hWnd，也没有SetFocus。
• 不能承载子控件。

对于需要这些功能的场景，请改用PictureBox。

拉伸和自动调整尺寸

Stretch是尺寸行为的主开关：

• Stretch = False（默认）：图片以其自然像素尺寸绘制，每次赋值新的Picture时Image自动调整自身大小以匹配。用户仍可手动调整控件大小——一旦如此，图片会被裁剪或在自然边界周围填充（不会重新拉伸）。
• Stretch = True：图片被缩放以填充Image的矩形。重采样算法由StretchMode选择；不保持宽高比。

图元文件（vbPicTypeMetafile、vbPicTypeEMetafile）是矢量的——它们始终缩放以适应且无论Stretch设置如何都保持宽高比。

PictureDpiScaling为True时，在绘制前将自然像素尺寸乘以当前DPI缩放因子——有助于使logo在高DPI显示器上与96-DPI显示器上保持相同的物理尺寸。

旋转

Angle以度为单位围绕控件矩形的左上角逆时针旋转渲染图片。0为自然方向；90为逆时针旋转四分之一圈；0到360之间的值给出任意旋转。控件的边界矩形不变——因此大旋转角度可能将可见图片推出矩形。Click、MouseDown和其他鼠标事件的命中测试仍使用未旋转的矩形。

边框

BorderStyle选择无边框（默认）和围绕矩形绘制的单凹陷边框。当边框存在时，Appearance选择3-D和平面（单色）版本。

源端和目标端OLE拖放

Image控件支持OLE拖放操作的两端：

• OLEDragMode控制源端。使用vbOLEDragAutomatic时，在Image上方按住鼠标并开始拖动会自动将当前Picture复制到结果DataObject中。使用vbOLEDragManual（默认）时，拖动必须通过从MouseDown处理程序调用OLEDrag来发起。
• OLEDropMode控制目标端。使用vbOLEDropManual时，OLEDragOver和OLEDragDrop事件触发，由应用程序决定如何处理。vbOLEDropAutomatic在Image上不受支持，赋值它会导致运行时错误5。

数据绑定

设置DataSource和DataField将Picture连接到Data控件记录集的字段。绑定字段在每次移动时作为二进制图片数据读取；将Nothing赋值给Picture会将空值等效写回记录集，任何其他赋值会通过绑定字段序列化图片的字节。

属性

Anchors

决定Image的哪些边随父级对应边调整的边集合。只读——通过返回的Anchors对象设置各个.Left、.Top、.Right、.Bottom标志。

Angle

渲染图片的旋转角度，以度为单位，围绕控件矩形的左上角逆时针旋转。Double，默认0。

Appearance

边框的样式，作为AppearanceConstants的成员：vbAppearFlat或vbAppear3d（默认）。仅在BorderStyle为vbFixedSingleBorder时有意义。

BorderStyle

绘制在矩形周围的边框样式。ControlBorderStyleConstants的成员：vbNoBorder（0，默认）或vbFixedSingleBorder（1）。

Container

承载此Image的控件——通常是窗体、Frame或UserControl。用Get读取，用Set更改。

ControlType

标识此控件为图像的只读ControlTypeConstants值。始终为vbImage。

DataChanged

绑定的Picture自上次从DataSource保存或刷新以来是否已被写入。Boolean。设置DataChanged = True也会将绑定记录集标记为脏。

DataField

绑定的DataSource记录集中由Picture镜像的字段名称。String。

DataFormat

INFO

保留用于与VB6兼容；目前在twinBASIC中尚未实现。

DataMember

INFO

保留用于与VB6兼容；目前在twinBASIC中尚未实现。

DataSource

对Data控件（或其他DataSource提供者）的引用，其记录集为DataField提供值。用Set设置。

Dock

Image在其容器中的停靠位置。DockModeConstants的成员：vbDockNone（默认）、vbDockLeft、vbDockTop、vbDockRight、vbDockBottom或vbDockFill。停靠的图像忽略Anchors。

DragIcon

在控件被拖放时用作鼠标光标的StdPicture（参见Drag和DragMode）。

DragMode

控件是否应在用户按住鼠标时自行拖动（手动VB拖动形式，与OLE拖动不同）。DragModeConstants的成员：vbManual（0，默认——从代码调用Drag）或vbAutomatic（1）。

Enabled

决定控件是否接受鼠标输入。禁用的Image仍正常绘制但忽略鼠标事件。Boolean，默认True。

Height

控件的高度，默认以缇为单位（或以容器的ScaleMode单位）。Double。当Stretch为False且赋值新Picture时，高度自动调整到图片的自然像素高度。

Index

当控件是控件数组的一部分时，此实例在数组中的Long零基索引。在非数组实例上读取Index会引发运行时错误343（对象不是数组）。运行时只读。

Left

从容器左边缘到控件左边缘的水平距离。Double。

MouseIcon

当MousePointer为vbCustom且指针在控件上方时用作鼠标光标的StdPicture。

MousePointer

指针在控件上方时显示的鼠标光标。MousePointerConstants的成员。

Name

控件在其父窗体上的唯一设计时名称。运行时只读。

OLEDragMode

当用户开始拖动Image时是否自动启动OLE拖动。OLEDragConstants的成员：vbOLEDragManual（0，默认——应用程序调用OLEDrag）或vbOLEDragAutomatic（1——框架自动将当前Picture复制到结果DataObject中）。

OLEDropMode

Image如何响应到达其上的OLE放置。OLEDropConstants的受限成员：vbOLEDropNone（0，默认）或vbOLEDropManual（1）。Image不支持自动放置；赋值vbOLEDropAutomatic会引发运行时错误5（无效的过程调用或参数）。

Parent

对最终包含此控件的Form（或UserControl）的引用。只读。

Picture

控件渲染的StdPicture。默认属性。

语法：Set object.Picture = picture

赋值Nothing恢复空图片而非移除表面。在Stretch为False时赋值新图片会自动调整控件到图片的自然像素尺寸；在Stretch为True时保留现有矩形并将新图片缩放以适应。

PictureDpiScaling

当True时，图片的自然像素尺寸在绘制前（并被自动调整尺寸逻辑使用）乘以当前DPI缩放因子。Boolean，默认False。

Stretch

图片是否被缩放以填充控件矩形（True）或以自然尺寸渲染并自动调整控件以适应（False，默认）。完整规则见拉伸和自动调整尺寸。图元文件无论此设置如何始终缩放。

StretchMode

当Stretch为True且图片被缩放时使用的重采样算法。Image.StretchModeConstants的成员：

常量	值	算法
vbStretchHalftone	0	GDI STRETCH_HALFTONE（默认——良好的通用质量）。
vbStretchColorOnColor	1	GDI STRETCH_COLORONCOLOR（最快、最低质量——最近邻）。
vbStretchLanczos8	2	自定义Lanczos重采样器，8瓣核（最高质量，最慢）。
vbStretchLanczos3	3	自定义Lanczos重采样器，3瓣核（高质量）。
vbStretchBicubic	4	自定义双三次重采样器。
vbStretchBilinear	5	自定义双线性重采样器。

Lanczos、双三次和双线性模式仅适用于实际需要调整尺寸的位图——图元文件和未缩放的位图回退到GDI模式。

Tag

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

ToolTipText

用户悬停在控件上方时作为工具提示显示的多行String。

Top

从容器顶部到控件顶部的垂直距离。Double。

Visible

控件是否显示。Boolean，默认True。

WhatsThisHelpID

INFO

保留用于与VB6兼容；目前在twinBASIC中尚未实现。参见ShowWhatsThis。

Width

控件的宽度，默认以缇为单位（或以容器的ScaleMode单位）。Double。当Stretch为False且赋值新Picture时，宽度自动调整到图片的自然像素宽度。

方法

Drag

开始、完成或取消手动VB样式拖动操作。与OLE拖动不同——参见OLEDrag。

语法：object.Drag [ Action ]

Action

可选 DragConstants的成员：vbCancel（0）、vbBeginDrag（1，默认）或vbEndDrag（2）。

Move

在单次调用中重新定位并可选地调整控件的尺寸。

语法：object.Move Left [, Top [, Width [, Height ] ] ]

Left

必需 给出新水平位置的Single。

Top、Width、Height

可选 对应属性的新值。省略的值保持不变。

OLEDrag

从此Image发起OLE拖动操作，引发OLEStartDrag事件以便应用程序填充DataObject（或者，如果源已被预填充，则立即开始拖动）。

语法：object.OLEDrag

Refresh

强制立即重绘Image在父级绘图表面上的矩形。

语法：object.Refresh

ShowWhatsThis

INFO

保留用于与VB6兼容；目前在twinBASIC中尚未实现。

语法：object.ShowWhatsThis

ZOrder

将Image带到容器内无窗口同级堆栈的前面或后面。

语法：object.ZOrder [ Position ]

Position

可选 ZOrderConstants的成员：vbBringToFront（0，默认）或vbSendToBack（1）。

事件

Click

当用户单击控件矩形时引发。默认事件。

语法：object_Click( )

DblClick

当用户双击控件矩形时引发。

语法：object_DblClick( )

DragDrop

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

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

DragOver

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

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

Initialize

在控件已连接到其容器的绘制周期但首次绘制之前引发一次。适用于依赖容器状态的最后一刻设置。

语法：object_Initialize( )

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 )