source: libcaca/trunk/ruby/README @ 2023

Last change on this file since 2023 was 2023, checked in by Pascal Terjan, 13 years ago
  • Improve the example in README
File size: 5.3 KB
Line 
1/* $Id$ */ /** \page libcaca-ruby Libcaca ruby bindings
2
3This a Ruby binding for libcucul and libcaca.
4
5There is no real documentation but "methods" on any object should help you :)
6
7The classes available for libcucul are :
8
9- Cucul::Canvas (functions that have a cucul_canvas_t* as first argument)
10
11- Cucul::Dither (functions that have a cucul_dither_t* as first argument)
12
13- Cucul::Font (functions that have a cucul_font_t* as first argument)
14 * The constructor can currently only accept the name of a builtin font
15
16The classes available for libcaca are :
17
18- Caca::Display
19- Caca::Event
20- Caca::Event::Key
21- Caca::Event::Key::Press
22- Caca::Event::Key::Release
23- Caca::Event::Mouse
24- Caca::Event::Mouse::Press
25- Caca::Event::Mouse::Release
26- Caca::Event::Mouse::Motion
27- Caca::Event::Resize
28- Caca::Event::Quit
29
30The character set conversion functions are not available yet in the binding.
31
32I tried to follow Ruby spirit meaning that :
33- most of the methods return self
34- the methods set_foo with only an argument are also available as foo=
35(returning the value instead of self)
36- the methods originally named get_foo are available only as foo
37
38What is currently available is :
39
40\code
41$ irb -rcucul
42irb(main):001:0> Cucul.constants
43=> ["BROWN", "BOLD", "GREEN", "LIGHTMAGENTA", "LIGHTBLUE", "BLINK",
44"MAGENTA", "DEFAULT", "TRANSPARENT", "BLUE", "LIGHTRED", "DARKGRAY",
45"UNDERLINE", "RED", "WHITE", "BLACK", "LIGHTCYAN", "LIGHTGRAY",
46"ITALICS", "CYAN", "YELLOW", "LIGHTGREEN", "Canvas", "Dither", "Font"]
47\endcode
48
49\code
50irb(main):002:0> Cucul::Canvas.methods.sort -
51Cucul::Canvas.ancestors[1].methods
52=> ["export_list", "import_list"]
53\endcode
54
55\code
56irb(main):003:0> Cucul::Canvas.instance_methods.sort -
57Cucul::Canvas.ancestors[1].instance_methods
58=> ["attr=", "blit", "clear", "create_frame", "cursor_x", "cursor_y",
59"dither_bitmap", "draw_box", "draw_circle", "draw_cp437_box", "draw_ellipse",
60"draw_line", "draw_polyline", "draw_thin_box", "draw_thin_ellipse",
61"draw_thin_line", "draw_thin_polyline", "draw_thin_triangle",
62"draw_triangle", "export_memory", "fill_box", "fill_ellipse",
63"fill_triangle", "flip", "flop", "frame=", "frame_count", "frame_name",
64"frame_name=", "free_frame", "get_attr", "get_char", "gotoxy",
65"handle_x", "handle_y", "height", "height=", "import_file",
66"import_memory", "invert", "printf", "put_attr", "put_char", "put_str",
67"rotate_180", "rotate_left", "rotate_right", "set_attr",
68"set_boundaries", "set_color_ansi", "set_color_argb", "set_frame",
69"set_frame_name", "set_handle", "set_height", "set_size", "set_width",
70"stretch_left", "stretch_right", "width", "width="]
71\endcode
72
73\code
74irb(main):004:0> Cucul::Font.methods.sort -
75Cucul::Font.ancestors[1].methods
76=> ["list"]
77\endcode
78
79\code
80irb(main):005:0> Cucul::Font.instance_methods.sort -
81Cucul::Font.ancestors[1].instance_methods
82=> ["blocks", "height", "width"]
83\endcode
84
85\code
86irb(main):006:0> Cucul::Dither.instance_methods.sort -
87Cucul::Dither.ancestors[1].instance_methods
88=> ["algorithm=", "algorithm_list", "antialias=", "antialias_list",
89"brightness=", "charset=", "charset_list", "color=", "color_list",
90"contrast=", "gamma=", "palette=", "set_algorithm", "set_antialias",
91"set_brightness", "set_charset", "set_color", "set_contrast",
92"set_gamma", "set_palette"]
93\endcode
94
95\code
96irb(main):007:0> Caca::Display.instance_methods.sort -
97Caca::Display.ancestors[1].instance_methods
98=> ["get_event", "height", "mouse=", "mouse_x", "mouse_y", "refresh",
99"set_mouse", "set_time", "set_title", "time", "time=", "title=", "width"]
100\endcode
101
102\code
103irb(main):008:0> Caca::Event.constants
104=> ["Key", "Quit", "TYPE", "Mouse", "Resize"]
105\endcode
106
107\code
108irb(main):009:0> Caca::Event::Key.instance_methods - Caca::Event::Key.ancestors[1].instance_methods
109=> ["ch", "utf32", "utf8"]
110\endcode
111
112\code
113irb(main):010:0> Caca::Event::Key.instance_methods - Caca::Event::Mouse.ancestors[1].instance_methods
114=> ["ch", "utf32", "utf8"]
115\endcode
116
117\code
118irb(main):011:0> Caca::Event::Mouse.instance_methods - Caca::Event::Mouse.ancestors[1].instance_methods
119=> ["button", "x", "y"]
120\endcode
121
122\code
123irb(main):018:0> Caca::Event::Resize.instance_methods - Caca::Event::Resize.ancestors[1].instance_methods
124=> ["w", "h"]
125\endcode
126
127And here are sample uses :
128
129\code
130$ ruby -rcucul -e 'c=Cucul::Canvas.new(6, 3).fill_box(0,0,2,2,"#"[0]);
131c2=Cucul::Canvas.new(1, 1).put_str(0,0,"x"); c.blit(1,1,c2); puts
132c.export_memory("irc")'
133###   
134#x#   
135### 
136\endcode
137
138\code
139$ ruby -e 'puts Cucul::Canvas.new(6,3).draw_thin_polyline([[0,0], [0,2],
140[5,2],[0,0]]).export_memory("irc")'
141-.   
142| `. 
143----`-
144\endcode
145
146\code
147$ ruby -rcucul -e 'p Cucul::Canvas.export_list'
148[["caca", "native libcaca format"], ["ansi", "ANSI"], ["utf8", "UTF-8
149with ANSI escape codes"], ["utf8cr", "UTF-8 with ANSI escape codes and
150MS-DOS \\r"], ["html", "HTML"], ["html3", "backwards-compatible HTML"],
151["irc", "IRC with mIRC colours"], ["ps", "PostScript document"], ["svg",
152"SVG vector image"], ["tga", "TGA image"]]
153\endcode
154
155\code
156$ ruby -rcucul -e 'p Cucul::Font.list'
157["Monospace 9", "Monospace Bold 12"]
158\endcode
159
160And now a real one:
161
162\code
163require 'caca'
164c = Cucul::Canvas.new(20,10)
165c.put_str(2, 3, "plop!")
166c.draw_thin_polyline([[0,0], [0,2], [5,2], [0,0]])
167d = Caca::Display.new(c)
168d.title = "Test !"
169d.refresh
170while((e = d.get_event(Caca::Event, -1)) &&
171       ! e.kind_of?(Caca::Event::Quit))
172    p e
173    d.refresh
174end
175\endcode
176
177*/
Note: See TracBrowser for help on using the repository browser.