payloads/libpayload/curses/PDCurses-3.4/doc/x11.txt

   1 X11 Considerations
   2 ==================
   3
   4 PDCurses for X11 uses the System V IPC shared memory facility, along
   5 with sockets, to share data between the curses program and the child
   6 process created to manage the X stuff.
   7
   8 When compiling your application, you need to include the <curses.h> or
   9 <xcurses.h> that comes with PDCurses. You also need to link your code
  10 with libXCurses. You may need to link with the following libraries under
  11 X11R5:
  12     Xaw Xmu Xt X11
  13
  14 or, under X11R6:
  15     Xaw Xmu Xt X11 SM ICE Xext
  16
  17 You can run "xcurses-config --libs" to show the link parameters for your
  18 system. If using dynamic linking, on some systems, "-lXCurses" suffices.
  19
  20 By calling Xinitscr() rather than initscr(), you can pass your program
  21 name and resource overrides to PDCurses. The program name is used as the
  22 title of the X window, and for defining X resources specific to your
  23 program.
  24
  25
  26 Interaction with stdio
  27 ----------------------
  28
  29 Be aware that curses programs that expect to have a normal tty
  30 underneath them will be very disappointed! Output directed to stdout
  31 will go to the xterm that invoked the PDCurses application, or to the
  32 console if not invoked directly from an xterm. Similarly, stdin will
  33 expect its input from the same place as stdout.
  34
  35
  36 X Resources
  37 -----------
  38
  39 PDCurses for X11 recognizes the following resources:
  40
  41     lines
  42     cols
  43     normalFont
  44     italicFont
  45     pointer
  46     pointerForeColor
  47     pointerBackColor
  48     cursorColor
  49     textCursor
  50     colorBlack
  51     colorRed
  52     colorGreen
  53     colorYellow
  54     colorBlue
  55     colorMagenta
  56     colorCyan
  57     colorWhite
  58     colorBoldBlack
  59     colorBoldRed
  60     colorBoldGreen
  61     colorBoldYellow
  62     colorBoldBlue
  63     colorBoldMagenta
  64     colorBoldCyan
  65     colorBoldWhite
  66     bitmap
  67     pixmap
  68     translations
  69     shmmin
  70     borderWidth
  71     borderColor
  72     clickPeriod
  73     doubleClickPeriod
  74     composeKey
  75
  76 lines:             Specifies the number of lines the "screen" will have.
  77                    Directly equates to LINES.
  78                    There is no theoretical maximum.
  79                    The minimum value must be 2.
  80                    Default:        24
  81
  82 cols:              Specifies the number of columns the "screen" will have.
  83                    Directly equates to COLS.
  84                    There is no theoretical maximum.
  85                    The minimum value must be 2.
  86                    Default:        80
  87
  88 normalFont:        The name of a fixed width font.
  89                    Default:        7x13
  90
  91 italicFont:        The name of a fixed width font to be used for
  92                    characters with A_ITALIC attributes. Must have the
  93                    same cell size as normalFont.
  94                    Default:        7x13 (obviously not an italic font)
  95
  96 pointer:           The name of a valid pointer cursor.
  97                    Default:        xterm
  98
  99 pointerForeColor:  The foreground color of the pointer.
 100                    Default:        black
 101
 102 pointerBackColor:  The background color of the pointer.
 103                    Default:        white
 104
 105 textCursor:        The alignment of the text cursor; horizontal or vertical.
 106                    Default:        horizontal
 107
 108 colorBlack:        The color of the COLOR_BLACK attribute.
 109                    Default:        Black
 110
 111 colorRed:          The color of the COLOR_RED attribute.
 112                    Default:        red3
 113
 114 colorGreen:        The color of the COLOR_GREEN attribute.
 115                    Default:        green3
 116
 117 colorYellow:       The color of the COLOR_YELLOW attribute.
 118                    Default:        yellow3
 119
 120 colorBlue:         The color of the COLOR_BLUE attribute.
 121                    Default:        blue3
 122
 123 colorMagenta:      The color of the COLOR_MAGENTA attribute.
 124                    Default:        magenta3
 125
 126 colorCyan:         The color of the COLOR_CYAN attribute.
 127                    Default:        cyan3
 128
 129 colorWhite:        The color of the COLOR_WHITE attribute.
 130                    Default:        Grey
 131
 132 colorBoldBlack:    COLOR_BLACK combined with A_BOLD.
 133                    Default:        grey40
 134
 135 colorBoldRed:      COLOR_RED combined with A_BOLD.
 136                    Default:        red1
 137
 138 colorBoldGreen:    COLOR_GREEN combined with A_BOLD.
 139                    Default:        green1
 140
 141 colorBoldYellow:   COLOR_YELLOW combined with A_BOLD.
 142                    Default:        yellow1
 143
 144 colorBoldBlue:     COLOR_BLUE combined with A_BOLD.
 145                    Default:        blue1
 146
 147 colorBoldMagenta:  COLOR_MAGENTA combined with A_BOLD.
 148                    Default:        magenta1
 149
 150 colorBoldCyan:     COLOR_CYAN combined with A_BOLD.
 151                    Default:        cyan1
 152
 153 colorBoldWhite:    COLOR_WHITE combined with A_BOLD.
 154                    Default:        White
 155
 156 bitmap:            The name of a valid bitmap file of depth 1 (black and white)
 157                    used for the application's icon. The file is an X bitmap.
 158                    Default:        a 32x32 or 64x64 pixmap depending on the
 159                                    window manager
 160
 161 pixmap:            The name of a valid pixmap file of any depth
 162                    supported by the window manager (color) for the
 163                    application's icon, The file is an X11 pixmap. This
 164                    resource is only available if the libXpm package has
 165                    been installed (most systems have this by default).
 166                    This resource overrides the "bitmap" resource.
 167                    Default:        none, uses default bitmap above
 168
 169 translations:      Translations enable the user to customize the action
 170                    that occurs when a key, combination of keys, or a
 171                    button is pressed.  The translations are similar to
 172                    those used by xterm.
 173                    Defaults:
 174                         <Key>:          XCursesKeyPress()
 175                         <KeyUp>:        XCursesKeyPress()
 176                         <BtnDown>:      XCursesButton()
 177                         <BtnUp>:        XCursesButton()
 178                         <BtnMotion>:    XCursesButton()
 179
 180                    The most useful action for KeyPress translations is
 181                    string(). The argument to the string() action can be
 182                    either a string or a hex representation of a
 183                    character; e.g., string(0x1b) will send the ASCII
 184                    escape character to the application; string("[11~")
 185                    will send [ 1 1 ~ , as separate keystrokes.
 186
 187 shmmin:            On most systems, there are two Unix kernel parameters
 188                    that determine the allowable size of a shared memory
 189                    segment. These parameters are usually something like
 190                    SHMMIN and SHMMAX. To use shared memory, a program
 191                    must allocate a segment of shared memory that is
 192                    between these two values.  Usually these values are
 193                    like 1 for SHMMIN and some large number for SHMMAX.
 194                    Sometimes the Unix kernel is configured to have a
 195                    value of SHMMIN that is bigger than the size of one
 196                    of the shared memory segments that libXCurses uses.
 197                    On these systems an error message like:
 198
 199                      Cannot allocate shared memory for SCREEN: Invalid argument
 200
 201                    will result. To overcome this problem, this resource
 202                    should be set to the kernel value for SHMMIN. This
 203                    ensures that a shared memory segment will always be
 204                    bigger than the kernel value for SHMMIN (and
 205                    hopefully less than SHMMAX!)
 206
 207                    Default:        0
 208
 209 borderColor:       The color of the border around the screen.
 210                    Default:        black
 211
 212 borderWidth:       The width in pixels of the border around the screen.
 213                    Default:        0
 214
 215 clickPeriod:       The period (in milliseconds) between a button
 216                    press and a button release that determines if a click
 217                    of a button has occurred.
 218                    Default:        100
 219
 220 doubleClickPeriod: The period (in milliseconds) between two button
 221                    press events that determines if a double click
 222                    of a button has occurred.
 223                    Default:        200
 224
 225 composeKey:        The name of the X key that defines the "compose key",
 226                    which is used to enter characters in the Latin-1
 227                    character set above 0xA0. (See "Compose Keys for
 228                    Latin-1" below.) This is used only when PDCurses is
 229                    built without XIM support. While in compose mode, the
 230                    text cursor will appear as a hollow rectangle.
 231                    Default:        Multi_key
 232
 233
 234 Using Resources
 235 ---------------
 236
 237 All applications have a top-level class name of "XCurses". If Xinitscr()
 238 is used, it sets an application's top-level widget name. (Otherwise the
 239 name defaults to "PDCurses".)
 240
 241 Examples for app-defaults or .Xdefaults:
 242
 243 !
 244 ! resources for XCurses class of programs
 245 !
 246 XCurses*lines:  30
 247 XCurses*cols:   80
 248 XCurses*normalFont:     9x13
 249 XCurses*bitmap: /tmp/xcurses.xbm
 250 XCurses*pointer: top_left_arrow
 251 !
 252 ! resources for testcurs - XCurses
 253 !
 254 testcurs.colorRed:      orange
 255 testcurs.colorBlack:    midnightblue
 256 testcurs.lines: 25
 257 *testcurs.Translations: #override \n \
 258   <Key>F12:  string(0x1b) string("[11~") \n
 259 !
 260 ! resources for THE - XCurses
 261 !
 262 ! resources with the * wildcard can be overridden by a parameter passed
 263 ! to initscr()
 264 !
 265 the*normalFont: 9x15
 266 the*lines:      40
 267 the*cols:       86
 268 the*pointer:    xterm
 269 the*pointerForeColor: white
 270 the*pointerBackColor: black
 271 !
 272 ! resources with the . format can not be overridden by a parameter passed
 273 ! to Xinitscr()
 274 !
 275 the.bitmap:     /home/mark/the/the64.xbm
 276 the.pixmap:     /home/mark/the/the64.xpm
 277
 278 Resources may also be passed as parameters to the Xinitscr() function.
 279 Parameters are strings in the form of switches; e.g., to set the color
 280 "red" to "indianred", and the number of lines to 30, the string passed
 281 to Xinitscr would be: "-colorRed indianred -lines 30"
 282
 283
 284 Compose Keys for Latin-1
 285 ------------------------
 286
 287 When built without XIM support, PDCurses for X11 provides its own,
 288 limited compose key system for Latin-1 characters. The available
 289 combinations are listed here. For a given character, any of the
 290 combinations shown in the last column may be used. To generate a
 291 character, press the "compose" key followed by one of the pairs of
 292 keystrokes. Where no key is evident, the spacebar is used.  Thus, to
 293 generate the NO-BREAK SPACE, press the "compose" key followed by two
 294 hits of the spacebar.
 295
 296 With a typical modern X server, you can get many more compose key
 297 combinations by using XIM instead. Configure PDCurses with --enable-xim
 298 to use XIM support.
 299
 300 This document is encoded in UTF-8.
 301
 302 +----+-----+---+---------------------------------+---------------------------+
 303 |Hex | Dec |Chr| Description ISO 10646-1:1993(E) | Compose key combinations  |
 304 +----+-----+---+---------------------------------+---------------------------+
 305 | A0 | 160 |   | NO-BREAK SPACE                  |                           |
 306 | A1 | 161 | ¡ | INVERTED EXCLAMATION MARK      | !   !!                    |
 307 | A2 | 162 | ¢ | CENT SIGN                      | c|  |c  c/  c$  C$  C|    |
 308 | A3 | 163 | £ | POUND SIGN                     | L-  L$  L=  l-  l$  l=  |-|
 309 | A4 | 164 | ¤ | CURRENCY SIGN                  | xo  ox  XO  g$            |
 310 | A5 | 165 | ¥ | YEN SIGN                       | =y  y=  =Y  Y=  Y-  y$  y-|
 311 | A6 | 166 | ¦ | BROKEN BAR                     | |   ||  vb  VB  |^        |
 312 | A7 | 167 | § | SECTION SIGN                   | SO  SS  s!  S!  so        |
 313 | A8 | 168 | ¨ | DIAERESIS                      | "   ""                    |
 314 | A9 | 169 | © | COPYRIGHT SIGN                         | CO  co  OC                |
 315 | AA | 170 | ª | FEMININE ORDINAL INDICATOR     | sa  SA  a_  A_            |
 316 | AB | 171 | « | LEFT DOUBLE ANGLE QUOTES       | <<                        |
 317 | AC | 172 | ¬ | NOT SIGN                       | -,  no  NO                |
 318 | AD | 173 |  | SOFT HYPHEN                    | -   --                    |
 319 | AE | 174 | ® | REGISTERED SIGN                | RO  ro  OR                |
 320 | AF | 175 | ¯ | MACRON                                 | -^  _^  __                |
 321 | B0 | 176 | ° | DEGREE SIGN                    | o   0^  0*  de  DE  ^0    |
 322 | B1 | 177 | ± | PLUS-MINUS SIGN                | -+  +-                    |
 323 | B2 | 178 | ² | SUPERSCRIPT TWO                | 2   2^  s2  ^2            |
 324 | B3 | 179 | ³ | SUPERSCRIPT THREE              | 3   3^  s3  ^3            |
 325 | B4 | 180 | ´ | ACUTE ACCENT                   | '   ''                    |
 326 | B5 | 181 | µ | MICRO SIGN                     | u   /u  /U  *m  *M        |
 327 | B6 | 182 | ¶ | PILCROW SIGN                   | p!  P!  pg  PG            |
 328 | B7 | 183 | · | MIDDLE DOT                     | .   .^  ..                |
 329 | B8 | 184 | ¸ | CEDILLA                        | ,   ,,                    |
 330 | B9 | 185 | ¹ | SUPERSCRIPT ONE                | 1   1^  s1  ^1            |
 331 | BA | 186 | º | MASCULINE ORDINAL INDICATOR    | o_  s0  S0                |
 332 | BB | 187 | » | RIGHT DOUBLE ANGLE QUOTES      | >>                        |
 333 | BC | 188 | ¼ | VULGAR FRACTION ONE QUARTER    | 14                        |
 334 | BD | 189 | ½ | VULGAR FRACTION ONE HALF       | 12                        |
 335 | BE | 190 | ¾ | VULGAR FRACTION THREE QUARTERS  | 34                       |
 336 | BF | 191 | ¿ | INVERTED QUESTION MARK                 | ?   ??                    |
 337 | C0 | 192 | À | CAPITAL A WITH GRAVE ACCENT    | `A  A`                    |
 338 | C1 | 193 | Á | CAPITAL A WITH ACUTE ACCENT    | 'A  A'                    |
 339 | C2 | 194 | Â | CAPITAL A WITH CIRCUMFLEX ACCENT| ^A  A^  A>               |
 340 | C3 | 195 | Ã | CAPITAL A WITH TILDE           | ~A  A~  A-                |
 341 | C4 | 196 | Ä | CAPITAL A WITH DIAERESIS       | "A  A"                    |
 342 | C5 | 197 | Å | CAPITAL A WITH RING ABOVE      | oA  Ao  A*  OA  *A        |
 343 | C6 | 198 | Æ | CAPITAL LIGATURE AE            | AE                        |
 344 | C7 | 199 | Ç | CAPITAL C WITH CEDILLA                 | ,C  C,                    |
 345 | C8 | 200 | È | CAPITAL E WITH GRAVE ACCENT    | `E  E`                    |
 346 | C9 | 201 | É | CAPITAL E WITH ACUTE ACCENT    | 'E  E'                    |
 347 | CA | 202 | Ê | CAPITAL E WITH CIRCUMFLEX ACCENT| ^E  E^  E>               |
 348 | CB | 203 | Ë | CAPITAL E WITH DIAERESIS       | "E  E"                    |
 349 | CC | 204 | Ì | CAPITAL I WITH GRAVE ACCENT    | `I  I`                    |
 350 | CD | 205 | Í | CAPITAL I WITH ACUTE ACCENT    | 'I  I'                    |
 351 | CE | 206 | Î | CAPITAL I WITH CIRCUMFLEX ACCENT| ^I  I^  I>               |
 352 | CF | 207 | Ï | CAPITAL I WITH DIAERESIS       | "I  I"                    |
 353 | D0 | 208 | Ð | CAPITAL ETH                    | D-                        |
 354 | D1 | 209 | Ñ | CAPITAL N WITH TILDE           | ~N  N~  N-                |
 355 | D2 | 210 | Ò | CAPITAL O WITH GRAVE ACCENT    | `O  O`                    |
 356 | D3 | 211 | Ó | CAPITAL O WITH ACUTE ACCENT    | 'O  O'                    |
 357 | D4 | 212 | Ô | CAPITAL O WITH CIRCUMFLEX ACCENT| ^O  O^  O>               |
 358 | D5 | 213 | Õ | CAPITAL O WITH TILDE           | ~O  O~  O-                |
 359 | D6 | 214 | Ö | CAPITAL O WITH DIAERESIS       | "O  O"                    |
 360 | D7 | 215 | × | MULTIPLICATION SIGN            | x   xx  XX  mu  MU        |
 361 | D8 | 216 | Ø | CAPITAL O WITH STROKE          | /O  O/                    |
 362 | D9 | 217 | Ù | CAPITAL U WITH GRAVE ACCENT    | `U  U`                    |
 363 | DA | 218 | Ú | CAPITAL U WITH ACUTE ACCENT    | 'U  U'                    |
 364 | DB | 219 | Û | CAPITAL U WITH CIRCUMFLEX ACCENT| ^U  U^  U>               |
 365 | DC | 220 | Ü | CAPITAL U WITH DIAERESIS       | "U  U"                    |
 366 | DD | 221 | Ý | CAPITAL Y WITH ACUTE ACCENT    | 'Y  Y'                    |
 367 | DE | 222 | Þ | CAPITAL THORN                  | P   TH  |P                |
 368 | DF | 223 | ß | SMALL SHARP S                  | ss                        |
 369 | E0 | 224 | à | SMALL A WITH GRAVE ACCENT      | `a  a`                    |
 370 | E1 | 225 | á | SMALL A WITH ACUTE ACCENT      | 'a  a'                    |
 371 | E2 | 226 | â | SMALL A WITH CIRCUMFLEX ACCENT  | ^a  a^  a>               |
 372 | E3 | 227 | ã | SMALL A WITH TILDE             | ~a  a~  a-                |
 373 | E4 | 228 | ä | SMALL A WITH DIAERESIS                 | "a  a"                    |
 374 | E5 | 229 | å | SMALL A WITH RING ABOVE        | oa  ao  Oa  a*  *a        |
 375 | E6 | 230 | æ | SMALL LIGATURE AE              | ae                        |
 376 | E7 | 231 | ç | SMALL C WITH CEDILLA           | ,c  c,                    |
 377 | E8 | 232 | è | SMALL E WITH GRAVE ACCENT      | `e  e`                    |
 378 | E9 | 233 | é | SMALL E WITH ACUTE ACCENT      | 'e  e'                    |
 379 | EA | 234 | ê | SMALL E WITH CIRCUMFLEX ACCENT  | ^e  e^  e>               |
 380 | EB | 235 | ë | SMALL E WITH DIAERESIS                 | "e  e"                    |
 381 | EC | 236 | ì | SMALL I WITH GRAVE ACCENT      | `i  i`                    |
 382 | ED | 237 | í | SMALL I WITH ACUTE ACCENT      | 'i  i'                    |
 383 | EE | 238 | î | SMALL I WITH CIRCUMFLEX ACCENT  | ^i  i^  i>               |
 384 | EF | 239 | ï | SMALL I WITH DIAERESIS                 | "i  i"                    |
 385 | F0 | 240 | ð | SMALL ETH                      | d-                        |
 386 | F1 | 241 | ñ | SMALL N WITH TILDE             | ~n  n~  n-                |
 387 | F2 | 242 | ò | SMALL O WITH GRAVE ACCENT      | `o  o`                    |
 388 | F3 | 243 | ó | SMALL O WITH ACUTE ACCENT      | 'o  o'                    |
 389 | F4 | 244 | ô | SMALL O WITH CIRCUMFLEX ACCENT  | ^o  o^  o>               |
 390 | F5 | 245 | õ | SMALL O WITH TILDE             | ~o  o~  o-                |
 391 | F6 | 246 | ö | SMALL O WITH DIAERESIS                 | "o  o"                    |
 392 | F7 | 247 | ÷ | DIVISION SIGN                  | -:  :-                    |
 393 | F8 | 248 | ø | SMALL O WITH OBLIQUE BAR       | /o  o/                    |
 394 | F9 | 249 | ù | SMALL U WITH GRAVE ACCENT      | `u  u`                    |
 395 | FA | 250 | ú | SMALL U WITH ACUTE ACCENT      | 'u  u'                    |
 396 | FB | 251 | û | SMALL U WITH CIRCUMFLEX ACCENT  | ^u  u^  u>               |
 397 | FC | 252 | ü | SMALL U WITH DIAERESIS                 | "u  u"                    |
 398 | FD | 253 | ý | SMALL Y WITH ACUTE ACCENT      | 'y  y'                    |
 399 | FE | 254 | þ | SMALL THORN                    | p   th  |p                |
 400 | FF | 255 | ÿ | SMALL Y WITH DIAERESIS                 | "y  y"                    |
 401 +----+-----+---+---------------------------------+---------------------------+
 402
 403
 404 Deprecated
 405 ----------
 406
 407 XCursesProgramName is no longer used. To set the program name, you must
 408 use Xinitscr(), or PDC_set_title() to set just the window title.
 409
 410 The XCursesExit() function is now called automatically via atexit().
 411 (Multiple calls to it are OK, so you don't need to remove it if you've
 412 already added it for previous versions of PDCurses.)
 413
 414 XCURSES is no longer defined automatically, but need not be defined,
 415 unless you want the X11-specific prototypes. (Normal curses programs
 416 won't need it.)