Finished review/fixes of Math and Miscellaneous categories of functions and macros.

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

diff --git a/docs/doxygen/groups/funcmacro_math.h b/docs/doxygen/groups/funcmacro_math.h
index 30093d63145841cbc7db0eabc89b0e271e4e339f..ee726b83c6bf25d1ff600ba29822e21d6acc2598 100644 (file)
--- a/docs/doxygen/groups/funcmacro_math.h
+++ b/docs/doxygen/groups/funcmacro_math.h
@@ -11,7 +11,5 @@
 @defgroup group_funcmacro_math Math
 @ingroup group_funcmacro
 
 @defgroup group_funcmacro_math Math
 @ingroup group_funcmacro
 

-@header{wx/math.h}
-

 */
 
 */
 

diff --git a/interface/base64.h b/interface/base64.h
index 9276bb20f1745745a4ae6cec05811b24f696766f..2162513bf47cd4a554e09559740831f185695e61 100644 (file)
--- a/interface/base64.h
+++ b/interface/base64.h
@@ -17,9 +17,9 @@
 /**
     This function encodes the given data using base64.
 
 /**
     This function encodes the given data using base64.
 

-    To allocate the buffer of the correct size, use wxBase64EncodedSize() or call
-    this function with @a dst set to @NULL -- it will then return the necessary
-    buffer size.
+    To allocate the buffer of the correct size, use wxBase64EncodedSize() or
+    call this function with @a dst set to @NULL -- it will then return the
+    necessary buffer size.

 
     This raw encoding function overload writes the output string into the
     provided buffer; the other overloads return it as a wxString.
 
     This raw encoding function overload writes the output string into the
     provided buffer; the other overloads return it as a wxString.


@@ -34,33 +34,39 @@
         The length of the input data.
 
     @returns @c wxCONV_FAILED if the output buffer is too small.
         The length of the input data.
 
     @returns @c wxCONV_FAILED if the output buffer is too small.

+
+    @header{wx/base64.h}

 */
 size_t wxBase64Encode(char* dst, size_t dstLen,
                       const void* src,
                       size_t srcLen);
 
 /**
 */
 size_t wxBase64Encode(char* dst, size_t dstLen,
                       const void* src,
                       size_t srcLen);
 
 /**

-    This function encodes the given data using base64 and returns the output
-    as a wxString.
+    This function encodes the given data using base64 and returns the output as
+    a wxString.

 
     There is no error return.
 
 
     There is no error return.
 

-    To allocate the buffer of the correct size, use wxBase64EncodedSize() or call
-    this function with @a dst set to @NULL -- it will then return the necessary
-    buffer size.
+    To allocate the buffer of the correct size, use wxBase64EncodedSize() or
+    call this function with @a dst set to @NULL -- it will then return the
+    necessary buffer size.

 
     @param src
         The input buffer, must not be @NULL.
     @param srcLen
         The length of the input data.
 
     @param src
         The input buffer, must not be @NULL.
     @param srcLen
         The length of the input data.

+
+    @header{wx/base64.h}

 */
 wxString wxBase64Encode(const void* src, size_t srcLen);
 
 /**
 */
 wxString wxBase64Encode(const void* src, size_t srcLen);
 
 /**

-    This function encodes the given data using base64 and returns the output
-    as a wxString.
+    This function encodes the given data using base64 and returns the output as
+    a wxString.

 
     There is no error return.
 
     There is no error return.

+
+    @header{wx/base64.h}

 */
 wxString wxBase64Encode(const wxMemoryBuffer& buf);
 
 */
 wxString wxBase64Encode(const wxMemoryBuffer& buf);
 


@@ -69,6 +75,8 @@ wxString wxBase64Encode(const wxMemoryBuffer& buf);
     Returns the size of the buffer necessary to contain the data encoded in a
     base64 string of length @e srcLen. This can be useful for allocating a
     buffer to be passed to wxBase64Decode().
     Returns the size of the buffer necessary to contain the data encoded in a
     base64 string of length @e srcLen. This can be useful for allocating a
     buffer to be passed to wxBase64Decode().

+
+    @header{wx/base64.h}

 */
 size_t wxBase64DecodedSize(size_t srcLen);
 
 */
 size_t wxBase64DecodedSize(size_t srcLen);
 


@@ -76,32 +84,36 @@ size_t wxBase64DecodedSize(size_t srcLen);
     Returns the length of the string with base64 representation of a buffer of
     specified size @e len. This can be useful for allocating the buffer passed
     to wxBase64Encode().
     Returns the length of the string with base64 representation of a buffer of
     specified size @e len. This can be useful for allocating the buffer passed
     to wxBase64Encode().

