ncurses 5.6 - patch 20070113
[ncurses.git] / include / curses.h.in
index 3b8696014d211c3f7f2711bb78cdb606467159f7..6e517f765651a4a053701d7c3d11334d51555c71 100644 (file)
@@ -1,5 +1,5 @@
 /****************************************************************************
- * Copyright (c) 1998-2003,2004 Free Software Foundation, Inc.              *
+ * Copyright (c) 1998-2005,2006 Free Software Foundation, Inc.              *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
 /****************************************************************************
  *  Author: Zeyd M. Ben-Halim <zmbenhal@netcom.com> 1992,1995               *
  *     and: Eric S. Raymond <esr@snark.thyrsus.com>                         *
- *     and: Thomas E. Dickey 1996-on                                        *
+ *     and: Thomas E. Dickey                        1996-on                 *
  ****************************************************************************/
 
-/* $Id: curses.h.in,v 1.148 2004/01/14 23:50:12 tom Exp $ */
+/* $Id: curses.h.in,v 1.167 2006/11/26 01:14:54 tom Exp $ */
 
 #ifndef __NCURSES_H
 #define __NCURSES_H
 #undef  NCURSES_VERSION
 #define NCURSES_VERSION "@NCURSES_MAJOR@.@NCURSES_MINOR@"
 
+/*
+ * Identify the mouse encoding version.
+ */
+#define NCURSES_MOUSE_VERSION @NCURSES_MOUSE_VERSION@
+
+/*
+ * Definitions to facilitate DLL's.
+ */
 #include <ncurses_dll.h>
 
+/*
+ * User-definable tweak to disable the include of <stdbool.h>.
+ */
+#ifndef NCURSES_ENABLE_STDBOOL_H
+#define NCURSES_ENABLE_STDBOOL_H @cf_cv_header_stdbool_h@
+#endif
+
 /*
  * NCURSES_ATTR_T is used to quiet compiler warnings when building ncurses
  * configured using --disable-macros.
  */
 #ifdef NCURSES_NOMACROS
+#ifndef NCURSES_ATTR_T
 #define NCURSES_ATTR_T attr_t
 #endif
+#endif /* NCURSES_NOMACROS */
 
 #ifndef NCURSES_ATTR_T
 #define NCURSES_ATTR_T int
@@ -76,6 +93,9 @@
 #undef  NCURSES_CONST
 #define NCURSES_CONST @NCURSES_CONST@
 
+#undef NCURSES_INLINE
+#define NCURSES_INLINE @NCURSES_INLINE@
+
 /*
  * The internal type used for color values
  */
 #undef NCURSES_SIZE_T
 #define        NCURSES_SIZE_T short
 
+/*
+ * Control whether tparm() supports varargs or fixed-parameter list.
+ */
+#undef NCURSES_TPARM_VARARGS
+#define NCURSES_TPARM_VARARGS @NCURSES_TPARM_VARARGS@
+
 /*
  * NCURSES_CH_T is used in building the library, but not used otherwise in
  * this header file, since that would make the normal/wide-character versions
 #undef NCURSES_CH_T
 #define NCURSES_CH_T @NCURSES_CH_T@
 
+#if @cf_cv_enable_lp64@ && defined(_LP64)
+typedef unsigned chtype;
+typedef unsigned mmask_t;
+#else
 typedef unsigned @cf_cv_typeof_chtype@ chtype;
+typedef unsigned @cf_cv_typeof_mmask_t@ mmask_t;
+#endif
 
 #include <stdio.h>
 #include <unctrl.h>
@@ -132,7 +164,7 @@ typedef @cf_cv_type_of_bool@ NCURSES_BOOL;
 
 #else                  /* c89, c99, etc. */
 
-#if @cf_cv_header_stdbool_h@
+#if NCURSES_ENABLE_STDBOOL_H
 #include <stdbool.h>
 /* use whatever the C compiler decides bool really is */
 #define NCURSES_BOOL bool
