PtLabel

`PtLabel`

A text, bitmap, or image label

Class hierarchy:

PtWidget --> PtBasic --> PtLabel

For more information, see the diagram of the widget hierarchy.

The PtLabel class provides a text string, bitmap, or image for labeling other widgets. When you use PtLabel to display a bitmap or image, you can have text pop up in a balloon to provide further meaning to the image.

PtLabel

A text string in a PtLabel widget.

As their name implies, labels are tags attached to objects to identify their name or nature. Label widgets are usually positioned beside the other widget they're describing, although in some cases (e.g. lists), the label will appear above the object.

There's no limit to the number of places you may wish to use label objects, but the most frequent use is to identify the name of an input field. For example, a mail program must provide input fields for indicating the recipient and the subject of a mail message being composed. The label widget lets you attach "To:" and "Subject:" tags to those input fields.

Labels aren't restricted to textual tags either. If you want to put a graphical representation such as an icon beside an object, you may use an image as the label.

Creating labels

You create labels using the PtLabel widget class. You can use text and images for the label. The default label type is a null-terminated text string.

To specify the type of label you want, you must use the Pt_ARG_LABEL_TYPE resource. The possible values for this resource are:

Pt_Z_STRING: The label is a null-terminated ASCII string. This is the default.
Pt_IMAGE: The label should be an image, typically a small icon. The data for the widget is an image structure.
Pt_TEXT_IMAGE: The label will display an image and text. The positioning of these two elements relative to each other is determined by the Pt_ARG_BALLOON_POSITION resource.

The data for the label is specified in different ways for each type. Different resources are used for the label data for different label types. This is particularly useful when you wish to switch quickly between image labels and text labels, so you can give the user a choice between using icons and textual descriptions of operations.

At the push of a button, the user can switch your interface from an iconic representation of commands (like the palette in the Photon Application Builder) to a textual representation of the same labels. The label is switched from an icon to text simply by changing the label type resource.

Text labels

When the label type is textual, the label widget gets the text to be displayed from the Pt_ARG_TEXT_STRING resource.

To specify the font the label should be drawn with when text labels are used, set the resource Pt_ARG_TEXT_FONT to the name of the font you want.

The label widget defines its own margins in addition to the margin width defined by the PtBasic widget class. There are separate left, right, top, and bottom margins, which are specified using these resources:

Pt_ARG_MARGIN_LEFT
Pt_ARG_MARGIN_RIGHT
Pt_ARG_MARGIN_TOP
Pt_ARG_MARGIN_BOTTOM

These margins are cumulative, so that the actual margin of one edge of the widget is the corresponding resource value added to the margin width.

The text label may be aligned independently to the left or right margin, or centered horizontally within the margins of the widget. The Pt_ARG_HORIZONTAL_ALIGNMENT resource controls this behavior. The values to specify for this horizontal alignment are:

Pt_LEFT - text is aligned to the left margin.
Pt_RIGHT - text is aligned to the right margin.
Pt_CENTER - text is centered between the left and right margins.

You can also control the vertical alignment, i.e. whether the text is aligned to the widget's top or bottom margin, or centered vertically between the two margins. The Pt_ARG_VERTICAL_ALIGNMENT resource controls this behavior. The values to specify for the vertical alignment are:

Pt_TOP -text is aligned to the top margin.
Pt_BOTTOM - text is aligned to the bottom margin.
Pt_CENTER - text is centered between the top and bottom margins.

Normally, the text displayed in the label widget will be aligned to the widget's top and left margins. The baseline is calculated by adding the ascender of the label font to the top margin. When text is aligned to the bottom of the widget, the baseline is calculated by subtracting the descender of the label font from the widget's bottom margin.

You can align the baselines of labels drawn with different fonts by selecting bottom alignment for each of the widgets and choosing appropriate margins for them. In this case, make sure you specify a widget height large enough to accommodate the height of the largest font used.

The desired baseline for your aligned widgets will be adjusted by the size of the maximum descender of all the fonts used. For each label, add the difference between this descender and the descender of that label's font, then add this difference to the widget's bottom margin. Keep track of this value so that you can recalculate the correct margin setting if you want to change the base margin or the font later on.

Image and bitmap labels

When the label is an image, the label widget gets the image from the Pt_ARG_LABEL_DATA resource, which contains a pointer to an image structure, of type PhImage_t, which is described in the Photon Library Reference.

The members of the image structure used by the label and button widgets are:

type

Specifies the type of image. This determines which other members of the image structure are significant and defines the format of the raw image data.

Images can be palette-based or raw. Palette-based images, including bitmaps, have a color palette that serves as a lookup table for determining what color should be displayed for each pixel. Each pixel in the image is encoded as an index into the lookup table, and the pixel is displayed using the color contained in the corresponding table entry.

