Update duplicated / outdated NWS documentation

Removes the old, copied NWS documentation blocks from all native
implementations and update the parent SalGraphics documentation.

Change-Id: I0eff8ea0987c5c841e1b023340b1c3787c09e2ca

7 files changed, 111 insertions, 293 deletions

diff --git a/vcl/inc/salgdi.hxx b/vcl/inc/salgdi.hxx
index 9ca24332903c..90f75b1bf6c2 100644
--- a/vcl/inc/salgdi.hxx
+++ b/vcl/inc/salgdi.hxx
@@ -337,10 +337,22 @@ public:
 
     //  native widget rendering functions
 
-    // Query the platform layer for control support
-    virtual bool                IsNativeControlSupported( ControlType nType, ControlPart nPart );
+    /**
+     * Query the platform layer for native control support.
+     *
+     * @param [in] eType The widget type.
+     * @param [in] ePart The part of the widget.
+     * @return true if the platform supports native drawing of the widget type defined by part.
+     */
+    virtual bool                IsNativeControlSupported(
+                                    ControlType eType, ControlPart ePart );
+
 
-    // Query the native control to determine if it was acted upon
+    /**
+     * Query the native control to determine if it was acted upon
+     *
+     * @see hitTestNativeControl
+     */
     bool                        HitTestNativeScrollbar(
                                     ControlPart nPart,
                                     const Rectangle& rControlRegion,
@@ -348,7 +360,11 @@ public:
                                     bool& rIsInside,
                                     const OutputDevice *pOutDev );
 
-    // Request rendering of a particular control and/or part
+    /**
+     * Request rendering of a particular control and/or part
+     *
+     * @see drawNativeControl
+     */
     bool                        DrawNativeControl(
                                     ControlType nType,
                                     ControlPart nPart,
@@ -358,7 +374,11 @@ public:
                                     const OUString& aCaption,
                                     const OutputDevice *pOutDev );
 
-    // Query the native control's actual drawing region (including adornment)
+    /**
+     * Query the native control's actual drawing region (including adornment)
+     *
+     * @see getNativeControlRegion
+     */
     bool                        GetNativeControlRegion(
                                     ControlType nType,
                                     ControlPart nPart,
@@ -462,7 +482,6 @@ protected:
                                     const SalPoint* const* pPtAry,
                                     const PolyFlags* const* pFlgAry ) = 0;
 
-
     virtual bool                drawGradient(
                                     const tools::PolyPolygon& rPolyPoly,
                                     const Gradient& rGradient ) = 0;
@@ -508,24 +527,66 @@ protected:
                                     void* pPtr,
                                     sal_uLong nSize ) = 0;
 
-    // native widget rendering methods that require mirroring
+    /**
+     * Query if a position is inside the native widget part.
+     *
+     * Mainly used for scrollbars.
+     *
+     * @param [in] eType The widget type.
+     * @param [in] ePart The part of the widget.
+     * @param [in] rBoundingControlRegion The bounding Rectangle of
+                   the complete control in VCL frame coordinates.
+     * @param [in] aPos The position to check the hit.
+     * @param [out] rIsInside true, if \a aPos was inside the native widget.
+     * @return true, if the query was successful.
+     */
     virtual bool                hitTestNativeControl(
-                                    ControlType nType, ControlPart nPart,
-                                    const Rectangle& rControlRegion,
-                                    const Point& aPos,
-                                    bool& rIsInside );
-
+                                    ControlType eType, ControlPart ePart,
+                                    const Rectangle& rBoundingControlRegion,
+                                    const Point& aPos, bool& rIsInside );
+
+    /**
+     * Draw the requested control.
+     *
+     * @param [in] eType The widget type.
+     * @param [in] ePart The part of the widget.
+     * @param [in] rBoundingControlRegion The bounding rectangle of
+     *             the complete control in VCL frame coordinates.
+     * @param [in] eState The general state of the control (enabled, focused, etc.).
+     * @param [in] aValue Addition control specific information.
+     * @param [in] aCaption  A caption or title string (like button text etc.).
+     * @return true, if the control could be drawn.
+     */
     virtual bool                drawNativeControl(
-                                    ControlType nType, ControlPart nPart,
-                                    const Rectangle& rControlRegion,
-                                    ControlState nState,
+                                    ControlType eType, ControlPart ePart,
+                                    const Rectangle& rBoundingControlRegion,
+                                    ControlState eState,
                                     const ImplControlValue& aValue,
                                     const OUString& aCaption );
 
