man/keyok.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
   3 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
   4 .\"                                                                          *
   5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   6 .\" copy of this software and associated documentation files (the            *
   7 .\" "Software"), to deal in the Software without restriction, including      *
   8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
   9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
  10 .\" copies of the Software, and to permit persons to whom the Software is    *
  11 .\" furnished to do so, subject to the following conditions:                 *
  12 .\"                                                                          *
  13 .\" The above copyright notice and this permission notice shall be included  *
  14 .\" in all copies or substantial portions of the Software.                   *
  15 .\"                                                                          *
  16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23 .\"                                                                          *
  24 .\" Except as contained in this notice, the name(s) of the above copyright   *
  25 .\" holders shall not be used in advertising or otherwise to promote the     *
  26 .\" sale, use or other dealings in this Software without prior written       *
  27 .\" authorization.                                                           *
  28 .\"***************************************************************************
  29 .\"
  30 .\" Author: Thomas E. Dickey 1997
  31 .\"
  32 .\" $Id: keyok.3x,v 1.42 2024/05/18 20:06:09 tom Exp $
  33 .TH keyok 3X 2024-05-18 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
  34 .
  35 .de bP
  36 .ie n  .IP \(bu 4
  37 .el    .IP \(bu 2
  38 ..
  39 .
  40 .SH NAME
  41 \fB\%keyok\fP \-
  42 enable or disable a \fIcurses\fP function key code
  43 .SH SYNOPSIS
  44 .nf
  45 \fB#include <curses.h>
  46 .PP
  47 \fBint keyok(int \fIkey-code\fP, bool \fIbf\fP);
  48 .fi
  49 .SH DESCRIPTION
  50 The
  51 .B \%keyok
  52 .I \%ncurses
  53 extension permits a
  54 .I curses
  55 application to disable a function key
  56 .I key-code
  57 returned by \fB\%wgetch\fP(3X)
  58 (wide-character API users:
  59 \fB\%wget_wch\fP(3X)).
  60 Key codes that have been disabled can be re-enabled.
  61 .I bf
  62 indicates the desired enablement status.
  63 This operation is more fine-grained than calling \fB\%keypad\fP(3X),
  64 which affects
  65 .I all
  66 function keys.
  67 .SH RETURN VALUE
  68 .B \%keyok
  69 returns
  70 .B ERR
  71 if
  72 .bP
  73 .I key-code
  74 is nonpositive,
  75 .bP
  76 .I key-code
  77 is not a recognized value,
  78 or
  79 .bP
  80 enablement of
  81 .I key-code
  82 is already in the desired state.
  83 .PP
  84 Otherwise,
  85 .B \%keyok
  86 returns
  87 .BR OK "."
  88 .SH EXTENSIONS
  89 .B \%keyok
  90 is an
  91 .I \%ncurses
  92 extension.
  93 .SH PORTABILITY
  94 Applications employing
  95 .I \%ncurses
  96 extensions should condition their use on the visibility of the
  97 .B \%NCURSES_VERSION
  98 preprocessor macro.
  99 .PP
 100 NetBSD
 101 .I curses
 102 since 2.0 (2004) supports
 103 .BR \%keyok "."
 104 .SH AUTHORS
 105 Thomas Dickey
 106 .SH SEE ALSO
 107 \fB\%ncurses\fP(3X),
 108 \fB\%define_key\fP(3X),
 109 \fB\%key_defined\fP(3X),
 110 \fB\%keybound\fP(3X),
 111 \fB\%keyok\fP(3X),