Image class

An Image is a windowless lightweight control for displaying a picture --- a bitmap, JPEG, GIF, PNG, icon, cursor, or Windows metafile. It is the small, efficient alternative to PictureBox: no underlying Win32 window, no drawing surface, no child controls, no focus --- just a rectangle on the parent that paints whatever is in Picture. Image controls are ideal for logos, decorative artwork, custom-drawn buttons, glyph rows, and any other place where a heavy PictureBox would be overkill.

The default property is Picture and the default event is 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

Windowless rendering

An Image has no hWnd. The framework paints it directly onto its parent's drawing surface during the parent's paint cycle, so the control is much cheaper than a PictureBox and adds no Win32 window of its own. The trade-offs are the same as for any windowless control:

• No focus, no keyboard input, no KeyDown / KeyPress / KeyUp / GotFocus / LostFocus / Validate.
• No hWnd to pass to API functions, and no SetFocus.
• Cannot host child controls.

For anything that needs those, use PictureBox instead.

Stretch and auto-sizing

Stretch is the master switch for sizing behaviour:

• Stretch = False (default): the picture is drawn at its natural pixel size and the Image auto-resizes itself to match every time a new Picture is assigned. The user may still resize the control manually --- once that happens the picture is clipped or padded around the natural bounds (it is not re-stretched).
• Stretch = True: the picture is scaled to fill the Image's rectangle. The resampling algorithm is chosen by StretchMode; aspect ratio is not preserved.

Metafiles (vbPicTypeMetafile, vbPicTypeEMetafile) are vector --- they always scale to fit and the aspect ratio is preserved regardless of Stretch.

PictureDpiScaling, when True, multiplies the natural pixel dimensions by the current DPI scale factor before drawing --- useful for keeping a logo the same physical size on a high-DPI monitor as on a 96-DPI one.

Rotation

Angle rotates the rendered picture, in degrees, anti-clockwise around the top-left corner of the control's rectangle. 0 is the natural orientation; 90 is a quarter turn anti-clockwise; values between 0 and 360 give arbitrary rotations. The control's bounding rectangle does not change --- large rotation angles can therefore push the visible picture outside the rectangle. Hit-testing for Click, MouseDown, and the other mouse events still uses the unrotated rectangle.

Border

BorderStyle chooses between no border (the default) and a single sunken border drawn around the rectangle. When a border is present, Appearance selects between a 3-D and a flat (monochrome) version of it.

Source-side and destination-side OLE drag-drop

The Image control supports both ends of an OLE drag-drop operation:

• OLEDragMode controls the source side. With vbOLEDragAutomatic, holding the mouse over the Image and beginning a drag automatically copies the current Picture into the resulting DataObject. With vbOLEDragManual (default) drags must be initiated by calling OLEDrag from a MouseDown handler.
• OLEDropMode controls the destination side. With vbOLEDropManual the OLEDragOver and OLEDragDrop events fire and the application decides what to do. vbOLEDropAutomatic is not supported on an Image and assigning it raises run-time error 5.

Data binding

Setting DataSource and DataField connects the Picture to a field of a Data control's recordset. The bound field is read as binary picture data on each move; assigning Nothing to Picture writes a null-equivalent back to the recordset, and any other assignment serialises the picture's bytes back through the bound field.

Properties

Anchors

The set of edges of the parent that the Image's corresponding edges follow when the parent resizes. Read-only --- assign individual .Left, .Top, .Right, .Bottom flags through the returned Anchors object.

Angle

The rotation of the rendered picture, in degrees, anti-clockwise around the top-left of the control's rectangle. Double, default 0.

Appearance

The style of the border, as a member of AppearanceConstants: vbAppearFlat or vbAppear3d (default). Only meaningful when BorderStyle is vbFixedSingleBorder.

BorderStyle

The style of border drawn around the rectangle. A member of ControlBorderStyleConstants: vbNoBorder (0, default) or vbFixedSingleBorder (1).

Container

The control that hosts this Image --- typically the form, a Frame, or a UserControl. Read with Get, change with Set.

ControlType

