1curses(3XCURSES) X/Open Curses Library Functions curses(3XCURSES)
2
6 curses - introduction and overview of X/Open Curses
7
9 The Curses screen management package conforms fully with Issue 4, Ver‐
10 sion 2 of the X/Open Curses specification. It provides a set of
11 internationalized functions and macros for creating and modifying
12 input and output to a terminal screen. This includes functions for
13 creating windows, highlighting text, writing to the screen, reading
14 from user input, and moving the cursor.
15 X/Open Curses is a terminal-independent package, providing a common
18 user interface to a variety of terminal types. Its portability is
19 facilitated by the Terminfo database which contains a compiled defini‐
20 tion of each terminal type. By referring to the database information
21 X/Open Curses gains access to low-level details about individual termi‐
22 nals.
23 X/Open Curses tailors its activities to the terminal type specified by
26 the TERM environment variable. The TERM environment variable may be
27 set in the Korn Shell (see ksh(1)) by typing:
28 export TERM=terminal_name
30 To set environment variables using other command line interfaces or
35 shells, see the environ(5) manual page.
36 Three additional environment variables are useful, and can be set in
39 the Korn Shell:
40 1. If you have an alternate Terminfo database containing termi‐
42 nal types that are not available in the system default data‐
43 base /usr/share/lib/terminfo, you can specify the TERMINFO
44 environment variable to point to this alternate database:
45 export TERMINFO=path
47 This path specifies the location of the alternate compiled
50 Terminfo database whose structure consists of directory
51 names 0 to 9 and a to z (which represent the first letter
52 of the compiled terminal definition file name).
53 The alternate database specified by TERMINFO is examined
55 before the system default database. If the terminal type
56 specified by TERM cannot be found in either database, the
57 default terminal type dumb is assumed.
58 2. To specify a window width smaller than your screen width
60 (for example, in situations where your communications line
61 is slow), set the COLUMNS environment variable to the
62 number of vertical columns you want between the left and
63 right margins:
64 export COLUMNS=number
66 The number of columns may be set to a number smaller than
69 the screen size; however, if set larger than the screen or
70 window width, the results are undefined.
71 The value set using this environment variable takes prece‐
73 dence over the value normally used for the terminal.
74 3. To specify a window height smaller than your current screen
76 height (for example, in situations where your communications
77 line is slow), override the LINES environment variable by
78 setting it to a smaller number of horizontal lines:
79 export LINES=number
81 The number of lines may be set to a number smaller than the
84 screen height; however, if set larger than the screen or
85 window height, the results are undefined.
86 The value set using this environment variable takes prece‐
88 dence over the value normally used for the terminal.
89 Data Types
91 X/Open Curses defines the following data types:
92 attr_t An integral type that holds an OR-ed set of attributes. The
94 attributes acceptable are those which begin with the WA_
95 prefix .
96 bool Boolean data type.
99 cchar_t A type that refers to a string consisting of a spacing wide
102 character, up to 5 non-spacing wide characters, and zero
103 or more attributes of any type. See Attributes, Color
104 Pairs, and Renditions. A null cchar_t object terminates
105 arrays of cchar_t objects.
106 chtype An integral type whose values are formed by OR-ing an
109 "unsigned char" with a color pair. and with zero or more
110 attributes. The attributes acceptable are those which begin
111 with the A_ prefix and COLOR_PAIR(3XCURSES)
112 SCREEN An opaque data type associated with a terminal's display
115 screen.
116 TERMINAL An opaque data type associated with a terminal. It contains
119 information about the terminal's capabilities (as defined
120 by terminfo), the terminal modes, and current state of
121 input/output operations.
122 wchar_t An integral data type whose values represent wide charac‐
125 ters.
126 WINDOW An opaque data type associated with a window.
129 Screens, Windows, and Terminals
132 The X/Open Curses manual pages refer at various points to screens, win‐
133 dows (also subwindows, derived windows, and pads), and terminals. The
134 following list defines each of these terms.
135 Screen A screen is a terminal's physical output device. The SCREEN
137 data type is associated with a terminal.
138 Window Window objects are two-dimensional arrays of characters and
141 their renditions. X/Open Curses provides stdscr, a default
142 window which is the size of of the terminal screen. You can
143 use the newwin(3XCURSES) function to create others.
144 To refer to a window, use a variable declared as WINDOW *. X/Open
148 Curses includes both functions that modify stdscr, and more general
149 versions that let you specify a window.
150 There are three sub-types of windows:
153 Subwindow A window which has been created within another window
155 (the parent window) and whose position has been spec‐
156 ified with absolute screen coordinates. The der‐
157 win(3XCURSES) and subwin(3XCURSES) functions can be
158 used to create subwindows.
159 Derived Window A subwindow whose position is defined relative to the
162 parent window's coordinates rather than in absolute
163 terms.
164 Pad A special type of window that can be larger than the
167 screen. For more information, see the new‐
168 pad(3XCURSES) man page.
169 Terminal A terminal is the input and output device which char‐
172 acter-based applications use to interact with the
173 user. The TERMINAL data type is associated with such
174 a device.
175 Attributes, Color Pairs, and Renditions
178 A character's rendition consists of its attributes (such as underlining
179 or reverse video) and its color pair (the foreground and background
180 colors). When using waddstr(3XCURSES), waddchstr(3XCURSES),
181 wprintw(3XCURSES), winsch(3XCURSES), and so on, the window's rendition
182 is combined with that character's renditions. The window rendition is
183 the attributes and color set using the attroff(3XCURSES) and
184 attr_off(3XCURSES) sets of functions. The window's background character
185 and rendition are set with the bkgdset(3XCURSES) and bkgrnd‐
186 set(3XCURSES) sets of functions.
187 When spaces are written to the screen, the background character and
190 window rendition replace the space. For example, if the background
191 rendition and character is A_UNDERLINE|'*', text written to the window
192 appears underlined and the spaces appear as underlined asterisks.
193 Each character written retains the rendition that it has obtained. This
196 allows the character to be copied "as is" to or from a window with the
197 addchstr(3XCURSES) or inch(3XCURSES) functions.
198 A_ Constant Values for Attributes
200 You can specify Attributes, Color Pairs, and Renditions attributes
201 using the constants listed in the tables below. The following constants
202 modify objects of type chtype:
203 ┌──────────────────────────────────────────────────────────────┐
208 │ Constant Description │
209 ├──────────────────────────────────────────────────────────────┤
210 │A_ALTCHARSET Alternate character set │
211 │A_ATTRIBUTES Bit-mask to extract attributes │
212 │A_BLINK Blinking │
213 │A_BOLD Bold │
214 │A_CHARTEXT Bit-mask to extract a character │
215 │A_COLOR Bit-mask to extract color-pair │
216 │ information │
217 │A_DIM Half-bright │
218 │A_INVIS Invisible │
219 │A_PROTECT Protected │
220 │A_REVERSE Reverse video │
221 │A_STANDOUT Highlights specific to terminal │
222 │A_UNDERLINE Underline │
223 └──────────────────────────────────────────────────────────────┘
224 WA_ Constant Values for Attributes
226 The following constants modify objects of type attr_t:
227 ┌──────────────────────────────────────────────────────────────┐
232 │ Constant Description │
233 ├──────────────────────────────────────────────────────────────┤
234 │WA_ALTCHARSET Alternate character set │
235 │WA_ATTRIBUTES Attribute mask │
236 │WA_BLINK Blinking │
237 │WA_BOLD Bold │
238 │WA_DIM Half-bright │
239 │WA_HORIZONTAL Horizontal highlight │
240 │WA_INVIS Invisible │
241 │WA_LEFT Left highlist │
242 │WA_LOW Low highlist │
243 │WA_PROTECT Protected │
244 │WA_REVERSE Reverse video │
245 │WA_RIGHT Right highlight │
246 │WA_STANDOUT Highlights specific to terminal │
247 │WA_TOP Top highlight │
248 │WA_UNDERLINE Underline │
249 │WA_VERTICAL Vertical highlight │
250 └──────────────────────────────────────────────────────────────┘
251 Color Macros
253 Colors always appear in pairs; the foreground color of the character
254 itself and the background color of the field on which it is displayed.
255 The following color macros are defined:
256 ┌───────────────────────────────────────────────────────────┐
261 │ Macro Description │
262 ├───────────────────────────────────────────────────────────┤
263 │COLOR_BLACK Black │
264 │COLOR_BLUE Blue │
265 │COLOR_GREEN Green │
266 │COLOR_CYAN Cyan │
267 │COLOR_RED Red │
268 │COLOR_MAGENTA Magenta │
269 │COLOR_YELLOW Yellow │
270 │COLOR_WHITE White │
271 └───────────────────────────────────────────────────────────┘
272 Together, a character's attributes and its color pair form the charac‐
275 ter's rendition. A character's rendition moves with the character dur‐
276 ing any scrolling or insert/delete operations. If your terminal lacks
277 support for the specified rendition, X/Open Curses may substitute a
278 different rendition.
279 The COLOR_PAIR(3XCURSES) function modifies a chtype object. The
282 PAIR_NUMBER(3XCURSES) function extracts the color pair from a chtype
283 object.
284 Functions for Modifying a Window's Color
286 The following functions modify a window's color:
287 ┌─────────────────────────────────────────────────────────────┐
292 │ Function Description │
293 ├─────────────────────────────────────────────────────────────┤
294 │attr_set(), wattr_set() Change the window's rendition. │
295 │color_set(), wcolor_set() Set the window's color │
296 └─────────────────────────────────────────────────────────────┘
297 Non-Spacing Characters
299 When the wcwidth(3C) function returns a width of zero for a character,
300 that character is called a non-spacing character. Non-spacing charac‐
301 ters can be written to a window. Each non-spacing character is associ‐
302 ated with a spacing character (that is, one which does not have a width
303 of zero) and modifies that character. You cannot address a non-spacing
304 character directly. Whenever you perform an X/Open Curses operation on
305 the associated character, you are implicitly addressing the non-spac‐
306 ing character.
307 Non-spacing characters do not have a rendition. For functions that use
310 wide characters and a rendition, X/Open Curses ignores any rendition
311 specified for non-spacing characters. Multi-column characters have one
312 rendition that applies to all columns spanned.
313 Complex Characters
315 The cchar_t date type represents a complex character. A complex charac‐
316 ter may contain a spacing character, its associated non-spacing charac‐
317 ters, and its rendition. This implementation of complex characters sup‐
318 ports up to 5 non-spacing characters for each spacing character.
319 When a cchar_t object representing a non-spacing complex character is
322 written to the screen, its rendition is not used, but rather it becomes
323 associated with the rendition of the existing character at that loca‐
324 tion. The setcchar(3XCURSES) function initializes an object of type
325 cchar_t. The getcchar(3XCURSES) function extracts the contents of a
326 cchar_t object.
327 Display Operations
329 In adding internationalization support to X/Open Curses, every attempt
330 was made to minimize the number of changes to the historical CURSES
331 package. This enables programs written to use the historical implemen‐
332 tation of CURSES to use the internationalized version with little or no
333 modification. The following rules apply to the internationalized X/Open
334 Curses package:
335 o The cursor can be placed anywhere in the window. Window
337 and screen origins are (0,0).
338 o A multi-column character cannot be displayed in the last
340 column, because the character would appear truncated.
341 Instead, the background character is displayed in the last
342 column and the multi-column character appears at the begin‐
343 ning of the next line. This is called wrapping.
344 If the original line is the last line in the scroll region
346 and scrolling is enabled, X/Open Curses moves the contents
347 of each line in the region to the previous line. The first
348 line of the region is lost. The last line of the scrolling
349 region contains any wrapped characters. The remainder of
350 that line is filled with the background character. If
351 scrolling is disabled, X/Open Curses truncates any character
352 that would extend past the last column of the screen.
353 o Overwrites operate on screen columns. If displaying a sin‐
355 gle-column or multi-column character results in overwriting
356 only a portion of a multi-column character or characters,
357 background characters are displayed in place of the non-
358 overwritten portions.
359 o Insertions and deletions operate on whole characters. The
361 cursor is moved to the first column of the character prior
362 to performing the operation.
363 Overlapping Windows
365 When windows overlap, it may be necessary to overwrite only part of a
366 multi-column character. As mentioned earlier, the non-overwritten
367 portions are replaced with the background character. This results in
368 issues concerning the overwrite(3XCURSES), overlay(3XCURSES), copy‐
369 win(3XCURSES), wnoutrefresh(3XCURSES), and wrefresh(3XCURSES) func‐
370 tions.
371 Special Characters
373 Some functions assign special meanings to certain special characters:
374 Backspace Moves the cursor one column towards the beginning
376 of the line. If the cursor was already at the
377 beginning of the line, it remains there. All sub‐
378 sequent characters are added or inserted at this
379 point.
380 Carriage Return Moves the cursor to the beginning of the current
383 line. If the cursor was already at the beginning
384 of the line, it remains there. All subsequent
385 characters are added or inserted at this point.
386 Newline When adding characters, X/Open Curses fills the
389 remainder of the line with the background charac‐
390 ter (effectively truncating the newline) and
391 scrolls the window as described earlier. All
392 subsequent characters are inserted at the start
393 of the new line.
394 When inserting characters, X/Open Curses fills
396 the remainder of the line with the background
397 character (effectively truncating the line),
398 moves the cursor to the beginning of a new line,
399 and scrolls the window as described earlier. All
400 subsequent characters are placed at the start of
401 the new line.
402 Tab moves subsequent characters to next horizontal
405 tab strop. Default tab stops are set at 0, 8, 16,
406 and so on.
407 When adding or inserting characters, X/Open
409 Curses inserts or adds the background character
410 into each column until the next tab stop is
411 reached. If there are no remaining tab stops on
412 the current line, wrapping and scrolling occur
413 as described earlier.
414 Control Characters When X/Open Curses functions perform special
417 character processing, they convert control char‐
418 acters to the ^X notation, where X is a single-
419 column character (uppercase, if it is a letter)
420 and writes that notation to the window. Func‐
421 tions that retrieve text from the window will
422 retrieve the converted notation not the original.
423 X/Open Curses displays non-printable bytes, that have their high bit
427 set, using the M-X meta notation where X is the non-printable byte with
428 its high bit turned off.
429 Input Processing
431 There are four input modes possible with X/Open Curses that affect the
432 behavior of input functions like getch(3XCURSES) and getnstr(3XCURSES).
433 Line Canonical (Cooked) In line input mode, the terminal driver han‐
435 dles the input of line units as well as
436 SIGERASE and SIGKILL character processing.
437 See termio(7I) for more information.
438 In this mode, the getch() and getnstr()
440 functions will not return until a complete
441 line has been read by the terminal driver,
442 at which point only the requested number of
443 bytes/characters are returned. The rest of
444 the line unit remains unread until subse‐
445 quent call to the getch() or getnstr()
446 functions.
447 The functions nocbreak(3XCURSES) and
449 noraw(3XCURSES) are used to enter this mode.
450 These functions are described on the
451 cbreak(3XCURSES) man page which also details
452 which termios flags are enabled.
453 Of the modes available, this one gives
455 applications the least amount of control
456 over input. However, it is the only input
457 mode possible on a block mode terminal.
458 cbreak Mode Byte/character input provides a finer degree
461 of control. The terminal driver passes
462 each byte read to the application without
463 interpreting erase and kill characters. It
464 is the application's responsibility to han‐
465 dle line editing. It is unknown whether the
466 signal characters (SIGINTR, SIGQUIT, SIG‐
467 SUSP) and flow control characters (SIGSTART,
468 SIGSTOP) are enabled. To ensure that they
469 are, call the noraw() function first, then
470 call the cbreak() function.
471 halfdelay Mode This is the same as the cbreak() mode with a
474 timeout. The terminal driver waits for a
475 byte to be received or for a timer to
476 expire, in which case the getch() function
477 either returns a byte or ERR respectively.
478 This mode overrides timeouts set for an
479 individual window with the wtimeout() func‐
480 tion.
481 raw Mode This mode provides byte/character input with
484 the most control for an application. It is
485 similar to cbreak() mode, but also disables
486 signal character processing (SIGINTR, SIG‐
487 SUSP, SIGQUIT) and flow control processing
488 (SIGSTART, SIGSTOP) so that the application
489 can process them as it wants.
490 These modes affect all X/Open Curses input. The default input mode is
494 inherited from the parent process when the application starts up.
495 A timeout similar to halfdelay(3XCURSES) can be applied to individual
498 windows (see timeout(3XCURSES)). The nodelay(3XCURSES) function is
499 equivalent to setting wtimeout(3XCURSES) for a window with a zero time‐
500 out (non-blocking) or infinite delay (blocking).
501 To handle function keys, keypad(3XCURSES) must be enabled. When it is
504 enabled, the getch() function returns a KEY_ constant for a uniquely
505 encoded key defined for that terminal. When keypad() is disabled, the
506 getch() function returns the individual bytes composing the function
507 key (see getch(3XCURSES) and wget_wch(3XCURSES)). By default, key‐
508 pad() is disabled.
509 When processing function keys, once the first byte is recognized, a
512 timer is set for each subsequent byte in the sequence. If any byte in
513 the function key sequence is not received before the timer expires,
514 the bytes already received are pushed into a buffer and the original
515 first byte is returned. Subsequent X/Open Curses input would take bytes
516 from the buffer until exhausted, after which new input from the termi‐
517 nal will be requested. Enabling and disabling of the function key
518 interbyte timer is handled by the notimeout(3XCURSES) function. By
519 default, notimeout() is disabled (that is, the timer is used).
520 X/Open Curses always disables the terminal driver's echo processing.
523 The echo(3XCURSES) and noecho(3XCURSES) functions control X/Open Curses
524 software echoing. When software echoing is enabled, X/Open Curses
525 input functions echo printable characters, control keys, and meta keys
526 in the input window at the last cursor position. Functions keys are
527 never echoed. When software echoing is disabled, it is the applica‐
528 tion's responsibility to handle echoing.
529
531 Example 1 Copying Single-Column Characters Over Single-Column Charac‐
532 ters
533 In the upcoming examples, some characters have special meanings:
536 o {, [, and ( represent the left halves of multi-column char‐
539 acters. }, ], and ) represent the corresponding right halves
540 of the same multi-column characters.
541 o Alphanumeric characters and periods (.) represent single-
543 column characters.
544 o The number sign (#) represents the background character.
546 copywin(s, t, 0, 1, 0, 1, 1, 3, 0)
548 s t → t
550 abcdef ...... .bcd..
551 ghijkl ...... .hij..
552 There are no special problems with this situation.
556 Example 2 Copying Multi-column Characters Over Single-Column Characters
559 copywin(s, t, 0, 1, 0, 1, 1, 3, 0)
561 s t → t
563 a[]def ...... .[]d..
564 gh()kl ...... .h()..
565 There are no special problems with this situation.
569 Example 3 Copying Single-Column Characters From Source Overlaps Multi-
572 column Characters In Target
573 copywin(s, t, 0, 1, 0, 1, 1, 3, 0)
575 s t → t
577 abcdef [].... #bcd..
578 ghijk tol ...(). .hij#.
579 Overwriting multi-column characters in t has resulted in the # back‐
583 ground characters being required to erase the remaining halves of the
584 target's multi-column characters.
585 Example 4 Copy Incomplete Multi-column Characters From Source To Tar‐
588 get.
589 copywin(s, t, 0, 1, 0, 1, 1, 3, 0)
591 s t → t
593 []cdef 123456 []cd56
594 ghi()l 789012 7hi()2
595 The ] and ( halves of the multi-column characters have been copied from
599 the source and expanded in the target outside of the specified target
600 region.
601 Consider a pop-up dialog box that contains single-column characters and
605 a base window that contains multi-column characters and you do the fol‐
606 lowing:
607 save=dupwin(dialog); /* create backing store */
610 overwrite(cursor, save); /* save region to be overlayed */
611 wrefresh(dialog); /* display dialog */
612 wrefresh(save); /* restore screen image */
613 delwin(save); /* release backing store */
614 You can use code similar to this to implement generic popup() and pop‐
618 down() routines in a variety of CURSES implementations (including BSD
619 UNIX, and UNIX System V). In the simple case where the base window con‐
620 tains single-column characters only, it would correctly restore the
621 image that appeared on the screen before the dialog box was displayed.
622 However, with multi-column characters, the overwrite() function might
626 save a region with incomplete multi-column characters. The wre‐
627 fresh(dialog) statement results in the behavior described in example 3
628 above. The behavior described in this example (that is, example 4)
629 allows the wrefresh(save) statement to restore the window correctly.
630 Example 5 Copying An Incomplete Multi-column Character To Region Next
633 To Screen Margin (Not A Window Edge)
634 Two cases of copying an incomplete multi-column character to a region
637 next to a screen margin follow:
638 copywin(s, t, 0, 1, 0, 0, 1, 2, 0)
641 s t → t
643 []cdef 123456 #cd456
644 ghijkl 789012 hij012
645 The background character (#) replaces the ] character that would have
649 been copied from the source, because it is not possible to expand the
650 multi-column character to its complete form.
651 copywin(s, t, 0, 1, 0, 3, 1, 5, 0)
654 s t → t
656 abcdef 123456 123bcd
657 ghi()l 789012 789hi#
658 This second example is the same as the first, but with the right mar‐
662 gin.
663
666 See attributes(5) for descriptions of the following attributes:
667 ┌─────────────────────────────┬─────────────────────────────┐
672 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
673 ├─────────────────────────────┼─────────────────────────────┤
674 │Interface Stability │Standard │
675 ├─────────────────────────────┼─────────────────────────────┤
676 │MT-Level │Unsafe │
677 └─────────────────────────────┴─────────────────────────────┘
678
680 ksh(1), COLOR_PAIR(3XCURSES), PAIR_NUMBER(3XCURSES), addch‐
681 str(3XCURSES), attr_off(3XCURSES), attroff(3XCURSES),
682 bkgdset(3XCURSES), bkgrndset(3XCURSES), cbreak(3XCURSES), copy‐
683 win(3XCURSES), derwin(3XCURSES), echo(3XCURSES), getcchar(3XCURSES),
684 getch(3XCURSES), getnstr(3XCURSES), halfdelay(3XCURSES),
685 inch(3XCURSES), keypad(3XCURSES), libcurses(3XCURSES), new‐
686 pad(3XCURSES), newwin(3XCURSES), nocbreak(3XCURSES), nodelay(3XCURSES),
687 noecho(3XCURSES), noraw(3XCURSES), notimeout(3XCURSES), over‐
688 lay(3XCURSES), overwrite(3XCURSES), setcchar(3XCURSES), sub‐
689 win(3XCURSES), timeout(3XCURSES), waddchstr(3XCURSES),
690 waddstr(3XCURSES), wcwidth(3C), wget_wch(3XCURSES), winsch(3XCURSES),
691 wnoutrefresh(3XCURSES), wprintw(3XCURSES), wrefresh(3XCURSES), wtime‐
692 out(3XCURSES), attributes(5), environ(5), standards(5), termio(7I)
693SunOS 5.11 5 Jun 2002 curses(3XCURSES)