Ncurses Functions
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 — Checks if terminal color definitions can be changed
- ncurses_cbreak — Switch off 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 — Retrieves RGB components of a color
- ncurses_color_set — Set active foreground and background colors
- 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 — Checks if terminal has color capabilities
- 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 — Define a terminal color
- ncurses_init_pair — Define 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 — Retrieves foreground and background colors of a color pair
- 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 — Initializes color functionality
- 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
Коментарии
With your CGI version of PHP compiled with ncurses support, console apps are amazingly easy!
For example:
whack the following into a file, chmod +x it, and run it.
#!/usr/local/bin/php -q
<?php
ncurses_init();
ncurses_border(25,25,18,18,24,24,23,23); // Do a lovely border
ncurses_move(1,1); // Start top left(inside border)
ncurses_addstr("Welcome to NCurses");
ncurses_addstr(" with PHP!");
ncurses_refresh(); // Send buffer to screen
ncurses_end(); // Clean up, and quit
?>
Youll notice the second addstr simply tacks onto the first.
actually *that* example does not work...
here is one that I took and trimmed down from the ncurses examples.
I will do some more and post them here..
<?
ncurses_init();
##############################################
ncurses_noecho();
$large = ncurses_newwin(20, 60, 2, 10);
$small = ncurses_newwin(10, 30, 7, 25);
ncurses_refresh();
ncurses_wrefresh($large);
ncurses_wrefresh($small);
ncurses_mvwaddstr($small, 5, 5, " Test String ");
ncurses_wrefresh($small);
ncurses_getch();
##############################################
ncurses_end(); // Clean up, and quit
?>
This is from PHP 4.3.0RC0 compiled with the following flags..
./configure --prefix=/wwwroot/php --with-config-file-path=/wwwroot/php --with-mysql --enable-pcntl --with-tsrm-pthreads --enable-sysvsem --enable-sysvshm --with-curl --enable-bcmath --enable-sigchild --enable-sockets --with-ncurses
This is from the examples that come with the latest release.
From:
php-4.3.0RC3/ext/ncurses/example1.php
I found this useful...
<?php
$n=0;
ncurses_init();
if(ncurses_has_colors()){
ncurses_start_color();
ncurses_init_pair(1,NCURSES_COLOR_RED,NCURSES_COLOR_BLACK);
ncurses_init_pair(2,NCURSES_COLOR_GREEN,NCURSES_COLOR_BLACK);
ncurses_init_pair(3,NCURSES_COLOR_YELLOW,NCURSES_COLOR_BLACK);
ncurses_init_pair(4,NCURSES_COLOR_BLUE,NCURSES_COLOR_BLACK);
ncurses_init_pair(5,NCURSES_COLOR_MAGENTA,NCURSES_COLOR_BLACK);
ncurses_init_pair(6,NCURSES_COLOR_CYAN,NCURSES_COLOR_BLACK);
ncurses_init_pair(7,NCURSES_COLOR_WHITE,NCURSES_COLOR_BLACK);
}
while(1){
for ($x=0; $x<80; $x++) {
for ($y=0; $y<24; $y++) {
$n++;
ncurses_move($y,$x);
ncurses_addch($n+64);
ncurses_color_set($n%8);
ncurses_refresh();
if($n>26)$n=0;
}
}
ncurses_getch();
}
?>
I noticed a lack of a getxy() function so I wrote one.
You may need to change the path for your resize cmd.
<?
function getxy(){
$rez = `/usr/X11R6/bin/resize`;
$rez = explode("\n",$rez);
while(list($key,$val)=each($rez)){
$a=explode("=",$val);
if(trim($a[0])=="COLUMNS"){ $COLUMNS = $a[1]; }
if(trim($a[0])=="LINES"){ $LINES = $a[1]; }
}//
$retval[0]=$COLUMNS;
$retval[1]=$LINES;
return $retval;
}
print_r(getxy());
?>
See the documentation for ncurses_border and ncurses_wrefresh for some more examples of doing windowing and dynamic sizing.. I also posted some information to the zend.com code-gallery for doing ncurses under php.
In the example above, if you run resize from a C shell it will output the sizes in C shell syntax, run resize with -u to force Bourne syntax:
The $win parameter is just for future compatibility.
function ncurses_getmaxyx($win, &$y, &$x)
{
exec("/usr/X11R6/bin/resize -u", $output);
$cols = explode("=", $output[0]);
$rows = explode("=", $output[1]);
$x = intval($cols[1]);
$y = intval($rows[1]);
}
For those of you who want to check if <ENTER> key is passed,
you have to check the key agains both NL and CR keys:
function get_str()
{
for ($str = "";;){
$key = ncurses_getch();
switch ($key){
case 10: // newline
case 13: // Carrige Return
return($str);
default:
$str .= chr($key);
ncurses_refresh();
} // switch
} // for
} // get_str()
Hope that would help.
I had a small problem building php+ncurses support.
ncurses include files were installed in:
ncurses_installed_dir/include/ncurses
This caused problems when building php with ncurse support.
php was looking for include files in:
ncurses_installed_dir/include
However, include files were located in include/ncurses
I had to make symbolic links of files in ncurses directory so php could see them:
# cd ncurses_insalled_directory/include
# ln -s ncurses/* .
After that it worked.
This is not meant as spam to get people to use my client.
I have been working on a PHP4 IRC client with ncurses interface and I think it is a useful example of how ncurses with php could be used.
It is GPL licensed so you can just go and take a loot at it.
It can be found at http://torc.sourceforge.net or http://www.darkwired.org/projects/torc/
I hope this will help out some of you because php ncurses can be quite difficult I experienced :]
For any questions about the code you can ofcourse just mail me.
Here is a function which would do the job for missing
ncurses_wclrtoeol() function:
/* wclrtoeol()
* Erases the current line to the right of the cursor
*/
function wclrtoeol($win)
{
# get current position
ncurses_getyx($win, &$crow, &$ccol);
# get maximum row and col for this window:
ncurses_getmaxyx($win, &$max_row, &$max_col);
for ($col = $ccol; $col < $max_col; $col ++){
ncurses_wmove($win, $crow, $col);
ncurses_waddch($win, 32);
}
}
What if you want to draw a new window and after removing it, showing the pervious screen again? Unfortunately, there is no such a thing in php/ncurses as there is in original curses library (touchwin if I'm not mistaken - It has been a long time!).
However, you can do this by a simple trick! You can
dump the screen to a temp file and then restore it back
again!
Take a look at this function:
# Function: show_a_win()
# - Displays a small window and writes something in it.
# - waits for a key
# - shows the pervious screen again
function show_a_win()
{
# Dump the current screen into a temp file:
$tmpfile = tempnam("/tmp", "dump.");
# Create a new window.
$newwin = ncurses_newwin(4, 60, 10, 10);
# Write something and then refresh it
ncurses_mvwaddstr($newwin, 1, 1, "This is a test.");
ncurses_wrefresh($newwin);
# Wait for a key
ncurses_wgetch($newwin);
ncurses_delwin($newwin); /* delete the window */
/* Restore the screen the same way it was before entering
* into the function:
*/
ncurses_scr_restore($tmpfile);
unlink($tmpfile); /* Remove temp file */
}
Here is a function that takes an associative array, presents a menu in a new window, allows the user to make a choice using up and down arrows and the enter key, and returns the value of the menu item.
Limitations include:
No way of scrolling a long list, either horiontally or vertically;
No arguments for placement on screen, although this is easy to add;
No multiple selection;
Will produce all kinds of errors and warnings if the terminal is smaller than is necessary to create the window.
I'm very new at using the ncurses library; Comments and improvements would be greatly appreciated!
<?php
/**
* Create a simple selection menu
* @param array Associative array; The value will be shown on the menu, while the key will be returned when the associated value is selected.
* @return mixed
*/
function ncurses_menu_select( $menu ) {
$keys = array_keys( $menu );
$values = array_values( $menu );
$height = $width = 0;
$height = count( $menu ) + 2;
foreach( $values as $value ) {
$width = max( $width, strlen( $value ) + 2 );
}
$menu_window = ncurses_newwin( $height, $width, 5, 5 );
ncurses_wborder( $menu_window, 0,0, 0,0, 0,0, 0,0 );
$current = 0;
for( $a = 0; $a < count( $values ); $a++ ) {
if ( $a == $current ) {
ncurses_wattron( $menu_window, NCURSES_A_REVERSE );
ncurses_mvwaddstr( $menu_window, 1 + $a, 1, $values[ $a ] );
ncurses_wattroff( $menu_window, NCURSES_A_REVERSE );
} else {
ncurses_mvwaddstr( $menu_window, 1 + $a, 1, $values[ $a ] );
}
}
ncurses_wrefresh( $menu_window );
while( ! in_array( $key = ncurses_getch( $menu_window ), array( 13, 10 ) ) ) {
if ( $key == NCURSES_KEY_UP AND $current > 0 ) {
$move = -1;
} else if ( $key == NCURSES_KEY_DOWN and $current < count( $values ) - 1 ) {
$move = 1;
} else {
$move = 0;
}
ncurses_mvwaddstr( $menu_window, 1 + $current, 1, $values[ $current ] );
$current += $move;
ncurses_wattron( $menu_window, NCURSES_A_REVERSE );
ncurses_mvwaddstr( $menu_window, 1 + $current, 1, $values[ $current ] );
ncurses_wattroff( $menu_window, NCURSES_A_REVERSE );
ncurses_wrefresh( $menu_window );
}
ncurses_delwin( $menu_window );
return $keys[ $current ];
}
?>
Example Use:
<?php
// Initialie ncurses
$ncurse = ncurses_init();
// A full screen window
$fullscreen = ncurses_newwin ( 0, 0, 0, 0);
// Add a pretty border
ncurses_border(0,0, 0,0, 0,0, 0,0);
// Draw everything so far
ncurses_refresh();
// Set up menu array
$menu_items = array(
'one' => 'Menu Item #1',
'two' => 'Menu Item #2',
'three' => 'Menu Item #3' );
// Display menu and return selection
$selection = ncurses_menu_select( $menu_items );
// Print selection
ncurses_mvaddstr( 1, 1, 'You selected ' . $menu_items[$selection] . ' with the value ' . $selection );
// Draw updates
ncurses_refresh( $fullscreen );
// End
ncurses_end();
?>
Not calling ncurses_end() can (will) cause issues with terminals. Although registering a shutdown function which includes ncurses_end() may help, sometimes things go awry and you're stuck with a terminal that is acting in strange ways.
This can be fixed! *NIX systems (FreeBSD, Linux, UNIX, et al.) usually support the 'reset' command which resets the terminal settings and allows you to get things back to normal.
An implementation of a scrolling selection box:
<?php
function ncurses_menu_select( $options, $values, $max_height = 7, $max_width = 20, $y = 2, $x = 2 ) {
// Size inside of borders
$height = $max_height - 2;
$width = $max_width - 2;
// Number of options
$num_options = count( $options );
// Trim all values to fit
foreach( $options as $key => $value ) {
$options[ $key ] = substr( $value, 0, $width );
}
// Create Window
$menu_window = ncurses_newwin( $max_height, $max_width, $y, $x );
ncurses_wborder( $menu_window, 0, 0, 0, 0, 0, 0, 0, 0 );
// Initialize Window
$current = 0; // Currently selected
$position = 1; // Position in list
$topitem = 0; // Top menu item
for ( $a = 0; $a < min( $height, $num_options ); $a++ ) {
if ( $a == $current ) {
ncurses_wattron( $menu_window, NCURSES_A_REVERSE );
ncurses_mvwaddstr( $menu_window, 1 + $a, 1, $options[ $a ] );
ncurses_wattroff( $menu_window, NCURSES_A_REVERSE );
} else {
ncurses_mvwaddstr( $menu_window, 1 + $a, 1, $options[ $a ] );
}
}
ncurses_mvwaddstr( $menu_window, 1, 0, '*' );
ncurses_wrefresh( $menu_window );
// Loop until a selection is made
while( ! in_array( $key = ncurses_getch( $menu_window ), array( 13, 10 ) ) ) {
if ( $key == NCURSES_KEY_UP && $current > 0 ) {
$move = -1;
} else if ( $key == NCURSES_KEY_DOWN && $current < $num_options - 1 ) {
$move = 1;
} else {
continue;
}
$current += $move;
$position += $move;
// If we scroll off the window, redraw items.
if ( $position < 1 || $position > $height ) {
if ( $position < 1 ) {
$position = 1;
} else {
$position = $height;
}
$topitem += $move;
for ( $a = 1; $a <= $height; $a++ ) {
ncurses_mvwaddstr( $menu_window, $a, 1, str_repeat( ' ', $width ) );
if ( $a == $position ) {
ncurses_wattron( $menu_window, NCURSES_A_REVERSE );
ncurses_mvwaddstr( $menu_window, $a, 1, $options[ $topitem + $a - 1 ] );
ncurses_wattroff( $menu_window, NCURSES_A_REVERSE );
} else {
ncurses_mvwaddstr( $menu_window, $a, 1, $options[ $topitem + $a - 1 ] );
}
}
} else { // Just update changed items
ncurses_wattron( $menu_window, NCURSES_A_REVERSE );
ncurses_mvwaddstr( $menu_window, $position, 1, $options[ $current ] );
ncurses_wattroff( $menu_window, NCURSES_A_REVERSE );
ncurses_mvwaddstr( $menu_window, $position - $move, 1, $options[ $current - $move ] );
}
// Update 'scroll bar dot'
ncurses_wborder( $menu_window, 0, 0, 0, 0, 0, 0, 0, 0 );
$dot_position = round ( ( $current / $num_options ) * ( $height - 1 ) );
ncurses_mvwaddstr( $menu_window, 1 + $dot_position, 0, '*' );
ncurses_wrefresh( $menu_window );
}
return $values[ $current ];
}
?>
Here is a small example, how to use STDIN to read keys combinations in console.
$stdin = fopen('php://stdin', 'r');
stream_set_timeout($stdin, 1);
while (1) {
$temp="";
while (1) {
if(stream_select($read = array($stdin), $write = NULL, $except = NULL, 0))
$temp .= ord(fgetc($stdin));
else break;
}
// F1 : $temp == 27914949126
// ALT+F1 : $temp = 2727914949126
// ....
usleep("50000");
}
To determine screen width and height without any external (OS specific) commands, I use:
<?php
ncurses_init();
$fullscreen = ncurses_newwin ( 0, 0, 0, 0);
ncurses_getmaxyx($fullscreen,&$a,&$b);
ncurses_end();
echo "Width:$b\nHeight:$a\n";
?>