diff options
Diffstat (limited to 'doc/html/man/curs_util.3x.html')
| -rw-r--r-- | doc/html/man/curs_util.3x.html | 169 |
1 files changed, 109 insertions, 60 deletions
diff --git a/doc/html/man/curs_util.3x.html b/doc/html/man/curs_util.3x.html index 8181efa..5499bd4 100644 --- a/doc/html/man/curs_util.3x.html +++ b/doc/html/man/curs_util.3x.html @@ -1,7 +1,8 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <!-- + * t **************************************************************************** - * Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. * + * Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * * copy of this software and associated documentation files (the * @@ -27,7 +28,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_util.3x,v 1.32 2010/12/04 18:38:55 tom Exp @ + * @Id: curs_util.3x,v 1.37 2013/07/20 19:43:45 tom Exp @ --> <HTML> <HEAD> @@ -48,8 +49,8 @@ </PRE> <H2>NAME</H2><PRE> <STRONG>delay_output</STRONG>, <STRONG>filter</STRONG>, <STRONG>flushinp</STRONG>, <STRONG>getwin</STRONG>, <STRONG>key_name</STRONG>, <STRONG>keyname</STRONG>, - <STRONG>nofilter</STRONG>, <STRONG>putwin</STRONG>, <STRONG>unctrl</STRONG>, <STRONG>use_env</STRONG>, <STRONG>wunctrl</STRONG> - miscellaneous - <STRONG>curses</STRONG> utility routines + <STRONG>nofilter</STRONG>, <STRONG>putwin</STRONG>, <STRONG>unctrl</STRONG>, <STRONG>use_env</STRONG>, <STRONG>use_tioctl</STRONG>, <STRONG>wunctrl</STRONG> - + miscellaneous <STRONG>curses</STRONG> utility routines </PRE> @@ -63,6 +64,7 @@ <STRONG>void</STRONG> <STRONG>filter(void);</STRONG> <STRONG>void</STRONG> <STRONG>nofilter(void);</STRONG> <STRONG>void</STRONG> <STRONG>use_env(bool</STRONG> <STRONG>f);</STRONG> + <STRONG>void</STRONG> <STRONG>use_tioctl(bool</STRONG> <STRONG>f);</STRONG> <STRONG>int</STRONG> <STRONG>putwin(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>FILE</STRONG> <STRONG>*filep);</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*getwin(FILE</STRONG> <STRONG>*filep);</STRONG> <STRONG>int</STRONG> <STRONG>delay_output(int</STRONG> <STRONG>ms);</STRONG> @@ -122,16 +124,66 @@ <STRONG>$TERM</STRONG>. The limitation arises because the <STRONG>filter</STRONG> routine modifies the in-memory copy of the terminal information. - The <STRONG>use_env</STRONG> routine, if used, is called before <STRONG>initscr</STRONG> or - <STRONG>newterm</STRONG> are called. When called with <STRONG>FALSE</STRONG> as an argu- - ment, the values of <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the - <EM>terminfo</EM> database will be used, even if environment vari- - ables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> (used by default) are set, or if - <STRONG>curses</STRONG> is running in a window (in which case default be- - havior would be to use the window size if <STRONG>LINES</STRONG> and - <STRONG>COLUMNS</STRONG> are not set). Note that setting <STRONG>LINES</STRONG> or <STRONG>COLUMNS</STRONG> - overrides the corresponding size which may be obtained - from the operating system. + The <STRONG>use_env</STRONG> routine, if used, should be called before + <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> are called (because those compute the + screen size). It modifies the way <STRONG>ncurses</STRONG> treats environ- + ment variables when determining the screen size. + + <STRONG>o</STRONG> Normally ncurses looks first at the terminal database + for the screen size. + + If <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG> for parameter, it + stops here unless If <STRONG>use_tioctl</STRONG> was also called with + <STRONG>TRUE</STRONG> for parameter. + + <STRONG>o</STRONG> Then it asks for the screen size via operating system + calls. If successful, it overrides the values from + the terminal database. + + <STRONG>o</STRONG> Finally (unless <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG> parame- + ter), ncurses examines the <STRONG>LINES</STRONG> or <STRONG>COLUMNS</STRONG> environ- + ment variables, using a value in those to override the + results from the operating system or terminal data- + base. + + Ncurses also updates the screen size in response to + SIGWINCH, unless overridden by the <STRONG>LINES</STRONG> or <STRONG>COLUMNS</STRONG> + environment variables, + + The <STRONG>use_tioctl</STRONG> routine, if used, should be called before + <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> are called (because those compute the + screen size). After <STRONG>use_tioctl</STRONG> is called with <STRONG>TRUE</STRONG> as an + argument, ncurses modifies the last step in its computa- + tion of screen size as follows: + + <STRONG>o</STRONG> checks if the <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> environment variables + are set to a number greater than zero. + + <STRONG>o</STRONG> for each, ncurses updates the corresponding environ- + ment variable with the value that it has obtained via + operating system call or from the terminal database. + + <STRONG>o</STRONG> ncurses re-fetches the value of the environment vari- + ables so that it is still the environment variables + which set the screen size. + + The <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> routines combine as summarized + here: + + <EM>use</EM><STRONG>_</STRONG><EM>env</EM> <EM>use</EM><STRONG>_</STRONG><EM>tioctl</EM> <EM>Summary</EM> + ---------------------------------------------------------------- + TRUE FALSE This is the default behavior. ncurses + uses operating system calls unless over- + ridden by $LINES or $COLUMNS environment + variables. + TRUE TRUE ncurses updates $LINES and $COLUMNS + based on operating system calls. + + FALSE TRUE ncurses ignores $LINES and $COLUMNS, us- + es operating system calls to obtain + size. + FALSE FALSE ncurses relies on the terminal database + to determine size. The <STRONG>putwin</STRONG> routine writes all data associated with window <EM>win</EM> into the file to which <EM>filep</EM> points. This information @@ -191,60 +243,60 @@ control code. If <STRONG>use_legacy_coding</STRONG> has been called with a <STRONG>2</STRONG> parameter, <STRONG>unctrl</STRONG> returns the parameter, i.e., a one-character string with the parameter as - the first character. Otherwise, it returns ``~@'', - ``~A'', etc., analogous to ``^@'', ``^A'', C0 con- - trols. + the first character. Otherwise, it returns "~@", + "~A", etc., analogous to "^@", "^A", C0 controls. - X/Open Curses does not document whether <STRONG>unctrl</STRONG> can - be called before initializing curses. This imple- - mentation permits that, and returns the ``~@'', - etc., values in that case. + X/Open Curses does not document whether <STRONG>unctrl</STRONG> can + be called before initializing curses. This imple- + mentation permits that, and returns the "~@", etc., + values in that case. - <STRONG>o</STRONG> parameter values outside the 0 to 255 range. <STRONG>unc-</STRONG> + <STRONG>o</STRONG> parameter values outside the 0 to 255 range. <STRONG>unc-</STRONG> <STRONG>trl</STRONG> returns a null pointer. The SVr4 documentation describes the action of <STRONG>filter</STRONG> only - in the vaguest terms. The description here is adapted - from the XSI Curses standard (which erroneously fails to + in the vaguest terms. The description here is adapted + from the XSI Curses standard (which erroneously fails to describe the disabling of <STRONG>cuu</STRONG>). - The strings returned by <STRONG>unctrl</STRONG> in this implementation are - determined at compile time, showing C1 controls from the - upper-128 codes with a `~' prefix rather than `^'. Other - implementations have different conventions. For example, - they may show both sets of control characters with `^', - and strip the parameter to 7 bits. Or they may ignore C1 - controls and treat all of the upper-128 codes as print- + The strings returned by <STRONG>unctrl</STRONG> in this implementation are + determined at compile time, showing C1 controls from the + upper-128 codes with a `~' prefix rather than `^'. Other + implementations have different conventions. For example, + they may show both sets of control characters with `^', + and strip the parameter to 7 bits. Or they may ignore C1 + controls and treat all of the upper-128 codes as print- able. This implementation uses 8 bits but does not modify the string to reflect locale. The <STRONG>use_legacy_coding</STRONG> func- tion allows the caller to change the output of <STRONG>unctrl</STRONG>. - Likewise, the <STRONG>meta</STRONG> function allows the caller to change - the output of <STRONG>keyname</STRONG>, i.e., it determines whether to use - the `M-' prefix for ``meta'' keys (codes in the range 128 - to 255). Both <STRONG>use_legacy_coding</STRONG> and <STRONG>meta</STRONG> succeed only af- - ter curses is initialized. X/Open Curses does not docu- - ment the treatment of codes 128 to 159. When treating - them as ``meta'' keys (or if <STRONG>keyname</STRONG> is called before ini- - tializing curses), this implementation returns strings - ``M-^@'', ``M-^A'', etc. - - The <STRONG>keyname</STRONG> function may return the names of user-defined - string capabilities which are defined in the terminfo en- - try via the <STRONG>-x</STRONG> option of <STRONG>tic</STRONG>. This implementation auto- - matically assigns at run-time keycodes to user-defined - strings which begin with "k". The keycodes start at - KEY_MAX, but are not guaranteed to be the same value for - different runs because user-defined codes are merged from - all terminal descriptions which have been loaded. The - <STRONG>use_extended_names</STRONG> function controls whether this data is - loaded when the terminal description is read by the li- + Likewise, the <STRONG>meta</STRONG> function allows the caller to change + the output of <STRONG>keyname</STRONG>, i.e., it determines whether to use + the `M-' prefix for "meta" keys (codes in the range 128 to + 255). Both <STRONG>use_legacy_coding</STRONG> and <STRONG>meta</STRONG> succeed only after + curses is initialized. X/Open Curses does not document + the treatment of codes 128 to 159. When treating them as + "meta" keys (or if <STRONG>keyname</STRONG> is called before initializing + curses), this implementation returns strings "M-^@", + "M-^A", etc. + + The <STRONG>keyname</STRONG> function may return the names of user-defined + string capabilities which are defined in the terminfo en- + try via the <STRONG>-x</STRONG> option of <STRONG>tic</STRONG>. This implementation auto- + matically assigns at run-time keycodes to user-defined + strings which begin with "k". The keycodes start at + KEY_MAX, but are not guaranteed to be the same value for + different runs because user-defined codes are merged from + all terminal descriptions which have been loaded. The + <STRONG>use_extended_names</STRONG> function controls whether this data is + loaded when the terminal description is read by the li- brary. - The <STRONG>nofilter</STRONG> routine is specific to ncurses. It was not - supported on Version 7, BSD or System V implementations. - It is recommended that any code depending on ncurses ex- - tensions be conditioned using NCURSES_VERSION. + The <STRONG>nofilter</STRONG> and <STRONG>use_tioctl</STRONG> routines are specific to + ncurses. They were not supported on Version 7, BSD or + System V implementations. It is recommended that any code + depending on ncurses extensions be conditioned using + NCURSES_VERSION. </PRE> @@ -258,9 +310,6 @@ <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> </PRE> <HR> -<ADDRESS> -Man(1) output converted with -<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a> -</ADDRESS> +Man(1) output converted with <a href="http://invisible-island.net/scripts/readme.html#others_scripts">man2html</a> </BODY> </HTML> |