The QtxSplash widget provides a splash screen that can be shown during application startup. More...

#include <QtxSplash.h>

Inheritance diagram for QtxSplash:

Public Types
enum	ProgressBarFlags { LeftSide = 0x0001, RightSide = 0x0002, TopSide = 0x0004, BottomSide = 0x0008, LeftToRight = 0x0010, RightToLeft = 0x0020 }
	Progress bar position and direction. More...
Public Slots
void	setMessage (const QString &, const int, const QColor &=QColor())
	Set status message for the splash screen and define its color and aligment flags.
void	setMessage (const QString &)
	Set status message for the splash screen.
void	clear ()
	Remove the message being displayed on the splash screen.
Public Member Functions
virtual	~QtxSplash ()
	Destructor.
void	setPixmap (const QPixmap &)
	Set the pixmap that will be used as the splash screen's image.
QPixmap	pixmap () const
	Get the pixmap that is used as the splash screen's image.
void	setHideOnClick (const bool)
	Set/clear the 'hide on mouse click' flag.
bool	hideOnClick () const
	Get the 'hide on mouse click' flag.
void	setProgressVisible (const bool)
	Enable/disable displaying of the progress bar.
bool	progressVisible () const
	Check if the progress bar is displayed.
void	setMessageVisible (const bool)
	Enable/disable displaying of the status message.
bool	messageVisible () const
	Check if the status message is displayed.
void	setPercentageVisible (const bool)
	Enable/disable displaying progress percentage.
bool	percentageVisible () const
	Check if the progress percentage is displayed.
void	setTotalSteps (const int)
	Set total progress steps to total.
int	totalSteps () const
	Get total progress steps number.
void	setProgress (const int)
	Set current progress.
void	setProgress (const int, const int)
	Set current progress to progress and total number of progress steps to total.
int	progress () const
	Get current progress.
void	setMargin (const int)
	Set splash window margin (a border width).
int	margin () const
	Get splash window margin (a border width).
void	setProgressWidth (const int)
	Set progress bar width.
int	progressWidth () const
	Get progress bar width.
void	setProgressFlags (const int)
	Set progress bar position and direction.
int	progressFlags () const
	Get progress bar flags: position and direction.
void	setProgressColors (const QColor &, const QColor &=QColor(), const Qt::Orientation=Qt::Vertical)
	Set progress bar colors.
void	setProgressColors (const QGradient &)
	Set progress bar colors.
const QGradient *	progressColors () const
	Get custom progress bar colors.
void	setOpacity (const double)
	Set progress bar and status text message opacity.
double	opacity () const
	Get progress bar and status text message opacity.
void	setTextAlignment (const int)
	Set message text alignment flags.
int	textAlignment () const
	Get message text alignment flags.
void	setTextColors (const QColor &, const QColor &=QColor())
	Set message text colors.
void	textColors (QColor &, QColor &) const
	Get message text colors.
void	setConstantInfo (const QString &info)
	Set constant info text to be displayed on the splash screen.
QString	constantInfo () const
	Get constant info text.
void	setOption (const QString &, const QString &)
	Set constant information option value.
QString	option (const QString &) const
	Get constant information option value.
QString	message () const
	Get current status message.
int	error () const
	Get error code.
void	finish (QWidget *)
	Wait until widget mainWin is displayed.
void	repaint ()
	Repaint the splash screen.
void	readSettings (QtxResourceMgr *, const QString &=QString())
	Read splash settings from the resources manager.
Static Public Member Functions
static QtxSplash *	splash (const QPixmap &=QPixmap())
	Get the only instance of the splash screen widget.
static void	setStatus (const QString &, const int=-1)
	Send the status message and (optionally) current progress to the splash screen.
static void	setError (const QString &, const QString &=QString(), const int=-1)
	Set error status and show error message box to the user.
Protected Member Functions
virtual void	mousePressEvent (QMouseEvent *)
	Process mouse button pressing event.
virtual void	customEvent (QEvent *)
	Process custom event sent by setStatus() method.
virtual void	paintEvent (QPaintEvent *)
	Customize paint event.
virtual void	drawContents (QPainter *)
	Draw the contents of the splash screen.
