[Libreoffice-commits] core.git: include/vcl
Chris Sherlock
chris.sherlock79 at gmail.com
Tue Jan 28 02:26:18 PST 2014
include/vcl/svapp.hxx | 550 ++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 447 insertions(+), 103 deletions(-)
New commits:
commit a650d9e368b72c2490ff661a047cd6a11472158e
Author: Chris Sherlock <chris.sherlock79 at gmail.com>
Date: Mon Jan 27 16:33:19 2014 +1100
Document Application class
Documented more of the VCL Application class's public functions
via Doxygen markup.
Also, change from global groups to member groups.
Change-Id: I5e80e707874db99c60e899d078f41c7817e2b6c3
Reviewed-on: https://gerrit.libreoffice.org/7664
Reviewed-by: Michael Meeks <michael.meeks at collabora.com>
Tested-by: Michael Meeks <michael.meeks at collabora.com>
diff --git a/include/vcl/svapp.hxx b/include/vcl/svapp.hxx
index 058f6ad..efc4454 100644
--- a/include/vcl/svapp.hxx
+++ b/include/vcl/svapp.hxx
@@ -141,15 +141,12 @@ private:
};
/**
- @brief Abstract base class used for the LibreOffice Desktop class.
-
- Abstract base class used for the LibreOffice Desktop class.
+ @brief Abstract base class used mainly 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
+ function: Main(), 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
@@ -167,15 +164,19 @@ public:
DIALOG_CANCEL_FATAL ///< cancel any dialogs by std::abort
};
- /**
- Default constructor for Application class.
+ /** @name Initialization
+ The following functions perform initialization and deinitialization
+ of the application.
+ */
+ ///@{
+
+ /** 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
+ @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
@@ -184,14 +185,40 @@ public:
/** Virtual destructor for Application class.
- Deinitializes the LibreOffice global instance data structure, then
- deinitializes any platform specific data structures.
+ 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();
+ /** 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();
+
+ ///@}
+
/** @brief Pure virtual entrypoint to the application.
Main() is the pure virtual entrypoint to your application. You
@@ -199,13 +226,13 @@ public:
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
+ 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.
+ 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
@@ -245,13 +272,13 @@ public:
Some examples in the source tree can be found here:
- \example vcl\workben\svdem.cxx
+ 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
+ vcl/fpicker/test/svdem.cxx
*/
-
virtual int Main() = 0;
/** Exit from the application
@@ -268,10 +295,11 @@ public:
*/
virtual void UserEvent( sal_uLong nEvent, void* pEventData );
- /** @defgroup changes Change notification functions
- Functions that notify when changes occur in the application
- @{
+ /** @name Change Notification Functions
+
+ 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
@@ -283,49 +311,30 @@ public:
/** Notify the application that data has changed via an event.
- @param rDCEvt Reference to a @DataChangedEvent object - this will not
- be changed
+ @param rDCEvt Const reference to a DataChangedEvent object
- @see FocusChanged
+ @see FocusChanged, NotifyAllWindows
*/
virtual void DataChanged( const DataChangedEvent& rDCEvt );
- /** @} */ // end of changes
-
- /** @defgroup Initialization Initialization functions
- @{
- */
-
- /** Initialize the application itself.
+ /** Notify all windows that the application has changed data.
- @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.
+ @param rDCEvt Reference to a DataChangedEvent object
- @see Init, DeInit
+ @see DataChanged
*/
- virtual void InitFinished();
+ static void NotifyAllWindows( DataChangedEvent& rDCEvt );
- /** Deinitialized the application itself.
+ ///@}
- @attention Note that the global data structures and platform specific
- deinitialization is done in the destructor.
+ /** @name Command Line Processing
- @see Init, InitFinished
+ Command line processing is done via the following functions. They
+ give the number of parameters, the parameters themselves and a way
+ to get the name of the invoking application.
*/
- virtual void DeInit();
-
- /** @} */ // end of Initialization
-
- /** @defgroup CommandLine Command line processing
- @{
- */
+ ///@{
/** Gets the number of command line parameters passed to the application
@@ -353,9 +362,13 @@ public:
*/
static OUString GetAppFileName();
- /** @} */ // end of CommandLine
+ ///@}
+
+ /** @name Error Handling
+
+ \em Very rudimentary error handling is done by these
+ functions.
- /** @defgroup ErrorHandling Error handling
@{
*/
@@ -376,7 +389,7 @@ public:
/** Ends the program prematurely with an error message.
- If the --norestore command line argument is given (assuming
+ If the \code --norestore \endcode 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.
@@ -386,13 +399,18 @@ public:
*/
static void Abort( const OUString& rErrorText );
- /** @} */ // end of CommandLine
+ ///@}
- /** @defgroup EventLoop Event loop functions
- @{
+ /** @name Event Loop
+
+ Event loop functions
+
+ Functions that handle the LibreOffice main event loop are here,
+ including a global lock called the Solar Mutex.
*/
+ ///@{
- /** Run the main event processing loop until it is quit by @Quit.
+ /** Run the main event processing loop until it is quit by Quit().
@see Quit, Reschedule, Yield, EndYield, GetSolarMutex,
GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
@@ -441,7 +459,7 @@ public:
*/
static void EndYield();
- /** @Brief Get the Solar Mutex for this thread.
+ /** @brief Get the Solar Mutex for this thread.
Get the Solar Mutex that prevents other threads from accessing VCL
concurrently.
@@ -466,7 +484,7 @@ public:
*/
static oslThreadIdentifier GetMainThreadIdentifier();
- /** @Brief Release Solar Mutex(es) for this thread
+ /** @brief Release Solar Mutex(es) for this thread
Release the Solar Mutex(es) that prevents other threads from accessing
VCL concurrently.
@@ -480,7 +498,7 @@ public:
*/
static sal_uLong ReleaseSolarMutex();
- /** @Brief Acquire Solar Mutex(es) for this thread.
+ /** @brief Acquire Solar Mutex(es) for this thread.
Acquire the Solar Mutex(es) that prevents other threads from accessing
VCL concurrently.
@@ -492,9 +510,9 @@ public:
*/
static void AcquireSolarMutex( sal_uLong nCount );
- /** @Brief Enables "no yield" mode
+ /** @brief Enables "no yield" mode
- "No yield" mode prevents @Yield from waiting for events.
+ "No yield" mode prevents Yield() from waiting for events.
@remarks This was originally implemented in OOo bug 98792 to improve
Impress slideshows.
@@ -505,9 +523,9 @@ public:
*/
static void EnableNoYieldMode();
- /** @Brief Disables "no yield" mode
+ /** @brief Disables "no yield" mode
- "No yield" mode prevents @Yield from waiting for events.
+ "No yield" mode prevents Yield() from waiting for events.
@remarks This was originally implemented in OOo bug 98792 to improve
Impress slideshows.
@@ -590,7 +608,7 @@ public:
*/
static sal_uLong GetLastInputInterval();
- /** @} */ // end of EventLoop
+ ///@}
/* Determines if the UI is captured.
@@ -602,9 +620,13 @@ public:
*/
static sal_Bool IsUICaptured();
- /** defgroup Settings Application settings
- @{
+ /** @name Settings
+
+ The following functions set system settings (e.g. tab color, etc.). There are functions
+ that set settings objects, and functions that set and get the actual system settings for
+ the application.
*/
+ ///@{
/** Sets user settings in settings object to override system settings
@@ -641,7 +663,6 @@ public:
*/
static void SetSettings( const AllSettings& rSettings );
-
/** Gets the application's settings. If the application hasn't initialized
it's settings, then it does so (lazy initialization).
@@ -652,94 +673,417 @@ public:
*/
static const AllSettings& GetSettings();
- /** @} */ // end of Settings
+ /** Validate that the currently selected system UI font is suitable
+ to display the application's UI.
- static void NotifyAllWindows( DataChangedEvent& rDCEvt );
+ 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 and false if the test
+ string could not be displayed with the system font.
+ */
+ static bool ValidateSystemFont();
+
+ /** Get the application's locale data wrapper.
+
+ @returns reference to a LocaleDataWrapper object
+ */
+ static const LocaleDataWrapper& GetAppLocaleDataWrapper();
+
+ ///@}
+ /** @name Event Listeners
+
+ A set of event listeners and callers. Note that in this code there is
+ platform specific functions - namely for zoom and scroll events.
+ */
+ ///@{
+
+ /** Add a VCL event listener to the application. If no event listener exists,
+ then initialize the application's event listener with a new one, then add
+ the event listener.
+
+ @param rEventListener Const reference to the event listener to add.
+
+ @see RemoveEventListener, AddKeyListener, RemoveKeyListener
+ */
static void AddEventListener( const Link& rEventListener );
+
+ /** Remove a VCL event listener from the application.
+
+ @param rEventListener Const refernece to the event listener to be removed
+
+ @see AddEventListener, AddKeyListener, RemoveKeyListener
+ */
static void RemoveEventListener( const Link& rEventListener );
+
+ /** Add a keypress listener to the application. If keypress listener exists,
+ then initialize the application's keypress event listener with a new one, then
+ add the keypress listener.
+
+ @param rKeyListener Const reference to the keypress event listener to add
+
+ @see AddEventListener, RemoveEventListener, RemoveKeyListener
+ */
static void AddKeyListener( const Link& rKeyListener );
+
+ /** Remove a keypress listener from the application.
+
+ @param rKeyListener Const reference to the keypress event listener to be removed
+
+ @see AddEventListener, RemoveEventListener, AddKeyListener
+ */
static void RemoveKeyListener( const Link& rKeyListener );
+
+ /** Send event to all VCL application event listeners
+
+ @param nEvent Event ID
+ @param pWin Pointer to window to send event
+ @param pData Pointer to data to send with event
+
+ @see ImplCallEventListeners(VclSimpleEvent* pEvent)
+ */
static void ImplCallEventListeners( sal_uLong nEvent, Window* pWin, void* pData );
+
+ /** Send event to all VCL application event listeners
+
+ @param pEvent Pointer to VclSimpleEvent
+
+ @see ImplCallEventListeners(sal_uLong nEvent, Windows* pWin, void* pData);
+ */
static void ImplCallEventListeners( VclSimpleEvent* pEvent );
+
+ /** Handle keypress event
+
+ @param nEvent Event ID for keypress
+ @param pWin Pointer to window that receives the event
+ @param pKeyEvent Received key event
+
+ @see PostKeyEvent
+ */
static sal_Bool HandleKey( sal_uLong nEvent, Window *pWin, KeyEvent* pKeyEvent );
+ /** Send keypress event
+
+ @param nEvent Event ID for keypress
+ @param pWin Pointer to window to which the event is sent
+ @param pKeyEvent Key event to send
+
+ @see HandleKey
+ */
static sal_uLong PostKeyEvent( sal_uLong nEvent, Window *pWin, KeyEvent* pKeyEvent );
+
+ /** Send mouse event
+
+ @param nEvent Event ID for mouse event
+ @param pWin Pointer to window to which the event is sent
+ @param pKeyEvent Mouse event to send
+ */
static sal_uLong PostMouseEvent( sal_uLong nEvent, Window *pWin, MouseEvent* pMouseEvent );
+
#if !HAVE_FEATURE_DESKTOP
+ /** Send zoom event
+
+ @param nEvent Event ID for zoom event
+ @param pWin Pointer to window to which the event is sent
+ @param pZoomEvent Zoom event to send
+ */
static sal_uLong PostZoomEvent( sal_uLong nEvent, Window *pWin, ZoomEvent* pZoomEvent );
+
+ /* Send scroll event
+
+ @param nEvent Event ID for scroll event
+ @param pWin Pointer to window to which the event is sent
+ @param pScrollEvent Scroll event to send
+ */
static sal_uLong PostScrollEvent( sal_uLong nEvent, Window *pWin, ScrollEvent* pScrollEvent );
#endif
+
+ /** Remove mouse and keypress events from a window... any also zoom and scroll events
+ if the platform supports it.
+
+ @param pWin Window to remove events from
+
+ @see HandleKey, PostKeyEvent, PostMouseEvent, PostZoomEvent, PostScrollEvent
+ */
static void RemoveMouseAndKeyEvents( Window *pWin );
+ /** Post a user event to the default window.
+
+ User events allow for the deferral of work to later in the main-loop - at idle.
+
+ @param rLink Link to event callback function
+ @param pCaller Pointer to data sent to the event by the caller. Optional.
+
+ @return the event ID used to post the event.
+ */
static sal_uLong PostUserEvent( const Link& rLink, void* pCaller = NULL );
+
+ /** Post a user event to the default window.
+
+ @param rEventID Reference to event ID to be posted
+ @param rLink Link to event callback function
+ @param pCaller Pointer to data sent to teh event by the caller. Optional.
+
+ @return true if there is a default window and the event could be posted to it successfully.
+ */
static sal_Bool PostUserEvent( sal_uLong& rEventId, const Link& rLink, void* pCaller = NULL );
+
+ /** Remove user event based on event ID
+
+ @param nUserEvent Numeric user event to remove
+ */
static void RemoveUserEvent( sal_uLong nUserEvent );
+ /** Insert an idle handler into the application.
+
+ If the idle event manager doesn't exist, then initialize it.
+
+ @param rLink const reference to the idle handler
+ @param nPrio The priority of the idle handler - idle handlers of a higher
+ priority will be processed before this handler.
+
+ @return true if the handler was inserted successfully, false if it couldn't be inserted.
+ */
static sal_Bool InsertIdleHdl( const Link& rLink, sal_uInt16 nPriority );
+
+ /** Remove an idle handler from the application.
+
+ @param rLink const reference to the idle handler to remove
+ */
static void RemoveIdleHdl( const Link& rLink );
+
+ /** @deprecated AppEvent is used only in the Desktop class now. However, it is
+ intended to notify the application that an event has occured. It was in oldsv.cxx,
+ but is still needed by a number of functions.
+
+ @param rAppEvent const reference to ApplicationEvent event
+ */
virtual void AppEvent( const ApplicationEvent& rAppEvent );
+ ///@}
+
+ /** @name Application Window Functions
+
+ Functions that deal with the application's windows
+ */
+ ///@{
+
+ /** Get the main application window.
+
+ @remark the main application window (or App window) has a style of WB_APP,
+ there can only be on WorkWindow with this style, if a dialog or floating
+ window cannot find a parent, then the parent becomes the app window.
+
+ It also becomes the "default window", is used for help, is a fallback if
+ the application has no name, and a number of other things.
+
+ returns Pointer to main application window.
+
+ @see GetFocusWindow, GetDefaultDevice
+ */
static WorkWindow* GetAppWindow();
+
+ /** Get the currently focussed window.
+
+ @returns Pointer to focused window.
+
+ @see GetAppWindow, GetDefaultDevice
+ */
static Window* GetFocusWindow();
+
+ /** Get the default "device" (in this case the default window).
+
+ @returns Pointer to an OutputDevice. However, it is a Window object -
+ Window class subclasses OutputDevice.
+
+ @see GetAppWindow, GetFocusWindow
+ */
static OutputDevice* GetDefaultDevice();
+ /** Get the first top-level window of the application.
+
+ @returns Pointer to top-level window (a Window object)
+
+ @see GetNextTopLevelWindow, GetTopWindowCount, GetTopWindow,
+ GetActiveTopWindow
+ */
static Window* GetFirstTopLevelWindow();
+
+ /** Get the next top level window.
+
+ @param pWindow Pointer to Window object you wish to get the next
+ window from.
+
+ @returns Pointer to next top window.
+ */
static Window* GetNextTopLevelWindow( Window* pWindow );
+ /** Return the number of top-level windows being used by the application
+
+ @returns the number of top-level windows
+
+ @see GetFirstTopLevelWindow, GetNextTopLevelWindow, GetTopWindow,
+ GetActiveTopWindow
+
+ */
static long GetTopWindowCount();
+
+ /** Get the nth top window.
+
+ @remark Top windows are actually implemented in a one-way linked list.
+ This iterates through top level windows n times.
+
+ @param nIndex The index of the top-level window
+
+ @returns The nth top-level window of the application
+
+ @see GetFirstTopLevelWindow, GetNextTopLevelWindow, GetTopWindowCount,
+ GetActiveTopWindow
+ */
static Window* GetTopWindow( long nIndex );
+
+ /** Get the "active" top window.
+
+ An "active" top window is one that has a child window that has the
+ application's focus.
+
+ @returns the active top window
+
+ @see GetFirstTopLevelWindow, GetNextTopLevelWindow, GetTopWindowCount,
+ GetTopWindow
+ */
static Window* GetActiveTopWindow();
+ ///@}
+
+ /** Set the application's name.
+
+ @param rUniqueName What to set the application name to
+
+ @see GetAppName
+ */
static void SetAppName( const OUString& rUniqueName );
+
+
+ /** @name Application Name, Branding
+ */
+ ///@{
+
+ /** Get the application's name.
+
+ @returns The application name.
+ */
static OUString GetAppName();
+
+ /** Load a localized branding PNG file as a bitmap.
+
+ @param pName Name of the bitmap to load.
+ @param rBitmap Reference to BitmapEx object to load PNG into
+
+ @returns true if the PNG could be loaded, otherwise returns false.
+ */
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.
+ /** @name Display and Screen
+ */
+ ///*{
- @returns
- <TRUE/> if the system font is suitable for our UI
- <FALSE/> if the test string could not be displayed with the system font
- */
- static bool ValidateSystemFont();
+ /** Set the default name of the application for message dialogs and printing.
- // default name of the application for message dialogs and printing
+ @param rDisplayName const reference to string to set the Display name to.
+
+ @see GetDisplayName
+ */
static void SetDisplayName( const OUString& rDisplayName );
+
+ /** Get the default name of the application for messag dialogs and printing.
+
+ @returns The display name of the application.
+ */
static OUString GetDisplayName();
+ /** Get the number of screens available for the display.
+
+ @returns The number of screens available.
+
+ @see GetScreenPosSizePixel
+ */
static unsigned int GetScreenCount();
+
+ /** Get a screen's rectangular area.
+
+ @param nScreen The number of the screen requested.
+
+ @returns The area of the screen in a Rectangle object.
+
+ @see GetScreenCount
+ */
static Rectangle GetScreenPosSizePixel( unsigned int nScreen );
- // IsUnifiedDisplay returns:
- // true: screens form up one large display area
- // windows can be moved between single screens
- // (e.g. Xserver with Xinerama, Windows)
- // false: different screens are separate and windows cannot be moved
- // between them (e.g. Xserver with multiple screens)
+ /** Determines if the screens that make up a display are seperate or
+ form one large display area.
+
+ @returns true when screens form up one large display area windows can be
+ moved between single screens (e.g. Xserver with Xinerama, Windows)
+ and false when different screens are separate and windows cannot be moved
+ between them (e.g. Xserver with multiple screens)
+
+ @see GetBestScreen, GetDisplayBuiltInScreen
+ */
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
- // will always be GetDisplayDefaultScreen()
- SAL_DLLPRIVATE static unsigned int GetBestScreen( const Rectangle& );
- // This returns the LCD screen number for a laptop, or the primary
- // 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.
+
+ /** Get the "best" screen.
+
+ @returns If IsUnifiedDisplay() == true the return value will be
+ nearest screen of the target rectangle.
+
+ In case of IsUnifiedDisplay() == false the return value
+ will always be GetDisplayDefaultScreen().
+
+ @see IsUnifiedDisplay, GetDisplayBuiltInScreen
+ */
+ SAL_DLLPRIVATE static unsigned int GetBestScreen( const Rectangle& );
+
+ /** Get the built-in screen.
+
+ @return
+ This returns the LCD screen number for a laptop, or the primary
+ 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.
+
+ @see IsUnifiedDisplay, GetBestScreen
+ */
static unsigned int GetDisplayBuiltInScreen();
- // Practically, this means - Get the screen we should run a presentation on.
+
+ /** Get the display's external screen.
+
+ Practically, this means - Get the screen we should run a presentation on.
+
+ @returns 0 or 1 currently, will fallback to the first available screen if
+ there are more than one external screens. May be changed in the future.
+ */
static unsigned int GetDisplayExternalScreen();
- static const LocaleDataWrapper& GetAppLocaleDataWrapper();
+ //@}
+
+ /** Insert accelerator
+ @param pAccel Pointer to an Accelerator object to insert
+
+ @returns true if successful, false if otherwise
+ */
static sal_Bool InsertAccel( Accelerator* pAccel );
+
+ /** Remove accelerator
+
+ @param pAccel Pointer to Accelerator object to remove
+ */
static void RemoveAccel( Accelerator* pAccel );
static long CallEventHooks( NotifyEvent& rEvt );
More information about the Libreoffice-commits
mailing list