+
+    @header{wx/base64.h}

 */
 size_t wxBase64EncodedSize(size_t len);
 
 /**
     This function decodes a Base64-encoded string.
 
 */
 size_t wxBase64EncodedSize(size_t len);
 
 /**
     This function decodes a Base64-encoded string.
 

-    This overload is a raw decoding function and decodes the data into the provided
-    buffer @a dst of the given size @e dstLen. An error is returned if the buffer
-    is not large enough -- that is not at least wxBase64DecodedSize(srcLen)() bytes.
+    This overload is a raw decoding function and decodes the data into the
+    provided buffer @a dst of the given size @e dstLen. An error is returned if
+    the buffer is not large enough -- that is not at least
+    wxBase64DecodedSize(srcLen) bytes.

 
     This overload returns the number of bytes written to the buffer or the
 
     This overload returns the number of bytes written to the buffer or the

-    necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on
-    error, e.g. if the output buffer is too small or invalid characters were
+    necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on error,
+    e.g. if the output buffer is too small or invalid characters were

     encountered in the input string.
 
     @param dst
     encountered in the input string.
 
     @param dst

-        Pointer to output buffer, may be @NULL to just compute the
-        necessary buffer size.
+        Pointer to output buffer, may be @NULL to just compute the necessary
+        buffer size.

     @param dstLen
         The size of the output buffer, ignored if dst is @NULL.
     @param src
     @param dstLen
         The size of the output buffer, ignored if dst is @NULL.
     @param src

-        The input string, must not be @NULL. For the version using
-        wxString, the input string should contain only ASCII characters.
+        The input string, must not be @NULL. For the version using wxString,
+        the input string should contain only ASCII characters.

     @param srcLen
     @param srcLen

-        The length of the input string or special value wxNO_LEN if the string is
-        NUL-terminated and the length should be computed by this function itself.
+        The length of the input string or special value wxNO_LEN if the string
+        is @NULL-terminated and the length should be computed by this function
+        itself.

     @param mode
         This parameter specifies the function behaviour when invalid characters
         are encountered in input. By default, any such character stops the
     @param mode
         This parameter specifies the function behaviour when invalid characters
         are encountered in input. By default, any such character stops the


@@ -109,8 +121,10 @@ size_t wxBase64EncodedSize(size_t len);
         white space characters are silently skipped instead. And if it is
         wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
     @param posErr
         white space characters are silently skipped instead. And if it is
         wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
     @param posErr

-        If this pointer is non-@NULL and an error occurs during
-        decoding, it is filled with the index of the invalid character.
+        If this pointer is non-@NULL and an error occurs during decoding, it is
+        filled with the index of the invalid character.
+
+    @header{wx/base64.h}

 */
 size_t wxBase64Decode(void* dst, size_t dstLen,
                       const char* src,
 */
 size_t wxBase64Decode(void* dst, size_t dstLen,
                       const char* src,


@@ -127,6 +141,8 @@ size_t wxBase64Decode(void* dst, size_t dstLen,
 
     This overload returns a buffer with the base64 decoded binary equivalent
     of the input string. In neither case is the buffer @NULL-terminated.
 
     This overload returns a buffer with the base64 decoded binary equivalent
     of the input string. In neither case is the buffer @NULL-terminated.

+
+    @header{wx/base64.h}

 */
 wxMemoryBuffer wxBase64Decode(const char* src,
                               size_t srcLen = wxNO_LEN,
 */
 wxMemoryBuffer wxBase64Decode(const char* src,
                               size_t srcLen = wxNO_LEN,


@@ -139,6 +155,8 @@ wxMemoryBuffer wxBase64Decode(const char* src,
 
     This overload takes as input a wxString and returns the internally-allocated
     memory as a wxMemoryBuffer, containing the base64 decoded data.
 
     This overload takes as input a wxString and returns the internally-allocated
     memory as a wxMemoryBuffer, containing the base64 decoded data.

+
+    @header{wx/base64.h}

 */
 wxMemoryBuffer wxBase64Decode(const wxString& src,
                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
 */
 wxMemoryBuffer wxBase64Decode(const wxString& src,
                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,

diff --git a/interface/colour.h b/interface/colour.h
index 238217afd511f3b68d6b6b1011379d3c5c9429df..e7ffbb84b94fc047ae44609a3fb1c3f090df7031 100644 (file)
--- a/interface/colour.h
+++ b/interface/colour.h
@@ -10,11 +10,10 @@
     @class wxColour
     @wxheader{colour.h}
 
     @class wxColour
     @wxheader{colour.h}
 

-    A colour is an object representing a combination of Red, Green, and Blue (RGB)
-    intensity values,
-    and is used to determine drawing colours. See the
-    entry for wxColourDatabase for how a pointer to a predefined,
-    named colour may be returned instead of creating a new colour.
+    A colour is an object representing a combination of Red, Green, and Blue
+    (RGB) intensity values, and is used to determine drawing colours. See the
+    entry for wxColourDatabase for how a pointer to a predefined, named colour
+    may be returned instead of creating a new colour.

 
     Valid RGB values are in the range 0 to 255.
 
 
     Valid RGB values are in the range 0 to 255.
 


@@ -24,18 +23,21 @@
     @category{gdi}
 
     @stdobjects
     @category{gdi}
 
     @stdobjects

-    ::Objects:, ::wxNullColour, ::Pointers:, ::wxBLACK, ::wxWHITE, ::wxRED,
-    ::wxBLUE, ::wxGREEN, ::wxCYAN, ::wxLIGHT_GREY,
+    ::wxNullColour, ::wxBLACK, ::wxWHITE, ::wxRED, ::wxBLUE, ::wxGREEN,
+    ::wxCYAN, ::wxLIGHT_GREY

 
     @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings
 */
 class wxColour : public wxObject
 {
 public:
 
     @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings
 */
 class wxColour : public wxObject
 {
 public:

-    //@{
+

     /**
     /**

-        Copy constructor.
+        Default constructor.
+    */
+    wxColour();

 
 

+    /**

         @param red
             The red value.
         @param green
         @param red
             The red value.
         @param green


@@ -43,22 +45,22 @@ public:
         @param blue
             The blue value.
         @param alpha
         @param blue
             The blue value.
         @param alpha

-            The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to 255
-        (wxALPHA_OPAQUE).
+            The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to
+            255 (wxALPHA_OPAQUE).
+    */
+    wxColour(unsigned char red, unsigned char green, unsigned char blue,
+             unsigned char alpha = wxALPHA_OPAQUE);
+
+    /**

         @param colourName
             The colour name.
         @param colourName
             The colour name.

-        @param colour
-            The colour to copy.
+    */
+    wxColour(const wxString& colourName);

 
 

-        @see wxColourDatabase
+    /**
+        Copy constructor.

     */
     */

-    wxColour();
-    wxColour(unsigned char red, unsigned char green,
-             unsigned char blue,
-             unsigned char alpha = wxALPHA_OPAQUE);
-    wxColour(const wxString& colourNname);

     wxColour(const wxColour& colour);
     wxColour(const wxColour& colour);

-    //@}

 
     /**
         Returns the alpha value, on platforms where alpha is not yet supported, this
 
     /**
         Returns the alpha value, on platforms where alpha is not yet supported, this


@@ -71,24 +73,24 @@ public:
     */
     unsigned char Blue() const;
 
     */
     unsigned char Blue() const;
 

-    //@{

     /**
     /**

-        is not
+        Converts this colour to a wxString using the given flags.
+
+        The supported flags are wxC2S_NAME, to obtain the colour name (e.g.
+        wxColour(255,0,0) == "red"), wxC2S_CSS_SYNTAX, to obtain the colour in
+        the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax (e.g.
+        wxColour(255,0,0,85) == "rgba(255,0,0,0.333)"), and wxC2S_HTML_SYNTAX,
+        to obtain the colour as "#" followed by 6 hexadecimal digits (e.g.
+        wxColour(255,0,0) == "#FF0000").
+
+        This function never fails and always returns a non-empty string but
+        asserts if the colour has alpha channel (i.e. is non opaque) but
+        wxC2S_CSS_SYNTAX (which is the only one supporting alpha) is not

         specified in flags.
 
         @wxsince{2.7.0}
     */
     wxString GetAsString(long flags);
         specified in flags.
 
         @wxsince{2.7.0}
     */
     wxString GetAsString(long flags);

-    const wxC2S_NAME, to obtain the colour name (e.g.
-            wxColour(255,0,0) - "red"), wxC2S_CSS_SYNTAX, to obtain
-    the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax
-    (e.g. wxColour(255,0,0,85) - "rgba(255,0,0,0.333)"), and
-    wxC2S_HTML_SYNTAX, to obtain the colour as  "#" followed
-    by 6 hexadecimal digits (e.g. wxColour(255,0,0) - "#FF0000").
-    This function never fails and always returns a non-empty string but asserts if
-    the colour has alpha channel (i.e. is non opaque) but
-        wxC2S_CSS_SYNTAX();
-    //@}

 
     /**
         Returns a pixel value which is platform-dependent. On Windows, a COLORREF is
 
     /**
         Returns a pixel value which is platform-dependent. On Windows, a COLORREF is


@@ -117,12 +119,15 @@ public:
     //@{
     /**
         Sets the RGB intensity values using the given values (first overload),
     //@{
     /**
         Sets the RGB intensity values using the given values (first overload),

-        extracting them from the packed long (second overload), using the given string (third overloard).
+        extracting them from the packed long (second overload), using the given
+        string (third overloard).
+

         When using third form, Set() accepts: colour names (those listed in
         When using third form, Set() accepts: colour names (those listed in

-        wxTheColourDatabase()), the CSS-like
-        @c "rgb(r,g,b)" or @c "rgba(r,g,b,a)" syntax (case insensitive)
-        and the HTML-like syntax (i.e. @c "#" followed by 6 hexadecimal digits
-        for red, green, blue components).
+        wxTheColourDatabase()), the CSS-like @c "rgb(r,g,b)" or
+        @c "rgba(r,g,b,a)" syntax (case insensitive) and the HTML-like syntax
+        (i.e. @c "#" followed by 6 hexadecimal digits for red, green, blue
+        components).
+

         Returns @true if the conversion was successful, @false otherwise.
 
         @wxsince{2.7.0}
         Returns @true if the conversion was successful, @false otherwise.
 
         @wxsince{2.7.0}


@@ -158,23 +163,11 @@ public:
 };
 
 
 };
 
 

-/**
-    FIXME
-*/
-wxColour Objects:
-;
-

 /**
     FIXME
 */
 wxColour wxNullColour;
 
 /**
     FIXME
 */
 wxColour wxNullColour;
 

-/**
-    FIXME
-*/
-wxColour Pointers:
-;
-

 /**
     FIXME
 */
 /**
     FIXME
 */


@@ -211,3 +204,32 @@ wxColour wxCYAN;
 wxColour wxLIGHT_GREY;
 
 
 wxColour wxLIGHT_GREY;
 
 

+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @ingroup group_funcmacro_misc */
+//@{
+
+/**
+    Converts string to a wxColour best represented by the given string. Returns
+    @true on success.
+
+    @see wxToString(const wxColour&)
+
+    @header{wx/colour.h}
+*/
+bool wxFromString(const wxString& string, wxColour* colour);
+
+/**
+    Converts the given wxColour into a string.
+
+    @see wxFromString(const wxString&, wxColour*)
+
+    @header{wx/colour.h}
+*/
+wxString wxToString(const wxColour& colour);
+
+//@}
+

diff --git a/interface/cpp.h b/interface/cpp.h
index f1763222026528de01ac40c9aa77855ae7100d86..b8585c519c1bf6f028768919648915b65ebab5ec 100644 (file)
--- a/interface/cpp.h
+++ b/interface/cpp.h
@@ -6,34 +6,47 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+
+/** @ingroup group_funcmacro_misc */

 //@{
 /**
 //@{
 /**

-    These macro return the concatenation of the tokens passed as their arguments.
-    Unlike when using the preprocessor @c  operator, the arguments undergo
-    the macro expansion before being concatenated.
+    This macro returns the concatenation of the arguments passed. Unlike when
+    using the preprocessor operator, the arguments undergo macro expansion
+    before being concatenated.
+
+    @header{wx/cpp.h}

 */
 */

-wxCONCAT(x1, x2);
-wxCONCAT3(x1, x2, x3);
-wxCONCAT4(x1, x2, x3, x4);
-wxCONCAT5(x1, x2, x3, x4, x5);
+#define wxCONCAT(x1, x2)
+#define wxCONCAT3(x1, x2, x3)
+#define wxCONCAT4(x1, x2, x3, x4)
+#define wxCONCAT5(x1, x2, x3, x4, x5)

 //@}
 
 //@}
 

+/** @ingroup group_funcmacro_misc */
+//@{

 
 /**
 
 /**

-Returns the string representation of the given symbol which can be either a
-literal or a macro (hence the advantage of using this macro instead of the
-standard preprocessor @c # operator which doesn't work with macros).
-Notice that this macro always produces a @c char string, use
-wxSTRINGIZE_T() to build a wide string Unicode build.
+    Returns the string representation of the given symbol which can be either a
+    literal or a macro (hence the advantage of using this macro instead of the
+    standard preprocessor @c # operator which doesn't work with macros).
+
+    Notice that this macro always produces a @c char string, use
+    wxSTRINGIZE_T() to build a wide string Unicode build.

 
 

-@see wxCONCAT()
+    @see wxCONCAT()
+
+    @header{wx/cpp.h}

 */
 */

-#define wxSTRINGIZE(x)     /* implementation is private */
+#define wxSTRINGIZE(x)

 
 /**
     Returns the string representation of the given symbol as either an ASCII or
 
 /**
     Returns the string representation of the given symbol as either an ASCII or

-    Unicode string, depending on the current build. This is the Unicode-friendly
-    equivalent of wxSTRINGIZE().
+    Unicode string, depending on the current build. This is the
+    Unicode-friendly equivalent of wxSTRINGIZE().
+
+    @header{wx/cpp.h}

 */
 */

-#define wxSTRINGIZE_T(x)     /* implementation is private */
+#define wxSTRINGIZE_T(x)
+
+//@}

 
 

diff --git a/interface/dde.h b/interface/dde.h
index 67efd416098480a6ced8af89bb0b080aab969f37..520508906bab17a92a8aeca6652d00e1692afb23 100644 (file)
--- a/interface/dde.h
+++ b/interface/dde.h
@@ -314,20 +314,30 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

+/** @ingroup group_funcmacro_misc */
+//@{
+

 /**
 /**

-    Called when wxWidgets exits, to clean up the DDE system. This no longer needs
-    to be
-    called by the application.
-    See also wxDDEInitialize().
+    Called when wxWidgets exits, to clean up the DDE system. This no longer
+    needs to be called by the application.
+
+    @see wxDDEInitialize()
+
+    @header{wx/dde.h}

 */
 void wxDDECleanUp();
 
 /**
     Initializes the DDE system. May be called multiple times without harm.
 */
 void wxDDECleanUp();
 
 /**
     Initializes the DDE system. May be called multiple times without harm.

-    This no longer needs to be called by the application: it will be called
-    by wxWidgets if necessary.
-    See also wxDDEServer, wxDDEClient, wxDDEConnection,
-    wxDDECleanUp().
+
+    This no longer needs to be called by the application: it will be called by
+    wxWidgets if necessary.
+
+    @see wxDDEServer, wxDDEClient, wxDDEConnection, wxDDECleanUp()
+
+    @header{wx/dde.h}

 */
 void wxDDEInitialize();
 
 */
 void wxDDEInitialize();
 

+//@}
+

diff --git a/interface/debug.h b/interface/debug.h
index 8668d880aa9ec00d1d700a426a63066290efd942..6338b9147902b1adfc9995994f0102f1df8729c9 100644 (file)
--- a/interface/debug.h
+++ b/interface/debug.h
@@ -202,3 +202,19 @@ void wxTrap();
 
 //@}
 
 
 //@}
 

+
+
+/** @ingroup group_funcmacro_misc */
+//@{
+
+/**
+    This macro expands to the name of the current function if the compiler
+    supports any of @c __FUNCTION__, @c __func__ or equivalent variables or
+    macros or to @NULL if none of them is available.
+
+    @header{wx/debug.h}
+*/
+#define __WXFUNCTION__
+
+//@}
+

diff --git a/interface/defs.h b/interface/defs.h
index 9aaed38e01085963c20a6c8e4a88843390d4a99b..8064aab26f7e968b96414996141a096000e4a93a 100644 (file)
--- a/interface/defs.h
+++ b/interface/defs.h
@@ -67,98 +67,121 @@
 
 
 
 
 
 

+/** @ingroup group_funcmacro_misc */
+//@{

 
 /**
 
 /**

-    This macro is similar to wxDEPRECATED() but can be used
-    to not only declare the function @a func as deprecated but to also provide
-    its (inline) implementation @e body.
+    This macro can be used around a function declaration to generate warnings
+    indicating that this function is deprecated (i.e. obsolete and planned to
+    be removed in the future) when it is used. Only Visual C++ 7 and higher and
+    g++ compilers currently support this functionality.
+
+    Example of use:
+
+    @code
+    // old function, use wxString version instead
+    wxDEPRECATED( void wxGetSomething(char *buf, size_t len) );
+
+    // ...
+    wxString wxGetSomething();
+    @endcode
+
+    @header{wx/defs.h}
+*/
+#define wxDEPRECATED(function)
+
+/**
+    This is a special version of wxDEPRECATED() macro which only does something
+    when the deprecated function is used from the code outside wxWidgets itself
+    but doesn't generate warnings when it is used from wxWidgets.
+
+    It is used with the virtual functions which are called by the library
+    itself -- even if such function is deprecated the library still has to call
+    it to ensure that the existing code overriding it continues to work, but
+    the use of this macro ensures that a deprecation warning will be generated
+    if this function is used from the user code or, in case of Visual C++, even
+    when it is simply overridden.
+
+    @header{wx/defs.h}
+*/
+#define wxDEPRECATED_BUT_USED_INTERNALLY(function)
+
+/**
+    This macro is similar to wxDEPRECATED() but can be used to not only declare
+    the function @a function as deprecated but to also provide its (inline)
+    implementation @a body.
+

     It can be used as following:
 
     @code
     class wxFoo
     It can be used as following:
 
     @code
     class wxFoo

-        {
-        public:
-            // OldMethod() is deprecated, use NewMethod() instead
-            void NewMethod();
-            wxDEPRECATED_INLINE( void OldMethod(), NewMethod() );
-        };
+    {
+    public:
+        // OldMethod() is deprecated, use NewMethod() instead
+        void NewMethod();
+        wxDEPRECATED_INLINE( void OldMethod(), NewMethod() );
+    };

     @endcode
     @endcode

+
+    @header{wx/defs.h}

 */
 */

-#define wxDEPRECATED_INLINE(func, body)     /* implementation is private */
+#define wxDEPRECATED_INLINE(func, body)

 
 /**
     @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if
 
 /**
     @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if

-    the compiler supports it or nothing otherwise. Thus, it can be used even in the
-    code which might have to be compiled with an old compiler without support for
-    this language feature but still take advantage of it when it is available.
-*/
+    the compiler supports it or nothing otherwise. Thus, it can be used even in
+    the code which might have to be compiled with an old compiler without
+    support for this language feature but still take advantage of it when it is
+    available.

 
 

+    @header{wx/defs.h}
+*/
+#define wxEXPLICIT

 
 /**
     GNU C++ compiler gives a warning for any class whose destructor is private
     unless it has a friend. This warning may sometimes be useful but it doesn't
 
 /**
     GNU C++ compiler gives a warning for any class whose destructor is private
     unless it has a friend. This warning may sometimes be useful but it doesn't

-    make sense for reference counted class which always delete themselves (hence
-    destructor should be private) but don't necessarily have any friends, so this
-    macro is provided to disable the warning in such case. The @a name parameter
-    should be the name of the class but is only used to construct a unique friend
-    class name internally. Example of using the macro:
+    make sense for reference counted class which always delete themselves
+    (hence destructor should be private) but don't necessarily have any
+    friends, so this macro is provided to disable the warning in such case. The
+    @a name parameter should be the name of the class but is only used to
+    construct a unique friend class name internally.
+
+    Example of using the macro:

 
     @code
     class RefCounted
 
     @code
     class RefCounted

-        {
-        public:
-            RefCounted() { m_nRef = 1; }
-            void IncRef() { m_nRef++ ; }
-            void DecRef() { if ( !--m_nRef ) delete this; }
+    {
+    public:
+        RefCounted() { m_nRef = 1; }
+        void IncRef() { m_nRef++ ; }
+        void DecRef() { if ( !--m_nRef ) delete this; }

 
 

-        private:
-            ~RefCounted() { }
+    private:
+        ~RefCounted() { }

 
 

-            wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted)
-        };
+        wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted)
+    };

     @endcode
 
     Notice that there should be no semicolon after this macro.
     @endcode
 
     Notice that there should be no semicolon after this macro.

-*/
-#define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name)     /* implementation is private */
-
-/**
-    This macro can be used around a function declaration to generate warnings
-    indicating that this function is deprecated (i.e. obsolete and planned to be
-    removed in the future) when it is used. Only Visual C++ 7 and higher and g++
-    compilers currently support this functionality.
-    Example of use:
-
-    @code
-    // old function, use wxString version instead
-        wxDEPRECATED( void wxGetSomething(char *buf, size_t len) );

 
 

-        // ...
-        wxString wxGetSomething();
-    @endcode
+    @header{wx/defs.h}

 */
 */

-
+#define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name)

 
 /**
     This macro is the same as the standard C99 @c va_copy for the compilers
 
 /**
     This macro is the same as the standard C99 @c va_copy for the compilers

-    which support it or its replacement for those that don't. It must be used to
-    preserve the value of a @c va_list object if you need to use it after
+    which support it or its replacement for those that don't. It must be used
+    to preserve the value of a @c va_list object if you need to use it after

     passing it to another function because it can be modified by the latter.
     passing it to another function because it can be modified by the latter.

+

     As with @c va_start, each call to @c wxVaCopy must have a matching
     @c va_end.
     As with @c va_start, each call to @c wxVaCopy must have a matching
     @c va_end.

-*/
-void wxVaCopy(va_list argptrDst, va_list argptrSrc);

 
 

-/**
-    This is a special version of wxDEPRECATED() macro which
-    only does something when the deprecated function is used from the code outside
-    wxWidgets itself but doesn't generate warnings when it is used from wxWidgets.
-    It is used with the virtual functions which are called by the library itself --
-    even if such function is deprecated the library still has to call it to ensure
-    that the existing code overriding it continues to work, but the use of this
-    macro ensures that a deprecation warning will be generated if this function is
-    used from the user code or, in case of Visual C++, even when it is simply
-    overridden.
+    @header{wx/defs.h}

 */
 */

+void wxVaCopy(va_list argptrDst, va_list argptrSrc);

 
 

+//@}

 
 

diff --git a/interface/dynlib.h b/interface/dynlib.h
index 699532161105555abf94cf46d8f71ee19dc118bc..c5abb1b599b07cfcfc92e7b96306eec5f960c102 100644 (file)
--- a/interface/dynlib.h
+++ b/interface/dynlib.h
@@ -363,24 +363,31 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

+/** @ingroup group_funcmacro_misc */
+//@{
+

 /**
     When loading a function from a DLL you always have to cast the returned
 /**
     When loading a function from a DLL you always have to cast the returned

-    @c void * pointer to the correct type and, even more annoyingly, you have to
-    repeat this type twice if you want to declare and define a function pointer all
-    in one line
+    <tt>void *</tt> pointer to the correct type and, even more annoyingly, you
+    have to repeat this type twice if you want to declare and define a function
+    pointer all in one line.
+

     This macro makes this slightly less painful by allowing you to specify the
     This macro makes this slightly less painful by allowing you to specify the

-    type only once, as the first parameter, and creating a variable of this type
-    named after the function but with @c pfn prefix and initialized with the
-    function @a name from the wxDynamicLibrary
-    @e dynlib.
+    type only once, as the first parameter, and creating a variable of this
+    type named after the function but with @c pfn prefix and initialized with
+    the function @a name from the wxDynamicLibrary @a dynlib.

 
     @param type
 
     @param type

-        the type of the function
+        The type of the function.

     @param name
     @param name

-        the name of the function to load, not a string (without quotes,
-        it is quoted automatically by the macro)
+        The name of the function to load, not a string (without quotes, it is
+        quoted automatically by the macro).

     @param dynlib
     @param dynlib

-        the library to load the function from
+        The library to load the function from.
+
+    @header{wx/dynlib.h}

 */
 */

-#define wxDYNLIB_FUNCTION(type, name, dynlib)     /* implementation is private */
+#define wxDYNLIB_FUNCTION(type, name, dynlib)
+
+//@}

 
 

diff --git a/interface/event.h b/interface/event.h
index fdb5f4fec789cbaa4df6d346d77c0b804c304ad8..22fab0484ef4842a1ef31071ceaa49e438adbc22 100644 (file)
--- a/interface/event.h
+++ b/interface/event.h
@@ -2781,11 +2781,24 @@ public:
 
 
 
 
 
 

+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @ingroup group_funcmacro_misc */
+//@{
+

 /**
     In a GUI application, this function posts @a event to the specified @e dest
 /**
     In a GUI application, this function posts @a event to the specified @e dest

-    object using wxEvtHandler::AddPendingEvent.
+    object using wxEvtHandler::AddPendingEvent().
+
+    Otherwise, it dispatches @a event immediately using
+    wxEvtHandler::ProcessEvent(). See the respective documentation for details
+    (and caveats).

 
 

-    Otherwise, it dispatches @a event immediately using wxEvtHandler::ProcessEvent.
-    See the respective documentation for details (and caveats).
+    @header{wx/event.h}

 */
 void wxPostEvent(wxEvtHandler* dest, wxEvent& event);
 */
 void wxPostEvent(wxEvtHandler* dest, wxEvent& event);

+
+//@}
+

diff --git a/interface/font.h b/interface/font.h
index 6eea89b481b41e5eb042897fdaab01b02c3ac382..bcbe16bd900ce085ce4d9927d359df7bc9c8215e 100644 (file)
--- a/interface/font.h
+++ b/interface/font.h
@@ -654,38 +654,55 @@ public:
 /**
     FIXME
 */
 /**
     FIXME
 */

-wxFont Objects:
-;
+wxFont wxNullFont;

 
 /**
     FIXME
 */
 
 /**
     FIXME
 */

-wxFont wxNullFont;
+wxFont wxNORMAL_FONT;

 
 /**
     FIXME
 */
 
 /**
     FIXME
 */

-wxFont Pointers:
-;
+wxFont wxSMALL_FONT;

 
 /**
     FIXME
 */
 
 /**
     FIXME
 */

-wxFont wxNORMAL_FONT;
+wxFont wxITALIC_FONT;

 
 /**
     FIXME
 */
 
 /**
     FIXME
 */

-wxFont wxSMALL_FONT;
+wxFont wxSWISS_FONT;
+
+
+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @ingroup group_funcmacro_misc */
+//@{

 
 /**
 
 /**

-    FIXME
+    Converts string to a wxFont best represented by the given string. Returns
+    @true on success.
+
+    @see wxToString(const wxFont&)
+
+    @header{wx/font.h}

 */
 */

-wxFont wxITALIC_FONT;
+bool wxFromString(const wxString& string, wxFont* font);

 
 /**
 
 /**

-    FIXME
+    Converts the given wxFont into a string.
+
+    @see wxFromString(const wxString&, wxFont*)
+
+    @header{wx/font.h}

 */
 */

-wxFont wxSWISS_FONT;
+wxString wxToString(const wxFont& font);

 
 

+//@}

 
 

diff --git a/interface/longlong.h b/interface/longlong.h
index b67f4a623e830d34073f0c7a82119db8e0a64a8b..fc970ea8e6044632a5451b90cf0d6f2f1f93900c 100644 (file)
--- a/interface/longlong.h
+++ b/interface/longlong.h
@@ -145,6 +145,9 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

+/** @ingroup group_funcmacro_misc */
+//@{
+

 /**
     This macro is defined to contain the @c printf() format specifier using
     which 64 bit integer numbers (i.e. those of type @c wxLongLong_t) can be
 /**
     This macro is defined to contain the @c printf() format specifier using
     which 64 bit integer numbers (i.e. those of type @c wxLongLong_t) can be


@@ -152,40 +155,48 @@ public:
 
     @code
     #ifdef wxLongLong_t
 
     @code
     #ifdef wxLongLong_t

-            wxLongLong_t ll = wxLL(0x1234567890abcdef);
-            printf("Long long = %" wxLongLongFmtSpec "x\n", ll);
-        #endif
+        wxLongLong_t ll = wxLL(0x1234567890abcdef);
+        printf("Long long = %" wxLongLongFmtSpec "x\n", ll);
+    #endif

     @endcode
 
     @see wxLL()
     @endcode
 
     @see wxLL()

-*/

 
 

+    @header{wx/longlong.h}
+*/
+#define wxLongLongFmtSpec

 
 /**
 
 /**

-    This macro is defined for the platforms with a native 64 bit integer type and
-    allows to define unsigned 64 bit compile time constants:
+    This macro is defined for the platforms with a native 64 bit integer type
+    and allow the use of 64 bit compile time constants:

 
     @code
     #ifdef wxLongLong_t
 
     @code
     #ifdef wxLongLong_t

-            unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef);
-        #endif
+        wxLongLong_t ll = wxLL(0x1234567890abcdef);
+    #endif

     @endcode
 
     @endcode
 

-    @see wxLL(), wxLongLong
+    @see wxULL(), wxLongLong
+
+    @header{wx/longlong.h}

 */
 */

-wxLongLong_t wxULL(number);
+wxLongLong_t wxLL(number);

 
 /**
 
 /**

-    This macro is defined for the platforms with a native 64 bit integer type and
-    allows to define 64 bit compile time constants:
+    This macro is defined for the platforms with a native 64 bit integer type
+    and allow the use of 64 bit compile time constants:

 
     @code
     #ifdef wxLongLong_t
 
     @code
     #ifdef wxLongLong_t

-            wxLongLong_t ll = wxLL(0x1234567890abcdef);
-        #endif
+        unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef);
+    #endif

     @endcode
 
     @endcode
 

-    @see wxULL(), wxLongLong
+    @see wxLL(), wxLongLong
+
+    @header{wx/longlong.h}

 */
 */

-wxLongLong_t wxLL(number);
+wxLongLong_t wxULL(number);
+
+//@}

 
 

diff --git a/interface/math.h b/interface/math.h
index cb05148368b72ae718da2b86a439c38a485e2d1b..e60620eaa5e4b1e8a508de667a3f97f1ffa51265 100644 (file)
--- a/interface/math.h
+++ b/interface/math.h
@@ -6,10 +6,23 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/** @ingroup group_funcmacro_math */
+//@{
+

 /**
 /**

-Returns a non-zero value if @a x is neither infinite nor NaN (not a number),
-returns 0 otherwise.
+    Returns a non-zero value if @a x is neither infinite nor NaN (not a
+    number), returns 0 otherwise.
+
+    @header{wx/math.h}

 */
 int wxFinite(double x);
 
 */
 int wxFinite(double x);
 

+/**
+    Returns a non-zero value if x is NaN (not a number), returns 0 otherwise.
+
+    @header{wx/math.h}
+*/
+bool wxIsNaN(double x);
+
+//@}

 
 

diff --git a/interface/scopeguard.h b/interface/scopeguard.h
index 0a68edd65b813677745c3aeaa80b24789da8cbfa..495ed93199e87a02538076bafe7785845a087257 100644 (file)
--- a/interface/scopeguard.h
+++ b/interface/scopeguard.h
@@ -6,37 +6,41 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/** @ingroup group_funcmacro_misc */

 //@{
 /**
 //@{
 /**

-    This family of macros is similar to wxON_BLOCK_EXIT()
-    but calls a method of the given object instead of a free function.
-*/
-wxON_BLOCK_EXIT_OBJ0(obj, method);
-wxON_BLOCK_EXIT_OBJ1(obj, method, p1);
-wxON_BLOCK_EXIT_OBJ2(obj, method, p1, p2);
-//@}
-
-
-//@{
-/**
-    This family of macros allows to ensure that the global function @e func
-    with 0, 1, 2 or more parameters (up to some implementaton-defined limit) is
-    executed on scope exit, whether due to a normal function return or because an
-    exception has been thrown. A typical example of its usage:
+    This macro ensures that the global @a function with 0, 1, 2 or more
+    parameters (up to some implementaton-defined limit) is executed on scope
+    exit, whether due to a normal function return or because an exception has
+    been thrown. A typical example of its usage:

 
     @code
     void *buf = malloc(size);
 
     @code
     void *buf = malloc(size);

-        wxON_BLOCK_EXIT1(free, buf);
+    wxON_BLOCK_EXIT1(free, buf);

     @endcode
 
     Please see the original article by Andrei Alexandrescu and Petru Marginean
     @endcode
 
     Please see the original article by Andrei Alexandrescu and Petru Marginean

-    published in December 2000 issue of C/C++ Users Journal for more
-    details.
+    published in December 2000 issue of C/C++ Users Journal for more details.
+
+    @see wxON_BLOCK_EXIT_OBJ0()
+
+    @header{wx/scopeguard.h}
+*/
+#define wxON_BLOCK_EXIT0(function)
+#define wxON_BLOCK_EXIT1(function, p1)
+#define wxON_BLOCK_EXIT2(function, p1, p2)
+//@}
+
+/** @ingroup group_funcmacro_misc */
+//@{
+/**
+    This family of macros is similar to wxON_BLOCK_EXIT0(), but calls a method
+    of the given object instead of a free function.

 
 

-    @see wxON_BLOCK_EXIT_OBJ()
+    @header{wx/scopeguard.h}

 */
 */

-wxON_BLOCK_EXIT0(func);
-wxON_BLOCK_EXIT1(func, p1);
-wxON_BLOCK_EXIT2(func, p1, p2);
+#define wxON_BLOCK_EXIT_OBJ0(object, method)
+#define wxON_BLOCK_EXIT_OBJ1(object, method, p1)
+#define wxON_BLOCK_EXIT_OBJ2(object, method, p1, p2)

 //@}
 
 //@}
 

diff --git a/interface/stockitem.h b/interface/stockitem.h
index e99dac6765a0964e3fd01904b70423a09c99cec2..61f958d3eeccd17e21ab1223c57a1924a3fc4ae9 100644 (file)
--- a/interface/stockitem.h
+++ b/interface/stockitem.h
@@ -6,21 +6,26 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/** @ingroup group_funcmacro_misc */
+//@{
+

 /**
 /**

-Returns label that should be used for given @a id element.
+    Returns label that should be used for given @a id element.
+
+    @param id
+        Given id of the wxMenuItem, wxButton, wxToolBar tool, etc.
+    @param withCodes
+        If @false then strip accelerator code from the label; useful for
+        getting labels without accelerator char code like for toolbar tooltip
+        or on platforms without traditional keyboard like smartphones.
+    @param accelerator
+        Optional accelerator string automatically added to label; useful for
+        building labels for wxMenuItem.

 
 

-@param id
-    given id of the wxMenuItem, wxButton, wxToolBar tool, etc.
-@param withCodes
-    if @false then strip accelerator code from the label;
-    useful for getting labels without accelerator char code like for toolbar
-tooltip or
-    on platforms without traditional keyboard like smartphones
-@param accelerator
-    optional accelerator string automatically added to label; useful
-    for building labels for wxMenuItem
+    @header{wx/stockitem.h}

 */
 wxString wxGetStockLabel(wxWindowID id, bool withCodes = true,
                          const wxString& accelerator = wxEmptyString);
 
 */
 wxString wxGetStockLabel(wxWindowID id, bool withCodes = true,
                          const wxString& accelerator = wxEmptyString);
 

+//@}

 
 

diff --git a/interface/string.h b/interface/string.h
index 973a07a48919509c0ce815576b04dab204d20ca1..4441581d90fec3ff91b9d64f8d9bb2d6bd5bf227 100644 (file)
--- a/interface/string.h
+++ b/interface/string.h
@@ -1248,27 +1248,3 @@ public:
     wxChar* operator wxChar *();
 };
 
     wxChar* operator wxChar *();
 };
 

-
-
-// ============================================================================
-// Global functions/macros
-// ============================================================================
-
-//@{
-/**
-    Converts its argument to string.
-    See also: wxFromString().
-*/
-wxString wxToString(const wxColour& col);
-wxString wxToString(const wxFont& col);
-//@}
-
-//@{
-/**
-    Converts string to the type of the second argument. Returns @true on success.
-    See also: wxToString().
-*/
-bool wxFromString(const wxString& str, wxColour* col);
-bool wxFromString(const wxString& str, wxFont* col);
-//@}
-

diff --git a/interface/utils.h b/interface/utils.h
index 4f48f7dfc0a5133d390160e2724811faab5f1edd..01cbd0b2c4ccad48fe5c52aafea93a867b427e74 100644 (file)
--- a/interface/utils.h
+++ b/interface/utils.h
@@ -206,272 +206,323 @@ bool wxUnsetEnv(const wxString& var);
 
 
 
 
 
 

+/** @ingroup group_funcmacro_misc */
+//@{
+

 /**
 /**

-    Returns the type of power source as one of @c wxPOWER_SOCKET,
-    @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN.
-    @c wxPOWER_UNKNOWN is also the default on platforms where this
+    Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
+    @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
+    @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
+    @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this

     feature is not implemented (currently everywhere but MS Windows).
 
     @header{wx/utils.h}
 */
     feature is not implemented (currently everywhere but MS Windows).
 
     @header{wx/utils.h}
 */

-wxPowerType wxGetPowerType();
+wxBatteryState wxGetBatteryState();

 
 /**
 
 /**

-    This function returns the "user id" also known as "login name" under Unix
-    i.e.  something like "jsmith". It uniquely identifies the current user (on
-    this system).  Under Windows or NT, this function first looks in the
-    environment variables USER and LOGNAME; if neither of these is found, the
-    entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
-
-    @return Returns the login name if successful or an empty string otherwise.
-
-    @see wxGetUserName()
+    Returns the type of power source as one of @c wxPOWER_SOCKET,
+    @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the
+    default on platforms where this feature is not implemented (currently
+    everywhere but MS Windows).

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetUserId();
+wxPowerType wxGetPowerType();

 
 /**
 
 /**

-    @deprecated
-    This form is deprecated, use wxGetUserId() version that returns wxString.
+    Under X only, returns the current display name.

 
 

-    @param buf Buffer to store login name in.
-    @param sz  Size of the buffer.
+    @see wxSetDisplayName()

 
 

-    @return Returns @true if successful, @false otherwise.
- */
-bool wxGetUserId(char* buf, int sz);
+    @header{wx/utils.h}
+*/
+wxString wxGetDisplayName();

 
 /**
 
 /**

-    Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
-    @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
-    @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
-    @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where
-    this feature is not implemented (currently everywhere but MS Windows).
+    For normal keys, returns @true if the specified key is currently down.
+
+    For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if
+    the key is toggled such that its LED indicator is lit. There is currently
+    no way to test whether togglable keys are up or down.
+
+    Even though there are virtual key codes defined for mouse buttons, they
+    cannot be used with this function currently.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxBatteryState wxGetBatteryState();
+bool wxGetKeyState(wxKeyCode key);

 
 /**
 
 /**

-    @deprecated
-    This function is obsolete, please use wxWindow::FindWindowByName() instead.
-
-    Find a window by its name (as given in a window constructor or Create()
-    function call).  If @a parent is @NULL, the search will start from all
-    top-level frames and dialog boxes; if non-@NULL, the search will be limited
-    to the given window hierarchy.  The search is recursive in both cases.  If
-    no such named window is found, wxFindWindowByLabel() is called.
+    Returns the mouse position in screen coordinates.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL);
+wxPoint wxGetMousePosition();

 
 /**
 
 /**

-    This function is deprecated as the ids generated by it can conflict with the
-    ids defined by the user code, use @c wxID_ANY to assign ids which are
-    guaranteed to not conflict with the user-defined ids for the controls and menu
-    items you create instead of using this function.
-
-    Generates an integer identifier unique to this run of the program.
+    Returns the current state of the mouse.  Returns a wxMouseState instance
+    that contains the current position of the mouse pointer in screen
+    coordinates, as well as boolean values indicating the up/down status of the
+    mouse buttons and the modifier keys.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-long wxNewId();
+wxMouseState wxGetMouseState();

 
 /**
 
 /**

-    Ensures that ids subsequently generated by @b NewId do not clash with
-    the given @b id.
+    This function enables or disables all top level windows. It is used by
+    wxSafeYield().

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxRegisterId(long id);
+void wxEnableTopLevelWindows(bool enable = true);

 
 /**
 
 /**

-    For normal keys, returns @true if the specified key is currently down.
-    For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns
-    @true if the key is toggled such that its LED indicator is lit. There is
-    currently no way to test whether togglable keys are up or down.
-    Even though there are virtual key codes defined for mouse buttons, they
-    cannot be used with this function currently.
+    Find the deepest window at the given mouse position in screen coordinates,
+    returning the window if found, or @NULL if not.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-bool wxGetKeyState(wxKeyCode key);
+wxWindow* wxFindWindowAtPoint(const wxPoint& pt);

 
 /**
 
 /**

-    Returns the string containing the description of the current platform in a
-    user-readable form. For example, this function may return strings like
-    @c Windows NT Version 4.0 or @c Linux 2.2.2 i386.
+    @deprecated Replaced by wxWindow::FindWindowByLabel().

 
 

-    @see ::wxGetOsVersion
+    Find a window by its label. Depending on the type of window, the label may
+    be a window title or panel item label. If @a parent is @NULL, the search
+    will start from all top-level frames and dialog boxes; if non-@NULL, the
+    search will be limited to the given window hierarchy. The search is
+    recursive in both cases.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetOsDescription();
+wxWindow* wxFindWindowByLabel(const wxString& label,
+                              wxWindow* parent = NULL);

 
 /**
 
 /**

-    Return the (current) user's home directory.
+    @deprecated Replaced by wxWindow::FindWindowByName().

 
 

-    @see wxGetUserHome(), wxStandardPaths
+    Find a window by its name (as given in a window constructor or @e Create
+    function call). If @a parent is @NULL, the search will start from all
+    top-level frames and dialog boxes; if non-@NULL, the search will be limited
+    to the given window hierarchy. The search is recursive in both cases.
+
+    If no such named window is found, wxFindWindowByLabel() is called.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetHomeDir();
+wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL);

 
 /**
 
 /**

-    Sleeps for the specified number of milliseconds. Notice that usage of this
-    function is encouraged instead of calling usleep(3) directly because the
-    standard usleep() function is not MT safe.
+    Find a menu item identifier associated with the given frame's menu bar.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxMilliSleep(unsigned long milliseconds);
+int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
+                     const wxString& itemString);

 
 /**
 
 /**

-    Sleeps for the specified number of microseconds. The microsecond resolution may
-    not, in fact, be available on all platforms (currently only Unix platforms with
-    nanosleep(2) may provide it) in which case this is the same as
-    wxMilliSleep()(@e microseconds/1000).
+    @deprecated Ids generated by it can conflict with the Ids defined by the
+                user code, use @c wxID_ANY to assign ids which are guaranteed
+                to not conflict with the user-defined ids for the controls and
+                menu items you create instead of using this function.
+
+    Generates an integer identifier unique to this run of the program.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxMicroSleep(unsigned long microseconds);
+long wxNewId();

 
 

+/**
+    Ensures that Ids subsequently generated by wxNewId() do not clash with the
+    given @a id.
+
+    @header{wx/utils.h}
+*/
+void wxRegisterId(long id);

 
 /**
 
 /**

-    Find a menu item identifier associated with the given frame's menu bar.
+    Opens the @a url in user's default browser. If the @a flags parameter
+    contains @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
+    (currently this is only supported under Windows). The @a url may also be a
+    local file path (with or without the "file://" prefix), if it doesn't
+    correspond to an existing file and the URL has no scheme "http://" is
+    prepended to it by default.
+
+    Returns @true if the application was successfully launched.
+
+    @note For some configurations of the running user, the application which is
+          launched to open the given URL may be URL-dependent (e.g. a browser
+          may be used for local URLs while another one may be used for remote
+          URLs).

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
-                    const wxString& itemString);
+bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);

 
 /**
 
 /**

-    This function enables or disables all top level windows. It is used by
-    ::wxSafeYield.
+    Loads a user-defined Windows resource as a string. If the resource is
+    found, the function creates a new character array and copies the data into
+    it. A pointer to this data is returned. If unsuccessful, @NULL is returned.
+
+    The resource must be defined in the @c .rc file using the following syntax:
+
+    @code
+    myResource TEXT file.ext
+    @endcode
+
+    Where @c file.ext is a file that the resource compiler can find.
+
+    This function is available under Windows only.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxEnableTopLevelWindows(bool enable = true);
+wxString wxLoadUserResource(const wxString& resourceName,
+                            const wxString& resourceType = "TEXT");

 
 /**
 
 /**

-    Strips any menu codes from @a str and returns the result.
-    By default, the functions strips both the mnemonics character (@c '')
-    which is used to indicate a keyboard shortkey, and the accelerators, which are
-    used only in the menu items and are separated from the main text by the
-    @c \t (TAB) character. By using @a flags of
-    @c wxStrip_Mnemonics or @c wxStrip_Accel to strip only the former
-    or the latter part, respectively.
-    Notice that in most cases
-    wxMenuItem::GetLabelFromText or
-    wxControl::GetLabelText can be used instead.
+    @deprecated Replaced by wxWindow::Close(). See the
+                @ref overview_windowdeletion "window deletion overview".
+
+    Tells the system to delete the specified object when all other events have
+    been processed. In some environments, it is necessary to use this instead
+    of deleting a frame directly with the delete operator, because some GUIs
+    will still send events to a deleted window.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxStripMenuCodes(const wxString& str,
-                            int flags = wxStrip_All);
+void wxPostDelete(wxObject* object);

 
 /**
 
 /**

-    Open the @a url in user's default browser. If @a flags parameter contains
-    @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
-    (currently this is only supported under Windows). The @a url may also be a
-    local file path (with or without @c file:// prefix), if it doesn't
-    correspond to an existing file and the URL has no scheme @c http:// is
-    prepended to it by default.
-    Returns @true if the application was successfully launched.
-    Note that for some configurations of the running user, the application which
-    is launched to open the given URL may be URL-dependent (e.g. a browser may be
-    used for
-    local URLs while another one may be used for remote URLs).
+    Under X only, sets the current display name. This is the X host and display
+    name such as "colonsay:0.0", and the function indicates which display
+    should be used for creating windows from this point on. Setting the display
+    within an application allows multiple displays to be used.
+
+    @see wxGetDisplayName()

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
+void wxSetDisplayName(const wxString& displayName);

 
 /**
 
 /**

-    Executes a command in an interactive shell window. If no command is
-    specified, then just the shell is spawned.
-    See also wxExecute(), @ref overview_sampleexec "Exec sample".
+    Strips any menu codes from @a str and returns the result.
+
+    By default, the functions strips both the mnemonics character (@c '&')
+    which is used to indicate a keyboard shortkey, and the accelerators, which
+    are used only in the menu items and are separated from the main text by the
+    @c \t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
+    @c wxStrip_Accel to strip only the former or the latter part, respectively.
+
+    Notice that in most cases wxMenuItem::GetLabelFromText() or
+    wxControl::GetLabelText() can be used instead.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-bool wxShell(const wxString& command = NULL);
+wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
+
+//@}
+
+
+
+
+

 
 /**
 
 /**

-    Gets the version and the operating system ID for currently running OS.
-    See wxPlatformInfo for more details about wxOperatingSystemId.
+    This function returns the "user id" also known as "login name" under Unix
+    i.e.  something like "jsmith". It uniquely identifies the current user (on
+    this system).  Under Windows or NT, this function first looks in the
+    environment variables USER and LOGNAME; if neither of these is found, the
+    entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.

 
 

-    @see ::wxGetOsDescription, wxPlatformInfo
+    @return Returns the login name if successful or an empty string otherwise.
+
+    @see wxGetUserName()

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxOperatingSystemId wxGetOsVersion(int* major = NULL,
-                                    int* minor = NULL);
+wxString wxGetUserId();

 
 /**
 
 /**

-    Returns the FQDN (fully qualified domain host name) or an empty string on
-    error.
+    @deprecated
+    This form is deprecated, use wxGetUserId() version that returns wxString.

 
 

-    @see wxGetHostName()
+    @param buf Buffer to store login name in.
+    @param sz  Size of the buffer.
+
+    @return Returns @true if successful, @false otherwise.
+ */
+bool wxGetUserId(char* buf, int sz);
+
+/**
+    Returns the string containing the description of the current platform in a
+    user-readable form. For example, this function may return strings like
+    @c Windows NT Version 4.0 or @c Linux 2.2.2 i386.
+
+    @see ::wxGetOsVersion

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetFullHostName();
+wxString wxGetOsDescription();

 
 /**
 
 /**

-    Tells the system to delete the specified object when
-    all other events have been processed. In some environments, it is
-    necessary to use this instead of deleting a frame directly with the
-    delete operator, because some GUIs will still send events to a deleted window.
-    Now obsolete: use wxWindow::Close instead.
+    Return the (current) user's home directory.
+
+    @see wxGetUserHome(), wxStandardPaths

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxPostDelete(wxObject* object);
+wxString wxGetHomeDir();

 
 /**
 
 /**

-    @b NB: This function is obsolete, please use
-    wxWindow::FindWindowByLabel instead.
-    Find a window by its label. Depending on the type of window, the label may be a
-    window title
-    or panel item label. If @a parent is @NULL, the search will start from all
-    top-level
-    frames and dialog boxes; if non-@NULL, the search will be limited to the given
-    window hierarchy.
-    The search is recursive in both cases.
+    Sleeps for the specified number of milliseconds. Notice that usage of this
+    function is encouraged instead of calling usleep(3) directly because the
+    standard usleep() function is not MT safe.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxWindow* wxFindWindowByLabel(const wxString& label,
-                                wxWindow* parent = NULL);
+void wxMilliSleep(unsigned long milliseconds);

 
 

+/**
+    Sleeps for the specified number of microseconds. The microsecond resolution may
+    not, in fact, be available on all platforms (currently only Unix platforms with
+    nanosleep(2) may provide it) in which case this is the same as
+    wxMilliSleep()(@e microseconds/1000).
+
+    @header{wx/utils.h}
+*/
+void wxMicroSleep(unsigned long microseconds);

 
 /**
 
 /**

-    Returns the mouse position in screen coordinates.
+    Executes a command in an interactive shell window. If no command is
+    specified, then just the shell is spawned.
+    See also wxExecute(), @ref overview_sampleexec "Exec sample".

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxPoint wxGetMousePosition();
+bool wxShell(const wxString& command = NULL);

 
 /**
 
 /**

-    Loads a user-defined Windows resource as a string. If the resource is found,
-    the function creates
-    a new character array and copies the data into it. A pointer to this data is
-    returned. If unsuccessful, @NULL is returned.
-    The resource must be defined in the @c .rc file using the following syntax:
+    Gets the version and the operating system ID for currently running OS.
+    See wxPlatformInfo for more details about wxOperatingSystemId.

 
 

-    @code
-    myResource TEXT file.ext
-    @endcode
+    @see ::wxGetOsDescription, wxPlatformInfo

 
 

-    where @c file.ext is a file that the resource compiler can find.
-    This function is available under Windows only.
+    @header{wx/utils.h}
+*/
+wxOperatingSystemId wxGetOsVersion(int* major = NULL,
+                                    int* minor = NULL);
+
+/**
+    Returns the FQDN (fully qualified domain host name) or an empty string on
+    error.
+
+    @see wxGetHostName()

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxLoadUserResource(const wxString& resourceName,
-                            const wxString& resourceType = "TEXT");
+wxString wxGetFullHostName();

 
 /**
     Returns the amount of free memory in bytes under environments which
 
 /**
     Returns the amount of free memory in bytes under environments which


@@ -499,13 +550,6 @@ wxString wxGetHostName();
 bool wxGetHostName(char* buf, int sz);
 //@}
 
 bool wxGetHostName(char* buf, int sz);
 //@}
 

-/**
-    Under X only, returns the current display name. See also wxSetDisplayName().
-
-    @header{wx/utils.h}
-*/
-wxString wxGetDisplayName();
-

 /**
     Returns the home directory for the given user. If the @a user is empty
     (default value), this function behaves like
 /**
     Returns the home directory for the given user. If the @a user is empty
     (default value), this function behaves like


@@ -702,16 +746,6 @@ unsigned long wxGetProcessId();
 int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL,
             int flags = 0);
 
 int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL,
             int flags = 0);
 

-/**
-    Returns the current state of the mouse.  Returns a wxMouseState
-    instance that contains the current position of the mouse pointer in
-    screen coordinates, as well as boolean values indicating the up/down
-    status of the mouse buttons and the modifier keys.
-
-    @header{wx/utils.h}
-*/
-wxMouseState wxGetMouseState();
-

 //@{
 /**
     Copies the user's email address into the supplied buffer, by
 //@{
 /**
     Copies the user's email address into the supplied buffer, by


@@ -743,17 +777,3 @@ void wxSleep(int secs);
 */
 bool wxIsPlatformLittleEndian();
 
 */
 bool wxIsPlatformLittleEndian();
 

-/**
-    Under X only, sets the current display name. This is the X host and display
-    name such
-    as "colonsay:0.0", and the function indicates which display should be used for
-    creating
-    windows from this point on. Setting the display within an application allows
-    multiple
-    displays to be used.
-    See also wxGetDisplayName().
-
-    @header{wx/utils.h}
-*/
-void wxSetDisplayName(const wxString& displayName);
-

diff --git a/interface/window.h b/interface/window.h
index 2166b02de2840054ff572694c5bf772c8786aec6..8b2f9d40973436964e555abfaca021353f6dbdb6 100644 (file)
--- a/interface/window.h
+++ b/interface/window.h
@@ -2613,27 +2613,32 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/**
-    Find the deepest window at the given mouse position in screen coordinates,
-    returning the window if found, or @NULL if not.
-*/
-wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
+/** @ingroup group_funcmacro_misc */
+//@{

 
 /**
     Find the deepest window at the mouse pointer position, returning the window
     and current pointer position in screen coordinates.
 
 /**
     Find the deepest window at the mouse pointer position, returning the window
     and current pointer position in screen coordinates.

+
+    @header{wx/window.h}

 */
 wxWindow* wxFindWindowAtPointer(wxPoint& pt);
 
 /**
 */
 wxWindow* wxFindWindowAtPointer(wxPoint& pt);
 
 /**

-    Gets the currently active window (implemented for MSW and GTK only currently,
-    always returns @NULL in the other ports).
+    Gets the currently active window (implemented for MSW and GTK only
+    currently, always returns @NULL in the other ports).
+
+    @header{wx/window.h}

 */
 wxWindow* wxGetActiveWindow();
 
 /**
 */
 wxWindow* wxGetActiveWindow();
 
 /**

-    Returns the first top level parent of the given window, or in other words, the
-    frame or dialog containing it, or @NULL.
+    Returns the first top level parent of the given window, or in other words,
+    the frame or dialog containing it, or @NULL.
+
+    @header{wx/window.h}

 */
 */

-wxWindow* wxGetTopLevelParent(wxWindow win);
+wxWindow* wxGetTopLevelParent(wxWindow* window);
+
+//@}