The Label Widget
Author: Roland Krause 2002, roland_krause@freenet.de
Description: Documentation to XawPlus

### _________________________________________________________XawPlus

### The Label Widget

Application Header file Class Header file Class Class Name Superclass | <X11/XawPlus/Label.h> <X11/XawPlus/LabelP.h> labelWidgetClass Label Simple

A Label widget is a text string or bitmap displayed within a rectangular region of the screen. The label may contain multiple lines of characters. The Label widget will allow its string to be left, right, or center justified. Normally, this widget can be neither selected nor directly edited by the user. It is intended for use as an output device only.

### Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the Label widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is grey75. The bitmap and leftBitmap resources also provides support of XPM styled pixmaps. These pixmaps may be nonrectangular, using the clipMask or the leftClipMask resource. Label has installed converters to supply these resources from the resource database.

Label has a truncate mechanism for label strings, which are too long for the labels window. Those strings will be truncated from the left or from the right side, dependent on the resource truncLeftSide. Default is to truncate from the right side. It is possible to deactivate this mechanism with the the resource truncateLabel. This feature is not very useful for multiline labels and therefore not supported.

With release 3.0 of XawPlus full UNICODE support is available using the encoding resource. UNICODE support works independent of the locale settings and requires UTF8 coded label strings. Since it is not possible to put UNICODE directly in resource files, UTF8 code is used to avoid problems with the resource manager.

### Resources

When creating a Label widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

Name | Class | Type | Default Value
OBJECT: |  |  |
destroyCallback | Callback | Pointer | NULL
RECTANGLE: |  |  |
borderWidth height sensitive width x y | BorderWidth Height Sensitive Width Position Position | Dimension Dimension Boolean Dimension Position Position | 0 12 True 12 0 0
CORE: |  |  |
border background mappedWhenManaged | BorderColor Background MappedWhenManaged | Pixel Pixel Boolean | XtDefaultForeground grey75 True
SIMPLE: |  |  |
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth | Cursor Cursor Foreground Background Insensitive International Background Background Width | Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension | None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
LABEL: |  |  |
font fontset encoding foreground internalHeight internalWidth justify resize truncateLabel truncLeftSide label leftBitmap leftClipMask bitmap clipMask | Font FontSet Encoding Foreground Height Width Justify Resize Truncate Truncate Label LeftBitmap LeftBitmap Pixmap Pixmap | XFontStruct* FontSet unsigned char Pixel Dimension Dimension XtJustify Boolean Boolean Boolean String Bitmap ClipMask Bitmap ClipMask | XtDefaultFont XtDefaultFontSet XawTextEncoding8bit XtDefaultForeground 2 4 XtJustifyCenter True True False NULL None None None None

internalHeight, internalWidth | These resources defines the internal border width between the label string or the bitmap and the border of this widget.
justify | Defines how to jusify a label string in a label widget (left, right or centered).
resize | Defines how to handle a resize event after creation of the widget. Default is to handle every resize event and to justify the labels interiors.
truncateLabel | Defines what to do with a label string, if it is too long. Default is to truncate the string until it fits into the widgets window.
truncateLeftSide | Defines to truncate a too long label string from the left side. In this case the strings starts with two dots and the end of the string remains visible. Default ist to cut it from the right side.
font | With this resource it is possible to set any available font to display the label text.
fontset | A set of fonts which will be used, if the international resource is set.
encoding | Two types of encoding are available, the default 8 bit encoding and the 16 bit encoding (unicode). With 16 bit encoding the label string is expected in UTF8 and displayed with the font found in the font resource. The handling of UNICODE is independent of the locale settings. Note that the character codes from 0x00 to 0x7f are also valid as UTF8 code. For this range of characters every editor is usable to edit label strings. If you need character codes in the range from 0x80 to 0xffff a special editor like yudit is required. If any malformed UTF8 code is found, it is displayed as an asterix *. If the UTF8 code of a character is out of range (higher than 0xffff), it is displayed as a tilde sign.
foreground | This is the foreground color, used to display a label text.
label | Defines the label text. It is not possible to use both a label and a bitmap, but it is possible to use a label with a leftBitmap.
leftBitmap | This resource defines a bitmap or a XPM styled pixmap, placed left of the label text. XPM pixmaps are detected through their filename extension .xpm.
leftClipMask | This resource defines a bitmap or a XPM styled pixmap, used as a clip mask for the leftBitmap resource. If the background color of an XPM pixmap is defined as None, it is usable as bitmap and as a clip mask. Otherwise the user needs a second bitmap, if a clip mask is required.
bitmap | Defines a bitmap or a XPM styled pixmap to display in the label widget. It is not possible to use a bitmap together with a label or a leftBitmap.
clipMask | This resource defines a bitmap or a XPM styled pixmap, used as a clip mask for the bitmap resource.

### Convenience Routines

Since XawPlus 2.1 there is a new function to control the truncate mechanism. In Label the truncate mechanism is only activated, if it is a Label itself and not the superclass of another widget. The reason is, that derived widgets have another idea how to place the label interiors correctly.

> void TruncateLabelString(lw, usableWidth)
> LabelWidget lw;
> int usableWidth;

> lw | Specifies the Label widget.
> usableWidth | Specifies the usable window width inside of the label.

### XawPlus_________________________________________________________