revised n*h headers

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56267 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/notebook.h

@@ -42,10 +42,9 @@
     @library{wxcore}
     @category{miscwnd}
 
-    @see wxBookCtrl, wxBookCtrlEvent, wxImageList,
+    @see wxBookCtrl, wxBookCtrlEvent, wxImageList, @ref page_samples_notebook
-        @ref page_samples_notebook "Notebook Sample"
 */
-class wxNotebook : public wxBookCtrl overview
+class wxNotebook : public wxBookCtrl
 {
 public:
 
@@ -70,7 +69,7 @@ public:
         @param style
             The window style. See wxNotebook.
         @param name
-            The name of the control (used only under Motif).
+            The name of the control.
     */
     wxNotebook(wxWindow* parent, wxWindowID id,
                const wxPoint& pos = wxDefaultPosition,
@@ -113,8 +112,7 @@ public:
     void AdvanceSelection(bool forward = true);
 
     /**
-        Sets the image list for the page control and takes ownership of
+        Sets the image list for the page control and takes ownership of the list.
-        the list.
 
         @see wxImageList, SetImageList()
     */
@@ -122,16 +120,16 @@ public:
 
     /**
         Changes the selection for the given page, returning the previous selection.
-        The call to this function does not generate the page changing events.
+
-        This is the only difference with SetSelection(). See
+        The call to this function does NOT generate the page changing events.
-        @ref overview_eventhandling_prog "User Generated Events"
+        This is the only difference with SetSelection().
-        for more infomation.
+        See @ref overview_eventhandling_prog for more infomation.
     */
     virtual int ChangeSelection(size_t page);
 
     /**
-        Creates a notebook control. See wxNotebook() for a description
+        Creates a notebook control.
-        of the parameters.
+        See wxNotebook() for a description of the parameters.
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxPoint& pos = wxDefaultPosition,
@@ -189,6 +187,7 @@ public:
 
     /**
         Returns the currently selected page, or -1 if none was selected.
+
         Note that this method may return either the previously or newly
         selected page when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler
         depending on the platform and so wxBookCtrlEvent::GetSelection should be
@@ -198,10 +197,10 @@ public:
 
     /**
         If running under Windows and themes are enabled for the application, this
-        function
+        function returns a suitable colour for painting the background of a notebook
-        returns a suitable colour for painting the background of a notebook page, and
+        page, and can be passed to SetBackgroundColour().
-        can be passed
+
-        to @c SetBackgroundColour. Otherwise, an uninitialised colour will be returned.
+        Otherwise, an uninitialised colour will be returned.
     */
     virtual wxColour GetThemeBackgroundColour() const;
 
@@ -226,8 +225,9 @@ public:
             <TD>The point was over a currently selected page, not over any tab.
             Note that this flag is present only if wxNOT_FOUND is returned.</TD></TR>
             </TABLE>
-@return Returns the zero-based tab index or wxNOT_FOUND if there is no
+
-                 tab at the specified position.
+        @return Returns the zero-based tab index or @c wxNOT_FOUND if there is no
+                tab at the specified position.
     */
     virtual int HitTest(const wxPoint& pt, long* flags = NULL) const;
 
@@ -268,8 +268,8 @@ public:
     bool RemovePage(size_t page);
 
     /**
-        Sets the image list for the page control. It does not take
+        Sets the image list for the page control.
-        ownership of the image list, you must delete it yourself.
+        It does not take ownership of the image list, you must delete it yourself.
 
         @see wxImageList, AssignImageList()
     */
@@ -277,6 +277,7 @@ public:
 
     /**
         Sets the amount of space around each page's icon and label, in pixels.
+
         @note The vertical padding cannot be changed in wxGTK.
     */
     virtual void SetPadding(const wxSize& padding);
@@ -289,6 +290,7 @@ public:
 
     /**
         Sets the width and height of the pages.
+
         @note This method is currently not implemented for wxGTK.
     */
     virtual void SetPageSize(const wxSize& size);
@@ -301,8 +303,10 @@ public:
     /**
         Sets the selection for the given page, returning the previous selection.
         The call to this function generates the page changing events.
-        This function is deprecated and should not be used in new code. Please use the
+
-        ChangeSelection() function instead.
+        @deprecated
+        This function is deprecated and should not be used in new code.
+        Please use the ChangeSelection() function instead.
 
         @see GetSelection()
     */

interface/wx/notifmsg.h

@@ -9,79 +9,86 @@
 /**
     @class wxNotificationMessage
 
-    This class allows to show the user a message non intrusively. Currently it is
+    This class allows to show the user a message non intrusively.
-    implemented natively only for the Maemo platform and uses (non-modal) dialogs
+
-    for the display of the notifications under the other platforms but it will be
+    Currently it is implemented natively only for the Maemo platform and uses
-    extended to use the platform-specific notifications in the other ports in the
+    (non-modal) dialogs for the display of the notifications under the other
-    future.
+    platforms but it will be extended to use the platform-specific notifications
+    in the other ports in the future.
 
     Notice that this class is not a window and so doesn't derive from wxWindow.
 
-    @library{wxbase}
+    @library{wxadv}
-    @category{FIXME}
+    @category{misc}
 */
 class wxNotificationMessage : public wxEvtHandler
 {
 public:
-    //@{
     /**
-        , @b wxWindow*@e parent = @NULL, @b int@e flags = @c wxICON_INFORMATION)
+        Default constructor, use SetParent(), SetTitle() and SetMessage() to
-        Create a notification object with the given attributes.
+        initialize the object before showing it.
-        See SetTitle(),
-        SetMessage(),
-        SetParent() and
-        SetFlags() for the description of the
-        corresponding parameters.
     */
     wxNotificationMessage();
-    wxNotificationMessage(const wxString& title);
+
-    //@}
+    /**
+        Create a notification object with the given attributes.
+
+        See SetTitle(), SetMessage(), SetParent() and SetFlags() for the
+        description of the corresponding parameters.
+    */
+    wxNotificationMessage(const wxString& title, const wxString& message = wxEmptyString,
+                          wxWindow* parent = NULL, int flags = wxICON_INFORMATION);
 
     /**
         Hides the notification.
-        Returns @true if it was hidden or @false if it couldn't be done (e.g. on
+
-        some
+        Returns @true if it was hidden or @false if it couldn't be done
-        systems automatically hidden notifications can't be hidden manually)
+        (e.g. on some systems automatically hidden notifications can't be
+        hidden manually).
     */
     virtual bool Close();
 
     /**
         This parameter can be currently used to specify the icon to show in the
-        notification. Valid values are @c wxICON_INFORMATION,
+        notification.
-        @c wxICON_WARNING and @c wxICON_ERROR (notice that
+
-        @c wxICON_QUESTION is not allowed here).
+        Valid values are @c wxICON_INFORMATION, @c wxICON_WARNING and
+        @c wxICON_ERROR (notice that @c wxICON_QUESTION is not allowed here).
         Some implementations of this class may not support the icons.
     */
     void SetFlags(int flags);
 
     /**
-        Set the main text of the notification. This should be a more detailed
+        Set the main text of the notification.
-        description than the title but still limited to reasonable length (not more
+
-        than 256 characters).
+        This should be a more detailed description than the title but still limited
+        to reasonable length (not more than 256 characters).
     */
     void SetMessage(const wxString& message);
 
     /**
         Set the parent for this notification: the notification will be associated with
         the top level parent of this window or, if this method is not called, with the
-        main application window by default
+        main application window by default.
     */
     void SetParent(wxWindow* parent);
 
     /**
         Set the title, it must be a concise string (not more than 64 characters), use
-        SetMessage() to give the user more
+        SetMessage() to give the user more details.
-        details.
     */
     void SetTitle(const wxString& title);
 
     /**
-        Show the notification to the user and hides it after timeout seconds
+        Show the notification to the user and hides it after @a timeout seconds
-        pass. Special values @c Timeout_Auto and @c Timeout_Never can be
+        are elapsed.
-        used here, notice that you shouldn't rely on @a timeout being exactly
+
-        respected because the current platform may only support default timeout value
+        Special values @c Timeout_Auto and @c Timeout_Never can be used here,
+        notice that you shouldn't rely on @a timeout being exactly respected
+        because the current platform may only support default timeout value
         and also because the user may be able to close the notification.
-        Returns @false if an error occurred.
+
+        @return @false if an error occurred.
     */
     virtual bool Show(int timeout = Timeout_Auto);
 };