PHP Manual
PrevNext

LXXV. 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

NameDefaultChangeable
ncurses.value"42"PHP_INI_ALL
ncurses.string"foobar"PHP_INI_ALL
For further details and definition of the PHP_INI_* constants see ini_set().

Resource Types

This extension has no resource types defined.

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.

Error codes

On error ncurses functions return NCURSES_ERR.

Colors

Table 2. ncurses color constants

constantmeaning
NCURSES_COLOR_BLACKno color (black)
NCURSES_COLOR_WHITEwhite
NCURSES_COLOR_REDred - supported when terminal is in color mode
NCURSES_COLOR_GREENgreen - supported when terminal is in color mode
NCURSES_COLOR_YELLOWyellow - supported when terminal is in color mode
NCURSES_COLOR_BLUEblue - supported when terminal is in color mode
NCURSES_COLOR_CYANcyan - supported when terminal is in color mode
NCURSES_COLOR_MAGENTAmagenta - supported when terminal is in color mode

Keys

Table 3. ncurses key constants

constantmeaning
NCURSES_KEY_F0 - NCURSES_KEY_F64function keys F1 - F64
NCURSES_KEY_DOWNdown arrow
NCURSES_KEY_UPup arrow
NCURSES_KEY_LEFTleft arrow
NCURSES_KEY_RIGHTright arrow
NCURSES_KEY_HOMEhome key (upward+left arrow)
NCURSES_KEY_BACKSPACEbackspace
NCURSES_KEY_DLdelete line
NCURSES_KEY_ILinsert line
NCURSES_KEY_DCdelete character
NCURSES_KEY_ICinsert char or enter insert mode
NCURSES_KEY_EICexit insert char mode
NCURSES_KEY_CLEARclear screen
NCURSES_KEY_EOSclear to end of screen
NCURSES_KEY_EOLclear to end of line
NCURSES_KEY_SFscroll one line forward
NCURSES_KEY_SRscroll one line backward
NCURSES_KEY_NPAGEnext page
NCURSES_KEY_PPAGEprevious page
NCURSES_KEY_STABset tab
NCURSES_KEY_CTABclear tab
NCURSES_KEY_CATABclear all tabs
NCURSES_KEY_SRESETsoft (partial) reset
NCURSES_KEY_RESETreset or hard reset
NCURSES_KEY_PRINTprint
NCURSES_KEY_LLlower left
NCURSES_KEY_A1upper left of keypad
NCURSES_KEY_A3upper right of keypad
NCURSES_KEY_B2center of keypad
NCURSES_KEY_C1lower left of keypad
NCURSES_KEY_C3lower right of keypad
NCURSES_KEY_BTABback tab
NCURSES_KEY_BEGbeginning
NCURSES_KEY_CANCELcancel
NCURSES_KEY_CLOSEclose
NCURSES_KEY_COMMANDcmd (command)
NCURSES_KEY_COPYcopy
NCURSES_KEY_CREATEcreate
NCURSES_KEY_ENDend
NCURSES_KEY_EXITexit
NCURSES_KEY_FINDfind
NCURSES_KEY_HELPhelp
NCURSES_KEY_MARKmark
NCURSES_KEY_MESSAGEmessage
NCURSES_KEY_MOVEmove
NCURSES_KEY_NEXTnext
NCURSES_KEY_OPENopen
NCURSES_KEY_OPTIONSoptions
NCURSES_KEY_PREVIOUSprevious
NCURSES_KEY_REDOredo
NCURSES_KEY_REFERENCEref (reference)
NCURSES_KEY_REFRESHrefresh
NCURSES_KEY_REPLACEreplace
NCURSES_KEY_RESTARTrestart
NCURSES_KEY_RESUMEresume
NCURSES_KEY_SAVEsave
NCURSES_KEY_SBEGshiftet beg (beginning)
NCURSES_KEY_SCANCELshifted cancel
NCURSES_KEY_SCOMMANDshifted command
NCURSES_KEY_SCOPYshifted copy
NCURSES_KEY_SCREATEshifted create
NCURSES_KEY_SDCshifted delete char
NCURSES_KEY_SDLshifted delete line
NCURSES_KEY_SELECTselect
NCURSES_KEY_SENDshifted end
NCURSES_KEY_SEOLshifted end of line
NCURSES_KEY_SEXITshifted exit
NCURSES_KEY_SFINDshifted find
NCURSES_KEY_SHELPshifted help
NCURSES_KEY_SHOMEshifted home
NCURSES_KEY_SICshifted input
NCURSES_KEY_SLEFTshifted left arrow
NCURSES_KEY_SMESSAGEshifted message
NCURSES_KEY_SMOVEshifted move
NCURSES_KEY_SNEXTshifted next
NCURSES_KEY_SOPTIONSshifted options
NCURSES_KEY_SPREVIOUSshifted previous
NCURSES_KEY_SPRINTshifted print
NCURSES_KEY_SREDOshifted redo
NCURSES_KEY_SREPLACEshifted replace
NCURSES_KEY_SRIGHTshifted right arrow
NCURSES_KEY_SRSUMEshifted resume
NCURSES_KEY_SSAVEshifted save
NCURSES_KEY_SSUSPENDshifted suspend
NCURSES_KEY_UNDOundo
NCURSES_KEY_MOUSEmouse event has occurred
NCURSES_KEY_MAXmaximum key value

Mouse

Table 4. mouse constants

Constantmeaning
NCURSES_BUTTON1_RELEASED - NCURSES_BUTTON4_RELEASEDbutton (1-4) released
NCURSES_BUTTON1_PRESSED - NCURSES_BUTTON4_PRESSEDbutton (1-4) pressed
NCURSES_BUTTON1_CLICKED - NCURSES_BUTTON4_CLICKEDbutton (1-4) clicked
NCURSES_BUTTON1_DOUBLE_CLICKED - NCURSES_BUTTON4_DOUBLE_CLICKEDbutton (1-4) double clicked
NCURSES_BUTTON1_TRIPLE_CLICKED - NCURSES_BUTTON4_TRIPLE_CLICKEDbutton (1-4) triple clicked
NCURSES_BUTTON_CTRLctrl pressed during click
NCURSES_BUTTON_SHIFTshift pressed during click
NCURSES_BUTTON_ALTalt pressed during click
NCURSES_ALL_MOUSE_EVENTSreport all mouse events
NCURSES_REPORT_MOUSE_POSITIONreport 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 -- Set LINES for iniscr() and newterm() to 1
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 its 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 attributed 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
ncurses_panel_below --  Returns the panel below panel
ncurses_panel_window --  Returns the window associated with panel
ncurses_pnoutrefresh --  Copies a region from a pad into the virtual screen
ncurses_prefresh --  Copies a region from a pad into the virtual screen
ncurses_putp -- Apply padding information to the string and output it
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 -- Turn off the given attributes for soft function-key labels
ncurses_slk_attron -- Turn on the given attributes for soft function-key labels
ncurses_slk_attrset -- Set given attributes for soft function-key labels
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 -- Forces 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 -- Display the string on the terminal in the video attribute mode
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
PrevHomeNext
syslogUpncurses_addch