]>
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_misc */
213 Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
214 @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
215 @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
216 @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this
217 feature is not implemented (currently everywhere but MS Windows).
221 wxBatteryState
wxGetBatteryState();
224 Returns the type of power source as one of @c wxPOWER_SOCKET,
225 @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the
226 default on platforms where this feature is not implemented (currently
227 everywhere but MS Windows).
231 wxPowerType
wxGetPowerType();
234 Under X only, returns the current display name.
236 @see wxSetDisplayName()
240 wxString
wxGetDisplayName();
243 For normal keys, returns @true if the specified key is currently down.
245 For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if
246 the key is toggled such that its LED indicator is lit. There is currently
247 no way to test whether togglable keys are up or down.
249 Even though there are virtual key codes defined for mouse buttons, they
250 cannot be used with this function currently.
254 bool wxGetKeyState(wxKeyCode key
);
257 Returns the mouse position in screen coordinates.
261 wxPoint
wxGetMousePosition();
264 Returns the current state of the mouse. Returns a wxMouseState instance
265 that contains the current position of the mouse pointer in screen
266 coordinates, as well as boolean values indicating the up/down status of the
267 mouse buttons and the modifier keys.
271 wxMouseState
wxGetMouseState();
274 This function enables or disables all top level windows. It is used by
279 void wxEnableTopLevelWindows(bool enable
= true);
282 Find the deepest window at the given mouse position in screen coordinates,
283 returning the window if found, or @NULL if not.
287 wxWindow
* wxFindWindowAtPoint(const wxPoint
& pt
);
290 @deprecated Replaced by wxWindow::FindWindowByLabel().
292 Find a window by its label. Depending on the type of window, the label may
293 be a window title or panel item label. If @a parent is @NULL, the search
294 will start from all top-level frames and dialog boxes; if non-@NULL, the
295 search will be limited to the given window hierarchy. The search is
296 recursive in both cases.
300 wxWindow
* wxFindWindowByLabel(const wxString
& label
,
301 wxWindow
* parent
= NULL
);
304 @deprecated Replaced by wxWindow::FindWindowByName().
306 Find a window by its name (as given in a window constructor or @e Create
307 function call). If @a parent is @NULL, the search will start from all
308 top-level frames and dialog boxes; if non-@NULL, the search will be limited
309 to the given window hierarchy. The search is recursive in both cases.
311 If no such named window is found, wxFindWindowByLabel() is called.
315 wxWindow
* wxFindWindowByName(const wxString
& name
, wxWindow
* parent
= NULL
);
318 Find a menu item identifier associated with the given frame's menu bar.
322 int wxFindMenuItemId(wxFrame
* frame
, const wxString
& menuString
,
323 const wxString
& itemString
);
326 @deprecated Ids generated by it can conflict with the Ids defined by the
327 user code, use @c wxID_ANY to assign ids which are guaranteed
328 to not conflict with the user-defined ids for the controls and
329 menu items you create instead of using this function.
331 Generates an integer identifier unique to this run of the program.
338 Ensures that Ids subsequently generated by wxNewId() do not clash with the
343 void wxRegisterId(long id
);
346 Opens the @a url in user's default browser. If the @a flags parameter
347 contains @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
348 (currently this is only supported under Windows). The @a url may also be a
349 local file path (with or without the "file://" prefix), if it doesn't
350 correspond to an existing file and the URL has no scheme "http://" is
351 prepended to it by default.
353 Returns @true if the application was successfully launched.
355 @note For some configurations of the running user, the application which is
356 launched to open the given URL may be URL-dependent (e.g. a browser
357 may be used for local URLs while another one may be used for remote
362 bool wxLaunchDefaultBrowser(const wxString
& url
, int flags
= 0);
365 Loads a user-defined Windows resource as a string. If the resource is
366 found, the function creates a new character array and copies the data into
367 it. A pointer to this data is returned. If unsuccessful, @NULL is returned.
369 The resource must be defined in the @c .rc file using the following syntax:
372 myResource TEXT file.ext
375 Where @c file.ext is a file that the resource compiler can find.
377 This function is available under Windows only.
381 wxString
wxLoadUserResource(const wxString
& resourceName
,
382 const wxString
& resourceType
= "TEXT");
385 @deprecated Replaced by wxWindow::Close(). See the
386 @ref overview_windowdeletion "window deletion overview".
388 Tells the system to delete the specified object when all other events have
389 been processed. In some environments, it is necessary to use this instead
390 of deleting a frame directly with the delete operator, because some GUIs
391 will still send events to a deleted window.
395 void wxPostDelete(wxObject
* object
);
398 Under X only, sets the current display name. This is the X host and display
399 name such as "colonsay:0.0", and the function indicates which display
400 should be used for creating windows from this point on. Setting the display
401 within an application allows multiple displays to be used.
403 @see wxGetDisplayName()
407 void wxSetDisplayName(const wxString
& displayName
);
410 Strips any menu codes from @a str and returns the result.
412 By default, the functions strips both the mnemonics character (@c '&')
413 which is used to indicate a keyboard shortkey, and the accelerators, which
414 are used only in the menu items and are separated from the main text by the
415 @c \t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
416 @c wxStrip_Accel to strip only the former or the latter part, respectively.
418 Notice that in most cases wxMenuItem::GetLabelFromText() or
419 wxControl::GetLabelText() can be used instead.
423 wxString
wxStripMenuCodes(const wxString
& str
, int flags
= wxStrip_All
);
433 This function returns the "user id" also known as "login name" under Unix
434 i.e. something like "jsmith". It uniquely identifies the current user (on
435 this system). Under Windows or NT, this function first looks in the
436 environment variables USER and LOGNAME; if neither of these is found, the
437 entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
439 @return Returns the login name if successful or an empty string otherwise.
445 wxString
wxGetUserId();
449 This form is deprecated, use wxGetUserId() version that returns wxString.
451 @param buf Buffer to store login name in.
452 @param sz Size of the buffer.
454 @return Returns @true if successful, @false otherwise.
456 bool wxGetUserId(char* buf
, int sz
);
459 Returns the string containing the description of the current platform in a
460 user-readable form. For example, this function may return strings like
461 @c Windows NT Version 4.0 or @c Linux 2.2.2 i386.
463 @see ::wxGetOsVersion
467 wxString
wxGetOsDescription();
470 Return the (current) user's home directory.
472 @see wxGetUserHome(), wxStandardPaths
476 wxString
wxGetHomeDir();
479 Sleeps for the specified number of milliseconds. Notice that usage of this
480 function is encouraged instead of calling usleep(3) directly because the
481 standard usleep() function is not MT safe.
485 void wxMilliSleep(unsigned long milliseconds
);
488 Sleeps for the specified number of microseconds. The microsecond resolution may
489 not, in fact, be available on all platforms (currently only Unix platforms with
490 nanosleep(2) may provide it) in which case this is the same as
491 wxMilliSleep()(@e microseconds/1000).
495 void wxMicroSleep(unsigned long microseconds
);
498 Executes a command in an interactive shell window. If no command is
499 specified, then just the shell is spawned.
500 See also wxExecute(), @ref overview_sampleexec "Exec sample".
504 bool wxShell(const wxString
& command
= NULL
);
507 Gets the version and the operating system ID for currently running OS.
508 See wxPlatformInfo for more details about wxOperatingSystemId.
510 @see ::wxGetOsDescription, wxPlatformInfo
514 wxOperatingSystemId
wxGetOsVersion(int* major
= NULL
,
518 Returns the FQDN (fully qualified domain host name) or an empty string on
525 wxString
wxGetFullHostName();
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 Returns the home directory for the given user. If the @a user is empty
555 (default value), this function behaves like
556 wxGetHomeDir() i.e. returns the current user home
558 If the home directory couldn't be determined, an empty string is returned.
562 wxString
wxGetUserHome(const wxString
& user
= "");
566 @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr
567 and it only takes the @c command argument,
568 and returns a 3-element list @c ( status, output, errors ), where
569 @c output and @c errors are array references.
570 Executes another program in Unix or Windows.
571 The first form takes a command string, such as @c "emacs file.txt".
572 The second form takes an array of values: a command, any number of
573 arguments, terminated by @NULL.
574 The semantics of the third and fourth versions is different from the first two
575 and is described in more details below.
576 If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow
577 of control immediately returns. If it contains @c wxEXEC_SYNC, the current
578 application waits until the other program has terminated.
579 In the case of synchronous execution, the return value is the exit code of
580 the process (which terminates by the moment the function returns) and will be
581 -1 if the process couldn't be started and typically 0 if the process
582 terminated successfully. Also, while waiting for the process to
583 terminate, wxExecute will call wxYield(). Because of this, by
584 default this function disables all application windows to avoid unexpected
585 reentrancies which could result from the users interaction with the program
586 while the child process is running. If you are sure that it is safe to not
587 disable the program windows, you may pass @c wxEXEC_NODISABLE flag to
588 prevent this automatic disabling from happening.
589 For asynchronous execution, however, the return value is the process id and
590 zero value indicates that the command could not be executed. As an added
591 complication, the return value of -1 in this case indicates that we didn't
592 launch a new process, but connected to the running one (this can only happen in
593 case of using DDE under Windows for command execution). In particular, in this,
594 and only this, case the calling code will not get the notification about
596 If callback isn't @NULL and if execution is asynchronous,
597 wxProcess::OnTerminate will be called when
598 the process finishes. Specifying this parameter also allows you to redirect the
599 standard input and/or output of the process being launched by calling
600 wxProcess::Redirect. If the child process IO is redirected,
601 under Windows the process window is not shown by default (this avoids having to
602 flush an unnecessary console for the processes which don't create any windows
603 anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from
604 happening, i.e. with this flag the child process window will be shown normally.
605 Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure
606 that the new process is a group leader (this will create a new session if
607 needed). Calling wxKill() passing wxKILL_CHILDREN will
608 kill this process as well as all of its children (except those which have
609 started their own session).
610 The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
611 place while the child process is running. It should be only used for very
612 short-lived processes as otherwise the application windows risk becoming
613 unresponsive from the users point of view. As this flag only makes sense with
614 @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags
615 is provided as a convenience.
616 Finally, you may use the third overloaded version of this function to execute
617 a process (always synchronously, the contents of @a flags is or'd with
618 @c wxEXEC_SYNC) and capture its output in the array @e output. The
619 fourth version adds the possibility to additionally capture the messages from
620 standard error output in the @a errors array.
621 @b NB: Currently wxExecute() can only be used from the main thread, calling
622 this function from another thread will result in an assert failure in debug
623 build and won't work.
626 The command to execute and any parameters to pass to it as a
629 The command to execute should be the first element of this
630 array, any additional ones are the command parameters and the array must be
631 terminated with a @NULL pointer.
633 Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
634 wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
635 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
636 their combination, in wxEXEC_SYNC case.
638 An optional pointer to wxProcess
640 @see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample".
644 long wxExecute(const wxString
& command
,
645 int sync
= wxEXEC_ASYNC
,
646 wxProcess
* callback
= NULL
);
647 long wxExecute(char** argv
,
648 int flags
= wxEXEC_ASYNC
,
649 wxProcess
* callback
= NULL
);
650 long wxExecute(wchar_t** argv
,
651 int flags
= wxEXEC_ASYNC
,
652 wxProcess
* callback
= NULL
);
653 long wxExecute(const wxString
& command
,
654 wxArrayString
& output
,
656 long wxExecute(const wxString
& command
,
657 wxArrayString
& output
,
658 wxArrayString
& errors
,
663 Returns a string representing the current date and time.
670 Returns @true if the operating system the program is running under is 64 bit.
671 The check is performed at run-time and may differ from the value available at
672 compile-time (at compile-time you can just check if @c sizeof(void*)==8)
673 since the program could be running in emulation mode or in a mixed 32/64 bit
675 (bi-architecture operating system).
676 Very important: this function is not 100% reliable on some systems given the
678 that there isn't always a standard way to do a reliable check on the OS
683 bool wxIsPlatform64Bit();
686 Returns the number uniquely identifying the current process in the system.
687 If an error occurs, 0 is returned.
691 unsigned long wxGetProcessId();
694 Equivalent to the Unix kill function: send the given signal @a sig to the
695 process with PID @e pid. The valid signal values are
700 wxSIGNONE = 0, // verify if the process exists under Unix
709 wxSIGKILL, // forcefully kill, dangerous!
715 wxSIGTERM // terminate the process gently
719 @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning
720 under both Unix and Windows but all the other signals are equivalent to
721 @c wxSIGTERM under Windows.
722 Returns 0 on success, -1 on failure. If @a rc parameter is not @NULL, it will
723 be filled with an element of @c wxKillError enum:
728 wxKILL_OK, // no error
729 wxKILL_BAD_SIGNAL, // no such signal
730 wxKILL_ACCESS_DENIED, // permission denied
731 wxKILL_NO_PROCESS, // no such process
732 wxKILL_ERROR // another, unspecified error
736 The @a flags parameter can be wxKILL_NOCHILDREN (the default),
737 or wxKILL_CHILDREN, in which case the child processes of this
738 process will be killed too. Note that under Unix, for wxKILL_CHILDREN
739 to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER
742 @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample"
746 int wxKill(long pid
, int sig
= wxSIGTERM
, wxKillError rc
= NULL
,
751 Copies the user's email address into the supplied buffer, by
752 concatenating the values returned by wxGetFullHostName()
754 Returns @true if successful, @false otherwise.
758 wxString
wxGetEmailAddress();
759 bool wxGetEmailAddress(char* buf
, int sz
);
763 Sleeps for the specified number of seconds.
767 void wxSleep(int secs
);
770 Returns @true if the current platform is little endian (instead of big
772 The check is performed at run-time.
774 @see @ref overview_byteordermacros "Byte order macros"
778 bool wxIsPlatformLittleEndian();