X11Pane

X11Pane Class

The X11Pane class provides the basic methods and instance variables for creating and displaying a window on a X display.

The X11Pane class does not, itself, provide methods for moving, resizing, or handling input or changing focus.

The X11TerminalStream class handles X input events. The X11Pane constructor new also creates a X11TerminalStream object in the X11Pane's inputStream instance variable. There is a short example program in the X11TerminalStream section. See X11TerminalStream.

This class uses the default visual or a X window without buffering, so applications need to be careful to handle InputEvents correctly, or graphics drawing may result in flicker, depending how the window manager handles X Window System events. See the Ctalk Tutorial for information about how to use InputEvent objects in applications.

However, X11Pane class provides the address of the window’s graphics context in the xGC instance variable, so applications that use this class for graphical displays can create and use their own visuals if necessary.

Instance Variables

backgroundColor

A String object that contains the name of the window’s background color. The value is the background color of the window, independent of the background color of any buffers used by subpanes. Normally this value is set by the background method, described below.

Note that if a subclass of X11Pane has set a ‘backgroundColor’ resource, then that color overrides this variable’s value when a program creates subpane windows. The window creation generally happens when attaching a pane object to its parent pane, with an attachTo method.

If unset, the default background color is black.

borderWidth

An Integer object that contains the window’s border width in pixels. The default is 1 pixel.

container

A Symbol that refers to a pane’s container (i.e., parent) Pane object. For top-level X11Pane objects this value should be NULL.

depth

An Integer that contains the default depth of the display screen. Ctalk sets this value when creating the window of a X11Pane object or an instance of one of X11Pane's subclasses. Normally applications should not need to change this value.

displayPtr

A Symbol that holds the pointer to the display connection; i.e., the Display * returned by XOpenDisplay(3). Most windows use the display connection opened when the main window is created. Dialogs, which create their own main windows, open their own connection to the display. Generally, programs should not need to change this.

When using subpanes, it’s convenient to set the subpane’s displayPtr variable to the value of the main window pane’s value. This is generally done in the attachTo methods, with a line that looks something like this.

haveXft

A Boolean that has the value of ‘true’ if Ctalk is built with the Xft and Fontconfig libraries, and they have been initialized with a call to X11FreeTypeFont : initFontLib.

modal

A Boolean that determines how Ctalk draws in the window. True for popup windows, false otherwise.

self displayPtr = self mainWindow displayPtr;

fontVar

A X11Font object that contains information about the Window or Pane’s current font.

fontDesc

A String that contains a X Logical Font Descriptor for the font to be used by the window. If the value is ‘(null)’, the window uses the system’s fixed font.

foregroundColor

A String object that contains the name of the window’s foreground color. If unset, the default foreground color is black.

ftFontVar

An X11FreeTypeFont object that contains the pane’s current font, if the X11TextEditorPane object uses outline fonts.

If, on the other hand, the pane uses X11 bitmap fonts, the Pane uses the fontVar instance variable. Which requires no additional initialization.

To determine whether a machine has outline fonts available, a program could use a set of statements like this in its initialization.

Boolean new useXFonts;
X11Pane new myPane;

...

if (myPane ftFontVar version >= 10) {
  myPane ftFontVar initFontLib;
  useXFonts = false;
} else {
  useXFonts = true;
}

inputStream

A X11TerminalStream object that provides InputEvent objects to the application. See X11TerminalStream.

resources

This is an AssociativeArray that an object can use to store any data that determine its run-time appearance, like colors, dimensions, or options. Generally a Pane class sets default resources in its new method, which application programs can then update with its own resources after the Pane object has been constructed.

As a brief example, here’s a sample initialization from the X11MessageBoxPane : new method.

paneName resources atPut "backgroundColor", "gray";
paneName resources atPut "pad", 10;
paneName resources atPut "messageText", "Your\nMessage\nHere";
paneName resources atPut "buttonText", "Ok";

Then, when an application program constructs the widgets when it is run, it can use a line like this.

l_label background self resources at "backgroundColor";
l_label multiLine self resources at "messageText";

Remember that the Collection : atPut method does not check for an existing key, so be sure to remove the old value first. This is done with the Collection : removeAt method, or simply with the Collection : replaceAt method.

if (l_label resources keyExists "backgroundColor")
  l_label resources removeAt "backgroundColor";
l_label resources atPut "backgroundColor", "blue";

or,

if (!l_label resources replaceAt "backgroundColor", "blue")
  l_label resources atPut "backgroundColor", "blue";

Refer to the Collection class section for more information about the methods it defines. See Collection.

xGC

A Symbol that contains the address of the window’s graphics context. The X11Pane class does not, at this time, provide methods or instance data for drawables, so the application needs to implement its own drawable for each window.

xWindowID

An Integer that contains the window’s id that a program can use with X library functions.

Class Variables

xColormap

An Integer that contains the resource ID of the default color map.

Instance Methods

attachTo (Object parentPane)

Attach the receiver to parentPane. The value of parentPane’s subWidget instance variable is the receiver.

background (String color_name)

Sets the background color of the pane object’s window. For buffered Panes, programs need to set the background color of that Pane independently. This method also has the effect of clearing the window.

If a program doesn’t set a background color for the window, the default background color is white.

clearRectangle (int x, int y, int width, int height)

Clear the area of the receiver’s window with the dimensions given as the arguments.

clearWindow (void)

Clear the receiver’s window. This method clears only the main window and does not affect any image buffers associated with the pane object. To also clear the pane object’s image buffers, use clearRectangle, above.

defaultCursor (void)

Restore the window’s default cursor, which is normally the cursor of the parent window.

deleteAndClose (void)

Delete the receiver window and close the display.

displayHeight (void)

Returns an Integer with the display’s height in pixels.

displayWidth (void)

Returns an Integer with the display’s width in pixels.

faceRegular (void)

faceBold (void)

faceItalic (void)

faceBoldItalic (void)

These methods select which X11FreeTypeFont typeface a pane should use. These methods need the program to initialize the Xft libraries (with the initFontLib method in X11FreeTypeFont class), and the pane has established a connection to the X server (with the openEventStream method).

font (String font_desc)

Set the X font used for drawing on the window. This font can be set independently of the fonts used by subpanes. See X11TextPane, and See X11Bitmap.

Because the Ctalk libraries use shared memory to manage font information, it is generally necessary to call this method after the openEventStream method, for the program to calculate the character spacing of multiple typefaces correctly.

foreground (String colorName)

Sets the window’s foreground color (the default color for drawing on the window) to colorName. If a program doesn’t set the window’s foreground color, the default color is black.

ftFont (String family, Integer slant,

Integer weight Integer dpi, Float pointSize) Selects an outline font for use by the X11Pane object. The method selects the font, and fills in the ftFontVar instance variable with the font’s information. Programs should first determine if FreeType fonts are available on the system, by using the X11FreeTypeFont method version first, as in this example.

Boolean new useXFonts;
X11Pane new myPane;

...

if (myPane ftFontVar version >= 10) {
  myPane ftFontVar initFontLib;
  useXFonts = false;
} else {
  useXFonts = true;
}

...

/* Selects the font DejaVu Sans Mono, regular slant, normal weight,
   72 dpi, 12 points. */
myPane ftFont "DejaVu Sans Mono", 0, 80, 72, 12.0;

The X11FreeTypeFont class also provides methods that use Xft and X11 font descriptors to select fonts. See X11FreeTypeFont.

initialize (int width, int height)

initialize (int x, int y, int width, int height)

Create the window and its graphics context with the width and height given as the arguments. This method also opens a connection to the X server if necessary. This method uses the window system to set the window’s initial position.

Create the window and its graphics context with the dimensions given as the arguments. This method also opens the connection to the X server if necessary.

This method is here for older programs, or programs that set the window position directly. Otherwise, use the form of initialize, below, that takes the window’s geometry flags as an argument, and only set the window’s position if the user provides one on the command line and the program retrieves it with parseX11Geometry.

Even more simply, a program can set x_org and y_org to zero, and let the window system handle any positioning. Or use the form of initialize that uses only the width and height arguments.

initialize (int x, int y, int width, int height, int geom_flags)

Create the window and its graphics context with the dimensions given as the arguments. Like the other forms of initialize, this method also opens the connection to the X server if necessary.

The geom_flags argument provides placement hints for the window’s initial position. It has the format provided by the parseX11Geometry method in Application class. See parseX11Geometry.

The x and y parameters can also be given directly if the program sets the window position itself. If these arguments are zero, then the window manager or the user supplied window geometry determine the window placement.

initialize (int x, int y, int width, int height, int geom_flags, char *win_title)

This method is similar to the five-argument form of initialize, and additionally sets the window’s title using the contents of the string win_title.

isTopLevel (void)

Return TRUE if the receiver’s container pane is NULL.

mainWindow (void)

Returns the X11Pane object that manages a program’s main window. The method retrieves the main window object by following the references of each subpane’s container instance variable. If the top-level pane object is not a X11Pane, the method prints a warning.

map (void)

Map the receiver window onto the X display.

openEventStream (void)

Open the window’s input stream, a X11TerminalStream object. The X11TerminalStream section of the manual describes X input event handling. See X11TerminalStream.

putStrXY (Integer xOrg, Integer yOrg, String str)

Draw the string on the receiver’s drawable surface at xOrg, yOrg, using the selected font.

putStrXY (Integer xOrg, Integer yOrg, String str)

Draw the string on the receiver’s drawable surface at xOrg, yOrg. Currently this method is the same as putStrXY, above.

raiseWindow (void)

Display the receiver window above other windows on the X display. Note that the method’s name was changed from raise to avoid warnings when including the C raise(3) function.

setResources (String resourceName, String resourceClass)

Set the resource name and class of the main window. Normally the resource name is the name of the application, which may vary from the window title. The resource class should be used to identify the window for X resources.

A program can call this method either before or after connecting to the server with the openEventStream method. Generally, if the resources affect the appearance of decorations provided by the system, like the window frame or icon, the window needs to be remapped for the changes to be visible, but this may vary with the application and the type of window manager.

setWMTitle (char *title)

Set the window’s title. Because setting a X window’s title requires communication between the window and the display server, this method requires that the window is first mapped and raised (with the map and raiseWindow methods, above), and has a connection to the display server (which is done with the openEventStream method, also above).

In other words, when setting a window’s title for the first time, this method works best when used just before processing any other events.

subPaneNotify (InputEvent event)

Called by applications that need to invoke sub-pane handlers in response to window events. For examples of its usage, refer to the section for X11CanvasPane, See X11CanvasPane, and other X11Pane subclasses.

useCursor (Cursor cursor_object)

Display the X11 cursor defined by cursor_object, a X11Cursor object, in the receiver’s window. To create cursors, See X11Cursor.

useXRender (Boolean b)

If b is true, draw graphics using the X Render extension if it is available. If b is false, use Xlib for graphics drawing. The default is to draw using the X Render extension if it is available.

usingXRender (void)

Returns a Boolean value of True if the program is using the X Render extension for drawing, False otherwise.