include/vcl/svapp.hxx | 468 ++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 418 insertions(+), 50 deletions(-)
New commits:
commit 89a7b8a13285dcf614b162c1b8bd94b6785d3f87
Author: Chris Sherlock <chris.sherloc...@gmail.com>
Date: Sat Jan 18 23:10:58 2014 +1100
Document VCL Application class
Documented the VCL Application class in Doxygen format. Also
reindented some of the code, and moved ValidateSystemFont down
the list of class functions (better code organization).
Change-Id: Id421647a9a25e11be87b0f6c46d1ac0f4846f6a4
Reviewed-on: https://gerrit.libreoffice.org/7515
Reviewed-by: Michael Meeks <michael.me...@collabora.com>
Tested-by: Michael Meeks <michael.me...@collabora.com>
diff --git a/include/vcl/svapp.hxx b/include/vcl/svapp.hxx
index 1620efa..a3333ee 100644
--- a/include/vcl/svapp.hxx
+++ b/include/vcl/svapp.hxx
@@ -140,78 +140,432 @@ private:
std::vector<OUString> aData;
};
+/**
+ @brief Abstract base class used for the LibreOffice Desktop class.
+
+ Abstract base class used for the LibreOffice Desktop class.
+
+ The Application class is an abstract class with one pure virtual
+ function: @Main. The main class that is subclassed is the Desktop
+ class, however there are a \em lot of static functions that are
+ vital for applications. It is really meant to be subclassed to
+ provide a global singleton, and heavily relies on a single data
+ structure ImplSVData
+ The reason Application exists is because the VCL used to be a
+ standalone framework, long since abandoned by anything other than
+ our application.
+
+ @see Desktop, ImplSVData
+ */
class VCL_DLLPUBLIC Application
{
public:
enum DialogCancelMode {
- DIALOG_CANCEL_OFF, ///< do not automatically cancel dialogs
- DIALOG_CANCEL_SILENT, ///< silently cancel any dialogs
- DIALOG_CANCEL_FATAL
- ///< cancel any dialogs by std::abort
+ DIALOG_CANCEL_OFF, ///< do not automatically cancel dialogs
+ DIALOG_CANCEL_SILENT, ///< silently cancel any dialogs
+ DIALOG_CANCEL_FATAL ///< cancel any dialogs by std::abort
};
+ /**
+ Default constructor for Application class.
+
+ Initializes the LibreOffice global instance data structure if needed,
+ and then sets itself to be the Application class. Also initializes any
+ platform specific data structures.
+
+ @attention The initialization of the application itself is done in
+ @Init
+
+ @see InitSalData is implemented by platform specific code.
+ ImplInitSVData initializes the global instance data
+ */
Application();
+
+ /** Virtual destructor for Application class.
+
+ Deinitializes the LibreOffice global instance data structure, then
+ deinitializes any platform specific data structures.
+
+ @see ImplDeInitSVData deinitializes the global instance data,
+ DeInitSalData is implemented by platform specific code
+ */
virtual ~Application();
+ /** @brief Pure virtual entrypoint to the application.
+
+ Main() is the pure virtual entrypoint to your application. You
+ inherit your class from Application and subclass this function to
+ implement an application.
+
+ The Main() function does not pass in command line parameters,
+ you must use the functions @GetCommandLineParamCount() and
+ @GetCommandLineParam to get these values as these are platform
+ independent ways of getting the command line (use @GetAppFileName
+ to get the invoked executable filename).
+
+ Once in this function, you create windows, etc. then call on
+ @Execute to start the application's main event loop.
+
+ An example code snippet follows (it won't compile, this just gives the
+ general flavour of the framework and is adapted from an old HelloWorld
+ example program that Star Division used to provide as part of their
+ library).
+
+ \code{.cpp}
+ class TheApplication : public Application
+ {
+ public:
+ virtual void Main();
+ };
+
+ class TheWindow : public WorkWindow
+ {
+ public:
+ TheWindow(Window *parent, WinBits windowStyle) :
+ WorkWindow(parent, windowStyle) {}
+
+ virtual void Paint(const Rectangle &);
+ };
+
+ void TheWindow::Paint(const Rectangle&)
+ {
+ DrawText(Point(100,100), String("Hello World!"));
+ }
+
+ void TheApplication::Main()
+ {
+ TheWindow aWindow(NULL, WB_APP | WB_STDWORK);
+ aWindow.Show();
+ Execute();
+ }
+
+ TheApplication anApplication;
+ \endcode
+
+ Some examples in the source tree can be found here:
+
+ \example vcl\workben\svdem.cxx
+ This is an example of how to use the Application and WorkWindow.
Unfortunately, it
+ no longer compiles.
+
+ \example vcl\fpicker\test\svdem.cxx
+ */
+
virtual int Main() = 0;
- virtual sal_Bool QueryExit();
+ /** Exit from the application
+
+ @returns true if exited successfully, false if not able to fully exit
+ */
+ virtual sal_Bool QueryExit();
+ /** Send user event.
+
+ @param nEvent The numeric ID of the event
+ @param pEventData Pointer to a data associated with the event. Use
+ a reinterpret_cast<void*> to pass in the parameter.
+ */
virtual void UserEvent( sal_uLong nEvent, void* pEventData
);
+ // Functions that notify when changes occur in the application
+
+ /** Notify that the application is no longer the "focused" (or current)
+ application - needed for Windowing systems where an end user can switch
+ from one application to another.
+
+ @see DataChanged
+ */
virtual void FocusChanged();
+
+ /** Notify the application that data has changed via an event.
+
+ @param rDCEvt Reference to a @DataChangedEvent object - this will not
+ be changed
+
+ @see FocusChanged
+ */
virtual void DataChanged( const DataChangedEvent& rDCEvt );
+ // Initialization functions
+
+ /** Initialize the application itself.
+
+ @attention Note that the global data structures and platform specific
+ initialization is done in the constructor.
+
+ @see InitFinished, DeInit
+ */
virtual void Init();
+
+ /** Finish initialization of the application.
+
+ @see Init, DeInit
+ */
virtual void InitFinished();
+
+ /** Deinitialized the application itself.
+
+ @attention Note that the global data structures and platform specific
+ deinitialization is done in the destructor.
+
+ @see Init, InitFinished
+ */
virtual void DeInit();
+ // Command line processing:
+
+ /** Gets the number of command line parameters passed to the application
+
+ @return sal_uInt16 - the number of parameters
+
+ @see GetCommandLineParam, GetAppFileName
+ */
static sal_uInt16 GetCommandLineParamCount();
+
+ /** Gets a particular command line parameter
+
+ @param nParam The index of the parameter to return.
+
+ @return The command line parameter as an OUString
+
+ @see GetCommandLineParamCount, GetAppFileName
+ */
static OUString GetCommandLineParam( sal_uInt16 nParam );
+
+ /** Get the name of the file used to start the application
+
+ @return The filename as an OUString
+
+ @see GetCommandLineParamCount, GetCommandLineParam
+ */
static OUString GetAppFileName();
+ // Error handling
+ /** Handles an error code.
+
+ @remark This is not actually an exception. It merely takes an
+ error code, then in most cases aborts. The list of exception
+ identifiers can be found at include/vcl/apptypes.hxx - each
+ one starts with EXC_*
+
+ @param nError The error code identifier
+
+ @returns sal_uInt16 value - if it is 0, then the error wasn't handled.
+
+ @see Abort
+ */
virtual sal_uInt16 Exception( sal_uInt16 nError );
+
+ /** Ends the program prematurely with an error message.
+
+ If the --norestore command line argument is given (assuming
+ this process is run by developers who are interested in cores,
+ vs. end users who are not) then it does a coredump.
+
+ @param rErrorText The error message to report.
+
+ @see Exception
+ */
static void Abort( const OUString& rErrorText );
+ // Event loop functions:
+
+ /** Run the main event processing loop until it is quit by @Quit.
+
+ @see Quit, Reschedule, Yield, EndYield, GetSolarMutex,
+ GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
+ EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ */
static void Execute();
+
+ /** Quit the program
+
+ @see Execute, Reschedule, Yield, EndYield, GetSolarMutex,
+ GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
+ EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ */
static void Quit();
+
+ /** Attempt to reschedule in processing of current event(s)
+
+ @param bAllEvents If set to true, then try to process all the
+ events. If set to false, then only process the current
+ event. Defaults to false.
+
+ @see Execute, Quit, Yield, EndYield, GetSolarMutex,
+ GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
+ EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+
+ */
static void Reschedule( bool bAllEvents = false );
+
+ /** Allow processing of the next event.
+
+ @see Execute, Quit, Reschedule, EndYield, GetSolarMutex,
+ GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
+ EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ */
static void Yield();
+
+ /**
+
+ @see Execute, Quit, Reschedule, Yield, GetSolarMutex,
+ GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
+ EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ */
static void EndYield();
+
+ /** @Brief Get the Solar Mutex for this thread.
+
+ Get the Solar Mutex that prevents other threads from accessing VCL
+ concurrently.
+
+ @returns SolarMutex reference
+
+ @see Execute, Quit, Reschedule, Yield, EndYield,
+ GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
+ EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ */
static comphelper::SolarMutex& GetSolarMutex();
+
+ /** Get the main thread ID.
+
+ @returns oslThreadIdentifier that contains the thread ID
+
+ @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
+ ReleaseSolarMutex, AcquireSolarMutex,
+ EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ */
static oslThreadIdentifier GetMainThreadIdentifier();
- static sal_uLong ReleaseSolarMutex();
+
+ /** @Brief Release Solar Mutex(es) for this thread
+
+ Release the Solar Mutex(es) that prevents other threads from accessing
+ VCL concurrently.
+
+ @returns The number of mutexes that were acquired by this thread.
+
+ @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
+ GetMainThreadIdentifier, AcquireSolarMutex,
+ EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ */
+
+ static sal_uLong ReleaseSolarMutex();
+
+ /** @Brief Acquire Solar Mutex(es) for this thread.
+
+ Acquire the Solar Mutex(es) that prevents other threads from accessing
+ VCL concurrently.
+
+ @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
+ GetMainThreadIdentifier, ReleaseSolarMutex,
+ EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ */
static void AcquireSolarMutex( sal_uLong nCount );
+
+ /** @Brief Enables "no yield" mode
+
+ "No yield" mode prevents @Yield from waiting for events.
+
+ @remarks This was originally implemented in OOo bug 98792 to improve
+ Impress slideshows. For some reason, to \em disable no yield mode, you
+ call on EnableNoYieldMode
+
+ @param i_bNoYield If set to false, then "no yield" mode is turned
off.
+ If set to true, then "no yield" mode is turned on.
+
+ @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
+ GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
+ AddPostYieldListener, RemovePostYieldListener
+ */
static void EnableNoYieldMode( bool i_bNoYield );
+
+ /** Add a listener for yield events
+
+ @param i_rListener Listener to add
+
+ @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
+ GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
+ RemovePostYieldListener
+ */
static void AddPostYieldListener( const Link& i_rListener
);
+
+
+ /** Remove listener for yield events
+
+ @param i_rListener Listener to remove
+
+ @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
+ GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
+ AddPostYieldListener
+ */
static void RemovePostYieldListener( const Link&
i_rListener );
- static sal_Bool IsInMain();
- static sal_Bool IsInExecute();
- static sal_Bool IsInModalMode();
- static sal_uInt16 GetDispatchLevel();
+ /** Queries whether the application is in "main", i.e. not yet in
+ the event loop
+
+ @returns true if in main, false if not in main
+
+ @see IsInExecute, IsInModalMode
+ */
+ static sal_Bool IsInMain();
+
+ /** Queries whether the application is in the event loop
+
+ @returns true if in the event loop, false if not
+
+ @see IsInMain, IsInModalMode
+ */
+ static sal_Bool IsInExecute();
+
+ /** Queries whether application has a modal dialog active.
+
+ @returns true if a modal dialog is active, false if not
+
+ @see IsInMain, IsInExecute
+ */
+ static sal_Bool IsInModalMode();
+
+ /** Return how many events are being dispatched.
+
+ @returns the number of events currently being dispatched
+ */
+ static sal_uInt16 GetDispatchLevel();
+
+ /** Determine if there are any pending input events.
+
+ @param nType input identifier, defined in include/vcl/apptypes.hxx
+ The default is VCL_INPUT_ANY.
+
+ @returns true if there are pending events, false if not.
+
+ @see GetLastInputInterval
+ */
static bool AnyInput( sal_uInt16 nType = VCL_INPUT_ANY );
- static sal_uLong GetLastInputInterval();
- static sal_Bool IsUICaptured();
- virtual void SystemSettingsChanging( AllSettings& rSettings,
- Window* pFrame );
- static void MergeSystemSettings( AllSettings& rSettings );
- /** validate that the currently selected system UI font is suitable
- to display the application's UI.
+ /** The interval from the last time that input was received.
- A localized test string will be checked if it can be displayed
- in the currently selected system UI font. If no glyphs are
- missing it can be assumed that the font is proper for display
- of the application's UI.
+ @returns system ticks - last input time
- @returns
- <TRUE/> if the system font is suitable for our UI
- <FALSE/> if the test string could not be displayed with the system font
+ @see AnyInput
+ */
+ static sal_uLong GetLastInputInterval();
+
+ /* Determines if the UI is captured.
+
+ The UI is considered captured if a system dialog is open (e.g. printer
setup),
+ a floating window, menu or toolbox dropdown is open, or a window has been
+ captured by the mouse.
+
+ @returns true if UI is captured, false if not
*/
- static bool ValidateSystemFont();
+ static sal_Bool IsUICaptured();
+
+ virtual void SystemSettingsChanging( AllSettings& rSettings,
+ Window* pFrame );
+ static void MergeSystemSettings( AllSettings& rSettings );
static void SetSettings( const AllSettings& rSettings );
static const AllSettings& GetSettings();
@@ -223,21 +577,21 @@ public:
static void RemoveKeyListener( const Link& rKeyListener );
static void ImplCallEventListeners( sal_uLong nEvent,
Window* pWin, void* pData );
static void ImplCallEventListeners( VclSimpleEvent* pEvent
);
- static sal_Bool HandleKey( sal_uLong nEvent, Window *pWin,
KeyEvent* pKeyEvent );
+ static sal_Bool HandleKey( sal_uLong nEvent, Window *pWin,
KeyEvent* pKeyEvent );
- static sal_uLong PostKeyEvent( sal_uLong nEvent, Window
*pWin, KeyEvent* pKeyEvent );
- static sal_uLong PostMouseEvent( sal_uLong nEvent, Window
*pWin, MouseEvent* pMouseEvent );
+ static sal_uLong PostKeyEvent( sal_uLong nEvent, Window *pWin,
KeyEvent* pKeyEvent );
+ static sal_uLong PostMouseEvent( sal_uLong nEvent, Window
*pWin, MouseEvent* pMouseEvent );
#if !HAVE_FEATURE_DESKTOP
static sal_uLong PostZoomEvent( sal_uLong nEvent, Window *pWin,
ZoomEvent* pZoomEvent );
static sal_uLong PostScrollEvent( sal_uLong nEvent, Window
*pWin, ScrollEvent* pScrollEvent );
#endif
static void RemoveMouseAndKeyEvents( Window *pWin );
- static sal_uLong PostUserEvent( const Link& rLink, void*
pCaller = NULL );
- static sal_Bool PostUserEvent( sal_uLong& rEventId, const
Link& rLink, void* pCaller = NULL );
+ static sal_uLong PostUserEvent( const Link& rLink, void*
pCaller = NULL );
+ static sal_Bool PostUserEvent( sal_uLong& rEventId, const
Link& rLink, void* pCaller = NULL );
static void RemoveUserEvent( sal_uLong nUserEvent );
- static sal_Bool InsertIdleHdl( const Link& rLink,
sal_uInt16 nPriority );
+ static sal_Bool InsertIdleHdl( const Link& rLink, sal_uInt16
nPriority );
static void RemoveIdleHdl( const Link& rLink );
virtual void AppEvent( const ApplicationEvent& rAppEvent );
@@ -257,11 +611,25 @@ public:
static OUString GetAppName();
static bool LoadBrandBitmap (const char* pName, BitmapEx
&rBitmap);
+ /** validate that the currently selected system UI font is suitable
+ to display the application's UI.
+
+ A localized test string will be checked if it can be displayed
+ in the currently selected system UI font. If no glyphs are
+ missing it can be assumed that the font is proper for display
+ of the application's UI.
+
+ @returns
+ <TRUE/> if the system font is suitable for our UI
+ <FALSE/> if the test string could not be displayed with the system font
+ */
+
// default name of the application for message dialogs and printing
+ static bool ValidateSystemFont();
+
static void SetDisplayName( const OUString& rDisplayName );
static OUString GetDisplayName();
-
static unsigned int GetScreenCount();
static Rectangle GetScreenPosSizePixel( unsigned int nScreen );
@@ -271,7 +639,7 @@ public:
// (e.g. Xserver with Xinerama, Windows)
// false: different screens are separate and windows cannot be moved
// between them (e.g. Xserver with multiple screens)
- static bool IsUnifiedDisplay();
+ static bool IsUnifiedDisplay();
// if IsUnifiedDisplay() == true the return value will be
// nearest screen of the target rectangle
// in case of IsUnifiedDisplay() == false the return value
@@ -281,13 +649,13 @@ public:
// external VGA display for a desktop machine - it is where a presenter
// console should be rendered if there are other (non-built-in) screens
// present.
- static unsigned int GetDisplayBuiltInScreen();
+ static unsigned int GetDisplayBuiltInScreen();
// Practically, this means - Get the screen we should run a presentation
on.
- static unsigned int GetDisplayExternalScreen();
+ static unsigned int GetDisplayExternalScreen();
static const LocaleDataWrapper& GetAppLocaleDataWrapper();
- static sal_Bool InsertAccel( Accelerator* pAccel );
+ static sal_Bool InsertAccel( Accelerator* pAccel );
static void RemoveAccel( Accelerator* pAccel );
static long CallEventHooks( NotifyEvent& rEvt );
@@ -296,23 +664,23 @@ public:
static Help* GetHelp();
static void EnableAutoHelpId( sal_Bool bEnabled = sal_True
);
- static sal_Bool IsAutoHelpIdEnabled();
+ static sal_Bool IsAutoHelpIdEnabled();
static void EnableAutoMnemonic( sal_Bool bEnabled =
sal_True );
- static sal_Bool IsAutoMnemonicEnabled();
+ static sal_Bool IsAutoMnemonicEnabled();
- static sal_uLong GetReservedKeyCodeCount();
+ static sal_uLong GetReservedKeyCodeCount();
static const KeyCode* GetReservedKeyCode( sal_uLong i );
static void SetDefDialogParent( Window* pWindow );
static Window* GetDefDialogParent();
- static DialogCancelMode GetDialogCancelMode();
- static void SetDialogCancelMode( DialogCancelMode mode );
- static sal_Bool IsDialogCancelEnabled();
+ static DialogCancelMode GetDialogCancelMode();
+ static void SetDialogCancelMode( DialogCancelMode mode );
+ static sal_Bool IsDialogCancelEnabled();
static void SetSystemWindowMode( sal_uInt16 nMode );
- static sal_uInt16 GetSystemWindowMode();
+ static sal_uInt16 GetSystemWindowMode();
static void SetDialogScaleX( short nScale );
@@ -345,7 +713,7 @@ public:
Must only be called with the Solar mutex locked.
*/
- static bool CanToggleImeStatusWindow();
+ static bool CanToggleImeStatusWindow();
/** Toggle any IME status window on and off.
@@ -354,19 +722,19 @@ public:
Must only be called with the Solar mutex locked.
*/
- static void ShowImeStatusWindow(bool bShow);
+ static void ShowImeStatusWindow(bool bShow);
/** Return true if any IME status window should be turned on by default
(this decision can be locale dependent, for example).
Can be called without the Solar mutex locked.
*/
- static bool GetShowImeStatusWindowDefault();
+ static bool GetShowImeStatusWindowDefault();
/** Returns a string representing the desktop environment
the process is currently running in.
*/
- static const OUString& GetDesktopEnvironment();
+ static const OUString& GetDesktopEnvironment();
/** Add a file to the system shells recent document list if there is any.
This function may have no effect under Unix because there is no
@@ -380,11 +748,11 @@ public:
If an empty string will be provided "application/octet-stream"
will be used.
*/
- static void AddToRecentDocumentList(const OUString& rFileUrl, const
OUString& rMimeType, const OUString& rDocumentService);
+ static void AddToRecentDocumentList(const OUString&
rFileUrl, const OUString& rMimeType, const OUString& rDocumentService);
/** Do we have a native / system file selector available ?
*/
- static bool hasNativeFileSelection();
+ static bool hasNativeFileSelection();
/** Create a platform specific file picker, if one is available,
otherwise return an empty reference
@@ -400,7 +768,7 @@ public:
createFolderPicker( const com::sun::star::uno::Reference<
com::sun::star::uno::XComponentContext >&
rServiceManager );
- static bool IsEnableAccessInterface() {return true;}
+ static bool IsEnableAccessInterface() {return true;}
private:
_______________________________________________
Libreoffice-commits mailing list
libreoffice-comm...@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice-commits
