KWWidgets
vtkKWKeyBindingsManager.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: vtkKWKeyBindingsManager.h,v
4 
5  Copyright (c) Kitware, Inc.
6  All rights reserved.
7  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
8 
9  This software is distributed WITHOUT ANY WARRANTY; without even
10  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
11  PURPOSE. See the above copyright notice for more information.
12 
13 =========================================================================*/
14 // .NAME vtkKWKeyBindingsManager - a keyboard shortcut manager.
15 // .SECTION Description
16 // This class is basically a manager that acts as a container for a set of
17 // key bindings.
18 // Any object that define a key binding can register it here.
19 // This manager can be queried later on to list all key bindings, for example.
20 // This class does not support reassigning key bindings yet.
21 // .SECTION See Also
22 // vtkKWKeyBindingsWidget
23 
24 
25 #ifndef __vtkKWKeyBindingsManager_h
26 #define __vtkKWKeyBindingsManager_h
27 
28 #include "vtkKWObject.h"
29 
30 class vtkKWKeyBindingsManagerInternals;
31 class vtkKWEventMap;
32 
34 {
35 public:
36  static vtkKWKeyBindingsManager* New();
37  vtkTypeRevisionMacro(vtkKWKeyBindingsManager,vtkKWObject);
38  void PrintSelf(ostream& os, vtkIndent indent);
39 
40  // Description:
41  // Add or set or remove a key binding. Setting a key binding will remove any
42  // items that were previously associated to that specific binding.
43  // 'target' is generally a pointer to the class that set up this binding.
44  // 'binding' is the binding itself, in a Tk event form (say, <KeyPress-p>)
45  // 'callback_object' and 'callback_command' define the callback associated
46  // to this binding. The 'object' argument is the object that will have
47  // the 'command' (method) called on it. The 'method' argument is the
48  // name of the method to be called and any arguments in string form.
49  // If the 'object' is NULL, the method is still evaluated as a
50  // simple Tcl command.
51  // simple Tcl command.
52  // 'context' is a string in plain English (or preferably localized) that
53  // explains in which context this key binding is valid. For example:
54  // "Any 2D View", or "Any Main Window". It usually is a simple/short
55  // description of the class setting the binding (i.e. the 'target').
56  // 'description' is a string in plain English (or preferably localized) that
57  // explains what that binding does. For example: "Reset the camera".
58  virtual void AddKeyBinding(
59  vtkObject *target,
60  const char *binding,
61  vtkObject *callback_object = NULL,
62  const char *callback_command = NULL,
63  const char *context = NULL,
64  const char *description = NULL);
65  virtual void SetKeyBinding(
66  vtkObject *target,
67  const char *binding,
68  vtkObject *callback_object = NULL,
69  const char *callback_command = NULL,
70  const char *context = NULL,
71  const char *description = NULL);
72  virtual void RemoveKeyBinding(
73  vtkObject *target,
74  const char *binding = NULL,
75  vtkObject *callback_object = NULL,
76  const char *callback_command = NULL);
77 
78  // Description:
79  // Query the key bindings. While a little convoluted, this is the fastest
80  // way to query the internal bindings: iterate over the targets, then
81  // iterate over the bindings for each target, then iterate over the callback
82  // objects for each binding, then iterate over the key bindings entries
83  // themselves for each callback objet; for each entry (given a target,
84  // binding, callback object and index), you can retrieve the callback
85  // command, context and description.
86  // See vtkKWKeyBindingsWidget.cxx for an example.
87  virtual int GetNumberOfTargets();
88  virtual vtkObject* GetNthTarget(int idx);
89  virtual int GetNumberOfBindings(vtkObject *target);
90  virtual const char* GetNthBinding(vtkObject *target, int idx);
91  virtual int GetNumberOfCallbackObjects(
92  vtkObject *target, const char *binding);
93  virtual vtkObject* GetNthCallbackObject(
94  vtkObject *target, const char *binding, int idx);
95  virtual int GetNumberOfKeyBindings(
96  vtkObject *target, const char *binding, vtkObject *callback_object);
97  virtual const char* GetNthCallbackCommand(
98  vtkObject *target, const char *binding,vtkObject *callback_object,int idx);
99  virtual const char* GetNthContext(
100  vtkObject *target, const char *binding,vtkObject *callback_object,int idx);
101  virtual const char* GetNthDescription(
102  vtkObject *target, const char *binding,vtkObject *callback_object,int idx);
103 
104  // Description:
105  // Convenience method that can be used to add all the key and keysym
106  // bindings found in a vtkKWEventMap.
107  virtual void SetKeyBindingsFromEventMap(vtkKWEventMap *map);
108 
109  // Description:
110  // Get a "pretty" representation of a binding (remove trailing <>, Key-,
111  // KeyPress-, translate some keysyms, change - into +, uppercase the key).
112  virtual const char* GetPrettyBinding(const char *binding);
113 
114  // Description:
115  // Get a "pretty" representation of a context (if the context is a single
116  // word, i.e. maybe a class name, remove the usual prefixes, and separate
117  // each words).
118  virtual const char* GetPrettyContext(const char *context);
119 
120 protected:
123 
124  //BTX
125  // PIMPL Encapsulation for STL containers
126  vtkKWKeyBindingsManagerInternals *Internals;
127  //ETX
128 
129  // Description:
130  // Processes the events that are passed through CallbackCommand (or others).
131  // Subclasses can oberride this method to process their own events, but
132  // should call the superclass too.
133  virtual void ProcessCallbackCommandEvents(
134  vtkObject *caller, unsigned long event, void *calldata);
135 
136 private:
137 
138  vtkKWKeyBindingsManager(const vtkKWKeyBindingsManager&); // Not implemented
139  void operator=(const vtkKWKeyBindingsManager&); // Not implemented
140 };
141 
142 #endif
143