diff --git a/interface/aboutdlg.h b/interface/aboutdlg.h index 680f112cc5..5420dc3fc2 100644 --- a/interface/aboutdlg.h +++ b/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); +//@} diff --git a/interface/accel.h b/interface/accel.h index adc35e4f80..87a820b06b 100644 --- a/interface/accel.h +++ b/interface/accel.h @@ -180,6 +180,11 @@ public: wxAcceleratorTable operator =(const wxAcceleratorTable& accel); }; + +// ============================================================================ +// Global functions/macros +// ============================================================================ + /** An empty accelerator table. */ diff --git a/interface/animate.h b/interface/animate.h index 3631671843..bbdf2f2872 100644 --- a/interface/animate.h +++ b/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. */ diff --git a/interface/app.h b/interface/app.h index 33e501cd0d..4f0baf3bfa 100644 --- a/interface/app.h +++ b/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: - -/** - The global pointer to the singleton wxApp object. - - @see wxApp::GetInstance() -*/ -wxApp *wxTheApp; +/** @ingroup group_funcmacro_appinitterm */ +//@{ /** 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, - you must make it available using DECLARE_APP(). + Thus, before using it anywhere but in the same module where this macro is + 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 - using the default wxWidgets entry code (e.g. main or WinMain). For example, you - can initialize wxWidgets from an Microsoft Foundation Classes application using - this function. + 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); - The following overload of wxEntry is available under all platforms: - (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). +/** + This function initializes wxWidgets in a platform-dependent way. Use this if you + 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(); + //@} diff --git a/interface/arrstr.h b/interface/arrstr.h index a367d28f82..35c6ab3557 100644 --- a/interface/arrstr.h +++ b/interface/arrstr.h @@ -10,27 +10,26 @@ @class wxArrayString @wxheader{arrstr.h} - wxArrayString is an efficient container for storing - 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). + wxArrayString is an efficient container for storing wxString objects. - 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 + 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(), 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, - wxArrayString::Last or - @ref wxArrayString::operatorindex operator[] are not constant, so the - array elements may be modified in place like this + The references returned by wxArrayString::Item, wxArrayString::Last or + wxArrayString::operator[] are not constant, so the 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) which makes it much more efficient if you add strings to - the array rarely (because, of course, you have to pay for Index() efficiency - by having Add() be slower) but search for them often. Several methods should - not be used with sorted array (basically, all which break the order of items) - which is mentioned in their description. + wxArrayString::Index() function (instead of linear search for wxArrayString::Index()) + which makes it much more efficient if you add strings to the array rarely + (because, of course, you have to pay for Index() efficiency by having Add() be + slower) but search for them often. Several methods should not be used with + sorted array (basically, all which break the order of items) which is + mentioned in their description. - Final word: none of the methods of wxArrayString is virtual including its - destructor, so this class should not be used as a base class. + @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 - the item is inserted at the correct position to keep the array sorted and not - appended. - See also: Insert() + + @warning + For sorted arrays, the index of the inserted item will not be, in general, + equal to GetCount() - 1 because the item is inserted at the correct position + 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 - GetCount() will return 0. However, this - function does not free the memory used by the array and so should be used when - the array is going to be reused for storing other strings. Otherwise, you - should use Clear() to empty the array and free - memory. + Empties the array: after a call to this function GetCount() will return 0. + However, this function does not free the memory used by the array and so + should be used when the array is going to be reused for storing other strings. + Otherwise, you 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 - @a bFromEnd is @false or from end otherwise. If @e bCase, comparison is - case sensitive (default), otherwise the case is ignored. + Search the element in the array, starting from the beginning if @a bFromEnd + is @false or from end otherwise. If @e bCase, comparison is case sensitive + (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 - parameters in the latter case. + wxSortedArrayString, but it ignores the @a bCase and @a bFromEnd parameters + 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 - example, to insert the string in the beginning of the array you would write + position @e nIndex. Thus, for example, to insert the string in the beginning of + the array you would write: + + @code + Insert("foo", 0); + @endcode - If @a nIndex is equal to @e GetCount() this function behaves as - Add(). - @b 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! + 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 - wxString parameters and returning an @e int value less than, equal to or - greater than 0 if the first string is less than, equal to or greater than the + @e CompareFunction is defined as a function taking two @e const wxString + parameters and returning an @e int value less than, equal to or greater + 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 - mode, but no check is done in release mode. - This is the operator version of Item() method. + result from an attempt to access an element beyond the end of array in + debug mode, but no check is done in release mode. + + 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 - with @a escape are not considered as separators. + immediately prefixed 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 - sep and returns - the result as a wxString. + Concatenate all lines of the given wxArrayString object using the separator + @a sep and returns 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 - in the strings contained in @a arr before joining them which is necessary - in order to be able to recover the original array contents from the string - later using wxSplit(). + occurrence of @e sep in the strings contained in @a arr before joining them + which is necessary in order to be able to recover the original array contents + from the string later using wxSplit(). + + @see wxSplit() */ wxString wxJoin(const wxArrayString& arr, const wxChar sep, - const wxChar escape = '\'); + const wxChar escape = '\\'); +//@} diff --git a/interface/artprov.h b/interface/artprov.h index 695c9d500b..9883b6b777 100644 --- a/interface/artprov.h +++ b/interface/artprov.h @@ -11,18 +11,18 @@ @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 - that is needed is to derive a class from wxArtProvider, override either its - wxArtProvider::CreateBitmap and/or its - wxArtProvider::CreateIconBundle methods - and register the provider with - wxArtProvider::Push: + replace standard art with their own version. + + All that is needed is to derive a class from wxArtProvider, override either its + wxArtProvider::CreateBitmap and/or its wxArtProvider::CreateIconBundle methods + and register the provider with wxArtProvider::Push: @code - class MyProvider : public wxArtProvider + class MyProvider : public wxArtProvider { protected: wxBitmap CreateBitmap(const wxArtID& id, @@ -39,96 +39,120 @@ @endcode If you need bitmap images (of the same artwork) that should be displayed at - different sizes - you should probably consider overriding wxArtProvider::CreateIconBundle + different sizes 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 - platform native icons as provided by wxArtProvider::GetBitmap or - wxArtProvider::GetIcon (NB: this is not yet really - possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too - small). + code and use platform native icons as provided by wxArtProvider::GetBitmap or + wxArtProvider::GetIcon. + @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 - wxArtProvider::CreateBitmap - wxArtProvider::CreateIconBundle - wxArtProvider::Delete - wxArtProvider::GetBitmap - wxArtProvider::GetIconBundle - wxArtProvider::GetIcon - wxArtProvider::Insert - wxArtProvider::Pop - wxArtProvider::Push - wxArtProvider::Remove - - - Identifying art resources + @section wxartprovider_identify Identifying art resources Every bitmap and icon bundle are known to wxArtProvider under an unique ID that - is used when - 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 + is used when 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 @ref page_utils_samples_artprovider): + + +
+ @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 + + @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 + + @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 +
Additionally, any string recognized by custom art providers registered using wxArtProvider::Push may be used. - @library{wxcore} - @category{FIXME} + @note + 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 @@ -178,6 +177,11 @@ public: @param size 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() */ @@ -186,8 +190,8 @@ public: const wxSize& size); /** - This method is similar to CreateBitmap() but - can be used when a bitmap (or an icon) exists in several sizes. + This method is similar to CreateBitmap() but can be used when a bitmap + (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 - @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. + Same as wxArtProvider::GetBitmap, but return a wxIcon object + (or ::wxNullIcon on failure). */ 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. @@ -237,7 +243,7 @@ public: wxArtID unique identifier of the icon bundle. @param client wxArtClient identifier of the client (i.e. who is asking for the icon - bundle). + bundle). @returns The icon bundle if one of registered providers recognizes the ID or wxNullIconBundle otherwise. @@ -246,68 +252,8 @@ public: const wxArtClient& client = wxART_OTHER); /** - Every bitmap and icon bundle are known to wxArtProvider under an unique ID that - is used when - 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). + 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 - will be queried as the first provider). + Register new art provider and add it to the top of providers stack + (i.e. it will be queried as the first provider). @see Insert() */ diff --git a/interface/atomic.h b/interface/atomic.h index 1e9305cf1c..3ec54209db 100644 --- a/interface/atomic.h +++ b/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. + 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); +//@} diff --git a/interface/event.h b/interface/event.h index 9dde84415d..28e44fed5d 100644 --- a/interface/event.h +++ b/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); \ No newline at end of file diff --git a/interface/log.h b/interface/log.h index 80a2b1dfb4..af135f16dd 100644 --- a/interface/log.h +++ b/interface/log.h @@ -923,4 +923,25 @@ void wxVLogStatus(const char* formatString, va_list argPtr); void wxLogSysError(const char* formatString, ... ); void wxVLogSysError(const char* formatString, va_list argPtr); -//@} \ No newline at end of file +//@} + + +/** + 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); + + diff --git a/interface/utils.h b/interface/utils.h index bd3f03ccb5..8a7f02988b 100644 --- a/interface/utils.h +++ b/interface/utils.h @@ -233,433 +233,425 @@ void wxMicroSleep(unsigned long microseconds); */ void wxInfoMessageBox(wxWindow ( parent = NULL); - /** - Find a menu item identifier associated with the given frame's menu bar. - */ - int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, - const wxString& itemString); +/** + Find a menu item identifier associated with the given frame's menu bar. +*/ +int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, + const wxString& itemString); - /** - This function enables or disables all top level windows. It is used by - ::wxSafeYield. - */ - void wxEnableTopLevelWindows(bool enable = true); +/** + This function enables or disables all top level windows. It is used by + ::wxSafeYield. +*/ +void wxEnableTopLevelWindows(bool enable = true); - /** - 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. - */ - wxString wxStripMenuCodes(const wxString& str, - int flags = wxStrip_All); +/** + 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. +*/ +wxString wxStripMenuCodes(const wxString& str, + int flags = wxStrip_All); - /** - @b NB: This function is now obsolete, please use wxLogError() - instead. - Displays @a msg and continues. This writes to standard error under - Unix, and pops up a message box under Windows. Used for internal - wxWidgets errors. See also wxFatalError(). - */ - void wxError(const wxString& msg, - const wxString& title = "wxWidgets Internal Error"); +/** + @b NB: This function is now obsolete, please use wxLogError() + instead. + Displays @a msg and continues. This writes to standard error under + Unix, and pops up a message box under Windows. Used for internal + wxWidgets errors. See also wxFatalError(). +*/ +void wxError(const wxString& msg, + const wxString& title = "wxWidgets Internal Error"); - /** - 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). - */ - bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0); +/** + 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). +*/ +bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0); - /** - 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". - */ - bool wxShell(const wxString& command = NULL); +/** + 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". +*/ +bool wxShell(const wxString& command = NULL); - /** - Gets the version and the operating system ID for currently running OS. - See wxPlatformInfo for more details about wxOperatingSystemId. +/** + Gets the version and the operating system ID for currently running OS. + See wxPlatformInfo for more details about wxOperatingSystemId. - @see ::wxGetOsDescription, wxPlatformInfo - */ - wxOperatingSystemId wxGetOsVersion(int* major = NULL, - int* minor = NULL); + @see ::wxGetOsDescription, wxPlatformInfo +*/ +wxOperatingSystemId wxGetOsVersion(int* major = NULL, + int* minor = NULL); - /** - Returns the FQDN (fully qualified domain host name) or an empty string on - error. +/** + Returns the FQDN (fully qualified domain host name) or an empty string on + error. - @see wxGetHostName() - */ - wxString wxGetFullHostName(); + @see wxGetHostName() +*/ +wxString wxGetFullHostName(); - /** - Changes the cursor to the given cursor for all windows in the application. - Use wxEndBusyCursor() to revert the cursor back - to its previous state. These two calls can be nested, and a counter - ensures that only the outer calls take effect. - See also wxIsBusy(), wxBusyCursor. - */ - void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); +/** + Changes the cursor to the given cursor for all windows in the application. + Use wxEndBusyCursor() to revert the cursor back + to its previous state. These two calls can be nested, and a counter + ensures that only the outer calls take effect. + See also wxIsBusy(), wxBusyCursor. +*/ +void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); - /** - 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. - */ - void wxPostDelete(wxObject* object); +/** + 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. +*/ +void wxPostDelete(wxObject* object); - /** - @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. - */ - wxWindow* wxFindWindowByLabel(const wxString& label, - wxWindow* parent = NULL); +/** + @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. +*/ +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. - */ - wxPoint wxGetMousePosition(); +/** + Returns the mouse position in screen coordinates. +*/ +wxPoint wxGetMousePosition(); - /** - 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: +/** + 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 + @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. - */ - wxString wxLoadUserResource(const wxString& resourceName, - const wxString& resourceType = "TEXT"); + where @c file.ext is a file that the resource compiler can find. + This function is available under Windows only. +*/ +wxString wxLoadUserResource(const wxString& resourceName, + const wxString& resourceType = "TEXT"); - /** - Returns the amount of free memory in bytes under environments which - support it, and -1 if not supported or failed to perform measurement. - */ - wxMemorySize wxGetFreeMemory(); +/** + Returns the amount of free memory in bytes under environments which + support it, and -1 if not supported or failed to perform measurement. +*/ +wxMemorySize wxGetFreeMemory(); - /** - This is a macro defined as @c getenv() or its wide char version in Unicode - mode. - Note that under Win32 it may not return correct value for the variables set - with wxSetEnv(), use wxGetEnv() function - instead. - */ - wxChar* wxGetEnv(const wxString& var); +/** + This is a macro defined as @c getenv() or its wide char version in Unicode + mode. + Note that under Win32 it may not return correct value for the variables set + with wxSetEnv(), use wxGetEnv() function + instead. +*/ +wxChar* wxGetEnv(const wxString& var); //@{ - /** - Copies the current host machine's name into the supplied buffer. Please note - that the returned name is @e not fully qualified, i.e. it does not include - the domain name. - Under Windows or NT, this function first looks in the environment - variable SYSTEM_NAME; if this is not found, the entry @b HostName - in the @b wxWidgets section of the WIN.INI file is tried. - The first variant of this function returns the hostname if successful or an - empty string otherwise. The second (deprecated) function returns @true - if successful, @false otherwise. +/** + Copies the current host machine's name into the supplied buffer. Please note + that the returned name is @e not fully qualified, i.e. it does not include + the domain name. + Under Windows or NT, this function first looks in the environment + variable SYSTEM_NAME; if this is not found, the entry @b HostName + in the @b wxWidgets section of the WIN.INI file is tried. + The first variant of this function returns the hostname if successful or an + empty string otherwise. The second (deprecated) function returns @true + if successful, @false otherwise. - @see wxGetFullHostName() - */ - wxString wxGetHostName(); - bool wxGetHostName(char* buf, int sz); + @see wxGetFullHostName() +*/ +wxString wxGetHostName(); +bool wxGetHostName(char* buf, int sz); //@} - /** - Returns the current value of the environment variable @a var in @e value. - @a value may be @NULL if you just want to know if the variable exists - and are not interested in its value. - Returns @true if the variable exists, @false otherwise. - */ - bool wxGetEnv(const wxString& var, wxString* value); +/** + Returns the current value of the environment variable @a var in @e value. + @a value may be @NULL if you just want to know if the variable exists + and are not interested in its value. + Returns @true if the variable exists, @false otherwise. +*/ +bool wxGetEnv(const wxString& var, wxString* value); - /** - Under X only, returns the current display name. See also wxSetDisplayName(). - */ - wxString wxGetDisplayName(); +/** + Under X only, returns the current display name. See also wxSetDisplayName(). +*/ +wxString wxGetDisplayName(); - /** - Ring the system bell. - Note that this function is categorized as a GUI one and so is not thread-safe. - */ - void wxBell(); +/** + Ring the system bell. + Note that this function is categorized as a GUI one and so is not thread-safe. +*/ +void wxBell(); - /** - Returns the home directory for the given user. If the @a user is empty - (default value), this function behaves like - wxGetHomeDir() i.e. returns the current user home - directory. - If the home directory couldn't be determined, an empty string is returned. - */ - wxString wxGetUserHome(const wxString& user = ""); +/** + Returns the home directory for the given user. If the @a user is empty + (default value), this function behaves like + wxGetHomeDir() i.e. returns the current user home + directory. + If the home directory couldn't be determined, an empty string is returned. +*/ +wxString wxGetUserHome(const wxString& user = ""); //@{ - /** - @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr - and it only takes the @c command argument, - and returns a 3-element list @c ( status, output, errors ), where - @c output and @c errors are array references. - Executes another program in Unix or Windows. - The first form takes a command string, such as @c "emacs file.txt". - The second form takes an array of values: a command, any number of - arguments, terminated by @NULL. - The semantics of the third and fourth versions is different from the first two - and is described in more details below. - If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow - of control immediately returns. If it contains @c wxEXEC_SYNC, the current - application waits until the other program has terminated. - In the case of synchronous execution, the return value is the exit code of - the process (which terminates by the moment the function returns) and will be - -1 if the process couldn't be started and typically 0 if the process - terminated successfully. Also, while waiting for the process to - terminate, wxExecute will call wxYield(). Because of this, by - default this function disables all application windows to avoid unexpected - reentrancies which could result from the users interaction with the program - while the child process is running. If you are sure that it is safe to not - disable the program windows, you may pass @c wxEXEC_NODISABLE flag to - prevent this automatic disabling from happening. - For asynchronous execution, however, the return value is the process id and - zero value indicates that the command could not be executed. As an added - complication, the return value of -1 in this case indicates that we didn't - launch a new process, but connected to the running one (this can only happen in - case of using DDE under Windows for command execution). In particular, in this, - and only this, case the calling code will not get the notification about - process termination. - If callback isn't @NULL and if execution is asynchronous, - wxProcess::OnTerminate will be called when - the process finishes. Specifying this parameter also allows you to redirect the - standard input and/or output of the process being launched by calling - wxProcess::Redirect. If the child process IO is redirected, - under Windows the process window is not shown by default (this avoids having to - flush an unnecessary console for the processes which don't create any windows - anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from - happening, i.e. with this flag the child process window will be shown normally. - Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure - that the new process is a group leader (this will create a new session if - needed). Calling wxKill() passing wxKILL_CHILDREN will - kill this process as well as all of its children (except those which have - started their own session). - The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking - place while the child process is running. It should be only used for very - short-lived processes as otherwise the application windows risk becoming - unresponsive from the users point of view. As this flag only makes sense with - @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags - is provided as a convenience. - Finally, you may use the third overloaded version of this function to execute - a process (always synchronously, the contents of @a flags is or'd with - @c wxEXEC_SYNC) and capture its output in the array @e output. The - fourth version adds the possibility to additionally capture the messages from - standard error output in the @a errors array. - @b NB: Currently wxExecute() can only be used from the main thread, calling - this function from another thread will result in an assert failure in debug - build and won't work. +/** + @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr + and it only takes the @c command argument, + and returns a 3-element list @c ( status, output, errors ), where + @c output and @c errors are array references. + Executes another program in Unix or Windows. + The first form takes a command string, such as @c "emacs file.txt". + The second form takes an array of values: a command, any number of + arguments, terminated by @NULL. + The semantics of the third and fourth versions is different from the first two + and is described in more details below. + If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow + of control immediately returns. If it contains @c wxEXEC_SYNC, the current + application waits until the other program has terminated. + In the case of synchronous execution, the return value is the exit code of + the process (which terminates by the moment the function returns) and will be + -1 if the process couldn't be started and typically 0 if the process + terminated successfully. Also, while waiting for the process to + terminate, wxExecute will call wxYield(). Because of this, by + default this function disables all application windows to avoid unexpected + reentrancies which could result from the users interaction with the program + while the child process is running. If you are sure that it is safe to not + disable the program windows, you may pass @c wxEXEC_NODISABLE flag to + prevent this automatic disabling from happening. + For asynchronous execution, however, the return value is the process id and + zero value indicates that the command could not be executed. As an added + complication, the return value of -1 in this case indicates that we didn't + launch a new process, but connected to the running one (this can only happen in + case of using DDE under Windows for command execution). In particular, in this, + and only this, case the calling code will not get the notification about + process termination. + If callback isn't @NULL and if execution is asynchronous, + wxProcess::OnTerminate will be called when + the process finishes. Specifying this parameter also allows you to redirect the + standard input and/or output of the process being launched by calling + wxProcess::Redirect. If the child process IO is redirected, + under Windows the process window is not shown by default (this avoids having to + flush an unnecessary console for the processes which don't create any windows + anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from + happening, i.e. with this flag the child process window will be shown normally. + Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure + that the new process is a group leader (this will create a new session if + needed). Calling wxKill() passing wxKILL_CHILDREN will + kill this process as well as all of its children (except those which have + started their own session). + The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking + place while the child process is running. It should be only used for very + short-lived processes as otherwise the application windows risk becoming + unresponsive from the users point of view. As this flag only makes sense with + @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags + is provided as a convenience. + Finally, you may use the third overloaded version of this function to execute + a process (always synchronously, the contents of @a flags is or'd with + @c wxEXEC_SYNC) and capture its output in the array @e output. The + fourth version adds the possibility to additionally capture the messages from + standard error output in the @a errors array. + @b NB: Currently wxExecute() can only be used from the main thread, calling + this function from another thread will result in an assert failure in debug + build and won't work. - @param command - The command to execute and any parameters to pass to it as a - single string. - @param argv - The command to execute should be the first element of this - array, any additional ones are the command parameters and the array must be - terminated with a @NULL pointer. - @param flags - Combination of bit masks wxEXEC_ASYNC, - wxEXEC_SYNC and wxEXEC_NOHIDE - @param callback - An optional pointer to wxProcess + @param command + The command to execute and any parameters to pass to it as a + single string. + @param argv + The command to execute should be the first element of this + array, any additional ones are the command parameters and the array must be + terminated with a @NULL pointer. + @param flags + Combination of bit masks wxEXEC_ASYNC, + wxEXEC_SYNC and wxEXEC_NOHIDE + @param callback + An optional pointer to wxProcess - @see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample". - */ - long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC, - wxProcess* callback = NULL); - wxPerl note: long wxExecute(char** argv, - int flags = wxEXEC_ASYNC, - wxProcess* callback = NULL); - wxPerl note: long wxExecute(const wxString& command, - wxArrayString& output, - int flags = 0); - wxPerl note: long wxExecute(const wxString& command, - wxArrayString& output, - wxArrayString& errors, - int flags = 0); + @see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample". +*/ +long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC, + wxProcess* callback = NULL); +wxPerl note: long wxExecute(char** argv, + int flags = wxEXEC_ASYNC, + wxProcess* callback = NULL); +wxPerl note: long wxExecute(const wxString& command, + wxArrayString& output, + int flags = 0); +wxPerl note: long wxExecute(const wxString& command, + wxArrayString& output, + wxArrayString& errors, + int flags = 0); //@} - /** - Returns a string representing the current date and time. - */ - wxString wxNow(); +/** + Returns a string representing the current date and time. +*/ +wxString wxNow(); - /** - Returns @true if the operating system the program is running under is 64 bit. - The check is performed at run-time and may differ from the value available at - compile-time (at compile-time you can just check if @c sizeof(void*)==8) - since the program could be running in emulation mode or in a mixed 32/64 bit - system - (bi-architecture operating system). - Very important: this function is not 100% reliable on some systems given the - fact - that there isn't always a standard way to do a reliable check on the OS - architecture. - */ - bool wxIsPlatform64Bit(); +/** + Returns @true if the operating system the program is running under is 64 bit. + The check is performed at run-time and may differ from the value available at + compile-time (at compile-time you can just check if @c sizeof(void*)==8) + since the program could be running in emulation mode or in a mixed 32/64 bit + system + (bi-architecture operating system). + Very important: this function is not 100% reliable on some systems given the + fact + that there isn't always a standard way to do a reliable check on the OS + architecture. +*/ +bool wxIsPlatform64Bit(); - /** - Returns the number uniquely identifying the current process in the system. - If an error occurs, 0 is returned. - */ - unsigned long wxGetProcessId(); +/** + Returns the number uniquely identifying the current process in the system. + If an error occurs, 0 is returned. +*/ +unsigned long wxGetProcessId(); - /** - Equivalent to the Unix kill function: send the given signal @a sig to the - process with PID @e pid. The valid signal values are +/** + Equivalent to the Unix kill function: send the given signal @a sig to the + process with PID @e pid. The valid signal values are - @code - 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 - }; - @endcode + @code + 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 + }; + @endcode - @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. - Returns 0 on success, -1 on failure. If @a rc parameter is not @NULL, it will - be filled with an element of @c wxKillError enum: + @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. + Returns 0 on success, -1 on failure. If @a rc parameter is not @NULL, it will + be filled with an element of @c wxKillError enum: - @code - 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 - }; - @endcode + @code + 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 + }; + @endcode - The @a flags parameter can be wxKILL_NOCHILDREN (the default), - or wxKILL_CHILDREN, in which case the child processes of this - process will be killed too. Note that under Unix, for wxKILL_CHILDREN - to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER - to wxExecute. + The @a flags parameter can be wxKILL_NOCHILDREN (the default), + or wxKILL_CHILDREN, in which case the child processes of this + process will be killed too. Note that under Unix, for wxKILL_CHILDREN + to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER + to wxExecute. - @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample" - */ - int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL, - int flags = 0); + @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample" +*/ +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. - */ - wxMouseState wxGetMouseState(); +/** + 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. +*/ +wxMouseState wxGetMouseState(); - /** - Returns @true if between two wxBeginBusyCursor() and - wxEndBusyCursor() calls. - See also wxBusyCursor. - */ - bool wxIsBusy(); +/** + Returns @true if between two wxBeginBusyCursor() and + wxEndBusyCursor() calls. + See also wxBusyCursor. +*/ +bool wxIsBusy(); //@{ - /** - Copies the user's email address into the supplied buffer, by - concatenating the values returned by wxGetFullHostName() - and wxGetUserId(). - Returns @true if successful, @false otherwise. - */ - wxString wxGetEmailAddress(); - bool wxGetEmailAddress(char* buf, int sz); +/** + Copies the user's email address into the supplied buffer, by + concatenating the values returned by wxGetFullHostName() + and wxGetUserId(). + Returns @true if successful, @false otherwise. +*/ +wxString wxGetEmailAddress(); +bool wxGetEmailAddress(char* buf, int sz); //@} - /** - Sleeps for the specified number of seconds. - */ - void wxSleep(int secs); +/** + Sleeps for the specified number of seconds. +*/ +void wxSleep(int secs); - /** - Sets the value of the environment variable @a var (adding it if necessary) - to @e value. - Returns @true on success. +/** + Sets the value of the environment variable @a var (adding it if necessary) + to @e value. + Returns @true on success. - @see wxUnsetEnv() - */ - bool wxSetEnv(const wxString& var, const wxString& value); + @see wxUnsetEnv() +*/ +bool wxSetEnv(const wxString& var, const wxString& value); - /** - Returns @true if the current platform is little endian (instead of big - endian). - The check is performed at run-time. +/** + Returns @true if the current platform is little endian (instead of big + endian). + The check is performed at run-time. - @see @ref overview_byteordermacros "Byte order macros" - */ - bool wxIsPlatformLittleEndian(); + @see @ref overview_byteordermacros "Byte order macros" +*/ +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(). - */ - void wxSetDisplayName(const wxString& displayName); +/** + 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(). +*/ +void wxSetDisplayName(const wxString& displayName);