Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52499 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-03-14 15:35:10 +00:00
parent c0cc7004a6
commit 39fb805670
10 changed files with 763 additions and 701 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
interface/aboutdlg.h
View File

@@ -171,6 +171,9 @@ public:
// Global functions/macros // Global functions/macros
// ============================================================================ // ============================================================================
/** @ingroup group_funcmacro_dialog */
//@{
/** /**
This function shows the standard about dialog containing the information This function shows the standard about dialog containing the information
specified in @a info. If the current platform has a native about dialog 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); void wxGenericAboutBox(const wxAboutDialogInfo& info);
//@}

5
interface/accel.h
View File

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

6
interface/animate.h
View File

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

109
interface/app.h
View File

@@ -608,6 +608,14 @@ public:
// Global functions/macros // Global functions/macros
// ============================================================================ // ============================================================================
/**
The global pointer to the singleton wxApp object.
@see wxApp::GetInstance()
*/
wxApp *wxTheApp;
/** @ingroup group_funcmacro_rtti */ /** @ingroup group_funcmacro_rtti */
//@{ //@{
@@ -648,20 +656,15 @@ public:
/** @ingroup group_funcmacro_appinitterm */
/** //@{
The global pointer to the singleton wxApp object.
@see wxApp::GetInstance()
*/
wxApp *wxTheApp;
/** /**
This function doesn't exist in wxWidgets but it is created by using This function doesn't exist in wxWidgets but it is created by using
the IMPLEMENT_APP() macro. the IMPLEMENT_APP() macro.
Thus, before using it anywhere but in the same module where this macro is used, Thus, before using it anywhere but in the same module where this macro is
you must make it available using DECLARE_APP(). used, you must make it available using DECLARE_APP().
The advantage of using this function compared to directly using the global 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 wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
@@ -670,15 +673,6 @@ wxApp *wxTheApp;
*/ */
wxAppDerivedClass wxGetApp(); 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 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 faults under Windows or segmentation violations in the Unix world) will be
@@ -696,32 +690,6 @@ void wxExit();
*/ */
bool wxHandleFatalExceptions(bool doIt = true); 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 This function is used in wxBase only and only if you don't create
@@ -752,17 +720,33 @@ void wxUninitialize();
*/ */
bool wxYield(); bool wxYield();
//@{
/** /**
This initializes wxWidgets in a platform-dependent way. Use this if you are not This function is similar to wxYield, except that it disables the user input to
using the default wxWidgets entry code (e.g. main or WinMain). For example, you all program windows before calling wxYield and re-enables it again
can initialize wxWidgets from an Microsoft Foundation Classes application using afterwards. If @a win is not @NULL, this window will remain enabled,
this function. allowing the implementation of some limited user interaction.
Returns the result of the call to ::wxYield.
*/
bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false);
The following overload of wxEntry is available under all platforms: /**
(notice that under Windows CE platform, and only there, the type of @a pCmdLine This function initializes wxWidgets in a platform-dependent way. Use this if you
is @c wchar_t *, otherwise it is @c char *, even in Unicode build). are not using the default wxWidgets entry code (e.g. main or WinMain).
For example, you can initialize wxWidgets from an Microsoft Foundation Classes
(MFC) application using this function.
@note This overload of wxEntry is available under all platforms.
@see wxEntryStart()
*/
int wxEntry(int& argc, wxChar** argv);
/**
See wxEntry(int&,wxChar**) for more info about this function.
Notice that under Windows CE platform, and only there, the type of @a pCmdLine
is @c wchar_t *, otherwise it is @c char *, even in Unicode build.
@remarks To clean up wxWidgets, call wxApp::OnExit followed by the static @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static
function wxApp::CleanUp. For example, if exiting from an MFC application function wxApp::CleanUp. For example, if exiting from an MFC application
@@ -778,12 +762,27 @@ bool wxYield();
} }
@endcode @endcode
@see wxEntryStart()
*/ */
int wxEntry(int& argc, wxChar** argv);
int wxEntry(HINSTANCE hInstance, int wxEntry(HINSTANCE hInstance,
HINSTANCE hPrevInstance = NULL, HINSTANCE hPrevInstance = NULL,
char* pCmdLine = NULL, char* pCmdLine = NULL,
int nCmdShow = SW_SHOWNORMAL); 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();
//@} //@}

230
interface/arrstr.h
View File

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

314
interface/artprov.h
View File

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

17
interface/atomic.h
View File

@@ -6,9 +6,24 @@
// Licence: wxWindows license // 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); 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);
//@}

10
interface/event.h
View File

@@ -2766,3 +2766,13 @@ public:
void SetCursor(const wxCursor& cursor); 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);

