[Libreoffice-commits] core.git: include/vcl
Chris Sherlock
chris.sherlock79 at gmail.com
Thu Jan 23 01:18:49 PST 2014
include/vcl/svapp.hxx | 163 +++++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 142 insertions(+), 21 deletions(-)
New commits:
commit a9f0b3bd33f93c4066ae9b38241c5cf67f6f4a46
Author: Chris Sherlock <chris.sherlock79 at gmail.com>
Date: Wed Jan 22 18:18:15 2014 +1100
Document more of VCL's Application class
* Documented the Application class's settings functions. When
reading through the code, I have noticed that GetSettings
intializes the application settings (!) and that SetSettings
relies on GetSettings to initialize the settings (!), so I
have listed a todo entry.
Furthermore, I've also noticed that SetSystemSettings and
MergeSystemSettings may be confused with the purpose of
SetSettings so I've added a todo entry that recommends that
we return an AllSettings object and make the parameters const.
* Minor whitespace changes
* Update @see for a number of public functions
* Group functions into Doxygen modules
Change-Id: I48f8d21a5d6436a2ae545e5156b877d57a8bc585
diff --git a/include/vcl/svapp.hxx b/include/vcl/svapp.hxx
index f0fe3ca..05d982a 100644
--- a/include/vcl/svapp.hxx
+++ b/include/vcl/svapp.hxx
@@ -268,7 +268,10 @@ public:
*/
virtual void UserEvent( sal_uLong nEvent, void* pEventData );
- // Functions that notify when changes occur in the application
+ /** @defgroup changes 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
@@ -287,7 +290,12 @@ public:
*/
virtual void DataChanged( const DataChangedEvent& rDCEvt );
- // Initialization functions
+ /** @} */ // end of changes
+
+ /** @defgroup Initialization
+ Initialization functions
+ @{
+ */
/** Initialize the application itself.
@@ -313,7 +321,12 @@ public:
*/
virtual void DeInit();
- // Command line processing:
+ /** @} */ // end of Initialization
+
+
+ /** @defgroup CommandLine Command line processing
+ @{
+ */
/** Gets the number of command line parameters passed to the application
@@ -341,7 +354,12 @@ public:
*/
static OUString GetAppFileName();
- // Error handling
+ /** @} */ // end of CommandLine
+
+ /** @defgroup ErrorHandling Error handling
+ @{
+ */
+
/** Handles an error code.
@remark This is not actually an exception. It merely takes an
@@ -369,13 +387,18 @@ public:
*/
static void Abort( const OUString& rErrorText );
- // Event loop functions:
+ /** @} */ // end of CommandLine
+
+ /** @defgroup EventLoop 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
+ EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+ RemovePostYieldListener
*/
static void Execute();
@@ -383,7 +406,8 @@ public:
@see Execute, Reschedule, Yield, EndYield, GetSolarMutex,
GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
- EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+ RemovePostYieldListener
*/
static void Quit();
@@ -395,8 +419,8 @@ public:
@see Execute, Quit, Yield, EndYield, GetSolarMutex,
GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
- EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
-
+ EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+ RemovePostYieldListener
*/
static void Reschedule( bool bAllEvents = false );
@@ -404,7 +428,8 @@ public:
@see Execute, Quit, Reschedule, EndYield, GetSolarMutex,
GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
- EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+ RemovePostYieldListener
*/
static void Yield();
@@ -412,7 +437,8 @@ public:
@see Execute, Quit, Reschedule, Yield, GetSolarMutex,
GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
- EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+ RemovePostYieldListener
*/
static void EndYield();
@@ -425,7 +451,8 @@ public:
@see Execute, Quit, Reschedule, Yield, EndYield,
GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
- EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+ RemovePostYieldListener
*/
static comphelper::SolarMutex& GetSolarMutex();
@@ -435,7 +462,8 @@ public:
@see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
ReleaseSolarMutex, AcquireSolarMutex,
- EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+ RemovePostYieldListener
*/
static oslThreadIdentifier GetMainThreadIdentifier();
@@ -448,9 +476,9 @@ public:
@see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
GetMainThreadIdentifier, AcquireSolarMutex,
- EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+ RemovePostYieldListener
*/
-
static sal_uLong ReleaseSolarMutex();
/** @Brief Acquire Solar Mutex(es) for this thread.
@@ -460,7 +488,8 @@ public:
@see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
GetMainThreadIdentifier, ReleaseSolarMutex,
- EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+ EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+ RemovePostYieldListener
*/
static void AcquireSolarMutex( sal_uLong nCount );
@@ -473,7 +502,7 @@ public:
@see DisableNoYieldMode, Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
- AddPostYieldListener, RemovePostYieldListener
+ DisableNoYield, AddPostYieldListener, RemovePostYieldListener
*/
static void EnableNoYieldMode();
@@ -486,8 +515,9 @@ public:
@see EnableNoYieldMode, Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
- AddPostYieldListener, RemovePostYieldListener
+ EnableNoYield, AddPostYieldListener, RemovePostYieldListener
*/
+
static void DisableNoYieldMode();
/** Add a listener for yield events
@@ -496,18 +526,17 @@ public:
@see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
- RemovePostYieldListener
+ EnableNoYieldMode, DisableNoYieldMode, 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
+ AddPostYieldListener, EnableNoYieldMode, DisableNoYieldMode
*/
static void RemovePostYieldListener( const Link& i_rListener );
@@ -562,6 +591,8 @@ public:
*/
static sal_uLong GetLastInputInterval();
+ /** @} */ // end of EventLoop
+
/* Determines if the UI is captured.
The UI is considered captured if a system dialog is open (e.g. printer setup),
@@ -572,11 +603,101 @@ public:
*/
static sal_Bool IsUICaptured();
+ /** defgroup Settings Application settings
+ @{
+ */
+
+ /** Overrides system settings with user settings.
+
+ The system settings that can be overridden are:
+ - window dragging options (on or off, including live scrolling!)
+ - style settings (e.g. cehckbox color, border color, 3D colors,
+ button rollover colors, etc.)
+ - mouse settings
+ - menu options, including the mouse follows the menu and whether menu
+ icons are used
+
+ @remark One wonders why this is a virtual function when all the other
+ settings options are static functions. What is it about overridding
+ an AllSettings object that requires it to have it's own Application
+ instance, when LibreOffice only keeps one Application instance around
+ at any time?
+
+ Another thing about this function is that it is a remarkably awkward
+ name that doesn't \em really describe what it does.
+
+ @todo Recommend that rSettings be made immutable and
+ we return a new AllSettings because as it stands it would be easy to
+ believe that this function changes system settings, which it does not
+ as this is the job of @SetSettings.
+
+ @param rSettings Reference to the settings object to change.
+
+ @see MergeSystemSettings, SetSettings, GetSettings
+ */
virtual void SystemSettingsChanging( AllSettings& rSettings );
+
+ /** Set the settings object to the platform/desktop environment system
+ settings.
+
+ @todo Incredibly, this gets the default window, then it uses whatever
+ the system settings of this window are. This seems entirely unnecessary.
+ Furthermore, to do this trick it then calls on @ImplUpdateGlobalSettings
+ (a function of the @Window class, which in turn calls on a platform
+ specific SalFrame UpdateSettings to update the settings object to the
+ environment's defaults.
+
+ This would be better refactored to a function that gets the environment's
+ defaults without having to get a Window instance.
+
+ @todo Recommend that rSettings be made immutable and
+ we return a new AllSettings because as it stands it would be easy to
+ believe that this function changes system settings, which it does not
+ as this is the job of @SetSettings.
+
+ @param rSettings Reference to the settings object to change.
+
+ @see SystemSettingsChanging, SetSettings, GetSettings
+ */
static void MergeSystemSettings( AllSettings& rSettings );
+ /** Sets the application's settings and notifies all windows of the
+ change.
+
+ @todo If the application hasn't initialized its settings yet, then
+ currently it calls on GetSettings to initialize the settings. Recommend
+ moving the initialization to a private function and call on this
+ instead.
+
+ @param rSettings const reference to settings object used to
+ change the application's settings.
+
+ @see SystemSettingsChanging, MergeSystemSettings, GetSettings
+ */
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).
+
+ @remark This is a const function. However, it can update the
+ application's settings object in pSVData. Be warned!
+
+ @todo We need to call on @GetSettings to initialize the application's
+ settings! This makes absolutely no sense. See @SetSettings, which does
+ exactly this and doesn't care about the return value. Recommend
+ moving this initialization code to a private function and call on
+ this seperately.
+
+ @returns AllSettings instance that contains the current settings of the
+ application.
+
+ @see SystemSettingsChanging, MergeSystemSettings, SetSettings
+ */
static const AllSettings& GetSettings();
+
+ /** @} */ // end of Settings
+
static void NotifyAllWindows( DataChangedEvent& rDCEvt );
static void AddEventListener( const Link& rEventListener );
More information about the Libreoffice-commits
mailing list