revised a* interface headers; categorized many functions; moved some functions to their correct header

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

interface/aboutdlg.h

@@ -171,6 +171,9 @@ public:
 // Global functions/macros
 // ============================================================================
 
+/** @ingroup group_funcmacro_dialog */
+//@{
+
 /**
     This function shows the standard about dialog containing the information
     specified in @a info. If the current platform has a native about dialog
@@ -214,3 +217,4 @@ void wxAboutBox(const wxAboutDialogInfo& info);
 */
 void wxGenericAboutBox(const wxAboutDialogInfo& info);
 
+//@}

interface/accel.h

@@ -180,6 +180,11 @@ public:
     wxAcceleratorTable operator =(const wxAcceleratorTable& accel);
 };
 
+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
 /**
     An empty accelerator table.
 */

interface/animate.h

@@ -170,7 +170,6 @@ public:
 
 /**
     @class wxAnimation
-    @ingroup group_class_gdi
     @wxheader{animate.h}
 
     This class encapsulates the concept of a platform-dependent animation.
@@ -270,6 +269,11 @@ public:
     wxAnimation operator =(const wxAnimation& brush);
 };
 
+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
 /**
     An empty animation object.
 */

interface/app.h

@@ -608,6 +608,14 @@ public:
 // Global functions/macros
 // ============================================================================
 
+/**
+    The global pointer to the singleton wxApp object.
+
+    @see wxApp::GetInstance()
+*/
+wxApp *wxTheApp;
+
+
 
 /** @ingroup group_funcmacro_rtti */
 //@{
@@ -648,20 +656,15 @@ public:
 
 
 
-
+/** @ingroup group_funcmacro_appinitterm */
-/**
+//@{
-    The global pointer to the singleton wxApp object.
-
-    @see wxApp::GetInstance()
-*/
-wxApp *wxTheApp;
 
 /**
     This function doesn't exist in wxWidgets but it is created by using
     the IMPLEMENT_APP() macro.
 
-    Thus, before using it anywhere but in the same module where this macro is used,
+    Thus, before using it anywhere but in the same module where this macro is
-    you must make it available using DECLARE_APP().
+    used, you must make it available using DECLARE_APP().
 
     The advantage of using this function compared to directly using the global
     wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
@@ -670,15 +673,6 @@ wxApp *wxTheApp;
 */
 wxAppDerivedClass wxGetApp();
 
-/**
-    Exits application after calling wxApp::OnExit.
-
-    Should only be used in an emergency: normally the top-level frame
-    should be deleted (after deleting all other frames) to terminate the
-    application. See wxCloseEvent and wxApp.
-*/
-void wxExit();
-
 /**
     If @a doIt is @true, the fatal exceptions (also known as general protection
     faults under Windows or segmentation violations in the Unix world) will be
@@ -696,32 +690,6 @@ void wxExit();
 */
 bool wxHandleFatalExceptions(bool doIt = true);
 
-/**
-    Returns the error code from the last system call. This function uses
-    @c errno on Unix platforms and @c GetLastError under Win32.
-
-    @see wxSysErrorMsg(), wxLogSysError()
-*/
-unsigned long wxSysErrorCode();
-
-/**
-    In a GUI application, this function posts @a event to the specified @e dest
-    object using wxEvtHandler::AddPendingEvent.
-
-    Otherwise, it dispatches @a event immediately using wxEvtHandler::ProcessEvent.
-    See the respective documentation for details (and caveats).
-*/
-void wxPostEvent(wxEvtHandler* dest, wxEvent& event);
-
-
-/**
-    Returns the error message corresponding to the given system error code. If
-    @a errCode is 0 (default), the last error code (as returned by
-    wxSysErrorCode()) is used.
-
-    @see wxSysErrorCode(), wxLogSysError()
-*/
-const wxChar* wxSysErrorMsg(unsigned long errCode = 0);
 
 /**
     This function is used in wxBase only and only if you don't create
@@ -752,17 +720,33 @@ void wxUninitialize();
 */
 bool wxYield();
 
-
-//@{
 /**
-    This initializes wxWidgets in a platform-dependent way. Use this if you are not
+    This function is similar to wxYield, except that it disables the user input to
-    using the default wxWidgets entry code (e.g. main or WinMain). For example, you
+    all program windows before calling wxYield and re-enables it again
-    can initialize wxWidgets from an Microsoft Foundation Classes application using
+    afterwards. If @a win is not @NULL, this window will remain enabled,
-    this function.
+    allowing the implementation of some limited user interaction.
+    Returns the result of the call to ::wxYield.
+*/
+bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false);
 
-    The following overload of wxEntry is available under all platforms:
+/**
-    (notice that under Windows CE platform, and only there, the type of @a pCmdLine
+    This function initializes wxWidgets in a platform-dependent way. Use this if you
-    is @c wchar_t *, otherwise it is @c char *, even in Unicode build).
+    are not using the default wxWidgets entry code (e.g. main or WinMain).
+
+    For example, you can initialize wxWidgets from an Microsoft Foundation Classes
+    (MFC) application using this function.
+
+    @note This overload of wxEntry is available under all platforms.
+
+    @see wxEntryStart()
+*/
+int wxEntry(int& argc, wxChar** argv);
+
+/**
+    See wxEntry(int&,wxChar**) for more info about this function.
+
+    Notice that under Windows CE platform, and only there, the type of @a pCmdLine
+    is @c wchar_t *, otherwise it is @c char *, even in Unicode build.
 
     @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static
              function wxApp::CleanUp. For example, if exiting from an MFC application
@@ -778,12 +762,27 @@ bool wxYield();
              }
              @endcode
 
-    @see wxEntryStart()
 */
-int wxEntry(int& argc, wxChar** argv);
 int wxEntry(HINSTANCE hInstance,
             HINSTANCE hPrevInstance = NULL,
             char* pCmdLine = NULL,
             int nCmdShow = SW_SHOWNORMAL);
+
+//@}
+
+
+
+/** @ingroup group_funcmacro_procctrl */
+//@{
+
+/**
+    Exits application after calling wxApp::OnExit.
+
+    Should only be used in an emergency: normally the top-level frame
+    should be deleted (after deleting all other frames) to terminate the
+    application. See wxCloseEvent and wxApp.
+*/
+void wxExit();
+
 //@}
 

interface/arrstr.h

@@ -10,27 +10,26 @@
     @class wxArrayString
     @wxheader{arrstr.h}
 
-    wxArrayString is an efficient container for storing
+    wxArrayString is an efficient container for storing wxString objects.
-    wxString objects. It has the same features as all
-    wxArray classes, i.e. it dynamically expands when new items
-    are added to it (so it is as easy to use as a linked list), but the access
-    time to the elements is constant, instead of being linear in number of
-    elements as in the case of linked lists. It is also very size efficient and
-    doesn't take more space than a C array @e wxString[] type (wxArrayString
-    uses its knowledge of internals of wxString class to achieve this).
 
-    This class is used in the same way as other dynamic arrays(),
+    It has the same features as all wxArray classes, i.e. it dynamically expands
-    except that no @e WX_DEFINE_ARRAY declaration is needed for it. When a
+    when new items are added to it (so it is as easy to use as a linked list),
-    string is added or inserted in the array, a copy of the string is created, so
+    but the access time to the elements is constant, instead of being linear in
-    the original string may be safely deleted (e.g. if it was a @e wxChar *
+    number of elements as in the case of linked lists. It is also very size
-    pointer the memory it was using can be freed immediately after this). In
+    efficient and doesn't take more space than a C array @e wxString[] type
-    general, there is no need to worry about string memory deallocation when using
+    (wxArrayString uses its knowledge of internals of wxString class to achieve this).
+
+    This class is used in the same way as other dynamic arrays(), except that no
+    @e WX_DEFINE_ARRAY declaration is needed for it.
+    When a string is added or inserted in the array, a copy of the string is created,
+    so the original string may be safely deleted (e.g. if it was a @e wxChar *
+    pointer the memory it was using can be freed immediately after this).
+    In general, there is no need to worry about string memory deallocation when using
     this class - it will always free the memory it uses itself.
 
-    The references returned by wxArrayString::Item,
+    The references returned by wxArrayString::Item, wxArrayString::Last or
-    wxArrayString::Last or
+    wxArrayString::operator[] are not constant, so the array elements may
-    @ref wxArrayString::operatorindex operator[] are not constant, so the
+    be modified in place like this:
-    array elements may be modified in place like this
 
     @code
     array.Last().MakeUpper();
@@ -39,37 +38,54 @@
     There is also a variant of wxArrayString called wxSortedArrayString which has
     exactly the same methods as wxArrayString, but which always keeps the string
     in it in (alphabetical) order. wxSortedArrayString uses binary search in its
-    wxArrayString::Index function (instead of linear search for
+    wxArrayString::Index() function (instead of linear search for wxArrayString::Index())
-    wxArrayString::Index) which makes it much more efficient if you add strings to
+    which makes it much more efficient if you add strings to the array rarely
-    the array rarely (because, of course, you have to pay for Index() efficiency
+    (because, of course, you have to pay for Index() efficiency by having Add() be
-    by having Add() be slower) but search for them often. Several methods should
+    slower) but search for them often. Several methods should not be used with
-    not be used with sorted array (basically, all which break the order of items)
+    sorted array (basically, all which break the order of items) which is
-    which is mentioned in their description.
+    mentioned in their description.
 
-    Final word: none of the methods of wxArrayString is virtual including its
+    @note none of the methods of wxArrayString is virtual including its
           destructor, so this class should not be used as a base class.
 
+    Although this is not true strictly speaking, this class may be considered as
+    a specialization of wxArray class for the wxString member data: it is not
+    implemented like this, but it does have all of the wxArray functions.
+
     @library{wxbase}
     @category{containers}
 
-    @see wxArray, wxString, @ref overview_wxstringoverview "wxString overview"
+    @see wxArray, wxString, @ref overview_string
 */
 class wxArrayString : public wxArray
 {
 public:
-    //@{
     /**
-        Constructor from a wxString array. Pass a size @a sz and array @e arr.
+        Default constructor.
     */
     wxArrayString();
+
+    /**
+        Copy constructor. Note that when an array is assigned to a sorted array,
+        its contents is automatically sorted during construction.
+    */
     wxArrayString(const wxArrayString& array);
+
+    //@{
+    /**
+        Constructor from a C string array. Pass a size sz and array arr.
+    **/
     wxArrayString(size_t sz, const char** arr);
     wxArrayString(size_t sz, const wchar_t** arr);
-    wxArrayString(size_t sz, const wxString* arr);
     //@}
 
     /**
-        Destructor frees memory occupied by the array strings. For the performance
+        Constructor from a wxString array. Pass a size @a sz and array @e arr.
+    */
+    wxArrayString(size_t sz, const wxString* arr);
+
+    /**
+        Destructor frees memory occupied by the array strings. For performance
         reasons it is not virtual, so this class should not be derived from.
     */
     ~wxArrayString();
@@ -77,11 +93,13 @@ public:
     /**
         Appends the given number of @a copies of the new item @a str to the
         array and returns the index of the first new item in the array.
-        @b Warning: For sorted arrays, the index of the inserted item will not be,
+
-        in general, equal to GetCount() - 1 because
+        @warning
-        the item is inserted at the correct position to keep the array sorted and not
+        For sorted arrays, the index of the inserted item will not be, in general,
-        appended.
+        equal to GetCount() - 1 because the item is inserted at the correct position
-        See also: Insert()
+        to keep the array sorted and not appended.
+
+        @see Insert()
     */
     size_t Add(const wxString& str, size_t copies = 1);
 
@@ -89,23 +107,25 @@ public:
         Preallocates enough memory to store @a nCount items. This function may be
         used to improve array class performance before adding a known number of items
         consecutively.
-        See also: @ref wxArray::memorymanagement "Dynamic array memory management"
+
+        @todo FIX THIS LINK
+
+        @see @ref wxArray::memorymanagement "Dynamic array memory management"
     */
     void Alloc(size_t nCount);
 
     /**
         Clears the array contents and frees memory.
-        See also: Empty()
+
+        @see Empty()
     */
     void Clear();
 
     /**
-        Empties the array: after a call to this function
+        Empties the array: after a call to this function GetCount() will return 0.
-        GetCount() will return 0. However, this
+        However, this function does not free the memory used by the array and so 
-        function does not free the memory used by the array and so should be used when
+        should be used when the array is going to be reused for storing other strings.
-        the array is going to be reused for storing other strings. Otherwise, you
+        Otherwise, you should use Clear() to empty the array and free memory.
-        should use Clear() to empty the array and free
-        memory.
     */
     void Empty();
 
@@ -115,12 +135,13 @@ public:
     size_t GetCount() const;
 
     /**
-        Search the element in the array, starting from the beginning if
+        Search the element in the array, starting from the beginning if @a bFromEnd
-        @a bFromEnd is @false or from end otherwise. If @e bCase, comparison is
+        is @false or from end otherwise. If @e bCase, comparison is case sensitive
-        case sensitive (default), otherwise the case is ignored.
+        (default), otherwise the case is ignored.
+
         This function uses linear search for wxArrayString and binary search for
-        wxSortedArrayString, but it ignores the @a bCase and @a bFromEnd
+        wxSortedArrayString, but it ignores the @a bCase and @a bFromEnd parameters
-        parameters in the latter case.
+        in the latter case.
         Returns index of the first item matched or @c wxNOT_FOUND if there is no match.
     */
     int Index(const wxString& sz, bool bCase = true,
@@ -128,14 +149,18 @@ public:
 
     /**
         Insert the given number of @a copies of the new element in the array before the
-        position @e nIndex. Thus, for
+        position @e nIndex. Thus, for example, to insert the string in the beginning of
-        example, to insert the string in the beginning of the array you would write
+        the array you would write:
 
-        If @a nIndex is equal to @e GetCount() this function behaves as
+        @code
-        Add().
+        Insert("foo", 0);
-        @b Warning: this function should not be used with sorted arrays because it
+        @endcode
-        could break the order of items and, for example, subsequent calls to
+        
-        Index() would then not work!
+        If @a nIndex is equal to @e GetCount() this function behaves as Add().
+
+        @warning this function should not be used with sorted arrays because it
+                 could break the order of items and, for example, subsequent calls
+                 to Index() would then not work!
     */
     void Insert(const wxString& str, size_t nIndex,
                 size_t copies = 1);
@@ -150,8 +175,8 @@ public:
         Return the array element at position @e nIndex. An assert failure will
         result from an attempt to access an element beyond the end of array in debug
         mode, but no check is done in release mode.
-        See also @ref operatorindex() operator[] for the operator
+
-        version.
+        @see operator[] for the operator version.
     */
     wxString Item(size_t nIndex) const;
 
@@ -165,7 +190,8 @@ public:
     /**
         Removes the first item matching this value. An assert failure is provoked by
         an attempt to remove an element which does not exist in debug build.
-        See also: Index()
+
+        @see Index()
     */
     void Remove(const wxString& sz);
 
@@ -177,23 +203,58 @@ public:
     /**
         Releases the extra memory allocated by the array. This function is useful to
         minimize the array memory consumption.
-        See also: Alloc(), @ref wxArray::memorymanagement "Dynamic array memory
+
+        @todo FIX THIS LINK
+
+        @see Alloc(), @ref wxArray::memorymanagement "Dynamic array memory
         management"
     */
     void Shrink();
 
-    //@{
+    /**
+        Sorts the array in alphabetical order or in reverse alphabetical order if
+        @a reverseOrder is @true. The sort is case-sensitive.
+
+        @warning this function should not be used with sorted array because it could
+                 break the order of items and, for example, subsequent calls to Index()
+                 would then not work!
+    */
+
+    void Sort(bool reverseOrder = false);
+
     /**
         Sorts the array using the specified @a compareFunction for item comparison.
-        @e CompareFunction is defined as a function taking two @e const
+        @e CompareFunction is defined as a function taking two @e const wxString
-        wxString parameters and returning an @e int value less than, equal to or
+        parameters and returning an @e int value less than, equal to or greater 
-        greater than 0 if the first string is less than, equal to or greater than the
+        than 0 if the first string is less than, equal to or greater than the
         second one.
+
+        Example:
+        The following example sorts strings by their length.
+
+        @code
+        static int CompareStringLen(const wxString& first, const wxString& second)
+        {
+            return first.length() - second.length();
+        }
+        
+        ...
+        
+        wxArrayString array;
+        
+        array.Add("one");
+        array.Add("two");
+        array.Add("three");
+        array.Add("four");
+        
+        array.Sort(CompareStringLen);
+        @endcode
+
+        @warning this function should not be used with sorted array because
+                 it could break the order of items and, for example, subsequent
+                 calls to Index() would then not work!
     */
-    void Sort(bool reverseOrder = false);
-Warning:
     void Sort(CompareFunction compareFunction);
-    //@}
 
     /**
         Compares 2 arrays respecting the case. Returns @true if the arrays have
@@ -214,9 +275,10 @@ Warning:
 
     /**
         Return the array element at position @e nIndex. An assert failure will
-        result from an attempt to access an element beyond the end of array in debug
+        result from an attempt to access an element beyond the end of array in
-        mode, but no check is done in release mode.
+        debug mode, but no check is done in release mode.
-        This is the operator version of Item() method.
+
+        This is the operator version of the Item() method.
     */
     wxString operator[](size_t nIndex);
 };
@@ -227,31 +289,35 @@ Warning:
 // Global functions/macros
 // ============================================================================
 
+/** @ingroup group_funcmacro_string */
+//@{
+
 /**
     Splits the given wxString object using the separator @a sep and returns the
     result as a wxArrayString.
+
     If the @a escape character is non-@NULL, then the occurrences of @a sep
-    immediately prefixed
+    immediately prefixed with @a escape are not considered as separators.
-    with @a escape are not considered as separators.
     Note that empty tokens will be generated if there are two or more adjacent
     separators.
 
     @see wxJoin()
 */
 wxArrayString wxSplit(const wxString& str, const wxChar sep,
-                      const wxChar escape = '
+                      const wxChar escape = '\\');
-                                            ');
 
 /**
-    Concatenate all lines of the given wxArrayString object using the separator @a
+    Concatenate all lines of the given wxArrayString object using the separator
-    sep and returns
+    @a sep and returns the result as a wxString.
-    the result as a wxString.
+
     If the @a escape character is non-@NULL, then it's used as prefix for each
-    occurrence of @e sep
+    occurrence of @e sep in the strings contained in @a arr before joining them
-    in the strings contained in @a arr before joining them which is necessary
+    which is necessary in order to be able to recover the original array contents
-    in order to be able to recover the original array contents from the string
+    from the string later using wxSplit().
-    later using wxSplit().
+
+    @see wxSplit()
 */
 wxString wxJoin(const wxArrayString& arr, const wxChar sep,
-                const wxChar escape = '\');
+                const wxChar escape = '\\');
 
+//@}

interface/artprov.h

@@ -11,15 +11,15 @@
     @wxheader{artprov.h}
 
     wxArtProvider class is used to customize the look of wxWidgets application.
+
     When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file
     dialog), it does not use a hard-coded resource but asks wxArtProvider for it
     instead. This way users can plug in their own wxArtProvider class and easily
-    replace standard art with their own version. All
+    replace standard art with their own version.
-    that is needed is to derive a class from wxArtProvider, override either its
+
-    wxArtProvider::CreateBitmap and/or its
+    All that is needed is to derive a class from wxArtProvider, override either its
-    wxArtProvider::CreateIconBundle methods
+    wxArtProvider::CreateBitmap and/or its wxArtProvider::CreateIconBundle methods
-    and register the provider with
+    and register the provider with wxArtProvider::Push:
-    wxArtProvider::Push:
 
     @code
       class MyProvider : public wxArtProvider
@@ -39,96 +39,120 @@
     @endcode
 
     If you need bitmap images (of the same artwork) that should be displayed at
-    different sizes
+    different sizes you should probably consider overriding wxArtProvider::CreateIconBundle
-    you should probably consider overriding wxArtProvider::CreateIconBundle
     and supplying icon bundles that contain different bitmap sizes.
 
     There's another way of taking advantage of this class: you can use it in your
-    code and use
+    code and use platform native icons as provided by wxArtProvider::GetBitmap or
-    platform native icons as provided by wxArtProvider::GetBitmap or
+    wxArtProvider::GetIcon.
-    wxArtProvider::GetIcon (NB: this is not yet really
-    possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too
-    small).
 
+    @todo IS THIS NB TRUE?
+    (NB: this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider
+     bitmaps is too small).
 
-    wxArtProvider::~wxArtProvider
+    @section wxartprovider_identify Identifying art resources
-    wxArtProvider::CreateBitmap
-    wxArtProvider::CreateIconBundle
-    wxArtProvider::Delete
-    wxArtProvider::GetBitmap
-    wxArtProvider::GetIconBundle
-    wxArtProvider::GetIcon
-    wxArtProvider::Insert
-    wxArtProvider::Pop
-    wxArtProvider::Push
-    wxArtProvider::Remove
-
-
-    Identifying art resources
 
     Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
-    is used when
+    is used when requesting a resource from it. The ID is represented by wxArtID type
-    requesting a resource from it. The ID is represented by wxArtID type and can
+    and can have one of these predefined values (you can see bitmaps represented by these
-    have one of these predefined values (you can see bitmaps represented by these
+    constants in the @ref page_utils_samples_artprovider):
-    constants in the artprov() sample):
-
-     wxART_ERROR
-     wxART_QUESTION
-     wxART_WARNING
-     wxART_INFORMATION
-     wxART_ADD_BOOKMARK
-     wxART_DEL_BOOKMARK
-     wxART_HELP_SIDE_PANEL
-     wxART_HELP_SETTINGS
-     wxART_HELP_BOOK
-     wxART_HELP_FOLDER
-     wxART_HELP_PAGE
-     wxART_GO_BACK
-     wxART_GO_FORWARD
-     wxART_GO_UP
-     wxART_GO_DOWN
-     wxART_GO_TO_PARENT
-     wxART_GO_HOME
-     wxART_PRINT
-     wxART_HELP
-     wxART_TIP
-     wxART_REPORT_VIEW
-     wxART_LIST_VIEW
-     wxART_NEW_DIR
-     wxART_FOLDER
-     wxART_FOLDER_OPEN
-     wxART_GO_DIR_UP
-     wxART_EXECUTABLE_FILE
-     wxART_NORMAL_FILE
-     wxART_TICK_MARK
-     wxART_CROSS_MARK
-     wxART_MISSING_IMAGE
-     wxART_NEW
-     wxART_FILE_OPEN
-     wxART_FILE_SAVE
-     wxART_FILE_SAVE_AS
-     wxART_DELETE
-     wxART_COPY
-     wxART_CUT
-     wxART_PASTE
-     wxART_UNDO
-     wxART_REDO
-     wxART_QUIT
-     wxART_FIND
-     wxART_FIND_AND_REPLACE
-     wxART_HARDDISK
-     wxART_FLOPPY
-     wxART_CDROM
-     wxART_REMOVABLE
 
+    <table>
+    <tr><td>
+     @li wxART_ERROR
+     @li wxART_QUESTION
+     @li wxART_WARNING
+     @li wxART_INFORMATION
+     @li wxART_ADD_BOOKMARK
+     @li wxART_DEL_BOOKMARK
+     @li wxART_HELP_SIDE_PANEL
+     @li wxART_HELP_SETTINGS
+     @li wxART_HELP_BOOK
+     @li wxART_HELP_FOLDER
+     @li wxART_HELP_PAGE
+     @li wxART_GO_BACK
+     @li wxART_GO_FORWARD
+     @li wxART_GO_UP
+    </td><td>
+     @li wxART_GO_DOWN
+     @li wxART_GO_TO_PARENT
+     @li wxART_GO_HOME
+     @li wxART_PRINT
+     @li wxART_HELP
+     @li wxART_TIP
+     @li wxART_REPORT_VIEW
+     @li wxART_LIST_VIEW
+     @li wxART_NEW_DIR
+     @li wxART_FOLDER
+     @li wxART_FOLDER_OPEN
+     @li wxART_GO_DIR_UP
+     @li wxART_EXECUTABLE_FILE
+     @li wxART_NORMAL_FILE
+     @li wxART_TICK_MARK
+     @li wxART_CROSS_MARK
+    </td><td>
+     @li wxART_MISSING_IMAGE
+     @li wxART_NEW
+     @li wxART_FILE_OPEN
+     @li wxART_FILE_SAVE
+     @li wxART_FILE_SAVE_AS
+     @li wxART_DELETE
+     @li wxART_COPY
+     @li wxART_CUT
+     @li wxART_PASTE
+     @li wxART_UNDO
+     @li wxART_REDO
+     @li wxART_QUIT
+     @li wxART_FIND
+     @li wxART_FIND_AND_REPLACE
+     @li wxART_HARDDISK
+     @li wxART_FLOPPY
+     @li wxART_CDROM
+     @li wxART_REMOVABLE
+    </td></tr>
+    </table>
 
     Additionally, any string recognized by custom art providers registered using
     wxArtProvider::Push may be used.
 
-    @library{wxcore}
+    @note
-    @category{FIXME}
+    When running under GTK+ 2, GTK+ stock item IDs (e.g. @c "gtk-cdrom") may be used
+    as well. Additionally, if wxGTK was compiled against GTK+ >= 2.4, then it is also
+    possible to load icons from current icon theme by specifying their name (without
+    extension and directory components).
+    Icon themes recognized by GTK+ follow the freedesktop.org Icon Themes specification
+    (see http://freedesktop.org/Standards/icon-theme-spec).
+    Note that themes are not guaranteed to contain all icons, so wxArtProvider may
+    return ::wxNullBitmap or ::wxNullIcon.
+    The default theme is typically installed in @c /usr/share/icons/hicolor.
 
-    @see See the artprov() sample for an example of wxArtProvider usage.
+
+    @section wxartprovider_clients Clients
+
+    Client is the entity that calls wxArtProvider's GetBitmap or GetIcon function.
+    It is represented by wxClientID type and can have one of these values:
+
+    @li wxART_TOOLBAR 
+    @li wxART_MENU 
+    @li wxART_BUTTON 
+    @li wxART_FRAME_ICON 
+    @li wxART_CMN_DIALOG 
+    @li wxART_HELP_BROWSER 
+    @li wxART_MESSAGE_BOX 
+    @li wxART_OTHER (used for all requests that don't fit into any of the 
+        categories above)
+
+    Client ID servers as a hint to wxArtProvider that is supposed to help it to
+    choose the best looking bitmap. For example it is often desirable to use
+    slightly different icons in menus and toolbars even though they represent
+    the same action (e.g. wxART_FILE_OPEN). Remember that this is really only a
+    hint for wxArtProvider -- it is common that wxArtProvider::GetBitmap returns
+    identical bitmap for different client values!
+
+    @library{wxcore}
+    @category{misc,data}
+
+    @see the @ref page_utils_samples_artprovider for an example of wxArtProvider usage.
 */
 class wxArtProvider : public wxObject
 {
@@ -139,31 +163,6 @@ public:
     */
     ~wxArtProvider();
 
-    /**
-        Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
-        function. It is represented by wxClientID type and can have one of these
-        values:
-         wxART_TOOLBAR
-         wxART_MENU
-         wxART_BUTTON
-         wxART_FRAME_ICON
-         wxART_CMN_DIALOG
-         wxART_HELP_BROWSER
-         wxART_MESSAGE_BOX
-         wxART_OTHER (used for all requests that don't fit into any of the categories
-        above)
-        Client ID servers as a hint to wxArtProvider that is supposed to help it to
-        choose the best looking bitmap. For example it is often desirable to use
-        slightly different icons in menus and toolbars even though they represent the
-        same action (e.g. @c wx_ART_FILE_OPEN). Remember that this is really
-        only a hint for wxArtProvider -- it is common that
-        GetBitmap()
-        returns identical bitmap for different @e client values!
-        
-        @see See the artprov() sample for an example of wxArtProvider usage.
-    */
-
-
     /**
         Derived art provider classes must override this method to create requested art
         resource. Note that returned bitmaps are cached by wxArtProvider and it is
@@ -179,6 +178,11 @@ public:
             Preferred size of the bitmap. The function may return a bitmap of different
             dimensions, it will be automatically rescaled to meet client's request.
 
+        @note
+        This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap
+        or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider
+        for a resource.
+        
         @see CreateIconBundle()
     */
     wxBitmap CreateBitmap(const wxArtID& id,
@@ -186,8 +190,8 @@ public:
                           const wxSize& size);
 
     /**
-        This method is similar to CreateBitmap() but
+        This method is similar to CreateBitmap() but can be used when a bitmap
-        can be used when a bitmap (or an icon) exists in several sizes.
+        (or an icon) exists in several sizes.
     */
     wxIconBundle CreateIconBundle(const wxArtID& id,
                                   const wxArtClient& client);
@@ -214,21 +218,23 @@ public:
                               const wxArtClient& client = wxART_OTHER,
                               const wxSize& size = wxDefaultSize);
 
-    //@{
     /**
-        Returns a suitable size hint for the given @e wxArtClient. If
+        Same as wxArtProvider::GetBitmap, but return a wxIcon object
-        @a platform_default is @true, return a size based on the current platform,
+        (or ::wxNullIcon on failure).
-        otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may
-        be
-        returned if the client doesn't have a specified size, like wxART_OTHER for
-        example.
     */
     static wxIcon GetIcon(const wxArtID& id,
                           const wxArtClient& client = wxART_OTHER,
                           const wxSize& size = wxDefaultSize);
+
+    /**
+        Returns a suitable size hint for the given @e wxArtClient. If
+        @a platform_default is @true, return a size based on the current platform,
+        otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may
+        be returned if the client doesn't have a specified size, like wxART_OTHER for
+        example.
+    */
     static wxSize GetSizeHint(const wxArtClient& client,
                               bool platform_default = false);
-    //@}
 
     /**
         Query registered providers for icon bundle with given ID.
@@ -246,68 +252,8 @@ public:
                                       const wxArtClient& client = wxART_OTHER);
 
     /**
-        Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
+        Register new art provider and add it to the bottom of providers stack
-        is used when
+        (i.e. it will be queried as the last one).
-        requesting a resource from it. The ID is represented by wxArtID type and can
-        have one of these predefined values (you can see bitmaps represented by these
-        constants in the artprov() sample):
-        
-         wxART_ERROR
-         wxART_QUESTION
-         wxART_WARNING
-         wxART_INFORMATION
-         wxART_ADD_BOOKMARK
-         wxART_DEL_BOOKMARK
-         wxART_HELP_SIDE_PANEL
-         wxART_HELP_SETTINGS
-         wxART_HELP_BOOK
-         wxART_HELP_FOLDER
-         wxART_HELP_PAGE
-         wxART_GO_BACK
-         wxART_GO_FORWARD
-         wxART_GO_UP
-         wxART_GO_DOWN
-         wxART_GO_TO_PARENT
-         wxART_GO_HOME
-         wxART_PRINT
-         wxART_HELP
-         wxART_TIP
-         wxART_REPORT_VIEW
-         wxART_LIST_VIEW
-         wxART_NEW_DIR
-         wxART_FOLDER
-         wxART_FOLDER_OPEN
-         wxART_GO_DIR_UP
-         wxART_EXECUTABLE_FILE
-         wxART_NORMAL_FILE
-         wxART_TICK_MARK
-         wxART_CROSS_MARK
-         wxART_MISSING_IMAGE
-         wxART_NEW
-         wxART_FILE_OPEN
-         wxART_FILE_SAVE
-         wxART_FILE_SAVE_AS
-         wxART_DELETE
-         wxART_COPY
-         wxART_CUT
-         wxART_PASTE
-         wxART_UNDO
-         wxART_REDO
-         wxART_QUIT
-         wxART_FIND
-         wxART_FIND_AND_REPLACE
-         wxART_HARDDISK
-         wxART_FLOPPY
-         wxART_CDROM
-         wxART_REMOVABLE
-        Additionally, any string recognized by custom art providers registered using
-        Push() may be used.
-    */
-
-
-    /**
-        Register new art provider and add it to the bottom of providers stack (i.e.
-        it will be queried as the last one).
         
         @see Push()
     */
@@ -319,8 +265,8 @@ public:
     static bool Pop();
 
     /**
-        Register new art provider and add it to the top of providers stack (i.e. it
+        Register new art provider and add it to the top of providers stack
-        will be queried as the first provider).
+        (i.e. it will be queried as the first provider).
         
         @see Insert()
     */

interface/atomic.h

@@ -6,9 +6,24 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @ingroup group_funcmacro_atomic */
+//@{
+
 /**
     This function increments @a value in an atomic manner.
 */
 void wxAtomicInc(wxAtomicInt& value);
 
+/**
+    This function decrements value in an atomic manner.
+    Returns 0 if value is 0 after decrementation or any non-zero value
+    (not necessarily equal to the value of the variable) otherwise.
+*/
+wxInt32 wxAtomicDec(wxAtomicInt& value);
 
+//@}

interface/event.h

@@ -2766,3 +2766,13 @@ public:
     void SetCursor(const wxCursor& cursor);
 };
 