virtual void	drawProgressBar (QPainter *)
	Draw progress bar.
virtual void	drawMessage (QPainter *)
	Draw status message.
Private Types
typedef QMap< QString, QString >	OptMap
Private Member Functions
	QtxSplash (const QPixmap &)
	Constructor.
void	drawContents ()
	Draw the splash screen window contents.
void	setError (const int)
	Sets error code.
QString	fullMessage () const
	Get full message which includes constant info and status message.
Private Attributes
QPixmap	myPixmap
	splash pixmap
QString	myInfo
	constant info
QString	myMessage
	current status message
int	myAlignment
	text alignment flags (Qt.Alignment)
QColor	myColor
	text color
QColor	myShadowColor
	text shadow color
bool	myHideOnClick
	'hide on click' flag
int	myProgress
	current progress
int	myTotal
	total progress steps
QGradient	myGradient
	progress bar custom gradient
int	myProgressWidth
	progress bar width
int	myProgressFlags
	progress bar flags (QtxSplash.ProgressBarFlags)
int	myMargin
	margin (for progress bar and status message)
double	myOpacity
	progress bar / status message opacity
int	myError
	error code
OptMap	myOptions
	constant info options
bool	myShowProgress
	'show progress bar' flag
bool	myShowMessage
	'show status message' flag
bool	myShowPercent
	'show percentage' flag
Static Private Attributes
static QtxSplash *	mySplash = 0
	The only one instance of splash screen.

Detailed Description

A splash screen is a widget that is usually displayed when an application is being started. Splash screens are often used for applications that have long start up times to provide the user with feedback that the application is loading.

Only one instance of the QtxSplash widget can be created. To access the splash screen widget, use static method QtxSplash.splash(), which creates an instance of the QtxSplash widget (if it is not yet creaed) and returns a pointer to it. You should not destroy this instance - it is done automatically after application main window is shown. Just use methods finish() to make splash screen wait untill main window is shown.

The splash screen appears in the center of the screen. The most common usage is to show a splash screen before the main widget is displayed on the screen. For example,

  int main(int argc, char *argv[])
  {
    QApplication app(argc, argv);
    QPixmap pixmap(":/splash.png");
    QtxSplash* splash = QtxsSplash::splash(pixmap);
    splash->show();
    app.processEvents();
    ... // do application loading and initialization
    MainWindow window;
    window.show();
    splash->finish(&window);
    return app.exec();
  }

The user can hide the splash screen by clicking on it with the mouse. Since the splash screen is typically displayed before the event loop has started running, it is necessary to periodically call QApplication.processEvents() to receive the mouse clicks. To activate the possibility of hiding the splash screen on the mouse click, use setHideOnClick() method passing true as parameter. By default, this feature is switched off.

It is sometimes useful to update the splash screen with any status messages and/or progress information, for example, announcing connections established or modules loaded as the application starts up. QtxSplash class provides the functionality to show status messages and(or) progress bar.

  QPixmap pixmap(":/splash.png");
  QtxSplash* splash = QtxSplash::splash(pixmap);
  splash->setProgress(0, 5); // progress from 0 to 5
  splash->show();
  app.processEvents();
  // doing first step
  splash->setMessage("Step 1");
  splash->setProgress(1); // progress is 20%
  qApp->processEvents();
  // ... perform some actions
  // doing second step
  splash->setMessage("Step 2");
  splash->setProgress(2); // progress is 40%
  qApp->processEvents();
  // ... perform some actions
  ... et cetera

There is a static function QtxSplash.setStatus() which allows to put the next status message and current progress with one call. It can substitue two calls: setMessage() and setProgress().

QtxSplash class provides also a lot of functions to customize its behavior. Set progress bar width with setProgressWidth() method, its position and direction with setProgressFlags(). It can be single-colored or gradient-colored. Use setProgressColors() methods for this. You can even set your own gradient scale with QLinearGradient, QRadialGradient or QConicalGradient and use it for the progress bar coloring. In addition, it is possible to enable/disable displaying of the progress percentage with setPercentageVisible() method.

Displaying of the progress bar and status messages can be switched on/off with setProgressVisible() and setMessageVisible() methods.

