ncurses 4.1
[ncurses.git] / Ada95 / html / curs_util.3x.html
1 <HTML>
2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
3 <PRE>
4        <STRONG>unctrl</STRONG>,   <STRONG>keyname</STRONG>,   <STRONG>filter</STRONG>,   <STRONG>use_env</STRONG>,   <STRONG>putwin</STRONG>,  <STRONG>getwin</STRONG>,
5        <STRONG>delay_output</STRONG>, <STRONG>flushinp</STRONG> - miscellaneous <STRONG>curses</STRONG> utility rou-
6        tines
7
8
9 </PRE>
10 <H2>SYNOPSIS</H2><PRE>
11        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
12
13        <STRONG>char</STRONG> <STRONG>*unctrl(chtype</STRONG> <STRONG>c);</STRONG>
14        <STRONG>char</STRONG> <STRONG>*keyname(int</STRONG> <STRONG>c);</STRONG>
15        <STRONG>void</STRONG> <STRONG>filter(void);</STRONG>
16        <STRONG>void</STRONG> <STRONG>use_env(char</STRONG> <STRONG>bool);</STRONG>
17        <STRONG>int</STRONG> <STRONG>putwin(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>FILE</STRONG> <STRONG>*filep);</STRONG>
18        <STRONG>WINDOW</STRONG> <STRONG>*getwin(FILE</STRONG> <STRONG>*filep);</STRONG>
19        <STRONG>int</STRONG> <STRONG>delay_output(int</STRONG> <STRONG>ms);</STRONG>
20        <STRONG>int</STRONG> <STRONG>flushinp(void);</STRONG>
21
22
23 </PRE>
24 <H2>DESCRIPTION</H2><PRE>
25        The  <STRONG>unctrl</STRONG> macro expands to a character string which is a
26        printable representation  of  the  character  <EM>c</EM>.   Control
27        characters  are  displayed  in  the <STRONG>^</STRONG><EM>X</EM> notation.  Printing
28        characters are displayed as is.
29
30        The <STRONG>keyname</STRONG> routine returns a character string correspond-
31        ing to the key <EM>c</EM>.
32
33        The <STRONG>filter</STRONG> routine, if used, must be called before <STRONG>initscr</STRONG>
34        or <STRONG>newterm</STRONG> are called.  The effect is that,  during  those
35        calls,  <STRONG>LINES</STRONG>  is  set  to 1; the capabilities <STRONG>clear</STRONG>, <STRONG>cup</STRONG>,
36        <STRONG>cud</STRONG>, <STRONG>cud1</STRONG>, <STRONG>cuu1</STRONG>, <STRONG>cuu</STRONG>,  <STRONG>vpa</STRONG>  are  disabled;  and  the  <STRONG>home</STRONG>
37        string is set to the value of <STRONG>cr</STRONG>.
38
39        The  <STRONG>use_env</STRONG> routine, if used, is called before <STRONG>initscr</STRONG> or
40        <STRONG>newterm</STRONG> are called.  When called with <STRONG>FALSE</STRONG>  as  an  argu-
41        ment,  the  values  of  <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the
42        <EM>terminfo</EM> database will be used, even if environment  vari-
43        ables  <STRONG>LINES</STRONG>  and <STRONG>COLUMNS</STRONG> (used by default) are set, or if
44        <STRONG>curses</STRONG> is running in  a  window  (in  which  case  default
45        behavior  would  be  to  use  the window size if <STRONG>LINES</STRONG> and
46        <STRONG>COLUMNS</STRONG> are not set).
47
48        The <STRONG>putwin</STRONG> routine writes all data associated with  window
49        <EM>win</EM> into the file to which <EM>filep</EM> points.  This information
50        can be later retrieved using the <STRONG>getwin</STRONG> function.
51
52        The <STRONG>getwin</STRONG> routine reads window related data stored in the
53        file  by <STRONG>putwin</STRONG>.  The routine then creates and initializes
54        a new window using that data.  It returns a pointer to the
55        new window.
56
57        The  <STRONG>delay_output</STRONG>  routine inserts an <EM>ms</EM> millisecond pause
58        in output.  This routine should not  be  used  extensively
59        because  padding  characters  are  used  rather than a CPU
60        been  typed  by  the user and has not yet been read by the
61        program.
62
63
64 </PRE>
65 <H2>RETURN VALUE</H2><PRE>
66        Except for  <STRONG>flushinp</STRONG>,  routines  that  return  an  integer
67        return  <STRONG>ERR</STRONG>  upon  failure and <STRONG>OK</STRONG> (SVr4 specifies only "an
68        integer value other than <STRONG>ERR</STRONG>") upon successful completion.
69
70        <STRONG>flushinp</STRONG> always returns <STRONG>OK</STRONG>.
71
72        Routines that return pointers return <STRONG>NULL</STRONG> on error.
73
74
75 </PRE>
76 <H2>PORTABILITY</H2><PRE>
77        The  XSI  Curses  standard,  Issue 4 describes these func-
78        tions.
79
80        The SVr4 documentation describes the action of <STRONG>filter</STRONG> only
81        in  the  vaguest  terms.   The description here is adapted
82        from the XSI Curses standard (which erroneously  fails  to
83        describe the disabling of <STRONG>cuu</STRONG>).
84
85
86 </PRE>
87 <H2>NOTES</H2><PRE>
88        Note  that  <STRONG>unctrl</STRONG>  is  a macro, which is defined in &lt;<STRONG>unc-</STRONG>
89        <STRONG>trl.h</STRONG>&gt;.
90
91
92 </PRE>
93 <H2>SEE ALSO</H2><PRE>
94        <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3X)</A></STRONG>, <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3X)</A></STRONG>.
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120 </PRE>
121 </BODY>
122 </HTML>