[Linuxwacom-devel] [PATCH] xsetwacom: refer KeySyms defined by keysymdef.h in man page

[Ping Cheng]

xsetwacom accepts keys in X11 KeySyms format. To make the interface
user friendly, we mapped a set of modifiers to aliases that can be
recognized by most users. But, there are a few less recognizable or
confusing keys/modifiers left. This patch tells users where to find
the X11 KeySyms code they are looking for.

Return key is added as a bonus (by-product ;).

Signed-off-by: Ping Cheng <***@wacom.com>
Tested-by: Kelly Price <***@gmail.com>
---
man/xsetwacom.man | 13 +++++++------
tools/xsetwacom.c | 4 ++++
2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/man/xsetwacom.man b/man/xsetwacom.man
index 1930d67..8276e32 100644
--- a/man/xsetwacom.man
+++ b/man/xsetwacom.man
@@ -109,17 +109,18 @@ button-number will produce a press of X11 button 3 (i.e. right click).
Action mappings allow button presses to perform many events. They take the form
of a string of keywords and arguments.

-The "key" keyword is following by a list of key names. These can optionally
+The "key" keyword is followed by a list of key names. These can optionally
be preceded by "+" for press and "-" for release. If +/- is not given,
press-and-release is assumed, except for modifier keys which are left pressed.
-Key names can be X11 KeySyms or some aliases such as 'shift' or 'f1' (the
+Key names can be X11 KeySyms code or some aliases such as 'shift' or 'f1' (the
full list can be seen with the
.B list modifiers
-command).
+command). To assign a key that is not in the modifiers list, look for its KeySyms
+code in keysymdef.h under /usr/include/X11 on your system.

-For example, "key +a +shift b -shift -a" converts the button into a series of
-keystrokes, in this example "press a, press shift, press and release b,
-release shift, release a".
+For example, "key +a +shift b -shift -a 0xff0d" converts the button into a
+series of keystrokes, in this example "press a, press shift, press and release b,
+release shift, release a, then enter".

The "button" keyword is similar except that its arguments are X11 button
numbers.
diff --git a/tools/xsetwacom.c b/tools/xsetwacom.c
index 2f75d78..aa5f7a1 100644
--- a/tools/xsetwacom.c
+++ b/tools/xsetwacom.c
@@ -605,6 +605,8 @@ static struct modifier specialkeys[] = {

{"backspace", "BackSpace"}, {"Backspace", "BackSpace"},

+ {"return", "Return"},
+
{"tab", "Tab"},

{"PgUp", "Prior"}, {"PgDn", "Next"},
@@ -937,6 +939,8 @@ static void list_mod(Display *dpy)
m = specialkeys;
while(m->name)
printf(" %s\n", m++->name);
+
+ printf("If you don't see your special key listed above, please use its keysyms code or refer to man page for details.\n");
}

static void list(Display *dpy, int argc, char **argv)

[Peter Hutterer]

Post by Ping Cheng
xsetwacom accepts keys in X11 KeySyms format. To make the interface
user friendly, we mapped a set of modifiers to aliases that can be
recognized by most users. But, there are a few less recognizable or
confusing keys/modifiers left. This patch tells users where to find
the X11 KeySyms code they are looking for.
Return key is added as a bonus (by-product ;).

No, please don't add this in the same patch. it's completely unrelated and
for stable branch cherry-picking, etc. hiding these things in the same patch
is a bad idea.

Golden rule: when you need to write "Also..." in a commit message you
probably need two patches :)

Same goes for typo fixes (which IMO you can just push directly, they're
usually safe anyway).

