Next: , Previous: , Up: Classes   [Index]

X11LabelPane

X11LabelPane Class

X11LabelPane objects display text in graphical windows. The class provides instance variables and methods that control the label’s font, border, justification, whether the label is highlighted when the pointer is over it, and formatting of single and multiple line labels.

Formatting label text for multiple line labels, as well as controlling the text’s justification, is described in the subsections below.

Here is a simple example program that displays a X11LabelPane widget. 


#include <ctalk/ctalkdefs.h>

#define FTFONTS    /* Comment this line out to use X fonts. */
#define MULTILINE  /* Comment out to display a single line label. */
#define ROUNDED    /* Comment out to draw borders with straight edges. */

int main (int argv, char **argc) {
  X11Pane new xPane;
  X11PaneDispatcher new xTopLevelPane;
  X11LabelPane new xLabelPane;
  InputEvent new e;
  Exception new ex;

#ifdef FTFONTS 
  xPane ftFontVar initFontLib;
  xLabelPane resources replaceAt "ftFont", "DejaVu Sans-12:bold";
  xLabelPane selectFont;
#endif       

  xLabelPane resources replaceAt "backgroundColor", "white";

  xPane initialize 0, 0, 300, 300;
  xPane inputStream eventMask =
    WINDELETE|EXPOSE|ENTERWINDOWNOTIFY|LEAVEWINDOWNOTIFY;
  xTopLevelPane attachTo xPane;
  xLabelPane attachTo xTopLevelPane, "150x150+c+50";
  xPane map;
  xPane raiseWindow;

  xPane openEventStream;

#ifndef FTFONTS
  xLabelPane font "-*-helvetica-medium-r-*-*-*-120-*-*-*-*-*-*";
#endif

#ifdef MULTILINE
  xLabelPane multiLine "Labels\ncan occupy\nmultiple\nlines.";
#else
  xLabelPane text "A Label";
#endif

#ifdef ROUNDED
  xLabelPane radius = 10;
#endif  

  xLabelPane draw;
  
  while (TRUE) {
    xPane inputStream queueInput;
    if (xPane inputStream eventPending) {
      e become xPane inputStream inputQueue unshift;
      xPane subPaneNotify e;  /* Call the classes' event handlers. */
      if (ex pending)
	ex handle;
      
      switch (e eventClass value)
     	{
     	case WINDELETE:
      	  xPane deleteAndClose;
     	  exit (0);
     	  break;
     	default:
     	  break;
     	}
    }
  }
}

Multiple Line Labels

If the label’s text contains embedded newline ‘\n’ characters, and the text is defined using the multiLine method, below, then the text is display on multiple lines, with the breaks appearing where the newline characters appear in the text. The text is displayed centered vertically, and justified as described in the next section.

For single line labels, use the text method with a String argument to fit on one line.

Justification

The X11LabelPane widget contains a simple layout engine that can center label text, or justify it against the right or left margins.

The text’s justification is determined by the setting of the justification instance variable, which can have one of three values, which are defined by the following macros: 


LABEL_LEFT
LABEL_RIGHT
LABEL_CENTER

These macros are defined in the ctalk/ctalkdefs.h include file. To use them, add the line 


#include <ctalk/ctalkdefs.h>

to the beginning of the source module.

The widget calculates the right and left margins as the following: 


(aLabel margin) + (aLabel highlightBorderWidth) + (aLabel padding)

The highlighted border width is included regardless of whether the border actually is drawn or the label is hightlighted, so text alignment remains constant if a program draws and then obscures the border, or when the pointer passes over the label.

Resources

The resources that X11LabelPane : new defines by default are stored in the resources instance variable, an AssociativeArray that is declared in X11Pane class. For a description, see the resources instance variable documentation. See PaneResources.

boldFont

The font that the label uses for highlighting text by printing in bold type.

font
ftFont

A String that contains the text font’s Fontconfig font descriptor. The default is ‘sans serif-12’.

Note that the class still checks for the ‘ftFont’ resource for compatibility with previous versions, but the class now uses the ‘font’ resource to make int consistent with other classes.

For more information about Fontconfig descriptors, refer to the X11FreeTypeFont class. See X11FreeTypeFont.

backgroundColor

A String that contains the pane’s background color. This is the color of the pane’s X subwindow, so it is generally useful to set this to the color of the surrounding window, if you want the label to blend in with its surrounding drawing area.

borderColor

A String that contains the name of the pane’s border color. The default is black

An Integer that contains the line width the pane’s border. The default is ‘1’.

foregroundColor

A String that contains the name of the color that fills the pane’s visible area. The default is ‘white’.

grayedColor

The color of the text and border when the pane is grayed. The default is gray.

highlightBorderColor

The color of the border when the pane is highlighted. The default is ‘black’.

highlightBorderWidth

The width of the border when the pane is highlighted the default is ‘2’.

highlightForegroundColor

A String that contains the color name of the pane’s visible area when it the pane is in a highlighted state, which is generally when the pointer is over the pane’s window area. The default is ‘orange’.

highlightTextBold

A Boolean that causes the label to display its text in a bold font when the label is highlighted, if the font library supports it. The default is ‘false’.

highlightTextColor

A String that contains the text color when the pane is in a highlighted state, generally when the pointer is over the pane. The default is black.

