English
资源说明：Interface to ncurses using Ruby FFI (Foreign Function Interface)
= ffi-ncurses
Author: Sean O'Halpin
A pure-ruby wrapper for {http://invisible-island.net/ncurses/ ncursesw
5.x} using the {https://github.com/ffi/ffi ffi} library.
All of the core ncursesw functions are supported along with the Panel
library. The main things left to do are support for the Menu and Form
libraries.
The API is a transliteration of the C API rather than an attempt to
provide an idiomatic Ruby object-oriented API. The intent is to
provide a 'close to the metal' wrapper around the ncurses library upon
which you can build your own abstractions.
Please note that this documentation does not cover individual
ncursesw methods. For that you'll need to refer to existing
ncursesw documentation. For example, to find out about +addstr+,
use:
$ man addstr
One benefit of using a minimal wrapper approach is that you can use
existing examples and man pages to find out how to use the library. To
get an overview of ncurses, use:
$ man ncurses
Having said that, this release also includes a wrapper that emulates
the existing Ncurses library API. To use it, substitute
require 'ffi-ncurses/ncurses'
for
require 'ncurses'
or create a file called 'ncurses.rb' on your +$LOAD_PATH+ ($:) that
requires +ffi-ncurses/ncurses.rb+.
Below you'll find some very preliminary notes on usage. See the
examples directory for real working examples, which among other things
show how to input and output UTF-8, deal with pointers and handle wide
characters.
This version of ffi-ncurses defaults to loading ncursesw, the 'wide
character' version which supports UTF-8 and double width characters.
Tested on Ubuntu 10.04 with ruby1.8.7 and 1.9.2 using ffi (>= 0.6.3)
and JRuby 1.6.4 (head). A previous version of the library was tested
on Mac OS X 10.04. Please let me know if anything has stopped working.
Rubinius is not supported as its FFI does not provide the required
API, especially for dealing with buffers and pointers.
This is still very much a work-in-progress, so expect some rough edges
(and please {https://github.com/seanohalpin/ffi-ncurses/issues report
them}). Having said that, you can do quite a lot with it as it is.
= Install
$ [sudo] gem install ffi-ncurses
= Usage
Load the library with:
require 'ffi-ncurses'
FFI::NCurses methods can be called as module methods:
begin
FFI::NCurses.initscr
FFI::NCurses.clear
FFI::NCurses.addstr("Hello world!")
FFI::NCurses.refresh
FFI::NCurses.getch
ensure
FFI::NCurses.endwin
end
or as included methods:
include FFI::NCurses
begin
initscr
cbreak
noecho
curs_set 0
clear
move 10, 10
standout
addstr("Hi!")
standend
refresh
getch
ensure
endwin
end
== Set up screen
require 'ffi-ncurses'
FFI::NCurses.initscr
begin
...
ensure
FFI::NCurses.endwin
end
== Typical initialization
FFI::NCurses.initscr
FFI::NCurses.start_color
FFI::NCurses.curs_set 0
FFI::NCurses.raw
FFI::NCurses.noecho
FFI::NCurses.keypad(FFI::NCurses.stdscr, true)
== Colours
start_color
init_pair(1, FFI::NCurses::COLOR_BLACK, FFI::NCurses::COLOR_RED)
attr_set FFI::NCurses::A_NORMAL, 1, nil
addch("A"[0].ord) # works in both 1.8.7 and 1.9.x
addch("Z"[0].ord | COLOR_PAIR(1))
See +examples/color.rb+ for an example of use.
== Cursor
=== Turn cursor off
FFI::NCurses.curs_set 0
=== Turn cursor on
FFI::NCurses.curs_set 1
== Windows
require 'ffi-ncurses'
include FFI::NCurses
begin
initscr
win = newwin(6, 12, 15, 15)
box(win, 0, 0)
inner_win = newwin(4, 10, 16, 16)
waddstr(inner_win, (["Hello!"] * 5).join(' '))
wrefresh(win)
wrefresh(inner_win)
ch = wgetch(inner_win)
delwin(win)
rescue => e
FFI::NCurses.endwin
raise
ensure
FFI::NCurses.endwin
end
== Panels
See +examples/panel_simple.rb+ for how to use panels.
== Mouse handling
NOTE: In previous versions of ffi-ncurses, the ncurses mouse API was
included separately. You now no longer need to require
'ffi-ncurses/mouse' to get mouse support.
To use the mouse with ffi-ncurses, you first need to specify that you
want keypad translation with:
keypad stdscr, true
otherwise your program will receive the raw mouse escape codes,
instead of +KEY_MOUSE+ mouse event codes.
Specify which events you want to handle with:
mousemask(ALL_MOUSE_EVENTS | REPORT_MOUSE_POSITION, nil)
and set up a mouse event structure to receive the returned values:
mouse_event = FFI::NCurses::MEVENT.new
Receiving mouse events is a two-stage process: first, you are notified
that a mouse event has taken place through a special key code, then
you retrieve the event using +getmouse+. For example:
ch = getch
case ch
when FFI::NCurses::KEY_MOUSE
if getmouse(mouse_event) == FFI::NCurses::OK
The mouse event contains the button state (+bstate+) and x, y
coordinates. You can test for the button state using:
if mouse_event[:bstate] & FFI::NCurses::BUTTON1_PRESSED
or
if FFI::NCurses.BUTTON_PRESS(mouse_event[:bstate], 1)
The possible button states are: +PRESS+, +RELEASE+, +CLICK+,
+DOUBLE_CLICK+ and +TRIPLE_CLICK+.
See +examples/mouse.rb+ for a complete example.
== Specifying which curses library to use
You can specify which variant of curses you want to use by setting the
environment variable +RUBY_FFI_NCURSES_LIB+ to the one you want. For
example, to use the PDCurses X11 curses lib, use:
RUBY_FFI_NCURSES_LIB=XCurses ruby examples/example.rb
You could also use this to specify ncursesw-dbg for example to get
access to the +trace+ functions.
= Examples
+examples/acs_chars.rb+ :: How to display box drawing characters
+examples/attributes.rb+ :: How to set attributes
+examples/color.rb+ :: How to initialize and use colour
+examples/cursor.rb+ :: How to turn the cursor on and off
+examples/doc-eg1.rb+ :: Example 1 from the documentation
+examples/doc-eg2.rb+ :: Example 2 from the documentation
+examples/doc-eg3.rb+ :: Example 3 from the documentation
+examples/example.rb+ :: An example showing off the main features of ncurses
+examples/getkey.rb+ :: How to get Unicode input
+examples/getsetsyx.rb+ :: Shows how to use the getsetyx function
+examples/globals.rb+ :: Display ncurses global variables
+examples/hello.rb+ :: Hello world
+examples/hellowide.rb+ :: Hello world using wide characters
+examples/keys.rb+ :: How to use the getch function. See getkey for a more general solution
+examples/mouse.rb+ :: How to use the mouse
+examples/multiterm.rb+ :: How to display on more than one tty
+examples/newterm.rb+ :: How to use +newterm+ so you can pipe stdin into an ncurses program
+examples/panel_simple.rb+ :: How to use panels
+examples/printw-variadic.rb+:: How to call the +printw+ method
+examples/ripoffline.rb+ :: An example of the +ripoffline+ method
+examples/softkeys.rb+ :: How to set up soft keys (function key labels)
+examples/stdscr.rb+ :: Shows that +initscr+ returns same value as +stdscr+
+examples/temp_leave.rb+ :: How to temporarily shell out from an ncurses program
+examples/viewer.rb+ :: A simple file viewer (lesser than less) that shows how to use pads and pop up windows
+examples/wacs_chars.rb+ :: How to display wide (Unicode) box drawing characters
+examples/windows.rb+ :: Move a window about the screen
= Issues
Please report any issues on the {https://github.com/seanohalpin/ffi-ncurses/issues github issues} page.
= Trivia
While researching ncurses on Google, I innocently entered "curses
getsx" as a search term. NSFW and definitely not one for "I'm Feeling
Lucky".
= TO DO
== Tests
This is tricky - I'm not sure exactly how to properly test a wrapper
for a library like ncurses. I certainly don't want to test ncurses!
Instead, I want to ensure my wrapper faithfully reproduces the
functionality of the platform's ncurses lib. To that end, I'm
experimenting with a simple DSL to generate both C and Ruby versions
of a test. With that I can generate equivalent programs and compare
the output. However, this is not really ready for prime time yet.
== Tidy up internals and examples
Things got a bit messy as I switched between the Linux and Mac
versions. The examples should be more focussed.
= Credits
Thanks to rahul and manveru for their support!
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