Post by Ping Cheng
---
man/xsetwacom.man | 13 +++++++------
tools/xsetwacom.c | 4 ++++
2 files changed, 11 insertions(+), 6 deletions(-)
diff --git a/man/xsetwacom.man b/man/xsetwacom.man
index 1930d67..8276e32 100644
--- a/man/xsetwacom.man
+++ b/man/xsetwacom.man
@@ -109,17 +109,18 @@ button-number will produce a press of X11 button 3 (i.e. right click).
Action mappings allow button presses to perform many events. They take the form
of a string of keywords and arguments.
-The "key" keyword is following by a list of key names. These can optionally
+The "key" keyword is followed by a list of key names. These can optionally
be preceded by "+" for press and "-" for release. If +/- is not given,
press-and-release is assumed, except for modifier keys which are left pressed.
-Key names can be X11 KeySyms or some aliases such as 'shift' or 'f1' (the
+Key names can be X11 KeySyms code or some aliases such as 'shift' or 'f1' (the

don't use keysyms code, that's confusing because key code is a specific term
in X.
"Key names can be an X11 KeySym or ...."

Post by Ping Cheng
full list can be seen with the
.B list modifiers
-command).
+command). To assign a key that is not in the modifiers list, look for its KeySyms
+code in keysymdef.h under /usr/include/X11 on your system.

hmm, that makes me wonder why we have special treatment for modifiers. IIRC
they're just special so we can use "shift" instead of "Shift_L". but we
should parse the actual keysym as well. maybe a future patch.
either way:

"To assign a key that is not in the modifiers list use the KeySym in
/usr/include/X11/keysymdef.h with the XK_ prefix removed.
For exampmle, XK_BackSpace should be specified as "BackSpace".
"

Post by Ping Cheng
-For example, "key +a +shift b -shift -a" converts the button into a series of
-keystrokes, in this example "press a, press shift, press and release b,
-release shift, release a".
+For example, "key +a +shift b -shift -a 0xff0d" converts the button into a
+series of keystrokes, in this example "press a, press shift, press and release b,
+release shift, release a, then enter".

whoah, does this actually work? I didn't know that we parsed hex codes
correctly.

Post by Ping Cheng
The "button" keyword is similar except that its arguments are X11 button
numbers.
diff --git a/tools/xsetwacom.c b/tools/xsetwacom.c
index 2f75d78..aa5f7a1 100644
--- a/tools/xsetwacom.c
+++ b/tools/xsetwacom.c
@@ -605,6 +605,8 @@ static struct modifier specialkeys[] = {
{"backspace", "BackSpace"}, {"Backspace", "BackSpace"},
+ {"return", "Return"},
+

as said above, this needs to be a separate patch (feel free to push, no need
for re-review here if it's just that one line anyway). But do make a note
in the commmit message about the "Enter" vs "Return" controversy :)

Post by Ping Cheng
{"tab", "Tab"},
{"PgUp", "Prior"}, {"PgDn", "Next"},
@@ -937,6 +939,8 @@ static void list_mod(Display *dpy)
m = specialkeys;
while(m->name)
printf(" %s\n", m++->name);
+
+ printf("If you don't see your special key listed above, please use its keysyms code or refer to man page for details.\n");

"Keys not listed above can be specified via their KeySym. See the man page
for details."

Cheers,
Peter

Post by Ping Cheng
}
static void list(Display *dpy, int argc, char **argv)
--
1.9.1

------------------------------------------------------------------------------

[Ping Cheng]

On Wed, Aug 3, 2016 at 10:52 PM, Peter Hutterer

Post by Peter Hutterer

Post by Ping Cheng
xsetwacom accepts keys in X11 KeySyms format. To make the interface
user friendly, we mapped a set of modifiers to aliases that can be
recognized by most users. But, there are a few less recognizable or
confusing keys/modifiers left. This patch tells users where to find
the X11 KeySyms code they are looking for.
Return key is added as a bonus (by-product ;).

No, please don't add this in the same patch. it's completely unrelated and
for stable branch cherry-picking, etc. hiding these things in the same patch
is a bad idea.
Golden rule: when you need to write "Also..." in a commit message you
probably need two patches :)
Same goes for typo fixes (which IMO you can just push directly, they're
usually safe anyway).

