remaining t*h interface revisions

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

interface/wx/tglbtn.h

@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        tglbtn.h
-// Purpose:     interface of wxBitmapToggleButton
+// Purpose:     interface of wxBitmapToggleButton, wxToggleButton
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -10,14 +10,12 @@
 /**
     @class wxToggleButton
 
-    wxToggleButton is a button that stays pressed when clicked by the user. In
+    wxToggleButton is a button that stays pressed when clicked by the user.
-    other words, it is similar to wxCheckBox in
+    In other words, it is similar to wxCheckBox in functionality but looks like a wxButton.
-    functionality but looks like a wxButton.
 
     Since wxWidgets version 2.9.0 this control emits an update UI event.
 
-    You can see wxToggleButton in action in the sixth page of the
+    You can see wxToggleButton in action in @ref page_samples_controls.
-    controls() sample.
 
     @beginEventTable{wxCommandEvent}
     @event{EVT_TOGGLEBUTTON(id, func)}
@@ -48,11 +46,11 @@ public:
         @param label
             Text to be displayed next to the toggle button.
         @param pos
-            Toggle button position. If wxDefaultPosition is specified then a
+            Toggle button position.
-        default position is chosen.
+            If wxDefaultPosition is specified then a default position is chosen.
         @param size
-            Toggle button size. If wxDefaultSize is specified then a
+            Toggle button size.
-        default size is chosen.
+            If wxDefaultSize is specified then a default size is chosen.
         @param style
             Window style. See wxToggleButton.
         @param validator
@@ -76,8 +74,8 @@ public:
     virtual ~wxToggleButton();
 
     /**
-        Creates the toggle button for two-step construction. See wxToggleButton()
+        Creates the toggle button for two-step construction.
-        for details.
+        See wxToggleButton() for details.
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& label,
@@ -95,8 +93,8 @@ public:
     virtual bool GetValue() const;
 
     /**
-        Sets the toggle button to the given state. This does not cause a
+        Sets the toggle button to the given state.
-        @c EVT_TOGGLEBUTTON event to be emitted.
+        This does not cause a @c EVT_TOGGLEBUTTON event to be emitted.
 
         @param state
             If @true, the button is pressed.
@@ -161,8 +159,8 @@ public:
     virtual bool GetValue() const;
 
     /**
-        Sets the toggle button to the given state. This does not cause a
+        Sets the toggle button to the given state.
-        @c EVT_TOGGLEBUTTON event to be emitted.
+        This does not cause a @c EVT_TOGGLEBUTTON event to be emitted.
 
         @param state
             If @true, the button is pressed.

interface/wx/timer.h

@@ -9,27 +9,26 @@
 /**
     @class wxTimer
 
-    The wxTimer class allows you to execute code at specified intervals. Its
+    The wxTimer class allows you to execute code at specified intervals.
-    precision is platform-dependent, but in general will not be better than 1ms nor
+    Its precision is platform-dependent, but in general will not be better than
-    worse than 1s.
+    @c 1ms nor worse than @c 1s.
 
     There are three different ways to use this class:
 
-     You may derive a new class from wxTimer and override the
+    - You may derive a new class from wxTimer and override the
-    wxTimer::Notify member to perform the required action.
+      wxTimer::Notify member to perform the required action.
-     Or you may redirect the notifications to any
+    - You may redirect the notifications to any wxEvtHandler derived object by
-    wxEvtHandler derived object by using the non-default
+      using the non-default constructor or wxTimer::SetOwner.
-    constructor or wxTimer::SetOwner. Then use the @c EVT_TIMER
+      Then use the @c EVT_TIMER macro to connect it to the event handler which
-    macro to connect it to the event handler which will receive
+      will receive wxTimerEvent notifications.
-    wxTimerEvent notifications.
+    - You may use a derived class and the @c EVT_TIMER macro to connect it to
-     Or you may use a derived class and the @c EVT_TIMER
+      an event handler defined in the derived class. If the default constructor
-    macro to connect it to an event handler defined in the derived class.
+      is used, the timer object will be its own owner object, since it is
-    If the default constructor is used, the timer object will be its
+      derived from wxEvtHandler.
-    own owner object, since it is derived from wxEvtHandler.
 
-    In any case, you must start the timer with wxTimer::Start
+    In any case, you must start the timer with wxTimer::Start() after constructing
-    after constructing it before it actually starts sending notifications. It can
+    it before it actually starts sending notifications.
-    be stopped later with wxTimer::Stop.
+    It can be stopped later with wxTimer::Stop().
 
     @note A timer can only be used from the main thread.
 
@@ -41,14 +40,18 @@
 class wxTimer : public wxEvtHandler
 {
 public:
-    //@{
     /**
-        Creates a timer and associates it with @e owner. Please see
+        Default constructor.
-        SetOwner() for the description of parameters.
+        If you use it to construct the object and don't call SetOwner() later,
+        you must override Notify() method to process the notifications.
     */
     wxTimer();
+
+    /**
+        Creates a timer and associates it with @a owner.
+        Please see SetOwner() for the description of parameters.
+    */
     wxTimer(wxEvtHandler* owner, int id = -1);
-    //@}
 
     /**
         Destructor. Stops the timer if it is running.
@@ -67,14 +70,15 @@ public:
 
     /**
         Returns the current @e owner of the timer.
+
         If non-@NULL this is the event handler which will receive the
-        @ref overview_wxtimerevent "timer events" when the timer is running.
+        timer events (see wxTimerEvent) when the timer is running.
     */
     wxEvtHandler GetOwner() const;
 
     /**
-        Returns @true if the timer is one shot, i.e. if it will stop after firing the
+        Returns @true if the timer is one shot, i.e. if it will stop after firing
-        first notification automatically.
+        the first notification automatically.
     */
     bool IsOneShot() const;
 
