1 files changed, 93 insertions, 0 deletions
diff --git a/doc/PenButtons.txt b/doc/PenButtons.txt
new file mode 100644
index 0000000..5a9f3b3
--- /dev/null
+++ b/doc/PenButtons.txt
@@ -0,0 +1,93 @@
+-------------------------------
+xf86-input-tc1kpen: Pen buttons
+-------------------------------
+
+xf86-input-tc1kpen can be configured to work using
+different pen buttons modes.  Each mode defines
+rules to control pen button events.
+Note that the modes may be modified via buttons mapping.
+It is up to user which mode would suit him, better.
+Note that all the modes below may be tested via
+the calibration utility (to allow the user to chose
+the best for him).
+
+xf86-input-tc1kpen currently supports the following
+pen buttons modes:
+
+
+
+2HW: 2 buttons in HW mode
+-------------------------
+
+Pen tip acts like mouse button 1 (by default).
+Press event is sent when pen taps the tablet,
+release event is sent when pen tip leaves the
+tablet surface.
+
+Pen button acts like mouse button 3 (by default).
+It has no binding to pen tip.
+Press event is sent when pen button is pressed
+in tablet proximity, release event is sent when
+pen button is released in tablet proximity.
+
+
+
+2EMU: 2 buttons in emulation mode
+---------------------------------
+
+Pen tip acts like in the HW mode.
+
+Pressing pen button has no effect unless combined
+with pen tap.  If pen button is pressed while pen
+taps the tablet, the result is mouse 3 press event
+(by default).
+It doesn't matter which of pen button or tip is
+released first, but as soon as the pen tip leaves
+the tablet, mouse 3 release event is sent.
+
+
+
+3EMU: 3 buttons in emulation mode (no tap)
+------------------------------------------
+
+This mode adds button 2 (by default) to the
+2-button emulation mode.
+That means that button 1 and 3 events are sent
+in exactly the same circumstances as in the 2-btn
+emu. mode.
+
+The new thing is that if you press and release
+the pen button within a defined timeout in tablet
+proximity, immediate button 2 press/release events
+are sent as soon as you release the button.
+
+This mode may be nice e.g. when copy-pasting a text:
+you "dip" the text using the pen tip and then you
+"drop" it by clicking the pen button while hovering
+the pen over the destination.
+
+
+
+3EMUtap: 3 buttons in emulation mode (with tap)
+-----------------------------------------------
+
+Again, button 2 (by default) is added to the 2-btn
+emulation mode.
+This one works like this:
+
+The pen button can be used as a switch for pen tip events.
+If you press and release pen button in tablet proximity
+within a defined timeout, the subsequent use of pen
+tip will produce button 2 press/release events (rather
+than button 1 events).
+Then, it switches back to normal (button 1).
+The switching is reversible, so if you switch to
+button 2 and then change your mind, you may switch
+to button 1 just by repeating the pen button "click".
+The state is also re-set by moving the pen out of tablet
+proximity (no matter in which state the pen was).
+
+Note that this mode really enables full 3-button
+functionality (compared to the no-tap mode where you
+can't e.g. drag-and-drop with button 2).
+