Post by Ping Cheng
---
man/xsetwacom.man | 13 +++++++------
tools/xsetwacom.c | 4 ++++
2 files changed, 11 insertions(+), 6 deletions(-)
diff --git a/man/xsetwacom.man b/man/xsetwacom.man
index 1930d67..8276e32 100644
--- a/man/xsetwacom.man
+++ b/man/xsetwacom.man
@@ -109,17 +109,18 @@ button-number will produce a press of X11 button 3 (i.e. right click).
Action mappings allow button presses to perform many events. They take the form
of a string of keywords and arguments.
-The "key" keyword is following by a list of key names. These can optionally
+The "key" keyword is followed by a list of key names. These can optionally
be preceded by "+" for press and "-" for release. If +/- is not given,
press-and-release is assumed, except for modifier keys which are left pressed.
-Key names can be X11 KeySyms or some aliases such as 'shift' or 'f1' (the
+Key names can be X11 KeySyms code or some aliases such as 'shift' or 'f1' (the

don't use keysyms code, that's confusing because key code is a specific term
in X.
"Key names can be an X11 KeySym or ...."

Post by Ping Cheng
full list can be seen with the
.B list modifiers
-command).
+command). To assign a key that is not in the modifiers list, look for its KeySyms
+code in keysymdef.h under /usr/include/X11 on your system.

hmm, that makes me wonder why we have special treatment for modifiers. IIRC
they're just special so we can use "shift" instead of "Shift_L". but we
should parse the actual keysym as well. maybe a future patch.

Well, modifier used to mean the key won't do anything by itself until
another(other)
key(s) is pressed. So, modifiers would always have two separate
states: pressed or released.

"Key +shift a -shift" is different from "Key shift a shift"

You made those individual states available to all keys although

"key +a +shift b -shift- a" is the same as "key a +shift b -shift"

With that change, all keys could be treated the same way by xsetwacom.

Post by Peter Hutterer
"To assign a key that is not in the modifiers list use the KeySym in
/usr/include/X11/keysymdef.h with the XK_ prefix removed.
For exampmle, XK_BackSpace should be specified as "BackSpace".

Post by Ping Cheng
-For example, "key +a +shift b -shift -a" converts the button into a series of
-keystrokes, in this example "press a, press shift, press and release b,
-release shift, release a".
+For example, "key +a +shift b -shift -a 0xff0d" converts the button into a
+series of keystrokes, in this example "press a, press shift, press and release b,
+release shift, release a, then enter".

whoah, does this actually work? I didn't know that we parsed hex codes
correctly.

Yeah, it was there at the beginning. Since it was too long ago, we
just forgot what we've done...

Post by Peter Hutterer

Post by Ping Cheng
The "button" keyword is similar except that its arguments are X11 button
numbers.
diff --git a/tools/xsetwacom.c b/tools/xsetwacom.c
index 2f75d78..aa5f7a1 100644
--- a/tools/xsetwacom.c
+++ b/tools/xsetwacom.c
@@ -605,6 +605,8 @@ static struct modifier specialkeys[] = {
{"backspace", "BackSpace"}, {"Backspace", "BackSpace"},
+ {"return", "Return"},
+

as said above, this needs to be a separate patch (feel free to push, no need
for re-review here if it's just that one line anyway). But do make a note
in the commmit message about the "Enter" vs "Return" controversy :)

Done and pushed.

Post by Peter Hutterer

Post by Ping Cheng
{"tab", "Tab"},
{"PgUp", "Prior"}, {"PgDn", "Next"},
@@ -937,6 +939,8 @@ static void list_mod(Display *dpy)
m = specialkeys;
while(m->name)
printf(" %s\n", m++->name);
+
+ printf("If you don't see your special key listed above, please use its keysyms code or refer to man page for details.\n");

"Keys not listed above can be specified via their KeySym. See the man page
for details."

It will be in the updated patch (v2) and posted here for review.

Thank you for your comments.

Ping

------------------------------------------------------------------------------

[Peter Hutterer]

Post by Ping Cheng
On Wed, Aug 3, 2016 at 10:52 PM, Peter Hutterer

Post by Peter Hutterer

Post by Ping Cheng
xsetwacom accepts keys in X11 KeySyms format. To make the interface
user friendly, we mapped a set of modifiers to aliases that can be
recognized by most users. But, there are a few less recognizable or
confusing keys/modifiers left. This patch tells users where to find
the X11 KeySyms code they are looking for.
Return key is added as a bonus (by-product ;).

No, please don't add this in the same patch. it's completely unrelated and
for stable branch cherry-picking, etc. hiding these things in the same patch
is a bad idea.
Golden rule: when you need to write "Also..." in a commit message you
probably need two patches :)
Same goes for typo fixes (which IMO you can just push directly, they're
usually safe anyway).