To change the progress bar and status message transparency, use setOpacity() function. The methods setTextAlignment() and setTextColors() can be used to change the attributes of the status messages.

The displayed message text can include constant info and status message. The constant info is set by setConstantInfo() method and status message is set by setMessage().

Sometimes it is useful to display an error message above the splash screen window. For example, it can be necessary if an error occurs when loading the application. Method setError() can be used to show the error message and set the error code which can be then retrieved with the error() function.

There is one more helpful feature. The QtxSplash class can read all the settings from the resource file with help of resource manager (QtxResourceMgr class). Refer to the method readSettings() for more details.

Member Typedef Documentation

typedef QMap<QString, QString> QtxSplash.OptMap [private]

Member Enumeration Documentation

enum QtxSplash::ProgressBarFlags

Enumerator:

LeftSide	progress bar is displayed at the left side
RightSide	progress bar is displayed at the right side
TopSide	progress bar is displayed at the top side
BottomSide	progress bar is displayed at the bottom side
LeftToRight	show progress from left to right (from top to bottom)
RightToLeft	show progress from right to left (from bottom to top)

Constructor & Destructor Documentation

QtxSplash::QtxSplash ( const QPixmap & pixmap ) [private]

Construct a splash screen that will display the pixmap.

Parameters:

pixmap splash screen pixmap

See also:: setPixmap(), pixmap()

References setPixmap().

QtxSplash::~QtxSplash ( ) [virtual]

References mySplash.

Member Function Documentation

QtxSplash * QtxSplash::splash ( const QPixmap & px = QPixmap() ) [static]

If the splash screen widget does not exist yet, it is created with specified pixmap. Otherwise, pixmap px is set to existing widget.

Parameters:

px	splash screen pixmap

Returns:: splash screen widget

See also:: setPixmap(), pixmap()

References mySplash, QtxSplash(), and setPixmap().

void QtxSplash::setStatus	(	const QString &	msg,
		const int	progress = `-1`
	)		`[static]`

If the second parameter is less than 0 (default) than it is ignored and only the status message is changed. If you want to modify progress also, pass positive value to the progress parameter explicitly.

Parameters:

msg	progress status message
progress	current progress

See also:: setMessage(), setProgress()

References mySplash.

void QtxSplash::setError	(	const QString &	error,
		const QString &	title = `QString()`,
		const int	code = `-1`
	)		`[static]`

Parameters:

error	error message
title	message box title
code	error code

See also:: error()

References error(), mySplash, and setError().

void QtxSplash::setPixmap ( const QPixmap & pixmap )

Parameters:

pixmap spash screen image pixmap

See also:: pixmap()

References drawContents(), myPixmap, pixmap(), and repaint().

QPixmap QtxSplash::pixmap ( ) const

Returns:: spash screen image pixmap

See also:: setPixmap()

References myPixmap.

void QtxSplash::setHideOnClick ( const bool on )

When this flag is set, user can hide the splash screen window by clicking on it with mouse. But for this to work it is necessary to call periodically QApplication.processEvents() in order to allow event loop to process events because usually main application loop is not yet started at that moment.

By default this flag is set to false.

Parameters:

on	new flag state

See also:: hideOnClick()

References myHideOnClick.

bool QtxSplash::hideOnClick ( ) const

Returns:: 'hide on mouse click' flag

See also:: setHideOnClick()

References myHideOnClick.

void QtxSplash::setProgressVisible ( const bool on )

Parameters:

on	if `true`, progress bar will be enabled

See also:: progressVisible(), setMessageVisible()

References myShowProgress, and repaint().

bool QtxSplash::progressVisible ( ) const

Returns:: true if progress bar is enabled

See also:: setProgressVisible()

References myShowProgress.

void QtxSplash::setMessageVisible ( const bool on )

Parameters:

on	if `true`, status message will be enabled

See also:: messageVisible(), setProgressVisible()

References myShowMessage, and repaint().

bool QtxSplash::messageVisible ( ) const

Returns:: true if status message is enabled

See also:: setMessageVisible()

References myShowMessage.

void QtxSplash::setPercentageVisible ( const bool enable )

Parameters:

enable if true, percentage will be displayed

See also:: percentageVisible()

References myShowPercent, and repaint().

