libyui  3.2.3
 All Classes Files Functions Variables Typedefs Enumerations Friends Pages
YDialog.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: YDialog.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 
26 #ifndef YDialog_h
27 #define YDialog_h
28 
29 #include "YSingleChildContainerWidget.h"
30 #include <stack>
31 #include <map>
32 
33 class YShortcutManager;
34 class YPushButton;
35 class YDialogPrivate;
36 class YEvent;
37 class YEventFilter;
38 
39 // See YTypes.h for enum YDialogType and enum YDialogColorMode
40 
41 
43 {
44 protected:
45  /**
46  * Constructor.
47  *
48  * 'dialogType' is one of YMainDialog or YPopupDialog.
49  *
50  * 'colorMode' can be set to YDialogWarnColor to use very bright "warning"
51  * colors or YDialogInfoColor to use more prominent, yet not quite as
52  * bright as "warning" colors. Use both only very rarely.
53  **/
54  YDialog( YDialogType dialogType,
55  YDialogColorMode colorMode = YDialogNormalColor );
56 
57  /**
58  * Destructor.
59  * Don't delete a dialog directly, use YDialog::deleteTopmostDialog()
60  * or YDialog::destroy().
61  **/
62  virtual ~YDialog();
63 
64 public:
65  /**
66  * Return a descriptive name of this widget class for logging,
67  * debugging etc.
68  **/
69  virtual const char * widgetClass() const { return "YDialog"; }
70 
71  /**
72  * Open a newly created dialog: Finalize it and make it visible
73  * on the screen.
74  *
75  * Applications should call this once after all children are created.
76  * If the application doesn't do this, it will be done automatically upon
77  * the next call of YDialog::waitForEvent() (or related). This is OK if
78  * YDialog::waitForEvent() is called immediately after creating the dialog
79  * anyway. If it is not, the application might appear sluggish to the user.
80  *
81  * Derived classes are free to reimplement this, but they should call this
82  * base class method in the new implementation.
83  **/
84  void open();
85 
86  /**
87  * Return 'true' if open() has already been called for this dialog.
88  **/
89  bool isOpen() const;
90 
91  /**
92  * Wait for a user event. In most cases, this means waiting until the user
93  * has clicked on a button in this dialog. If any widget has its 'notify'
94  * flag set (`opt(`notify) in YCP, setNotify( true ) in C++), an action on
95  * such a widget will also make waitForEvent() return.
96  *
97  * If the specified timeout elapses without any user event, a YTimeoutEvent
98  * will be returned. 0 means no timeout (wait forever).
99  *
100  * If open() has not been called for this dialog until now,
101  * it is called now.
102  *
103  * The dialog retains ownership of the event and will delete it upon the
104  * next call to waitForEvent() or pollEvent() or when the dialog is
105  * deleted. This also means that the return value of this function can
106  * safely be ignored without fear of memory leaks.
107  *
108  * Applications can create YEventFilters to act upon some events before
109  * they are delivered to the application. Each event filter of this dialog
110  * is called (in undefined order) in waitForEvent(). An event filter can
111  * consume an event (in which case waitForEvent() will return to its
112  * internal event loop), pass it through unchanged, or even replace it with
113  * a new event. Refer to the YEventFilter documentation for more details.
114  *
115  * If this dialog is not the topmost dialog, an exception is thrown.
116  **/
117  YEvent * waitForEvent( int timeout_millisec = 0 );
118 
119  /**
120  * Check if a user event is pending. If there is one, return it.
121  * If there is none, do not wait for one - return 0.
122  *
123  * If open() has not been called for this dialog until now,
124  * it is called now.
125  *
126  * The dialog retains ownership of the event and will delete it upon the
127  * next call to waitForEvent() or pollEvent() or when the dialog is
128  * deleted. This also means that the return value of this function can
129  * safely be ignored without fear of memory leaks.
130  *
131  * If this dialog is not the topmost dialog, an exception is thrown.
132  **/
133  YEvent * pollEvent();
134 
135  /**
136  * Return 'true' if this dialog is the topmost dialog.
137  **/
138  bool isTopmostDialog() const;
139 
140  /**
141  * Close and delete this dialog (and all its children) if it is the topmost
142  * dialog. If this is not the topmost dialog, this will throw an exception
143  * if 'doThrow' is true (default).
144  *
145  * Remember that all pointers to the dialog and its children will be
146  * invalid after this operation.
147  *
148  * This is intentionally not named close() since close() would not imply
149  * that the dialog and its children are deleted.
150  *
151  * Returns 'true' upon success, 'false' upon failure.
152  **/
153  bool destroy( bool doThrow = true );
154 
155  /**
156  * Delete the topmost dialog.
157  *
158  * Will throw a YUINoDialogException if there is no dialog and 'doThrow' is
159  * 'true'.
160  *
161  * This is equivalent to YDialog::currentDialog()->destroy().
162  *
163  * Returns 'true' if there is another open dialog after deleting,
164  * 'false' if there is none.
165  **/
166  static bool deleteTopmostDialog( bool doThrow = true );
167 
168  /**
169  * Delete all open dialogs.
170  **/
171  static void deleteAllDialogs();
172 
173  /**
174  * Delete all dialogs from the topmost to the one specified.
175  **/
176  static void deleteTo( YDialog * dialog );
177 
178  /**
179  * Returns the number of currently open dialogs (from 1 on), i.e., the
180  * depth of the dialog stack.
181  **/
182  static int openDialogsCount();
183 
184  /**
185  * Return the current (topmost) dialog.
186  *
187  * If there is none, throw a YUINoDialogException if 'doThrow' is 'true'
188  * and return 0 if 'doThrow' is false.
189  **/
190  static YDialog * currentDialog( bool doThrow = true );
191 
192  /**
193  * Alias for currentDialog().
194  **/
195  static YDialog * topmostDialog( bool doThrow = true )
196  { return currentDialog( doThrow ); }
197 
198  /**
199  * Set the initial dialog size, depending on dialogType:
200  * YMainDialog dialogs get the UI's "default main window" size,
201  * YPopupDialog dialogs use their content's preferred size.
202  **/
203  void setInitialSize();
204 
205  /**
206  * Recalculate the layout of the dialog and of all its children after
207  * children have been added or removed or if any of them changed its
208  * preferred width of height.
209  *
210  * This is a very expensive operation. Call it only when really necessary.
211  * YDialog::open() includes a call to YDialog::setInitialSize() which does
212  * the same.
213  *
214  * The basic idea behind this function is to call it when the dialog
215  * changed after it (and its children hierarchy) was initially created.
216  **/
217  void recalcLayout();
218 
219  /**
220  * Return this dialog's type (YMainDialog / YPopupDialog /YWizardDialog).
221  **/
222  YDialogType dialogType() const;
223 
224  /**
225  * Return 'true' if this dialog is a dialog of main dialog size:
226  * YMainDialog or YWizardDialog.
227  **/
228  bool isMainDialog();
229 
230  /**
231  * Return this dialog's color mode.
232  **/
233  YDialogColorMode colorMode() const;
234 
235  /**
236  * Checks the keyboard shortcuts of widgets in this dialog unless shortcut
237  * checks are postponed or 'force' is 'true'.
238  *
239  * A forced shortcut check resets postponed checking.
240  **/
241  void checkShortcuts( bool force = false );
242 
243  /**
244  * From now on, postpone keyboard shortcut checks - i.e. normal (not
245  * forced) checkKeyboardShortcuts() will do nothing. Reset this mode by
246  * forcing a shortcut check with checkKeyboardShortcuts( true ).
247  **/
248  void postponeShortcutCheck();
249 
250  /**
251  * Return whether or not shortcut checking is currently postponed.
252  **/
253  bool shortcutCheckPostponed() const;
254 
255  /**
256  * Return this dialog's default button: The button that is activated when
257  * the user hits [Return] anywhere in this dialog. Note that this is not
258  * the same as the button that currently has the keyboard focus.
259  *
260  * This might return 0 if there is no default button.
261  **/
262  YPushButton * defaultButton() const;
263 
264  /**
265  * Delete an event.
266  **/
267  void deleteEvent( YEvent * event );
268 
269  /**
270  * Add an event filter. This can be useful to catch certain types of events
271  * before they are delivered to the application. All event filters are
272  * called (in unspecified order) in waitForEvent(). Each one may consume
273  * an event, pass it through unchanged, or replace it with a newly created
274  * event.
275  *
276  * Normally, an YEventFilter should be created on the heap with 'new'. In
277  * that case, the dialog's destructor will take care of deleting it.
278  *
279  * In rare cases it might make sense to create an YEventFilter on the stack
280  * (as a local variable) and rely on that variable to go out of scope and
281  * be destroyed before the dialog gets destroyed. But that may be risky.
282  *
283  * Notice that applications never need to call this function: YEventFilter
284  * does it automatically in its constructor.
285  **/
286  void addEventFilter( YEventFilter * eventFilter );
287 
288  /**
289  * Remove an event filter.
290  *
291  * Notice that applications never need to call this function: YEventFilter
292  * does it automatically in its destructor.
293  **/
294  void removeEventFilter( YEventFilter * eventFilter );
295 
296  /**
297  * Highlight a child widget of this dialog. This is meant for debugging:
298  * YDialogSpy and similar uses.
299  *
300  * No more than one widget can be highlighted at any one time in the same
301  * dialog. Highlighting another widget un-highlights a previously
302  * highlighted widget. 0 means 'unhighlight the last highlighted widget,
303  * but don't highlight any other'.
304  *
305  * This default implementation does nothing.
306  **/
307  virtual void highlight( YWidget * child ) {}
308 
309  /**
310  * Set this dialog's default button (the button that is activated when
311  * the user hits [Return] anywhere in this dialog). 0 means no default
312  * button.
313  *
314  * There should be no more than one default button in a dialog.
315  *
316  * Derived classes are free to overwrite this method, but they should
317  * call this base class method in the new implementation.
318  **/
319  virtual void setDefaultButton( YPushButton * defaultButton );
320 
321  /**
322  * Activate this dialog: Make sure that it is shown as the topmost dialog
323  * of this application and that it can receive input.
324  *
325  * Derived classes are required to implement this.
326  **/
327  virtual void activate() = 0;
328 
329  /**
330  * Show the specified text in a pop-up dialog with a local event loop.
331  * This is useful for help texts.
332  * 'richText' indicates if YRichText formatting should be applied.
333  **/
334  static void showText( const std::string & text, bool richText = false );
335 
336  /**
337  * Show the help text for the specified widget. If it doesn't have one,
338  * traverse up the widget hierarchy until there is one.
339  *
340  * If there is a help text, it is displayed in a pop-up dialog with a local
341  * event loop.
342  *
343  * This returns 'true' on success (there was a help text) and 'false' on
344  * failure (no help text).
345  **/
346  static bool showHelpText( YWidget * widget );
347 
348  /**
349  * Show the release notes
350  *
351  * If there are release notes, they are displayed in a pop-up dialog with a local
352  * event loop.
353  *
354  * This returns 'true' on success (there were relnotes) and 'false' on
355  * failure (no relnotes).
356  **/
357  static bool showRelNotesText();
358 
359 
360 protected:
361 
362  /**
363  * Internal open() method. This is called (exactly once during the life
364  * time of the dialog) in open().
365  *
366  * Derived classes are required to implement this to do whatever is
367  * necessary to make this dialog visible on the screen.
368  **/
369  virtual void openInternal() = 0;
370 
371  /**
372  * Wait for a user event.
373  *
374  * Derived classes are required to implement this.
375  **/
376  virtual YEvent * waitForEventInternal( int timeout_millisec ) = 0;
377 
378  /**
379  * Check if a user event is pending. If there is one, return it.
380  * If there is none, do not wait for one - return 0.
381  *
382  * Derived classes are required to implement this.
383  **/
384  virtual YEvent * pollEventInternal() = 0;
385 
386  /**
387  * Filter out invalid events: Return 0 if the event does not belong to this
388  * dialog or the unchanged event if it does.
389  **/
390  YEvent * filterInvalidEvents( YEvent * event );
391 
392  /**
393  * Call the installed event filters.
394  **/
395  YEvent * callEventFilters( YEvent * event );
396 
397  /**
398  * Delete all (remaining) event filters.
399  **/
400  void deleteEventFilters();
401 
402  /**
403  * Stack holding all currently existing dialogs.
404  **/
405  static std::stack<YDialog *> _dialogStack;
406 
407 private:
408 
410 };
411 
412 
413 #endif // YDialog_h
YPushButton * defaultButton() const
Return this dialog's default button: The button that is activated when the user hits [Return] anywher...
Definition: YDialog.cc:337
void deleteEvent(YEvent *event)
Delete an event.
Definition: YDialog.cc:508
static bool showHelpText(YWidget *widget)
Show the help text for the specified widget.
Definition: YDialog.cc:700
void deleteEventFilters()
Delete all (remaining) event filters.
Definition: YDialog.cc:237
virtual void setDefaultButton(YPushButton *defaultButton)
Set this dialog's default button (the button that is activated when the user hits [Return] anywhere i...
Definition: YDialog.cc:344
Helper class to manage keyboard shortcuts within one dialog and resolve keyboard shortcut conflicts...
void postponeShortcutCheck()
From now on, postpone keyboard shortcut checks - i.e.
Definition: YDialog.cc:305
static bool deleteTopmostDialog(bool doThrow=true)
Delete the topmost dialog.
Definition: YDialog.cc:545
Abstract base class to filter events.
Definition: YEventFilter.h:62
Abstract base class for events to be returned upon UI::UserInput() and related functions.
Definition: YEvent.h:43
YDialogType dialogType() const
Return this dialog's type (YMainDialog / YPopupDialog /YWizardDialog).
Definition: YDialog.cc:273
YEvent * filterInvalidEvents(YEvent *event)
Filter out invalid events: Return 0 if the event does not belong to this dialog or the unchanged even...
Definition: YDialog.cc:444
void checkShortcuts(bool force=false)
Checks the keyboard shortcuts of widgets in this dialog unless shortcut checks are postponed or 'forc...
Definition: YDialog.cc:319
Container widget class that manages one child.
void removeEventFilter(YEventFilter *eventFilter)
Remove an event filter.
Definition: YDialog.cc:622
virtual void openInternal()=0
Internal open() method.
static void deleteAllDialogs()
Delete all open dialogs.
Definition: YDialog.cc:562
bool shortcutCheckPostponed() const
Return whether or not shortcut checking is currently postponed.
Definition: YDialog.cc:312
virtual YEvent * pollEventInternal()=0
Check if a user event is pending.
static YDialog * currentDialog(bool doThrow=true)
Return the current (topmost) dialog.
Definition: YDialog.cc:531
bool isTopmostDialog() const
Return 'true' if this dialog is the topmost dialog.
Definition: YDialog.cc:224
YEvent * callEventFilters(YEvent *event)
Call the installed event filters.
Definition: YDialog.cc:634
virtual void highlight(YWidget *child)
Highlight a child widget of this dialog.
Definition: YDialog.h:307
void open()
Open a newly created dialog: Finalize it and make it visible on the screen.
Definition: YDialog.cc:203
void addEventFilter(YEventFilter *eventFilter)
Add an event filter.
Definition: YDialog.cc:600
YDialog(YDialogType dialogType, YDialogColorMode colorMode=YDialogNormalColor)
Constructor.
Definition: YDialog.cc:150
void setInitialSize()
Set the initial dialog size, depending on dialogType: YMainDialog dialogs get the UI's "default main...
Definition: YDialog.cc:358
static void deleteTo(YDialog *dialog)
Delete all dialogs from the topmost to the one specified.
Definition: YDialog.cc:572
static bool showRelNotesText()
Show the release notes.
Definition: YDialog.cc:731
virtual void activate()=0
Activate this dialog: Make sure that it is shown as the topmost dialog of this application and that i...
static void showText(const std::string &text, bool richText=false)
Show the specified text in a pop-up dialog with a local event loop.
Definition: YDialog.cc:654
static int openDialogsCount()
Returns the number of currently open dialogs (from 1 on), i.e., the depth of the dialog stack...
Definition: YDialog.cc:593
virtual ~YDialog()
Destructor.
Definition: YDialog.cc:167
void recalcLayout()
Recalculate the layout of the dialog and of all its children after children have been added or remove...
Definition: YDialog.cc:370
virtual YEvent * waitForEventInternal(int timeout_millisec)=0
Wait for a user event.
YEvent * pollEvent()
Check if a user event is pending.
Definition: YDialog.cc:419
Abstract base class of all UI widgets.
Definition: YWidget.h:54
static YDialog * topmostDialog(bool doThrow=true)
Alias for currentDialog().
Definition: YDialog.h:195
virtual const char * widgetClass() const
Return a descriptive name of this widget class for logging, debugging etc.
Definition: YDialog.h:69
bool destroy(bool doThrow=true)
Close and delete this dialog (and all its children) if it is the topmost dialog.
Definition: YDialog.cc:252
static std::stack< YDialog * > _dialogStack
Stack holding all currently existing dialogs.
Definition: YDialog.h:405
YEvent * waitForEvent(int timeout_millisec=0)
Wait for a user event.
Definition: YDialog.cc:379
bool isOpen() const
Return 'true' if open() has already been called for this dialog.
Definition: YDialog.cc:217
YDialogColorMode colorMode() const
Return this dialog's color mode.
Definition: YDialog.cc:298
bool isMainDialog()
Return 'true' if this dialog is a dialog of main dialog size: YMainDialog or YWizardDialog.
Definition: YDialog.cc:280