Post by Ping Cheng
---
man/xsetwacom.man | 13 +++++++------
tools/xsetwacom.c | 4 ++++
2 files changed, 11 insertions(+), 6 deletions(-)
diff --git a/man/xsetwacom.man b/man/xsetwacom.man
index 1930d67..8276e32 100644
--- a/man/xsetwacom.man
+++ b/man/xsetwacom.man
@@ -109,17 +109,18 @@ button-number will produce a press of X11 button 3 (i.e. right click).
Action mappings allow button presses to perform many events. They take the form
of a string of keywords and arguments.
-The "key" keyword is following by a list of key names. These can optionally
+The "key" keyword is followed by a list of key names. These can optionally
be preceded by "+" for press and "-" for release. If +/- is not given,
press-and-release is assumed, except for modifier keys which are left pressed.
-Key names can be X11 KeySyms or some aliases such as 'shift' or 'f1' (the
+Key names can be X11 KeySyms code or some aliases such as 'shift' or 'f1' (the

don't use keysyms code, that's confusing because key code is a specific term
in X.
"Key names can be an X11 KeySym or ...."

Post by Ping Cheng
full list can be seen with the
.B list modifiers
-command).
+command). To assign a key that is not in the modifiers list, look for its KeySyms
+code in keysymdef.h under /usr/include/X11 on your system.

hmm, that makes me wonder why we have special treatment for modifiers. IIRC
they're just special so we can use "shift" instead of "Shift_L". but we
should parse the actual keysym as well. maybe a future patch.

Well, modifier used to mean the key won't do anything by itself until
another(other)
key(s) is pressed. So, modifiers would always have two separate
states: pressed or released.
"Key +shift a -shift" is different from "Key shift a shift"
You made those individual states available to all keys although
"key +a +shift b -shift- a" is the same as "key a +shift b -shift"

These two are different though the difference won't have any effect in most
clients. The first holds a down, shift down, presses and releases b, then
releases shift and then a. The latter presses and releases a before doing a
shift+b.

Post by Ping Cheng
With that change, all keys could be treated the same way by xsetwacom.

I had another look at this, the difference is that while the +/- syntax
works for all keys including modifiers, modifiers automatically hold down
when no +/- is specified. so
"key shift a shift" is the same as
"key +shift a -shift"
maybe this is something worth pointing out in the man page.

Post by Ping Cheng

Post by Peter Hutterer
"To assign a key that is not in the modifiers list use the KeySym in
/usr/include/X11/keysymdef.h with the XK_ prefix removed.
For exampmle, XK_BackSpace should be specified as "BackSpace".

Post by Ping Cheng
-For example, "key +a +shift b -shift -a" converts the button into a series of
-keystrokes, in this example "press a, press shift, press and release b,
-release shift, release a".
+For example, "key +a +shift b -shift -a 0xff0d" converts the button into a
+series of keystrokes, in this example "press a, press shift, press and release b,
+release shift, release a, then enter".

whoah, does this actually work? I didn't know that we parsed hex codes
correctly.

Yeah, it was there at the beginning. Since it was too long ago, we
just forgot what we've done...

looks like it is XStringToKeysym that does the conversion because we don't
have any special code for that. handy to know.

Cheers,
Peter

Post by Ping Cheng

Post by Peter Hutterer

