man/curs_kernel.3x

   1 .TH curs_kernel 3X ""
   2 .SH NAME
   3 \fBdef_prog_mode\fR, \fBdef_shell_mode\fR,
   4 \fBreset_prog_mode\fR, \fBreset_shell_mode\fR, \fBresetty\fR,
   5 \fBsavetty\fR, \fBgetsyx\fR, \fBsetsyx\fR, \fBripoffline\fR,
   6 \fBcurs_set\fR, \fBnapms\fR - low-level \fBcurses\fR routines
   7 .SH SYNOPSIS
   8 \fB#include <curses.h>\fR
   9
  10 \fBint def_prog_mode(void);\fR
  11 .br
  12 \fBint def_shell_mode(void);\fR
  13 .br
  14 \fBint reset_prog_mode(void);\fR
  15 .br
  16 \fBint reset_shell_mode(void);\fR
  17 .br
  18 \fBint resetty(void);\fR
  19 .br
  20 \fBint savetty(void);\fR
  21 .br
  22 \fBvoid getsyx(int y, int x);\fR
  23 .br
  24 \fBvoid setsyx(int y, int x);\fR
  25 .br
  26 \fBint ripoffline(int line, int (*init)(WINDOW *, int));\fR
  27 .br
  28 \fBint curs_set(int visibility);\fR
  29 .br
  30 \fBint napms(int ms);\fR
  31 .br
  32 .SH DESCRIPTION
  33 The following routines give low-level access to various \fBcurses\fR
  34 capabilities.  Theses routines typically are used inside library
  35 routines.
  36
  37 The \fBdef_prog_mode\fR and \fBdef_shell_mode\fR routines save the
  38 current terminal modes as the "program" (in \fBcurses\fR) or "shell"
  39 (not in \fBcurses\fR) state for use by the \fBreset_prog_mode\fR and
  40 \fBreset_shell_mode\fR routines.  This is done automatically by
  41 \fBinitscr\fR.  There is one such save area for each screen context
  42 allocated by \fBnewterm()\fR.
  43
  44 The \fBreset_prog_mode\fR and \fBreset_shell_mode\fR routines restore
  45 the terminal to "program" (in \fBcurses\fR) or "shell" (out of
  46 \fBcurses\fR) state.  These are done automatically by \fBendwin\fR
  47 and, after an \fBendwin\fR, by \fBdoupdate\fR, so they normally are
  48 not called.
  49
  50 The \fBresetty\fR and \fBsavetty\fR routines save and restore the
  51 state of the terminal modes.  \fBsavetty\fR saves the current state in
  52 a buffer and \fBresetty\fR restores the state to what it was at the
  53 last call to \fBsavetty\fR.
  54
  55 The \fBgetsyx\fR routine returns the current coordinates of the virtual screen
  56 cursor in \fIy\fR and \fIx\fR.  If \fBleaveok\fR is currently \fBTRUE\fR, then
  57 \fB-1\fR,\fB-1\fR is returned.  If lines have been removed from the top of the
  58 screen, using \fBripoffline\fR, \fIy\fR and \fIx\fR include these lines;
  59 therefore, \fIy\fR and \fIx\fR should be used only as arguments for
  60 \fBsetsyx\fR.
  61
  62 The \fBsetsyx\fR routine sets the virtual screen cursor to
  63 \fIy\fR, \fIx\fR.  If \fIy\fR and \fIx\fR are both \fB-1\fR, then
  64 \fBleaveok\fR is set.  The two routines \fBgetsyx\fR and \fBsetsyx\fR
  65 are designed to be used by a library routine, which manipulates
  66 \fBcurses\fR windows but does not want to change the current position
  67 of the program's cursor.  The library routine would call \fBgetsyx\fR
  68 at the beginning, do its manipulation of its own windows, do a
  69 \fBwnoutrefresh\fR on its windows, call \fBsetsyx\fR, and then call
  70 \fBdoupdate\fR.
  71
  72 The \fBripoffline\fR routine provides access to the same facility that
  73 \fBslk_init\fR [see \fBcurs_slk\fR(3X)] uses to reduce the size of the
  74 screen.  \fBripoffline\fR must be called before \fBinitscr\fR or
  75 \fBnewterm\fR is called.  If \fIline\fR is positive, a line is removed
  76 from the top of \fBstdscr\fR; if \fIline\fR is negative, a line is
  77 removed from the bottom.  When this is done inside \fBinitscr\fR, the
  78 routine \fBinit\fR (supplied by the user) is called with two
  79 arguments: a window pointer to the one-line window that has been
  80 allocated and an integer with the number of columns in the window.
  81 Inside this initialization routine, the integer variables \fBLINES\fR
  82 and \fBCOLS\fR (defined in \fB<curses.h>\fR) are not guaranteed to be
  83 accurate and \fBwrefresh\fR or \fBdoupdate\fR must not be called.  It
  84 is allowable to call \fBwnoutrefresh\fR during the initialization
  85 routine.
  86
  87 \fBripoffline\fR can be called up to five times before calling \fBinitscr\fR or
  88 \fBnewterm\fR.
  89
  90 The \fBcurs_set\fR routine sets the cursor state is set to invisible,
  91 normal, or very visible for \fBvisibility\fR equal to \fB0\fR,
  92 \fB1\fR, or \fB2\fR respectively.  If the terminal supports the
  93 \fIvisibility\fR requested, the previous \fIcursor\fR state is
  94 returned; otherwise, \fBERR\fR is returned.
  95
  96 The \fBnapms\fR routine is used to sleep for \fIms\fR milliseconds.
  97 .SH RETURN VALUE
  98 Except for \fBcurs_set\fR, these routines always return \fBOK\fR.
  99 \fBcurs_set\fR returns the previous cursor state, or \fBERR\fR if the
 100 requested \fIvisibility\fR is not supported.
 101 .SH NOTES
 102 Note that \fBgetsyx\fR is a macro, so \fB&\fR is not necessary before
 103 the variables \fIy\fR and \fIx\fR.
 104
 105 The SVr4 man pages warn that the return value of \fBcurs_set\fR "is currently
 106 incorrect".  This implementation gets it right, but it may be unwise to count
 107 on the correctness of the return value anywhere else.
 108 .SH PORTABILITY
 109 The functions \fBsetsyx\fR and \fBgetsyx\fR are not described in the XSI
 110 Curses standard, Issue 4.  All other functions are as described in XSI Curses.
 111
 112 The SVr4 documentation describes \fBsetsyx\fR and \fBgetsyx\fR as having return
 113 type int. This is misleading, as they are macros with no documented semantics
 114 for the return value.
 115 .SH SEE ALSO
 116 \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_outopts\fR(3X), \fBcurs_refresh\fR(3X),
 117 \fBcurs_scr_dump\fR(3X), \fBcurs_slk\fR(3X)
 118 .\"#
 119 .\"# The following sets edit modes for GNU EMACS
 120 .\"# Local Variables:
 121 .\"# mode:nroff
 122 .\"# fill-column:79
 123 .\"# End: