X11CanvasPane (Ctalk)

X11CanvasPane

`X11CanvasPane` Class

The X11CanvasPane class provides the instance variables and methods for basic X window graphics operations like drawing points, lines, and rectangles. The width and color of shapes is controlled by the pen instance variable.

Here is brief drawing program that uses a X11CanvasPane object. Clicking on the pane’s window draws a dot at that point. If the program is given the argument ‘-v’, the program displays the X events it receives from the display.


int main (int argv, char **argc) {
  X11Pane new xPane;
  X11PaneDispatcher new xTopLevelPane;
  X11CanvasPane new xCanvasPane;
  InputEvent new e;
  Integer new nEvents;
  Integer new verbose;
  Exception new ex;
  String new text;
  Application new paneApp;

  paneApp enableExceptionTrace;
  paneApp installExitHandlerBasic;

  xPane initialize 0, 0, 200, 100;
  xPane inputStream eventMask =
    WINDELETE|BUTTONPRESS|BUTTONRELEASE|MOVENOTIFY|EXPOSE;
  xTopLevelPane attachTo xPane;
  xCanvasPane attachTo xTopLevelPane;
  xPane map;
  xPane raiseWindow;

  xPane openEventStream;

  xCanvasPane clear;
  xCanvasPane background "blue";
  xCanvasPane pen width = 5;
  xCanvasPane pen colorName = "white";

  xCanvasPane refresh;

  verbose = FALSE;
  if (argc == 2) {
    if (!strcmp (argv[1], "-v")) {
      verbose = TRUE;
    }
  }

  WriteFileStream classInit;

  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) 
	{
	  /*
	   *  Handle both types of events in case the window
	   *  manager doesn't distinguish between them.
	   */
	case MOVENOTIFY:
	  if (verbose) {
	    stdoutStream printOn "MOVENOTIFY\t%d\t%d\t%d\t%d\n",
	      e xEventData1, 
	      e xEventData2, 
	      e xEventData3, 
	      e xEventData4;
	    stdoutStream printOn "Window\t\t%d\t%d\t%d\t%d\n",
	      xPane origin x, 
	      xPane origin y, 
	      xPane size x,
	      xPane size y;
	  }
	  break;
	case RESIZENOTIFY:
	  if (verbose) {
	    stdoutStream printOn "RESIZENOTIFY\t%d\t%d\t%d\t%d\n",
	      e xEventData1, 
	      e xEventData2, 
	      e xEventData3, 
	      e xEventData4;
	    stdoutStream printOn "Window\t\t%d\t%d\t%d\t%d\n",
	      xPane origin x, 
	      xPane origin y, 
	      xPane size x,
	      xPane size y;
	  }
	  break;
	case EXPOSE:
	  if (verbose) {
	    stdoutStream printOn "Expose\t\t%d\t%d\t%d\t%d\t%d\n",
	      e xEventData1, 
	      e xEventData2, 
	      e xEventData3, 
	      e xEventData4,
	      e xEventData5;
	  }
	  break;
	case BUTTONPRESS:
	  xCanvasPane drawPoint e xEventData1, e xEventData2;
	  if (verbose) {
	    stdoutStream printOn "ButtonPress\t\t%d\t%d\t%d\t%d\t%d\n",
	      e xEventData1, 
	      e xEventData2, 
	      e xEventData3, 
	      e xEventData4,
	      e xEventData5;
	  }
	  xCanvasPane refresh;
	  break;
	case BUTTONRELEASE:
	  if (verbose) {
	    stdoutStream printOn "ButtonRelease\t\t%d\t%d\t%d\t%d\t%d\n",
	      e xEventData1, 
	      e xEventData2, 
	      e xEventData3, 
	      e xEventData4,
	      e xEventData5;
	  }
	  break;
	case WINDELETE:
 	  xPane deleteAndClose;
	  exit (0);
	  break;
	default:
	  break;
	}
    }
  }
}

Instance Variables

