man/define_key.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: define_key.3x,v 1.44 2024/05/18 20:04:21 tom Exp $
  33 .TH define_key 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\%define_key\fP \-
  42 define a \fIcurses\fP function key code
  43 .SH SYNOPSIS
  44 .nf
  45 \fB#include <curses.h>
  46 .PP
  47 \fBint define_key(const char * \fIdefinition\fP, int \fIkey-code\fP);
  48 .fi
  49 .SH DESCRIPTION
  50 The
  51 .B \%define_key
  52 .I \%ncurses
  53 extension permits a
  54 .I curses
  55 application to
  56 .I bind
  57 a string
  58 .I definition
  59 to the function key
  60 .I key-code
  61 returned by \fB\%wgetch\fP(3X)
  62 (wide-character API users:
  63 \fB\%wget_wch\fP(3X))
  64 when \fB\%keypad\fP(3X) is enabled in a window and a function key is
  65 pressed.
  66 .I \%ncurses
  67 interprets such a binding as it does those in the
  68 .I \%term\%info
  69 database entry for the terminal type.
  70 .PP
  71 A
  72 .I definition
  73 of
  74 .B NULL
  75 removes any existing one
  76 .IR key-code "."
  77 Similarly,
  78 a non-positive
  79 .I key-code
  80 removes any existing bindings for
  81 .IR definition "."
  82 .SH RETURN VALUE
  83 .B \%define_key
  84 returns
  85 .B ERR
  86 if
  87 .bP
  88 .I definition
  89 is
  90 .B NULL
  91 and
  92 .I key-code
  93 is nonpositive,
  94 or
  95 .bP
  96 insufficient memory is available to bind
  97 .I definition
  98 to
  99 .IR key-code "."
 100 .PP
 101 Otherwise,
 102 .B \%define_key
 103 returns
 104 .BR OK "."
 105 .SH EXTENSIONS
 106 .B \%define_key
 107 is an
 108 .I \%ncurses
 109 extension.
 110 .SH PORTABILITY
 111 Applications employing
 112 .I \%ncurses
 113 extensions should condition their use on the visibility of the
 114 .B \%NCURSES_VERSION
 115 preprocessor macro.
 116 .PP
 117 NetBSD
 118 .I curses
 119 since 2.0 (2004) supports
 120 .BR \%define_key "."
 121 .SH AUTHORS
 122 Thomas Dickey
 123 .SH SEE ALSO
 124 \fB\%ncurses\fP(3X),
 125 \fB\%keyok\fP(3X),
 126 \fB\%key_defined\fP(3X),
 127 \fB\%keybound\fP(3X),
 128 \fB\%keyok\fP(3X),
 129 \fB\%terminfo\fP(5)