@@ -146,6 +178,9 @@ typedef @cf_cv_type_of_bool@ NCURSES_BOOL;
 
 #ifdef __cplusplus
 extern "C" {
+#define NCURSES_CAST(type,value) static_cast<type>(value)
+#else
+#define NCURSES_CAST(type,value) (type)(value)
 #endif
 
 /*
@@ -192,7 +227,7 @@ extern NCURSES_EXPORT_VAR(chtype*) _nc_acs_map(void);
 extern NCURSES_EXPORT_VAR(chtype) acs_map[];
 #endif
 
-#define NCURSES_ACS(c) (acs_map[(unsigned char)c])
+#define NCURSES_ACS(c) (acs_map[NCURSES_CAST(unsigned char,c)])
 
 /* VT100 symbols begin here */
 #define ACS_ULCORNER   NCURSES_ACS('l') /* upper left corner */
@@ -310,6 +345,9 @@ typedef struct
 {
     attr_t     attr;
     wchar_t    chars[CCHARW_MAX];
+#if @NCURSES_EXT_COLORS@
+    int                ext_color;      /* color pair, must be more than 16-bits */
+#endif
 }
 cchar_t;
 
@@ -366,6 +404,9 @@ struct _win_st
 
 #ifdef _XOPEN_SOURCE_EXTENDED
        cchar_t  _bkgrnd;       /* current background char/attribute pair */
+#if @NCURSES_EXT_COLORS@
+       int     _color;         /* current color-pair for non-space character */
+#endif
 #endif
 };
 
@@ -382,8 +423,6 @@ extern NCURSES_EXPORT_VAR(int)      TABSIZE;
  */
 extern NCURSES_EXPORT_VAR(int) ESCDELAY;       /* ESC expire time in milliseconds */
 
-extern NCURSES_EXPORT_VAR(char) ttytype[];     /* needed for backward compatibility */
-
 /*
  * These functions are extensions - not in XSI Curses.
  */
@@ -399,7 +438,9 @@ extern NCURSES_EXPORT(int) resize_term (int, int);
 extern NCURSES_EXPORT(int) resizeterm (int, int);
 extern NCURSES_EXPORT(int) use_default_colors (void);
 extern NCURSES_EXPORT(int) use_extended_names (bool);
+extern NCURSES_EXPORT(int) use_legacy_coding (int);
 extern NCURSES_EXPORT(int) wresize (WINDOW *, int, int);
+extern NCURSES_EXPORT(void) nofilter(void);
 #else
 #define curses_version() NCURSES_VERSION
 #endif
@@ -465,7 +506,11 @@ extern NCURSES_EXPORT(int) wgetnstr_events(WINDOW *,char *,int,_nc_eventlist *);
 
 /*
  * We cannot define these in ncurses_cfg.h, since they require parameters to be
- * passed (that's non-portable).
+ * passed (that is non-portable).  If you happen to be using gcc with warnings
+ * enabled, define
+ *     GCC_PRINTF
+ *     GCC_SCANF
+ * to improve checking of calls to printw(), etc.
  */
 #ifndef GCC_PRINTFLIKE
 #if defined(GCC_PRINTF) && !defined(printf)
@@ -655,7 +700,6 @@ extern NCURSES_EXPORT(int) pnoutrefresh (WINDOW*,int,int,int,int,int,int);/* imp
 extern NCURSES_EXPORT(int) prefresh (WINDOW *,int,int,int,int,int,int);        /* implemented */
 extern NCURSES_EXPORT(int) printw (const char *,...)                   /* implemented */
                GCC_PRINTFLIKE(1,2);
-extern NCURSES_EXPORT(int) putp (const char *);                                /* implemented */
 extern NCURSES_EXPORT(int) putwin (WINDOW *, FILE *);                  /* implemented */
 extern NCURSES_EXPORT(void) qiflush (void);                            /* implemented */
 extern NCURSES_EXPORT(int) raw (void);                                 /* implemented */
@@ -701,13 +745,9 @@ extern NCURSES_EXPORT(WINDOW *) subwin (WINDOW *,int,int,int,int); /* implemente
 extern NCURSES_EXPORT(int) syncok (WINDOW *, bool);                    /* implemented */
 extern NCURSES_EXPORT(chtype) termattrs (void);                                /* implemented */
 extern NCURSES_EXPORT(char *) termname (void);                         /* implemented */
