iw4x-client/deps/pdcurses/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