Please add a small usage example to the README and/or link the API reference

[ell1e]

Dear AccessKit Team, I would like to recommend that you add a small usage example to the README and/or link the API reference. Something where somebody writing a new UI toolkit can quickly get an idea how accessibility events like focus changes and so on are going to be handled with AccessKit. I assume this documentation alredy exists, but just isn't very prominent in the README, which would be nice to change. Thank you for your work!

[ell1e]

For what it's worth, after some more digging the only documentation of the C API I found is the header file itself. I can't currently make out how to use this, with the following things probably being things that would be nice to explain in an example:

• What is a node? I assume some abstract representation of a widget, but making this clear would be nice.

• What is a flow, as used in accesskit_node_set_flow_to?

• Why would an abstract node need to know things like the background color, wouldn't it just be enough if it knows the semantics (e.g. emphasized, if it's a text input or a read-only text label, and so on)?

• Is an accesskit_action something the toolkit is meant to inform the compositor of, or the other way around when something like Orca tries to control the app, or both?

• There seems to be things like node set and node level, I wonder what that is.

• C-specific deployment question: for basic UI libraries like libwayland, libxcb, libinput, and something like accesskit, I expect to be able to do both of the following approaches: 1. just link a specific version, with the understanding if my app is packaged by the distribution, it'll build and link it with a matching version that the distribution ships, and 2. dlopen() whatever library variant in whatever version exists on the current system while manually adapting, since I expect these fundamental libs to do API versioning (that is, append _v2 if a function signature changes, and so on).

  I have doubts this is currently the case for AccessKit, simply because I have full KDE Plasma installed, and it's not there. If it was a fundamental basic UI library to just dlopen() it should ideally be preinstalled with major desktops.

  This is an additional concern with AccessKit specifically since the release seems to be relatively large to ship in terms of download size. Also, rust libraries are still somewhat harder to build for end users that want to build a C/C++ program primarily, and then might need to depend on this library. So they probably wouldn't want to always build it from source either when building a program using it.

I hope some of these questions could be linked in some beginner documentation with C examples from the README. Since so many people are coming from the C/C++ side still, especially even if they're not actually using C/C++ but also not Rust since C is still the main API interop language many know and rely on, I assume this might greatly help adoption if answers to these questions are easy to find.

My apologies if all of this is already trivially available, and I'm just too confused to see it.

[DataTriny]

Hello @ell1e, thank you for reaching out.

There is in fact a link to the examples directory in the README, but you might have missed it since it is at the end of the "How to use in a CMake project" chapter. Examples are too long to fit into the README, but we should move the link to a dedicated chapter.

Unfortunately the state of the project's documentation is very poor at the moment, and documenting the bindings is not my priority. We would like to automatically generate it from the Rust side but haven't found a satisfactory solution to this problem yet.

When it comes to the build process, I clearly favor static linking, but dynamic libraries for Linux can easily be generated with Meson. I can't tell you much on the state of packaging for different Linux distributions but I wouldn't recommend it, especially since we haven't reached 1.0.

[ell1e]

While I can relate to the ease of static linking, many of my programs turn out to be under 10MiB total. So it doesn't really seem an easy sell for such small programs to ship a library that is more than twice as large, simply to reach the accessibility features of the compositor better. That's why I brought up the question of planning to eventually push for it to be pre-installed for any major Wayland desktop as a shared library.

Thanks for the examples link, that seems useful! My apologies for missing that one.

I have a question I suggest you also answer in some prominent section, like in the README, or some overview page in future documentation. SDL2 and many other C libraries expect you to check return values for being null pointers, and can handle out of memory especially on Windows in some way where the application can decide how to proceed without necessarily crashing.

I assume from how the API looks like that accesskit doesn't support this mode of operation. So you should make clear what happens if memory runs out, I assume some sort of _exit(1) or similar, since this isn't what all C libraries do. (I would think the majority I've used actually don't.) Also, this can make bindings from higher level languages with exceptions harder, since they typically may expect an out of memory error to be catchable as well.

Anyway, sorry for the long comments. The project seems exciting, since I've long wondered how to handle accessibility properly in a custom UI toolkit. I hope it succeeds in getting adopted.

[mwcampbell]

Hi @ell1e. Thanks for your interest in AccessKit.

If memory allocation fails, accesskit-c will abort the process with a Rust panic. Panicking on allocation failure is standard behavior for Rust. And it's not even that unusual for C libraries; GLib does it too.

Also, a clarification about the size of the library: The Linux x86-64 shared library is 1.8 MB stripped. We ship our binary builds without stripping because we don't want to compromise your ability to debug the library. But it does make the library look bigger than it actually is when incorporated in a released product. I do think 1.8 MB is a bit large, but that's due to the complexity of the underlying D-Bus protocol on Linux. If I'm ever able to resume my [Newton Wayland-native accessibility project]https://blogs.gnome.org/a11y/2024/06/18/update-on-newton-the-wayland-native-accessibility-project/)(, then we'll have a much simpler interface between the app/toolkit and the compositor.

[ell1e]

Oh, I see, an 1.8MiB size actually sounds quite nice! That's great to hear. Still, I hope shared linking (as a system lib) will be available at some point.

And it's not even that unusual for C libraries; GLib does it too.

Outside of some UI libraries (and certainly not all of them), I rarely see it in the C/C++ realm. So for some somewhat lowlevel helper lib like accesskit, I would personally consider it atypical. Therefore, it's worth pointing out more prominently in the README.

[ell1e]

Actually, one more suggestion for the README:

After more thought, I realized that if I build and run the example, I wouldn't know how to actually verify that it works. Would I run orca, or is there some visual way that shows what's transmitted and with what meta information, or what's the recommended way to try it out? I think that could use some hints in the README as well. This also seems not to be addressed on https://accesskit.dev/ and also not on https://accesskit.dev/how-it-works/ either.

[mwcampbell]

I've always tested the examples by running the relevant screen reader on each platform, so Orca in this case. There's also the Accerciser accessibility testing tool, which @DataTriny has some experience using.

[DataTriny]

Testing instructions are printed on the standard output upon starting the examples:

accesskit-c/examples/sdl/hello_world.c

Line 290 in ac163d1

printf("This example has no visible GUI, and a keyboard interface:\n");