-extern NCURSES_EXPORT(int) tigetflag (NCURSES_CONST char *);           /* implemented */
-extern NCURSES_EXPORT(int) tigetnum (NCURSES_CONST char *);            /* implemented */
-extern NCURSES_EXPORT(char *) tigetstr (NCURSES_CONST char *);         /* implemented */
 extern NCURSES_EXPORT(void) timeout (int);                             /* generated */
 extern NCURSES_EXPORT(int) touchline (WINDOW *, int, int);             /* generated */
 extern NCURSES_EXPORT(int) touchwin (WINDOW *);                                /* generated */
-extern NCURSES_EXPORT(char *) tparm (NCURSES_CONST char *, ...);       /* implemented */
 extern NCURSES_EXPORT(int) typeahead (int);                            /* implemented */
 extern NCURSES_EXPORT(int) ungetch (int);                              /* implemented */
 extern NCURSES_EXPORT(int) untouchwin (WINDOW *);                      /* generated */
@@ -777,7 +817,36 @@ extern NCURSES_EXPORT(int) wtouchln (WINDOW *,int,int,int);                /* implemented */
 extern NCURSES_EXPORT(int) wvline (WINDOW *,chtype,int);               /* implemented */
 
 /*
- * vid_attr() was implemented originally based on the draft of XSI curses.
+ * These are also declared in <term.h>:
+ */
+extern NCURSES_EXPORT(int) tigetflag (NCURSES_CONST char *);           /* implemented */
+extern NCURSES_EXPORT(int) tigetnum (NCURSES_CONST char *);            /* implemented */
+extern NCURSES_EXPORT(char *) tigetstr (NCURSES_CONST char *);         /* implemented */
+extern NCURSES_EXPORT(int) putp (const char *);                                /* implemented */
+
+#if NCURSES_TPARM_VARARGS
+extern NCURSES_EXPORT(char *) tparm (NCURSES_CONST char *, ...);       /* implemented */
+#else
+extern NCURSES_EXPORT(char *) tparm (NCURSES_CONST char *, long,long,long,long,long,long,long,long,long);      /* implemented */
+extern NCURSES_EXPORT(char *) tparm_varargs (NCURSES_CONST char *, ...);       /* implemented */
+#endif
+
+extern NCURSES_EXPORT_VAR(char) ttytype[];     /* needed for backward compatibility */
+
+/*
+ * These functions are not in X/Open, but we use them in macro definitions:
+ */
+extern NCURSES_EXPORT(int) getcurx (const WINDOW *);                   /* generated */
+extern NCURSES_EXPORT(int) getcury (const WINDOW *);                   /* generated */
+extern NCURSES_EXPORT(int) getbegx (const WINDOW *);                   /* generated */
+extern NCURSES_EXPORT(int) getbegy (const WINDOW *);                   /* generated */
+extern NCURSES_EXPORT(int) getmaxx (const WINDOW *);                   /* generated */
+extern NCURSES_EXPORT(int) getmaxy (const WINDOW *);                   /* generated */
+extern NCURSES_EXPORT(int) getparx (const WINDOW *);                   /* generated */
+extern NCURSES_EXPORT(int) getpary (const WINDOW *);                   /* generated */
+
+/*
+ * vid_attr() was implemented originally based on a draft of XSI curses.
  */
 #ifndef _XOPEN_SOURCE_EXTENDED
 #define vid_attr(a,pair,opts) vidattr(a)
@@ -788,7 +857,7 @@ extern NCURSES_EXPORT(int) wvline (WINDOW *,chtype,int);            /* implemented */
 #define NCURSES_ATTR_SHIFT       8
 #define NCURSES_BITS(mask,shift) ((mask) << ((shift) + NCURSES_ATTR_SHIFT))
 
