libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YApplication.h
00001 /*
00002   Copyright (C) 2000-2012 Novell, Inc
00003   This library is free software; you can redistribute it and/or modify
00004   it under the terms of the GNU Lesser General Public License as
00005   published by the Free Software Foundation; either version 2.1 of the
00006   License, or (at your option) version 3.0 of the License. This library
00007   is distributed in the hope that it will be useful, but WITHOUT ANY
00008   WARRANTY; without even the implied warranty of MERCHANTABILITY or 
00009   FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
00010   License for more details. You should have received a copy of the GNU
00011   Lesser General Public License along with this library; if not, write
00012   to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
00013   Floor, Boston, MA 02110-1301 USA
00014 */
00015 
00016 
00017 /*-/
00018 
00019   File:         YApplication.h
00020 
00021   Author:       Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 #ifndef YApplication_h
00026 
00027 #include <string>
00028 #include "YUI.h"
00029 #include "ImplPtr.h"
00030 #include "YMenuItem.h"
00031 #include  "YIconLoader.h"
00032 
00033 
00034 
00035 class YWidget;
00036 class YWidgetID;
00037 class YApplicationPrivate;
00038 
00039 
00040 /**
00041  * Class for application-wide values and functions.
00042  * This is a singleton. Access and create it via the static functions in YUI.
00043  **/
00044 class YApplication
00045 {
00046 protected:
00047 
00048     friend class YUI;
00049     /**
00050      * Constructor.
00051      *
00052      * Use YUI::app() to get the singleton for this class.
00053      **/
00054     YApplication();
00055 
00056     /**
00057      * Destructor.
00058      **/
00059     virtual ~YApplication();
00060 
00061 public:
00062 
00063     /**
00064      * Find a widget in the topmost dialog by its ID.
00065      *
00066      * If there is no widget with that ID (or no dialog at all), this function
00067      * throws a YUIWidgetNotFoundException if 'doThrow' is 'true'. It returns 0
00068      * if 'doThrow' is 'false'.
00069      **/
00070     YWidget * findWidget( YWidgetID * id, bool doThrow = true ) const;
00071 
00072     /**
00073      * Get the base path for icons used by the UI. Selection widgets like
00074      * YSelectionBox, YComboBox, etc. or YWizard prepend this to icon
00075      * specifications that don't use an absolute path.
00076      **/
00077     virtual std::string iconBasePath() const;
00078 
00079     /**
00080      * Set the icon base path.
00081      **/
00082     virtual void setIconBasePath( const std::string & newIconBasePath );
00083 
00084     YIconLoader *iconLoader();
00085 
00086     /**
00087      * Return the default function key number for a widget with the specified
00088      * label or 0 if there is none. Any keyboard shortcuts that may be
00089      * contained in 'label' are stripped away before any comparison.
00090      *
00091      * The basic idea behind this concept is to have an easy default mapping
00092      * from buttons etc. with the same semantics to function keys:
00093      *
00094      * "OK"     -> F10
00095      * "Accept" -> F10
00096      * "Yes"    -> F10
00097      * "Next"   -> F10
00098      *
00099      * "Cancel" -> F9
00100      * "No"     -> F9
00101      * ...
00102      *
00103      * This function returns 10 for F10, F for F9 etc.;
00104      * 0 means "no function key".
00105      **/
00106     int defaultFunctionKey( const std::string & label ) const;
00107 
00108     /**
00109      * Add a mapping from the specified label to the specified F-key number.
00110      * This is the counterpart to defaultFunctionKey().
00111      *
00112      * This only affects widgets that are created after this call.
00113      **/
00114     void setDefaultFunctionKey( const std::string & label, int fkey );
00115 
00116     /**
00117      * Clear all previous label-to-function-key mappings.
00118      **/
00119     void clearDefaultFunctionKeys();
00120 
00121     /**
00122      * Set language and encoding for the locale environment ($LANG).
00123      *
00124      * This affects UI-internal translations (e.g. for predefined dialogs like
00125      * file selection), encoding and fonts.
00126      *
00127      * 'language' is the ISO short code ("de_DE", "en_US", ...).
00128      *
00129      * 'encoding' an (optional) encoding ("utf8", ...) that will be appended if
00130      * present.
00131      *
00132      * Derived classes can overwrite this method, but they should call this
00133      * base class method at the beginning of the new implementation.
00134      **/
00135     virtual void setLanguage( const std::string & language,
00136                               const std::string & encoding = std::string() );
00137 
00138     /**
00139      * Return the current language from the locale environment ($LANG).
00140      * If 'stripEncoding' is true, any encoding (".utf8" etc.) is removed.
00141      **/
00142     std::string language( bool stripEncoding = false ) const;
00143 
00144     /**
00145      * Return a string for a named glyph:
00146      *
00147      *    YUIGlyph_ArrowLeft
00148      *    YUIGlyph_ArrowRight
00149      *    YUIGlyph_ArrowUp
00150      *    YUIGlyph_ArrowDown
00151      *    YUIGlyph_CheckMark
00152      *    YUIGlyph_BulletArrowRight
00153      *    YUIGlyph_BulletCircle
00154      *    YUIGlyph_BulletSquare
00155      *
00156      * Using this is discouraged in new applications.
00157      * This method is available for backward compatibility.
00158      *
00159      * This default implementation returns simple textual representations for
00160      * each glyph simbol (e.g., "->" for YUIGlyphArrorRight).
00161      *
00162      * Derived classes are free to overwrite this. It does not make sense to
00163      * call this base class method in a new implementation.
00164      **/
00165     virtual std::string glyph( const std::string & glyphSymbolName );
00166 
00167     /**
00168      * Open a directory selection box and prompt the user for an existing
00169      * directory.
00170      *
00171      * 'startDir' is the initial directory that is displayed.
00172      *
00173      * 'headline' is an explanatory text for the directory selection box.
00174      * Graphical UIs may omit that if no window manager is running.
00175      *
00176      * Returns the selected directory name
00177      * or an empty string if the user canceled the operation.
00178      *
00179      * Derived classes are required to implement this.
00180      **/
00181     virtual std::string askForExistingDirectory( const std::string & startDir,
00182                                             const std::string & headline ) = 0;
00183 
00184     /**
00185      * Open a file selection box and prompt the user for an existing file.
00186      *
00187      * 'startWith' is the initial directory or file.
00188      *
00189      * 'filter' is one or more blank-separated file patterns, e.g.
00190      * "*.png *.jpg"
00191      *
00192      * 'headline' is an explanatory text for the file selection box.
00193      * Graphical UIs may omit that if no window manager is running.
00194      *
00195      * Returns the selected file name
00196      * or an empty string if the user canceled the operation.
00197      *
00198      * Derived classes are required to implement this.
00199      **/
00200     virtual std::string askForExistingFile( const std::string & startWith,
00201                                        const std::string & filter,
00202                                        const std::string & headline ) = 0;
00203 
00204     /**
00205      * Open a file selection box and prompt the user for a file to save data
00206      * to.  Automatically asks for confirmation if the user selects an existing
00207      * file.
00208      *
00209      * 'startWith' is the initial directory or file.
00210      *
00211      * 'filter' is one or more blank-separated file patterns, e.g.
00212      * "*.png *.jpg"
00213      *
00214      * 'headline' is an explanatory text for the file selection box.
00215      * Graphical UIs may omit that if no window manager is running.
00216      *
00217      * Returns the selected file name
00218      * or an empty string if the user canceled the operation.
00219      *
00220      * Derived classes are required to implement this.
00221      **/
00222     virtual std::string askForSaveFileName( const std::string & startWith,
00223                                        const std::string & filter,
00224                                        const std::string & headline ) = 0;
00225 
00226     /**
00227      * Open a context menu for a widget
00228      *
00229      * 'itemCollection' describes the menu structure
00230      *
00231      * Returns true on success (otherwise false).
00232      *
00233      * Derived classes are free to overwrite this.
00234      **/
00235     virtual bool openContextMenu( const YItemCollection & itemCollection );
00236 
00237 
00238     /**
00239      * Set the current product name ("openSUSE", "SLES", ...).
00240      * This name will be expanded in help texts when the &product; entity is
00241      * used.
00242      *
00243      * Derived classes can overwrite this method, but they should call this
00244      * base class method in the new implementation.
00245      **/
00246     virtual void setProductName( const std::string & productName );
00247 
00248     /**
00249      * Set the current product name ("openSUSE", "SLES", ...).
00250      **/
00251     std::string productName() const;
00252 
00253     /**
00254      * Convert logical layout spacing units into device dependent units.
00255      * A default size dialog is assumed to be 80x25 layout spacing units.
00256      *
00257      * Derived classes may want to reimplement this method.
00258      **/
00259     virtual int deviceUnits( YUIDimension dim, float layoutUnits );
00260 
00261     /**
00262      * Convert device dependent units into logical layout spacing units.
00263      * A default size dialog is assumed to be 80x25 layout spacing units.
00264      *
00265      * Derived classes may want to reimplement this method.
00266      **/
00267     virtual float layoutUnits( YUIDimension dim, int deviceUnits );
00268 
00269     /**
00270      * Set reverse layout for Arabic / Hebrew support.
00271      *
00272      * Derived classes can overwrite this method, but they should call this
00273      * base class method in the new implementation.
00274      **/
00275     virtual void setReverseLayout( bool reverse );
00276 
00277     /**
00278      * Returns 'true' if widget geometry should be reversed for languages that
00279      * have right-to-left writing direction (Arabic, Hebrew).
00280      **/
00281     bool reverseLayout() const;
00282 
00283     /**
00284      * Change the (mouse) cursor to indicate busy status.
00285      * This default implementation does nothing.
00286      **/
00287     virtual void busyCursor() {}
00288 
00289     /**
00290      * Change the (mouse) cursor back from busy status to normal.
00291      * This default implementation does nothing.
00292      **/
00293     virtual void normalCursor() {}
00294 
00295     /**
00296      * Make a screen shot and save it to the specified file.
00297      * This default implementation does nothing.
00298      **/
00299     virtual void makeScreenShot( const std::string & fileName ) {}
00300 
00301     /**
00302      * Beep.
00303      * This default implementation does nothing.
00304      **/
00305     virtual void beep() {}
00306 
00307 
00308     //
00309     // NCurses (text mode) specific
00310     //
00311 
00312     /**
00313      * Redraw the screen.
00314      * This default implementation does nothing.
00315      **/
00316     virtual void redrawScreen() {}
00317 
00318     /**
00319      * Initialize the (text) console keyboard.
00320      * This default implementation does nothing.
00321      **/
00322     virtual void initConsoleKeyboard() {}
00323 
00324     /**
00325      * Set the (text) console font according to the current encoding etc.
00326      * See the setfont(8) command and the console HowTo for details.
00327      *
00328      * This default implementation does nothing.
00329      **/
00330     virtual void setConsoleFont( const std::string & console_magic,
00331                                  const std::string & font,
00332                                  const std::string & screen_map,
00333                                  const std::string & unicode_map,
00334                                  const std::string & language )
00335         {}
00336 
00337     /**
00338      * Run a shell command (typically an interactive program using NCurses)
00339      * in a terminal (window).
00340      *
00341      * This is useful for text UIs (e.g., NCurses) that need special
00342      * preparation prior to running an NCurses-based application and special
00343      * clean-up afterwards.
00344      *
00345      * This default implementation logs an error and returns -1.
00346      **/
00347     virtual int runInTerminal( const std::string & command );
00348 
00349 
00350     //
00351     // Display information.
00352     //
00353     // Width and height are returned in the the UI's native dimension:
00354     // Pixels for graphical UIs, character cells for text UIs.
00355     // -1 means "value cannot be obtained" for int functions.
00356     //
00357     // Derived classes are required to implement these functions.
00358     //
00359 
00360     virtual int  displayWidth()                 = 0;
00361     virtual int  displayHeight()                = 0;
00362     virtual int  displayDepth()                 = 0;
00363     virtual long displayColors()                = 0;
00364 
00365     // Size of main dialogs
00366     virtual int  defaultWidth()                 = 0;
00367     virtual int  defaultHeight()                = 0;
00368 
00369     //
00370     // UI capabilities
00371     //
00372 
00373     virtual bool isTextMode()                   = 0;
00374     virtual bool hasImageSupport()              = 0;
00375     virtual bool hasIconSupport()               = 0;
00376     virtual bool hasAnimationSupport()          = 0;
00377     virtual bool hasFullUtf8Support()           = 0;
00378     virtual bool richTextSupportsTable()        = 0;
00379     virtual bool leftHandedMouse()              = 0;
00380     virtual bool hasWizardDialogSupport() { return false; }
00381 
00382 
00383     /**
00384      * Set the application title
00385      **/
00386     virtual void setApplicationTitle ( const std::string& title );
00387     
00388     /**
00389      * Get the application title
00390      * 
00391      * Default title is the running command (argv[0])
00392      **/
00393     virtual const std::string& applicationTitle() const;
00394     
00395     /**
00396      * Set the application Icon
00397      **/    
00398     virtual void setApplicationIcon ( const std::string& icon );
00399     
00400     /**
00401      * Get the application Icon
00402      * 
00403      * Default icon is an empty string
00404      **/
00405      virtual const std::string& applicationIcon() const;
00406 
00407 private:
00408 
00409     ImplPtr<YApplicationPrivate> priv;
00410 
00411 };
00412 
00413 #define YApplication_h
00414 
00415 #endif // YApplication_h
 All Classes Functions Variables Enumerations Friends