A read-only ControlTypeConstants value identifying this control as an image. Always vbImage.

DataChanged

Whether the bound Picture has been written to since the last save or refresh from the DataSource. Boolean. Setting DataChanged = True also marks the bound recordset as dirty.

DataField

The name of the field, in the recordset of the bound DataSource, whose binary value is mirrored by Picture. String.

DataFormat

INFO

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

DataMember

INFO

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

DataSource

A reference to a Data control (or other DataSource provider) whose recordset supplies the value for DataField. Set with Set.

Dock

Where the Image is docked within its container. A member of DockModeConstants: vbDockNone (default), vbDockLeft, vbDockTop, vbDockRight, vbDockBottom, or vbDockFill. Docked images ignore Anchors.

DragIcon

A StdPicture used as the mouse cursor while the control is being drag-and-dropped (see Drag and DragMode).

DragMode

Whether the control should drag itself (the manual VB-drag form, distinct from OLE drag) when the user holds the mouse over it. A member of DragModeConstants: vbManual (0, default --- call Drag from code) or vbAutomatic (1).

Enabled

Determines whether the control accepts mouse input. A disabled Image still paints normally but ignores mouse events. Boolean, default True.

Height

The control's height, in twips by default (or in the container's ScaleMode units). Double. When Stretch is False and a new Picture is assigned, the height auto-resizes to the picture's natural pixel height.

Index

When the control is part of a control array, the Long zero-based index of this instance within the array. Reading Index on a non-array instance raises run-time error 343 (Object not an array). Read-only at run time.

Left

The horizontal distance from the left edge of the container to the left edge of the control. Double.

MouseIcon

A StdPicture used as the mouse cursor when MousePointer is vbCustom and the pointer is over the control.

MousePointer

The mouse cursor shown when the pointer is over the control. A member of MousePointerConstants.

Name

The unique design-time name of the control on its parent form. Read-only at run time.

OLEDragMode

Whether an OLE drag is started automatically when the user begins dragging the Image. A member of OLEDragConstants: vbOLEDragManual (0, default --- application calls OLEDrag) or vbOLEDragAutomatic (1 --- the framework copies the current Picture into the resulting DataObject automatically).

OLEDropMode

How the Image responds to OLE drops arriving on it. A restricted member of OLEDropConstants: vbOLEDropNone (0, default) or vbOLEDropManual (1). Automatic drop is not supported on an Image; assigning vbOLEDropAutomatic raises run-time error 5 (Invalid procedure call or argument).

Parent

A reference to the Form (or UserControl) that ultimately contains the control. Read-only.

Picture

The StdPicture rendered by the control. Default property.

Syntax: Set object.Picture = picture

Assigning Nothing restores an empty picture rather than removing the surface. Assigning a new picture while Stretch is False auto-resizes the control to the picture's natural pixel dimensions; while Stretch is True the existing rectangle is preserved and the new picture is scaled to fit.

PictureDpiScaling

When True, the picture's natural pixel dimensions are multiplied by the current DPI scale factor before being drawn (and used by the auto-size logic). Boolean, default False.

Stretch

Whether the picture is scaled to fill the control's rectangle (True) or rendered at its natural size with the control auto-sized to fit (False, default). See Stretch and auto-sizing for the full rules. Metafiles always scale regardless of this setting.

StretchMode

The resampling algorithm used when Stretch is True and the picture is scaled. A member of Image.StretchModeConstants:

Constant	Value	Algorithm
vbStretchHalftone	0	GDI STRETCH_HALFTONE (default --- good general-purpose quality).
vbStretchColorOnColor	1	GDI STRETCH_COLORONCOLOR (fastest, lowest quality --- nearest neighbour).
vbStretchLanczos8	2	Custom Lanczos resampler with an 8-lobe kernel (highest quality, slowest).
vbStretchLanczos3	3	Custom Lanczos resampler with a 3-lobe kernel (high quality).
vbStretchBicubic	4	Custom bicubic resampler.
vbStretchBilinear	5	Custom bilinear resampler.

