plucky (3) def_shell_mode.3ncurses.gz

Provided by: ncurses-doc_6.5+20250216-1_all bug

NAME

       def_prog_mode,  def_shell_mode,  reset_prog_mode,  reset_shell_mode,  resetty,  savetty,  getsyx, setsyx,
       curs_set, mvcur, napms, ripoffline - low-level curses routines

SYNOPSIS

       #include <curses.h>

       int def_prog_mode(void);
       int def_shell_mode(void);

       int reset_prog_mode(void);
       int reset_shell_mode(void);

       int resetty(void);
       int savetty(void);

       void getsyx(int y, int x);
       void setsyx(int y, int x);

       int curs_set(int visibility);
       int mvcur(int oldrow, int oldcol, int newrow, int newcol);
       int napms(int ms);
       int ripoffline(int line, int (*init)(WINDOW *, int));

DESCRIPTION

       The following routines give low-level access to various curses capabilities.   These  routines  typically
       are used inside library routines.

   def_prog_mode, def_shell_mode
       The  def_prog_mode  and  def_shell_mode  routines  save  the  current terminal modes as the “program” (in
       curses) or “shell” (not in curses) state for use by the reset_prog_mode  and  reset_shell_mode  routines.
       This  is done automatically by initscr.  There is one such save area for each screen context allocated by
       newterm.

   reset_prog_mode, reset_shell_mode
       The reset_prog_mode and reset_shell_mode routines restore  the  terminal  to  “program”  (in  curses)  or
       “shell” (out of curses) state.  These are done automatically by endwin(3NCURSES) and, after an endwin, by
       doupdate, so they normally are not called.

   resetty, savetty
       The resetty and savetty routines save and restore the state of the terminal  modes.   savetty  saves  the
       current state in a buffer and resetty restores the state to what it was at the last call to savetty.

   getsyx
       getsyx   stores   the   coordinates  of  virtual  screen  (newscr)  cursor  in  y  and  x.   If  newscr's
       leaveok(3NCURSES) output option is TRUE, getsyx stores -1 in both y and x.  If lines  have  been  removed
       from  the  top  of  the  screen using ripoffline, y includes these lines; therefore, y and x populated by
       getsyx should be used only as arguments for setsyx.

       Few applications use this feature; most call getyx(3NCURSES) instead.

   setsyx
       setsyx sets the virtual screen (newscr) cursor location to (y,  x).   setsyx(-1,  -1)  is  equivalent  to
       leaveok(newscr, TRUE).

       getsyx  and  setsyx  are  designed  to be used by a function that manipulates curses windows but seeks to
       avoid changing the cursor position.  Such a  function  would  first  call  getsyx,  modify  its  windows'
       content, call wnoutrefresh(3NCURSES) on them, call setsyx, then call doupdate(3NCURSES).

       Few applications use this feature; most call wmove(3NCURSES) instead.

   curs_set
       curs_set  adjusts  the cursor visibility to “invisible”, “visible”, “very visible”, as its argument is 0,
       1, or 2, respectively.  It returns the previous visibility if the requested one  is  supported,  and  ERR
       otherwise.

   mvcur
       mvcur  provides  low-level  cursor motion.  It takes effect immediately, rather than at the next refresh.
       Unlike the other low-level output functions, which either write to the  standard  output  stream  or  are
       passed  a function pointer to perform output, mvcur uses a file descriptor derived from the output stream
       parameter of newterm(3NCURSES).

       One application of mvcur accompanies the temporary use of  another  program  to  write  to  the  terminal
       screen.   For  example, first call refresh(3NCURSES) to ensure that the screen and the library's model of
       it is up to date; then call reset_shell_mode; write to the screen with  the  external  application;  call
       reset_prog_mode;  and  finally  call  mvcur(..., ..., -1, -1) to move the terminal cursor to where curses
       thinks it is, since the library has no knowledge of how the external application moved it.

   napms
       napms sleeps for ms milliseconds.  If ms exceeds 30,000 (thirty seconds), it is capped at that value.

   ripoffline
       ripoffline provides access to the same facility that slk_init(3NCURSES) uses to reduce the  size  of  the
       screen.  ripoffline must be called before initscr or newterm is called, to prepare these initial actions:

       •   If line is positive, a line is removed from the top of stdscr.

       •   if line is negative, a line is removed from the bottom.

       When  the  resulting  initialization  is  done inside initscr, the routine init (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 LINES and COLS (defined in <curses.h>) are  not
       guaranteed  to  be  accurate  and  wrefresh  or  doupdate  must  not  be called.  It is allowable to call
       wnoutrefresh during the initialization routine.

       ripoffline can be called up to five times before calling initscr or newterm.

RETURN VALUE

       Except for curs_set, these functions return OK on success and ERR on failure.

       curs_set returns the previous cursor visibility, and returns ERR if the terminal type  does  not  support
       the requested visibility.

       napms always succeeds.

       mvcur fails if the position (newrow, newcol) is outside the screen boundaries.

       In ncurses,

       •   def_prog_mode,  def_shell_mode,  reset_prog_mode, and reset_shell_mode return ERR if the terminal was
           not initialized, or if the operating system's function for obtaining terminal settings fails.

       •   ripoffline returns ERR if the accumulated quantity of ripped-off lines would exceed the maximum (5).

NOTES

       getsyx is a macro; use of the & operator before its arguments is unnecessary.

       The endwin function of both ncurses and SVr4 curses calls curs_set if  the  latter  has  previously  been
       called  to  set  the  cursor  visibility  to a value other than normal; that is, either invisible or very
       visible.  There is no way for ncurses to determine the initial cursor visibility to restore it.

EXTENSIONS

       In ncurses, mvcur accepts -1 for either or both old coordinates.  This value tells ncurses that  the  old
       location  is  unknown,  and  that  it  must  use  only  absolute motion, as with the cursor_address (cup)
       capability, rather than the least costly combination of absolute and relative motion.

PORTABILITY

       Applications  employing  ncurses  extensions  should  condition  their  use  on  the  visibility  of  the
       NCURSES_VERSION preprocessor macro.

       The  virtual  screen  functions  setsyx  and  getsyx  are  not  described in X/Open Curses Issue 4.  SVr4
       documents each of them as returning an int.  This is misleading, as they are macros  with  no  documented
       semantics for returning values.

       All other functions are as described in X/Open Curses.  It specifies no error conditions for them, except
       as described for curs_set in section “RETURN VALUE” above.

       The System V Interface Definition, Version 4 (1995), specified all of these functions except curs_set  as
       returning OK.

       Older  SVr4  man  pages  warn  that  the  return  value  of  curs_set  “is  currently  incorrect”.   This
       implementation gets it right, but counting on its correctness anywhere else may be unwise.

       X/Open Curses specifies ripoffline as returning OK with no possibility of failure (“[c]alls to ripoffline
       above this limit [five lines] have no effect but report success”).

       X/Open Curses notes:

              After  use of mvcur(), the model Curses maintains of the state of the terminal might not match the
              actual state of the terminal.  An application should touch and refresh the window before  resuming
              conventional use of Curses.

       Both   ncurses   and   SVr4   curses  implement  mvcur  using  the  SCREEN  object  allocated  in  either
       initscr(3NCURSES) or newterm(3NCURSES).  X/Open Curses states that the old location  must  be  given  for
       mvcur to accommodate terminals that lack absolute cursor positioning.

       If  interrupted by a signal, ncurses restarts napms.  That, and the limitation to 30 seconds, differ from
       other implementations.

SEE ALSO

       ncurses(3NCURSES),   initscr(3NCURSES),   outopts(3NCURSES),    refresh(3NCURSES),    scr_dump(3NCURSES),
       slk(3NCURSES), curses_variables(3NCURSES)