some s*h interface headers reviews

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

interface/wx/sashwin.h

@@ -6,15 +6,38 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+
+/**
+    See wxSashWindow.
+*/
+enum wxSashEdgePosition
+{
+    wxSASH_TOP = 0,
+    wxSASH_RIGHT,
+    wxSASH_BOTTOM,
+    wxSASH_LEFT,
+    wxSASH_NONE = 100
+};
+
+/**
+    See wxSashEvent.
+*/
+enum wxSashDragStatus
+{
+    wxSASH_STATUS_OK,
+    wxSASH_STATUS_OUT_OF_RANGE
+};
+
+
 /**
     @class wxSashWindow
 
     wxSashWindow allows any of its edges to have a sash which can be dragged
     to resize the window. The actual content window will be created by the
-    application
+    application as a child of wxSashWindow.
-    as a child of wxSashWindow. The window (or an ancestor) will be notified of a
+
-    drag
+    The window (or an ancestor) will be notified of a drag via a
-    via a wxSashEvent notification.
+    wxSashEvent notification.
 
     @beginStyleTable
     @style{wxSW_3D}
@@ -45,7 +68,11 @@
 class wxSashWindow : public wxWindow
 {
 public:
-    //@{
+    /**
+        Default ctor.
+    */
+    wxSashWindow();
+
     /**
         Constructs a sash window, which can be a child of a frame, dialog or any other
         non-control window.
@@ -56,10 +83,8 @@ public:
             Window identifier. If -1, will automatically create an identifier.
         @param pos
             Window position. wxDefaultPosition is (-1, -1) which indicates that
-        wxSashWindows
+            wxSashWindows should generate a default position for the window.
-            should generate a default position for the window. If using the
+            If using the wxSashWindow class directly, supply an actual position.
-        wxSashWindow class directly, supply
-            an actual position.
         @param size
             Window size. wxDefaultSize is (-1, -1) which indicates that wxSashWindows
             should generate a default size for the window.
@@ -68,13 +93,11 @@ public:
         @param name
             Window name.
     */
-    wxSashWindow();
     wxSashWindow(wxWindow* parent, wxWindowID id,
                  const wxPoint& pos = wxDefaultPosition,
                  const wxSize& size = wxDefaultSize,
                  long style = wxCLIP_CHILDREN | wxSW_3D,
                  const wxString& name = "sashWindow");
-    //@}
 
     /**
         Destructor.
@@ -174,10 +197,32 @@ public:
     A sash event is sent when the sash of a wxSashWindow has been
     dragged by the user.
 
-    @library{wxadv}
+    @remarks
-    @category{FIXME}
+    When a sash belonging to a sash window is dragged by the user, and then released,
+    this event is sent to the window, where it may be processed by an event table
+    entry in a derived class, a plug-in event handler or an ancestor class.
+    Note that the wxSashWindow doesn't change the window's size itself.
+    It relies on the application's event handler to do that.
+    This is because the application may have to handle other consequences of the resize,
+    or it may wish to veto it altogether. The event handler should look at the drag
+    rectangle: see wxSashEvent::GetDragRect to see what the new size of the window
+    would be if the resize were to be applied.
+    It should also call wxSashEvent::GetDragStatus to see whether the drag was
+    OK or out of the current allowed range.
 
-    @see wxSashWindow, @ref overview_eventhandlingoverview
+    @beginEventTable{wxSashEvent}
+    @event{EVT_SASH_DRAGGED(id, func)}
+        Process a wxEVT_SASH_DRAGGED event, when the user has finished dragging a sash.
+    @event{EVT_SASH_DRAGGED_RANGE(id1, id2, func)}
+        Process a wxEVT_SASH_DRAGGED_RANGE event, when the user has finished
+        dragging a sash. The event handler is called when windows with ids in
+        the given range have their sashes dragged.
+    @endEventTable
+
+    @library{wxadv}
+    @category{events}
+
+    @see wxSashWindow, @ref overview_eventhandling
 */
 class wxSashEvent : public wxCommandEvent
 {
@@ -189,22 +234,22 @@ public:
 
     /**
         Returns the rectangle representing the new size the window would be if the
-        resize was applied. It is
+        resize was applied. It is up to the application to set the window size if required.
-        up to the application to set the window size if required.
     */
     wxRect GetDragRect() const;
 
     /**
-        Returns the status of the sash: one of wxSASH_STATUS_OK,
+        Returns the status of the sash: one of wxSASH_STATUS_OK, wxSASH_STATUS_OUT_OF_RANGE.
-        wxSASH_STATUS_OUT_OF_RANGE.
+
         If the drag caused the notional bounding box of the window to flip over, for
         example, the drag will be out of rage.
     */
     wxSashDragStatus GetDragStatus() const;
 
     /**
-        Returns the dragged edge. The return value is one of wxSASH_TOP, wxSASH_RIGHT,
+        Returns the dragged edge.
-        wxSASH_BOTTOM, wxSASH_LEFT.
+
+        The return value is one of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT.
     */
     wxSashEdgePosition GetEdge() const;
 };

interface/wx/sckipc.h

@@ -6,6 +6,42 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+
+/**
+    See wxTCPConnection.
+*/
+enum wxIPCFormat
+{
+  wxIPC_INVALID =          0,
+  wxIPC_TEXT =             1,  /* CF_TEXT */
+  wxIPC_BITMAP =           2,  /* CF_BITMAP */
+  wxIPC_METAFILE =         3,  /* CF_METAFILEPICT */
+  wxIPC_SYLK =             4,
+  wxIPC_DIF =              5,
+  wxIPC_TIFF =             6,
+  wxIPC_OEMTEXT =          7,  /* CF_OEMTEXT */
+  wxIPC_DIB =              8,  /* CF_DIB */
+  wxIPC_PALETTE =          9,
+  wxIPC_PENDATA =          10,
+  wxIPC_RIFF =             11,
+  wxIPC_WAVE =             12,
+  wxIPC_UTF16TEXT =        13, /* CF_UNICODE */
+  wxIPC_ENHMETAFILE =      14,
+  wxIPC_FILENAME =         15, /* CF_HDROP */
+  wxIPC_LOCALE =           16,
+  wxIPC_UTF8TEXT =         17,
+  wxIPC_UTF32TEXT =        18,
+#if SIZEOF_WCHAR_T == 2
+  wxIPC_UNICODETEXT = wxIPC_UTF16TEXT,
+#elif SIZEOF_WCHAR_T == 4
+  wxIPC_UNICODETEXT = wxIPC_UTF32TEXT,
+#else
+#  error "Unknown wchar_t size"
+#endif
+  wxIPC_PRIVATE =          20
+};
+
+
 /**
     @class wxTCPServer
 
@@ -16,9 +52,9 @@
     A DDE-based implementation for Windows is available using wxDDEServer.
 
     @library{wxnet}
-    @category{FIXME}
+    @category{net}
 
-    @see wxTCPClient, wxTCPConnection, @ref overview_ipcoverview "IPC overview"
+    @see wxTCPClient, wxTCPConnection, @ref overview_ipc
 */
 class wxTCPServer : public wxObject
 {
@@ -29,19 +65,22 @@ public:
     wxTCPServer();
 
     /**
-        Registers the server using the given service name. Under Unix, the
+        Registers the server using the given service name.
-        string must contain an integer id which is used as an Internet port
+
-        number. @false is returned if the call failed (for example, the port
+        Under Unix, the string must contain an integer id which is used as an
-        number is already in use).
+        Internet port number. @false is returned if the call failed
+        (for example, the port number is already in use).
     */
     virtual bool Create(const wxString& service);
 
     /**
         When a client calls @b MakeConnection, the server receives the
-        message and this member is called. The application should derive a
+        message and this member is called.
-        member to intercept this message and return a connection object of
+
-        either the standard wxTCPConnection type, or of a user-derived type. If the
+        The application should derive a member to intercept this message and
-        topic is "STDIO", the application may wish to refuse the connection.
+        return a connection object of either the standard wxTCPConnection type,
+        or of a user-derived type.
+        If the topic is "STDIO", the application may wish to refuse the connection.
         Under Unix, when a server is created the OnAcceptConnection message is
         always sent for standard input and output.
     */
@@ -59,18 +98,17 @@ public:
 
     A DDE-based implementation for Windows is available using wxDDEClient.
 
-    To create a client which can communicate with a suitable server,
+    To create a client which can communicate with a suitable server, you need
-    you need to derive a class from wxTCPConnection and another from wxTCPClient.
+    to derive a class from wxTCPConnection and another from wxTCPClient.
     The custom wxTCPConnection class will intercept communications in
     a 'conversation' with a server, and the custom wxTCPServer is required
-    so that a user-overridden wxTCPClient::OnMakeConnection member can return
+    so that a user-overridden wxTCPClient::OnMakeConnection() member can return
     a wxTCPConnection of the required class, when a connection is made.
 
     @library{wxnet}
-    @category{FIXME}
+    @category{net}
 
-    @see wxTCPServer, wxTCPConnection, @ref overview_ipcoverview "Interprocess
+    @see wxTCPServer, wxTCPConnection, @ref overview_ipc
-    communications overview"
 */
 class wxTCPClient : public wxObject
 {
@@ -82,12 +120,13 @@ public:
 
     /**
         Tries to make a connection with a server specified by the host
-        (a machine name under Unix), service name (must
+        (a machine name under Unix), service name (must contain an integer
-        contain an integer port number under Unix), and a topic string. If the
+        port number under Unix), and a topic string.
-        server allows a connection, a wxTCPConnection object will be returned.
+
+        If the server allows a connection, a wxTCPConnection object will be returned.
+
         The type of wxTCPConnection returned can be altered by overriding
-        the OnMakeConnection() member to return your own
+        the OnMakeConnection() member to return your own derived connection object.
-        derived connection object.
     */
     virtual wxConnectionBase* MakeConnection(const wxString& host,
                                              const wxString& service,
@@ -98,10 +137,11 @@ public:
         be altered by deriving the @b OnMakeConnection member to return your
         own derived connection object. By default, a wxTCPConnection
         object is returned.
+
         The advantage of deriving your own connection class is that it will
         enable you to intercept messages initiated by the server, such
-        as wxTCPConnection::OnAdvise. You may also want to
+        as wxTCPConnection::OnAdvise(). You may also want to store
-        store application-specific data in instances of the new class.
+        application-specific data in instances of the new class.
     */
     virtual wxConnectionBase* OnMakeConnection();
 
@@ -123,36 +163,37 @@ public:
     A DDE-based implementation for Windows is available using wxDDEConnection.
 
     A wxTCPConnection object can be created by making a connection using a
-    wxTCPClient object, or by the acceptance of a connection by a
+    wxTCPClient object, or by the acceptance of a connection by a wxTCPServer object.
-    wxTCPServer object. The bulk of a conversation is controlled by
+    The bulk of a conversation is controlled by calling members in a
-    calling members in a @b wxTCPConnection object or by overriding its
+    @b wxTCPConnection object or by overriding its members.
-    members.
 
     An application should normally derive a new connection class from
     wxTCPConnection, in order to override the communication event handlers
     to do something interesting.
 
     @library{wxnet}
-    @category{FIXME}
+    @category{net}
 
-    @see wxTCPClient, wxTCPServer, @ref overview_ipcoverview "Interprocess
+    @see wxTCPClient, wxTCPServer, @ref overview_ipc
-    communications overview"
 */
 class wxTCPConnection : public wxObject
 {
 public:
     //@{
     /**
-        Constructs a connection object. If no user-defined connection object is
+        Constructs a connection object.
-        to be derived from wxTCPConnection, then the constructor should not be
+
-        called directly, since the default connection object will be provided on
+        If no user-defined connection object is to be derived from wxTCPConnection,
-        requesting (or accepting) a connection. However, if the user defines his
+        then the constructor should not be called directly, since the default
-        or her own derived connection object, the wxTCPServer::OnAcceptConnection
+        connection object will be provided on requesting (or accepting) a connection.
-        and/or wxTCPClient::OnMakeConnection members should be replaced by
+
-        functions which construct the new connection object. If the arguments of
+        However, if the user defines his or her own derived connection object,
-        the wxTCPConnection constructor are void, then a default buffer is
+        the wxTCPServer::OnAcceptConnection and/or wxTCPClient::OnMakeConnection
-        associated with the connection. Otherwise, the programmer must provide a
+        members should be replaced by functions which construct the new connection object.
-        a buffer and size of the buffer for the connection object to use in
+
+        If the arguments of the wxTCPConnection constructor are void, then a default
+        buffer is associated with the connection. Otherwise, the programmer must
+        provide a buffer and size of the buffer for the connection object to use in
         transactions.
     */
     wxTCPConnection();
@@ -162,9 +203,11 @@ public:
     //@{
     /**
         Called by the server application to advise the client of a change in
-        the data associated with the given item. Causes the client
+        the data associated with the given item.
-        connection's OnAdvise()
+
-        member to be called. Returns @true if successful.
+        Causes the client connection's OnAdvise() member to be called.
+
+        Returns @true if successful.
     */
     bool Advise(const wxString& item, const void* data, size_t size,
                 wxIPCFormat format = wxIPC_PRIVATE);
@@ -175,22 +218,25 @@ public:
 
     /**
         Called by the client or server application to disconnect from the other
-        program; it causes the OnDisconnect() message
+        program; it causes the OnDisconnect() message to be sent to the
-        to be sent to the corresponding connection object in the other
+        corresponding connection object in the other program.
-        program. The default behaviour of @b OnDisconnect is to delete the
+
+        The default behaviour of @b OnDisconnect is to delete the
         connection, but the calling application must explicitly delete its
-        side of the connection having called @b Disconnect. Returns @true if
+        side of the connection having called @b Disconnect.
-        successful.
+
+        Returns @true if successful.
     */
     virtual bool Disconnect();
 
     //@{
     /**
-        Called by the client application to execute a command on the server. Can
+        Called by the client application to execute a command on the server.
-        also be used to transfer arbitrary data to the server (similar
+        Can also be used to transfer arbitrary data to the server (similar
-        to Poke() in that respect). Causes the
+        to Poke() in that respect). Causes the server connection's OnExecute()
-        server connection's OnExecute() member to be
+        member to be called.
-        called. Returns @true if successful.
+
+        Returns @true if successful.
     */
     bool Execute(const void* data, size_t size,
                  wxIPCFormat format = wxIPC_PRIVATE);
@@ -211,15 +257,15 @@ public:
 
     /**
         Message sent to the client or server application when the other
-        application notifies it to delete the connection. Default behaviour is
+        application notifies it to delete the connection.
-        to delete the connection object.
+        Default behaviour is to delete the connection object.
     */
     virtual bool OnDisconnect();
 
     /**
         Message sent to the server application when the client notifies it to
-        execute the given data. Note that there is no item associated with
+        execute the given data.
-        this message.
+        Note that there is no item associated with this message.
     */
     virtual bool OnExecute(const wxString& topic, const void* data,
                            size_t size,
@@ -235,9 +281,9 @@ public:
                         wxIPCFormat format);
 
     /**
-        Message sent to the server application when the client
+        Message sent to the server application when the client calls Request().
-        calls Request(). The server
+
-        should respond by returning a character string from @b OnRequest,
+        The server should respond by returning a character string from @b OnRequest,
         or @NULL to indicate no data.
     */
     virtual const void* OnRequest(const wxString& topic,
@@ -247,16 +293,16 @@ public:
 
     /**
         Message sent to the server application by the client, when the client
-        wishes to start an 'advise loop' for the given topic and item. The
+        wishes to start an 'advise loop' for the given topic and item.
-        server can refuse to participate by returning @false.
+        The server can refuse to participate by returning @false.
     */
     virtual bool OnStartAdvise(const wxString& topic,
                                const wxString& item);
 
     /**
         Message sent to the server application by the client, when the client
-        wishes to stop an 'advise loop' for the given topic and item. The
+        wishes to stop an 'advise loop' for the given topic and item.
-        server can refuse to stop the advise loop by returning @false, although
+        The server can refuse to stop the advise loop by returning @false, although
         this doesn't have much meaning in practice.
     */
     virtual bool OnStopAdvise(const wxString& topic,
@@ -264,10 +310,9 @@ public:
 
     //@{
     /**
-        Called by the client application to poke data into the server. Can be
+        Called by the client application to poke data into the server.
-        used to transfer arbitrary data to the server. Causes the server
+        Can be used to transfer arbitrary data to the server. Causes the server
-        connection's OnPoke() member
+        connection's OnPoke() member to be called. Returns @true if successful.
-        to be called. Returns @true if successful.
     */
     bool Poke(const wxString& item, const void* data, size_t size,
               wxIPCFormat format = wxIPC_PRIVATE);
@@ -277,9 +322,10 @@ public:
     //@}
 
     /**
-        Called by the client application to request data from the server. Causes
+        Called by the client application to request data from the server.
-        the server connection's OnRequest() member to be called. Returns a
+        Causes the server connection's OnRequest() member to be called.
-        character string (actually a pointer to the connection's buffer) if
+
+        Returns a character string (actually a pointer to the connection's buffer) if
         successful, @NULL otherwise.
     */
     const void* Request(const wxString& item, size_t* size,
@@ -287,16 +333,17 @@ public:
 
     /**
         Called by the client application to ask if an advise loop can be started
-        with the server. Causes the server connection's OnStartAdvise()
+        with the server.
-        member to be called. Returns @true if the server okays it, @false
+
-        otherwise.
+        Causes the server connection's OnStartAdvise() member to be called.
+        Returns @true if the server okays it, @false otherwise.
     */
     virtual bool StartAdvise(const wxString& item);
 
     /**
-        Called by the client application to ask if an advise loop can be
+        Called by the client application to ask if an advise loop can be stopped.
-        stopped. Causes the server connection's OnStopAdvise() member
+        Causes the server connection's OnStopAdvise() member to be called.
-        to be called. Returns @true if the server okays it, @false otherwise.
+        Returns @true if the server okays it, @false otherwise.
     */
     virtual bool StopAdvise(const wxString& item);
 };

interface/wx/sckstrm.h

@@ -14,7 +14,7 @@
     and it does not support seeking.
 
     @library{wxnet}
-    @category{streams}
+    @category{net,streams}
 
     @see wxSocketBase
 */
@@ -38,7 +38,7 @@ public:
     and it does not support seeking.
 
     @library{wxnet}
-    @category{streams}
+    @category{net,streams}
 
     @see wxSocketBase
 */

interface/wx/scrolbar.h

@@ -9,10 +9,28 @@
 /**
     @class wxScrollBar
 
-    A wxScrollBar is a control that represents a horizontal or
+    A wxScrollBar is a control that represents a horizontal or vertical scrollbar.
-    vertical scrollbar. It is distinct from the two scrollbars that some windows
+
-    provide automatically, but the two types of scrollbar share the way
+    It is distinct from the two scrollbars that some windows provide automatically,
-    events are received.
+    but the two types of scrollbar share the way events are received.
+
+    @remarks
+    A scrollbar has the following main attributes: range, thumb size, page size, and position.
+    The range is the total number of units associated with the view represented by the scrollbar.
+    For a table with 15 columns, the range would be 15.
+    The thumb size is the number of units that are currently visible.
+    For the table example, the window might be sized so that only 5 columns are
+    currently visible, in which case the application would set the thumb size to 5.
+    When the thumb size becomes the same as or greater than the range, the scrollbar
+    will be automatically hidden on most platforms.
+    The page size is the number of units that the scrollbar should scroll by,
+    when 'paging' through the data. This value is normally the same as the thumb
+    size length, because it is natural to assume that the visible window size defines a page.
+    The scrollbar position is the current thumb position.
+    Most applications will find it convenient to provide a function called AdjustScrollbars()
+    which can be called initially, from an OnSize event handler, and whenever the
+    application data changes in size. It will adjust the view, object and page
+    size according to the size of the window and the size of the data.
 
     @beginStyleTable
     @style{wxSB_HORIZONTAL}
@@ -21,6 +39,70 @@
            Specifies a vertical scrollbar.
     @endStyleTable
 
+    @beginEventTable{wxScrollEvent}
+    You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting
+    scroll events from controls, or EVT_SCROLL... macros without window IDs for
+    intercepting scroll events from the receiving window -- except for this,
+    the macros behave exactly the same.
+    @event{EVT_SCROLL(func)}
+        Process all scroll events.
+    @event{EVT_SCROLL_TOP(func)}
+        Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
+    @event{EVT_SCROLL_BOTTOM(func)}
+        Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
+    @event{EVT_SCROLL_LINEUP(func)}
+        Process wxEVT_SCROLL_LINEUP line up events.
+    @event{EVT_SCROLL_LINEDOWN(func)}
+        Process wxEVT_SCROLL_LINEDOWN line down events.
+    @event{EVT_SCROLL_PAGEUP(func)}
+        Process wxEVT_SCROLL_PAGEUP page up events.
+    @event{EVT_SCROLL_PAGEDOWN(func)}
+        Process wxEVT_SCROLL_PAGEDOWN page down events.
+    @event{EVT_SCROLL_THUMBTRACK(func)}
+        Process wxEVT_SCROLL_THUMBTRACK thumbtrack events
+        (frequent events sent as the user drags the thumbtrack).
+    @event{EVT_SCROLL_THUMBRELEASE(func)}
+        Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
+    @event{EVT_SCROLL_CHANGED(func)}
+        Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
+    @event{EVT_COMMAND_SCROLL(id, func)}
+        Process all scroll events.
+    @event{EVT_COMMAND_SCROLL_TOP(id, func)}
+        Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
+    @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)}
+        Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
+    @event{EVT_COMMAND_SCROLL_LINEUP(id, func)}
+        Process wxEVT_SCROLL_LINEUP line up events.
+    @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)}
+        Process wxEVT_SCROLL_LINEDOWN line down events.
+    @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)}
+        Process wxEVT_SCROLL_PAGEUP page up events.
+    @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)}
+        Process wxEVT_SCROLL_PAGEDOWN page down events.
+    @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)}
+        Process wxEVT_SCROLL_THUMBTRACK thumbtrack events
+        (frequent events sent as the user drags the thumbtrack).
+    @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)}
+        Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
+    @event{EVT_COMMAND_SCROLL_CHANGED(func)}
+        Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
+    @endEventTable
+
+    @section scrollbar_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
+
+    The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the
+    thumb using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event
+    is also followed by an EVT_SCROLL_CHANGED event).
+
+    The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change
+    the thumb position, and when clicking next to the thumb
+    (In all these cases the EVT_SCROLL_THUMBRELEASE event does not happen).
+
+    In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/moving has
+    finished independently of the way it had started. Please see the widgets sample
+    ("Slider" page) to see the difference between EVT_SCROLL_THUMBRELEASE and
+    EVT_SCROLL_CHANGED in action.
+
     @library{wxcore}
     @category{ctrl}
     <!-- @appearance{scrollbar.png} -->
@@ -34,7 +116,7 @@ public:
       Default constructor
     */
     wxScrollBar();
-    
+
     /**
         Constructor, creating and showing a scrollbar.
 
@@ -81,9 +163,10 @@ public:
                 const wxString& name = "scrollBar");
 
     /**
-        Returns the page size of the scrollbar. This is the number of scroll units
+        Returns the page size of the scrollbar.
-        that will be scrolled when the user pages up or down. Often it is the
+
-        same as the thumb size.
+        This is the number of scroll units that will be scrolled when the user
+        pages up or down. Often it is the same as the thumb size.
 
         @see SetScrollbar()
     */
@@ -121,15 +204,29 @@ public:
             The maximum position of the scrollbar.
         @param pageSize
             The size of the page size in scroll units. This is the number of units
-            the scrollbar will scroll when it is paged up or down. Often it is the same
+            the scrollbar will scroll when it is paged up or down.
-        as
+            Often it is the same as the thumb size.
-            the thumb size.
         @param refresh
             @true to redraw the scrollbar, @false otherwise.
 
-        @remarks Let's say you wish to display 50 lines of text, using the same
+        @remarks
-                 font. The window is sized so that you can only see 16
+            Let's say you wish to display 50 lines of text, using the same
-                 lines at a time.
+            font. The window is sized so that you can only see 16 lines at a time.
+            You would use:
+            @code
+            scrollbar->SetScrollbar(0, 16, 50, 15);
+            @endcode
+            The page size is 1 less than the thumb size so that the last line of
+            the previous page will be visible on the next page, to help orient the user.
+            Note that with the window at this size, the thumb position can never
+            go above 50 minus 16, or 34.
+            You can determine how many lines are currently visible by dividing
+            the current view size by the character height in pixels.
+            When defining your own scrollbar behaviour, you will always need to
+            recalculate the scrollbar settings when the window size changes.
+            You could therefore put your scrollbar calculations and SetScrollbar()
+            call into a function named AdjustScrollbars, which can be called
+            initially and also from a wxSizeEvent event handler function.
     */
     virtual void SetScrollbar(int position, int thumbSize, int range,
                               int pageSize,

interface/wx/settings.h

@@ -6,11 +6,154 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+
+/**
+    Possible values for wxSystemSettings::GetFont() parameter.
+*/
+enum wxSystemFont
+{
+    wxSYS_OEM_FIXED_FONT = 10,   //!< Original equipment manufacturer dependent fixed-pitch font.
+    wxSYS_ANSI_FIXED_FONT,       //!< Windows fixed-pitch font.
+    wxSYS_ANSI_VAR_FONT,         //!< Windows variable-pitch (proportional) font.
+    wxSYS_SYSTEM_FONT,           //!< System font.
+    wxSYS_DEVICE_DEFAULT_FONT,   //!< Device-dependent font (Windows NT only).
+    wxSYS_DEFAULT_PALETTE,       //!< @todo docme.
+    wxSYS_SYSTEM_FIXED_FONT,     //!< @todo docme.
+
+    /**
+        Default font for user interface objects such as menus and dialog boxes.
+        Note that with modern GUIs nothing guarantees that the same font is used
+        for all GUI elements, so some controls might use a different font by default.
+    */
+    wxSYS_DEFAULT_GUI_FONT
+};
+
+
+/**
+    Possible values for wxSystemSettings::GetColour() parameter.
+*/
+enum wxSystemColour
+{
+    wxSYS_COLOUR_SCROLLBAR,           //!< The scrollbar grey area.
+    wxSYS_COLOUR_BACKGROUND,          //!< The desktop colour.
+    wxSYS_COLOUR_ACTIVECAPTION,       //!< Active window caption.
+    wxSYS_COLOUR_INACTIVECAPTION,     //!< Inactive window caption.
+    wxSYS_COLOUR_MENU,                //!< Menu background.
+    wxSYS_COLOUR_WINDOW,              //!< Window background.
+    wxSYS_COLOUR_WINDOWFRAME,         //!< Window frame.
+    wxSYS_COLOUR_MENUTEXT,            //!< Menu text.
+    wxSYS_COLOUR_WINDOWTEXT,          //!< Text in windows.
+    wxSYS_COLOUR_CAPTIONTEXT,         //!< Text in caption, size box and scrollbar arrow box.
+    wxSYS_COLOUR_ACTIVEBORDER,        //!< Active window border.
+    wxSYS_COLOUR_INACTIVEBORDER,      //!< Inactive window border.
+    wxSYS_COLOUR_APPWORKSPACE,        //!< Background colour MDI applications.
+    wxSYS_COLOUR_HIGHLIGHT,           //!< Item(s) selected in a control.
+    wxSYS_COLOUR_HIGHLIGHTTEXT,       //!< Text of item(s) selected in a control.
+    wxSYS_COLOUR_BTNFACE,             //!< Face shading on push buttons.
+    wxSYS_COLOUR_BTNSHADOW,           //!< Edge shading on push buttons.
+    wxSYS_COLOUR_GRAYTEXT,            //!< Greyed (disabled) text.
+    wxSYS_COLOUR_BTNTEXT,             //!< Text on push buttons.
+    wxSYS_COLOUR_INACTIVECAPTIONTEXT, //!< Colour of text in active captions.
+    wxSYS_COLOUR_BTNHIGHLIGHT,        //!< Highlight colour for buttons (same as wxSYS_COLOUR_3DHILIGHT).
+    wxSYS_COLOUR_3DDKSHADOW,          //!< Dark shadow for three-dimensional display elements.
+    wxSYS_COLOUR_3DLIGHT,             //!< Light colour for three-dimensional display elements.
+    wxSYS_COLOUR_INFOTEXT,            //!< Text colour for tooltip controls.
+    wxSYS_COLOUR_INFOBK,              //!< Background colour for tooltip controls.
+
+    wxSYS_COLOUR_DESKTOP = wxSYS_COLOUR_BACKGROUND,
+    wxSYS_COLOUR_3DFACE = wxSYS_COLOUR_BTNFACE,
+    wxSYS_COLOUR_3DSHADOW = wxSYS_COLOUR_BTNSHADOW,
+    wxSYS_COLOUR_BTNHILIGHT = wxSYS_COLOUR_BTNHIGHLIGHT,
+    wxSYS_COLOUR_3DHIGHLIGHT = wxSYS_COLOUR_BTNHIGHLIGHT,
+    wxSYS_COLOUR_3DHILIGHT = wxSYS_COLOUR_BTNHIGHLIGHT,
+
+    wxSYS_COLOUR_LISTBOX,
+    wxSYS_COLOUR_HOTLIGHT,
+    wxSYS_COLOUR_GRADIENTACTIVECAPTION,
+    wxSYS_COLOUR_GRADIENTINACTIVECAPTION,
+    wxSYS_COLOUR_MENUHILIGHT,
+    wxSYS_COLOUR_MENUBAR,
+
+    wxSYS_COLOUR_MAX
+};
+
+/**
+    Possible values for wxSystemSettings::GetMetric() index parameter.
+*/
+enum wxSystemMetric
+{
+    wxSYS_MOUSE_BUTTONS,      //!< Number of buttons on mouse, or zero if no mouse was installed.
+    wxSYS_BORDER_X,           //!< Width of single border.
+    wxSYS_BORDER_Y,           //!< Height of single border.
+    wxSYS_CURSOR_X,           //!< Width of cursor.
+    wxSYS_CURSOR_Y,           //!< Height of cursor.
+    wxSYS_DCLICK_X,           //!< Width in pixels of rectangle within which two successive mouse clicks must fall to generate a double-click.
+    wxSYS_DCLICK_Y,           //!< Height in pixels of rectangle within which two successive mouse clicks must fall to generate a double-click.
+    wxSYS_DCLICK_MSEC,        //!< Maximal time, in milliseconds, which may pass between subsequent clicks for a double click to be generated.
+    wxSYS_DRAG_X,             //!< Width in pixels of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins.
+    wxSYS_DRAG_Y,             //!< Height in pixels of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins.
+    wxSYS_EDGE_X,             //!< Width of a 3D border, in pixels.
+    wxSYS_EDGE_Y,             //!< Height of a 3D border, in pixels.
+    wxSYS_HSCROLL_ARROW_X,    //!< Width of arrow bitmap on horizontal scrollbar.
+    wxSYS_HSCROLL_ARROW_Y,    //!< Height of arrow bitmap on horizontal scrollbar.
+    wxSYS_HTHUMB_X,           //!< Width of horizontal scrollbar thumb.
+    wxSYS_ICON_X,             //!< The default width of an icon.
+    wxSYS_ICON_Y,             //!< The default height of an icon.
+    wxSYS_ICONSPACING_X,      //!< Width of a grid cell for items in large icon view, in pixels. Each item fits into a rectangle of this size when arranged.
+    wxSYS_ICONSPACING_Y,      //!< Height of a grid cell for items in large icon view, in pixels. Each item fits into a rectangle of this size when arranged.
+    wxSYS_WINDOWMIN_X,        //!< Minimum width of a window.
+    wxSYS_WINDOWMIN_Y,        //!< Minimum height of a window.
+    wxSYS_SCREEN_X,           //!< Width of the screen in pixels.
+    wxSYS_SCREEN_Y,           //!< Height of the screen in pixels.
+    wxSYS_FRAMESIZE_X,        //!< Width of the window frame for a wxTHICK_FRAME window.
+    wxSYS_FRAMESIZE_Y,        //!< Height of the window frame for a wxTHICK_FRAME window.
+    wxSYS_SMALLICON_X,        //!< Recommended width of a small icon (in window captions, and small icon view).
+    wxSYS_SMALLICON_Y,        //!< Recommended height of a small icon (in window captions, and small icon view).
+    wxSYS_HSCROLL_Y,          //!< Height of horizontal scrollbar in pixels.
+    wxSYS_VSCROLL_X,          //!< Width of vertical scrollbar in pixels.
+    wxSYS_VSCROLL_ARROW_X,    //!< Width of arrow bitmap on a vertical scrollbar.
+    wxSYS_VSCROLL_ARROW_Y,    //!< Height of arrow bitmap on a vertical scrollbar.
+    wxSYS_VTHUMB_Y,           //!< Height of vertical scrollbar thumb.
+    wxSYS_CAPTION_Y,          //!< Height of normal caption area.
+    wxSYS_MENU_Y,             //!< Height of single-line menu bar.
+    wxSYS_NETWORK_PRESENT,    //!< 1 if there is a network present, 0 otherwise.
+    wxSYS_PENWINDOWS_PRESENT, //!< 1 if PenWindows is installed, 0 otherwise.
+    wxSYS_SHOW_SOUNDS,        //!< Non-zero if the user requires an application to present information
+                              //!< visually in situations where it would otherwise present the information
+                              //!< only in audible form; zero otherwise.
+    wxSYS_SWAP_BUTTONS,       //!< Non-zero if the meanings of the left and right mouse buttons are swapped; zero otherwise.
+    wxSYS_DCLICK_MSEC
+};
+
+/**
+    Possible values for wxSystemSettings::HasFeature() parameter.
+*/
+enum wxSystemFeature
+{
+    wxSYS_CAN_DRAW_FRAME_DECORATIONS = 1,
+    wxSYS_CAN_ICONIZE_FRAME,
+    wxSYS_TABLET_PRESENT
+};
+
+/**
+    Values for different screen designs.
+*/
+enum wxSystemScreenType
+{
+    wxSYS_SCREEN_NONE = 0,  //!< Undefined screen type.
+
+    wxSYS_SCREEN_TINY,      //!< Tiny screen, less than 320x240
+    wxSYS_SCREEN_PDA,       //!< PDA screen, 320x240 or more but less than 640x480
+    wxSYS_SCREEN_SMALL,     //!< Small screen, 640x480 or more but less than 800x600
+    wxSYS_SCREEN_DESKTOP    //!< Desktop screen, 800x600 or more
+};
+
+
 /**
     @class wxSystemSettings
 
-    wxSystemSettings allows the application to ask for details about
+    wxSystemSettings allows the application to ask for details about the system.
-    the system. This can include settings such as standard colours, fonts,
+    This can include settings such as standard colours, fonts,
     and user interface element sizes.
 
     @library{wxcore}
@@ -22,383 +165,49 @@ class wxSystemSettings : public wxObject
 {
 public:
     /**
-        Default constructor. You don't need to create an instance of wxSystemSettings
+        Default constructor.
+
+        You don't need to create an instance of wxSystemSettings
         since all of its functions are static.
     */
     wxSystemSettings();
 
     /**
         Returns a system colour.
-        @a index can be one of:
+        @a index can be one of the ::wxSystemColour enum values.
-
-        @b wxSYS_COLOUR_SCROLLBAR
-
-        The scrollbar grey area.
-
-        @b wxSYS_COLOUR_BACKGROUND
-
-        The desktop colour.
-
-        @b wxSYS_COLOUR_ACTIVECAPTION
-
-        Active window caption.
-
-        @b wxSYS_COLOUR_INACTIVECAPTION
-
-        Inactive window caption.
-
-        @b wxSYS_COLOUR_MENU
-
-        Menu background.
-
-        @b wxSYS_COLOUR_WINDOW
-
-        Window background.
-
-        @b wxSYS_COLOUR_WINDOWFRAME
-
-        Window frame.
-
-        @b wxSYS_COLOUR_MENUTEXT
-
-        Menu text.
-
-        @b wxSYS_COLOUR_WINDOWTEXT
-
-        Text in windows.
-
-        @b wxSYS_COLOUR_CAPTIONTEXT
-
-        Text in caption, size box and scrollbar arrow box.
-
-        @b wxSYS_COLOUR_ACTIVEBORDER
-
-        Active window border.
-
-        @b wxSYS_COLOUR_INACTIVEBORDER
-
-        Inactive window border.
-
-        @b wxSYS_COLOUR_APPWORKSPACE
-
-        Background colour MDI applications.
-
-        @b wxSYS_COLOUR_HIGHLIGHT
-
-        Item(s) selected in a control.
-
-        @b wxSYS_COLOUR_HIGHLIGHTTEXT
-
-        Text of item(s) selected in a control.
-
-        @b wxSYS_COLOUR_BTNFACE
-
-        Face shading on push buttons.
-
-        @b wxSYS_COLOUR_BTNSHADOW
-
-        Edge shading on push buttons.
-
-        @b wxSYS_COLOUR_GRAYTEXT
-
-        Greyed (disabled) text.
-
-        @b wxSYS_COLOUR_BTNTEXT
-
-        Text on push buttons.
-
-        @b wxSYS_COLOUR_INACTIVECAPTIONTEXT
-
-        Colour of text in active captions.
-
-        @b wxSYS_COLOUR_BTNHIGHLIGHT
-
-        Highlight colour for buttons (same as wxSYS_COLOUR_3DHILIGHT).
-
-        @b wxSYS_COLOUR_3DDKSHADOW
-
-        Dark shadow for three-dimensional display elements.
-
-        @b wxSYS_COLOUR_3DLIGHT
-
-        Light colour for three-dimensional display elements.
-
-        @b wxSYS_COLOUR_INFOTEXT
-
-        Text colour for tooltip controls.
-
-        @b wxSYS_COLOUR_INFOBK
-
-        Background colour for tooltip controls.
-
-        @b wxSYS_COLOUR_DESKTOP
-
-        Same as wxSYS_COLOUR_BACKGROUND.
-
-        @b wxSYS_COLOUR_3DFACE
-
-        Same as wxSYS_COLOUR_BTNFACE.
-
-        @b wxSYS_COLOUR_3DSHADOW
-
-        Same as wxSYS_COLOUR_BTNSHADOW.
-
-        @b wxSYS_COLOUR_3DHIGHLIGHT
-
-        Same as wxSYS_COLOUR_BTNHIGHLIGHT.
-
-        @b wxSYS_COLOUR_3DHILIGHT
-
-        Same as wxSYS_COLOUR_BTNHIGHLIGHT.
-
-        @b wxSYS_COLOUR_BTNHILIGHT
-
-        Same as wxSYS_COLOUR_BTNHIGHLIGHT.
     */
     static wxColour GetColour(wxSystemColour index);
 
     /**
         Returns a system font.
-        @a index can be one of:
+        @a index can be one of the ::wxSystemFont enum values.
-
-        @b wxSYS_OEM_FIXED_FONT
-
-        Original equipment manufacturer dependent fixed-pitch font.
-
-        @b wxSYS_ANSI_FIXED_FONT
-
-        Windows fixed-pitch font.
-
-        @b wxSYS_ANSI_VAR_FONT
-
-        Windows variable-pitch (proportional) font.
-
-        @b wxSYS_SYSTEM_FONT
-
-        System font.
-
-        @b wxSYS_DEVICE_DEFAULT_FONT
-
-        Device-dependent font (Windows NT only).
-
-        @b wxSYS_DEFAULT_GUI_FONT
-
-        Default font for user interface
-        objects such as menus and dialog boxes. Note that with modern GUIs nothing
-        guarantees that the same font is used for all GUI elements, so some controls
-        might use a different font by default.
     */
     static wxFont GetFont(wxSystemFont index);
 
     /**
         Returns the value of a system metric, or -1 if the metric is not supported on
         the current system.
+
         The value of @a win determines if the metric returned is a global value or
         a wxWindow based value, in which case it might determine the widget, the
         display the window is on, or something similar. The window given should be as
-        close to the
+        close to the metric as possible (e.g a wxTopLevelWindow in case of the
-        metric as possible (e.g a wxTopLevelWindow in case of the wxSYS_CAPTION_Y
+        wxSYS_CAPTION_Y metric).
-        metric).
-        @a index can be one of:
 
-        @b wxSYS_MOUSE_BUTTONS
+        @a index can be one of the ::wxSystemMetric enum values.
-
-        Number of buttons on mouse, or zero if no mouse was installed.
-
-        @b wxSYS_BORDER_X
-
-        Width of single border.
-
-        @b wxSYS_BORDER_Y
-
-        Height of single border.
-
-        @b wxSYS_CURSOR_X
-
-        Width of cursor.
-
-        @b wxSYS_CURSOR_Y
-
-        Height of cursor.
-
-        @b wxSYS_DCLICK_X
-
-        Width in pixels of rectangle within which two successive mouse
-        clicks must fall to generate a double-click.
-
-        @b wxSYS_DCLICK_Y
-
-        Height in pixels of rectangle within which two successive mouse
-        clicks must fall to generate a double-click.
-
-        @b wxSYS_DCLICK_MSEC
-
-        Maximal time, in milliseconds, which may
-        pass between subsequent clicks for a double click to be generated.
-
-        @b wxSYS_DRAG_X
-
-        Width in pixels of a rectangle centered on a drag point
-        to allow for limited movement of the mouse pointer before a drag operation
-        begins.
-
-        @b wxSYS_DRAG_Y
-
-        Height in pixels of a rectangle centered on a drag point
-        to allow for limited movement of the mouse pointer before a drag operation
-        begins.
-
-        @b wxSYS_EDGE_X
-
-        Width of a 3D border, in pixels.
-
-        @b wxSYS_EDGE_Y
-
-        Height of a 3D border, in pixels.
-
-        @b wxSYS_HSCROLL_ARROW_X
-
-        Width of arrow bitmap on horizontal scrollbar.
-
-        @b wxSYS_HSCROLL_ARROW_Y
-
-        Height of arrow bitmap on horizontal scrollbar.
-
-        @b wxSYS_HTHUMB_X
-
-        Width of horizontal scrollbar thumb.
-
-        @b wxSYS_ICON_X
-
-        The default width of an icon.
-
-        @b wxSYS_ICON_Y
-
-        The default height of an icon.
-
-        @b wxSYS_ICONSPACING_X
-
-        Width of a grid cell for items in large icon view,
-        in pixels. Each item fits into a rectangle of this size when arranged.
-
-        @b wxSYS_ICONSPACING_Y
-
-        Height of a grid cell for items in large icon view,
-        in pixels. Each item fits into a rectangle of this size when arranged.
-
-        @b wxSYS_WINDOWMIN_X
-
-        Minimum width of a window.
-
-        @b wxSYS_WINDOWMIN_Y
-
-        Minimum height of a window.
-
-        @b wxSYS_SCREEN_X
-
-        Width of the screen in pixels.
-
-        @b wxSYS_SCREEN_Y
-
-        Height of the screen in pixels.
-
-        @b wxSYS_FRAMESIZE_X
-
-        Width of the window frame for a wxTHICK_FRAME window.
-
-        @b wxSYS_FRAMESIZE_Y
-
-        Height of the window frame for a wxTHICK_FRAME window.
-
-        @b wxSYS_SMALLICON_X
-
-        Recommended width of a small icon (in window captions, and small icon view).
-
-        @b wxSYS_SMALLICON_Y
-
-        Recommended height of a small icon (in window captions, and small icon view).
-
-        @b wxSYS_HSCROLL_Y
-
-        Height of horizontal scrollbar in pixels.
-
-        @b wxSYS_VSCROLL_X
-
-        Width of vertical scrollbar in pixels.
-
-        @b wxSYS_VSCROLL_ARROW_X
-
-        Width of arrow bitmap on a vertical scrollbar.
-
-        @b wxSYS_VSCROLL_ARROW_Y
-
-        Height of arrow bitmap on a vertical scrollbar.
-
-        @b wxSYS_VTHUMB_Y
-
-        Height of vertical scrollbar thumb.
-
-        @b wxSYS_CAPTION_Y
-
-        Height of normal caption area.
-
-        @b wxSYS_MENU_Y
-
-        Height of single-line menu bar.
-
-        @b wxSYS_NETWORK_PRESENT
-
-        1 if there is a network present, 0 otherwise.
-
-        @b wxSYS_PENWINDOWS_PRESENT
-
-        1 if PenWindows is installed, 0 otherwise.
-
-        @b wxSYS_SHOW_SOUNDS
-
-        Non-zero if the user requires an application to present information visually in
-        situations
-        where it would otherwise present the information only in audible form; zero
-        otherwise.
-
-        @b wxSYS_SWAP_BUTTONS
-
-        Non-zero if the meanings of the left and right mouse buttons are swapped; zero
-        otherwise.
 
         @a win is a pointer to the window for which the metric is requested.
         Specifying the @a win parameter is encouraged, because some metrics on some
-        ports are not supported without one,
+        ports are not supported without one,or they might be capable of reporting
-        or they might be capable of reporting better values if given one. If a window
+        better values if given one. If a window does not make sense for a metric,
-        does not make sense for a metric,
         one should still be given, as for example it might determine which displays
-        cursor width is requested with
+        cursor width is requested with wxSYS_CURSOR_X.
-        wxSYS_CURSOR_X.
     */
     static int GetMetric(wxSystemMetric index, wxWindow* win = NULL);
 
     /**
-        Returns the screen type. The return value is one of:
+        Returns the screen type.
-
+        The return value is one of the ::wxSystemScreenType enum values.
-        @b wxSYS_SCREEN_NONE
-
-        Undefined screen type
-
-        @b wxSYS_SCREEN_TINY
-
-        Tiny screen, less than 320x240
-
-        @b wxSYS_SCREEN_PDA
-
-        PDA screen, 320x240 or more but less than 640x480
-
-        @b wxSYS_SCREEN_SMALL
-
-        Small screen, 640x480 or more but less than 800x600
-
-        @b wxSYS_SCREEN_DESKTOP
-
-        Desktop screen, 800x600 or more
     */
     static wxSystemScreenType GetScreenType();
 };

interface/wx/sizer.h

@@ -10,33 +10,28 @@
     @class wxStdDialogButtonSizer
 
     This class creates button layouts which conform to the standard button spacing
-    and ordering defined by the platform
+    and ordering defined by the platform or toolkit's user interface guidelines
-    or toolkit's user interface guidelines (if such things exist). By using this
+    (if such things exist). By using this class, you can ensure that all your
-    class, you can ensure that all your
     standard dialogs look correct on all major platforms. Currently it conforms to
-    the Windows, GTK+ and Mac OS X
+    the Windows, GTK+ and Mac OS X human interface guidelines.
-    human interface guidelines.
 
     When there aren't interface guidelines defined for a particular platform or
-    toolkit, wxStdDialogButtonSizer reverts
+    toolkit, wxStdDialogButtonSizer reverts to the Windows implementation.
-    to the Windows implementation.
 
-    To use this class, first add buttons to the sizer by calling AddButton (or
+    To use this class, first add buttons to the sizer by calling
-    SetAffirmativeButton, SetNegativeButton,
+    wxStdDialogButtonSizer::AddButton (or wxStdDialogButtonSizer::SetAffirmativeButton,
-    or SetCancelButton) and then call Realize in order to create the actual button
+    wxStdDialogButtonSizer::SetNegativeButton or wxStdDialogButtonSizer::SetCancelButton)
-    layout used. Other than these special
+    and then call Realize in order to create the actual button layout used.
-    operations, this sizer works like any other sizer.
+    Other than these special operations, this sizer works like any other sizer.
 
     If you add a button with wxID_SAVE, on Mac OS X the button will be renamed to
-    "Save" and
+    "Save" and the wxID_NO button will be renamed to "Don't Save" in accordance
-    the wxID_NO button will be renamed to "Don't Save" in accordance with the Mac
+    with the Mac OS X Human Interface Guidelines.
-    OS X Human Interface Guidelines.
 
     @library{wxcore}
     @category{winlayout}
 
-    @see wxSizer, @ref overview_sizer "Sizer Overview",
+    @see wxSizer, @ref overview_sizer, wxDialog::CreateButtonSizer
-    wxDialog::CreateButtonSizer
 */
 class wxStdDialogButtonSizer : public wxBoxSizer
 {
@@ -49,39 +44,45 @@ public:
     /**
         Adds a button to the wxStdDialogButtonSizer. The @a button must have
         one of the following identifiers:
-         wxID_OK
+         - wxID_OK
-         wxID_YES
+         - wxID_YES
-         wxID_SAVE
+         - wxID_SAVE
-         wxID_APPLY
+         - wxID_APPLY
-         wxID_CLOSE
+         - wxID_CLOSE
-         wxID_NO
+         - wxID_NO
-         wxID_CANCEL
+         - wxID_CANCEL
-         wxID_HELP
+         - wxID_HELP
-         wxID_CONTEXT_HELP
+         - wxID_CONTEXT_HELP
     */
     void AddButton(wxButton* button);
 
     /**
-        Rearranges the buttons and applies proper spacing between buttons to make them
+        Rearranges the buttons and applies proper spacing between buttons to make
-        match the platform or toolkit's interface guidelines.
+        them match the platform or toolkit's interface guidelines.
     */
     void Realize();
 
     /**
-        Sets the affirmative button for the sizer. This allows you to use identifiers
+        Sets the affirmative button for the sizer.
-        other than the standard identifiers outlined above.
+
+        This allows you to use identifiers other than the standard identifiers
+        outlined above.
     */
     void SetAffirmativeButton(wxButton* button);
 
     /**
-        Sets the cancel button for the sizer. This allows you to use identifiers other
+        Sets the cancel button for the sizer.
-        than the standard identifiers outlined above.
+
+        This allows you to use identifiers other than the standard identifiers
+        outlined above.
     */
     void SetCancelButton(wxButton* button);
 
     /**
-        Sets the negative button for the sizer. This allows you to use identifiers
+        Sets the negative button for the sizer.
-        other than the standard identifiers outlined above.
+
+        This allows you to use identifiers other than the standard identifiers
+        outlined above.
     */
     void SetNegativeButton(wxButton* button);
 };
@@ -92,10 +93,11 @@ public:
     @class wxSizerItem
 
     The wxSizerItem class is used to track the position, size and other
-    attributes of each item managed by a wxSizer. It is not usually necessary
+    attributes of each item managed by a wxSizer.
-    to use this class because the sizer elements can also be identified by
+
-    their positions or window or sizer pointers but sometimes it may be more
+    It is not usually necessary to use this class because the sizer elements can
-    convenient to use it directly.
+    also be identified by their positions or window or sizer pointers but sometimes
+    it may be more convenient to use it directly.
 
     @library{wxcore}
     @category{winlayout}

interface/wx/slider.h

@@ -44,7 +44,7 @@
     @category{ctrl}
     <!-- @appearance{slider.png} -->
 
-    @see @ref overview_eventhandlingoverview, wxScrollBar
+    @see @ref overview_eventhandling, wxScrollBar
 */
 class wxSlider : public wxControl
 {
@@ -53,7 +53,7 @@ public:
        Default constructor
     */
     wxSlider();
-    
+
     /**
         Constructor, creating and showing a slider.
 

interface/wx/taskbar.h

@@ -15,7 +15,7 @@
 
     @section taskbaricon_xnote X Window System Note
     Under X Window System, the window manager must support either the
-    @link http://freedesktop.org/wiki/Specifications/systemtray-spec "System Tray Protocol"
+    "System Tray Protocol" (see http://freedesktop.org/wiki/Specifications/systemtray-spec)
     by freedesktop.org (WMs used by modern desktop environments such as GNOME >= 2,
     KDE >= 3 and XFCE >= 4 all do) or the older methods used in GNOME 1.2 and KDE 1 and 2.
 

interface/wx/textfile.h

@@ -11,9 +11,9 @@
 enum wxTextFileType
 {
     wxTextFileType_None,  //!< incomplete (the last line of the file only)
-    wxTextFileType_Unix,  //!< line is terminated with 'LF' = 0xA = 10 = '\n'
+    wxTextFileType_Unix,  //!< line is terminated with 'LF' = 0xA = 10 = '\\n'
     wxTextFileType_Dos,   //!< line is terminated with 'CR' 'LF'
-    wxTextFileType_Mac,   //!< line is terminated with 'CR' = 0xD = 13 = '\r'
+    wxTextFileType_Mac,   //!< line is terminated with 'CR' = 0xD = 13 = '\\r'
     wxTextFileType_Os2    //!< line is terminated with 'CR' 'LF'
 };
 
@@ -101,7 +101,7 @@ public:
     //@{
     /**
         Creates the file with the given name or the name which was given in the
-        @ref ctor() constructor. The array of file lines is initially empty.
+        @ref wxTextFile() constructor. The array of file lines is initially empty.
 
         It will fail if the file already exists, Open() should be used in this case.
     */
@@ -238,7 +238,7 @@ public:
     //@{
     /**
         Open() opens the file with the given name or the name which was given in the
-        @ref ctor() constructor and also loads file in memory on success.
+        @ref wxTextFile() constructor and also loads file in memory on success.
 
         It will fail if the file does not exist, Create() should be used in this case.
 
@@ -262,7 +262,7 @@ public:
         for example, DOS files to Unix.
 
         The @a conv argument is only meaningful in Unicode build of wxWidgets when
-        it is used to convert all lines to multibyte representation before writing them
+        it is used to convert all lines to multibyte representation before writing
         them to physical file.
 
         @return