libyui  3.3.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 protected:
235 
236  /**
237  * This virtual method is called when threads are activated in case the
238  * execution control is currently on the side of the module. This means
239  * that no UserInput() or PollInput() is pending. The module just does some
240  * work. The UI <-> module protocol is in the "UI waits for the next
241  * command" state. The UI can override this method when it wants to react
242  * to user input or other external events such as repaint requests from the
243  * X server.
244  *
245  * 'fd_ycp' file descriptor that should be used to determine when
246  * to leave the idle loop. As soon as it is readable, the loop must
247  * be left. In order to avoid polling you can combine it with other
248  * ui-specific fds and do a common select() call.
249  **/
250  virtual void idleLoop( int fd_ycp ) = 0;
251 
252  /**
253  * Tells the ui thread that it should terminate and waits
254  * until it does so.
255  **/
256  void terminateUIThread();
257 
258  /**
259  * Creates and launches the ui thread.
260  **/
261  void createUIThread();
262  friend void *start_ui_thread( void *ui_int );
263 
264  /**
265  * Destructor for the UI thread. This will be called as the last thing the
266  * UI thread does.
267  *
268  * Derived classes can overwrite this. In most cases it makes sense to call
269  * this base class method in the new implementation.
270  **/
271  virtual void uiThreadDestructor();
272 
273  /**
274  * Signals the ui thread by sending one byte through the pipe
275  * to it.
276  **/
277  void signalUIThread();
278 
279  /**
280  * Waits for the ui thread to send one byte through the pipe
281  * to the ycp thread and reads this byte from the pipe.
282  **/
283  bool waitForUIThread();
284 
285  /**
286  * Signals the ycp thread by sending one byte through the pipe
287  * to it.
288  **/
289  void signalYCPThread();
290 
291  /**
292  * Waits for the ycp thread to send one byte through the pipe
293  * to the ycp thread and reads this byte from the pipe.
294  **/
295  bool waitForYCPThread();
296 
297  /**
298  * Set the button order (in YButtonBox widgets) from environment
299  * variables:
300  *
301  * $Y2_BUTTON_ORDER="KDE"
302  * $Y2_BUTTON_ORDER="Gnome"
303  *
304  * (all case insensitive)
305  **/
307 
308 
309  //
310  // Data members
311  //
312 
313  /**
314  * true if a seperate UI thread is created
315  **/
317 
318  /**
319  * Handle to the ui thread.
320  **/
321  pthread_t _uiThread;
322 
323  /**
324  * Inter-thread communication between the YCP thread and the UI thread:
325  * The YCP thread supplies data here and signals the UI thread,
326  * the UI thread picks up the data, executes the function, puts
327  * the result here and signals the YCP thread that waits until
328  * the result is available.
329  **/
331 
332  /**
333  * Used to synchronize data transfer with the ui thread.
334  * It stores a pair of file descriptors of a pipe. For each YCP value
335  * we send to the ui thread, we write one aribrary byte here.
336  **/
337  int pipe_to_ui[2];
338 
339  /**
340  * Used to synchronize data transfer with the ui thread.
341  * It stores a pair of file descriptors of a pipe. For each YCP value
342  * we get from the ui thread, we read one aribrary byte from here.
343  **/
344  int pipe_from_ui[2];
345 
346  /**
347  * This is a flag that signals the ui thread that it should
348  * terminate. This is done by setting the flag to true. The ui
349  * thread replies by setting the flag back to false directly
350  * after terminating itself.
351  **/
353 
354  /**
355  * Flag that keeps track of blocked events.
356  * Never query this directly, use eventsBlocked() instead.
357  **/
359 
360 private:
361 
362  static YUI * _ui;
363 };
364 
365 
366 
367 #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:344
void setButtonOrderFromEnvironment()
Set the button order (in YButtonBox widgets) from environment variables:
Definition: YUI.cc:386
static YWidgetFactory * widgetFactory()
Return the widget factory that provides all the createXY() methods for standard (mandatory, i.e.
Definition: YUI.cc:126
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:235
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:182
int pipe_to_ui[2]
Used to synchronize data transfer with the ui thread.
Definition: YUI.h:337
void terminateUIThread()
Tells the ui thread that it should terminate and waits until it does so.
Definition: YUI.cc:246
bool _withThreads
true if a seperate UI thread is created
Definition: YUI.h:316
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:273
static void ensureUICreated()
Make sure there is a UI (with a UI plug-in) created.
Definition: YUI.cc:170
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:111
void shutdownThreads()
Shut down multithreading.
Definition: YUI.cc:259
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:325
bool _eventsBlocked
Flag that keeps track of blocked events.
Definition: YUI.h:358
void uiThreadMainLoop()
This method implements the UI thread in case it is existing.
Definition: YUI.cc:353
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:141
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:285
void signalYCPThread()
Signals the ycp thread by sending one byte through the pipe to it.
Definition: YUI.cc:313
virtual ~YUI()
Destructor.
Definition: YUI.cc:82
static YApplication * app()
Return the global YApplication object.
Definition: YUI.cc:156
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:352
A window in the desktop environment.
Definition: YDialog.h:47
Abstract widget factory for mandatory widgets.
YUI(bool withThreads)
Constructor.
Definition: YUI.cc:69
pthread_t _uiThread
Handle to the ui thread.
Definition: YUI.h:321
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:118
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:330