X11TextPane (Ctalk)

X11TextPane

`X11TextPane` Class

X11TextPane objects display text within a X window. The class defines methods to display text when opening or resizing a window, and scrolling through the text.

The Ctalk distribution’s, demos, subdirectory contains several example applications of X11TextPane objects.

Viewing Text

With a X11TextPane window open, the class provides the following keyboard commands.


Key(s)                 Action
------                 ------
j, Control-N, <Up>     Scroll the text down by one line.
k, Control-P, <Down>   Scroll the text up by one line.
Control-V              Scroll the text down one screenful.
Control-T              Scroll the text up one screenful.
Control-Q              Go to the start of the text.
Control-Z              Go to the end of the text.
Escape, Control-C      Close the window and exit the program.

Adding and Formatting Text

To display text, the class provides the methods addText, putStr, and printOn.

The addText method wraps long lines to fit within the window’s viewing area, and recognizes newline characters as hard line breaks and inserts soft line breaks where necessary. The methods putStr and printOn can display shorter items of text at specific X,Y positions.

For word wrapped text, each member of the textList instance variable (described below) is a TextBox object, which is an iternal class that is used exclusively by __ctalkWrapText library function and the displayText method.

The class supports both X bitmapped fonts and the X11FreeTypeFont outline font libraries. Applications enable outline font support by calling the X11FreeTypeFont method initFontLib at the start of the program.

In addition, the class supports different typefaces and simple line formatting with a small set of HTML-like formatting tags.

Tag(s)                Action
------                ------
<b>, </b>             Start/end boldface type.
<i>, </i>             Start/end italic (or oblique) type.
<center>, </center>   Start/end a centered line of text.

Instance Variables

leading

An Integer that contains the extra space between lines, in pixels. Its value depends on the font that the program uses. The dimensions of Xlib bitmap fonts seems to provide enough space without adding any extra space. Outline fonts, however, seem to need this. The default is 2 (pixels), which the program can set whenever it selects a font. Currently, this variable has no effect with Xlib fonts, though.

lineHeight

An Integer that contains the height of a line in pixels. Its value is set when the program selects a font. The default is 12 pixels, which is the value used whenever a program doesn’t specify any fonts. The total lineHeight is the height of the tallest character ascent + the longest character descent, and optionally, any leading, either added by the font designer or the X11TextPane object. Refer to the font method, below.

scrollHeight

An Integer that contains the number of lines that the text moves when scrolling by one screenful. Its value is


textPaneObject scrollHeight = textPaneObject viewHeight -
                                textPaneObject scrollMargin

scrollMargin

An Integer that contains the number of lines to overlap when scrolling by pagefuls. Its default value is 3.

text

A String that contains the unformmated text to be displayed in the window. Formatting raw text for display is done by the addText method, below.

textList

This List object contains the output of the word wrapping routines. Each item of the List is a TextBox object, an internal class that stores information about each word of the text.

textLines

An Integer that contains the number of lines of text after it is formatted.

viewStartLine

An Integer that contains the number of the first text line that is visible in the window.

requestClose

A Boolean that indicates whether the X11TextPane object has requested to be closed, normally in response to an Escape or Control-C keypress.

viewXOffset

An Integer that contains the left margin of the text when displayed in the window.

viewHeight

viewWidth

Integer objects that contain the width and height of viewable area, in characters. These are normally determined by the font that the program selects, and after the program calculates the line height (refer to the font method, below). The X11TextPane class adjusts for variable width fonts and faces whenever necessary (and possible, in some cases).

If the program has selected a font, the X11TextPane class calculates the width and height of the viewing area like this.


self viewHeight = self size y / self lineHeight;
self viewWidth = self size x / self fontVar maxWidth;

If the program doesn’t select any fonts, the class uses 14 pixels as the height of each character and 12 pixels as the character width.

Instance Methods

addText (Object text)

Adds the argument’s text to the receiver pane’s text instance variable, then word-wraps the entire text into the textList instance variable.

attachTo (Object parentPane)

Attaches the X11TextPane object to its parent pane. The parent pane should always be a X11PaneDispatcher object.

cursorPos (Integer x, Integer y)

Set the pane’s cursor to the coordinates given as arguments.

background (String colorname)

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

clear (void)

Clear the pane to the background color.

displayText (void)

Update the pane’s text. The pane’s window is updated at the next refresh message (see below).

faceRegular (void)

faceBold (void)

faceItalic (void)

faceBoldItalic (void)

Selects the typeface of the currently selected font. The font should be selected by a previous call to the font method (below). The font call gathers information about the type variations if the typeface is available.

font (String font_descriptor)

Loads the bitmap font named by font_descriptor and the bold, italic, and bold italic typefaces if they are available, and makes the font named by the argument the currently selected the receiver Pane’s currently selected font.

If a program uses outline fonts, it has more freedom to decide when to select the fonts, because the font libraries operate independently of the program’s connection to the GUI. See X11FreeTypeFont.

Programs that use Xlib bitmap fonts, however, need to wait until the connection to the GUI is opened, with a call to openEventStream (class X11Pane). See X11Pane.

Here’s a code snippet from X11TextPane class.


  X11FreeTypeFont new ftFont;
  Integer new ftMaxCharWidth;
  
  self fontDescStr = fontDesc;
  self fontVar getFontInfo fontDesc;
  (X11Bitmap *)self paneBuffer font fontDesc;

  if (ftFont libIsInitialized) {
    self lineHeight = ftFont textHeight "ghyl";
    self lineHeight += self leading;
    ftMaxCharWidth = ftFont textWidth "M";
    self viewWidth = self size x / ftMaxCharWidth;
  } else {
    /* Note that we don't add the leading to the lineHeight here */
    self lineHeight = self fontVar height;
    self viewWidth = self size x / self fontVar maxWidth;
  }
  self viewHeight = self size y / self lineHeight;

foreground (String colorname)

Set the forground color of the text pane. See the note for X11Bitmap class’s foreground method. See X11Bitmap.

gotoXY (Integer x, Integer y)

Set the pane’s cursor to the coordinates given as arguments. The coordinates are the number of horizontal and vertical pixels from the pane’s top-left corner.

This method is a synonym for cursorPos, above.

new (String paneName)

Creates a X11TextPane object and initializes the pane’s event handlers and other instance data.

If the argument list contains more than one name, create X11TextPane objects with the names given by the arguments.

printOn (char *fmt, ...)

Print the argument, which is a printf(3) style format string with arguments for the format conversion specifiers, in the pane’s buffer at the position given by the pane’s software cursor. To update the visible window with the pane buffer’s contents, call the refresh method (below), after calling this function.

putChar (Character c)

Write a character in the pane’s window at the pane’s cursor position.

putStr (String s)

Write a string in the pane’s window at the pane’s cursor position.

refresh (void)

Update the text displayed in the pane’s window.

subPaneDestroy (Object subPaneReference, InputEvent event)

The class’s destructor method. This method deletes only the data associated with the pane object’s window, not the pane object itself, which is treated like any other object.

subPaneExpose (Object subPaneReference, InputEvent event)

The class’s EXPOSE event handler. Refreshes the main window from the pane’s text buffer.

subPaneKbdInput (Object subPaneReference, InputEvent event)

The handler for KEYPRESS and KEYRELEASE events from the window system.

subPaneResize (Object subPaneReference, InputEvent event)

The handler for RESIZENOTIFY events from the window system.