dragStart: A Point object that records the beginning of a canvas motion operation within a window or view port.
moveCursor: The X11Cursor displayed when moving the X11CanvasPane object within a window or view port.
pen: A Pen object that contains the width in pixels and color of lines and points drawn on the pane’s window.
regions: An AssociativeArray that contains the rectangular regions defined by the defineRegion method, below.
viewHeight: An Integer that contains the height of the pane’s window and buffers in pixels.
viewWidth: An Integer that contains the height of the pane’s window and buffers in pixels.
viewXOrg: The X coordinate of the upper right-hand corner of a canvas’ visible rectangle within a window or view port.
viewYOrg: The Y coordinate of the upper right-hand corner of a canvas’ visible rectangle within a window or view port.

Instance Methods

attachTo (Object parent_pane)

attachTo (Object parent_pane, String geometry)

attachTo (Object parent_pane, Integer xOrg, Integer yOrg)

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

Attach a X11CanvasPane object to its parent pane, which is typically a X11PaneDispatcher object. With one argument, this method initializes the size of the pane’s window and buffers to the parent pane’s dimensions, and positions the pane at the upper left-hand origin of the main window.

If two arguments are present, the second is a String with the geometry specifcation for the subpane. Subpane geometry strings have the form:


[-]width[%]x[-]height[%][+[-]x[%]+[-]y[%]]

