ncursesw 1.4.8 → 1.4.9

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.
Files changed (7) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +352 -0
  3. metadata +5 -26
  4. checksums.yaml.gz.sig +0 -0
  5. data.tar.gz.sig +0 -1
  6. data/README +0 -357
  7. metadata.gz.sig +0 -0
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 3b9cbd26a49c5909011d8abab8f6d40c451fe805
4
- data.tar.gz: bd48b83e93ae7a2b5d23383c622dc472b595e911
3
+ metadata.gz: fca9709dd82761c91ed68a7fa83f68447578ecae
4
+ data.tar.gz: c70bb1b07d1d47a96ec380660f32cf2c8cbf4a47
5
5
  SHA512:
6
- metadata.gz: 36bef0f00c21e095842efd458c2beb41468b55f0f977a4dac1dd7195f94a6387aef6cd2fdf7c9cc10351156f6c872b66ce05479334a7e97dc19a47c889457a84
7
- data.tar.gz: c6f4df3b104312ed6a2c8455cd1f7d5001c9762b08fae6f09e6a73042cfe0a74a524379608bdee0b2fefed57ef8bed45343ff77174d4bb3b8c5f3db9469db8ae
6
+ metadata.gz: 4bec4cb14cf4cd128959ec2ac2571d4116ce2fc86a35912721d727b60de45f8384449428c5661c376c4c3b22a0d4960026ae967374ea274c4a6278bbe15d61a2
7
+ data.tar.gz: 0bc200eb0ef8ffc80b9f0938296f72b228a892dd6db8d03515e78315040bda05a4c78f3f37cb466345482051a520cbce6ae5b6a79212a25c6aebdd091756ed9b
@@ -0,0 +1,352 @@
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`.
metadata CHANGED
@@ -1,40 +1,19 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ncursesw
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.4.8
4
+ version: 1.4.9
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tobias Herzke
8
8
  - Sup developers
9
9
  autorequire:
10
10
  bindir: bin
11
- cert_chain:
12
- - |
13
- -----BEGIN CERTIFICATE-----
14
- MIIDVDCCAjygAwIBAgIBADANBgkqhkiG9w0BAQUFADBQMQswCQYDVQQDDAJlZzEV
15
- MBMGCgmSJomT8ixkARkWBWdhdXRlMRUwEwYKCZImiZPyLGQBGRYFdmV0c2oxEzAR
16
- BgoJkiaJk/IsZAEZFgNjb20wHhcNMTMwNTA4MTAzODQ3WhcNMTQwNTA4MTAzODQ3
17
- WjBQMQswCQYDVQQDDAJlZzEVMBMGCgmSJomT8ixkARkWBWdhdXRlMRUwEwYKCZIm
18
- iZPyLGQBGRYFdmV0c2oxEzARBgoJkiaJk/IsZAEZFgNjb20wggEiMA0GCSqGSIb3
19
- DQEBAQUAA4IBDwAwggEKAoIBAQC7sNc5zY4MrYB7eywE/aK2IoDqpM9lq4ZFlHzt
20
- Pmq1LG6ah2lu/HfjqxiPoqwY7QkdSOGDLSk7G8YBqDA/tODhkPPSTqxBDzYyCO46
21
- haWTtoN5tJkxIDJKp1nVXHi0Mlb4GJVKd9P0q95BeBYBfs8vyPN+y4b4Gebgx9U3
22
- KqMDbe5h9MAPZGmtiRFMb3ugmiujDm7v8fACa5EtSvK/lxMkRDglecT/knE99NYI
23
- l35SO/Bune1bxYmkwW64mQ4wRlGVeAnX+19msALfS9rdJL26dfW2LgqWi5QoVTBH
24
- KNKTl/i3fxK0mzgtnoRCWdMJQFNNonFTnPUUawi1c9Kh4AdPAgMBAAGjOTA3MAkG
25
- A1UdEwQCMAAwHQYDVR0OBBYEFJNCOxL0SWcbW2M+DIEUzAMz1bZsMAsGA1UdDwQE
26
- AwIEsDANBgkqhkiG9w0BAQUFAAOCAQEAr3QUayd0geBDExO+WwzaEPAuUZ3zWQYG
27
- G9vrplCkmJtjS/X/wVAef7Jn/V5MNkXKXsiOgXJXki+n7HulNZUf1rzr7Un96gVJ
28
- 1hq/ZTuapnPpstBqqdv60RB8HNGydHQeEz6us5z3nj+KchPqJ657Dz8oX/Nm6/24
29
- 7QSQpCh8xBYdSWEpoIE0zUSY77LtVTRVwIr9uDpWTTr9kCVBINBsOQNjWKruEWjV
30
- +JMuDs+iWefpF4R3BySoOc1Q4WoES3+oc0qo37MsAZyfnQIPTZkyLZCMxeL6Mha4
31
- hFc2yANBj8voaY5C74Cg2VqExtcnSaxUtW9wC4w5hOlg0AVfb1JWzg==
32
- -----END CERTIFICATE-----
33
- date: 2014-04-24 00:00:00.000000000 Z
11
+ cert_chain: []
12
+ date: 2014-07-05 00:00:00.000000000 Z
34
13
  dependencies: []
35
14
  description: Tweaked version of ncursesw from http://ncurses-ruby.berlios.de/.
36
15
  email:
37
- - sup-talk@rubyforge.org
16
+ - supmua@googlegroups.com
38
17
  executables: []
39
18
  extensions:
40
19
  - extconf.rb
@@ -42,7 +21,7 @@ extra_rdoc_files: []
42
21
  files:
43
22
  - COPYING
44
23
  - Changes
45
- - README
24
+ - README.md
46
25
  - THANKS
47
26
  - TODO
48
27
  - compat.h
Binary file
data.tar.gz.sig DELETED
@@ -1 +0,0 @@
1
- `�T0�`-E!.�:蕯��z� �0c>#���>`/�t^�Y�jM�7�fRM�˜��+^|@��5}�!ዃ٢�cPG4���H:))C����s�Pm�Q���ܐ��/d�����_��l�@��f��y����+۾�<s�p_J�\!p�ۓ�S��f���X� j����>n�������J�rVO�]N)/B��ܫ�}0��!h5֣�S
data/README DELETED
@@ -1,357 +0,0 @@
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
- (C) 2013 2014 Gaute Hope <eg@gaute.vetsj.com>
9
- (C) 2013 2014 Sup developers
10
-
11
- This module is free software; you can redistribute it and/or
12
- modify it under the terms of the GNU Lesser General Public
13
- License as published by the Free Software Foundation; either
14
- version 2 of the License, or (at your option) any later version.
15
-
16
- This module is distributed in the hope that it will be useful,
17
- but WITHOUT ANY WARRANTY; without even the implied warranty of
18
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19
- Lesser General Public License for more details.
20
-
21
- You should have received a copy of the GNU Lesser General Public
22
- License along with this module; if not, write to the Free Software
23
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24
- ------------------------------------------------------------------------
25
-
26
- Overview
27
- ========
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
44
- - Installation and Usage
45
- - External Variables
46
- - Constants
47
- - Functions (and their Interfaces)
48
- - Module / Class Hierarchie
49
- - The WINDOW class
50
- - The panel Library
51
- - The form Library
52
- - The menu Library
53
- - Locale handling
54
- - Ncurses and Ruby Threads
55
- - Example programs
56
-
57
- General Ncurses Literature
58
- --------------------------
59
-
60
- If you don't know how to use ncurses from C, then please read an
61
- introduction to ncurses before continuing with this README. Eric
62
- Raymond has written an introduction that should be part of the ncurses
63
- development package installed on your computer.
64
- If you'd like a gentler introduction, then you have two options:
65
- (1) there is a part of a chapter in "The Linux Programmer's Guide" dealing
66
- with ncurses, available from www.tldp.org. It is quite old by now,
67
- but the ncurses interface has not changed since then, regarding the
68
- scope of covered functions, so it is still a very good read.
69
- (2) There is also an up-to-date "NCURSES-Programming-HOWTO" in the HOWTO
70
- collection of the Linux Documentation Project, also available at
71
- www.tldp.org, which is worth a read.
72
-
73
- You will also appreciate the extensive man-pages of ncurses, a useful
74
- reference while coding.
75
-
76
-
77
- Installation and Usage
78
- ======================
79
-
80
- ruby extconf.rb
81
- make
82
- make install
83
-
84
- In your programs:
85
- require "ncurses.rb"
86
-
87
- If your programs use the scanw functions (most unlikely) you will have to
88
- install the scanf library for ruby (http://www.rubyhacker.com/code/scanf).
89
-
90
- Most ncurses functions are only available after either Ncurses.initscr or
91
- Ncurses.newterm has returned successfully.
92
-
93
- External Variables
94
- ==================
95
-
96
- External variables are accessed read-only, by module functions taking no
97
- arguments. They are spelled exactly like their C counterparts. Sometimes, this
98
- leads to module functions beginning with an uppercase letter (e.g.
99
- Ncurses.LINES).
100
-
101
- One of these external variables, ESCDELAY, is also settable with a ruby method
102
- (Ncurses.ESCDELAY=).
103
-
104
- Another external variable, Ncurses.RESIZEDELAY is introduced by this wrapper.
105
- It contains the maximum milliseconds delay with which terminal resizesings are
106
- recognized.
107
-
108
- Constants
109
- =========
110
- (static C Preprocessor macros)
111
-
112
- Constants are implemented as module constants in the Ncurses module, if
113
- possible. Ruby constants can not start with an underscore, so these constants
114
- have been renamed (they lost the leading underscore). There are,however,
115
- module functions with the same name as these constants, that also return
116
- the constant's value, when invoked (e.g. "Ncurses._ENDLINE" returns the value
117
- of the constant "Ncurses::ENDLINE", which has the same value as the C constant
118
- "_ENDLINE").
119
-
120
- Note: The ncurses macros starting with ACS_ are not constants, their value
121
- depends on the terminal in use. Nevertheless, they are implemented as
122
- constants of the Ncurses module, but since they depend on the terminal, they
123
- are not initialized before initscr() has been called. If you need more than
124
- one terminal in a single program, you can access the ACS_ values through member
125
- functions of class SCREEN.
126
-
127
-
128
- Functions (and their Interfaces)
129
- ================================
130
-
131
- Functions (also those only implemented by macros in C) can be accessed
132
- as module functions of the Module Ncurses. They take exactly the same
133
- arguments as their C counterparts. Some of the C functions return additional
134
- arguments through pointer arguments. These are implemented as follows:
135
-
136
-
137
- Functions expecting pointers to integer types
138
- ---------------------------------------------
139
-
140
- When the C-function expects a pointer to int, short, chtype, or attr_type,
141
- You should use a variable containing an empty array as the argument to the ruby
142
- function. This is because ruby passes these types (ints) "by value" instead of
143
- "by reference"; but arrays are passed by reference, so that you can see the
144
- changes to them.
145
- Attention: some macro-only functions like getsyx accept variables of type int,
146
- but, being macros, they write values to their arguments. Thus, they also need
147
- empty array arguments when called from ruby.
148
- Example:
149
- color_pair_number = 4
150
- foreground_color = []
151
- background_color = []
152
- if (Ncurses.pair_content(color_pair_number, foreground_color,
153
- background_color) != Ncurses::ERR)
154
- "color pair number #{color_pair_number} contains color number " +
155
- "#{foreground_color[0]} as the foreground color, and color " +
156
- "number #{background_color[0]} as the background color")
157
- end
158
-
159
- There are 2 functions that read a value from the location pointed to by a
160
- pointer to int, and store another value at those locations. These functions are
161
- mouse_trafo and wmouse_trafo. When calling these functions, you have to provide
162
- 2 arrays, each filled with exacly one Integer. The values contained in these
163
- arrays will then be changed by the ruby module function.
164
-
165
-
166
- Functions expecting (non-const) pointers to char
167
- ------------------------------------------------
168
-
169
- When the C-function expects a pointer to char, you should use a variable
170
- containing an empty string as the argument to the ruby function.
171
- Example:
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
- The string that the C function would store at the pointer-to-char location
180
- will be appended to the given string.
181
-
182
- Functions expecting const pointers to char do not modify the string they
183
- receive, you can pass any string to them.
184
-
185
-
186
-
187
- Functions expecting pointers to structs
188
- ---------------------------------------------------
189
-
190
- When the C-function expects a pointer to WINDOW, SCREEN, MEVENT,
191
- PANEL, FORM, FIELD or FIELDTYPE then simply pass it the corresponding,
192
- already existing ruby object.
193
-
194
-
195
- scanf style functions expecting various pointers
196
- ---------------------------------------------------
197
-
198
- namely scanw, mvscanw, wscanw, mvwscanw. Use an array after the format string.
199
- The scanned values will be placed there. Remember, you need scanf for ruby
200
- installed for these functions to work.
201
-
202
- Module / Class Hierarchie
203
- =========================
204
-
205
- module Ncurses
206
- class WINDOW; end
207
- class SCREEN; end
208
- class MEVENT; end
209
- module Panel
210
- class PANEL; end
211
- end
212
- module Form
213
- class FORM; end
214
- class FIELD; end
215
- class FIELDTYPE; end
216
- end
217
- module Menu
218
- class MENU; end
219
- class ITEM; end
220
- end
221
- end
222
-
223
-
224
- The WINDOW class
225
- ================
226
-
227
- The class WINDOW implements method_missing and tries to map invoked
228
- methods to Ncurses module functions using a simple heuristic:
229
-
230
- If the method name starts with "mv", it looks for a Ncurses module
231
- function that starts with "mvw", and if it exists, adds itself to the
232
- argument list and calls this function.
233
- If no such module function exists, or the name of the invoked method
234
- does not start with "mv", it looks if there is a module function with
235
- the name "w" + methodname, and if it exists, adds itself again to the
236
- argument list and calls this function.
237
- If this module function did not exist either, then, as a last step, it
238
- invokes a module function with the same name as the method, adding
239
- itself to the argument list.
240
-
241
- Example: If you invoke win.mvaddch(y,x,ch) on an Ncurses::WINDOW
242
- object, it will delegate the method call to
243
- Ncurses.mvwaddch(win,y,x,ch).
244
-
245
- Other examples:
246
-
247
- win.printw("hello") => Ncurses.wprintw(win, "hello")
248
-
249
- win.getmaxyx(y=[],
250
- x=[]) => Ncurses.getmaxyx(win,y,x)
251
-
252
- win.delwin() => Ncurses.delwin(win) # win cannot be used
253
- # after this call
254
-
255
-
256
- The panel Library
257
- =================
258
-
259
- The panel library has also been wrapped. All panel functions are
260
- implemented as module functions of the module Ncurses::Panel.
261
-
262
- Most of these functions are also implemented as methods of class
263
- Ncurses::Panel::PANEL, once with their original name and once with the
264
- subword "panel" and an adjacent underscore removed.
265
-
266
- The form Library
267
- ================
268
-
269
- The form library was wrapped inside the Ncurses:Form module. All
270
- form functions are implemented as module functions on the module
271
- Ncurses::Form. In addition, all function for which the first
272
- parameter is one of the objects are also implemented as an instance
273
- method of the respective class. For example, instead of calling
274
- post_form(form), you can use form.post_form().
275
-
276
- Three objects are defined in the Ncurses:Form module:
277
- 1. FORM
278
- 2. FIELD
279
- 3. FIELDTYPE
280
-
281
- They are wrapping actual ncurses pointers and should be use whenever a
282
- pointer to one of these types is expected in function calls.
283
-
284
- All form constants are defined in the module as Ruby constants with
285
- the same name as the curses constants.
286
-
287
- Constructors for FORM, FIELD and FIELDTYPE objects are also provided,
288
- and they expect the same parameters as new_form, new_field and
289
- new_fieldtype curses functions.
290
-
291
- Field validation is implemented using Ruby Proc objects. You must
292
- provide a Ruby block whenever a function pointer is expected in curses
293
- function arguments. See the example form2.rb for more details.
294
-
295
- The functions form_userptr and field_userptr are not supported. Use
296
- form.user_object and field.user_object to store Ruby objects instead.
297
-
298
- The menu Library
299
- ================
300
-
301
- The menu library was wrapped inside the Ncurses:Menu module. All
302
- menu functions are implemented as module functions in the module
303
- Ncurses::Menu. In addition, all functions for which the first
304
- parameter is one of the objects are also implemented as an instance
305
- method of the respective class. For example, instead of calling
306
- post_menu(menu), you can use menu.post_menu().
307
-
308
- Two objects are defined in the Ncurses:Menu module:
309
- 1. MENU
310
- 2. ITEM
311
-
312
- They are wrapping actual ncurses pointers and should be use whenever a
313
- pointer to one of these types is expected in function calls.
314
-
315
- All menu constants are defined in the module as Ruby constants with
316
- the same name as the curses constants.
317
-
318
- Constructors for MENU and ITEM objects are also provided, and they
319
- expect the same parameters as new_menu and new_item curses functions.
320
-
321
- You must provide a Ruby block whenever a function pointer is expected
322
- in curses function arguments.
323
-
324
- The functions menu_userptr and item_userptr are not supported. Use
325
- menu.user_object and item.user_object to store Ruby objects instead.
326
-
327
- Locale handling
328
- ===============
329
-
330
- The C library function setlocale is not technically an Ncurses function.
331
- However, it is used by many ncurses programs, and for this purpose,
332
- a wrapper for this function is also included in ncurses-ruby.
333
-
334
- The function is implemented as a module function Ncurses.ruby, and
335
- expects two arguments, an Integer and a String. It returns a string.
336
- The constants that can be used as the Integer argument are also wrapped
337
- as constants in the Ncurses module. See the manual page for setlocale
338
- for documentation of this function.
339
-
340
- Ncurses and Ruby Threads
341
- ========================
342
-
343
- The ncurses library is not thread-safe. Your application must properly
344
- serialize calls into ncurses.
345
-
346
- Prior to release 0.9.2, the getch and wgetch calls used to block the
347
- complete ruby interpreter, all threads. This is no longer so. Other
348
- threads should now continue to run during blocking calls to getch and
349
- wgetch.
350
-
351
- Example programs
352
- ================
353
-
354
- Directory "examples" contains a few example programs demonstrating how
355
- to use the ncurses library with ruby. Be sure to read the file
356
- "examples/LICENSES_for_examples".
357
-
metadata.gz.sig DELETED
Binary file