bool QtxSplash::percentageVisible ( ) const

Returns:: true if percentage displaying is enabled

See also:: setPercentageVisible()

References myShowPercent.

void QtxSplash::setTotalSteps ( const int total )

Parameters:

total total number of progress steps

See also:: totalSteps(), setProgress(), progress()

References myTotal, and repaint().

int QtxSplash::totalSteps ( ) const

Returns:: total number of progress steps

See also:: setTotalSteps(), setProgress(), progress()

References myTotal.

void QtxSplash::setProgress ( const int progress )

Parameters:

progress current progress

See also:: progress(), setTotalSteps(), setTotalSteps(),

References myProgress, and repaint().

void QtxSplash::setProgress	(	const int	progress,
		const int	total
	)

Parameters:

progress	current progress
total	total number of progress steps

References myProgress, myTotal, and repaint().

int QtxSplash::progress ( ) const

Returns:: current progress

See also:: setProgress(), setTotalSteps(), setTotalSteps(),

References myProgress.

void QtxSplash::setMargin ( const int margin )

Note, that margin is used only for drawing the progress bar and status messages.

Parameters:

margin new margin width

See also:: margin()

References myMargin, and repaint().

int QtxSplash::margin ( ) const

Returns:: current margin width

See also:: setMargin()

References myMargin.

void QtxSplash::setProgressWidth ( const int width )

Parameters:

width new progress bar width

See also:: progressWidth()

References myProgressWidth, and repaint().

int QtxSplash::progressWidth ( ) const

Returns:: current progress bar width

See also:: setProgressWidth()

References myProgressWidth.

void QtxSplash::setProgressFlags ( const int flags )

By default, progress bar is displayed at the bottom side and shows progress from left to right but this behaviour can be changed.

Parameters:

flags ORed progress bar flags (QtxSplash.ProgressBarFlags)

See also:: progressFlags()

References BottomSide, LeftSide, LeftToRight, myProgressFlags, repaint(), RightSide, RightToLeft, and TopSide.

int QtxSplash::progressFlags ( ) const

Returns:: ORed progress bar flags (QtxSplash.ProgressBarFlags)

See also:: setProgressFlags()

References myProgressFlags.

void QtxSplash::setProgressColors	(	const QColor &	startColor,
		const QColor &	endColor = `QColor()`,
		const Qt::Orientation	orientation = `Qt::Vertical`
	)

If the colors differ the two-colored gradient bar is drawn.

If the endColor is not valid, startColor is used instead (i.e. simple, one-colored progress bar is drawn).

The parameter orientation defines the type of gradient to be drawn - horizontal or vertical. Default is vertical.

Parameters:

startColor	start gradient color (or mono-color)
endColor	end gradient color
orientation	gradient type (Qt.Orientation)

See also:: progressColors()

References test_table.l, and Vertical.

void QtxSplash::setProgressColors ( const QGradient & gradient )

Use this method to display multi-colored gradient progress bar. You have to use QLinearGradient, QRadialGradient or QConicalGradient classes to define the gradient.

Note, that progress bar coordinates can be defined in absolute or relative mode. In absolute mode the actual coordinates of the gradient key points (like start and final point for linear gradient, center and focal point for radial gradient, etc) are calculated from the top-left progress bar's corner. In relative mode you have to use values from 0 to 1 (including) to define the key points positions.

For example:

  QLinearGradient lg(0.5, 0, 1, 1);
  lg.setColorAt(0.2, Qt::blue);
  lg.setColorAt(0.6, Qt::red);
  lg.setSpread(QGradient::RepeatSpread);
  splash->setProgressGradient(lg);

The above code creates linear gradient, which sets start stop to the center of the progress bar; the final stop is assigned to its right-bottom corner. The color scale (blue to red) is changed by the progress bar diagonal.

Parameters:

gradient color gradient to be used for progress bar coloring

See also:: progressColors()

References myGradient, and repaint().

const QGradient * QtxSplash::progressColors ( ) const

Returns:: color gradient used for progress bar coloring

See also:: setProgressColors()

References myGradient.

void QtxSplash::setOpacity ( const double opacity )

The value should be in the range 0.0 to 1.0, where 0.0 is fully transparent and 1.0 is fully opaque.