+
+
+/**
+    In a GUI application, this function posts @a event to the specified @e dest
+    object using wxEvtHandler::AddPendingEvent.
+
+    Otherwise, it dispatches @a event immediately using wxEvtHandler::ProcessEvent.
+    See the respective documentation for details (and caveats).
+*/
+void wxPostEvent(wxEvtHandler* dest, wxEvent& event);

interface/log.h

@@ -924,3 +924,24 @@ void wxLogSysError(const char* formatString, ... );
 void wxVLogSysError(const char* formatString,
                     va_list argPtr);
 //@}
+
+
+/**
+    Returns the error code from the last system call. This function uses
+    @c errno on Unix platforms and @c GetLastError under Win32.
+
+    @see wxSysErrorMsg(), wxLogSysError()
+*/
+unsigned long wxSysErrorCode();
+
+
+/**
+    Returns the error message corresponding to the given system error code. If
+    @a errCode is 0 (default), the last error code (as returned by
+    wxSysErrorCode()) is used.
+
+    @see wxSysErrorCode(), wxLogSysError()
+*/
+const wxChar* wxSysErrorMsg(unsigned long errCode = 0);
+
+

interface/utils.h

@@ -341,14 +341,6 @@ void wxInfoMessageBox(wxWindow ( parent = NULL);
 wxWindow* wxFindWindowByLabel(const wxString& label,
                                 wxWindow* parent = NULL);
 
-                      /**
-                          This function is similar to wxYield, except that it disables the user input to
-                          all program windows before calling wxYield and re-enables it again
-                          afterwards. If @a win is not @NULL, this window will remain enabled,
-                          allowing the implementation of some limited user interaction.
-                          Returns the result of the call to ::wxYield.
-                      */
-                      bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false);
 
 /**
     Returns the mouse position in screen coordinates.