X11ButtonPane

X11ButtonPane Class

The X11ButtonPane class defines instance variables and methods that draw buttons on X windows. The buttons’ appearance is defined by the values in the resources and instance variables, and they may be used to define the format of customized buttons.

X11ButtonPane objects also contain a X11LabelPane object, which is used to render the visual elements, like the text, border, and highlighting, on the button’s face.

In many cases the button’s X11LabelPane subpane inherits the definitions of the X11ButtonPane's instance variables and resources, generally when a program constructs the pane during a call to the attachTo method.

Here are several example programs. The first draws beveled buttons, the second draws rounded, non-beveled buttons.

/* -*-c-*- */

/*
 *  buttons.ca - X11ButtonPane demonstration.
 *
 *    To build, use this command line:
 *
 *      ctcc -x buttons.ca -o buttons
 *
 *    There are several options that control the buttons' appearance.
 *    Some of them use the #defines below.  Consult the X11ButtonPane
 *    section in the Ctalk language reference for a full description
 *    of the X11ButtonPane class.
 */


#include <ctalk/ctalkdefs.h>

/* Uncomment this #define to use X bitmap fonts. */
/* #define XFONTS */

/* Also, uncomment this to draw multiline labels. */
/* #define MULTILINE */

/* Uncomment if you want the buttons to be highlighted with wider
   borders and a bold label (if the font supports it). */
/* #define BOLD_HILITE */

/* See the X11FreeTypeFont section of the the Ctalk reference. */
#define FTFONT_BOLD   200
#define FTFONT_MEDIUM 100

int main (void) {
  X11Pane new mainWindow;
  X11PaneDispatcher new dispatcher;
  X11ButtonPane new lbutton;
  X11ButtonPane new rbutton;
  X11LabelPane new label;
  InputEvent new e;

  mainWindow backgroundColor = "blue";

  label canFocus = false;
  label ftFontVar initFontLib;
  label resources replaceAt "borderWidth", 0;

  label resources replaceAt "backgroundColor", "blue";
  label resources replaceAt "foregroundColor", "blue";
  label resources replaceAt "textColor", "white";
  lbutton resources replaceAt "backgroundColor", "blue";
  rbutton resources replaceAt "backgroundColor", "blue";
  lbutton resources replaceAt "ftFont", "sans serif-10";
  rbutton resources replaceAt "ftFont", "sans serif-10";

  mainWindow initialize 255, 200;
  mainWindow inputStream eventMask = 
    EXPOSE|ENTERWINDOWNOTIFY|LEAVEWINDOWNOTIFY|BUTTONPRESS|BUTTONRELEASE|KEYPRESS|KEYRELEASE|WINDELETE|MOTIONNOTIFY;
  dispatcher attachTo mainWindow;
#ifdef MULTILINE
  lbutton attachTo dispatcher, "100x60+25+100";
  rbutton attachTo dispatcher, "100x60+135+100";
#else  
  lbutton attachTo dispatcher, "90x50+25+100";
  rbutton attachTo dispatcher, "90x50+135+100";
#endif  
  label attachTo dispatcher, "147x80+c+15";

  mainWindow map;
  mainWindow raiseWindow;

  mainWindow openEventStream;

  mainWindow setWMTitle "X11ButtonPane Demo";

#ifndef XFONTS
  label ftFontVar initFontLib;
#else
  lbutton label font "fixed";
#endif  

  label multiLine "X11ButtonPane\nDemo";

#ifndef MULTILINE
  lbutton label text "Left";
  rbutton label text "Right";
#else
  lbutton label multiLine "Click\nHere";
  rbutton label multiLine "Click\nHere, Too";
#endif

#ifdef BOLD_HILITE
  lbutton label resources replaceAt "highlightForegroundColor",
    (lbutton resources at "foregroundColor");
  rbutton label resources replaceAt "highlightForegroundColor",
    (rbutton resources at "foregroundColor");
  lbutton label resources replaceAt "highlightBorderWidth", 2;
  rbutton label resources replaceAt "highlightBorderWidth", 2;
  rbutton label resources replaceAt "highlightTextBold", true;
  lbutton label resources replaceAt "highlightTextBold", true;
#endif  

  lbutton draw;
  lbutton refresh;
  rbutton draw;
  rbutton refresh;
  label draw;
  label refresh;

  while (TRUE) {
    mainWindow inputStream queueInput;
    if (mainWindow inputStream eventPending) {
      e become mainWindow inputStream inputQueue unshift;

      mainWindow subPaneNotify e;

      switch (e eventClass value)
	{
	case EXPOSE:
	  lbutton subPaneExpose (lbutton, e);
	  rbutton subPaneExpose (rbutton, e);
	  label subPaneExpose (label, e);
	  break;
	case WINDELETE:
 	  mainWindow deleteAndClose;
	  exit (0);
	  break;
	default:
	  if (lbutton haveClick) {
	    printf ("left button!\n");
	    lbutton clearClick;
	  } else if (rbutton haveClick) {
	    printf ("right button!\n");
	    rbutton clearClick;
	  }
	  break;
	}
    } else {
      usleep (1000);
    }
  }

}

