snowleopard-ncurses 1.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/Changes ADDED
@@ -0,0 +1,53 @@
1
+ ncurses-ruby-1.1
2
+ * Bugfixes by T. Sutherland in _tracef and _tracedump.
3
+
4
+ ncurses-ruby-1.0
5
+ * Mousemask bugfix from P.Duncan.
6
+ * Solved timing problems that affected visual smoothness of reactions
7
+ to user input
8
+ * Each SCREEN got back its own "halfdelay" and "cbreak" settings
9
+
10
+ ncurses-ruby-0.9.2
11
+ * Preventing getch and wgetch functions from blocking other ruby threads.
12
+ * Previously ncurses-ruby installed two files named "ncurses.rb" and
13
+ "ncurses.so". The "ncurses.so" is now renamed to "ncurses_bin.so"
14
+ to prevent "require 'ncurses'" from accidentally loading only the
15
+ binary file in case that this is found first in ruby's load path.
16
+ * Reintroduced ability to "include" Ncurses functions:
17
+ Use "include Ncurses::Namespace" for that. This is implemented via
18
+ method_missing, so that ncurses functions (some of which have very
19
+ common names) will not hide other functions defined in the extended
20
+ scope. (Any existing method_missing function is properly aliased and
21
+ called after an unsuccessful lookup.)
22
+
23
+ ncurses-ruby-0.9.1
24
+ * Bugfix in *in*str functions (Hiroshi Sainohira)
25
+ * Fix linking error on Mac OS X and some other platforms (Andreas Schwarz)
26
+
27
+ ncurses-ruby-0.9:
28
+ * Forms wrapper contributed by Simon Kaczor
29
+ * ncurses-ruby now also works with ncurses-4.2
30
+ (an old release from 1998, needed for Zaurus-port)
31
+ * First binary package for Sharp Zaurus (arm-linux)
32
+
33
+ ncurses-ruby-0.8:
34
+ * Bugfix: Calls into the ncurses library prior to calling
35
+ Ncurses::initscr or Ncurses::newterm had previously crashed
36
+ the Ruby interpreter.
37
+ Fixed by delaying the binding of most Ncurses functions
38
+ until after Ncurses::initscr or Ncurses::newterm have been
39
+ called.
40
+ * Replaced module functions with singleton functions. This
41
+ means that
42
+ include Ncurses
43
+ initscr
44
+ is no longer possible. Instead, use
45
+ Ncurses.initscr
46
+ Reasons: - Consistency. The shortcut has never been possible
47
+ with all ncurses functions.
48
+ - Namespace pollution. Some ncurses functions have
49
+ too common names.
50
+
51
+ ncurses-ruby-0.7.2:
52
+ * reintroduced Ncurses::pechochar and Ncurses::redrawwin in the ncurses build.
53
+ These had been removed by mistake because they did not work with PDCurses.
@@ -0,0 +1,28 @@
1
+ Changes
2
+ COPYING
3
+ MANIFEST
4
+ README
5
+ THANKS
6
+ TODO
7
+ VERSION
8
+ examples/example.rb
9
+ examples/form.rb
10
+ examples/form2.rb
11
+ examples/hello_ncurses.rb
12
+ examples/LICENSES_for_examples
13
+ examples/rain.rb
14
+ examples/tclock.rb
15
+ examples/read_line.rb
16
+ examples/test_scanw.rb
17
+ extconf.rb
18
+ form_wrap.c
19
+ form_wrap.h
20
+ make_dist.rb
21
+ ncurses_wrap.c
22
+ ncurses_wrap.h
23
+ lib/ncurses.rb
24
+ panel_wrap.c
25
+ panel_wrap.h
26
+ menu_wrap.c
27
+ menu_wrap.h
28
+
@@ -0,0 +1,194 @@
1
+
2
+ SHELL = /bin/sh
3
+
4
+ #### Start of system configuration section. ####
5
+
6
+ srcdir = .
7
+ topdir = /Users/rahul/.rvm/rubies/ruby-1.9.2-head/include/ruby-1.9.1
8
+ hdrdir = /Users/rahul/.rvm/rubies/ruby-1.9.2-head/include/ruby-1.9.1
9
+ arch_hdrdir = /Users/rahul/.rvm/rubies/ruby-1.9.2-head/include/ruby-1.9.1/$(arch)
10
+ VPATH = $(srcdir):$(arch_hdrdir)/ruby:$(hdrdir)/ruby
11
+ prefix = $(DESTDIR)/Users/rahul/.rvm/rubies/ruby-1.9.2-head
12
+ rubylibprefix = $(libdir)/$(RUBY_BASE_NAME)
13
+ exec_prefix = $(prefix)
14
+ vendorhdrdir = $(rubyhdrdir)/vendor_ruby
15
+ sitehdrdir = $(rubyhdrdir)/site_ruby
16
+ rubyhdrdir = $(includedir)/$(RUBY_BASE_NAME)-$(ruby_version)
17
+ vendordir = $(rubylibprefix)/vendor_ruby
18
+ sitedir = $(rubylibprefix)/site_ruby
19
+ ridir = $(datarootdir)/$(RI_BASE_NAME)
20
+ mandir = $(datarootdir)/man
21
+ localedir = $(datarootdir)/locale
22
+ libdir = $(exec_prefix)/lib
23
+ psdir = $(docdir)
24
+ pdfdir = $(docdir)
25
+ dvidir = $(docdir)
26
+ htmldir = $(docdir)
27
+ infodir = $(datarootdir)/info
28
+ docdir = $(datarootdir)/doc/$(PACKAGE)
29
+ oldincludedir = $(DESTDIR)/usr/include
30
+ includedir = $(prefix)/include
31
+ localstatedir = $(prefix)/var
32
+ sharedstatedir = $(prefix)/com
33
+ sysconfdir = $(prefix)/etc
34
+ datadir = $(datarootdir)
35
+ datarootdir = $(prefix)/share
36
+ libexecdir = $(exec_prefix)/libexec
37
+ sbindir = $(exec_prefix)/sbin
38
+ bindir = $(exec_prefix)/bin
39
+ rubylibdir = $(rubylibprefix)/$(ruby_version)
40
+ archdir = $(rubylibdir)/$(arch)
41
+ sitelibdir = $(sitedir)/$(ruby_version)
42
+ sitearchdir = $(sitelibdir)/$(sitearch)
43
+ vendorlibdir = $(vendordir)/$(ruby_version)
44
+ vendorarchdir = $(vendorlibdir)/$(sitearch)
45
+
46
+ CC = gcc
47
+ CXX = g++
48
+ LIBRUBY = $(LIBRUBY_SO)
49
+ LIBRUBY_A = lib$(RUBY_SO_NAME)-static.a
50
+ LIBRUBYARG_SHARED = -l$(RUBY_SO_NAME)
51
+ LIBRUBYARG_STATIC = -l$(RUBY_SO_NAME)-static
52
+ OUTFLAG = -o
53
+ COUTFLAG = -o
54
+
55
+ RUBY_EXTCONF_H =
56
+ cflags = $(optflags) $(debugflags) $(warnflags)
57
+ optflags = -O3
58
+ debugflags = -ggdb
59
+ warnflags = -Wextra -Wno-unused-parameter -Wno-parentheses -Wpointer-arith -Wwrite-strings -Wno-missing-field-initializers -Wshorten-64-to-32 -Wno-long-long
60
+ CFLAGS = -fno-common $(cflags) -fno-common -pipe -g -DNCURSES_OPAQUE=0
61
+ INCFLAGS = -I. -I$(arch_hdrdir) -I$(hdrdir)/ruby/backward -I$(hdrdir) -I$(srcdir)
62
+ DEFS =
63
+ CPPFLAGS = -DHAVE_UNISTD_H -DHAVE_LOCALE_H -DHAVE_NCURSES_H -DHAVE_NEWSCR -DHAVE_TABSIZE -DHAVE_ESCDELAY -DHAVE_KEYBOUND -DHAVE_CURSES_VERSION -DHAVE_TIGETSTR -DHAVE_GETWIN -DHAVE_PUTWIN -DHAVE_UNGETMOUSE -DHAVE_MOUSEMASK -DHAVE_WENCLOSE -DHAVE_MOUSEINTERVAL -DHAVE_WMOUSE_TRAFO -DHAVE_MCPRINT -DHAVE_HAS_KEY -DHAVE_DELSCREEN -DHAVE_DEFINE_KEY -DHAVE_KEYOK -DHAVE_RESIZETERM -DHAVE_USE_DEFAULT_COLORS -DHAVE_USE_EXTENDED_NAMES -DHAVE_WRESIZE -DHAVE_ATTR_ON -DHAVE_ATTR_OFF -DHAVE_ATTR_SET -DHAVE_CHGAT -DHAVE_COLOR_SET -DHAVE_FILTER -DHAVE_INTRFLUSH -DHAVE_MVCHGAT -DHAVE_MVHLINE -DHAVE_MVVLINE -DHAVE_MVWCHGAT -DHAVE_MVWHLINE -DHAVE_MVWVLINE -DHAVE_NOQIFLUSH -DHAVE_PUTP -DHAVE_QIFLUSH -DHAVE_SCR_DUMP -DHAVE_SCR_INIT -DHAVE_SCR_RESTORE -DHAVE_SCR_SET -DHAVE_SLK_ATTR_OFF -DHAVE_SLK_ATTR_ON -DHAVE_SLK_ATTR -DHAVE_SLK_ATTR_SET -DHAVE_SLK_COLOR -DHAVE_TIGETFLAG -DHAVE_TIGETNUM -DHAVE_USE_ENV -DHAVE_VIDATTR -DHAVE_VID_ATTR -DHAVE_WATTR_ON -DHAVE_WATTR_OFF -DHAVE_WATTR_SET -DHAVE_WCHGAT -DHAVE_WCOLOR_SET -DHAVE_GETATTRS -DHAVE_ASSUME_DEFAULT_COLORS -DHAVE_ATTR_GET -DHAVE_PANEL_H -DHAVE_FORM_H -DHAVE_MENU_H -D_XOPEN_SOURCE -D_DARWIN_C_SOURCE $(DEFS) $(cppflags)
64
+ CXXFLAGS = $(CFLAGS) $(cxxflags)
65
+ ldflags = -L.
66
+ dldflags = -Wl,-undefined,dynamic_lookup -Wl,-multiply_defined,suppress -Wl,-flat_namespace
67
+ ARCH_FLAG =
68
+ DLDFLAGS = $(ldflags) $(dldflags)
69
+ LDSHARED = $(CC) -dynamic -bundle
70
+ LDSHAREDXX = $(CXX) -dynamic -bundle
71
+ AR = ar
72
+ EXEEXT =
73
+
74
+ RUBY_BASE_NAME = ruby
75
+ RUBY_INSTALL_NAME = ruby
76
+ RUBY_SO_NAME = ruby.1.9.1
77
+ arch = x86_64-darwin10
78
+ sitearch = $(arch)
79
+ ruby_version = 1.9.1
80
+ ruby = /Users/rahul/.rvm/rubies/ruby-1.9.2-head/bin/ruby
81
+ RUBY = $(ruby)
82
+ RM = rm -f
83
+ RM_RF = $(RUBY) -run -e rm -- -rf
84
+ RMDIRS = $(RUBY) -run -e rmdir -- -p
85
+ MAKEDIRS = /opt/local/bin/gmkdir -p
86
+ INSTALL = /opt/local/bin/ginstall -c
87
+ INSTALL_PROG = $(INSTALL) -m 0755
88
+ INSTALL_DATA = $(INSTALL) -m 644
89
+ COPY = cp
90
+
91
+ #### End of system configuration section. ####
92
+
93
+ preload =
94
+
95
+ libpath = . $(libdir)
96
+ LIBPATH = -L. -L$(libdir)
97
+ DEFFILE =
98
+
99
+ CLEANFILES = mkmf.log
100
+ DISTCLEANFILES =
101
+ DISTCLEANDIRS =
102
+
103
+ extout =
104
+ extout_prefix =
105
+ target_prefix =
106
+ LOCAL_LIBS =
107
+ LIBS = $(LIBRUBYARG_SHARED) -lmenu -lform -lpanel -lncurses -lpthread -ldl -lobjc
108
+ SRCS = form_wrap.c menu_wrap.c ncurses_wrap.c panel_wrap.c
109
+ OBJS = form_wrap.o menu_wrap.o ncurses_wrap.o panel_wrap.o
110
+ TARGET = ncurses_bin
111
+ DLLIB = $(TARGET).bundle
112
+ EXTSTATIC =
113
+ STATIC_LIB =
114
+
115
+ BINDIR = $(bindir)
116
+ RUBYCOMMONDIR = $(sitedir)$(target_prefix)
117
+ RUBYLIBDIR = $(sitelibdir)$(target_prefix)
118
+ RUBYARCHDIR = $(sitearchdir)$(target_prefix)
119
+ HDRDIR = $(rubyhdrdir)/ruby$(target_prefix)
120
+ ARCHHDRDIR = $(rubyhdrdir)/$(arch)/ruby$(target_prefix)
121
+
122
+ TARGET_SO = $(DLLIB)
123
+ CLEANLIBS = $(TARGET).bundle
124
+ CLEANOBJS = *.o *.bak
125
+
126
+ all: $(DLLIB)
127
+ static: $(STATIC_LIB)
128
+ .PHONY: all install static install-so install-rb
129
+ .PHONY: clean clean-so clean-rb
130
+
131
+ clean-rb-default::
132
+ clean-rb::
133
+ clean-so::
134
+ clean: clean-so clean-rb-default clean-rb
135
+ @-$(RM) $(CLEANLIBS) $(CLEANOBJS) $(CLEANFILES)
136
+
137
+ distclean-rb-default::
138
+ distclean-rb::
139
+ distclean-so::
140
+ distclean: clean distclean-so distclean-rb-default distclean-rb
141
+ @-$(RM) Makefile $(RUBY_EXTCONF_H) conftest.* mkmf.log
142
+ @-$(RM) core ruby$(EXEEXT) *~ $(DISTCLEANFILES)
143
+ @-$(RMDIRS) $(DISTCLEANDIRS)
144
+
145
+ realclean: distclean
146
+ install: install-so install-rb
147
+
148
+ install-so: $(RUBYARCHDIR)
149
+ install-so: $(RUBYARCHDIR)/$(DLLIB)
150
+ $(RUBYARCHDIR)/$(DLLIB): $(DLLIB)
151
+ @-$(MAKEDIRS) $(@D)
152
+ $(INSTALL_PROG) $(DLLIB) $(@D)
153
+ install-rb: pre-install-rb install-rb-default
154
+ install-rb-default: pre-install-rb-default
155
+ pre-install-rb: Makefile
156
+ pre-install-rb-default: Makefile
157
+ pre-install-rb-default: $(RUBYLIBDIR)
158
+ install-rb-default: $(RUBYLIBDIR)/ncurses.rb
159
+ $(RUBYLIBDIR)/ncurses.rb: $(srcdir)/lib/ncurses.rb
160
+ @-$(MAKEDIRS) $(@D)
161
+ $(INSTALL_DATA) $(srcdir)/lib/ncurses.rb $(@D)
162
+ $(RUBYARCHDIR):
163
+ $(MAKEDIRS) $@
164
+ $(RUBYLIBDIR):
165
+ $(MAKEDIRS) $@
166
+
167
+ site-install: site-install-so site-install-rb
168
+ site-install-so: install-so
169
+ site-install-rb: install-rb
170
+
171
+ .SUFFIXES: .c .m .cc .cxx .cpp .C .o
172
+
173
+ .cc.o:
174
+ $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $<
175
+
176
+ .cxx.o:
177
+ $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $<
178
+
179
+ .cpp.o:
180
+ $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $<
181
+
182
+ .C.o:
183
+ $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $<
184
+
185
+ .c.o:
186
+ $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -c $<
187
+
188
+ $(DLLIB): $(OBJS) Makefile
189
+ @-$(RM) $(@)
190
+ $(LDSHARED) -o $@ $(OBJS) $(LIBPATH) $(DLDFLAGS) $(LOCAL_LIBS) $(LIBS)
191
+
192
+
193
+
194
+ $(OBJS): $(hdrdir)/ruby.h $(hdrdir)/ruby/defines.h $(arch_hdrdir)/ruby/config.h
data/README ADDED
@@ -0,0 +1,355 @@
1
+ $Id: README,v 1.16 2009/05/03 14:13:27 t-peters Exp $
2
+ ------------------------------------------------------------------------
3
+ This directory contains a ruby module for accessing the FSF's ncurses
4
+ library.
5
+ (C) 2002, 2003, 2004 Tobias Peters <t-peters@users.berlios.de>
6
+ (C) 2004 Simon Kaczor <skaczor@cox.net>
7
+ (C) 2005 2006 Tobias Herzke <t-peters@users.berlios.de>
8
+
9
+ This module is free software; you can redistribute it and/or
10
+ modify it under the terms of the GNU Lesser General Public
11
+ License as published by the Free Software Foundation; either
12
+ version 2 of the License, or (at your option) any later version.
13
+
14
+ This module is distributed in the hope that it will be useful,
15
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
16
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17
+ Lesser General Public License for more details.
18
+
19
+ You should have received a copy of the GNU Lesser General Public
20
+ License along with this module; if not, write to the Free Software
21
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22
+ ------------------------------------------------------------------------
23
+
24
+ Overview
25
+ ========
26
+
27
+ This README file explains how to use the ncurses ruby interface. It is
28
+ assumed that the reader has a rough understanding of what the ncurses
29
+ library is and how to use it from the C language. It then goes into
30
+ detail, explaining what is covered by the ruby interface, and the
31
+ rules that were followed in translating the C interface into a ruby
32
+ interface.
33
+
34
+ This ncurses interface provides access to the functions, macros,
35
+ global variables and constants of the ncurses library. These are
36
+ mapped to a Ruby Module named "Ncurses": Functions and external
37
+ variables are implemented as singleton functions of the Module
38
+ Ncurses.
39
+
40
+ This README is organized into the following parts:
41
+ - Overview
42
+ - Installation and Usage
43
+ - External Variables
44
+ - Constants
45
+ - Functions (and their Interfaces)
46
+ - Module / Class Hierarchie
47
+ - The WINDOW class
48
+ - The panel Library
49
+ - The form Library
50
+ - The menu Library
51
+ - Locale handling
52
+ - Ncurses and Ruby Threads
53
+ - Example programs
54
+
55
+ General Ncurses Literature
56
+ --------------------------
57
+
58
+ If you don't know how to use ncurses from C, then please read an
59
+ introduction to ncurses before continuing with this README. Eric
60
+ Raymond has written an introduction that should be part of the ncurses
61
+ development package installed on your computer.
62
+ If you'd like a gentler introduction, then you have two options:
63
+ (1) there is a part of a chapter in "The Linux Programmer's Guide" dealing
64
+ with ncurses, available from www.tldp.org. It is quite old by now,
65
+ but the ncurses interface has not changed since then, regarding the
66
+ scope of covered functions, so it is still a very good read.
67
+ (2) There is also an up-to-date "NCURSES-Programming-HOWTO" in the HOWTO
68
+ collection of the Linux Documentation Project, also available at
69
+ www.tldp.org, which is worth a read.
70
+
71
+ You will also appreciate the extensive man-pages of ncurses, a useful
72
+ reference while coding.
73
+
74
+
75
+ Installation and Usage
76
+ ======================
77
+
78
+ ruby extconf.rb
79
+ make
80
+ make install
81
+
82
+ In your programs:
83
+ require "ncurses.rb"
84
+
85
+ If your programs use the scanw functions (most unlikely) you will have to
86
+ install the scanf library for ruby (http://www.rubyhacker.com/code/scanf).
87
+
88
+ Most ncurses functions are only available after either Ncurses.initscr or
89
+ Ncurses.newterm has returned successfully.
90
+
91
+ External Variables
92
+ ==================
93
+
94
+ External variables are accessed read-only, by module functions taking no
95
+ arguments. They are spelled exactly like their C counterparts. Sometimes, this
96
+ leads to module functions beginning with an uppercase letter (e.g.
97
+ Ncurses.LINES).
98
+
99
+ One of these external variables, ESCDELAY, is also settable with a ruby method
100
+ (Ncurses.ESCDELAY=).
101
+
102
+ Another external variable, Ncurses.RESIZEDELAY is introduced by this wrapper.
103
+ It contains the maximum milliseconds delay with which terminal resizesings are
104
+ recognized.
105
+
106
+ Constants
107
+ =========
108
+ (static C Preprocessor macros)
109
+
110
+ Constants are implemented as module constants in the Ncurses module, if
111
+ possible. Ruby constants can not start with an underscore, so these constants
112
+ have been renamed (they lost the leading underscore). There are,however,
113
+ module functions with the same name as these constants, that also return
114
+ the constant's value, when invoked (e.g. "Ncurses._ENDLINE" returns the value
115
+ of the constant "Ncurses::ENDLINE", which has the same value as the C constant
116
+ "_ENDLINE").
117
+
118
+ Note: The ncurses macros starting with ACS_ are not constants, their value
119
+ depends on the terminal in use. Nevertheless, they are implemented as
120
+ constants of the Ncurses module, but since they depend on the terminal, they
121
+ are not initialized before initscr() has been called. If you need more than
122
+ one terminal in a single program, you can access the ACS_ values through member
123
+ functions of class SCREEN.
124
+
125
+
126
+ Functions (and their Interfaces)
127
+ ================================
128
+
129
+ Functions (also those only implemented by macros in C) can be accessed
130
+ as module functions of the Module Ncurses. They take exactly the same
131
+ arguments as their C counterparts. Some of the C functions return additional
132
+ arguments through pointer arguments. These are implemented as follows:
133
+
134
+
135
+ Functions expecting pointers to integer types
136
+ ---------------------------------------------
137
+
138
+ When the C-function expects a pointer to int, short, chtype, or attr_type,
139
+ You should use a variable containing an empty array as the argument to the ruby
140
+ function. This is because ruby passes these types (ints) "by value" instead of
141
+ "by reference"; but arrays are passed by reference, so that you can see the
142
+ changes to them.
143
+ Attention: some macro-only functions like getsyx accept variables of type int,
144
+ but, being macros, they write values to their arguments. Thus, they also need
145
+ empty array arguments when called from ruby.
146
+ Example:
147
+ color_pair_number = 4
148
+ foreground_color = []
149
+ background_color = []
150
+ if (Ncurses.pair_content(color_pair_number, foreground_color,
151
+ background_color) != Ncurses::ERR)
152
+ "color pair number #{color_pair_number} contains color number " +
153
+ "#{foreground_color[0]} as the foreground color, and color " +
154
+ "number #{background_color[0]} as the background color")
155
+ end
156
+
157
+ There are 2 functions that read a value from the location pointed to by a
158
+ pointer to int, and store another value at those locations. These functions are
159
+ mouse_trafo and wmouse_trafo. When calling these functions, you have to provide
160
+ 2 arrays, each filled with exacly one Integer. The values contained in these
161
+ arrays will then be changed by the ruby module function.
162
+
163
+
164
+ Functions expecting (non-const) pointers to char
165
+ ------------------------------------------------
166
+
167
+ When the C-function expects a pointer to char, you should use a variable
168
+ containing an empty string as the argument to the ruby function.
169
+ Example:
170
+ line2 = ""
171
+ if (Ncurses.mvwinnstr(Ncurses.stdscr, y=2, x=0, line2,
172
+ Ncurses.getmaxx(Ncurses.stdscr)) == Ncurses::ERR)
173
+ raise "could not scan 3rd line"
174
+ else
175
+ Ncurses.beep if line2.index("|")
176
+ end
177
+ The string that the C function would store at the pointer-to-char location
178
+ will be appended to the given string.
179
+
180
+ Functions expecting const pointers to char do not modify the string they
181
+ receive, you can pass any string to them.
182
+
183
+
184
+
185
+ Functions expecting pointers to structs
186
+ ---------------------------------------------------
187
+
188
+ When the C-function expects a pointer to WINDOW, SCREEN, MEVENT,
189
+ PANEL, FORM, FIELD or FIELDTYPE then simply pass it the corresponding,
190
+ already existing ruby object.
191
+
192
+
193
+ scanf style functions expecting various pointers
194
+ ---------------------------------------------------
195
+
196
+ namely scanw, mvscanw, wscanw, mvwscanw. Use an array after the format string.
197
+ The scanned values will be placed there. Remember, you need scanf for ruby
198
+ installed for these functions to work.
199
+
200
+ Module / Class Hierarchie
201
+ =========================
202
+
203
+ module Ncurses
204
+ class WINDOW; end
205
+ class SCREEN; end
206
+ class MEVENT; end
207
+ module Panel
208
+ class PANEL; end
209
+ end
210
+ module Form
211
+ class FORM; end
212
+ class FIELD; end
213
+ class FIELDTYPE; end
214
+ end
215
+ module Menu
216
+ class MENU; end
217
+ class ITEM; end
218
+ end
219
+ end
220
+
221
+
222
+ The WINDOW class
223
+ ================
224
+
225
+ The class WINDOW implements method_missing and tries to map invoked
226
+ methods to Ncurses module functions using a simple heuristic:
227
+
228
+ If the method name starts with "mv", it looks for a Ncurses module
229
+ function that starts with "mvw", and if it exists, adds itself to the
230
+ argument list and calls this function.
231
+ If no such module function exists, or the name of the invoked method
232
+ does not start with "mv", it looks if there is a module function with
233
+ the name "w" + methodname, and if it exists, adds itself again to the
234
+ argument list and calls this function.
235
+ If this module function did not exist either, then, as a last step, it
236
+ invokes a module function with the same name as the method, adding
237
+ itself to the argument list.
238
+
239
+ Example: If you invoke win.mvaddch(y,x,ch) on an Ncurses::WINDOW
240
+ object, it will delegate the method call to
241
+ Ncurses.mvwaddch(win,y,x,ch).
242
+
243
+ Other examples:
244
+
245
+ win.printw("hello") => Ncurses.wprintw(win, "hello")
246
+
247
+ win.getmaxyx(y=[],
248
+ x=[]) => Ncurses.getmaxyx(win,y,x)
249
+
250
+ win.delwin() => Ncurses.delwin(win) # win cannot be used
251
+ # after this call
252
+
253
+
254
+ The panel Library
255
+ =================
256
+
257
+ The panel library has also been wrapped. All panel functions are
258
+ implemented as module functions of the module Ncurses::Panel.
259
+
260
+ Most of these functions are also implemented as methods of class
261
+ Ncurses::Panel::PANEL, once with their original name and once with the
262
+ subword "panel" and an adjacent underscore removed.
263
+
264
+ The form Library
265
+ ================
266
+
267
+ The form library was wrapped inside the Ncurses:Form module. All
268
+ form functions are implemented as module functions on the module
269
+ Ncurses::Form. In addition, all function for which the first
270
+ parameter is one of the objects are also implemented as an instance
271
+ method of the respective class. For example, instead of calling
272
+ post_form(form), you can use form.post_form().
273
+
274
+ Three objects are defined in the Ncurses:Form module:
275
+ 1. FORM
276
+ 2. FIELD
277
+ 3. FIELDTYPE
278
+
279
+ They are wrapping actual ncurses pointers and should be use whenever a
280
+ pointer to one of these types is expected in function calls.
281
+
282
+ All form constants are defined in the module as Ruby constants with
283
+ the same name as the curses constants.
284
+
285
+ Constructors for FORM, FIELD and FIELDTYPE objects are also provided,
286
+ and they expect the same parameters as new_form, new_field and
287
+ new_fieldtype curses functions.
288
+
289
+ Field validation is implemented using Ruby Proc objects. You must
290
+ provide a Ruby block whenever a function pointer is expected in curses
291
+ function arguments. See the example form2.rb for more details.
292
+
293
+ The functions form_userptr and field_userptr are not supported. Use
294
+ form.user_object and field.user_object to store Ruby objects instead.
295
+
296
+ The menu Library
297
+ ================
298
+
299
+ The menu library was wrapped inside the Ncurses:Menu module. All
300
+ menu functions are implemented as module functions in the module
301
+ Ncurses::Menu. In addition, all functions for which the first
302
+ parameter is one of the objects are also implemented as an instance
303
+ method of the respective class. For example, instead of calling
304
+ post_menu(menu), you can use menu.post_menu().
305
+
306
+ Two objects are defined in the Ncurses:Menu module:
307
+ 1. MENU
308
+ 2. ITEM
309
+
310
+ They are wrapping actual ncurses pointers and should be use whenever a
311
+ pointer to one of these types is expected in function calls.
312
+
313
+ All menu constants are defined in the module as Ruby constants with
314
+ the same name as the curses constants.
315
+
316
+ Constructors for MENU and ITEM objects are also provided, and they
317
+ expect the same parameters as new_menu and new_item curses functions.
318
+
319
+ You must provide a Ruby block whenever a function pointer is expected
320
+ in curses function arguments.
321
+
322
+ The functions menu_userptr and item_userptr are not supported. Use
323
+ menu.user_object and item.user_object to store Ruby objects instead.
324
+
325
+ Locale handling
326
+ ===============
327
+
328
+ The C library function setlocale is not technically an Ncurses function.
329
+ However, it is used by many ncurses programs, and for this purpose,
330
+ a wrapper for this function is also included in ncurses-ruby.
331
+
332
+ The function is implemented as a module function Ncurses.ruby, and
333
+ expects two arguments, an Integer and a String. It returns a string.
334
+ The constants that can be used as the Integer argument are also wrapped
335
+ as constants in the Ncurses module. See the manual page for setlocale
336
+ for documentation of this function.
337
+
338
+ Ncurses and Ruby Threads
339
+ ========================
340
+
341
+ The ncurses library is not thread-safe. Your application must properly
342
+ serialize calls into ncurses.
343
+
344
+ Prior to release 0.9.2, the getch and wgetch calls used to block the
345
+ complete ruby interpreter, all threads. This is no longer so. Other
346
+ threads should now continue to run during blocking calls to getch and
347
+ wgetch.
348
+
349
+ Example programs
350
+ ================
351
+
352
+ Directory "examples" contains a few example programs demonstrating how
353
+ to use the ncurses library with ruby. Be sure to read the file
354
+ "examples/LICENSES_for_examples".
355
+