@@ -86,14 +90,16 @@ public:
     /**
         This member should be overridden by the user if the default constructor was
         used and SetOwner() wasn't called.
+
         Perform whatever action which is to be taken periodically here.
     */
     virtual void Notify();
 
     /**
-        Associates the timer with the given @a owner object. When the timer is
+        Associates the timer with the given @a owner object.
-        running, the owner will receive @ref overview_wxtimerevent "timer events" with
+
-        id equal to @a id specified here.
+        When the timer is running, the owner will receive timer events (see wxTimerEvent)
+        with @a id equal to @a id specified here.
     */
     void SetOwner(wxEvtHandler* owner, int id = -1);
 
@@ -101,19 +107,14 @@ public:
         (Re)starts the timer. If @a milliseconds parameter is -1 (value by default),
         the previous value is used. Returns @false if the timer could not be started,
         @true otherwise (in MS Windows timers are a limited resource).
-        If @a oneShot is @false (the default), the Notify()
-        function will be called repeatedly until the timer is stopped. If @true,
-        it will be called only once and the timer will stop automatically. To make your
-        code more readable you may also use the following symbolic constants:
 
-        wxTIMER_CONTINUOUS
+        If @a oneShot is @false (the default), the Notify() function will be called
-
+        repeatedly until the timer is stopped.
-        Start a normal, continuously running, timer
+        If @true, it will be called only once and the timer will stop automatically.
-
-        wxTIMER_ONE_SHOT
-
-        Start a one shot timer
 
+        To make your code more readable you may also use the following symbolic constants:
+        - wxTIMER_CONTINUOUS: Start a normal, continuously running, timer
+        - wxTIMER_ONE_SHOT: Start a one shot timer
         If the timer was already running, it will be stopped by this method before
         restarting it.
     */

interface/wx/tipdlg.h

@@ -19,9 +19,9 @@
     use it instead of the one returned by wxCreateFileTipProvider().
 
     @library{wxadv}
-    @category{FIXME}
+    @category{misc}
 
-    @see @ref overview_tipsoverview "Startup tips overview", ::wxShowTip
+    @see @ref overview_tips, ::wxShowTip
 */
 class wxTipProvider
 {
@@ -35,26 +35,27 @@ public:
     wxTipProvider(size_t currentTip);
 
     /**
-        Returns the index of the current tip (i.e. the one which would be returned by
+        Returns the index of the current tip (i.e. the one which would be returned by GetTip()).
-        GetTip).
+
         The program usually remembers the value returned by this function after calling
-        wxShowTip(). Note that it is not the same as the value which
+        wxShowTip(). Note that it is not the same as the value which was passed to
-        was passed to wxShowTip + 1 because the user might have pressed the "Next"
+        wxShowTip + 1 because the user might have pressed the "Next" button in
-        button in the tip dialog.
+        the tip dialog.
     */
     size_t GetCurrentTip() const;
 
     /**
-        Return the text of the current tip and pass to the next one. This function is
+        Return the text of the current tip and pass to the next one.
-        pure virtual, it should be implemented in the derived classes.
+        This function is pure virtual, it should be implemented in the derived classes.
     */
     wxString GetTip();
 
     /**
-        Returns a modified tip. This function will be called immediately after read,
+        Returns a modified tip.
-        and before being check whether it is a comment, an empty string or a string
+
-        to translate. You can optionally override this in your custom user-derived
+        This function will be called immediately after read, and before being check
-        class
+        whether it is a comment, an empty string or a string to translate.
+        You can optionally override this in your custom user-derived class
         to optionally to modify the tip as soon as it is read. You can return any
         modification to the string. If you return wxEmptyString, then this tip is
         skipped, and the next one is read.

interface/wx/tipwin.h

@@ -9,10 +9,10 @@
 /**
     @class wxTipWindow
 
-    Shows simple text in a popup tip window on creation. This is used by
+    Shows simple text in a popup tip window on creation.
-    wxSimpleHelpProvider to show popup help. The
+    This is used by wxSimpleHelpProvider to show popup help.
-    window automatically destroys itself when the user clicks on it or it loses the
+    The window automatically destroys itself when the user clicks on it or it
-    focus.
+    loses the focus.
 
     You may also use this class to emulate the tooltips when you need finer
     control over them than what the standard tooltips provide.
@@ -34,12 +34,10 @@ public:
             The length of each line, in pixels. Set to a very large
             value to avoid wrapping lines
         @param windowPtr
-            Simply passed to
+            Simply passed to SetTipWindowPtr() below, please see its
-            SetTipWindowPtr below, please see its
             documentation for the description of this parameter
         @param rectBounds
-            If non-@NULL, passed to
+            If non-@NULL, passed to SetBoundingRect() below, please see its
-            SetBoundingRect below, please see its
             documentation for the description of this parameter
     */
     wxTipWindow(wxWindow* parent, const wxString& text,
@@ -51,6 +49,7 @@ public:
         By default, the tip window disappears when the user clicks the mouse or presses
         a keyboard key or if it loses focus in any other way - for example because the
         user switched to another application window.
+
         Additionally, if a non-empty @a rectBound is provided, the tip window will
         also automatically close if the mouse leaves this area. This is useful to
         dismiss the tip mouse when the mouse leaves the object it is associated with.
@@ -63,7 +62,7 @@ public:
     /**
         When the tip window closes itself (which may happen at any moment and
         unexpectedly to the caller) it may @NULL out the pointer pointed to by
-        @e it windowPtr. This is helpful to avoid dereferencing the tip window which
+        @a windowPtr. This is helpful to avoid dereferencing the tip window which
         had been already closed and deleted.
     */
     void SetTipWindowPtr(wxTipWindow** windowPtr);