Post by Ping Cheng
The "button" keyword is similar except that its arguments are X11 button
numbers.
diff --git a/tools/xsetwacom.c b/tools/xsetwacom.c
index 2f75d78..aa5f7a1 100644
--- a/tools/xsetwacom.c
+++ b/tools/xsetwacom.c
@@ -605,6 +605,8 @@ static struct modifier specialkeys[] = {
{"backspace", "BackSpace"}, {"Backspace", "BackSpace"},
+ {"return", "Return"},
+

as said above, this needs to be a separate patch (feel free to push, no need
for re-review here if it's just that one line anyway). But do make a note
in the commmit message about the "Enter" vs "Return" controversy :)

Done and pushed.

Post by Peter Hutterer

Post by Ping Cheng
{"tab", "Tab"},
{"PgUp", "Prior"}, {"PgDn", "Next"},
@@ -937,6 +939,8 @@ static void list_mod(Display *dpy)
m = specialkeys;
while(m->name)
printf(" %s\n", m++->name);
+
+ printf("If you don't see your special key listed above, please use its keysyms code or refer to man page for details.\n");

"Keys not listed above can be specified via their KeySym. See the man page
for details."

It will be in the updated patch (v2) and posted here for review.
Thank you for your comments.
Ping

------------------------------------------------------------------------------

[Ping Cheng]

On Wed, Aug 3, 2016 at 10:52 PM, Peter Hutterer

Post by Peter Hutterer

Post by Ping Cheng
xsetwacom accepts keys in X11 KeySyms format. To make the interface
user friendly, we mapped a set of modifiers to aliases that can be
recognized by most users. But, there are a few less recognizable or
confusing keys/modifiers left. This patch tells users where to find
the X11 KeySyms code they are looking for.
Return key is added as a bonus (by-product ;).

No, please don't add this in the same patch. it's completely unrelated and
for stable branch cherry-picking, etc. hiding these things in the same patch
is a bad idea.
Golden rule: when you need to write "Also..." in a commit message you
probably need two patches :)
Same goes for typo fixes (which IMO you can just push directly, they're
usually safe anyway).

Post by Ping Cheng
---
man/xsetwacom.man | 13 +++++++------
tools/xsetwacom.c | 4 ++++
2 files changed, 11 insertions(+), 6 deletions(-)
diff --git a/man/xsetwacom.man b/man/xsetwacom.man
index 1930d67..8276e32 100644
--- a/man/xsetwacom.man
+++ b/man/xsetwacom.man
@@ -109,17 +109,18 @@ button-number will produce a press of X11 button 3 (i.e. right click).
Action mappings allow button presses to perform many events. They take the form
of a string of keywords and arguments.
-The "key" keyword is following by a list of key names. These can optionally
+The "key" keyword is followed by a list of key names. These can optionally
be preceded by "+" for press and "-" for release. If +/- is not given,
press-and-release is assumed, except for modifier keys which are left pressed.
-Key names can be X11 KeySyms or some aliases such as 'shift' or 'f1' (the
+Key names can be X11 KeySyms code or some aliases such as 'shift' or 'f1' (the

don't use keysyms code, that's confusing because key code is a specific term
in X.
"Key names can be an X11 KeySym or ...."

I guess key code is not the same as keysym code. What does "The new
keysym code" mean in the following description (from keysymdef.h)?
Does it mean the set of keysym + value?

"
* For any future extension of the keysyms with characters already
* found in ISO 10646 / Unicode, the following algorithm shall be
* used. The new keysym code position will simply be the character's
* Unicode number plus 0x01000000. The keysym values in the range
* 0x01000100 to 0x0110ffff are reserved to represent Unicode
* characters in the range U+0100 to U+10FFFF.
"

Then what term do I use for the value of a keysym? That value can be
used directly without any confusion or extra work.

Cheers,

Ping

Post by Peter Hutterer

Post by Ping Cheng
full list can be seen with the
.B list modifiers
-command).
+command). To assign a key that is not in the modifiers list, look for its KeySyms
+code in keysymdef.h under /usr/include/X11 on your system.

hmm, that makes me wonder why we have special treatment for modifiers. IIRC
they're just special so we can use "shift" instead of "Shift_L". but we
should parse the actual keysym as well. maybe a future patch.
"To assign a key that is not in the modifiers list use the KeySym in
/usr/include/X11/keysymdef.h with the XK_ prefix removed.
For exampmle, XK_BackSpace should be specified as "BackSpace".

Post by Ping Cheng
-For example, "key +a +shift b -shift -a" converts the button into a series of
-keystrokes, in this example "press a, press shift, press and release b,
-release shift, release a".
+For example, "key +a +shift b -shift -a 0xff0d" converts the button into a
+series of keystrokes, in this example "press a, press shift, press and release b,
+release shift, release a, then enter".

