README.md (13466B) - raw
1 $Id: README,v 1.16 2009-05-03 14:13:27 t-peters Exp $y
2
3 This directory contains a ruby module for accessing the FSF's ncurses
4 library.
5
6 * (C) 2002, 2003, 2004 Tobias Peters <t-peters@users.berlios.de>
7 * (C) 2004 Simon Kaczor <skaczor@cox.net>
8 * (C) 2005 2006 Tobias Herzke <t-peters@users.berlios.de>
9 * (C) 2013 2014 Gaute Hope <eg@gaute.vetsj.com>
10 * (C) 2013 2014 Sup developers
11
12 This module is free software; you can redistribute it and/or
13 modify it under the terms of the GNU Lesser General Public
14 License as published by the Free Software Foundation; either
15 version 2 of the License, or (at your option) any later version.
16
17 This module is distributed in the hope that it will be useful,
18 but WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
21
22 You should have received a copy of the GNU Lesser General Public
23 License along with this module; if not, write to the Free Software
24 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25
26
27 # Overview
28
29 This README file explains how to use the `ncurses` ruby interface. It is
30 assumed that the reader has a rough understanding of what the `ncurses`
31 library is and how to use it from the C language. It then goes into
32 detail, explaining what is covered by the ruby interface, and the
33 rules that were followed in translating the C interface into a ruby
34 interface.
35
36 This `ncurses` interface provides access to the functions, macros,
37 global variables and constants of the `ncurses` library. These are
38 mapped to a Ruby Module named `ncurses`: Functions and external
39 variables are implemented as singleton functions of the Module
40 `Ncurses`.
41
42 This README is organized into the following parts:
43 - [Overview](#overview)
44 - [Installation and Usage](#installation-and-usage)
45 - [External Variables](#external-variables)
46 - [Constants](#constants)
47 - [Functions (and their Interfaces)](#functions-and-their-interfaces)
48 - [Module / Class Hierarchy](#module--class-hierarchy)
49 - [The Window class](#the-window-class)
50 - [The Panel Library](#the-panel-library)
51 - [The Form Library](#the-form-library)
52 - [The Menu Library](#the-menu-library)
53 - [Locale handling](#locale-handling)
54 - [Ncurses and Ruby Threads](#ncurses-and-ruby-threads)
55 - [Example programs](#example-programs)
56
57 ## General Ncurses Literature
58
59 If you don't know how to use `ncurses` from C, then please read an
60 introduction to `ncurses` before continuing with this README. Eric
61 Raymond has written an introduction that should be part of the `ncurses`
62 development package installed on your computer.
63
64 If you'd like a gentler introduction, then you have two options:
65
66 1. there is a part of a chapter in "The Linux Programmer's Guide" dealing
67 with `ncurses`, available from www.tldp.org. It is quite old by now,
68 but the `ncurses` interface has not changed since then, regarding the
69 scope of covered functions, so it is still a very good read.
70
71 2. There is also an up-to-date "NCURSES-Programming-HOWTO" in the HOWTO
72 collection of the Linux Documentation Project, also available at
73 www.tldp.org, which is worth a read.
74
75 You will also appreciate the extensive man-pages of `ncurses`, a useful
76 reference while coding.
77
78 ## Installation and Usage
79
80 gem install ncursesw
81
82 Or add to your Gemfile
83
84 gem 'ncursesw'
85
86 If your programs use the `scanw` functions (most unlikely) you will have to
87 install the `scanf` library for ruby (http://www.rubyhacker.com/code/scanf).
88
89 Most `ncurses` functions are only available after either `Ncurses.initscr` or
90 `Ncurses.newterm` has returned successfully.
91
92 ## External Variables
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`, can also be set 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 resizings 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 Functions (also those only implemented by macros in C) can be accessed
129 as module functions of the Module Ncurses. They take exactly the same
130 arguments as their C counterparts. Some of the C functions return additional
131 arguments through pointer arguments. These are implemented as follows:
132
133
134 ## Functions expecting pointers to integer types
135
136 When the C-function expects a pointer to `int`, `short`, `chtype`, or `attr_type`,
137 You should use a variable containing an empty array as the argument to the ruby
138 function. This is because ruby passes these types (`int`) "by value" instead of
139 "by reference"; but arrays are passed by reference, so that you can see the
140 changes to them.
141
142 **Attention:** some macro-only functions like `getsyx` accept variables of type `int`,
143 but, being macros, they write values to their arguments. Thus, they also need
144 empty array arguments when called from ruby.
145
146 Example:
147
148 color_pair_number = 4
149 foreground_color = []
150 background_color = []
151 if (Ncurses.pair_content(color_pair_number, foreground_color,
152 background_color) != Ncurses::ERR)
153 "color pair number #{color_pair_number} contains color number " +
154 "#{foreground_color[0]} as the foreground color, and color " +
155 "number #{background_color[0]} as the background color")
156 end
157
158 There are 2 functions that read a value from the location pointed to by a
159 pointer to int, and store another value at those locations. These functions are
160 `mouse_trafo` and `wmouse_trafo`. When calling these functions, you have to provide
161 2 arrays, each filled with exacly one Integer. The values contained in these
162 arrays will then be changed by the ruby module function.
163
164
165 ## Functions expecting (non-const) pointers to char
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
170 **Example:**
171
172 line2 = ""
173 if (Ncurses.mvwinnstr(Ncurses.stdscr, y=2, x=0, line2,
174 Ncurses.getmaxx(Ncurses.stdscr)) == Ncurses::ERR)
175 raise "could not scan 3rd line"
176 else
177 Ncurses.beep if line2.index("|")
178 end
179
180 The string that the C function would store at the pointer-to-char location
181 will be appended to the given string.
182
183 Functions expecting const pointers to char do not modify the string they
184 receive, you can pass any string to them.
185
186
187 ## Functions expecting pointers to structs
188
189 When the C-function expects a pointer to `WINDOW`, `SCREEN`, `MEVENT`,
190 `PANEL`, `FORM`, `FIELD` or `FIELDTYPE` then simply pass it the corresponding,
191 already existing ruby object.
192
193
194 ## scanf style functions expecting various pointers
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 Hierarchy
201
202 module Ncurses
203 class WINDOW; end
204 class SCREEN; end
205 class MEVENT; end
206 module Panel
207 class PANEL; end
208 end
209 module Form
210 class FORM; end
211 class FIELD; end
212 class FIELDTYPE; end
213 end
214 module Menu
215 class MENU; end
216 class ITEM; end
217 end
218 end
219
220
221 ## The Window class
222
223 The class `WINDOW` implements `method_missing` and tries to map invoked
224 methods to `ncurses` module functions using a simple heuristic:
225
226 If the method name starts with `mv`, it looks for a `ncurses` module
227 function that starts with `mvw`, and if it exists, adds itself to the
228 argument list and calls this function.
229
230 If no such module function exists, or the name of the invoked method
231 does not start with `mv`, it looks if there is a module function with
232 the name `w` + `methodname`, and if it exists, adds itself again to the
233 argument list and calls this function.
234
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 The panel library has also been wrapped. All panel functions are
257 implemented as module functions of the module `Ncurses::Panel`.
258
259 Most of these functions are also implemented as methods of class
260 `Ncurses::Panel::PANEL`, once with their original name and once with the
261 subword `panel` and an adjacent underscore removed.
262
263 ## The Form Library
264
265 The form library was wrapped inside the `Ncurses:Form` module. All
266 form functions are implemented as module functions on the module
267 `Ncurses::Form`. In addition, all function for which the first
268 parameter is one of the objects are also implemented as an instance
269 method of the respective class. For example, instead of calling
270 `post_form(form)`, you can use `form.post_form()`.
271
272 Three objects are defined in the `Ncurses:Form` module:
273
274 1. `FORM`
275 2. `FIELD`
276 3. `FIELDTYPE`
277
278 They are wrapping actual ncurses pointers and should be use whenever a
279 pointer to one of these types is expected in function calls.
280
281 All form constants are defined in the module as Ruby constants with
282 the same name as the `curses` constants.
283
284 Constructors for `FORM`, `FIELD` and `FIELDTYPE` objects are also provided,
285 and they expect the same parameters as `new_form`, `new_field` and
286 `new_fieldtype` `curses` functions.
287
288 Field validation is implemented using Ruby `Proc` objects. You must
289 provide a Ruby block whenever a function pointer is expected in `curses`
290 function arguments. See the example `form2.rb` for more details.
291
292 The functions `form_userptr` and `field_userptr` are not supported. Use
293 `form.user_object` and `field.user_object` to store Ruby objects instead.
294
295 ## The Menu Library
296
297 The menu library was wrapped inside the `Ncurses:Menu` module. All
298 menu functions are implemented as module functions in the module
299 `Ncurses::Menu`. In addition, all functions for which the first
300 parameter is one of the objects, are also implemented as an instance
301 method of the respective class.
302
303 For example, instead of calling `post_menu(menu)`, you can use
304 `menu.post_menu()`.
305
306 Two objects are defined in the `Ncurses:Menu` module:
307
308 1. `MENU`
309 2. `ITEM`
310
311 They are wrapping actual `ncurses` pointers and should be use whenever a
312 pointer to one of these types is expected in function calls.
313
314 All menu constants are defined in the module as Ruby constants with
315 the same name as the `curses` constants.
316
317 Constructors for `MENU` and `ITEM` objects are also provided, and they
318 expect the same parameters as `new_menu` and `new_item` curses functions.
319
320 You must provide a Ruby block whenever a function pointer is expected
321 in `curses` function arguments.
322
323 The functions `menu_userptr` and `item_userptr` are not supported. Use
324 `menu.user_object` and `item.user_object` to store Ruby objects instead.
325
326 ## Locale handling
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 The `ncurses` library is not thread-safe. Your application must properly
341 serialize calls into `ncurses`.
342
343 Prior to release 0.9.2, the `getch` and `wgetch` calls used to block the
344 complete ruby interpreter, all threads. This is no longer so. Other
345 threads should now continue to run during blocking calls to `getch` and
346 `wgetch`.
347
348 ## Example programs
349
350 Directory `examples` contains a few example programs demonstrating how
351 to use the ncurses library with ruby. Be sure to read the file
352 `examples/LICENSES_for_examples`.