23
interface/log.h
View File

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

746
interface/utils.h
View File

@@ -233,433 +233,425 @@ void wxMicroSleep(unsigned long microseconds);
*/ */
void wxInfoMessageBox(wxWindow ( parent = NULL); void wxInfoMessageBox(wxWindow ( parent = NULL);
/** /**
Find a menu item identifier associated with the given frame's menu bar. Find a menu item identifier associated with the given frame's menu bar.
*/ */
int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
const wxString& itemString); const wxString& itemString);
/** /**
This function enables or disables all top level windows. It is used by This function enables or disables all top level windows. It is used by
::wxSafeYield. ::wxSafeYield.
*/ */
void wxEnableTopLevelWindows(bool enable = true); void wxEnableTopLevelWindows(bool enable = true);
/** /**
Strips any menu codes from @a str and returns the result. Strips any menu codes from @a str and returns the result.
By default, the functions strips both the mnemonics character (@c '') By default, the functions strips both the mnemonics character (@c '')
which is used to indicate a keyboard shortkey, and the accelerators, which are 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 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 \t (TAB) character. By using @a flags of
@c wxStrip_Mnemonics or @c wxStrip_Accel to strip only the former @c wxStrip_Mnemonics or @c wxStrip_Accel to strip only the former
or the latter part, respectively. or the latter part, respectively.
Notice that in most cases Notice that in most cases
wxMenuItem::GetLabelFromText or wxMenuItem::GetLabelFromText or
wxControl::GetLabelText can be used instead. wxControl::GetLabelText can be used instead.
*/ */
wxString wxStripMenuCodes(const wxString& str, wxString wxStripMenuCodes(const wxString& str,
int flags = wxStrip_All); int flags = wxStrip_All);
/** /**
@b NB: This function is now obsolete, please use wxLogError() @b NB: This function is now obsolete, please use wxLogError()
instead. instead.
Displays @a msg and continues. This writes to standard error under Displays @a msg and continues. This writes to standard error under
Unix, and pops up a message box under Windows. Used for internal Unix, and pops up a message box under Windows. Used for internal
wxWidgets errors. See also wxFatalError(). wxWidgets errors. See also wxFatalError().
*/ */
void wxError(const wxString& msg, void wxError(const wxString& msg,
const wxString& title = "wxWidgets Internal Error"); const wxString& title = "wxWidgets Internal Error");
/** /**
Open the @a url in user's default browser. If @a flags parameter contains 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 @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 (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 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 correspond to an existing file and the URL has no scheme @c http:// is
prepended to it by default. prepended to it by default.
Returns @true if the application was successfully launched. Returns @true if the application was successfully launched.
Note that for some configurations of the running user, the application which 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 is launched to open the given URL may be URL-dependent (e.g. a browser may be
used for used for
local URLs while another one may be used for remote URLs). local URLs while another one may be used for remote URLs).
*/ */
bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0); bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
/** /**
Executes a command in an interactive shell window. If no command is Executes a command in an interactive shell window. If no command is
specified, then just the shell is spawned. specified, then just the shell is spawned.
See also wxExecute(), @ref overview_sampleexec "Exec sample". See also wxExecute(), @ref overview_sampleexec "Exec sample".
*/ */
bool wxShell(const wxString& command = NULL); bool wxShell(const wxString& command = NULL);
/** /**
Gets the version and the operating system ID for currently running OS. Gets the version and the operating system ID for currently running OS.
See wxPlatformInfo for more details about wxOperatingSystemId. See wxPlatformInfo for more details about wxOperatingSystemId.
@see ::wxGetOsDescription, wxPlatformInfo @see ::wxGetOsDescription, wxPlatformInfo
*/ */
wxOperatingSystemId wxGetOsVersion(int* major = NULL, wxOperatingSystemId wxGetOsVersion(int* major = NULL,
int* minor = NULL); int* minor = NULL);
/** /**
Returns the FQDN (fully qualified domain host name) or an empty string on Returns the FQDN (fully qualified domain host name) or an empty string on
error. error.
@see wxGetHostName() @see wxGetHostName()
*/ */
wxString wxGetFullHostName(); wxString wxGetFullHostName();
/** /**
Changes the cursor to the given cursor for all windows in the application. Changes the cursor to the given cursor for all windows in the application.
Use wxEndBusyCursor() to revert the cursor back Use wxEndBusyCursor() to revert the cursor back
to its previous state. These two calls can be nested, and a counter to its previous state. These two calls can be nested, and a counter
ensures that only the outer calls take effect. ensures that only the outer calls take effect.
See also wxIsBusy(), wxBusyCursor. See also wxIsBusy(), wxBusyCursor.
*/ */
void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
/** /**
Tells the system to delete the specified object when Tells the system to delete the specified object when
all other events have been processed. In some environments, it is all other events have been processed. In some environments, it is
necessary to use this instead of deleting a frame directly with the 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. delete operator, because some GUIs will still send events to a deleted window.
Now obsolete: use wxWindow::Close instead. Now obsolete: use wxWindow::Close instead.
*/ */
void wxPostDelete(wxObject* object); void wxPostDelete(wxObject* object);
/** /**
@b NB: This function is obsolete, please use @b NB: This function is obsolete, please use
wxWindow::FindWindowByLabel instead. wxWindow::FindWindowByLabel instead.
Find a window by its label. Depending on the type of window, the label may be a Find a window by its label. Depending on the type of window, the label may be a
window title window title
or panel item label. If @a parent is @NULL, the search will start from all or panel item label. If @a parent is @NULL, the search will start from all
top-level top-level
frames and dialog boxes; if non-@NULL, the search will be limited to the given frames and dialog boxes; if non-@NULL, the search will be limited to the given
window hierarchy. window hierarchy.
The search is recursive in both cases. The search is recursive in both cases.
*/ */
wxWindow* wxFindWindowByLabel(const wxString& label, wxWindow* wxFindWindowByLabel(const wxString& label,
wxWindow* parent = NULL); 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. Returns the mouse position in screen coordinates.
*/ */
wxPoint wxGetMousePosition(); wxPoint wxGetMousePosition();
/** /**
Loads a user-defined Windows resource as a string. If the resource is found, Loads a user-defined Windows resource as a string. If the resource is found,
the function creates the function creates
a new character array and copies the data into it. A pointer to this data is a new character array and copies the data into it. A pointer to this data is
returned. If unsuccessful, @NULL is returned. returned. If unsuccessful, @NULL is returned.
The resource must be defined in the @c .rc file using the following syntax: The resource must be defined in the @c .rc file using the following syntax:
@code @code
myResource TEXT file.ext myResource TEXT file.ext
@endcode @endcode
where @c file.ext is a file that the resource compiler can find. where @c file.ext is a file that the resource compiler can find.
This function is available under Windows only. This function is available under Windows only.
*/ */
wxString wxLoadUserResource(const wxString& resourceName, wxString wxLoadUserResource(const wxString& resourceName,
const wxString& resourceType = "TEXT"); const wxString& resourceType = "TEXT");
/** /**
Returns the amount of free memory in bytes under environments which Returns the amount of free memory in bytes under environments which
support it, and -1 if not supported or failed to perform measurement. support it, and -1 if not supported or failed to perform measurement.
*/ */
wxMemorySize wxGetFreeMemory(); wxMemorySize wxGetFreeMemory();
/** /**
This is a macro defined as @c getenv() or its wide char version in Unicode This is a macro defined as @c getenv() or its wide char version in Unicode
mode. mode.
Note that under Win32 it may not return correct value for the variables set Note that under Win32 it may not return correct value for the variables set
with wxSetEnv(), use wxGetEnv() function with wxSetEnv(), use wxGetEnv() function
instead. instead.
*/ */
wxChar* wxGetEnv(const wxString& var); wxChar* wxGetEnv(const wxString& var);
//@{ //@{
/** /**
Copies the current host machine's name into the supplied buffer. Please note 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 that the returned name is @e not fully qualified, i.e. it does not include
the domain name. the domain name.
Under Windows or NT, this function first looks in the environment Under Windows or NT, this function first looks in the environment
variable SYSTEM_NAME; if this is not found, the entry @b HostName variable SYSTEM_NAME; if this is not found, the entry @b HostName
in the @b wxWidgets section of the WIN.INI file is tried. 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 The first variant of this function returns the hostname if successful or an
empty string otherwise. The second (deprecated) function returns @true empty string otherwise. The second (deprecated) function returns @true
if successful, @false otherwise. if successful, @false otherwise.
@see wxGetFullHostName() @see wxGetFullHostName()
*/ */
wxString wxGetHostName(); wxString wxGetHostName();
bool wxGetHostName(char* buf, int sz); bool wxGetHostName(char* buf, int sz);
//@} //@}
/** /**
Returns the current value of the environment variable @a var in @e 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 @a value may be @NULL if you just want to know if the variable exists
and are not interested in its value. and are not interested in its value.
Returns @true if the variable exists, @false otherwise. Returns @true if the variable exists, @false otherwise.
*/ */
bool wxGetEnv(const wxString& var, wxString* value); bool wxGetEnv(const wxString& var, wxString* value);
/** /**
Under X only, returns the current display name. See also wxSetDisplayName(). Under X only, returns the current display name. See also wxSetDisplayName().
*/ */
wxString wxGetDisplayName(); wxString wxGetDisplayName();
/** /**
Ring the system bell. Ring the system bell.
Note that this function is categorized as a GUI one and so is not thread-safe. Note that this function is categorized as a GUI one and so is not thread-safe.
*/ */
void wxBell(); void wxBell();
/** /**
Returns the home directory for the given user. If the @a user is empty Returns the home directory for the given user. If the @a user is empty
(default value), this function behaves like (default value), this function behaves like
wxGetHomeDir() i.e. returns the current user home wxGetHomeDir() i.e. returns the current user home
directory. directory.
If the home directory couldn't be determined, an empty string is returned. If the home directory couldn't be determined, an empty string is returned.
*/ */
wxString wxGetUserHome(const wxString& user = ""); wxString wxGetUserHome(const wxString& user = "");
//@{ //@{
/** /**
@b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr
and it only takes the @c command argument, and it only takes the @c command argument,
and returns a 3-element list @c ( status, output, errors ), where and returns a 3-element list @c ( status, output, errors ), where
@c output and @c errors are array references. @c output and @c errors are array references.
Executes another program in Unix or Windows. Executes another program in Unix or Windows.
The first form takes a command string, such as @c "emacs file.txt". 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 The second form takes an array of values: a command, any number of
arguments, terminated by @NULL. arguments, terminated by @NULL.
The semantics of the third and fourth versions is different from the first two The semantics of the third and fourth versions is different from the first two
and is described in more details below. and is described in more details below.
If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow
of control immediately returns. If it contains @c wxEXEC_SYNC, the current of control immediately returns. If it contains @c wxEXEC_SYNC, the current
application waits until the other program has terminated. application waits until the other program has terminated.
In the case of synchronous execution, the return value is the exit code of 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 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 -1 if the process couldn't be started and typically 0 if the process
terminated successfully. Also, while waiting for the process to terminated successfully. Also, while waiting for the process to
terminate, wxExecute will call wxYield(). Because of this, by terminate, wxExecute will call wxYield(). Because of this, by
default this function disables all application windows to avoid unexpected default this function disables all application windows to avoid unexpected
reentrancies which could result from the users interaction with the program 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 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 disable the program windows, you may pass @c wxEXEC_NODISABLE flag to
prevent this automatic disabling from happening. prevent this automatic disabling from happening.
For asynchronous execution, however, the return value is the process id and 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 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 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 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, 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 and only this, case the calling code will not get the notification about
process termination. process termination.
If callback isn't @NULL and if execution is asynchronous, If callback isn't @NULL and if execution is asynchronous,
wxProcess::OnTerminate will be called when wxProcess::OnTerminate will be called when
the process finishes. Specifying this parameter also allows you to redirect the the process finishes. Specifying this parameter also allows you to redirect the
standard input and/or output of the process being launched by calling standard input and/or output of the process being launched by calling
wxProcess::Redirect. If the child process IO is redirected, wxProcess::Redirect. If the child process IO is redirected,
under Windows the process window is not shown by default (this avoids having to 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 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 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. 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 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 that the new process is a group leader (this will create a new session if
needed). Calling wxKill() passing wxKILL_CHILDREN will needed). Calling wxKill() passing wxKILL_CHILDREN will
kill this process as well as all of its children (except those which have kill this process as well as all of its children (except those which have
started their own session). started their own session).
The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking 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 place while the child process is running. It should be only used for very
short-lived processes as otherwise the application windows risk becoming short-lived processes as otherwise the application windows risk becoming
unresponsive from the users point of view. As this flag only makes sense with 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 @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags
is provided as a convenience. is provided as a convenience.
Finally, you may use the third overloaded version of this function to execute 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 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 @c wxEXEC_SYNC) and capture its output in the array @e output. The
fourth version adds the possibility to additionally capture the messages from fourth version adds the possibility to additionally capture the messages from
standard error output in the @a errors array. standard error output in the @a errors array.
@b NB: Currently wxExecute() can only be used from the main thread, calling @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 this function from another thread will result in an assert failure in debug
build and won't work. build and won't work.
@param command @param command
The command to execute and any parameters to pass to it as a The command to execute and any parameters to pass to it as a
single string. single string.
@param argv @param argv
The command to execute should be the first element of this The command to execute should be the first element of this
array, any additional ones are the command parameters and the array must be array, any additional ones are the command parameters and the array must be
terminated with a @NULL pointer. terminated with a @NULL pointer.
@param flags @param flags
Combination of bit masks wxEXEC_ASYNC, Combination of bit masks wxEXEC_ASYNC,
wxEXEC_SYNC and wxEXEC_NOHIDE wxEXEC_SYNC and wxEXEC_NOHIDE
@param callback @param callback
An optional pointer to wxProcess An optional pointer to wxProcess
@see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample". @see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample".
*/ */
long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC, long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC,
wxProcess* callback = NULL); wxProcess* callback = NULL);
wxPerl note: long wxExecute(char** argv, wxPerl note: long wxExecute(char** argv,
int flags = wxEXEC_ASYNC, int flags = wxEXEC_ASYNC,
wxProcess* callback = NULL); wxProcess* callback = NULL);
wxPerl note: long wxExecute(const wxString& command, wxPerl note: long wxExecute(const wxString& command,
wxArrayString& output, wxArrayString& output,
int flags = 0); int flags = 0);
wxPerl note: long wxExecute(const wxString& command, wxPerl note: long wxExecute(const wxString& command,
wxArrayString& output, wxArrayString& output,
wxArrayString& errors, wxArrayString& errors,
int flags = 0); int flags = 0);
//@} //@}
/** /**
Returns a string representing the current date and time. Returns a string representing the current date and time.
*/ */
wxString wxNow(); wxString wxNow();
/** /**
Returns @true if the operating system the program is running under is 64 bit. 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 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) 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 since the program could be running in emulation mode or in a mixed 32/64 bit
system system
(bi-architecture operating system). (bi-architecture operating system).
Very important: this function is not 100% reliable on some systems given the Very important: this function is not 100% reliable on some systems given the
fact fact
that there isn't always a standard way to do a reliable check on the OS that there isn't always a standard way to do a reliable check on the OS
architecture. architecture.
*/ */
bool wxIsPlatform64Bit(); bool wxIsPlatform64Bit();
/** /**
Returns the number uniquely identifying the current process in the system. Returns the number uniquely identifying the current process in the system.
If an error occurs, 0 is returned. If an error occurs, 0 is returned.
*/ */
unsigned long wxGetProcessId(); unsigned long wxGetProcessId();
/** /**
Equivalent to the Unix kill function: send the given signal @a sig to the Equivalent to the Unix kill function: send the given signal @a sig to the
process with PID @e pid. The valid signal values are process with PID @e pid. The valid signal values are
@code @code
enum wxSignal enum wxSignal
{ {
wxSIGNONE = 0, // verify if the process exists under Unix wxSIGNONE = 0, // verify if the process exists under Unix
wxSIGHUP, wxSIGHUP,
wxSIGINT, wxSIGINT,
wxSIGQUIT, wxSIGQUIT,
wxSIGILL, wxSIGILL,
wxSIGTRAP, wxSIGTRAP,
wxSIGABRT, wxSIGABRT,
wxSIGEMT, wxSIGEMT,
wxSIGFPE, wxSIGFPE,
wxSIGKILL, // forcefully kill, dangerous! wxSIGKILL, // forcefully kill, dangerous!
wxSIGBUS, wxSIGBUS,
wxSIGSEGV, wxSIGSEGV,
wxSIGSYS, wxSIGSYS,
wxSIGPIPE, wxSIGPIPE,
wxSIGALRM, wxSIGALRM,
wxSIGTERM // terminate the process gently wxSIGTERM // terminate the process gently
}; };
@endcode @endcode
@c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning
under both Unix and Windows but all the other signals are equivalent to under both Unix and Windows but all the other signals are equivalent to
@c wxSIGTERM under Windows. @c wxSIGTERM under Windows.
Returns 0 on success, -1 on failure. If @a rc parameter is not @NULL, it will 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: be filled with an element of @c wxKillError enum:
@code @code
enum wxKillError enum wxKillError
{ {
wxKILL_OK, // no error wxKILL_OK, // no error
wxKILL_BAD_SIGNAL, // no such signal wxKILL_BAD_SIGNAL, // no such signal
wxKILL_ACCESS_DENIED, // permission denied wxKILL_ACCESS_DENIED, // permission denied
wxKILL_NO_PROCESS, // no such process wxKILL_NO_PROCESS, // no such process
wxKILL_ERROR // another, unspecified error wxKILL_ERROR // another, unspecified error
}; };
@endcode @endcode
The @a flags parameter can be wxKILL_NOCHILDREN (the default), The @a flags parameter can be wxKILL_NOCHILDREN (the default),
or wxKILL_CHILDREN, in which case the child processes of this or wxKILL_CHILDREN, in which case the child processes of this
process will be killed too. Note that under Unix, for wxKILL_CHILDREN 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 work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER
to wxExecute. to wxExecute.
@see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample" @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample"
*/ */
int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL, int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL,
int flags = 0); int flags = 0);
/** /**
Returns the current state of the mouse. Returns a wxMouseState Returns the current state of the mouse. Returns a wxMouseState
instance that contains the current position of the mouse pointer in instance that contains the current position of the mouse pointer in
screen coordinates, as well as boolean values indicating the up/down screen coordinates, as well as boolean values indicating the up/down
status of the mouse buttons and the modifier keys. status of the mouse buttons and the modifier keys.
*/ */
wxMouseState wxGetMouseState(); wxMouseState wxGetMouseState();
/** /**
Returns @true if between two wxBeginBusyCursor() and Returns @true if between two wxBeginBusyCursor() and
wxEndBusyCursor() calls. wxEndBusyCursor() calls.
See also wxBusyCursor. See also wxBusyCursor.
*/ */
bool wxIsBusy(); bool wxIsBusy();
//@{ //@{
/** /**
Copies the user's email address into the supplied buffer, by Copies the user's email address into the supplied buffer, by
concatenating the values returned by wxGetFullHostName() concatenating the values returned by wxGetFullHostName()
and wxGetUserId(). and wxGetUserId().
Returns @true if successful, @false otherwise. Returns @true if successful, @false otherwise.
*/ */
wxString wxGetEmailAddress(); wxString wxGetEmailAddress();
bool wxGetEmailAddress(char* buf, int sz); bool wxGetEmailAddress(char* buf, int sz);
//@} //@}
/** /**
Sleeps for the specified number of seconds. Sleeps for the specified number of seconds.
*/ */
void wxSleep(int secs); void wxSleep(int secs);
/** /**
Sets the value of the environment variable @a var (adding it if necessary) Sets the value of the environment variable @a var (adding it if necessary)
to @e value. to @e value.
Returns @true on success. Returns @true on success.
@see wxUnsetEnv() @see wxUnsetEnv()
*/ */
bool wxSetEnv(const wxString& var, const wxString& value); bool wxSetEnv(const wxString& var, const wxString& value);
/** /**
Returns @true if the current platform is little endian (instead of big Returns @true if the current platform is little endian (instead of big
endian). endian).
The check is performed at run-time. The check is performed at run-time.
@see @ref overview_byteordermacros "Byte order macros" @see @ref overview_byteordermacros "Byte order macros"
*/ */
bool wxIsPlatformLittleEndian(); bool wxIsPlatformLittleEndian();
/** /**
Under X only, sets the current display name. This is the X host and display Under X only, sets the current display name. This is the X host and display
name such name such
as "colonsay:0.0", and the function indicates which display should be used for as "colonsay:0.0", and the function indicates which display should be used for
creating creating
windows from this point on. Setting the display within an application allows windows from this point on. Setting the display within an application allows
multiple multiple
displays to be used. displays to be used.
See also wxGetDisplayName(). See also wxGetDisplayName().
*/ */
void wxSetDisplayName(const wxString& displayName); void wxSetDisplayName(const wxString& displayName);