libyui  3.0.13
 All Classes Functions Variables Enumerations Friends
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;
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  * Convert logical layout spacing units into device dependent units.
267  * A default size dialog is assumed to be 80x25 layout spacing units.
268  *
269  * Derived classes may want to reimplement this method.
270  **/
271  virtual int deviceUnits( YUIDimension dim, float layoutUnits );
272 
273  /**
274  * Convert device dependent units into logical layout spacing units.
275  * A default size dialog is assumed to be 80x25 layout spacing units.
276  *
277  * Derived classes may want to reimplement this method.
278  **/
279  virtual float layoutUnits( YUIDimension dim, int deviceUnits );
280 
281  /**
282  * Set reverse layout for Arabic / Hebrew support.
283  *
284  * Derived classes can overwrite this method, but they should call this
285  * base class method in the new implementation.
286  **/
287  virtual void setReverseLayout( bool reverse );
288 
289  /**
290  * Returns 'true' if widget geometry should be reversed for languages that
291  * have right-to-left writing direction (Arabic, Hebrew).
292  **/
293  bool reverseLayout() const;
294 
295  /**
296  * Change the (mouse) cursor to indicate busy status.
297  * This default implementation does nothing.
298  **/
299  virtual void busyCursor() {}
300 
301  /**
302  * Change the (mouse) cursor back from busy status to normal.
303  * This default implementation does nothing.
304  **/
305  virtual void normalCursor() {}
306 
307  /**
308  * Make a screen shot and save it to the specified file.
309  * This default implementation does nothing.
310  **/
311  virtual void makeScreenShot( const std::string & fileName ) {}
312 
313  /**
314  * Beep.
315  * This default implementation does nothing.
316  **/
317  virtual void beep() {}
318 
319 
320  //
321  // NCurses (text mode) specific
322  //
323 
324  /**
325  * Redraw the screen.
326  * This default implementation does nothing.
327  **/
328  virtual void redrawScreen() {}
329 
330  /**
331  * Initialize the (text) console keyboard.
332  * This default implementation does nothing.
333  **/
334  virtual void initConsoleKeyboard() {}
335 
336  /**
337  * Set the (text) console font according to the current encoding etc.
338  * See the setfont(8) command and the console HowTo for details.
339  *
340  * This default implementation does nothing.
341  **/
342  virtual void setConsoleFont( const std::string & console_magic,
343  const std::string & font,
344  const std::string & screen_map,
345  const std::string & unicode_map,
346  const std::string & language )
347  {}
348 
349  /**
350  * Run a shell command (typically an interactive program using NCurses)
351  * in a terminal (window).
352  *
353  * This is useful for text UIs (e.g., NCurses) that need special
354  * preparation prior to running an NCurses-based application and special
355  * clean-up afterwards.
356  *
357  * This default implementation logs an error and returns -1.
358  **/
359  virtual int runInTerminal( const std::string & command );
360 
361 
362  //
363  // Display information.
364  //
365  // Width and height are returned in the the UI's native dimension:
366  // Pixels for graphical UIs, character cells for text UIs.
367  // -1 means "value cannot be obtained" for int functions.
368  //
369  // Derived classes are required to implement these functions.
370  //
371 
372  virtual int displayWidth() = 0;
373  virtual int displayHeight() = 0;
374  virtual int displayDepth() = 0;
375  virtual long displayColors() = 0;
376 
377  // Size of main dialogs
378  virtual int defaultWidth() = 0;
379  virtual int defaultHeight() = 0;
380 
381  //
382  // UI capabilities
383  //
384 
385  virtual bool isTextMode() = 0;
386  virtual bool hasImageSupport() = 0;
387  virtual bool hasIconSupport() = 0;
388  virtual bool hasAnimationSupport() = 0;
389  virtual bool hasFullUtf8Support() = 0;
390  virtual bool richTextSupportsTable() = 0;
391  virtual bool leftHandedMouse() = 0;
392  virtual bool hasWizardDialogSupport() { return false; }
393 
394 
395  /**
396  * Set the application title
397  **/
398  virtual void setApplicationTitle ( const std::string& title );
399 
400  /**
401  * Get the application title
402  *
403  * Default title is the running command (argv[0])
404  **/
405  virtual const std::string& applicationTitle() const;
406 
407  /**
408  * Set the application Icon
409  **/
410  virtual void setApplicationIcon ( const std::string& icon );
411 
412  /**
413  * Get the application Icon
414  *
415  * Default icon is an empty string
416  **/
417  virtual const std::string& applicationIcon() const;
418 
419 private:
420 
422 
423 };
424 
425 #define YApplication_h
426 
427 #endif // YApplication_h
virtual void setApplicationTitle(const std::string &title)
virtual bool openContextMenu(const YItemCollection &itemCollection)
std::string productName() const
Definition: YUI.h:48
virtual float layoutUnits(YUIDimension dim, int deviceUnits)
void clearDefaultFunctionKeys()
virtual std::string askForExistingFile(const std::string &startWith, const std::string &filter, const std::string &headline)=0
std::map< std::string, std::string > releaseNotes() const
virtual void setIconBasePath(const std::string &newIconBasePath)
Definition: YApplication.cc:98
virtual int deviceUnits(YUIDimension dim, float layoutUnits)
int defaultFunctionKey(const std::string &label) const
virtual std::string iconBasePath() const
Definition: YApplication.cc:91
virtual std::string askForSaveFileName(const std::string &startWith, const std::string &filter, const std::string &headline)=0
virtual ~YApplication()
Definition: YApplication.cc:72
virtual std::string askForExistingDirectory(const std::string &startDir, const std::string &headline)=0
virtual int runInTerminal(const std::string &command)
YWidget * findWidget(YWidgetID *id, bool doThrow=true) const
Definition: YApplication.cc:79
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)
Definition: YApplication.h:342
virtual void initConsoleKeyboard()
Definition: YApplication.h:334
virtual const std::string & applicationTitle() const
virtual void busyCursor()
Definition: YApplication.h:299
virtual void normalCursor()
Definition: YApplication.h:305
void setDefaultFunctionKey(const std::string &label, int fkey)
std::string language(bool stripEncoding=false) const
virtual std::string glyph(const std::string &glyphSymbolName)
virtual void setApplicationIcon(const std::string &icon)
virtual void beep()
Definition: YApplication.h:317
virtual void makeScreenShot(const std::string &fileName)
Definition: YApplication.h:311
virtual void setProductName(const std::string &productName)
virtual void setReverseLayout(bool reverse)
virtual void setLanguage(const std::string &language, const std::string &encoding=std::string())
bool reverseLayout() const
void setReleaseNotes(const std::map< std::string, std::string > &relNotes)
virtual void redrawScreen()
Definition: YApplication.h:328
virtual const std::string & applicationIcon() const