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