+    /**
+     * Get the native control regions for the control part.
+     *
+     * If the return value is true, \a rNativeBoundingRegion contains
+     * the true bounding region covered by the control including any
+     * adornment, while \a rNativeContentRegion contains the area
+     * within the control that can be safely drawn into without drawing over
+     * the borders of the control.
+     *
+     * @param [in] eType Type of the widget.
+     * @param [in] ePart Specification of the widget's part if it consists of more than one.
+     * @param [in] rBoundingControlRegion The bounding region of the control in VCL frame coordinates.
+     * @param [in] eState The general state of the control (enabled, focused, etc.).
+     * @param [in] aValue Addition control specific information.
+     * @param [in] aCaption A caption or title string (like button text etc.).
+     * @param [out] rNativeBoundingRegion The region covered by the control including any adornment.
+     * @param [out] rNativeContentRegion The region within the control that can be safely drawn into.
+     * @return true, if the regions are filled.
+     */
     virtual bool                getNativeControlRegion(
-                                    ControlType nType, ControlPart nPart,
-                                    const Rectangle& rControlRegion,
-                                    ControlState nState,
+                                    ControlType eType, ControlPart ePart,
+                                    const Rectangle& rBoundingControlRegion,
+                                    ControlState eState,
                                     const ImplControlValue& aValue,
                                     const OUString& aCaption,
                                     Rectangle &rNativeBoundingRegion,
@@ -569,19 +630,14 @@ protected:
                                     const SalBitmap* pAlphaBitmap) = 0;
 
     /** Render solid rectangle with given transparency
-
-      @param nX             Top left coordinate of rectangle
-
-      @param nY             Bottom right coordinate of rectangle
-
-      @param nWidth         Width of rectangle
-
-      @param nHeight        Height of rectangle
-
-      @param nTransparency  Transparency value (0-255) to use. 0 blits and opaque, 255 a
-                            fully transparent rectangle
-
-      @returns true if successfully drawn, false if not able to draw rectangle
+     *
+     * @param nX             Top left coordinate of rectangle
+     * @param nY             Bottom right coordinate of rectangle
+     * @param nWidth         Width of rectangle
+     * @param nHeight        Height of rectangle
+     * @param nTransparency  Transparency value (0-255) to use. 0 blits and opaque, 255 a
+     *                       fully transparent rectangle
+     * @returns true if successfully drawn, false if not able to draw rectangle
      */
     virtual bool                drawAlphaRect(
                                     long nX, long nY,
diff --git a/vcl/osx/salnativewidgets.cxx b/vcl/osx/salnativewidgets.cxx
index a9d263f3c476..36e8bf3db016 100644
--- a/vcl/osx/salnativewidgets.cxx
+++ b/vcl/osx/salnativewidgets.cxx
@@ -157,13 +157,6 @@ static bool AquaGetScrollRect( /* TODO: int nScreen, */  ControlPart nPart,
     return bRetVal;
 }
 
-/*
- * IsNativeControlSupported()
- * --------------------------
- * Returns true if the platform supports native
- * drawing of the control defined by nPart.
- *
- */
 bool AquaSalGraphics::IsNativeControlSupported( ControlType nType, ControlPart nPart )
 {
     bool bOk = false;
@@ -292,13 +285,6 @@ bool AquaSalGraphics::IsNativeControlSupported( ControlType nType, ControlPart n
     return bOk;
 }
 
-/*
- * HitTestNativeScrollbar()
- *
- *  If the return value is true, bIsInside contains information whether
- *  aPos was or was not inside the native widget specified by the
- *  nType/nPart combination.
- */
 bool AquaSalGraphics::hitTestNativeControl( ControlType nType, ControlPart nPart, const Rectangle& rControlRegion,
                         const Point& rPos, bool& rIsInside )
 {
@@ -346,15 +332,6 @@ UInt32 AquaSalGraphics::getTrackState( ControlState nState )
     return kThemeTrackActive;
 }
 
-/*
- * DrawNativeControl()
- *
- *  Draws the requested control described by nPart/nState.
- *
- *  rControlRegion: The bounding region of the complete control in VCL frame coordinates.
- *  aValue:     An optional value (tristate/numerical/string)
- *  aCaption:   A caption or title string (like button text etc)
- */
 bool AquaSalGraphics::drawNativeControl(ControlType nType,
                     ControlPart nPart,
                     const Rectangle& rControlRegion,
@@ -1068,19 +1045,6 @@ bool AquaSalGraphics::drawNativeControl(ControlType nType,
     return bOK;
 }
 
-/*
- * GetNativeControlRegion()
- *
- *  If the return value is true, rNativeBoundingRegion
- *  contains the true bounding region covered by the control
- *  including any adornment, while rNativeContentRegion contains the area
- *  within the control that can be safely drawn into without drawing over
- *  the borders of the control.
- *
- *  rControlRegion: The bounding region of the control in VCL frame coordinates.
- *  aValue:     An optional value (tristate/numerical/string)
- *  aCaption:       A caption or title string (like button text etc)
- */
 bool AquaSalGraphics::getNativeControlRegion( ControlType nType, ControlPart nPart, const Rectangle& rControlRegion, ControlState /*nState*/,
                                                const ImplControlValue& aValue, const OUString&,
                                                 Rectangle &rNativeBoundingRegion, Rectangle &rNativeContentRegion )
diff --git a/vcl/source/gdi/salnativewidgets-none.cxx b/vcl/source/gdi/salnativewidgets-none.cxx
index 99e8882c9a5f..afe6c2e6dab9 100644
--- a/vcl/source/gdi/salnativewidgets-none.cxx
+++ b/vcl/source/gdi/salnativewidgets-none.cxx
@@ -23,73 +23,28 @@
  *  Placeholder for no native widgets
  ***************************************************************/
 
-/*
- * IsNativeControlSupported()
- *
- *  Returns true if the platform supports native
- *  drawing of the control defined by nPart
- */
 bool SalGraphics::IsNativeControlSupported( ControlType, ControlPart )
 {
     return false;
 }
 
-/*
- * HitTestNativeScrollbar()
- *
- *  If the return value is true, bIsInside contains information whether
- *  aPos was or was not inside the native widget specified by the
- *  nType/nPart combination.
- */
-bool SalGraphics::hitTestNativeControl( ControlType,
-                              ControlPart,
-                              const Rectangle&,
-                              const Point&,
-                              bool& )
+bool SalGraphics::hitTestNativeControl( ControlType, ControlPart,
+                                        const Rectangle&, const Point&, bool& )
 {
     return false;
 }
 
-/*
- * DrawNativeControl()
- *
- *  Draws the requested control described by nPart/nState.
- *
- *  rControlRegion: The bounding region of the complete control in VCL frame coordinates.
- *  aValue:         An optional value (tristate/numerical/string)
- *  aCaption:   A caption or title string (like button text etc)
- */
-bool SalGraphics::drawNativeControl(    ControlType,
-                            ControlPart,
-                            const Rectangle&,
-                            ControlState,
-                            const ImplControlValue&,
-                            const OUString& )
+bool SalGraphics::drawNativeControl( ControlType, ControlPart,
+                                     const Rectangle&, ControlState,
+                                     const ImplControlValue&, const OUString& )
 {
     return false;
 }
 
-/*
- * GetNativeControlRegion()
- *
- *  If the return value is true, rNativeBoundingRegion
- *  contains the true bounding region covered by the control
- *  including any adornment, while rNativeContentRegion contains the area
- *  within the control that can be safely drawn into without drawing over
- *  the borders of the control.
- *
- *  rControlRegion: The bounding region of the control in VCL frame coordinates.
- *  aValue:     An optional value (tristate/numerical/string)
- *  aCaption:       A caption or title string (like button text etc)
- */
-bool SalGraphics::getNativeControlRegion(  ControlType,
-                                ControlPart,
-                                const Rectangle&,
-                                ControlState,
-                                const ImplControlValue&,
-                                const OUString&,
-                                Rectangle &,
-                                Rectangle & )
+bool SalGraphics::getNativeControlRegion( ControlType, ControlPart,
+                                          const Rectangle&, ControlState,
+                                          const ImplControlValue&,
+                                          const OUString&, Rectangle&, Rectangle& )
 {
     return false;
 }
diff --git a/vcl/unx/gtk/salnativewidgets-gtk.cxx b/vcl/unx/gtk/salnativewidgets-gtk.cxx
index a3eea1636475..8d0c96c42a1f 100644
--- a/vcl/unx/gtk/salnativewidgets-gtk.cxx
+++ b/vcl/unx/gtk/salnativewidgets-gtk.cxx
@@ -632,12 +632,6 @@ void GtkSalGraphics::copyBits( const SalTwoRect& rPosAry,
     X11SalGraphics::copyBits( rPosAry, pSrcGraphics );
 }
 
-/*
- * IsNativeControlSupported()
- *
- *  Returns true if the platform supports native
- *  drawing of the control defined by nPart
- */
 bool GtkSalGraphics::IsNativeControlSupported( ControlType nType, ControlPart nPart )
 {
     switch(nType)
@@ -741,15 +735,6 @@ bool GtkSalGraphics::IsNativeControlSupported( ControlType nType, ControlPart nP
     return false;
 }
 
-/*
- * HitTestNativeScrollbar()
- *
- *  bIsInside is set to true if aPos is contained within the
- *  given part of the control, whose bounding region is
- *  given by rControlRegion (in VCL frame coordinates).
- *
- *  returns whether bIsInside was really set.
- */
 bool GtkSalGraphics::hitTestNativeControl( ControlType        nType,
                                 ControlPart        nPart,
                                 const Rectangle&        rControlRegion,
@@ -852,15 +837,6 @@ bool GtkSalGraphics::hitTestNativeControl( ControlType        nType,
     }
 }
 
-/*
- * DrawNativeControl()
- *
- *  Draws the requested control described by nPart/nState.
- *
- *  rControlRegion:    The bounding region of the complete control in VCL frame coordinates.
- *  aValue:          An optional value (tristate/numerical/string)
- *  rCaption:      A caption or title string (like button text etc)
- */
 bool GtkSalGraphics::drawNativeControl(ControlType nType, ControlPart nPart,
         const Rectangle& rControlRegion, ControlState nState,
         const ImplControlValue& aValue, const OUString& rCaption)
@@ -1098,19 +1074,6 @@ bool GtkSalGraphics::DoDrawNativeControl(
     return false;
 }
 
-/*
- * GetNativeControlRegion()
- *
- *  If the return value is true, rNativeBoundingRegion
- *  contains the true bounding region covered by the control
- *  including any adornment, while rNativeContentRegion contains the area
- *  within the control that can be safely drawn into without drawing over
- *  the borders of the control.
- *
- *  rControlRegion:    The bounding region of the control in VCL frame coordinates.
- *  aValue:        An optional value (tristate/numerical/string)
- *  rCaption:        A caption or title string (like button text etc)
- */
 bool GtkSalGraphics::getNativeControlRegion(  ControlType nType,
                                 ControlPart nPart,
                                 const Rectangle& rControlRegion,
diff --git a/vcl/unx/kde/salnativewidgets-kde.cxx b/vcl/unx/kde/salnativewidgets-kde.cxx
index de55f1bb05d3..dc3cd619d649 100644
--- a/vcl/unx/kde/salnativewidgets-kde.cxx
+++ b/vcl/unx/kde/salnativewidgets-kde.cxx
@@ -1254,17 +1254,6 @@ class KDESalGraphics : public X11SalGraphics
                                          Rectangle &rNativeBoundingRegion, Rectangle &rNativeContentRegion ) override;
 };
 
-/** What widgets can be drawn the native way.
-
-    @param nType
-    Type of the widget.
-
-    @param nPart
-    Specification of the widget's part if it consists of more than one.
-
-    @return true if the platform supports native drawing of the widget nType
-    defined by nPart.
-*/
 bool KDESalGraphics::IsNativeControlSupported( ControlType nType, ControlPart nPart )
 {
     return
@@ -1292,12 +1281,6 @@ bool KDESalGraphics::IsNativeControlSupported( ControlType nType, ControlPart nP
         ;
 }
 
-/** Test whether the position is in the native widget.
-
-    If the return value is true, bIsInside contains information whether
-    aPos was or was not inside the native widget specified by the
-    nType/nPart combination.
-*/
 bool KDESalGraphics::hitTestNativeControl( ControlType nType, ControlPart nPart,
                                            const Rectangle& rControlRegion, const Point& rPos,
                                            bool& rIsInside )
@@ -1393,17 +1376,6 @@ bool KDESalGraphics::hitTestNativeControl( ControlType nType, ControlPart nPart,
     return false;
 }
 
-/** Draw the requested control described by nPart/nState.
-
-    @param rControlRegion
-    The bounding region of the complete control in VCL frame coordinates.
-
-    @param aValue
-    An optional value (tristate/numerical/string).
-
-    @param aCaption
-    A caption or title string (like button text etc.)
-*/
 bool KDESalGraphics::drawNativeControl( ControlType nType, ControlPart nPart,
                                         const Rectangle& rControlRegion, ControlState nState,
                                         const ImplControlValue& aValue,
@@ -1511,23 +1483,6 @@ bool KDESalGraphics::drawNativeControl( ControlType nType, ControlPart nPart,
     return bReturn;
 }
 
-/** Check if the bounding regions match.
-
-    If the return value is true, rNativeBoundingRegion
-    contains the true bounding region covered by the control
-    including any adornment, while rNativeContentRegion contains the area
-    within the control that can be safely drawn into without drawing over
-    the borders of the control.
-
-    @param rControlRegion
-    The bounding region of the control in VCL frame coordinates.
-
-    @param aValue
-    An optional value (tristate/numerical/string)
-
-    @param aCaption
-    A caption or title string (like button text etc.)
-*/
 bool KDESalGraphics::getNativeControlRegion( ControlType nType, ControlPart nPart,
                                              const Rectangle& rControlRegion, ControlState nState,
                                              const ImplControlValue&,
diff --git a/vcl/unx/kde4/KDESalGraphics.hxx b/vcl/unx/kde4/KDESalGraphics.hxx
index 38dd169eb9ce..501fbe3ba679 100644
--- a/vcl/unx/kde4/KDESalGraphics.hxx
+++ b/vcl/unx/kde4/KDESalGraphics.hxx
@@ -27,67 +27,27 @@
 
 #include <QtGui/QImage>
 
-/** handles graphics drawings requests and performs the needed drawing operations */
+/**
+ * Handles native graphics requests and performs the needed drawing operations.
+ */
 class KDESalGraphics : public X11SalGraphics
 {
-    std::unique_ptr<QImage> m_image;
-    QRect lastPopupRect;
-
-    public:
-        /**
-            What widgets can be drawn the native way.
-            @param type Type of the widget.
-            @param part Specification of the widget's part if it consists of more than one.
-            @return true if the platform supports native drawing of the widget type defined by part.
-        */
-        virtual bool IsNativeControlSupported( ControlType type, ControlPart part ) override;
-
-        /** Test whether the position is in the native widget.
-            If the return value is TRUE, bIsInside contains information whether
-            aPos was or was not inside the native widget specified by the
-            type/part combination.
-        */
-        virtual bool hitTestNativeControl( ControlType type, ControlPart part,
-                                        const Rectangle& rControlRegion, const Point& aPos,
-                                        bool& rIsInside ) override;
-        /** Draw the requested control described by part/nControlState.
-
-            @param rControlRegion
-            The bounding Rectangle of the complete control in VCL frame coordinates.
+public:
+    virtual bool IsNativeControlSupported( ControlType, ControlPart ) override;
 
-            @param aValue
-            An optional value (tristate/numerical/string).
+    virtual bool hitTestNativeControl( ControlType, ControlPart,
+                                       const Rectangle&, const Point&, bool& ) override;
 
-            @param aCaption
-            A caption or title string (like button text etc.)
-        */
-        virtual bool drawNativeControl( ControlType type, ControlPart part,
-                                        const Rectangle& rControlRegion, ControlState nControlState,
-                                        const ImplControlValue& aValue,
-                                        const OUString& aCaption ) override;
+    virtual bool drawNativeControl( ControlType, ControlPart, const Rectangle&,
+                                    ControlState, const ImplControlValue&, const OUString& ) override;
 
-        /** Check if the bounding regions match.
+    virtual bool getNativeControlRegion( ControlType, ControlPart, const Rectangle&,
+                                         ControlState, const ImplControlValue&,
+                                         const OUString&, Rectangle&, Rectangle& ) override;
 
-            If the return value is TRUE, rNativeBoundingRegion
-            contains the true bounding region covered by the control
-            including any adornment, while rNativeContentRegion contains the area
-            within the control that can be safely drawn into without drawing over
-            the borders of the control.
-
-            @param rControlRegion
-            The bounding region of the control in VCL frame coordinates.
-
-            @param aValue
-            An optional value (tristate/numerical/string)
-
-            @param aCaption
-            A caption or title string (like button text etc.)
-        */
-        virtual bool getNativeControlRegion( ControlType type, ControlPart part,
-                                            const Rectangle& rControlRegion, ControlState nControlState,
-                                            const ImplControlValue& aValue,
-                                            const OUString& aCaption,
-                                            Rectangle &rNativeBoundingRegion, Rectangle &rNativeContentRegion ) override;
+private:
+    std::unique_ptr<QImage> m_image;
+    QRect lastPopupRect;
 };
 
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/vcl/win/gdi/salnativewidgets-luna.cxx b/vcl/win/gdi/salnativewidgets-luna.cxx
index 23fa61ad9725..07586b4db0df 100644
--- a/vcl/win/gdi/salnativewidgets-luna.cxx
+++ b/vcl/win/gdi/salnativewidgets-luna.cxx
@@ -226,12 +226,6 @@ static HTHEME getThemeHandle( HWND hWnd, LPCWSTR name )
     return hTheme;
 }
 
-/*
- * IsNativeControlSupported()
- *
- *  Returns TRUE if the platform supports native
- *  drawing of the control defined by nPart
- */
 bool WinSalGraphics::IsNativeControlSupported( ControlType nType, ControlPart nPart )
 {
     HTHEME hTheme = nullptr;
@@ -339,13 +333,6 @@ bool WinSalGraphics::IsNativeControlSupported( ControlType nType, ControlPart nP
     return (hTheme != nullptr);
 }
 
-/*
- * HitTestNativeScrollbar()
- *
- *  If the return value is TRUE, bIsInside contains information whether
- *  aPos was or was not inside the native widget specified by the
- *  nType/nPart combination.
- */
 bool WinSalGraphics::hitTestNativeControl( ControlType,
                               ControlPart,
                               const Rectangle&,
@@ -1147,15 +1134,6 @@ bool ImplDrawNativeControl( HDC hDC, HTHEME hTheme, RECT rc,
     return false;
 }
 
-/*
- * DrawNativeControl()
- *
- *  Draws the requested control described by nPart/nState.
- *
- *  rControlRegion: The bounding region of the complete control in VCL frame coordinates.
- *  aValue:         An optional value (tristate/numerical/string)
- *  aCaption:   A caption or title string (like button text etc)
- */
 bool WinSalGraphics::drawNativeControl( ControlType nType,
                                         ControlPart nPart,
                                         const Rectangle& rControlRegion,
@@ -1316,19 +1294,6 @@ bool WinSalGraphics::drawNativeControl( ControlType nType,
     return bOk;
 }
 
-/*
- * GetNativeControlRegion()
- *
- *  If the return value is TRUE, rNativeBoundingRegion
- *  contains the true bounding region covered by the control
- *  including any adornment, while rNativeContentRegion contains the area
- *  within the control that can be safely drawn into without drawing over
- *  the borders of the control.
- *
- *  rControlRegion: The bounding region of the control in VCL frame coordinates.
- *  aValue:     An optional value (tristate/numerical/string)
- *  aCaption:       A caption or title string (like button text etc)
- */
 bool WinSalGraphics::getNativeControlRegion(  ControlType nType,
                                 ControlPart nPart,
                                 const Rectangle& rControlRegion,