Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
keypad(3XCURSES)	X/Open Curses Library Functions	      keypad(3XCURSES)

       keypad -	enable/disable keypad handling

       cc [ flag... ] file... -I /usr/xpg4/include -L /usr/xpg4/lib \
       -R /usr/xpg4/lib	-lcurses [ library... ]

       c89 [ flag... ] file... -lcurses	[ library... ]

       #include	<curses.h>

       int keypad(WINDOW *win, bool bf);

       win	Is  a  pointer to the window in	which to enable/disable	keypad

       bf	Is a Boolean expression.

       The keypad() function controls keypad translation. If bf	is TRUE,  key-
       pad  translation	is enabled. If bf is FALSE, keypad translation is dis-
       abled. The initial state	is FALSE.

       This function affects the behavior of any function that	provides  key-
       board input.

       If the terminal in use requires a command to enable it to transmit dis-
       tinctive	codes when a function key is pressed, then after keypad	trans-
       lation  is  first enabled, the implementation transmits this command to
       the terminal before an affected input function tries to read any	 char-
       acters from that	terminal.

       The Curses input	model provides the following ways to obtain input from
       the keyboard:

   Keypad processing
       The application can enable or disable  keypad  translation  by  calling
       keypad().  When	translation is enabled,	Curses attempts	to translate a
       sequence	of terminal input that represents the pressing of  a  function
       into  a	single	key  code. When	translation is disabled, Curses	passes
       terminal	input to the application without such translation, and any in-
       terpretation  of	the input as representing the pressing of a keypad key
       must be done by the application.

       The complete set	of key codes for keypad	keys that Curses  can  process
       is  specified  by the constants defined in <curses.h> whose names begin
       with "KEY_". Each terminal type described in the	terminfo database  may
       support some or all of these key	codes. The terminfo database specifies
       the sequence of input characters	from the terminal type that correspond
       to each key code.

       The  Curses  inplementation  cannot  translate keypad keys on terminals
       where pressing the keys does not	transmit a unique sequence.

       When translation	is enabled and a character that	could be the beginning
       of  a  function key (such as escape) is received, Curses	notes the time
       and begins accumulating	characters.  If	 Curses	  receives  additional
       characters  that	represent the processing of a keypad key within	an un-
       specified interval from the  time  the  character  was  received,  then
       Curses converts this input to a key code	for presentation to the	appli-
       cation. If such characters  are	not  received  during  this  interval,
       translation  of this input does not occur and the individual characters
       are presented to	the application	separately. (Because Curses waits  for
       this interval to	accumulate a key code, many terminals experience a de-
       lay between the time a user presses the escape key and the time the es-
       cape key	is returned to the application.)

       In addition, No Timeout Mode provides that in any case where Curses has
       received	part of	a function key sequence, it waits indefinitely for the
       complete	key sequence. The "unspecified interval" in the	previous para-
       graph becomes infinite in No Timeout Mode. No Timeout Mode  allows  the
       use  of	function  keys	over slow communication	lines. No Timeout Mode
       lets the	user type the individual characters  of	 a  function  key  se-
       quence,	but  also  delays  application	response when the user types a
       character (not a	function key) that begins a function key sequence. For
       this  reason, in	No Timeout Mode	many terminals will appear to hang be-
       tween the time a	user presses the escape	key and	the time  another  key
       is   pressed.   No  Timeout  Mode  is  switchable  by  calling  notime-

       If any special characters (<backspace>, <carriage  return>,  <newline>,
       <tab>)  are defined or redefined	to be characters that are members of a
       function	key sequence, then Curses will	be  unable  to	recognize  and
       translate those function	keys.

       Several	of  the	modes discussed	below are described in terms of	avail-
       ability of input. If keypad translation is enabled, then	input  is  not
       available  once	Curses has begun receiving a keypad sequence until the
       sequence	is completely received or the interval has elapsed.

   Input Mode
       The following four mutually-specific Curses modes let  the  application
       control the effect of flow-control characters, the interrupt character,
       the erase character, and	the kill character:

       | Input Mode	   Effect				    |
       |Cooked Mode	   This	achieves normal	line-at-a-time pro- |
       |		  cessing  with	all special characters han- |
       |		  dled	outside	  the	application.   This |
       |		  achieves  the	 same  effect as canonical- |
       |		  mode input processing. The state  of	the |
       |		  ISIG	and IXON flags are not changed upon |
       |		  entering    this    mode    by    calling |
       |		  nocbreak(3XCURSES),  and are set upon	en- |
       |		  tering   this	  mode	 by   calling	no- |
       |		  raw(3XCURSES).			    |
       |							    |
       |		  Erase	 and  kill characters are supported |
       |		  from any supported locale, no	matter	the |
       |		  width	of the character.		    |
       |cbreak Mode	  Characters  typed by the user	are immedi- |
       |		  ately	available to  the  application	and |
       |		  Curses  does not perform special process- |
       |		  ing on either	the erase character or	the |
       |		  kill	character.  An	application can	set |
       |		  cbreak mode to do its	 own  line  editing |
       |		  but to let the abort character be used to |
       |		  abort	the task. This	mode  achieves	the |
       |		  same effect as non-canonical-mode, Case B |
       |		  input	processing (with MIN set to  1	and |
       |		  ICRNL	cleared.) The state of the ISIG	and |
       |		  IXON flags are not changed upon  entering |
       |		  this mode.				    |
       |Half-Delay Mode	   The effect is the same as cbreak, except |
       |		  that input functions wait until a charac- |
       |		  ter  is  available or	an interval defined |
       |		  by  the  application	elapses,  whichever |
       |		  comes	 first.	This mode achieves the same |
       |		  effect as non-canonical-mode,	Case C	in- |
       |		  put  processing  (with  TIME	set  to	the |
       |		  value	specified by the application.)	The |
       |		  state	 of the	ISIG and IXON flags are	not |
       |		  changed upon entering	this mode.	    |
       |Raw Mode	  Raw mode gives  the  application  maximum |
       |		  control over terminal	input. The applica- |
       |		  tion sees each character as it is  typed. |
       |		  This	achieves  the  same  effect as non- |
       |		  canonical mode, Case D input	processing. |
       |		  The  ISIG and	IXON flags are cleared upon |
       |		  entering this	mode.			    |

       The terminal interface settings are reported  when  the	process	 calls
       initscr(3XCURSES)  or  newterm(3XCURSES)	 to  initialize	Curses and re-
       stores these settings when endwin(3XCURSES) is called. The initial  in-
       put  mode  for  Curses  operations is especially	unless Enhanced	Curses
       compliance, in which the	initial	mode is	cbreak mode, is	supported.

       The behavior of the BREAK key depends on	 other	bits  in  the  display
       driver that are not set by Curses.

   Delay Mode
       Two  mutually-exclusive	delay modes specify how	quickly	certain	Curses
       functions return	to the application when	there  is  no  terminal	 input
       waiting when the	function is called:

       No Delay	       The function fails.

       Delay		The  application waits until text is passed through to
		       the application.	If cbreak or Raw Mode is set, this  is
		       after one character. Otherwise, this is after the first
		       <newline> character, end-of-line	character, or  end-of-
		       file character.

       The effect of No	Delay Mode on function key processing is unspecified.

   Echo	processing
       Echo  mode  determines  whether	Curses	echoes typed characters	to the
       screen. The effect of Echo mode is analogous to the effect of the  ECHO
       flag  in	 the local mode	field of the termios structure associated with
       the terminal device connected to	the  window.  However,	Curses	always
       clears the ECHO flag when invoked, to inhibit the operating system from
       performing echoing. The method of echoing characters is	not  identical
       to  the operating system's method of echoing characters,	because	Curses
       performs	additional processing of terminal input.

       If in Echo mode,	Curses performs	's's own echoing.  Any	visible	 input
       character  is  stored  in  the current or specified window by the input
       function	that the application called, at	that window's cursor position,
       as though addch(3XCURSES) were called, with all consequent effects such
       as cursor movement and wrapping.

       If not in Echo mode, any	echoing	of input must be performed by the  ap-
       plication. Applications often perform their own echoing in a controlled
       area of the screen, or do not echo at all, so they disable Echo mode.

       It may not be possible to turn off echo processing for synchronous  and
       networked  asynchronous	terminals  because echo	processing is done di-
       rectly by the terminals.	Applications running on	such terminals	should
       be  aware  that any characters typed will appear	on the screen at wher-
       ever the	cursor is positioned.

       Upon successful completion, the keypad()	function  returns  OK.	Other-
       wise, it	returns	ERR.

       No errors are defined.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |Unsafe			   |

       addch(3XCURSES),	 endwin(3XCURSES), getch(3XCURSES), initscr(3XCURSES),
       libcurses(3XCURSES),   newterm(3XCURSES),    nocbreak(3XCURSES),	   no-
       raw(3XCURSES), attributes(5), standards(5)

SunOS 5.10			  5 Jun	2002		      keypad(3XCURSES)


Want to link to this manual page? Use this URL:

home | help