Raw images have actual RGB color values encoded in the image data.

More than one pixel may be encoded in each byte of the image data, so image-scan lines are padded out to a byte boundary.

Bitmaps are encoded with 1 bit-per-pixel. The bit ordering is most significant bit first. The two types of bitmap are:

Pg_BITMAP_BACKFILL - a bitonal image - the two colors are specified in the color palette.
Pg_BITMAP_TRANSPARENT - a monochrome image with transparent regions. "Ones" in the image data are drawn using color palette entry 1; zeros are treated as transparent, so they're not drawn.

The other types of palette-based images are:

Pg_IMAGE_PALETTE_BYTE - palette-based image encoded as 8 bits-per-pixel.
Pg_IMAGE_PALETTE_NIBBLE - palette-based image encoded as 4 bits-per-pixel. The most significant nibble in a byte specifies the leftmost pixel. The bit ordering within a nibble is most significant bit first.

Raw images are all encoded using 16, 24, or 32 bits-per-pixel. The types of raw images are:

Pg_IMAGE_DIRECT_8888 - raw image with 8 bits each for blue, green, and red (with an additional 8 bits reserved).
Pg_IMAGE_DIRECT_888 - raw image with 8 bits each for blue, green, and red.
Pg_IMAGE_DIRECT_664 - raw image with 6 bits each for green and red, and 4 bits for blue.
Pg_IMAGE_DIRECT_555 - raw image with 5 bits each for blue, green, and red.

bpl

The number of bytes used to encode each scan line. This depends on the image type and size.

size

The width and height of the image in pixels.

colors

The number of colors used in the image for palette-based images. It is used for determining how many color palette entries are significant.

palette

The color lookup table for determining the color of each pixel in the image.

image

The raw image data.

For more information about manipulating images and image data formats, see the Photon Programmer's Guide.

Balloons

Balloons are a very handy feature of the PtLabel widget class. You use a balloon to display a line of text when the user's pointer pauses on top of a widget for more than a second.

This can be very useful in an application with a lot of labels or buttons containing iconic images. Whenever the user pauses on an icon, a little text box will pop up beside it to display the name or action the icon represents.

To use balloons with label class widgets:

Set the Pt_SHOW_BALLOON flag for the Pt_ARG_LABEL_FLAGS resource.
Set the Pt_ARG_BALLOON_POSITION resource to define the location.

The Pt_ARG_TEXT_STRING resource defines the text displayed in the balloon. If the entire string is visible within the widget, you probably don't need to set the Pt_SHOW_BALLOON flag. If the label has been truncated or is currently displaying an iconic image, you can set the flag and the balloon feature will be automatically enabled for the widget.

New resources:

Resource	C type	Pt type	Default
Pt_ARG_ACCEL_KEY	`char *`	String	NULL
Pt_ARG_BALLOON_COLOR	`PgColor_t`	Scalar	Pg_BLACK
Pt_ARG_BALLOON_FILL_COLOR	`PgColor_t`	Scalar	Pt_BALLOONCOLOR
Pt_ARG_BALLOON_POSITION	`short`	Scalar	Pt_BALLOON_RIGHT
Pt_ARG_HORIZONTAL_ALIGNMENT	`unsigned char`	Scalar	Pt_LEFT
Pt_ARG_LABEL_BALLOON	`PtWidget_t * (*)()`	Pointer	Pt_INFLATE_BALLOON
Pt_ARG_LABEL_DATA	`void *`	Alloc	NULL
Pt_ARG_LABEL_FLAGS	`char`	Flag	Pt_LABEL_SELECT_SHIFT
Pt_ARG_LABEL_TYPE	`char`	Scalar	Pt_Z_STRING
Pt_ARG_LINE_SPACING	`ushort_t`	Scalar	0
Pt_ARG_MARGIN_BOTTOM	`unsigned short`	Scalar	0
Pt_ARG_MARGIN_LEFT	`unsigned short`	Scalar	0
Pt_ARG_MARGIN_RIGHT	`unsigned short`	Scalar	0
Pt_ARG_MARGIN_TOP	`unsigned short`	Scalar	0
Pt_ARG_TEXT_FONT	`char *`	String	`"helv12"`
Pt_ARG_TEXT_STRING	`char *`	String	NULL
Pt_ARG_UNDERLINE1	`unsigned short`	Scalar	Pg_BLACK
Pt_ARG_UNDERLINE2	`unsigned short`	Scalar	Pg_TRANSPARENT
Pt_ARG_UNDERLINE_TYPE	`unsigned short`	Scalar	Pt_NO_ULINE
Pt_ARG_VERTICAL_ALIGNMENT	`unsigned char`	Scalar	Pt_CENTER