/* roundbuttons.ca - X11ButtonPane Rounded Buttons -*-c-*- */

#include <ctalk/ctalkdefs.h>

/* To avoid overlapping arcs, corner_radius < (button_minor_dimen / 2) */
#define CORNER_RADIUS 13

int main (void) {
  X11Pane new mainWindow;
  X11PaneDispatcher new dispatcher;
  X11ButtonPane new lbutton;
  X11ButtonPane new rbutton;
  X11LabelPane new label;
  InputEvent new e;

  mainWindow backgroundColor = "blue";
  label ftFontVar initFontLib;
  label resources replaceAt "backgroundColor", "blue";
  rbutton resources replaceAt "backgroundColor", "blue";
  lbutton resources replaceAt "backgroundColor", "blue";
  rbutton resources replaceAt "foregroundColor", "blue";
  lbutton resources replaceAt "foregroundColor", "blue";


  mainWindow initialize 225, 150;
  mainWindow inputStream eventMask = 
    EXPOSE|ENTERWINDOWNOTIFY|LEAVEWINDOWNOTIFY|BUTTONPRESS|BUTTONRELEASE|KEYPRESS|KEYRELEASE|WINDELETE|MOTIONNOTIFY;
  dispatcher attachTo mainWindow;
  lbutton attachTo dispatcher, "80x30+22+100";
  rbutton attachTo dispatcher, "80x30+124+100";
  label attachTo dispatcher, "147x80+32+15";

  mainWindow map;
  mainWindow raiseWindow;

  mainWindow openEventStream;

  mainWindow setWMTitle "X11ButtonPane Demo";

  label multiLine "X11ButtonPane\nRounded Button\nDemo";
  label canFocus = false;
  label borderWidth = 0;
  label resources replaceAt "borderColor", "blue";
  label resources replaceAt "textColor", "white";
  label resources replaceAt "backgroundColor", "blue";
  label resources replaceAt "foregroundColor", "blue";

  rbutton resources replaceAt "foregroundColor", "blue";
  lbutton resources replaceAt "foregroundColor", "blue";
  rbutton resources replaceAt "textColor", "white";
  lbutton resources replaceAt "textColor", "white";


  lbutton label text "Left";
  rbutton label text "Right";

  lbutton bevelEdges = false;
  lbutton radius = CORNER_RADIUS;
  rbutton bevelEdges = false;
  rbutton radius = CORNER_RADIUS;

  lbutton draw;
  lbutton refresh;
  rbutton draw;
  rbutton refresh;
  label draw;
  label refresh;

  while (TRUE) {
    mainWindow inputStream queueInput;
    if (mainWindow inputStream eventPending) {
      e become mainWindow inputStream inputQueue unshift;

      mainWindow subPaneNotify e;

      switch (e eventClass value)
	{
	case EXPOSE:
	  lbutton subPaneExpose (lbutton, e);
	  rbutton subPaneExpose (rbutton, e);
	  label subPaneExpose (label, e);
	  break;
	case WINDELETE:
 	  mainWindow deleteAndClose;
	  exit (0);
	  break;
	default:
	  if (lbutton haveClick) {
	    printf ("left button!\n");
	    lbutton clearClick;
	  } else if (rbutton haveClick) {
	    printf ("right button!\n");
	    rbutton clearClick;
	  }
	  break;
	}
    } else {
      usleep (1000);
    }
  }

}

