libyui  3.4.2
YShortcut.h
1 /*
2  Copyright (C) 2000-2012 Novell, Inc
3  This library is free software; you can redistribute it and/or modify
4  it under the terms of the GNU Lesser General Public License as
5  published by the Free Software Foundation; either version 2.1 of the
6  License, or (at your option) version 3.0 of the License. This library
7  is distributed in the hope that it will be useful, but WITHOUT ANY
8  WARRANTY; without even the implied warranty of MERCHANTABILITY or
9  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
10  License for more details. You should have received a copy of the GNU
11  Lesser General Public License along with this library; if not, write
12  to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
13  Floor, Boston, MA 02110-1301 USA
14 */
15 
16 
17 /*-/
18 
19  File: YShortcut.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 
26 #ifndef YShortcut_h
27 #define YShortcut_h
28 
29 #include "YWidget.h"
30 #include <string>
31 #include <vector>
32 
33 class YItem;
34 
35 
36 /**
37  * Helper class for shortcut management:
38  * This class holds data about the shortcut for one single widget.
39  **/
40 class YShortcut
41 {
42 public:
43  /**
44  * Constructor
45  **/
46  YShortcut( YWidget *shortcut_widget );
47 
48  /**
49  * Destructor
50  **/
51  virtual ~YShortcut();
52 
53  /**
54  * Marker for "no shortcut"
55  **/
56  enum { None = 0 };
57 
58  /**
59  * Returns the YWidget this shortcut data belong to.
60  **/
61  YWidget * widget() const { return _widget; }
62 
63  /**
64  * Returns the textual representation of the widget class of the widget
65  * this shortcut data belongs to.
66  **/
67  const char * widgetClass() const { return widget()->widgetClass(); }
68 
69  /**
70  * Returns 'true' if the widget that is associated with this shortcut is a
71  * button (derived from YPushButton).
72  **/
73  bool isButton() const { return _isButton; }
74 
75  /**
76  * Returns 'true' if the widget that is associated with this shortcut is a
77  * wizard button (one of the navigation buttons of a wizard).
78  **/
79  bool isWizardButton() const { return _isWizardButton; }
80 
81  /**
82  * Returns the complete shortcut string (which may or may not contain "&"),
83  * i.e. the value of the widget's shortcut property. For PushButtons, this
84  * is the label on the button ( e.g., "&Details..." ), for other widgets
85  * usually the caption above it.
86  *
87  * This value is chached, i.e. this isn't a too expensive operation.
88  **/
89  std::string shortcutString();
90 
91  /**
92  * Returns the shortcut string ( from the widget's shortcut property )
93  * without any "&" markers.
94  **/
95  std::string cleanShortcutString();
96 
97  /**
98  * Static version of the above for general use:
99  * Returns the specified string without any "&" markers.
100  **/
101  static std::string cleanShortcutString( std::string shortcutString );
102 
103  /**
104  * The preferred shortcut character, i.e. the character that had been
105  * preceded by "&" before checking / resolving conflicts began.
106  **/
107  char preferred();
108 
109  /**
110  * The actual shortcut character.
111  *
112  * This may be different from preferred() if it is overridden.
113  **/
114  char shortcut();
115 
116  /**
117  * Set (override) the shortcut character.
118  **/
119  virtual void setShortcut( char newShortcut );
120 
121  /**
122  * Clear the shortcut: Override the shortcut character with nothing.
123  * This may happen if a conflict cannot be resolved.
124  **/
125  void clearShortcut();
126 
127  /**
128  * Query the internal 'conflict' marker. This class doesn't care about that
129  * flag, it just stores it for the convenience of higher-level classes.
130  **/
131  bool conflict() { return _conflict; }
132 
133  /**
134  * Set or unset the internal 'conflict' marker.
135  **/
136  void setConflict( bool newConflictState = true ) { _conflict = newConflictState; }
137 
138  /**
139  * Obtain the number of distinct valid shortcut characters in the shortcut
140  * string, i.e. how many different shortcuts that widget could get.
141  **/
142  int distinctShortcutChars();
143 
144  /**
145  * Return true if this shortcut contains any character that would be valid
146  * as a shortcut character.
147  **/
148  bool hasValidShortcutChar();
149 
150  /**
151  * Static function: Returns the character used for marking keyboard
152  * shortcuts.
153  **/
154  static char shortcutMarker() { return '&'; }
155 
156  /**
157  * Static function: Find the next occurrence of the shortcut marker ('&')
158  * in a string, beginning at starting position start_pos.
159  *
160  * Returns string::npos if not found or the position of the shortcut marker
161  * (not the shortcut character!) if found.
162  **/
163  static std::string::size_type findShortcutPos( const std::string & str, std::string::size_type start_pos = 0 );
164 
165  /**
166  * Static function: Find the next shortcut marker in a string, beginning at
167  * starting position start_pos.
168  *
169  * Returns the shortcut character or 0 if none found.
170  **/
171  static char findShortcut( const std::string & str, std::string::size_type start_pos = 0 );
172 
173  /**
174  * Returns 'true' if 'c' is a valid shortcut character, i.e. [a-zA-Z0-9],
175  * 'false' otherwise.
176  **/
177  static bool isValid( char c );
178 
179  /**
180  * Return the normalized version of shortcut character 'c', i.e. a
181  * lowercase letter or a digit [a-z0-9]. Returns 0 if 'c' is invalid.
182  **/
183  static char normalized( char c );
184 
185  /**
186  * Obtain a widget's shortcut property - the string that contains "&" to
187  * designate a shortcut.
188  **/
189  static std::string getShortcutString( const YWidget * widget );
190 
191 
192 protected:
193 
194  /**
195  * Obtain the the shortcut property of this shortcut's widget - the string
196  * that contains "&" to designate a shortcut.
197  **/
198  virtual std::string getShortcutString();
199 
200 
201  // Data members
202 
203  YWidget * _widget;
204  std::string _shortcutString;
205  bool _shortcutStringCached;
206 
207  std::string _cleanShortcutString;
208  bool _cleanShortcutStringCached;
209 
210  int _preferred; // int to enable initializing with invalid char (-1)
211  int _shortcut; // int to enable initializing with invalid char (-1)
212 
213  bool _conflict;
214  bool _isButton;
215  bool _isWizardButton;
216  int _distinctShortcutChars;
217 };
218 
219 
220 
221 /**
222  * Special case for widgets that can have multiple shortcuts based on items
223  * (like YDumbTab)
224  **/
226 {
227 public:
228  /**
229  * Constructor.
230  **/
232  : YShortcut( widget )
233  , _item( item )
234  {}
235 
236  /**
237  * Destructor.
238  **/
239  virtual ~YItemShortcut() {}
240 
241  /**
242  * Return the associated item.
243  **/
244  YItem * item() const { return _item; }
245 
246  /**
247  * Set (override) the shortcut character.
248  * In this subclass, it will change the internally stored item.
249  **/
250  virtual void setShortcut( char newShortcut );
251 
252 protected:
253 
254  /**
255  * Obtain the the shortcut property of this shortcut's widget - the string
256  * that contains "&" to designate a shortcut.
257  **/
258  virtual std::string getShortcutString();
259 
260 
261 private:
262 
263  YItem * _item;
264 };
265 
266 
267 typedef std::vector<YShortcut *> YShortcutList;
268 typedef YShortcutList::iterator YShortcutListIterator;
269 
270 
271 #endif // YShortcut_h
virtual ~YShortcut()
Destructor.
Definition: YShortcut.cc:69
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
Definition: YWidget.h:72
char preferred()
The preferred shortcut character, i.e.
Definition: YShortcut.cc:117
static std::string::size_type findShortcutPos(const std::string &str, std::string::size_type start_pos=0)
Static function: Find the next occurrence of the shortcut marker (&#39;&&#39;) in a string, beginning at starting position start_pos.
Definition: YShortcut.cc:254
virtual std::string getShortcutString()
Obtain the the shortcut property of this shortcut&#39;s widget - the string that contains "&" to designat...
Definition: YShortcut.cc:237
const char * widgetClass() const
Returns the textual representation of the widget class of the widget this shortcut data belongs to...
Definition: YShortcut.h:67
YItem * item() const
Return the associated item.
Definition: YShortcut.h:244
Helper class for shortcut management: This class holds data about the shortcut for one single widget...
Definition: YShortcut.h:40
virtual void setShortcut(char newShortcut)
Set (override) the shortcut character.
Definition: YShortcut.cc:141
static char normalized(char c)
Return the normalized version of shortcut character &#39;c&#39;, i.e.
Definition: YShortcut.cc:299
virtual ~YItemShortcut()
Destructor.
Definition: YShortcut.h:239
void setConflict(bool newConflictState=true)
Set or unset the internal &#39;conflict&#39; marker.
Definition: YShortcut.h:136
std::string cleanShortcutString()
Returns the shortcut string ( from the widget&#39;s shortcut property ) without any "&" markers...
Definition: YShortcut.cc:91
Special case for widgets that can have multiple shortcuts based on items (like YDumbTab) ...
Definition: YShortcut.h:225
static char shortcutMarker()
Static function: Returns the character used for marking keyboard shortcuts.
Definition: YShortcut.h:154
bool isButton() const
Returns &#39;true&#39; if the widget that is associated with this shortcut is a button (derived from YPushBut...
Definition: YShortcut.h:73
bool conflict()
Query the internal &#39;conflict&#39; marker.
Definition: YShortcut.h:131
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:49
static char findShortcut(const std::string &str, std::string::size_type start_pos=0)
Static function: Find the next shortcut marker in a string, beginning at starting position start_pos...
Definition: YShortcut.cc:280
std::string shortcutString()
Returns the complete shortcut string (which may or may not contain "&"), i.e.
Definition: YShortcut.cc:75
void clearShortcut()
Clear the shortcut: Override the shortcut character with nothing.
Definition: YShortcut.cc:173
int distinctShortcutChars()
Obtain the number of distinct valid shortcut characters in the shortcut string, i.e.
Definition: YShortcut.cc:180
bool hasValidShortcutChar()
Return true if this shortcut contains any character that would be valid as a shortcut character...
Definition: YShortcut.cc:222
YItemShortcut(YWidget *widget, YItem *item)
Constructor.
Definition: YShortcut.h:231
YWidget * widget() const
Returns the YWidget this shortcut data belong to.
Definition: YShortcut.h:61
Abstract base class of all UI widgets.
Definition: YWidget.h:54
char shortcut()
The actual shortcut character.
Definition: YShortcut.cc:129
bool isWizardButton() const
Returns &#39;true&#39; if the widget that is associated with this shortcut is a wizard button (one of the nav...
Definition: YShortcut.h:79
YShortcut(YWidget *shortcut_widget)
Constructor.
Definition: YShortcut.cc:41
static bool isValid(char c)
Returns &#39;true&#39; if &#39;c&#39; is a valid shortcut character, i.e.
Definition: YShortcut.cc:289