SftPicture2 Documentation

SftPicture2 - Image and Text Description Header

SftPicture2 is the shared header that describes images, glyphs and text labels used by every Softel vdm DLL control (SftTree, SftTabs, SftBox, SftMask, SftButton). The two structures defined here - SFT_PICTURE and SFT_TEXT - appear as fields on per-product control structures (SFTBUTTON_CONTROL.Picture1, SFTTREE_CELL.Picture, SFTTABS_TAB.Picture, etc.) and supply a uniform model for image and text rendering across all DLL controls.

The header provides:

A type-tagged union (SFT_PICTURE) that can hold a bitmap, icon, image list entry, OLE picture, GDI+ image, .NET image, color sample, dimension placeholder, AVI animation, or one of seven built-in glyphs (check box, 3-state check box, radio button, up/down, sort indicator).
A text-rendering descriptor (SFT_TEXT) with font, color, alignment, orientation, optional GDI+ rendering hints, and a set of selection-outline flags.
Picture type constants (SFT_PICTURE_*) that select which member of the SFT_PICTURE union is meaningful.
Alignment constants (SFT_PICALIGN_*) that drive horizontal and vertical positioning of pictures and text within their slot.
Orientation constants (SFT_ORIENTATION_*), SFT_NOCOLOR, SFT_PICFLAG_FREE, SFT_IMAGEOVL_GHOSTED, and SFT_TEXT_* text-rendering flags.
A small library of inline helper functions (Sft_InitPicture, Sft_ClearPicture, Sft_CopyPicture, Sft_IsPicture*, Sft_SetPicture* and Sft_GetPicture*) that initialize, query and populate SFT_PICTURE slots without the caller manipulating the union directly.

Header inclusion

Per-product DLL headers (SftTree.h, SftTabs.h, SftBox.h, SftMask.h, SftButton.h) include SftPicture2.h automatically. Application code that uses any one of those product headers therefore has access to SFT_PICTURE, SFT_TEXT and the helper functions without an explicit #include "SftPicture2.h".

Direct inclusion is only needed in source files that work with picture / text descriptors but do not include any per-product header (rare).

Type discrimination

SFT_PICTURE is a type-tagged union: the type field selects which arm of the embedded Picture union is meaningful, and the Sft_SetPicture* setters keep both fields consistent with each other. Reading code can use the Sft_IsPicture* predicates instead of switching on type directly.

Per-product support: not every DLL control supports every SFT_PICTURE_* type. Each product's documentation lists the picture types it accepts.

Picture types

Constant	Slot	Description
SFT_PICTURE_BITMAP	Picture.hBitmap	A device-dependent bitmap. Top-left pixel is the transparent color.
SFT_PICTURE_ICON	Picture.hIcon	An icon of any size.
SFT_PICTURE_ICON_16x16	Picture.hIcon	Discontinued. 16x16 icon. New code should use SFT_PICTURE_ICON.
SFT_PICTURE_ICON_32x32	Picture.hIcon	Discontinued. 32x32 icon (alias for SFT_PICTURE_ICON). New code should use SFT_PICTURE_ICON.
SFT_PICTURE_IMAGELIST	Picture.Image	An entry in an image list. Holds the HIMAGELIST plus normal and disabled image indices.
SFT_PICTURE_IMAGELISTOVL	Picture.ImageOvl	An image list entry with an overlay image index.
SFT_PICTURE_IDISPATCH	Picture.IPicDisp	An OLE picture object accessed through IPictureDisp.
SFT_PICTURE_IPICTURE	Picture.IPic	An OLE picture object accessed through IPicture.
SFT_PICTURE_GDIPLUS	Picture.GDIPlusImage.lpImageObject	A GDI+ image (PNG, TIFF, JPEG, GIF, EMF+).
SFT_PICTURE_NET	Picture.NETImage.pUnknown	A .NET System.Drawing.Image reference.
SFT_PICTURE_AVI	Picture.hwndAnim	An AVI clip hosted in a Microsoft Animation control. The HWND of the animation control.
SFT_PICTURE_COLOR_SAMPLE	Picture.ColorSample	A solid color swatch with optional border. Width / height / sample color / frame color.
SFT_PICTURE_SIZEONLY	Picture.Dimension	A layout placeholder that reserves space but draws nothing.
SFT_PICTURE_CB	Picture.CheckBox	A two-state check box glyph (state 0 / 1).
SFT_PICTURE_CB3	Picture.CheckBox	A three-state check box glyph (state -1 / 0 / 1).
SFT_PICTURE_RB	Picture.CheckBox	A radio button glyph.
SFT_PICTURE_UPDOWN	Picture.CheckBox	An up / down arrow glyph.
SFT_PICTURE_UPDOWNSORT	Picture.CheckBox	A sort-direction indicator (up = ascending, down = descending).