Retrieving Button States

The X11ButtonPane class provides several methods to retrieve the state of a button object.

haveClick

Returns true or false depending on whether the button has been clicked recently. This means that programs do not need to constantly monitor a button’s state. If haveClick returns true, then the click state can be cleared with the clearClick method (below).

isClicked

This method returns true or false depending on whether the pointer’s button 1 is currently pressed within the button’s area.

clearClick

Resets a previous clicked state as returned by the haveClick method, above.

text

Returns a String with the button’s text. If the text is displayed on several lines, the method concatenates the lines with a space character ‘' '’ between them.

Resources

The resources that X11ButtonPane : 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.

backgroundColor

A String that contains the color used to draw the button’s background. This includes the actual subwindow that receives the button’s events from the display server. The resources’ default value is ‘gray’.

If you want the button’s background to match its parent window, add a statement like the following before attaching the button to its parent window with the attachTo method (assuming in this example that the parent window’s background is also ‘blue’).

myButton resources replaceAt "backgroundColor", "blue";

When the program creates the actual X subwindow (again, by calling the attachTo method), the Ctalk libraries then check for a resource or instance variable named either, ‘background’ or ‘backgroundColor’ and uses its value to set the X subwindow’s background color.

borderColor

A String that contains the name of the color used to draw the label’s borders. The default value is ‘black’.

borderWidth

An Integer that contains the width of the visible border in pixels. Its default value is ‘1’. To draw buttons without borders, programs can set this resource to ‘0’.

foregroundColor

A String that defines the color used for the button’s drawable face. Its default color is ‘gray’.

font

A String that contains the Fontconfig descriptor of the button’s default font. Its default value is ‘sans serif-12’. The button’s label inherits the descriptor as its default font when attaching the button (and its X11LabelPane label) to its parent window with the attachTo method.

To change the label’s font, include a statement like the one in the example, after the button has been fully initialized by the attachTo method.

myButton label resources replaceAt "ftFont", "URW Gothic L-10";

The font, ‘URW Gothic L,’ is a Type 1 font included in the Ghostscript gsfonts package.

Note that the older, ‘ftFont’ key has been changed to, ‘font’, so it’s consitent with other classes’ resources. The class still uses the older ‘ftfont’ resource key if a program uses it.

highlightForegroundColor

A String that contains the color used to fill the button’s face when the pointer is over the button. Its default value is ‘gray90’.

If you want buttons to display a thicker border and bold font for highlighting, you can include a set of statements like the following in the program, after the program attaches the button to its parent pane.

myButton label resources replaceAt "highlightForegroundColor",
  (myButton resources at "foregroundColor");
myButton label resources replaceAt "highlightBorderWidth", 2;

To cause the button’s text to be emphasized when the button is highlighted, add a line like this one.

myButton label resources replaceAt "highlightTextBold", true;

This is only effective if the font library supports boldfacing (i.e., mainly Freetype and Type 1 fonts).

In these cases, the label subpane doesn’t automatically inherit these values, so it’s necessary to use the label’s declaration, myButton label, directly.

highlightBorderColor

A String that defines the color to use when drawing a highlighted border. The default is ‘black’.

highlightBorderWidth

An Integer that defines the border width in pixels when the button is highlighted. The default value is ‘1’. (That is, the button doesn’t use a heavier border for emphasis by default.)

The label subpane inherits this value when the attachTo method constructs the button pane.

highlightHPenColor

highlightVPenColor

shadowPenColor

These are String objects that define the colors for the highlighted and shadowed button edges when drawing a beveled button.

textColor

A String that contains the color used to draw the button’s text. This value is inherited by the button’s label widget. The textColor resources’ default value is ‘black’.