The Lanczos, bicubic, and bilinear modes only apply to bitmaps that actually need resizing --- metafiles and unscaled bitmaps fall back to the GDI mode.

Tag

A free-form String the application can use to associate custom data with the control. Ignored by the framework.

ToolTipText

A multi-line String displayed as a tooltip when the user hovers over the control.

Top

The vertical distance from the top of the container to the top of the control. Double.

Visible

Whether the control is shown. Boolean, default True.

WhatsThisHelpID

INFO

Reserved for compatibility with VB6; not currently implemented in twinBASIC. See ShowWhatsThis.

Width

The control's width, in twips by default (or in the container's ScaleMode units). Double. When Stretch is False and a new Picture is assigned, the width auto-resizes to the picture's natural pixel width.

Methods

Drag

Begins, completes, or cancels a manual VB-style drag operation. Distinct from OLE drag --- see OLEDrag.

Syntax: object.Drag [ Action ]

Action

optional A member of DragConstants: vbCancel (0), vbBeginDrag (1, default), or vbEndDrag (2).

Move

Repositions and optionally resizes the control in a single call.

Syntax: object.Move Left [, Top [, Width [, Height ] ] ]

Left

required A Single giving the new horizontal position.

Top, Width, Height

optional New values for the corresponding properties. Omitted values are left unchanged.

OLEDrag

Initiates an OLE drag operation from this Image, raising the OLEStartDrag event so the application can populate the DataObject (or, if the source has already been pre-populated, begins the drag immediately).

Syntax: object.OLEDrag

Refresh

Forces an immediate repaint of the Image's rectangle on the parent's drawing surface.

Syntax: object.Refresh

ShowWhatsThis

INFO

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

Syntax: object.ShowWhatsThis

ZOrder

Brings the Image to the front or back of the windowless-sibling stack within its container.

Syntax: object.ZOrder [ Position ]

Position

optional A member of ZOrderConstants: vbBringToFront (0, default) or vbSendToBack (1).

Events

Click

Raised when the user single-clicks the control's rectangle. Default event.

Syntax: object_Click( )

DblClick

Raised when the user double-clicks the control's rectangle.

Syntax: object_DblClick( )

DragDrop

Raised on the destination control when a manual VB-style drag operation ends over it.

Syntax: object_DragDrop( Source As Control, X As Single, Y As Single )

DragOver

Raised on the control under the cursor while a manual VB-style drag operation is in progress.

Syntax: object_DragOver( Source As Control, X As Single, Y As Single, State As Integer )

Initialize

Raised once, after the control has been connected to its container's paint cycle but before it is first painted. Useful for last-minute setup that depends on container state.

Syntax: object_Initialize( )

MouseDown

Raised when the user presses any mouse button over the control.

Syntax: object_MouseDown( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseMove

Raised when the cursor moves over the control.

Syntax: object_MouseMove( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseUp

Raised when the user releases a mouse button over the control.

Syntax: object_MouseUp( Button As Integer, Shift As Integer, X As Single, Y As Single )

OLECompleteDrag

Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted.

Syntax: object_OLECompleteDrag( Effect As Long )

OLEDragDrop

Raised on the destination control when the user drops data on it.

Syntax: object_OLEDragDrop( Data As DataObject, Effect As Long, Button As Integer, Shift As Integer, X As Single, Y As Single )

OLEDragOver

Raised on the destination control while an OLE drag passes over it.

Syntax: object_OLEDragOver( Data As DataObject, Effect As Long, Button As Integer, Shift As Integer, X As Single, Y As Single, State As Integer )

OLEGiveFeedback

Raised on the source control during a drag so the application can adjust the cursor or other visual feedback.

Syntax: object_OLEGiveFeedback( Effect As Long, DefaultCursors As Boolean )

OLESetData

Raised on the source control when the destination requests data in a format that was registered but not yet supplied.

Syntax: object_OLESetData( Data As DataObject, DataFormat As Integer )

OLEStartDrag

Raised on the source control at the start of an OLE drag, so the application can populate the DataObject and choose the allowed effects.

Syntax: object_OLEStartDrag( Data As DataObject, AllowedEffects As Long )