]>
git.saurik.com Git - wxWidgets.git/blob - interface/utils.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxWindowDisabler
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxWindowDisabler
13 This class disables all windows of the application (may be with the exception
14 of one of them) in its constructor and enables them back in its destructor.
16 This is useful when you want to indicate to the user that the application
17 is currently busy and cannot respond to user input.
24 class wxWindowDisabler
28 Disables all top level windows of the applications.
30 If @a disable is @c false nothing is done. This can be convenient if
31 the windows should be disabled depending on some condition.
35 wxWindowDisabler(bool disable
= true);
38 Disables all top level windows of the applications with the exception of
39 @a winToSkip if it is not @NULL.
41 wxWindowDisabler(wxWindow
* winToSkip
);
44 Reenables back the windows disabled by the constructor.
55 This class makes it easy to tell your user that the program is temporarily busy.
56 Just create a wxBusyCursor object on the stack, and within the current scope,
57 the hourglass will be shown.
64 for (int i = 0; i 100000; i++)
68 It works by calling wxBeginBusyCursor() in the constructor,
69 and wxEndBusyCursor() in the destructor.
74 @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler
80 Constructs a busy cursor object, calling wxBeginBusyCursor().
82 wxBusyCursor(wxCursor
* cursor
= wxHOURGLASS_CURSOR
);
85 Destroys the busy cursor object, calling wxEndBusyCursor().
92 // ============================================================================
93 // Global functions/macros
94 // ============================================================================
97 /** @ingroup group_funcmacro_dialog */
101 Changes the cursor to the given cursor for all windows in the application.
102 Use wxEndBusyCursor() to revert the cursor back to its previous state.
103 These two calls can be nested, and a counter ensures that only the outer
106 @see wxIsBusy(), wxBusyCursor
110 void wxBeginBusyCursor(wxCursor
* cursor
= wxHOURGLASS_CURSOR
);
113 Changes the cursor back to the original cursor, for all windows in the
114 application. Use with wxBeginBusyCursor().
116 @see wxIsBusy(), wxBusyCursor
120 void wxEndBusyCursor();
123 Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor()
133 Ring the system bell.
135 @note This function is categorized as a GUI one and so is not thread-safe.
142 Shows a message box with the information about the wxWidgets build used,
143 including its version, most important build parameters and the version of
144 the underlying GUI toolkit. This is mainly used for diagnostic purposes
145 and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which
146 doesn't otherwise handle this event.
152 void wxInfoMessageBox(wxWindow parent
= NULL
);
158 /** @ingroup group_funcmacro_env */
162 This is a macro defined as @c getenv() or its wide char version in Unicode
165 Note that under Win32 it may not return correct value for the variables set
166 with wxSetEnv(), use wxGetEnv() function instead.
170 wxChar
* wxGetenv(const wxString
& var
);
173 Returns the current value of the environment variable @c var in @c value.
174 @c value may be @NULL if you just want to know if the variable exists and
175 are not interested in its value.
177 Returns @true if the variable exists, @false otherwise.
181 bool wxGetEnv(const wxString
& var
, wxString
* value
);
184 Sets the value of the environment variable @c var (adding it if necessary)
187 Returns @true on success.
193 bool wxSetEnv(const wxString
& var
, const wxString
& value
);
196 Removes the variable @c var from the environment. wxGetEnv() will return
197 @NULL after the call to this function.
199 Returns @true on success.
203 bool wxUnsetEnv(const wxString
& var
);
209 /** @ingroup group_funcmacro_log */
213 @deprecated Replaced by wxLogDebug().
215 Displays a debugging message. Under Windows, this will appear on the
216 debugger command window, and under Unix, it will be written to standard
219 The syntax is identical to @e printf(), pass a format string and a variable
222 @note Under Windows, if your application crashes before the message appears
223 in the debugging window, put a wxYield() call after each wxDebugMsg()
224 call. wxDebugMsg() seems to be broken under WIN32s (at least for
225 Watcom C++): preformat your messages and use OutputDebugString
230 void wxDebugMsg(const wxString
& format
, ... );
233 @deprecated Replaced by wxLogFatalError().
235 Displays @a message and exits. This writes to standard error under Unix,
236 and pops up a message box under Windows. Used for fatal internal wxWidgets
243 void wxFatalError(const wxString
& message
,
244 const wxString
& title
= "wxWidgets Fatal Error");
247 @deprecated Replaced by wxLogError().
249 Displays @a message and continues. This writes to standard error under
250 Unix, and pops up a message box under Windows. Used for internal wxWidgets
257 void wxError(const wxString
& message
,
258 const wxString
& title
= "wxWidgets Internal Error");
265 Returns the type of power source as one of @c wxPOWER_SOCKET,
266 @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN.
267 @c wxPOWER_UNKNOWN is also the default on platforms where this
268 feature is not implemented (currently everywhere but MS Windows).
272 wxPowerType
wxGetPowerType();
276 This function returns the "user id" also known as "login name" under Unix i.e.
277 something like "jsmith". It uniquely identifies the current user (on this
279 Under Windows or NT, this function first looks in the environment
280 variables USER and LOGNAME; if neither of these is found, the entry @b UserId
281 in the @b wxWidgets section of the WIN.INI file is tried.
282 The first variant of this function returns the login name if successful or an
283 empty string otherwise. The second (deprecated) function returns @true
284 if successful, @false otherwise.
290 wxString
wxGetUserId();
291 bool wxGetUserId(char* buf
, int sz
);
295 Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
296 @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
297 @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
298 @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where
299 this feature is not implemented (currently everywhere but MS Windows).
303 wxBatteryState
wxGetBatteryState();
306 @b NB: This function is obsolete, please use
307 wxWindow::FindWindowByName instead.
308 Find a window by its name (as given in a window constructor or @b Create
310 If @a parent is @NULL, the search will start from all top-level
311 frames and dialog boxes; if non-@NULL, the search will be limited to the given
313 The search is recursive in both cases.
314 If no such named window is found, @b wxFindWindowByLabel is called.
318 wxWindow
* wxFindWindowByName(const wxString
& name
,
319 wxWindow
* parent
= NULL
);
322 This function is deprecated as the ids generated by it can conflict with the
323 ids defined by the user code, use @c wxID_ANY to assign ids which are
324 guaranteed to not conflict with the user-defined ids for the controls and menu
325 items you create instead of using this function.
327 Generates an integer identifier unique to this run of the program.
334 Ensures that ids subsequently generated by @b NewId do not clash with
339 void wxRegisterId(long id
);
342 For normal keys, returns @true if the specified key is currently down.
343 For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns
344 @true if the key is toggled such that its LED indicator is lit. There is
345 currently no way to test whether togglable keys are up or down.
346 Even though there are virtual key codes defined for mouse buttons, they
347 cannot be used with this function currently.
351 bool wxGetKeyState(wxKeyCode key
);
354 Returns the string containing the description of the current platform in a
355 user-readable form. For example, this function may return strings like
356 @c Windows NT Version 4.0 or @c Linux 2.2.2 i386.
358 @see ::wxGetOsVersion
362 wxString
wxGetOsDescription();
365 Return the (current) user's home directory.
367 @see wxGetUserHome(), wxStandardPaths
371 wxString
wxGetHomeDir();
374 Sleeps for the specified number of milliseconds. Notice that usage of this
375 function is encouraged instead of calling usleep(3) directly because the
376 standard usleep() function is not MT safe.
380 void wxMilliSleep(unsigned long milliseconds
);
383 Sleeps for the specified number of microseconds. The microsecond resolution may
384 not, in fact, be available on all platforms (currently only Unix platforms with
385 nanosleep(2) may provide it) in which case this is the same as
386 wxMilliSleep()(@e microseconds/1000).
390 void wxMicroSleep(unsigned long microseconds
);
394 Find a menu item identifier associated with the given frame's menu bar.
398 int wxFindMenuItemId(wxFrame
* frame
, const wxString
& menuString
,
399 const wxString
& itemString
);
402 This function enables or disables all top level windows. It is used by
407 void wxEnableTopLevelWindows(bool enable
= true);
410 Strips any menu codes from @a str and returns the result.
411 By default, the functions strips both the mnemonics character (@c '')
412 which is used to indicate a keyboard shortkey, and the accelerators, which are
413 used only in the menu items and are separated from the main text by the
414 @c \t (TAB) character. By using @a flags of
415 @c wxStrip_Mnemonics or @c wxStrip_Accel to strip only the former
416 or the latter part, respectively.
417 Notice that in most cases
418 wxMenuItem::GetLabelFromText or
419 wxControl::GetLabelText can be used instead.
423 wxString
wxStripMenuCodes(const wxString
& str
,
424 int flags
= wxStrip_All
);
427 Open the @a url in user's default browser. If @a flags parameter contains
428 @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
429 (currently this is only supported under Windows). The @a url may also be a
430 local file path (with or without @c file:// prefix), if it doesn't
431 correspond to an existing file and the URL has no scheme @c http:// is
432 prepended to it by default.
433 Returns @true if the application was successfully launched.
434 Note that for some configurations of the running user, the application which
435 is launched to open the given URL may be URL-dependent (e.g. a browser may be
437 local URLs while another one may be used for remote URLs).
441 bool wxLaunchDefaultBrowser(const wxString
& url
, int flags
= 0);
444 Executes a command in an interactive shell window. If no command is
445 specified, then just the shell is spawned.
446 See also wxExecute(), @ref overview_sampleexec "Exec sample".
450 bool wxShell(const wxString
& command
= NULL
);
453 Gets the version and the operating system ID for currently running OS.
454 See wxPlatformInfo for more details about wxOperatingSystemId.
456 @see ::wxGetOsDescription, wxPlatformInfo
460 wxOperatingSystemId
wxGetOsVersion(int* major
= NULL
,
464 Returns the FQDN (fully qualified domain host name) or an empty string on
471 wxString
wxGetFullHostName();
474 Tells the system to delete the specified object when
475 all other events have been processed. In some environments, it is
476 necessary to use this instead of deleting a frame directly with the
477 delete operator, because some GUIs will still send events to a deleted window.
478 Now obsolete: use wxWindow::Close instead.
482 void wxPostDelete(wxObject
* object
);
485 @b NB: This function is obsolete, please use
486 wxWindow::FindWindowByLabel instead.
487 Find a window by its label. Depending on the type of window, the label may be a
489 or panel item label. If @a parent is @NULL, the search will start from all
491 frames and dialog boxes; if non-@NULL, the search will be limited to the given
493 The search is recursive in both cases.
497 wxWindow
* wxFindWindowByLabel(const wxString
& label
,
498 wxWindow
* parent
= NULL
);
502 Returns the mouse position in screen coordinates.
506 wxPoint
wxGetMousePosition();
509 Loads a user-defined Windows resource as a string. If the resource is found,
511 a new character array and copies the data into it. A pointer to this data is
512 returned. If unsuccessful, @NULL is returned.
513 The resource must be defined in the @c .rc file using the following syntax:
516 myResource TEXT file.ext
519 where @c file.ext is a file that the resource compiler can find.
520 This function is available under Windows only.
524 wxString
wxLoadUserResource(const wxString
& resourceName
,
525 const wxString
& resourceType
= "TEXT");
528 Returns the amount of free memory in bytes under environments which
529 support it, and -1 if not supported or failed to perform measurement.
531 wxMemorySize
wxGetFreeMemory();
535 Copies the current host machine's name into the supplied buffer. Please note
536 that the returned name is @e not fully qualified, i.e. it does not include
538 Under Windows or NT, this function first looks in the environment
539 variable SYSTEM_NAME; if this is not found, the entry @b HostName
540 in the @b wxWidgets section of the WIN.INI file is tried.
541 The first variant of this function returns the hostname if successful or an
542 empty string otherwise. The second (deprecated) function returns @true
543 if successful, @false otherwise.
545 @see wxGetFullHostName()
549 wxString
wxGetHostName();
550 bool wxGetHostName(char* buf
, int sz
);
554 Under X only, returns the current display name. See also wxSetDisplayName().
558 wxString
wxGetDisplayName();
561 Returns the home directory for the given user. If the @a user is empty
562 (default value), this function behaves like
563 wxGetHomeDir() i.e. returns the current user home
565 If the home directory couldn't be determined, an empty string is returned.
569 wxString
wxGetUserHome(const wxString
& user
= "");
573 @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr
574 and it only takes the @c command argument,
575 and returns a 3-element list @c ( status, output, errors ), where
576 @c output and @c errors are array references.
577 Executes another program in Unix or Windows.
578 The first form takes a command string, such as @c "emacs file.txt".
579 The second form takes an array of values: a command, any number of
580 arguments, terminated by @NULL.
581 The semantics of the third and fourth versions is different from the first two
582 and is described in more details below.
583 If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow
584 of control immediately returns. If it contains @c wxEXEC_SYNC, the current
585 application waits until the other program has terminated.
586 In the case of synchronous execution, the return value is the exit code of
587 the process (which terminates by the moment the function returns) and will be
588 -1 if the process couldn't be started and typically 0 if the process
589 terminated successfully. Also, while waiting for the process to
590 terminate, wxExecute will call wxYield(). Because of this, by
591 default this function disables all application windows to avoid unexpected
592 reentrancies which could result from the users interaction with the program
593 while the child process is running. If you are sure that it is safe to not
594 disable the program windows, you may pass @c wxEXEC_NODISABLE flag to
595 prevent this automatic disabling from happening.
596 For asynchronous execution, however, the return value is the process id and
597 zero value indicates that the command could not be executed. As an added
598 complication, the return value of -1 in this case indicates that we didn't
599 launch a new process, but connected to the running one (this can only happen in
600 case of using DDE under Windows for command execution). In particular, in this,
601 and only this, case the calling code will not get the notification about
603 If callback isn't @NULL and if execution is asynchronous,
604 wxProcess::OnTerminate will be called when
605 the process finishes. Specifying this parameter also allows you to redirect the
606 standard input and/or output of the process being launched by calling
607 wxProcess::Redirect. If the child process IO is redirected,
608 under Windows the process window is not shown by default (this avoids having to
609 flush an unnecessary console for the processes which don't create any windows
610 anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from
611 happening, i.e. with this flag the child process window will be shown normally.
612 Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure
613 that the new process is a group leader (this will create a new session if
614 needed). Calling wxKill() passing wxKILL_CHILDREN will
615 kill this process as well as all of its children (except those which have
616 started their own session).
617 The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
618 place while the child process is running. It should be only used for very
619 short-lived processes as otherwise the application windows risk becoming
620 unresponsive from the users point of view. As this flag only makes sense with
621 @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags
622 is provided as a convenience.
623 Finally, you may use the third overloaded version of this function to execute
624 a process (always synchronously, the contents of @a flags is or'd with
625 @c wxEXEC_SYNC) and capture its output in the array @e output. The
626 fourth version adds the possibility to additionally capture the messages from
627 standard error output in the @a errors array.
628 @b NB: Currently wxExecute() can only be used from the main thread, calling
629 this function from another thread will result in an assert failure in debug
630 build and won't work.
633 The command to execute and any parameters to pass to it as a
636 The command to execute should be the first element of this
637 array, any additional ones are the command parameters and the array must be
638 terminated with a @NULL pointer.
640 Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
641 wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
642 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
643 their combination, in wxEXEC_SYNC case.
645 An optional pointer to wxProcess
647 @see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample".
651 long wxExecute(const wxString
& command
,
652 int sync
= wxEXEC_ASYNC
,
653 wxProcess
* callback
= NULL
);
654 long wxExecute(char** argv
,
655 int flags
= wxEXEC_ASYNC
,
656 wxProcess
* callback
= NULL
);
657 long wxExecute(wchar_t** argv
,
658 int flags
= wxEXEC_ASYNC
,
659 wxProcess
* callback
= NULL
);
660 long wxExecute(const wxString
& command
,
661 wxArrayString
& output
,
663 long wxExecute(const wxString
& command
,
664 wxArrayString
& output
,
665 wxArrayString
& errors
,
670 Returns a string representing the current date and time.
677 Returns @true if the operating system the program is running under is 64 bit.
678 The check is performed at run-time and may differ from the value available at
679 compile-time (at compile-time you can just check if @c sizeof(void*)==8)
680 since the program could be running in emulation mode or in a mixed 32/64 bit
682 (bi-architecture operating system).
683 Very important: this function is not 100% reliable on some systems given the
685 that there isn't always a standard way to do a reliable check on the OS
690 bool wxIsPlatform64Bit();
693 Returns the number uniquely identifying the current process in the system.
694 If an error occurs, 0 is returned.
698 unsigned long wxGetProcessId();
701 Equivalent to the Unix kill function: send the given signal @a sig to the
702 process with PID @e pid. The valid signal values are
707 wxSIGNONE = 0, // verify if the process exists under Unix
716 wxSIGKILL, // forcefully kill, dangerous!
722 wxSIGTERM // terminate the process gently
726 @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning
727 under both Unix and Windows but all the other signals are equivalent to
728 @c wxSIGTERM under Windows.
729 Returns 0 on success, -1 on failure. If @a rc parameter is not @NULL, it will
730 be filled with an element of @c wxKillError enum:
735 wxKILL_OK, // no error
736 wxKILL_BAD_SIGNAL, // no such signal
737 wxKILL_ACCESS_DENIED, // permission denied
738 wxKILL_NO_PROCESS, // no such process
739 wxKILL_ERROR // another, unspecified error
743 The @a flags parameter can be wxKILL_NOCHILDREN (the default),
744 or wxKILL_CHILDREN, in which case the child processes of this
745 process will be killed too. Note that under Unix, for wxKILL_CHILDREN
746 to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER
749 @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample"
753 int wxKill(long pid
, int sig
= wxSIGTERM
, wxKillError rc
= NULL
,
757 Returns the current state of the mouse. Returns a wxMouseState
758 instance that contains the current position of the mouse pointer in
759 screen coordinates, as well as boolean values indicating the up/down
760 status of the mouse buttons and the modifier keys.
764 wxMouseState
wxGetMouseState();
768 Copies the user's email address into the supplied buffer, by
769 concatenating the values returned by wxGetFullHostName()
771 Returns @true if successful, @false otherwise.
775 wxString
wxGetEmailAddress();
776 bool wxGetEmailAddress(char* buf
, int sz
);
780 Sleeps for the specified number of seconds.
784 void wxSleep(int secs
);
787 Returns @true if the current platform is little endian (instead of big
789 The check is performed at run-time.
791 @see @ref overview_byteordermacros "Byte order macros"
795 bool wxIsPlatformLittleEndian();
798 Under X only, sets the current display name. This is the X host and display
800 as "colonsay:0.0", and the function indicates which display should be used for
802 windows from this point on. Setting the display within an application allows
805 See also wxGetDisplayName().
809 void wxSetDisplayName(const wxString
& displayName
);