Instance Variables

bevelEdges

A Boolean that causes the widget to display beveled edges if true.

bevelWidth

An Integer that defines the width of the button’s bevelled edges in pixels.

borderColor

A String that contains the name of the button’s border color when drawing a non-beveled button.

borderMargin

An Integer that defines the distance between the border and the pane’s edge in pixels, when drawing a non-beveled button.

borderWidth

borderHighlighWidth

Integer values that determine the width a non-beveled button when it is clicked on and in its non-highlighted state.

clicked

A Boolean that is true when the pointer’s Button 1 is pressed while over the widget, and false otherwise.

highlightHPen

highlightVPen

shadowPen

Pen objects that defines the color of the edges’ bevels when drawing a beveled widget.

hover

A Boolean that is true if the pointer is over the button’s window, false otherwise. Normally, this causes the button to draw its face using highlighted colors, fonts, and borders.

label

A X11LabelPane object that contains a button’s text and provides the methods to draw on the button’s surface. See X11LabelPane.

radius

If greater than zero (‘0’), this Integer defines the radius in pixels of the curves displayed when the button is drawn with rounded corners.

Instance Methods

attachTo (Object parentPane, String geometry)

attachTo (Object parentPane)

attachTo (Object parentPane, Integer xOrg, Integer yOrg)

attachTo (Object parentPane, Integer xOrg, Integer yOrg, Integer xSize, Integer ySize)

Attaches the receiver to the parentPane named by parentPane, with the placement and size given by geometry. The parent pane should generally be a X11PaneDispatcher which directs X events to the correct subpane.

The positioning of subwindows within the parent window is controlled by the arguments to the attachTo methods; in particular, these methods accept a geometry specification, as an argument, which has the following format.

If only parentPane is given as an argument, the child pane occupies the entire width and height of the parent pane.

If the program has initialized the Xft Freetype libraries, this method also fills in the pane object’s ftFontVar instance variable with the selected font, which is normally a system-defined standard font during app initialization.

width[%]xheight[%]+x[%]+y[%]

If a dimension does not contain a percent (‘%’) sign, the dimensions are in pixels. With a percent sign, the dimensions are a fractional percentage of the parent pane’s width or height, or a horizontal or vertical distance that places the subwindow’s upper left-hand corner that distance from the parent window’s upper left-hand corner.

clearClick (void)

Resets a button’s clicked state as returned by haveClick to false.

clearClick (configureFonts

A convenience method that localizes the button’s label font for more uses, especially with composite widgets like dialog boxes. This method set’s the label subpane’s font to the button’s ‘font’ resource.

draw (void)

Draws the button and its label on the pane’s buffer so the widget can be displayed with the refresh method.

If the program has saved a font specification to the widget’s ftFontVar instance variable, then this method also selects the font before drawing the widget. If you want a button to display a different font than the surronding window, this is the way to declare and save a font specification.

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

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

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

haveClicked (void)

Returns a Boolean true or false depending on whether the button has been clicked previously. In that case, the program should call the clearClick method to detect further button clicks.

isClicked (void)

Returns a Boolean value of true or false depending on whether the pointer’s button 1 is currently pressed within the button.

new (String newObjectName)

The X11ButtonPane constructor. Creates a X11ButtonPane object with the classes’ instance variables, and initialized the object’s event handlers and Pen objects for drawing a beveled button.

subPaneExpose (Object subPane, InputEvent event)

subPaneButtonPress (Object subPane, InputEvent event)

subPaneEnter (Object subPane, InputEvent event)

subPaneLeave (Object subPane, InputEvent event)

subPaneResize (Object subPane, InputEvent event)

The class’s handlers for events generated by the X server.

subPaneFocusIn (void)

subPaneFocusOut (void)

Handlers for focus changes generated by the application. These do not respond to X events and don’t require any arguments. These methods are designed to be called by methods like X11PaneDispatcher : shiftFocus (e.g., in response to a Tab keypress).

text (void)

Returns a String with the button’s text. If the text is displayed on multiple lines, this method concatenates the lines with a space character (‘ ’) between them.