CI: Use git master for xkeyboard-config on Linux

[platform/upstream/libxkbcommon.git] / doc / quick-guide.md

diff --git a/doc/quick-guide.md b/doc/quick-guide.md
index ca62be1..eb1a757 100644 (file)
--- a/doc/quick-guide.md
+++ b/doc/quick-guide.md
@@ -1,6 +1,6 @@
 # Quick Guide
 
 # 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:
 
 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,9 +16,11 @@ 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:
 
 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
 
 Also, the library contains many more functions for examining and using
 the library context, the keymap and the keyboard state. See the


@@ -27,34 +29,41 @@ xkbcommon/ for more details.
 
 ## Code
 
 
 ## 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 <xkbcommon/xkbcommon.h>
 
 
 ~~~{.c}
     #include <xkbcommon/xkbcommon.h>
 

-    struct xkb_context ctx;
+    struct xkb_context *ctx;

 
     ctx = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
     if (!ctx) <error>
 ~~~
 
 
     ctx = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
     if (!ctx) <error>
 ~~~
 

-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.
 
 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
 
 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;
 
 ~~~{.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);
 
     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}
 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 = <...>;
     const char *keymap_string = <...>;

+    struct xkb_keymap *keymap;

 
     keymap = xkb_keymap_new_from_string(ctx, keymap_string,
                                         XKB_KEYMAP_FORMAT_TEXT_V1,
 
     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.
 ~~~
 
 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;
 
 ~~~{.c}
     struct xkb_state *state;


@@ -108,7 +120,7 @@ For X11/XCB clients, this is better:
     if (!state) <error>
 ~~~
 
     if (!state) <error>
 ~~~
 

-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}
 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}
 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)
         <got a space>
 
     if (keysym == XKB_KEY_Space)
         <got a 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;
 
     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:
 ~~~
 
 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);
 ~~~
 
     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
 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.
 
 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 (<key repeat> && !xkb_keymap_key_repeats(keymap, keycode))
 
 ~~~{.c}
     if (<key repeat> && !xkb_keymap_key_repeats(keymap, keycode))


@@ -195,7 +207,7 @@ information usually comes in a form of some "state changed" event):
                                     event->locked_layout);
 ~~~
 
                                     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:
 
 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:
         <The Num Lock LED is active>
 ~~~
 
         <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);
 
 ~~~{.c}
     xkb_state_unref(state);