-#define A_NORMAL       0L
+#define A_NORMAL       (@cf_cv_1UL@ - @cf_cv_1UL@)
 #define A_ATTRIBUTES   NCURSES_BITS(~(@cf_cv_1UL@ - @cf_cv_1UL@),0)
 #define A_CHARTEXT     (NCURSES_BITS(@cf_cv_1UL@,0) - @cf_cv_1UL@)
 #define A_COLOR                NCURSES_BITS(((@cf_cv_1UL@) << 8) - @cf_cv_1UL@,0)
@@ -808,23 +877,15 @@ extern NCURSES_EXPORT(int) wvline (WINDOW *,chtype,int);          /* implemented */
 #define A_TOP          NCURSES_BITS(@cf_cv_1UL@,21)
 #define A_VERTICAL     NCURSES_BITS(@cf_cv_1UL@,22)
 
-#define COLOR_PAIR(n)  NCURSES_BITS(n, 0)
-#define PAIR_NUMBER(a) ((int)(((a) & A_COLOR) >> NCURSES_ATTR_SHIFT))
-
 /*
- * pseudo functions
+ * Most of the pseudo functions are macros that either provide compatibility
+ * with older versions of curses, or provide inline functionality to improve
+ * performance.
  */
-#define wgetstr(w, s)          wgetnstr(w, s, -1)
-#define getnstr(s, n)          wgetnstr(stdscr, s, n)
 
-#define setterm(term)          setupterm(term, 1, (int *)0)
-
-#define fixterm()              reset_prog_mode()
-#define resetterm()            reset_shell_mode()
-#define saveterm()             def_prog_mode()
-#define crmode()               cbreak()
-#define nocrmode()             nocbreak()
-#define gettmode()
+/*
+ * These pseudo functions are always implemented as macros:
+ */
 
 #define getyx(win,y,x)         (y = getcury(win), x = getcurx(win))
 #define getbegyx(win,y,x)      (y = getbegy(win), x = getbegx(win))
@@ -838,6 +899,24 @@ extern NCURSES_EXPORT(int) wvline (WINDOW *,chtype,int);           /* implemented */
                         else {newscr->_leaveok=FALSE;wmove(newscr,(y),(x));} \
                    } while(0)
 
+#ifndef NCURSES_NOMACROS
+
+/*
+ * These miscellaneous pseudo functions are provided for compatibility:
+ */
+
+#define wgetstr(w, s)          wgetnstr(w, s, -1)
+#define getnstr(s, n)          wgetnstr(stdscr, s, n)
+
+#define setterm(term)          setupterm(term, 1, (int *)0)
+
+#define fixterm()              reset_prog_mode()
+#define resetterm()            reset_shell_mode()
+#define saveterm()             def_prog_mode()
+#define crmode()               cbreak()
+#define nocrmode()             nocbreak()
+#define gettmode()
+
 /* It seems older SYSV curses versions define these */
 #define getattrs(win)          ((win)?(win)->_attrs:A_NORMAL)
 #define getcurx(win)           ((win)?(win)->_curx:ERR)
@@ -851,11 +930,16 @@ extern NCURSES_EXPORT(int) wvline (WINDOW *,chtype,int);          /* implemented */
 
 #define wstandout(win)         (wattrset(win,A_STANDOUT))
 #define wstandend(win)         (wattrset(win,A_NORMAL))
-#define wattr_set(win,a,p,opts) ((win)->_attrs = (((a) & ~A_COLOR) | COLOR_PAIR(p)), OK)
 
-#define wattron(win,at)                wattr_on(win, (attr_t) at, (void *)0)
-#define wattroff(win,at)       wattr_off(win, (attr_t) at, (void *)0)
+#define wattron(win,at)                wattr_on(win, NCURSES_CAST(attr_t, at), NULL)
+#define wattroff(win,at)       wattr_off(win, NCURSES_CAST(attr_t, at), NULL)
+
+#if defined(_XOPEN_SOURCE_EXTENDED) && @NCURSES_EXT_COLORS@
+#define wattrset(win,at)       ((win)->_color = PAIR_NUMBER(at), \
+                                (win)->_attrs = (at))
+#else
 #define wattrset(win,at)       ((win)->_attrs = (at))