The dimensions are in pixels, unless a percent sign (‘%’) follows a dimension, or a minus sign (‘-’ precedes the dimension.

When a percent sign follows the dimension, the width of the pane in pixels is the fractional percentage of the parent pane’s width or height.

If a minus sign precedes the dimension, the dimension is measured relative to the opposite edge of the parent window; i.e., a width of ‘-15’ places the subpane’s right edge 15 pixels in from the right edge of the parent window. A x position of ‘-90’ places the subpane’s top edge (not the subpane’s bottom edge) 90 pixels from the bottom edge of the parent window.

The String may contain a combination of absolute and relative dimensions.

With only the width and height given, the method positions the pane at xOrg,yOrg within the parent pane, which usually is relative to the upper left hand origin of the window. This is generally used to center modal dialog panes over their parent window.

With all four dimensions given, the method positions the pane at xOrg,yOrg within the parent pane, with the width and height xSize,ySize.

background (String color)

Set the background of the pane to color. You need to update the pane using, for example, clearRectangle, for the new background to be visible. See the note for X11Bitmap class’s background method. See X11Bitmap.

clear (void)

Clear the pane to the background color.

clearRectangle (Intger xOrg, Integer yOrg, Integer xSize, Integer ySize)

Clear the pane’s image to the window background in a rectangle bounded by the method’s arguments, and update the top-level pane’s window.

copy (X11Bitmap src_bitmap, Integer src_x_ort, Integer src_y_org, Integer src_width, Integer src_height, Integer dest_x_org, Integer dest_y_org)

Copies the contents of src_bitmap to the receiver’s drawing surface. The source dimensions are determined by src_x_org, src_y_org, src_width, and src_height. The method draws the source bitmap’s contents with the source’s upper left-hand corner at dest_x_org, dest_y_org.

The X11Bitmap's parent drawable must be the receiver’s drawable surface, and the color depths of the source and destination must match.

The process is similar to the refresh method, below, so programs do not need to call both copy and refresh for the same operation.

This slightly abbreviated example program is included in the Ctalk package at test/expect/examples-x11/canvas-copy.c as well as the XPM graphic, but almost any XPM should work as well.

#include "coffee-cup.xpm"

/* 
   Set these to the width and height of your pixmap,
   and edit the pixmapFromData expression below to
   the xpm's declaration name. 
*/
#define XPM_WIDTH 127
#define XPM_HEIGHT 141

X11CanvasPane instanceMethod drawXPMs (X11Bitmap xpmBitmap) {
  Integer new i;

  for (i = 0; i < 5; i++) {
    self copy xpmBitmap, 0, 0, XPM_WIDTH, XPM_HEIGHT, (i* 40), (i * 40);
  }

  self refresh;
}

int main () {
  X11Pane new xPane;
  InputEvent new e;
  X11PaneDispatcher new xTopLevelPane;
  X11CanvasPane new xCanvasPane;
  Application new paneApp;
  X11Bitmap new srcBitmap;

  paneApp enableExceptionTrace;
  paneApp installExitHandlerBasic;

  xPane initialize 10, 10, 300, 300;
  xTopLevelPane attachTo xPane;
  xCanvasPane attachTo xTopLevelPane;

  srcBitmap create xCanvasPane xWindowID, XPM_WIDTH, XPM_HEIGHT, 
    xCanvasPane depth;

  xPane map;
  xPane raiseWindow;
  xPane openEventStream;

  xCanvasPane background "white";

  srcBitmap pixmapFromData (0, 0, coffee_cup);

  xCanvasPane drawXPMs srcBitmap;

  while (TRUE) {
    xPane inputStream queueInput;
    if (xPane inputStream eventPending) {
      e become xPane inputStream inputQueue unshift;
      /* We don't have to use, "xPane subPaneNotify e" here, because
         the program doesn't need to handle any X events for the
         graphics classes. */
      switch (e eventClass value)
        {
        case WINDELETE:
          xPane deleteAndClose;
          exit (0);
          break;
        case EXPOSE:
        case RESIZENOTIFY:
	  xCanvasPane drawXPMs srcBitmap;
          break;
        default:
          break;
        }
    }
    usleep (100000);
  }
}

Note: The copy method retrieves the paneBuffer instance variable. If you use an expresion like the following, then the program calls the X11Bitmap : copy method instead. See X11Bitmap.


  myRcvrPane paneBuffer copy ...

defineRegion (String regionName, Integer xOrg, Integer yOrg, Integer xSize, Integer ySize)

Define a rectangular region with name regionName with the upper left-hand corner at xOrg, yOrg relative to the upper left-hand corner of the canvas. The region has the width xSize and height ySize. When handling input events, the window system clips the region to the canvas’ viewable area.

drawCircle (Circle aCircle, Integer filled, String bgColor)

drawCircle (Circle aCircle, Pen aPen, Integer filled, String bgColor)

Draw the circle defined by aCircle in the receiver’s paneBuffer. If filled is true, draws a filled circle. If the aPen argument is given, draws the circle with the color and the line width defined by the Pen, and fills the interior of the circle with bgColor.

For an example program, refer to the Circle section of this manual. See Circle.

drawPoint (Intger x, Integer y)

Draw a dot on the pane’s window at the x and y coordinates given by the arguments.

drawLine (Line aLine)

drawLine (Line aLine, Pen aPen)

drawLine (Intger startX, Integer startY, Integer endX, Integer endY)

drawLine (Intger startX, Integer startY, Integer endX, Integer endY, pen aPen)

With one argument, a Line object, draws the line using the receiver’s Pen instance variable. With two arguments, draws the Line object with the color and line width given by aPen.

If given the line’s endpoints as arguments, the method draws a line on the pane’s window from the point given by the startX and startY arguments to the point given by the endX and endY arguments, with the color and the line width given by the receiver’s Pen object.

drawLine (Intger xOrg, Integer yOrg, Integer xSize, Integer ySize)

drawLine (Intger xOrg, Integer yOrg, Integer xSize, Integer ySize, Pen aPen)

Draw a filled rectangle on the pane’s window with the upper-left hand corner at the point given by the xOrg and yOrg arguments, with the width xSize and the height ySize. If a Pen argument isn’t given, uses the line width and color defined by the receiver’s pen instance variable; otherwise uses the line width and color defined by the aPen argument.

drawRoundedRectangle (Intger xOrg, Integer yOrg, Integer xSize, Integer ySize, Integer radius)

drawRoundedRectangle (Intger xOrg, Integer yOrg, Integer xSize, Integer ySize, Pen aPen, Pen aPen, Integer radius)

Similar to drawFilledRectangle, but this method takes an extra argument, the radius of the corner arcs that round the rendered rectangle’s corners.

If the aPen argument is given, the method uses its color and line width for drawing. Otherwise, the method uses the color and line width defined by the X11CanvasPane object for drawing.

drawRectangle (Intger xOrg, Integer yOrg, Integer xSize, Integer ySize)

drawRectangle (Intger xOrg, Integer yOrg, Integer xSize, Pen aPen, Integer ySize)

Draw the borders of a rectangle on the pane’s window with the upper-left hand corner at the point given by the xOrg and yOrg arguments, with the width xSize and the height ySize.

If the aPen argument is given, the method uses its color and line width for drawing. Otherwise, the method uses the color and line width defined by the X11CanvasPane object for drawing.

drawRoundedRectangle (Intger xOrg, Integer yOrg, Integer xSize, Integer ySize, Integer radius)

drawRoundedRectangle (Intger xOrg, Integer yOrg, Integer xSize, Integer ySize, Pen aPen, Integer radius)

This method is similar to drawRectangle, except that it takes an extra argument, radius, which specifies the radius of the arcs that form the rectangle’s corners.

If the aPen argument is given, the method uses its color and line width for drawing. Otherwise, the method uses the color and line width defined by the X11CanvasPane object for drawing.

directCopy (X11Bitmap src_bitmap, Integer src_x_ort, Integer src_y_org, Integer src_width, Integer src_height, Integer dest_x_org, Integer dest_y_org)

Similar to the copy method, above, except directCopy copies the X11Bitmap object given as its argument directly to the window. This might be quicker, and doesn’t require that the program call refresh (below) to update the window contents, but this method may also cause flickering when the window is updated.

foreground (String color)

Set the background of the pane to color. See the note for X11Bitmap class’s background method. See X11Bitmap.

new (String pane_name)

Create a new X11CanvasPane instance and initialize its event handlers.

If the argument list contains more than one label, create a new X11CanvasPane object with the names given by the arguments; for example,


X11CanvasPane new pane1, pane2, pane3;

pixmapFromData (int x_org, int y_org, char *xpm_data[])

Draw the X pixmap defined by xpm_data with the upper left corner at x_org,y_org on the receiver’s pane.

The xpm_data argument is the name of the array declared at the start of a xpm file’s data array.

putStrXY (Integer xOrg, Integer yOrg String text)

putStrXY (Integer xOrg, Integer yOrg String text, String font_desc)

putStrXY (Integer xOrg, Integer yOrg String text, String font_desc, String color_name))