Parameters:

opacity new opacity value

See also:: opacity()

References myOpacity, opacity(), and repaint().

double QtxSplash::opacity ( ) const

Returns:: current opacity value

See also:: setOpacity()

References myOpacity.

void QtxSplash::setTextAlignment ( const int alignment )

Default flags are Qt.AlignBottom | Qt.AlignRight.

Parameters:

alignment alignment flags (Qt.Alignment)

See also:: textAlignment()

References myAlignment, and repaint().

int QtxSplash::textAlignment ( ) const

Returns:: alignment flags (Qt.Alignment)

See also:: setTextAlignment()

References myAlignment.

void QtxSplash::setTextColors	(	const QColor &	color,
		const QColor &	shadow = `QColor()`
	)

If shadow parameter is invalid color, the simple one-colored text is drawn. Otherwise, second parameter is used to draw the text shadow.

Parameters:

color	message text color
shadow	message text shadow color

See also:: textColors()

References myColor, myShadowColor, and repaint().

void QtxSplash::textColors	(	QColor &	color,
		QColor &	shadow
	)		const

Parameters:

color	message text color
shadow	message text shadow color

See also:: setTextColors()

References myColor, and myShadowColor.

void QtxSplash::setConstantInfo ( const QString & info )

The displayed text includes constant info and status message. The constant message is set by setConstantInfo() method and status message is set by setMessage().

Parameters:

info	constant info text

See also:: constantInfo(), message(), setMessage(), option(), setOption()

References myInfo, and repaint().

QString QtxSplash::constantInfo ( ) const

Returns:: constant info text

See also:: setConstantInfo(), message(), setMessage()

References myInfo.

void QtxSplash::setOption	(	const QString &	name,
		const QString &	value
	)

The option is a part of the constant information text, which is replaced at the time of the displaying.

The following options are supported:

%A - could be used as application name
%V - could be used as application version
%L - could be used as application license information
%C - could be used as application copyright information

For example,

  splash->setContantInfo("%A [%V]\n%C");
  splash->setOption("%A", "MyApplication" );
  splash->setOption("%V", "Version 1.0" );
  splash->setOption("%C", "Copyright (C) MyCompany 2008" );

Parameters:

name	option name
option	value

See also:: option(), setConstantInfo(), constantInfo()

References myOptions, and repaint().

QString QtxSplash::option ( const QString & name ) const

Parameters:

name	option name

Returns:: option value or empty string if option is not set

See also:: setOption(), setConstantInfo(), constantInfo()

References myOptions.

QString QtxSplash::message ( ) const

Returns:: status message

See also:: setMessage(), constantInfo(), setConstantInfo()

References myMessage.

int QtxSplash::error ( ) const

This function returns error code, set previously with setError() method. If no error code has been set, 0 is returned.

Returns:: last error code

See also:: setError()

References myError.

void QtxSplash::finish ( QWidget * mainWin )

Makes the splash screen wait until the widget mainWin is displayed and then hide and close splash window.

Parameters:

mainWin application main window

void QtxSplash::repaint ( )

References drawContents().

void QtxSplash::readSettings	(	QtxResourceMgr *	resMgr,
		const QString &	section = `QString()`
	)

This method can be used to setup the splash screen look-n-feel. By default, "splash" section of the resources file is used, but you can use any other section. All the splash screen parameters can be defined via resources file:

"image" : splash screen image, see setPixmap()
"margin" : splash window margin, see setMargin()
"show_progress" : show progress bar flag, see setProgressVisible()
"show_message" : show status messages flag, see setMessageVisible()
"show_percents" : show progress percentage flag, see setPercentageVisible()
"progress_width" : progress bar width(), see setProgressWidth()
"progress_flags" : progress bar position and direction, see setProgressFlags()
"constant_info" : status messages constant info, see setConstantInfo()
"text_colors" : status messages color(s), see setTextColors()
"progress_colors" : progress bar color(s), see setProgressColors()
"opacity" : progress bar and status messages opacity, see setOpacity()
"font" : status messages font
"alignment" : status messages alignment flags, see setTextAlignment()
"hide_on_click" : hide-on-click flag, see setHideOnClick()