PDCursesMod/x11/README.md

PDCurses for X11

This is a port of PDCurses for X11, aka XCurses. It is designed to allow existing curses programs to be re-compiled with PDCurses, resulting in native X11 programs.

Building

• Run "./configure". To build the narrow-character version of the library, specify "--disable-widec" as a parameter.

  If your system is lacking in UTF-8 support, you can force the use of UTF-8 instead of the system locale via "--enable-force-utf8".

  If configure can't find your X include files or X libraries, you can specify the paths with the arguments "--x-includes=inc_path" and/or "--x-libraries=lib_path".

  By default, the library and demo programs are built with the optimizer switch -O2. You can turn this off, and turn on debugging (-g), by adding "--enable-debug" to the configure command.

• Run "make". This should build libXCurses. Add the target "demos" to build the sample programs.

• Optionally, run "make install". To avoid conflicts with any existing curses installations, copies of curses.h and panel.h are installed in (by default) /usr/local/include/xcurses.

Usage

When compiling your application, you need to include the <curses.h> that comes with PDCurses. You also need to link your code with libXCurses. You may need to link with the following libraries:

Xaw Xmu Xt X11 SM ICE Xext Xpm

You can run "xcurses-config --libs" to show the link parameters for your system. If using dynamic linking, on some systems, "-lXCurses" suffices.

By calling Xinitscr() rather than initscr(), you can pass your program name and resource overrides to PDCurses. The program name is used as the title of the X window, and for defining X resources specific to your program. You can also set the width and height via PDC_COLS and PDC_LINES (command-line options and resources will take precedence), and as always, you can set the title via PDC_set_title().

Interaction with stdio

Be aware that curses programs that expect to have a normal tty underneath them will be very disappointed! Output directed to stdout will go to the xterm that invoked the PDCurses application, or to the console if not invoked directly from an xterm. Similarly, stdin will expect its input from the same place as stdout.

X Resources

PDCurses for X11 recognizes the following resources:

lines, cols

Specify the number of lines and columns the "screen" will have. Directly equate to LINES and COLS. There is no theoretical maximum. The minimum values must each be 2. Defaults: 24, 80

normalFont, italicFont, boldFont

Names of fonts to use. These should be fixed-width. italicFont and boldFont are used for characters with the A_ITALIC and A_BOLD atttributes, respectively (if PDC_set_bold(), in the case of boldFont), and must have the same cell size as normalFont.

Defaults -- wide:

• -misc-fixed-medium-r-normal--20-200-75-75-c-100-iso10646-1
• -misc-fixed-medium-o-normal--20-200-75-75-c-100-iso10646-1
• -misc-fixed-bold-r-normal--20-200-75-75-c-100-iso10646-1

Narrow:

• -misc-fixed-medium-r-normal--13-120-75-75-c-70-iso8859-1
• -misc-fixed-medium-o-normal--13-120-75-75-c-70-iso8859-1
• -misc-fixed-bold-r-normal--13-120-75-75-c-70-iso8859-1

pointer

The name of a valid pointer cursor. Default: xterm

pointerForeColor, pointerBackColor

Foreground and background colors for the pointer. Defaults: black, white

textCursor

The alignment of the text cursor; horizontal or vertical. Default: horizontal

colorBlack through colorWhite

The initial values for the first eight colors, as represented by the curses macros COLOR_BLACK through COLOR_WHITE. Note that these can all be changed via init_color().

The defaults are Black, red3, green3, yellow3, blue3, magenta3, cyan3 and Grey.

colorBoldBlack through colorBoldWhite

The initial values for the next eight colors (8 through 15). When COLORS was limited to 8, these colors could only be accessed by combining the appropriate COLOR_# with the A_BOLD attribute, in the case of foreground colors, or A_BLINK for background colors. They can now be used directly by their numbers (or COLOR_# + 8). (Note that some terminals still use COLORS = 8.) See also PDC_set_bold() and PDC_set_blink().

The defaults are grey40, red1, green1, yellow1, blue1, magenta1, cyan1 and White.

bitmap

The name of a valid bitmap file of depth 1 (black and white) used for the application's icon. The file is an X bitmap. Default: none

pixmap

The name of a valid pixmap file of any depth supported by the window manager (color) for the application's icon, The file is an X11 pixmap. This resource overrides the "bitmap" resource. Default: a 32x32 or 64x64 pixmap depending on the window manager

clickPeriod

The period (in milliseconds) between a button press and a button release that determines if a click of a button has occurred. Default: 100

doubleClickPeriod

The period (in milliseconds) between two button press events that determines if a double click of a button has occurred. Default: 200

Using Resources

All applications have a top-level class name of "XCurses". If Xinitscr() is used, it sets an application's top-level widget name. (Otherwise the name defaults to "PDCurses".)

Examples for app-defaults or .Xdefaults:

!
! resources for XCurses class of programs
!
XCurses*lines:  30
XCurses*cols:   80
XCurses*normalFont:     9x13
XCurses*bitmap: /tmp/xcurses.xbm
XCurses*pointer: top_left_arrow
!
! resources for testcurs - XCurses
!
testcurs.colorRed:      orange
testcurs.colorBlack:    midnightblue
testcurs.lines: 25
*testcurs.Translations: #override \n \
  <Key>F12:  string(0x1b) string("[11~") \n
!
! resources for THE - XCurses
!
! resources with the * wildcard can be overridden by a parameter passed
! to initscr()
!
the*normalFont: 9x15
the*lines:      40
the*cols:       86
the*pointer:    xterm
the*pointerForeColor: white
the*pointerBackColor: black
!
! resources with the . format can not be overridden by a parameter passed
! to Xinitscr()
!
the.bitmap:     /home/mark/the/the64.xbm
the.pixmap:     /home/mark/the/the64.xpm

Resources may also be passed as parameters to the Xinitscr() function. Parameters are strings in the form of switches; e.g., to set the color "red" to "indianred", and the number of lines to 30, the string passed to Xinitscr would be: "-colorRed indianred -lines 30"

Deprecated

XCursesProgramName is no longer used. To set the program name, you must use Xinitscr(), or PDC_set_title() to set just the window title.

The XCursesExit() function is now called automatically via atexit(). (Multiple calls to it are OK, so you don't need to remove it if you've already added it for previous versions of PDCurses.)

XCURSES is no longer defined automatically, but need not be defined, unless you want the X11-specific prototypes. (Normal curses programs won't need it.)

Distribution Status

As of April 13, 2006, the files in this directory are released to the public domain, except for ScrollBox*, which are under essentially the MIT X License; config.guess and config.sub, which are under the GPL; and configure, which is under a free license described within it.

Acknowledgements

X11 port was provided by Mark Hessling mark@rexx.org Single-process modifications by William McBrine