Explicitly mention that wxDateTime ticks origin is in UTC.

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

diff --git a/interface/wx/utils.h b/interface/wx/utils.h
index 3dfa72f319515d719d2c35fc22a4c00a94d2c7b9..34a9e15347460572c0d182de67325c60e1614f1c 100644 (file)
--- a/interface/wx/utils.h
+++ b/interface/wx/utils.h
@@ -6,6 +6,56 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    Signal constants used by wxProcess.
+*/
+enum wxSignal
+{
+    wxSIGNONE = 0,  //!< verify if the process exists under Unix
+    wxSIGHUP,
+    wxSIGINT,
+    wxSIGQUIT,
+    wxSIGILL,
+    wxSIGTRAP,
+    wxSIGABRT,
+    wxSIGEMT,
+    wxSIGFPE,
+    wxSIGKILL,      //!< forcefully kill, dangerous!
+    wxSIGBUS,
+    wxSIGSEGV,
+    wxSIGSYS,
+    wxSIGPIPE,
+    wxSIGALRM,
+    wxSIGTERM       //!< terminate the process gently
+};
+
+/**
+    Return values for wxProcess::Kill.
+*/
+enum wxKillError
+{
+    wxKILL_OK,              //!< no error
+    wxKILL_BAD_SIGNAL,      //!< no such signal
+    wxKILL_ACCESS_DENIED,   //!< permission denied
+    wxKILL_NO_PROCESS,      //!< no such process
+    wxKILL_ERROR            //!< another, unspecified error
+};
+
+enum wxKillFlags
+{
+    wxKILL_NOCHILDREN = 0,  //!< don't kill children
+    wxKILL_CHILDREN = 1     //!< kill children
+};
+
+enum wxShutdownFlags
+{
+    wxSHUTDOWN_FORCE    = 1, //!< can be combined with other flags (MSW-only)
+    wxSHUTDOWN_POWEROFF = 2, //!< power off the computer
+    wxSHUTDOWN_REBOOT   = 4, //!< shutdown and reboot
+    wxSHUTDOWN_LOGOFF   = 8  //!< close session (currently MSW-only)
+};
+
+

 /**
     @class wxWindowDisabler
 
 /**
     @class wxWindowDisabler
 


@@ -142,6 +192,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();
 


@@ -153,7 +205,9 @@ void wxBell();
     doesn't otherwise handle this event.
 
     @since 2.9.0
     doesn't otherwise handle this event.
 
     @since 2.9.0

+

     @see wxGetLibraryVersionInfo()
     @see wxGetLibraryVersionInfo()

+

     @header{wx/utils.h}
 */
 void wxInfoMessageBox(wxWindow* parent);
     @header{wx/utils.h}
 */
 void wxInfoMessageBox(wxWindow* parent);


@@ -167,8 +221,11 @@ void wxInfoMessageBox(wxWindow* parent);
     Get wxWidgets version information.
 
     @since 2.9.2
     Get wxWidgets version information.
 
     @since 2.9.2

+

     @see wxVersionInfo
     @see wxVersionInfo

+

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

+

     @library{wxcore}
 */
 wxVersionInfo wxGetLibraryVersionInfo();
     @library{wxcore}
 */
 wxVersionInfo wxGetLibraryVersionInfo();


@@ -349,6 +406,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);


@@ -458,24 +518,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
     @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
+
+    @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.
+
+    @library{wxbase}
+
+    @header{wx/utils.h}

 
 

-    Where @c file.ext is a file that the resource compiler can find.
+    @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.
 
 
     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


@@ -523,6 +651,22 @@ void wxQsort(void* pbase, size_t total_elems,
 */
 void wxSetDisplayName(const wxString& displayName);
 
 */
 void wxSetDisplayName(const wxString& displayName);
 

+
+/**
+   flags for wxStripMenuCodes
+*/
+enum
+{
+    // strip '&' characters
+    wxStrip_Mnemonics = 1,
+
+    // strip everything after '\t'
+    wxStrip_Accel = 2,
+
+    // strip everything (this is the default)
+    wxStrip_All = wxStrip_Mnemonics | wxStrip_Accel
+};
+

 /**
     Strips any menu codes from @a str and returns the result.
 
 /**
     Strips any menu codes from @a str and returns the result.