Functions

Function	Description
Sft_InitPicture	Zero a SFT_PICTURE so it represents an empty slot.
Sft_ClearPicture	Reset a SFT_PICTURE without releasing the resources it referenced.
Sft_CopyPicture	Copy one SFT_PICTURE to another (handles / COM pointers copied verbatim).
Sft_IsPicture	Return TRUE if the slot is non-empty.
Sft_IsPictureBitmap / Icon / etc.	Type-specific predicates - one per supported picture type.
Sft_SetPictureBitmap	Store an HBITMAP.
Sft_SetPictureIcon	Store an HICON (any size, 16x16, or 32x32 variants).
Sft_SetPictureImageList	Store an image list reference (with or without overlay).
Sft_SetPictureColorSample	Store a color swatch.
Sft_SetPictureIDispatch	Store an IPictureDisp pointer.
Sft_SetPictureIPicture	Store an IPicture pointer.
Sft_SetPictureAnimate	Store the HWND of an AVI animation control.
Sft_SetPictureSizeOnly	Store a dimension-only placeholder.
Sft_SetPictureCheckBox	Store a two-state or three-state check box glyph.
Sft_SetPictureRadioButton	Store a radio button glyph.
Sft_SetPictureUpDown	Store an up/down or sort-direction glyph.
Sft_SetPictureGDIPlusImage	Store a Gdiplus::Image* pointer.
Sft_SetPictureNETImage	Store an IUnknown* for a .NET image.
Sft_GetPictureSize	Return the picture's pixel width and height.
Sft_InitText	Zero a SFT_TEXT structure.

Constants

Constant family	Page	Purpose
SFT_PICTURE_*	Picture type constants	Selects which member of SFT_PICTURE.Picture is meaningful.
SFT_PICALIGN_*	Alignment constants	Horizontal and vertical alignment for pictures and text within a slot.
SFT_ORIENTATION_*	Orientation constants	Horizontal vs vertical text orientation.
SFT_PICFLAG_FREE	SFT_PICFLAG	Internal ownership marker on SFT_PICTURE.flag1.
SFT_IMAGEOVL_GHOSTED	SFT_IMAGEOVL	Style flag for the image-list overlay variant.
SFT_NOCOLOR	SFT_NOCOLOR	Sentinel COLORREF meaning "use the default".
SFT_TEXT_*	Text flags	Selection-outline / background flags on SFT_TEXT.flag2.
SFTPICTURE_VERSION	SFTPICTURE_VERSION	Header revision identifier.

Structure layout

Structure	Page	Purpose
SFT_PICTURE	SFT_PICTURE Structure	Image / picture / glyph descriptor.
SFT_TEXT	SFT_TEXT Structure	Text label descriptor (caption, font, color, alignment, GDI+ hints).

Resource ownership

Resources stored in a SFT_PICTURE - HBITMAP, HICON, HIMAGELIST, IPicture pointers, GDI+ Image objects, .NET IUnknown pointers, animation HWNDs - remain owned by the application. The helper functions never destroy handles or release COM references. Sft_ClearPicture only zeroes the structure. The application must keep its resources alive for as long as a SftXxx control might use them (typically until the control is destroyed) and is responsible for releasing them itself.

Per-product caveat

Not every DLL product supports every picture type. SftButton/DLL accepts SFT_PICTURE_GDIPLUS, SFT_PICTURE_BITMAP and SFT_PICTURE_ICON for its image slots; SftTree/DLL adds SFT_PICTURE_CB / RB / UPDOWN glyphs for its built-in cell renderers; SftTabs/DLL accepts a smaller subset for tab-label images; and so on. Each per-product help file lists the supported types for that product's image fields.

Documentation

DLL-Based Controls

ActiveX Controls

.NET Controls

Support