ruby-changes:19639
From: drbrain <ko1@a...>
Date: Sun, 22 May 2011 11:08:43 +0900 (JST)
Subject: [ruby-changes:19639] drbrain:r31683 (trunk): * ext/curses/curses.c: Complete documentation. Patch by Vincent
drbrain 2011-05-22 11:08:30 +0900 (Sun, 22 May 2011) New Revision: 31683 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=31683 Log: * ext/curses/curses.c: Complete documentation. Patch by Vincent Batts. [Ruby 1.9 - Bug #4748] Modified files: trunk/ChangeLog trunk/ext/curses/curses.c Index: ChangeLog =================================================================== --- ChangeLog (revision 31682) +++ ChangeLog (revision 31683) @@ -1,3 +1,8 @@ +Sun May 22 11:07:47 2011 Eric Hodel <drbrain@s...> + + * ext/curses/curses.c: Complete documentation. Patch by Vincent + Batts. [Ruby 1.9 - Bug #4748] + Sun May 22 09:29:43 2011 KOSAKI Motohiro <kosaki.motohiro@g...> * test/ruby/test_rubyoptions.rb (TestRubyOptions#test_set_program_name): Index: ext/curses/curses.c =================================================================== --- ext/curses/curses.c (revision 31682) +++ ext/curses/curses.c (revision 31683) @@ -149,6 +149,19 @@ */ #define curses_stdscr curses_init_screen +/* + * Document-method: Curses.close_screen + * + * A program should always call Curses.close_screen before exiting or + * escaping from curses mode temporarily. This routine + * restores tty modes, moves the cursor to the lower + * left-hand corner of the screen and resets the terminal + * into the proper non-visual mode. + * + * Calling Curses.refresh or Curses.doupdate after a temporary + * escape causes the program to resume visual mode. + * + */ static VALUE curses_close_screen(void) { @@ -161,6 +174,13 @@ return Qnil; } +/* + * This is no runtime method, + * but a function called before the proc ends + * + * Similar to Curses.close_screen, except that it also + * garbage collects/unregisters the Curses.stdscr + */ static void curses_finalize(VALUE dummy) { @@ -175,6 +195,13 @@ } #ifdef HAVE_ISENDWIN +/* + * Document-method: Curses.closed? + * + * Returns +true+ if the window/screen has been closed, + * without any subsequent Curses.refresh calls, + * returns +false+ otherwise. + */ static VALUE curses_closed(void) { @@ -188,6 +215,13 @@ #define curses_closed rb_f_notimplement #endif +/* + * Document-method: Curses.clear + * + * Clears every position on the screen completely, + * so that a subsequent call by Curses.refresh for the screen/window + * will be repainted from scratch. + */ static VALUE curses_clear(VALUE obj) { @@ -196,6 +230,11 @@ return Qnil; } +/* + * Document-method: Curses.clrtoeol + * + * Clears to the end of line, that the cursor is currently on. + */ static VALUE curses_clrtoeol(void) { @@ -204,6 +243,12 @@ return Qnil; } +/* + * Document-method: Curses.refresh + * + * Refreshes the windows and lines. + * + */ static VALUE curses_refresh(VALUE obj) { @@ -212,6 +257,14 @@ return Qnil; } +/* + * Document-method: Curses.doupdate + * + * Refreshes the windows and lines. + * + * Curses.doupdate allows multiple updates with + * more efficiency than Curses.refresh alone. + */ static VALUE curses_doupdate(VALUE obj) { @@ -224,6 +277,12 @@ return Qnil; } +/* + * Document-method: Curses.echo + * + * Enables characters typed by the user + * to be echoed by Curses.getch as they are typed. + */ static VALUE curses_echo(VALUE obj) { @@ -232,6 +291,12 @@ return Qnil; } +/* + * Document-method: Curses.noecho + * + * Disables characters typed by the user + * to be echoed by Curses.getch as they are typed. + */ static VALUE curses_noecho(VALUE obj) { @@ -240,6 +305,20 @@ return Qnil; } +/* + * Document-method: Curses.raw + * + * Put the terminal into raw mode. + * + * Raw mode is similar to Curses.cbreak mode, in that characters typed + * are immediately passed through to the user program. + * + * The differences are that in raw mode, the interrupt, quit, + * suspend, and flow control characters are all passed through + * uninterpreted, instead of generating a signal. The behavior + * of the BREAK key depends on other bits in the tty driver + * that are not set by curses. + */ static VALUE curses_raw(VALUE obj) { @@ -248,6 +327,13 @@ return Qnil; } +/* + * Document-method: Curses.noraw + * + * Put the terminal out of raw mode. + * + * see Curses.raw for more detail + */ static VALUE curses_noraw(VALUE obj) { @@ -256,6 +342,28 @@ return Qnil; } +/* + * Document-method: Curses.cbreak + * + * Put the terminal into cbreak mode. + * + * Normally, the tty driver buffers typed characters until + * a newline or carriage return is typed. The Curses.cbreak + * routine disables line buffering and erase/kill + * character-processing (interrupt and flow control characters + * are unaffected), making characters typed by the user + * immediately available to the program. + * + * The Curses.nocbreak routine returns the terminal to normal (cooked) mode. + * + * Initially the terminal may or may not be in cbreak mode, + * as the mode is inherited; therefore, a program should + * call Curses.cbreak or Curses.nocbreak explicitly. + * Most interactive programs using curses set the cbreak mode. + * Note that Curses.cbreak overrides Curses.raw. + * + * see also Curses.raw + */ static VALUE curses_cbreak(VALUE obj) { @@ -264,6 +372,13 @@ return Qnil; } +/* + * Document-method: Curses.nocbreak + * + * Put the terminal into normal mode (out of cbreak mode). + * + * See Curses.cbreak for more detail. + */ static VALUE curses_nocbreak(VALUE obj) { @@ -272,6 +387,20 @@ return Qnil; } +/* + * Document-method: Curses.nl + * + * Enable the underlying display device to translate + * the return key into newline on input, and whether it + * translates newline into return and line-feed on output + * (in either case, the call Curses.addch('\n') does the + * equivalent of return and line feed on the virtual screen). + * + * Initially, these translations do occur. If you disable + * them using Curses.nonl, curses will be able to make better use + * of the line-feed capability, resulting in faster cursor + * motion. Also, curses will then be able to detect the return key. + */ static VALUE curses_nl(VALUE obj) { @@ -280,6 +409,14 @@ return Qnil; } +/* + * Document-method: Curses.nl + * + * Disable the underlying display device to translate + * the return key into newline on input + * + * See Curses.nl for more detail + */ static VALUE curses_nonl(VALUE obj) { @@ -288,6 +425,14 @@ return Qnil; } +/* + * Document-method: Curses.beep + * + * Sounds an audible alarm on the terminal, if possible; + * otherwise it flashes the screen (visual bell). + * + * see also Curses.flash + */ static VALUE curses_beep(VALUE obj) { @@ -298,6 +443,14 @@ return Qnil; } +/* + * Document-method: Curses.flash + * + * Flashs the screen, for visual alarm on the terminal, if possible; + * otherwise it sounds the alert. + * + * see also Curses.beep + */ static VALUE curses_flash(VALUE obj) { @@ -351,6 +504,14 @@ #define curses_ungetch rb_f_notimplement #endif +/* + * Document-method: Curses.setpos + * call-seq: setpos(y, x) + * + * A setter for the position of the cursor, + * using coordinates +x+ and +y+ + * + */ static VALUE curses_setpos(VALUE obj, VALUE y, VALUE x) { @@ -359,6 +520,15 @@ return Qnil; } +/* + * Document-method: Curses.standout + * + * Enables the best highlighting mode of the terminal. + * + * This is equivalent to Curses:Window.attron(A_STANDOUT) + * + * see also Curses::Window.attrset additional information + */ static VALUE curses_standout(VALUE obj) { @@ -367,6 +537,15 @@ return Qnil; } +/* + * Document-method: Curses.standend + * + * Enables the Normal display (no highlight) + * + * This is equivalent to Curses.attron(A_NORMAL) + * + * see also Curses::Window.attrset for additional information. + */ static VALUE curses_standend(VALUE obj) { @@ -375,6 +554,11 @@ return Qnil; } +/* + * Document-method: Curses.inch + * + * Returns the character at the current position. + */ static VALUE curses_inch(VALUE obj) { @@ -382,6 +566,14 @@ return CH2FIX(inch()); } +/* + * Document-method: Curses.addch + * call-seq: addch(ch) + * + * Add a character +ch+, with attributes, then advance the cursor. + * + * see also the system manual for curs_addch(3) + */ static VALUE curses_addch(VALUE obj, VALUE ch) { @@ -390,6 +582,13 @@ return Qnil; } +/* + * Document-method: Curses.insch + * call-seq: insch(ch) + * + * Insert a character +ch+, before the cursor. + * + */ static VALUE curses_insch(VALUE obj, VALUE ch) { @@ -464,6 +663,12 @@ return Qnil; } +/* + * Document-method: Curses.getstr + * + * This is equivalent to a series f Curses::Window.getch calls + * + */ static VALUE curses_getstr(VALUE obj) { @@ -474,6 +679,12 @@ return rb_locale_str_new_cstr(rtn); } +/* + * Document-method: Curses.delch + * + * Delete the character under the cursor + * + */ static VALUE curses_delch(VALUE obj) { @@ -482,6 +693,12 @@ return Qnil; } +/* + * Document-method: Curses.deleteln + * + * Delete the line under the cursor. + * + */ static VALUE curses_deleteln(VALUE obj) { @@ -492,6 +709,12 @@ return Qnil; } +/* + * Document-method: Curses.insertln + * + * Inserts a line above the cursor, and the bottom line is lost + * + */ static VALUE curses_insertln(VALUE obj) { @@ -502,6 +725,12 @@ return Qnil; } +/* + * Document-method: Curses.keyname + * call-seq: keyname(c) + * + * Returns the character string corresponding to key +c+ + */ static VALUE curses_keyname(VALUE obj, VALUE c) { @@ -522,19 +751,32 @@ #endif } +/* + * Document-method: Curses.lines + * + * Returns the number of lines on the screen + */ static VALUE curses_lines(void) { return INT2FIX(LINES); } +/* + * Document-method: Curses.cols + * + * Returns the number of columns on the screen + */ static VALUE curses_cols(void) { return INT2FIX(COLS); } -/** +/* + * Document-method: Curses.curs_set + * call-seq: curs_set(visibility) + * * Sets Cursor Visibility. * 0: invisible * 1: visible @@ -552,6 +794,18 @@ #endif } +/* + * Document-method: Curses.scrl + * call-seq: scrl(num) + * + * Scrolls the current window Fixnum +num+ lines. + * The current cursor position is not changed. + * + * For positive +num+, it scrolls up. + * + * For negative +num+, it scrolls down. + * + */ static VALUE curses_scrl(VALUE obj, VALUE n) { @@ -564,6 +818,19 @@ #endif } +/* + * Document-method: Curses.setscrreg + * call-seq: setscrreg(top, bottom) + * + * Set a software scrolling region in a window. + * +top+ and +bottom+ are lines numbers of the margin. + * + * If this option and Curses.scrollok are enabled, an attempt to move off + * the bottom margin line causes all lines in the scrolling region + * to scroll one line in the direction of the first line. + * Only the text of the window is scrolled. + * + */ static VALUE curses_setscrreg(VALUE obj, VALUE top, VALUE bottom) { @@ -576,6 +843,14 @@ #endif } +/* + * Document-method: Curses.attroff + * call-seq: attroff(attrs) + * + * Turns on the named attributes +attrs+ without affecting any others. + * + * See also Curses::Window.attrset for additional information. + */ static VALUE curses_attroff(VALUE obj, VALUE attrs) { @@ -584,6 +859,15 @@ /* return INT2FIX(attroff(NUM2INT(attrs))); */ } +/* + * Document-method: Curses.attron + * call-seq: attron(attrs) + * + * Turns off the named attributes +attrs+ + * without turning any other attributes on or off. + * + * See also Curses::Window.attrset for additional information. + */ static VALUE curses_attron(VALUE obj, VALUE attrs) { @@ -593,8 +877,11 @@ } /* + * Document-method: Curses.attrset * call-seq: attrset(attrs) * + * Sets the current attributes of the given window to +attrs+. + * * see also Curses::Window.attrset * */ @@ -755,6 +1042,14 @@ } #ifdef USE_COLOR +/* + * Document-method: Curses.start_color + * + * Initializes the color attributes, for terminals that support it. + * + * This must be called, in order to use color attributes. + * It is good practice to call it just after Curses.init_screen + */ static VALUE curses_start_color(VALUE obj) { @@ -763,6 +1058,20 @@ return (start_color() == OK) ? Qtrue : Qfalse; } +/* + * Document-method: Curses.init_pair + * call-seq: init_pair(pair, f, b) + * + * Changes the definition of a color-pair. + * + * It takes three arguments: the number of the color-pair to be changed +pair+, + * the foreground color number +f+, and the background color number +b+. + * + * If the color-pair was previously initialized, the screen is + * refreshed and all occurrences of that color-pair are changed + * to the new definition. + * + */ static VALUE curses_init_pair(VALUE obj, VALUE pair, VALUE f, VALUE b) { @@ -771,6 +1080,22 @@ return (init_pair(NUM2INT(pair),NUM2INT(f),NUM2INT(b)) == OK) ? Qtrue : Qfalse; } +/* + * Document-method: Curses.init_color + * call-seq: init_color(color, r, g, b) + * + * Changes the definition of a color. It takes four arguments: + * * the number of the color to be changed, +color+ + * * the amount of red, +r+ + * * the amount of green, +g+ + * * the amount of blue, +b+ + * + * The value of the first argument must be between 0 and COLORS. + * (See the section Colors for the default color index.) Each + * of the last three arguments must be a value between 0 and 1000. + * When Curses.init_color is used, all occurrences of that color + * on the screen immediately change to the new definition. + */ static VALUE curses_init_color(VALUE obj, VALUE color, VALUE r, VALUE g, VALUE b) { @@ -780,6 +1105,11 @@ NUM2INT(g),NUM2INT(b)) == OK) ? Qtrue : Qfalse; } +/* + * Document-method: Curses.has_colors? + * + * Returns +true+ or +false+ depending on whether the terminal has color capbilities. + */ static VALUE curses_has_colors(VALUE obj) { @@ -787,6 +1117,11 @@ return has_colors() ? Qtrue : Qfalse; } +/* + * Document-method: Curses.can_change_color? + * + * Returns +true+ or +false+ depending on whether the terminal can change color attributes + */ static VALUE curses_can_change_color(VALUE obj) { @@ -795,6 +1130,11 @@ } #if defined(HAVE_COLORS) +/* + * Document-method: Curses.color + * + * returns COLORS + */ static VALUE curses_colors(VALUE obj) { @@ -804,6 +1144,12 @@ #define curses_colors rb_f_notimplement #endif +/* + * Document-method: Curses.color_content + * call-seq: color_content(color) + * + * Returns an 3 item Array of the RGB values in +color+ + */ static VALUE curses_color_content(VALUE obj, VALUE color) { @@ -816,6 +1162,11 @@ #if defined(HAVE_COLOR_PAIRS) +/* + * Document-method: Curses.color_pairs + * + * Returns the COLOR_PAIRS available, if the curses library supports it. + */ static VALUE curses_color_pairs(VALUE obj) { @@ -825,6 +1176,13 @@ #define curses_color_pairs rb_f_notimplement #endif +/* + * Document-method: Curses.pair_content + * call-seq: pair_content(pair) + * + * Returns a 2 item Array, with the foreground and + * background color, in +pair+ + */ static VALUE curses_pair_content(VALUE obj, VALUE pair) { @@ -835,12 +1193,28 @@ return rb_ary_new3(2,INT2FIX(f),INT2FIX(b)); } +/* + * Document-method: Curses.color_pair + * call-seq: color_pair(attrs) + * + * Sets the color pair attributes to +attrs+. + * + * This should be equivalent to Curses.attrset(COLOR_PAIR(+attrs+)) + * + * TODO: validate that equivalency + */ static VALUE curses_color_pair(VALUE obj, VALUE attrs) { return INT2FIX(COLOR_PAIR(NUM2INT(attrs))); } +/* + * Document-method: Curses.pair_number + * call-seq: pair_number(attrs) + * + * Returns the Fixnum color pair number of attributes +attrs+. + */ static VALUE curses_pair_number(VALUE obj, VALUE attrs) { @@ -877,7 +1251,11 @@ /* * Document-method: Curses.getmouse * - * Returns the current mouse or nil + * Returns coordinates of the mouse. + * + * This will read and pop the mouse event data off the queue + * + * TODO: all the BUTTON* constants are needed here, to examine the mask of the event */ static VALUE curses_getmouse(VALUE obj) @@ -892,6 +1270,14 @@ return (getmouse(mdata->mevent) == OK) ? val : Qnil; } +/* + * Document-method: Curses.ungetmouse + * + * It pushes a KEY_MOUSE event onto the input queue, and associates with that + * event the given state data and screen-relative character-cell coordinates. + * + * The Curses.ungetmouse function behaves analogously to Curses.ungetch. + */ static VALUE curses_ungetmouse(VALUE obj, VALUE mevent) { @@ -902,6 +1288,22 @@ return (ungetmouse(mdata->mevent) == OK) ? Qtrue : Qfalse; } +/* + * Document-method: Curses.mouseinterval + * call-seq: mouseinterval(interval) + * + * The Curses.mouseinterval function sets the maximum time + * (in thousands of a second) that can elapse between press + * and release events for them to be recognized as a click. + * + * Use Curses.mouseinterval(0) to disable click resolution. + * This function returns the previous interval value. + * + * Use Curses.mouseinterval(-1) to obtain the interval without + * altering it. + * + * The default is one sixth of a second. + */ static VALUE curses_mouseinterval(VALUE obj, VALUE interval) { @@ -909,6 +1311,12 @@ return mouseinterval(NUM2INT(interval)) ? Qtrue : Qfalse; } +/* + * Document-method: Curses.mousemask + * call-seq: mousemask(mask) + * + * Returns the +mask+ of the reportable events + */ static VALUE curses_mousemask(VALUE obj, VALUE mask) { @@ -982,6 +1390,14 @@ #endif #ifdef HAVE_DEF_PROG_MODE +/* + * Document-method: Curses.def_prog_mode + * + * Save the current terminal modes as the "program" + * state for use by the Curses.reset_prog_mode + * + * This is done automatically by Curses.init_screen + */ static VALUE curses_def_prog_mode(VALUE obj) { @@ -993,6 +1409,14 @@ #endif #ifdef HAVE_RESET_PROG_MODE +/* + * Document-method: Curses.reset_prog_mode + * + * Reset the current terminal modes to the saved state + * by the Curses.def_prog_mode + * + * This is done automatically by Curses.close_screen + */ static VALUE curses_reset_prog_mode(VALUE obj) { @@ -1179,7 +1603,8 @@ * Document-method: Curses::Window.setpos * call-seq: setpos(y, x) * - * A setter for the position of the window, + * A setter for the position of the cursor + * in the current window, * using coordinates +x+ and +y+ * */ @@ -2030,7 +2455,7 @@ * == Description * An implementation of the CRT screen handling and optimization library. * - * == Structures + * == Structures and such * * === Classes * @@ -2042,6 +2467,21 @@ * * Curses - basis for the curses implementation * * Curses::Key - the collection of constants * + * === Constants + * + * For whatever reason, these are not picked up in the RDoc + * These are Integer of the colors. + * + * * COLOR_BLACK = 0 + * * COLOR_RED = 1 + * * COLOR_GREEN = 2 + * * COLOR_YELLOW = 3 + * * COLOR_BLUE = 4 + * * COLOR_MAGENTA = 5 + * * COLOR_CYAN = 6 + * * COLOR_WHITE = 7 + * + * * == Examples * * * hello.rb @@ -2051,6 +2491,12 @@ * * rain.rb * :include: rain.rb * + * + * == TODO + * + * * document all the A_* constants + * * document all the BUTTON*_* constants + * * document all the ALL_MOUSE_EVENTS and REPORT_MOUSE_POSITION constants */ void Init_curses(void) @@ -2292,15 +2738,60 @@ rb_curses_define_const(A_COLOR); #ifdef COLORS + /* + * Document-const: Curses::COLORS + * + * Integer of the colors available + */ rb_curses_define_const(COLORS); #endif + /* + * Document-const: Curses::COLOR_BLACK + * + * Integer of the color black + */ rb_curses_define_const(COLOR_BLACK); + /* + * Document-const: COLOR_RED + * + * Integer of the color red + */ rb_curses_define_const(COLOR_RED); + /* + * Document-const: COLOR_GREEN + * + * Integer of the color green + */ rb_curses_define_const(COLOR_GREEN); + /* + * Document-const: COLOR_YELLOW + * + * Integer of the color yellow + */ rb_curses_define_const(COLOR_YELLOW); + /* + * Document-const: COLOR_BLUE + * + * Integer of the color blue + */ rb_curses_define_const(COLOR_BLUE); + /* + * Document-const: COLOR_MAGENTA + * + * Integer of the color magenta + */ rb_curses_define_const(COLOR_MAGENTA); + /* + * Document-const: COLOR_CYAN + * + * Integer of the color cyan + */ rb_curses_define_const(COLOR_CYAN); + /* + * Document-const: COLOR_WHITE + * + * Integer of the color white + */ rb_curses_define_const(COLOR_WHITE); #endif /* USE_COLOR */ #ifdef USE_MOUSE -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/