Pt_ARG_ACCEL_KEY

C type	Pt type	Default
`char *`	String	NULL

Lets you underline the accelerator key within the widget's text string. You typically use this resource for hotkeys.

Pt_ARG_BALLOON_COLOR

C type	Pt type	Default
`PgColor_t`	Scalar	Pg_BLACK

Defines the balloon's text color.

Pt_ARG_BALLOON_FILL_COLOR

C type	Pt type	Default
`PgColor_t`	Scalar	Pt_BALLOONCOLOR

Defines the balloon's fill color.

Pt_ARG_BALLOON_POSITION

C type	Pt type	Default
`short`	Scalar	Pt_BALLOON_RIGHT

Indicates where the label text will pop up. If Pt_ARG_LABEL_TYPE is Pt_TEXT_IMAGE, this reource controls the positioning of the text and image elements relative to each other. Possible values:

Pt_BALLOON_INPLACE
Pt_BALLOON_TOP
Pt_BALLOON_LEFT
Pt_BALLOON_RIGHT
Pt_BALLOON_BOTTOM

Pt_ARG_HORIZONTAL_ALIGNMENT

C type	Pt type	Default
`unsigned char`	Scalar	Pt_LEFT

The horizontal alignment for the text string. Possible values:

Pt_LEFT
Pt_CENTER
Pt_RIGHT

Pt_ARG_LABEL_BALLOON

C type	Pt type	Default
`PtWidget_t * (*)()`	Pointer	Pt_INFLATE_BALLOON

By default, when a user pauses the pointer over this widget, the widget will display a small yellow balloon. If you want to change the look or default text of the balloon, you can use this resource to override the default inflate function.

Here's a prototype of the inflate function:

PtWidget_t * InflateBalloon( PtWidget_t *window,
                             PtWidget_t *widget,
                             int position,
                             char *text,
                             char *font,
                             PgColor_t fill_color,
                             PgColor_t text_color );

where:

window: The window widget of the widget that requires the balloon.
widget: The widget that requires the balloon.
position: The balloon-position resource (see Pt_ARG_BITMAP_BALLOON_POSITION in PtBitmap).
text: The text to display (see Pt_ARG_BITMAP_TEXT in PtBitmap).
font: The font for the text.
fill_color: The fill color (see Pt_ARG_BITMAP_BALLOON_FILL_COLOR in PtBitmap).
text_color: The balloon-text color (see Pt_ARG_BITMAP_BALLOON_COLOR in PtBitmap).

You can use the supplied values in your inflate function or ignore them and use your own values.

Pt_ARG_LABEL_DATA

C type	Pt type	Default
`void *`	Alloc	NULL

A pointer. If the label type (see Pt_ARG_LABEL_TYPE, below) is Pt_IMAGE, this resource is used to pass data to the widget.

Remember that this is an Alloc resource. When you set this resource, the widget copies the PhImage_t structure but not the data pointed to by the members of the structure. After setting this resource, you can free() the PhImage_t if you don't need it, but don't free() the members of it.

Pt_ARG_LABEL_FLAGS

C type	Pt type	Default
`char`	Flag	Pt_LABEL_SELECT_SHIFT

Possible values:

Pt_BACKFILL_TEXT: If this is set, the widget fills the text background with the widget's fill color before rendering the text.
Pt_LABEL_SELECT_SHIFT: If this is set, the text shifts down and to the right by one pixel when the widget is armed. Otherwise, the text doesn't shift.
Pt_SHOW_BALLOON: If the pointer remains motionless for 1.25 seconds over the label, a balloon pops up with the label's text.
Pt_BALLOON_AS_REQUIRED: Same as Pt_SHOW_BALLOON, except the balloon is inflated only if the label is clipped by its parent container.

Pt_ARG_LABEL_TYPE

C type	Pt type	Default
`char`	Scalar	Pt_Z_STRING

The type of information displayed by the label. Possible values:

Pt_Z_STRING

Use Pt_ARG_TEXT_STRING to display the text.

Pt_IMAGE

Use Pt_ARG_LABEL_DATA to display an image. See PhImage_t, in the Photon Library Reference.

Set the flags member of the PhImage_t structure to:

Ph_RELEASE_IMAGE | Ph_RELEASE_PALETTE |
Ph_RELEASE_TRANSPARENCY_MASK | Ph_RELEASE_GHOST_BITMAP

before providing the image to the widget. If you do this, the memory used for the image is released when the widget is unrealized or destroyed.

Pt_TEXT_IMAGE

Display the image and text of the label. The positioning of these two elements relative to each other is determined by the Pt_ARG_BALLOON_POSITION resource.

Pt_ARG_LINE_SPACING

C type	Pt type	Default
`ushort_t`	Scalar	0

