LXVIII. Ncurses terminal screen control functions
Introduction
ncurses (new curses) is a free software emulation of curses in System V Rel 4.0 (and above). It uses terminfo format, supports pads, colors, multiple highlights, form characters and function key mapping. Because of the interactive nature of this library, it will be of little use for writing Web applications, but may be useful when writing scripts meant using PHP from the command line.
| Warning |
This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and anything else documented about this extension -- may change without notice in a future release of PHP. Use this extension at your own risk. |
Ncurses is available for the following platforms:
AIX
BeOS
Cygwin
Digital Unix (aka OSF1)
FreeBSD
GNU/Linux
HPUX
IRIX
OS/2
SCO OpenServer
Solaris
SunOS
Requirements
You need the ncurses libraries and headerfiles. Download the latest version from the ftp://ftp.gnu.org/pub/gnu/ncurses/ or from an other GNU-Mirror.
Installation
To get these functions to work, you have to compile the CGI or CLI version of PHP with --with-ncurses[=DIR].
Runtime Configuration
The behaviour of these functions is affected by settings in php.ini.
Table 1. Ncurses configuration options
| Name | Default | Changeable |
|---|---|---|
| ncurses.value | "42" | PHP_INI_ALL |
| ncurses.string | "foobar" | PHP_INI_ALL |
Predefined Constants
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Colors
Table 2. ncurses color constants
| constant | meaning |
|---|---|
| NCURSES_COLOR_BLACK | no color (black) |
| NCURSES_COLOR_WHITE | white |
| NCURSES_COLOR_RED | red - supported when terminal is in color mode |
| NCURSES_COLOR_GREEN | green - supported when terminal is in color mod |
| NCURSES_COLOR_YELLOW | yellow - supported when terminal is in color mod |
| NCURSES_COLOR_BLUE | blue - supported when terminal is in color mod |
| NCURSES_COLOR_CYAN | cyan - supported when terminal is in color mod |
| NCURSES_COLOR_MAGENTA | magenta - supported when terminal is in color mod |
Keys
Table 3. ncurses key constants
| constant | meaning |
|---|---|
| NCURSES_KEY_F0 - NCURSES_KEY_F64 | function keys F1 - F64 |
| NCURSES_KEY_DOWN | down arrow |
| NCURSES_KEY_UP | up arrow |
| NCURSES_KEY_LEFT | left arrow |
| NCURSES_KEY_RIGHT | right arrow |
| NCURSES_KEY_HOME | home key (upward+left arrow) |
| NCURSES_KEY_BACKSPACE | backspace |
| NCURSES_KEY_DL | delete line |
| NCURSES_KEY_IL | insert line |
| NCURSES_KEY_DC | delete character |
| NCURSES_KEY_IC | insert char or enter insert mode |
| NCURSES_KEY_EIC | exit insert char mode |
| NCURSES_KEY_CLEAR | clear screen |
| NCURSES_KEY_EOS | clear to end of screen |
| NCURSES_KEY_EOL | clear to end of line |
| NCURSES_KEY_SF | scroll one line forward |
| NCURSES_KEY_SR | scroll one line backward |
| NCURSES_KEY_NPAGE | next page |
| NCURSES_KEY_PPAGE | previous page |
| NCURSES_KEY_STAB | set tab |
| NCURSES_KEY_CTAB | clear tab |
| NCURSES_KEY_CATAB | clear all tabs |
| NCURSES_KEY_SRESET | soft (partial) reset |
| NCURSES_KEY_RESET | reset or hard reset |
| NCURSES_KEY_PRINT | |
| NCURSES_KEY_LL | lower left |
| NCURSES_KEY_A1 | upper left of keypad |
| NCURSES_KEY_A3 | upper right of keypad |
| NCURSES_KEY_B2 | center of keypad |
| NCURSES_KEY_C1 | lower left of keypad |
| NCURSES_KEY_C3 | lower right of keypad |
| NCURSES_KEY_BTAB | back tab |
| NCURSES_KEY_BEG | beginning |
| NCURSES_KEY_CANCEL | cancel |
| NCURSES_KEY_CLOSE | close |
| NCURSES_KEY_COMMAND | cmd (command) |
| NCURSES_KEY_COPY | copy |
| NCURSES_KEY_CREATE | create |
| NCURSES_KEY_END | end |
| NCURSES_KEY_EXIT | exit |
| NCURSES_KEY_FIND | find |
| NCURSES_KEY_HELP | help |
| NCURSES_KEY_MARK | mark |
| NCURSES_KEY_MESSAGE | message |
| NCURSES_KEY_MOVE | move |
| NCURSES_KEY_NEXT | next |
| NCURSES_KEY_OPEN | open |
| NCURSES_KEY_OPTIONS | options |
| NCURSES_KEY_PREVIOUS | previous |
| NCURSES_KEY_REDO | redo |
| NCURSES_KEY_REFERENCE | ref (reference) |
| NCURSES_KEY_REFRESH | refresh |
| NCURSES_KEY_REPLACE | replace |
| NCURSES_KEY_RESTART | restart |
| NCURSES_KEY_RESUME | resume |
| NCURSES_KEY_SAVE | save |
| NCURSES_KEY_SBEG | shiftet beg (beginning) |
| NCURSES_KEY_SCANCEL | shifted cancel |
| NCURSES_KEY_SCOMMAND | shifted command |
| NCURSES_KEY_SCOPY | shifted copy |
| NCURSES_KEY_SCREATE | shifted create |
| NCURSES_KEY_SDC | shifted delete char |
| NCURSES_KEY_SDL | shifted delete line |
| NCURSES_KEY_SELECT | select |
| NCURSES_KEY_SEND | shifted end |
| NCURSES_KEY_SEOL | shifted end of line |
| NCURSES_KEY_SEXIT | shifted exit |
| NCURSES_KEY_SFIND | shifted find |
| NCURSES_KEY_SHELP | shifted help |
| NCURSES_KEY_SHOME | shifted home |
| NCURSES_KEY_SIC | shifted input |
| NCURSES_KEY_SLEFT | shifted left arrow |
| NCURSES_KEY_SMESSAGE | shifted message |
| NCURSES_KEY_SMOVE | shifted move |
| NCURSES_KEY_SNEXT | shifted next |
| NCURSES_KEY_SOPTIONS | shifted options |
| NCURSES_KEY_SPREVIOUS | shifted previous |
| NCURSES_KEY_SPRINT | shifted print |
| NCURSES_KEY_SREDO | shifted redo |
| NCURSES_KEY_SREPLACE | shifted replace |
| NCURSES_KEY_SRIGHT | shifted right arrow |
| NCURSES_KEY_SRSUME | shifted resume |
| NCURSES_KEY_SSAVE | shifted save |
| NCURSES_KEY_SSUSPEND | shifted suspend |
| NCURSES_KEY_UNDO | undo |
| NCURSES_KEY_MOUSE | mouse event has occured |
| NCURSES_KEY_MAX | maximum key value |
Mouse
Table 4. mouse constants
| Constant | meaning |
|---|---|
| NCURSES_BUTTON1_RELEASED - NCURSES_BUTTON4_RELEASED | button (1-4) released |
| NCURSES_BUTTON1_PRESSED - NCURSES_BUTTON4_PRESSED | button (1-4) pressed |
| NCURSES_BUTTON1_CLICKED - NCURSES_BUTTON4_CLICKED | button (1-4) clicked |
| NCURSES_BUTTON1_DOUBLE_CLICKED - NCURSES_BUTTON4_DOUBLE_CLICKED | button (1-4) double clicked |
| NCURSES_BUTTON1_TRIPLE_CLICKED - NCURSES_BUTTON4_TRIPLE_CLICKED | button (1-4) triple clicked |
| NCURSES_BUTTON_CTRL | ctrl pressed during click |
| NCURSES_BUTTON_SHIFT | shift pressed during click |
| NCURSES_BUTTON_ALT | alt pressed during click |
| NCURSES_ALL_MOUSE_EVENTS | report all mouse events |
| NCURSES_REPORT_MOUSE_POSITION | report mouse position |
- Table of Contents
- ncurses_addch -- Add character at current position and advance cursor
- ncurses_addchnstr -- Add attributed string with specified length at current position
- ncurses_addchstr -- Add attributed string at current position
- ncurses_addnstr -- Add string with specified length at current position
- ncurses_addstr -- Output text at current position
- ncurses_assume_default_colors -- Define default colors for color 0
- ncurses_attroff -- Turn off the given attributes
- ncurses_attron -- Turn on the given attributes
- ncurses_attrset -- Set given attributes
- ncurses_baudrate -- Returns baudrate of terminal
- ncurses_beep -- Let the terminal beep
- ncurses_bkgd -- Set background property for terminal screen
- ncurses_bkgdset -- Control screen background
- ncurses_border -- Draw a border around the screen using attributed characters
- ncurses_bottom_panel -- Moves a visible panel to the bottom of the stack
- ncurses_can_change_color -- Check if we can change terminals colors
- ncurses_cbreak -- Switch of input buffering
- ncurses_clear -- Clear screen
- ncurses_clrtobot -- Clear screen from current position to bottom
- ncurses_clrtoeol -- Clear screen from current position to end of line
- ncurses_color_content -- Gets the RGB value for color
- ncurses_color_set -- Set fore- and background color
- ncurses_curs_set -- Set cursor state
- ncurses_def_prog_mode -- Saves terminals (program) mode
- ncurses_def_shell_mode -- Saves terminals (shell) mode
- ncurses_define_key -- Define a keycode
- ncurses_del_panel -- Remove panel from the stack and delete it (but not the associated window)
- ncurses_delay_output -- Delay output on terminal using padding characters
- ncurses_delch -- Delete character at current position, move rest of line left
- ncurses_deleteln -- Delete line at current position, move rest of screen up
- ncurses_delwin -- Delete a ncurses window
- ncurses_doupdate -- Write all prepared refreshes to terminal
- ncurses_echo -- Activate keyboard input echo
- ncurses_echochar -- Single character output including refresh
- ncurses_end -- Stop using ncurses, clean up the screen
- ncurses_erase -- Erase terminal screen
- ncurses_erasechar -- Returns current erase character
- ncurses_filter --
- ncurses_flash -- Flash terminal screen (visual bell)
- ncurses_flushinp -- Flush keyboard input buffer
- ncurses_getch -- Read a character from keyboard
- ncurses_getmaxyx -- Returns the size of a window
- ncurses_getmouse -- Reads mouse event
- ncurses_getyx -- Returns the current cursor position for a window
- ncurses_halfdelay -- Put terminal into halfdelay mode
- ncurses_has_colors -- Check if terminal has colors
- ncurses_has_ic -- Check for insert- and delete-capabilities
- ncurses_has_il -- Check for line insert- and delete-capabilities
- ncurses_has_key -- Check for presence of a function key on terminal keyboard
- ncurses_hide_panel -- Remove panel from the stack, making it invisible
- ncurses_hline -- Draw a horizontal line at current position using an attributed character and max. n characters long
- ncurses_inch -- Get character and attribute at current position
- ncurses_init_color -- Set new RGB value for color
- ncurses_init_pair -- Allocate a color pair
- ncurses_init -- Initialize ncurses
- ncurses_insch -- Insert character moving rest of line including character at current position
- ncurses_insdelln -- Insert lines before current line scrolling down (negative numbers delete and scroll up)
- ncurses_insertln -- Insert a line, move rest of screen down
- ncurses_insstr -- Insert string at current position, moving rest of line right
- ncurses_instr -- Reads string from terminal screen
- ncurses_isendwin -- Ncurses is in endwin mode, normal screen output may be performed
- ncurses_keyok -- Enable or disable a keycode
- ncurses_keypad -- Turns keypad on or off
- ncurses_killchar -- Returns current line kill character
- ncurses_longname -- Returns terminals description
- ncurses_meta -- Enables/Disable 8-bit meta key information
- ncurses_mouse_trafo -- Transforms coordinates
- ncurses_mouseinterval -- Set timeout for mouse button clicks
- ncurses_mousemask -- Sets mouse options
- ncurses_move_panel -- Moves a panel so that it's upper-left corner is at [startx, starty]
- ncurses_move -- Move output position
- ncurses_mvaddch -- Move current position and add character
- ncurses_mvaddchnstr -- Move position and add attrributed string with specified length
- ncurses_mvaddchstr -- Move position and add attributed string
- ncurses_mvaddnstr -- Move position and add string with specified length
- ncurses_mvaddstr -- Move position and add string
- ncurses_mvcur -- Move cursor immediately
- ncurses_mvdelch -- Move position and delete character, shift rest of line left
- ncurses_mvgetch -- Move position and get character at new position
- ncurses_mvhline -- Set new position and draw a horizontal line using an attributed character and max. n characters long
- ncurses_mvinch -- Move position and get attributed character at new position
- ncurses_mvvline -- Set new position and draw a vertical line using an attributed character and max. n characters long
- ncurses_mvwaddstr -- Add string at new position in window
- ncurses_napms -- Sleep
- ncurses_new_panel -- Create a new panel and associate it with window
- ncurses_newpad -- Creates a new pad (window)
- ncurses_newwin -- Create a new window
- ncurses_nl -- Translate newline and carriage return / line feed
- ncurses_nocbreak -- Switch terminal to cooked mode
- ncurses_noecho -- Switch off keyboard input echo
- ncurses_nonl -- Do not translate newline and carriage return / line feed
- ncurses_noqiflush -- Do not flush on signal characters
- ncurses_noraw -- Switch terminal out of raw mode
- ncurses_pair_content -- Gets the RGB value for color
- ncurses_panel_above -- Returns the panel above panel. If panel is null, returns the bottom panel in the stack
- ncurses_panel_below -- Returns the panel below panel. If panel is null, returns the top panel in the stack
- ncurses_panel_window -- Returns the window associated with panel
- ncurses_pnoutrefresh -- Copys a region from a pad into the virtual screen
- ncurses_prefresh -- Copys a region from a pad into the virtual screen
- ncurses_putp --
- ncurses_qiflush -- Flush on signal characters
- ncurses_raw -- Switch terminal into raw mode
- ncurses_refresh -- Refresh screen
- ncurses_replace_panel -- Replaces the window associated with panel
- ncurses_reset_prog_mode -- Resets the prog mode saved by def_prog_mode
- ncurses_reset_shell_mode -- Resets the shell mode saved by def_shell_mode
- ncurses_resetty -- Restores saved terminal state
- ncurses_savetty -- Saves terminal state
- ncurses_scr_dump -- Dump screen content to file
- ncurses_scr_init -- Initialize screen from file dump
- ncurses_scr_restore -- Restore screen from file dump
- ncurses_scr_set -- Inherit screen from file dump
- ncurses_scrl -- Scroll window content up or down without changing current position
- ncurses_show_panel -- Places an invisible panel on top of the stack, making it visible
- ncurses_slk_attr -- Returns current soft label key attribute
- ncurses_slk_attroff --
- ncurses_slk_attron --
- ncurses_slk_attrset --
- ncurses_slk_clear -- Clears soft labels from screen
- ncurses_slk_color -- Sets color for soft label keys
- ncurses_slk_init -- Initializes soft label key functions
- ncurses_slk_noutrefresh -- Copies soft label keys to virtual screen
- ncurses_slk_refresh -- Copies soft label keys to screen
- ncurses_slk_restore -- Restores soft label keys
- ncurses_slk_set -- Sets function key labels
- ncurses_slk_touch -- Fources output when ncurses_slk_noutrefresh is performed
- ncurses_standend -- Stop using 'standout' attribute
- ncurses_standout -- Start using 'standout' attribute
- ncurses_start_color -- Start using colors
- ncurses_termattrs -- Returns a logical OR of all attribute flags supported by terminal
- ncurses_termname -- Returns terminals (short)-name
- ncurses_timeout -- Set timeout for special key sequences
- ncurses_top_panel -- Moves a visible panel to the top of the stack
- ncurses_typeahead -- Specify different filedescriptor for typeahead checking
- ncurses_ungetch -- Put a character back into the input stream
- ncurses_ungetmouse -- Pushes mouse event to queue
- ncurses_update_panels -- Refreshes the virtual screen to reflect the relations between panels in the stack.
- ncurses_use_default_colors -- Assign terminal default colors to color id -1
- ncurses_use_env -- Control use of environment information about terminal size
- ncurses_use_extended_names -- Control use of extended names in terminfo descriptions
- ncurses_vidattr --
- ncurses_vline -- Draw a vertical line at current position using an attributed character and max. n characters long
- ncurses_waddch -- Adds character at current position in a window and advance cursor
- ncurses_waddstr -- Outputs text at current postion in window
- ncurses_wattroff -- Turns off attributes for a window
- ncurses_wattron -- Turns on attributes for a window
- ncurses_wattrset -- Set the attributes for a window
- ncurses_wborder -- Draws a border around the window using attributed characters
- ncurses_wclear -- Clears window
- ncurses_wcolor_set -- Sets windows color pairings
- ncurses_werase -- Erase window contents
- ncurses_wgetch -- Reads a character from keyboard (window)
- ncurses_whline -- Draws a horizontal line in a window at current position using an attributed character and max. n characters long
- ncurses_wmouse_trafo -- Transforms window/stdscr coordinates
- ncurses_wmove -- Moves windows output position
- ncurses_wnoutrefresh -- Copies window to virtual screen
- ncurses_wrefresh -- Refresh window on terminal screen
- ncurses_wstandend -- End standout mode for a window
- ncurses_wstandout -- Enter standout mode for a window
- ncurses_wvline -- Draws a vertical line in a window at current position using an attributed character and max. n characters long