diff options
| author | Rong-En Fan <rafan@FreeBSD.org> | 2008-11-09 09:06:04 +0000 |
|---|---|---|
| committer | Rong-En Fan <rafan@FreeBSD.org> | 2008-11-09 09:06:04 +0000 |
| commit | a388f199193767bacbb38b172ab89cb84369736c (patch) | |
| tree | a1816f5667d2280b970ca44e407bac8cc4496c0a /man | |
| parent | aa59d4d4c5dda7e1c6f9dc0cc6edc58992a525c7 (diff) | |
| download | src-a388f199193767bacbb38b172ab89cb84369736c.tar.gz src-a388f199193767bacbb38b172ab89cb84369736c.zip | |
- Flatten the vendor area
Notes
Notes:
svn path=/vendor/ncurses/dist/; revision=184786
Diffstat (limited to 'man')
131 files changed, 19837 insertions, 0 deletions
diff --git a/man/MKterminfo.sh b/man/MKterminfo.sh new file mode 100755 index 000000000000..3a9960956567 --- /dev/null +++ b/man/MKterminfo.sh @@ -0,0 +1,110 @@ +#!/bin/sh +# $Id: MKterminfo.sh,v 1.12 2003/01/11 21:42:12 tom Exp $ +# +# MKterminfo.sh -- generate terminfo.5 from Caps tabular data +# +#*************************************************************************** +# Copyright (c) 1998,2002,2003 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 * +# "Software"), to deal in the Software without restriction, including * +# without limitation the rights to use, copy, modify, merge, publish, * +# distribute, distribute with modifications, sublicense, and/or sell * +# copies of the Software, and to permit persons to whom the Software is * +# furnished to do so, subject to the following conditions: * +# * +# The above copyright notice and this permission notice shall be included * +# in all copies or substantial portions of the Software. * +# * +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +# IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +# THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +# * +# Except as contained in this notice, the name(s) of the above copyright * +# holders shall not be used in advertising or otherwise to promote the * +# sale, use or other dealings in this Software without prior written * +# authorization. * +#*************************************************************************** +# +# This script takes terminfo.head and terminfo.tail and splices in between +# them a table derived from the Caps data file. Besides avoiding having +# the docs fall out of sync with the table, this also lets us set up tbl +# commands for better formatting of the table. +# +# NOTE: The s in this script really are control characters. It translates +# to \n because I couldn't get used to inserting linefeeds directly. There +# had better be no s in the table source text. +# +# keep the order independent of locale: +if test "${LANGUAGE+set}" = set; then LANGUAGE=C; export LANGUAGE; fi +if test "${LANG+set}" = set; then LANG=C; export LANG; fi +if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi +if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi +if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi +if test "${LC_COLLATE+set}" = set; then LC_COLLATE=C; export LC_COLLATE; fi + +# +head=$1 +caps=$2 +tail=$3 +cat <<'EOF' +'\" t +.\" DO NOT EDIT THIS FILE BY HAND! +.\" It is generated from terminfo.head, Caps, and terminfo.tail. +.\" +.\" Note: this must be run through tbl before nroff. +.\" The magic cookie on the first line triggers this under some man programs. +EOF +cat $head + +temp=temp$$ +sorted=sorted$$ +unsorted=unsorted$$ +trap "rm -f $sorted $temp $unsorted; exit 99" 1 2 5 15 + +sed -n <$caps "\ +/%%-STOP-HERE-%%/q +/^#%/s/#%//p +/^#/d +s/[ ][ ]*/ /g +s/$/T}/ +s/ [A-Z0-9_()\-][A-Z0-9_()\-]* [0-9\-][0-9\-]* [Y\-][B\-][C\-][G\-][EK\-]\** / T{/ +s/ bool / /p +s/ num / /p +s/ str / /p +" |sed -e 's/^$/../' | tr "\134" "\006" >$unsorted + +rm -f $sorted +rm -f $temp +saved=no +while true +do + data= + read data + test -z "$data" && break + case "$data" in #(vi + **) #(vi + echo "$data" >>$temp + saved=yes + ;; + *) + if test $saved = yes ; then + saved=no + sort $temp >>$sorted + rm -f $temp + fi + echo "$data" >>$sorted + ;; + esac +done <$unsorted +test $saved = yes && sort $temp >>$sorted + +sed -e 's/^\.\.$//' $sorted | tr "\005\006" "\012\134" +cat $tail + +rm -f $sorted $temp $unsorted diff --git a/man/Makefile.in b/man/Makefile.in new file mode 100644 index 000000000000..c04f7c9eea57 --- /dev/null +++ b/man/Makefile.in @@ -0,0 +1,80 @@ +# $Id: Makefile.in,v 1.41 2007/03/31 15:54:06 tom Exp $ +############################################################################## +# Copyright (c) 1998-2006,2007 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 "Software"), # +# to deal in the Software without restriction, including without limitation # +# the rights to use, copy, modify, merge, publish, distribute, distribute # +# with modifications, sublicense, and/or sell copies of the Software, and to # +# permit persons to whom the Software is furnished to do so, subject to the # +# following conditions: # +# # +# The above copyright notice and this permission notice shall be included in # +# all copies or substantial portions of the Software. # +# # +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # +# THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING # +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER # +# DEALINGS IN THE SOFTWARE. # +# # +# Except as contained in this notice, the name(s) of the above copyright # +# holders shall not be used in advertising or otherwise to promote the sale, # +# use or other dealings in this Software without prior written # +# authorization. # +############################################################################## +# +# Author: Thomas E. Dickey 1996,1997 +# +# Makefile for ncurses manual pages. +# +# NOTE: When you add or rename a man page, make sure you update both +# the top-level MANIFEST and any man/*.renames files! + +SHELL = /bin/sh + +DESTDIR = @DESTDIR@ +srcdir = @srcdir@ +prefix = @prefix@ +exec_prefix = @exec_prefix@ +datadir = @datadir@ +mandir = @mandir@ + +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ + +all \ +sources : terminfo.5 +depend : +tags : + +$(DESTDIR)$(mandir) : + sh $(srcdir)/../mkdirs.sh $@ + +EDITARGS = $(DESTDIR)$(mandir) $(srcdir) terminfo.5 $(srcdir)/*.[0-9]* + +install install.man : terminfo.5 $(DESTDIR)$(mandir) + sh ../edit_man.sh normal installing $(EDITARGS) + +uninstall uninstall.man : + -sh ../edit_man.sh normal removing $(EDITARGS) + +# We compose terminfo.5 from the real sources... +CAPLIST=$(srcdir)/../include/@TERMINFO_CAPS@ +terminfo.5: $(srcdir)/terminfo.head $(CAPLIST) $(srcdir)/terminfo.tail Makefile $(srcdir)/MKterminfo.sh + sh $(srcdir)/MKterminfo.sh $(srcdir)/terminfo.head $(CAPLIST) $(srcdir)/terminfo.tail >terminfo.5 + +mostlyclean : + -rm -f core tags TAGS *~ *.bak *.ln *.atac trace + +clean: mostlyclean + rm -f terminfo.5 + +../edit_man.sed : make_sed.sh @MANPAGE_RENAMES@ + sh $(srcdir)/make_sed.sh @MANPAGE_RENAMES@ >../edit_man.sed + +distclean realclean: clean + rm -f Makefile ../edit_man.* ../man_alias.* diff --git a/man/captoinfo.1m b/man/captoinfo.1m new file mode 100644 index 000000000000..de57a27cf0f4 --- /dev/null +++ b/man/captoinfo.1m @@ -0,0 +1,193 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: captoinfo.1m,v 1.22 2007/06/02 20:40:07 tom Exp $ +.TH @CAPTOINFO@ 1M "" +.ds n 5 +.ds d @TERMINFO@ +.SH NAME +\fB@CAPTOINFO@\fR - convert a \fItermcap\fR description into a \fIterminfo\fR description +.SH SYNOPSIS +\fB@CAPTOINFO@\fR [\fB-v\fR\fIn\fR \fIwidth\fR] [\fB-V\fR] [\fB-1\fR] [\fB-w\fR \fIwidth\fR] \fIfile\fR . . . +.SH DESCRIPTION +\fB@CAPTOINFO@\fR looks in \fIfile\fR for \fBtermcap\fR descriptions. For each +one found, an equivalent \fBterminfo\fR description is written to standard +output. Termcap \fBtc\fR capabilities are translated directly to terminfo +\fBuse\fR capabilities. +.PP +If no \fIfile\fR is given, then the environment variable \fBTERMCAP\fR is used +for the filename or entry. If \fBTERMCAP\fR is a full pathname to a file, only +the terminal whose name is specified in the environment variable \fBTERM\fR is +extracted from that file. If the environment variable \fBTERMCAP\fR is not +set, then the file \fB\*d\fR is read. +.TP 5 +\fB-v\fR +print out tracing information on standard error as the program runs. +.TP 5 +\fB-V\fR +print out the version of the program in use on standard error and exit. +.TP 5 +\fB-1\fR +cause the fields to print out one to a line. Otherwise, the fields +will be printed several to a line to a maximum width of 60 +characters. +.TP 5 +\fB-w\fR +change the output to \fIwidth\fR characters. +.SH FILES +.TP 20 +\*d +Compiled terminal description database. +.SH TRANSLATIONS FROM NONSTANDARD CAPABILITIES +.PP +Some obsolete nonstandard capabilities will automatically be translated +into standard (SVr4/XSI Curses) terminfo capabilities by \fB@CAPTOINFO@\fR. +Whenever one of these automatic translations is done, the program +will issue an notification to stderr, inviting the user to check that +it has not mistakenly translated a completely unknown and random +capability and/or syntax error. +.PP +.TS H +c c c c +c c c c +l l l l. +Nonstd Std From Terminfo +name name capability +_ +BO mr AT&T enter_reverse_mode +CI vi AT&T cursor_invisible +CV ve AT&T cursor_normal +DS mh AT&T enter_dim_mode +EE me AT&T exit_attribute_mode +FE LF AT&T label_on +FL LO AT&T label_off +XS mk AT&T enter_secure_mode +EN @7 XENIX key_end +GE ae XENIX exit_alt_charset_mode +GS as XENIX enter_alt_charset_mode +HM kh XENIX key_home +LD kL XENIX key_dl +PD kN XENIX key_npage +PN po XENIX prtr_off +PS pf XENIX prtr_on +PU kP XENIX key_ppage +RT @8 XENIX kent +UP ku XENIX kcuu1 +KA k; Tek key_f10 +KB F1 Tek key_f11 +KC F2 Tek key_f12 +KD F3 Tek key_f13 +KE F4 Tek key_f14 +KF F5 Tek key_f15 +BC Sb Tek set_background +FC Sf Tek set_foreground +HS mh Iris enter_dim_mode +.TE +.PP +XENIX termcap also used to have a set of extension capabilities +for forms drawing, designed to take advantage of the IBM PC +high-half graphics. They were as follows: +.PP +.TS H +c c +l l. +Cap Graphic +_ +G2 upper left +G3 lower left +G1 upper right +G4 lower right +GR pointing right +GL pointing left +GU pointing up +GD pointing down +GH horizontal line +GV vertical line +GC intersection +G6 upper left +G7 lower left +G5 upper right +G8 lower right +Gr tee pointing right +Gr tee pointing left +Gu tee pointing up +Gd tee pointing down +Gh horizontal line +Gv vertical line +Gc intersection +GG acs magic cookie count +.TE +.PP +If the single-line capabilities occur in an entry, they will automatically +be composed into an \fIacsc\fR string. The double-line capabilities and +\fBGG\fR are discarded with a warning message. +.PP +IBM's AIX has a terminfo facility descended from SVr1 terminfo but incompatible +with the SVr4 format. The following AIX extensions are automatically +translated: +.TS +c c +l l. +IBM XSI +_ +ksel kslt +kbtab kcbt +font0 s0ds +font1 s1ds +font2 s2ds +font3 s3ds +.TE +.PP +Additionally, the AIX \fIbox1\fR capability will be automatically translated to +an \fIacsc\fR string. +.PP +Hewlett-Packard's terminfo library supports two nonstandard terminfo +capabilities \fImeml\fR (memory lock) and \fImemu\fR (memory unlock). +These will be discarded with a warning message. +.SH NOTES +This utility is actually a link to \fB@TIC@\fR(1M), running in \fI-I\fR mode. +You can use other \fB@TIC@\fR options such as \fB-f\fR and \fB-x\fR. +.PP +The trace option is not identical to SVr4's. Under SVr4, instead of following +the \fB-v\fR with a trace level n, you repeat it n times. +.SH SEE ALSO +\fB@INFOCMP@\fR(1M), +\fBcurses\fR(3X), +\fBterminfo\fR(\*n) +.PP +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.SH AUTHOR +Eric S. Raymond <esr@snark.thyrsus.com> +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/clear.1 b/man/clear.1 new file mode 100644 index 000000000000..31d0f93e05b9 --- /dev/null +++ b/man/clear.1 @@ -0,0 +1,53 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2000,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: clear.1,v 1.6 2006/12/24 18:07:53 tom Exp $ +.TH @CLEAR@ 1 "" +.ds n 5 +.SH NAME +\fB@CLEAR@\fR - clear the terminal screen +.SH SYNOPSIS +\fB@CLEAR@\fR +.br +.SH DESCRIPTION +\fB@CLEAR@\fR clears your screen if this is possible. It looks in the +environment for the terminal type and then in the \fBterminfo\fR database to +figure out how to clear the screen. +.PP +\fB@CLEAR@\fR ignores any command-line parameters that may be present. +.SH SEE ALSO +\fB@TPUT@\fR(1), \fBterminfo\fR(\*n) +.PP +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x new file mode 100644 index 000000000000..51ac1a4b5c35 --- /dev/null +++ b/man/curs_add_wch.3x @@ -0,0 +1,135 @@ +.\"*************************************************************************** +.\" Copyright (c) 2001-2002,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_add_wch.3x,v 1.6 2006/12/24 15:22:22 tom Exp $ +.TH curs_add_wch 3X "" +.SH NAME +\fBadd_wch\fP, +\fBwadd_wch\fP, +\fBmvadd_wch\fP, +\fBmvwadd_wch\fP, +\fBecho_wchar\fP, +\fBwecho_wchar\fP - add a complex character and rendition to a \fBcurses\fR window, then advance the cursor +.SH SYNOPSIS +.PP +\fB#include <curses.h>\fP +.sp +.B "int add_wch( const cchar_t *\fIwch\fB );" +.br +.B "int wadd_wch( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );" +.br +.B "int mvadd_wch( int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );" +.br +.B "int mvwadd_wch( WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );" +.br +.B "int echo_wchar( const cchar_t *\fIwch\fB );" +.br +.B "int wecho_wchar( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );" +.br +.SH DESCRIPTION +.PP +The +\fBadd_wch\fP, +\fBwadd_wch\fP, +\fBmvadd_wch\fP, and +\fBmvwadd_wch\fP +functions put the complex character \fIwch\fP into the given +window at its current position, +which is then advanced. +These functions perform +wrapping and special-character processing as follows: +.TP 5 +- +If \fIwch\fP refers to a spacing character, +then any previous character at that location is removed. +A new character specified by \fIwch\fP is +placed at that location with rendition specified by \fIwch\fP. +The cursor then advances to +the next spacing character on the screen. +.TP 5 +- +If \fIwch\fP refers to a non-spacing character, +all previous characters at that location are preserved. +The non-spacing characters of \fIwch\fP +are added to the spacing complex character, +and the rendition specified by \fIwch\fP is ignored. +.TP 5 +- +If the character part of \fIwch\fP is +a tab, newline, backspace or other control character, +the window is updated and the cursor moves as if \fBaddch\fR were called. +.PP +The \fBecho_wchar\fP +function is functionally equivalent to a call to +\fBadd_wch\fP +followed by a call to +\fBrefresh\fP. +Similarly, the +\fBwecho_wchar\fP +is functionally equivalent to a call to +\fBwadd_wch\fP +followed by a call to +\fBwrefresh\fP. +The knowledge +that only a single character is being output is taken into consideration and, +for non-control characters, a considerable performance gain might be seen +by using the *\fBecho\fP* functions instead of their equivalents. +.SH RETURN VALUES +.PP +All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success. +.SH NOTES +.PP +Note that +\fBadd_wch\fP, +\fBmvadd_wch\fP, +\fBmvwadd_wch\fP, and +\fBecho_wchar\fP +may be macros. +.SH PORTABILITY +.PP +All these functions are described in the XSI Curses standard, Issue 4. +The defaults specified for forms-drawing characters apply in the POSIX locale. +.PP +XSI documents constants beginning with \fBWACS_\fP which are used for +line-drawing. +Those are not currently implemented in \fBncurses\fP. +.SH SEE ALSO +.PP +\fBcurses\fR(3X), +\fBcurs_addch\fR(3X), +\fBcurs_attr\fR(3X), +\fBcurs_clear\fR(3X), +\fBcurs_outopts\fR(3X), +\fBcurs_refresh\fR(3X), +\fBputwc\fR(3) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_add_wchstr.3x b/man/curs_add_wchstr.3x new file mode 100644 index 000000000000..f84c2cb98c24 --- /dev/null +++ b/man/curs_add_wchstr.3x @@ -0,0 +1,97 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002-2004,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_add_wchstr.3x,v 1.6 2005/01/02 01:28:49 tom Exp $ +.TH curs_add_wchstr 3X "" +.SH NAME +\fBadd_wchstr\fR, +\fBadd_wchnstr\fR, +\fBwadd_wchstr\fR, +\fBwadd_wchnstr\fR, +\fBmvadd_wchstr\fR, +\fBmvadd_wchnstr\fR, +\fBmvwadd_wchstr\fR, +\fBmvwadd_wchnstr\fR \- add an array of complex characters (and attributes) to a curses window +.SH SYNOPSIS +.B #include <curses.h> +.PP +.nf +\fBint add_wchstr(const cchar_t *\fR\fIwchstr\fR\fB);\fR +.br +\fBint add_wchnstr(const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint wadd_wchstr(WINDOW *\fR \fIwin\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB);\fR +.br +\fBint wadd_wchnstr(WINDOW *\fR \fIwin\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvadd_wchstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB);\fR +.br +\fBint mvadd_wchnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvwadd_wchstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB);\fR +.br +\fBint mvwadd_wchnstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR +.fi +.SH DESCRIPTION +These routines copy the array of complex characters \fIwchstr\fR +into the window image structure at and after the current cursor position. +The four routines with \fIn\fR as the last +argument copy at most \fIn\fR elements, but no more than will fit on the line. +If \fBn\fR=\fB-1\fR then the whole array is copied, +to the maximum number of characters that will fit on the line. +.PP +The window cursor is \fInot\fR advanced. +These routines work faster than \fBwaddnstr\fR. +On the other hand, they do not perform checking +(such as for the newline, backspace, or carriage return characters), +they do not advance the current cursor position, +they do not expand other control characters to ^-escapes, +and they truncate the string if it crosses the right margin, +rather than wrapping it around to the new line. +.PP +These routines end successfully +on encountering a null \fIcchar_t\fR, or +when they have filled the current line. +If a complex character cannot completely fit at the end of the current line, +the remaining columns are filled with the background character and rendition. +.SH NOTES +All functions except \fBwadd_wchnstr\fR may be macros. +.SH RETURN VALUES +All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success. +.SH PORTABILITY +All these entry points are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_addchstr\fR(3X), +\fBcurs_addwstr\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_addch.3x b/man/curs_addch.3x new file mode 100644 index 000000000000..73918b88b954 --- /dev/null +++ b/man/curs_addch.3x @@ -0,0 +1,181 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_addch.3x,v 1.27 2007/06/02 20:40:07 tom Exp $ +.TH curs_addch 3X "" +.SH NAME +\fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, +\fBechochar\fR, +\fBwechochar\fR - add a character (with attributes) to a \fBcurses\fR window, then advance the cursor +.SH SYNOPSIS +\fB#include <curses.h>\fR +.PP +\fBint addch(const chtype ch);\fR +.br +\fBint waddch(WINDOW *win, const chtype ch);\fR +.br +\fBint mvaddch(int y, int x, const chtype ch);\fR +.br +\fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR +.br +\fBint echochar(const chtype ch);\fR +.br +\fBint wechochar(WINDOW *win, const chtype ch);\fR +.br +.SH DESCRIPTION +The \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR and \fBmvwaddch\fR routines put +the character \fIch\fR into the given window at its current window position, +which is then advanced. They are analogous to \fBputchar\fR in \fBstdio\fR(3). +If the advance is at the right margin, the cursor automatically wraps to the +beginning of the next line. At the bottom of the current scrolling region, if +\fBscrollok\fR is enabled, the scrolling region is scrolled up one line. +.PP +If \fIch\fR is a tab, newline, or backspace, +the cursor is moved appropriately within the window. +Backspace moves the cursor one character left; at the left +edge of a window it does nothing. +Newline does a \fBclrtoeol\fR, +then moves the cursor to the window left margin on the next line, +scrolling the window if on the last line. +Tabs are considered to be at every eighth column. +The tab interval may be altered by setting the \fBTABSIZE\fR variable. +.PP +If \fIch\fR is any control character other than tab, newline, or backspace, it +is drawn in \fB^\fR\fIX\fR notation. Calling \fBwinch\fR after adding a +control character does not return the character itself, but instead returns +the ^-representation of the control character. +.PP +Video attributes can be combined with a character argument passed to +\fBaddch\fR or related functions by logical-ORing them into the character. +(Thus, text, including attributes, can be copied from one place to another +using \fBinch\fR and \fBaddch\fR.) See the \fBcurs_attr\fR(3X) page for +values of predefined video attribute constants that can be usefully OR'ed +into characters. +.PP +The \fBechochar\fR and \fBwechochar\fR routines are equivalent to a call to +\fBaddch\fR followed by a call to \fBrefresh\fR, or a call to \fBwaddch\fR +followed by a call to \fBwrefresh\fR. The knowledge that only a single +character is being output is used and, for non-control characters, a +considerable performance gain may be seen by using these routines instead of +their equivalents. +.SS Line Graphics +The following variables may be used to add line drawing characters to the +screen with routines of the \fBaddch\fR family. The default character listed +below is used if the \fBacsc\fR capability does not define a terminal-specific +replacement for it. +The names are taken from VT100 nomenclature. +.PP +.TS +l l l +_ _ _ +l l l. +\fIName\fR \fIDefault\fR \fIDescription\fR +ACS_BLOCK # solid square block +ACS_BOARD # board of squares +ACS_BTEE + bottom tee +ACS_BULLET o bullet +ACS_CKBOARD : checker board (stipple) +ACS_DARROW v arrow pointing down +ACS_DEGREE ' degree symbol +ACS_DIAMOND + diamond +ACS_GEQUAL > greater-than-or-equal-to +ACS_HLINE - horizontal line +ACS_LANTERN # lantern symbol +ACS_LARROW < arrow pointing left +ACS_LEQUAL < less-than-or-equal-to +ACS_LLCORNER + lower left-hand corner +ACS_LRCORNER + lower right-hand corner +ACS_LTEE + left tee +ACS_NEQUAL ! not-equal +ACS_PI * greek pi +ACS_PLMINUS # plus/minus +ACS_PLUS + plus +ACS_RARROW > arrow pointing right +ACS_RTEE + right tee +ACS_S1 - scan line 1 +ACS_S3 - scan line 3 +ACS_S7 - scan line 7 +ACS_S9 \&_ scan line 9 +ACS_STERLING f pound-sterling symbol +ACS_TTEE + top tee +ACS_UARROW ^ arrow pointing up +ACS_ULCORNER + upper left-hand corner +ACS_URCORNER + upper right-hand corner +ACS_VLINE | vertical line +.TE +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success +(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon +successful completion, unless otherwise noted in the preceding routine +descriptions. +.SH NOTES +Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and +\fBechochar\fR may be macros. +.SH PORTABILITY +All these functions are described in the XSI Curses standard, Issue 4. +The defaults specified for forms-drawing characters apply in the POSIX locale. +.LP +Some ACS symbols +(ACS_S3, +ACS_S7, +ACS_LEQUAL, +ACS_GEQUAL, +ACS_PI, +ACS_NEQUAL, +ACS_STERLING) +were not documented in +any publicly released System V. However, many publicly available terminfos +include \fBacsc\fR strings in which their key characters (pryz{|}) are +embedded, and a second-hand list of their character descriptions has come +to light. The ACS-prefixed names for them were invented for \fBncurses\fR(3X). +.LP +The \fBTABSIZE\fR variable is implemented in some versions of curses, +but is not part of X/Open curses. +.LP +If \fIch\fR is a carriage return, +the cursor is moved to the beginning of the current row of the window. +This is true of other implementations, but is not documented. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_attr\fR(3X), +\fBcurs_clear\fR(3X), +\fBcurs_inch\fR(3X), +\fBcurs_outopts\fR(3X), +\fBcurs_refresh\fR(3X), +\fBputc\fR(3). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_add_wch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_addchstr.3x b/man/curs_addchstr.3x new file mode 100644 index 000000000000..ac1b040021e5 --- /dev/null +++ b/man/curs_addchstr.3x @@ -0,0 +1,99 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_addchstr.3x,v 1.12 2006/12/02 17:02:45 tom Exp $ +.TH curs_addchstr 3X "" +.na +.hy 0 +.SH NAME +\fBaddchstr\fR, +\fBaddchnstr\fR, +\fBwaddchstr\fR, +\fBwaddchnstr\fR, +\fBmvaddchstr\fR, +\fBmvaddchnstr\fR, +\fBmvwaddchstr\fR, +\fBmvwaddchnstr\fR - add a string of characters (and attributes) to a \fBcurses\fR window +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.PP +\fBint addchstr(const chtype *chstr);\fR +.br +\fBint addchnstr(const chtype *chstr, int n);\fR +.br +\fBint waddchstr(WINDOW *win, const chtype *chstr);\fR +.br +\fBint waddchnstr(WINDOW *win, const chtype *chstr, int n);\fR +.br +\fBint mvaddchstr(int y, int x, const chtype *chstr);\fR +.br +\fBint mvaddchnstr(int y, int x, const chtype *chstr, int n);\fR +.br +\fBint mvwaddchstr(WINDOW *win, int y, int x, const chtype *chstr);\fR +.br +\fBint mvwaddchnstr(WINDOW *win, int y, int x, const chtype *chstr, int n);\fR +.SH DESCRIPTION +These routines copy \fIchstr\fR into the window image structure at and after +the current cursor position. The four routines with \fIn\fR as the last +argument copy at most \fIn\fR elements, but no more than will fit on the line. +If \fBn\fR=\fB-1\fR then the whole string is copied, to the maximum number of +characters that will fit on the line. +.PP +The window cursor is \fInot\fR advanced, and these routines work faster than +\fBwaddnstr\fR. On the other hand, they do not perform any kind of checking +(such as for the newline, backspace, or carriage return characters), they do not +advance the current cursor position, they do not expand other control characters +to ^-escapes, and they truncate the string if it crosses the right margin, +rather than wrapping it around to the new line. +.SH RETURN VALUES +All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success +(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon +successful completion, unless otherwise noted in the preceding routine +descriptions. +.PP +X/Open does not define any error conditions. +This implementation returns an error +if the window pointer is null. +.SH NOTES +Note that all routines except \fBwaddchnstr\fR may be macros. +.SH PORTABILITY +These entry points are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fR(3X). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_add_wchstr\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_addstr.3x b/man/curs_addstr.3x new file mode 100644 index 000000000000..488b9dd8e752 --- /dev/null +++ b/man/curs_addstr.3x @@ -0,0 +1,97 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_addstr.3x,v 1.13 2005/05/15 16:17:14 tom Exp $ +.TH curs_addstr 3X "" +.na +.hy 0 +.SH NAME +\fBaddstr\fR, +\fBaddnstr\fR, +\fBwaddstr\fR, +\fBwaddnstr\fR, +\fBmvaddstr\fR, +\fBmvaddnstr\fR, +\fBmvwaddstr\fR, +\fBmvwaddnstr\fR - add a string of characters to a \fBcurses\fR window and advance cursor +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include <curses.h>\fR +.PP +\fBint addstr(const char *\fR\fIstr\fR\fB);\fR +.br +\fBint addnstr(const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint waddstr(WINDOW *\fR\fIwin\fR\fB, const char *\fR\fIstr\fR\fB);\fR +.br +\fBint waddnstr(WINDOW *\fR\fIwin\fR\fB, const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvaddstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB);\fR +.br +\fBint mvaddnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvwaddstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr\fR\fB);\fR +.br +\fBint mvwaddnstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const char *\fR\fIstr, int \fR\fIn\fR\fB);\fR +.fi +.SH DESCRIPTION +These routines write the characters of the (null-terminated) character string +\fIstr\fR on the given window. +It is similar to calling \fBwaddch\fR once for each character in the string. +The four routines with \fIn\fR as the last argument +write at most \fIn\fR characters. +If \fIn\fR is -1, then the entire string will be added, +up to the maximum number of characters that will fit on the line, +or until a terminating null is reached. +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success +(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon +successful completion. +.PP +X/Open does not define any error conditions. +This implementation returns an error +if the window pointer is null or +if the string pointer is null or +if the corresponding calls to \fBwaddch\fP return an error. +.SH NOTES +Note that all of these routines except \fBwaddstr\fR and \fBwaddnstr\fR may be +macros. +.SH PORTABILITY +All these entry points are described in the XSI Curses standard, Issue 4. The +XSI errors EILSEQ and EOVERFLOW, associated with extended-level conformance, +are not yet detected. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_addch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_addwstr.3x b/man/curs_addwstr.3x new file mode 100644 index 000000000000..63d274608cc7 --- /dev/null +++ b/man/curs_addwstr.3x @@ -0,0 +1,94 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_addwstr.3x,v 1.7 2006/02/25 20:59:08 tom Exp $ +.TH curs_addwstr 3X "" +.na +.hy 0 +.SH NAME +\fBaddwstr\fR, +\fBaddnwstr\fR, +\fBwaddwstr\fR, +\fBwaddnwstr\fR, +\fBmvaddwstr\fR, +\fBmvaddnwstr\fR, +\fBmvwaddwstr\fR, +\fBmvwaddnwstr\fR \- add a string of wide characters to a \fBcurses\fR window and advance cursor +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include <curses.h>\fR +.PP +\fBint addwstr(const wchar_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint addnwstr(const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint waddwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint waddnwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvaddwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint mvaddnwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvwaddwstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint mvwaddnwstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.fi +.SH DESCRIPTION +These routines write the characters of the +(null-terminated) \fBwchar_t\fR character string +\fIwstr\fR on the given window. +It is similar to constructing a \fBcchar_t\fR for each wchar_t in the string, +then calling \fBwadd_wch\fR for the resulting \fBcchar_t\fR. +.PP +The \fImv\fR routines perform cursor movement once, before writing any +characters. +Thereafter, the cursor is advanced as a side-effect of writing to the window. +.PP +The four routines with \fIn\fR as the last argument +write at most \fIn\fR \fBwchar_t\fR characters. +If \fIn\fR is -1, then the entire string will be added, +up to the maximum number of characters that will fit on the line, +or until a terminating null is reached. +.SH RETURN VALUES +All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success. +.SH NOTES +Note that all of these routines except \fBwaddnwstr\fR may be macros. +.SH PORTABILITY +All these entry points are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_add_wch\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_attr.3x b/man/curs_attr.3x new file mode 100644 index 000000000000..cf58affee13d --- /dev/null +++ b/man/curs_attr.3x @@ -0,0 +1,270 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_attr.3x,v 1.31 2007/03/17 20:30:33 tom Exp $ +.TH curs_attr 3X "" +.na +.hy 0 +.SH NAME +\fBattroff\fR, +\fBwattroff\fR, +\fBattron\fR, +\fBwattron\fR, +\fBattrset\fR, +\fBwattrset\fR, +\fBcolor_set\fR, +\fBwcolor_set\fR, +\fBstandend\fR, +\fBwstandend\fR, +\fBstandout\fR, +\fBwstandout\fR, +\fBattr_get\fR, +\fBwattr_get\fR, +\fBattr_off\fR, +\fBwattr_off\fR, +\fBattr_on\fR, +\fBwattr_on\fR, +\fBattr_set\fR, +\fBwattr_set\fR, +\fBchgat\fR, +\fBwchgat\fR, +\fBmvchgat\fR, +\fBmvwchgat\fR, +\fBPAIR_NUMBER\fR - \fBcurses\fR character and window attribute control routines +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.br +\fBint attroff(int attrs);\fR +.br +\fBint wattroff(WINDOW *win, int attrs);\fR +.br +\fBint attron(int attrs);\fR +.br +\fBint wattron(WINDOW *win, int attrs);\fR +.br +\fBint attrset(int attrs);\fR +.br +\fBint wattrset(WINDOW *win, int attrs);\fR +.br +\fBint color_set(short color_pair_number, void* opts);\fR +.br +\fBint wcolor_set(WINDOW *win, short color_pair_number,\fR + \fBvoid* opts);\fR +.br +\fBint standend(void);\fR +.br +\fBint wstandend(WINDOW *win);\fR +.br +\fBint standout(void);\fR +.br +\fBint wstandout(WINDOW *win);\fR +.br +\fBint attr_get(attr_t *attrs, short *pair, void *opts);\fR +.br +\fBint wattr_get(WINDOW *win, attr_t *attrs, short *pair,\fR + \fBvoid *opts);\fR +.br +\fBint attr_off(attr_t attrs, void *opts);\fR +.br +\fBint wattr_off(WINDOW *win, attr_t attrs, void *opts);\fR +.br +\fBint attr_on(attr_t attrs, void *opts);\fR +.br +\fBint wattr_on(WINDOW *win, attr_t attrs, void *opts);\fR +.br +\fBint attr_set(attr_t attrs, short pair, void *opts);\fR +.br +\fBint wattr_set(WINDOW *win, attr_t attrs, short pair, void *opts);\fR +.br +\fBint chgat(int n, attr_t attr, short color,\fR + \fBconst void *opts)\fR +.br +\fBint wchgat(WINDOW *win, int n, attr_t attr,\fR + \fBshort color, const void *opts)\fR +.br +\fBint mvchgat(int y, int x, int n, attr_t attr,\fR + \fBshort color, const void *opts)\fR +.br +\fBint mvwchgat(WINDOW *win, int y, int x, int n,\fR + \fBattr_t attr, short color, const void *opts)\fR +.br +.SH DESCRIPTION +These routines manipulate the current attributes of the named window. The +current attributes of a window apply to all characters that are written into +the window with \fBwaddch\fR, \fBwaddstr\fR and \fBwprintw\fR. Attributes are +a property of the character, and move with the character through any scrolling +and insert/delete line/character operations. To the extent possible, they are +displayed as appropriate modifications to the graphic rendition of characters +put on the screen. +.PP +The routine \fBattrset\fR sets the current attributes of the given window to +\fIattrs\fR. The routine \fBattroff\fR turns off the named attributes without +turning any other attributes on or off. The routine \fBattron\fR turns on the +named attributes without affecting any others. The routine \fBstandout\fR is +the same as \fBattron(A_STANDOUT)\fR. The routine \fBstandend\fR is the same +as \fBattrset(A_NORMAL)\fR or \fBattrset(0)\fR, that is, it turns off all +attributes. +.PP +The \fBattrset\fR and related routines do not affect the attributes used +when erasing portions of the window. +See \fBcurs_bkgd\fR(3X) for functions which modify the attributes used for +erasing and clearing. +.PP +The routine \fBcolor_set\fR sets the current color of the given window to the +foreground/background combination described by the color_pair_number. The +parameter opts is reserved for future use, applications must supply a null +pointer. +.PP +The routine \fBwattr_get\fR returns the current attribute and color pair for +the given window; \fBattr_get\fR returns the current attribute and color pair +for \fBstdscr\fR. +The remaining \fBattr_\fR* functions operate exactly like the corresponding +\fBattr\fR* functions, except that they take arguments of type \fBattr_t\fR +rather than \fBint\fR. +.PP +The routine \fBchgat\fR changes the attributes of a given number of characters +starting at the current cursor location of \fBstdscr\fR. It does not update +the cursor and does not perform wrapping. A character count of -1 or greater +than the remaining window width means to change attributes all the way to the +end of the current line. The \fBwchgat\fR function generalizes this to any +window; the \fBmvwchgat\fR function does a cursor move before acting. In these +functions, the color argument is a color-pair index (as in the first argument +of \fIinit_pair\fR, see \fBcurs_color\fR(3X)). The \fBopts\fR argument is not +presently used, but is reserved for the future (leave it \fBNULL\fR). +.SS Attributes +The following video attributes, defined in \fB<curses.h>\fR, can be passed to +the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'd with the +characters passed to \fBaddch\fR. +.PP +.TS +center ; +l l . +\fBA_NORMAL\fR Normal display (no highlight) +\fBA_STANDOUT\fR Best highlighting mode of the terminal. +\fBA_UNDERLINE\fR Underlining +\fBA_REVERSE\fR Reverse video +\fBA_BLINK\fR Blinking +\fBA_DIM\fR Half bright +\fBA_BOLD\fR Extra bright or bold +\fBA_PROTECT\fR Protected mode +\fBA_INVIS\fR Invisible or blank mode +\fBA_ALTCHARSET\fR Alternate character set +\fBA_CHARTEXT\fR Bit-mask to extract a character +\fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR Color-pair number \fIn\fR +.TE +.PP +The following macro is the reverse of \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR: +.PP +.br +\fBPAIR_NUMBER(\fR\fIattrs\fR) Returns the pair number associated + with the \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR attribute. +.br +.PP +The return values of many of these routines are not meaningful (they are +implemented as macro-expanded assignments and simply return their argument). +The SVr4 manual page claims (falsely) that these routines always return \fB1\fR. +.SH NOTES +Note that \fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR, +\fBattrset\fR, \fBwattrset\fR, \fBstandend\fR and \fBstandout\fR may be macros. +.PP +\fBCOLOR_PAIR\fP values can only be OR'd with attributes if the pair +number is less than 256. +The alternate functions such as \fBcolor_set\fP can pass a color pair +value directly. +However, ncurses ABI 4 and 5 simply OR this value within the alternate functions. +You must use ncurses ABI 6 to support more than 256 color pairs. +.SH PORTABILITY +These functions are supported in the XSI Curses standard, Issue 4. The +standard defined the dedicated type for highlights, \fBattr_t\fR, which is not +defined in SVr4 curses. The functions taking \fBattr_t\fR arguments are +not supported under SVr4. +.PP +The XSI Curses standard states that whether the traditional functions +\fBattron\fR/\fBattroff\fR/\fBattrset\fR can manipulate attributes other than +\fBA_BLINK\fR, \fBA_BOLD\fR, \fBA_DIM\fR, \fBA_REVERSE\fR, \fBA_STANDOUT\fR, or +\fBA_UNDERLINE\fR is "unspecified". Under this implementation as well as +SVr4 curses, these functions correctly manipulate all other highlights +(specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\fR). +.PP +XSI Curses added the new entry points, \fBattr_get\fR, \fBattr_on\fR, +\fBattr_off\fR, \fBattr_set\fR, \fBwattr_on\fR, \fBwattr_off\fR, +\fBwattr_get\fR, \fBwattr_set\fR. These are intended to work with +a new series of highlight macros prefixed with \fBWA_\fR. +.PP +Older versions of this library did not force an update of the screen +when changing the attributes. +Use \fBtouchwin\fR to force the screen to match the updated attributes. +.PP +.TS +center ; +l l . +\fBWA_NORMAL\fR Normal display (no highlight) +\fBWA_STANDOUT\fR Best highlighting mode of the terminal. +\fBWA_UNDERLINE\fR Underlining +\fBWA_REVERSE\fR Reverse video +\fBWA_BLINK\fR Blinking +\fBWA_DIM\fR Half bright +\fBWA_BOLD\fR Extra bright or bold +\fBWA_ALTCHARSET\fR Alternate character set +.TE +.PP +The XSI curses standard specifies that each pair of corresponding \fBA_\fR +and \fBWA_\fR-using functions operates on the same current-highlight +information. +.PP +The XSI standard extended conformance level adds new highlights +\fBA_HORIZONTAL\fR, \fBA_LEFT\fR, \fBA_LOW\fR, \fBA_RIGHT\fR, \fBA_TOP\fR, +\fBA_VERTICAL\fR (and corresponding \fBWA_\fR macros for each) which this +implementation does not yet support. +.SH RETURN VALUE +All routines return the integer \fBOK\fR on success, or \fBERR\fP on failure. +.PP +X/Open does not define any error conditions. +.PP +This implementation returns an error +if the window pointer is null. +The \fBwcolor_set\fP function returns an error if the color pair parameter +is outside the range 0..COLOR_PAIRS-1. +This implementation also provides +\fBgetattrs\fR +for compatibility with older versions of curses. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_addch\fR(3X), +\fBcurs_addstr\fR(3X), +\fBcurs_bkgd\fR(3X), +\fBcurs_printw\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_beep.3x b/man/curs_beep.3x new file mode 100644 index 000000000000..49e57619de3c --- /dev/null +++ b/man/curs_beep.3x @@ -0,0 +1,63 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_beep.3x,v 1.10 2005/01/08 17:55:51 tom Exp $ +.TH curs_beep 3X "" +.SH NAME +\fBbeep\fR, \fBflash\fR - \fBcurses\fR bell and screen flash routines +.SH SYNOPSIS +\fB#include <curses.h>\fR +.PP +\fBint beep(void);\fR +.br +\fBint flash(void);\fR +.br +.SH DESCRIPTION +The \fBbeep\fR and \fBflash\fR routines are used to alert the terminal user. +The routine \fBbeep\fR sounds an audible alarm on the terminal, if possible; +otherwise it flashes the screen (visible bell). The routine \fBflash\fR +flashes the screen, and if that is not possible, sounds the alert. If neither +alert is possible, nothing happens. Nearly all terminals have an audible alert +(bell or beep), but only some can flash the screen. +.SH RETURN VALUE +These routines return \fBOK\fR if they succeed in beeping or flashing, +\fBERR\fR otherwise. +.SH EXTENSIONS +SVr4's beep and flash routines always returned \fBOK\fR, so it was not +possible to tell when the beep or flash failed. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +Like SVr4, it specifies that they always return \fBOK\fR. +.SH SEE ALSO +\fBcurses\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_bkgd.3x b/man/curs_bkgd.3x new file mode 100644 index 000000000000..b2d768a441d9 --- /dev/null +++ b/man/curs_bkgd.3x @@ -0,0 +1,98 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2002,2003 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_bkgd.3x,v 1.19 2003/12/27 18:50:40 tom Exp $ +.TH curs_bkgd 3X "" +.SH NAME +\fBbkgdset\fR, \fBwbkgdset\fR, +\fBbkgd\fR, \fBwbkgd\fR, +\fBgetbkgd\fR - \fBcurses\fR window background manipulation routines +.SH SYNOPSIS +\fB#include <curses.h>\fR +.PP +\fBvoid bkgdset(chtype ch);\fR +.br +\fBvoid wbkgdset(WINDOW *win, chtype ch);\fR +.br +\fBint bkgd(chtype ch);\fR +.br +\fBint wbkgd(WINDOW *win, chtype ch);\fR +.br +\fBchtype getbkgd(WINDOW *win);\fR +.br +.SH DESCRIPTION +The \fBbkgdset\fR and \fBwbkgdset\fR routines manipulate the +background of the named window. +The window background is a \fBchtype\fR consisting of +any combination of attributes (i.e., rendition) and a character. +The attribute part of the background is combined (OR'ed) with all non-blank +characters that are written into the window with \fBwaddch\fR. Both +the character and attribute parts of the background are combined with +the blank characters. The background becomes a property of the +character and moves with the character through any scrolling and +insert/delete line/character operations. +.PP +To the extent possible on a particular terminal, +the attribute part of the background is displayed +as the graphic rendition of the character put on the screen. +.PP +The \fBbkgd\fR and \fBwbkgd\fR functions +set the background property of the current or specified window +and then apply this setting to every character position in that window: +.PP +.RS +The rendition of every character on the screen is changed to +the new background rendition. +.PP +Wherever the former background character +appears, it is changed to the new background character. +.RE +.PP +The \fBgetbkgd\fR function returns the given window's current background +character/attribute pair. +.SH RETURN VALUE +The routines \fBbkgd\fR and \fBwbkgd\fR return the integer \fBOK\fR. +The SVr4.0 manual says "or a non-negative integer if \fBimmedok\fR is set", +but this appears to be an error. +.SH NOTES +Note that \fBbkgdset\fR and \fBbkgd\fR may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +It specifies that \fBbkgd\fR and \fBwbkgd\fR return \fBERR\fR on failure. +but gives no failure conditions. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_addch\fR(3X), +\fBcurs_attr\fR(3X), +\fBcurs_outopts\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_bkgrnd.3x b/man/curs_bkgrnd.3x new file mode 100644 index 000000000000..8c6f6afff6f4 --- /dev/null +++ b/man/curs_bkgrnd.3x @@ -0,0 +1,106 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002-2004,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_bkgrnd.3x,v 1.3 2006/02/25 21:49:19 tom Exp $ +.TH curs_bkgrnd 3X "" +.SH NAME +\fBbkgrnd\fR, +\fBwbkgrnd\fR, +\fBbkgrndset\fR, +\fBwbkgrndset\fR, +\fBgetbkgrnd\fR, +\fBwgetbkgrnd\fR \- \fBcurses\fR window complex background manipulation routines +.SH SYNOPSIS +.PP +.B #include <curses.h> +.sp +\fBint bkgrnd(\fR\fB const cchar_t *\fR\fIwch\fR\fB);\fR +.br +\fBint wbkgrnd(\fR\fB WINDOW *\fR\fIwin\fR\fB, const cchar_t *\fR\fIwch\fR\fB);\fR +.br +\fBvoid bkgrndset(const cchar_t *\fR\fIwch\fR \fB);\fR +.br +\fBvoid wbkgrndset(WINDOW *\fR\fIwin\fR\fB, const cchar_t *\fR\fIwch\fR\fB);\fR +.br +\fBint getbkgrnd(cchar_t *\fR\fIwch\fR\fB);\fR +.br +\fBint wgetbkgrnd(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwch\fR\fB);\fR +.br +.SH DESCRIPTION +The \fBbkgrndset\fR and \fBwbkgrndset\fR routines manipulate the +background of the named window. +The window background is a \fBcchar_t\fR consisting of +any combination of attributes (i.e., rendition) and a complex character. +The attribute part of the background is combined (OR'ed) with all non-blank +characters that are written into the window with \fBwaddch\fR. Both +the character and attribute parts of the background are combined with +the blank characters. +The background becomes a property of the +character and moves with the character through any scrolling and +insert/delete line/character operations. +.PP +To the extent possible on a +particular terminal, the attribute part of the background is displayed +as the graphic rendition of the character put on the screen. +.PP +The \fBbkgrnd\fR and \fBwbkgrnd\fR functions +set the background property of the current or specified window +and then apply this setting to every character position in that window: +.RS +.PP +The rendition of every character on the screen is changed to +the new background rendition. +.PP +Wherever the former background character +appears, it is changed to the new background character. +.RE +.PP +The \fBgetbkgrnd\fR function returns the given window's current background +character/attribute pair via the \fBwch\fR pointer. +. +.SH NOTES +Note that +\fBbkgrnd\fR, +\fBbkgrndset\fR, and +\fBgetbkgrnd\fR +may be macros. +.SH RETURN VALUES +The \fBbkgrndset\fR and \fBwbkgrndset\fR routines do not return a value. +.PP +Upon successful completion, the other functions return \fBOK\fR. +Otherwise, they return \fBERR\fR. +A null window pointer is treated as an error. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_bkgd\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_border.3x b/man/curs_border.3x new file mode 100644 index 000000000000..09f9a4c221f9 --- /dev/null +++ b/man/curs_border.3x @@ -0,0 +1,155 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_border.3x,v 1.19 2007/02/24 16:15:38 tom Exp $ +.TH curs_border 3X "" +.na +.hy 0 +.SH NAME +\fBborder\fR, +\fBwborder\fR, +\fBbox\fR, +\fBhline\fR, +\fBwhline\fR, +\fBvline\fR, +\fBwvline\fR, +\fBmvhline\fR, +\fBmvwhline\fR, +\fBmvvline\fR, +\fBmvwvline\fR - create \fBcurses\fR borders, horizontal and vertical lines +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.br +\fBint border(chtype ls, chtype rs, chtype ts, chtype bs,\fR + \fBchtype tl, chtype tr, chtype bl, chtype br);\fR +.br +\fBint wborder(WINDOW *win, chtype ls, chtype rs,\fR + \fBchtype ts, chtype bs, chtype tl, chtype tr,\fR + \fBchtype bl, chtype br);\fR +.br +\fBint box(WINDOW *win, chtype verch, chtype horch);\fR +.br +\fBint hline(chtype ch, int n);\fR +.br +\fBint whline(WINDOW *win, chtype ch, int n);\fR +.br +\fBint vline(chtype ch, int n);\fR +.br +\fBint wvline(WINDOW *win, chtype ch, int n);\fR +.br +\fBint mvhline(int y, int x, chtype ch, int n);\fR +.br +\fBint mvwhline(WINDOW *, int y, int x, chtype ch, int n);\fR +.br +\fBint mvvline(int y, int x, chtype ch, int n);\fR +.br +\fBint mvwvline(WINDOW *, int y, int x, chtype ch, int n);\fR +.br +.SH DESCRIPTION +The \fBborder\fR, \fBwborder\fR and \fBbox\fR routines +draw a box around the edges of a window. +Other than the window, each argument is a character with attributes: +.sp +.RS +\fIls\fR - left side, +.br +\fIrs\fR - right side, +.br +\fIts\fR - top side, +.br +\fIbs\fR - bottom side, +.br +\fItl\fR - top left-hand corner, +.br +\fItr\fR - top right-hand corner, +.br +\fIbl\fR - bottom left-hand corner, and +.br +\fIbr\fR - bottom right-hand corner. +.RE +.PP +If any of these arguments is zero, then the corresponding +default values (defined in \fBcurses.h\fR) are used instead: +.sp +.RS +\fBACS_VLINE\fR, +.br +\fBACS_VLINE\fR, +.br +\fBACS_HLINE\fR, +.br +\fBACS_HLINE\fR, +.br +\fBACS_ULCORNER\fR, +.br +\fBACS_URCORNER\fR, +.br +\fBACS_LLCORNER\fR, +.br +\fBACS_LRCORNER\fR. +.RE +.PP +\fBbox(\fR\fIwin\fR\fB, \fR\fIverch\fR\fB, \fR\fIhorch\fR\fB)\fR is a shorthand +for the following call: \fBwborder(\fR\fIwin\fR\fB,\fR \fIverch\fR\fB,\fR +\fIverch\fR\fB,\fR \fIhorch\fR\fB,\fR \fIhorch\fR\fB, 0, 0, 0, 0)\fR. +.PP +The \fBhline\fR and \fBwhline\fR functions draw a horizontal (left to right) +line using \fIch\fR starting at the current cursor position in the window. The +current cursor position is not changed. The line is at most \fIn\fR characters +long, or as many as fit into the window. +.PP +The \fBvline\fR and \fBwvline\fR functions draw a vertical (top to bottom) line +using \fIch\fR starting at the current cursor position in the window. The +current cursor position is not changed. The line is at most \fIn\fR characters +long, or as many as fit into the window. +.SH RETURN VALUE +All routines return the integer \fBOK\fR. The SVr4.0 manual says "or a +non-negative integer if \fBimmedok\fR is set", but this appears to be an error. +.PP +X/Open does not define any error conditions. +This implementation returns an error +if the window pointer is null. +.SH NOTES +The borders generated by these functions are \fIinside\fR borders (this +is also true of SVr4 curses, though the fact is not documented). +.PP +Note that \fBborder\fR and \fBbox\fR may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +The standard specifies that they return \fBERR\fR on failure, +but specifies no error conditions. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_outopts\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_border_set.3x b/man/curs_border_set.3x new file mode 100644 index 000000000000..dbf865385b78 --- /dev/null +++ b/man/curs_border_set.3x @@ -0,0 +1,207 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002-2004,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_border_set.3x,v 1.6 2005/05/15 16:17:37 tom Exp $ +.TH curs_border_set 3X "" +.na +.hy 0 +.SH NAME +\fBborder_set\fR, +\fBwborder_set\fR, +\fBbox_set\fR, +\fBhline_set\fR, +\fBwhline_set\fR, +\fBmvhline_set\fR, +\fBmvwhline_set\fR, +\fBvline_set\fR, +\fBwvline_set\fR, +\fBmvvline_set\fR, +\fBmvwvline_set\fR \- create \fBcurses\fR borders or lines using complex characters and renditions +.ad +.hy +.SH SYNOPSIS +.PP +\fB#include <curses.h>\fR +.sp +\fBint border_set(\fR + \fBconst cchar_t *\fR\fIls\fR, \fBconst cchar_t *\fR\fIrs\fR, + \fBconst cchar_t *\fR\fIts\fR, \fBconst cchar_t *\fR\fIbs\fR, + \fBconst cchar_t *\fR\fItl\fR, \fBconst cchar_t *\fR\fItr\fR, + \fBconst cchar_t *\fR\fIbl\fR, \fBconst cchar_t *\fR\fIbr\fR +\fB);\fR +.br +\fBint wborder_set(\fR + \fBWINDOW *win\fR, + \fBconst cchar_t *\fR\fIls\fR, \fBconst cchar_t *\fR\fIrs\fR, + \fBconst cchar_t *\fR\fIts\fR, \fBconst cchar_t *\fR\fIbs\fR, + \fBconst cchar_t *\fR\fItl\fR, \fBconst cchar_t *\fR\fItr\fR, + \fBconst cchar_t *\fR\fIbl\fR, \fBconst cchar_t *\fR\fIbr\fR\fB);\fR +.br +\fBint box_set(\fR + \fBWINDOW *win\fR, + \fBconst cchar_t *\fR\fIverch\fR, + \fBconst cchar_t *\fR\fIhorch\fR\fB);\fR +.br +\fBint hline_set(\fR + \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR +.br +\fBint whline_set(\fR + \fBWINDOW *\fR\fIwin\fR, + \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR +.br +\fBint mvhline_set(\fR + \fBint \fR\fIy\fR, \fBint \fR\fIx\fR, + \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR +.br +\fBint mvwhline_set(\fR + \fBWINDOW *\fR\fIwin\fR, + \fBint \fR\fIy\fR, \fBint \fR\fIx\fR, + \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR +.br +\fBint vline_set(\fR + \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR +.br +\fBint wvline_set(\fR + \fBWINDOW *\fR\fIwin\fR, + \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR +.br +\fBint mvvline_set(\fR + \fBint \fR\fIy\fR, \fBint \fR\fIx\fR, + \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR +.br +\fBint mvwvline_set(\fR + \fBWINDOW *\fR\fIwin\fR, + \fBint \fR\fIy\fR, \fBint \fR\fIx\fR, + \fBconst cchar_t *\fR\fIwch\fR, \fBint \fR\fIn\fR\fB);\fR +.br +.SH DESCRIPTION +.PP +The +\fBborder_set\fR +and +\fBwborder_set\fR +functions draw a border around the edges of the current or specified window. +These functions do not change the cursor position, and do not wrap. +.PP +Other than the window, each argument is a complex character with attributes: +.RS +\fIls\fR - left side, +.br +\fIrs\fR - right side, +.br +\fIts\fR - top side, +.br +\fIbs\fR - bottom side, +.br +\fItl\fR - top left-hand corner, +.br +\fItr\fR - top right-hand corner, +.br +\fIbl\fR - bottom left-hand corner, and +.br +\fIbr\fR - bottom right-hand corner. +.RE +.PP +If any of these arguments is zero, then the corresponding +default values (defined in \fBcurses.h\fR) are used instead: +.RS +\fBWACS_VLINE\fR, +.br +\fBWACS_VLINE\fR, +.br +\fBWACS_HLINE\fR, +.br +\fBWACS_HLINE\fR, +.br +\fBWACS_ULCORNER\fR, +.br +\fBWACS_URCORNER\fR, +.br +\fBWACS_LLCORNER\fR, and +.br +\fBWACS_LRCORNER\fR. +.RE +.PP +\fBbox_set(\fR\fIwin\fR, \fIverch\fR\fB, \fR\fIhorch\fR\fB);\fR +is a shorthand for the following call: +.PP +\fBwborder_set(\fR\fIwin\fR\fB, \fR\fIverch\fR\fB, \fR\fIverch\fR\fB,\fR + \fIhorch\fR\fB, \fR\fIhorch\fR\fB, NULL, NULL, NULL, NULL);\fR +.PP +The +\fB*line_set\fR +functions use +\fIwch\fR +to draw a line starting at the current cursor position in the window. +The line is at most \fIn\fR characters long or as many as fit into the window. +The current cursor position is not changed. +.PP +The +\fBhline_set\fR, +\fBmvhline_set\fR, +\fBmvwhline_set\fR, and +\fBwhline_set\fR +functions draw a line proceeding toward the last column of the same line. +.PP +The +\fBvline_set\fR, +\fBmvvline_set\fR, +\fBmvwvline_set\fR, and +\fBwvline_set\fR +functions draw a line proceeding toward the last line of the window. +.br +.SH NOTES +.PP +Note that +\fBborder_set\fR, +\fBhline_set\fR, +\fBmvhline_set\fR, +\fBmvvline_set\fR, +\fBmvwhline_set\fR, +\fBmvwvline_set\fR, and +\fBvline_set\fR +may be macros. +.br +.SH RETURN VALUES +.PP +Upon successful completion, these functions return +\fBOK\fR. +Otherwise, they return +\fBERR\fR. +.PP +Functions using a window parameter return an error if it is null. +.SH SEE ALSO +\fBncurses\fR(3X), +\fBcurs_border\fR(3X), +\fBcurs_outopts\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_clear.3x b/man/curs_clear.3x new file mode 100644 index 000000000000..adbfd2cc001d --- /dev/null +++ b/man/curs_clear.3x @@ -0,0 +1,121 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_clear.3x,v 1.11 2007/12/29 15:58:38 tom Exp $ +.TH curs_clear 3X "" +.na +.hy 0 +.SH NAME +\fBerase\fR, +\fBwerase\fR, +\fBclear\fR, +\fBwclear\fR, +\fBclrtobot\fR, +\fBwclrtobot\fR, +\fBclrtoeol\fR, +\fBwclrtoeol\fR - clear all or part of a \fBcurses\fR window +.ad +.hy +.SH SYNOPSIS +\fB# include <curses.h>\fR +.sp +\fBint erase(void);\fR +.br +\fBint werase(WINDOW *win);\fR +.br +\fBint clear(void);\fR +.br +\fBint wclear(WINDOW *win);\fR +.br +\fBint clrtobot(void);\fR +.br +\fBint wclrtobot(WINDOW *win);\fR +.br +\fBint clrtoeol(void);\fR +.br +\fBint wclrtoeol(WINDOW *win);\fR +.br +.SH DESCRIPTION +The \fBerase\fR and \fBwerase\fR routines copy blanks to every +position in the window, clearing the screen. +.PP +The \fBclear\fR and \fBwclear\fR routines are like \fBerase\fR and +\fBwerase\fR, but they also call \fBclearok\fR, so that the screen is +cleared completely on the next call to \fBwrefresh\fR for that window +and repainted from scratch. +.PP +The \fBclrtobot\fR and \fBwclrtobot\fR routines erase from the cursor to the +end of screen. That is, they erase all lines below the cursor in the window. +Also, the current line to the right of the cursor, inclusive, is erased. +.PP +The \fBclrtoeol\fR and \fBwclrtoeol\fR routines erase the current line +to the right of the cursor, inclusive, to the end of the current line. +.PP +Blanks created by erasure have the current background rendition (as set +by \fBwbkgdset\fR) merged into them. +.SH RETURN VALUE +All routines return the integer \fBOK\fR on success and \fBERR\fP on failure. +The SVr4.0 manual says "or a +non-negative integer if \fBimmedok\fR is set", but this appears to be an error. +.PP +X/Open defines no error conditions. +In this implementation, +functions using a window pointer parameter return an error if it is null. +.SH NOTES +Note that \fBerase\fR, \fBwerase\fR, \fBclear\fR, \fBwclear\fR, +\fBclrtobot\fR, and \fBclrtoeol\fR may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. The +standard specifies that they return \fBERR\fR on failure, but specifies no +error conditions. +.PP +Some historic curses implementations had, as an undocumented feature, the +ability to do the equivalent of \fBclearok(..., 1)\fR by saying +\fBtouchwin(stdscr)\fR or \fBclear(stdscr)\fR. This will not work under +ncurses. +.PP +This implementation, and others such as Solaris, +sets the current position to 0,0 after erasing +via \fBwerase()\fP and \fBwclear()\fP. +That fact is not documented in other implementations, +and may not be true of implementations +which were not derived from SVr4 source. +.PP +Not obvious from the description, +most implementations clear the screen after \fBwclear\fP +even for a subwindow or derived window. +If you do not want to clear the screen during the next \fBwrefresh\fP, +use \fBwerase\fP instead. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_outopts\fR(3X), \fBcurs_refresh\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_color.3x b/man/curs_color.3x new file mode 100644 index 000000000000..99e63eff136e --- /dev/null +++ b/man/curs_color.3x @@ -0,0 +1,248 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2004,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_color.3x,v 1.28 2005/12/18 00:00:37 tom Exp $ +.TH curs_color 3X "" +.na +.hy 0 +.SH NAME +\fBstart_color\fR, +\fBinit_pair\fR, +\fBinit_color\fR, +\fBhas_colors\fR, +\fBcan_change_color\fR, +\fBcolor_content\fR, +\fBpair_content\fR, +\fBCOLOR_PAIR\fR - \fBcurses\fR color manipulation routines +.ad +.hy +.SH SYNOPSIS +\fB# include <curses.h>\fR +.br +\fBint start_color(void);\fR +.br +\fBint init_pair(short pair, short f, short b);\fR +.br +\fBint init_color(short color, short r, short g, short b);\fR +.br +\fBbool has_colors(void);\fR +.br +\fBbool can_change_color(void);\fR +.br +\fBint color_content(short color, short *r, short *g, short *b);\fR +.br +\fBint pair_content(short pair, short *f, short *b);\fR +.br +.SH DESCRIPTION +.SS Overview +\fBcurses\fR support color attributes on terminals with that capability. To +use these routines \fBstart_color\fR must be called, usually right after +\fBinitscr\fR. Colors are always used in pairs (referred to as color-pairs). +A color-pair consists of a foreground color (for characters) and a background +color (for the blank field on which the characters are displayed). A +programmer initializes a color-pair with the routine \fBinit_pair\fR. After it +has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR), a macro defined in +\fB<curses.h>\fR, can be used as a new video attribute. +.PP +If a terminal is capable of redefining colors, the programmer can use the +routine \fBinit_color\fR to change the definition of a color. The routines +\fBhas_colors\fR and \fBcan_change_color\fR return \fBTRUE\fR or \fBFALSE\fR, +depending on whether the terminal has color capabilities and whether the +programmer can change the colors. The routine \fBcolor_content\fR allows a +programmer to extract the amounts of red, green, and blue components in an +initialized color. The routine \fBpair_content\fR allows a programmer to find +out how a given color-pair is currently defined. +.SS Routine Descriptions +The \fBstart_color\fR routine requires no arguments. It must be +called if the programmer wants to use colors, and before any other +color manipulation routine is called. It is good practice to call +this routine right after \fBinitscr\fR. \fBstart_color\fR initializes +eight basic colors (black, red, green, yellow, blue, magenta, cyan, +and white), and two global variables, \fBCOLORS\fR and +\fBCOLOR_PAIRS\fR (respectively defining the maximum number of colors +and color-pairs the terminal can support). It also restores the +colors on the terminal to the values they had when the terminal was +just turned on. +.PP +The \fBinit_pair\fR routine changes the definition of a color-pair. It takes +three arguments: the number of the color-pair to be changed, the foreground +color number, and the background color number. +For portable applications: +.TP 5 +- +The value of the first argument +must be between \fB1\fR and \fBCOLOR_PAIRS-1\fR. +.TP 5 +- +The value of the second and +third arguments must be between 0 and \fBCOLORS\fR. +Color pair 0 is assumed to be white on black, +but is actually whatever the terminal implements before color is initialized. +It cannot be modified by the application. +.PP +If the color-pair was previously +initialized, the screen is refreshed and all occurrences of that color-pair +are changed to the new definition. +.PP +As an extension, ncurses allows you to set color pair 0 via +the \fBassume_default_colors\fR routine, or to specify the use of +default colors (color number \fB-1\fR) if you first invoke the +\fBuse_default_colors\fR routine. +.PP +The \fBinit_color\fR routine changes the definition of a color. It takes four +arguments: the number of the color to be changed followed by three RGB values +(for the amounts of red, green, and blue components). The value of the first +argument must be between \fB0\fR and \fBCOLORS\fR. (See the section +\fBColors\fR for the default color index.) Each of the last three arguments +must be a value between 0 and 1000. When \fBinit_color\fR is used, all +occurrences of that color on the screen immediately change to the new +definition. +.PP +The \fBhas_colors\fR routine requires no arguments. It returns \fBTRUE\fR if +the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR. This +routine facilitates writing terminal-independent programs. For example, a +programmer can use it to decide whether to use color or some other video +attribute. +.PP +The \fBcan_change_color\fR routine requires no arguments. It returns +\fBTRUE\fR if the terminal supports colors and can change their definitions; +other, it returns \fBFALSE\fR. This routine facilitates writing +terminal-independent programs. +.PP +The \fBcolor_content\fR routine gives programmers a way to find the intensity +of the red, green, and blue (RGB) components in a color. It requires four +arguments: the color number, and three addresses of \fBshort\fRs for storing +the information about the amounts of red, green, and blue components in the +given color. The value of the first argument must be between 0 and +\fBCOLORS\fR. The values that are stored at the addresses pointed to by the +last three arguments are between 0 (no component) and 1000 (maximum amount of +component). +.PP +The \fBpair_content\fR routine allows programmers to find out what colors a +given color-pair consists of. It requires three arguments: the color-pair +number, and two addresses of \fBshort\fRs for storing the foreground and the +background color numbers. The value of the first argument must be between 1 +and \fBCOLOR_PAIRS-1\fR. The values that are stored at the addresses pointed +to by the second and third arguments are between 0 and \fBCOLORS\fR. +.SS Colors +In \fB<curses.h>\fR the following macros are defined. These are the default +colors. \fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default +background color for all terminals. +.PP +.nf + \fBCOLOR_BLACK\fR + \fBCOLOR_RED\fR + \fBCOLOR_GREEN\fR + \fBCOLOR_YELLOW\fR + \fBCOLOR_BLUE\fR + \fBCOLOR_MAGENTA\fR + \fBCOLOR_CYAN\fR + \fBCOLOR_WHITE\fR +.fi +.SH RETURN VALUE +The routines \fBcan_change_color()\fR and \fBhas_colors()\fR return \fBTRUE\fR +or \fBFALSE\fR. +.PP +All other routines return the integer \fBERR\fR upon failure and an \fBOK\fR +(SVr4 specifies only "an integer value other than \fBERR\fR") upon successful +completion. +.PP +X/Open defines no error conditions. +This implementation will return \fBERR\fR on attempts to +use color values outside the range 0 to COLORS-1 +(except for the default colors extension), +or use color pairs outside the range 0 to COLOR_PAIR-1. +Color values used in \fBinit_color\fP must be in the range 0 to 1000. +An error is returned from all functions +if the terminal has not been initialized. +An error is returned from secondary functions such as \fBinit_pair\fP +if \fBstart_color\fP was not called. +.RS +.TP 5 +\fBinit_color\fP +returns an error if the terminal does not support +this feature, e.g., if the \fIinitialize_color\fP capability is absent +from the terminal description. +.TP 5 +\fBstart_color\fP +returns an error +If the color table cannot be allocated. +.RE +.SH NOTES +In the \fIncurses\fR implementation, there is a separate color activation flag, +color palette, color pairs table, and associated COLORS and COLOR_PAIRS counts +for each screen; the \fBstart_color\fR function only affects the current +screen. The SVr4/XSI interface is not really designed with this in mind, and +historical implementations may use a single shared color palette. +.PP +Note that setting an implicit background color via a color pair affects only +character cells that a character write operation explicitly touches. To change +the background color used when parts of a window are blanked by erasing or +scrolling operations, see \fBcurs_bkgd\fR(3X). +.PP +Several caveats apply on 386 and 486 machines with VGA-compatible graphics: +.TP 5 +- +COLOR_YELLOW is actually brown. To get yellow, use COLOR_YELLOW combined with +the \fBA_BOLD\fR attribute. +.TP 5 +- +The A_BLINK attribute should in theory cause the background to go bright. This +often fails to work, and even some cards for which it mostly works (such as the +Paradise and compatibles) do the wrong thing when you try to set a bright +"yellow" background (you get a blinking yellow foreground instead). +.TP 5 +- +Color RGB values are not settable. +.SH PORTABILITY +This implementation satisfies XSI Curses's minimum maximums +for \fBCOLORS\fR and \fBCOLOR_PAIRS\fR. +.PP +The \fBinit_pair\fP routine accepts negative values of foreground +and background color to support the \fBuse_default_colors\fP extension, +but only if that routine has been first invoked. +.PP +The assumption that \fBCOLOR_BLACK\fR is the default +background color for all terminals can be modified using the +\fBassume_default_colors\fP extension. +.PP +This implementation checks the pointers, +e.g., for the values returned by +\fBcolor_content\fP and \fBpair_content\fP, +and will treat those as optional parameters when null. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_initscr\fR(3X), +\fBcurs_attr\fR(3X), +\fBdefault_colors\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_delch.3x b/man/curs_delch.3x new file mode 100644 index 000000000000..70266678d7c6 --- /dev/null +++ b/man/curs_delch.3x @@ -0,0 +1,70 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2000,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_delch.3x,v 1.8 2006/02/25 21:42:57 tom Exp $ +.TH curs_delch 3X "" +.SH NAME +\fBdelch\fR, +\fBwdelch\fR, +\fBmvdelch\fR, +\fBmvwdelch\fR - delete character under the cursor in a \fBcurses\fR window +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint delch(void);\fR +.br +\fBint wdelch(WINDOW *win);\fR +.br +\fBint mvdelch(int y, int x);\fR +.br +\fBint mvwdelch(WINDOW *win, int y, int x);\fR +.br +.SH DESCRIPTION +These routines delete the character under the cursor; all characters to the +right of the cursor on the same line are moved to the left one position and the +last character on the line is filled with a blank. The cursor position does +not change (after moving to \fIy\fR, \fIx\fR, if specified). (This does not +imply use of the hardware delete character feature.) +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and an \fBOK\fR (SVr4 +specifies only "an integer value other than \fBERR\fR") upon successful +completion. +.SH NOTES +Note that \fBdelch\fR, \fBmvdelch\fR, and \fBmvwdelch\fR may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. The +standard specifies that they return \fBERR\fR on failure, but specifies no +error conditions. +.SH SEE ALSO +\fBcurses\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_deleteln.3x b/man/curs_deleteln.3x new file mode 100644 index 000000000000..fc7b16a96d07 --- /dev/null +++ b/man/curs_deleteln.3x @@ -0,0 +1,91 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_deleteln.3x,v 1.11 2007/06/02 20:40:07 tom Exp $ +.TH curs_deleteln 3X "" +.SH NAME +\fBdeleteln\fR, +\fBwdeleteln\fR, +\fBinsdelln\fR, +\fBwinsdelln\fR, +\fBinsertln\fR, +\fBwinsertln\fR - delete and insert lines in a \fBcurses\fR window +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint deleteln(void);\fR +.br +\fBint wdeleteln(WINDOW *win);\fR +.br +\fBint insdelln(int n);\fR +.br +\fBint winsdelln(WINDOW *win, int n);\fR +.br +\fBint insertln(void);\fR +.br +\fBint winsertln(WINDOW *win);\fR +.br +.SH DESCRIPTION +The \fBdeleteln\fR and \fBwdeleteln\fR routines delete the line under the +cursor in the window; all lines below the current line are moved up one line. +The bottom line of the window is cleared. The cursor position does not change. +.PP +The \fBinsdelln\fR and \fBwinsdelln\fR routines, for positive \fIn\fR, insert +\fIn\fR lines into the specified window above the current line. The \fIn\fR +bottom lines are lost. For negative \fIn\fR, delete \fIn\fR lines (starting +with the one under the cursor), and move the remaining lines up. The bottom +\fIn\fR lines are cleared. The current cursor position remains the same. +.PP +The \fBinsertln\fR and \fBwinsertln\fR routines insert a blank line above the +current line and the bottom line is lost. +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and an \fBOK\fR (SVr4 +specifies only "an integer value other than \fBERR\fR") upon successful +completion. +.PP +X/Open defines no error conditions. +In this implementation, +if the window parameter is null, an error is returned. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. The +standard specifies that they return \fBERR\fR on failure, but specifies no +error conditions. +.SH NOTES +Note that all but \fBwinsdelln\fR may be macros. +.PP +These routines do not require a hardware line delete or insert feature in the +terminal. In fact, they will not use hardware line delete/insert unless +\fBidlok(..., TRUE)\fR has been set on the current window. +.SH SEE ALSO +\fBcurses\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_extend.3x b/man/curs_extend.3x new file mode 100644 index 000000000000..3092253fff0b --- /dev/null +++ b/man/curs_extend.3x @@ -0,0 +1,85 @@ +.\"*************************************************************************** +.\" Copyright (c) 1999-2004,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1999-on +.\" +.\" $Id: curs_extend.3x,v 1.17 2006/12/24 18:01:48 tom Exp $ +.TH curs_extend 3X "" +.SH NAME +\fBcurses_version\fP, +\fBuse_extended_names\fP \- miscellaneous curses extensions +. +.SH SYNOPSIS +\fB#include <curses.h>\fP +.sp +\fBconst char * curses_version(void);\fP +.br +\fBint use_extended_names(bool enable);\fP +.SH DESCRIPTION +These functions are extensions to the curses library +which do not fit easily into other categories. +.PP +Use +.I curses_version() +to get the version number, including patch level of the library, e.g., +.B 5.0.19991023 +.PP +The +.I use_extended_names() +function controls whether the calling application +is able to use user-defined or nonstandard names +which may be compiled into the terminfo +description, i.e., via the terminfo or termcap interfaces. +Normally these names are available for use, since the essential decision +is made by using the \fB-x\fP option of \fB@TIC@\fP to compile +extended terminal definitions. +However you can disable this feature +to ensure compatibility with other implementations of curses. +.SH PORTABILITY +These 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 them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBcurs_getch\fR(3X), +\fBcurs_mouse\fR(3X), +\fBcurs_print\fR(3X), +\fBcurs_util\fR(3X), +\fBdefault_colors\fR(3X), +\fBdefine_key\fR(3X), +\fBkeybound\fR(3X), +\fBkeyok\fR(3X), +\fBresizeterm\fR(3X), +\fBwresize\fR(3X). +.SH AUTHOR +Thomas Dickey. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x new file mode 100644 index 000000000000..6ecff799b5d6 --- /dev/null +++ b/man/curs_get_wch.3x @@ -0,0 +1,161 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_get_wch.3x,v 1.6 2006/02/25 21:47:06 tom Exp $ +.TH curs_get_wch 3X "" +.SH NAME +\fBget_wch\fR, +\fBwget_wch\fR, +\fBmvget_wch\fR, +\fBmvwget_wch\fR, +\fBunget_wch\fR \- get (or push back) a wide character from curses terminal keyboard +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint get_wch(wint_t *\fR\fIwch\fR\fB);\fR +.br +\fBint wget_wch(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR +.br +\fBint mvget_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR +.br +\fBint mvwget_wch(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwch\fR\fB);\fR +.br +\fBint unget_wch(const wchar_t \fR\fIwch\fR\fB);\fR +.SH DESCRIPTION +The +\fBget_wch\fR, +\fBwget_wch\fR, +\fBmvget_wch\fR, and +\fBmvwget_wch\fR +functions read a character +from the terminal associated with the current or specified window. +In no-delay mode, +if no input is waiting, the value \fBERR\fR is returned. +In delay mode, +the program waits until the system passes text through to the program. +Depending on the setting of \fBcbreak\fR, +this is after one character (cbreak mode), +or after the first newline (nocbreak mode). +In half-delay mode, +the program waits until the user types a character or the specified +timeout interval has elapsed. +.PP +Unless \fBnoecho\fR has been set, +these routines echo the character into the designated window. +.PP +If the window is not a pad and has been moved or modified since the +last call to \fBwrefresh\fR, +\fBwrefresh\fR will be called before another character is read. +.PP +If \fBkeypad\fR is enabled, +these functions respond to +the pressing of a function key by setting the object pointed to by +\fIwch\fR +to the corresponding +\fBKEY_\fR +value defined +in +\fB<curses.h>\fR +and returning +\fBKEY_CODE_YES\fR. +If a character (such as escape) that could be the +beginning of a function key is received, curses sets a timer. +If the remainder +of the sequence does arrive within the designated time, curses passes through +the character; otherwise, curses returns the function key value. +For this +reason, many terminals experience a delay between the time a user presses +the escape key and the time the escape is returned to the program. +.PP +The +\fBunget_wch\fR +function pushes the wide character +\fIwch\fR +back onto the head of the input queue, so the wide character +is returned by the next call to +\fBget_wch\fR. +The pushback of +one character is guaranteed. +If the program calls +\fBunget_wch\fR +too many times without an intervening call to +\fBget_wch\fR, +the operation may fail. +.SH NOTES +The header file +\fB<curses.h>\fR +automatically +includes the header file +\fB<stdio.h>\fR. +.PP +Applications should not define the escape key by itself as a single-character +function. +.PP +When using +\fBget_wch\fR, +\fBwget_wch\fR, +\fBmvget_wch\fR, or +\fBmvwget_wch\fR, applications should +not use +\fBnocbreak\fR +mode and +\fBecho\fR +mode +at the same time. +Depending on the state of the tty driver when each character +is typed, the program may produce undesirable results. +.PP +All functions except \fBwget_wch\fR and \fBunget_wch\fR +may be macros. +.SH RETURN VALUES +When +\fBget_wch\fR, +\fBwget_wch\fR, +\fBmvget_wch\fR, and +\fBmvwget_wch\fR +functions successfully +report the pressing of a function key, they return +\fBKEY_CODE_YES\fR. +When they successfully report a wide character, they return +\fBOK\fR. +Otherwise, they return +\fBERR\fR. +.PP +Upon successful completion, +\fBunget_wch\fR +returns +\fBOK\fR. +Otherwise, the function returns +\fBERR\fR. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_getch\fR(3X), +\fBcurs_ins_wch\fR(3X), +\fBcurs_inopts\fR(3X), +\fBcurs_move\fR(3X), +\fBcurs_refresh\fR(3X) diff --git a/man/curs_get_wstr.3x b/man/curs_get_wstr.3x new file mode 100644 index 000000000000..4286c78b0d2a --- /dev/null +++ b/man/curs_get_wstr.3x @@ -0,0 +1,178 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_get_wstr.3x,v 1.6 2006/02/25 21:49:19 tom Exp $ +.TH curs_get_wstr 3X "" +.na +.hy 0 +.SH NAME +\fBget_wstr\fR, +\fBgetn_wstr\fR, +\fBwget_wstr\fR, +\fBwgetn_wstr\fR, +\fBmvget_wstr\fR, +\fBmvgetn_wstr\fR, +\fBmvwget_wstr\fR, +\fBmvwgetn_wstr\fR \- get an array of wide characters from a curses terminal keyboard +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include <curses.h>\fR +.sp +\fBint get_wstr(wint_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint getn_wstr(wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint wget_wstr(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint wgetn_wstr(WINDOW *\fR\fIwin\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvget_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint mvgetn_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvwget_wstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint mvwgetn_wstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wint_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.fi +.SH DESCRIPTION +The effect of +\fBget_wstr\fR +is as though a series of calls +to +\fBget_wch\fR +were made, until a newline, other end-of-line, or end-of-file condition is processed. +An end-of-file condition is represented by \fBWEOF\fR, as defined in \fB<wchar.h>\fR. +The newline and end-of-line conditions are represented by the \fB\\n\fR \fBwchar_t\fR value. +In all instances, the end of the string is terminated by a null \fBwchar_t\fR. +The routine places resulting values in the area pointed to by \fIwstr\fR. +.PP +The user's erase and kill characters are interpreted. If keypad +mode is on for the window, \fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR +are both considered equivalent to the user's kill character. +.PP +Characters input are echoed only if \fBecho\fR is currently on. In that case, +backspace is echoed as deletion of the previous character (typically a left +motion). +.PP +The effect of +\fBwget_wstr\fR +is as though a series of +calls to +\fBwget_wch\fR +were made. +.PP +The effect of +\fBmvget_wstr\fR +is as though a call to +\fBmove\fR +and then a series of calls to +\fBget_wch\fR +were +made. +.PP +The effect of +\fBmvwget_wstr\fR +is as though a call to +\fBwmove\fR +and then a series of calls to +\fBwget_wch\fR +were made. +.PP +The +\fBgetn_wstr\fR, +\fBmvgetn_wstr\fR, +\fBmvwgetn_wstr\fR, and +\fBwgetn_wstr\fR +functions are identical +to the +\fBget_wstr\fR, +\fBmvget_wstr\fR, +\fBmvwget_wstr\fR, and +\fBwget_wstr\fR +functions, respectively, +except that the +\fB*n_*\fR +versions read at most +\fIn\fR +characters, letting the application prevent overflow of the +input buffer. +.SH NOTES +Using +\fBget_wstr\fR, +\fBmvget_wstr\fR, +\fBmvwget_wstr\fR, or +\fBwget_wstr\fR +to read a line that +overflows the array pointed to by +\fBwstr\fR +causes undefined +results. +The use of +\fBgetn_wstr\fR, +\fBmvgetn_wstr\fR, +\fBmvwgetn_wstr\fR, or +\fBwgetn_wstr\fR, respectively, is recommended. +.PP +These functions cannot return \fBKEY_\fR values because there +is no way to distinguish a \fBKEY_\fR value from a valid \fBwchar_t\fR value. +.PP +All of these routines except \fBwgetn_wstr\fR may be macros. +.SH RETURN VALUES +All of these functions return \fBOK\fR upon successful completion. +Otherwise, they return \fBERR\fR. +.PP +Functions using a window parameter return an error if it is null. +.RS +.TP 5 +\fBwgetn_wstr\fP +returns an error if the associated call to \fBwget_wch\fP failed. +.RE +.SH PORTABILITY +These functions are described in The Single Unix Specification, Version 2. +No error conditions are defined. +This implementation returns ERR if the window pointer is null, +or if the lower-level \fBwget_wch\fR call returns an ERR. +In the latter case, +an ERR return without other data is treated as an end-of-file condition, +and the returned array contains a \fBWEOF\fR followed by a null \fBwchar_t\fR. +.PP +X/Open curses documents these functions to pass an array of \fBwchar_t\fR, +but all of the vendors implement this using \fBwint_t\fR. +.SH SEE ALSO +Functions: +\fBcurses\fR(3X), +\fBcurs_get_wch\fR(3X), +\fBcurs_getstr\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_getcchar.3x b/man/curs_getcchar.3x new file mode 100644 index 000000000000..b811a37db8f7 --- /dev/null +++ b/man/curs_getcchar.3x @@ -0,0 +1,144 @@ +.\"*************************************************************************** +.\" Copyright (c) 2001-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_getcchar.3x,v 1.10 2006/12/24 16:00:02 tom Exp $ +.TH curs_getcchar 3X "" +.SH NAME +\fBgetcchar\fP, +\fBsetcchar\fP \- Get a wide character string and rendition from a \fBcchar_t\fP or set a \fBcchar_t\fP from a wide-character string +.SH SYNOPSIS +\fB#include <curses.h>\fP +.sp +\fBint getcchar(\fP +.br +.B " const cchar_t *\fIwcval\fP," +.br +.B " wchar_t *\fIwch\fP," +.br +.B " attr_t *\fIattrs\fP," +.br +.B " short *\fIcolor_pair\fP," +.br +.B " void *\fIopts\fP );" +.sp +.B "int setcchar(" +.br +.B " cchar_t *\fIwcval\fP," +.br +.B " const wchar_t *\fIwch\fP," +.br +.B " const attr_t \fIattrs\fP," +.br +.B " short \fIcolor_pair\fP," +.br +.B " void *\fIopts\fP );" +.SH DESCRIPTION +.PP +The \fBgetcchar\fP function gets a wide-character string +and rendition from a \fBcchar_t\fP argument. +When \fIwch\fP is not a null pointer, +the \fBgetcchar\fP function does the following: +.TP 5 +- +Extracts information from a \fBcchar_t\fP value \fIwcval\fP +.TP 5 +- +Stores the character attributes in the location pointed to by \fIattrs\fP +.TP 5 +- +Stores the color-pair in the location pointed to by \fIcolor_pair\fP +.TP 5 +- +Stores the wide-character string, +characters referenced by \fIwcval\fP, into the array pointed to by \fIwch\fP. +.PP +When +\fIwch\fP +is a null pointer, the +\fBgetcchar\fP +function does the following: +.TP 5 +- +Obtains the number of wide characters pointed to by \fIwcval\fP +.TP 5 +- +Does not change the data referenced by +\fIattrs\fP +or +\fIcolor_pair\fP +.PP +The \fBsetcchar\fP function initializes the location pointed to by \fIwcval\fP +by using: +.TP 5 +- +The character attributes in +\fIattrs\fP +.TP 5 +- +The color pair in +\fIcolor_pair\fP +.TP 5 +- +The wide-character string pointed to by \fIwch\fP. +The string must be L'\\0' terminated, +contain at most one character with strictly positive width, +which must be the first, +and contain no characters of negative width. +.SH NOTES +.PP +The \fIopts\fP argument is reserved for future use. +Currently, an application must provide a null pointer as \fIopts\fP. +.PP +The \fIwcval\fP argument may be a value generated by a call to +\fBsetcchar\fP or by a function that has a \fBcchar_t\fP output argument. +If \fIwcval\fP is constructed by any other means, the effect is unspecified. +.SH RETURN VALUES +.PP +When \fIwch\fP is a null pointer, +\fBgetcchar\fP returns the number of wide characters referenced by +\fIwcval\fP. +.PP +When \fIwch\fP is not a null pointer, +\fBgetcchar\fP returns \fBOK\fP upon successful completion, +and \fBERR\fP otherwise. +.PP +Upon successful completion, \fBsetcchar\fP returns \fBOK\fP. +Otherwise, it returns \fBERR\fP. +.SH SEE ALSO +.PP +Functions: +\fBcurs_attr\fR(3X), +\fBcurs_color\fR(3X), +\fBcurses\fR(3X), +\fBwcwidth\fR(3). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_getch.3x b/man/curs_getch.3x new file mode 100644 index 000000000000..71fed5f7b60d --- /dev/null +++ b/man/curs_getch.3x @@ -0,0 +1,328 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_getch.3x,v 1.30 2006/12/02 17:02:53 tom Exp $ +.TH curs_getch 3X "" +.na +.hy 0 +.SH NAME +\fBgetch\fR, +\fBwgetch\fR, +\fBmvgetch\fR, +\fBmvwgetch\fR, +\fBungetch\fR, +\fBhas_key\fR \- get (or push back) characters from \fBcurses\fR terminal keyboard +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.PP +\fBint getch(void);\fR +.br +\fBint wgetch(WINDOW *win);\fR +.br +\fBint mvgetch(int y, int x);\fR +.br +\fBint mvwgetch(WINDOW *win, int y, int x);\fR +.br +\fBint ungetch(int ch);\fR +.br +\fBint has_key(int ch);\fR +.br +.SH DESCRIPTION +The \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR and \fBmvwgetch\fR, routines read +a character from the window. +In no-delay mode, if no input is waiting, the value \fBERR\fR is returned. +In delay mode, the program waits until the system +passes text through to the program. +Depending on the setting of \fBcbreak\fR, +this is after one character (cbreak mode), +or after the first newline (nocbreak mode). +In half-delay mode, +the program waits until a character is typed or the +specified timeout has been reached. +.PP +Unless \fBnoecho\fR has been set, +then the character will also be echoed into the +designated window according to the following rules: +If the character is the current erase character, left arrow, or backspace, +the cursor is moved one space to the left and that screen position is erased +as if \fBdelch\fR had been called. +If the character value is any other \fBKEY_\fR define, the user is alerted +with a \fBbeep\fR call. +Otherwise the character is simply output to the screen. +.PP +If the window is not a pad, and it has been moved or modified since the last +call to \fBwrefresh\fR, \fBwrefresh\fR will be called before another character +is read. +.PP +If \fBkeypad\fR is \fBTRUE\fR, and a function key is pressed, the token for +that function key is returned instead of the raw characters. +Possible function +keys are defined in \fB<curses.h>\fR as macros with values outside the range +of 8-bit characters whose names begin with \fBKEY_\fR. Thus, a variable +intended to hold the return value of a function key must be of short size or +larger. +.PP +When a character that could be the beginning of a function key is received +(which, on modern terminals, means an escape character), +\fBcurses\fR sets a timer. +If the remainder of the sequence does not come in within the designated +time, the character is passed through; +otherwise, the function key value is returned. +For this reason, many terminals experience a delay between the time +a user presses the escape key and the escape is returned to the program. +.PP +The \fBungetch\fR routine places \fIch\fR back onto the input queue to be +returned by the next call to \fBwgetch\fR. +There is just one input queue for all windows. +.PP +.SS Function Keys +The following function keys, defined in \fB<curses.h>\fR, might be returned by +\fBgetch\fR if \fBkeypad\fR has been enabled. +Note that not all of these are +necessarily supported on any particular terminal. +.sp +.TS +center tab(/) ; +l l +l l . +\fIName\fR/\fIKey\fR \fIname\fR +KEY_BREAK/Break key +KEY_DOWN/The four arrow keys ... +KEY_UP +KEY_LEFT +KEY_RIGHT +KEY_HOME/Home key (upward+left arrow) +KEY_BACKSPACE/Backspace +KEY_F0/T{ +Function keys; space for 64 keys is reserved. +T} +KEY_F(\fIn\fR)/T{ +For 0 \(<= \fIn\fR \(<= 63 +T} +KEY_DL/Delete line +KEY_IL/Insert line +KEY_DC/Delete character +KEY_IC/Insert char or enter insert mode +KEY_EIC/Exit insert char mode +KEY_CLEAR/Clear screen +KEY_EOS/Clear to end of screen +KEY_EOL/Clear to end of line +KEY_SF/Scroll 1 line forward +KEY_SR/Scroll 1 line backward (reverse) +KEY_NPAGE/Next page +KEY_PPAGE/Previous page +KEY_STAB/Set tab +KEY_CTAB/Clear tab +KEY_CATAB/Clear all tabs +KEY_ENTER/Enter or send +KEY_SRESET/Soft (partial) reset +KEY_RESET/Reset or hard reset +KEY_PRINT/Print or copy +KEY_LL/Home down or bottom (lower left) +KEY_A1/Upper left of keypad +KEY_A3/Upper right of keypad +KEY_B2/Center of keypad +KEY_C1/Lower left of keypad +KEY_C3/Lower right of keypad +KEY_BTAB/Back tab key +KEY_BEG/Beg(inning) key +KEY_CANCEL/Cancel key +KEY_CLOSE/Close key +KEY_COMMAND/Cmd (command) key +KEY_COPY/Copy key +KEY_CREATE/Create key +KEY_END/End key +KEY_EXIT/Exit key +KEY_FIND/Find key +KEY_HELP/Help key +KEY_MARK/Mark key +KEY_MESSAGE/Message key +KEY_MOUSE/Mouse event read +KEY_MOVE/Move key +KEY_NEXT/Next object key +KEY_OPEN/Open key +KEY_OPTIONS/Options key +KEY_PREVIOUS/Previous object key +KEY_REDO/Redo key +KEY_REFERENCE/Ref(erence) key +KEY_REFRESH/Refresh key +KEY_REPLACE/Replace key +KEY_RESIZE/Screen resized +KEY_RESTART/Restart key +KEY_RESUME/Resume key +KEY_SAVE/Save key +KEY_SBEG/Shifted beginning key +KEY_SCANCEL/Shifted cancel key +KEY_SCOMMAND/Shifted command key +KEY_SCOPY/Shifted copy key +KEY_SCREATE/Shifted create key +KEY_SDC/Shifted delete char key +KEY_SDL/Shifted delete line key +KEY_SELECT/Select key +KEY_SEND/Shifted end key +KEY_SEOL/Shifted clear line key +KEY_SEXIT/Shifted exit key +KEY_SFIND/Shifted find key +KEY_SHELP/Shifted help key +KEY_SHOME/Shifted home key +KEY_SIC/Shifted input key +KEY_SLEFT/Shifted left arrow key +KEY_SMESSAGE/Shifted message key +KEY_SMOVE/Shifted move key +KEY_SNEXT/Shifted next key +KEY_SOPTIONS/Shifted options key +KEY_SPREVIOUS/Shifted prev key +KEY_SPRINT/Shifted print key +KEY_SREDO/Shifted redo key +KEY_SREPLACE/Shifted replace key +KEY_SRIGHT/Shifted right arrow +KEY_SRSUME/Shifted resume key +KEY_SSAVE/Shifted save key +KEY_SSUSPEND/Shifted suspend key +KEY_SUNDO/Shifted undo key +KEY_SUSPEND/Suspend key +KEY_UNDO/Undo key +.TE +.PP +Keypad is arranged like this: +.sp +.TS +center allbox tab(/) ; +c c c . +\fBA1\fR/\fBup\fR/\fBA3\fR +\fBleft\fR/\fBB2\fR/\fBright\fR +\fBC1\fR/\fBdown\fR/\fBC3\fR +.TE +.sp +The \fBhas_key\fR routine takes a key value from the above list, and +returns TRUE or FALSE according to whether +the current terminal type recognizes a key with that value. +Note that a few values do not correspond to a real key, +e.g., \fBKEY_RESIZE\fP and \fBKEY_MOUSE\fP. +See \fBresizeterm\fR(3X) for more details about \fBKEY_RESIZE\fP, and +\fBcurs_mouse\fR(3X) for a discussion of \fBKEY_MOUSE\fP. +.PP +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and an integer value +other than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successful +completion. +.RS +.TP 5 +\fBungetch\fP +returns an error +if there is no more room in the FIFO. +.TP 5 +\fBwgetch\fP +returns an error +if the window pointer is null, or +if its timeout expires without having any data. +.RE +.SH NOTES +Use of the escape key by a programmer for a single character function is +discouraged, as it will cause a delay of up to one second while the +keypad code looks for a following function-key sequence. +.PP +Note that some keys may be the same as commonly used control +keys, e.g., \fBKEY_ENTER\fP versus control/M, \fBKEY_BACKSPACE\fP versus control/H. +Some curses implementations may differ according to whether they +treat these control keys specially (and ignore the terminfo), or +use the terminfo definitions. +\fBNcurses\fR uses the terminfo definition. +If it says that \fBKEY_ENTER\fP is control/M, +\fBgetch\fR will return \fBKEY_ENTER\fP +when you press control/M. +.PP +When using \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, or +\fBmvwgetch\fR, nocbreak mode (\fBnocbreak\fR) and echo mode +(\fBecho\fR) should not be used at the same time. +Depending on the +state of the tty driver when each character is typed, the program may +produce undesirable results. +.PP +Note that \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR may be macros. +.PP +Historically, the set of keypad macros was largely defined by the extremely +function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Safari 4. +Modern +personal computers usually have only a small subset of these. +IBM PC-style +consoles typically support little more than \fBKEY_UP\fR, \fBKEY_DOWN\fR, +\fBKEY_LEFT\fR, \fBKEY_RIGHT\fR, \fBKEY_HOME\fR, \fBKEY_END\fR, +\fBKEY_NPAGE\fR, \fBKEY_PPAGE\fR, and function keys 1 through 12. +The Ins key +is usually mapped to \fBKEY_IC\fR. +.SH PORTABILITY +The *get* functions are described in the XSI Curses standard, Issue 4. +They +read single-byte characters only. +The standard specifies that they return +\fBERR\fR on failure, but specifies no error conditions. +.PP +The echo behavior of these functions on input of \fBKEY_\fR or backspace +characters was not specified in the SVr4 documentation. +This description is +adopted from the XSI Curses standard. +.PP +The behavior of \fBgetch\fR and friends in the presence of handled signals is +unspecified in the SVr4 and XSI Curses documentation. +Under historical curses +implementations, it varied depending on whether the operating system's +implementation of handled signal receipt interrupts a \fBread\fR(2) call in +progress or not, and also (in some implementations) depending on whether an +input timeout or non-blocking mode has been set. +.PP +Programmers concerned about portability should be prepared for either of two +cases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receipt +interrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to +\fBEINTR\fR. +Under the \fBncurses\fR implementation, handled signals never +interrupt \fBgetch\fR. +.PP +The \fBhas_key\fR function is unique to \fBncurses\fR. +We recommend that +any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_inopts\fR(3X), +\fBcurs_mouse\fR(3X), +\fBcurs_move\fR(3X), +\fBcurs_refresh\fR(3X), +\fBresizeterm\fR(3X). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_get_wch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x new file mode 100644 index 000000000000..f131765043a1 --- /dev/null +++ b/man/curs_getstr.3x @@ -0,0 +1,122 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_getstr.3x,v 1.15 2006/01/12 00:30:58 tom Exp $ +.TH curs_getstr 3X "" +.na +.hy 0 +.SH NAME +\fBgetstr\fR, +\fBgetnstr\fR, +\fBwgetstr\fR, +\fBwgetnstr\fR, +\fBmvgetstr\fR, +\fBmvgetnstr\fR, +\fBmvwgetstr\fR, +\fBmvwgetnstr\fR - accept character strings from \fBcurses\fR terminal keyboard +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint getstr(char *str);\fR +.br +\fBint getnstr(char *str, int n);\fR +.br +\fBint wgetstr(WINDOW *win, char *str);\fR +.br +\fBint wgetnstr(WINDOW *win, char *str, int n);\fR +.br +\fBint mvgetstr(int y, int x, char *str);\fR +.br +\fBint mvwgetstr(WINDOW *win, int y, int x, char *str);\fR +.br +\fBint mvgetnstr(int y, int x, char *str, int n);\fR +.br +\fBint mvwgetnstr(WINDOW *, int y, int x, char *str, int n);\fR +.br +.SH DESCRIPTION +The function \fBgetstr\fR is equivalent to a series of calls to \fBgetch\fR, +until a newline or carriage return is received (the terminating character is +not included in the returned string). The resulting value is placed in the +area pointed to by the character pointer \fIstr\fR. +.PP +\fBwgetnstr\fR reads at most \fIn\fR characters, thus preventing a possible +overflow of the input buffer. Any attempt to enter more characters (other +than the terminating newline or carriage return) causes a beep. Function +keys also cause a beep and are ignored. The \fBgetnstr\fR function reads +from the \fIstdscr\fR default window. +.PP +The user's erase and kill characters are interpreted. If keypad +mode is on for the window, \fBKEY_LEFT\fR and \fBKEY_BACKSPACE\fR +are both considered equivalent to the user's kill character. +.PP +Characters input are echoed only if \fBecho\fR is currently on. In that case, +backspace is echoed as deletion of the previous character (typically a left +motion). +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and an \fBOK\fR (SVr4 +specifies only "an integer value other than \fBERR\fR") upon successful +completion. +.PP +X/Open defines no error conditions. +.PP +In this implementation, +these functions return an error +if the window pointer is null, or +if its timeout expires without having any data. +.PP +This implementation provides an extension as well. +If a SIGWINCH interrupts the function, it will return \fBKEY_RESIZE\fP +rather than \fBOK\fP or \fBERR\fP. +.SH NOTES +Note that \fBgetstr\fR, \fBmvgetstr\fR, and \fBmvwgetstr\fR may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +They read single-byte characters only. +The standard does not define any error conditions. +This implementation returns ERR if the window pointer is null, +or if the lower-level \fBwgetch\fR call returns an ERR. +.PP +SVr3 and early SVr4 curses implementations did not reject function keys; +the SVr4.0 documentation claimed that "special keys" (such as function +keys, "home" key, "clear" key, \fIetc\fR.) are "interpreted", without +giving details. It lied. In fact, the `character' value appended to the +string by those implementations was predictable but not useful +(being, in fact, the low-order eight bits of the key's KEY_ value). +.PP +The functions \fBgetnstr\fR, \fBmvgetnstr\fR, and \fBmvwgetnstr\fR were +present but not documented in SVr4. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_getch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_getyx.3x b/man/curs_getyx.3x new file mode 100644 index 000000000000..2581253d7c78 --- /dev/null +++ b/man/curs_getyx.3x @@ -0,0 +1,106 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_getyx.3x,v 1.16 2007/05/12 16:34:49 tom Exp $ +.TH curs_getyx 3X "" +.SH NAME +\fBgetyx\fR, +\fBgetparyx\fR, +\fBgetbegyx\fR, +\fBgetmaxyx\fR - get \fBcurses\fR cursor and window coordinates +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBvoid getyx(WINDOW *win, int y, int x);\fR +.br +\fBvoid getparyx(WINDOW *win, int y, int x);\fR +.br +\fBvoid getbegyx(WINDOW *win, int y, int x);\fR +.br +\fBvoid getmaxyx(WINDOW *win, int y, int x);\fR +.br +.SH DESCRIPTION +The \fBgetyx\fR macro places the current cursor position of the given window in +the two integer variables \fIy\fR and \fIx\fR. +.PP +If \fIwin\fR is a subwindow, the \fBgetparyx\fR macro places the beginning +coordinates of the subwindow relative to the parent window into two integer +variables \fIy\fR and \fIx\fR. +Otherwise, \fB-1\fR is placed into \fIy\fR and \fIx\fR. +.PP +Like \fBgetyx\fR, the \fBgetbegyx\fR and \fBgetmaxyx\fR macros store +the current beginning coordinates and size of the specified window. +.SH RETURN VALUE +The return values of these macros are undefined (i.e., +they should not be used as the right-hand side of assignment statements). +.SH NOTES +All of these interfaces are macros. +A "\fB&\fR" is not necessary before the variables \fIy\fR and \fIx\fR. +.SH PORTABILITY +The +\fBgetyx\fR, +\fBgetparyx\fR, +\fBgetbegyx\fR and +\fBgetmaxyx\fR +macros are described in the XSI Curses standard, Issue 4. +.PP +This implementation also provides functions +\fBgetbegx\fR, +\fBgetbegy\fR, +\fBgetcurx\fR, +\fBgetcury\fR, +\fBgetmaxx\fR, +\fBgetmaxy\fR, +\fBgetparx\fR and +\fBgetpary\fR +for compatibility with older versions of curses. +.PP +Although X/Open Curses does not address this, +many implementations provide members of the WINDOW structure +containing values corresponding to these macros. +For best portability, do not rely on using the data in WINDOW, +since some implementations make WINDOW opaque (do not allow +direct use of its members). +.PP +Besides the problem of opaque structures, +the data stored in like-named members may not have like-values in +different implementations. +For example, the WINDOW._maxx and WINDOW._maxy values in ncurses +have (at least since release 1.8.1) differed by one from some +other implementations. +The difference is hidden by means of the macro \fBgetmaxyx\fP. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_legacy\fR(3X), +\fBcurs_opaque\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_in_wch.3x b/man/curs_in_wch.3x new file mode 100644 index 000000000000..8709d130f180 --- /dev/null +++ b/man/curs_in_wch.3x @@ -0,0 +1,68 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_in_wch.3x,v 1.2 2006/02/25 21:42:22 tom Exp $ +.TH curs_in_wch 3X "" +.SH NAME +\fBin_wch\fR, +\fBmvin_wch\fR, +\fBmvwin_wch\fR, +\fBwin_wch\fR - extract a complex character and rendition from a window +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint in_wch(cchar_t *\fR\fIwcval\fR\fB);\fR +.br +\fBint mvin_wch(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR +.br +\fBint mvwin_wch(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR +.br +\fBint win_wch(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwcval\fR\fB);\fR +.SH DESCRIPTION +These functions extract the complex character and rendition from +the current position in the named window into the \fBcchar_t\fR object +referenced by wcval. +.SH RETURN VALUE +No errors are defined in the XSI Curses standard. +This implementation checks for null pointers, returns ERR in that case. +Also, the \fImv\fR routines check for error moving the cursor, returning ERR +in that case. +Otherwise they return OK +.SH NOTES +Note that all of these routines may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_inch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_in_wchstr.3x b/man/curs_in_wchstr.3x new file mode 100644 index 000000000000..b04a1f54cd76 --- /dev/null +++ b/man/curs_in_wchstr.3x @@ -0,0 +1,122 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_in_wchstr.3x,v 1.6 2006/12/02 17:03:07 tom Exp $ +.TH curs_in_wchstr 3X "" +.na +.hy 0 +.SH NAME +\fBin_wchstr\fR, +\fBin_wchnstr\fR, +\fBwin_wchstr\fR, +\fBwin_wchnstr\fR, +\fBmvin_wchstr\fR, +\fBmvin_wchnstr\fR, +\fBmvwin_wchstr\fR, +\fBmvwin_wchnstr\fR \- get an array of complex characters and renditions from a curses window +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include <curses.h>\fR +.sp +\fBint in_wchstr(cchar_t *\fR\fIwchstr\fR\fB);\fR +.br +\fBint in_wchnstr(cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint win_wchstr(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR +.br +\fBint win_wchnstr(WINDOW *\fR\fIwin\fR\fB, cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvin_wchstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR +.br +\fBint mvin_wchnstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvwin_wchstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR\fB);\fR +.br +\fBint mvwin_wchnstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, cchar_t *\fR\fIwchstr\fR, int \fIn\fR\fB);\fR +.fi +.SH DESCRIPTION +These functions return an array of complex characters in \fIwchstr\fR, +starting at the current cursor position in the named window. +Attributes (rendition) are stored with the characters. +.PP +The +\fBin_wchnstr\fR, +\fBmvin_wchnstr\fR, +\fBmvwin_wchnstr\fR +and +\fBwin_wchnstr\fR +fill the array +with at most +\fIn\fR +\fBcchar_t\fR +elements. +.br +.SH NOTES +Note that all routines except +\fBwin_wchnstr\fR +may be +macros. +.PP +Reading a line that overflows the array pointed to by +\fIwchstr\fR +with +\fBin_wchstr\fR, +\fBmvin_wchstr\fR, +\fBmvwin_wchstr\fR +or +\fBwin_wchstr\fR +causes undefined results. Therefore, the use of +\fBin_wchnstr\fR, +\fBmvin_wchnstr\fR, +\fBmvwin_wchnstr\fR, or +\fBwin_wchnstr\fR +is recommended. +.SH RETURN VALUES +Upon successful completion, these functions return +\fBOK\fR. +Otherwise, they return +\fBERR\fR. +.SH PORTABILITY +The XSI Curses defines no error conditions. +This implementation checks for null pointers, +returning ERR in that case. +.SH SEE ALSO +Functions: +\fBcurses\fR(3X), +\fBcurs_in_wch\fR(3X), +\fBcurs_instr\fR(3X), +\fBcurs_inwstr\fR(3X) +\fBcurs_inchstr\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_inch.3x b/man/curs_inch.3x new file mode 100644 index 000000000000..3091b9c0e6ae --- /dev/null +++ b/man/curs_inch.3x @@ -0,0 +1,77 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_inch.3x,v 1.13 2006/12/02 16:58:55 tom Exp $ +.TH curs_inch 3X "" +.SH NAME +\fBinch\fR, \fBwinch\fR, \fBmvinch\fR, \fBmvwinch\fR +- get a character and attributes from a \fBcurses\fR window +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBchtype inch(void);\fR +.br +\fBchtype winch(WINDOW *win);\fR +.br +\fBchtype mvinch(int y, int x);\fR +.br +\fBchtype mvwinch(WINDOW *win, int y, int x);\fR +.br +.SH DESCRIPTION +These routines return the character, of type \fBchtype\fR, at the current +position in the named window. If any attributes are set for that position, +their values are OR'ed into the value returned. Constants defined in +\fB<curses.h>\fR can be used with the \fB&\fR (logical AND) operator to +extract the character or attributes alone. +. +.SS Attributes +The following bit-masks may be AND-ed with characters returned by \fBwinch\fR. +. +.TS +l l . +\fBA_CHARTEXT\fR Bit-mask to extract character +\fBA_ATTRIBUTES\fR Bit-mask to extract attributes +\fBA_COLOR\fR Bit-mask to extract color-pair field information +.TE +.SH NOTES +Note that all of these routines may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fR(3X). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_in_wch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_inchstr.3x b/man/curs_inchstr.3x new file mode 100644 index 000000000000..18c21dc3190d --- /dev/null +++ b/man/curs_inchstr.3x @@ -0,0 +1,101 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_inchstr.3x,v 1.12 2006/12/02 17:00:58 tom Exp $ +.TH curs_inchstr 3X "" +.na +.hy 0 +.SH NAME +\fBinchstr\fR, +\fBinchnstr\fR, +\fBwinchstr\fR, +\fBwinchnstr\fR, +\fBmvinchstr\fR, +\fBmvinchnstr\fR, +\fBmvwinchstr\fR, +\fBmvwinchnstr\fR - get a string of characters (and attributes) from a \fBcurses\fR window +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint inchstr(chtype *chstr);\fR +.br +\fBint inchnstr(chtype *chstr, int n);\fR +.br +\fBint winchstr(WINDOW *win, chtype *chstr);\fR +.br +\fBint winchnstr(WINDOW *win, chtype *chstr, int n);\fR +.br +\fBint mvinchstr(int y, int x, chtype *chstr);\fR +.br +\fBint mvinchnstr(int y, int x, chtype *chstr, int n);\fR +.br +\fBint mvwinchstr(WINDOW *win, int y, int x, chtype *chstr);\fR +.br +\fBint mvwinchnstr(WINDOW *win, int y, int x, chtype *chstr, int n);\fR +.br +.SH DESCRIPTION +These routines return a NULL-terminated array of \fBchtype\fR quantities, +starting at the current cursor position in the named window and ending at the +right margin of the window. The four functions with \fIn\fR as +the last argument, return a leading substring at most \fIn\fR characters long +(exclusive of the trailing (chtype)0). +Constants defined in \fB<curses.h>\fR can be used with the \fB&\fR (logical +AND) operator to extract the character or the attribute alone from any position +in the \fIchstr\fR [see \fBcurs_inch\fR(3X)]. +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and an integer value +other than \fBERR\fR upon successful completion (the number of characters +retrieved, exclusive of the trailing 0). +.PP +No error conditions are defined. +If the \fIchstr\fP parameter is null, +no data is returned, +and the return value is zero. +.SH NOTES +Note that all routines except \fBwinchnstr\fR may be macros. SVr4 does not +document whether the result string is 0-terminated; it does not document +whether a length limit argument includes any trailing 0; and it does not +document the meaning of the return value. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. It is no +more specific than the SVr4 documentation on the trailing 0. It does specify +that the successful return of the functions is \fBOK\fR. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_inch\fR(3X). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_in_wchstr\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x new file mode 100644 index 000000000000..1a865f94ec08 --- /dev/null +++ b/man/curs_initscr.3x @@ -0,0 +1,132 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_initscr.3x,v 1.14 2005/05/15 16:18:01 tom Exp $ +.TH curs_initscr 3X "" +.na +.hy 0 +.SH NAME +\fBinitscr\fR, +\fBnewterm\fR, +\fBendwin\fR, +\fBisendwin\fR, +\fBset_term\fR, +\fBdelscreen\fR - \fBcurses\fR screen initialization and manipulation routines +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBWINDOW *initscr(void);\fR +.br +\fBint endwin(void);\fR +.br +\fBbool isendwin(void);\fR +.br +\fBSCREEN *newterm(char *type, FILE *outfd, FILE *infd);\fR +.br +\fBSCREEN *set_term(SCREEN *new);\fR +.br +\fBvoid delscreen(SCREEN* sp);\fR +.br +.SH DESCRIPTION +\fBinitscr\fR is normally the first \fBcurses\fR routine to call when +initializing a program. A few special routines sometimes need to be +called before it; these are \fBslk_init\fR, \fBfilter\fR, \fBripoffline\fR, +\fBuse_env\fR. For multiple-terminal applications, \fBnewterm\fR may be +called before \fBinitscr\fR. +.PP +The initscr code determines the terminal type and initializes all \fBcurses\fR +data structures. \fBinitscr\fR also causes the first call to \fBrefresh\fR to +clear the screen. If errors occur, \fBinitscr\fR writes an appropriate error +message to standard error and exits; otherwise, a pointer is returned to +\fBstdscr\fR. +.PP +A program that outputs to more than one terminal should use the \fBnewterm\fR +routine for each terminal instead of \fBinitscr\fR. A program that needs to +inspect capabilities, so it can continue to run in a line-oriented mode if the +terminal cannot support a screen-oriented program, would also use +\fBnewterm\fR. The routine \fBnewterm\fR should be called once for each +terminal. It returns a variable of type \fBSCREEN *\fR which should be saved +as a reference to that terminal. The arguments are the \fItype\fR of the +terminal to be used in place of \fB$TERM\fR, a file pointer for output to the +terminal, and another file pointer for input from the terminal (if \fItype\fR +is \fBNULL\fR, \fB$TERM\fR will be used). The program must also call +\fBendwin\fR for each terminal being used before exiting from \fBcurses\fR. +If \fBnewterm\fR is called more than once for the same terminal, the first +terminal referred to must be the last one for which \fBendwin\fR is called. +.PP +A program should always call \fBendwin\fR before exiting or escaping from +\fBcurses\fR 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 \fBrefresh\fR or \fBdoupdate\fR after a +temporary escape causes the program to resume visual mode. +.PP +The \fBisendwin\fR routine returns \fBTRUE\fR if \fBendwin\fR has been +called without any subsequent calls to \fBwrefresh\fR, and \fBFALSE\fR +otherwise. +.PP +The \fBset_term\fR routine is used to switch between different +terminals. The screen reference \fBnew\fR becomes the new current +terminal. The previous terminal is returned by the routine. This is +the only routine which manipulates \fBSCREEN\fR pointers; all other +routines affect only the current terminal. +.PP +The \fBdelscreen\fR routine frees storage associated with the +\fBSCREEN\fR data structure. The \fBendwin\fR routine does not do +this, so \fBdelscreen\fR should be called after \fBendwin\fR if a +particular \fBSCREEN\fR is no longer needed. +.SH RETURN VALUE +\fBendwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR +upon successful completion. +.PP +Routines that return pointers always return \fBNULL\fR on error. +.PP +X/Open defines no error conditions. +In this implementation +\fBendwin\fP returns an error if the terminal was not initialized. +.SH NOTES +Note that \fBinitscr\fR and \fBnewterm\fR may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. It +specifies that portable applications must not call \fBinitscr\fR more than +once. +.PP +Old versions of curses, e.g., BSD 4.4, may have returned a null pointer +from \fBinitscr\fR when an error is detected, rather than exiting. +It is safe but redundant to check the return value of \fBinitscr\fR +in XSI Curses. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_refresh\fR(3X), +\fBcurs_slk\fR(3X), \fBcurs_util\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x new file mode 100644 index 000000000000..7b5a17b8f125 --- /dev/null +++ b/man/curs_inopts.3x @@ -0,0 +1,242 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_inopts.3x,v 1.13 2005/05/15 16:18:07 tom Exp $ +.TH curs_inopts 3X "" +.na +.hy 0 +.SH NAME +\fBcbreak\fR, +\fBnocbreak\fR, +\fBecho\fR, +\fBnoecho\fR, +\fBhalfdelay\fR, +\fBintrflush\fR, +\fBkeypad\fR, +\fBmeta\fR, +\fBnodelay\fR, +\fBnotimeout\fR, +\fBraw\fR, +\fBnoraw\fR, +\fBnoqiflush\fR, +\fBqiflush\fR, +\fBtimeout\fR, +\fBwtimeout\fR, +\fBtypeahead\fR - \fBcurses\fR input options +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.PP +\fBint cbreak(void);\fR +.br +\fBint nocbreak(void);\fR +.br +\fBint echo(void);\fR +.br +\fBint noecho(void);\fR +.br +\fBint halfdelay(int tenths);\fR +.br +\fBint intrflush(WINDOW *win, bool bf);\fR +.br +\fBint keypad(WINDOW *win, bool bf);\fR +.br +\fBint meta(WINDOW *win, bool bf);\fR +.br +\fBint nodelay(WINDOW *win, bool bf);\fR +.br +\fBint raw(void);\fR +.br +\fBint noraw(void);\fR +.br +\fBvoid noqiflush(void);\fR +.br +\fBvoid qiflush(void);\fR +.br +\fBint notimeout(WINDOW *win, bool bf);\fR +.br +\fBvoid timeout(int delay);\fR +.br +\fBvoid wtimeout(WINDOW *win, int delay);\fR +.br +\fBint typeahead(int fd);\fR +.br +.SH DESCRIPTION +Normally, the tty driver buffers typed characters until a newline or carriage +return is typed. The \fBcbreak\fR 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 \fBnocbreak\fR routine returns the terminal to normal (cooked) +mode. +.PP +Initially the terminal may or may not be in \fBcbreak\fR mode, as the mode is +inherited; therefore, a program should call \fBcbreak\fR or \fBnocbreak\fR +explicitly. Most interactive programs using \fBcurses\fR set the \fBcbreak\fR +mode. Note that \fBcbreak\fR overrides \fBraw\fR. +[See \fBcurs_getch\fR(3X) for a +discussion of how these routines interact with \fBecho\fR and \fBnoecho\fR.] +.PP +The \fBecho\fR and \fBnoecho\fR routines control whether characters typed by +the user are echoed by \fBgetch\fR as they are typed. Echoing by the tty +driver is always disabled, but initially \fBgetch\fR is in echo mode, so +characters typed are echoed. Authors of most interactive programs prefer to do +their own echoing in a controlled area of the screen, or not to echo at all, so +they disable echoing by calling \fBnoecho\fR. +[See \fBcurs_getch\fR(3X) for a +discussion of how these routines interact with \fBcbreak\fR and +\fBnocbreak\fR.] +.PP +The \fBhalfdelay\fR routine is used for half-delay mode, which is similar to +\fBcbreak\fR mode in that characters typed by the user are immediately +available to the program. However, after blocking for \fItenths\fR tenths of +seconds, ERR is returned if nothing has been typed. The value of \fBtenths\fR +must be a number between 1 and 255. Use \fBnocbreak\fR to leave half-delay +mode. +.PP +If the \fBintrflush\fR option is enabled, (\fIbf\fR is \fBTRUE\fR), when an +interrupt key is pressed on the keyboard (interrupt, break, quit) all output in +the tty driver queue will be flushed, giving the effect of faster response to +the interrupt, but causing \fBcurses\fR to have the wrong idea of what is on +the screen. Disabling (\fIbf\fR is \fBFALSE\fR), the option prevents the +flush. The default for the option is inherited from the tty driver settings. +The window argument is ignored. +.PP +The \fBkeypad\fR option enables the keypad of the user's terminal. If +enabled (\fIbf\fR is \fBTRUE\fR), the user can press a function key +(such as an arrow key) and \fBwgetch\fR returns a single value +representing the function key, as in \fBKEY_LEFT\fR. If disabled +(\fIbf\fR is \fBFALSE\fR), \fBcurses\fR does not treat function keys +specially and the program has to interpret the escape sequences +itself. If the keypad in the terminal can be turned on (made to +transmit) and off (made to work locally), turning on this option +causes the terminal keypad to be turned on when \fBwgetch\fR is +called. The default value for keypad is false. +.PP +Initially, whether the terminal returns 7 or 8 significant bits on +input depends on the control mode of the tty driver [see termio(7)]. +To force 8 bits to be returned, invoke \fBmeta\fR(\fIwin\fR, +\fBTRUE\fR); this is equivalent, under POSIX, to setting the CS8 flag +on the terminal. To force 7 bits to be returned, invoke +\fBmeta\fR(\fIwin\fR, \fBFALSE\fR); this is equivalent, under POSIX, +to setting the CS7 flag on the terminal. The window argument, +\fIwin\fR, is always ignored. If the terminfo capabilities \fBsmm\fR +(meta_on) and \fBrmm\fR (meta_off) are defined for the terminal, +\fBsmm\fR is sent to the terminal when \fBmeta\fR(\fIwin\fR, +\fBTRUE\fR) is called and \fBrmm\fR is sent when \fBmeta\fR(\fIwin\fR, +\fBFALSE\fR) is called. +.PP +The \fBnodelay\fR option causes \fBgetch\fR to be a non-blocking call. +If no input is ready, \fBgetch\fR returns \fBERR\fR. If disabled +(\fIbf\fR is \fBFALSE\fR), \fBgetch\fR waits until a key is pressed. +.PP +While interpreting an input escape sequence, \fBwgetch\fR sets a timer +while waiting for the next character. If \fBnotimeout(\fR\fIwin\fR, +\fBTRUE\fR) is called, then \fBwgetch\fR does not set a timer. The +purpose of the timeout is to differentiate between sequences received +from a function key and those typed by a user. +.PP +The \fBraw\fR and \fBnoraw\fR routines place the terminal into or out of raw +mode. Raw mode is similar to \fBcbreak\fR 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 +\fBcurses\fR. +.PP +When the \fBnoqiflush\fR routine is used, normal flush of input and +output queues associated with the \fBINTR\fR, \fBQUIT\fR and +\fBSUSP\fR characters will not be done [see termio(7)]. When +\fBqiflush\fR is called, the queues will be flushed when these control +characters are read. You may want to call \fBnoqiflush()\fR in a signal +handler if you want output to continue as though the interrupt +had not occurred, after the handler exits. +.PP +The \fBtimeout\fR and \fBwtimeout\fR routines set blocking or +non-blocking read for a given window. If \fIdelay\fR is negative, +blocking read is used (i.e., waits indefinitely for +input). If \fIdelay\fR is zero, then non-blocking read is used +(i.e., read returns \fBERR\fR if no input is waiting). If +\fIdelay\fR is positive, then read blocks for \fIdelay\fR +milliseconds, and returns \fBERR\fR if there is still no input. +Hence, these routines provide the same functionality as \fBnodelay\fR, +plus the additional capability of being able to block for only +\fIdelay\fR milliseconds (where \fIdelay\fR is positive). +.PP +The \fBcurses\fR library does ``line-breakout optimization'' by looking for +typeahead periodically while updating the screen. If input is found, +and it is coming from a tty, the current update is postponed until +\fBrefresh\fR or \fBdoupdate\fR is called again. This allows faster +response to commands typed in advance. Normally, the input FILE +pointer passed to \fBnewterm\fR, or \fBstdin\fR in the case that +\fBinitscr\fR was used, will be used to do this typeahead checking. +The \fBtypeahead\fR routine specifies that the file descriptor +\fIfd\fR is to be used to check for typeahead instead. If \fIfd\fR is +-1, then no typeahead checking is done. +.SH RETURN VALUE +All routines that return an integer return \fBERR\fR upon failure and OK (SVr4 +specifies only "an integer value other than \fBERR\fR") upon successful +completion, unless otherwise noted in the preceding routine descriptions. +.PP +X/Open does not define any error conditions. +In this implementation, +functions with a window parameter will return an error if it is null. +Any function will also return an error if the terminal was not initialized. +Also, +.RS +.TP 5 +\fBhalfdelay\fP +returns an error +if its parameter is outside the range 1..255. +.RE +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.PP +The ncurses library obeys the XPG4 standard and the historical practice of the +AT&T curses implementations, in that the echo bit is cleared when curses +initializes the terminal state. BSD curses differed from this slightly; it +left the echo bit on at initialization, but the BSD \fBraw\fR call turned it +off as a side-effect. For best portability, set echo or noecho explicitly +just after initialization, even if your program remains in cooked mode. +.SH NOTES +Note that \fBecho\fR, \fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR, +\fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBnoqiflush\fR, +\fBqiflush\fR, \fBtimeout\fR, and \fBwtimeout\fR may be macros. +.PP +The \fBnoraw\fR and \fBnocbreak\fR calls follow historical practice in that +they attempt to restore to normal (`cooked') mode from raw and cbreak modes +respectively. Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver +control states that are hard to predict or understand; it is not recommended. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_getch\fR(3X), \fBcurs_initscr\fR(3X), \fBtermio\fR(7) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_ins_wch.3x b/man/curs_ins_wch.3x new file mode 100644 index 000000000000..bb8a9a34afa9 --- /dev/null +++ b/man/curs_ins_wch.3x @@ -0,0 +1,65 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_ins_wch.3x,v 1.3 2006/02/25 21:42:22 tom Exp $ +.TH curs_ins_wch 3X "" +.SH NAME +\fBins_wch\fR, +\fBmvins_wch\fR, +\fBmvwins_wch\fR, +\fBwins_wch\fR \- insert a complex character and rendition into a window +.SH SYNOPSIS +#include <curses.h> +.sp +\fBint ins_wch(const cchar_t *\fR\fIwch\fR\fB);\fR +.br +\fBint wins_wch(WINDOW *\fR\fIwin, const cchar_t *\fR\fIwch\fR\fB);\fR +.br +\fBint mvins_wch(int \fR\fIy, int \fR\fIx, const cchar_t *\fR\fIwch\fR\fB);\fR +.br +\fBint mvwins_wch(WINDOW *\fR\fIwin, int \fR\fIy, int \fR\fIx, const cchar_t *\fR\fIwch\fR\fB);\fR +.SH DESCRIPTION +These routines, insert the complex character \fIwch\fR with rendition +before the character under the cursor. +All characters to the right of the cursor are moved one space to the right, +with the possibility of the rightmost character on the line being lost. +The insertion operation does not change the cursor position. +.SH RETURN VALUE +If successful, these functions return OK. +If not, they return ERR. +.SH ERRORS +No errors are defined. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_insch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_ins_wstr.3x b/man/curs_ins_wstr.3x new file mode 100644 index 000000000000..0c153c4c67e4 --- /dev/null +++ b/man/curs_ins_wstr.3x @@ -0,0 +1,108 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_ins_wstr.3x,v 1.4 2005/05/15 17:02:54 tom Exp $ +.TH curs_ins_wstr 3X "" +.na +.hy 0 +.SH NAME +\fBins_wstr\fR, +\fBins_nwstr\fR, +\fBwins_wstr\fR, +\fBwins_nwstr\fR, +\fBmvins_wstr\fR, +\fBmvins_nwstr\fR, +\fBmvwins_wstr\fR, +\fBmvwins_nwstr\fR \- insert a wide-character string into a curses window +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include <curses.h>\fR +.sp +\fBint ins_wstr(const wchar_t *\fR\fIwstr);\fR +.br +\fBint ins_nwstr(const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint wins_wstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint wins_nwstr(WINDOW *\fR\fIwin\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvins_wstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint mvins_nwstr(int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvwins_wstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB);\fR +.br +\fBint mvwins_nwstr(WINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, const wchar_t *\fR\fIwstr\fR\fB, int \fR\fIn\fR\fB);\fR +.fi +.SH DESCRIPTION +These routines insert a \fBwchar_t\fR character string +(as many characters as will fit on the line) +before the character under the cursor. +All characters to the right of the cursor are shifted right, +with the possibility of the rightmost characters on the line being lost. +No wrapping is performed. +The cursor position does not change +(after moving to \fIy\fR, \fIx\fR, if specified). +The four routines with \fIn\fR as the last argument +insert a leading substring of at most \fIn\fR \fBwchar_t\fR characters. +If \fIn\fR is less than 1, the entire string is inserted. +.PP +If a character in \fIwstr\fR is a tab, newline, carriage return or +backspace, the cursor is moved appropriately within the window. +A newline also does a \fBclrtoeol\fR before moving. +Tabs are considered to be at every eighth column. +If a character in \fIwstr\fR is another control character, +it is drawn in the \fB^\fR\fIX\fR notation. +Calling \fBwin_wch\fR after adding a control character +(and moving to it, if necessary) +does not return the control character, +but instead returns a character in the ^-representation +of the control character. +.SH NOTES +Note that all but wins_nwstr may be macros. +.PP +If the first character in the string is a nonspacing character, these +functions will fail. +XSI does not define what will happen if a nonspacing character follows +a control character. +.SH RETURN VALUES +Upon successful completion, these functions return OK. +Otherwise, they return ERR. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_insstr\fR(3X), +\fBcurs_in_wch\fR(3X), +\fBcurs_ins_wch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_insch.3x b/man/curs_insch.3x new file mode 100644 index 000000000000..78ab5a59c89b --- /dev/null +++ b/man/curs_insch.3x @@ -0,0 +1,74 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_insch.3x,v 1.10 2006/12/02 17:01:50 tom Exp $ +.TH curs_insch 3X "" +.SH NAME +\fBinsch\fR, +\fBwinsch\fR, +\fBmvinsch\fR, +\fBmvwinsch\fR - insert a character before cursor in a \fBcurses\fR window +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint insch(chtype ch);\fR +.br +\fBint winsch(WINDOW *win, chtype ch);\fR +.br +\fBint mvinsch(int y, int x, chtype ch);\fR +.br +\fBint mvwinsch(WINDOW *win, int y, int x, chtype ch);\fR +.br +.SH DESCRIPTION +These routines insert the character \fIch\fR before the character under the +cursor. All characters to the right of the cursor are moved one space to the +right, with the possibility of the rightmost character on the line being lost. +The insertion operation does not change the cursor position. +.SH RETURN VALUE +All routines that return an integer return \fBERR\fR upon failure and OK (SVr4 +specifies only "an integer value other than \fBERR\fR") upon successful +completion, unless otherwise noted in the preceding routine descriptions. +.SH NOTES +These routines do not necessarily imply use of a hardware insert character +feature. +.PP +Note that \fBinsch\fR, \fBmvinsch\fR, and \fBmvwinsch\fR may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fR(3X). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_ins_wch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_insstr.3x b/man/curs_insstr.3x new file mode 100644 index 000000000000..1536ea293a5a --- /dev/null +++ b/man/curs_insstr.3x @@ -0,0 +1,101 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_insstr.3x,v 1.18 2006/12/24 14:59:30 tom Exp $ +.TH curs_insstr 3X "" +.SH NAME +\fBinsstr\fR, +\fBinsnstr\fR, +\fBwinsstr\fR, +\fBwinsnstr\fR, +\fBmvinsstr\fR, +\fBmvinsnstr\fR, +\fBmvwinsstr\fR, +\fBmvwinsnstr\fR - insert string before cursor in a \fBcurses\fR window +.SH SYNOPSIS +\fB#include <curses.h>\fR +.br +\fBint insstr(const char *str);\fR +.br +\fBint insnstr(const char *str, int n);\fR +.br +\fBint winsstr(WINDOW *win, const char *str);\fR +.br +\fBint winsnstr(WINDOW *win, const char *str, int n);\fR +.br +\fBint mvinsstr(int y, int x, const char *str);\fR +.br +\fBint mvinsnstr(int y, int x, const char *str, int n);\fR +.br +\fBint mvwinsstr(WINDOW *win, int y, int x, const char *str);\fR +.br +\fBint mvwinsnstr(WINDOW *win, int y, int x, const char *str, int n);\fR +.br +.SH DESCRIPTION +These routines insert a character string +(as many characters as will fit on the line) +before the character under the cursor. +All characters to the right of the cursor are shifted right +with the possibility of the rightmost characters on the line being lost. +The cursor position does not change +(after moving to \fIy\fR, \fIx\fR, if specified). +The functions with \fIn\fR as the last argument +insert a leading substring of at most \fIn\fR characters. +If \fIn\fR<=0, then the entire string is inserted. +.PP +Special characters are handled as in \fBaddch\fP. +.SH RETURN VALUE +All routines that return an integer return \fBERR\fR upon failure and OK (SVr4 +specifies only "an integer value other than \fBERR\fR") upon successful +completion, unless otherwise noted in the preceding routine descriptions. +.PP +X/Open defines no error conditions. +In this implementation, +if the window parameter is null or the str parameter is null, +an error is returned. +.SH NOTES +Note that all but \fBwinsnstr\fR may be macros. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4, which adds +const qualifiers to the arguments. +.LP +The Single Unix Specification, Version 2 states that +\fBinsnstr\fP and \fBwinsnstr\fP perform wrapping. +This is probably an error, since it makes this group of functions inconsistent. +Also, no implementation of curses documents this inconsistency. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_util\fR(3X), +\fBcurs_clear\fR(3X), +\fBcurs_inch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_instr.3x b/man/curs_instr.3x new file mode 100644 index 000000000000..a93de2728322 --- /dev/null +++ b/man/curs_instr.3x @@ -0,0 +1,89 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_instr.3x,v 1.13 2006/02/25 21:49:19 tom Exp $ +.TH curs_instr 3X "" +.SH NAME +\fBinstr\fR, +\fBinnstr\fR, +\fBwinstr\fR, +\fBwinnstr\fR, +\fBmvinstr\fR, +\fBmvinnstr\fR, +\fBmvwinstr\fR, +\fBmvwinnstr\fR - get a string of characters from a \fBcurses\fR window +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint instr(char *str);\fR +.br +\fBint innstr(char *str, int n);\fR +.br +\fBint winstr(WINDOW *win, char *str);\fR +.br +\fBint winnstr(WINDOW *win, char *str, int n);\fR +.br +\fBint mvinstr(int y, int x, char *str);\fR +.br +\fBint mvinnstr(int y, int x, char *str, int n);\fR +.br +\fBint mvwinstr(WINDOW *win, int y, int x, char *str);\fR +.br +\fBint mvwinnstr(WINDOW *win, int y, int x, char *str, int n);\fR +.br +.SH DESCRIPTION +These routines return a string of characters in \fIstr\fR, extracted starting +at the current cursor position in the named window. +Attributes are stripped from the characters. The four +functions with \fIn\fR as the last argument return a leading substring at most +\fIn\fR characters long (exclusive of the trailing NUL). +.SH RETURN VALUE +All of the functions return \fBERR\fR upon failure, +or the number of characters actually read into the string. +.PP +X/Open defines no error conditions. +In this implementation, +if the window parameter is null or the str parameter is null, +a zero is returned. +.SH NOTES +Note that all routines except \fBwinnstr\fR may be macros. +.SH PORTABILITY +SVr4 does not +document whether a length limit includes or excludes the trailing NUL. +.PP +The ncurses library extends the XSI description by allowing a negative +value for \fIn\fR. +In this case, the functions return the string ending at the right margin. +.SH SEE ALSO +\fBcurses\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_inwstr.3x b/man/curs_inwstr.3x new file mode 100644 index 000000000000..990789cb9b32 --- /dev/null +++ b/man/curs_inwstr.3x @@ -0,0 +1,93 @@ +.\"*************************************************************************** +.\" Copyright (c) 2002-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_inwstr.3x,v 1.5 2006/02/25 21:20:20 tom Exp $ +.TH curs_inwstr 3X "" +.SH NAME +\fBinwstr\fR, +\fBinnwstr\fR, +\fBwinwstr\fR, +\fBwinnwstr\fR, +\fBmvinwstr\fR, +\fBmvinnwstr\fR, +\fBmvwinwstr\fR, +\fBmvwinnwstr\fR \- get a string of \fBwchar_t\fR characters from a curses window +.SH SYNOPSIS +.nf +\fB#include <curses.h> \fR +.sp +\fBint inwstr(\fR\fBwchar_t *\fR\fIstr\fR\fB);\fR +.br +\fBint innwstr(\fR\fBwchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint winwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIstr\fR\fB);\fR +.br +\fBint winnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, wchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvinwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB);\fR +.br +\fBint mvinnwstr(\fR\fBint \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR +.br +\fBint mvwinwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB);\fR +.br +\fBint mvwinnwstr(\fR\fBWINDOW *\fR\fIwin\fR\fB, int \fR\fIy\fR\fB, int \fR\fIx\fR\fB, wchar_t *\fR\fIstr\fR\fB, int \fR\fIn\fR\fB);\fR +.fi +.SH DESCRIPTION +These routines return a string of \fBwchar_t\fR characters in \fIwstr\fR, +extracted starting at the current cursor position in the named window. +Attributes are stripped from the characters. +The four functions with \fIn\fR as the last argument return a leading substring at most +\fIn\fR bytes long (exclusive of the trailing NUL). +Transfer stops at the end of the current line, or when \fIn\fR bytes have +been stored at the location referenced by \fIwstr\fR. +.PP +If the size \fIn\fR is not large enough to store a complete character, +an error is generated. +.SH NOTES +Note that all routines except +\fBwinnwstr\fR +may be macros. +.SH RETURN VALUES +All routines return +\fBERR\fR +upon failure. Upon +successful completion, the *\fBinwstr\fR +routines return +\fBOK\fR, and the *\fBinnwstr\fR +routines return the +number of characters read into the string. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_instr\fR(3X), +\fBcurs_in_wchstr\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x new file mode 100644 index 000000000000..9403973840e4 --- /dev/null +++ b/man/curs_kernel.3x @@ -0,0 +1,186 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2001,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_kernel.3x,v 1.15 2005/05/15 16:18:13 tom Exp $ +.TH curs_kernel 3X "" +.na +.hy 0 +.SH NAME +\fBdef_prog_mode\fR, +\fBdef_shell_mode\fR, +\fBreset_prog_mode\fR, +\fBreset_shell_mode\fR, +\fBresetty\fR, +\fBsavetty\fR, +\fBgetsyx\fR, +\fBsetsyx\fR, +\fBripoffline\fR, +\fBcurs_set\fR, +\fBnapms\fR - low-level \fBcurses\fR routines +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint def_prog_mode(void);\fR +.br +\fBint def_shell_mode(void);\fR +.br +\fBint reset_prog_mode(void);\fR +.br +\fBint reset_shell_mode(void);\fR +.br +\fBint resetty(void);\fR +.br +\fBint savetty(void);\fR +.br +\fBvoid getsyx(int y, int x);\fR +.br +\fBvoid setsyx(int y, int x);\fR +.br +\fBint ripoffline(int line, int (*init)(WINDOW *, int));\fR +.br +\fBint curs_set(int visibility);\fR +.br +\fBint napms(int ms);\fR +.br +.SH DESCRIPTION +The following routines give low-level access to various \fBcurses\fR +capabilities. Theses routines typically are used inside library +routines. +.PP +The \fBdef_prog_mode\fR and \fBdef_shell_mode\fR routines save the +current terminal modes as the "program" (in \fBcurses\fR) or "shell" +(not in \fBcurses\fR) state for use by the \fBreset_prog_mode\fR and +\fBreset_shell_mode\fR routines. This is done automatically by +\fBinitscr\fR. There is one such save area for each screen context +allocated by \fBnewterm()\fR. +.PP +The \fBreset_prog_mode\fR and \fBreset_shell_mode\fR routines restore +the terminal to "program" (in \fBcurses\fR) or "shell" (out of +\fBcurses\fR) state. These are done automatically by \fBendwin\fR +and, after an \fBendwin\fR, by \fBdoupdate\fR, so they normally are +not called. +.PP +The \fBresetty\fR and \fBsavetty\fR routines save and restore the +state of the terminal modes. \fBsavetty\fR saves the current state in +a buffer and \fBresetty\fR restores the state to what it was at the +last call to \fBsavetty\fR. +.PP +The \fBgetsyx\fR routine returns the current coordinates of the virtual screen +cursor in \fIy\fR and \fIx\fR. If \fBleaveok\fR is currently \fBTRUE\fR, then +\fB-1\fR,\fB-1\fR is returned. If lines have been removed from the top of the +screen, using \fBripoffline\fR, \fIy\fR and \fIx\fR include these lines; +therefore, \fIy\fR and \fIx\fR should be used only as arguments for +\fBsetsyx\fR. +.PP +The \fBsetsyx\fR routine sets the virtual screen cursor to +\fIy\fR, \fIx\fR. If \fIy\fR and \fIx\fR are both \fB-1\fR, then +\fBleaveok\fR is set. The two routines \fBgetsyx\fR and \fBsetsyx\fR +are designed to be used by a library routine, which manipulates +\fBcurses\fR windows but does not want to change the current position +of the program's cursor. The library routine would call \fBgetsyx\fR +at the beginning, do its manipulation of its own windows, do a +\fBwnoutrefresh\fR on its windows, call \fBsetsyx\fR, and then call +\fBdoupdate\fR. +.PP +The \fBripoffline\fR routine provides access to the same facility that +\fBslk_init\fR [see \fBcurs_slk\fR(3X)] uses to reduce the size of the +screen. \fBripoffline\fR must be called before \fBinitscr\fR or +\fBnewterm\fR is called. If \fIline\fR is positive, a line is removed +from the top of \fBstdscr\fR; if \fIline\fR is negative, a line is +removed from the bottom. When this is done inside \fBinitscr\fR, the +routine \fBinit\fR (supplied by the user) is called with two +arguments: a window pointer to the one-line window that has been +allocated and an integer with the number of columns in the window. +Inside this initialization routine, the integer variables \fBLINES\fR +and \fBCOLS\fR (defined in \fB<curses.h>\fR) are not guaranteed to be +accurate and \fBwrefresh\fR or \fBdoupdate\fR must not be called. It +is allowable to call \fBwnoutrefresh\fR during the initialization +routine. +.PP +\fBripoffline\fR can be called up to five times before calling \fBinitscr\fR or +\fBnewterm\fR. +.PP +The \fBcurs_set\fR routine sets the cursor state is set to invisible, +normal, or very visible for \fBvisibility\fR equal to \fB0\fR, +\fB1\fR, or \fB2\fR respectively. If the terminal supports the +\fIvisibility\fR requested, the previous \fIcursor\fR state is +returned; otherwise, \fBERR\fR is returned. +.PP +The \fBnapms\fR routine is used to sleep for \fIms\fR milliseconds. +.SH RETURN VALUE +Except for \fBcurs_set\fR, these routines always return \fBOK\fR. +.PP +\fBcurs_set\fR +returns the previous cursor state, or \fBERR\fR if the +requested \fIvisibility\fR is not supported. +.PP +X/Open defines no error conditions. +In this implementation +.RS +.TP 5 +\fBdef_prog_mode\fR, \fBdef_shell_mode\fR, \fBreset_prog_mode\fR, \fBreset_shell_mode\fR +return an error +if the terminal was not initialized, or +if the I/O call to obtain the terminal settings fails. +.TP 5 +\fBripoffline\fP +returns an error if the maximum number of ripped-off lines +exceeds the maximum (NRIPS = 5). +.RE +.SH NOTES +Note that \fBgetsyx\fR is a macro, so \fB&\fR is not necessary before +the variables \fIy\fR and \fIx\fR. +.PP +Older SVr4 man pages warn that the return value of \fBcurs_set\fR "is currently +incorrect". This implementation gets it right, but it may be unwise to count +on the correctness of the return value anywhere else. +.PP +Both ncurses and SVr4 will call \fBcurs_set\fR in \fBendwin\fR +if \fBcurs_set\fR +has been called to make the cursor other than normal, i.e., either +invisible or very visible. +There is no way for ncurses to determine the initial cursor state to +restore that. +.SH PORTABILITY +The functions \fBsetsyx\fR and \fBgetsyx\fR are not described in the XSI +Curses standard, Issue 4. All other functions are as described in XSI Curses. +.PP +The SVr4 documentation describes \fBsetsyx\fR and \fBgetsyx\fR as having return +type int. This is misleading, as they are macros with no documented semantics +for the return value. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_outopts\fR(3X), \fBcurs_refresh\fR(3X), +\fBcurs_scr_dump\fR(3X), \fBcurs_slk\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_legacy.3x b/man/curs_legacy.3x new file mode 100644 index 000000000000..251ae496b851 --- /dev/null +++ b/man/curs_legacy.3x @@ -0,0 +1,93 @@ +.\"*************************************************************************** +.\" Copyright (c) 2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_legacy.3x,v 1.1 2007/04/07 23:54:29 tom Exp $ +.TH curs_legacy 3X "" +.SH NAME +\fBgetbegx\fR, +\fBgetbegy\fR, +\fBgetcurx\fR, +\fBgetcury\fR, +\fBgetmaxx\fR, +\fBgetmaxy\fR, +\fBgetparx\fR, +\fBgetpary\fR - get \fBcurses\fR cursor and window coordinates +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint getbegx(WINDOW *win);\fR +.br +\fBint getbegy(WINDOW *win);\fR +.br +\fBint getcurx(WINDOW *win);\fR +.br +\fBint getcury(WINDOW *win);\fR +.br +\fBint getmaxx(WINDOW *win);\fR +.br +\fBint getmaxy(WINDOW *win);\fR +.br +\fBint getparx(WINDOW *win);\fR +.br +\fBint getpary(WINDOW *win);\fR +.br +.SH DESCRIPTION +The \fBgetbegy\fR and \fBgetbegx\fR functions return the same +data as \fBgetbegyx\fR. +.PP +The \fBgetcury\fR and \fBgetcurx\fR functions return the same +data as \fBgetyx\fR. +.PP +The \fBgetmaxy\fR and \fBgetmaxx\fR functions return the same +data as \fBgetmaxyx\fR. +.PP +The \fBgetpary\fR and \fBgetparx\fR functions return the same +data as \fBgetparyx\fR. +.SH RETURN VALUE +These functions return an integer, +or ERR if the window parameter is null. +.SH NOTES +All of these interfaces are provided as macros and functions. +The macros are suppressed (and only the functions provided) +when \fBNCURSES_OPAQUE\fR is defined. +The standard forms such as \fBgetyx\fP must be implemented as macros, +and (in this implementation) are defined in terms of the functions +described here, +to avoid reliance on internal details of the WINDOW structure. +.SH PORTABILITY +These functions were supported on Version 7, BSD or System V implementations. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_getyx\fR(3X), +\fBcurs_opaque\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x new file mode 100644 index 000000000000..23f9f9c6d7d0 --- /dev/null +++ b/man/curs_mouse.3x @@ -0,0 +1,310 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_mouse.3x,v 1.30 2006/12/30 23:43:34 tom Exp $ +.TH curs_mouse 3X "" +.na +.hy 0 +.SH NAME +\fBgetmouse\fR, \fBungetmouse\fR, +\fBmousemask\fR, \fBwenclose\fR, +\fBmouse_trafo\fR, \fBwmouse_trafo\fR, +\fBmouseinterval\fR - mouse interface through curses +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include <curses.h> +.PP +\fBtypedef unsigned long mmask_t; +.PP +typedef struct +{ + short id; \fI/* ID to distinguish multiple devices */\fB + int x, y, z; \fI/* event coordinates */\fB + mmask_t bstate; \fI/* button state bits */\fB +} +MEVENT;\fR +.fi +.br +\fBint getmouse(MEVENT *event);\fR +.br +\fBint ungetmouse(MEVENT *event);\fR +.br +\fBmmask_t mousemask(mmask_t newmask, mmask_t *oldmask);\fR +.br +\fBbool wenclose(const WINDOW *win, int y, int x);\fR +.br +\fBbool mouse_trafo(int* pY, int* pX, bool to_screen);\fR +.br +\fBbool wmouse_trafo(const WINDOW* win, int* pY, int* pX,\fR +.br + \fBbool to_screen);\fR +.br +\fBint mouseinterval(int erval);\fR +.br +.SH DESCRIPTION +These functions provide an interface to mouse events from +\fBncurses\fR(3X). +Mouse events are represented by \fBKEY_MOUSE\fR +pseudo-key values in the \fBwgetch\fR input stream. +.PP +To make mouse events visible, use the \fBmousemask\fR function. +This will set +the mouse events to be reported. +By default, no mouse events are reported. +The function will return a mask to indicate which of the specified mouse events +can be reported; on complete failure it returns 0. +If oldmask is non-NULL, +this function fills the indicated location with the previous value of the given +window's mouse event mask. +.PP +As a side effect, setting a zero mousemask may turn off the mouse pointer; +setting a nonzero mask may turn it on. +Whether this happens is device-dependent. +.PP +Here are the mouse event type masks which may be defined: +.PP +.TS +l l +_ _ +l l. +\fIName\fR \fIDescription\fR +BUTTON1_PRESSED mouse button 1 down +BUTTON1_RELEASED mouse button 1 up +BUTTON1_CLICKED mouse button 1 clicked +BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked +BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked +_ +BUTTON2_PRESSED mouse button 2 down +BUTTON2_RELEASED mouse button 2 up +BUTTON2_CLICKED mouse button 2 clicked +BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked +BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked +_ +BUTTON3_PRESSED mouse button 3 down +BUTTON3_RELEASED mouse button 3 up +BUTTON3_CLICKED mouse button 3 clicked +BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked +BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked +_ +BUTTON4_PRESSED mouse button 4 down +BUTTON4_RELEASED mouse button 4 up +BUTTON4_CLICKED mouse button 4 clicked +BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked +BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked +_ +BUTTON5_PRESSED mouse button 5 down +BUTTON5_RELEASED mouse button 5 up +BUTTON5_CLICKED mouse button 5 clicked +BUTTON5_DOUBLE_CLICKED mouse button 5 double clicked +BUTTON5_TRIPLE_CLICKED mouse button 5 triple clicked +_ +BUTTON_SHIFT shift was down during button state change +BUTTON_CTRL control was down during button state change +BUTTON_ALT alt was down during button state change +ALL_MOUSE_EVENTS report all button state changes +REPORT_MOUSE_POSITION report mouse movement +_ +.TE +.PP +Once a class of mouse events have been made visible in a window, +calling the \fBwgetch\fR function on that window may return +\fBKEY_MOUSE\fR as an indicator that a mouse event has been queued. +To read the event data and pop the event off the queue, call +\fBgetmouse\fR. +This function will return \fBOK\fR if a mouse event +is actually visible in the given window, \fBERR\fR otherwise. +When \fBgetmouse\fR returns \fBOK\fR, the data deposited as y and +x in the event structure coordinates will be screen-relative character-cell +coordinates. +The returned state mask will have exactly one bit set to +indicate the event type. +.PP +The \fBungetmouse\fR function behaves analogously to \fBungetch\fR. +It pushes +a \fBKEY_MOUSE\fR event onto the input queue, and associates with that event +the given state data and screen-relative character-cell coordinates. +.PP +The \fBwenclose\fR function tests whether a given pair of screen-relative +character-cell coordinates is enclosed by a given window, returning TRUE +if it is and FALSE otherwise. +It is useful for determining what subset of +the screen windows enclose the location of a mouse event. +.PP +The \fBwmouse_trafo\fR function transforms a given pair of coordinates +from stdscr-relative coordinates +to coordinates relative to the given window or vice versa. +Please remember, that stdscr-relative coordinates are not always identical +to window-relative coordinates due to the mechanism to reserve lines on top +or bottom of the screen for other purposes +(see the \fBripoffline()\fP and \fBslk_init\fR calls, for example). +If the parameter \fBto_screen\fR is \fBTRUE\fR, the pointers +\fBpY, pX\fR must reference the coordinates of a location +inside the window \fBwin\fR. +They are converted to window-relative coordinates and returned +through the pointers. +If the conversion was successful, the function returns \fBTRUE\fR. +If one of the parameters was NULL or the location is +not inside the window, \fBFALSE\fR is returned. +If \fBto_screen\fR is +\fBFALSE\fR, the pointers \fBpY, pX\fR must reference window-relative +coordinates. +They are converted to stdscr-relative coordinates if the +window \fBwin\fR encloses this point. +In this case the function returns \fBTRUE\fR. +If one of the parameters is NULL or the point is not inside the +window, \fBFALSE\fR is returned. +Please notice, that the referenced coordinates +are only replaced by the converted coordinates if the transformation was +successful. +.PP +The \fBmouse_trafo\fR function performs the same translation +as \fBwmouse_trafo\fR, +using stdscr for \fBwin\fR. +.PP +The \fBmouseinterval\fR 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 \fBmouseinterval(0)\fR to disable click resolution. +This function returns the previous interval value. +Use \fBmouseinterval(-1)\fR to obtain the interval without altering it. +The default is one sixth of a second. +.PP +Note that mouse events will be ignored when input is in cooked mode, and will +cause an error beep when cooked mode is being simulated in a window by a +function such as \fBgetstr\fR that expects a linefeed for input-loop +termination. +.SH RETURN VALUE +\fBgetmouse\fR and \fBungetmouse\fR +return the integer \fBERR\fR upon failure or \fBOK\fR +upon successful completion. +.RS +.TP 5 +\fBgetmouse\fP +returns an error. +If no mouse driver was initialized, or +if the mask parameter is zero, +.TP 5 +\fBungetmouse\fP +returns an error if the FIFO is full. +.RE +.PP +\fBmousemask\fR +returns the mask of reportable events. +.PP +\fBmouseinterval\fR +returns the previous interval value, unless +the terminal was not initialized. +In that case, it returns the maximum interval value (166). +.PP +\fBwenclose\fR and \fBwmouse_trafo\fR +are boolean functions returning \fBTRUE\fR or \fBFALSE\fR depending +on their test result. +.SH PORTABILITY +These calls were designed for \fBncurses\fR(3X), and are not found in SVr4 +curses, 4.4BSD curses, or any other previous version of curses. +.PP +The feature macro \fBNCURSES_MOUSE_VERSION\fR is provided so the preprocessor +can be used to test whether these features are present. +If the interface is changed, the value of \fBNCURSES_MOUSE_VERSION\fR will be +incremented. +These values for \fBNCURSES_MOUSE_VERSION\fR may be +specified when configuring ncurses: +.RS +.TP 3 +1 +has definitions for reserved events. +The mask uses 28 bits. +.TP 3 +2 +adds definitions for button 5, +removes the definitions for reserved events. +The mask uses 29 bits. +.RE +.PP +The order of the \fBMEVENT\fR structure members is not guaranteed. +Additional fields may be added to the structure in the future. +.PP +Under \fBncurses\fR(3X), these calls are implemented using either +xterm's built-in mouse-tracking API or +platform-specific drivers including +.RS +Alessandro Rubini's gpm server. +.br +FreeBSD sysmouse +.br +OS/2 EMX +.RE +If you are using an unsupported configuration, +mouse events will not be visible to +\fBncurses\fR(3X) (and the \fBmousemask\fR function will always +return \fB0\fR). +.PP +If the terminfo entry contains a \fBXM\fR string, +this is used in the xterm mouse driver to control the +way the terminal is initialized for mouse operation. +The default, if \fBXM\fR is not found, +corresponds to private mode 1000 of xterm: +.RS +\\E[?1000%?%p1%{1}%=%th%el%; +.RE +The z member in the event structure is not presently used. +It is intended +for use with touch screens (which may be pressure-sensitive) or with +3D-mice/trackballs/power gloves. +.SH BUGS +Mouse events under xterm will not in fact be ignored during cooked mode, +if they have been enabled by \fBmousemask\fR. +Instead, the xterm mouse +report sequence will appear in the string read. +.PP +Mouse events under xterm will not be detected correctly in a window with +its keypad bit off, since they are interpreted as a variety of function key. +Your terminfo description should have \fBkmous\fR set to "\\E[M" +(the beginning of the response from xterm for mouse clicks). +Other values for \fBkmous\fR are permitted, +but under the same assumption, +i.e., it is the beginning of the response. +.PP +Because there are no standard terminal responses that would serve to identify +terminals which support the xterm mouse protocol, \fBncurses\fR assumes that +if your $TERM environment variable contains "xterm", +or \fBkmous\fR is defined in +the terminal description, then the terminal may send mouse events. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_kernel\fR(3X), +\fBcurs_slk\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_move.3x b/man/curs_move.3x new file mode 100644 index 000000000000..804637792be5 --- /dev/null +++ b/man/curs_move.3x @@ -0,0 +1,69 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_move.3x,v 1.12 2006/02/25 21:49:19 tom Exp $ +.TH curs_move 3X "" +.na +.hy 0 +.SH NAME +\fBmove\fR, +\fBwmove\fR - move \fBcurses\fR window cursor +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint move(int y, int x);\fR +.br +\fBint wmove(WINDOW *win, int y, int x);\fR +.br +.SH DESCRIPTION +These routines move the cursor associated with the window to line \fIy\fR and +column \fIx\fR. This routine does not move the physical cursor of the terminal +until \fBrefresh\fR is called. The position specified is relative to the upper +left-hand corner of the window, which is (0,0). +.SH RETURN VALUE +These routines return \fBERR\fR upon failure and OK (SVr4 +specifies only "an integer value other than \fBERR\fR") upon successful +completion. +.PP +Specifically, they return an error +if the window pointer is null, or +if the position is outside the window. +.SH NOTES +Note that \fBmove\fR may be a macro. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_refresh\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_opaque.3x b/man/curs_opaque.3x new file mode 100644 index 000000000000..6c9cfaa18a35 --- /dev/null +++ b/man/curs_opaque.3x @@ -0,0 +1,133 @@ +.\"*************************************************************************** +.\" Copyright (c) 2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_opaque.3x,v 1.6 2007/09/08 18:49:13 tom Exp $ +.TH curs_opaque 3X "" +.na +.hy 0 +.SH NAME +\fBis_cleared\fR, +\fBis_idlok\fR, +\fBis_idcok\fR, +\fBis_immedok\fR, +\fBis_keypad\fR, +\fBis_leaveok\fR, +\fBis_nodelay\fR, +\fBis_timeout\fR, +\fBis_scrollok\fR, +\fBis_syncok\fR - \fBcurses\fR window properties +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBbool is_cleared(const WINDOW *win);\fR +.br +\fBbool is_idcok(const WINDOW *win);\fR +.br +\fBbool is_idlok(const WINDOW *win);\fR +.br +\fBbool is_immedok(const WINDOW *win);\fR +.br +\fBbool is_keypad(const WINDOW *win);\fR +.br +\fBbool is_leaveok(const WINDOW *win);\fR +.br +\fBbool is_nodelay(const WINDOW *win);\fR +.br +\fBbool is_notimeout(const WINDOW *win);\fR +.br +\fBbool is_scrollok(const WINDOW *win);\fR +.br +\fBbool is_syncok(const WINDOW *win);\fR +.br +\fBWINDOW * wgetparent(const WINDOW *win);\fR +.br +\fBint wgetscrreg(const WINDOW *win, int *top, int *bottom);\fR +.br +.SH DESCRIPTION +This implementation provides functions which return properties +set in the WINDOW structure, allowing it to be ``opaque'' if +the symbol \fBNCURSES_OPAQUE\fR is defined: +.TP 5 +\fBis_cleared\fR +returns the value set in \fBclearok\fR +.TP 5 +\fBis_idcok\fR +returns the value set in \fBidcok\fR +.TP 5 +\fBis_idlok\fR +returns the value set in \fBidlok\fR +.TP 5 +\fBis_immedok\fR +returns the value set in \fBimmedok\fR +.TP 5 +\fBis_keypad\fR +returns the value set in \fBkeypad\fR +.TP 5 +\fBis_leaveok\fR +returns the value set in \fBleaveok\fR +.TP 5 +\fBis_nodelay\fR +returns the value set in \fBnodelay\fR +.TP 5 +\fBis_notimeout\fR +returns the value set in \fBnotimeout\fR +.TP 5 +\fBis_scrollok\fR +returns the value set in \fBscrollok\fR +.TP 5 +\fBis_syncok\fR +returns the value set in \fBsyncok\fR +.TP 5 +\fBwgetparent\fR +returns the parent WINDOW pointer for subwindows, +or NULL for windows having no parent. +.TP 5 +\fBwgetscrreg\fR +returns the top and bottom rows for the scrolling margin as set in \fBwsetscrreg\fP. +.SH RETURN VALUE +These functions all return TRUE or FALSE, except as noted. +.SH NOTES +Both a macro and a function are provided for each name. +.SH PORTABILITY +These 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. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_inopts\fR(3X), +\fBcurs_outopts\fR(3X), +\fBcurs_window\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_outopts.3x b/man/curs_outopts.3x new file mode 100644 index 000000000000..3fd437a312bb --- /dev/null +++ b/man/curs_outopts.3x @@ -0,0 +1,222 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_outopts.3x,v 1.21 2007/06/02 20:40:07 tom Exp $ +.TH curs_outopts 3X "" +.na +.hy 0 +.SH NAME +\fBclearok\fR, +\fBidlok\fR, +\fBidcok\fR, +\fBimmedok\fR, +\fBleaveok\fR, +\fBsetscrreg\fR, +\fBwsetscrreg\fR, +\fBscrollok\fR, +\fBnl\fR, +\fBnonl\fR - \fBcurses\fR output options +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint clearok(WINDOW *win, bool bf);\fR +.br +\fBint idlok(WINDOW *win, bool bf);\fR +.br +\fBvoid idcok(WINDOW *win, bool bf);\fR +.br +\fBvoid immedok(WINDOW *win, bool bf);\fR +.br +\fBint leaveok(WINDOW *win, bool bf);\fR +.br +\fBint setscrreg(int top, int bot);\fR +.br +\fBint wsetscrreg(WINDOW *win, int top, int bot);\fR +.br +\fBint scrollok(WINDOW *win, bool bf);\fR +.br +\fBint nl(void);\fR +.br +\fBint nonl(void);\fR +.br +.SH DESCRIPTION +These routines set options that change the style of output within +\fBcurses\fR. +All options are initially \fBFALSE\fR, unless otherwise stated. +It is not necessary to turn these options off before calling \fBendwin\fR. +.PP +If \fBclearok\fR is called with \fBTRUE\fR as argument, the next +call to \fBwrefresh\fR with this window will clear the screen completely and +redraw the entire screen from scratch. +This is useful when the contents of the +screen are uncertain, or in some cases for a more pleasing visual effect. +If +the \fIwin\fR argument to \fBclearok\fR is the global variable \fBcurscr\fR, +the next call to \fBwrefresh\fR with any window causes the screen to be cleared +and repainted from scratch. +.PP +If \fBidlok\fR is called with \fBTRUE\fR as second argument, \fBcurses\fR +considers using the hardware insert/delete line feature of terminals so +equipped. +Calling \fBidlok\fR with \fBFALSE\fR as second argument disables use +of line insertion and deletion. +This option should be enabled only if the +application needs insert/delete line, for example, for a screen editor. +It is +disabled by default because insert/delete line tends to be visually annoying +when used in applications where it is not really needed. +If insert/delete line +cannot be used, \fBcurses\fR redraws the changed portions of all lines. +.PP +If \fBidcok\fR is called with \fBFALSE\fR as second argument, \fBcurses\fR +no longer considers using the hardware insert/delete character feature of +terminals so equipped. +Use of character insert/delete is enabled by default. +Calling \fBidcok\fR with \fBTRUE\fR as second argument re-enables use +of character insertion and deletion. +.PP +If \fBimmedok\fR is called with \fBTRUE as argument\fR, any change +in the window image, such as the ones caused by \fBwaddch, wclrtobot, wscrl\fR, +etc., automatically cause a call to \fBwrefresh\fR. +However, it may +degrade performance considerably, due to repeated calls to \fBwrefresh\fR. +It is disabled by default. +.PP +Normally, the hardware cursor is left at the location of the window cursor +being refreshed. +The \fBleaveok\fR option allows the cursor to be left +wherever the update happens to leave it. +It is useful for applications where +the cursor is not used, since it reduces the need for cursor motions. +.PP +The \fBsetscrreg\fR and \fBwsetscrreg\fR routines allow the application +programmer to set a software scrolling region in a window. +\fItop\fR and +\fIbot\fR are the line numbers of the top and bottom margin of the scrolling +region. +(Line 0 is the top line of the window.) If this option and +\fBscrollok\fR 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. +(Note that this +has nothing to do with the use of a physical scrolling region capability in the +terminal, like that in the VT100. +If \fBidlok\fR is enabled and the terminal +has either a scrolling region or insert/delete line capability, they will +probably be used by the output routines.) +.PP +The \fBscrollok\fR option controls what happens when the cursor of a window is +moved off the edge of the window or scrolling region, either as a result of a +newline action on the bottom line, or typing the last character of the last +line. +If disabled, (\fIbf\fR is \fBFALSE\fR), the cursor is left on the bottom +line. +If enabled, (\fIbf\fR is \fBTRUE\fR), the window is scrolled up one line +(Note that to get the physical scrolling effect on the terminal, it is +also necessary to call \fBidlok\fR). +.PP +The \fBnl\fR and \fBnonl\fR routines control whether the underlying display +device translates the return key into newline on input, and whether it +translates newline into return and line-feed on output (in either case, the +call \fBaddch('\\n')\fR does the equivalent of return and line feed on the +virtual screen). +Initially, these translations do occur. +If you disable them +using \fBnonl\fR, \fBcurses\fR will be able to make better use of the line-feed +capability, resulting in faster cursor motion. +Also, \fBcurses\fR will then be +able to detect the return key. +.SH RETURN VALUE +The functions \fBsetscrreg\fR and \fBwsetscrreg\fR return \fBOK\fR upon success +and \fBERR\fR upon failure. +All other routines that return an integer always +return \fBOK\fR. +.PP +X/Open does not define any error conditions. +.PP +In this implementation, those functions that have a window pointer +will return an error if the window pointer is null. +.RS +.TP 5 +.B wclrtoeol +returns an error +if the cursor position is about to wrap. +.TP 5 +.B wsetscrreg +returns an error if the scrolling region limits extend outside the window. +.RE +.PP +X/Open does not define any error conditions. +This implementation returns an error +if the window pointer is null. +.SH PORTABILITY +These functions are described in the XSI Curses standard, Issue 4. +.PP +The XSI Curses standard is ambiguous on the question of whether \fBraw\fR() +should disable the CRLF translations controlled by \fBnl\fR() and \fBnonl\fR(). +BSD curses did turn off these translations; AT&T curses (at least as late as +SVr1) did not. +We choose to do so, on the theory that a programmer requesting +raw input wants a clean (ideally 8-bit clean) connection that the operating +system will not alter. +.PP +Some historic curses implementations had, as an undocumented feature, the +ability to do the equivalent of \fBclearok(..., 1)\fR by saying +\fBtouchwin(stdscr)\fR or \fBclear(stdscr)\fR. +This will not work under +ncurses. +.PP +Earlier System V curses implementations specified that with \fBscrollok\fR +enabled, any window modification triggering a scroll also forced a physical +refresh. +XSI Curses does not require this, and \fBncurses\fR avoids doing +it to perform better vertical-motion optimization at \fBwrefresh\fR +time. +.PP +The XSI Curses standard does not mention that the cursor should be +made invisible as a side-effect of \fBleaveok\fR. +SVr4 curses documentation does this, but the code does not. +Use \fBcurs_set\fR to make the cursor invisible. +.SH NOTES +Note that \fBclearok\fR, \fBleaveok\fR, \fBscrollok\fR, \fBidcok\fR, \fBnl\fR, +\fBnonl\fR and \fBsetscrreg\fR may be macros. +.PP +The \fBimmedok\fR routine is useful for windows that are used as terminal +emulators. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_addch\fR(3X), \fBcurs_clear\fR(3X), +\fBcurs_initscr\fR(3X), \fBcurs_scroll\fR(3X), \fBcurs_refresh\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_overlay.3x b/man/curs_overlay.3x new file mode 100644 index 000000000000..066c3a4a50f6 --- /dev/null +++ b/man/curs_overlay.3x @@ -0,0 +1,87 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_overlay.3x,v 1.14 2006/02/25 21:49:19 tom Exp $ +.TH curs_overlay 3X "" +.na +.hy 0 +.SH NAME +\fBoverlay\fR, +\fBoverwrite\fR, +\fBcopywin\fR - overlay and manipulate overlapped \fBcurses\fR windows +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint overlay(const WINDOW *srcwin, WINDOW *dstwin);\fR +.br +\fBint overwrite(const WINDOW *srcwin, WINDOW *dstwin);\fR +.br +\fBint copywin(const WINDOW *srcwin, WINDOW *dstwin, int sminrow,\fR + \fBint smincol, int dminrow, int dmincol, int dmaxrow,\fR + \fBint dmaxcol, int overlay);\fR +.SH DESCRIPTION +The \fBoverlay\fR and \fBoverwrite\fR routines overlay \fIsrcwin\fR on +top of \fIdstwin\fR. \fIscrwin\fR and \fIdstwin\fR are not required +to be the same size; only text where the two windows overlap is +copied. The difference is that \fBoverlay\fR is non-destructive +(blanks are not copied) whereas \fBoverwrite\fR is destructive. +.PP +The \fBcopywin\fR routine provides a finer granularity of control over the +\fBoverlay\fR and \fBoverwrite\fR routines. Like in the \fBprefresh\fR +routine, a rectangle is specified in the destination window, (\fIdminrow\fR, +\fIdmincol\fR) and (\fIdmaxrow\fR, \fIdmaxcol\fR), and the upper-left-corner +coordinates of the source window, (\fIsminrow\fR, \fIsmincol\fR). If the +argument \fIoverlay\fR is \fBtrue\fR, then copying is non-destructive, as in +\fBoverlay\fR. +.SH RETURN VALUE +Routines that return an integer return \fBERR\fR upon failure, and \fBOK\fR +(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful +completion. +.PP +X/Open defines no error conditions. +In this implementation, +\fBcopywin\fP, +\fBoverlay\fP and \fBoverwrite\fP return an error +if either of the window pointers are null, or +if some part of the window would be placed off-screen. +.SH NOTES +Note that \fBoverlay\fR and \fBoverwrite\fR may be macros. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions (adding the const +qualifiers). It further specifies their behavior in the presence of characters +with multibyte renditions (not yet supported in this implementation). +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_pad\fR(3X), \fBcurs_refresh\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_pad.3x b/man/curs_pad.3x new file mode 100644 index 000000000000..c7222074ebeb --- /dev/null +++ b/man/curs_pad.3x @@ -0,0 +1,162 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2004,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_pad.3x,v 1.14 2005/05/15 16:18:43 tom Exp $ +.TH curs_pad 3X "" +.na +.hy 0 +.SH NAME +\fBnewpad\fR, +\fBsubpad\fR, +\fBprefresh\fR, +\fBpnoutrefresh\fR, +\fBpechochar\fR, +\fBpecho_wchar\fR - create and display \fBcurses\fR pads +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBWINDOW *newpad(int nlines, int ncols);\fR +.br +\fBWINDOW *subpad(WINDOW *orig, int nlines, int ncols,\fR + \fBint begin_y, int begin_x);\fR +.br +\fBint prefresh(WINDOW *pad, int pminrow, int pmincol,\fR + \fBint sminrow, int smincol, int smaxrow, int smaxcol);\fR +.br +\fBint pnoutrefresh(WINDOW *pad, int pminrow, int pmincol,\fR + \fBint sminrow, int smincol, int smaxrow, int smaxcol);\fR +.br +\fBint pechochar(WINDOW *pad, chtype ch);\fR +.br +\fBint pecho_wchar(WINDOW *pad, const cchar_t *wch);\fR +.SH DESCRIPTION +The \fBnewpad\fR routine creates and returns a pointer to a new pad data +structure with the given number of lines, \fInlines\fR, and columns, +\fIncols\fR. +A pad is like a window, except that it is not restricted by the +screen size, and is not necessarily associated with a particular part of the +screen. +Pads can be used when a large window is needed, and only a part of the +window will be on the screen at one time. +Automatic refreshes of pads +(e.g., from scrolling or echoing of input) do not occur. +It is not +legal to call \fBwrefresh\fR with a \fIpad\fR as an argument; the routines +\fBprefresh\fR or \fBpnoutrefresh\fR should be called instead. +Note that these +routines require additional parameters to specify the part of the pad to be +displayed and the location on the screen to be used for the display. +.PP +The \fBsubpad\fR routine creates and returns a pointer to a subwindow within a +pad with the given number of lines, \fInlines\fR, and columns, \fIncols\fR. +Unlike \fBsubwin\fR, which uses screen coordinates, the window is at position +(\fIbegin\fR_\fIx\fR\fB,\fR \fIbegin\fR_\fIy\fR) on the pad. +The window is +made in the middle of the window \fIorig\fR, so that changes made to one window +affect both windows. +During the use of this routine, it will often be +necessary to call \fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before +calling \fBprefresh\fR. +.PP +The \fBprefresh\fR and \fBpnoutrefresh\fR routines are analogous to +\fBwrefresh\fR and \fBwnoutrefresh\fR except that they relate to pads instead +of windows. +The additional parameters are needed to indicate what part of the +pad and screen are involved. +\fIpminrow\fR and \fIpmincol\fR specify the upper +left-hand corner of the rectangle to be displayed in the pad. +\fIsminrow\fR, +\fIsmincol\fR, \fIsmaxrow\fR, and \fIsmaxcol\fR specify the edges of the +rectangle to be displayed on the screen. +The lower right-hand corner of the +rectangle to be displayed in the pad is calculated from the screen coordinates, +since the rectangles must be the same size. +Both rectangles must be entirely +contained within their respective structures. +Negative values of +\fIpminrow\fR, \fIpmincol\fR, \fIsminrow\fR, or \fIsmincol\fR are treated as if +they were zero. +.PP +The \fBpechochar\fR routine is functionally equivalent to a call to \fBaddch\fR +followed by a call to \fBrefresh\fR, a call to \fBwaddch\fR followed by a call +to \fBwrefresh\fR, or a call to \fBwaddch\fR followed by a call to +\fBprefresh\fR. +The knowledge that only a single character is being output is +taken into consideration and, for non-control characters, a considerable +performance gain might be seen by using these routines instead of their +equivalents. +In the case of \fBpechochar\fR, the last location of the pad on +the screen is reused for the arguments to \fBprefresh\fR. +.PP +The \fBpecho_wchar\fR function is the analogous wide-character +form of \fBpechochar\fR. +It outputs one character to a pad and immediately refreshes the pad. +It does this by a call to \fBwadd_wch\fR followed by a call to \fBprefresh\fR. +.SH RETURN VALUE +Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR +(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful +completion. +.PP +Routines that return pointers return \fBNULL\fR on error, and set \fBerrno\fR +to \fBENOMEM\fR. +.PP +X/Open does not define any error conditions. +In this implementation +.RS +.TP 5 +\fBprefresh\fP and \fBpnoutrefresh\fP +return an error +if the window pointer is null, or +if the window is not really a pad or +if the area to refresh extends off-screen or +if the minimum coordinates are greater than the maximum. +.TP 5 +\fBpechochar\fP +returns an error +if the window is not really a pad, and the associated call +to \fBwechochar\fP returns an error. +.TP 5 +\fBpecho_wchar\fP +returns an error +if the window is not really a pad, and the associated call +to \fBwecho_wchar\fP returns an error. +.RE +.SH NOTES +Note that \fBpechochar\fR may be a macro. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_refresh\fR(3X), \fBcurs_touch\fR(3X), \fBcurs_addch\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_print.3x b/man/curs_print.3x new file mode 100644 index 000000000000..92b9ca2dafcc --- /dev/null +++ b/man/curs_print.3x @@ -0,0 +1,74 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_print.3x,v 1.8 2006/02/25 21:49:19 tom Exp $ +.TH curs_print 3X "" +.SH NAME +\fBmcprint\fR - ship binary data to printer +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint mcprint(char *data, int len);\fR +.SH DESCRIPTION +This function uses the \fBmc5p\fR or \fBmc4\fR and \fBmc5\fR capabilities, +if they are present, to ship given data to a printer attached to the terminal. +.PP +Note that the \fBmcprint\fR code has no way to do flow control with the printer +or to know how much buffering it has. Your application is responsible for +keeping the rate of writes to the printer below its continuous throughput rate +(typically about half of its nominal cps rating). Dot-matrix printers and +6-page-per-minute lasers can typically handle 80cps, so a good conservative +rule of thumb is to sleep for a second after shipping each 80-character line. +. +.SH RETURN VALUE +The \fBmcprint\fR function returns \fBERR\fR if the write operation aborted +for some reason. In this case, errno will contain either an error associated +with \fBwrite(2)\fR or one of the following: +.TP 5 +ENODEV +Capabilities for printer redirection do not exist. +.TP 5 +ENOMEM +Couldn't allocate sufficient memory to buffer the printer write. +.PP +When \fBmcprint\fR succeeds, it returns the number of characters actually +sent to the printer. +.SH PORTABILITY +The \fBmcprint\fR call was designed for \fBncurses\fR(3X), and is not found +in SVr4 curses, 4.4BSD curses, or any other previous version of curses. +.SH BUGS +Padding in the \fBmc5p\fR, \fBmc4\fR and \fBmc5\fR capabilities will not be +interpreted. +.SH SEE ALSO +\fBcurses\fR(3X)\fR +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_printw.3x b/man/curs_printw.3x new file mode 100644 index 000000000000..ead0f183dc09 --- /dev/null +++ b/man/curs_printw.3x @@ -0,0 +1,94 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_printw.3x,v 1.17 2006/12/24 16:05:17 tom Exp $ +.TH curs_printw 3X "" +.na +.hy 0 +.SH NAME +\fBprintw\fR, +\fBwprintw\fR, +\fBmvprintw\fR, +\fBmvwprintw\fR, +\fBvwprintw\fR, \fBvw_printw\fR - print formatted output in \fBcurses\fR windows +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint printw(const char *fmt, ...);\fR +.br +\fBint wprintw(WINDOW *win, const char *fmt, ...);\fR +.br +\fBint mvprintw(int y, int x, const char *fmt, ...);\fR +.br +\fBint mvwprintw(WINDOW *win, int y, int x, const char *fmt, ...);\fR +.br +\fBint vwprintw(WINDOW *win, const char *fmt, va_list varglist);\fR +.br +\fBint vw_printw(WINDOW *win, const char *fmt, va_list varglist);\fR +.br +.SH DESCRIPTION +The \fBprintw\fR, \fBwprintw\fR, \fBmvprintw\fR and \fBmvwprintw\fR +routines are analogous to \fBprintf\fR [see \fBprintf\fR(3)]. In +effect, the string that would be output by \fBprintf\fR is output +instead as though \fBwaddstr\fR were used on the given window. +.PP +The \fBvwprintw\fR and \fBwv_printw\fR routines are analogous +to \fBvprintf\fR [see \fBprintf\fR(3)] +and perform a \fBwprintw\fR using a variable argument list. +The third argument is a \fBva_list\fR, a pointer to a +list of arguments, as defined in \fB<stdarg.h>\fR. +.SH RETURN VALUE +Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR +(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful +completion. +.PP +X/Open defines no error conditions. +In this implementation, +an error may be returned if it cannot allocate enough memory for the +buffer used to format the results. +It will return an error if the window pointer is null. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. The function +\fBvwprintw\fR is marked TO BE WITHDRAWN, and is to be replaced by a function +\fBvw_printw\fR using the \fB<stdarg.h>\fR interface. +The Single Unix Specification, Version 2 states that +\fBvw_printw\fR is preferred to \fBvwprintw\fR since the latter requires +including \fB<varargs.h>\fR, which +cannot be used in the same file as \fB<stdarg.h>\fR. +This implementation uses \fB<stdarg.h>\fR for both, because that header +is included in \fB<curses.h\fR>. +.SH SEE ALSO +\fBcurses\fR(3X), \fBprintf\fR(3), \fBvprintf(3)\fR +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_refresh.3x b/man/curs_refresh.3x new file mode 100644 index 000000000000..5ce06903d83d --- /dev/null +++ b/man/curs_refresh.3x @@ -0,0 +1,144 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2001,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_refresh.3x,v 1.12 2005/05/15 16:18:49 tom Exp $ +.TH curs_refresh 3X "" +.na +.hy 0 +.SH NAME +\fBdoupdate\fR, +\fBredrawwin\fR, +\fBrefresh\fR, +\fBwnoutrefresh\fR, +\fBwredrawln\fR, +\fBwrefresh\fR - refresh \fBcurses\fR windows and lines +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint refresh(void);\fR +.br +\fBint wrefresh(WINDOW *win);\fR +.br +\fBint wnoutrefresh(WINDOW *win);\fR +.br +\fBint doupdate(void);\fR +.br +\fBint redrawwin(WINDOW *win);\fR +.br +\fBint wredrawln(WINDOW *win, int beg_line, int num_lines);\fR +.br +.SH DESCRIPTION +The \fBrefresh\fR and \fBwrefresh\fR routines (or \fBwnoutrefresh\fR and +\fBdoupdate\fR) must be called to get actual output to the terminal, as other +routines merely manipulate data structures. +The routine \fBwrefresh\fR copies +the named window to the physical terminal screen, taking into account what is +already there to do optimizations. +The \fBrefresh\fR routine is the +same, using \fBstdscr\fR as the default window. +Unless \fBleaveok\fR has been +enabled, the physical cursor of the terminal is left at the location of the +cursor for that window. +.PP +The \fBwnoutrefresh\fR and \fBdoupdate\fR routines allow multiple updates with +more efficiency than \fBwrefresh\fR alone. +In addition to all the window +structures, \fBcurses\fR keeps two data structures representing the terminal +screen: a physical screen, describing what is actually on the screen, and a +virtual screen, describing what the programmer wants to have on the screen. +.PP +The routine \fBwrefresh\fR works by first calling \fBwnoutrefresh\fR, which +copies the named window to the virtual screen, and then calling \fBdoupdate\fR, +which compares the virtual screen to the physical screen and does the actual +update. +If the programmer wishes to output several windows at once, a series +of calls to \fBwrefresh\fR results in alternating calls to \fBwnoutrefresh\fR +and \fBdoupdate\fR, causing several bursts of output to the screen. +By first +calling \fBwnoutrefresh\fR for each window, it is then possible to call +\fBdoupdate\fR once, resulting in only one burst of output, with fewer total +characters transmitted and less CPU time used. +If the \fIwin\fR argument to +\fBwrefresh\fR is the global variable \fBcurscr\fR, the screen is immediately +cleared and repainted from scratch. +.PP +The phrase "copies the named window to the virtual screen" above is ambiguous. +What actually happens is that all \fItouched\fR (changed) lines in the window +are copied to the virtual screen. +This affects programs that use overlapping +windows; it means that if two windows overlap, you can refresh them in either +order and the overlap region will be modified only when it is explicitly +changed. +(But see the section on \fBPORTABILITY\fR below for a warning about +exploiting this behavior.) +.PP +The \fBwredrawln\fR routine indicates to \fBcurses\fR that some screen lines +are corrupted and should be thrown away before anything is written over them. +It touches the indicated lines (marking them changed). +The routine \fBredrawwin\fR() touches the entire window. +.SH RETURN VALUE +Routines that return an integer return \fBERR\fR upon failure, and \fBOK\fR +(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful +completion. +.PP +X/Open does not define any error conditions. +In this implementation +.RS +.TP 5 +\fBwnoutrefresh\fP +returns an error +if the window pointer is null, or +if the window is really a pad. +.TP 5 +\fBwredrawln\fP +returns an error +if the associated call to \fBtouchln\fP returns an error. +.RE +.SH NOTES +Note that \fBrefresh\fR and \fBredrawwin\fR may be macros. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +.PP +Whether \fBwnoutrefresh()\fR copies to the virtual screen the entire contents +of a window or just its changed portions has never been well-documented in +historic curses versions (including SVr4). +It might be unwise to rely on +either behavior in programs that might have to be linked with other curses +implementations. +Instead, you can do an explicit \fBtouchwin()\fR before the +\fBwnoutrefresh()\fR call to guarantee an entire-contents copy anywhere. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_outopts\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_scanw.3x b/man/curs_scanw.3x new file mode 100644 index 000000000000..71ba9eeb4ddf --- /dev/null +++ b/man/curs_scanw.3x @@ -0,0 +1,97 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2000,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_scanw.3x,v 1.14 2006/12/24 16:05:49 tom Exp $ +.TH curs_scanw 3X "" +.SH NAME +\fBscanw\fR, +\fBwscanw\fR, +\fBmvscanw\fR, +\fBmvwscanw\fR, +\fBvwscanw\fR, \fBvw_scanw\fR - convert formatted input from a \fBcurses\fR window +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint scanw(char *fmt, ...);\fR +.br +\fBint wscanw(WINDOW *win, char *fmt, ...);\fR +.br +\fBint mvscanw(int y, int x, char *fmt, ...);\fR +.br +\fBint mvwscanw(WINDOW *win, int y, int x, char *fmt, ...);\fR +.br +\fBint vw_scanw(WINDOW *win, char *fmt, va_list varglist);\fR +.br +\fBint vwscanw(WINDOW *win, char *fmt, va_list varglist);\fR +.SH DESCRIPTION +The \fBscanw\fR, \fBwscanw\fR and \fBmvscanw\fR routines are analogous to +\fBscanf\fR [see \fBscanf\fR(3)]. The effect of these routines is as though +\fBwgetstr\fR were called on the window, and the resulting line used as input +for \fBsscanf\fR(3). Fields which do not map to a variable in the \fIfmt\fR +field are lost. +.PP +The \fBvwscanw\fR and \fBvw_scanw\fR routines are analogous to \fBvscanf\fR. +They perform a \fBwscanw\fR using a variable argument list. +The third argument is a \fIva_list\fR, +a pointer to a list of arguments, as defined in \fB<stdarg.h>\fR. +.SH RETURN VALUE +\fBvwscanw\fR returns \fBERR\fR on failure and an integer equal to the +number of fields scanned on success. +.PP +Applications may use the return value from the \fBscanw\fR, \fBwscanw\fR, +\fBmvscanw\fR and \fBmvwscanw\fR routines to determine the number of fields +which were mapped in the call. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. The function +\fBvwscanw\fR is marked TO BE WITHDRAWN, and is to be replaced by a function +\fBvw_scanw\fR using the \fB<stdarg.h>\fR interface. +The Single Unix Specification, Version 2 states that +\fBvw_scanw\fR is preferred to \fBvwscanw\fR since the latter requires +including \fB<varargs.h>\fR, which +cannot be used in the same file as \fB<stdarg.h>\fR. +This implementation uses \fB<stdarg.h>\fR for both, because that header +is included in \fB<curses.h\fR>. +.LP +Both XSI and The Single Unix Specification, Version 2 state that these +functions return ERR or OK. +Since the underlying \fBscanf\fR can return the number of items scanned, +and the SVr4 code was documented to use this feature, +this is probably an editing error which was introduced in XSI, +rather than being done intentionally. +Portable applications should only test if the return value is ERR, +since the OK value (zero) is likely to be misleading. +One possible way to get useful results would be to use a "%n" conversion +at the end of the format string to ensure that something was processed. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_getstr\fR(3X), \fBcurs_printw\fR(3X), \fBscanf\fR(3) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x new file mode 100644 index 000000000000..7884f6aa0648 --- /dev/null +++ b/man/curs_scr_dump.3x @@ -0,0 +1,102 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_scr_dump.3x,v 1.7 2006/12/24 16:05:49 tom Exp $ +.TH curs_scr_dump 3X "" +.na +.hy 0 +.SH NAME +\fBscr_dump\fR, +\fBscr_restore\fR, +\fBscr_init\fR, +\fBscr_set\fR - read (write) a \fBcurses\fR screen from (to) a file +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint scr_dump(const char *filename);\fR +.br +\fBint scr_restore(const char *filename);\fR +.br +\fBint scr_init(const char *filename);\fR +.br +\fBint scr_set(const char *filename);\fR +.br +.SH DESCRIPTION +The \fBscr_dump\fR routine dumps the current contents of the virtual screen +to the file \fIfilename\fR. +.PP +The \fBscr_restore\fR routine sets the virtual screen to the contents +of \fIfilename\fR, which must have been written using \fBscr_dump\fR. The next +call to \fBdoupdate\fR restores the screen to the way it looked in the dump +file. +.PP +The \fBscr_init\fR routine reads in the contents of \fIfilename\fR and uses +them to initialize the \fBcurses\fR data structures about what the terminal +currently has on its screen. If the data is determined to be valid, +\fBcurses\fR bases its next update of the screen on this information rather +than clearing the screen and starting from scratch. \fBscr_init\fR is used +after \fBinitscr\fR or a \fBsystem\fR call to share +the screen with another process which has done a \fBscr_dump\fR after its +\fBendwin\fR call. The data is declared invalid if the terminfo capabilities +\fBrmcup\fR and \fBnrrmc\fR exist; also if the terminal has been written to +since the preceding \fBscr_dump\fR call. +.PP +The \fBscr_set\fR routine is a combination of \fBscr_restore\fR and +\fBscr_init\fR. It tells the program that the information in \fIfilename\fR is +what is currently on the screen, and also what the program wants on the screen. +This can be thought of as a screen inheritance function. +.PP +To read (write) a window from (to) a file, use the \fBgetwin\fR and +\fBputwin\fR routines [see \fBcurs_util\fR(3X)]. +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and \fBOK\fR +upon success. +.PP +X/Open defines no error conditions. +In this implementation, +each will return an error if the file cannot be opened. +.SH NOTES +Note that \fBscr_init\fR, \fBscr_set\fR, and \fBscr_restore\fR may be macros. +.SH PORTABILITY +The XSI Curses standard, Issue 4, describes these functions (adding the const +qualifiers). +.PP +The SVr4 docs merely say under \fBscr_init\fR that the dump data is also +considered invalid "if the time-stamp of the tty is old" but do not define +"old". +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_refresh\fR(3X), +\fBcurs_util\fR(3X), \fBsystem\fR(3) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_scroll.3x b/man/curs_scroll.3x new file mode 100644 index 000000000000..754b71499841 --- /dev/null +++ b/man/curs_scroll.3x @@ -0,0 +1,96 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_scroll.3x,v 1.13 2006/02/25 21:49:19 tom Exp $ +.TH curs_scroll 3X "" +.na +.hy 0 +.SH NAME +\fBscroll\fR, +\fBscrl\fR, +\fBwscrl\fR - scroll a \fBcurses\fR window +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint scroll(WINDOW *win);\fR +.br +\fBint scrl(int n);\fR +.br +\fBint wscrl(WINDOW *win, int n);\fR +.br +.SH DESCRIPTION +The \fBscroll\fR routine scrolls the window up one line. +This involves moving +the lines in the window data structure. +As an optimization, if the scrolling +region of the window is the entire screen, the physical screen may be scrolled +at the same time. +.PP +For positive \fIn\fR, the \fBscrl\fR and \fBwscrl\fR routines scroll the +window up \fIn\fR lines (line \fIi\fR+\fIn\fR becomes \fIi\fR); otherwise +scroll the window down \fIn\fR lines. +This involves moving the lines in the +window character image structure. +The current cursor position is not changed. +.PP +For these functions to work, scrolling must be enabled via \fBscrollok\fR. +.SH RETURN VALUE +These routines return \fBERR\fR upon failure, and \fBOK\fR (SVr4 only specifies +"an integer value other than \fBERR\fR") upon successful completion. +.PP +X/Open defines no error conditions. +.PP +This implementation returns an error +if the window pointer is null, or +if scrolling is not enabled in the window, e.g., with \fBscrollok\fP. +.SH NOTES +Note that \fBscrl\fR and \fBscroll\fR may be macros. +.PP +The SVr4 documentation says that the optimization of physically scrolling +immediately if the scroll region is the entire screen "is" performed, not +"may be" performed. +This implementation deliberately does not guarantee +that this will occur, to leave open the possibility of smarter +optimization of multiple scroll actions on the next update. +.PP +Neither the SVr4 nor the XSI documentation specify whether the current +attribute or +current color-pair of blanks generated by the scroll function is zeroed. +Under this implementation it is. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_outopts\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_slk.3x b/man/curs_slk.3x new file mode 100644 index 000000000000..6361268b19d9 --- /dev/null +++ b/man/curs_slk.3x @@ -0,0 +1,205 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_slk.3x,v 1.16 2007/06/02 20:40:07 tom Exp $ +.TH curs_slk 3X "" +.na +.hy 0 +.SH NAME +\fBslk_init\fR, +\fBslk_set\fR, +\fBslk_refresh\fR, +\fBslk_noutrefresh\fR, +\fBslk_label\fR, +\fBslk_clear\fR, +\fBslk_restore\fR, +\fBslk_touch\fR, +\fBslk_attron\fR, +\fBslk_attrset\fR, +\fBslk_attroff\fR, +\fBslk_attr_on\fR, +\fBslk_attr_set\fR, +\fBslk_attr_off\fR, +\fBslk_attr\fR, +\fBslk_color\fR - \fBcurses\fR soft label routines +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint slk_init(int fmt);\fR +.br +\fBint slk_set(int labnum, const char *label, int fmt);\fR +.br +\fBint slk_refresh(void);\fR +.br +\fBint slk_noutrefresh(void);\fR +.br +\fBchar *slk_label(int labnum);\fR +.br +\fBint slk_clear(void);\fR +.br +\fBint slk_restore(void);\fR +.br +\fBint slk_touch(void);\fR +.br +\fBint slk_attron(const chtype attrs);\fR +.br +\fBint slk_attroff(const chtype attrs);\fR +.br +\fBint slk_attrset(const chtype attrs);\fR +.br +\fBint slk_attr_on(attr_t attrs, void* opts);\fR +.br +\fBint slk_attr_off(const attr_t attrs, void * opts);\fR +.br +\fBint slk_attr_set(const attr_t attrs,\fR +.br + \fBshort color_pair_number, void* opts);\fR +.br +\fBattr_t slk_attr(void);\fR +.br +\fBint slk_color(short color_pair_number);\fR +.br +.SH DESCRIPTION +The slk* functions manipulate the set of soft function-key labels that exist on +many terminals. For those terminals that do not have soft labels, +\fBcurses\fR takes over the bottom line of \fBstdscr\fR, reducing the size of +\fBstdscr\fR and the variable \fBLINES\fR. \fBcurses\fR standardizes on eight +labels of up to eight characters each. In addition to this, the ncurses +implementation supports a mode where it simulates 12 labels of up to five +characters each. This is most common for todays PC like enduser devices. +Please note that ncurses simulates this mode by taking over up to two lines at +the bottom of the screen, it does not try to use any hardware support for this +mode. +.PP +The \fBslk_init\fR routine must be called before \fBinitscr\fR or \fBnewterm\fR +is called. If \fBinitscr\fR eventually uses a line from \fBstdscr\fR to +emulate the soft labels, then \fIfmt\fR determines how the labels are arranged +on the screen. Setting \fIfmt\fR to \fB0\fR indicates a 3-2-3 arrangement of +the labels, \fB1\fR indicates a 4-4 arrangement and \fB2\fR indicates the +PC like 4-4-4 mode. If \fBfmt\fR is set to \fB3\fR, it is again the PC like +4-4-4 mode, but in addition an index line is generated, helping the user to +identify the key numbers easily. +.PP +The \fBslk_set\fR routine requires \fIlabnum\fR to be a label number, +from \fB1\fR to \fB8\fR (resp. \fB12\fR); \fIlabel\fR must be the string +to be put on the label, up to eight (resp. five) characters in length. +A null string or a null pointer sets up a blank label. \fIfmt\fR is either +\fB0\fR, \fB1\fR, or \fB2\fR, indicating whether the label is to be +left-justified, centered, or right-justified, respectively, within the +label. +.PP +The \fBslk_refresh\fR and \fBslk_noutrefresh\fR routines correspond to +the \fBwrefresh\fR and \fBwnoutrefresh\fR routines. +.PP +The \fBslk_label\fR routine returns the current label for label number +\fIlabnum\fR, with leading and trailing blanks stripped. +.PP +The \fBslk_clear\fR routine clears the soft labels from the screen. +.PP +The \fBslk_restore\fR routine restores the soft labels to the screen +after a \fBslk_clear\fR has been performed. +.PP +The \fBslk_touch\fR routine forces all the soft labels to be output +the next time a \fBslk_noutrefresh\fR is performed. +.PP +The \fBslk_attron\fR, \fBslk_attrset\fR, \fBslk_attroff\fR and \fBslk_attr\fR +routines correspond to \fBattron\fR, \fBattrset\fR, \fBattroff\fR and \fBattr_get\fR. +They have an effect only if soft labels are simulated on the bottom line of +the screen. The default highlight for soft keys is A_STANDOUT (as in +System V curses, which does not document this fact). +.PP +The \fBslk_color\fR routine corresponds to \fBcolor_set\fR. It has an effect only +if soft labels are simulated on the bottom line of the screen. +. +.SH RETURN VALUE +These routines return \fBERR\fR upon failure and OK (SVr4 specifies only "an +integer value other than \fBERR\fR") upon successful completion. +.PP +X/Open defines no error conditions. +In this implementation +.RS +.TP 5 +\fBslk_attr\fR +returns the attribute used for the soft keys. +.TP 5 +.na +.hy 0 +\fBslk_attroff\fP, \fBslk_attron\fP, \fBslk_clear\fP, \fBslk_noutrefresh\fP, \fBslk_refresh\fP, \fBslk_touch\fP +.ad +.hy +return an error +if the terminal or the softkeys were not initialized. +.TP 5 +\fBslk_attrset\fP +returns an error +if the terminal or the softkeys were not initialized. +.TP 5 +\fBslk_attr_set\fP +returns an error +if the terminal or the softkeys were not initialized, or +the color pair is outside the range 0..COLOR_PAIRS-1, +or opts is not null. +.TP 5 +\fBslk_color\fP +returns an error +if the terminal or the softkeys were not initialized, or +the color pair is outside the range 0..COLOR_PAIRS-1. +.TP 5 +\fBslk_init\fR +returns an error +if the format parameter is outside the range 0..3. +.TP 5 +\fBslk_label\fR +returns \fBNULL\fR on error. +.TP 5 +\fBslk_set\fP +returns an error +if the terminal or the softkeys were not initialized, or +the \fIlabnum\fP parameter is outside the range of label counts, or +if the format parameter is outside the range 0..2, or if +memory for the labels cannot be allocated. +.RE +.SH NOTES +Most applications would use \fBslk_noutrefresh\fR because a +\fBwrefresh\fR is likely to follow soon. +.SH PORTABILITY +The XSI Curses standard, Issue 4, describes these functions. It changes the +argument type of the attribute-manipulation functions \fBslk_attron\fR, +\fBslk_attroff\fR, \fBslk_attrset\fR to be \fBattr_t\fR, and adds \fBconst\fR +qualifiers. The format codes \fB2\fR and \fB3\fR for \fBslk_init()\fR and the +function \fBslk_attr\fR are specific to ncurses. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_attr\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_refresh\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_termattrs.3x b/man/curs_termattrs.3x new file mode 100644 index 000000000000..1e07307d19c0 --- /dev/null +++ b/man/curs_termattrs.3x @@ -0,0 +1,134 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_termattrs.3x,v 1.10 2007/06/02 20:40:07 tom Exp $ +.TH curs_termattrs 3X "" +.SH NAME +\fBbaudrate\fR, +\fBerasechar\fR, +\fBerasewchar\fR, +\fBhas_ic\fR, +\fBhas_il\fR, +\fBkillchar\fR, +\fBkillwchar\fR, +\fBlongname\fR, +\fBterm_attrs\fR, +\fBtermattrs\fR, +\fBtermname\fR - \fBcurses\fR environment query routines +.SH SYNOPSIS +\fB#include <curses.h>\fR +.PP +\fBint baudrate(void);\fR +.br +\fBchar erasechar(void);\fR +.br +\fBint erasewchar(wchar_t *\fR\fIch\fR\fB);\fR +.br +\fBbool has_ic(void);\fR +.br +\fBbool has_il(void);\fR +.br +\fBchar killchar(void);\fR +.br +\fBint killwchar(wchar_t *\fR\fIch\fR\fB);\fR +.br +\fBchar *longname(void);\fR +.br +\fBattr_t term_attrs(void);\fR +.br +\fBchtype termattrs(void);\fR +.br +\fBchar *termname(void);\fR +.br +.SH DESCRIPTION +The \fBbaudrate\fR routine returns the output speed of the terminal. The +number returned is in bits per second, for example \fB9600\fR, and is an +integer. +.PP +The \fBerasechar\fR routine returns the user's current erase character. +.PP +The \fBerasewchar\fR routine stores the current erase character +in the location referenced by \fIch\fR. +If no erase character has been defined, the routine fails +and the location referenced by \fIch\fR is not changed. +.PP +The \fBhas_ic\fR routine is true if the terminal has insert- and delete- +character capabilities. +.PP +The \fBhas_il\fR routine is true if the terminal has insert- and delete-line +capabilities, or can simulate them using scrolling regions. This might +be used to determine if it would be appropriate to turn on physical +scrolling using \fBscrollok\fR. +.PP +The \fBkillchar\fR routine returns the user's current line kill character. +.PP +The \fBkillwchar\fR routine stores the current line-kill character +in the location referenced by \fIch\fR. +If no line-kill character has been defined, +the routine fails and the location referenced by \fIch\fR is not changed. +.PP +The \fBlongname\fR routine returns a pointer to a static area +containing a verbose description of the current terminal. The maximum +length of a verbose description is 128 characters. It is defined only +after the call to \fBinitscr\fR or \fBnewterm\fR. The area is +overwritten by each call to \fBnewterm\fR and is not restored by +\fBset_term\fR, so the value should be saved between calls to +\fBnewterm\fR if \fBlongname\fR is going to be used with multiple +terminals. +.PP +If a given terminal does not support a video attribute that an +application program is trying to use, \fBcurses\fR may substitute a +different video attribute for it. +The \fBtermattrs\fR and \fBterm_attrs\fR functions +return a logical \fBOR\fR of all video attributes supported by the +terminal using \fIA_\fR and \fIWA_\fR constants respectively. +This information is useful when a \fBcurses\fR program +needs complete control over the appearance of the screen. +.PP +The \fBtermname\fR routine returns the terminal name used by \fBsetupterm\fR. +.SH RETURN VALUE +\fBlongname\fR and \fBtermname\fR return \fBNULL\fR on error. +.PP +Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR +(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful +completion. +.SH NOTES +Note that \fBtermattrs\fR may be a macro. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. It changes the +return type of \fBtermattrs\fR to the new type \fBattr_t\fR. +Most versions of curses truncate the result returned by \fBtermname\fR to +14 characters. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_outopts\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x new file mode 100644 index 000000000000..93ac2fb146d1 --- /dev/null +++ b/man/curs_termcap.3x @@ -0,0 +1,167 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_termcap.3x,v 1.22 2007/06/02 20:40:07 tom Exp $ +.TH curs_termcap 3X "" +.ds n 5 +.SH NAME +\fBtgetent\fR, +\fBtgetflag\fR, +\fBtgetnum\fR, +\fBtgetstr\fR, +\fBtgoto\fR, +\fBtputs\fR - direct \fBcurses\fR interface to the terminfo capability database +.SH SYNOPSIS +\fB#include <curses.h>\fR +.br +\fB#include <term.h>\fR +.sp +\fBextern char PC;\fR +.br +\fBextern char * UP;\fR +.br +\fBextern char * BC;\fR +.br +\fBextern @NCURSES_OSPEED@ ospeed;\fR +.sp +\fBint tgetent(char *bp, const char *name);\fR +.br +\fBint tgetflag(char *id);\fR +.br +\fBint tgetnum(char *id);\fR +.br +\fBchar *tgetstr(char *id, char **area);\fR +.br +\fBchar *tgoto(const char *cap, int col, int row);\fR +.br +\fBint tputs(const char *str, int affcnt, int (*putc)(int));\fR +.br +.SH DESCRIPTION +These routines are included as a conversion aid for programs that use +the \fItermcap\fR library. Their parameters are the same and the +routines are emulated using the \fIterminfo\fR database. Thus, they +can only be used to query the capabilities of entries for which a +terminfo entry has been compiled. +.PP +The \fBtgetent\fR routine loads the entry for \fIname\fR. +It returns 1 on success, 0 if there is no such entry, and -1 if the +terminfo database could not be found. +The emulation ignores the buffer pointer \fIbp\fR. +.PP +The \fBtgetflag\fR routine gets the boolean entry for \fIid\fR, +or zero if it is not available. +.PP +The \fBtgetnum\fR routine gets the numeric entry for \fIid\fR, +or -1 if it is not available. +.PP +The \fBtgetstr\fR routine returns the string entry for \fIid\fR, +or zero if it is not available. +Use \fBtputs\fR to output the returned string. +The return value will also be copied to the buffer pointed to by \fIarea\fR, +and the \fIarea\fR value will be updated to point past the null ending +this value. +.PP +Only the first two characters of the \fBid\fR parameter of +\fBtgetflag\fR, +\fBtgetnum\fR and +\fBtgetstr\fR are compared in lookups. +.PP +The \fBtgoto\fR routine instantiates the parameters into the given capability. +The output from this routine is to be passed to \fBtputs\fR. +.PP +The \fBtputs\fR routine is described on the \fBcurs_terminfo\fR(3X) manual +page. It can retrieve capabilities by either termcap or terminfo name. +.PP +The variables +\fBPC\fR, +\fBUP\fR and +\fBBC\fR +are set by \fBtgetent\fR to the terminfo entry's data for +\fBpad_char\fR, +\fBcursor_up\fR and +\fBbackspace_if_not_bs\fR, +respectively. +\fBUP\fR is not used by ncurses. +\fBPC\fR is used in the \fBtdelay_output\fR function. +\fBBC\fR is used in the \fBtgoto\fR emulation. +The variable \fBospeed\fR is set by ncurses in a system-specific coding +to reflect the terminal speed. +. +.SH RETURN VALUE +Except where explicitly noted, +routines that return an integer return \fBERR\fR upon failure and \fBOK\fR +(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful +completion. +.PP +Routines that return pointers return \fBNULL\fR on error. +.SH BUGS +If you call \fBtgetstr\fR to fetch \fBca\fR or any other parameterized string, +be aware that it will be returned in terminfo notation, not the older and +not-quite-compatible termcap notation. This will not cause problems if all +you do with it is call \fBtgoto\fR or \fBtparm\fR, which both expand +terminfo-style strings as terminfo. +(The \fBtgoto\fR function, if configured to support termcap, will check +if the string is indeed terminfo-style by looking for "%p" parameters or +"$<..>" delays, and invoke a termcap-style parser if the string does not +appear to be terminfo). +.PP +Because terminfo conventions for representing padding in string capabilities +differ from termcap's, \fBtputs("50");\fR will put out a literal "50" rather +than busy-waiting for 50 milliseconds. Cope with it. +.PP +Note that termcap has nothing analogous to terminfo's \fBsgr\fR string. +One consequence of this is that termcap applications assume \fRme\fR +(terminfo \fBsgr0\fR) does not reset the alternate character set. +This implementation checks for, and modifies the data shown to the +termcap interface to accommodate termcap's limitation in this respect. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. However, they +are marked TO BE WITHDRAWN and may be removed in future versions. +.PP +Neither the XSI Curses standard nor the SVr4 man pages documented the return +values of \fBtgetent\fR correctly, though all three were in fact returned ever +since SVr1. +In particular, an omission in the XSI Curses documentation has been +misinterpreted to mean that \fBtgetent\fR returns \fBOK\fR or \fBERR\fR. +Because the purpose of these functions is to provide compatibility with +the \fItermcap\fR library, that is a defect in XCurses, Issue 4, Version 2 +rather than in ncurses. +.PP +External variables are provided for support of certain termcap applications. +However, termcap applications' use of those variables is poorly documented, +e.g., not distinguishing between input and output. +In particular, some applications are reported to declare and/or +modify \fBospeed\fR. +.SH SEE ALSO +\fBcurses\fR(3X), \fBterminfo\fR(\*n), \fBputc\fR(3). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x new file mode 100644 index 000000000000..5af0b8fbe27c --- /dev/null +++ b/man/curs_terminfo.3x @@ -0,0 +1,336 @@ +.\"*************************************************************************** +.\" Copyright (c) 1999-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_terminfo.3x,v 1.28 2007/05/26 20:09:06 tom Exp $ +.TH curs_terminfo 3X "" +.ds n 5 +.na +.hy 0 +.SH NAME +\fBdel_curterm\fR, +\fBmvcur\fR, +\fBputp\fR, +\fBrestartterm\fR, +\fBset_curterm\fR, +\fBsetterm\fR, +\fBsetupterm\fR, +\fBtigetflag\fR, +\fBtigetnum\fR, +\fBtigetstr\fR, +\fBtparm\fR, +\fBtputs\fR, +\fBvid_attr\fR, +\fBvid_puts\fR, +\fBvidattr\fR, +\fBvidputs\fR - \fBcurses\fR interfaces to terminfo database +.ad +.hy +.SH SYNOPSIS +.nf +\fB#include <curses.h>\fR +.br +\fB#include <term.h>\fR +.PP +\fBint setupterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR +.br +\fBint setterm(char *\fR\fIterm\fR\fB);\fR +.br +\fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR +.br +\fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR +.br +\fBint restartterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR +.br +\fBchar *tparm(char *\fR\fIstr\fR\fB, ...);\fR +.br +\fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR +.br +\fBint putp(const char *\fR\fIstr\fR\fB);\fR +.br +\fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR +.br +\fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR +.br +\fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(char));\fR +.br +\fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR +.br +\fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR +.br +\fBint tigetflag(char *\fR\fIcapname\fR\fB);\fR +.br +\fBint tigetnum(char *\fR\fIcapname\fR\fB);\fR +.br +\fBchar *tigetstr(char *\fR\fIcapname\fR\fB);\fR +.br +.fi +.SH DESCRIPTION +These low-level routines must be called by programs that have to deal +directly with the \fBterminfo\fR database to handle certain terminal +capabilities, such as programming function keys. For all other +functionality, \fBcurses\fR routines are more suitable and their use is +recommended. +.PP +Initially, \fBsetupterm\fR should be called. Note that +\fBsetupterm\fR is automatically called by \fBinitscr\fR and +\fBnewterm\fR. This defines the set of terminal-dependent variables +[listed in \fBterminfo\fR(\*n)]. +The \fBterminfo\fR variables +\fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as +follows: +.RS +.PP +If \fBuse_env(FALSE)\fR has been called, values for +\fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used. +.PP +Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR +exist, their values are used. If these environment variables do not +exist and the program is running in a window, the current window size +is used. Otherwise, if the environment variables do not exist, the +values for \fBlines\fR and \fBcolumns\fR specified in the +\fBterminfo\fR database are used. +.RE +.PP +The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this +order) to get the definitions for these strings, numbers, and flags. +Parameterized strings should be passed through \fBtparm\fR to instantiate them. +All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed +with \fBtputs\fR or \fBputp\fR. Call the \fBreset_shell_mode\fR to restore the +tty modes before exiting [see \fBcurs_kernel\fR(3X)]. Programs which use +cursor addressing should output \fBenter_ca_mode\fR upon startup and should +output \fBexit_ca_mode\fR before exiting. Programs desiring shell escapes +should call +.PP +\fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell +is called and should output \fBenter_ca_mode\fR and call +\fBreset_prog_mode\fR after returning from the shell. +.PP +The \fBsetupterm\fR routine reads in the \fBterminfo\fR database, +initializing the \fBterminfo\fR structures, but does not set up the +output virtualization structures used by \fBcurses\fR. The terminal +type is the character string \fIterm\fR; if \fIterm\fR is null, the +environment variable \fBTERM\fR is used. +All output is to file descriptor \fBfildes\fR which is initialized for output. +If \fIerrret\fR is not null, +then \fBsetupterm\fR returns \fBOK\fR or +\fBERR\fR and stores a status value in the integer pointed to by +\fIerrret\fR. +A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR +is normal. +If \fBERR\fR is returned, examine \fIerrret\fR: +.RS +.TP 5 +.B 1 +means that the terminal is hardcopy, cannot be used for curses applications. +.TP 5 +.B 0 +means that the terminal could not be found, +or that it is a generic type, +having too little information for curses applications to run. +.TP 5 +.B -1 +means that the \fBterminfo\fR database could not be found. +.RE +.PP +If \fIerrret\fR is +null, \fBsetupterm\fR prints an error message upon finding an error +and exits. Thus, the simplest call is: +.sp + \fBsetupterm((char *)0, 1, (int *)0);\fR, +.sp +which uses all the defaults and sends the output to \fBstdout\fR. +.PP +The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR. The call: +.sp + \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR +.sp +provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR. +The \fBsetterm\fR routine is included here for BSD compatibility, and +is not recommended for new programs. +.PP +The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to +\fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and +string variables use the values from \fInterm\fR. It returns the old value +of \fBcur_term\fR. +.PP +The \fBdel_curterm\fR routine frees the space pointed to by +\fIoterm\fR and makes it available for further use. If \fIoterm\fR is +the same as \fBcur_term\fR, references to any of the \fBterminfo\fR +boolean, numeric, and string variables thereafter may refer to invalid +memory locations until another \fBsetupterm\fR has been called. +.PP +The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR, +except that it is called after restoring memory to a previous state (for +example, when reloading a game saved as a core image dump). It assumes that +the windows and the input and output options are the same as when memory was +saved, but the terminal type and baud rate may be different. Accordingly, +it saves various tty state bits, calls \fBsetupterm\fP, +and then restores the bits. +.PP +The \fBtparm\fR routine instantiates the string \fIstr\fR with +parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR +with the parameters applied. +.PP +The \fBtputs\fR routine applies padding information to the string +\fIstr\fR and outputs it. The \fIstr\fR must be a terminfo string +variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or +\fBtgoto\fR. \fIaffcnt\fR is the number of lines affected, or 1 if +not applicable. \fIputc\fR is a \fBputchar\fR-like routine to which +the characters are passed, one at a time. +.PP +The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR. +Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to +the \fIfildes\fR specified in \fBsetupterm\fR. +.PP +The \fBvidputs\fR routine displays the string on the terminal in the +video attribute mode \fIattrs\fR, which is any combination of the +attributes listed in \fBcurses\fR(3X). The characters are passed to +the \fBputchar\fR-like routine \fIputc\fR. +.PP +The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except +that it outputs through \fBputchar\fR. +.PP +The \fBvid_attr\fR and \fBvid_puts\fR routines correspond to vidattr and vidputs, +respectively. +They use a set of arguments for representing the video attributes plus color, +i.e., +one of type attr_t for the attributes and one of short for +the color_pair number. +The \fBvid_attr\fR and \fBvid_puts\fR routines +are designed to use the attribute constants with the \fIWA_\fR prefix. +The opts argument is reserved for future use. +Currently, applications must provide a null pointer for that argument. +.PP +The \fBmvcur\fR routine provides low-level cursor motion. It takes +effect immediately (rather than at the next refresh). +.PP +The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return +the value of the capability corresponding to the \fBterminfo\fR +\fIcapname\fR passed to them, such as \fBxenl\fR. +.PP +The \fBtigetflag\fR routine returns the value \fB-1\fR if +\fIcapname\fR is not a boolean capability, +or \fB0\fR if it is canceled or absent from the terminal description. +.PP +The \fBtigetnum\fR routine returns the value \fB-2\fR if +\fIcapname\fR is not a numeric capability, +or \fB-1\fR if it is canceled or absent from the terminal description. +.PP +The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR +if \fIcapname\fR is not a string capability, +or \fB0\fR if it is canceled or absent from the terminal description. +.PP +The \fIcapname\fR for each capability is given in the table column entitled +\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n). +.sp +.RS +\fBchar *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR +.sp +\fBchar *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR +.sp +\fBchar *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR +.RE +.PP +These null-terminated arrays contain the \fIcapnames\fR, the +\fBtermcap\fR codes, and the full C names, for each of the +\fBterminfo\fR variables. +.SH RETURN VALUE +Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR +(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful +completion, unless otherwise noted in the preceding routine descriptions. +.PP +Routines that return pointers always return \fBNULL\fR on error. +.PP +X/Open defines no error conditions. +In this implementation +.RS +.TP 5 +\fBdel_curterm\fP +returns an error +if its terminal parameter is null. +.TP 5 +\fBrestartterm\fP +returns an error +if the associated call to \fBsetupterm\fP returns an error. +.TP 5 +\fBsetupterm\fP +returns an error +if it cannot allocate enough memory, or +create the initial windows (stdscr, curscr, newscr). +Other error conditions are documented above. +.RE +.SH NOTES +The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR. +It may be useful when you want to test for terminal capabilities without +committing to the allocation of storage involved in \fBinitscr\fR. +.PP +Note that \fBvidattr\fR and \fBvidputs\fR may be macros. +.SH PORTABILITY +The function \fBsetterm\fR is not described in the XSI Curses standard and must +be considered non-portable. All other functions are as described in the XSI +curses standard. +.PP +\fBsetupterm\fP copies the terminal name to the array \fBttytype\fP. +This is not part of X/Open Curses, but is assumed by some applications. +.PP +In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and +returns \fBOK\fR or \fBERR\fR. We have chosen to implement the XSI Curses +semantics. +.PP +In System V Release 4, the third argument of \fBtputs\fR has the type +\fBint (*putc)(char)\fR. +.PP +The XSI Curses standard prototypes \fBtparm\fR with a fixed number of parameters, +rather than a variable argument list. +This implementation uses a variable argument list. +Portable applications should provide 9 parameters after the format; +zeroes are fine for this purpose. +.PP +XSI notes that after calling \fBmvcur\fR, the curses state may not match the +actual terminal state, and that an application should touch and refresh +the window before resuming normal curses calls. +Both ncurses and System V Release 4 curses implement \fBmvcur\fR using +the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR. +So though it is documented as a terminfo function, +\fBmvcur\fR is really a curses function which is not well specified. +.PP +XSI states that the old location must be given for \fBmvcur\fP. +This implementation allows the caller to use -1's for the old ordinates. +In that case, the old location is unknown. +.PP +Extended terminal capability names, e.g., as defined by \fBtic\ -x\fP, +are not stored in the arrays described in this section. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X), +\fBputc\fR(3), \fBterminfo\fR(\*n) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_threads.3x b/man/curs_threads.3x new file mode 100644 index 000000000000..17dabdb7b40a --- /dev/null +++ b/man/curs_threads.3x @@ -0,0 +1,603 @@ +.\"*************************************************************************** +.\" Copyright (c) 2008 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_threads.3x,v 1.12 2008/04/12 18:22:51 tom Exp $ +.TH curs_threads 3X "" +.na +.hy 0 +.SH NAME +\fBuse_screen\fR, +\fBuse_window\fR - \fBcurses\fR thread support +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fR +\fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fR +.br +\fBint set_escdelay(int size);\fR +.br +\fBint set_tabsize(int size);\fR +.br +\fBint use_screen(SCREEN *scr, NCURSES_WINDOW_CB func, void *data);\fR +.br +\fBint use_window(WINDOW *win, NCURSES_SCREEN_CB func, void *data);\fR +.br +.SH DESCRIPTION +This implementation can be configured to provide rudimentary support +for multi-threaded applications. +This makes a different set of libraries, e.g., \fIlibncursest\fP since +the binary interfaces are different. +.PP +Rather than modify the interfaces to pass a thread specifier to +each function, it adds a few functions which can be used in any +configuration which hide the mutex's needed to prevent concurrent +use of the global variables when configured for threading. +.PP +In addition to forcing access to members of the \fBWINDOW\fP structure +to be via functions (see \fBcurs_opaque\fP(3x)), +it makes functions of the common global variables, +e.g., +COLORS, +COLOR_PAIRS, +COLS, +ESCDELAY, +LINES, +TABSIZE +curscr, +newscr and +ttytype. +Those variables are maintained as read-only values, stored in the \fBSCREEN\fP +structure. +.PP +Even this is not enough to make a thread-safe application using curses. +A multi-threaded application would be expected to have threads updating +separate windows (within the same device), +or updating on separate screens (on different devices). +Also, a few of the global variables are considered writable by some +applications. +The functions described here address these special situations. +.PP +The ESCDELAY and TABSIZE global variables are modified by some applications. +To modify them in any configuration, +use the \fBset_escdelay\fP or \fBset_tabsize\fP functions. +Other global variables are not modifiable. +.PP +The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse +granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP +parameters, and call a user-supplied function, +passing it a \fIdata\fP parameter, +and returning the value from the user-supplied function to the application. +.\" *************************************************************************** +.SS USAGE +All of the ncurses library functions assume that the locale is not +altered during operation. +In addition, +they use data which is maintained within a hierarchy of scopes. +.RS +.TP 3 +- +global data, e.g., used in the low-level terminfo or termcap interfaces. +.TP 3 +- +terminal data, e.g., associated with a call to \fIset_curterm\fP. +The terminal data are initialized when screens are created. +.TP 3 +- +screen data, e.g., associated with a call to \fInewterm\fP or \fIinitscr\fP. +.TP 3 +- +window data, e.g., associated with a call to \fInewwin\fP or \fIsubwin\fP. +Windows are associated with screens. +Pads are not necessarily associated with a particular screen. +.IP +Most curses applications operate on one or more windows within a single screen. +.TP 3 +- +reentrant, i.e., it uses only the data passed as parameters. +.RE +.PP +This table lists the scope of data used for each symbol in the +ncurses library when it is configured to support threading: +.TS +center tab(/); +l l +l l . +Symbol/Scope += +BC/global +COLORS/screen (readonly) +COLOR_PAIR/reentrant +COLOR_PAIRS/screen (readonly) +COLS/screen (readonly) +ESCDELAY/screen (readonly, see \fIset_escdelay\fP) +LINES/screen (readonly) +PAIR_NUMBER/reentrant +PC/global +SP/global +TABSIZE/screen (readonly) +UP/global +acs_map/screen (readonly) +add_wch/window (stdscr) +add_wchnstr/window (stdscr) +add_wchstr/window (stdscr) +addch/window (stdscr) +addchnstr/window (stdscr) +addchstr/window (stdscr) +addnstr/window (stdscr) +addnwstr/window (stdscr) +addstr/window (stdscr) +addwstr/window (stdscr) +assume_default_colors/screen +attr_get/window (stdscr) +attr_off/window (stdscr) +attr_on/window (stdscr) +attr_set/window (stdscr) +attroff/window (stdscr) +attron/window (stdscr) +attrset/window (stdscr) +baudrate/screen +beep/screen +bkgd/window (stdscr) +bkgdset/window (stdscr) +bkgrnd/window (stdscr) +bkgrndset/window (stdscr) +boolcodes/global (readonly) +boolfnames/global (readonly) +boolnames/global (readonly) +border/window (stdscr) +border_set/window (stdscr) +box/window (stdscr) +box_set/window (stdscr) +can_change_color/terminal +cbreak/screen +chgat/window (stdscr) +clear/window (stdscr) +clearok/window +clrtobot/window (stdscr) +clrtoeol/window (stdscr) +color_content/screen +color_set/window (stdscr) +copywin/window locks(source, target) +cur_term/terminal +curs_set/screen +curscr/screen (readonly) +curses_version/global (readonly) +def_prog_mode/terminal +def_shell_mode/terminal +define_key/screen +del_curterm/screen +delay_output/screen +delch/window (stdscr) +deleteln/window (stdscr) +delscreen/global locks(screenlist, screen) +delwin/global locks(windowlist) +derwin/screen +doupdate/screen +dupwin/screen locks(window) +echo/screen +echo_wchar/window (stdscr) +echochar/window (stdscr) +endwin/screen +erase/window (stdscr) +erasechar/window (stdscr) +erasewchar/window (stdscr) +filter/global +flash/terminal +flushinp/screen +get_wch/screen (input-operation) +get_wstr/screen (input-operation) +getattrs/window +getbegx/window +getbegy/window +getbkgd/window +getbkgrnd/window +getcchar/reentrant +getch/screen (input-operation) +getcurx/window +getcury/window +getmaxx/window +getmaxy/window +getmouse/screen (input-operation) +getn_wstr/screen (input-operation) +getnstr/screen (input-operation) +getparx/window +getpary/window +getstr/screen (input-operation) +getwin/screen (input-operation) +halfdelay/screen +has_colors/terminal +has_ic/terminal +has_il/terminal +has_key/screen +hline/window (stdscr) +hline_set/window (stdscr) +idcok/window +idlok/window +immedok/window +in_wch/window (stdscr) +in_wchnstr/window (stdscr) +in_wchstr/window (stdscr) +inch/window (stdscr) +inchnstr/window (stdscr) +inchstr/window (stdscr) +init_color/screen +init_pair/screen +initscr/global locks(screenlist) +innstr/window (stdscr) +innwstr/window (stdscr) +ins_nwstr/window (stdscr) +ins_wch/window (stdscr) +ins_wstr/window (stdscr) +insch/window (stdscr) +insdelln/window (stdscr) +insertln/window (stdscr) +insnstr/window (stdscr) +insstr/window (stdscr) +instr/window (stdscr) +intrflush/terminal +inwstr/window (stdscr) +is_cleared/window +is_idcok/window +is_idlok/window +is_immedok/window +is_keypad/window +is_leaveok/window +is_linetouched/window +is_nodelay/window +is_notimeout/window +is_scrollok/window +is_syncok/window +is_term_resized/terminal +is_wintouched/window +isendwin/screen +key_defined/screen +key_name/global (static data) +keybound/screen +keyname/global (static data) +keyok/screen +keypad/window +killchar/terminal +killwchar/terminal +leaveok/window +longname/screen +mcprint/terminal +meta/screen +mouse_trafo/window (stdscr) +mouseinterval/screen +mousemask/screen +move/window (stdscr) +mvadd_wch/window (stdscr) +mvadd_wchnstr/window (stdscr) +mvadd_wchstr/window (stdscr) +mvaddch/window (stdscr) +mvaddchnstr/window (stdscr) +mvaddchstr/window (stdscr) +mvaddnstr/window (stdscr) +mvaddnwstr/window (stdscr) +mvaddstr/window (stdscr) +mvaddwstr/window (stdscr) +mvchgat/window (stdscr) +mvcur/screen +mvdelch/window (stdscr) +mvderwin/window (stdscr) +mvget_wch/screen (input-operation) +mvget_wstr/screen (input-operation) +mvgetch/screen (input-operation) +mvgetn_wstr/screen (input-operation) +mvgetnstr/screen (input-operation) +mvgetstr/screen (input-operation) +mvhline/window (stdscr) +mvhline_set/window (stdscr) +mvin_wch/window (stdscr) +mvin_wchnstr/window (stdscr) +mvin_wchstr/window (stdscr) +mvinch/window (stdscr) +mvinchnstr/window (stdscr) +mvinchstr/window (stdscr) +mvinnstr/window (stdscr) +mvinnwstr/window (stdscr) +mvins_nwstr/window (stdscr) +mvins_wch/window (stdscr) +mvins_wstr/window (stdscr) +mvinsch/window (stdscr) +mvinsnstr/window (stdscr) +mvinsstr/window (stdscr) +mvinstr/window (stdscr) +mvinwstr/window (stdscr) +mvprintw/window (stdscr) +mvscanw/screen +mvvline/window (stdscr) +mvvline_set/window (stdscr) +mvwadd_wch/window +mvwadd_wchnstr/window +mvwadd_wchstr/window +mvwaddch/window +mvwaddchnstr/window +mvwaddchstr/window +mvwaddnstr/window +mvwaddnwstr/window +mvwaddstr/window +mvwaddwstr/window +mvwchgat/window +mvwdelch/window +mvwget_wch/screen (input-operation) +mvwget_wstr/screen (input-operation) +mvwgetch/screen (input-operation) +mvwgetn_wstr/screen (input-operation) +mvwgetnstr/screen (input-operation) +mvwgetstr/screen (input-operation) +mvwhline/window +mvwhline_set/window +mvwin/window +mvwin_wch/window +mvwin_wchnstr/window +mvwin_wchstr/window +mvwinch/window +mvwinchnstr/window +mvwinchstr/window +mvwinnstr/window +mvwinnwstr/window +mvwins_nwstr/window +mvwins_wch/window +mvwins_wstr/window +mvwinsch/window +mvwinsnstr/window +mvwinsstr/window +mvwinstr/window +mvwinwstr/window +mvwprintw/window +mvwscanw/screen +mvwvline/window +mvwvline_set/window +napms/reentrant +newpad/global locks(windowlist) +newscr/screen (readonly) +newterm/global locks(screenlist) +newwin/global locks(windowlist) +nl/screen +nocbreak/screen +nodelay/window +noecho/screen +nofilter/global +nonl/screen +noqiflush/terminal +noraw/screen +notimeout/window +numcodes/global (readonly) +numfnames/global (readonly) +numnames/global (readonly) +ospeed/global +overlay/window locks(source, target) +overwrite/window locks(source, target) +pair_content/screen +pecho_wchar/screen +pechochar/screen +pnoutrefresh/screen +prefresh/screen +printw/window +putp/global +putwin/window +qiflush/terminal +raw/screen +redrawwin/window +refresh/screen +reset_prog_mode/screen +reset_shell_mode/screen +resetty/terminal +resize_term/screen locks(windowlist) +resizeterm/screen +restartterm/screen +ripoffline/global (static data) +savetty/terminal +scanw/screen +scr_dump/screen +scr_init/screen +scr_restore/screen +scr_set/screen +scrl/window (stdscr) +scroll/window +scrollok/window +set_curterm/screen +set_escdelay/screen +set_tabsize/screen +set_term/global locks(screenlist, screen) +setcchar/reentrant +setscrreg/window (stdscr) +setupterm/global +slk_attr/screen +slk_attr_off/screen +slk_attr_on/screen +slk_attr_set/screen +slk_attroff/screen +slk_attron/screen +slk_attrset/screen +slk_clear/screen +slk_color/screen +slk_init/screen +slk_label/screen +slk_noutrefresh/screen +slk_refresh/screen +slk_restore/screen +slk_set/screen +slk_touch/screen +slk_wset/screen +standend/window +standout/window +start_color/screen +stdscr/screen (readonly) +strcodes/global (readonly) +strfnames/global (readonly) +strnames/global (readonly) +subpad/window +subwin/window +syncok/window +term_attrs/screen +termattrs/screen +termname/terminal +tgetent/global +tgetflag/global +tgetnum/global +tgetstr/global +tgoto/global +tigetflag/terminal +tigetnum/terminal +tigetstr/terminal +timeout/window (stdscr) +touchline/window +touchwin/window +tparm/global (static data) +tputs/screen +trace/global (static data) +ttytype/screen (readonly) +typeahead/screen +unctrl/screen +unget_wch/screen (input-operation) +ungetch/screen (input-operation) +ungetmouse/screen (input-operation) +untouchwin/window +use_default_colors/screen +use_env/global (static data) +use_extended_names/global (static data) +use_legacy_coding/screen +use_screen/global locks(screenlist, screen) +use_window/global locks(windowlist, window) +vid_attr/screen +vid_puts/screen +vidattr/screen +vidputs/screen +vline/window (stdscr) +vline_set/window (stdscr) +vw_printw/window +vw_scanw/screen +vwprintw/window +vwscanw/screen +wadd_wch/window +wadd_wchnstr/window +wadd_wchstr/window +waddch/window +waddchnstr/window +waddchstr/window +waddnstr/window +waddnwstr/window +waddstr/window +waddwstr/window +wattr_get/window +wattr_off/window +wattr_on/window +wattr_set/window +wattroff/window +wattron/window +wattrset/window +wbkgd/window +wbkgdset/window +wbkgrnd/window +wbkgrndset/window +wborder/window +wborder_set/window +wchgat/window +wclear/window +wclrtobot/window +wclrtoeol/window +wcolor_set/window +wcursyncup/screen (affects window plus parents) +wdelch/window +wdeleteln/window +wecho_wchar/window +wechochar/window +wenclose/window +werase/window +wget_wch/screen (input-operation) +wget_wstr/screen (input-operation) +wgetbkgrnd/window +wgetch/screen (input-operation) +wgetn_wstr/screen (input-operation) +wgetnstr/screen (input-operation) +wgetparent/window +wgetscrreg/window +wgetstr/screen (input-operation) +whline/window +whline_set/window +win_wch/window +win_wchnstr/window +win_wchstr/window +winch/window +winchnstr/window +winchstr/window +winnstr/window +winnwstr/window +wins_nwstr/window +wins_wch/window +wins_wstr/window +winsch/window +winsdelln/window +winsertln/window +winsnstr/window +winsstr/window +winstr/window +winwstr/window +wmouse_trafo/window +wmove/window +wnoutrefresh/screen +wprintw/window +wredrawln/window +wrefresh/screen +wresize/window locks(windowlist) +wscanw/screen +wscrl/window +wsetscrreg/window +wstandend/window +wstandout/window +wsyncdown/screen (affects window plus parents) +wsyncup/screen (affects window plus parents) +wtimeout/window +wtouchln/window +wunctrl/global (static data) +wvline/window +wvline_set/window +.TE +.\" *************************************************************************** +.SH RETURN VALUE +These functions all return TRUE or FALSE, except as noted. +.SH NOTES +Both a macro and a function are provided for each name. +.SH PORTABILITY +These 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. +.SH SEE ALSO +\fBcurses\fR(3X), +\fBcurs_opaque\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_touch.3x b/man/curs_touch.3x new file mode 100644 index 000000000000..a7d07bc3ffbe --- /dev/null +++ b/man/curs_touch.3x @@ -0,0 +1,116 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_touch.3x,v 1.11 2006/02/25 21:49:19 tom Exp $ +.TH curs_touch 3X "" +.na +.hy 0 +.SH NAME +\fBtouchwin\fR, +\fBtouchline\fR, +\fBuntouchwin\fR, +\fBwtouchln\fR, +\fBis_linetouched\fR, +\fBis_wintouched\fR - \fBcurses\fR refresh control routines +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.br +\fBint touchwin(WINDOW *win);\fR +.br +\fBint touchline(WINDOW *win, int start, int count);\fR +.br +\fBint untouchwin(WINDOW *win);\fR +.br +\fBint wtouchln(WINDOW *win, int y, int n, int changed);\fR +.br +\fBbool is_linetouched(WINDOW *win, int line);\fR +.br +\fBbool is_wintouched(WINDOW *win);\fR +.br +.SH DESCRIPTION +The \fBtouchwin\fR and \fBtouchline\fR routines throw away all +optimization information about which parts of the window have been +touched, by pretending that the entire window has been drawn on. This +is sometimes necessary when using overlapping windows, since a change +to one window affects the other window, but the records of which lines +have been changed in the other window do not reflect the change. The +routine \fBtouchline\fR only pretends that \fIcount\fR lines have been +changed, beginning with line \fIstart\fR. +.PP +The \fBuntouchwin\fR routine marks all lines in the window as unchanged since +the last call to \fBwrefresh\fR. +.PP +The \fBwtouchln\fR routine makes \fIn\fR lines in the window, starting +at line \fIy\fR, look as if they have (\fIchanged\fR\fB=1\fR) or have +not (\fIchanged\fR\fB=0\fR) been changed since the last call to +\fBwrefresh\fR. +.PP +The \fBis_linetouched\fR and \fBis_wintouched\fR routines return +\fBTRUE\fR if the specified line/window was modified since the last +call to \fBwrefresh\fR; otherwise they return \fBFALSE\fR. In +addition, \fBis_linetouched\fR returns \fBERR\fR if \fIline\fR is not +valid for the given window. +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and an integer value +other than \fBERR\fR upon successful completion, unless otherwise noted in the +preceding routine descriptions. +.PP +X/Open does not define any error conditions. +In this implementation +.RS +.TP 5 +\fBis_linetouched\fP +returns an error +if the window pointer is null, or +if the line number is outside the window. +Note that ERR is distinct from TRUE and FALSE, which are the normal return values of this function. +.TP 5 +\fBwtouchln\fP +returns an error +if the window pointer is null, or +if the line number is outside the window. +.RE +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +.PP +Some historic curses implementations had, as an undocumented feature, the +ability to do the equivalent of \fBclearok(..., 1)\fR by saying +\fBtouchwin(stdscr)\fR or \fBclear(stdscr)\fR. This will not work under +ncurses. +.SH NOTES +Note that all routines except \fBwtouchln\fR may be macros. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_refresh\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_trace.3x b/man/curs_trace.3x new file mode 100644 index 000000000000..ca7495272d33 --- /dev/null +++ b/man/curs_trace.3x @@ -0,0 +1,153 @@ +.\"*************************************************************************** +.\" Copyright (c) 2000-2005,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_trace.3x,v 1.8 2007/02/24 17:33:49 tom Exp $ +.TH curs_trace 3X "" +.na +.hy 0 +.SH NAME +\fB_tracef\fR, +\fB_tracedump\fR, +\fB_traceattr\fR, +\fB_traceattr2\fR, +\fB_nc_tracebits\fR, +\fB_tracechar\fR, +\fB_tracechtype\fR, +\fB_tracechtype2\fR, +\fB_tracemouse\fR, +\fBtrace\fR - \fBcurses\fR debugging routines +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBvoid _tracef(const char *format, ...);\fR +.br +\fBvoid _tracedump(const char *label, WINDOW *win);\fR +.br +\fBchar *_traceattr(attr_t attr);\fR +.br +\fBchar *_traceattr2(int buffer, chtype ch);\fR +.br +\fBchar *_nc_tracebits(void);\fR +.br +\fBchar *_tracechar(int);\fR +.br +\fBchar *_tracechtype(chtype ch);\fR +.br +\fBchar *_tracechtype2(int buffer, chtype ch);\fR +.br +\fBchar *_tracemouse(const MEVENT *event);\fR +.br +\fBvoid trace(const unsigned int param);\fR +.SH DESCRIPTION +The \fBtrace\fR routines are used for debugging the ncurses libraries, +as well as applications which use the ncurses libraries. +These functions are normally available only with the debugging library +\fIlibncurses_g.a\fR, but may be compiled into any model (shared, static, +profile) by defining the symbol \fBTRACE\fR. +.PP +The principal parts of this interface are the \fBtrace\fR routine which +selectively enables different tracing features, and the \fB_tracef\fR +routine which writes formatted data to the \fItrace\fR file. +.PP +Calling \fBtrace\fR with a nonzero parameter opens the file \fBtrace\fR +in the current directory for output. The parameter is formed by OR'ing +values from the list of \fBTRACE_\fP\fIxxx\fR definitions in \fB<curses.h>\fR. +These include: +.TP 5 +TRACE_DISABLE +turn off tracing. +.TP 5 +TRACE_TIMES +trace user and system times of updates. +.TP 5 +TRACE_TPUTS +trace tputs calls. +.TP 5 +TRACE_UPDATE +trace update actions, old & new screens. +.TP 5 +TRACE_MOVE +trace cursor movement and scrolling. +.TP 5 +TRACE_CHARPUT +trace all character outputs. +.TP 5 +TRACE_ORDINARY +trace all update actions. +The old and new screen contents are written to the trace file +for each refresh. +.TP 5 +TRACE_CALLS +trace all curses calls. +The parameters for each call are traced, as well as return values. +.TP 5 +TRACE_VIRTPUT +trace virtual character puts, i.e., calls to \fBaddch\fR. +.TP 5 +TRACE_IEVENT +trace low-level input processing, including timeouts. +.TP 5 +TRACE_BITS +trace state of TTY control bits. +.TP 5 +TRACE_ICALLS +trace internal/nested calls. +.TP 5 +TRACE_CCALLS +trace per-character calls. +.TP 5 +TRACE_DATABASE +trace read/write of terminfo/termcap data. +.TP 5 +TRACE_ATTRS +trace changes to video attributes and colors. +.TP 5 +TRACE_MAXIMUM +maximum trace level, enables all of the separate trace features. +.PP +Some tracing features are enabled whenever the \fBtrace\fR parameter +is nonzero. Some features overlap. +The specific names are used as a guideline. +.SH RETURN VALUE +Routines which return a value are designed to be used as parameters +to the \fB_tracef\fR routine. +.SH PORTABILITY +These functions are not part of the XSI interface. +Some other curses implementations are known to +have similar, undocumented features, +but they are not compatible with ncurses. +.SH SEE ALSO +\fBcurses\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_util.3x b/man/curs_util.3x new file mode 100644 index 000000000000..4c8929abfce7 --- /dev/null +++ b/man/curs_util.3x @@ -0,0 +1,226 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_util.3x,v 1.25 2007/05/26 21:44:42 tom Exp $ +.TH curs_util 3X "" +.na +.hy 0 +.SH NAME +\fBdelay_output\fR, +\fBfilter\fR, +\fBflushinp\fR, +\fBgetwin\fR, +\fBkey_name\fR, +\fBkeyname\fR, +\fBnofilter\fR, +\fBputwin\fR, +\fBunctrl\fR, +\fBuse_env\fR, +\fBwunctrl\fR - miscellaneous \fBcurses\fR utility routines +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBchar *unctrl(chtype c);\fR +.br +\fBwchar_t *wunctrl(cchar_t *c);\fR +.br +\fBchar *keyname(int c);\fR +.br +\fBchar *key_name(wchar_t w);\fR +.br +\fBvoid filter(void);\fR +.br +\fBvoid nofilter(void);\fR +.br +\fBvoid use_env(bool f);\fR +.br +\fBint putwin(WINDOW *win, FILE *filep);\fR +.br +\fBWINDOW *getwin(FILE *filep);\fR +.br +\fBint delay_output(int ms);\fR +.br +\fBint flushinp(void);\fR +.br +.SH DESCRIPTION +The \fBunctrl\fR routine returns a character string which is a printable +representation of the character \fIc\fR, ignoring attributes. +Control characters are displayed in the \fB^\fR\fIX\fR notation. +Printing characters are displayed as is. +The corresponding \fBwunctrl\fR returns a printable representation of +a wide-character. +.PP +The \fBkeyname\fR routine returns a character string corresponding to the key \fIc\fR. +Control characters are displayed in the \fB^\fR\fIX\fR notation. +Values above 128 are either meta characters, shown in the \fBM-\fR\fIX\fR notation, +or the names of function keys, or null. +The corresponding \fBkey_name\fR returns a character string corresponding +to the wide-character value \fIw\fR. +The two functions do not return the same set of strings; +the latter returns null where the former would display a meta character. +.PP +The \fBfilter\fR routine, if used, must be called before \fBinitscr\fR or +\fBnewterm\fR are called. The effect is that, during those calls, \fBLINES\fR +is set to 1; the capabilities \fBclear\fR, \fBcup\fR, \fBcud\fR, \fBcud1\fR, +\fBcuu1\fR, \fBcuu\fR, \fBvpa\fR are disabled; and the \fBhome\fR string is +set to the value of \fBcr\fR. +.PP +The \fBnofilter\fP routine cancels the effect of a preceding \fBfilter\fP +call. +That allows the caller to initialize a screen on a different device, +using a different value of \fB$TERM\fP. +The limitation arises because the \fBfilter\fP routine modifies the +in-memory copy of the terminal information. +.PP +The \fBuse_env\fR routine, if used, is called before \fBinitscr\fR or +\fBnewterm\fR are called. When called with \fBFALSE\fR as an +argument, the values of \fBlines\fR and \fBcolumns\fR specified in the +\fIterminfo\fR database will be used, even if environment variables +\fBLINES\fR and \fBCOLUMNS\fR (used by default) are set, or if +\fBcurses\fR is running in a window (in which case default behavior +would be to use the window size if \fBLINES\fR and \fBCOLUMNS\fR are +not set). +Note that setting \fBLINES\fR or \fBCOLUMNS\fR overrides the +corresponding size which may be obtained from the operating system. +.PP +The \fBputwin\fR routine writes all data associated with window \fIwin\fR into +the file to which \fIfilep\fR points. This information can be later retrieved +using the \fBgetwin\fR function. +.PP +The \fBgetwin\fR routine reads window related data stored in the file by +\fBputwin\fR. The routine then creates and initializes a new window using that +data. It returns a pointer to the new window. +.PP +The \fBdelay_output\fR routine inserts an \fIms\fR millisecond pause +in output. This routine should not be used extensively because +padding characters are used rather than a CPU pause. +If no padding character is specified, this uses \fBnapms\fR to perform the delay. +.PP +The \fBflushinp\fR routine throws away any typeahead that has been typed by the +user and has not yet been read by the program. +.SH RETURN VALUE +Except for \fBflushinp\fR, routines that return an integer return \fBERR\fR +upon failure and \fBOK\fR (SVr4 specifies only "an integer value other than +\fBERR\fR") upon successful completion. +.PP +Routines that return pointers return \fBNULL\fR on error. +.PP +X/Open does not define any error conditions. +In this implementation +.RS +.TP 5 +\fBflushinp\fR +returns an error if the terminal was not initialized. +.TP 5 +\fBputwin\fP +returns an error if the associated \fBfwrite\fP calls return an error. +.RE +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +It states that \fBunctrl\fR and \fBwunctrl\fR will return a null pointer if +unsuccessful, but does not define any error conditions. +This implementation checks for three cases: +.RS +.TP 5 +- +the parameter is a 7-bit US-ASCII code. +This is the case that X/Open Curses documented. +.TP 5 +- +the parameter is in the range 128-159, i.e., a C1 control code. +If \fBuse_legacy_coding\fP has been called with a \fB2\fP parameter, +\fBunctrl\fP 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 controls. +.IP +X/Open Curses does not document whether \fBunctrl\fP can be called before +initializing curses. +This implementation permits that, +and returns the ``~@'', etc., values in that case. +.TP 5 +- +parameter values outside the 0 to 255 range. +\fBunctrl\fP returns a null pointer. +.RE +.PP +The SVr4 documentation describes the action of \fBfilter\fR only in the vaguest +terms. The description here is adapted from the XSI Curses standard (which +erroneously fails to describe the disabling of \fBcuu\fR). +.PP +The strings returned by \fBunctrl\fR 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 +printable. +This implementation uses 8 bits but does not modify the string to reflect +locale. +The \fBuse_legacy_coding\fP function allows the caller to +change the output of \fBunctrl\fP. +.PP +Likewise, the \fBmeta\fP function allows the caller to change the +output of \fBkeyname\fP, i.e., +it determines whether to use the `M-' prefix +for ``meta'' keys (codes in the range 128 to 255). +Both \fBuse_legacy_coding\fP and \fBmeta\fP 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 \fBkeyname\fP is called before initializing curses), +this implementation returns strings ``M-^@'', ``M-^A'', etc. +.PP +The \fBkeyname\fP function may return the names of user-defined +string capabilities which are defined in the terminfo entry via the \fB-x\fP +option of \fBtic\fP. +This implementation automatically 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. +.PP +The \fBnofilter\fP 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 extensions +be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBlegacy_coding\fR(3X), +\fBcurses\fR(3X), +\fBcurs_initscr\fR(3X), +\fBcurs_kernel\fR(3X), +\fBcurs_scr_dump\fR(3X), +\fBlegacy_coding\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/curs_window.3x b/man/curs_window.3x new file mode 100644 index 000000000000..552862e9e253 --- /dev/null +++ b/man/curs_window.3x @@ -0,0 +1,188 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_window.3x,v 1.14 2006/02/25 21:49:19 tom Exp $ +.TH curs_window 3X "" +.na +.hy 0 +.SH NAME +\fBnewwin\fR, +\fBdelwin\fR, +\fBmvwin\fR, +\fBsubwin\fR, +\fBderwin\fR, +\fBmvderwin\fR, +\fBdupwin\fR, +\fBwsyncup\fR, +\fBsyncok\fR, +\fBwcursyncup\fR, +\fBwsyncdown\fR - create \fBcurses\fR windows +.ad +.hy +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBWINDOW *newwin(int nlines, int ncols, int begin_y,\fR + \fBint begin_x);\fR +.br +\fBint delwin(WINDOW *win);\fR +.br +\fBint mvwin(WINDOW *win, int y, int x);\fR +.br +\fBWINDOW *subwin(WINDOW *orig, int nlines, int ncols,\fR + \fBint begin_y, int begin_x);\fR +.br +\fBWINDOW *derwin(WINDOW *orig, int nlines, int ncols,\fR + \fBint begin_y, int begin_x);\fR +.br +\fBint mvderwin(WINDOW *win, int par_y, int par_x);\fR +.br +\fBWINDOW *dupwin(WINDOW *win);\fR +.br +\fBvoid wsyncup(WINDOW *win);\fR +.br +\fBint syncok(WINDOW *win, bool bf);\fR +.br +\fBvoid wcursyncup(WINDOW *win);\fR +.br +\fBvoid wsyncdown(WINDOW *win);\fR +.br +.SH DESCRIPTION +Calling \fBnewwin\fR creates and returns a pointer to a new window with the +given number of lines and columns. The upper left-hand corner of the window is +at line \fIbegin\fR_\fIy\fR, column \fIbegin\fR_\fIx\fR. If either +\fInlines\fR or \fIncols\fR is zero, they default to \fBLINES -\fR +\fIbegin\fR_\fIy\fR and \fBCOLS -\fR \fIbegin\fR_\fIx\fR. A new full-screen +window is created by calling \fBnewwin(0,0,0,0)\fR. +.PP +Calling \fBdelwin\fR deletes the named window, freeing all memory +associated with it (it does not actually erase the window's screen +image). Subwindows must be deleted before the main window can be +deleted. +.PP +Calling \fBmvwin\fR moves the window so that the upper left-hand +corner is at position (\fIx\fR, \fIy\fR). If the move would cause the +window to be off the screen, it is an error and the window is not +moved. Moving subwindows is allowed, but should be avoided. +.PP +Calling \fBsubwin\fR creates and returns a pointer to a new window +with the given number of lines, \fInlines\fR, and columns, +\fIncols\fR. The window is at position (\fIbegin\fR_\fIy\fR, +\fIbegin\fR_\fIx\fR) on the screen. (This position is relative to the +screen, and not to the window \fIorig\fR.) The window is made in the +middle of the window \fIorig\fR, so that changes made to one window +will affect both windows. The subwindow shares memory with the window +\fIorig\fR. When using this routine, it is necessary to call +\fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before calling +\fBwrefresh\fR on the subwindow. +.PP +Calling \fBderwin\fR is the same as calling \fBsubwin,\fR except that +\fIbegin\fR_\fIy\fR and \fIbegin\fR_\fIx\fR are relative to the origin +of the window \fIorig\fR rather than the screen. There is no +difference between the subwindows and the derived windows. +.PP +Calling \fBmvderwin\fR moves a derived window (or subwindow) +inside its parent window. The screen-relative parameters of the +window are not changed. This routine is used to display different +parts of the parent window at the same physical position on the +screen. +.PP +Calling \fBdupwin\fR creates an exact duplicate of the window \fIwin\fR. +.PP +Calling \fBwsyncup\fR touches all locations in ancestors of \fIwin\fR that are +changed in \fIwin\fR. If \fBsyncok\fR is called with second argument +\fBTRUE\fR then \fBwsyncup\fR is called automatically whenever there is a +change in the window. +.PP +The \fBwsyncdown\fR routine touches each location in \fIwin\fR that has been +touched in any of its ancestor windows. This routine is called by +\fBwrefresh\fR, so it should almost never be necessary to call it manually. +.PP +The routine \fBwcursyncup\fR updates the current cursor position of all the +ancestors of the window to reflect the current cursor position of the +window. +.SH RETURN VALUE +Routines that return an integer return the integer \fBERR\fR upon failure and +\fBOK\fR (SVr4 only specifies "an integer value other than \fBERR\fR") upon +successful completion. +.PP +Routines that return pointers return \fBNULL\fR on error. +.PP +X/Open defines no error conditions. +In this implementation +.RS +.TP 5 +\fBdelwin\fR +returns an error if the window pointer is null, or +if the window is the parent of another window. +.IP +This implementation also maintains a list of windows, +and checks that the pointer passed to \fBdelwin\fP is one that +it created, returning an error if it was not.. +.TP 5 +\fBmvderwin\fP +returns an error +if the window pointer is null, or +if some part of the window would be placed off-screen. +.TP 5 +\fBmvwin\fP +returns an error +if the window pointer is null, or +if the window is really a pad, or +if some part of the window would be placed off-screen. +.TP 5 +\fBsyncok\fP +returns an error +if the window pointer is null. +.RE +.SH NOTES +If many small changes are made to the window, the \fBwsyncup\fR option could +degrade performance. +.PP +Note that \fBsyncok\fR may be a macro. +.SH BUGS +The subwindow functions (\fIsubwin\fR, \fIderwin\fR, \fImvderwin\fR, +\fBwsyncup\fR, \fBwsyncdown\fR, \fBwcursyncup\fR, \fBsyncok\fR) are flaky, +incompletely implemented, and not well tested. +.PP +The System V curses documentation is very unclear about what \fBwsyncup\fR +and \fBwsyncdown\fR actually do. It seems to imply that they are only +supposed to touch exactly those lines that are affected by ancestor changes. +The language here, and the behavior of the \fBcurses\fR implementation, +is patterned on the XPG4 curses standard. The weaker XPG4 spec may result +in slower updates. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +.SH SEE ALSO +\fBcurses\fR(3X), \fBcurs_refresh\fR(3X), \fBcurs_touch\fR(3X) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/default_colors.3x b/man/default_colors.3x new file mode 100644 index 000000000000..32518ba9d9cf --- /dev/null +++ b/man/default_colors.3x @@ -0,0 +1,144 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1997,1999,2000,2005 +.\" +.\" $Id: default_colors.3x,v 1.20 2006/12/24 15:02:53 tom Exp $ +.TH default_colors 3X "" +.SH NAME +\fBuse_default_colors\fR, +\fBassume_default_colors\fR \- use terminal's default colors +.SH SYNOPSIS +\fB#include <curses.h>\fP +.sp +\fBint use_default_colors(void);\fP +.br +\fBint assume_default_colors(int fg, int bg);\fP +.SH DESCRIPTION +The +.I use_default_colors() +and +.I assume_default_colors() +functions are extensions to the curses library. +They are used with terminals that support ISO 6429 color, or equivalent. +These terminals allow the application to reset color to an unspecified +default value (e.g., with SGR 39 or SGR 49). +.PP +Applications that paint a colored background over the whole screen +do not take advantage of SGR 39 and SGR 49. +Some applications are designed to work with the default background, +using colors only for text. +For example, there are several implementations of the \fBls\fP program +which use colors to denote different file types or permissions. +These "color ls" programs do not necessarily modify the background color, +typically using only the \fIsetaf\fP terminfo capability to set the +foreground color. +Full-screen applications that use default colors can achieve similar +visual effects. +.PP +The first function, +.I use_default_colors() +tells the curses library to assign terminal default +foreground/background colors to color number -1. So init_pair(x,COLOR_RED,-1) +will initialize pair x as red on default background and init_pair(x,-1,COLOR_BLUE) will +initialize pair x as default foreground on blue. +.PP +The other, +.I assume_default_colors() +is a refinement which tells which colors to paint for color pair 0. +This function recognizes a special color number -1, +which denotes the default terminal color. +.PP +The following are equivalent: +.RS +.br +.I use_default_colors(); +.br +.I assume_default_colors(-1,-1); +.RE +.PP +These are ncurses extensions. +For other curses implementations, color +number -1 does not mean anything, just as for ncurses before a +successful call of \fIuse_default_colors()\fP or \fIassume_default_colors()\fP. +.PP +Other curses implementations do not allow an application to modify color pair 0. +They assume that the background is COLOR_BLACK, +but do not ensure that the color pair 0 is painted to match the +assumption. +If your application does not use either +.I use_default_colors() +or +.I assume_default_colors() +ncurses will paint a white foreground (text) with black background +for color pair 0. +.SH RETURN VALUE +These functions return the integer \fBERR\fP upon failure and \fBOK\fP on success. +They will fail if either the terminal does not support +the \fIorig_pair\fP or \fIorig_colors\fP capability. +If the \fIinitialize_pair\fP capability is found, this causes an +error as well. +.SH NOTES +Associated with this extension, the \fBinit_pair\fR function accepts +negative arguments to specify default foreground or background colors. +.PP +The \fIuse_default_colors()\fP function was added to support \fIded\fP. +This is a full-screen application which uses curses to manage only part +of the screen. The bottom portion of the screen, which is of adjustable +size, is left uncolored to display the results from shell commands. +The top portion of the screen colors filenames using a scheme like the +"color ls" programs. +Attempting to manage the background color of the screen for this application +would give unsatisfactory results for a variety of reasons. +This extension was devised after +noting that color xterm (and similar programs) provides a background color +which does not necessarily correspond to any of the ANSI colors. +While a special terminfo entry could be constructed using nine colors, +there was no mechanism provided within curses to account for the related +\fIorig_pair\fP and \fIback_color_erase\fP capabilities. +.PP +The \fIassume_default_colors()\fP function was added to solve +a different problem: support for applications which would use +environment variables and other configuration to bypass curses' +notion of the terminal's default colors, setting specific values. +.SH PORTABILITY +These 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 them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBcurs_color\fR(3X), +\fBded\fP(1). +.SH AUTHOR +Thomas Dickey (from an analysis of the requirements for color xterm +for XFree86 3.1.2C, February 1996). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/define_key.3x b/man/define_key.3x new file mode 100644 index 000000000000..216a3cbce4b6 --- /dev/null +++ b/man/define_key.3x @@ -0,0 +1,65 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2004,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1997 +.\" +.\" $Id: define_key.3x,v 1.12 2006/02/25 21:49:19 tom Exp $ +.TH define_key 3X "" +.SH NAME +\fBdefine_key\fP \- define a keycode +.SH SYNOPSIS +\fB#include <curses.h>\fP +.sp +\fBint define_key(const char *definition, int keycode);\fP +.SH DESCRIPTION +This is an extension to the curses library. +It permits an application to define keycodes with their corresponding control +strings, so that the ncurses library will interpret them just as it would +the predefined codes in the terminfo database. +.PP +If the given string is null, any existing definition for the keycode is +removed. +Similarly, if the given keycode is negative or zero, any existing string +for the given definition is removed. +.SH RETURN VALUE +The keycode must be greater than zero, else ERR is returned. +.SH PORTABILITY +These 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 them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBkeyok\fR(3X), +\fBkey_defined\fR(3X). +.SH AUTHOR +Thomas Dickey. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form.3x b/man/form.3x new file mode 100644 index 000000000000..75fc78aee2d4 --- /dev/null +++ b/man/form.3x @@ -0,0 +1,208 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2008 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form.3x,v 1.21 2008/04/26 17:11:52 tom Exp $ +.TH form 3X "" +.SH NAME +\fBform\fR - curses extension for programming forms +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +.SH DESCRIPTION +The \fBform\fR library provides terminal-independent facilities for composing +form screens on character-cell terminals. The library includes: field +routines, which create and modify form fields; and form routines, which group +fields into forms, display forms on the screen, and handle interaction with the +user. +.PP +The \fBform\fR library uses the \fBcurses\fR libraries, and a curses +initialization routine such as \fBinitscr\fR must be called before using any of +these functions. To use the \fBform\fR library, link with the options +\fB-lform -lcurses\fR. +. +.SS Current Default Values for Field Attributes +. +The \fBform\fR library maintains a default value for field attributes. You +can get or set this default by calling the appropriate \fBset_\fR +or retrieval +routine with a \fBNULL\fR field pointer. Changing this default with a +\fBset_\fR function affects future field creations, but does not change the +rendering of fields already created. +. +.SS Routine Name Index +. +The following table lists each \fBform\fR routine and the name of +the manual page on which it is described. +. +.TS +l l +l l . +\fBcurses\fR Routine Name Manual Page Name += +current_field \fBform_page\fR(3X) +data_ahead \fBform_data\fR(3X) +data_behind \fBform_data\fR(3X) +dup_field \fBform_field_new\fR(3X) +dynamic_field_info \fBform_field_info\fR(3X) +field_arg \fBform_field_validation\fR(3X) +field_back \fBform_field_attributes\fR(3X) +field_buffer \fBform_field_buffer\fR(3X) +field_count \fBform_field\fR(3X) +field_fore \fBform_field_attributes\fR(3X) +field_index \fBform_page\fR(3X) +field_info \fBform_field_info\fR(3X) +field_init \fBform_hook\fR(3X) +field_just \fBform_field_just\fR(3X) +field_opts \fBform_field_opts\fR(3X) +field_opts_off \fBform_field_opts\fR(3X) +field_opts_on \fBform_field_opts\fR(3X) +field_pad \fBform_field_attributes\fR(3X) +field_status \fBform_field_buffer\fR(3X) +field_term \fBform_hook\fR(3X) +field_type \fBform_field_validation\fR(3X) +field_userptr \fBform_field_userptr\fR(3X) +form_driver \fBform_driver\fR(3X) +form_fields \fBform_field\fR(3X) +form_init \fBform_hook\fR(3X) +form_opts \fBform_opts\fR(3X) +form_opts_off \fBform_opts\fR(3X) +form_opts_on \fBform_opts\fR(3X) +form_page \fBform_page\fR(3X) +form_request_by_name \fBform_requestname\fR(3X) +form_request_name \fBform_requestname\fR(3X) +form_sub \fBform_win\fR(3X) +form_term \fBform_hook\fR(3X) +form_userptr \fBform_userptr\fR(3X) +form_win \fBform_win\fR(3X) +free_field \fBform_field_new\fR(3X) +free_fieldtype \fBform_fieldtype\fR(3X) +free_form \fBform_new\fR(3X) +link_field \fBform_field_new\fR(3X) +link_fieldtype \fBform_fieldtype\fR(3X) +move_field \fBform_field\fR(3X) +new_field \fBform_field_new\fR(3X) +new_fieldtype \fBform_fieldtype\fR(3X) +new_form \fBform_new\fR(3X) +new_page \fBform_new_page\fR(3X) +pos_form_cursor \fBform_cursor\fR(3X) +post_form \fBform_post\fR(3X) +scale_form \fBform_win\fR(3X) +set_current_field \fBform_page\fR(3X) +set_field_back \fBform_field_attributes\fR(3X) +set_field_buffer \fBform_field_buffer\fR(3X) +set_field_fore \fBform_field_attributes\fR(3X) +set_field_init \fBform_hook\fR(3X) +set_field_just \fBform_field_just\fR(3X) +set_field_opts \fBform_field_opts\fR(3X) +set_field_pad \fBform_field_attributes\fR(3X) +set_field_status \fBform_field_buffer\fR(3X) +set_field_term \fBform_hook\fR(3X) +set_field_type \fBform_field_validation\fR(3X) +set_field_userptr \fBform_field_userptr\fR(3X) +set_fieldtype_arg \fBform_fieldtype\fR(3X) +set_fieldtype_choice \fBform_fieldtype\fR(3X) +set_form_fields \fBform_field\fR(3X) +set_form_init \fBform_hook\fR(3X) +set_form_opts \fBform_field_opts\fR(3X) +set_form_page \fBform_page\fR(3X) +set_form_sub \fBform_win\fR(3X) +set_form_term \fBform_hook\fR(3X) +set_form_userptr \fBform_userptr\fR(3X) +set_form_win \fBform_win\fR(3X) +set_max_field \fBform_field_buffer\fR(3X) +set_new_page \fBform_new_page\fR(3X) +unpost_form \fBform_post\fR(3X) +.TE +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fR on error, +and set errno to the corresponding error-code returned by functions +returning an integer. +Routines that return +an integer return one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_CONNECTED +The field is already connected to a form. +.TP 5 +.B E_INVALID_FIELD +Contents of a field are not valid. +.TP 5 +.B E_NOT_CONNECTED +No fields are connected to the form. +.TP 5 +.B E_NOT_POSTED +The form has not been posted. +.TP 5 +.B E_NO_ROOM +Form is too large for its window. +.TP 5 +.B E_POSTED +The form is already posted. +.TP 5 +.B E_REQUEST_DENIED +The form driver could not process the request. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_UNKNOWN_COMMAND +The form driver code saw an unknown request code. +.SH SEE ALSO +\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header files +\fB<curses.h>\fR and \fB<eti.h>\fR. +.PP +In your library list, libform.a should be before libncurses.a; that is, +you want to say `-lform -lncurses', not the other way around (which would +give you a link error using most linkers). +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric +S. Raymond. +.SH SEE ALSO +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_cursor.3x b/man/form_cursor.3x new file mode 100644 index 000000000000..bf9f28d6c61e --- /dev/null +++ b/man/form_cursor.3x @@ -0,0 +1,75 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_cursor.3x,v 1.6 2006/11/04 18:50:24 tom Exp $ +.TH form_cursor 3X "" +.SH NAME +\fBform_cursor\fR - position a form window cursor +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int pos_form_cursor(FORM *form); +.br +.SH DESCRIPTION +The function \fBpos_form_cursor\fR restores the cursor to the position required +for the forms driver to continue processing requests. This is useful after +\fBcurses\fR routines have been called to do screen-painting in response to a +form operation. +.SH RETURN VALUE +This routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_NOT_POSTED +The form has not been posted. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +. +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_data.3x b/man/form_data.3x new file mode 100644 index 000000000000..2ba004c3387e --- /dev/null +++ b/man/form_data.3x @@ -0,0 +1,63 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_data.3x,v 1.8 2006/02/25 21:38:26 tom Exp $ +.TH form_data 3X "" +.SH NAME +\fBform_data\fR - test for off-screen data in given forms +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +bool data_ahead(const FORM *form); +.br +bool data_behind(const FORM *form); +.br +.SH DESCRIPTION +The function \fBdata_ahead\fR tests whether there is off-screen data +ahead in the given form. It returns TRUE (1) or FALSE (0). +.PP +The function \fBdata_behind\fR tests whether there is off-screen data +behind in the given form. It returns TRUE (1) or FALSE (0). +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_driver.3x b/man/form_driver.3x new file mode 100644 index 000000000000..85b1df8277d6 --- /dev/null +++ b/man/form_driver.3x @@ -0,0 +1,324 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_driver.3x,v 1.15 2007/06/02 22:56:49 tom Exp $ +.TH form_driver 3X "" +.SH NAME +\fBform_driver\fR - command-processing loop of the form system +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int form_driver(FORM *form, int c); +.br +.SH DESCRIPTION +Once a form has been posted (displayed), you should funnel input events to it +through \fBform_driver\fR. This routine has two major input cases; either +the input is a form navigation request or it is a printable ASCII character. +The form driver requests are as follows: +.TP 5 +REQ_NEXT_PAGE +Move to the next page. +.TP 5 +REQ_PREV_PAGE +Move to the previous page. +.TP 5 +REQ_FIRST_PAGE +Move to the first page. +.TP 5 +REQ_LAST_PAGE +Move to the last field. +.sp +.TP 5 +REQ_NEXT_FIELD +Move to the next field. +.TP 5 +REQ_PREV_FIELD +Move to the previous field. +.TP 5 +REQ_FIRST_FIELD +Move to the first field. +.TP 5 +REQ_LAST_FIELD +Move to the last field. +.TP 5 +REQ_SNEXT_FIELD +Move to the sorted next field. +.TP 5 +REQ_SPREV_FIELD +Move to the sorted previous field. +.TP 5 +REQ_SFIRST_FIELD +Move to the sorted first field. +.TP 5 +REQ_SLAST_FIELD +Move to the sorted last field. +.TP 5 +REQ_LEFT_FIELD +Move left to a field. +.TP 5 +REQ_RIGHT_FIELD +Move right to a field. +.TP 5 +REQ_UP_FIELD +Move up to a field. +.TP 5 +REQ_DOWN_FIELD +Move down to a field. +.sp +.TP 5 +REQ_NEXT_CHAR +Move to the next char. +.TP 5 +REQ_PREV_CHAR +Move to the previous char. +.TP 5 +REQ_NEXT_LINE +Move to the next line. +.TP 5 +REQ_PREV_LINE +Move to the previous line. +.TP 5 +REQ_NEXT_WORD +Move to the next word. +.TP 5 +REQ_PREV_WORD +Move to the previous word. +.TP 5 +REQ_BEG_FIELD +Move to the beginning of the field. +.TP 5 +REQ_END_FIELD +Move to the end of the field. +.TP 5 +REQ_BEG_LINE +Move to the beginning of the line. +.TP 5 +REQ_END_LINE +Move to the end of the line. +.TP 5 +REQ_LEFT_CHAR +Move left in the field. +.TP 5 +REQ_RIGHT_CHAR +Move right in the field. +.TP 5 +REQ_UP_CHAR +Move up in the field. +.TP 5 +REQ_DOWN_CHAR +Move down in the field. +.sp +.TP 5 +REQ_NEW_LINE +Insert or overlay a new line. +.TP 5 +REQ_INS_CHAR +Insert a blank at the cursor. +.TP 5 +REQ_INS_LINE +Insert a blank line at the cursor. +.TP 5 +REQ_DEL_CHAR +Delete character at the cursor. +.TP 5 +REQ_DEL_PREV +Delete character before the cursor. +.TP 5 +REQ_DEL_LINE +Delete line at the cursor. +.TP 5 +REQ_DEL_WORD +Delete blank-delimited word at the cursor. +.TP 5 +REQ_CLR_EOL +Clear to end of line from cursor. +.TP 5 +REQ_CLR_EOF +Clear to end of field from cursor. +.TP 5 +REQ_CLR_FIELD +Clear the entire field. +.TP 5 +REQ_OVL_MODE +Enter overlay mode. +.TP 5 +REQ_INS_MODE +Enter insert mode. +.sp +.TP 5 +REQ_SCR_FLINE +Scroll the field forward a line. +.TP 5 +REQ_SCR_BLINE +Scroll the field backward a line. +.TP 5 +REQ_SCR_FPAGE +Scroll the field forward a page. +.TP 5 +REQ_SCR_BPAGE +Scroll the field backward a page. +.TP 5 +REQ_SCR_FHPAGE +Scroll the field forward half a page. +.TP 5 +REQ_SCR_BHPAGE +Scroll the field backward half a page. +.sp +.TP 5 +REQ_SCR_FCHAR +Scroll the field forward a character. +.TP 5 +REQ_SCR_BCHAR +Scroll the field backward a character. +.TP 5 +REQ_SCR_HFLINE +Horizontal scroll the field forward a line. +.TP 5 +REQ_SCR_HBLINE +Horizontal scroll the field backward a line. +.TP 5 +REQ_SCR_HFHALF +Horizontal scroll the field forward half a line. +.TP 5 +REQ_SCR_HBHALF +Horizontal scroll the field backward half a line. +.sp +.TP +REQ_VALIDATION +Validate field. +.TP +REQ_NEXT_CHOICE +Display next field choice. +.TP +REQ_PREV_CHOICE +Display previous field choice. +.PP +If the second argument is a printable ASCII character, the driver places it +in the current position in the current field. If it is one of the forms +requests listed above, that request is executed. +.SS MOUSE HANDLING +.PP +If the second argument is the KEY_MOUSE special key, the associated +mouse event is translated into one of the above pre-defined requests. +Currently only clicks in the user window (e.g. inside the form display +area or the decoration window) are handled. +.PP +If you click above the display region of the form: +.RS +.TP +a REQ_PREV_FIELD is generated for a single click, +.TP +a REQ_PREV_PAGE is generated for a double-click and +.TP +a REQ_FIRST_FIELD is generated for a triple-click. +.RE +.PP +If you click below the display region of the form: +.RS +.TP +a REQ_NEXT_FIELD is generated for a single click, +.TP +a REQ_NEXT_PAGE is generated for a double-click and +.TP +a REQ_LAST_FIELD is generated for a triple-click. +.RE +.PP +If you click at an field inside the display area of the form: +.RS +.TP 3 +- +the form cursor is positioned to that field. +.TP 3 +- +If you double-click a field, +the form cursor is positioned to that field +and \fBE_UNKNOWN_COMMAND\fR is returned. +This return value makes sense, +because a double click usually means that an field-specific action should +be returned. +It is exactly the purpose of this return value to signal that an +application specific command should be executed. +.TP 3 +- +If a translation +into a request was done, \fBform_driver\fR returns the result of this request. +.RE +.PP +If you clicked outside the user window or the mouse event couldn't be translated +into a form request an \fBE_REQUEST_DENIED\fR is returned. +.SS APPLICATION-DEFINED COMMANDS +.PP +If the second argument is neither printable ASCII nor one of the above +pre-defined form requests, the driver assumes it is an application-specific +command and returns \fBE_UNKNOWN_COMMAND\fR. Application-defined commands +should be defined relative to \fBMAX_COMMAND\fR, the maximum value of these +pre-defined requests. +.SH RETURN VALUE +\fBform_driver\fR returns one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NOT_POSTED +The form has not been posted. +.TP 5 +.B E_INVALID_FIELD +Contents of field is invalid. +.TP 5 +.B E_REQUEST_DENIED +The form driver could not process the request. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_UNKNOWN_COMMAND +The form driver code saw an unknown request code. +. +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header files +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_field.3x b/man/form_field.3x new file mode 100644 index 000000000000..f3a26c57dac0 --- /dev/null +++ b/man/form_field.3x @@ -0,0 +1,98 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field.3x,v 1.8 2006/11/04 18:01:38 tom Exp $ +.TH form_field 3X "" +.SH NAME +\fBform_field\fR - make and break connections between fields and forms +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_form_fields(FORM *form, FIELD **fields); +.br +FIELD **form_fields(const FORM *form); +.br +int field_count(const FORM *form); +.br +int move_field(FIELD *field, int frow, int fcol); +.br +.SH DESCRIPTION +The function \fBset_form_fields\fR changes the field pointer array of +the given \fIform\fR. The array must be terminated by a \fBNULL\fR. +.PP +The function \fBform_fields\fR returns the field array of the given form. +.PP +The function \fBfield_count\fR returns the count of fields in \fIform\fR. +.PP +The function \fBmove_field\fR moves the given field (which must be disconnected) +to a specified location on the screen. +.SH RETURN VALUES +The function \fBform_fields\fR returns a pointer (which may be \fBNULL\fR). +It does not set errno. +.PP +The function \fBfield_count\fR returns \fBERR\fR if the \fIform\fP parameter +is \fBNULL\fP. +.PP +The functions \fBset_form_fields\fR and \fBmove_field\fR return one of +the following codes on error: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CONNECTED +The field is already connected to a form. +.TP 5 +.B E_POSTED +The form is already posted. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.PP +The SVr4 forms library documentation specifies the \fBfield_count\fR error value +as -1 (which is the value of \fBERR\fR). +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_field_attributes.3x b/man/form_field_attributes.3x new file mode 100644 index 000000000000..90dc0f31b63b --- /dev/null +++ b/man/form_field_attributes.3x @@ -0,0 +1,92 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2002,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_attributes.3x,v 1.10 2006/11/04 18:51:26 tom Exp $ +.TH form_field_attributes 3X "" +.SH NAME +\fBform_field_attributes\fR - color and attribute control for form fields +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_field_fore(FIELD *field, chtype attr); +.br +chtype field_fore(const FIELD *field); +.br +int set_field_back(FIELD *field, chtype attr); +.br +chtype field_back(const FIELD *field); +.br +int set_field_pad(FIELD *field, int pad); +.br +int field_pad(const FIELD *field); +.br +.SH DESCRIPTION +The function \fBset_field_fore\fR sets the foreground attribute of +\fIfield\fR. This is the highlight used to display the field contents. The +function \fBfield_fore\fR returns the foreground attribute. The default is +\fBA_STANDOUT\fR. +.PP +The function \fBset_field_back\fR sets the background attribute of +\fIform\fR. This is the highlight used to display the extent fields in the +form. The function \fBfield_back\fR returns the background attribute. The +default is \fBA_NORMAL\fR. +.PP +The function \fBset_field_pad\fR sets the character used to fill the field. +The function \fBfield_pad\fR returns the given form's pad character. The +default is a blank. +.SH RETURN VALUE +These routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +. +.SH SEE ALSO +\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_field_buffer.3x b/man/form_field_buffer.3x new file mode 100644 index 000000000000..cac6a088e5ed --- /dev/null +++ b/man/form_field_buffer.3x @@ -0,0 +1,112 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_buffer.3x,v 1.14 2006/11/04 17:12:00 tom Exp $ +.TH form_field_buffer 3X "" +.SH NAME +\fBform_field_buffer\fR - field buffer control +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_field_buffer(FIELD *field, int buf, const char *value); +.br +char *field_buffer(const FIELD *field, int buffer); +.br +int set_field_status(FIELD *field, bool status); +.br +bool field_status(const FIELD *field); +.br +int set_max_field(FIELD *field, int max); +.br +.SH DESCRIPTION +The function \fBset_field_buffer\fR sets the numbered buffer of the given field +to contain a given string. Buffer 0 is the displayed value of the field; other +numbered buffers may be allocated by applications through the \fBnbuf\fR +argument of (see \fBform_field_new\fR(3X)) but are not manipulated by the forms +library. The function \fBfield_buffer\fR returns the address of the buffer. +Please note that this buffer has always the length of the buffer, that means +that it may typically contain trailing spaces. If you entered leading spaces +the buffer may also contain them. If you want the raw data, you must write your +own routine that copies the value out of the buffer and removes the leading +and trailing spaces. Please note also, that subsequent operations on the form +will probably change the content of the buffer. So do not use it for long term +storage of the entered form data. +.PP +The function \fBset_field_status\fR sets the associated status flag of +\fIfield\fR; \fBfield_status\fR gets the current value. The status flag +is set to a nonzero value whenever the field changes. +.PP +The function \fBset_max_field\fR sets the maximum size for a dynamic field. +An argument of 0 turns off any maximum size threshold for that field. +.SH RETURN VALUE +The \fBfield_buffer\fR function returns NULL on error. +It sets errno according to their success: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.PP +The \fBfield_status\fR function returns \fBTRUE\fR or \fBFALSE\fR. +.PP +The remaining routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.SH SEE ALSO +\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +.PP +When configured for wide-characters, \fBfield_buffer\fP returns a pointer +to temporary storage (allocated and freed by the library). +The application should not attempt to modify the data. +It will be freed on the next call to \fBfield_buffer\fP to return the +same buffer. +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_field_info.3x b/man/form_field_info.3x new file mode 100644 index 000000000000..bde312856951 --- /dev/null +++ b/man/form_field_info.3x @@ -0,0 +1,85 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_info.3x,v 1.10 2006/11/04 17:14:31 tom Exp $ +.TH form_field_info 3X "" +.SH NAME +\fBform_field_info\fR - retrieve field characteristics +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int field_info(const FIELD *field, int *rows, int *cols, + int *frow, int *fcol, int *nrow, int *nbuf); +.br +int dynamic_field_info(const FIELD *field, int *rows, int *cols, int *max); +.br +.SH DESCRIPTION +The function \fBfield_info\fR returns the sizes and other attributes passed in +to the field at its creation time. The attributes are: height, width, row of +upper-left corner, column of upper-left corner, number off-screen rows, and +number of working buffers. +.PP +The function \fBdynamic_field_info\fR returns the actual size of the field, and +its maximum possible size. If the field has no size limit, the location +addressed by the third argument will be set to 0. +A field can be made dynamic +by turning off the \fBO_STATIC\fR option with \fBfield_opts_off\fR. +.SH RETURN VALUE +These routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.SH SEE ALSO +\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.PP +A null (zero pointer) is accepted for any of the return values, +to ignore that value. +Not all implementations allow this, e.g., Solaris 2.7 does not. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_field_just.3x b/man/form_field_just.3x new file mode 100644 index 000000000000..15d6cb254df1 --- /dev/null +++ b/man/form_field_just.3x @@ -0,0 +1,78 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_just.3x,v 1.9 2006/11/04 17:12:00 tom Exp $ +.TH form_field_just 3X "" +.SH NAME +\fBform_field_just\fR - retrieve field characteristics +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_field_just(FIELD *field, int justification); +.br +int field_just(const FIELD *field); +.br +.SH DESCRIPTION +The function \fBset_field_just\fR sets the justification attribute of +a field; \fBfield_just\fR returns a field's justification attribute. +The attribute may be one of NO_JUSTIFICATION, JUSTIFY_RIGHT, +JUSTIFY_LEFT, or JUSTIFY_CENTER. +. +.SH RETURN VALUE +The function \fBfield_just\fR returns one of: NO_JUSTIFICATION, +JUSTIFY_RIGHT, JUSTIFY_LEFT, or JUSTIFY_CENTER. +.PP +The function \fBset_field_just\fR returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.SH SEE ALSO +\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_field_new.3x b/man/form_field_new.3x new file mode 100644 index 000000000000..6095de1ccbb2 --- /dev/null +++ b/man/form_field_new.3x @@ -0,0 +1,106 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_new.3x,v 1.16 2007/06/02 20:40:07 tom Exp $ +.TH form_field_new 3X "" +.SH NAME +\fBform_field_new\fR - create and destroy form fields +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +FIELD *new_field(int height, int width, + int toprow, int leftcol, + int offscreen, int nbuffers); +.br +FIELD *dup_field(FIELD *field, int toprow, int leftcol); +.br +FIELD *link_field(FIELD *field, int toprow, int leftcol); +.br +int free_field(FIELD *field); +.br +.SH DESCRIPTION +The function \fBnew_field\fR allocates a new field and initializes it from the +parameters given: height, width, row of upper-left corner, column of upper-left +corner, number off-screen rows, and number of additional working buffers. +.PP +The function \fBdup_field\fR duplicates a field at a new location. Most +attributes (including current contents, size, validation type, buffer count, +growth threshold, justification, foreground, background, pad character, +options, and user pointer) are copied. Field status and the field page bit are +not copied. +.PP +The function \fBlink_field\fR acts like \fBdup_field\fR, but the new field +shares buffers with its parent. Attribute data is separate. +.PP +The function \fBfree_field\fR de-allocates storage associated with a field. +.SH RETURN VALUE +The function, \fBnew_field\fR, \fBdup_field\fR, \fBlink_field\fR return +\fBNULL\fR on error. +They set errno according to their success: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred, e.g., malloc failure. +.PP +The function \fBfree_field\fR returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CONNECTED +field is connected. +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.PP +It may be unwise to count on the set of attributes copied by +\fBdup_field\fR being portable; the System V forms library documents are +not very explicit about what gets copied and what does not. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_field_opts.3x b/man/form_field_opts.3x new file mode 100644 index 000000000000..d505279ceb20 --- /dev/null +++ b/man/form_field_opts.3x @@ -0,0 +1,124 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_opts.3x,v 1.13 2007/02/24 17:34:27 tom Exp $ +.TH form_field_opts 3X "" +.SH NAME +\fBform_field_opts\fR - set and get field options +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_field_opts(FIELD *field, Field_Options opts); +.br +int field_opts_on(FIELD *field, Field_Options opts); +.br +int field_opts_off(FIELD *field, Field_Options opts); +.br +Field_Options field_opts(const FIELD *field); +.br +.SH DESCRIPTION +The function \fBset_field_opts\fR sets all the given field's option bits (field +option bits may be logically-OR'ed together). +.PP +The function \fBfield_opts_on\fR turns on the given option bits, and leaves +others alone. +.PP +The function \fBfield_opts_off\fR turns off the given option bits, and leaves +others alone. +.PP +The function \fBfield_opts\fR returns the field's current option bits. +.PP +The following options are defined (all are on by default): +.TP 5 +O_VISIBLE +The field is displayed. If this option is off, display of the field is +suppressed. +.TP 5 +O_ACTIVE +The field is visited during processing. If this option is off, the field will +not be reachable by navigation keys. Please notice that an invisible field +appears to be inactive also. +.TP 5 +O_PUBLIC +The field contents are displayed as data is entered. +.TP 5 +O_EDIT +The field can be edited. +.TP 5 +O_WRAP +Words that do not fit on a line are wrapped to the next line. Words are +blank-separated. +.TP 5 +O_BLANK +The field is cleared whenever a character is entered at the first position. +.TP 5 +O_AUTOSKIP +Skip to the next field when this one fills. +.TP 5 +O_NULLOK +Allow a blank field. +.TP 5 +O_STATIC +Field buffers are fixed to field's original size. +Turn this option off to create a dynamic field. +.TP 5 +O_PASSOK +Validate field only if modified by user. +.SH RETURN VALUE +Except for \fBfield_opts\fR, each routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CURRENT +The field is the current field. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.TP 5 +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_field_userptr.3x b/man/form_field_userptr.3x new file mode 100644 index 000000000000..47b9ed424d19 --- /dev/null +++ b/man/form_field_userptr.3x @@ -0,0 +1,69 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_userptr.3x,v 1.8 2006/11/04 18:04:37 tom Exp $ +.TH form_field_userptr 3X "" +.SH NAME +\fBform_field_userptr\fR - associate application data with a form field +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_field_userptr(FIELD *field, void*userptr); +.br +void *field_userptr(const FIELD *field); +.br +.SH DESCRIPTION +Every form field has a field that can be used to hold application-specific data +(that is, the form-driver code leaves it alone). These functions get and set +that field. +.SH RETURN VALUE +The function \fBfield_userptr\fR returns a pointer (which may be \fBNULL\fR). +It does not set errno. +.PP +The function \fBset_field_userptr\fR returns \fBE_OK\fP (success). +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.PP +The user pointer is a void pointer. +We chose not to leave it as a char pointer for SVr4 compatibility. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_field_validation.3x b/man/form_field_validation.3x new file mode 100644 index 000000000000..2da52efd2e36 --- /dev/null +++ b/man/form_field_validation.3x @@ -0,0 +1,144 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_field_validation.3x,v 1.16 2006/12/24 16:08:08 tom Exp $ +.TH form_field_validation 3X "" +.SH NAME +\fBform_field_validation\fR - data type validation for fields +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_field_type(FIELD *field, FIELDTYPE *type, ...); +.br +FIELDTYPE *field_type(const FIELD *field); +.br +void *field_arg(const FIELD *field); +.sp +FIELDTYPE *TYPE_ALNUM; +.br +FIELDTYPE *TYPE_ALPHA; +.br +FIELDTYPE *TYPE_ENUM; +.br +FIELDTYPE *TYPE_INTEGER; +.br +FIELDTYPE *TYPE_NUMERIC; +.br +FIELDTYPE *TYPE_REGEXP; +.br +FIELDTYPE *TYPE_IPV4; +.br +.SH DESCRIPTION +The function \fBset_field_type\fR declares a data type for a given form field. +This is the type checked by validation functions. +The predefined types are as follows: +.TP 5 +TYPE_ALNUM +Alphanumeric data. Requires a third \fBint\fR argument, a minimum field width. +.TP 5 +TYPE_ALPHA +Character data. Requires a third \fBint\fR argument, a minimum field width. +.TP 5 +TYPE_ENUM +Accept one of a specified set of strings. Requires a third \fB(char **)\fR +argument pointing to a string list; a fourth \fBint\fR flag argument to enable +case-sensitivity; and a fifth \fBint\fR flag argument specifying whether a partial +match must be a unique one (if this flag is off, a prefix matches the first +of any set of more than one list elements with that prefix). Please notice +that the string list is not copied, only a reference to it is stored in the +field. So you should avoid using a list that lives in automatic variables +on the stack. +.TP 5 +TYPE_INTEGER +Integer data, parsable to an integer by \fBatoi(3)\fR. Requires a third +\fBint\fR argument controlling the precision, a fourth \fBlong\fR argument +constraining minimum value, and a fifth \fBlong\fR constraining maximum value. +If the maximum value is less than or equal to the minimum value, the range is +simply ignored. On return the field buffer is formatted according to the +\fBprintf\fR format specification ".*ld", where the '*' is replaced by the +precision argument. +For details of the precision handling see \fBprintf's\fR man-page. +.TP 5 +TYPE_NUMERIC +Numeric data (may have a decimal-point part). Requires a third +\fBint\fR argument controlling the precision, a fourth \fBdouble\fR +argument constraining minimum value, and a fifth \fBdouble\fR constraining +maximum value. If your system supports locales, the decimal point character +to be used must be the one specified by your locale. +If the maximum value is less than or equal to the minimum value, the range is +simply ignored. On return the field buffer is formatted according to the +\fBprintf\fR format specification ".*f", where the '*' is replaced by the +precision argument. +For details of the precision handling see \fBprintf's\fR man-page. +.TP 5 +TYPE_REGEXP +Regular expression data. Requires a regular expression \fB(char *)\fR third argument; +the data is valid if the regular expression matches it. Regular expressions +are in the format of \fBregcomp\fR and \fBregexec\fR. Please notice +that the regular expression must match the whole field. If you have for +example an eight character wide field, a regular expression "^[0-9]*$" always +means that you have to fill all eight positions with digits. If you want to +allow fewer digits, you may use for example "^[0-9]* *$" which is good for +trailing spaces (up to an empty field), or "^ *[0-9]* *$" which is good for +leading and trailing spaces around the digits. +.TP 5 +TYPE_IPV4 +An Internet Protocol Version 4 address. This requires no additional argument. It +is checked whether or not the buffer has the form a.b.c.d, where a,b,c and d are +numbers between 0 and 255. Trailing blanks in the buffer are ignored. The address +itself is not validated. Please note that this is an ncurses extension. This +field type may not be available in other curses implementations. +.PP +It is possible to set up new programmer-defined field types. See the +\fBform_fieldtype\fR(3X) manual page. +.SH RETURN VALUE +The functions \fBfield_type\fR and \fBfield_arg\fR return \fBNULL\fR on +error. The function \fBset_field_type\fR returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_fieldtype.3x b/man/form_fieldtype.3x new file mode 100644 index 000000000000..0d42faed6cc2 --- /dev/null +++ b/man/form_fieldtype.3x @@ -0,0 +1,148 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_fieldtype.3x,v 1.14 2006/11/04 17:12:00 tom Exp $ +.TH form_fieldtype 3X "" +.SH NAME +\fBform_fieldtype\fR - define validation-field types +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +FIELDTYPE *new_fieldtype( + bool (* const field_check)(FIELD *, const void *), + bool (* const char_check)(int, const void *)); +.br +int free_fieldtype(FIELDTYPE *fieldtype); +.br +int set_fieldtype_arg( + FIELDTYPE *fieldtype, + void *(* const make_arg)(va_list *), + void *(* const copy_arg)(const void *), + void (* const free_arg)(void *)); +.br +int set_fieldtype_choice( + FIELDTYPE *fieldtype, + bool (* const next_choice)(FIELD *, const void *), + bool (* const prev_choice)(FIELD *, const void *)); +.br +FIELDTYPE *link_fieldtype(FIELDTYPE *type1, + FIELDTYPE *type2); +.br +.SH DESCRIPTION +The function \fBnew_fieldtype\fR creates a new field type usable for data +validation. You supply it with \fIfield_check\fR, a predicate to check the +validity of an entered data string whenever the user attempts to leave a field. +The (FIELD *) argument is passed in so the validation predicate can see the +field's buffer, sizes and other attributes; the second argument is an +argument-block structure, about which more below. +.PP +You also supply \fBnew_fieldtype\fR with \fIchar_check\fR, +a function to validate input characters as they are entered; it will be passed +the character to be checked and a pointer to an argument-block structure. +.PP +The function \fBfree_fieldtype\fR frees the space allocated for a given +validation type. +.PP +The function \fBset_fieldtype_arg\fR associates three storage-management functions +with a field type. +The \fImake_arg\fR function is automatically applied to the +list of arguments you give \fBset_field_type\fR when attaching validation +to a field; its job is to bundle these into an allocated argument-block +object which can later be passed to validation predicated. +The other two hook arguments should copy and free argument-block structures. +They will be used by the forms-driver code. +You must supply the \fImake_arg\fR function, +the other two are optional, you may supply NULL for them. +In this case it is assumed +that \fImake_arg\fR does not allocate memory but simply loads the +argument into a single scalar value. +.PP +The function \fBlink_fieldtype\fR creates +a new field type from the two given types. +They are connected by an logical 'OR'. +.PP +The form driver requests \fBREQ_NEXT_CHOICE\fR and \fBREQ_PREV_CHOICE\fR assume +that the possible values of a field form an ordered set, and provide the forms +user with a way to move through the set. +The \fBset_fieldtype_choice\fR +function allows forms programmers to define successor and predecessor functions +for the field type. +These functions take the field pointer and an +argument-block structure as arguments. +.SH RETURN VALUE +The pointer-valued routines return NULL on error. +They set errno according to their success: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred, e.g., malloc failure. +.PP +The integer-valued routines return one of the following codes on +error: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CONNECTED +The field is already connected to a form. +.TP 5 +.B E_CURRENT +The field is the current field. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.PP +All of the \fB(char *)\fR arguments of these functions should actually be +\fB(void *)\fR. The type has been left uncorrected for strict compatibility +with System V. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_hook.3x b/man/form_hook.3x new file mode 100644 index 000000000000..cd47a24a59c8 --- /dev/null +++ b/man/form_hook.3x @@ -0,0 +1,100 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_hook.3x,v 1.9 2007/02/24 17:34:18 tom Exp $ +.TH form_hook 3X "" +.SH NAME +\fBform_hook\fR - set hooks for automatic invocation by applications +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_field_init(FORM *form, Form_Hook func); +.br +Form_Hook field_init(const FORM *form); +.br +int set_field_term(FORM *form, Form_Hook func); +.br +Form_Hook field_term(const FORM *form); +.br +int set_form_init(FORM *form, Form_Hook func); +.br +Form_Hook form_init(const FORM *form); +.br +int set_form_term(FORM *form, Form_Hook func); +.br +Form_Hook form_term(const FORM *form); +.br +.SH DESCRIPTION +These functions make it possible to set hook functions to be called at various +points in the automatic processing of input event codes by \fBform_driver\fR. +.PP +The function \fBset_field_init\fR sets a hook to be called at form-post time +and each time the selected field changes (after the change). \fBfield_init\fR +returns the current field init hook, if any (\fBNULL\fR if there is no such +hook). +.PP +The function \fBset_field_term\fR sets a hook to be called at form-unpost time +and each time the selected field changes (before the change). \fBfield_term\fR +returns the current field term hook, if any (\fBNULL\fR if there is no such +hook). +.PP +The function \fBset_form_init\fR sets a hook to be called at form-post time and +just after a page change once it is posted. \fBform_init\fR returns the +current form init hook, if any (\fBNULL\fR if there is no such hook). +.PP +The function \fBset_form_term\fR sets a hook to be called at form-unpost time +and just before a page change once it is posted. \fBform_init\fR +returns the current form term hook, if any (\fBNULL\fR if there is no such +hook). +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fR on error. Other routines +return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_new.3x b/man/form_new.3x new file mode 100644 index 000000000000..cac4f508b38b --- /dev/null +++ b/man/form_new.3x @@ -0,0 +1,89 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_new.3x,v 1.7 2006/11/04 17:12:00 tom Exp $ +.TH form_new 3X "" +.SH NAME +\fBform_new\fR - create and destroy forms +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +FORM *new_form(FIELD **fields); +.br +int free_form(FORM *form); +.br +.SH DESCRIPTION +The function \fBnew_form\fR creates a new form connected to a specified field +pointer array (which must be \fBNULL\fR-terminated). +.PP +The function \fBfree_form\fR disconnects \fIform\fR from its field array +and frees the storage allocated for the form. +.SH RETURN VALUE +The function \fBnew_form\fR returns \fBNULL\fR on error. +It sets errno according to the function's success: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CONNECTED +The field is already connected to a form. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred, e.g., malloc failure. +.PP +The function \fBfree_form\fR returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The form has already been posted. +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_new_page.3x b/man/form_new_page.3x new file mode 100644 index 000000000000..5b7f58d4a46a --- /dev/null +++ b/man/form_new_page.3x @@ -0,0 +1,77 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2002,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_new_page.3x,v 1.8 2006/11/04 17:12:00 tom Exp $ +.TH form_new_page 3X "" +.SH NAME +\fBform_new_page\fR - form pagination functions +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_new_page(FIELD *field, bool new_page_flag); +.br +bool new_page(const FIELD *field); +.br +.SH DESCRIPTION +The function \fBset_new_page\fR sets or resets a flag marking the given field +as the beginning of a new page on its form. +.PP +The function \fBnew_page\fR is a predicate which tests if a given field marks +a page beginning on its form. +.SH RETURN VALUE +The function \fBnew_page\fR returns \fBTRUE\fR or \fBFALSE\fR. +.PP +The function \fBset_new_page\fR return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_CONNECTED +The given field is already connected to a form. +.SH SEE ALSO +\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_opts.3x b/man/form_opts.3x new file mode 100644 index 000000000000..0caaae7c8837 --- /dev/null +++ b/man/form_opts.3x @@ -0,0 +1,90 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_opts.3x,v 1.9 2007/02/24 17:34:36 tom Exp $ +.TH form_opts 3X "" +.SH NAME +\fBform_opts\fR - set and get form options +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_form_opts(FORM *form, Field_Options opts); +.br +int form_opts_on(FORM *form, Field_Options opts); +.br +int form_opts_off(FORM *form, Field_Options opts); +.br +Field_Options form_opts(const FORM *form); +.br +.SH DESCRIPTION +The function \fBset_form_opts\fR sets all the given form's option bits (form +option bits may be logically-OR'ed together). +.PP +The function \fBform_opts_on\fR turns on the given option bits, and leaves +others alone. +.PP +The function \fBform_opts_off\fR turns off the given option bits, and leaves +others alone. +.PP +The function \fBform_opts\fR returns the form's current option bits. +.PP +The following options are defined (all are on by default): +.TP 5 +O_NL_OVERLOAD +Overload the \fBREQ_NEW_LINE\fR forms driver request so that calling it at the +end of a field goes to the next field. +.TP 5 +O_BS_OVERLOAD +Overload the \fBREQ_DEL_PREV\fR forms driver request so that calling it at the +beginning of a field goes to the previous field. +.SH RETURN VALUE +Except for \fBform_opts\fR, each routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_page.3x b/man/form_page.3x new file mode 100644 index 000000000000..50ed54db4cc5 --- /dev/null +++ b/man/form_page.3x @@ -0,0 +1,96 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_page.3x,v 1.10 2006/11/04 18:52:32 tom Exp $ +.TH form_page 3X "" +.SH NAME +\fBform_page\fR - set and get form page number +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_current_field(FORM *form, FIELD *field); +.br +FIELD *current_field(const FORM *); +.br +int set_form_page(FORM *form, int n); +.br +int form_page(const FORM *form); +.br +int field_index(const FIELD *field); +.br +.SH DESCRIPTION +The function \fBset_current field\fR sets the current field of the given +form; \fBcurrent_field\fR returns the current field of the given form. +.PP +The function \fBset_form_page\fR sets the form's page number (goes to page +\fIn\fR of the form). +.PP +The function \fBform_page\fR returns the form's current page number. +.PP +The function \fBfield_index\fR returns the index of the field in the +field array of the form it is connected to. It returns \fBERR\fR if +the argument is the null pointer or the field is not connected. +.SH RETURN VALUE +Except for \fBform_page\fR, each routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_INVALID_FIELD +Contents of a field are not valid. +.TP 5 +.B E_REQUEST_DENIED +The form driver could not process the request. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +. +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_post.3x b/man/form_post.3x new file mode 100644 index 000000000000..6bf1607799c6 --- /dev/null +++ b/man/form_post.3x @@ -0,0 +1,91 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_post.3x,v 1.7 2006/11/04 18:53:20 tom Exp $ +.TH form_post 3X "" +.SH NAME +\fBform_post\fR - write or erase forms from associated subwindows +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int post_form(FORM *form); +.br +int unpost_form(FORM *form); +.br +.SH DESCRIPTION +The function \fBpost_form\fR displays a form to its associated subwindow. To +trigger physical display of the subwindow, use \fBrefresh\fR or some equivalent +\fBcurses\fR routine (the implicit \fBdoupdate\fR triggered by an \fBcurses\fR +input request will do). +.PP +The function \fBunpost_form\fR erases form from its associated subwindow. +.SH RETURN VALUE +These routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NOT_POSTED +The form has not been posted. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the form. +.TP 5 +.B E_NO_ROOM +Form is too large for its window. +.TP 5 +.B E_POSTED +The form has already been posted. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +. +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_requestname.3x b/man/form_requestname.3x new file mode 100644 index 000000000000..a172f857b1e3 --- /dev/null +++ b/man/form_requestname.3x @@ -0,0 +1,70 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_requestname.3x,v 1.7 2006/11/04 17:57:49 tom Exp $ +.TH form_requestname 3X "" +.SH NAME +\fBform_requestname\fR - handle printable form request names +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +const char *form_request_name(int request); +.br +int form_request_by_name(const char *name); +.br +.SH DESCRIPTION +The function \fBform_request_name\fR returns the printable name of a form +request code. +.br +The function \fBform_request_by_name\fR searches in the name-table for a request +with the given name and returns its request code. Otherwise E_NO_MATCH is returned. +.SH RETURN VALUE +\fBform_request_name\fR returns \fBNULL\fR on error and sets errno +to \fBE_BAD_ARGUMENT\fR. +.br +\fBform_request_by_name\fR returns \fBE_NO_MATCH\fR on error. +It does not set errno. +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These 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 them be conditioned using NCURSES_VERSION. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_userptr.3x b/man/form_userptr.3x new file mode 100644 index 000000000000..7be0bf860480 --- /dev/null +++ b/man/form_userptr.3x @@ -0,0 +1,69 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_userptr.3x,v 1.11 2006/11/04 18:43:24 tom Exp $ +.TH form_userptr 3X "" +.SH NAME +\fBform_userptr\fR - associate application data with a form item +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_form_userptr(FORM *form, void *userptr); +.br +void* form_userptr(const FORM *form); +.br +.SH DESCRIPTION +Every form and every form item has a field that can be used to hold +application-specific data (that is, the form-driver code leaves it alone). +These functions get and set the form user pointer field. +.SH RETURN VALUE +The function \fBform_userptr\fR returns a pointer (which may be \fBNULL\fR). +It does not set errno. +.PP +The function \fBset_form_userptr\fR returns \fBE_OK\fP (success). +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.PP +The user pointer is a void pointer. +We chose not to leave it as a char pointer for SVr4 compatibility. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/form_win.3x b/man/form_win.3x new file mode 100644 index 000000000000..c8f64f2e04ad --- /dev/null +++ b/man/form_win.3x @@ -0,0 +1,95 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: form_win.3x,v 1.10 2006/11/04 17:12:00 tom Exp $ +.TH form_win 3X "" +.SH NAME +\fBform_win\fR - make and break form window and subwindow associations +.SH SYNOPSIS +\fB#include <form.h>\fR +.br +int set_form_win(FORM *form, WINDOW *win); +.br +WINDOW *form_win(const FORM *form); +.br +int set_form_sub(FORM *form, WINDOW *sub); +.br +WINDOW *form_sub(const FORM *form); +.br +int scale_form(const FORM *form, int *rows, int *columns); +.br +.SH DESCRIPTION +Every form has an associated pair of \fBcurses\fR windows. The form window +displays any title and border associated with the window; the form subwindow +displays the items of the form that are currently available for selection. +.PP +The first four functions get and set those windows. It is not necessary to set +either window; by default, the driver code uses \fBstdscr\fR for both. +.PP +In the \fBset_\fR functions, window argument of \fBNULL\fR is treated as though +it were \fBstsdcr\fR. A form argument of \fBNULL\fR is treated as a request +to change the system default form window or subwindow. +.PP +The function \fBscale_form\fR returns the minimum size required for the +subwindow of \fIform\fR. +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fR on error. Routines that return +an integer return one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The form has already been posted. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the form. +.SH SEE ALSO +\fBcurses\fR(3X), \fBform\fR(3X). +.SH NOTES +The header file \fB<form.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V forms library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/infocmp.1m b/man/infocmp.1m new file mode 100644 index 000000000000..b1a88e76723b --- /dev/null +++ b/man/infocmp.1m @@ -0,0 +1,437 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2004,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: infocmp.1m,v 1.44 2006/12/24 18:16:31 tom Exp $ +.TH @INFOCMP@ 1M "" +.ds n 5 +.ds d @TERMINFO@ +.SH NAME +\fB@INFOCMP@\fR - compare or print out \fIterminfo\fR descriptions +.SH SYNOPSIS +\fB@INFOCMP@\fR [\fB-\ +1\ +C\ +E\ +F\ +G\ +I\ +L\ +T\ +U\ +V\ +c\ +d\ +e\ +g\ +i\ +l\ +n\ +p\ +q\ +r\ +t\ +u\ +x\ +\fR] +.br + [\fB-v\fR \fIn\fR] [\fB-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR] [\fB-R \fR\fBsubset\fR] +.br + [\fB-w\fR\ \fIwidth\fR] [\fB-A\fR\ \fIdirectory\fR] [\fB-B\fR\ \fIdirectory\fR] +.br + [\fItermname\fR...] +.SH DESCRIPTION +\fB@INFOCMP@\fR can be used to compare a binary \fBterminfo\fR entry with other +terminfo entries, rewrite a \fBterminfo\fR description to take advantage of the +\fBuse=\fR terminfo field, or print out a \fBterminfo\fR description from the +binary file (\fBterm\fR) in a variety of formats. In all cases, the boolean +fields will be printed first, followed by the numeric fields, followed by the +string fields. +.SS Default Options +If no options are specified and zero or one \fItermnames\fR are specified, the +\fB-I\fR option will be assumed. If more than one \fItermname\fR is specified, +the \fB-d\fR option will be assumed. +.SS Comparison Options [-d] [-c] [-n] +\fB@INFOCMP@\fR compares the \fBterminfo\fR description of the first terminal +\fItermname\fR with each of the descriptions given by the entries for the other +terminal's \fItermnames\fR. If a capability is defined for only one of the +terminals, the value returned will depend on the type of the capability: +\fBF\fR for boolean variables, \fB-1\fR for integer variables, and \fBNULL\fR +for string variables. +.PP +The \fB-d\fR option produces a list of each capability that is different +between two entries. This option is useful to show the difference between two +entries, created by different people, for the same or similar terminals. +.PP +The \fB-c\fR option produces a list of each capability that is common between +two entries. Capabilities that are not set are ignored. This option can be +used as a quick check to see if the \fB-u\fR option is worth using. +.PP +The \fB-n\fR option produces a list of each capability that is in neither +entry. If no \fItermnames\fR are given, the environment variable \fBTERM\fR +will be used for both of the \fItermnames\fR. This can be used as a quick +check to see if anything was left out of a description. +.SS Source Listing Options [-I] [-L] [-C] [-r] +The \fB-I\fR, \fB-L\fR, and \fB-C\fR options will produce a source listing for +each terminal named. +. +.TS +center tab(/) ; +l l . +\fB-I\fR/use the \fBterminfo\fR names +\fB-L\fR/use the long C variable name listed in <\fBterm.h\fR> +\fB-C\fR/use the \fBtermcap\fR names +\fB-r\fR/when using \fB-C\fR, put out all capabilities in \fBtermcap\fR form +.TE +.PP +If no \fItermnames\fR are given, the environment variable \fBTERM\fR will be +used for the terminal name. +.PP +The source produced by the \fB-C\fR option may be used directly as a +\fBtermcap\fR entry, but not all parameterized strings can be changed to +the \fBtermcap\fR format. \fB@INFOCMP@\fR will attempt to convert most of the +parameterized information, and anything not converted will be plainly marked in +the output and commented out. These should be edited by hand. +.PP +All padding information for strings will be collected together and placed +at the beginning of the string where \fBtermcap\fR expects it. Mandatory +padding (padding information with a trailing '/') will become optional. +.PP +All \fBtermcap\fR variables no longer supported by \fBterminfo\fR, but which +are derivable from other \fBterminfo\fR variables, will be output. Not all +\fBterminfo\fR capabilities will be translated; only those variables which were +part of \fBtermcap\fR will normally be output. Specifying the \fB-r\fR option +will take off this restriction, allowing all capabilities to be output in +\fItermcap\fR form. +.PP +Note that because padding is collected to the beginning of the capability, not +all capabilities are output. Mandatory padding is not supported. Because +\fBtermcap\fR strings are not as flexible, it is not always possible to convert +a \fBterminfo\fR string capability into an equivalent \fBtermcap\fR format. A +subsequent conversion of the \fBtermcap\fR file back into \fBterminfo\fR format +will not necessarily reproduce the original \fBterminfo\fR +source. +.PP +Some common \fBterminfo\fR parameter sequences, their \fBtermcap\fR +equivalents, and some terminal types which commonly have such sequences, are: +. +.TS +center tab(/) ; +l c l +l l l. +\fBterminfo/termcap\fR/Representative Terminals += +\fB%p1%c/%.\fR/adm +\fB%p1%d/%d\fR/hp, ANSI standard, vt100 +\fB%p1%'x'%+%c/%+x\fR/concept +\fB%i/%i\fRq/ANSI standard, vt100 +\fB%p1%?%'x'%>%t%p1%'y'%+%;/%>xy\fR/concept +\fB%p2\fR is printed before \fB%p1/%r\fR/hp +.TE +.SS Use= Option [-u] +The \fB-u\fR option produces a \fBterminfo\fR source description of the first +terminal \fItermname\fR which is relative to the sum of the descriptions given +by the entries for the other terminals \fItermnames\fR. It does this by +analyzing the differences between the first \fItermname\fR and the other +\fItermnames\fR and producing a description with \fBuse=\fR fields for the +other terminals. In this manner, it is possible to retrofit generic terminfo +entries into a terminal's description. Or, if two similar terminals exist, but +were coded at different times or by different people so that each description +is a full description, using \fB@INFOCMP@\fR will show what can be done to change +one description to be relative to the other. +.PP +A capability will get printed with an at-sign (@) if it no longer exists in the +first \fItermname\fR, but one of the other \fItermname\fR entries contains a +value for it. A capability's value gets printed if the value in the first +\fItermname\fR is not found in any of the other \fItermname\fR entries, or if +the first of the other \fItermname\fR entries that has this capability gives a +different value for the capability than that in the first \fItermname\fR. +.PP +The order of the other \fItermname\fR entries is significant. Since the +terminfo compiler \fBtic\fR does a left-to-right scan of the capabilities, +specifying two \fBuse=\fR entries that contain differing entries for the same +capabilities will produce different results depending on the order that the +entries are given in. \fB@INFOCMP@\fR will flag any such inconsistencies between +the other \fItermname\fR entries as they are found. +.PP +Alternatively, specifying a capability \fIafter\fR a \fBuse=\fR entry that +contains that capability will cause the second specification to be ignored. +Using \fB@INFOCMP@\fR to recreate a description can be a useful check to make +sure that everything was specified correctly in the original source +description. +.PP +Another error that does not cause incorrect compiled files, but will slow down +the compilation time, is specifying extra \fBuse=\fR fields that are +superfluous. \fB@INFOCMP@\fR will flag any other \fItermname use=\fR fields that +were not needed. +.SS Changing Databases [-A \fIdirectory\fR] [-B \fIdirectory\fR] +The location of the compiled \fBterminfo\fR database is taken from the +environment variable \fBTERMINFO\fR . If the variable is not defined, or the +terminal is not found in that location, the system \fBterminfo\fR database, +in \fB@TERMINFO@\fR, will be used. The options \fB-A\fR +and \fB-B\fR may be used to override this location. The \fB-A\fR option will +set \fBTERMINFO\fR for the first \fItermname\fR and the \fB-B\fR option will +set \fBTERMINFO\fR for the other \fItermnames\fR. With this, it is possible to +compare descriptions for a terminal with the same name located in two different +databases. This is useful for comparing descriptions for the same terminal +created by different people. +.SS Other Options +.TP 5 +\fB-1\fR +causes the fields to be printed out one to a line. Otherwise, +the fields will be printed several to a line to a maximum width +of 60 characters. +.TP +\fB-a\fR +tells \fB@INFOCMP@\fP to retain commented-out capabilities rather than discarding +them. Capabilities are commented by prefixing them with a period. +.TP 5 +\fB-E\fR +Dump the capabilities of the given terminal as tables, needed in +the C initializer for a +TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR). +This option is useful for preparing versions of the curses library hardwired +for a given terminal type. +The tables are all declared static, and are named according to the type +and the name of the corresponding terminal entry. +.sp +Before ncurses 5.0, the split between the \fB-e\fP and \fB-E\fP +options was not needed; but support for extended names required making +the arrays of terminal capabilities separate from the TERMTYPE structure. +.TP 5 +\fB-e\fR +Dump the capabilities of the given terminal as a C initializer for a +TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR). +This option is useful for preparing versions of the curses library hardwired +for a given terminal type. +.TP 5 +\fB-F\fR +compare terminfo files. This assumes that two following arguments are +filenames. The files are searched for pairwise matches between +entries, with two entries considered to match if any of their names do. +The report printed to standard output lists entries with no matches in +the other file, and entries with more than one match. For entries +with exactly one match it includes a difference report. Normally, +to reduce the volume of the report, use references are +not resolved before looking for differences, but resolution can be forced +by also specifying \fB-r\fR. +.TP 5 +\fB-f\fR +Display complex terminfo strings which contain if/then/else/endif expressions +indented for readability. +.TP 5 +\fB-G\fR +Display constant literals in decimal form +rather than their character equivalents. +.TP 5 +\fB-g\fR +Display constant character literals in quoted form +rather than their decimal equivalents. +.TP 5 +\fB-i\fR +Analyze the initialization (\fBis1\fR, \fBis2\fR, \fBis3\fR), and reset +(\fBrs1\fR, \fBrs2\fR, \fBrs3\fR), strings in the entry. For each string, the +code tries to analyze it into actions in terms of the other capabilities in the +entry, certain X3.64/ISO 6429/ECMA-48 capabilities, and certain DEC VT-series +private modes (the set of recognized special sequences has been selected for +completeness over the existing terminfo database). Each report line consists +of the capability name, followed by a colon and space, followed by a printable +expansion of the capability string with sections matching recognized actions +translated into {}-bracketed descriptions. Here is a list of the DEC/ANSI +special sequences recognized: +i. +.TS +center tab(/) ; +l l +l l. +Action/Meaning += +RIS/full reset +SC/save cursor +RC/restore cursor +LL/home-down +RSR/reset scroll region += +DECSTR/soft reset (VT320) +S7C1T/7-bit controls (VT220) += +ISO DEC G0/enable DEC graphics for G0 +ISO UK G0/enable UK chars for G0 +ISO US G0/enable US chars for G0 +ISO DEC G1/enable DEC graphics for G1 +ISO UK G1/enable UK chars for G1 +ISO US G1/enable US chars for G1 += +DECPAM/application keypad mode +DECPNM/normal keypad mode +DECANSI/enter ANSI mode += +ECMA[+-]AM/keyboard action mode +ECMA[+-]IRM/insert replace mode +ECMA[+-]SRM/send receive mode +ECMA[+-]LNM/linefeed mode += +DEC[+-]CKM/application cursor keys +DEC[+-]ANM/set VT52 mode +DEC[+-]COLM/132-column mode +DEC[+-]SCLM/smooth scroll +DEC[+-]SCNM/reverse video mode +DEC[+-]OM/origin mode +DEC[+-]AWM/wraparound mode +DEC[+-]ARM/auto-repeat mode +.TE +.sp +It also recognizes a SGR action corresponding to ANSI/ISO 6429/ECMA Set +Graphics Rendition, with the values NORMAL, BOLD, UNDERLINE, BLINK, and +REVERSE. All but NORMAL may be prefixed with `+' (turn on) or `-' (turn off). +.PP +An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}). +.TP 5 +\fB-l\fR +Set output format to terminfo. +.TP 5 +\fB-p\fR +Ignore padding specifications when comparing strings. +.TP 5 +\fB-q\fR +Make the comparison listing shorter by omitting subheadings, and using +"-" for absent capabilities, "@" for canceled rather than "NULL". +.TP 5 +\fB-R\fR\fIsubset\fR +Restrict output to a given subset. This option is for use with archaic +versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support +the full set of SVR4/XSI Curses terminfo; and variants such as AIX +that have their own extensions incompatible with SVr4/XSI. Available terminfo +subsets are "SVr1", "Ultrix", "HP", and "AIX"; see \fBterminfo\fR(\*n) for +details. You can also choose the subset "BSD" which selects only capabilities +with termcap equivalents recognized by 4.4BSD. +.TP +\fB-s \fR\fI[d|i|l|c]\fR +The \fB-s\fR option sorts the fields within each type according to the argument +below: +.br +.RS 5 +.TP 5 +\fBd\fR +leave fields in the order that they are stored in the \fIterminfo\fR database. +.TP 5 +\fBi\fR +sort by \fIterminfo\fR name. +.TP 5 +\fBl\fR +sort by the long C variable name. +.TP 5 +\fBc\fR +sort by the \fItermcap\fR name. +.RE +.IP +If the \fB-s\fR option is not given, the fields printed out will be +sorted alphabetically by the \fBterminfo\fR name within each type, +except in the case of the \fB-C\fR or the \fB-L\fR options, which cause the +sorting to be done by the \fBtermcap\fR name or the long C variable +name, respectively. +.TP 5 +\fB-T\fR +eliminates size-restrictions on the generated text. +This is mainly useful for testing and analysis, since the compiled +descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). +.TP +\fB-t\fR +tells \fBtic\fP to discard commented-out capabilities. +Normally when translating from terminfo to termcap, +untranslatable capabilities are commented-out. +.TP 5 +\fB-U\fR +tells \fB@INFOCMP@\fP to not post-process the data after parsing the source file. +This feature helps when comparing the actual contents of two source files, +since it excludes the inferences that \fB@INFOCMP@\fP makes to fill in missing +data. +.TP 5 +\fB-V\fR +reports the version of ncurses which was used in this program, and exits. +.TP 5 +\fB-v\fR \fIn\fR +prints out tracing information on standard error as the program runs. +Higher values of n induce greater verbosity. +.TP 5 +\fB-w\fR \fIwidth\fR +changes the output to \fIwidth\fR characters. +.TP +\fB-x\fR +print information for user-defined capabilities. +These are extensions to the terminfo repertoire which can be loaded +using the \fB-x\fR option of \fBtic\fP. +.SH FILES +.TP 20 +\*d +Compiled terminal description database. +.SH EXTENSIONS +The +\fB-E\fR, +\fB-F\fR, +\fB-G\fR, +\fB-R\fR, +\fB-T\fR, +\fB-V\fR, +\fB-a\fR, +\fB-e\fR, +\fB-f\fR, +\fB-g\fR, +\fB-i\fR, +\fB-l\fR, +\fB-p\fR, +\fB-q\fR and +\fB-t\fR +options are not supported in SVr4 curses. +.PP +The \fB-r\fR option's notion of `termcap' capabilities is System V Release 4's. +Actual BSD curses versions will have a more restricted set. To see only the +4.4BSD set, use \fB-r\fR \fB-RBSD\fR. +.SH BUGS +The \fB-F\fR option of \fB@INFOCMP@\fR(1M) should be a \fB@TOE@\fR(1M) mode. +.SH SEE ALSO +\fB@CAPTOINFO@\fR(1M), +\fB@INFOTOCAP@\fR(1M), +\fB@TIC@\fR(1M), +\fB@TOE@\fR(1M), +\fBcurses\fR(3X), +\fBterminfo\fR(\*n). +.PP +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.SH AUTHOR +Eric S. Raymond <esr@snark.thyrsus.com> +and +.br +Thomas E. Dickey <dickey@invisible-island.net> +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/infotocap.1m b/man/infotocap.1m new file mode 100644 index 000000000000..19160b449561 --- /dev/null +++ b/man/infotocap.1m @@ -0,0 +1,77 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1999-2004,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: infotocap.1m,v 1.8 2006/12/24 20:13:56 tom Exp $ +.TH @INFOTOCAP@ 1M "" +.ds n 5 +.ds d @TERMINFO@ +.SH NAME +\fB@INFOTOCAP@\fR - convert a \fIterminfo\fR description into a \fItermcap\fR description +.SH SYNOPSIS +\fB@INFOTOCAP@\fR [\fB-v\fR\fIn\fR \fIwidth\fR] [\fB-V\fR] [\fB-1\fR] [\fB-w\fR \fIwidth\fR] \fIfile\fR . . . +.SH DESCRIPTION +\fB@INFOTOCAP@\fR looks in \fIfile\fR for \fBterminfo\fR descriptions. For each +one found, an equivalent \fBtermcap\fR description is written to standard +output. Terminfo \fBuse\fR capabilities are translated directly to termcap +\fBtc\fR capabilities. +.TP 5 +\fB-v\fR +print out tracing information on standard error as the program runs. +.TP 5 +\fB-V\fR +print out the version of the program in use on standard error and exit. +.TP 5 +\fB-1\fR +cause the fields to print out one to a line. Otherwise, the fields +will be printed several to a line to a maximum width of 60 +characters. +.TP 5 +\fB-w\fR +change the output to \fIwidth\fR characters. +.SH FILES +.TP 20 +\*d +Compiled terminal description database. +.SH NOTES +This utility is actually a link to \fI@TIC@\fR, running in \fI-C\fR mode. +You can use other \fI@TIC@\fR options such as \fB-f\fR and \fB-x\fR. +.SH SEE ALSO +\fBcurses\fR(3X), +\fB@TIC@\fR(1M), +\fB@INFOCMP@\fR(1M), +\fBterminfo\fR(\*n) +.PP +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/key_defined.3x b/man/key_defined.3x new file mode 100644 index 000000000000..d7413da6fe35 --- /dev/null +++ b/man/key_defined.3x @@ -0,0 +1,60 @@ +.\"*************************************************************************** +.\" Copyright (c) 2003-2004,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 2003 +.\" +.\" $Id: key_defined.3x,v 1.4 2006/02/25 21:50:01 tom Exp $ +.TH key_defined 3X "" +.SH NAME +\fBkey_defined\fP \- check if a keycode is defined +.SH SYNOPSIS +\fB#include <curses.h>\fP +.sp +\fBint key_defined(const char *definition);\fP +.SH DESCRIPTION +This is an extension to the curses library. +It permits an application to determine if a string is currently bound +to any keycode. +.SH RETURN VALUE +If the string is bound to a keycode, its value (greater than zero) is returned. +If no keycode is bound, zero is returned. +If the string conflicts with longer strings which are bound to keys, -1 is returned. +.SH PORTABILITY +These 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 them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBdefine_key\fR(3X). +.SH AUTHOR +Thomas Dickey. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/keybound.3x b/man/keybound.3x new file mode 100644 index 000000000000..93e17945a31a --- /dev/null +++ b/man/keybound.3x @@ -0,0 +1,64 @@ +.\"*************************************************************************** +.\" Copyright (c) 1999-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1999 +.\" +.\" $Id: keybound.3x,v 1.6 2006/02/25 21:47:06 tom Exp $ +.TH keyok 3X "" +.SH NAME +\fBkeybound\fP \- return definition of keycode +.SH SYNOPSIS +\fB#include <curses.h>\fP +.sp +\fBchar * keybound(int keycode, int count);\fP +.SH DESCRIPTION +This is an extension to the curses library. +It permits an application to determine the string which is defined +in the terminfo for specific keycodes. +.SH RETURN VALUE +The \fIkeycode\fP parameter must be greater than zero, else NULL is returned. +If it does not correspond to a defined key, then NULL is returned. +The \fIcount\fP parameter is used to allow the application to iterate +through multiple definitions, counting from zero. +When successful, +the function returns a string which must be freed by the caller. +.SH PORTABILITY +These 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 them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBdefine_key\fR(3X), +\fBkeyok\fR(3X). +.SH AUTHOR +Thomas Dickey. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/keyok.3x b/man/keyok.3x new file mode 100644 index 000000000000..08c2a27778ea --- /dev/null +++ b/man/keyok.3x @@ -0,0 +1,63 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1997 +.\" +.\" $Id: keyok.3x,v 1.9 2006/02/25 21:47:06 tom Exp $ +.TH keyok 3X "" +.SH NAME +\fBkeyok\fP \- enable or disable a keycode +.SH SYNOPSIS +\fB#include <curses.h>\fP +.sp +\fBint keyok(int keycode, bool enable);\fP +.SH DESCRIPTION +This is an extension to the curses library. +It permits an application to disable specific keycodes, rather than +use the \fIkeypad\fP function to disable all keycodes. +Keys that have been disabled can be reenabled. +.SH RETURN VALUE +The keycode must be greater than zero, else ERR is returned. +If it does not correspond to a defined key, then ERR is returned. +If the \fIenable\fP parameter is true, then the key must have been disabled, +and vice versa. +Otherwise, the function returns OK. +.SH PORTABILITY +These 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 them be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBdefine_key\fR(3X). +.SH AUTHOR +Thomas Dickey. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/legacy_coding.3x b/man/legacy_coding.3x new file mode 100644 index 000000000000..42c49fe5e96c --- /dev/null +++ b/man/legacy_coding.3x @@ -0,0 +1,82 @@ +.\"*************************************************************************** +.\" Copyright (c) 2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey +.\" +.\" $Id: legacy_coding.3x,v 1.3 2006/12/24 15:12:55 tom Exp $ +.TH legacy_coding 3X "" +.SH NAME +\fBuse_legacy_coding\fR \- use terminal's default colors +.SH SYNOPSIS +\fB#include <curses.h>\fP +.sp +\fBint use_legacy_coding(int level);\fP +.SH DESCRIPTION +The +.I use_legacy_coding() +function is an extension to the curses library. +It allows the caller to change the result of \fBunctrl\fP, +and suppress related checks within the library that would normally +cause nonprinting characters to be rendered in visible form. +This affects only 8-bit characters. +.PP +The \fIlevel\fP parameter controls the result: +.RS +.TP 5 +0 +the library functions normally, +rendering nonprinting characters as described in \fBunctrl\fP. +.TP +1 +the library ignores \fBisprintf\fP for codes in the range 160-255. +.TP +2 +the library ignores \fBisprintf\fP for codes in the range 128-255. +It also modifies the output of \fBunctrl\fP, showing codes in the +range 128-159 as is. +.RE +.SH RETURN VALUE +If the screen has not been initialized, +or the \fIlevel\fP parameter is out of range, +the function returns \fBERR\fP. +Otherwise, it returns the previous level: \fB0\fP, \fB1\fP or \fB2\fP. +.SH PORTABILITY +This 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 extensions +be conditioned using NCURSES_VERSION. +.SH SEE ALSO +\fBunctrl\fR. +.SH AUTHOR +Thomas Dickey (to support lynx's font-switching feature). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/make_sed.sh b/man/make_sed.sh new file mode 100755 index 000000000000..f2afac93ebc8 --- /dev/null +++ b/man/make_sed.sh @@ -0,0 +1,89 @@ +#!/bin/sh +# $Id: make_sed.sh,v 1.9 2005/07/16 18:15:31 tom Exp $ +############################################################################## +# Copyright (c) 1998-2003,2005 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 "Software"), # +# to deal in the Software without restriction, including without limitation # +# the rights to use, copy, modify, merge, publish, distribute, distribute # +# with modifications, sublicense, and/or sell copies of the Software, and to # +# permit persons to whom the Software is furnished to do so, subject to the # +# following conditions: # +# # +# The above copyright notice and this permission notice shall be included in # +# all copies or substantial portions of the Software. # +# # +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # +# THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING # +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER # +# DEALINGS IN THE SOFTWARE. # +# # +# Except as contained in this notice, the name(s) of the above copyright # +# holders shall not be used in advertising or otherwise to promote the sale, # +# use or other dealings in this Software without prior written # +# authorization. # +############################################################################## +# +# Author: Thomas E. Dickey 1997-2005 +# +# Construct a sed-script to perform renaming within man-pages. Originally +# written in much simpler form, this one accounts for the common cases of +# section-names in man-pages. + +if test $# != 1 ; then + echo '? expected a single filename' + exit 1 +fi + +COL=col$$ +INPUT=input$$ +UPPER=upper$$ +SCRIPT=script$$ +RESULT=result$$ +rm -f $UPPER $SCRIPT $RESULT +trap "rm -f $COL.* $INPUT $UPPER $SCRIPT $RESULT" 0 1 2 5 15 +fgrep -v \# $1 | \ +sed -e 's/[ ][ ]*/ /g' >$INPUT + +for F in 1 2 3 4 +do +sed -e 's/\./ /g' $INPUT | \ +cut -f $F > $COL.$F +done +for F in 2 4 +do + tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ <$COL.$F >$UPPER + mv $UPPER $COL.$F +done +paste $COL.* | \ +sed -e 's/^/s\/\\</' \ + -e 's/$/\//' >$UPPER + +echo "# Do the TH lines" >>$RESULT +sed -e 's/\//\/TH /' \ + -e 's/ / /' \ + -e 's/ / ""\/TH /' \ + -e 's/ / /' \ + -e 's/\/$/ ""\//' \ + $UPPER >>$RESULT + +echo "# Do the embedded references" >>$RESULT +sed -e 's/</<fB/' \ + -e 's/ /\\\\fR(/' \ + -e 's/ /)\/fB/' \ + -e 's/ /\\\\fR(/' \ + -e 's/\/$/)\//' \ + $UPPER >>$RESULT + +echo "# Do the \fBxxx\fR references in the .NAME section" >>$RESULT +sed -e 's/\\</^\\\\fB/' \ + -e 's/ [^ ]* /\\\\f[RP] -\/\\\\fB/' \ + -e 's/ .*$/\\\\fR -\//' \ + $UPPER >>$RESULT + +# Finally, send the result to standard output +cat $RESULT diff --git a/man/man_db.renames b/man/man_db.renames new file mode 100644 index 000000000000..5a09a03598b8 --- /dev/null +++ b/man/man_db.renames @@ -0,0 +1,176 @@ +############################################################################## +# Copyright (c) 1998-2007,2008 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 "Software"), # +# to deal in the Software without restriction, including without limitation # +# the rights to use, copy, modify, merge, publish, distribute, distribute # +# with modifications, sublicense, and/or sell copies of the Software, and to # +# permit persons to whom the Software is furnished to do so, subject to the # +# following conditions: # +# # +# The above copyright notice and this permission notice shall be included in # +# all copies or substantial portions of the Software. # +# # +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # +# THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING # +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER # +# DEALINGS IN THE SOFTWARE. # +# # +# Except as contained in this notice, the name(s) of the above copyright # +# holders shall not be used in advertising or otherwise to promote the sale, # +# use or other dealings in this Software without prior written # +# authorization. # +############################################################################## +# $Id: man_db.renames,v 0.40 2008/01/19 18:28:50 tom Exp $ +# Manual-page renamings for the man_db program +# +# Files: +captoinfo.1m captoinfo.1 +clear.1 clear.1 +curs_add_wch.3x add_wch.3ncurses +curs_add_wchstr.3x add_wchstr.3ncurses +curs_addch.3x addch.3ncurses +curs_addchstr.3x addchstr.3ncurses +curs_addstr.3x addstr.3ncurses +curs_addwstr.3x addwstr.3ncurses +curs_attr.3x attr.3ncurses +curs_beep.3x beep.3ncurses +curs_bkgd.3x bkgd.3ncurses +curs_bkgrnd.3x bkgrnd.3ncurses +curs_border.3x border.3ncurses +curs_border_set.3x border_set.3ncurses +curs_clear.3x clear.3ncurses +curs_color.3x color.3ncurses +curs_delch.3x delch.3ncurses +curs_deleteln.3x deleteln.3ncurses +curs_extend.3x extensions.3ncurses +curs_get_wch.3x get_wch.3ncurses +curs_get_wstr.3x get_wstr.3ncurses +curs_getcchar.3x getcchar.3ncurses +curs_getch.3x getch.3ncurses +curs_getstr.3x getstr.3ncurses +curs_getyx.3x getyx.3ncurses +curs_in_wch.3x in_wch.3ncurses +curs_in_wchstr.3x in_wchstr.3ncurses +curs_inch.3x inch.3ncurses +curs_inchstr.3x inchstr.3ncurses +curs_initscr.3x initscr.3ncurses +curs_inopts.3x inopts.3ncurses +curs_ins_wch.3x ins_wch.3ncurses +curs_ins_wstr.3x ins_wstr.3ncurses +curs_insch.3x insch.3ncurses +curs_insstr.3x insstr.3ncurses +curs_instr.3x instr.3ncurses +curs_inwstr.3x inwstr.3ncurses +curs_kernel.3x kernel.3ncurses +curs_legacy.3x legacy.3ncurses +curs_mouse.3x mouse.3ncurses +curs_move.3x move.3ncurses +curs_opaque.3x opaque.3ncurses +curs_outopts.3x outopts.3ncurses +curs_overlay.3x overlay.3ncurses +curs_pad.3x pad.3ncurses +curs_print.3x print.3ncurses +curs_printw.3x printw.3ncurses +curs_refresh.3x refresh.3ncurses +curs_scanw.3x scanw.3ncurses +curs_scr_dump.3x scr_dump.3ncurses +curs_scroll.3x scroll.3ncurses +curs_slk.3x slk.3ncurses +curs_termattrs.3x termattrs.3ncurses +curs_termcap.3x termcap.3ncurses +curs_terminfo.3x terminfo.3ncurses +curs_threads.3x threads.3ncurses +curs_touch.3x touch.3ncurses +curs_trace.3x trace.3ncurses +curs_util.3x util.3ncurses +curs_window.3x window.3ncurses +curses.3x ncurses.3ncurses +default_colors.3x default_colors.3ncurses +define_key.3x define_key.3ncurses +form.3x form.3form +form_cursor.3x cursor.3form +form_data.3x data.3form +form_driver.3x driver.3form +form_field.3x field.3form +form_field_attributes.3x field_attributes.3form +form_field_buffer.3x field_buffer.3form +form_field_info.3x field_info.3form +form_field_just.3x field_just.3form +form_field_new.3x field_new.3form +form_field_opts.3x field_opts.3form +form_field_userptr.3x field_userptr.3form +form_field_validation.3x field_validation.3form +form_fieldtype.3x fieldtype.3form +form_hook.3x hook.3form +form_new.3x new.3form +form_new_page.3x new_page.3form +form_opts.3x opts.3form +form_page.3x page.3form +form_post.3x post.3form +form_requestname.3x requestname.3form +form_userptr.3x userptr.3form +form_win.3x win.3form +infocmp.1m infocmp.1 +infotocap.1m infotocap.1 +key_defined.3x key_defined.3ncurses +keybound.3x keybound.3ncurses +keyok.3x keyok.3ncurses +legacy_coding.3x legacy_coding.3ncurses +menu.3x menu.3menu +menu_attributes.3x attributes.3menu +menu_cursor.3x cursor.3menu +menu_driver.3x driver.3menu +menu_format.3x format.3menu +menu_hook.3x hook.3menu +menu_items.3x items.3menu +menu_mark.3x mark.3menu +menu_new.3x new.3menu +menu_opts.3x opts.3menu +menu_pattern.3x pattern.3menu +menu_post.3x post.3menu +menu_requestname.3x requestname.3menu +menu_spacing.3x spacing.3menu +menu_userptr.3x userptr.3menu +menu_win.3x win.3menu +mitem_current.3x menu_current.3menu +mitem_name.3x menu_name.3menu +mitem_new.3x menu_new.3menu +mitem_opts.3x menu_opts.3menu +mitem_userptr.3x menu_userptr.3menu +mitem_value.3x menu_value.3menu +mitem_visible.3x menu_visible.3menu +ncurses.3x ncurses.3ncurses +panel.3x panel.3curses +printf.3s printf.3 +putc.3s putc.3 +resizeterm.3x resizeterm.3ncurses +scanf.3s scanf.3 +system.3s system.3 +term.5 term.5 +term.7 term.7 +terminfo.5 terminfo.5 +terminfo.\\\*n terminfo.5 +tic.1m tic.1 +toe.1m toe.1 +tput.1 tput.1 +tset.1 tset.1 +vprintf.3s vprintf.3 +wresize.3x wresize.3ncurses +# +# Other: +tack.1m tack.1 +# +getty.1 getty.8 +scanf.3 scanf.3 +ttys.5 ttys.4 +termio.7 termios.3 +system.3 system.3 +regcomp.3x regcomp.3 +regexec.3x regexec.3 +# +# vile:cfgmode diff --git a/man/manlinks.sed b/man/manlinks.sed new file mode 100644 index 000000000000..78055b4c7c7d --- /dev/null +++ b/man/manlinks.sed @@ -0,0 +1,102 @@ +# $Id: manlinks.sed,v 1.13 2008/01/19 23:31:17 tom Exp $ +############################################################################## +# Copyright (c) 2000-2003,2008 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 "Software"), # +# to deal in the Software without restriction, including without limitation # +# the rights to use, copy, modify, merge, publish, distribute, distribute # +# with modifications, sublicense, and/or sell copies of the Software, and to # +# permit persons to whom the Software is furnished to do so, subject to the # +# following conditions: # +# # +# The above copyright notice and this permission notice shall be included in # +# all copies or substantial portions of the Software. # +# # +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # +# THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING # +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER # +# DEALINGS IN THE SOFTWARE. # +# # +# Except as contained in this notice, the name(s) of the above copyright # +# holders shall not be used in advertising or otherwise to promote the sale, # +# use or other dealings in this Software without prior written # +# authorization. # +############################################################################## +# Given a manpage (nroff) as input, writes a list of the names that are +# listed in the "NAME" section, i.e., the names that we would like to use +# as aliases for the manpage -T.Dickey +# +# eliminate formatting controls that get in the way +/^'\\"/d +/\.\\"/d +/^\.br/d +/^\.sp/d +/typedef/d +s/^\.IX// +s/\\f.//g +s/[:,]/ /g +# +# eliminate unnecessary whitespace, convert multiple blanks to single space +s/^[ ][ ]*// +s/[ ][ ]*$// +s/[ ][ ]*/ /g +# +# convert ".SH" into a more manageable form +s/\.SH[ ][ ]*/.SH_(/ +# +# in ".SH NAME" +# change "\-" to "-", eliminate text after "-", and split the remaining lines +# at each space, making a list of names: +/^\.SH_(NAME/,/^\.SH_(SYNOPSIS/{ +s/\\-.*/ -/ +/ -/{ +s/ -.*// +s/ /\ +/g +} +/^-/{ +d +} +s/ /\ +/g +} +# +# in ".SH SYNOPSIS" +# remove any line that does not contain a '(', since we only want functions. +# then strip off return-type of each function. +# finally, remove the parameter list, which begins with a '('. +/^\.SH_(SYNOPSIS/,/^\.SH_(DESCRIPTION/{ +/^[^(]*$/d +# reduce +# .B "int add_wch( const cchar_t *\fIwch\fB );" +# to +# add_wch( const cchar_t *\fIwch\fB );" +s/^\([^ (]* [^ (]* [*]*\)//g +s/^\([^ (]* [*]*\)//g +# trim blanks in case we have +# void (*) (FORM *) field_init(const FORM *form); +s/) (/)(/g +# reduce stuff like +# void (*)(FORM *) field_init(const FORM *form); +# to +# field_init(const FORM *form); +s/^\(([^)]*)\)\(([^)]*)\)*[ ]*//g +# rename marker temporarily +s/\.SH_(/.SH_/ +# kill lines with ");", and trim off beginning of argument list. +s/[()].*// +# rename marker back +s/\.SH_/.SH_(/ +} +# +# delete ".SH DESCRIPTION" and following lines +/^\.SH_(DESCRIPTION/,${ +d +} +# +# delete any remaining directives +/^\./d diff --git a/man/menu.3x b/man/menu.3x new file mode 100644 index 000000000000..17d6fc120cba --- /dev/null +++ b/man/menu.3x @@ -0,0 +1,193 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2002,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu.3x,v 1.19 2006/11/04 18:38:29 tom Exp $ +.TH menu 3X "" +.SH NAME +\fBmenu\fR - curses extension for programming menus +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +.SH DESCRIPTION +The \fBmenu\fR library provides terminal-independent facilities for composing +menu systems on character-cell terminals. The library includes: item routines, +which create and modify menu items; and menu routines, which group items into +menus, display menus on the screen, and handle interaction with the user. +.PP +The \fBmenu\fR library uses the \fBcurses\fR libraries, and a curses +initialization routine such as \fBinitscr\fR must be called before using any of +these functions. To use the \fBmenu\fR library, link with the options +\fB-lmenu -lcurses\fR. +. +.SS Current Default Values for Item Attributes +. +The \fBmenu\fR library maintains a default value for item attributes. You can +get or set this default by calling the appropriate \fBget_\fR or \fBset_\fR +routine with a \fBNULL\fR item pointer. Changing this default with a +\fBset_\fR function affects future item creations, but does not change the +rendering of items already created. +. +.SS Routine Name Index +. +The following table lists each \fBmenu\fR routine and the name of +the manual page on which it is described. +. +.TS +l l . +\fBcurses\fR Routine Name Manual Page Name += +current_item \fBmitem_current\fR(3X) +free_item \fBmitem_new\fR(3X) +free_menu \fBmenu_new\fR(3X) +item_count \fBmenu_items\fR(3X) +item_description \fBmitem_name\fR(3X) +item_index \fBmitem_current\fR(3X) +item_init \fBmenu_hook\fR(3X) +item_name \fBmitem_name\fR(3X) +item_opts \fBmitem_opts\fR(3X) +item_opts_off \fBmitem_opts\fR(3X) +item_opts_on \fBmitem_opts\fR(3X) +item_term \fBmenu_hook\fR(3X) +item_userptr \fBmitem_userptr\fR(3X) +item_value \fBmitem_value\fR(3X) +item_visible \fBmitem_visible\fR(3X) +menu_back \fBmenu_attributes\fR(3X) +menu_driver \fBmenu_driver\fR(3X) +menu_fore \fBmenu_attributes\fR(3X) +menu_format \fBmenu_format\fR(3X) +menu_grey \fBmenu_attributes\fR(3X) +menu_init \fBmenu_hook\fR(3X) +menu_items \fBmenu_items\fR(3X) +menu_mark \fBmenu_mark\fR(3X) +menu_opts \fBmenu_opts\fR(3X) +menu_opts_off \fBmenu_opts\fR(3X) +menu_opts_on \fBmenu_opts\fR(3X) +menu_pad \fBmenu_attributes\fR(3X) +menu_pattern \fBmenu_pattern\fR(3X) +menu_request_by_name \fBmenu_requestname\fR(3X) +menu_request_name \fBmenu_requestname\fR(3X) +menu_spacing \fBmenu_spacing\fR(3X) +menu_sub \fBmenu_win\fR(3X) +menu_term \fBmenu_hook\fR(3X) +menu_userptr \fBmenu_userptr\fR(3X) +menu_win \fBmenu_win\fR(3X) +new_item \fBmitem_new\fR(3X) +new_menu \fBmenu_new\fR(3X) +pos_menu_cursor \fBmenu_cursor\fR(3X) +post_menu \fBmenu_post\fR(3X) +scale_menu \fBmenu_win\fR(3X) +set_current_item \fBmitem_current\fR(3X) +set_item_init \fBmenu_hook\fR(3X) +set_item_opts \fBmitem_opts\fR(3X) +set_item_term \fBmenu_hook\fR(3X) +set_item_userptr \fBmitem_userptr\fR(3X) +set_item_value \fBmitem_value\fR(3X) +set_menu_back \fBmenu_attributes\fR(3X) +set_menu_fore \fBmenu_attributes\fR(3X) +set_menu_format \fBmenu_format\fR(3X) +set_menu_grey \fBmenu_attributes\fR(3X) +set_menu_init \fBmenu_hook\fR(3X) +set_menu_items \fBmenu_items\fR(3X) +set_menu_mark \fBmenu_mark\fR(3X) +set_menu_opts \fBmitem_opts\fR(3X) +set_menu_pad \fBmenu_attributes\fR(3X) +set_menu_pattern \fBmenu_pattern\fR(3X) +set_menu_spacing \fBmenu_spacing\fR(3X) +set_menu_sub \fBmenu_win\fR(3X) +set_menu_term \fBmenu_hook\fR(3X) +set_menu_userptr \fBmenu_userptr\fR(3X) +set_menu_win \fBmenu_win\fR(3X) +set_top_row \fBmitem_current\fR(3X) +top_row \fBmitem_current\fR(3X) +unpost_menu \fBmenu_post\fR(3X) +.TE +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fR on error. Routines that return +an integer return one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NO_MATCH +Character failed to match. +.TP 5 +.B E_NO_ROOM +Menu is too large for its window. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.TP 5 +.B E_NOT_POSTED +The menu has not been posted. +.TP 5 +.B E_NOT_SELECTABLE +The designated item cannot be selected. +.TP 5 +.B E_POSTED +The menu is already posted. +.TP 5 +.B E_REQUEST_DENIED +The menu driver could not process the request. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_UNKNOWN_COMMAND +The menu driver code saw an unknown request code. +.SH SEE ALSO +\fBcurses\fR(3X) and related pages whose names begin "menu_" for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header files +\fB<curses.h>\fR and \fB<eti.h>\fR. +.PP +In your library list, libmenu.a should be before libncurses.a; that is, +you want to say `-lmenu -lncurses', not the other way around (which would +usually give a link-error). +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric +S. Raymond. +.SH SEE ALSO +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_attributes.3x b/man/menu_attributes.3x new file mode 100644 index 000000000000..d96ea234fd84 --- /dev/null +++ b/man/menu_attributes.3x @@ -0,0 +1,100 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2002,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_attributes.3x,v 1.9 2006/11/04 17:12:00 tom Exp $ +.TH menu_attributes 3X "" +.SH NAME +\fBmenu_attributes\fR - color and attribute control for menus +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_menu_fore(MENU *menu, chtype attr); +.br +chtype menu_fore(const MENU *menu); +.br +int set_menu_back(MENU *menu, chtype attr); +.br +chtype menu_back(const MENU *menu); +.br +int set_menu_grey(MENU *menu, chtype attr); +.br +chtype menu_grey(const MENU *menu); +.br +int set_menu_pad(MENU *menu, int pad); +.br +int menu_pad(const MENU *menu); +.br +.SH DESCRIPTION +The function \fBset_menu_fore\fR sets the foreground attribute of +\fImenu\fR. This is the highlight used for selected menu items. +\fBmenu_fore\fR returns the foreground attribute. The default +is \fBA_STANDOUT\fR. +.PP +The function \fBset_menu_back\fR sets the background attribute of +\fImenu\fR. This is the highlight used for selectable (but not currently +selected) menu items. The function \fBmenu_back\fR returns the background +attribute. The default is \fBA_NORMAL\fR. +.PP +The function \fBset_menu_grey\fR sets the grey attribute of \fImenu\fR. This is +the highlight used for un-selectable menu items in menus that permit more than +one selection. The function \fBmenu_grey\fR returns the grey attribute. +The default is \fBA_UNDERLINE\fR. +.PP +The function \fBset_menu_pad\fR sets the character used to fill the space +between the name and description parts of a menu item. \fBmenu_pad\fR returns +the given menu's pad character. The default is a blank. +.SH RETURN VALUE +These routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.SH SEE ALSO +\fBcurses\fR(3X) and related pages whose names begin "menu_" for detailed +descriptions of the entry points. +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_cursor.3x b/man/menu_cursor.3x new file mode 100644 index 000000000000..4ade0bf96269 --- /dev/null +++ b/man/menu_cursor.3x @@ -0,0 +1,73 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_cursor.3x,v 1.6 2006/11/04 17:13:57 tom Exp $ +.TH menu_cursor 3X "" +.SH NAME +\fBmenu_cursor\fR - position a menu's cursor +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int pos_menu_cursor(const MENU *menu); +.br +.SH DESCRIPTION +The function \fBpos_menu_cursor\fR restores the cursor to the current position +associated with the menu's selected item. This is useful after \fBcurses\fR +routines have been called to do screen-painting in response to a menu select. +.SH RETURN VALUE +This routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_NOT_POSTED +The menu has not been posted. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_driver.3x b/man/menu_driver.3x new file mode 100644 index 000000000000..bf7d8770a449 --- /dev/null +++ b/man/menu_driver.3x @@ -0,0 +1,201 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_driver.3x,v 1.14 2007/06/02 22:50:09 tom Exp $ +.TH menu_driver 3X "" +.SH NAME +\fBmenu_driver\fR - command-processing loop of the menu system +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int menu_driver(MENU *menu, int c); +.br +.SH DESCRIPTION +Once a menu has been posted (displayed), you should funnel input events to it +through \fBmenu_driver\fR. This routine has three major input cases; either +the input is a menu navigation request, it is a printable ASCII character or it +is the KEY_MOUSE special key associated with an mouse event. +The menu driver requests are as follows: +.TP 5 +REQ_LEFT_ITEM +Move left to an item. +.TP 5 +REQ_RIGHT_ITEM +Move right to an item. +.TP 5 +REQ_UP_ITEM +Move up to an item. +.TP 5 +REQ_DOWN_ITEM +Move down to an item. +.TP 5 +REQ_SCR_ULINE +Scroll up a line. +.TP 5 +REQ_SCR_DLINE +Scroll down a line. +.TP 5 +REQ_SCR_DPAGE +Scroll down a page. +.TP 5 +REQ_SCR_UPAGE +Scroll up a page. +.TP 5 +REQ_FIRST_ITEM +Move to the first item. +.TP 5 +REQ_LAST_ITEM +Move to the last item. +.TP 5 +REQ_NEXT_ITEM +Move to the next item. +.TP 5 +REQ_PREV_ITEM +Move to the previous item. +.TP 5 +REQ_TOGGLE_ITEM +Select/deselect an item. +.TP 5 +REQ_CLEAR_PATTERN +Clear the menu pattern buffer. +.TP 5 +REQ_BACK_PATTERN +Delete the previous character from the pattern buffer. +.TP 5 +REQ_NEXT_MATCH +Move to the next item matching the pattern match. +.TP 5 +REQ_PREV_MATCH +Move to the previous item matching the pattern match. +.PP +If the second argument is a printable ASCII character, the code appends +it to the pattern buffer and attempts to move to the next item matching +the new pattern. If there is no such match, \fBmenu_driver\fR returns +\fBE_NO_MATCH\fR and deletes the appended character from the buffer. +.PP +If the second argument is one of the above pre-defined requests, the +corresponding action is performed. +.SS MOUSE HANDLING +.PP +If the second argument is the KEY_MOUSE special key, the associated +mouse event is translated into one of the above pre-defined requests. +Currently only clicks in the user window (e.g. inside the menu display +area or the decoration window) are handled. +.PP +If you click above the display region of the menu: +.RS +.TP +a REQ_SCR_ULINE is generated for a single click, +.TP +a REQ_SCR_UPAGE is generated for a double-click and +.TP +a REQ_FIRST_ITEM is generated for a triple-click. +.RE +.PP +If you click below the display region of the menu: +.RS +.TP +a REQ_SCR_DLINE is generated for a single click, +.TP +a REQ_SCR_DPAGE is generated for a double-click and +.TP +a REQ_LAST_ITEM is generated for a triple-click. +.RE +.PP +If you click at an item inside the display area of the menu: +.RS +.TP 3 +- +the menu cursor is positioned to that item. +.TP 3 +- +If you double-click an item a REQ_TOGGLE_ITEM +is generated and \fBE_UNKNOWN_COMMAND\fR is returned. +This return value makes sense, +because a double click usually means that an item-specific action should +be returned. +It is exactly the purpose of this return value to signal that an +application specific command should be executed. +.TP 3 +- +If a translation +into a request was done, \fBmenu_driver\fR returns the result of this request. +.RE +.PP +If you clicked outside the user window or the mouse event couldn't be translated +into a menu request an \fBE_REQUEST_DENIED\fR is returned. +.SS APPLICATION-DEFINED COMMANDS +.PP +If the second argument is neither printable ASCII nor one of the above +pre-defined menu requests or KEY_MOUSE, the drive assumes it is an application-specific +command and returns \fBE_UNKNOWN_COMMAND\fR. Application-defined commands +should be defined relative to \fBMAX_COMMAND\fR, the maximum value of these +pre-defined requests. +.SH RETURN VALUE +\fBmenu_driver\fR return one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NOT_POSTED +The menu has not been posted. +.TP 5 +.B E_UNKNOWN_COMMAND +The menu driver code saw an unknown request code. +.TP 5 +.B E_NO_MATCH +Character failed to match. +.TP 5 +.B E_REQUEST_DENIED +The menu driver could not process the request. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header files +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. The support for mouse events is ncurses specific. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_format.3x b/man/menu_format.3x new file mode 100644 index 000000000000..f4d456f6f960 --- /dev/null +++ b/man/menu_format.3x @@ -0,0 +1,87 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2001,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_format.3x,v 1.10 2006/11/04 17:12:00 tom Exp $ +.TH menu_format 3X "" +.SH NAME +\fBmenu_format\fR - set and get menu sizes +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_menu_format(MENU *menu, int rows, int cols); +.br +void menu_format(const MENU *menu, int *rows, int *cols); +.br +.SH DESCRIPTION +The function \fBset_menu_format\fR sets the maximum display size of the given +menu. If this size is too small to display all menu items, the menu will be +made scrollable. If this size is larger than the menus subwindow and the +subwindow is too small to display all menu items, \fBpost_menu()\fR will fail. +.PP +The default format is 16 rows, 1 column. Calling \fBset_menu_format\fR with a +null menu pointer will change this default. A zero row or column argument to +\fBset_menu_format\fR is interpreted as a request not to change the current +value. +.PP +The function \fBmenu_format\fR returns the maximum-size constraints for the +given menu into the storage addressed by \fBrows\fR and \fBcols\fR. +.SH RETURN VALUE +These routines returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The menu is already posted. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_hook.3x b/man/menu_hook.3x new file mode 100644 index 000000000000..204e1ec41500 --- /dev/null +++ b/man/menu_hook.3x @@ -0,0 +1,101 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_hook.3x,v 1.9 2007/02/24 17:34:08 tom Exp $ +.TH menu_hook 3X "" +.SH NAME +\fBmenu_hook\fR - set hooks for automatic invocation by applications +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_item_init(MENU *menu, Menu_Hook func); +.br +Menu_Hook item_init(const MENU *menu); +.br +int set_item_term(MENU *menu, Menu_Hook func); +.br +Menu_Hook item_term(const MENU *menu); +.br +int set_menu_init(MENU *menu, Menu_Hook func); +.br +Menu_Hook menu_init(const MENU *menu); +.br +int set_menu_term(MENU *menu, Menu_Hook func); +.br +Menu_Hook menu_term(const MENU *menu); +.br +.SH DESCRIPTION +These functions make it possible to set hook functions to be called at various +points in the automatic processing of input event codes by \fBmenu_driver\fR. +.PP +The function \fBset_item_init\fR sets a hook to be called at menu-post time and +each time the selected item changes (after the change). \fBitem_init\fR +returns the current item init hook, if any (\fBNULL\fR if there is no such +hook). +.PP +The function \fBset_item_term\fR sets a hook to be called at menu-unpost time +and each time the selected item changes (before the change). \fBitem_term\fR +returns the current item term hook, if any (\fBNULL\fR if there is no such +hook). +.PP +The function \fBset_menu_init\fR sets a hook to be called at menu-post time and +just after the top row on the menu changes once it is posted. \fBmenu_init\fR +returns the current menu init hook, if any (\fBNULL\fR if there is no such +hook). +.PP +The function \fBset_menu_term\fR sets a hook to be called at menu-unpost time +and just before the top row on the menu changes once it is posted. +\fBmenu_term\fR returns the current menu term hook, if any (\fBNULL\fR if there +is no such hook). +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fR on error. Other routines +return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_items.3x b/man/menu_items.3x new file mode 100644 index 000000000000..091534385368 --- /dev/null +++ b/man/menu_items.3x @@ -0,0 +1,93 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_items.3x,v 1.7 2006/11/04 18:35:31 tom Exp $ +.TH menu_items 3X "" +.SH NAME +\fBmenu_items\fR - make and break connections between items and menus +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_menu_items(MENU *menu, ITEM **items); +.br +ITEM **menu_items(const MENU *menu); +.br +int item_count(const MENU *menu); +.br +.SH DESCRIPTION +The function \fBset_menu_items\fR changes the item pointer array of the given +\fImenu\fR. The array must be terminated by a \fBNULL\fR. +.PP +The function \fBmenu_items\fR returns the item array of the given menu. +.PP +The function \fBitem_count\fR returns the count of items in \fImenu\fR. +.SH RETURN VALUES +The function \fBmenu_items\fR returns a pointer (which may be \fBNULL\fR). +It does not set errno. +.PP +The function \fBitem_count\fR returns \fBERR\fR (the general \fBcurses\fR error +return value) if its \fImenu\fP parameter is \fBNULL\fP. +.PP +The function \fBset_menu_items\fR returns one of the following codes on error: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.TP 5 +.B E_POSTED +The menu is already posted. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.PP +The SVr4 menu library documentation specifies the \fBitem_count\fR error value +as -1 (which is the value of \fBERR\fR). +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_mark.3x b/man/menu_mark.3x new file mode 100644 index 000000000000..1db2b3ee1974 --- /dev/null +++ b/man/menu_mark.3x @@ -0,0 +1,86 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_mark.3x,v 1.9 2006/11/04 18:33:18 tom Exp $ +.TH menu_mark 3X "" +.SH NAME +\fBmenu_mark\fR - get and set the menu mark string +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_menu_mark(MENU *menu, const char *mark); +.br +const char *menu_mark(const MENU *menu); +.br +.SH DESCRIPTION +In order to make menu selections visible on older terminals without +highlighting or color capability, the menu library marks selected items +in a menu with a prefix string. +.PP +The function \fBset_menu_mark\fR sets the mark string for the given menu. +Calling \fBset_menu_mark\fR with a null menu item will abolish the mark string. +Note that changing the length of the mark string for a menu while the +menu is posted is likely to produce unhelpful behavior. +.PP +The default string is "-" (a dash). Calling \fBset_menu_mark\fR with +a non-\fBNULL\fR menu argument will change this default. +.PP +The function \fBmenu_mark\fR returns the menu's mark string (or \fBNULL\fR if +there is none). +.SH RETURN VALUE +The function \fBmenu_mark\fR returns a pointer (which may be \fBNULL\fR). +It does not set errno. +.PP +The function \fBset_menu_mark\fR may return the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_new.3x b/man/menu_new.3x new file mode 100644 index 000000000000..c2b98e499055 --- /dev/null +++ b/man/menu_new.3x @@ -0,0 +1,86 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_new.3x,v 1.9 2006/11/04 18:31:37 tom Exp $ +.TH menu_new 3X "" +.SH NAME +\fBmenu_new\fR - create and destroy menus +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +MENU *new_menu(ITEM **items); +.br +int free_menu(MENU *menu); +.br +.SH DESCRIPTION +The function \fBnew_menu\fR creates a new menu connected to a specified item +pointer array (which must be \fBNULL\fR-terminated). +.PP +The function \fBfree_menu\fR disconnects \fImenu\fR from its item array +and frees the storage allocated for the menu. +.SH RETURN VALUE +The function \fBnew_menu\fR returns \fBNULL\fR on error. +It sets errno according to the function's failure: +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred, e.g., malloc failure. +.PP +The function \fBfree_menu\fR returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The menu has already been posted. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_opts.3x b/man/menu_opts.3x new file mode 100644 index 000000000000..dc927c47700c --- /dev/null +++ b/man/menu_opts.3x @@ -0,0 +1,104 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_opts.3x,v 1.10 2007/02/24 17:33:59 tom Exp $ +.TH menu_opts 3X "" +.SH NAME +\fBmenu_opts\fR - set and get menu options +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_menu_opts(MENU *menu, Menu_Options opts); +.br +int menu_opts_on(MENU *menu, Menu_Options opts); +.br +int menu_opts_off(MENU *menu, Menu_Options opts); +.br +Menu_Options menu_opts(const MENU *menu); +.br +.SH DESCRIPTION +The function \fBset_menu_opts\fR sets all the given menu's option bits (menu +option bits may be logically-OR'ed together). +.PP +The function \fBmenu_opts_on\fR turns on the given option bits, and leaves +others alone. +.PP +The function \fBmenu_opts_off\fR turns off the given option bits, and leaves +others alone. +.PP +The function \fBmenu_opts\fR returns the menu's current option bits. +.PP +The following options are defined (all are on by default): +.TP 5 +O_ONEVALUE +Only one item can be selected for this menu. +.TP 5 +O_SHOWDESC +Display the item descriptions when the menu is posted. +.TP 5 +O_ROWMAJOR +Display the menu in row-major order. +.TP 5 +O_IGNORECASE +Ignore the case when pattern-matching. +.TP 5 +O_SHOWMATCH +Move the cursor to within the item name while pattern-matching. +.TP 5 +O_NONCYCLIC +Don't wrap around next-item and previous-item, +requests to the other end of the menu. +.SH RETURN VALUE +Except for \fBmenu_opts\fR, each routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_POSTED +The menu is already posted. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_pattern.3x b/man/menu_pattern.3x new file mode 100644 index 000000000000..50dee87a1e84 --- /dev/null +++ b/man/menu_pattern.3x @@ -0,0 +1,91 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_pattern.3x,v 1.10 2006/11/04 18:25:24 tom Exp $ +.TH menu_pattern 3X "" +.SH NAME +\fBmenu_pattern\fR - get and set a menu's pattern buffer +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_menu_pattern(MENU *menu, const char *pattern); +.br +char *menu_pattern(const MENU *menu); +.br +.SH DESCRIPTION +Every menu has an associated pattern match buffer. As input events that are +printable ASCII characters come in, they are appended to this match buffer +and tested for a match, as described in \fBmenu_driver\fR(3X). +.PP +The function \fBset_menu_pattern\fR sets the pattern buffer for the given menu +and tries to find the first matching item. If it succeeds, that item becomes +current; if not, the current item does not change. +.PP +The function \fBmenu_pattern\fR returns the pattern buffer of the given +\fImenu\fR. +.SH RETURN VALUE +The function \fBmenu_pattern\fR returns a pointer, which is \fBNULL\fR if the \fImenu\fP parameter is \fBNULL\fP. +Otherwise, it is a pointer to a string which is empty if no pattern has been set. +It does not set errno. +.PP +The function \fBset_menu_pattern\fR may return the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to menu. +.TP 5 +.B E_NO_MATCH +Character failed to match. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_post.3x b/man/menu_post.3x new file mode 100644 index 000000000000..e47facc9e4d9 --- /dev/null +++ b/man/menu_post.3x @@ -0,0 +1,91 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_post.3x,v 1.9 2006/11/04 17:12:00 tom Exp $ +.TH menu_post 3X "" +.SH NAME +\fBmenu_post\fR - write or erase menus from associated subwindows +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int post_menu(MENU *menu); +.br +int unpost_menu(MENU *menu); +.br +.SH DESCRIPTION +The function \fBpost_menu\fR displays a menu to its associated subwindow. To +trigger physical display of the subwindow, use \fBrefresh\fR or some equivalent +\fBcurses\fR routine (the implicit \fBdoupdate\fR triggered by an \fBcurses\fR +input request will do). \fBpost_menu\fR resets the selection status of all items. +.PP +The function \fBunpost_menu\fR erases menu from its associated subwindow. +.SH RETURN VALUE +These routines return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The menu has already been posted. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NO_ROOM +Menu is too large for its window. You should consider to use +\fBset_menu_format()\fR to solve the problem. +.TP 5 +.B E_NOT_POSTED +The menu has not been posted. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_requestname.3x b/man/menu_requestname.3x new file mode 100644 index 000000000000..1345aa784851 --- /dev/null +++ b/man/menu_requestname.3x @@ -0,0 +1,71 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_requestname.3x,v 1.7 2006/11/04 17:56:09 tom Exp $ +.TH menu_requestname 3X "" +.SH NAME +\fBmenu_requestname\fR - handle printable menu request names +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +const char *menu_request_name(int request); +.br +int menu_request_by_name(const char *name); +.br +.SH DESCRIPTION +The function \fBmenu_request_name\fR returns the printable name of a menu +request code. +.br +The function \fBmenu_request_by_name\fR searches in the name-table for a request +with the given name and returns its request code. +Otherwise E_NO_MATCH is returned. +.SH RETURN VALUE +\fBmenu_request_name\fR returns \fBNULL\fR on error +and sets errno to \fBE_BAD_ARGUMENT\fR. +.br +\fBmenu_request_by_name\fR returns \fBE_NO_MATCH\fR on error. +It does not set errno. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These 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 them be conditioned using NCURSES_VERSION. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_spacing.3x b/man/menu_spacing.3x new file mode 100644 index 000000000000..dfe03a8a55b1 --- /dev/null +++ b/man/menu_spacing.3x @@ -0,0 +1,84 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2001,2004 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_spacing.3x,v 1.8 2004/12/11 23:39:07 tom Exp $ +.TH menu_spacing 3X "" +.SH NAME +\fBmenu_spacing\fR - Control spacing between menu items. +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_menu_spacing(MENU *menu, + int spc_description, + int spc_rows, + int spc_columns); +.br +int menu_spacing(const MENU *menu, + int* spc_description, + int* spc_rows, + int* spc_columns); +.br +.SH DESCRIPTION +The function \fBset_menu_spacing\fR sets the spacing informations for the menu. +\fBspc_description\fR controls the number of spaces between an item name and an item +description. It must not be larger than \fBTABSIZE\fR. The menu system puts in the +middle of this spacing area the pad character. The remaining parts are filled with +spaces. +\fBspc_rows\fR controls the number of rows that are used for an item. It must not be +larger than 3. The menu system inserts the blank lines between item rows, these lines +will contain the pad character in the appropriate positions. +\fBspc_columns\fR controls the number of blanks between columns of items. It must not +be larger than TABSIZE. +A value of 0 for all the spacing values resets them to the default, which is 1 for all +of them. +.br +The function \fBmenu_spacing\fR passes back the spacing info for the menu. If a +pointer is NULL, this specific info is simply not returned. +.SH RETURN VALUE +Both routines return \fBE_OK\fR on success. \fBset_menu_spacing\fR may return +\fBE_POSTED\fR if the menu is posted, or \fBE_BAD_ARGUMENT\fR if one of the +spacing values is out of range. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These 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 them be conditioned using NCURSES_VERSION. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_userptr.3x b/man/menu_userptr.3x new file mode 100644 index 000000000000..b7be2adcd8d0 --- /dev/null +++ b/man/menu_userptr.3x @@ -0,0 +1,69 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_userptr.3x,v 1.8 2006/11/04 18:21:03 tom Exp $ +.TH menu_userptr 3X "" +.SH NAME +\fBmenu_userptr\fR - associate application data with a menu item +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_menu_userptr(MENU *menu, void *userptr); +.br +void *menu_userptr(const MENU *menu); +.br +.SH DESCRIPTION +Every menu and every menu item has a field that can be used to hold +application-specific data (that is, the menu-driver code leaves it alone). +These functions get and set the menu user pointer field. +.SH RETURN VALUE +\fBmenu_userptr\fR returns a pointer (which may be \fBNULL\fR). +It does not set errno. +.PP +\fBset_menu_userptr\fP returns \fBE_OK\fP (success). +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.PP +The user pointer is a void pointer. +We chose not to leave it as a char pointer for SVr4 compatibility. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/menu_win.3x b/man/menu_win.3x new file mode 100644 index 000000000000..aa356e18de7e --- /dev/null +++ b/man/menu_win.3x @@ -0,0 +1,95 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: menu_win.3x,v 1.8 2006/11/04 17:12:00 tom Exp $ +.TH menu_win 3X "" +.SH NAME +\fBmenu_win\fR - make and break menu window and subwindow associations +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_menu_win(MENU *menu, WINDOW *win); +.br +WINDOW *menu_win(const MENU *menu); +.br +int set_menu_sub(MENU *menu, WINDOW *sub); +.br +WINDOW *menu_sub(const MENU *menu); +.br +int scale_menu(const MENU *menu, int *rows, int *columns); +.br +.SH DESCRIPTION +Every menu has an associated pair of \fBcurses\fR windows. The menu window +displays any title and border associated with the window; the menu subwindow +displays the items of the menu that are currently available for selection. +.PP +The first four functions get and set those windows. It is not necessary to set +either window; by default, the driver code uses \fBstdscr\fR for both. +.PP +In the \fBset_\fR functions, window argument of \fBNULL\fR is treated as though +it were \fBstsdcr\fR. A menu argument of \fBNULL\fR is treated as a request +to change the system default menu window or subwindow. +.PP +The function \fBscale_menu\fR returns the minimum size required for the +subwindow of \fImenu\fR. +.SH RETURN VALUE +Routines that return pointers return \fBNULL\fR on error. Routines that return +an integer return one of the following error codes: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_POSTED +The menu has already been posted. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/mitem_current.3x b/man/mitem_current.3x new file mode 100644 index 000000000000..979f401341fe --- /dev/null +++ b/man/mitem_current.3x @@ -0,0 +1,102 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_current.3x,v 1.11 2006/11/04 18:18:19 tom Exp $ +.TH mitem_current 3X "" +.SH NAME +\fBmitem_current\fR - set and get current_menu_item +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_current_item(MENU *menu, const ITEM *item); +.br +ITEM *current_item(const MENU *menu); +.br +int set_top_row(MENU *menu, int row); +.br +int top_row(const MENU *menu); +.br +int item_index(const ITEM *item); +.br +.SH DESCRIPTION +The function \fBset_current_item\fR sets the current item (the item on which +the menu cursor is positioned). \fBcurrent_item\fR returns a pointer to the +current item in the given menu. +.PP +The function \fBset_top_row\fR sets the top row of the menu to show the given +row (the top row is initially 0, and is reset to this value whenever the +\fBO_ROWMAJOR\fR option is toggled). The item leftmost on the given row +becomes current. The function \fBtop_row\fR returns the number of the top menu +row being displayed. +.PP +The function \fBitem_index\fR returns the (zero-origin) index of \fIitem\fR in +the menu's item pointer list. +.SH RETURN VALUE +\fBcurrent_item\fR returns a pointer (which may be \fBNULL\fR). +It does not set errno. +.PP +\fBtop_row\fR and \fBitem_index\fR return \fBERR\fR (the general \fBcurses\fR +error value) if their \fImenu\fP parameter is \fBNULL\fP. +.PP +\fBset_current_item\fR and \fBset_top_row\fR return one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_BAD_STATE +Routine was called from an initialization or termination function. +.TP 5 +.B E_NOT_CONNECTED +No items are connected to the menu. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.PP +The SVr4 menu library documentation specifies the \fBtop_row\fR and +\fBindex_item\fR error value as -1 (which is the value of \fBERR\fR). +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/mitem_name.3x b/man/mitem_name.3x new file mode 100644 index 000000000000..12009edace35 --- /dev/null +++ b/man/mitem_name.3x @@ -0,0 +1,65 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_name.3x,v 1.6 2006/11/04 17:53:40 tom Exp $ +.TH mitem_name 3X "" +.SH NAME +\fBmitem_name\fR - get menu item name and description fields +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +const char *item_name(const ITEM *item); +.br +const char *item_description(const ITEM *item); +.br +.SH DESCRIPTION +The function \fBitem_name\fR returns the name part of the given item. +.br +The function \fBitem_description\fR returns the description part of the given +item. +.SH RETURN VALUE +These routines return a pointer (which may be \fBNULL\fR). +They do not set errno. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. +They were not supported on Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/mitem_new.3x b/man/mitem_new.3x new file mode 100644 index 000000000000..c0fa6edcf64a --- /dev/null +++ b/man/mitem_new.3x @@ -0,0 +1,90 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_new.3x,v 1.10 2006/11/04 18:16:36 tom Exp $ +.TH mitem_new 3X "" +.SH NAME +\fBmitem_new\fR - create and destroy menu items +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +ITEM *new_item(const char *name, const char *description); +.br +int free_item(ITEM *item); +.br +.SH DESCRIPTION +The function \fBnew_item\fR allocates a new item and initializes it from the +\fBname\fR and \fBdescription\fR pointers. Please notice that the item stores +only the pointers to the name and description. Those pointers must be valid +during the lifetime of the item. So you should be very careful with names +or descriptions allocated on the stack of some routines. +.br +The function \fBfree_item\fR de-allocates an item. Please notice that it +is the responsibility of the application to release the memory for the +name or the description of the item. +.SH RETURN VALUE +The function \fBnew_item\fR returns \fBNULL\fR on error. +It sets errno according to the function's failure: +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred, e.g., malloc failure. +.PP +The function \fBfree_item\fR returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_BAD_ARGUMENT +Routine detected an incorrect or out-of-range argument. +.TP 5 +.B E_CONNECTED +Item is connected to a menu. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/mitem_opts.3x b/man/mitem_opts.3x new file mode 100644 index 000000000000..2459dabfbae6 --- /dev/null +++ b/man/mitem_opts.3x @@ -0,0 +1,84 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_opts.3x,v 1.9 2007/02/24 17:33:32 tom Exp $ +.TH mitem_opts 3X "" +.SH NAME +\fBmitem_opts\fR - set and get menu item options +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_item_opts(ITEM *item, Item_Options opts); +.br +int item_opts_on(ITEM *item, Item_Options opts); +.br +int item_opts_off(ITEM *item, Item_Options opts); +.br +Item_Options item_opts(const ITEM *item); +.br +.SH DESCRIPTION +The function \fBset_item_opts\fR sets all the given item's option bits (menu +option bits may be logically-OR'ed together). +.PP +The function \fBitem_opts_on\fR turns on the given option bits, and leaves +others alone. +.PP +The function \fBitem_opts_off\fR turns off the given option bits, and leaves +others alone. +.PP +The function \fBitem_opts\fR returns the item's current option bits. +.PP +There is only one defined option bit mask, \fBO_SELECTABLE\fR. When this is +on, the item may be selected during menu processing. This option defaults +to on. +.SH RETURN VALUE +Except for \fBitem_opts\fR, each routine returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/mitem_userptr.3x b/man/mitem_userptr.3x new file mode 100644 index 000000000000..58951930244c --- /dev/null +++ b/man/mitem_userptr.3x @@ -0,0 +1,70 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_userptr.3x,v 1.9 2006/11/04 18:21:03 tom Exp $ +.TH mitem_userptr 3X "" +.SH NAME +\fBmitem_userptr\fR - associate application data with a menu item +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_item_userptr(ITEM *item, void *userptr); +.br +void *item_userptr(const ITEM *item); +.br +.SH DESCRIPTION +Every menu item has a field that can be used to hold application-specific data +(that is, the menu-driver code leaves it alone). These functions get and set +that field. +.SH RETURN VALUE +The function \fBitem_userptr\fR returns a pointer (possibly \fBNULL\fR). +It does not set errno. +.PP +The \fBset_item_userptr\fP always returns \fBE_OK\fP (success). +. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.PP +The user pointer is a void pointer. +We chose not to leave it as a char pointer for SVr4 compatibility. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/mitem_value.3x b/man/mitem_value.3x new file mode 100644 index 000000000000..748fd528675c --- /dev/null +++ b/man/mitem_value.3x @@ -0,0 +1,76 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2002,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_value.3x,v 1.8 2006/11/04 17:12:00 tom Exp $ +.TH mitem_value 3X "" +.SH NAME +\fBmitem_value\fR - set and get menu item values +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +int set_item_value(ITEM *item, bool value); +.br +bool item_value(const ITEM *item); +.br +.SH DESCRIPTION +If you turn off the menu option \fBO_ONEVALUE\fR (e.g., with +\fBset_menu_opts\fR or \fBmenu_opts_off\fR; see \fBmenu_opts\fR(3X)), the menu +becomes multi-valued; that is, more than one item may simultaneously be +selected. +.PP +In a multi_valued menu, you can used \fBset_item_value\fR to select the +given menu item (second argument \fBTRUE\fR) or deselect it (second argument +\fBFALSE\fR). +.SH RETURN VALUE +The function \fBset_item_value\fR returns one of the following: +.TP 5 +.B E_OK +The routine succeeded. +.TP 5 +.B E_SYSTEM_ERROR +System error occurred (see \fBerrno\fR). +.TP 5 +.B E_REQUEST_DENIED +The menu driver could not process the request. +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/mitem_visible.3x b/man/mitem_visible.3x new file mode 100644 index 000000000000..8f9039c2f6db --- /dev/null +++ b/man/mitem_visible.3x @@ -0,0 +1,59 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: mitem_visible.3x,v 1.5 1998/11/29 01:12:55 Rick.Ohnemus Exp $ +.TH mitem_visible 3X "" +.SH NAME +\fBmitem_visible\fR - check visibility of a menu item +.SH SYNOPSIS +\fB#include <menu.h>\fR +.br +bool item_visible(const ITEM *item); +.br +.SH DESCRIPTION +A menu item is visible when it is in the portion of a posted menu that +is mapped onto the screen (if the menu is scrollable, in particular, this +portion will be smaller than the whole menu). +.SH SEE ALSO +\fBcurses\fR(3X), \fBmenu\fR(3X). +.SH NOTES +The header file \fB<menu.h>\fR automatically includes the header file +\fB<curses.h>\fR. +.SH PORTABILITY +These routines emulate the System V menu library. They were not supported on +Version 7 or BSD versions. +.SH AUTHORS +Juergen Pfeifer. Manual pages and adaptation for new curses by Eric +S. Raymond. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/ncurses.3x b/man/ncurses.3x new file mode 100644 index 000000000000..ac3d049528c2 --- /dev/null +++ b/man/ncurses.3x @@ -0,0 +1,1141 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: ncurses.3x,v 1.89 2007/09/01 18:57:29 tom Exp $ +.hy 0 +.TH ncurses 3X "" +.ds n 5 +.ds d @TERMINFO@ +.SH NAME +\fBncurses\fR - CRT screen handling and optimization package +.SH SYNOPSIS +\fB#include <curses.h>\fR +.br +.SH DESCRIPTION +The \fBncurses\fR library routines give the user a terminal-independent method +of updating character screens with reasonable optimization. +This implementation is ``new curses'' (ncurses) and +is the approved replacement for +4.4BSD classic curses, which has been discontinued. +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.PP +The \fBncurses\fR library emulates the \fBcurses\fR(3X) library of +System V Release 4 UNIX, +and XPG4 (X/Open Portability Guide) curses (also known as XSI curses). +XSI stands for X/Open System Interfaces Extension. +The \fBncurses\fR library is freely redistributable in source form. +Differences from the SVr4 +curses are summarized under the \fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and +described in detail in the respective \fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections +of individual man pages. +.PP +The \fBncurses\fR library also provides many useful extensions, +i.e., features which cannot be implemented by a simple add-on library +but which require access to the internals of the library. +.PP +A program using these routines must be linked with the \fB-lncurses\fR option, +or (if it has been generated) with the debugging library \fB-lncurses_g\fR. +(Your system integrator may also have installed these libraries under +the names \fB-lcurses\fR and \fB-lcurses_g\fR.) +The ncurses_g library generates trace logs (in a file called 'trace' in the +current directory) that describe curses actions. +See also the section on \fBALTERNATE CONFIGURATIONS\fP. +.PP +The \fBncurses\fR package supports: overall screen, window and pad +manipulation; output to windows and pads; reading terminal input; control over +terminal and \fBcurses\fR input and output options; environment query +routines; color manipulation; use of soft label keys; terminfo capabilities; +and access to low-level terminal-manipulation routines. +.PP +To initialize the routines, the routine \fBinitscr\fR or \fBnewterm\fR +must be called before any of the other routines that deal with windows +and screens are used. +The routine \fBendwin\fR must be called before exiting. +To get character-at-a-time input without echoing (most +interactive, screen oriented programs want this), the following +sequence should be used: +.sp + \fBinitscr(); cbreak(); noecho();\fR +.sp +Most programs would additionally use the sequence: +.sp + \fBnonl();\fR + \fBintrflush(stdscr, FALSE);\fR + \fBkeypad(stdscr, TRUE);\fR +.sp +Before a \fBcurses\fR program is run, the tab stops of the terminal +should be set and its initialization strings, if defined, must be output. +This can be done by executing the \fBtput init\fR command +after the shell environment variable \fBTERM\fR has been exported. +\fBtset(1)\fR is usually responsible for doing this. +[See \fBterminfo\fR(\*n) for further details.] +.PP +The \fBncurses\fR library permits manipulation of data structures, +called \fIwindows\fR, which can be thought of as two-dimensional +arrays of characters representing all or part of a CRT screen. +A default window called \fBstdscr\fR, which is the size of the terminal +screen, is supplied. +Others may be created with \fBnewwin\fR. +.PP +Note that \fBcurses\fR does not handle overlapping windows, that's done by +the \fBpanel\fR(3X) library. +This means that you can either use +\fBstdscr\fR or divide the screen into tiled windows and not using +\fBstdscr\fR at all. +Mixing the two will result in unpredictable, and undesired, effects. +.PP +Windows are referred to by variables declared as \fBWINDOW *\fR. +These data structures are manipulated with routines described here and +elsewhere in the \fBncurses\fR manual pages. +Among those, the most basic +routines are \fBmove\fR and \fBaddch\fR. +More general versions of +these routines are included with names beginning with \fBw\fR, +allowing the user to specify a window. +The routines not beginning +with \fBw\fR affect \fBstdscr\fR. +.PP +After using routines to manipulate a window, \fBrefresh\fR is called, +telling \fBcurses\fR to make the user's CRT screen look like +\fBstdscr\fR. +The characters in a window are actually of type +\fBchtype\fR, (character and attribute data) so that other information +about the character may also be stored with each character. +.PP +Special windows called \fIpads\fR may also be manipulated. +These are windows +which are not constrained to the size of the screen and whose contents need not +be completely displayed. +See \fBcurs_pad\fR(3X) for more information. +.PP +In addition to drawing characters on the screen, video attributes and colors +may be supported, causing the characters to show up in such modes as +underlined, in reverse video, or in color on terminals that support such +display enhancements. +Line drawing characters may be specified to be output. +On input, \fBcurses\fR is also able to translate arrow and function keys that +transmit escape sequences into single values. +The video attributes, line +drawing characters, and input values use names, defined in \fB<curses.h>\fR, +such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR. +.PP +If the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if the +program is executing in a window environment, line and column information in +the environment will override information read by \fIterminfo\fR. +This would affect a program running in an AT&T 630 layer, +for example, where the size of a +screen is changeable (see \fBENVIRONMENT\fR). +.PP +If the environment variable \fBTERMINFO\fR is defined, any program using +\fBcurses\fR checks for a local terminal definition before checking in the +standard place. +For example, if \fBTERM\fR is set to \fBatt4424\fR, then the +compiled terminal definition is found in +.sp + \fB\*d/a/att4424\fR. +.sp +(The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoid +creation of huge directories.) However, if \fBTERMINFO\fR is set to +\fB$HOME/myterms\fR, \fBcurses\fR first checks +.sp + \fB$HOME/myterms/a/att4424\fR, +.sp +and if that fails, it then checks +.sp + \fB\*d/a/att4424\fR. +.sp +This is useful for developing experimental definitions or when write +permission in \fB\*d\fR is not available. +.PP +The integer variables \fBLINES\fR and \fBCOLS\fR are defined in +\fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of the +screen. +The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and +\fB0\fR, respectively. +.PP +The \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fR +which is used for certain low-level operations like clearing and redrawing a +screen containing garbage. +The \fBcurscr\fR can be used in only a few routines. +.\" +.SS Routine and Argument Names +Many \fBcurses\fR routines have two or more versions. +The routines prefixed with \fBw\fR require a window argument. +The routines prefixed with \fBp\fR require a pad argument. +Those without a prefix generally use \fBstdscr\fR. +.PP +The routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fR +coordinate to move to before performing the appropriate action. +The \fBmv\fR routines imply a call to \fBmove\fR before the call to the +other routine. +The coordinate \fIy\fR always refers to the row (of +the window), and \fIx\fR always refers to the column. +The upper left-hand corner is always (0,0), not (1,1). +.PP +The routines prefixed with \fBmvw\fR take both a window argument and +\fIx\fR and \fIy\fR coordinates. +The window argument is always specified before the coordinates. +.PP +In each case, \fIwin\fR is the window affected, and \fIpad\fR is the +pad affected; \fIwin\fR and \fIpad\fR are always pointers to type +\fBWINDOW\fR. +.PP +Option setting routines require a Boolean flag \fIbf\fR with the value +\fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR. +Most of the data types used in the library routines, +such as \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and \fBchtype\fR +are defined in \fB<curses.h>\fR. +Types used for the terminfo routines such as +\fBTERMINAL\fR are defined in \fB<term.h>\fR. +.PP +This manual page describes functions which may appear in any configuration +of the library. +There are two common configurations of the library: +.RS +.TP 5 +ncurses +the "normal" library, which handles 8-bit characters. +The normal (8-bit) library stores characters combined with attributes +in \fBchtype\fP data. +.IP +Attributes alone (no corresponding character) may be stored in \fBchtype\fP +or the equivalent \fBattr_t\fP data. +In either case, the data is stored in something like an integer. +.IP +Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBchtype\fP. +.TP 5 +ncursesw +the so-called "wide" library, which handles multibyte characters +(See the section on \fBALTERNATE CONFIGURATIONS\fP). +The "wide" library includes all of the calls from the "normal" library. +It adds about one third more calls using data types which store +multibyte characters: +.RS +.TP 5 +.B cchar_t +corresponds to \fBchtype\fP. +However it is a structure, because more data is stored than can fit into +an integer. +The characters are large enough to require a full integer value - and there +may be more than one character per cell. +The video attributes and color are stored in separate fields of the structure. +.IP +Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBcchar_t\fP. +.TP 5 +.B wchar_t +stores a "wide" character. +Like \fBchtype\fP, this may be an integer. +.TP 5 +.B wint_t +stores a \fBwchar_t\fP or \fBWEOF\fP - not the same, though both may have +the same size. +.RE +.IP +The "wide" library provides new functions which are analogous to +functions in the "normal" library. +There is a naming convention which relates many of the normal/wide variants: +a "_w" is inserted into the name. +For example, \fBwaddch\fP becomes \fBwadd_wch\fP. +.RE +.PP +.\" +.SS Routine Name Index +The following table lists each \fBcurses\fR routine and the name of +the manual page on which it is described. +Routines flagged with `*' +are ncurses-specific, not described by XPG4 or present in SVr4. +.PP +.TS +center tab(/); +l l +l l . +\fBcurses\fR Routine Name/Manual Page Name += +COLOR_PAIR/\fBcurs_color\fR(3X) +PAIR_NUMBER/\fBcurs_attr\fR(3X) +_nc_tracebits/\fBcurs_trace\fR(3X)* +_traceattr/\fBcurs_trace\fR(3X)* +_traceattr2/\fBcurs_trace\fR(3X)* +_tracechar/\fBcurs_trace\fR(3X)* +_tracechtype/\fBcurs_trace\fR(3X)* +_tracechtype2/\fBcurs_trace\fR(3X)* +_tracedump/\fBcurs_trace\fR(3X)* +_tracef/\fBcurs_trace\fR(3X)* +_tracemouse/\fBcurs_trace\fR(3X)* +add_wch/\fBcurs_add_wch\fR(3X) +add_wchnstr/\fBcurs_add_wchstr\fR(3X) +add_wchstr/\fBcurs_add_wchstr\fR(3X) +addch/\fBcurs_addch\fR(3X) +addchnstr/\fBcurs_addchstr\fR(3X) +addchstr/\fBcurs_addchstr\fR(3X) +addnstr/\fBcurs_addstr\fR(3X) +addnwstr/\fBcurs_addwstr\fR(3X) +addstr/\fBcurs_addstr\fR(3X) +addwstr/\fBcurs_addwstr\fR(3X) +assume_default_colors/\fBdefault_colors\fR(3X)* +attr_get/\fBcurs_attr\fR(3X) +attr_off/\fBcurs_attr\fR(3X) +attr_on/\fBcurs_attr\fR(3X) +attr_set/\fBcurs_attr\fR(3X) +attroff/\fBcurs_attr\fR(3X) +attron/\fBcurs_attr\fR(3X) +attrset/\fBcurs_attr\fR(3X) +baudrate/\fBcurs_termattrs\fR(3X) +beep/\fBcurs_beep\fR(3X) +bkgd/\fBcurs_bkgd\fR(3X) +bkgdset/\fBcurs_bkgd\fR(3X) +bkgrnd/\fBcurs_bkgrnd\fR(3X) +bkgrndset/\fBcurs_bkgrnd\fR(3X) +border/\fBcurs_border\fR(3X) +border_set/\fBcurs_border_set\fR(3X) +box/\fBcurs_border\fR(3X) +box_set/\fBcurs_border_set\fR(3X) +can_change_color/\fBcurs_color\fR(3X) +cbreak/\fBcurs_inopts\fR(3X) +chgat/\fBcurs_attr\fR(3X) +clear/\fBcurs_clear\fR(3X) +clearok/\fBcurs_outopts\fR(3X) +clrtobot/\fBcurs_clear\fR(3X) +clrtoeol/\fBcurs_clear\fR(3X) +color_content/\fBcurs_color\fR(3X) +color_set/\fBcurs_attr\fR(3X) +copywin/\fBcurs_overlay\fR(3X) +curs_set/\fBcurs_kernel\fR(3X) +curses_version/\fBcurs_extend\fR(3X)* +def_prog_mode/\fBcurs_kernel\fR(3X) +def_shell_mode/\fBcurs_kernel\fR(3X) +define_key/\fBdefine_key\fR(3X)* +del_curterm/\fBcurs_terminfo\fR(3X) +delay_output/\fBcurs_util\fR(3X) +delch/\fBcurs_delch\fR(3X) +deleteln/\fBcurs_deleteln\fR(3X) +delscreen/\fBcurs_initscr\fR(3X) +delwin/\fBcurs_window\fR(3X) +derwin/\fBcurs_window\fR(3X) +doupdate/\fBcurs_refresh\fR(3X) +dupwin/\fBcurs_window\fR(3X) +echo/\fBcurs_inopts\fR(3X) +echo_wchar/\fBcurs_add_wch\fR(3X) +echochar/\fBcurs_addch\fR(3X) +endwin/\fBcurs_initscr\fR(3X) +erase/\fBcurs_clear\fR(3X) +erasechar/\fBcurs_termattrs\fR(3X) +erasewchar/\fBcurs_termattrs\fR(3X) +filter/\fBcurs_util\fR(3X) +flash/\fBcurs_beep\fR(3X) +flushinp/\fBcurs_util\fR(3X) +get_wch/\fBcurs_get_wch\fR(3X) +get_wstr/\fBcurs_get_wstr\fR(3X) +getattrs/\fBcurs_attr\fR(3X) +getbegx/\fBcurs_legacy\fR(3X)* +getbegy/\fBcurs_legacy\fR(3X)* +getbegyx/\fBcurs_getyx\fR(3X) +getbkgd/\fBcurs_bkgd\fR(3X) +getbkgrnd/\fBcurs_bkgrnd\fR(3X) +getcchar/\fBcurs_getcchar\fR(3X) +getch/\fBcurs_getch\fR(3X) +getcurx/\fBcurs_legacy\fR(3X)* +getcury/\fBcurs_legacy\fR(3X)* +getmaxx/\fBcurs_legacy\fR(3X)* +getmaxy/\fBcurs_legacy\fR(3X)* +getmaxyx/\fBcurs_getyx\fR(3X) +getmouse/\fBcurs_mouse\fR(3X)* +getn_wstr/\fBcurs_get_wstr\fR(3X) +getnstr/\fBcurs_getstr\fR(3X) +getparx/\fBcurs_legacy\fR(3X)* +getpary/\fBcurs_legacy\fR(3X)* +getparyx/\fBcurs_getyx\fR(3X) +getstr/\fBcurs_getstr\fR(3X) +getsyx/\fBcurs_kernel\fR(3X) +getwin/\fBcurs_util\fR(3X) +getyx/\fBcurs_getyx\fR(3X) +halfdelay/\fBcurs_inopts\fR(3X) +has_colors/\fBcurs_color\fR(3X) +has_ic/\fBcurs_termattrs\fR(3X) +has_il/\fBcurs_termattrs\fR(3X) +has_key/\fBcurs_getch\fR(3X)* +hline/\fBcurs_border\fR(3X) +hline_set/\fBcurs_border_set\fR(3X) +idcok/\fBcurs_outopts\fR(3X) +idlok/\fBcurs_outopts\fR(3X) +immedok/\fBcurs_outopts\fR(3X) +in_wch/\fBcurs_in_wch\fR(3X) +in_wchnstr/\fBcurs_in_wchstr\fR(3X) +in_wchstr/\fBcurs_in_wchstr\fR(3X) +inch/\fBcurs_inch\fR(3X) +inchnstr/\fBcurs_inchstr\fR(3X) +inchstr/\fBcurs_inchstr\fR(3X) +init_color/\fBcurs_color\fR(3X) +init_pair/\fBcurs_color\fR(3X) +initscr/\fBcurs_initscr\fR(3X) +innstr/\fBcurs_instr\fR(3X) +innwstr/\fBcurs_inwstr\fR(3X) +ins_nwstr/\fBcurs_ins_wstr\fR(3X) +ins_wch/\fBcurs_ins_wch\fR(3X) +ins_wstr/\fBcurs_ins_wstr\fR(3X) +insch/\fBcurs_insch\fR(3X) +insdelln/\fBcurs_deleteln\fR(3X) +insertln/\fBcurs_deleteln\fR(3X) +insnstr/\fBcurs_insstr\fR(3X) +insstr/\fBcurs_insstr\fR(3X) +instr/\fBcurs_instr\fR(3X) +intrflush/\fBcurs_inopts\fR(3X) +inwstr/\fBcurs_inwstr\fR(3X) +is_cleared/\fBcurs_opaque\fR(3X)* +is_idcok/\fBcurs_opaque\fR(3X)* +is_idlok/\fBcurs_opaque\fR(3X)* +is_immedok/\fBcurs_opaque\fR(3X)* +is_keypad/\fBcurs_opaque\fR(3X)* +is_leaveok/\fBcurs_opaque\fR(3X)* +is_linetouched/\fBcurs_touch\fR(3X) +is_nodelay/\fBcurs_opaque\fR(3X)* +is_notimeout/\fBcurs_opaque\fR(3X)* +is_scrollok/\fBcurs_opaque\fR(3X)* +is_syncok/\fBcurs_opaque\fR(3X)* +is_term_resized/\fBresizeterm\fR(3X)* +is_wintouched/\fBcurs_touch\fR(3X) +isendwin/\fBcurs_initscr\fR(3X) +key_defined/\fBkey_defined\fR(3X)* +key_name/\fBcurs_util\fR(3X) +keybound/\fBkeybound\fR(3X)* +keyname/\fBcurs_util\fR(3X) +keyok/\fBkeyok\fR(3X)* +keypad/\fBcurs_inopts\fR(3X) +killchar/\fBcurs_termattrs\fR(3X) +killwchar/\fBcurs_termattrs\fR(3X) +leaveok/\fBcurs_outopts\fR(3X) +longname/\fBcurs_termattrs\fR(3X) +mcprint/\fBcurs_print\fR(3X)* +meta/\fBcurs_inopts\fR(3X) +mouse_trafo/\fBcurs_mouse\fR(3X)* +mouseinterval/\fBcurs_mouse\fR(3X)* +mousemask/\fBcurs_mouse\fR(3X)* +move/\fBcurs_move\fR(3X) +mvadd_wch/\fBcurs_add_wch\fR(3X) +mvadd_wchnstr/\fBcurs_add_wchstr\fR(3X) +mvadd_wchstr/\fBcurs_add_wchstr\fR(3X) +mvaddch/\fBcurs_addch\fR(3X) +mvaddchnstr/\fBcurs_addchstr\fR(3X) +mvaddchstr/\fBcurs_addchstr\fR(3X) +mvaddnstr/\fBcurs_addstr\fR(3X) +mvaddnwstr/\fBcurs_addwstr\fR(3X) +mvaddstr/\fBcurs_addstr\fR(3X) +mvaddwstr/\fBcurs_addwstr\fR(3X) +mvchgat/\fBcurs_attr\fR(3X) +mvcur/\fBcurs_terminfo\fR(3X) +mvdelch/\fBcurs_delch\fR(3X) +mvderwin/\fBcurs_window\fR(3X) +mvget_wch/\fBcurs_get_wch\fR(3X) +mvget_wstr/\fBcurs_get_wstr\fR(3X) +mvgetch/\fBcurs_getch\fR(3X) +mvgetn_wstr/\fBcurs_get_wstr\fR(3X) +mvgetnstr/\fBcurs_getstr\fR(3X) +mvgetstr/\fBcurs_getstr\fR(3X) +mvhline/\fBcurs_border\fR(3X) +mvhline_set/\fBcurs_border_set\fR(3X) +mvin_wch/\fBcurs_in_wch\fR(3X) +mvin_wchnstr/\fBcurs_in_wchstr\fR(3X) +mvin_wchstr/\fBcurs_in_wchstr\fR(3X) +mvinch/\fBcurs_inch\fR(3X) +mvinchnstr/\fBcurs_inchstr\fR(3X) +mvinchstr/\fBcurs_inchstr\fR(3X) +mvinnstr/\fBcurs_instr\fR(3X) +mvinnwstr/\fBcurs_inwstr\fR(3X) +mvins_nwstr/\fBcurs_ins_wstr\fR(3X) +mvins_wch/\fBcurs_ins_wch\fR(3X) +mvins_wstr/\fBcurs_ins_wstr\fR(3X) +mvinsch/\fBcurs_insch\fR(3X) +mvinsnstr/\fBcurs_insstr\fR(3X) +mvinsstr/\fBcurs_insstr\fR(3X) +mvinstr/\fBcurs_instr\fR(3X) +mvinwstr/\fBcurs_inwstr\fR(3X) +mvprintw/\fBcurs_printw\fR(3X) +mvscanw/\fBcurs_scanw\fR(3X) +mvvline/\fBcurs_border\fR(3X) +mvvline_set/\fBcurs_border_set\fR(3X) +mvwadd_wch/\fBcurs_add_wch\fR(3X) +mvwadd_wchnstr/\fBcurs_add_wchstr\fR(3X) +mvwadd_wchstr/\fBcurs_add_wchstr\fR(3X) +mvwaddch/\fBcurs_addch\fR(3X) +mvwaddchnstr/\fBcurs_addchstr\fR(3X) +mvwaddchstr/\fBcurs_addchstr\fR(3X) +mvwaddnstr/\fBcurs_addstr\fR(3X) +mvwaddnwstr/\fBcurs_addwstr\fR(3X) +mvwaddstr/\fBcurs_addstr\fR(3X) +mvwaddwstr/\fBcurs_addwstr\fR(3X) +mvwchgat/\fBcurs_attr\fR(3X) +mvwdelch/\fBcurs_delch\fR(3X) +mvwget_wch/\fBcurs_get_wch\fR(3X) +mvwget_wstr/\fBcurs_get_wstr\fR(3X) +mvwgetch/\fBcurs_getch\fR(3X) +mvwgetn_wstr/\fBcurs_get_wstr\fR(3X) +mvwgetnstr/\fBcurs_getstr\fR(3X) +mvwgetstr/\fBcurs_getstr\fR(3X) +mvwhline/\fBcurs_border\fR(3X) +mvwhline_set/\fBcurs_border_set\fR(3X) +mvwin/\fBcurs_window\fR(3X) +mvwin_wch/\fBcurs_in_wch\fR(3X) +mvwin_wchnstr/\fBcurs_in_wchstr\fR(3X) +mvwin_wchstr/\fBcurs_in_wchstr\fR(3X) +mvwinch/\fBcurs_inch\fR(3X) +mvwinchnstr/\fBcurs_inchstr\fR(3X) +mvwinchstr/\fBcurs_inchstr\fR(3X) +mvwinnstr/\fBcurs_instr\fR(3X) +mvwinnwstr/\fBcurs_inwstr\fR(3X) +mvwins_nwstr/\fBcurs_ins_wstr\fR(3X) +mvwins_wch/\fBcurs_ins_wch\fR(3X) +mvwins_wstr/\fBcurs_ins_wstr\fR(3X) +mvwinsch/\fBcurs_insch\fR(3X) +mvwinsnstr/\fBcurs_insstr\fR(3X) +mvwinsstr/\fBcurs_insstr\fR(3X) +mvwinstr/\fBcurs_instr\fR(3X) +mvwinwstr/\fBcurs_inwstr\fR(3X) +mvwprintw/\fBcurs_printw\fR(3X) +mvwscanw/\fBcurs_scanw\fR(3X) +mvwvline/\fBcurs_border\fR(3X) +mvwvline_set/\fBcurs_border_set\fR(3X) +napms/\fBcurs_kernel\fR(3X) +newpad/\fBcurs_pad\fR(3X) +newterm/\fBcurs_initscr\fR(3X) +newwin/\fBcurs_window\fR(3X) +nl/\fBcurs_outopts\fR(3X) +nocbreak/\fBcurs_inopts\fR(3X) +nodelay/\fBcurs_inopts\fR(3X) +noecho/\fBcurs_inopts\fR(3X) +nofilter/\fBcurs_util\fR(3X)* +nonl/\fBcurs_outopts\fR(3X) +noqiflush/\fBcurs_inopts\fR(3X) +noraw/\fBcurs_inopts\fR(3X) +notimeout/\fBcurs_inopts\fR(3X) +overlay/\fBcurs_overlay\fR(3X) +overwrite/\fBcurs_overlay\fR(3X) +pair_content/\fBcurs_color\fR(3X) +pechochar/\fBcurs_pad\fR(3X) +pnoutrefresh/\fBcurs_pad\fR(3X) +prefresh/\fBcurs_pad\fR(3X) +printw/\fBcurs_printw\fR(3X) +putp/\fBcurs_terminfo\fR(3X) +putwin/\fBcurs_util\fR(3X) +qiflush/\fBcurs_inopts\fR(3X) +raw/\fBcurs_inopts\fR(3X) +redrawwin/\fBcurs_refresh\fR(3X) +refresh/\fBcurs_refresh\fR(3X) +reset_prog_mode/\fBcurs_kernel\fR(3X) +reset_shell_mode/\fBcurs_kernel\fR(3X) +resetty/\fBcurs_kernel\fR(3X) +resizeterm/\fBresizeterm\fR(3X)* +restartterm/\fBcurs_terminfo\fR(3X) +ripoffline/\fBcurs_kernel\fR(3X) +savetty/\fBcurs_kernel\fR(3X) +scanw/\fBcurs_scanw\fR(3X) +scr_dump/\fBcurs_scr_dump\fR(3X) +scr_init/\fBcurs_scr_dump\fR(3X) +scr_restore/\fBcurs_scr_dump\fR(3X) +scr_set/\fBcurs_scr_dump\fR(3X) +scrl/\fBcurs_scroll\fR(3X) +scroll/\fBcurs_scroll\fR(3X) +scrollok/\fBcurs_outopts\fR(3X) +set_curterm/\fBcurs_terminfo\fR(3X) +set_term/\fBcurs_initscr\fR(3X) +setcchar/\fBcurs_getcchar\fR(3X) +setscrreg/\fBcurs_outopts\fR(3X) +setsyx/\fBcurs_kernel\fR(3X) +setterm/\fBcurs_terminfo\fR(3X) +setupterm/\fBcurs_terminfo\fR(3X) +slk_attr/\fBcurs_slk\fR(3X)* +slk_attr_off/\fBcurs_slk\fR(3X) +slk_attr_on/\fBcurs_slk\fR(3X) +slk_attr_set/\fBcurs_slk\fR(3X) +slk_attroff/\fBcurs_slk\fR(3X) +slk_attron/\fBcurs_slk\fR(3X) +slk_attrset/\fBcurs_slk\fR(3X) +slk_clear/\fBcurs_slk\fR(3X) +slk_color/\fBcurs_slk\fR(3X) +slk_init/\fBcurs_slk\fR(3X) +slk_label/\fBcurs_slk\fR(3X) +slk_noutrefresh/\fBcurs_slk\fR(3X) +slk_refresh/\fBcurs_slk\fR(3X) +slk_restore/\fBcurs_slk\fR(3X) +slk_set/\fBcurs_slk\fR(3X) +slk_touch/\fBcurs_slk\fR(3X) +standend/\fBcurs_attr\fR(3X) +standout/\fBcurs_attr\fR(3X) +start_color/\fBcurs_color\fR(3X) +subpad/\fBcurs_pad\fR(3X) +subwin/\fBcurs_window\fR(3X) +syncok/\fBcurs_window\fR(3X) +term_attrs/\fBcurs_termattrs\fR(3X) +termattrs/\fBcurs_termattrs\fR(3X) +termname/\fBcurs_termattrs\fR(3X) +tgetent/\fBcurs_termcap\fR(3X) +tgetflag/\fBcurs_termcap\fR(3X) +tgetnum/\fBcurs_termcap\fR(3X) +tgetstr/\fBcurs_termcap\fR(3X) +tgoto/\fBcurs_termcap\fR(3X) +tigetflag/\fBcurs_terminfo\fR(3X) +tigetnum/\fBcurs_terminfo\fR(3X) +tigetstr/\fBcurs_terminfo\fR(3X) +timeout/\fBcurs_inopts\fR(3X) +touchline/\fBcurs_touch\fR(3X) +touchwin/\fBcurs_touch\fR(3X) +tparm/\fBcurs_terminfo\fR(3X) +tputs/\fBcurs_termcap\fR(3X) +tputs/\fBcurs_terminfo\fR(3X) +trace/\fBcurs_trace\fR(3X)* +typeahead/\fBcurs_inopts\fR(3X) +unctrl/\fBcurs_util\fR(3X) +unget_wch/\fBcurs_get_wch\fR(3X) +ungetch/\fBcurs_getch\fR(3X) +ungetmouse/\fBcurs_mouse\fR(3X)* +untouchwin/\fBcurs_touch\fR(3X) +use_default_colors/\fBdefault_colors\fR(3X)* +use_env/\fBcurs_util\fR(3X) +use_extended_names/\fBcurs_extend\fR(3X)* +use_legacy_coding/\fBlegacy_coding\fR(3X)* +vid_attr/\fBcurs_terminfo\fR(3X) +vid_puts/\fBcurs_terminfo\fR(3X) +vidattr/\fBcurs_terminfo\fR(3X) +vidputs/\fBcurs_terminfo\fR(3X) +vline/\fBcurs_border\fR(3X) +vline_set/\fBcurs_border_set\fR(3X) +vw_printw/\fBcurs_printw\fR(3X) +vw_scanw/\fBcurs_scanw\fR(3X) +vwprintw/\fBcurs_printw\fR(3X) +vwscanw/\fBcurs_scanw\fR(3X) +wadd_wch/\fBcurs_add_wch\fR(3X) +wadd_wchnstr/\fBcurs_add_wchstr\fR(3X) +wadd_wchstr/\fBcurs_add_wchstr\fR(3X) +waddch/\fBcurs_addch\fR(3X) +waddchnstr/\fBcurs_addchstr\fR(3X) +waddchstr/\fBcurs_addchstr\fR(3X) +waddnstr/\fBcurs_addstr\fR(3X) +waddnwstr/\fBcurs_addwstr\fR(3X) +waddstr/\fBcurs_addstr\fR(3X) +waddwstr/\fBcurs_addwstr\fR(3X) +wattr_get/\fBcurs_attr\fR(3X) +wattr_off/\fBcurs_attr\fR(3X) +wattr_on/\fBcurs_attr\fR(3X) +wattr_set/\fBcurs_attr\fR(3X) +wattroff/\fBcurs_attr\fR(3X) +wattron/\fBcurs_attr\fR(3X) +wattrset/\fBcurs_attr\fR(3X) +wbkgd/\fBcurs_bkgd\fR(3X) +wbkgdset/\fBcurs_bkgd\fR(3X) +wbkgrnd/\fBcurs_bkgrnd\fR(3X) +wbkgrndset/\fBcurs_bkgrnd\fR(3X) +wborder/\fBcurs_border\fR(3X) +wborder_set/\fBcurs_border_set\fR(3X) +wchgat/\fBcurs_attr\fR(3X) +wclear/\fBcurs_clear\fR(3X) +wclrtobot/\fBcurs_clear\fR(3X) +wclrtoeol/\fBcurs_clear\fR(3X) +wcolor_set/\fBcurs_attr\fR(3X) +wcursyncup/\fBcurs_window\fR(3X) +wdelch/\fBcurs_delch\fR(3X) +wdeleteln/\fBcurs_deleteln\fR(3X) +wecho_wchar/\fBcurs_add_wch\fR(3X) +wechochar/\fBcurs_addch\fR(3X) +wenclose/\fBcurs_mouse\fR(3X)* +werase/\fBcurs_clear\fR(3X) +wget_wch/\fBcurs_get_wch\fR(3X) +wget_wstr/\fBcurs_get_wstr\fR(3X) +wgetbkgrnd/\fBcurs_bkgrnd\fR(3X) +wgetch/\fBcurs_getch\fR(3X) +wgetn_wstr/\fBcurs_get_wstr\fR(3X) +wgetnstr/\fBcurs_getstr\fR(3X) +wgetstr/\fBcurs_getstr\fR(3X) +whline/\fBcurs_border\fR(3X) +whline_set/\fBcurs_border_set\fR(3X) +win_wch/\fBcurs_in_wch\fR(3X) +win_wchnstr/\fBcurs_in_wchstr\fR(3X) +win_wchstr/\fBcurs_in_wchstr\fR(3X) +winch/\fBcurs_inch\fR(3X) +winchnstr/\fBcurs_inchstr\fR(3X) +winchstr/\fBcurs_inchstr\fR(3X) +winnstr/\fBcurs_instr\fR(3X) +winnwstr/\fBcurs_inwstr\fR(3X) +wins_nwstr/\fBcurs_ins_wstr\fR(3X) +wins_wch/\fBcurs_ins_wch\fR(3X) +wins_wstr/\fBcurs_ins_wstr\fR(3X) +winsch/\fBcurs_insch\fR(3X) +winsdelln/\fBcurs_deleteln\fR(3X) +winsertln/\fBcurs_deleteln\fR(3X) +winsnstr/\fBcurs_insstr\fR(3X) +winsstr/\fBcurs_insstr\fR(3X) +winstr/\fBcurs_instr\fR(3X) +winwstr/\fBcurs_inwstr\fR(3X) +wmouse_trafo/\fBcurs_mouse\fR(3X)* +wmove/\fBcurs_move\fR(3X) +wnoutrefresh/\fBcurs_refresh\fR(3X) +wprintw/\fBcurs_printw\fR(3X) +wredrawln/\fBcurs_refresh\fR(3X) +wrefresh/\fBcurs_refresh\fR(3X) +wresize/\fBwresize\fR(3X)* +wscanw/\fBcurs_scanw\fR(3X) +wscrl/\fBcurs_scroll\fR(3X) +wsetscrreg/\fBcurs_outopts\fR(3X) +wstandend/\fBcurs_attr\fR(3X) +wstandout/\fBcurs_attr\fR(3X) +wsyncdown/\fBcurs_window\fR(3X) +wsyncup/\fBcurs_window\fR(3X) +wtimeout/\fBcurs_inopts\fR(3X) +wtouchln/\fBcurs_touch\fR(3X) +wunctrl/\fBcurs_util\fR(3X) +wvline/\fBcurs_border\fR(3X) +wvline_set/\fBcurs_border_set\fR(3X) +.TE +.SH RETURN VALUE +Routines that return an integer return \fBERR\fR upon failure and an +integer value other than \fBERR\fR upon successful completion, unless +otherwise noted in the routine descriptions. +.PP +All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR, +\fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR. +The return values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and +\fBgetmaxyx\fR are undefined (i.e., these should not be used as the +right-hand side of assignment statements). +.PP +Routines that return pointers return \fBNULL\fR on error. +.SH ENVIRONMENT +The following environment symbols are useful for customizing the +runtime behavior of the \fBncurses\fR library. +The most important ones have been already discussed in detail. +.TP 5 +BAUDRATE +The debugging library checks this environment symbol when the application +has redirected output to a file. +The symbol's numeric value is used for the baudrate. +If no value is found, \fBncurses\fR uses 9600. +This allows testers to construct repeatable test-cases +that take into account costs that depend on baudrate. +.TP 5 +CC +When set, change occurrences of the command_character +(i.e., the \fBcmdch\fP capability) +of the loaded terminfo entries to the value of this symbol. +Very few terminfo entries provide this feature. +.TP 5 +COLUMNS +Specify the width of the screen in characters. +Applications running in a windowing environment usually are able to +obtain the width of the window in which they are executing. +If neither the \fBCOLUMNS\fP value nor the terminal's screen size is available, +\fBncurses\fR uses the size which may be specified in the terminfo database +(i.e., the \fBcols\fR capability). +.IP +It is important that your application use a correct size for the screen. +This is not always possible because your application may be +running on a host which does not honor NAWS (Negotiations About Window +Size), or because you are temporarily running as another user. +However, setting \fBCOLUMNS\fP and/or \fBLINES\fP overrides the library's +use of the screen size obtained from the operating system. +.IP +Either \fBCOLUMNS\fP or \fBLINES\fP symbols may be specified independently. +This is mainly useful to circumvent legacy misfeatures of terminal descriptions, +e.g., xterm which commonly specifies a 65 line screen. +For best results, \fBlines\fR and \fBcols\fR should not be specified in +a terminal description for terminals which are run as emulations. +.IP +Use the \fBuse_env\fR function to disable all use of external environment +(including system calls) to determine the screen size. +.TP 5 +ESCDELAY +Specifies the total time, in milliseconds, for which ncurses will +await a character sequence, e.g., a function key. +The default value, 1000 milliseconds, is enough for most uses. +However, it is made a variable to accommodate unusual applications. +.IP +The most common instance where you may wish to change this value +is to work with slow hosts, e.g., running on a network. +If the host cannot read characters rapidly enough, it will have the same +effect as if the terminal did not send characters rapidly enough. +The library will still see a timeout. +.IP +Note that xterm mouse events are built up from character sequences +received from the xterm. +If your application makes heavy use of multiple-clicking, you may +wish to lengthen this default value because the timeout applies +to the composed multi-click event as well as the individual clicks. +.IP +In addition to the environment variable, +this implementation provides a global variable with the same name. +Portable applications should not rely upon the presence of ESCDELAY +in either form, +but setting the environment variable rather than the global variable +does not create problems when compiling an application. +.TP 5 +HOME +Tells \fBncurses\fR where your home directory is. +That is where it may read and write auxiliary terminal descriptions: +.IP +$HOME/.termcap +.br +$HOME/.terminfo +.TP 5 +LINES +Like COLUMNS, specify the height of the screen in characters. +See COLUMNS for a detailed description. +.TP 5 +MOUSE_BUTTONS_123 +This applies only to the OS/2 EMX port. +It specifies the order of buttons on the mouse. +OS/2 numbers a 3-button mouse inconsistently from other +platforms: +.sp +1 = left +.br +2 = right +.br +3 = middle. +.sp +This symbol lets you customize the mouse. +The symbol must be three numeric digits 1-3 in any order, e.g., 123 or 321. +If it is not specified, \fBncurses\fR uses 132. +.TP 5 +NCURSES_ASSUMED_COLORS +Override the compiled-in assumption that the +terminal's default colors are white-on-black +(see \fBdefault_colors\fR(3X)). +You may set the foreground and background color values with this environment +variable by proving a 2-element list: foreground,background. +For example, to tell ncurses to not assume anything +about the colors, set this to "-1,-1". +To make it green-on-black, set it to "2,0". +Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed. +.TP 5 +NCURSES_NO_HARD_TABS +\fBNcurses\fP may use tabs as part of the cursor movement optimization. +In some cases, +your terminal driver may not handle these properly. +Set this environment variable to disable the feature. +You can also adjust your \fBstty\fP settings to avoid the problem. +.TP 5 +NCURSES_NO_MAGIC_COOKIES +Some terminals use a magic-cookie feature which requires special handling +to make highlighting and other video attributes display properly. +You can suppress the highlighting entirely for these terminals by +setting this environment variable. +.TP 5 +NCURSES_NO_PADDING +Most of the terminal descriptions in the terminfo database are written +for real "hardware" terminals. +Many people use terminal emulators +which run in a windowing environment and use curses-based applications. +Terminal emulators can duplicate +all of the important aspects of a hardware terminal, but they do not +have the same limitations. +The chief limitation of a hardware terminal from the standpoint +of your application is the management of dataflow, i.e., timing. +Unless a hardware terminal is interfaced into a terminal concentrator +(which does flow control), +it (or your application) must manage dataflow, preventing overruns. +The cheapest solution (no hardware cost) +is for your program to do this by pausing after +operations that the terminal does slowly, such as clearing the display. +.IP +As a result, many terminal descriptions (including the vt100) +have delay times embedded. +You may wish to use these descriptions, +but not want to pay the performance penalty. +.IP +Set the NCURSES_NO_PADDING symbol to disable all but mandatory +padding. +Mandatory padding is used as a part of special control +sequences such as \fIflash\fR. +.TP 5 +NCURSES_NO_SETBUF +Normally \fBncurses\fR enables buffered output during terminal initialization. +This is done (as in SVr4 curses) for performance reasons. +For testing purposes, both of \fBncurses\fR and certain applications, +this feature is made optional. +Setting the NCURSES_NO_SETBUF variable +disables output buffering, leaving the output in the original (usually +line buffered) mode. +.TP 5 +NCURSES_NO_UTF8_ACS +During initialization, the \fBncurses\fR library +checks for special cases where VT100 line-drawing (and the corresponding +alternate character set capabilities) described in the terminfo are known +to be missing. +Specifically, when running in a UTF-8 locale, +the Linux console emulator and the GNU screen program ignore these. +Ncurses checks the TERM environment variable for these. +For other special cases, you should set this environment variable. +Doing this tells ncurses to use Unicode values which correspond to +the VT100 line-drawing glyphs. +That works for the special cases cited, +and is likely to work for terminal emulators. +.IP +When setting this variable, you should set it to a nonzero value. +Setting it to zero (or to a nonnumber) +disables the special check for Linux and screen. +.TP 5 +NCURSES_TRACE +During initialization, the \fBncurses\fR debugging library +checks the NCURSES_TRACE symbol. +If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR +function, using that value as the argument. +.IP +The argument values, which are defined in \fBcurses.h\fR, provide several +types of information. +When running with traces enabled, your application will write the +file \fBtrace\fR to the current directory. +.TP 5 +TERM +Denotes your terminal type. +Each terminal type is distinct, though many are similar. +.TP 5 +TERMCAP +If the \fBncurses\fR library has been configured with \fItermcap\fR +support, \fBncurses\fR will check for a terminal's description in +termcap form if it is not available in the terminfo database. +.IP +The TERMCAP symbol contains either a terminal description (with +newlines stripped out), +or a file name telling where the information denoted by the TERM symbol exists. +In either case, setting it directs \fBncurses\fR to ignore +the usual place for this information, e.g., /etc/termcap. +.TP 5 +TERMINFO +Overrides the directory in which \fBncurses\fR searches for your terminal +description. +This is the simplest, but not the only way to change the list of directories. +The complete list of directories in order follows: +.RS +.TP 3 +- +the last directory to which \fBncurses\fR wrote, if any, is searched first +.TP 3 +- +the directory specified by the TERMINFO symbol +.TP 3 +- +$HOME/.terminfo +.TP 3 +- +directories listed in the TERMINFO_DIRS symbol +.TP 3 +- +one or more directories whose names are configured and compiled into the +ncurses library, e.g., +@TERMINFO@ +.RE +.TP 5 +TERMINFO_DIRS +Specifies a list of directories to search for terminal descriptions. +The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX. +All of the terminal descriptions are in terminfo form, which makes +a subdirectory named for the first letter of the terminal names therein. +.TP 5 +TERMPATH +If TERMCAP does not hold a file name then \fBncurses\fR checks +the TERMPATH symbol. +This is a list of filenames separated by spaces or colons (i.e., ":") on Unix, semicolons on OS/2 EMX. +If the TERMPATH symbol is not set, \fBncurses\fR looks in the files +/etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, in that order. +.PP +The library may be configured to disregard the following variables when the +current user is the superuser (root), or if the application uses setuid or +setgid permissions: +$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME. +.SH ALTERNATE CONFIGURATIONS +Several different configurations are possible, +depending on the configure script options used when building \fBncurses\fP. +There are a few main options whose effects are visible to the applications +developer using \fBncurses\fP: +.TP 5 +--disable-overwrite +The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP: +.RS +.sp +\fB#include <curses.h>\fR +.RE +.IP +This option is used to avoid filename conflicts when \fBncurses\fP +is not the main implementation of curses of the computer. +If \fBncurses\fP is installed disabling overwrite, it puts its headers in +a subdirectory, e.g., +.RS +.sp +\fB#include <ncurses/curses.h>\fR +.RE +.IP +It also omits a symbolic link which would allow you to use \fB-lcurses\fP +to build executables. +.TP 5 +--enable-widec +The configure script renames the library and (if the \fB--disable-overwrite\fP +option is used) puts the header files in a different subdirectory. +All of the library names have a "w" appended to them, +i.e., instead of +.RS +.sp +\fB-lncurses\fR +.RE +.IP +you link with +.RS +.sp +\fB-lncursesw\fR +.RE +.IP +You must also define \fB_XOPEN_SOURCE_EXTENDED\fP when compiling for the +wide-character library to use the extended (wide-character) functions. +The \fBcurses.h\fP file which is installed for the wide-character +library is designed to be compatible with the normal library's header. +Only the size of the \fBWINDOW\fP structure differs, and very few +applications require more than a pointer to \fBWINDOW\fPs. +If the headers are installed allowing overwrite, +the wide-character library's headers should be installed last, +to allow applications to be built using either library +from the same set of headers. +.TP 5 +--with-shared +.TP +--with-normal +.TP +--with-debug +.TP +--with-profile +The shared and normal (static) library names differ by their suffixes, +e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP. +The debug and profiling libraries add a "_g" and a "_p" to the root +names respectively, +e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP. +.TP 5 +--with-trace +The \fBtrace\fP function normally resides in the debug library, +but it is sometimes useful to configure this in the shared library. +Configure scripts should check for the function's existence rather +than assuming it is always in the debug library. +.SH FILES +.TP 5 +@DATADIR@/tabset +directory containing initialization files for the terminal capability database +@TERMINFO@ +terminal capability database +.SH SEE ALSO +\fBterminfo\fR(\*n) and related pages whose names begin "curs_" for detailed routine +descriptions. +.SH EXTENSIONS +The \fBncurses\fR library can be compiled with an option (\fB-DUSE_GETCAP\fR) +that falls back to the old-style /etc/termcap file if the terminal setup code +cannot find a terminfo entry corresponding to \fBTERM\fR. +Use of this feature +is not recommended, as it essentially includes an entire termcap compiler in +the \fBncurses\fR startup code, at significant cost in core and startup cycles. +.PP +The \fBncurses\fR library includes facilities for capturing mouse events on +certain terminals (including xterm). +See the \fBcurs_mouse\fR(3X) +manual page for details. +.PP +The \fBncurses\fR library includes facilities for responding to window +resizing events, e.g., when running in an xterm. +See the \fBresizeterm\fR(3X) +and \fBwresize\fR(3X) manual pages for details. +In addition, the library may be configured with a SIGWINCH handler. +.PP +The \fBncurses\fR library extends the fixed set of function key capabilities +of terminals by allowing the application designer to define additional +key sequences at runtime. +See the \fBdefine_key\fR(3X) +\fBkey_defined\fR(3X), +and \fBkeyok\fR(3X) manual pages for details. +.PP +The \fBncurses\fR library can exploit the capabilities of terminals which +implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an application +to reset the terminal to its original foreground and background colors. +From the users' perspective, the application is able to draw colored +text on a background whose color is set independently, providing better +control over color contrasts. +See the \fBdefault_colors\fR(3X) manual page for details. +.PP +The \fBncurses\fR library includes a function for directing application output +to a printer attached to the terminal device. +See the \fBcurs_print\fR(3X) manual page for details. +.SH PORTABILITY +The \fBncurses\fR library is intended to be BASE-level conformant with XSI +Curses. +The EXTENDED XSI Curses functionality +(including color support) is supported. +.PP +A small number of local differences (that is, individual differences between +the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR +sections of the library man pages. +.PP +This implementation also contains several extensions: +.RS 5 +.PP +The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4. +See the \fBcurs_getch\fR(3X) manual page for details. +.PP +The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4. +See the \fBcurs_slk\fR(3X) manual page for details. +.PP +The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR, +\fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not +part of XPG4, nor are they present in SVr4. +See the \fBcurs_mouse\fR(3X) manual page for details. +.PP +The routine \fBmcprint\fR was not present in any previous curses implementation. +See the \fBcurs_print\fR(3X) manual page for details. +.PP +The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4. +See the \fBwresize\fR(3X) manual page for details. +.PP +The WINDOW structure's internal details can be hidden from application +programs. +See \fBcurs_opaque\fR(3X) for the discussion of \fBis_scrollok\fR, etc. +.RE +.PP +In historic curses versions, delays embedded in the capabilities \fBcr\fR, +\fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay +bits in the UNIX tty driver. +In this implementation, all padding is done by sending NUL bytes. +This method is slightly more expensive, but narrows the interface +to the UNIX kernel significantly and increases the package's portability +correspondingly. +.SH NOTES +The header file \fB<curses.h>\fR automatically includes the header files +\fB<stdio.h>\fR and \fB<unctrl.h>\fR. +.PP +If standard output from a \fBncurses\fR program is re-directed to something +which is not a tty, screen updates will be directed to standard error. +This was an undocumented feature of AT&T System V Release 3 curses. +.SH AUTHORS +Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. +Based on pcurses by Pavel Curtis. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/panel.3x b/man/panel.3x new file mode 100644 index 000000000000..719a9e636bc5 --- /dev/null +++ b/man/panel.3x @@ -0,0 +1,190 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: panel.3x,v 1.14 2007/05/12 20:45:20 tom Exp $ +.TH panel 3X "" +.ds n 5 +.ds d @TERMINFO@ +.SH NAME +panel - panel stack extension for curses +.SH SYNOPSIS +\fB#include <panel.h>\fR +.P +\fBcc [flags] sourcefiles -lpanel -lncurses\fR +.P +\fBPANEL *new_panel(WINDOW *win)\fR +.br +\fBint bottom_panel(PANEL *pan)\fR +.br +\fBint top_panel(PANEL *pan)\fR +.br +\fBint show_panel(PANEL *pan)\fR +.br +\fBvoid update_panels();\fR +.br +\fBint hide_panel(PANEL *pan)\fR +.br +\fBWINDOW *panel_window(const PANEL *pan)\fR +.br +\fBint replace_panel(PANEL *pan, WINDOW *window)\fR +.br +\fBint move_panel(PANEL *pan, int starty, int startx)\fR +.br +\fBint panel_hidden(const PANEL *pan)\fR +.br +\fBPANEL *panel_above(const PANEL *pan)\fR +.br +\fBPANEL *panel_below(const PANEL *pan)\fR +.br +\fBint set_panel_userptr(PANEL *pan, const void *ptr)\fR +.br +\fBconst void *panel_userptr(const PANEL *pan)\fR +.br +\fBint del_panel(PANEL *pan)\fR +.br +.SH DESCRIPTION +Panels are \fBcurses\fR(3X) windows with the added feature of +depth. Panel functions allow the use of stacked windows and ensure +the proper portions of each window and the curses \fBstdscr\fR window are +hidden or displayed when panels are added, moved, modified or removed. +The set of currently visible panels is the stack of panels. The +\fBstdscr\fR window is beneath all panels, and is not considered part +of the stack. +.P +A window is associated with every panel. The panel routines enable +you to create, move, hide, and show panels, as well as position a +panel at any desired location in the stack. +.P +Panel routines are a functional layer added to \fBcurses\fR(3X), make only +high-level curses calls, and work anywhere terminfo curses does. +.SH FUNCTIONS +.TP +.B new_panel(win) +allocates a \fBPANEL\fR structure, associates it with +\fBwin\fR, places the panel on the top of the stack (causes it +to be displayed above any other panel) and returns a +pointer to the new panel. +.TP +.B update_panels() +refreshes the virtual screen to reflect the relations between the +panels in the stack, but does not call doupdate() to refresh the +physical screen. Use this function and not wrefresh or wnoutrefresh. +update_panels() may be called more than once before a call to +doupdate(), but doupdate() is the function responsible for updating +the physical screen. +.TP +.B del_panel(pan) +removes the given panel from the stack and deallocates the +\fBPANEL\fR structure (but not its associated window). +.TP +.B hide_panel(pan) +removes the given panel from the panel stack and thus hides it from +view. The \fBPANEL\fR structure is not lost, merely removed from the stack. +.TP +.B panel_hidden(pan) +returns TRUE if the panel is in the panel stack, +FALSE if it is not. +If the panel is a null pointer, return ERR. +.TP +.B show_panel(pan) +makes a hidden panel visible by placing it on top of the panels in the +panel stack. See COMPATIBILITY below. +.TP +.B top_panel(pan) +puts the given visible panel on top of all panels in the stack. See +COMPATIBILITY below. +.TP +.B bottom_panel(pan) +puts panel at the bottom of all panels. +.TP +.B move_panel(pan,starty,startx) +moves the given panel window so that its upper-left corner is at +\fBstarty\fR, \fBstartx\fR. It does not change the position of the +panel in the stack. Be sure to use this function, not \fBmvwin()\fR, +to move a panel window. +.TP +.B replace_panel(pan,window) +replaces the current window of panel with \fBwindow\fR (useful, for +example if you want to resize a panel; if you're using \fBncurses\fR, +you can call \fBreplace_panel\fR on the output of \fBwresize\fR(3X)). +It does not change the position of the panel in the stack. +.TP +.B panel_above(pan) +returns a pointer to the panel above pan. If the panel argument is +\fB(PANEL *)0\fR, it returns a pointer to the bottom panel in the stack. +.TP +.B panel_below(pan) +returns a pointer to the panel just below pan. If the panel argument +is \fB(PANEL *)0\fR, it returns a pointer to the top panel in the stack. +.TP +.B set_panel_userptr(pan,ptr) +sets the panel's user pointer. +.TP +.B panel_userptr(pan) +returns the user pointer for a given panel. +.TP +.B panel_window(pan) +returns a pointer to the window of the given panel. +.SH DIAGNOSTICS +Each routine that returns a pointer returns \fBNULL\fR if an error +occurs. Each routine that returns an int value returns \fBOK\fR if it +executes successfully and \fBERR\fR if not. +.SH COMPATIBILITY +Reasonable care has been taken to ensure compatibility +with the native panel facility introduced in SVr3.2 (inspection of +the SVr4 manual pages suggests the programming interface is unchanged). +The \fBPANEL\fR data structures are merely similar. The programmer +is cautioned not to directly use \fBPANEL\fR fields. +.P +The functions \fBshow_panel()\fR and \fBtop_panel()\fR are identical +in this implementation, and work equally well with displayed or hidden +panels. In the native System V implementation, \fBshow_panel()\fR is +intended for making a hidden panel visible (at the top of the stack) +and \fBtop_panel()\fR is intended for making an already-visible panel +move to the top of the stack. You are cautioned to use the correct +function to ensure compatibility with native panel libraries. +.SH NOTE +In your library list, libpanel.a should be before libncurses.a; that is, +you want to say `-lpanel -lncurses', not the other way around (which would +usually give a link-error). +.SH FILES +.P +panel.h +interface for the panels library +.P +libpanel.a +the panels library itself +.SH SEE ALSO +\fBcurses\fR(3X) +.PP +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.SH AUTHOR +Originally written by Warren Tucker <wht@n4hgf.mt-park.ga.us>, +primarily to assist in porting u386mon to systems without a native +panels library. Repackaged for ncurses by Zeyd ben-Halim. diff --git a/man/resizeterm.3x b/man/resizeterm.3x new file mode 100644 index 000000000000..888eaaf318d1 --- /dev/null +++ b/man/resizeterm.3x @@ -0,0 +1,100 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2005 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1996-2005 +.\" +.\" $Id: resizeterm.3x,v 1.11 2005/06/25 22:19:42 tom Exp $ +.TH resizeterm 3X "" +.SH NAME +\fBis_term_resized\fR, +\fBresize_term\fR, +\fBresizeterm\fR - change the curses terminal size +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBbool is_term_resized(int lines, int columns);\fR +.br +\fBint resize_term(int lines, int columns);\fR +.br +\fBint resizeterm(int lines, int columns);\fR +.SH DESCRIPTION +This is an extension to the curses library. +It provides callers with a hook into the \fBncurses\fR data to resize windows, +primarily for use by programs running in an X Window terminal (e.g., xterm). +The function \fBresizeterm\fR resizes the standard and current windows +to the specified dimensions, and adjusts other bookkeeping data used by +the \fBncurses\fR library that record the window dimensions. +.LP +Most of the work is done by the inner function \fBresize_term\fR. +The outer function \fBresizeterm\fR adds bookkeeping for the SIGWINCH handler. +When resizing the windows, +\fBresize_term\fR blank-fills the areas that are extended. +The calling application should fill in these areas with appropriate data. +The \fBresize_term\fR function attempts to resize all windows. +However, due to the calling convention of pads, +it is not possible to resize these +without additional interaction with the application. +.LP +A support function \fBis_term_resized\fR is provided so that applications +can check if the \fBresize_term\fR function would modify the window structures. +It returns TRUE if the windows would be modified, and FALSE otherwise. +.SH RETURN VALUE +Except as notes, these function return +the integer \fBERR\fR upon failure and \fBOK\fR on success. +They will fail if either of the dimensions are less than or equal to zero, +or if an error occurs while (re)allocating memory for the windows. +.SH NOTES +While these functions are intended to be used to support a signal handler +(i.e., for SIGWINCH), care should be taken to avoid invoking them in a +context where \fBmalloc\fR or \fBrealloc\fR may have been interrupted, +since it uses those functions. +.PP +If ncurses is configured to supply its own SIGWINCH handler, +the \fBresizeterm\fR function ungetch's a \fBKEY_RESIZE\fR which +will be read on the next call to \fBgetch\fR. +This is used to alert an application that the screen size has changed, +and that it should repaint special features such as pads that cannot +be done automatically. +.PP +If the environment variables \fBLINES\fP or \fBCOLUMNS\fP are set, +this overrides the library's use of the window size obtained from +the operating system. +Thus, even if a SIGWINCH is received, +no screen size change may be recorded. +In that case, no \fBKEY_RESIZE\fP is queued for the next call to \fBgetch\fP; +an \fBERR\fP will be returned instead. +.SH SEE ALSO +\fBwresize\fR(3X). +.SH AUTHOR +Thomas Dickey (from an equivalent function written in 1988 for BSD curses). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/term.5 b/man/term.5 new file mode 100644 index 000000000000..19af62a350ed --- /dev/null +++ b/man/term.5 @@ -0,0 +1,283 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2004,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: term.5,v 1.19 2006/12/24 18:12:38 tom Exp $ +.TH term 5 +.ds n 5 +.ds d @TERMINFO@ +.SH NAME +term \- format of compiled term file. +.SH SYNOPSIS +.B term +.SH DESCRIPTION +.SS STORAGE LOCATION +Compiled terminfo descriptions are placed under the directory \fB\*d\fP. +Two configurations are supported (when building the ncurses libraries): +.TP 5 +.B directory tree +A two-level scheme is used to avoid a linear search +of a huge \s-1UNIX\s+1 system directory: \fB\*d/c/name\fP where +.I name +is the name of the terminal, and +.I c +is the first character of +.IR name . +Thus, +.I act4 +can be found in the file \fB\*d/a/act4\fP. +Synonyms for the same terminal are implemented by multiple +links to the same compiled file. +.TP 5 +.B hashed database +Using Berkeley database, two types of records are stored: +the terminfo data in the same format as stored in a directory tree with +the terminfo's primary name as a key, +and records containing only aliases pointing to the primary name. +.IP +If built to write hashed databases, +ncurses can still read terminfo databases organized as a directory tree, +but cannot write entries into the directory tree. +It can write (or rewrite) entries in the hashed database. +.IP +ncurses distinguishes the two cases in the TERMINFO and TERMINFO_DIRS +environment variable by assuming a directory tree for entries that +correspond to an existing directory, +and hashed database otherwise. +.SS STORAGE FORMAT +The format has been chosen so that it will be the same on all hardware. +An 8 or more bit byte is assumed, but no assumptions about byte ordering +or sign extension are made. +.PP +The compiled file is created with the +.B @TIC@ +program, and read by the routine +.IR setupterm . +The file is divided into six parts: +the header, +terminal names, +boolean flags, +numbers, +strings, +and +string table. +.PP +The header section begins the file. +This section contains six short integers in the format +described below. +These integers are +.RS 5 +.TP 5 +(1) the magic number (octal 0432); +.TP 5 +(2) the size, in bytes, of the names section; +.TP 5 +(3) the number of bytes in the boolean section; +.TP 5 +(4) the number of short integers in the numbers section; +.TP 5 +(5) the number of offsets (short integers) in the strings section; +.TP 5 +(6) the size, in bytes, of the string table. +.RE +.PP +Short integers are stored in two 8-bit bytes. +The first byte contains the least significant 8 bits of the value, +and the second byte contains the most significant 8 bits. +(Thus, the value represented is 256*second+first.) +The value -1 is represented by the two bytes 0377, 0377; other negative +values are illegal. This value generally +means that the corresponding capability is missing from this terminal. +Note that this format corresponds to the hardware of the \s-1VAX\s+1 +and \s-1PDP\s+1-11 (that is, little-endian machines). +Machines where this does not correspond to the hardware must read the +integers as two bytes and compute the little-endian value. +.PP +The terminal names section comes next. +It contains the first line of the terminfo description, +listing the various names for the terminal, +separated by the `|' character. +The section is terminated with an \s-1ASCII NUL\s+1 character. +.PP +The boolean flags have one byte for each flag. +This byte is either 0 or 1 as the flag is present or absent. +The capabilities are in the same order as the file <term.h>. +.PP +Between the boolean section and the number section, +a null byte will be inserted, if necessary, +to ensure that the number section begins on an even byte (this is a +relic of the PDP-11's word-addressed architecture, originally +designed in to avoid IOT traps induced by addressing a word on an +odd byte boundary). +All short integers are aligned on a short word boundary. +.PP +The numbers section is similar to the flags section. +Each capability takes up two bytes, +and is stored as a little-endian short integer. +If the value represented is -1, the capability is taken to be missing. +.PP +The strings section is also similar. +Each capability is stored as a short integer, in the format above. +A value of -1 means the capability is missing. +Otherwise, the value is taken as an offset from the beginning +of the string table. +Special characters in ^X or \ec notation are stored in their +interpreted form, not the printing representation. +Padding information $<nn> and parameter information %x are +stored intact in uninterpreted form. +.PP +The final section is the string table. +It contains all the values of string capabilities referenced in +the string section. +Each string is null terminated. +.SS EXTENDED STORAGE FORMAT +The previous section describes the conventional terminfo binary format. +With some minor variations of the offsets (see PORTABILITY), +the same binary format is used in all modern UNIX systems. +Each system uses a predefined set of boolean, number or string capabilities. +.PP +The ncurses libraries and applications support extended terminfo binary format, +allowing users to define capabilities which are loaded at runtime. This +extension is made possible by using the fact that the other implementations +stop reading the terminfo data when they have reached the end of the size given +in the header. +ncurses checks the size, and if it exceeds that due to the predefined data, +continues to parse according to its own scheme. +.PP +First, it reads the extended header (5 short integers): +.RS 5 +.TP 5 +(1) +count of extended boolean capabilities +.TP 5 +(2) +count of extended numeric capabilities +.TP 5 +(3) +count of extended string capabilities +.TP 5 +(4) +size of the extended string table in bytes. +.TP 5 +(5) +last offset of the extended string table in bytes. +.RE +.PP +Using the counts and sizes, ncurses allocates arrays and reads data +for the extended capabilties in the same order as the header information. +.PP +The extended string table contains values for string capabilities. +After the end of these values, it contains the names for each of +the extended capabilities in order, e.g., booleans, then numbers and +finally strings. +. +.SH PORTABILITY +Note that it is possible for +.I setupterm +to expect a different set of capabilities +than are actually present in the file. +Either the database may have been updated since +.I setupterm +has been recompiled +(resulting in extra unrecognized entries in the file) +or the program may have been recompiled more recently +than the database was updated +(resulting in missing entries). +The routine +.I setupterm +must be prepared for both possibilities \- +this is why the numbers and sizes are included. +Also, new capabilities must always be added at the end of the lists +of boolean, number, and string capabilities. +.PP +Despite the consistent use of little-endian for numbers and the otherwise +self-describing format, it is not wise to count on portability of binary +terminfo entries between commercial UNIX versions. The problem is that there +are at least three versions of terminfo (under HP-UX, AIX, and OSF/1) which +diverged from System V terminfo after SVr1, and have added extension +capabilities to the string table that (in the binary format) collide with +System V and XSI Curses extensions. See \fBterminfo\fR(\*n) for detailed +discussion of terminfo source compatibility issues. +.SH EXAMPLE +As an example, here is a hex dump of the description for the Lear-Siegler +ADM-3, a popular though rather stupid early terminal: +.nf +.sp +adm3a|lsi adm3a, + am, + cols#80, lines#24, + bel=^G, clear=\032$<1>, cr=^M, cub1=^H, cud1=^J, + cuf1=^L, cup=\\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K, + home=^^, ind=^J, +.sp +.ft CW +\s-20000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3 +0010 61 7c 6c 73 69 20 61 64 6d 33 61 00 00 01 50 00 a|lsi ad m3a...P. +0020 ff ff 18 00 ff ff 00 00 02 00 ff ff ff ff 04 00 ........ ........ +0030 ff ff ff ff ff ff ff ff 0a 00 25 00 27 00 ff ff ........ ..%.'... +0040 29 00 ff ff ff ff 2b 00 ff ff 2d 00 ff ff ff ff ).....+. ..-..... +0050 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0060 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0070 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0080 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0090 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00a0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00b0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00c0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00d0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00e0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00f0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0100 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0110 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0120 ff ff ff ff ff ff 2f 00 07 00 0d 00 1a 24 3c 31 ....../. .....$<1 +0130 3e 00 1b 3d 25 70 31 25 7b 33 32 7d 25 2b 25 63 >..=%p1% {32}%+%c +0140 25 70 32 25 7b 33 32 7d 25 2b 25 63 00 0a 00 1e %p2%{32} %+%c.... +0150 00 08 00 0c 00 0b 00 0a 00 ........ .\s+2 +.ft R +.fi +.sp +.SH LIMITS +Some limitations: total compiled entries cannot exceed 4096 bytes. +The name field cannot exceed 128 bytes. +.SH FILES +\*d/*/* compiled terminal capability data base +.SH SEE ALSO +\fBcurses\fR(3X), \fBterminfo\fR(\*n). +.SH AUTHORS +Thomas E. Dickey +.br +extended terminfo format for ncurses 5.0 +.br +hashed database support for ncurses 5.6 +.sp +Eric S. Raymond +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/term.7 b/man/term.7 new file mode 100644 index 000000000000..7eda6fbd5870 --- /dev/null +++ b/man/term.7 @@ -0,0 +1,204 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2007 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: term.7,v 1.18 2007/06/02 20:40:07 tom Exp $ +.TH term 7 +.ds n 5 +.ds d @TERMINFO@ +.SH NAME +term \- conventions for naming terminal types +.SH DESCRIPTION +.PP +The environment variable \fBTERM\fR should normally contain the type name of +the terminal, console or display-device type you are using. This information +is critical for all screen-oriented programs, including your editor and mailer. +.PP +A default \fBTERM\fR value will be set on a per-line basis by either +\fB/etc/inittab\fR (Linux and System-V-like UNIXes) or \fB/etc/ttys\fR (BSD +UNIXes). This will nearly always suffice for workstation and microcomputer +consoles. +.PP +If you use a dialup line, the type of device attached to it may vary. Older +UNIX systems pre-set a very dumb terminal type like `dumb' or `dialup' on +dialup lines. Newer ones may pre-set `vt100', reflecting the prevalence of DEC +VT100-compatible terminals and personal-computer emulators. +.PP +Modern telnets pass your \fBTERM\fR environment variable from the local side to +the remote one. There can be problems if the remote terminfo or termcap entry +for your type is not compatible with yours, but this situation is rare and +can almost always be avoided by explicitly exporting `vt100' (assuming you +are in fact using a VT100-superset console, terminal, or terminal emulator.) +.PP +In any case, you are free to override the system \fBTERM\fR setting to your +taste in your shell profile. The \fBtset\fP(1) utility may be of assistance; +you can give it a set of rules for deducing or requesting a terminal type based +on the tty device and baud rate. +.PP +Setting your own \fBTERM\fR value may also be useful if you have created a +custom entry incorporating options (such as visual bell or reverse-video) +which you wish to override the system default type for your line. +.PP +Terminal type descriptions are stored as files of capability data underneath +\*d. To browse a list of all terminal names recognized by the system, do +.sp + @TOE@ | more +.sp +from your shell. These capability files are in a binary format optimized for +retrieval speed (unlike the old text-based \fBtermcap\fR format they replace); +to examine an entry, you must use the \fB@INFOCMP@\fR(1M) command. +Invoke it as follows: +.sp + @INFOCMP@ \fIentry-name\fR +.sp +where \fIentry-name\fR is the name of the type you wish to examine (and the +name of its capability file the subdirectory of \*d named for its first +letter). This command dumps a capability file in the text format described by +\fBterminfo\fR(\*n). +.PP +The first line of a \fBterminfo\fR(\*n) description gives the names by which +terminfo knows a terminal, separated by `|' (pipe-bar) characters with the last +name field terminated by a comma. The first name field is the type's +\fIprimary name\fR, and is the one to use when setting \fBTERM\fR. The last +name field (if distinct from the first) is actually a description of the +terminal type (it may contain blanks; the others must be single words). Name +fields between the first and last (if present) are aliases for the terminal, +usually historical names retained for compatibility. +.PP +There are some conventions for how to choose terminal primary names that help +keep them informative and unique. Here is a step-by-step guide to naming +terminals that also explains how to parse them: +.PP +First, choose a root name. The root will consist of a lower-case letter +followed by up to seven lower-case letters or digits. You need to avoid using +punctuation characters in root names, because they are used and interpreted as +filenames and shell meta-characters (such as !, $, *, ?, etc.) embedded in them +may cause odd and unhelpful behavior. The slash (/), or any other character +that may be interpreted by anyone's file system (\e, $, [, ]), is especially +dangerous (terminfo is platform-independent, and choosing names with special +characters could someday make life difficult for users of a future port). The +dot (.) character is relatively safe as long as there is at most one per root +name; some historical terminfo names use it. +.PP +The root name for a terminal or workstation console type should almost always +begin with a vendor prefix (such as \fBhp\fR for Hewlett-Packard, \fBwy\fR for +Wyse, or \fBatt\fR for AT&T terminals), or a common name of the terminal line +(\fBvt\fR for the VT series of terminals from DEC, or \fBsun\fR for Sun +Microsystems workstation consoles, or \fBregent\fR for the ADDS Regent series. +You can list the terminfo tree to see what prefixes are already in common use. +The root name prefix should be followed when appropriate by a model number; +thus \fBvt100\fR, \fBhp2621\fR, \fBwy50\fR. +.PP +The root name for a PC-Unix console type should be the OS name, +i.e. \fBlinux\fR, \fBbsdos\fR, \fBfreebsd\fR, \fBnetbsd\fR. It should +\fInot\fR be \fBconsole\fR or any other generic that might cause confusion in a +multi-platform environment! If a model number follows, it should indicate +either the OS release level or the console driver release level. +.PP +The root name for a terminal emulator (assuming it does not fit one of the +standard ANSI or vt100 types) should be the program name or a readily +recognizable abbreviation of it (i.e. \fBversaterm\fR, \fBctrm\fR). +.PP +Following the root name, you may add any reasonable number of hyphen-separated +feature suffixes. +.TP 5 +2p +Has two pages of memory. Likewise 4p, 8p, etc. +.TP 5 +mc +Magic-cookie. Some terminals (notably older Wyses) can only support one +attribute without magic-cookie lossage. Their base entry is usually paired +with another that has this suffix and uses magic cookies to support multiple +attributes. +.TP 5 +-am +Enable auto-margin (right-margin wraparound). +.TP 5 +-m +Mono mode - suppress color support. +.TP 5 +-na +No arrow keys - termcap ignores arrow keys which are actually there on the +terminal, so the user can use the arrow keys locally. +.TP 5 +-nam +No auto-margin - suppress am capability. +.TP 5 +-nl +No labels - suppress soft labels. +.TP 5 +-nsl +No status line - suppress status line. +.TP 5 +-pp +Has a printer port which is used. +.TP 5 +-rv +Terminal in reverse video mode (black on white). +.TP 5 +-s +Enable status line. +.TP 5 +-vb +Use visible bell (flash) rather than beep. +.TP 5 +-w +Wide; terminal is in 132 column mode. +.PP +Conventionally, if your terminal type is a variant intended to specify a +line height, that suffix should go first. So, for a hypothetical FuBarCo +model 2317 terminal in 30-line mode with reverse video, best form would be +\fBfubar-30-rv\fR (rather than, say, `fubar-rv-30'). +.PP +Terminal types that are written not as standalone entries, but rather as +components to be plugged into other entries via \fBuse\fP capabilities, +are distinguished by using embedded plus signs rather than dashes. +.PP +Commands which use a terminal type to control display often accept a -T +option that accepts a terminal name argument. Such programs should fall back +on the \fBTERM\fR environment variable when no -T option is specified. +.SH PORTABILITY +For maximum compatibility with older System V UNIXes, names and aliases +should be unique within the first 14 characters. +.SH FILES +.TP 5 +\*d/?/* +compiled terminal capability data base +.TP 5 +/etc/inittab +tty line initialization (AT&T-like UNIXes) +.TP 5 +/etc/ttys +tty line initialization (BSD-like UNIXes) +.SH SEE ALSO +\fBcurses\fR(3X), \fBterminfo\fR(\*n), \fBterm\fR(\*n). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/terminfo.head b/man/terminfo.head new file mode 100644 index 000000000000..7455675ab953 --- /dev/null +++ b/man/terminfo.head @@ -0,0 +1,107 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2004,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: terminfo.head,v 1.16 2007/03/04 00:09:46 tom Exp $ +.TH terminfo 5 "" "" "File Formats" +.ds n 5 +.ds d @TERMINFO@ +.SH NAME +terminfo \- terminal capability data base +.SH SYNOPSIS +\*d/*/* +.SH DESCRIPTION +.I Terminfo +is a data base describing terminals, used by screen-oriented programs such as +\fBnvi\fR(1), +\fBrogue\fR(1) +and libraries such as +\fBcurses\fR(3X). +.I Terminfo +describes terminals by giving a set of capabilities which they +have, by specifying how to perform screen operations, and by +specifying padding requirements and initialization sequences. +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.PP +Entries in +.I terminfo +consist of a sequence of `,' separated fields (embedded commas may be +escaped with a backslash or notated as \\054). +White space after the `,' separator is ignored. +The first entry for each terminal gives the names which are known for the +terminal, separated by `|' characters. +The first name given is the most common abbreviation for the terminal, +the last name given should be a long name fully identifying the terminal, +and all others are understood as synonyms for the terminal name. +All names but the last should be in lower case and contain no blanks; +the last name may well contain upper case and blanks for readability. +.PP +Lines beginning with a `#' in the first column are treated as comments. +While comment lines are legal at any point, the output of \fB@CAPTOINFO@\fP +and \fB@INFOTOCAP@\fP (aliases for \fB@TIC@\fP) +will move comments so they occur only between entries. +.PP +Newlines and leading tabs may be used for formatting entries for readability. +These are removed from parsed entries. +The \fB@INFOCMP@\ -f\fP option relies on this to format if-then-else expressions: +the result can be read by \fB@TIC@\fP. +.PP +Terminal names (except for the last, verbose entry) should +be chosen using the following conventions. +The particular piece of hardware making up the terminal should +have a root name, thus ``hp2621''. +This name should not contain hyphens. +Modes that the hardware can be in, or user preferences, should +be indicated by appending a hyphen and a mode suffix. +Thus, a vt100 in 132 column mode would be vt100-w. +The following suffixes should be used where possible: +.PP +.TS +center ; +l c l +l l l. +\fBSuffix Meaning Example\fP +-\fInn\fP Number of lines on the screen aaa-60 +-\fIn\fPp Number of pages of memory c100-4p +-am With automargins (usually the default) vt100-am +-m Mono mode; suppress color ansi-m +-mc Magic cookie; spaces when highlighting wy30-mc +-na No arrow keys (leave them in local) c100-na +-nam Without automatic margins vt100-nam +-nl No status line att4415-nl +-ns No status line hp2626-ns +-rv Reverse video c100-rv +-s Enable status line vt100-s +-vb Use visible bell instead of beep wy370-vb +-w Wide mode (> 80 columns, usually 132) vt100-w +.TE +.PP +For more on terminal naming conventions, see the \fBterm(7)\fR manual page. +.SS Capabilities +.\" Head of terminfo man page ends here +.ps -1 diff --git a/man/terminfo.tail b/man/terminfo.tail new file mode 100644 index 000000000000..d06d3a963a63 --- /dev/null +++ b/man/terminfo.tail @@ -0,0 +1,1703 @@ +.\" $Id: terminfo.tail,v 1.49 2008/02/16 20:57:43 tom Exp $ +.\" Beginning of terminfo.tail file +.\" This file is part of ncurses. +.\" See "terminfo.head" for copyright. +.ps +1 +. +.SS A Sample Entry +. +The following entry, describing an ANSI-standard terminal, is representative +of what a \fBterminfo\fR entry for a modern terminal typically looks like. +.PP +.nf +.in -2 +.ta .3i +.ft CW +\s-2ansi|ansi/pc-term compatible with color, + mc5i, + colors#8, ncv#3, pairs#64, + cub=\\E[%p1%dD, cud=\\E[%p1%dB, cuf=\\E[%p1%dC, + cuu=\\E[%p1%dA, dch=\\E[%p1%dP, dl=\\E[%p1%dM, + ech=\\E[%p1%dX, el1=\\E[1K, hpa=\\E[%p1%dG, ht=\\E[I, + ich=\\E[%p1%d@, il=\\E[%p1%dL, indn=\\E[%p1%dS, .indn=\\E[%p1%dT, + kbs=^H, kcbt=\\E[Z, kcub1=\\E[D, kcud1=\\E[B, + kcuf1=\\E[C, kcuu1=\\E[A, kf1=\\E[M, kf10=\\E[V, + kf11=\\E[W, kf12=\\E[X, kf2=\\E[N, kf3=\\E[O, kf4=\\E[P, + kf5=\\E[Q, kf6=\\E[R, kf7=\\E[S, kf8=\\E[T, kf9=\\E[U, + kich1=\\E[L, mc4=\\E[4i, mc5=\\E[5i, nel=\\r\\E[S, + op=\\E[37;40m, rep=%p1%c\\E[%p2%{1}%-%db, + rin=\\E[%p1%dT, s0ds=\\E(B, s1ds=\\E)B, s2ds=\\E*B, + s3ds=\\E+B, setab=\\E[4%p1%dm, setaf=\\E[3%p1%dm, + setb=\\E[4%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m, + setf=\\E[3%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m, + sgr=\\E[0;10%?%p1%t;7%;%?%p2%t;4%;%?%p3%t;7%;%?%p4%t;5%;%?%p6%t;1%;%?%p7%t;8%;%?%p8%t;11%;%?%p9%t;12%;m, + sgr0=\\E[0;10m, tbc=\\E[2g, u6=\\E[%d;%dR, u7=\\E[6n, + u8=\\E[?%[;0123456789]c, u9=\\E[c, vpa=\\E[%p1%dd,\s+2 +.in +2 +.fi +.ft R +.PP +Entries may continue onto multiple lines by placing white space at +the beginning of each line except the first. +Comments may be included on lines beginning with ``#''. +Capabilities in +.I terminfo +are of three types: +Boolean capabilities which indicate that the terminal has +some particular feature, numeric capabilities giving the size of the terminal +or the size of particular delays, and string +capabilities, which give a sequence which can be used to perform particular +terminal operations. +.PP +.SS Types of Capabilities +.PP +All capabilities have names. +For instance, the fact that +ANSI-standard terminals have +.I "automatic margins" +(i.e., an automatic return and line-feed +when the end of a line is reached) is indicated by the capability \fBam\fR. +Hence the description of ansi includes \fBam\fR. +Numeric capabilities are followed by the character `#' and then a positive value. +Thus \fBcols\fR, which indicates the number of columns the terminal has, +gives the value `80' for ansi. +Values for numeric capabilities may be specified in decimal, octal or hexadecimal, +using the C programming language conventions (e.g., 255, 0377 and 0xff or 0xFF). +.PP +Finally, string valued capabilities, such as \fBel\fR (clear to end of line +sequence) are given by the two-character code, an `=', and then a string +ending at the next following `,'. +.PP +A number of escape sequences are provided in the string valued capabilities +for easy encoding of characters there. +Both \fB\eE\fR and \fB\ee\fR +map to an \s-1ESCAPE\s0 character, +\fB^x\fR maps to a control-x for any appropriate x, and the sequences +\fB\en \el \er \et \eb \ef \es\fR give +a newline, line-feed, return, tab, backspace, form-feed, and space. +Other escapes include \fB\e^\fR for \fB^\fR, +\fB\e\e\fR for \fB\e\fR, +\fB\e\fR, for comma, +\fB\e:\fR for \fB:\fR, +and \fB\e0\fR for null. +(\fB\e0\fR will produce \e200, which does not terminate a string but behaves +as a null character on most terminals, providing CS7 is specified. +See stty(1).) +Finally, characters may be given as three octal digits after a \fB\e\fR. +.PP +A delay in milliseconds may appear anywhere in a string capability, enclosed in +$<..> brackets, as in \fBel\fP=\eEK$<5>, and padding characters are supplied by +.I tputs +to provide this delay. +The delay must be a number with at most one decimal +place of precision; it may be followed by suffixes `*' or '/' or both. +A `*' +indicates that the padding required is proportional to the number of lines +affected by the operation, and the amount given is the per-affected-unit +padding required. +(In the case of insert character, the factor is still the +number of +.IR lines +affected.) Normally, padding is advisory if the device has the \fBxon\fR +capability; it is used for cost computation but does not trigger delays. +A `/' +suffix indicates that the padding is mandatory and forces a delay of the given +number of milliseconds even on devices for which \fBxon\fR is present to +indicate flow control. +.PP +Sometimes individual capabilities must be commented out. +To do this, put a period before the capability name. +For example, see the second +.B ind +in the example above. +.br +.ne 5 +.PP +.SS Fetching Compiled Descriptions +.PP +If the environment variable TERMINFO is set, it is interpreted as the pathname +of a directory containing the compiled description you are working on. +Only +that directory is searched. +.PP +If TERMINFO is not set, the \fBncurses\fR version of the terminfo reader code +will instead look in the directory \fB$HOME/.terminfo\fR +for a compiled description. +If it fails to find one there, and the environment variable TERMINFO_DIRS is +set, it will interpret the contents of that variable as a list of colon- +separated directories to be searched (an empty entry is interpreted as a +command to search \fI\*d\fR). +If no description is found in any of the +TERMINFO_DIRS directories, the fetch fails. +.PP +If neither TERMINFO nor TERMINFO_DIRS is set, the last place tried will be the +system terminfo directory, \fI\*d\fR. +.PP +(Neither the \fB$HOME/.terminfo\fR lookups nor TERMINFO_DIRS extensions are +supported under stock System V terminfo/curses.) +.PP +.SS Preparing Descriptions +.PP +We now outline how to prepare descriptions of terminals. +The most effective way to prepare a terminal description is by imitating +the description of a similar terminal in +.I terminfo +and to build up a description gradually, using partial descriptions +with +.I vi +or some other screen-oriented program to check that they are correct. +Be aware that a very unusual terminal may expose deficiencies in +the ability of the +.I terminfo +file to describe it +or bugs in the screen-handling code of the test program. +.PP +To get the padding for insert line right (if the terminal manufacturer +did not document it) a severe test is to edit a large file at 9600 baud, +delete 16 or so lines from the middle of the screen, then hit the `u' +key several times quickly. +If the terminal messes up, more padding is usually needed. +A similar test can be used for insert character. +.PP +.SS Basic Capabilities +.PP +The number of columns on each line for the terminal is given by the +\fBcols\fR numeric capability. +If the terminal is a \s-1CRT\s0, then the +number of lines on the screen is given by the \fBlines\fR capability. +If the terminal wraps around to the beginning of the next line when +it reaches the right margin, then it should have the \fBam\fR capability. +If the terminal can clear its screen, leaving the cursor in the home +position, then this is given by the \fBclear\fR string capability. +If the terminal overstrikes +(rather than clearing a position when a character is struck over) +then it should have the \fBos\fR capability. +If the terminal is a printing terminal, with no soft copy unit, +give it both +.B hc +and +.BR os . +.RB ( os +applies to storage scope terminals, such as \s-1TEKTRONIX\s+1 4010 +series, as well as hard copy and APL terminals.) +If there is a code to move the cursor to the left edge of the current +row, give this as +.BR cr . +(Normally this will be carriage return, control M.) +If there is a code to produce an audible signal (bell, beep, etc) +give this as +.BR bel . +.PP +If there is a code to move the cursor one position to the left +(such as backspace) that capability should be given as +.BR cub1 . +Similarly, codes to move to the right, up, and down should be +given as +.BR cuf1 , +.BR cuu1 , +and +.BR cud1 . +These local cursor motions should not alter the text they pass over, +for example, you would not normally use `\fBcuf1\fP=\ ' because the +space would erase the character moved over. +.PP +A very important point here is that the local cursor motions encoded +in +.I terminfo +are undefined at the left and top edges of a \s-1CRT\s0 terminal. +Programs should never attempt to backspace around the left edge, +unless +.B bw +is given, +and never attempt to go up locally off the top. +In order to scroll text up, a program will go to the bottom left corner +of the screen and send the +.B ind +(index) string. +.PP +To scroll text down, a program goes to the top left corner +of the screen and sends the +.B ri +(reverse index) string. +The strings +.B ind +and +.B ri +are undefined when not on their respective corners of the screen. +.PP +Parameterized versions of the scrolling sequences are +.B indn +and +.B rin +which have the same semantics as +.B ind +and +.B ri +except that they take one parameter, and scroll that many lines. +They are also undefined except at the appropriate edge of the screen. +.PP +The \fBam\fR capability tells whether the cursor sticks at the right +edge of the screen when text is output, but this does not necessarily +apply to a +.B cuf1 +from the last column. +The only local motion which is defined from the left edge is if +.B bw +is given, then a +.B cub1 +from the left edge will move to the right edge of the previous row. +If +.B bw +is not given, the effect is undefined. +This is useful for drawing a box around the edge of the screen, for example. +If the terminal has switch selectable automatic margins, +the +.I terminfo +file usually assumes that this is on; i.e., \fBam\fR. +If the terminal has a command which moves to the first column of the next +line, that command can be given as +.B nel +(newline). +It does not matter if the command clears the remainder of the current line, +so if the terminal has no +.B cr +and +.B lf +it may still be possible to craft a working +.B nel +out of one or both of them. +.PP +These capabilities suffice to describe hard-copy and \*(lqglass-tty\*(rq terminals. +Thus the model 33 teletype is described as +.PP +.DT +.nf +.ft CW +.\".in -2 +\s-133\||\|tty33\||\|tty\||\|model 33 teletype, + bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1 +.\".in +2 +.ft R +.PP +while the Lear Siegler \s-1ADM-3\s0 is described as +.PP +.DT +.nf +.ft CW +.\".in -2 +\s-1adm3\||\|3\||\|lsi adm3, + am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J, + ind=^J, lines#24,\s+1 +.\".in +2 +.ft R +.fi +.PP +.SS Parameterized Strings +.PP +Cursor addressing and other strings requiring parameters +in the terminal are described by a +parameterized string capability, with +.IR printf (3) +like escapes \fB%x\fR in it. +For example, to address the cursor, the +.B cup +capability is given, using two parameters: +the row and column to address to. +(Rows and columns are numbered from zero and refer to the +physical screen visible to the user, not to any unseen memory.) +If the terminal has memory relative cursor addressing, +that can be indicated by +.BR mrcup . +.PP +The parameter mechanism uses a stack and special \fB%\fP codes +to manipulate it. +Typically a sequence will push one of the +parameters onto the stack and then print it in some format. +Print (e.g., "%d") is a special case. +Other operations, including "%t" pop their operand from the stack. +It is noted that more complex operations are often necessary, +e.g., in the \fBsgr\fP string. +.PP +The \fB%\fR encodings have the following meanings: +.PP +.TP 5 +\s-1%% +outputs `%' +.TP +%\fI[[\fP:\fI]flags][width[.precision]][\fPdoxXs\fI]\fP +as in \fBprintf\fP, flags are [-+#] and space. +Use a `:' to allow the next character to be a `-' flag, +avoiding interpreting "%-" as an operator. +.TP +%c +print pop() like %c in \fBprintf\fP +.TP +%s +print pop() like %s in \fBprintf\fP +.TP +%p[1-9] +push \fIi\fP'th parameter +.TP +%P[a-z] +set dynamic variable [a-z] to pop() +.TP +%g[a-z] +get dynamic variable [a-z] and push it +.TP +%P[A-Z] +set static variable [a-z] to pop() +.TP +%g[A-Z] +get static variable [a-z] and push it +.IP +The terms "static" and "dynamic" are misleading. +Historically, these are simply two different sets of variables, +whose values are not reset between calls to \fBtparm\fP. +However, that fact is not documented in other implementations. +Relying on it will adversely impact portability to other implementations. +.TP +%'\fIc\fP' +char constant \fIc\fP +.TP +%{\fInn\fP} +integer constant \fInn\fP +.TP +%l +push strlen(pop) +.TP +%+ %- %* %/ %m +arithmetic (%m is mod): push(pop() op pop()) +.TP +%& %| %^ +bit operations (AND, OR and exclusive-OR): push(pop() op pop()) +.TP +%= %> %< +logical operations: push(pop() op pop()) +.TP +%A, %O +logical AND and OR operations (for conditionals) +.TP +%! %~ +unary operations (logical and bit complement): push(op pop()) +.TP +%i +add 1 to first two parameters (for ANSI terminals) +.TP +%? \fIexpr\fP %t \fIthenpart\fP %e \fIelsepart\fP %; +This forms an if-then-else. +The %e \fIelsepart\fP is optional. +Usually the %? \fIexpr\fP part pushes a value onto the stack, +and %t pops it from the stack, testing if it is nonzero (true). +If it is zero (false), control passes to the %e (else) part. +.IP +It is possible to form else-if's a la Algol 68: +.RS +%? c\d1\u %t b\d1\u %e c\d2\u %t b\d2\u %e c\d3\u %t b\d3\u %e c\d4\u %t b\d4\u %e %; +.RE +.IP +where c\di\u are conditions, b\di\u are bodies. +.IP +Use the \fB-f\fP option of \fBtic\fP or \fB@INFOCMP@\fP to see +the structure of if-the-else's. +Some strings, e.g., \fBsgr\fP can be very complicated when written +on one line. +The \fB-f\fP option splits the string into lines with the parts indented. +.PP +Binary operations are in postfix form with the operands in the usual order. +That is, to get x-5 one would use "%gx%{5}%-". +%P and %g variables are +persistent across escape-string evaluations. +.PP +Consider the HP2645, which, to get to row 3 and column 12, needs +to be sent \eE&a12c03Y padded for 6 milliseconds. +Note that the order +of the rows and columns is inverted here, and that the row and column +are printed as two digits. +Thus its \fBcup\fR capability is \*(lqcup=6\eE&%p2%2dc%p1%2dY\*(rq. +.PP +The Microterm \s-1ACT-IV\s0 needs the current row and column sent +preceded by a \fB^T\fR, with the row and column simply encoded in binary, +\*(lqcup=^T%p1%c%p2%c\*(rq. +Terminals which use \*(lq%c\*(rq need to be able to +backspace the cursor (\fBcub1\fR), +and to move the cursor up one line on the screen (\fBcuu1\fR). +This is necessary because it is not always safe to transmit \fB\en\fR +\fB^D\fR and \fB\er\fR, as the system may change or discard them. +(The library routines dealing with terminfo set tty modes so that +tabs are never expanded, so \et is safe to send. +This turns out to be essential for the Ann Arbor 4080.) +.PP +A final example is the \s-1LSI ADM\s0-3a, which uses row and column +offset by a blank character, thus \*(lqcup=\eE=%p1%' '%+%c%p2%' '%+%c\*(rq. +After sending `\eE=', this pushes the first parameter, pushes the +ASCII value for a space (32), adds them (pushing the sum on the stack +in place of the two previous values) and outputs that value as a character. +Then the same is done for the second parameter. +More complex arithmetic is possible using the stack. +.PP +.SS Cursor Motions +.PP +If the terminal has a fast way to home the cursor +(to very upper left corner of screen) then this can be given as +\fBhome\fR; similarly a fast way of getting to the lower left-hand corner +can be given as \fBll\fR; this may involve going up with \fBcuu1\fR +from the home position, +but a program should never do this itself (unless \fBll\fR does) because it +can make no assumption about the effect of moving up from the home position. +Note that the home position is the same as addressing to (0,0): +to the top left corner of the screen, not of memory. +(Thus, the \eEH sequence on HP terminals cannot be used for +.BR home .) +.PP +If the terminal has row or column absolute cursor addressing, +these can be given as single parameter capabilities +.B hpa +(horizontal position absolute) +and +.B vpa +(vertical position absolute). +Sometimes these are shorter than the more general two parameter +sequence (as with the hp2645) and can be used in preference to +.BR cup . +If there are parameterized local motions (e.g., move +.I n +spaces to the right) these can be given as +.BR cud , +.BR cub , +.BR cuf , +and +.BR cuu +with a single parameter indicating how many spaces to move. +These are primarily useful if the terminal does not have +.BR cup , +such as the \s-1TEKTRONIX\s+1 4025. +.PP +If the terminal needs to be in a special mode when running +a program that uses these capabilities, +the codes to enter and exit this mode can be given as \fBsmcup\fR and \fBrmcup\fR. +This arises, for example, from terminals like the Concept with more than +one page of memory. +If the terminal has only memory relative cursor addressing and not screen +relative cursor addressing, a one screen-sized window must be fixed into +the terminal for cursor addressing to work properly. +This is also used for the \s-1TEKTRONIX\s+1 4025, +where +.B smcup +sets the command character to be the one used by terminfo. +If the \fBsmcup\fP sequence will not restore the screen after an +\fBrmcup\fP sequence is output (to the state prior to outputting +\fBrmcup\fP), specify \fBnrrmc\fP. +.PP +.SS Area Clears +.PP +If the terminal can clear from the current position to the end of the +line, leaving the cursor where it is, this should be given as \fBel\fR. +If the terminal can clear from the beginning of the line to the current +position inclusive, leaving +the cursor where it is, this should be given as \fBel1\fP. +If the terminal can clear from the current position to the end of the +display, then this should be given as \fBed\fR. +\fBEd\fR is only defined from the first column of a line. +(Thus, it can be simulated by a request to delete a large number of lines, +if a true +.B ed +is not available.) +.PP +.SS Insert/delete line and vertical motions +.PP +If the terminal can open a new blank line before the line where the cursor +is, this should be given as \fBil1\fR; this is done only from the first +position of a line. +The cursor must then appear on the newly blank line. +If the terminal can delete the line which the cursor is on, then this +should be given as \fBdl1\fR; this is done only from the first position on +the line to be deleted. +Versions of +.B il1 +and +.B dl1 +which take a single parameter and insert or delete that many lines can +be given as +.B il +and +.BR dl . +.PP +If the terminal has a settable scrolling region (like the vt100) +the command to set this can be described with the +.B csr +capability, which takes two parameters: +the top and bottom lines of the scrolling region. +The cursor position is, alas, undefined after using this command. +.PP +It is possible to get the effect of insert or delete line using +.B csr +on a properly chosen region; the +.B sc +and +.B rc +(save and restore cursor) commands may be useful for ensuring that +your synthesized insert/delete string does not move the cursor. +(Note that the \fBncurses\fR(3X) library does this synthesis +automatically, so you need not compose insert/delete strings for +an entry with \fBcsr\fR). +.PP +Yet another way to construct insert and delete might be to use a combination of +index with the memory-lock feature found on some terminals (like the HP-700/90 +series, which however also has insert/delete). +.PP +Inserting lines at the top or bottom of the screen can also be +done using +.B ri +or +.B ind +on many terminals without a true insert/delete line, +and is often faster even on terminals with those features. +.PP +The boolean \fBnon_dest_scroll_region\fR should be set if each scrolling +window is effectively a view port on a screen-sized canvas. +To test for +this capability, create a scrolling region in the middle of the screen, +write something to the bottom line, move the cursor to the top of the region, +and do \fBri\fR followed by \fBdl1\fR or \fBind\fR. +If the data scrolled +off the bottom of the region by the \fBri\fR re-appears, then scrolling +is non-destructive. +System V and XSI Curses expect that \fBind\fR, \fBri\fR, +\fBindn\fR, and \fBrin\fR will simulate destructive scrolling; their +documentation cautions you not to define \fBcsr\fR unless this is true. +This \fBcurses\fR implementation is more liberal and will do explicit erases +after scrolling if \fBndstr\fR is defined. +.PP +If the terminal has the ability to define a window as part of +memory, which all commands affect, +it should be given as the parameterized string +.BR wind . +The four parameters are the starting and ending lines in memory +and the starting and ending columns in memory, in that order. +.PP +If the terminal can retain display memory above, then the +\fBda\fR capability should be given; if display memory can be retained +below, then \fBdb\fR should be given. +These indicate +that deleting a line or scrolling may bring non-blank lines up from below +or that scrolling back with \fBri\fR may bring down non-blank lines. +.PP +.SS Insert/Delete Character +.PP +There are two basic kinds of intelligent terminals with respect to +insert/delete character which can be described using +.I terminfo. +The most common insert/delete character operations affect only the characters +on the current line and shift characters off the end of the line rigidly. +Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make +a distinction between typed and untyped blanks on the screen, shifting +upon an insert or delete only to an untyped blank on the screen which is +either eliminated, or expanded to two untyped blanks. +You can determine the +kind of terminal you have by clearing the screen and then typing +text separated by cursor motions. +Type \*(lqabc\ \ \ \ def\*(rq using local +cursor motions (not spaces) between the \*(lqabc\*(rq and the \*(lqdef\*(rq. +Then position the cursor before the \*(lqabc\*(rq and put the terminal in insert +mode. +If typing characters causes the rest of the line to shift +rigidly and characters to fall off the end, then your terminal does +not distinguish between blanks and untyped positions. +If the \*(lqabc\*(rq +shifts over to the \*(lqdef\*(rq which then move together around the end of the +current line and onto the next as you insert, you have the second type of +terminal, and should give the capability \fBin\fR, which stands for +\*(lqinsert null\*(rq. +While these are two logically separate attributes (one line versus multi-line +insert mode, and special treatment of untyped spaces) we have seen no +terminals whose insert mode cannot be described with the single attribute. +.PP +Terminfo can describe both terminals which have an insert mode, and terminals +which send a simple sequence to open a blank position on the current line. +Give as \fBsmir\fR the sequence to get into insert mode. +Give as \fBrmir\fR the sequence to leave insert mode. +Now give as \fBich1\fR any sequence needed to be sent just before sending +the character to be inserted. +Most terminals with a true insert mode +will not give \fBich1\fR; terminals which send a sequence to open a screen +position should give it here. +.PP +If your terminal has both, insert mode is usually preferable to \fBich1\fR. +Technically, you should not give both unless the terminal actually requires +both to be used in combination. +Accordingly, some non-curses applications get +confused if both are present; the symptom is doubled characters in an update +using insert. +This requirement is now rare; most \fBich\fR sequences do not +require previous smir, and most smir insert modes do not require \fBich1\fR +before each character. +Therefore, the new \fBcurses\fR actually assumes this +is the case and uses either \fBrmir\fR/\fBsmir\fR or \fBich\fR/\fBich1\fR as +appropriate (but not both). +If you have to write an entry to be used under +new curses for a terminal old enough to need both, include the +\fBrmir\fR/\fBsmir\fR sequences in \fBich1\fR. +.PP +If post insert padding is needed, give this as a number of milliseconds +in \fBip\fR (a string option). +Any other sequence which may need to be +sent after an insert of a single character may also be given in \fBip\fR. +If your terminal needs both to be placed into an `insert mode' and +a special code to precede each inserted character, then both +.BR smir / rmir +and +.B ich1 +can be given, and both will be used. +The +.B ich +capability, with one parameter, +.IR n , +will repeat the effects of +.B ich1 +.I n +times. +.PP +If padding is necessary between characters typed while not +in insert mode, give this as a number of milliseconds padding in \fBrmp\fP. +.PP +It is occasionally necessary to move around while in insert mode +to delete characters on the same line (e.g., if there is a tab after +the insertion position). +If your terminal allows motion while in +insert mode you can give the capability \fBmir\fR to speed up inserting +in this case. +Omitting \fBmir\fR will affect only speed. +Some terminals +(notably Datamedia's) must not have \fBmir\fR because of the way their +insert mode works. +.PP +Finally, you can specify +.B dch1 +to delete a single character, +.B dch +with one parameter, +.IR n , +to delete +.I n characters, +and delete mode by giving \fBsmdc\fR and \fBrmdc\fR +to enter and exit delete mode (any mode the terminal needs to be placed +in for +.B dch1 +to work). +.PP +A command to erase +.I n +characters (equivalent to outputting +.I n +blanks without moving the cursor) +can be given as +.B ech +with one parameter. +.PP +.SS "Highlighting, Underlining, and Visible Bells" +.PP +If your terminal has one or more kinds of display attributes, +these can be represented in a number of different ways. +You should choose one display form as +\f2standout mode\fR, +representing a good, high contrast, easy-on-the-eyes, +format for highlighting error messages and other attention getters. +(If you have a choice, reverse video plus half-bright is good, +or reverse video alone.) +The sequences to enter and exit standout mode +are given as \fBsmso\fR and \fBrmso\fR, respectively. +If the code to change into or out of standout +mode leaves one or even two blank spaces on the screen, +as the TVI 912 and Teleray 1061 do, +then \fBxmc\fR should be given to tell how many spaces are left. +.PP +Codes to begin underlining and end underlining can be given as \fBsmul\fR +and \fBrmul\fR respectively. +If the terminal has a code to underline the current character and move +the cursor one space to the right, +such as the Microterm Mime, +this can be given as \fBuc\fR. +.PP +Other capabilities to enter various highlighting modes include +.B blink +(blinking) +.B bold +(bold or extra bright) +.B dim +(dim or half-bright) +.B invis +(blanking or invisible text) +.B prot +(protected) +.B rev +(reverse video) +.B sgr0 +(turn off +.I all +attribute modes) +.B smacs +(enter alternate character set mode) +and +.B rmacs +(exit alternate character set mode). +Turning on any of these modes singly may or may not turn off other modes. +.PP +If there is a sequence to set arbitrary combinations of modes, +this should be given as +.B sgr +(set attributes), +taking 9 parameters. +Each parameter is either 0 or nonzero, as the corresponding attribute is on or off. +The 9 parameters are, in order: +standout, underline, reverse, blink, dim, bold, blank, protect, alternate +character set. +Not all modes need be supported by +.BR sgr , +only those for which corresponding separate attribute commands exist. +.PP +For example, the DEC vt220 supports most of the modes: +.PP +.TS +center; +l c c +l c c +lw28 lw6 lw2 lw20. +\fBtparm parameter attribute escape sequence\fP + +none none \\E[0m +p1 standout \\E[0;1;7m +p2 underline \\E[0;4m +p3 reverse \\E[0;7m +p4 blink \\E[0;5m +p5 dim not available +p6 bold \\E[0;1m +p7 invis \\E[0;8m +p8 protect not used +p9 altcharset ^O (off) ^N (on) +.TE +.PP +We begin each escape sequence by turning off any existing modes, since +there is no quick way to determine whether they are active. +Standout is set up to be the combination of reverse and bold. +The vt220 terminal has a protect mode, +though it is not commonly used in sgr +because it protects characters on the screen from the host's erasures. +The altcharset mode also is different in that it is either ^O or ^N, +depending on whether it is off or on. +If all modes are turned on, the resulting sequence is \\E[0;1;4;5;7;8m^N. +.PP +Some sequences are common to different modes. +For example, ;7 is output when either p1 or p3 is true, that is, if +either standout or reverse modes are turned on. +.PP +Writing out the above sequences, along with their dependencies yields +.PP +.TS +center; +l c c +l c c +lw28 lw6 lw2 lw20. +\fBsequence when to output terminfo translation\fP + +\\E[0 always \\E[0 +;1 if p1 or p6 %?%p1%p6%|%t;1%; +;4 if p2 %?%p2%|%t;4%; +;5 if p4 %?%p4%|%t;5%; +;7 if p1 or p3 %?%p1%p3%|%t;7%; +;8 if p7 %?%p7%|%t;8%; +m always m +^N or ^O if p9 ^N, else ^O %?%p9%t^N%e^O%; +.TE +.PP +Putting this all together into the sgr sequence gives: +.PP +.nf + sgr=\\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;7%; + %?%p4%t;5%;%?%p7%t;8%;m%?%p9%t\\016%e\\017%;, +.fi +.PP +Remember that if you specify sgr, you must also specify sgr0. +Also, some implementations rely on sgr being given if sgr0 is, +Not all terminfo entries necessarily have an sgr string, however. +Many terminfo entries are derived from termcap entries +which have no sgr string. +The only drawback to adding an sgr string is that termcap also +assumes that sgr0 does not exit alternate character set mode. +.PP +Terminals with the ``magic cookie'' glitch +.RB ( xmc ) +deposit special ``cookies'' when they receive mode-setting sequences, +which affect the display algorithm rather than having extra bits for +each character. +Some terminals, such as the HP 2621, automatically leave standout +mode when they move to a new line or the cursor is addressed. +Programs using standout mode should exit standout mode before +moving the cursor or sending a newline, +unless the +.B msgr +capability, asserting that it is safe to move in standout mode, is present. +.PP +If the terminal has +a way of flashing the screen to indicate an error quietly (a bell replacement) +then this can be given as \fBflash\fR; it must not move the cursor. +.PP +If the cursor needs to be made more visible than normal when it is +not on the bottom line (to make, for example, a non-blinking underline into an +easier to find block or blinking underline) +give this sequence as +.BR cvvis . +If there is a way to make the cursor completely invisible, give that as +.BR civis . +The capability +.BR cnorm +should be given which undoes the effects of both of these modes. +.PP +If your terminal correctly generates underlined characters +(with no special codes needed) +even though it does not overstrike, +then you should give the capability \fBul\fR. +If a character overstriking another leaves both characters on the screen, +specify the capability \fBos\fP. +If overstrikes are erasable with a blank, +then this should be indicated by giving \fBeo\fR. +.PP +.SS Keypad and Function Keys +.PP +If the terminal has a keypad that transmits codes when the keys are pressed, +this information can be given. +Note that it is not possible to handle +terminals where the keypad only works in local (this applies, for example, +to the unshifted HP 2621 keys). +If the keypad can be set to transmit or not transmit, +give these codes as \fBsmkx\fR and \fBrmkx\fR. +Otherwise the keypad is assumed to always transmit. +The codes sent by the left arrow, right arrow, up arrow, down arrow, +and home keys can be given as +\fBkcub1, kcuf1, kcuu1, kcud1, \fRand\fB khome\fR respectively. +If there are function keys such as f0, f1, ..., f10, the codes they send +can be given as \fBkf0, kf1, ..., kf10\fR. +If these keys have labels other than the default f0 through f10, the labels +can be given as \fBlf0, lf1, ..., lf10\fR. +The codes transmitted by certain other special keys can be given: +.B kll +(home down), +.B kbs +(backspace), +.B ktbc +(clear all tabs), +.B kctab +(clear the tab stop in this column), +.B kclr +(clear screen or erase key), +.B kdch1 +(delete character), +.B kdl1 +(delete line), +.B krmir +(exit insert mode), +.B kel +(clear to end of line), +.B ked +(clear to end of screen), +.B kich1 +(insert character or enter insert mode), +.B kil1 +(insert line), +.B knp +(next page), +.B kpp +(previous page), +.B kind +(scroll forward/down), +.B kri +(scroll backward/up), +.B khts +(set a tab stop in this column). +In addition, if the keypad has a 3 by 3 array of keys including the four +arrow keys, the other five keys can be given as +.BR ka1 , +.BR ka3 , +.BR kb2 , +.BR kc1 , +and +.BR kc3 . +These keys are useful when the effects of a 3 by 3 directional pad are needed. +.PP +Strings to program function keys can be given as +.BR pfkey , +.BR pfloc , +and +.BR pfx . +A string to program screen labels should be specified as \fBpln\fP. +Each of these strings takes two parameters: the function key number to +program (from 0 to 10) and the string to program it with. +Function key numbers out of this range may program undefined keys in +a terminal dependent manner. +The difference between the capabilities is that +.B pfkey +causes pressing the given key to be the same as the user typing the +given string; +.B pfloc +causes the string to be executed by the terminal in local; and +.B pfx +causes the string to be transmitted to the computer. +.PP +The capabilities \fBnlab\fP, \fBlw\fP and \fBlh\fP +define the number of programmable +screen labels and their width and height. +If there are commands to turn the labels on and off, +give them in \fBsmln\fP and \fBrmln\fP. +\fBsmln\fP is normally output after one or more pln +sequences to make sure that the change becomes visible. +.PP +.SS Tabs and Initialization +.PP +If the terminal has hardware tabs, the command to advance to the next +tab stop can be given as +.B ht +(usually control I). +A ``back-tab'' command which moves leftward to the preceding tab stop can +be given as +.BR cbt . +By convention, if the teletype modes indicate that tabs are being +expanded by the computer rather than being sent to the terminal, +programs should not use +.B ht +or +.B cbt +even if they are present, since the user may not have the tab stops +properly set. +If the terminal has hardware tabs which are initially set every +.I n +spaces when the terminal is powered up, +the numeric parameter +.B it +is given, showing the number of spaces the tabs are set to. +This is normally used by the +.IR tset +command to determine whether to set the mode for hardware tab expansion, +and whether to set the tab stops. +If the terminal has tab stops that can be saved in non-volatile memory, +the terminfo description can assume that they are properly set. +.PP +Other capabilities +include +.BR is1 , +.BR is2 , +and +.BR is3 , +initialization strings for the terminal, +.BR iprog , +the path name of a program to be run to initialize the terminal, +and \fBif\fR, the name of a file containing long initialization strings. +These strings are expected to set the terminal into modes consistent +with the rest of the terminfo description. +They are normally sent to the terminal, by the +.I init +option of the +.IR @TPUT@ +program, each time the user logs in. +They will be printed in the following order: +.RS +.TP +run the program +.BR iprog +.TP +output +.BR is1 +.BR is2 +.TP +set the margins using +.BR mgc , +.BR smgl +and +.BR smgr +.TP +set tabs using +.B tbc +and +.BR hts +.TP +print the file +.BR if +.TP +and finally +output +.BR is3 . +.RE +.PP +Most initialization is done with +.BR is2 . +Special terminal modes can be set up without duplicating strings +by putting the common sequences in +.B is2 +and special cases in +.B is1 +and +.BR is3 . +.PP +A set of sequences that does a harder reset from a totally unknown state +can be given as +.BR rs1 , +.BR rs2 , +.BR rf +and +.BR rs3 , +analogous to +.B is1 , +.B is2 , +.B if +and +.BR is3 +respectively. +These strings are output by the +.IR reset +program, which is used when the terminal gets into a wedged state. +Commands are normally placed in +.BR rs1 , +.BR rs2 +.B rs3 +and +.B rf +only if they produce annoying effects on the screen and are not +necessary when logging in. +For example, the command to set the vt100 into 80-column mode would +normally be part of +.BR is2 , +but it causes an annoying glitch of the screen and is not normally +needed since the terminal is usually already in 80 column mode. +.PP +The +.IR reset +program writes strings +including +.BR iprog , +etc., in the same order as the +.IR init +program, using +.BR rs1 , +etc., instead of +.BR is1 , +etc. +If any of +.BR rs1 , +.BR rs2 , +.BR rs3 , +or +.BR rf +reset capability strings are missing, the +.IR reset +program falls back upon the corresponding initialization capability string. +.PP +If there are commands to set and clear tab stops, they can be given as +.B tbc +(clear all tab stops) +and +.B hts +(set a tab stop in the current column of every row). +If a more complex sequence is needed to set the tabs than can be +described by this, the sequence can be placed in +.B is2 +or +.BR if . +.SS Delays and Padding +.PP +Many older and slower terminals do not support either XON/XOFF or DTR +handshaking, including hard copy terminals and some very archaic CRTs +(including, for example, DEC VT100s). +These may require padding characters +after certain cursor motions and screen changes. +.PP +If the terminal uses xon/xoff handshaking for flow control (that is, +it automatically emits ^S back to the host when its input buffers are +close to full), set +.BR xon . +This capability suppresses the emission of padding. +You can also set it +for memory-mapped console devices effectively that do not have a speed limit. +Padding information should still be included so that routines can +make better decisions about relative costs, but actual pad characters will +not be transmitted. +.PP +If \fBpb\fR (padding baud rate) is given, padding is suppressed at baud rates +below the value of \fBpb\fR. +If the entry has no padding baud rate, then +whether padding is emitted or not is completely controlled by \fBxon\fR. +.PP +If the terminal requires other than a null (zero) character as a pad, +then this can be given as \fBpad\fR. +Only the first character of the +.B pad +string is used. +.PP +.SS Status Lines +Some terminals have an extra `status line' which is not normally used by +software (and thus not counted in the terminal's \fBlines\fR capability). +.PP +The simplest case is a status line which is cursor-addressable but not +part of the main scrolling region on the screen; the Heathkit H19 has +a status line of this kind, as would a 24-line VT100 with a 23-line +scrolling region set up on initialization. +This situation is indicated +by the \fBhs\fR capability. +.PP +Some terminals with status lines need special sequences to access the +status line. +These may be expressed as a string with single parameter +\fBtsl\fR which takes the cursor to a given zero-origin column on the +status line. +The capability \fBfsl\fR must return to the main-screen +cursor positions before the last \fBtsl\fR. +You may need to embed the +string values of \fBsc\fR (save cursor) and \fBrc\fR (restore cursor) +in \fBtsl\fR and \fBfsl\fR to accomplish this. +.PP +The status line is normally assumed to be the same width as the width +of the terminal. +If this is untrue, you can specify it with the numeric +capability \fBwsl\fR. +.PP +A command to erase or blank the status line may be specified as \fBdsl\fR. +.PP +The boolean capability \fBeslok\fR specifies that escape sequences, tabs, +etc., work ordinarily in the status line. +.PP +The \fBncurses\fR implementation does not yet use any of these capabilities. +They are documented here in case they ever become important. +.PP +.SS Line Graphics +.PP +Many terminals have alternate character sets useful for forms-drawing. +Terminfo and \fBcurses\fR build in support for the drawing characters +supported by the VT100, with some characters from the AT&T 4410v1 added. +This alternate character set may be specified by the \fBacsc\fR capability. +.PP +.TS H +center expand; +c l l c +c l l c +lw28 lw6 lw2 lw20. +.\".TH +\fBGlyph ACS Ascii VT100\fR +\fBName Name Default Name\fR +UK pound sign ACS_STERLING f } +arrow pointing down ACS_DARROW v . +arrow pointing left ACS_LARROW < , +arrow pointing right ACS_RARROW > + +arrow pointing up ACS_UARROW ^ - +board of squares ACS_BOARD # h +bullet ACS_BULLET o ~ +checker board (stipple) ACS_CKBOARD : a +degree symbol ACS_DEGREE \e f +diamond ACS_DIAMOND + ` +greater-than-or-equal-to ACS_GEQUAL > z +greek pi ACS_PI * { +horizontal line ACS_HLINE - q +lantern symbol ACS_LANTERN # i +large plus or crossover ACS_PLUS + n +less-than-or-equal-to ACS_LEQUAL < y +lower left corner ACS_LLCORNER + m +lower right corner ACS_LRCORNER + j +not-equal ACS_NEQUAL ! | +plus/minus ACS_PLMINUS # g +scan line 1 ACS_S1 ~ o +scan line 3 ACS_S3 - p +scan line 7 ACS_S7 - r +scan line 9 ACS_S9 \&_ s +solid square block ACS_BLOCK # 0 +tee pointing down ACS_TTEE + w +tee pointing left ACS_RTEE + u +tee pointing right ACS_LTEE + t +tee pointing up ACS_BTEE + v +upper left corner ACS_ULCORNER + l +upper right corner ACS_URCORNER + k +vertical line ACS_VLINE | x +.TE +.PP +The best way to define a new device's graphics set is to add a column +to a copy of this table for your terminal, giving the character which +(when emitted between \fBsmacs\fR/\fBrmacs\fR switches) will be rendered +as the corresponding graphic. +Then read off the VT100/your terminal +character pairs right to left in sequence; these become the ACSC string. +.PP +.SS Color Handling +.PP +Most color terminals are either `Tektronix-like' or `HP-like'. +Tektronix-like +terminals have a predefined set of N colors (where N usually 8), and can set +character-cell foreground and background characters independently, mixing them +into N * N color-pairs. +On HP-like terminals, the use must set each color +pair up separately (foreground and background are not independently settable). +Up to M color-pairs may be set up from 2*M different colors. +ANSI-compatible +terminals are Tektronix-like. +.PP +Some basic color capabilities are independent of the color method. +The numeric +capabilities \fBcolors\fR and \fBpairs\fR specify the maximum numbers of colors +and color-pairs that can be displayed simultaneously. +The \fBop\fR (original +pair) string resets foreground and background colors to their default values +for the terminal. +The \fBoc\fR string resets all colors or color-pairs to +their default values for the terminal. +Some terminals (including many PC +terminal emulators) erase screen areas with the current background color rather +than the power-up default background; these should have the boolean capability +\fBbce\fR. +.PP +To change the current foreground or background color on a Tektronix-type +terminal, use \fBsetaf\fR (set ANSI foreground) and \fBsetab\fR (set ANSI +background) or \fBsetf\fR (set foreground) and \fBsetb\fR (set background). +These take one parameter, the color number. +The SVr4 documentation describes +only \fBsetaf\fR/\fBsetab\fR; the XPG4 draft says that "If the terminal +supports ANSI escape sequences to set background and foreground, they should +be coded as \fBsetaf\fR and \fBsetab\fR, respectively. +If the terminal +supports other escape sequences to set background and foreground, they should +be coded as \fBsetf\fR and \fBsetb\fR, respectively. +The \fIvidputs()\fR +function and the refresh functions use \fBsetaf\fR and \fBsetab\fR if they are +defined." +.PP +The \fBsetaf\fR/\fBsetab\fR and \fBsetf\fR/\fBsetb\fR capabilities take a +single numeric argument each. +Argument values 0-7 of \fBsetaf\fR/\fBsetab\fR are portably defined as +follows (the middle column is the symbolic #define available in the header for +the \fBcurses\fR or \fBncurses\fR libraries). +The terminal hardware is free to +map these as it likes, but the RGB values indicate normal locations in color +space. +.PP +.TS H +center; +l c c c +l l n l. +\fBColor #define Value RGB\fR +black \fBCOLOR_BLACK\fR 0 0, 0, 0 +red \fBCOLOR_RED\ \fR 1 max,0,0 +green \fBCOLOR_GREEN\fR 2 0,max,0 +yellow \fBCOLOR_YELLOW\fR 3 max,max,0 +blue \fBCOLOR_BLUE\fR 4 0,0,max +magenta \fBCOLOR_MAGENTA\fR 5 max,0,max +cyan \fBCOLOR_CYAN\fR 6 0,max,max +white \fBCOLOR_WHITE\fR 7 max,max,max +.TE +.PP +The argument values of \fBsetf\fR/\fBsetb\fR historically correspond to +a different mapping, i.e., +.TS H +center; +l c c c +l l n l. +\fBColor #define Value RGB\fR +black \fBCOLOR_BLACK\fR 0 0, 0, 0 +blue \fBCOLOR_BLUE\fR 1 0,0,max +green \fBCOLOR_GREEN\fR 2 0,max,0 +cyan \fBCOLOR_CYAN\fR 3 0,max,max +red \fBCOLOR_RED\ \fR 4 max,0,0 +magenta \fBCOLOR_MAGENTA\fR 5 max,0,max +yellow \fBCOLOR_YELLOW\fR 6 max,max,0 +white \fBCOLOR_WHITE\fR 7 max,max,max +.TE +It is important to not confuse the two sets of color capabilities; +otherwise red/blue will be interchanged on the display. +.PP +On an HP-like terminal, use \fBscp\fR with a color-pair number parameter to set +which color pair is current. +.PP +On a Tektronix-like terminal, the capability \fBccc\fR may be present to +indicate that colors can be modified. +If so, the \fBinitc\fR capability will +take a color number (0 to \fBcolors\fR - 1)and three more parameters which +describe the color. +These three parameters default to being interpreted as RGB +(Red, Green, Blue) values. +If the boolean capability \fBhls\fR is present, +they are instead as HLS (Hue, Lightness, Saturation) indices. +The ranges are +terminal-dependent. +.PP +On an HP-like terminal, \fBinitp\fR may give a capability for changing a +color-pair value. +It will take seven parameters; a color-pair number (0 to +\fBmax_pairs\fR - 1), and two triples describing first background and then +foreground colors. +These parameters must be (Red, Green, Blue) or +(Hue, Lightness, Saturation) depending on \fBhls\fR. +.PP +On some color terminals, colors collide with highlights. +You can register +these collisions with the \fBncv\fR capability. +This is a bit-mask of +attributes not to be used when colors are enabled. +The correspondence with the +attributes understood by \fBcurses\fR is as follows: +.PP +.TS +center; +l c c +lw25 lw2 lw10. +\fBAttribute Bit Decimal\fR +A_STANDOUT 0 1 +A_UNDERLINE 1 2 +A_REVERSE 2 4 +A_BLINK 3 8 +A_DIM 4 16 +A_BOLD 5 32 +A_INVIS 6 64 +A_PROTECT 7 128 +A_ALTCHARSET 8 256 +.TE +.PP +For example, on many IBM PC consoles, the underline attribute collides with the +foreground color blue and is not available in color mode. +These should have +an \fBncv\fR capability of 2. +.PP +SVr4 curses does nothing with \fBncv\fR, ncurses recognizes it and optimizes +the output in favor of colors. +.PP +.SS Miscellaneous +If the terminal requires other than a null (zero) character as a pad, then this +can be given as pad. +Only the first character of the pad string is used. +If the terminal does not have a pad character, specify npc. +Note that ncurses implements the termcap-compatible \fBPC\fR variable; +though the application may set this value to something other than +a null, ncurses will test \fBnpc\fR first and use napms if the terminal +has no pad character. +.PP +If the terminal can move up or down half a line, +this can be indicated with +.B hu +(half-line up) +and +.B hd +(half-line down). +This is primarily useful for superscripts and subscripts on hard-copy terminals. +If a hard-copy terminal can eject to the next page (form feed), give this as +.B ff +(usually control L). +.PP +If there is a command to repeat a given character a given number of +times (to save time transmitting a large number of identical characters) +this can be indicated with the parameterized string +.BR rep . +The first parameter is the character to be repeated and the second +is the number of times to repeat it. +Thus, tparm(repeat_char, 'x', 10) is the same as `xxxxxxxxxx'. +.PP +If the terminal has a settable command character, such as the \s-1TEKTRONIX\s+1 4025, +this can be indicated with +.BR cmdch . +A prototype command character is chosen which is used in all capabilities. +This character is given in the +.B cmdch +capability to identify it. +The following convention is supported on some UNIX systems: +The environment is to be searched for a +.B CC +variable, and if found, all +occurrences of the prototype character are replaced with the character +in the environment variable. +.PP +Terminal descriptions that do not represent a specific kind of known +terminal, such as +.IR switch , +.IR dialup , +.IR patch , +and +.IR network , +should include the +.B gn +(generic) capability so that programs can complain that they do not know +how to talk to the terminal. +(This capability does not apply to +.I virtual +terminal descriptions for which the escape sequences are known.) +.PP +If the terminal has a ``meta key'' which acts as a shift key, +setting the 8th bit of any character transmitted, this fact can +be indicated with +.BR km . +Otherwise, software will assume that the 8th bit is parity and it +will usually be cleared. +If strings exist to turn this ``meta mode'' on and off, they +can be given as +.B smm +and +.BR rmm . +.PP +If the terminal has more lines of memory than will fit on the screen +at once, the number of lines of memory can be indicated with +.BR lm . +A value of +.BR lm #0 +indicates that the number of lines is not fixed, +but that there is still more memory than fits on the screen. +.PP +If the terminal is one of those supported by the \s-1UNIX\s+1 virtual +terminal protocol, the terminal number can be given as +.BR vt . +.PP +Media copy +strings which control an auxiliary printer connected to the terminal +can be given as +.BR mc0 : +print the contents of the screen, +.BR mc4 : +turn off the printer, and +.BR mc5 : +turn on the printer. +When the printer is on, all text sent to the terminal will be sent +to the printer. +It is undefined whether the text is also displayed on the terminal screen +when the printer is on. +A variation +.B mc5p +takes one parameter, and leaves the printer on for as many characters +as the value of the parameter, then turns the printer off. +The parameter should not exceed 255. +All text, including +.BR mc4 , +is transparently passed to the printer while an +.B mc5p +is in effect. +.PP +.SS Glitches and Braindamage +.PP +Hazeltine terminals, which do not allow `~' characters to be displayed should +indicate \fBhz\fR. +.PP +Terminals which ignore a line-feed immediately after an \fBam\fR wrap, +such as the Concept and vt100, +should indicate \fBxenl\fR. +.PP +If +.B el +is required to get rid of standout +(instead of merely writing normal text on top of it), +\fBxhp\fP should be given. +.PP +Teleray terminals, where tabs turn all characters moved over to blanks, +should indicate \fBxt\fR (destructive tabs). +Note: the variable indicating this is now `dest_tabs_magic_smso'; in +older versions, it was teleray_glitch. +This glitch is also taken to mean that it is not possible to position +the cursor on top of a ``magic cookie'', +that to erase standout mode it is instead necessary to use +delete and insert line. +The ncurses implementation ignores this glitch. +.PP +The Beehive Superbee, which is unable to correctly transmit the escape +or control C characters, has +.BR xsb , +indicating that the f1 key is used for escape and f2 for control C. +(Only certain Superbees have this problem, depending on the ROM.) +Note that in older terminfo versions, this capability was called +`beehive_glitch'; it is now `no_esc_ctl_c'. +.PP +Other specific terminal problems may be corrected by adding more +capabilities of the form \fBx\fR\fIx\fR. +.PP +.SS Similar Terminals +.PP +If there are two very similar terminals, one (the variant) can be defined as +being just like the other (the base) with certain exceptions. +In the +definition of the variant, the string capability \fBuse\fR can be given with +the name of the base terminal. +The capabilities given before +.B use +override those in the base type named by +.BR use . +If there are multiple \fBuse\fR capabilities, they are merged in reverse order. +That is, the rightmost \fBuse\fR reference is processed first, then the one to +its left, and so forth. +Capabilities given explicitly in the entry override +those brought in by \fBuse\fR references. +.PP +A capability can be canceled by placing \fBxx@\fR to the left of the +use reference that imports it, where \fIxx\fP is the capability. +For example, the entry +.PP + 2621-nl, smkx@, rmkx@, use=2621, +.PP +defines a 2621-nl that does not have the \fBsmkx\fR or \fBrmkx\fR capabilities, +and hence does not turn on the function key labels when in visual mode. +This is useful for different modes for a terminal, or for different +user preferences. +.PP +.SS Pitfalls of Long Entries +.PP +Long terminfo entries are unlikely to be a problem; to date, no entry has even +approached terminfo's 4096-byte string-table maximum. +Unfortunately, the termcap +translations are much more strictly limited (to 1023 bytes), thus termcap translations +of long terminfo entries can cause problems. +.PP +The man pages for 4.3BSD and older versions of \fBtgetent()\fP instruct the user to +allocate a 1024-byte buffer for the termcap entry. +The entry gets null-terminated by +the termcap library, so that makes the maximum safe length for a termcap entry +1k-1 (1023) bytes. +Depending on what the application and the termcap library +being used does, and where in the termcap file the terminal type that \fBtgetent()\fP +is searching for is, several bad things can happen. +.PP +Some termcap libraries print a warning message or exit if they find an +entry that's longer than 1023 bytes; others do not; others truncate the +entries to 1023 bytes. +Some application programs allocate more than +the recommended 1K for the termcap entry; others do not. +.PP +Each termcap entry has two important sizes associated with it: before +"tc" expansion, and after "tc" expansion. +"tc" is the capability that +tacks on another termcap entry to the end of the current one, to add +on its capabilities. +If a termcap entry does not use the "tc" +capability, then of course the two lengths are the same. +.PP +The "before tc expansion" length is the most important one, because it +affects more than just users of that particular terminal. +This is the +length of the entry as it exists in /etc/termcap, minus the +backslash-newline pairs, which \fBtgetent()\fP strips out while reading it. +Some termcap libraries strip off the final newline, too (GNU termcap does not). +Now suppose: +.TP 5 +* +a termcap entry before expansion is more than 1023 bytes long, +.TP 5 +* +and the application has only allocated a 1k buffer, +.TP 5 +* +and the termcap library (like the one in BSD/OS 1.1 and GNU) reads +the whole entry into the buffer, no matter what its length, to see +if it is the entry it wants, +.TP 5 +* +and \fBtgetent()\fP is searching for a terminal type that either is the +long entry, appears in the termcap file after the long entry, or +does not appear in the file at all (so that \fBtgetent()\fP has to search +the whole termcap file). +.PP +Then \fBtgetent()\fP will overwrite memory, perhaps its stack, and probably core dump +the program. +Programs like telnet are particularly vulnerable; modern telnets +pass along values like the terminal type automatically. +The results are almost +as undesirable with a termcap library, like SunOS 4.1.3 and Ultrix 4.4, that +prints warning messages when it reads an overly long termcap entry. +If a +termcap library truncates long entries, like OSF/1 3.0, it is immune to dying +here but will return incorrect data for the terminal. +.PP +The "after tc expansion" length will have a similar effect to the +above, but only for people who actually set TERM to that terminal +type, since \fBtgetent()\fP only does "tc" expansion once it is found the +terminal type it was looking for, not while searching. +.PP +In summary, a termcap entry that is longer than 1023 bytes can cause, +on various combinations of termcap libraries and applications, a core +dump, warnings, or incorrect operation. +If it is too long even before +"tc" expansion, it will have this effect even for users of some other +terminal types and users whose TERM variable does not have a termcap +entry. +.PP +When in -C (translate to termcap) mode, the \fBncurses\fR implementation of +\fB@TIC@\fR(1M) issues warning messages when the pre-tc length of a termcap +translation is too long. +The -c (check) option also checks resolved (after tc +expansion) lengths. +.SS Binary Compatibility +It is not wise to count on portability of binary terminfo entries between +commercial UNIX versions. +The problem is that there are at least two versions +of terminfo (under HP-UX and AIX) which diverged from System V terminfo after +SVr1, and have added extension capabilities to the string table that (in the +binary format) collide with System V and XSI Curses extensions. +.SH EXTENSIONS +Some SVr4 \fBcurses\fR implementations, and all previous to SVr4, do not +interpret the %A and %O operators in parameter strings. +.PP +SVr4/XPG4 do not specify whether \fBmsgr\fR licenses movement while in +an alternate-character-set mode (such modes may, among other things, map +CR and NL to characters that do not trigger local motions). +The \fBncurses\fR implementation ignores \fBmsgr\fR in \fBALTCHARSET\fR +mode. +This raises the possibility that an XPG4 +implementation making the opposite interpretation may need terminfo +entries made for \fBncurses\fR to have \fBmsgr\fR turned off. +.PP +The \fBncurses\fR library handles insert-character and insert-character modes +in a slightly non-standard way to get better update efficiency. +See +the \fBInsert/Delete Character\fR subsection above. +.PP +The parameter substitutions for \fBset_clock\fR and \fBdisplay_clock\fR are +not documented in SVr4 or the XSI Curses standard. +They are deduced from the +documentation for the AT&T 505 terminal. +.PP +Be careful assigning the \fBkmous\fR capability. +The \fBncurses\fR wants to +interpret it as \fBKEY_MOUSE\fR, for use by terminals and emulators like xterm +that can return mouse-tracking information in the keyboard-input stream. +.PP +Different commercial ports of terminfo and curses support different subsets of +the XSI Curses standard and (in some cases) different extension sets. +Here +is a summary, accurate as of October 1995: +.PP +\fBSVR4, Solaris, ncurses\fR -- +These support all SVr4 capabilities. +.PP +\fBSGI\fR -- +Supports the SVr4 set, adds one undocumented extended string +capability (\fBset_pglen\fR). +.PP +\fBSVr1, Ultrix\fR -- +These support a restricted subset of terminfo capabilities. +The booleans +end with \fBxon_xoff\fR; the numerics with \fBwidth_status_line\fR; and the +strings with \fBprtr_non\fR. +.PP +\fBHP/UX\fR -- +Supports the SVr1 subset, plus the SVr[234] numerics \fBnum_labels\fR, +\fBlabel_height\fR, \fBlabel_width\fR, plus function keys 11 through 63, plus +\fBplab_norm\fR, \fBlabel_on\fR, and \fBlabel_off\fR, plus some incompatible +extensions in the string table. +.PP +\fBAIX\fR -- +Supports the SVr1 subset, plus function keys 11 through 63, plus a number +of incompatible string table extensions. +.PP +\fBOSF\fR -- +Supports both the SVr4 set and the AIX extensions. +.SH FILES +.TP 25 +\*d/?/* +files containing terminal descriptions +.SH SEE ALSO +\fB@TIC@\fR(1M), +\fB@INFOCMP@\fR(1M), +\fBcurses\fR(3X), +\fBprintf\fR(3), +\fBterm\fR(\*n). +.SH AUTHORS +Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. +Based on pcurses by Pavel Curtis. +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/tic.1m b/man/tic.1m new file mode 100644 index 000000000000..343ec323140d --- /dev/null +++ b/man/tic.1m @@ -0,0 +1,331 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: tic.1m,v 1.44 2006/12/24 17:59:11 tom Exp $ +.TH @TIC@ 1M "" +.ds n 5 +.ds d @TERMINFO@ +.SH NAME +\fBtic\fR - the \fIterminfo\fR entry-description compiler +.SH SYNOPSIS +\fBtic\fR +[\fB-\ +1\ +C\ +G\ +I\ +L\ +N\ +T\ +U\ +V\ +a\ +c\ +f\ +g\ +r\ +s\ +t\ +x\ +\fR] +[\fB-e\fR \fInames\fR] +[\fB-o\fR \fIdir\fR] +[\fB-R\fR \fIsubset\fR] +[\fB-v\fR[\fIn\fR]] +[\fB-w\fR[\fIn\fR]] +\fIfile\fR +.br +.SH DESCRIPTION +The command \fBtic\fR translates a \fBterminfo\fR file from source +format into compiled format. The compiled format is necessary for use with +the library routines in \fBncurses\fR(3X). +.PP +The results are normally placed in the system terminfo +directory \fB\*d\fR. There are two ways to change this behavior. +.PP +First, you may override the system default by setting the variable +\fBTERMINFO\fR in your shell environment to a valid (existing) directory name. +.PP +Secondly, if \fBtic\fR cannot get access to \fI\*d\fR or your TERMINFO +directory, it looks for the directory \fI$HOME/.terminfo\fR; if that directory +exists, the entry is placed there. +.PP +Libraries that read terminfo entries are expected to check for a TERMINFO +directory first, look at \fI$HOME/.terminfo\fR if TERMINFO is not set, and +finally look in \fI\*d\fR. +.TP +\fB-1\fR +restricts the output to a single column +.TP +\fB-a\fR +tells \fBtic\fP to retain commented-out capabilities rather than discarding +them. Capabilities are commented by prefixing them with a period. +This sets the \fB-x\fR option, because it treats the commented-out +entries as user-defined names. +If the source is termcap, accept the 2-character names required by version 6. +Otherwise these are ignored. +.TP +\fB-C\fR +Force source translation to termcap format. Note: this differs from the \fB-C\fR +option of \fB@INFOCMP@\fR(1M) in that it does not merely translate capability +names, but also translates terminfo strings to termcap format. Capabilities +that are not translatable are left in the entry under their terminfo names +but commented out with two preceding dots. +.TP +\fB-c\fR +tells \fBtic\fP to only check \fIfile\fR for errors, including syntax problems and +bad use links. If you specify \fB-C\fR (\fB-I\fR) with this option, the code +will print warnings about entries which, after use resolution, are more than +1023 (4096) bytes long. Due to a fixed buffer length in older termcap +libraries (and a documented limit in terminfo), these entries may cause core +dumps. +.TP +\fB-e \fR\fInames\fR +Limit writes and translations to the following comma-separated list of +terminals. +If any name or alias of a terminal matches one of the names in +the list, the entry will be written or translated as normal. +Otherwise no output will be generated for it. +The option value is interpreted as a file containing the list if it +contains a '/'. +(Note: depending on how tic was compiled, this option may require \fB-I\fR or \fB-C\fR.) +.TP +\fB-f\fR +Display complex terminfo strings which contain if/then/else/endif expressions +indented for readability. +.TP +\fB-G\fR +Display constant literals in decimal form +rather than their character equivalents. +.TP +\fB-g\fR +Display constant character literals in quoted form +rather than their decimal equivalents. +.TP +\fB-I\fR +Force source translation to terminfo format. +.TP +\fB-L\fR +Force source translation to terminfo format +using the long C variable names listed in <\fBterm.h\fR> +.TP +\fB-N\fR +Disable smart defaults. +Normally, when translating from termcap to terminfo, the compiler makes +a number of assumptions about the defaults of string capabilities +\fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR, +\fBcursor_down\fR, \fBscroll_forward\fR, \fBtab\fR, \fBnewline\fR, +\fBkey_backspace\fR, \fBkey_left\fR, and \fBkey_down\fR, then attempts +to use obsolete termcap capabilities to deduce correct values. It also +normally suppresses output of obsolete termcap capabilities such as \fBbs\fR. +This option forces a more literal translation that also preserves the +obsolete capabilities. +.TP +\fB-o\fR\fIdir\fR +Write compiled entries to given directory. Overrides the TERMINFO environment +variable. +.TP +\fB-R\fR\fIsubset\fR +Restrict output to a given subset. This option is for use with archaic +versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support +the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x +that have their own extensions incompatible with SVr4/XSI. Available subsets +are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; see \fBterminfo\fR(\*n) for details. +.TP +\fB-r\fR +Force entry resolution (so there are no remaining tc capabilities) even +when doing translation to termcap format. This may be needed if you are +preparing a termcap file for a termcap library (such as GNU termcap through +version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple +tc capabilities per entry. +.TP +\fB-s\fR +Summarize the compile by showing the directory into which entries +are written, and the number of entries which are compiled. +.TP +\fB-T\fR +eliminates size-restrictions on the generated text. +This is mainly useful for testing and analysis, since the compiled +descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). +.TP +\fB-t\fR +tells \fBtic\fP to discard commented-out capabilities. +Normally when translating from terminfo to termcap, +untranslatable capabilities are commented-out. +.TP 5 +\fB-U\fR +tells \fBtic\fP to not post-process the data after parsing the source file. +Normally, it infers data which is commonly missing in older terminfo data, +or in termcaps. +.TP +\fB-V\fR +reports the version of ncurses which was used in this program, and exits. +.TP +\fB-v\fR\fIn\fR +specifies that (verbose) output be written to standard error trace +information showing \fBtic\fR's progress. +The optional parameter \fIn\fR is a number from 1 to 10, inclusive, +indicating the desired level of detail of information. +If \fIn\fR is omitted, the default level is 1. +If \fIn\fR is specified and greater than 1, the level of +detail is increased. +.TP +\fB-w\fR\fIn\fR +specifies the width of the output. +The parameter is optional. +If it is omitted, it defaults to 60. +.TP +\fB-x\fR +Treat unknown capabilities as user-defined. +That is, if you supply a capability name which \fBtic\fP does not recognize, +it will infer its type (boolean, number or string) from the syntax and +make an extended table entry for that. +User-defined capability strings +whose name begins with ``k'' are treated as function keys. +.TP +\fIfile\fR +contains one or more \fBterminfo\fR terminal descriptions in source +format [see \fBterminfo\fR(\*n)]. Each description in the file +describes the capabilities of a particular terminal. +.PP +The debug flag levels are as follows: +.TP +1 +Names of files created and linked +.TP +2 +Information related to the ``use'' facility +.TP +3 +Statistics from the hashing algorithm +.TP +5 +String-table memory allocations +.TP +7 +Entries into the string-table +.TP +8 +List of tokens encountered by scanner +.TP +9 +All values computed in construction of the hash table +.LP +If the debug level \fIn\fR is not given, it is taken to be one. +.PP +All but one of the capabilities recognized by \fBtic\fR are documented +in \fBterminfo\fR(\*n). The exception is the \fBuse\fR capability. +.PP +When a \fBuse\fR=\fIentry\fR-\fIname\fR field is discovered in a +terminal entry currently being compiled, \fBtic\fR reads in the binary +from \fB\*d\fR to complete the entry. (Entries created from +\fIfile\fR will be used first. If the environment variable +\fBTERMINFO\fR is set, that directory is searched instead of +\fB\*d\fR.) \fBtic\fR duplicates the capabilities in +\fIentry\fR-\fIname\fR for the current entry, with the exception of +those capabilities that explicitly are defined in the current entry. +.PP +When an entry, e.g., \fBentry_name_1\fR, contains a +\fBuse=\fR\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled +capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in +\fBentry_name_1\fR before \fBuse=\fR for these capabilities to be +canceled in \fBentry_name_1\fR. +.PP +If the environment variable \fBTERMINFO\fR is set, the compiled +results are placed there instead of \fB\*d\fR. +.PP +Total compiled entries cannot exceed 4096 bytes. The name field cannot +exceed 512 bytes. Terminal names exceeding the maximum alias length +(32 characters on systems with long filenames, 14 characters otherwise) +will be truncated to the maximum alias length and a warning message will be printed. +.SH COMPATIBILITY +There is some evidence that historic \fBtic\fR implementations treated +description fields with no whitespace in them as additional aliases or +short names. This \fBtic\fR does not do that, but it does warn when +description fields may be treated that way and check them for dangerous +characters. +.SH EXTENSIONS +Unlike the stock SVr4 \fBtic\fR command, this implementation can actually +compile termcap sources. In fact, entries in terminfo and termcap syntax can +be mixed in a single source file. See \fBterminfo\fR(\*n) for the list of +termcap names taken to be equivalent to terminfo names. +.PP +The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR +capabilities. +This implementation of \fBtic\fR will find \fBuse\fR targets anywhere +in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if +\fBTERMINFO\fR is defined), or in the user's \fI$HOME/.terminfo\fR directory +(if it exists), or (finally) anywhere in the system's file tree of +compiled entries. +.PP +The error messages from this \fBtic\fR have the same format as GNU C +error messages, and can be parsed by GNU Emacs's compile facility. +.PP +The +\fB-C\fR, +\fB-G\fR, +\fB-I\fR, +\fB-N\fR, +\fB-R\fR, +\fB-T\fR, +\fB-V\fR, +\fB-a\fR, +\fB-e\fR, +\fB-f\fR, +\fB-g\fR, +\fB-o\fR, +\fB-r\fR, +\fB-s\fR, +\fB-t\fR and +\fB-x\fR +options +are not supported under SVr4. +The SVr4 \fB-c\fR mode does not report bad use links. +.PP +System V does not compile entries to or read entries from your +\fI$HOME/.terminfo\fR directory unless TERMINFO is explicitly set to it. +.SH FILES +.TP 5 +\fB\*d/?/*\fR +Compiled terminal description database. +.SH SEE ALSO +\fB@INFOCMP@\fR(1M), +\fB@CAPTOINFO@\fR(1M), +\fB@INFOTOCAP@\fR(1M), +\fB@TOE@\fR(1M), +\fBcurses\fR(3X), +\fBterminfo\fR(\*n). +.PP +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/toe.1m b/man/toe.1m new file mode 100644 index 000000000000..15303541dddc --- /dev/null +++ b/man/toe.1m @@ -0,0 +1,107 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2006,2008 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: toe.1m,v 1.21 2008/01/05 20:57:16 tom Exp $ +.TH @TOE@ 1M "" +.ds n 5 +.ds d @TERMINFO@ +.SH NAME +\fBtoe\fR - table of (terminfo) entries +.SH SYNOPSIS +\fBtoe\fR [\fB-v\fR[\fIn\fR]] [\fB-ahuUV\fR] \fIfile...\fR +.br +.SH DESCRIPTION +.PP +With no options, +\fBtoe\fR lists all available terminal types by primary name +with descriptions. +File arguments specify the directories to be scanned; if no +such arguments are given, +your default terminfo directory is scanned. +If you also specify the \fB-h\fR option, +a directory header will be issued as each +directory is entered. +.PP +There are other options intended for use by terminfo file maintainers: +.TP +\fB-a\fR +report on all of the terminal databases which ncurses would search, +rather than only the first one that it finds. +.TP +\fB-u\fR \fIfile\fR +says to write a report to the standard output, +listing dependencies in the given terminfo/termcap source file. +The report condenses the `use' relation: +each line consists of the primary name of a terminal that +has use capabilities, +followed by a colon, +followed by the +whitespace-separated primary names of all terminals which occur in those use +capabilities, +followed by a newline +.TP +\fB-U\fR \fIfile\fR +says to write a report to the standard output, +listing reverse dependencies in the given terminfo/termcap source file. +The report reverses the `use' relation: +each line consists of the primary name of a +terminal that occurs in use capabilities, +followed by a colon, +followed by the +whitespace-separated primary names of all terminals which depend on it, +followed by a newline. +.TP +\fB-v\fR\fIn\fR +specifies that (verbose) output be written to standard error, +showing \fBtoe\fR's progress. +The optional parameter \fIn\fR is a number from 1 to 10, +interpreted as for \fB@TIC@\fR(1M). +.TP +\fB-V\fR +reports the version of ncurses which was used in this program, +and exits. +.SH FILES +.TP 5 +\fB\*d/?/*\fR +Compiled terminal description database. +.SH SEE ALSO +\fB@TIC@\fR(1M), +\fB@INFOCMP@\fR(1M), +\fB@CAPTOINFO@\fR(1M), +\fB@INFOTOCAP@\fR(1M), +\fBcurses\fR(3X), +\fBterminfo\fR(\*n). +.PP +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/tput.1 b/man/tput.1 new file mode 100644 index 000000000000..bada0b1595ed --- /dev/null +++ b/man/tput.1 @@ -0,0 +1,325 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: tput.1,v 1.27 2006/12/24 18:11:31 tom Exp $ +.TH @TPUT@ 1 "" +.ds d @TERMINFO@ +.ds n 1 +.SH NAME +\fB@TPUT@\fR, \fBreset\fR - initialize a terminal or query terminfo database +.SH SYNOPSIS +\fB@TPUT@\fR [\fB-T\fR\fItype\fR] \fIcapname\fR [\fIparms\fR ... ] +.br +\fB@TPUT@\fR [\fB-T\fR\fItype\fR] \fBinit\fR +.br +\fB@TPUT@\fR [\fB-T\fR\fItype\fR] \fBreset\fR +.br +\fB@TPUT@\fR [\fB-T\fR\fItype\fR] \fBlongname\fR +.br +\fB@TPUT@ -S\fR \fB<<\fR +.br +\fB@TPUT@ -V\fR +.br +.SH DESCRIPTION +The \fB@TPUT@\fR utility uses the \fBterminfo\fR database to make the +values of terminal-dependent capabilities and information available to +the shell (see \fBsh\fR(1)), to initialize or reset the terminal, or +return the long name of the requested terminal type. +The result depends upon the capability's type: +.RS +.TP 5 +string +\fB@TPUT@\fR writes the string to the standard output. +No trailing newline is supplied. +.TP +integer +\fB@TPUT@\fR writes the decimal value to the standard output, +with a trailing newline. +.TP +boolean +\fB@TPUT@\fR simply sets the exit code +(\fB0\fR for TRUE if the terminal has the capability, +\fB1\fR for FALSE if it does not), +and writes nothing to the standard output. +.RE +.PP +Before using a value returned on the standard output, +the application should test the exit code +(e.g., \fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR. +(See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.) +For a complete list of capabilities +and the \fIcapname\fR associated with each, see \fBterminfo\fR(5). +.TP +\fB-T\fR\fItype\fR +indicates the \fItype\fR of terminal. Normally this option is +unnecessary, because the default is taken from the environment +variable \fBTERM\fR. If \fB-T\fR is specified, then the shell +variables \fBLINES\fR and \fBCOLUMNS\fR will be ignored,and the +operating system will not be queried for the actual screen size. +.TP +\fIcapname\fR +indicates the capability from the \fBterminfo\fR database. When +\fBtermcap\fR support is compiled in, the \fBtermcap\fR name for +the capability is also accepted. +.TP +\fIparms\fR +If the capability is a string that takes parameters, the arguments +\fIparms\fR will be instantiated into the string. +.IP +Most parameters are numbers. +Only a few terminfo capabilities require string parameters; +\fB@TPUT@\fR uses a table to decide which to pass as strings. +Normally \fB@TPUT@\fR uses \fBtparm\fR (3X) to perform the substitution. +If no parameters are given for the capability, +\fB@TPUT@\fR writes the string without performing the substitution. +.TP +\fB-S\fR +allows more than one capability per invocation of \fB@TPUT@\fR. The +capabilities must be passed to \fB@TPUT@\fR from the standard input +instead of from the command line (see example). +Only one \fIcapname\fR is allowed per line. +The \fB-S\fR option changes the +meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the +EXIT CODES section). +.IP +Again, \fB@TPUT@\fR uses a table and the presence of parameters in its input +to decide whether to use \fBtparm\fR (3X), +and how to interpret the parameters. +.TP +\fB-V\fR +reports the version of ncurses which was used in this program, and exits. +.TP +\fBinit\fR +If the \fBterminfo\fR database is present and an entry for the user's +terminal exists (see \fB-T\fR\fItype\fR, above), the following will +occur: +.RS +.TP +(1) +if present, the terminal's initialization strings will be +output as detailed in the \fBterminfo\fR(5) section on +.IR "Tabs and Initialization" , +.TP +(2) +any delays (e.g., newline) specified in the entry will +be set in the tty driver, +.TP +(3) +tabs expansion will be turned on or off according to +the specification in the entry, and +.TP +(4) +if tabs are not expanded, +standard tabs will be set (every 8 spaces). +.RE +.IP +If an entry does not +contain the information needed for any of the four above activities, +that activity will silently be skipped. +.TP +\fBreset\fR +Instead of putting out initialization strings, the terminal's +reset strings will be output if present (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR). +If the reset strings are not present, but initialization +strings are, the initialization strings will be output. +Otherwise, \fBreset\fR acts identically to \fBinit\fR. +.TP +\fBlongname\fR +If the \fBterminfo\fR database is present and an entry for the +user's terminal exists (see \fB-T\fR\fItype\fR above), then the long name +of the terminal will be put out. The long name is the last +name in the first line of the terminal's description in the +\fBterminfo\fR database [see \fBterm\fR(5)]. +.PP +If \fB@TPUT@\fR is invoked by a link named \fBreset\fR, this has the +same effect as \fB@TPUT@ reset\fR. +See \fBtset\fR for comparison, which has similar behavior. +.SH EXAMPLES +.TP 5 +\fB@TPUT@ init\fR +Initialize the terminal according to the type of +terminal in the environmental variable \fBTERM\fR. This +command should be included in everyone's .profile after +the environmental variable \fBTERM\fR has been exported, as +illustrated on the \fBprofile\fR(5) manual page. +.TP 5 +\fB@TPUT@ -T5620 reset\fR +Reset an AT&T 5620 terminal, overriding the type of +terminal in the environmental variable \fBTERM\fR. +.TP 5 +\fB@TPUT@ cup 0 0\fR +Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR +(the upper left corner of the screen, usually known as the "home" +cursor position). +.TP 5 +\fB@TPUT@ clear\fR +Echo the clear-screen sequence for the current terminal. +.TP 5 +\fB@TPUT@ cols\fR +Print the number of columns for the current terminal. +.TP 5 +\fB@TPUT@ -T450 cols\fR +Print the number of columns for the 450 terminal. +.TP 5 +\fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR +Set the shell variables \fBbold\fR, to begin stand-out mode +sequence, and \fBoffbold\fR, to end standout mode sequence, +for the current terminal. This might be followed by a +prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR +.TP 5 +\fB@TPUT@ hc\fR +Set exit code to indicate if the current terminal is a hard copy terminal. +.TP 5 +\fB@TPUT@ cup 23 4\fR +Send the sequence to move the cursor to row 23, column 4. +.TP 5 +\fB@TPUT@ cup\fR +Send the terminfo string for cursor-movement, with no parameters substituted. +.TP 5 +\fB@TPUT@ longname\fR +Print the long name from the \fBterminfo\fR database for the +type of terminal specified in the environmental +variable \fBTERM\fR. +.PP +.RS 5 +\fB@TPUT@ -S <<!\fR +.br +\fB> clear\fR +.br +\fB> cup 10 10\fR +.br +\fB> bold\fR +.br +\fB> !\fR +.RE +.TP 5 +\& +This example shows \fB@TPUT@\fR processing several capabilities in one invocation. +It clears the screen, +moves the cursor to position 10, 10 +and turns on bold (extra bright) mode. +The list is terminated by an exclamation mark (\fB!\fR) on a line by itself. +.SH FILES +.TP +\fB\*d\fR +compiled terminal description database +.TP +\fB@DATADIR@/tabset/*\fR +tab settings for some terminals, in a format +appropriate to be output to the terminal (escape +sequences that set margins and tabs); for more +information, see the "Tabs and Initialization" +section of \fBterminfo\fR(5) +.SH EXIT CODES +If the \fB-S\fR option is used, +\fB@TPUT@\fR checks for errors from each line, +and if any errors are found, will set the exit code to 4 plus the +number of lines with errors. +If no errors are found, the exit code is \fB0\fR. +No indication of which line failed can be given so +exit code \fB1\fR will never appear. Exit codes \fB2\fR, \fB3\fR, and +\fB4\fR retain their usual interpretation. +If the \fB-S\fR option is not used, +the exit code depends on the type of \fIcapname\fR: +.RS 5 +.TP +.I boolean +a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE. +.TP +.I string +a value of \fB0\fR is set if the +\fIcapname\fR is defined for this terminal \fItype\fR (the value of +\fIcapname\fR is returned on standard output); +a value of \fB1\fR is set if \fIcapname\fR +is not defined for this terminal \fItype\fR +(nothing is written to standard output). +.TP +.I integer +a value of \fB0\fR is always set, +whether or not \fIcapname\fR is defined for this terminal \fItype\fR. +To determine if \fIcapname\fR is defined for this terminal \fItype\fR, +the user must test the value written to standard output. +A value of \fB-1\fR +means that \fIcapname\fR is not defined for this terminal \fItype\fR. +.TP +.I other +\fBreset\fR or \fBinit\fR may fail to find their respective files. +In that case, the exit code is set to 4 + \fBerrno\fR. +.RE +.PP +Any other exit code indicates an error; see the DIAGNOSTICS section. +.SH DIAGNOSTICS +\fBtput\fR prints the following error messages and sets the corresponding exit +codes. +.PP +.ne 15 +.TS +l l. +exit code error message += +\fB0\fR T{ +(\fIcapname\fR is a numeric variable that is not specified in the +\fBterminfo\fR(5) database for this terminal type, e.g. +\fB@TPUT@ -T450 lines\fR and \fB@TPUT@ -T2621 xmc\fR) +T} +\fB1\fR no error message is printed, see the \fBEXIT CODES\fR section. +\fB2\fR usage error +\fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database +\fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR +\fB>4\fR error occurred in -S += +.TE +.SH PORTABILITY +.PP +The \fBlongname\fR and \fB-S\fR options, and the parameter-substitution +features used in the \fBcup\fR example, are not supported in BSD curses or in +AT&T/USL curses before SVr4. +.PP +X/Open documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP. +In this implementation, \fBclear\fP is part of the \fIcapname\fR support. +Other implementations of \fBtput\fP on +SVr4-based systems such as Solaris, IRIX64 and HPUX +as well as others such as AIX and Tru64 +provide support for \fIcapname\fR operands. +A few platforms such as FreeBSD and NetBSD recognize termcap names rather +than terminfo capability names in their respective \fBtput\fP commands. +.SH SEE ALSO +\fB@CLEAR@\fR(1), +\fBstty\fR(1), +\fBtabs\fR(\*n), +\fBterminfo\fR(5). +.PP +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/tset.1 b/man/tset.1 new file mode 100644 index 000000000000..e023064c08b7 --- /dev/null +++ b/man/tset.1 @@ -0,0 +1,288 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: tset.1,v 1.19 2006/12/24 15:00:30 tom Exp $ +.TH tset 1 "" +.SH NAME +\fBtset\fR, \fBreset\fR - terminal initialization +.SH SYNOPSIS +\fBtset\fR [\fB-IQVcqrsw\fR] [\fB-\fR] [\fB-e\fR \fIch\fR] [\fB-i\fR \fIch\fR] [\fB-k\fR \fIch\fR] [\fB-m\fR \fImapping\fR] [\fIterminal\fR] +.br +\fBreset\fR [\fB-IQVcqrsw\fR] [\fB-\fR] [\fB-e\fR \fIch\fR] [\fB-i\fR \fIch\fR] [\fB-k\fR \fIch\fR] [\fB-m\fR \fImapping\fR] [\fIterminal\fR] +.SH DESCRIPTION +\&\fBTset\fR initializes terminals. +\fBTset\fR first determines the type of terminal that you are using. +This determination is done as follows, using the first terminal type found. +.PP +1. The \fBterminal\fR argument specified on the command line. +.PP +2. The value of the \fBTERM\fR environmental variable. +.PP +3. (BSD systems only.) The terminal type associated with the standard +error output device in the \fI/etc/ttys\fR file. (On Linux and +System-V-like UNIXes, \fIgetty\fR does this job by setting +\fBTERM\fR according to the type passed to it by \fI/etc/inittab\fR.) +.PP +4. The default terminal type, ``unknown''. +.PP +If the terminal type was not specified on the command-line, the \fB-m\fR +option mappings are then applied (see the section +.B TERMINAL TYPE MAPPING +for more information). +Then, if the terminal type begins with a question mark (``?''), the +user is prompted for confirmation of the terminal type. An empty +response confirms the type, or, another type can be entered to specify +a new type. Once the terminal type has been determined, the terminfo +entry for the terminal is retrieved. If no terminfo entry is found +for the type, the user is prompted for another terminal type. +.PP +Once the terminfo entry is retrieved, the window size, backspace, interrupt +and line kill characters (among many other things) are set and the terminal +and tab initialization strings are sent to the standard error output. +Finally, if the erase, interrupt and line kill characters have changed, +or are not set to their default values, their values are displayed to the +standard error output. +Use the \fB-c\fP or \fB-w\fP option to select only the window sizing +versus the other initialization. +If neither option is given, both are assumed. +.PP +When invoked as \fBreset\fR, \fBtset\fR sets cooked and echo modes, +turns off cbreak and raw modes, turns on newline translation and +resets any unset special characters to their default values before +doing the terminal initialization described above. This is useful +after a program dies leaving a terminal in an abnormal state. Note, +you may have to type +.sp + \fB<LF>reset<LF>\fR +.sp +(the line-feed character is normally control-J) to get the terminal +to work, as carriage-return may no longer work in the abnormal state. +Also, the terminal will often not echo the command. +.PP +The options are as follows: +.TP 5 +.B -c +Set control characters and modes. +.B -e +Set the erase character to \fIch\fR. +.TP +.B -I +Do not send the terminal or tab initialization strings to the terminal. +.TP +.B -i +Set the interrupt character to \fIch\fR. +.TP +.B -k +Set the line kill character to \fIch\fR. +.TP +.B -m +Specify a mapping from a port type to a terminal. +See the section +.B TERMINAL TYPE MAPPING +for more information. +.TP +.B -Q +Do not display any values for the erase, interrupt and line kill characters. +Normally \fBtset\fR displays the values for control characters which +differ from the system's default values. +.TP +.B -q +The terminal type is displayed to the standard output, and the terminal is +not initialized in any way. The option `-' by itself is equivalent but +archaic. +.TP +.B -r +Print the terminal type to the standard error output. +.TP +.B -s +Print the sequence of shell commands to initialize the environment variable +\fBTERM\fR to the standard output. +See the section +.B SETTING THE ENVIRONMENT +for details. +.TP +.B -V +reports the version of ncurses which was used in this program, and exits. +.TP +.B -w +Resize the window to match the size deduced via \fBsetupterm\fP. +Normally this has no effect, +unless \fBsetupterm\fP is not able to detect the window size. +.PP +The arguments for the \fB-e\fR, \fB-i\fR, and \fB-k\fR +options may either be entered as actual characters or by using the `hat' +notation, i.e. control-h may be specified as ``^H'' or ``^h''. +. +.SH SETTING THE ENVIRONMENT +It is often desirable to enter the terminal type and information about +the terminal's capabilities into the shell's environment. +This is done using the \fB-s\fR option. +.PP +When the \fB-s\fR option is specified, the commands to enter the information +into the shell's environment are written to the standard output. If +the \fBSHELL\fR environmental variable ends in ``csh'', the commands +are for \fBcsh\fR, otherwise, they are for \fBsh\fR. +Note, the \fBcsh\fR commands set and unset the shell variable +\fBnoglob\fR, leaving it unset. The following line in the \fB.login\fR +or \fB.profile\fR files will initialize the environment correctly: +.sp + eval \`tset -s options ... \` +. +.SH TERMINAL TYPE MAPPING +When the terminal is not hardwired into the system (or the current +system information is incorrect) the terminal type derived from the +\fI/etc/ttys\fR file or the \fBTERM\fR environmental variable is often +something generic like \fBnetwork\fR, \fBdialup\fR, or \fBunknown\fR. +When \fBtset\fR is used in a startup script it is often desirable to +provide information about the type of terminal used on such ports. +.PP +The purpose of the \fB-m\fR option is to map +from some set of conditions to a terminal type, that is, to +tell \fBtset\fR +``If I'm on this port at a particular speed, guess that I'm on that +kind of terminal''. +.PP +The argument to the \fB-m\fR option consists of an optional port type, an +optional operator, an optional baud rate specification, an optional +colon (``:'') character and a terminal type. The port type is a +string (delimited by either the operator or the colon character). The +operator may be any combination of ``>'', ``<'', ``@'', and ``!''; ``>'' +means greater than, ``<'' means less than, ``@'' means equal to +and ``!'' inverts the sense of the test. +The baud rate is specified as a number and is compared with the speed +of the standard error output (which should be the control terminal). +The terminal type is a string. +.PP +If the terminal type is not specified on the command line, the \fB-m\fR +mappings are applied to the terminal type. If the port type and baud +rate match the mapping, the terminal type specified in the mapping +replaces the current type. If more than one mapping is specified, the +first applicable mapping is used. +.PP +For example, consider the following mapping: \fBdialup>9600:vt100\fR. +The port type is dialup , the operator is >, the baud rate +specification is 9600, and the terminal type is vt100. The result of +this mapping is to specify that if the terminal type is \fBdialup\fR, +and the baud rate is greater than 9600 baud, a terminal type of +\fBvt100\fR will be used. +.PP +If no baud rate is specified, the terminal type will match any baud rate. +If no port type is specified, the terminal type will match any port type. +For example, \fB-m dialup:vt100 -m :?xterm\fR +will cause any dialup port, regardless of baud rate, to match the terminal +type vt100, and any non-dialup port type to match the terminal type ?xterm. +Note, because of the leading question mark, the user will be +queried on a default port as to whether they are actually using an xterm +terminal. +.PP +No whitespace characters are permitted in the \fB-m\fR option argument. +Also, to avoid problems with meta-characters, it is suggested that the +entire \fB-m\fR option argument be placed within single quote characters, +and that \fBcsh\fR users insert a backslash character (``\e'') before +any exclamation marks (``!''). +.SH HISTORY +The \fBtset\fR command appeared in BSD 3.0. The \fBncurses\fR implementation +was lightly adapted from the 4.4BSD sources for a terminfo environment by Eric +S. Raymond <esr@snark.thyrsus.com>. +.SH COMPATIBILITY +The \fBtset\fR utility has been provided for backward-compatibility with BSD +environments (under most modern UNIXes, \fB/etc/inittab\fR and \fIgetty\fR(1) +can set \fBTERM\fR appropriately for each dial-up line; this obviates what was +\fBtset\fR's most important use). This implementation behaves like 4.4BSD +tset, with a few exceptions specified here. +.PP +The \fB-S\fR option of BSD tset no longer works; it prints an error message to stderr +and dies. The \fB-s\fR option only sets \fBTERM\fR, not \fBTERMCAP\fP. Both these +changes are because the \fBTERMCAP\fR variable is no longer supported under +terminfo-based \fBncurses\fR, which makes \fBtset -S\fR useless (we made it die +noisily rather than silently induce lossage). +.PP +There was an undocumented 4.4BSD feature that invoking tset via a link named +`TSET` (or via any other name beginning with an upper-case letter) set the +terminal to use upper-case only. This feature has been omitted. +.PP +The \fB-A\fR, \fB-E\fR, \fB-h\fR, \fB-u\fR and \fB-v\fR +options were deleted from the \fBtset\fR +utility in 4.4BSD. +None of them were documented in 4.3BSD and all are +of limited utility at best. +The \fB-a\fR, \fB-d\fR, and \fB-p\fR options are similarly +not documented or useful, but were retained as they appear to be in +widespread use. It is strongly recommended that any usage of these +three options be changed to use the \fB-m\fR option instead. The +-n option remains, but has no effect. The \fB-adnp\fR options are therefore +omitted from the usage summary above. +.PP +It is still permissible to specify the \fB-e\fR, \fB-i\fR, and \fB-k\fR options without +arguments, although it is strongly recommended that such usage be fixed to +explicitly specify the character. +.PP +As of 4.4BSD, executing \fBtset\fR as \fBreset\fR no longer implies the \fB-Q\fR +option. Also, the interaction between the - option and the \fIterminal\fR +argument in some historic implementations of \fBtset\fR has been removed. +.SH ENVIRONMENT +The \fBtset\fR command uses these environment variables: +.TP 5 +SHELL +tells \fBtset\fP whether to initialize \fBTERM\fP using \fBsh\fP or +\fBcsh\fP syntax. +.TP 5 +TERM +Denotes your terminal type. +Each terminal type is distinct, though many are similar. +.TP 5 +TERMCAP +may denote the location of a termcap database. +If it is not an absolute pathname, e.g., begins with a `/', +\fBtset\fP removes the variable from the environment before looking +for the terminal description. +.SH FILES +.TP 5 +/etc/ttys +system port name to terminal type mapping database (BSD versions only). +.TP +@TERMINFO@ +terminal capability database +.SH SEE ALSO +csh(1), +sh(1), +stty(1), +curs_terminfo(3X), +tty(4), +terminfo(5), +ttys(5), +environ(7) +.PP +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/man/wresize.3x b/man/wresize.3x new file mode 100644 index 000000000000..4d05d3ee7069 --- /dev/null +++ b/man/wresize.3x @@ -0,0 +1,64 @@ +.\"*************************************************************************** +.\" Copyright (c) 1998-2003,2006 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" Author: Thomas E. Dickey 1996 +.\" +.\" $Id: wresize.3x,v 1.9 2006/02/25 21:47:06 tom Exp $ +.TH wresize 3X "" +.SH NAME +\fBwresize\fR - resize a curses window +.SH SYNOPSIS +\fB#include <curses.h>\fR +.sp +\fBint wresize(WINDOW *win, int lines, int columns);\fR +.SH DESCRIPTION +The \fBwresize\fR function reallocates storage for an \fBncurses\fR +window to adjust its dimensions to the specified values. +If either dimension is larger than the current values, the +window's data is filled with blanks that have the current background rendition +(as set by \fBwbkgndset\fR) merged into them. +.SH RETURN VALUE +The function returns the integer \fBERR\fR upon failure and \fBOK\fR on success. +It will fail if either of the dimensions less than or equal to zero, +or if an error occurs while (re)allocating memory for the window. +.SH NOTES +The only restriction placed on the dimensions is that they be greater than zero. +The dimensions are not compared to \fBcurses\fR screen dimensions to +simplify the logic of \fBresizeterm\fR. +The caller must ensure that the window's dimensions fit within the +actual screen dimensions. +.SH SEE ALSO +\fBresizeterm\fR(3X). +.SH AUTHOR +Thomas Dickey (from an equivalent function written in 1988 for BSD curses). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: |