The space, in pixels, between the lines of text in the label.

Pt_ARG_MARGIN_BOTTOM

C type	Pt type	Default
`unsigned short`	Scalar	0

The amount of space between the bottom of the label's canvas and the canvas defined by the basic widget.

Pt_ARG_MARGIN_LEFT

C type	Pt type	Default
`unsigned short`	Scalar	0

The amount of space between the left side of the label's canvas and the canvas defined by the basic widget.

Pt_ARG_MARGIN_RIGHT

C type	Pt type	Default
`unsigned short`	Scalar	0

The amount of space between the right side of the label's canvas and the canvas defined by the basic widget.

Pt_ARG_MARGIN_TOP

C type	Pt type	Default
`unsigned short`	Scalar	0

The amount of space between the top of the label's canvas and the canvas defined by the basic widget.

Pt_ARG_TEXT_FONT

C type	Pt type	Default
`char *`	String	`"helv12"`

The font used for the label's text string; see PgSetFont().

Pt_ARG_TEXT_STRING

C type	Pt type	Default
`char *`	String	NULL

The text string to be displayed if Pt_ARG_LABEL_TYPE is Pt_Z_STRING or Pt_TEXT_IMAGE.

Pt_ARG_UNDERLINE1

C type	Pt type	Default
`unsigned short`	Scalar	Pg_BLACK

The underline color for the first line.

Pt_ARG_UNDERLINE2

C type	Pt type	Default
`unsigned short`	Scalar	Pg_TRANSPARENT

The underline color for the second line (used to create thick or beveled underlines).

Pt_ARG_UNDERLINE_TYPE

C type	Pt type	Default
`unsigned short`	Scalar	Pt_NO_ULINE

The type of underline. Possible values:

Pt_NO_ULINE
Pt_DOUBLE_ULINE (use with underline color)
Pt_SINGLE_ULINE (use with underline color)
Pt_ULINE_ETCHED_IN (use with border color)
Pt_ULINE_ETCHED_OUT (use with border color)

Pt_ARG_VERTICAL_ALIGNMENT

C type	Pt type	Default
`unsigned char`	Scalar	Pt_CENTER

The vertical alignment for the text string. Possible values:

Pt_TOP
Pt_CENTER
Pt_BOTTOM

Inherited resources:

If the widget modifies an inherited resource, the "Default override" column indicates the new value. This modification affects any subclasses of the widget.

Resource	Inherited from	Default override
Pt_ARG_AREA	`PtWidget`
Pt_ARG_BANDWIDTH_THRESHOLD	`PtBasic`	Not used by this class.
Pt_ARG_BITMAP_CURSOR	`PtWidget`
Pt_ARG_BORDER_WIDTH	`PtWidget`
Pt_ARG_BOT_BORDER_COLOR	`PtBasic`
Pt_ARG_COLOR	`PtBasic`
Pt_ARG_CURSOR_COLOR	`PtWidget`
Pt_ARG_CURSOR_TYPE	`PtWidget`
Pt_ARG_DATA	`PtWidget`
Pt_ARG_DIM	`PtWidget`
Pt_ARG_EFLAGS	`PtWidget`
Pt_ARG_FILL_COLOR	`PtBasic`
Pt_ARG_FILL_PATTERN	`PtBasic`
Pt_ARG_FLAGS	`PtWidget`
Pt_ARG_HELP_TOPIC	`PtWidget`
Pt_ARG_HIGHLIGHT_ROUNDNESS	`PtBasic`
Pt_ARG_MARGIN_HEIGHT	`PtBasic`	2
Pt_ARG_MARGIN_WIDTH	`PtBasic`	2
Pt_ARG_POS	`PtWidget`
Pt_ARG_RESIZE_FLAGS	`PtWidget`	Pt_RESIZE_XY_AS_REQUIRED
Pt_ARG_TOP_BORDER_COLOR	`PtBasic`
Pt_ARG_TRANS_PATTERN	`PtBasic`
Pt_ARG_USER_DATA	`PtWidget`
Pt_CB_ACTIVATE	`PtBasic`
Pt_CB_ARM	`PtBasic`
Pt_CB_BLOCKED	`PtWidget`
Pt_CB_DESTROYED	`PtWidget`
Pt_CB_DISARM	`PtBasic`
Pt_CB_GOT_FOCUS	`PtBasic`
Pt_CB_HOTKEY	`PtWidget`
Pt_CB_LOST_FOCUS	`PtBasic`
Pt_CB_MENU	`PtBasic`
Pt_CB_RAW	`PtWidget`
Pt_CB_REALIZED	`PtWidget`
Pt_CB_REPEAT	`PtBasic`
Pt_CB_UNREALIZED	`PtWidget`

QNX Community Resources