+#endif
 
 #define scroll(win)            wscrl(win,1)
 
@@ -876,6 +960,12 @@ extern NCURSES_EXPORT(int) wvline (WINDOW *,chtype,int);           /* implemented */
 #define waddstr(win,str)       waddnstr(win,str,-1)
 #define waddchstr(win,str)     waddchnstr(win,str,-1)
 
+/*
+ * These apply to the first 256 color pairs.
+ */
+#define COLOR_PAIR(n)  NCURSES_BITS(n, 0)
+#define PAIR_NUMBER(a) (NCURSES_CAST(int,(((a) & A_COLOR) >> NCURSES_ATTR_SHIFT)))
+
 /*
  * pseudo functions for standard screen
  */
@@ -940,7 +1030,7 @@ extern NCURSES_EXPORT(int) wvline (WINDOW *,chtype,int);           /* implemented */
 #define mvwgetnstr(win,y,x,str,n)      (wmove(win,y,x) == ERR ? ERR : wgetnstr(win,str,n))
 #define mvwgetstr(win,y,x,str)         (wmove(win,y,x) == ERR ? ERR : wgetstr(win,str))
 #define mvwhline(win,y,x,c,n)          (wmove(win,y,x) == ERR ? ERR : whline(win,c,n))
-#define mvwinch(win,y,x)               (wmove(win,y,x) == ERR ? (chtype)ERR : winch(win))
+#define mvwinch(win,y,x)               (wmove(win,y,x) == ERR ? NCURSES_CAST(chtype, ERR) : winch(win))
 #define mvwinchnstr(win,y,x,s,n)       (wmove(win,y,x) == ERR ? ERR : winchnstr(win,s,n))
 #define mvwinchstr(win,y,x,s)          (wmove(win,y,x) == ERR ? ERR : winchstr(win,s))
 #define mvwinnstr(win,y,x,s,n)         (wmove(win,y,x) == ERR ? ERR : winnstr(win,s,n))
@@ -972,16 +1062,26 @@ extern NCURSES_EXPORT(int) wvline (WINDOW *,chtype,int);         /* implemented */
 #define mvvline(y,x,c,n)               mvwvline(stdscr,y,x,c,n)
 
 /*
- * Some wide-character functions do not depend on the extensions.
+ * Some wide-character functions can be implemented without the extensions.
  */
 #define getbkgd(win)                    ((win)->_bkgd)
 
 #define slk_attr_off(a,v)              ((v) ? ERR : slk_attroff(a))
 #define slk_attr_on(a,v)               ((v) ? ERR : slk_attron(a))
 
+#if defined(_XOPEN_SOURCE_EXTENDED) && @NCURSES_EXT_COLORS@
+#define wattr_set(win,a,p,opts)                ((win)->_attrs = ((a) & ~A_COLOR), \
+                                        (win)->_color = (p), \
+                                        OK)
+#define wattr_get(win,a,p,opts)                ((void)((a) != 0 && (*(a) = (win)->_attrs)), \
+                                        (void)((p) != 0 && (*(p) = (win)->_color)), \
+                                        OK)
+#else
+#define wattr_set(win,a,p,opts)                ((win)->_attrs = (((a) & ~A_COLOR) | COLOR_PAIR(p)), OK)
 #define wattr_get(win,a,p,opts)                ((void)((a) != 0 && (*(a) = (win)->_attrs)), \
                                         (void)((p) != 0 && (*(p) = PAIR_NUMBER((win)->_attrs))), \
                                         OK)
+#endif
 
 /*
  * XSI curses deprecates SVr4 vwprintw/vwscanw, which are supposed to use
@@ -1000,6 +1100,8 @@ extern NCURSES_EXPORT(int) wvline (WINDOW *,chtype,int);          /* implemented */
 NCURSES_EXPORT(int) vsscanf(const char *, const char *, va_list);
 #endif
 
+#endif /* NCURSES_NOMACROS */
+
 /*
  * Pseudo-character tokens outside ASCII range.  The curses wgetch() function
  * will return any given one of these only if the corresponding k- capability