libyui  3.4.2
YUI.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: YUI.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YUI_h
26 #define YUI_h
27 
28 #include <pthread.h>
29 #include <string>
30 
31 #include "YTypes.h"
32 #include "YSettings.h"
33 
34 class YApplication;
35 class YWidget;
36 class YWidgetFactory;
38 class YEvent;
39 class YBuiltinCaller;
40 class YDialog;
41 class YMacroPlayer;
42 class YMacroRecorder;
43 
44 
45 /**
46  * Abstract base class of a libYUI user interface.
47  **/
48 class YUI
49 {
50  friend class YUIFunction;
51  friend class YUILoader;
52 
53 protected:
54  /**
55  * Constructor.
56  **/
57  YUI( bool withThreads );
58 
59 public:
60 
61  /**
62  * Destructor.
63  **/
64  virtual ~YUI();
65 
66  /**
67  * Shut down multithreading. This needs to be called before the destructor
68  * if the UI was created with threads. If the UI was created without
69  * threads, this does nothing.
70  **/
71  void shutdownThreads();
72 
73  /**
74  * Access the global UI.
75  **/
76  static YUI * ui();
77 
78  /**
79  * Return the widget factory that provides all the createXY() methods for
80  * standard (mandatory, i.e. non-optional) widgets.
81  *
82  * This will create the factory upon the first call and return a pointer to
83  * the one and only (singleton) factory upon each subsequent call.
84  * This may throw exceptions if the factory cannot be created.
85  **/
86  static YWidgetFactory * widgetFactory();
87 
88  /**
89  * Return the widget factory that provides all the createXY() methods for
90  * optional ("special") widgets and the corresponding hasXYWidget()
91  * methods.
92  *
93  * This will create the factory upon the first call and return a pointer to
94  * the one and only (singleton) factory upon each subsequent call.
95  * This may throw exceptions if the factory cannot be created.
96  **/
98 
99  /**
100  * Return the global YApplication object.
101  *
102  * This will create the YApplication upon the first call and return a
103  * pointer to the one and only (singleton) YApplication upon each
104  * subsequent call. This may throw exceptions if the YApplication cannot
105  * be created.
106  **/
107  static YApplication * app();
108 
109  /**
110  * Aliases for YUI::app()
111  **/
112  static YApplication * application() { return app(); }
113  static YApplication * yApp() { return app(); }
114 
115  /**
116  * Make sure there is a UI (with a UI plug-in) created.
117  *
118  * If there is none yet, this will use all-default parameters to load a UI
119  * plug-in and create a UI (without threads).
120  **/
121  static void ensureUICreated();
122 
123 
124 protected:
125 
126  /**
127  * Create the widget factory that provides all the createXY() methods for
128  * standard (mandatory, i.e. non-optional) widgets.
129  *
130  * Derived classes are required to implement this.
131  **/
132  virtual YWidgetFactory * createWidgetFactory() = 0;
133 
134  /**
135  * Create the widget factory that provides all the createXY() methods for
136  * optional ("special") widgets and the corresponding hasXYWidget()
137  * methods.
138  *
139  * Derived classes are required to implement this.
140  **/
142 
143  /**
144  * Create the YApplication object that provides global methods.
145  *
146  * Derived classes are required to implement this.
147  **/
148  virtual YApplication * createApplication() = 0;
149 
150 
151 public:
152 
153  /**
154  * Block (or unblock) events. If events are blocked, any event sent
155  * should be ignored until events are unblocked again.
156  *
157  * This default implementation keeps track of a simple internal flag that
158  * can be queried with eventsBlocked(), so if you reimplement
159  * blockEvents(), be sure to reimplement eventsBlocked() as well.
160  **/
161  virtual void blockEvents( bool block = true ) { _eventsBlocked = block; }
162 
163  /**
164  * Unblock events previously blocked. This is just an alias for
165  * blockEvents( false) for better readability.
166  *
167  * Note: This method is intentionally not virtual.
168  **/
169  void unblockEvents() { blockEvents( false ); }
170 
171  /**
172  * Returns 'true' if events are currently blocked.
173  *
174  * Reimplement this if you reimplement blockEvents().
175  **/
176  virtual bool eventsBlocked() const { return _eventsBlocked; }
177 
178  /**
179  * Notification that a widget is being deleted.
180  * This is called from the YWidget destructor.
181  *
182  * Derived classes can implement this for any clean-up actions such as
183  * deleting any events that might be pending for that widget.
184  **/
185  virtual void deleteNotify( YWidget * widget ) {}
186 
187  /**
188  * Must be called after the constructor of the Qt/NCurses ui
189  * is ready. Starts the ui thread.
190  **/
192 
193  /**
194  * Running with threads?
195  **/
196  bool runningWithThreads() const { return _withThreads; }
197 
198  /**
199  * This method implements the UI thread in case it is existing.
200  * The loop consists of calling idleLoop, getting the next
201  * command from the @ref YCPUIComponent, evaluating it, which
202  * possibly invovles calling userInput() or pollInput()
203  * and writes the answer back to the other thread where the request
204  * came from.
205  **/
206  void uiThreadMainLoop();
207 
208  /**
209  * Return the transparent inter-thread communication.
210  * This will return 0 until set from the outside.
211  **/
213 
214  /**
215  * Set the transparent inter-thread communication.
216  * Built-ins are only really called if there is a valid YBuiltinCaller set.
217  **/
219  { _builtinCaller = caller; }
220 
221  /**
222  * UI-specific runPkgSelection method.
223  *
224  * Derived classes are required to implement this.
225  *
226  * The packageSelector's dialog will take care of the event and delete it
227  * when appropriate. The returned pointer is valid until the next call to
228  * YDialog::userInput(), YDialog::pollInput(), or YUI::runPkgSelection() or
229  * until the dialog with the packageSelector is destroyed.
230  **/
231  virtual YEvent * runPkgSelection( YWidget * packageSelector ) = 0;
232 
233  /**
234  * Send a widget ID. This implementation simply sets the keyboard focus to
235  * that widget. If there is no widget with that ID, this will throw a
236  * YUIWidgetNotFoundException. This function returns the widget that was
237  * found in case the caller wants to do more with it than just set the
238  * keyboard focus to it.
239  **/
240  YWidget * sendWidgetID( const std::string & id );
241 
242 
243 protected:
244 
245  /**
246  * This virtual method is called when threads are activated in case the
247  * execution control is currently on the side of the module. This means
248  * that no UserInput() or PollInput() is pending. The module just does some
249  * work. The UI <-> module protocol is in the "UI waits for the next
250  * command" state. The UI can override this method when it wants to react
251  * to user input or other external events such as repaint requests from the
252  * X server.
253  *
254  * 'fd_ycp' file descriptor that should be used to determine when
255  * to leave the idle loop. As soon as it is readable, the loop must
256  * be left. In order to avoid polling you can combine it with other
257  * ui-specific fds and do a common select() call.
258  **/
259  virtual void idleLoop( int fd_ycp ) = 0;
260 
261  /**
262  * Tells the ui thread that it should terminate and waits
263  * until it does so.
264  **/
265  void terminateUIThread();
266 
267  /**
268  * Creates and launches the ui thread.
269  **/
270  void createUIThread();
271  friend void *start_ui_thread( void *ui_int );
272 
273  /**
274  * Destructor for the UI thread. This will be called as the last thing the
275  * UI thread does.
276  *
277  * Derived classes can overwrite this. In most cases it makes sense to call
278  * this base class method in the new implementation.
279  **/
280  virtual void uiThreadDestructor();
281 
282  /**
283  * Signals the ui thread by sending one byte through the pipe
284  * to it.
285  **/
286  void signalUIThread();
287 
288  /**
289  * Waits for the ui thread to send one byte through the pipe
290  * to the ycp thread and reads this byte from the pipe.
291  **/
292  bool waitForUIThread();
293 
294  /**
295  * Signals the ycp thread by sending one byte through the pipe
296  * to it.
297  **/
298  void signalYCPThread();
299 
300  /**
301  * Waits for the ycp thread to send one byte through the pipe
302  * to the ycp thread and reads this byte from the pipe.
303  **/
304  bool waitForYCPThread();
305 
306  /**
307  * Set the button order (in YButtonBox widgets) from environment
308  * variables:
309  *
310  * $Y2_BUTTON_ORDER="KDE"
311  * $Y2_BUTTON_ORDER="Gnome"
312  *
313  * (all case insensitive)
314  **/
316 
317 
318  //
319  // Data members
320  //
321 
322  /**
323  * true if a seperate UI thread is created
324  **/
326 
327  /**
328  * Handle to the ui thread.
329  **/
330  pthread_t _uiThread;
331 
332  /**
333  * Inter-thread communication between the YCP thread and the UI thread:
334  * The YCP thread supplies data here and signals the UI thread,
335  * the UI thread picks up the data, executes the function, puts
336  * the result here and signals the YCP thread that waits until
337  * the result is available.
338  **/
340 
341  /**
342  * Used to synchronize data transfer with the ui thread.
343  * It stores a pair of file descriptors of a pipe. For each YCP value
344  * we send to the ui thread, we write one aribrary byte here.
345  **/
346  int pipe_to_ui[2];
347 
348  /**
349  * Used to synchronize data transfer with the ui thread.
350  * It stores a pair of file descriptors of a pipe. For each YCP value
351  * we get from the ui thread, we read one aribrary byte from here.
352  **/
353  int pipe_from_ui[2];
354 
355  /**
356  * This is a flag that signals the ui thread that it should
357  * terminate. This is done by setting the flag to true. The ui
358  * thread replies by setting the flag back to false directly
359  * after terminating itself.
360  **/
362 
363  /**
364  * Flag that keeps track of blocked events.
365  * Never query this directly, use eventsBlocked() instead.
366  **/
368 
369 private:
370 
371  static YUI * _ui;
372 };
373 
374 
375 
376 #endif // YUI_h
virtual YEvent * runPkgSelection(YWidget *packageSelector)=0
UI-specific runPkgSelection method.
Abstract base class for macro recorders.
Abstract widget factory for optional ("special") widgets.
void setBuiltinCaller(YBuiltinCaller *caller)
Set the transparent inter-thread communication.
Definition: YUI.h:218
int pipe_from_ui[2]
Used to synchronize data transfer with the ui thread.
Definition: YUI.h:353
void setButtonOrderFromEnvironment()
Set the button order (in YButtonBox widgets) from environment variables:
Definition: YUI.cc:387
static YWidgetFactory * widgetFactory()
Return the widget factory that provides all the createXY() methods for standard (mandatory, i.e.
Definition: YUI.cc:127
Author: Stefan Hundhammer sh@suse.de
Abstract base class of a libYUI user interface.
Definition: YUI.h:48
void createUIThread()
Creates and launches the ui thread.
Definition: YUI.cc:236
virtual YApplication * createApplication()=0
Create the YApplication object that provides global methods.
virtual bool eventsBlocked() const
Returns &#39;true&#39; if events are currently blocked.
Definition: YUI.h:176
Abstract base class for macro player.
Definition: YMacroPlayer.h:35
static YApplication * application()
Aliases for YUI::app()
Definition: YUI.h:112
void topmostConstructorHasFinished()
Must be called after the constructor of the Qt/NCurses ui is ready.
Definition: YUI.cc:183
int pipe_to_ui[2]
Used to synchronize data transfer with the ui thread.
Definition: YUI.h:346
void terminateUIThread()
Tells the ui thread that it should terminate and waits until it does so.
Definition: YUI.cc:247
YWidget * sendWidgetID(const std::string &id)
Send a widget ID.
Definition: YUI.cc:482
bool _withThreads
true if a seperate UI thread is created
Definition: YUI.h:325
bool runningWithThreads() const
Running with threads?
Definition: YUI.h:196
Abstract base class for events to be returned upon UI::UserInput() and related functions.
Definition: YEvent.h:43
void signalUIThread()
Signals the ui thread by sending one byte through the pipe to it.
Definition: YUI.cc:274
static void ensureUICreated()
Make sure there is a UI (with a UI plug-in) created.
Definition: YUI.cc:171
virtual YOptionalWidgetFactory * createOptionalWidgetFactory()=0
Create the widget factory that provides all the createXY() methods for optional ("special") widgets a...
virtual void uiThreadDestructor()
Destructor for the UI thread.
Definition: YUI.cc:112
void shutdownThreads()
Shut down multithreading.
Definition: YUI.cc:260
bool waitForYCPThread()
Waits for the ycp thread to send one byte through the pipe to the ycp thread and reads this byte from...
Definition: YUI.cc:326
bool _eventsBlocked
Flag that keeps track of blocked events.
Definition: YUI.h:367
void uiThreadMainLoop()
This method implements the UI thread in case it is existing.
Definition: YUI.cc:354
Class to load one of the concrete UI plug-ins: Qt, NCurses, Gtk.
Definition: YUILoader.h:45
virtual void blockEvents(bool block=true)
Block (or unblock) events.
Definition: YUI.h:161
Class for application-wide values and functions.
Definition: YApplication.h:45
static YOptionalWidgetFactory * optionalWidgetFactory()
Return the widget factory that provides all the createXY() methods for optional ("special") widgets a...
Definition: YUI.cc:142
virtual void deleteNotify(YWidget *widget)
Notification that a widget is being deleted.
Definition: YUI.h:185
bool waitForUIThread()
Waits for the ui thread to send one byte through the pipe to the ycp thread and reads this byte from ...
Definition: YUI.cc:286
void signalYCPThread()
Signals the ycp thread by sending one byte through the pipe to it.
Definition: YUI.cc:314
virtual ~YUI()
Destructor.
Definition: YUI.cc:83
static YApplication * app()
Return the global YApplication object.
Definition: YUI.cc:157
virtual YWidgetFactory * createWidgetFactory()=0
Create the widget factory that provides all the createXY() methods for standard (mandatory, i.e.
bool _terminate_ui_thread
This is a flag that signals the ui thread that it should terminate.
Definition: YUI.h:361
A window in the desktop environment.
Definition: YDialog.h:47
Abstract widget factory for mandatory widgets.
YUI(bool withThreads)
Constructor.
Definition: YUI.cc:70
pthread_t _uiThread
Handle to the ui thread.
Definition: YUI.h:330
void unblockEvents()
Unblock events previously blocked.
Definition: YUI.h:169
YBuiltinCaller * builtinCaller() const
Return the transparent inter-thread communication.
Definition: YUI.h:212
Abstract base class of all UI widgets.
Definition: YWidget.h:54
static YUI * ui()
Access the global UI.
Definition: YUI.cc:119
Abstract base class for transparently calling a built-in function.
virtual void idleLoop(int fd_ycp)=0
This virtual method is called when threads are activated in case the execution control is currently o...
YBuiltinCaller * _builtinCaller
Inter-thread communication between the YCP thread and the UI thread: The YCP thread supplies data her...
Definition: YUI.h:339