libyui  3.3.1
YApplication.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: YApplication.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YApplication_h
26 
27 #include <string>
28 #include <map>
29 #include "YUI.h"
30 #include "ImplPtr.h"
31 #include "YMenuItem.h"
32 #include "YIconLoader.h"
33 
34 
35 
36 class YWidget;
37 class YWidgetID;
38 struct YApplicationPrivate;
39 
40 
41 /**
42  * Class for application-wide values and functions.
43  * This is a singleton. Access and create it via the static functions in YUI.
44  **/
46 {
47 protected:
48 
49  friend class YUI;
50  /**
51  * Constructor.
52  *
53  * Use YUI::app() to get the singleton for this class.
54  **/
55  YApplication();
56 
57  /**
58  * Destructor.
59  **/
60  virtual ~YApplication();
61 
62 public:
63 
64  /**
65  * Find a widget in the topmost dialog by its ID.
66  *
67  * If there is no widget with that ID (or no dialog at all), this function
68  * throws a YUIWidgetNotFoundException if 'doThrow' is 'true'. It returns 0
69  * if 'doThrow' is 'false'.
70  **/
71  YWidget * findWidget( YWidgetID * id, bool doThrow = true ) const;
72 
73  /**
74  * Get the base path for icons used by the UI. Selection widgets like
75  * YSelectionBox, YComboBox, etc. or YWizard prepend this to icon
76  * specifications that don't use an absolute path.
77  **/
78  virtual std::string iconBasePath() const;
79 
80  /**
81  * Set the icon base path.
82  **/
83  virtual void setIconBasePath( const std::string & newIconBasePath );
84 
85  YIconLoader *iconLoader();
86 
87  /**
88  * Return the default function key number for a widget with the specified
89  * label or 0 if there is none. Any keyboard shortcuts that may be
90  * contained in 'label' are stripped away before any comparison.
91  *
92  * The basic idea behind this concept is to have an easy default mapping
93  * from buttons etc. with the same semantics to function keys:
94  *
95  * "OK" -> F10
96  * "Accept" -> F10
97  * "Yes" -> F10
98  * "Next" -> F10
99  *
100  * "Cancel" -> F9
101  * "No" -> F9
102  * ...
103  *
104  * This function returns 10 for F10, F for F9 etc.;
105  * 0 means "no function key".
106  **/
107  int defaultFunctionKey( const std::string & label ) const;
108 
109  /**
110  * Add a mapping from the specified label to the specified F-key number.
111  * This is the counterpart to defaultFunctionKey().
112  *
113  * This only affects widgets that are created after this call.
114  **/
115  void setDefaultFunctionKey( const std::string & label, int fkey );
116 
117  /**
118  * Clear all previous label-to-function-key mappings.
119  **/
121 
122  /**
123  * Set language and encoding for the locale environment ($LANG).
124  *
125  * This affects UI-internal translations (e.g. for predefined dialogs like
126  * file selection), encoding and fonts.
127  *
128  * 'language' is the ISO short code ("de_DE", "en_US", ...).
129  *
130  * 'encoding' an (optional) encoding ("utf8", ...) that will be appended if
131  * present.
132  *
133  * Derived classes can overwrite this method, but they should call this
134  * base class method at the beginning of the new implementation.
135  **/
136  virtual void setLanguage( const std::string & language,
137  const std::string & encoding = std::string() );
138 
139  /**
140  * Return the current language from the locale environment ($LANG).
141  * If 'stripEncoding' is true, any encoding (".utf8" etc.) is removed.
142  **/
143  std::string language( bool stripEncoding = false ) const;
144 
145  /**
146  * Return a string for a named glyph:
147  *
148  * YUIGlyph_ArrowLeft
149  * YUIGlyph_ArrowRight
150  * YUIGlyph_ArrowUp
151  * YUIGlyph_ArrowDown
152  * YUIGlyph_CheckMark
153  * YUIGlyph_BulletArrowRight
154  * YUIGlyph_BulletCircle
155  * YUIGlyph_BulletSquare
156  *
157  * Using this is discouraged in new applications.
158  * This method is available for backward compatibility.
159  *
160  * This default implementation returns simple textual representations for
161  * each glyph simbol (e.g., "->" for YUIGlyphArrorRight).
162  *
163  * Derived classes are free to overwrite this. It does not make sense to
164  * call this base class method in a new implementation.
165  **/
166  virtual std::string glyph( const std::string & glyphSymbolName );
167 
168  /**
169  * Open a directory selection box and prompt the user for an existing
170  * directory.
171  *
172  * 'startDir' is the initial directory that is displayed.
173  *
174  * 'headline' is an explanatory text for the directory selection box.
175  * Graphical UIs may omit that if no window manager is running.
176  *
177  * Returns the selected directory name
178  * or an empty string if the user canceled the operation.
179  *
180  * Derived classes are required to implement this.
181  **/
182  virtual std::string askForExistingDirectory( const std::string & startDir,
183  const std::string & headline ) = 0;
184 
185  /**
186  * Open a file selection box and prompt the user for an existing file.
187  *
188  * 'startWith' is the initial directory or file.
189  *
190  * 'filter' is one or more blank-separated file patterns, e.g.
191  * "*.png *.jpg"
192  *
193  * 'headline' is an explanatory text for the file selection box.
194  * Graphical UIs may omit that if no window manager is running.
195  *
196  * Returns the selected file name
197  * or an empty string if the user canceled the operation.
198  *
199  * Derived classes are required to implement this.
200  **/
201  virtual std::string askForExistingFile( const std::string & startWith,
202  const std::string & filter,
203  const std::string & headline ) = 0;
204 
205  /**
206  * Open a file selection box and prompt the user for a file to save data
207  * to. Automatically asks for confirmation if the user selects an existing
208  * file.
209  *
210  * 'startWith' is the initial directory or file.
211  *
212  * 'filter' is one or more blank-separated file patterns, e.g.
213  * "*.png *.jpg"
214  *
215  * 'headline' is an explanatory text for the file selection box.
216  * Graphical UIs may omit that if no window manager is running.
217  *
218  * Returns the selected file name
219  * or an empty string if the user canceled the operation.
220  *
221  * Derived classes are required to implement this.
222  **/
223  virtual std::string askForSaveFileName( const std::string & startWith,
224  const std::string & filter,
225  const std::string & headline ) = 0;
226 
227  /**
228  * Open a context menu for a widget
229  *
230  * 'itemCollection' describes the menu structure
231  *
232  * Returns true on success (otherwise false).
233  *
234  * Derived classes are free to overwrite this.
235  **/
236  virtual bool openContextMenu( const YItemCollection & itemCollection );
237 
238 
239  /**
240  * Set the current product name ("openSUSE", "SLES", ...).
241  * This name will be expanded in help texts when the &product; entity is
242  * used.
243  *
244  * Derived classes can overwrite this method, but they should call this
245  * base class method in the new implementation.
246  **/
247  virtual void setProductName( const std::string & productName );
248 
249  /**
250  * Get the current product name ("openSUSE", "SLES", ...).
251  **/
252  std::string productName() const;
253 
254  /**
255  * Set release notes; map product => text
256  *
257  */
258  void setReleaseNotes( const std::map<std::string,std::string> & relNotes );
259 
260  /**
261  * Get the current release notes map
262  **/
263  std::map<std::string,std::string> releaseNotes() const;
264 
265  /**
266  * Set whether the product logo (in top bar) should be shown
267  */
268  void setShowProductLogo( bool show );
269 
270  /**
271  * Return true if product logo should be shown
272  */
273  bool showProductLogo() const;
274 
275  /**
276  * Convert logical layout spacing units into device dependent units.
277  * A default size dialog is assumed to be 80x25 layout spacing units.
278  *
279  * Derived classes may want to reimplement this method.
280  **/
281  virtual int deviceUnits( YUIDimension dim, float layoutUnits );
282 
283  /**
284  * Convert device dependent units into logical layout spacing units.
285  * A default size dialog is assumed to be 80x25 layout spacing units.
286  *
287  * Derived classes may want to reimplement this method.
288  **/
289  virtual float layoutUnits( YUIDimension dim, int deviceUnits );
290 
291  /**
292  * Set reverse layout for Arabic / Hebrew support.
293  *
294  * Derived classes can overwrite this method, but they should call this
295  * base class method in the new implementation.
296  **/
297  virtual void setReverseLayout( bool reverse );
298 
299  /**
300  * Returns 'true' if widget geometry should be reversed for languages that
301  * have right-to-left writing direction (Arabic, Hebrew).
302  **/
303  bool reverseLayout() const;
304 
305  /**
306  * Change the (mouse) cursor to indicate busy status.
307  * This default implementation does nothing.
308  **/
309  virtual void busyCursor() {}
310 
311  /**
312  * Change the (mouse) cursor back from busy status to normal.
313  * This default implementation does nothing.
314  **/
315  virtual void normalCursor() {}
316 
317  /**
318  * Make a screen shot and save it to the specified file.
319  * This default implementation does nothing.
320  **/
321  virtual void makeScreenShot( const std::string & fileName ) {}
322 
323  /**
324  * Beep.
325  * This default implementation does nothing.
326  **/
327  virtual void beep() {}
328 
329 
330  //
331  // NCurses (text mode) specific
332  //
333 
334  /**
335  * Redraw the screen.
336  * This default implementation does nothing.
337  **/
338  virtual void redrawScreen() {}
339 
340  /**
341  * Initialize the (text) console keyboard.
342  * This default implementation does nothing.
343  **/
344  virtual void initConsoleKeyboard() {}
345 
346  /**
347  * Set the (text) console font according to the current encoding etc.
348  * See the setfont(8) command and the console HowTo for details.
349  *
350  * This default implementation does nothing.
351  **/
352  virtual void setConsoleFont( const std::string & console_magic,
353  const std::string & font,
354  const std::string & screen_map,
355  const std::string & unicode_map,
356  const std::string & language )
357  {}
358 
359  /**
360  * Run a shell command (typically an interactive program using NCurses)
361  * in a terminal (window).
362  *
363  * This is useful for text UIs (e.g., NCurses) that need special
364  * preparation prior to running an NCurses-based application and special
365  * clean-up afterwards.
366  *
367  * This default implementation logs an error and returns -1.
368  **/
369  virtual int runInTerminal( const std::string & command );
370 
371 
372  /// @{
373  /**
374  * To mix TUI (NCurses) with stdio, enclose the UI parts
375  * within openUI/closeUI
376  *
377  * This default implementation does nothing.
378  */
379  virtual void openUI() {}
380  virtual void closeUI() {}
381  /// @}
382 
383  //
384  // Display information.
385  //
386  // Width and height are returned in the the UI's native dimension:
387  // Pixels for graphical UIs, character cells for text UIs.
388  // -1 means "value cannot be obtained" for int functions.
389  //
390  // Derived classes are required to implement these functions.
391  //
392 
393  virtual int displayWidth() = 0;
394  virtual int displayHeight() = 0;
395  virtual int displayDepth() = 0;
396  virtual long displayColors() = 0;
397 
398  // Size of main dialogs
399  virtual int defaultWidth() = 0;
400  virtual int defaultHeight() = 0;
401 
402  //
403  // UI capabilities
404  //
405 
406  virtual bool isTextMode() = 0;
407  virtual bool hasImageSupport() = 0;
408  virtual bool hasIconSupport() = 0;
409  virtual bool hasAnimationSupport() = 0;
410  virtual bool hasFullUtf8Support() = 0;
411  virtual bool richTextSupportsTable() = 0;
412  virtual bool leftHandedMouse() = 0;
413  virtual bool hasWizardDialogSupport() { return false; }
414 
415 
416  /**
417  * Set the application title
418  **/
419  virtual void setApplicationTitle ( const std::string& title );
420 
421  /**
422  * Get the application title
423  *
424  * Default title is the running command (argv[0])
425  **/
426  virtual const std::string& applicationTitle() const;
427 
428  /**
429  * Set the application Icon
430  **/
431  virtual void setApplicationIcon ( const std::string& icon );
432 
433  /**
434  * Get the application Icon
435  *
436  * Default icon is an empty string
437  **/
438  virtual const std::string& applicationIcon() const;
439 
440 private:
441 
443 
444 };
445 
446 #define YApplication_h
447 
448 #endif // YApplication_h
std::string productName() const
Get the current product name ("openSUSE", "SLES", ...).
bool showProductLogo() const
Return true if product logo should be shown.
virtual void setApplicationTitle(const std::string &title)
Set the application title.
virtual bool openContextMenu(const YItemCollection &itemCollection)
Open a context menu for a widget.
std::string language(bool stripEncoding=false) const
Return the current language from the locale environment ($LANG).
virtual std::string iconBasePath() const
Get the base path for icons used by the UI.
Definition: YApplication.cc:93
Abstract base class of a libYUI user interface.
Definition: YUI.h:48
virtual const std::string & applicationIcon() const
Get the application Icon.
virtual float layoutUnits(YUIDimension dim, int deviceUnits)
Convert device dependent units into logical layout spacing units.
YApplication()
Constructor.
Definition: YApplication.cc:63
int defaultFunctionKey(const std::string &label) const
Return the default function key number for a widget with the specified label or 0 if there is none...
std::vector< YItem * > YItemCollection
Collection of pointers to YItem.
Definition: YItem.h:38
void clearDefaultFunctionKeys()
Clear all previous label-to-function-key mappings.
virtual std::string askForExistingFile(const std::string &startWith, const std::string &filter, const std::string &headline)=0
Open a file selection box and prompt the user for an existing file.
virtual void openUI()
To mix TUI (NCurses) with stdio, enclose the UI parts within openUI/closeUI.
Definition: YApplication.h:379
virtual void setIconBasePath(const std::string &newIconBasePath)
Set the icon base path.
virtual int deviceUnits(YUIDimension dim, float layoutUnits)
Convert logical layout spacing units into device dependent units.
virtual std::string askForSaveFileName(const std::string &startWith, const std::string &filter, const std::string &headline)=0
Open a file selection box and prompt the user for a file to save data to.
virtual ~YApplication()
Destructor.
Definition: YApplication.cc:74
void setShowProductLogo(bool show)
Set whether the product logo (in top bar) should be shown.
virtual std::string askForExistingDirectory(const std::string &startDir, const std::string &headline)=0
Open a directory selection box and prompt the user for an existing directory.
virtual const std::string & applicationTitle() const
Get the application title.
virtual int runInTerminal(const std::string &command)
Run a shell command (typically an interactive program using NCurses) in a terminal (window)...
virtual void setConsoleFont(const std::string &console_magic, const std::string &font, const std::string &screen_map, const std::string &unicode_map, const std::string &language)
Set the (text) console font according to the current encoding etc.
Definition: YApplication.h:352
virtual void initConsoleKeyboard()
Initialize the (text) console keyboard.
Definition: YApplication.h:344
Class for application-wide values and functions.
Definition: YApplication.h:45
virtual void busyCursor()
Change the (mouse) cursor to indicate busy status.
Definition: YApplication.h:309
virtual void normalCursor()
Change the (mouse) cursor back from busy status to normal.
Definition: YApplication.h:315
YWidget * findWidget(YWidgetID *id, bool doThrow=true) const
Find a widget in the topmost dialog by its ID.
Definition: YApplication.cc:81
void setDefaultFunctionKey(const std::string &label, int fkey)
Add a mapping from the specified label to the specified F-key number.
bool reverseLayout() const
Returns &#39;true&#39; if widget geometry should be reversed for languages that have right-to-left writing di...
virtual std::string glyph(const std::string &glyphSymbolName)
Return a string for a named glyph:
std::map< std::string, std::string > releaseNotes() const
Get the current release notes map.
virtual void setApplicationIcon(const std::string &icon)
Set the application Icon.
virtual void beep()
Beep.
Definition: YApplication.h:327
virtual void makeScreenShot(const std::string &fileName)
Make a screen shot and save it to the specified file.
Definition: YApplication.h:321
virtual void setProductName(const std::string &productName)
Set the current product name ("openSUSE", "SLES", ...).
virtual void setReverseLayout(bool reverse)
Set reverse layout for Arabic / Hebrew support.
Abstract base class for widget IDs.
Definition: YWidgetID.h:36
Abstract base class of all UI widgets.
Definition: YWidget.h:54
virtual void setLanguage(const std::string &language, const std::string &encoding=std::string())
Set language and encoding for the locale environment ($LANG).
void setReleaseNotes(const std::map< std::string, std::string > &relNotes)
Set release notes; map product => text.
virtual void redrawScreen()
Redraw the screen.
Definition: YApplication.h:338