git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: progdlg.h
	3	// Purpose: interface of wxProgressDialog
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxProgressDialog
	11
	12	This class represents a dialog that shows a short message and a
	13	progress bar. Optionally, it can display ABORT and SKIP buttons, and
	14	the elapsed, remaining and estimated time for the end of the progress.
	15
	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
	23	@beginStyleTable
	24	@style{wxPD_APP_MODAL}
	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.
	28	@style{wxPD_AUTO_HIDE}
	29	Causes the progress dialog to disappear from screen as soon as the
	30	maximum value of the progress meter has been reached.
	31	If this style is not present, the dialog will become a modal dialog
	32	(see wxDialog::ShowModal) once the maximum value has been reached;
	33	this results in processing of pending events and may cause
	34	unwanted re-entrancies.
	35	@style{wxPD_SMOOTH}
	36	Causes smooth progress of the gauge control (uses a wxGauge with the
	37	@c wxGA_SMOOTH style).
	38	@style{wxPD_CAN_ABORT}
	39	This flag tells the dialog that it should have a "Cancel" button
	40	which the user may press. If this happens, the next call to
	41	Update() will return @false.
	42	@style{wxPD_CAN_SKIP}
	43	This flag tells the dialog that it should have a "Skip" button
	44	which the user may press. If this happens, the next call to
	45	Update() will return @true in its skip parameter.
	46	@style{wxPD_ELAPSED_TIME}
	47	This flag tells the dialog that it should show elapsed time (since
	48	creating the dialog).
	49	@style{wxPD_ESTIMATED_TIME}
	50	This flag tells the dialog that it should show estimated time.
	51	@style{wxPD_REMAINING_TIME}
	52	This flag tells the dialog that it should show remaining time.
	53	@endStyleTable
	54
	55	@library{wxbase}
	56	@category{cmndlg}
	57	*/
	58	class wxProgressDialog : public wxDialog
	59	{
	60	public:
	61	/**
	62	Constructor. Creates the dialog, displays it and disables user input
	63	for other windows, or, if @c wxPD_APP_MODAL flag is not given, for its
	64	parent window only.
	65
	66	@param title
	67	Dialog title to show in titlebar.
	68	@param message
	69	Message displayed above the progress bar.
	70	@param maximum
	71	Maximum value for the progress bar.
	72	In the generic implementation the progress bar is constructed
	73	only if this value is greater than zero.
	74	@param parent
	75	Parent window.
	76	@param style
	77	The dialog style. See wxProgressDialog.
	78	*/
	79	wxProgressDialog(const wxString& title, const wxString& message,
	80	int maximum = 100,
	81	wxWindow* parent = NULL,
	82	int style = wxPD_AUTO_HIDE \| wxPD_APP_MODAL);
	83
	84	/**
	85	Destructor. Deletes the dialog and enables all top level windows.
	86	*/
	87	virtual ~wxProgressDialog();
	88
	89	/**
	90	Returns the last value passed to the Update() function or
	91	@c wxNOT_FOUND if the dialog has no progress bar.
	92
	93	@since 2.9.0
	94	*/
	95	int GetValue() const;
	96
	97	/**
	98	Returns the maximum value of the progress meter, as passed to
	99	the constructor or @c wxNOT_FOUND if the dialog has no progress bar.
	100
	101	@since 2.9.0
	102	*/
	103	int GetRange() const;
	104
	105	/**
	106	Returns the last message passed to the Update() function;
	107	if you always passed wxEmptyString to Update() then the message
	108	set through the constructor is returned.
	109
	110	@since 2.9.0
	111	*/
	112	wxString GetMessage() const;
	113
	114	/**
	115	Like Update() but makes the gauge control run in indeterminate mode.
	116
	117	In indeterminate mode the remaining and the estimated time labels (if
	118	present) are set to to "Unknown" or to @a newmsg (if it's non-empty).
	119	Each call to this function moves the progress bar a bit to indicate
	120	that some progress was done.
	121
	122	@see wxGauge::Pulse(), Update()
	123	*/
	124	virtual bool Pulse(const wxString& newmsg = wxEmptyString, bool* skip = NULL);
	125
	126	/**
	127	Can be used to continue with the dialog, after the user had clicked the "Abort" button.
	128	*/
	129	void Resume();
	130
	131	/**
	132	Changes the maximum value of the progress meter given in the constructor.
	133	This function can only be called (with a positive value) if the value passed
	134	in the constructor was positive.
	135
	136	@since 2.9.1
	137	*/
	138	void SetRange(int maximum);
	139
	140	/**
	141	Updates the dialog, setting the progress bar to the new value and
	142	updating the message if new one is specified.
	143
	144	Returns @true unless the "Cancel" button has been pressed.
	145
	146	If @false is returned, the application can either immediately destroy the
	147	dialog or ask the user for the confirmation and if the abort is not confirmed
	148	the dialog may be resumed with Resume() function.
	149
	150	Notice that you may want to call Fit() to change the dialog size to
	151	conform to the length of the new message if desired. The dialog does
	152	not do this automatically.
	153
	154	@param value
	155	The new value of the progress meter. It should be less than or equal to
	156	the maximum value given to the constructor.
	157	See @c wxPD_AUTO_HIDE style for more info about the behaviour of
	158	wxProgressDialog when @a value is the maximum value given in the ctor.
	159	@param newmsg
	160	The new messages for the progress dialog text, if it is
	161	empty (which is the default) the message is not changed.
	162	@param skip
	163	If "Skip" button was pressed since last Update() call,
	164	this is set to @true.
	165	*/
	166	virtual bool Update(int value, const wxString& newmsg = wxEmptyString,
	167	bool* skip = NULL);
	168	};
	169