whoah, does this actually work? I didn't know that we parsed hex codes
correctly.

Post by Ping Cheng
The "button" keyword is similar except that its arguments are X11 button
numbers.
diff --git a/tools/xsetwacom.c b/tools/xsetwacom.c
index 2f75d78..aa5f7a1 100644
--- a/tools/xsetwacom.c
+++ b/tools/xsetwacom.c
@@ -605,6 +605,8 @@ static struct modifier specialkeys[] = {
{"backspace", "BackSpace"}, {"Backspace", "BackSpace"},
+ {"return", "Return"},
+

as said above, this needs to be a separate patch (feel free to push, no need
for re-review here if it's just that one line anyway). But do make a note
in the commmit message about the "Enter" vs "Return" controversy :)

Post by Ping Cheng
{"tab", "Tab"},
{"PgUp", "Prior"}, {"PgDn", "Next"},
@@ -937,6 +939,8 @@ static void list_mod(Display *dpy)
m = specialkeys;
while(m->name)
printf(" %s\n", m++->name);
+
+ printf("If you don't see your special key listed above, please use its keysyms code or refer to man page for details.\n");

"Keys not listed above can be specified via their KeySym. See the man page
for details."
Cheers,
Peter

Post by Ping Cheng
}
static void list(Display *dpy, int argc, char **argv)
--
1.9.1

------------------------------------------------------------------------------

[Peter Hutterer]

Post by Ping Cheng
On Wed, Aug 3, 2016 at 10:52 PM, Peter Hutterer

Post by Peter Hutterer

Post by Ping Cheng
xsetwacom accepts keys in X11 KeySyms format. To make the interface
user friendly, we mapped a set of modifiers to aliases that can be
recognized by most users. But, there are a few less recognizable or
confusing keys/modifiers left. This patch tells users where to find
the X11 KeySyms code they are looking for.
Return key is added as a bonus (by-product ;).

No, please don't add this in the same patch. it's completely unrelated and
for stable branch cherry-picking, etc. hiding these things in the same patch
is a bad idea.
Golden rule: when you need to write "Also..." in a commit message you
probably need two patches :)
Same goes for typo fixes (which IMO you can just push directly, they're
usually safe anyway).

Post by Ping Cheng
---
man/xsetwacom.man | 13 +++++++------
tools/xsetwacom.c | 4 ++++
2 files changed, 11 insertions(+), 6 deletions(-)
diff --git a/man/xsetwacom.man b/man/xsetwacom.man
index 1930d67..8276e32 100644
--- a/man/xsetwacom.man
+++ b/man/xsetwacom.man
@@ -109,17 +109,18 @@ button-number will produce a press of X11 button 3 (i.e. right click).
Action mappings allow button presses to perform many events. They take the form
of a string of keywords and arguments.
-The "key" keyword is following by a list of key names. These can optionally
+The "key" keyword is followed by a list of key names. These can optionally
be preceded by "+" for press and "-" for release. If +/- is not given,
press-and-release is assumed, except for modifier keys which are left pressed.
-Key names can be X11 KeySyms or some aliases such as 'shift' or 'f1' (the
+Key names can be X11 KeySyms code or some aliases such as 'shift' or 'f1' (the

don't use keysyms code, that's confusing because key code is a specific term
in X.
"Key names can be an X11 KeySym or ...."

I guess key code is not the same as keysym code. What does "The new
keysym code" mean in the following description (from keysymdef.h)?
Does it mean the set of keysym + value?
"
* For any future extension of the keysyms with characters already
* found in ISO 10646 / Unicode, the following algorithm shall be
* used. The new keysym code position will simply be the character's
* Unicode number plus 0x01000000. The keysym values in the range
* 0x01000100 to 0x0110ffff are reserved to represent Unicode
* characters in the range U+0100 to U+10FFFF.
"
Then what term do I use for the value of a keysym? That value can be
used directly without any confusion or extra work.

imo that's bad wording above. this isn't "keysym code" position, it's keysym
"code position", i.e. similar to a unicode code point. the keysym itself
*is* the value/code/code point.

- a physical keyboard generates a scancode
- the scancode is converted to a keycode
- the keycode is converted to a keysym (on the client side through XKB)
- the keysym is converted to a glyph (on the client side)

so just treat keysym as it's own word and entity without the need for a
"code" suffix. and note that a keysym is just a numeric value that clients
agree on how to convert into a glyph, similar to a unicode code point (which
some keysyms are anyway).

Cheers,
Peter

Post by Ping Cheng

Post by Peter Hutterer

Post by Ping Cheng
full list can be seen with the
.B list modifiers
-command).
+command). To assign a key that is not in the modifiers list, look for its KeySyms
+code in keysymdef.h under /usr/include/X11 on your system.

