X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fquick-guide.md;h=eb1a757e8164002ba44eb0be9c01ba231cf05a94;hb=c38d72ed2da6f1c29143e6203f9251c4798fed90;hp=6b336a4c93c078fc7566750322cafc04c1aaf30c;hpb=aa3e82364249e93d05b0c3eed4b050ec5d038478;p=platform%2Fupstream%2Flibxkbcommon.git diff --git a/doc/quick-guide.md b/doc/quick-guide.md index 6b336a4..eb1a757 100644 --- a/doc/quick-guide.md +++ b/doc/quick-guide.md @@ -1,6 +1,6 @@ # Quick Guide -## Intro +## Introduction This document contains a quick walk-through of the often-used parts of the library. We will employ a few use-cases to lead the examples: @@ -16,45 +16,54 @@ the library. We will employ a few use-cases to lead the examples: The snippets are not complete, and some support code is omitted. You can find complete and more complex examples in the source directory: -1. test/interactive-evdev.c contains an interactive evdev client. +1. tools/interactive-evdev.c contains an interactive evdev client. -2. test/interactive-x11.c contains an interactive X11 client. +2. tools/interactive-x11.c contains an interactive X11 client. + +3. tools/interactive-wayland.c contains an interactive Wayland client. Also, the library contains many more functions for examining and using the library context, the keymap and the keyboard state. See the -hyper-linked reference documentation or go through the xkbcommon/*.h -header files for more details. +hyper-linked reference documentation or go through the header files in +xkbcommon/ for more details. ## Code -Before we can do anything interesting, we need a library context. So -let's create one: +Before we can do anything interesting, we need a library context: ~~~{.c} #include - struct xkb_context ctx; + struct xkb_context *ctx; ctx = xkb_context_new(XKB_CONTEXT_NO_FLAGS); if (!ctx) ~~~ -The xkb_context contains the keymap include paths, the log level and +The `xkb_context` contains the keymap include paths, the log level and functions, and other general customizable administrativia. -Next we need to create a keymap, xkb_keymap. There are different ways to -do this. +Next we need to create a keymap, `xkb_keymap`. This is an immutable object +which contains all of the information about the keys, layouts, etc. There +are different ways to do this. If we are an evdev client, we have nothing to go by, so we need to ask the user for his/her keymap preferences (for example, an Icelandic keyboard with a Dvorak layout). The configuration format is commonly called RMLVO (Rules+Model+Layout+Variant+Options), the same format used -by the X server. With it, we can fill a struct called xkb_rule_names; -passing NULL chooses the system's default. +by the X server. With it, we can fill a struct called `xkb_rule_names`; +passing `NULL` chooses the system's default. ~~~{.c} struct xkb_keymap *keymap; - struct xkb_rule_names names = <...>; + /* Example RMLVO for Icelandic Dvorak. */ + struct xkb_rule_names names = { + .rules = NULL, + .model = "pc105", + .layout = "is", + .variant = "dvorak", + .options = "terminate:ctrl_alt_bksp" + }; keymap = xkb_keymap_new_from_names(ctx, &names, XKB_KEYMAP_COMPILE_NO_FLAGS); @@ -65,7 +74,9 @@ If we are a Wayland client, the compositor gives us a string complete with a keymap. In this case, we can create the keymap object like this: ~~~{.c} + /* From the wl_keyboard::keymap event. */ const char *keymap_string = <...>; + struct xkb_keymap *keymap; keymap = xkb_keymap_new_from_string(ctx, keymap_string, XKB_KEYMAP_FORMAT_TEXT_V1, @@ -92,7 +103,8 @@ we will use the core keyboard device: ~~~ Now that we have the keymap, we are ready to handle the keyboard devices. -For each device, we create an xkb_state: +For each device, we create an `xkb_state`, which remembers things like which +keyboard modifiers and LEDs are active: ~~~{.c} struct xkb_state *state; @@ -108,7 +120,7 @@ For X11/XCB clients, this is better: if (!state) ~~~ -When we have an xkb_state for a device, we can start handling key events +When we have an `xkb_state` for a device, we can start handling key events from it. Given a keycode for a key, we can get its keysym: ~~~{.c} @@ -123,7 +135,7 @@ from it. Given a keycode for a key, we can get its keysym: We can see which keysym we got, and get its name: ~~~{.c} - char[64] keysym_name; + char keysym_name[64]; if (keysym == XKB_KEY_Space) @@ -138,7 +150,7 @@ single event can result in multiple keysyms. Here's how to use it: const xkb_keysym_t *keysyms; int num_keysyms; - num_keysyms = xkb_state_key_get_syms(state, keycode); + num_keysyms = xkb_state_key_get_syms(state, keycode, &keysyms); ~~~ We can also get a UTF-8 string representation for this key: @@ -155,7 +167,7 @@ We can also get a UTF-8 string representation for this key: xkb_state_key_get_utf8(state, keycode, buffer, size); ~~~ -Of course, we also need to keep the xkb_state up-to-date with the +Of course, we also need to keep the `xkb_state` up-to-date with the keyboard device, if we want to get the correct keysyms in the future. If we are an evdev client, we must let the library know whether a key @@ -173,7 +185,7 @@ is pressed or released at any given time: The `changed` return value tells us exactly which parts of the state have changed. -If is is a key-repeat event, we can ask the keymap what to do with it: +If it is a key-repeat event, we can ask the keymap what to do with it: ~~~{.c} if ( && !xkb_keymap_key_repeats(keymap, keycode)) @@ -195,7 +207,7 @@ information usually comes in a form of some "state changed" event): event->locked_layout); ~~~ -Now that we have an always-up-to-date xkb_state, we can examine it. +Now that we have an always-up-to-date `xkb_state`, we can examine it. For example, we can check whether the Control modifier is active, or whether the Num Lock LED is active: @@ -208,8 +220,7 @@ whether the Num Lock LED is active: ~~~ -And that's it! When we're finished, we should free the objects we've -created: +And that's it! Eventually, we should free the objects we've created: ~~~{.c} xkb_state_unref(state);