Write text on the receiver pane’s drawing surface (usually a X11Bitmap) at position xOrg,yOrg. See X11Bitmap.

If the fourth argument is font_desc, the method draws the text using that font, which is either a X Logical Font Descriptor if using X bitmap fonts or a Fontconfig descriptor if using Freetype fonts.

For information about Fontconfig descriptors, refer to the X11FreeTypeFont section See X11FreeTypeFont. For information about X Logical Font Descriptors, refer to the X11Font section See X11Font.

If a color_name argument is also given, draws the text using that color.

selectFont (void)

selectFont (X11FreeTypeFont font)

This method selects the font and face defined by the reciever’s ftFontVar instance variable (with no arguments), or the font given as a single argument.

These methods ensure that the font-face selection is valid in any of the client-server memory spaces, and folds the font’s weight and slant into one of Ctalk’s predefined face slots: medium, bold, italic, or bold italic. This is basically a holdover from calculating font-face combinations for .BDF fonts; future versions of Ctalk should be able to use the typeface parameters directly.

This method is basically a combination of two other methods: X11FreeTypeFont : selectFont, and the library function __ctalkSelectXFontFace, which is used in the X11Bitmap methods: faceBold, faceRegular, faceItalic, and faceBoldItalic.

The four font face slots have definitions of that are given in both X11Bitmap class and ctalkdefs.h. The definitions are listed below.


#define X_FACE_REGULAR     (1 << 0)
#define X_FACE_BOLD        (1 << 1)
#define X_FACE_ITALIC      (1 << 2)
#define X_FACE_BOLD_ITALIC (1 << 3)

refresh (void)

Redraw the pane on the main window.

refreshReframe (void)

Redraw the pane on the main window. If the user has moved the pane by clicking and dragging on it, then reposition the pane within the window.

subPaneDestroy (Object subPaneRef, InputEvent event)

Deletes the pane’s window and its data when the user closes the pane’s window.

subPaneExpose (Object subPaneRef, InputEvent event)

Redraws the pane’s window whenever it is mapped or displayed after being covered by another window.

subPanePointerInput (Object subPaneRef, InputEvent event)

Default handler for mouse ButtonPress and ButtonRelease events. This method is a no-op here, but it can be re-implemented if necessary by subclasses. The application receives pointer events, like all other events, via the top-level window’s inputStream (a X11TerminalStream object).

subPaneResize (Object subPaneRef, InputEvent event)

The handler for Resize events from the X display. Resizes the pane’s X window and adjusts the pane’s dimensions.

X11CanvasPane

X11CanvasPane Class

Instance Variables

Instance Methods

`X11CanvasPane` Class