hmm, that makes me wonder why we have special treatment for modifiers. IIRC
they're just special so we can use "shift" instead of "Shift_L". but we
should parse the actual keysym as well. maybe a future patch.
"To assign a key that is not in the modifiers list use the KeySym in
/usr/include/X11/keysymdef.h with the XK_ prefix removed.
For exampmle, XK_BackSpace should be specified as "BackSpace".

Post by Ping Cheng
-For example, "key +a +shift b -shift -a" converts the button into a series of
-keystrokes, in this example "press a, press shift, press and release b,
-release shift, release a".
+For example, "key +a +shift b -shift -a 0xff0d" converts the button into a
+series of keystrokes, in this example "press a, press shift, press and release b,
+release shift, release a, then enter".

whoah, does this actually work? I didn't know that we parsed hex codes
correctly.

Post by Ping Cheng
The "button" keyword is similar except that its arguments are X11 button
numbers.
diff --git a/tools/xsetwacom.c b/tools/xsetwacom.c
index 2f75d78..aa5f7a1 100644
--- a/tools/xsetwacom.c
+++ b/tools/xsetwacom.c
@@ -605,6 +605,8 @@ static struct modifier specialkeys[] = {
{"backspace", "BackSpace"}, {"Backspace", "BackSpace"},
+ {"return", "Return"},
+

as said above, this needs to be a separate patch (feel free to push, no need
for re-review here if it's just that one line anyway). But do make a note
in the commmit message about the "Enter" vs "Return" controversy :)

Post by Ping Cheng
{"tab", "Tab"},
{"PgUp", "Prior"}, {"PgDn", "Next"},
@@ -937,6 +939,8 @@ static void list_mod(Display *dpy)
m = specialkeys;
while(m->name)
printf(" %s\n", m++->name);
+
+ printf("If you don't see your special key listed above, please use its keysyms code or refer to man page for details.\n");

"Keys not listed above can be specified via their KeySym. See the man page
for details."
Cheers,
Peter

Post by Ping Cheng
}
static void list(Display *dpy, int argc, char **argv)
--
1.9.1

------------------------------------------------------------------------------

[Ping Cheng]

xsetwacom accepts keys in X11 KeySyms format. To make the interface
user friendly, we mapped a set of modifiers to aliases that can be
recognized by most users. But, there are a few less recognizable or
confusing keys/modifiers left. This patch tells users where to find
the X11 KeySyms they are looking for.

Signed-off-by: Ping Cheng <***@wacom.com>
---
man/xsetwacom.man | 15 +++++++++++----
tools/xsetwacom.c | 3 +++
2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/man/xsetwacom.man b/man/xsetwacom.man
index 1930d67..234e9ba 100644
--- a/man/xsetwacom.man
+++ b/man/xsetwacom.man
@@ -109,7 +109,7 @@ button-number will produce a press of X11 button 3 (i.e. right click).
Action mappings allow button presses to perform many events. They take the form
of a string of keywords and arguments.

-The "key" keyword is following by a list of key names. These can optionally
+The "key" keyword is followed by a list of key names. These can optionally
be preceded by "+" for press and "-" for release. If +/- is not given,
press-and-release is assumed, except for modifier keys which are left pressed.
Key names can be X11 KeySyms or some aliases such as 'shift' or 'f1' (the
@@ -117,9 +117,16 @@ full list can be seen with the
.B list modifiers
command).

-For example, "key +a +shift b -shift -a" converts the button into a series of
-keystrokes, in this example "press a, press shift, press and release b,
-release shift, release a".
+To assign a key that is not in the modifiers list, use the KeySym in
+/usr/include/X11/keysymdef.h with the XK_ prefix removed or its actual value
+as is. For example, XK_BackSpace should be specified as "BackSpace". "0xff80"
+can also be used to replace "BackSpace" since it's the unique KeySym value of
+Backspace key.
+
+Here is a combined example: "key +a shift b shift -a 0xff0d" converts the
+button into a series of keystrokes. In this example, "press a, press shift,
+press and release b, release shift, release a, then press and release enter".
+"key +a +shift b -shift -a 0xff0d" does the same thing.

The "button" keyword is similar except that its arguments are X11 button
numbers.
diff --git a/tools/xsetwacom.c b/tools/xsetwacom.c
index f5291ee..bbc92f1 100644
--- a/tools/xsetwacom.c
+++ b/tools/xsetwacom.c
@@ -939,6 +939,9 @@ static void list_mod(Display *dpy)
m = specialkeys;
while(m->name)
printf(" %s\n", m++->name);
+
+ printf("Keys not listed above can be specified via their KeySyms."
+ " See the man page for details.\n");
}

static void list(Display *dpy, int argc, char **argv)

[Peter Hutterer]

Post by Ping Cheng
xsetwacom accepts keys in X11 KeySyms format. To make the interface
user friendly, we mapped a set of modifiers to aliases that can be
recognized by most users. But, there are a few less recognizable or
confusing keys/modifiers left. This patch tells users where to find
the X11 KeySyms they are looking for.

pushed, thanks.

d54db63..97d86e1 master -> master

Cheers,
Peter

Post by Ping Cheng
---
man/xsetwacom.man | 15 +++++++++++----
tools/xsetwacom.c | 3 +++
2 files changed, 14 insertions(+), 4 deletions(-)
diff --git a/man/xsetwacom.man b/man/xsetwacom.man
index 1930d67..234e9ba 100644
--- a/man/xsetwacom.man
+++ b/man/xsetwacom.man
@@ -109,7 +109,7 @@ button-number will produce a press of X11 button 3 (i.e. right click).
Action mappings allow button presses to perform many events. They take the form
of a string of keywords and arguments.
-The "key" keyword is following by a list of key names. These can optionally
+The "key" keyword is followed by a list of key names. These can optionally
be preceded by "+" for press and "-" for release. If +/- is not given,
press-and-release is assumed, except for modifier keys which are left pressed.
Key names can be X11 KeySyms or some aliases such as 'shift' or 'f1' (the
@@ -117,9 +117,16 @@ full list can be seen with the
.B list modifiers
command).
-For example, "key +a +shift b -shift -a" converts the button into a series of
-keystrokes, in this example "press a, press shift, press and release b,
-release shift, release a".
+To assign a key that is not in the modifiers list, use the KeySym in
+/usr/include/X11/keysymdef.h with the XK_ prefix removed or its actual value
+as is. For example, XK_BackSpace should be specified as "BackSpace". "0xff80"
+can also be used to replace "BackSpace" since it's the unique KeySym value of
+Backspace key.
+
+Here is a combined example: "key +a shift b shift -a 0xff0d" converts the
+button into a series of keystrokes. In this example, "press a, press shift,
+press and release b, release shift, release a, then press and release enter".
+"key +a +shift b -shift -a 0xff0d" does the same thing.
The "button" keyword is similar except that its arguments are X11 button
numbers.
diff --git a/tools/xsetwacom.c b/tools/xsetwacom.c
index f5291ee..bbc92f1 100644
--- a/tools/xsetwacom.c
+++ b/tools/xsetwacom.c
@@ -939,6 +939,9 @@ static void list_mod(Display *dpy)
m = specialkeys;
while(m->name)
printf(" %s\n", m++->name);
+
+ printf("Keys not listed above can be specified via their KeySyms."
+ " See the man page for details.\n");
}
static void list(Display *dpy, int argc, char **argv)
--
1.8.3.1

------------------------------------------------------------------------------