{"id":22281614,"url":"https://github.com/rust-x-bindings/rust-xcb","last_synced_at":"2025-04-10T03:49:01.406Z","repository":{"id":37739654,"uuid":"49162998","full_name":"rust-x-bindings/rust-xcb","owner":"rust-x-bindings","description":"Rust bindings and wrapper for XCB.","archived":false,"fork":false,"pushed_at":"2024-12-27T14:03:25.000Z","size":269274,"stargazers_count":167,"open_issues_count":13,"forks_count":66,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-03T02:08:44.268Z","etag":null,"topics":["bindings","rust","xcb"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"mstewartgallus/rust-xcb","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rust-x-bindings.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-06T21:32:55.000Z","updated_at":"2025-03-14T21:48:33.000Z","dependencies_parsed_at":"2024-11-09T22:26:57.931Z","dependency_job_id":"086188c1-9cb9-4603-9f84-9c80c8f0c76e","html_url":"https://github.com/rust-x-bindings/rust-xcb","commit_stats":{"total_commits":505,"total_committers":39,"mean_commits":"12.948717948717949","dds":0.2158415841584158,"last_synced_commit":"5c8e8fd8f7e1af59286e99bd8ead82dfc8f3675a"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-x-bindings%2Frust-xcb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-x-bindings%2Frust-xcb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-x-bindings%2Frust-xcb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-x-bindings%2Frust-xcb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rust-x-bindings","download_url":"https://codeload.github.com/rust-x-bindings/rust-xcb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154995,"owners_count":21056542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bindings","rust","xcb"],"created_at":"2024-12-03T16:19:49.170Z","updated_at":"2025-04-10T03:49:01.382Z","avatar_url":"https://github.com/rust-x-bindings.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rust XCB\n\nRust-XCB is a safe Rust interface to [XCB](http://xcb.freedesktop.org).\nRust-XCB uses under the hood the core XCB functions to connect and communicate\nwith the X server.\n\n__Documentation__:\nhttps://rust-x-bindings.github.io/rust-xcb/xcb/\n\nRust-XCB is constituted of the following components:\n - the core library\n - the X protocol and its extensions (generated from XML)\n\nSee [CONTRIBUTING.md](https://github.com/rust-x-bindings/rust-xcb/blob/main/CONTRIBUTING.md) for contributions.\n\n## The core library\n\nThe main component is the `Connection` class which is used to connect and\ncommunicate to the X server. The `Connection` class wraps calls to the C XCB\nfunctions in a safe to use interface.\n\nIn the new API (`v1.0+`), Rust-XCB takes care of all the heavy lifting of event\nand error resolution, including the handling of the different kinds of event\n(regular events, \"GeGeneric\" events, the specifics about Xkb ...) and present\nthem under a unified and safe to use `enum` instead of requesting the user to\nperform unsafe cast as in the C library.\n\nThe core library also provides many traits that are used in the protocol\nimplementation. e.g. the `BaseEvent` and `BaseError` traits, the `Reply` trait...\nThe `Raw` trait is also provided to convert into and from C event or error types.\n\n## The protocol implementation\n\nThe core X protocol and all the extensions present in XCB are generated from (almost exactly) the same XML\nas the XCB C bindings.\nThe generation is done by the build scripts, entirely written in Rust.\nThe build script do not generate bindings to the C protocol extensions, it\ngenerates directly a safe Rust implementation of the protocol:\n - Simple structures that have the same memory layout than C are translated in\n   Rust directly (e.g. points etc.)\n - More complex structures wrap a slice of raw data and provide accessor methods\n   (`Debug` will still print all the members correctly)\n - The masks use the `bitflags` crate macro\n - The enums are enums!\n - The unions are also enums that carry data\n - The Xids (handles to windows, pixmaps etc.) are type-safe implementations of the `Xid` trait.\n - The requests are structures that serialize themselves when passed to the\n   `Connection`.\n    - Each request has two type of cookie, for checked and unchecked requests.\n      This allows type safe reply fetching and error checking\n - The protocol and each extension provide an `Event` and an `Error` enum,\n   which are unified by the core library.\n\n## API\n\nHere are some highlights of the API.\n\n### Modules\n\nDirectly under the `xcb` crate is the hand-written core library.\nThe core protocol is generated in the `x` module and each extension protocol is also generated in its own module.\n\n### Window creation request\n\n```rust\nlet window: x::Window = conn.generate_id();\n\nconn.send_request(\u0026x::CreateWindow {\n    depth: x::COPY_FROM_PARENT as u8,\n    wid: window,\n    parent: screen.root(),\n    x: 0,\n    y: 0,\n    width: 150,\n    height: 150,\n    border_width: 10,\n    class: x::WindowClass::InputOutput,\n    visual: screen.root_visual(),\n    value_list: \u0026[\n        x::Cw::BackPixel(screen.white_pixel()),\n        x::Cw::EventMask(x::EventMask::EXPOSURE | x::EventMask::KEY_PRESS),\n    ],\n});\n```\n\n### Checked void request\n```rust\n// specific cookie type for the checked request\n// code would not compile with `conn.send_request(..)`\nlet cookie = conn.send_request_checked(\u0026x::MapWindow {window});\n// reports `Ok` or a resolved error enum (e.g. x::Error::Drawable(..))\nconn.check_request(cookie)?;\n```\n\n### Event and error handling\n\nEvents of the core protocol and each activated extension are unified in the `xcb::Event` enum.\nTherefore, all events can be handled in a single match expression.\nMany functions (such as `wait_for_event`) return a `xcb::Result` which allows idiomatic error handling.\n\n```rust\nfn main() -\u003e xcb::Result\u003c()\u003e {\n    // ...\n    loop {\n        match conn.wait_for_event()? {\n            xcb::Event::X(x::Event::KeyPress(key_press)) =\u003e {\n                // do stuff\n            }\n            xcb::Event::Xkb(xkb::Event::MapNotify(ev)) =\u003e {\n                // do other stuff (pass data to xkbcommon for example)\n            }\n            _ =\u003e {}\n        }\n    }\n}\n```\n\n### Debugging\n\nAll types in Rust XCB implement `Debug` in a way that allows recursive debug print.\nE.g. iterators will not print a useless pointer value, but will recurse down to each element.\n\nThere is in addition the optional `\"debug_atom_names\"` cargo feature under which each atom\nwill print its name for easier debugging in some situations.\nFor example, Xinput provide some information about input devices with atom identifiers.\nThis allows you to quickly look-up which atoms you need to intern and seek for.\nE.g. the feature would turn:\n```\nAtom {\n    res_id: 303,\n}\n```\ninto\n```\nAtom(\"Abs Pressure\" ; 303)\n```\n\nThe feature sets global variable to have access to the connection in the `Debug::fmt` call,\nso it should be activated only when needed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-x-bindings%2Frust-xcb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frust-x-bindings%2Frust-xcb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-x-bindings%2Frust-xcb/lists"}