1 #ifndef _library__keyboard__hpp__included__
2 #define _library__keyboard__hpp__included__
20 * A group of modifiers and keys.
22 * Instances of this class allow registering, unregistering and looking up modifiers and keys.
28 * Create a new instance.
30 keyboard() throw(std::bad_alloc
);
32 * Destroy an instance.
34 * The keys and modifiers in instance are not freed.
38 * Lookup modifier by name.
40 * Parameter name: The name of the modifier.
41 * Returns: The modifier.
42 * Throws std::runtime_error: No such modifier.
44 modifier
& lookup_modifier(const std::string
& name
) throw(std::runtime_error
);
46 * Try lookup modifier by name.
48 * Parameter name: The name of the modifier.
49 * Returns: The modifier, or NULL if not found.
51 modifier
* try_lookup_modifier(const std::string
& name
) throw();
53 * Look up all modifiers.
55 * Returns: The set of modifiers.
57 std::list
<modifier
*> all_modifiers() throw(std::bad_alloc
);
59 * Register a modifier.
61 * Parameter name: The name of the modifier.
62 * Parameter mod: The modifier.
64 void do_register(const std::string
& name
, modifier
& mod
) throw(std::bad_alloc
);
66 * Unregister a modifier.
68 * Parameter name: The name of the modifier.
70 void do_unregister(const std::string
& name
, modifier
& mod
) throw();
74 * Parameter name: The name of the key.
76 * Throws std::runtime_error: No such key.
78 key
& lookup_key(const std::string
& name
) throw(std::runtime_error
);
80 * Try lookup key by name.
82 * Parameter name: The name of the key.
83 * Returns: The key, or NULL if not found.
85 key
* try_lookup_key(const std::string
& name
) throw();
89 * Returns: The set of keys.
91 std::list
<key
*> all_keys() throw(std::bad_alloc
);
95 * Parameter name: The name of the key.
96 * Parameter mod: The key.
98 void do_register(const std::string
& name
, key
& mod
) throw(std::bad_alloc
);
102 * Parameter name: The name of the key.
104 void do_unregister(const std::string
& name
, key
& mod
) throw();
106 * Set exclusive listener for all keys at once.
108 void set_exclusive(event_listener
* listener
) throw();
112 void set_current_key(key
* key
) throw();
116 key
* get_current_key() throw();
118 keyboard(const keyboard
&);
119 keyboard
& operator=(const keyboard
&);
124 * A modifier or group of modifiers.
130 * Create a (group of) modifiers.
132 * Parameter keyb: The keyboard these will be on.
133 * Parameter _name: The name of the modifier.
135 modifier(keyboard
& keyb
, const std::string
& _name
) throw(std::bad_alloc
)
136 : kbd(keyb
), name(_name
)
138 keyb
.do_register(name
, *this);
141 * Create a linked modifier in group.
143 * Parameter keyb: The keyboard these will be on.
144 * Parameter _name: The name of the modifier.
145 * Parameter _link: The name of the modifier group this is in.
147 modifier(keyboard
& keyb
, const std::string
& _name
, const std::string
& _link
) throw(std::bad_alloc
)
148 : kbd(keyb
), name(_name
), link(_link
)
150 keyb
.do_register(name
, *this);
157 kbd
.do_unregister(name
, *this);
160 * Get associated keyboard.
162 keyboard
& get_keyboard() const throw() { return kbd
; }
164 * Get name of the modifier.
166 const std::string
& get_name() const throw() { return name
; }
168 * Get linked name of the modifier.
170 * Returns: The linked name, or "" if none.
172 const std::string
& get_link_name() const throw() { return link
; }
174 * Get the linked modifier.
176 * Returns: The linked modifier, or NULL if none (or not initialized yet).
178 modifier
* get_link() { return kbd
.try_lookup_modifier(link
); }
186 * A set of modifier keys.
192 * Add a modifier into the set.
194 * parameter mod: The modifier to add.
195 * parameter really: If true, actually add the key. If false, do nothing.
196 * throws std::bad_alloc: Not enough memory.
198 void add(modifier
& mod
, bool really
= true) throw(std::bad_alloc
);
200 * Remove a modifier from the set.
202 * parameter mod: The modifier to remove.
203 * parameter really: If true, actually remove the key. If false, do nothing.
204 * throws std::bad_alloc: Not enough memory.
206 void remove(modifier
& mod
, bool really
= true) throw(std::bad_alloc
);
208 * Construct modifier set from comma-separated string.
210 * parameter kbd: The keyboard to take the modifiers from.
211 * parameter modifiers: The modifiers as string
212 * returns: The constructed modifier set.
213 * throws std::bad_alloc: Not enough memory.
214 * throws std::runtime_error: Illegal modifier or wrong syntax.
216 static modifier_set
construct(keyboard
& kbd
, const std::string
& modifiers
) throw(std::bad_alloc
,
219 * Check modifier against its mask for validity.
221 * This method checks that:
222 * - for each modifier in set, either that or its linkage group is in mask.
223 * - Both modifier and its linkage group isn't in either set or mask.
225 * parameter mask: The mask to check against.
226 * returns: True if set is valid, false if not.
227 * throws std::bad_alloc: Not enough memory.
229 bool valid(modifier_set
& mask
) throw(std::bad_alloc
);
231 * Check if this modifier set triggers the action.
233 * Modifier set triggers another if for each modifier or linkage group in mask:
234 * - Modifier appears in both set and trigger.
235 * - At least one modifier with this linkage group appears in both set and trigger.
236 * - Modifiers with this linkage group do not appear in either set nor trigger.
239 bool triggers(const modifier_set
& trigger
, const modifier_set
& mask
) throw(std::bad_alloc
);
243 operator std::string() const throw(std::bad_alloc
);
247 * parameter m: Another set.
248 * returns: True if two sets are equal, false if not.
250 bool operator==(const modifier_set
& m
) const throw();
254 bool operator<(const modifier_set
& m
) const throw();
256 friend std::ostream
& operator<<(std::ostream
& os
, const modifier_set
& m
);
257 std::set
<modifier
*> set
;
261 * Debugging print. Prints textual version of set into stream.
263 * parameter os: The stream to print to.
264 * parameter m: The modifier set to print.
265 * returns: reference to os.
267 std::ostream
& operator<<(std::ostream
& os
, const modifier_set
& m
);
275 * A simple key (pressed/released)
279 * A joystick axis (pair of opposite directions or pressure-sensitive button).
283 * A joystick hat (directional control or a dpad).
293 * Joystick axis calibration structure.
295 struct axis_calibration
298 * Mode: -1 => Disabled, 0 => Pressure-sentive button, 1 => Axis.
304 * Mouse axis calibration structure.
306 struct mouse_calibration
309 * The offset from left of screen area to left of game area.
313 * Translate from screen coordinate to game coordinate.
315 int32_t get_calibrated_value(int32_t x
) const throw();
319 * Superclass of key event data.
325 * Create a new event.
327 * Parameter _chngmask: The change mask.
328 * Parameter _type: Type of the event.
330 event(uint32_t _chngmask
, keytype _type
) throw()
332 chngmask
= _chngmask
;
338 virtual ~event() throw();
340 * Get analog state. The format is dependent on key type.
342 virtual int32_t get_state() const throw() = 0;
344 * Get key change mask.
346 * Returns: A bitmask. Bit 2*n is the state of subkey n. Bit 2*n+1 is set if subkey changed state, else clear.
348 uint32_t get_change_mask() const throw() { return chngmask
; }
352 keytype
get_type() const throw() { return type
; }
359 * A simple key event.
361 class event_key
: public event
365 * Construct a new key event.
367 * Parameter chngmask: The change mask.
369 event_key(uint32_t chngmask
);
373 ~event_key() throw();
377 * Returns: 1 if pressed, 0 if released.
379 int32_t get_state() const throw();
387 class event_axis
: public event
391 * Construct a new axis event.
393 * Parameter state: The analog state.
394 * Parameter chngmask: The change mask.
395 * Parameter cal: The calibration structure.
397 event_axis(int32_t state
, uint32_t chngmask
);
401 ~event_axis() throw();
405 * Returns: Analog position of axis, -32768...32767 (0...32767 for pressure-sensitive buttons).
407 int32_t get_state() const throw();
410 axis_calibration cal
;
416 class event_hat
: public event
420 * Construct a new hat event.
422 * Parameter chngmask: The change mask to use.
424 event_hat(uint32_t chngmask
);
428 ~event_hat() throw();
432 * Returns: Bitmask: 1 => Up, 2 => Right, 4 => Down, 8 => Left.
434 int32_t get_state() const throw();
440 class event_mouse
: public event
444 * Construct a new mouse event.
446 * Parameter state: The game-relative position to use.
447 * Parameter cal: The calibration structure.
449 event_mouse(int32_t state
, const mouse_calibration
& cal
);
453 ~event_mouse() throw();
457 * Returns: Position of mouse relative to game area (with right/down positive).
459 int32_t get_state() const throw();
461 * Get calibration data.
463 mouse_calibration
get_calibration() { return cal
; }
466 mouse_calibration cal
;
470 * A keyboard event listener.
478 virtual ~event_listener() throw();
480 * Receive a key event.
482 * Parameter mods: Modifiers currently active.
483 * Parameter key: The key this event is about.
484 * Parameter event: The event.
486 virtual void on_key_event(modifier_set
& mods
, key
& key
, event
& event
) = 0;
490 * A (compound) key on keyboard.
498 * Parameter keyb: The keyboard this is on.
499 * Parameter name: The base name of the key.
500 * Parameter clazz: The class of the key.
501 * Parameter type: The type of key.
503 key(keyboard
& keyb
, const std::string
& name
, const std::string
& clazz
, keytype type
)
504 throw(std::bad_alloc
);
508 virtual ~key() throw();
512 const std::string
& get_class() { return clazz
; }
516 const std::string
& get_name() { return name
; }
518 * Get keyboard this is on.
520 keyboard
& get_keyboard() { return kbd
; }
524 keytype
get_type() const throw() { return type
; }
528 * Parameter listener: The listener.
529 * Parameter analog: If true, also pass analog events.
531 void add_listener(event_listener
& listener
, bool analog
) throw(std::bad_alloc
);
535 * Parameter listener: The listener.
537 void remove_listener(event_listener
& listener
) throw();
539 * Set exclusive listener.
541 * Parameter listener: The listener. NULL to ungrab key.
543 void set_exclusive(event_listener
* listener
) throw();
547 * Parameter mods: The current modifiers.
548 * Parameter state: The new state. The format is dependent on key type.
550 virtual void set_state(modifier_set mods
, int32_t state
) throw() = 0;
552 * Get analog state. The format is dependent on key type.
554 virtual int32_t get_state() const throw() = 0;
556 * Get digital state. The format is dependent on key type.
558 virtual int32_t get_state_digital() const throw() = 0;
560 * Get the subkey suffixes.
562 virtual std::vector
<std::string
> get_subkeys() throw(std::bad_alloc
) = 0;
564 * Dynamic cast to axis type.
566 key_axis
* cast_axis() throw();
568 * Dynamic cast to mouse type.
570 key_mouse
* cast_mouse() throw();
573 * Call all event listeners on this key.
575 * Parameter mods: The current modifiers.
576 * Parameter event: The event to pass.
578 void call_listeners(modifier_set
& mods
, event
& event
);
581 key
& operator=(key
&);
585 std::set
<event_listener
*> digital_listeners
;
586 std::set
<event_listener
*> analog_listeners
;
587 event_listener
* exclusive_listener
;
592 * A simple key on keyboard.
594 class key_key
: public key
600 * Parameter keyb: The keyboard this is on.
601 * Parameter name: The base name of the key.
602 * Parameter clazz: The class of the key.
604 key_key(keyboard
& keyb
, const std::string
& name
, const std::string
& clazz
) throw(std::bad_alloc
);
612 * Parameter mods: The current modifiers.
613 * Parameter state: The new state. 1 for pressed, 0 for released.
615 void set_state(modifier_set mods
, int32_t state
) throw();
617 * Get analog state. 1 for pressed, 0 for released.
619 int32_t get_state() const throw();
621 * Get digital state. 1 for pressed, 0 for released.
623 int32_t get_state_digital() const throw();
625 * Get the subkey suffixes.
627 std::vector
<std::string
> get_subkeys() throw(std::bad_alloc
);
630 key_key
& operator=(key_key
&);
637 class key_hat
: public key
643 * Parameter keyb: The keyboard this is on.
644 * Parameter name: The base name of the key.
645 * Parameter clazz: The class of the key.
647 key_hat(keyboard
& keyb
, const std::string
& name
, const std::string
& clazz
) throw(std::bad_alloc
);
655 * Parameter mods: The current modifiers.
656 * Parameter state: The new state. 1 => up, 2 => right, 4 => down, 8 => left.
658 void set_state(modifier_set mods
, int32_t state
) throw();
660 * Get analog state. 1 => up, 2 => right, 4 => down, 8 => left.
662 int32_t get_state() const throw();
664 * Get digital state. 1 => up, 2 => right, 4 => down, 8 => left.
666 int32_t get_state_digital() const throw();
668 * Get the subkey suffixes.
670 std::vector
<std::string
> get_subkeys() throw(std::bad_alloc
);
673 key_hat
& operator=(key_hat
&);
678 * An axis on keyboard.
680 class key_axis
: public key
686 * Parameter keyb: The keyboard this is on.
687 * Parameter name: The base name of the key.
688 * Parameter clazz: The class of the key.
689 * Parameter mode: Initial mode: -1 => disabled, 0 => axis, 1 => pressure
691 key_axis(keyboard
& keyb
, const std::string
& name
, const std::string
& clazz
, int mode
)
692 throw(std::bad_alloc
);
700 * Parameter mods: The current modifiers.
701 * Parameter state: The new state. Uncalibrated analog position.
703 void set_state(modifier_set mods
, int32_t state
) throw();
705 * Get analog state. -32767...32767 for axes, 0...32767 for pressure-sensitive buttons.
707 int32_t get_state() const throw();
709 * Get digital state. -1 => left, 0 => center/unpressed, 1 => Right/pressed.
711 int32_t get_state_digital() const throw();
713 * Get the subkey suffixes.
715 std::vector
<std::string
> get_subkeys() throw(std::bad_alloc
);
719 int get_mode() const throw();
723 void set_mode(int mode
, double tolerance
) throw();
726 key_axis
& operator=(key_axis
&);
729 double last_tolerance
;
734 * A mouse axis on keyboard.
736 class key_mouse
: public key
742 * Parameter keyb: The keyboard this is on.
743 * Parameter name: The base name of the key.
744 * Parameter clazz: The class of the key.
745 * Parameter cal: Initial calibration.
747 key_mouse(keyboard
& keyb
, const std::string
& name
, const std::string
& clazz
,
748 mouse_calibration cal
) throw(std::bad_alloc
);
752 ~key_mouse() throw();
756 * Parameter mods: The current modifiers.
757 * Parameter state: The new state. Screen-relative analog position.
759 void set_state(modifier_set mods
, int32_t state
) throw();
761 * Get analog state. Game-relative analog position.
763 int32_t get_state() const throw();
765 * Get digital state. Always returns 0.
767 int32_t get_state_digital() const throw();
769 * Get the subkey suffixes. Returns empty list.
771 std::vector
<std::string
> get_subkeys() throw(std::bad_alloc
);
775 mouse_calibration
get_calibration() const throw();
779 void set_calibration(mouse_calibration cal
) throw();
781 key_mouse(key_mouse
&);
782 key_mouse
& operator=(key_mouse
&);
784 mouse_calibration cal
;