]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: progdlg.h | |
e54c96f1 | 3 | // Purpose: interface of wxProgressDialog |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxProgressDialog | |
7c913512 | 11 | |
23324ae1 | 12 | This class represents a dialog that shows a short message and a |
3a567740 | 13 | progress bar. Optionally, it can display ABORT and SKIP buttons, and |
23324ae1 | 14 | the elapsed, remaining and estimated time for the end of the progress. |
7c913512 | 15 | |
3a567740 FM |
16 | Note that you must be aware that wxProgressDialog internally calls |
17 | wxEventLoopBase::YieldFor with @c wxEVT_CATEGORY_UI and @c wxEVT_CATEGORY_USER_INPUT | |
18 | and this may cause unwanted re-entrancies or the out-of-order processing | |
19 | of pending events (to help preventing the last problem if you're using | |
20 | wxProgressDialog in a multi-threaded application you should be sure to use | |
21 | wxThreadEvent for your inter-threads communications). | |
22 | ||
23324ae1 | 23 | @beginStyleTable |
8c6791e4 | 24 | @style{wxPD_APP_MODAL} |
23324ae1 FM |
25 | Make the progress dialog modal. If this flag is not given, it is |
26 | only "locally" modal - that is the input to the parent window is | |
27 | disabled, but not to the other ones. | |
8c6791e4 | 28 | @style{wxPD_AUTO_HIDE} |
23324ae1 FM |
29 | Causes the progress dialog to disappear from screen as soon as the |
30 | maximum value of the progress meter has been reached. | |
8c6791e4 | 31 | @style{wxPD_SMOOTH} |
23324ae1 | 32 | Causes smooth progress of the gauge control. |
8c6791e4 | 33 | @style{wxPD_CAN_ABORT} |
23324ae1 FM |
34 | This flag tells the dialog that it should have a "Cancel" button |
35 | which the user may press. If this happens, the next call to | |
36 | Update() will return @false. | |
8c6791e4 | 37 | @style{wxPD_CAN_SKIP} |
23324ae1 FM |
38 | This flag tells the dialog that it should have a "Skip" button |
39 | which the user may press. If this happens, the next call to | |
40 | Update() will return @true in its skip parameter. | |
8c6791e4 | 41 | @style{wxPD_ELAPSED_TIME} |
23324ae1 FM |
42 | This flag tells the dialog that it should show elapsed time (since |
43 | creating the dialog). | |
8c6791e4 | 44 | @style{wxPD_ESTIMATED_TIME} |
23324ae1 | 45 | This flag tells the dialog that it should show estimated time. |
8c6791e4 | 46 | @style{wxPD_REMAINING_TIME} |
23324ae1 FM |
47 | This flag tells the dialog that it should show remaining time. |
48 | @endStyleTable | |
7c913512 | 49 | |
23324ae1 FM |
50 | @library{wxbase} |
51 | @category{cmndlg} | |
52 | */ | |
53 | class wxProgressDialog : public wxDialog | |
54 | { | |
55 | public: | |
56 | /** | |
57 | Constructor. Creates the dialog, displays it and disables user input | |
b1b95a65 FM |
58 | for other windows, or, if @c wxPD_APP_MODAL flag is not given, for its |
59 | parent window only. | |
3c4f71cc | 60 | |
7c913512 | 61 | @param title |
4cc4bfaf | 62 | Dialog title to show in titlebar. |
7c913512 | 63 | @param message |
4cc4bfaf | 64 | Message displayed above the progress bar. |
7c913512 | 65 | @param maximum |
4cc4bfaf | 66 | Maximum value for the progress bar. |
af237ae4 FM |
67 | In the generic implementation the progress bar is constructed |
68 | only if this value is greater than zero. | |
7c913512 | 69 | @param parent |
4cc4bfaf | 70 | Parent window. |
7c913512 | 71 | @param style |
4cc4bfaf | 72 | The dialog style. See wxProgressDialog. |
23324ae1 FM |
73 | */ |
74 | wxProgressDialog(const wxString& title, const wxString& message, | |
75 | int maximum = 100, | |
4cc4bfaf | 76 | wxWindow* parent = NULL, |
23324ae1 FM |
77 | int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL); |
78 | ||
79 | /** | |
80 | Destructor. Deletes the dialog and enables all top level windows. | |
81 | */ | |
adaaa686 | 82 | virtual ~wxProgressDialog(); |
23324ae1 | 83 | |
af237ae4 FM |
84 | /** |
85 | Returns the last value passed to the Update() function or | |
86 | @c wxNOT_FOUND if the dialog has no progress bar. | |
87 | ||
88 | @since 2.9.0 | |
89 | */ | |
90 | int GetValue() const; | |
91 | ||
92 | /** | |
93 | Returns the maximum value of the progress meter, as passed to | |
94 | the constructor or @c wxNOT_FOUND if the dialog has no progress bar. | |
95 | ||
96 | @since 2.9.0 | |
97 | */ | |
98 | int GetRange() const; | |
99 | ||
100 | /** | |
101 | Returns the last message passed to the Update() function; | |
102 | if you always passed wxEmptyString to Update() then the message | |
103 | set through the constructor is returned. | |
104 | ||
105 | @since 2.9.0 | |
106 | */ | |
107 | wxString GetMessage() const; | |
108 | ||
23324ae1 | 109 | /** |
b1b95a65 FM |
110 | Works like Update() but makes the gauge control run in indeterminate mode |
111 | (see wxGauge documentation); sets the remaining and the estimated time labels | |
112 | (if present) to "Unknown" or to @a newmsg (if it's non-empty); moves the progress | |
113 | bar a bit to indicate that some progress was done. | |
23324ae1 | 114 | */ |
43c48e1e | 115 | virtual bool Pulse(const wxString& newmsg = wxEmptyString, bool* skip = NULL); |
23324ae1 FM |
116 | |
117 | /** | |
b1b95a65 | 118 | Can be used to continue with the dialog, after the user had clicked the "Abort" button. |
23324ae1 FM |
119 | */ |
120 | void Resume(); | |
121 | ||
122 | /** | |
123 | Updates the dialog, setting the progress bar to the new value and, if | |
b1b95a65 | 124 | given changes the message above it. Returns @true unless the "Cancel" button |
23324ae1 | 125 | has been pressed. |
b1b95a65 | 126 | |
23324ae1 | 127 | If @false is returned, the application can either immediately destroy the |
b1b95a65 FM |
128 | dialog or ask the user for the confirmation and if the abort is not confirmed |
129 | the dialog may be resumed with Resume() function. | |
3c4f71cc | 130 | |
7c913512 | 131 | @param value |
b1b95a65 FM |
132 | The new value of the progress meter. It should be less than or equal to |
133 | the maximum value given to the constructor and the dialog is closed if | |
4cc4bfaf | 134 | it is equal to the maximum. |
7c913512 | 135 | @param newmsg |
4cc4bfaf FM |
136 | The new messages for the progress dialog text, if it is |
137 | empty (which is the default) the message is not changed. | |
7c913512 | 138 | @param skip |
b1b95a65 FM |
139 | If "Skip" button was pressed since last Update() call, |
140 | this is set to @true. | |
23324ae1 | 141 | */ |
11e3af6e | 142 | virtual bool Update(int value, const wxString& newmsg = wxEmptyString, |
4cc4bfaf | 143 | bool* skip = NULL); |
23324ae1 | 144 | }; |
e54c96f1 | 145 |