LabelW class

A LabelW is a text that the program shows on a form and the user cannot edit. It has no window of its own: the form, or the container it is in, draws it.

The text Name of the author: on the ground of its form
Dim OldWidth As Single
LabelW1.Caption = "Name:"
LabelW1.AutoSize = True
OldWidth = LabelW1.Width
LabelW1.Caption = "Name of the customer:"
Debug.Print LabelW1.Width > OldWidth     ' the label has grown with its caption
' Output:
' True

The control stands in place of the Label of the VB package, the label of VB6. It holds its caption in Unicode, and adds SingleLine, EllipsisFormat with DisplayedCaption, MimicTextBox, and borders other than a single line.

Of the common members, the control has those under Name and place but HelpContextID, Font and FontQuality, Mouse, Dragging the control, OLE drag and drop and Right-to-left but RightToLeftLayout. It has no window, so it has neither hWnd nor hWndUserControl, and it never takes the focus, so it has no keyboard events.

LabelW or WindowedLabel

The package has the same label twice. WindowedLabel has the members of LabelW, with the same meanings, in a window of its own.

A LabelW is drawn on the window of its container. It costs no window, and with BackStyle set to CCBackStyleTransparent whatever the container draws behind it shows through. A control without a window is always behind the controls of its container that have one, and it has no handle to pass to an API function. Where the label must be in front of such a control, or a program needs its window handle, or another program reads the text of the form’s windows, a WindowedLabel is the one to use.

Lines, wrapping and size

The caption is drawn from the top left corner of the label, and a line break in it (vbCrLf) starts a new line. Three properties change that:

  • WordWrap also breaks a line between words where the label’s width ends.
  • SingleLine draws the whole caption on one line, line breaks included.
  • AutoSize changes the label’s size to fit the caption whenever the caption, the font or a property that changes the layout is set.
Three labels, each outlined in gray, with a caption of two lines whose second line is too long for the label: with WordWrap set to False the second line is cut at the right edge, with WordWrap set to True it goes on in a third line, and with SingleLine set to True both lines are on one line, cut at the right edge

WordWrap and SingleLine exclude each other. Setting SingleLine to True sets WordWrap to False, and setting WordWrap to True while SingleLine is True raises run-time error 383.

A label with AutoSize takes the width and the height of its caption. With WordWrap as well it keeps its width, unless one word is wider, and takes the height that the wrapped caption needs. The label grows away from the side that Alignment and VerticalAlignment name: a right-aligned label keeps its right edge, and a centered one its middle.

Dim OldRight As Single
LabelW1.Alignment = vbRightJustify
LabelW1.AutoSize = True
LabelW1.Caption = "Total:"
OldRight = LabelW1.Left + LabelW1.Width
LabelW1.Caption = "Total of all the orders:"
Debug.Print Abs(LabelW1.Left + LabelW1.Width - OldRight) < 20    ' the right edge has not moved
' Output:
' True

A caption too long for the label

A label without AutoSize shows as much of its caption as fits. EllipsisFormat makes it say that something is missing, by an ellipsis (...) at the end of the caption, in the middle of a file path, or at the end of a word. DisplayedCaption then returns the caption as the label last drew it, with the ellipsis.

LabelW1.AutoSize = False
LabelW1.SingleLine = True
LabelW1.EllipsisFormat = LblEllipsisFormatPath
LabelW1.Caption = "C:\Program Files\Some Vendor\Some Product\bin\program.exe"
LabelW1.ToolTipText = LabelW1.Caption        ' the whole path, for the mouse

Border and colors

BorderStyle draws a border inside the label’s rectangle, and BackStyle says whether the label fills its rectangle with BackColor first. The caption is drawn in ForeColor, or in the grey of disabled text while Enabled is False.

Appearance is a shortcut for the two looks of VB6. Setting it changes a border, if the label has one, to a single line for CCAppearanceFlat and to a sunken edge for CCAppearance3D, and sets ForeColor to vbWindowText or to vbButtonText. A program that wants another border or color sets it after Appearance.

