README.md
1# Rust XCB
2
3[![Build Status](https://travis-ci.org/rtbo/rust-xcb.svg?branch=master)](https://travis-ci.org/rtbo/rust-xcb)
4
5Rust-XCB is a set of bindings and wrappers for [XCB](http://xcb.freedesktop.org). It uses the XML
6protocol descriptions from XCB to generate the bindings and the wrappers.
7
8Rust-XCB is only intended as an interface to XCB, so provides nothing above and beyond that.
9
10```toml
11[dependencies]
12xcb = "0.8"
13```
14
15__Documentation__:
16http://rtbo.github.io/rust-xcb/xcb/index.html
17
18## The bindings
19
20The bindings are generated from the `rs_client.py` script with help from the `xcbgen` library (also
21from XCB). The bindings are inside the `ffi` module, which also contains the hand-written bindings
22to the core library.
23
24Bindings reflect the C API almost one for one.
25
26## The wrapper
27
28The wrappers are generated from the same files, and provide a safe and more convenient wrapper over
29the low-level bindings by having automatic destructors for returned data, trait implementations for
30object "types" and other safe helpers.
31
32## Example
33
34Drawing example (checkout for more [here](https://github.com/rtbo/rust-xcb/tree/master/examples)
35and also [here](https://github.com/rtbo/toy_xcb))
36
37```rust
38extern crate xcb;
39
40fn main() {
41 let points: &[xcb::Point] = &[
42 xcb::Point::new(10, 10),
43 xcb::Point::new(10, 20),
44 xcb::Point::new(20, 10),
45 xcb::Point::new(20, 20),
46 ];
47 let polyline: &[xcb::Point] = &[
48 xcb::Point::new(50, 10 ),
49 xcb::Point::new( 5, 20 ), /* rest of points are relative */
50 xcb::Point::new(25, -20),
51 xcb::Point::new(10, 10 )
52 ];
53 let segments: &[xcb::Segment] = &[
54 xcb::Segment::new(100, 10, 140, 30),
55 xcb::Segment::new(110, 25, 130, 60)
56 ];
57 let rectangles: &[xcb::Rectangle] = &[
58 xcb::Rectangle::new(10, 50, 40, 20),
59 xcb::Rectangle::new(80, 50, 10, 40)
60 ];
61 let arcs: &[xcb::Arc] = &[
62 xcb::Arc::new(10, 100, 60, 40, 0, 90 << 6),
63 xcb::Arc::new(90, 100, 55, 40, 0, 270 << 6)
64 ];
65
66
67 let (conn, screen_num) = xcb::Connection::connect(None).unwrap();
68 let setup = conn.get_setup();
69 let screen = setup.roots().nth(screen_num as usize).unwrap();
70
71 let foreground = conn.generate_id();
72
73 xcb::create_gc(&conn, foreground, screen.root(), &[
74 (xcb::GC_FOREGROUND, screen.black_pixel()),
75 (xcb::GC_GRAPHICS_EXPOSURES, 0),
76 ]);
77
78 let win = conn.generate_id();
79 xcb::create_window(&conn,
80 xcb::COPY_FROM_PARENT as u8,
81 win,
82 screen.root(),
83 0, 0,
84 150, 150,
85 10,
86 xcb::WINDOW_CLASS_INPUT_OUTPUT as u16,
87 screen.root_visual(), &[
88 (xcb::CW_BACK_PIXEL, screen.white_pixel()),
89 (xcb::CW_EVENT_MASK,
90 xcb::EVENT_MASK_EXPOSURE | xcb::EVENT_MASK_KEY_PRESS),
91 ]
92 );
93 xcb::map_window(&conn, win);
94 conn.flush();
95
96
97 loop {
98 let event = conn.wait_for_event();
99 match event {
100 None => { break; }
101 Some(event) => {
102 let r = event.response_type() & !0x80;
103 match r {
104 xcb::EXPOSE => {
105 /* We draw the points */
106 xcb::poly_point(&conn, xcb::COORD_MODE_ORIGIN as u8, win,
107 foreground, &points);
108
109 /* We draw the polygonal line */
110 xcb::poly_line(&conn, xcb::COORD_MODE_PREVIOUS as u8, win,
111 foreground, &polyline);
112
113 /* We draw the segements */
114 xcb::poly_segment(&conn, win, foreground, &segments);
115
116 /* We draw the rectangles */
117 xcb::poly_rectangle(&conn, win, foreground, &rectangles);
118
119 /* We draw the arcs */
120 xcb::poly_arc(&conn, win, foreground, &arcs);
121
122 /* We flush the request */
123 conn.flush();
124
125 },
126 xcb::KEY_PRESS => {
127 let key_press : &xcb::KeyPressEvent = unsafe {
128 xcb::cast_event(&event)
129 };
130 println!("Key '{}' pressed", key_press.detail());
131 break;
132 },
133 _ => {}
134 }
135 }
136 }
137 }
138}
139```
140