textColor

A String that contains the text color when the pane is not highlighted. The default is ‘black’.

xFont

A String that contains the text fonts X Logical Font Descriptor. Refer to xfontsel(1) and xlsfonts(1) for information about XLFD’s. The default is ‘fixed’.

Instance Variables

boldFont

A X11FreeTypeFont object that the label uses to highlight text by printing it in boldfaced text.

border

A Boolean that controls whether the label displays a border. The default is ‘true’.

borderColor

A String that contains the name of the border’s color if the label displays a border. The default is ‘black’.

borderWidth

An Integer that defines the width of the border in pixels when the widget is not highlighted. The default is ‘2’.

grayed

A Boolean that determines whether to draw the widget in a grayed, or inactive, state. The state has no other effect for a X11LabelPane object. It can indicate the state of other controls in the window. The default is false.

grayedColor

A String that contains the name of the color to draw the widget when it is grayed. The default is is ‘gray’.

haveMultiLine

A Boolean that indicates whether the widget’s text is defined using the multiLine method, and indicates that the widget should format the label’s text to span multiple lines.

highlightBackgroundColor

A String that contains the color to draw a highlighted label’s background.

highlightBorderColor

A String that contain’s the name of a highlighed border’s color. The default is ‘black’.

highlightBorderWidth

An Integer that determines the width in pixels of the label’s border when the widget is highlighed. The default is two pixels.

highlightTextColor

A String that contains the name of the text color when the widget is drawn highlighted. The default is ‘black’.

initialized

A Boolean that indicates that the widget has initialized its instance variable states from the resource values. Normally, a class does this in an attachTo method, but this class uses the superclasses’ attachTo methods, so the class uses this to perform the initialization on the first call to the draw method.

justify

An Integer that determines whether to draw the label’s text centered horizontally, or justified on the right or left margins.

This variable recognizes three values, which are #defines in the ctalk/ctalkdefs.h include file. The definitions are: 


LABEL_LEFT
LABEL_CENTER
LABEL_RIGHT

To use these macros, add the statement 


#include <ctalk/ctalkdefs.h>

near the top of the source module.

leading

An Integer that defines the space between lines of a multi-line label. This variable only affects text drawn using scalable fonts of the Freetype library. X11 bitmap fonts contain the leading in the character glyphs.

lineHeight

An Integer that contains the label’s font height + the leading.

margin

An Integer that defines the distance in pixels between the border and the edges of the X11LabelPane object.

padding

An Integer that defines the minimum distance in pixels between the inner edge of the border and the pane object’s text.

parHeight

For multi-line labels, an Integer that contains the height of all of the lines of text. For single-line labels, the lineHeight and parHeight are the same.

radius

An Integer that describes the radius to round the corners of the border with. If the value is ‘0’ (the default), then draw borders with straight edges.

textColor

A String that defines the name of the text color when the widget is not highlighted. The default is ‘black’.

textLine

A String that contains the label’s text if the text is to appear on a single line. The default is an empty string.

textLines

An Array that contains a multi-line widget’s text, as set using the multiLine method.

Instance Methods

draw (void)
drawButtonLayout (void)

Draws the text of the label, and updates the visible label on the display. The instance variables in this class and the text font’s class allow programs to adjust how the text is laid out.

The drawButtonLayout method is similar, but it uses a different algorithm that is more suited to laying out text on button labels.

If the widget has saved a font specification to its ftFontVar instance variable, then this method also selects the font before drawing the label. If you want a label to have a different font than the rest of the window, this is how to declare and save a font specification. 


/* The label inherits the ftFont method from X11Pane class. */

label ftFont "DejaVu Sans", FTFONT_ROMAN, FTFONT_MEDIUM, DEFAULT_DPI, 10.0;
label ftFontVar saveSelectedFont;

The X11FreeTypeFont section describes the parameters that the X11FreeTypeFont class uses when selecting fonts. See X11FreeTypeFont.

new

Creates a new X11LabelPane object, initializes the object’s instance variables and event handlers, and sets the pane’s default foreground and background colors.

selectFontOld (void)

This method was formerly named selectFont, although it has been superceded by X11CanvasPane : selectFont.

subPaneExpose (Object subPane, InputEvent event)

The widget’s Expose event handler. When the widget receives an Expose event, this method redraws the widget.

subPaneEnter (Object subPane, InputEvent event)
subPaneLeave (Object subPane, InputEvent event)

The widget’s EnterNotify and LeaveNotify event handlers. These methods set the subPane's highlight instance variable to true or false (if the widget is configured to accept input focus), then calls the draw method to redraw the label.

subPaneResize (Object subPane, InputEvent event)

Handles resize events received from the display server.

font (String fontdesc)

Sets the X11 font to use for the label’s text. When drawing using Freetype scalable fonts, the widget uses the ftFont method from X11CanvasPane.

text (String labelText)

Sets the text of a single-line label.

text (String labelText)

Sets the receiver’s textLine instance variable for single-line labels.

multiText (String labelText)

Divides the text given as the argument into lines where newline characters ‘\n’ appear in the text, and sets the elements of the receiver’s textLine instance variable to one line for each array element. Also sets the haveMultiLine instance variable to true.

Next: , Previous: , Up: Classes   [Index]