LabelW1.BorderStyle = CCBorderStyleRaised
LabelW1.ForeColor = vbRed
LabelW1.Appearance = CCAppearanceFlat
Debug.Print LabelW1.BorderStyle = CCBorderStyleSingle
Debug.Print LabelW1.ForeColor = vbWindowText
' Output:
' True
' True

Properties

Alignment

Where each line of the caption stands in the label’s width. A member of AlignmentConstants: vbLeftJustify (the default), vbRightJustify or vbCenter. Another value raises run-time error 380.

Appearance

The look of the label. A member of CCAppearanceConstants. Default: CCAppearance3D. Another value raises run-time error 380. An assignment also sets ForeColor and changes a border: see Border and colors.

AutoSize

Whether the label changes its size to fit its caption. Boolean. Default: False. See Lines, wrapping and size. The size does not take EllipsisFormat into account.

BackColor

The color the label fills its rectangle with while BackStyle is CCBackStyleOpaque. OLE_COLOR. Default: vbButtonFace.

BackStyle

Whether the label fills its rectangle or lets what is behind it show. A member of CCBackStyleConstants. Default: CCBackStyleOpaque. Another value raises run-time error 380.

BorderStyle

The border of the label. A member of CCBorderStyleConstants. Default: CCBorderStyleNone. Another value raises run-time error 380. The border takes its width from the room the caption has.

Caption

The text of the label. String. A control newly drawn on a form has its own name. It is the control’s default property.

An assignment of another text raises Change. Assigning the text the label already has does nothing.

DisplayedCaption

The caption as the label last drew it: the caption itself, or, with an EllipsisFormat and a caption too long for the label, the caption with the ellipsis in place of what does not fit. String, read-only. It is empty until the label has been drawn on the screen.

EllipsisFormat

Whether and where the label puts an ellipsis in a caption that is too long for it. A member of LblEllipsisFormatConstants. Default: LblEllipsisFormatNone. Another value raises run-time error 380.

ForeColor

The color of the caption. OLE_COLOR. A control newly drawn on a form has black. An assignment to Appearance sets it again.

MimicTextBox

Whether the label lays its caption out as a multi-line text box does: a word too long for a line is broken between characters, and a last line that would show only in part is not drawn. Boolean. Default: False. It has an effect while WordWrap is True.

SingleLine

Whether the whole caption is drawn on one line. Boolean. Default: False. Setting it to True sets WordWrap to False. On one line, VerticalAlignment places the line in the label’s height.

UseMnemonic

Whether an ampersand (&) in the caption makes the character after it the label’s access key. Boolean. Default: True, with which that character is underlined, the ampersand is not drawn, and && draws one ampersand. With False the caption is drawn as it is.

VerticalAlignment

Where the caption stands in the label’s height. A member of CCVerticalAlignmentConstants. Default: CCVerticalAlignmentTop. Another value raises run-time error 380.

WordWrap

Whether a line that is too long for the label’s width is broken between words. Boolean. Default: False. Setting it to True while SingleLine is True raises run-time error 383.

Events

Change

Raised when Caption has changed.

Syntax: object_Change( )

LblEllipsisFormatConstants

The values of EllipsisFormat.

Four labels of one line, each outlined in gray, with a file path too long for them as the caption: in LblEllipsisFormatNone the path is cut at the right edge, in LblEllipsisFormatEnd and LblEllipsisFormatWord it ends in three dots, and in LblEllipsisFormatPath three dots take the place of its middle so that the file name shows
Member Value Description
LblEllipsisFormatNone 0 No ellipsis: the caption is cut where the label ends.
LblEllipsisFormatEnd 1 An ellipsis in place of the end of the caption.
LblEllipsisFormatPath 2 An ellipsis in the middle of the caption, so that as much as fits of what follows the last backslash still shows: for a file path.
LblEllipsisFormatWord 3 An ellipsis in place of the end of a word that does not fit.

See Also

  • Common members – the members this control shares with the package’s other controls
  • WindowedLabel – the same label in a window of its own
  • Label – the label of the VB package