Add test for absence of events from wxSpinCtrlDouble ctor.

[wxWidgets.git] / interface / wx / utils.h

diff --git a/interface/wx/utils.h b/interface/wx/utils.h
index 6fbbc2a1a229ee4aafb21108a5e6cd84984d28a1..5573a19b93e4f89b9e6a6234f04b1cc1f6f8e600 100644 (file)
--- a/interface/wx/utils.h
+++ b/interface/wx/utils.h
@@ -2,7 +2,6 @@
 // Name:        utils.h
 // Purpose:     interface of various utility classes and functions
 // Author:      wxWidgets team
 // Name:        utils.h
 // Purpose:     interface of various utility classes and functions
 // Author:      wxWidgets team

-// RCS-ID:      $Id$

 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 


@@ -192,6 +191,8 @@ bool wxIsBusy();
     @note This function is categorized as a GUI one and so is not thread-safe.
 
     @header{wx/utils.h}
     @note This function is categorized as a GUI one and so is not thread-safe.
 
     @header{wx/utils.h}

+
+    @library{wxcore}

 */
 void wxBell();
 
 */
 void wxBell();
 


@@ -404,6 +405,9 @@ void wxEnableTopLevelWindows(bool enable = true);
     Find the deepest window at the given mouse position in screen coordinates,
     returning the window if found, or @NULL if not.
 
     Find the deepest window at the given mouse position in screen coordinates,
     returning the window if found, or @NULL if not.
 

+    This function takes child windows at the given position into account even
+    if they are disabled. The hidden children are however skipped by it.
+

     @header{wx/utils.h}
 */
 wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
     @header{wx/utils.h}
 */
 wxWindow* wxFindWindowAtPoint(const wxPoint& pt);


@@ -454,7 +458,7 @@ int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-long wxNewId();
+int wxNewId();

 
 /**
     Ensures that Ids subsequently generated by wxNewId() do not clash with the
 
 /**
     Ensures that Ids subsequently generated by wxNewId() do not clash with the


@@ -462,7 +466,7 @@ long wxNewId();
 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxRegisterId(long id);
+void wxRegisterId(int id);

 
 /**
     Opens the @a document in the application associated with the files of this
 
 /**
     Opens the @a document in the application associated with the files of this


@@ -513,24 +517,92 @@ bool wxLaunchDefaultApplication(const wxString& document, int flags = 0);
 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
 
 /**
 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
 
 /**

-    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.
+    Loads an object from Windows resource file.

 
 

-    The resource must be defined in the @c .rc file using the following syntax:
+    This function loads the resource with the given name and type from the
+    resources embedded into a Windows application.

 
 

+    The typical use for it is to load some data from the data files embedded
+    into the program itself. For example, you could have the following fragment
+    in your @c .rc file

     @code
     @code

-    myResource TEXT file.ext
+        mydata  MYDATA  "myfile.dat"
+    @endcode
+    and then use it in the following way:
+    @code
+        const void* data = NULL;
+        size_t size = 0;
+        if ( !wxLoadUserResource(&data, &size, "mydata", "MYDATA") ) {
+            ... handle error ...
+        }
+        else {
+            // Use the data in any way, for example:
+            wxMemoryInputStream is(data, size);
+            ... read the data from stream ...
+        }

     @endcode
 
     @endcode
 

-    Where @c file.ext is a file that the resource compiler can find.
+    @param outData Filled with the pointer to the data on successful return.
+        Notice that this pointer does @em not need to be freed by the caller.
+    @param outLen Filled with the length of the data in bytes.
+    @param resourceName The name of the resource to load.
+    @param resourceType The type of the resource in usual Windows format, i.e.
+        either a real string like "MYDATA" or an integer created by the
+        standard Windows @c MAKEINTRESOURCE() macro, including any constants
+        for the standard resources types like @c RT_RCDATA.
+    @param module The @c HINSTANCE of the module to load the resources from.
+        The current module is used by default.
+    @return true if the data was loaded from resource or false if it couldn't
+        be found (in which case no error is logged) or was found but couldn't
+        be loaded (which is unexpected and does result in an error message).

 
     This function is available under Windows only.
 
 
     This function is available under Windows only.
 

+    @library{wxbase}
+
+    @header{wx/utils.h}
+
+    @since 2.9.1
+ */
+bool
+wxLoadUserResource(const void **outData,
+                   size_t *outLen,
+                   const wxString& resourceName,
+                   const wxChar* resourceType = "TEXT",
+                   WXHINSTANCE module = 0);
+
+/**
+    Loads a user-defined Windows resource as a string.
+
+    This is a wrapper for the general purpose overload wxLoadUserResource(const
+    void**, size_t*, const wxString&, const wxChar*, WXHINSTANCE) and can be
+    more convenient for the string data, but does an extra copy compared to the
+    general version.
+
+    @param resourceName The name of the resource to load.
+    @param resourceType The type of the resource in usual Windows format, i.e.
+        either a real string like "MYDATA" or an integer created by the
+        standard Windows @c MAKEINTRESOURCE() macro, including any constants
+        for the standard resources types like @c RT_RCDATA.
+    @param pLen Filled with the length of the returned buffer if it is
+        non-@NULL. This parameter should be used if NUL characters can occur in
+        the resource data. It is new since wxWidgets 2.9.1
+    @param module The @c HINSTANCE of the module to load the resources from.
+        The current module is used by default. This parameter is new since
+        wxWidgets 2.9.1.
+    @return A pointer to the data to be <tt>delete[]<tt>d by caller on success
+        or @NULL on error.
+
+    This function is available under Windows only.
+
+    @library{wxbase}
+

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

-wxString wxLoadUserResource(const wxString& resourceName,
-                            const wxString& resourceType = "TEXT");
+char* wxLoadUserResource(const wxString& resourceName,
+                         const wxChar* resourceType = "TEXT",
+                         int* pLen = NULL,
+                         WXHINSTANCE module = 0);

 
 /**
     @deprecated Replaced by wxWindow::Close(). See the
 
 /**
     @deprecated Replaced by wxWindow::Close(). See the


@@ -1205,7 +1277,12 @@ unsigned long wxGetProcessId();
 
     @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under
     both Unix and Windows but all the other signals are equivalent to
 
     @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under
     both Unix and Windows but all the other signals are equivalent to

-    @c wxSIGTERM under Windows.
+    @c wxSIGTERM under Windows. Moreover, under Windows, @c wxSIGTERM is
+    implemented by posting a message to the application window, so it only
+    works if the application does have windows. If it doesn't, as is notably
+    always the case for the console applications, you need to use @c wxSIGKILL
+    to actually kill the process. Of course, this doesn't allow the process to
+    shut down gracefully and so should be avoided if possible.

 
     Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,
     it will be filled with a value from the @c wxKillError enum:
 
     Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,
     it will be filled with a value from the @c wxKillError enum: