Version: 8.3.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Pages
QtxSplash Class Reference

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

#include <QtxSplash.h>

Inheritance diagram for QtxSplash:
Inheritance graph

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. More...
 
void setMessage (const QString &)
 Set status message for the splash screen. More...
 
void clear ()
 Remove the message being displayed on the splash screen. More...
 

Public Member Functions

virtual ~QtxSplash ()
 Destructor. More...
 
void setPixmap (const QPixmap &)
 Set the pixmap that will be used as the splash screen's image. More...
 
QPixmap pixmap () const
 Get the pixmap that is used as the splash screen's image. More...
 
void setHideOnClick (const bool)
 Set/clear the 'hide on mouse click' flag. More...
 
bool hideOnClick () const
 Get the 'hide on mouse click' flag. More...
 
void setProgressVisible (const bool)
 Enable/disable displaying of the progress bar. More...
 
bool progressVisible () const
 Check if the progress bar is displayed. More...
 
void setMessageVisible (const bool)
 Enable/disable displaying of the status message. More...
 
bool messageVisible () const
 Check if the status message is displayed. More...
 
void setPercentageVisible (const bool)
 Enable/disable displaying progress percentage. More...
 
bool percentageVisible () const
 Check if the progress percentage is displayed. More...
 
void setTotalSteps (const int)
 Set total progress steps to total. More...
 
int totalSteps () const
 Get total progress steps number. More...
 
void setProgress (const int)
 Set current progress. More...
 
void setProgress (const int, const int)
 Set current progress to progress and total number of progress steps to total. More...
 
int progress () const
 Get current progress. More...
 
void setMargin (const int)
 Set splash window margin (a border width). More...
 
int margin () const
 Get splash window margin (a border width). More...
 
void setProgressWidth (const int)
 Set progress bar width. More...
 
int progressWidth () const
 Get progress bar width. More...
 
void setProgressFlags (const int)
 Set progress bar position and direction. More...
 
int progressFlags () const
 Get progress bar flags: position and direction. More...
 
void setProgressColors (const QColor &, const QColor &=QColor(), const Qt::Orientation=Qt::Vertical)
 Set progress bar colors. More...
 
void setProgressColors (const QGradient &)
 Set progress bar colors. More...
 
const QGradient * progressColors () const
 Get custom progress bar colors. More...
 
void setOpacity (const double)
 Set progress bar and status text message opacity. More...
 
double opacity () const
 Get progress bar and status text message opacity. More...
 
void setTextAlignment (const int)
 Set message text alignment flags. More...
 
int textAlignment () const
 Get message text alignment flags. More...
 
void setTextColors (const QColor &, const QColor &=QColor())
 Set message text colors. More...
 
void textColors (QColor &, QColor &) const
 Get message text colors. More...
 
void setConstantInfo (const QString &info)
 Set constant info text to be displayed on the splash screen. More...
 
QString constantInfo () const
 Get constant info text. More...
 
void setOption (const QString &, const QString &)
 Set constant information option value. More...
 
QString option (const QString &) const
 Get constant information option value. More...
 
QString message () const
 Get current status message. More...
 
int error () const
 Get error code. More...
 
void finish (QWidget *)
 Wait until widget mainWin is displayed. More...
 
void repaint ()
 Repaint the splash screen. More...
 
void readSettings (QtxResourceMgr *, const QString &=QString())
 Read splash settings from the resources manager. More...
 

Static Public Member Functions

static QtxSplashsplash (const QPixmap &=QPixmap())
 Get the only instance of the splash screen widget. More...
 
static void setStatus (const QString &, const int=-1)
 Send the status message and (optionally) current progress to the splash screen. More...
 
static void setError (const QString &, const QString &=QString(), const int=-1)
 Set error status and show error message box to the user. More...
 

Protected Member Functions

virtual void mousePressEvent (QMouseEvent *)
 Process mouse button pressing event. More...
 
virtual void customEvent (QEvent *)
 Process custom event sent by setStatus() method. More...
 
virtual void paintEvent (QPaintEvent *)
 Customize paint event. More...
 
virtual void drawContents (QPainter *)
 Draw the contents of the splash screen. More...
 
virtual void drawProgressBar (QPainter *)
 Draw progress bar. More...
 
virtual void drawMessage (QPainter *)
 Draw status message. More...
 

Private Types

typedef QMap< QString, QString > OptMap
 

Private Member Functions

 QtxSplash (const QPixmap &)
 Constructor. More...
 
void drawContents ()
 Draw the splash screen window contents. More...
 
void setError (const int)
 Sets error code. More...
 
QString fullMessage () const
 Get full message which includes constant info and status message. More...
 

Private Attributes

QPixmap myPixmap
 splash pixmap More...
 
QString myInfo
 constant info More...
 
QString myMessage
 current status message More...
 
int myAlignment
 text alignment flags (Qt::Alignment) More...
 
QColor myColor
 text color More...
 
QColor myShadowColor
 text shadow color More...
 
bool myHideOnClick
 'hide on click' flag More...
 
int myProgress
 current progress More...
 
int myTotal
 total progress steps More...
 
QGradient myGradient
 progress bar custom gradient More...
 
int myProgressWidth
 progress bar width More...
 
int myProgressFlags
 progress bar flags (QtxSplash::ProgressBarFlags) More...
 
int myMargin
 margin (for progress bar and status message) More...
 
double myOpacity
 progress bar / status message opacity More...
 
int myError
 error code More...
 
OptMap myOptions
 constant info options More...
 
bool myShowProgress
 'show progress bar' flag More...
 
bool myShowMessage
 'show status message' flag More...
 
bool myShowPercent
 'show percentage' flag More...
 

Static Private Attributes

static QtxSplashmySplash = 0
 The only one instance of splash screen. More...
 

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");
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

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
pixmapsplash screen pixmap
See Also
setPixmap(), pixmap()

References setPixmap().

QtxSplash::~QtxSplash ( )
virtual

References mySplash.

Member Function Documentation

void QtxSplash::clear ( )
slot

This is equivalent to setMessage("");

See Also
message(), setMessage()

References myMessage, and repaint().

QString QtxSplash::constantInfo ( ) const
Returns
constant info text
See Also
setConstantInfo(), message(), setMessage()

References myInfo.

void QtxSplash::customEvent ( QEvent ce)
protectedvirtual
void QtxSplash::drawContents ( QPainter *  p)
protectedvirtual
void QtxSplash::drawContents ( )
private

References myPixmap.

void QtxSplash::drawMessage ( QPainter *  p)
protectedvirtual
void QtxSplash::drawProgressBar ( QPainter *  p)
protectedvirtual
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
mainWinapplication main window
QString QtxSplash::fullMessage ( ) const
private
Returns
get fill message text
See Also
constantInfo(), setConstantInfo(), message(), setMessage()

References myInfo, myMessage, and option().

bool QtxSplash::hideOnClick ( ) const
Returns
'hide on mouse click' flag
See Also
setHideOnClick()

References myHideOnClick.

int QtxSplash::margin ( ) const
Returns
current margin width
See Also
setMargin()

References myMargin.

QString QtxSplash::message ( ) const
Returns
status message
See Also
setMessage(), constantInfo(), setConstantInfo()

References myMessage.

bool QtxSplash::messageVisible ( ) const
Returns
true if status message is enabled
See Also
setMessageVisible()

References myShowMessage.

void QtxSplash::mousePressEvent ( QMouseEvent *  )
protectedvirtual

Hides splash screen if the 'hide on mouse click' flag is set.

Parameters
memouse event (not used)
See Also
hideOnClick(), setHideOnClick()

References myHideOnClick.

double QtxSplash::opacity ( ) const
Returns
current opacity value
See Also
setOpacity()

References myOpacity.

QString QtxSplash::option ( const QString &  name) const
Parameters
nameoption name
Returns
option value or empty string if option is not set
See Also
setOption(), setConstantInfo(), constantInfo()

References myOptions.

void QtxSplash::paintEvent ( QPaintEvent *  )
protectedvirtual

This function is implemented to work-around the Qt bug on some Linux distribututions when the drawing on the splash screen widget is not allowed.

Parameters
pepaint event (not used)
bool QtxSplash::percentageVisible ( ) const
Returns
true if percentage displaying is enabled
See Also
setPercentageVisible()

References myShowPercent.

QPixmap QtxSplash::pixmap ( ) const
Returns
spash screen image pixmap
See Also
setPixmap()

References myPixmap.

int QtxSplash::progress ( ) const
Returns
current progress
See Also
setProgress(), setTotalSteps(), setTotalSteps(),

References myProgress.

const QGradient * QtxSplash::progressColors ( ) const
Returns
color gradient used for progress bar coloring
See Also
setProgressColors()

References myGradient.

int QtxSplash::progressFlags ( ) const
Returns
ORed progress bar flags (QtxSplash::ProgressBarFlags)
See Also
setProgressFlags()

References myProgressFlags.

bool QtxSplash::progressVisible ( ) const
Returns
true if progress bar is enabled
See Also
setProgressVisible()

References myShowProgress.

int QtxSplash::progressWidth ( ) const
Returns
current progress bar width
See Also
setProgressWidth()

References myProgressWidth.

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:

Parameters
resMgrresources manager
sectionresources file section name (if empty, the default "splash" section is used).

References BottomSide, Horizontal, LeftSide, LeftToRight, px(), RightSide, RightToLeft, setConstantInfo(), setHideOnClick(), setMargin(), setMessageVisible(), setOpacity(), setPercentageVisible(), setPixmap(), setProgressColors(), setProgressFlags(), setProgressVisible(), setProgressWidth(), setTextAlignment(), setTextColors(), TopSide, QtxResourceMgr::value(), and Vertical.

void QtxSplash::repaint ( )

References drawContents().

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
infoconstant info text
See Also
constantInfo(), message(), setMessage(), option(), setOption()

References myInfo, and repaint().

void QtxSplash::setError ( const QString &  error,
const QString &  title = QString(),
const int  code = -1 
)
static
Parameters
errorerror message
titlemessage box title
codeerror code
See Also
error()

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

void QtxSplash::setError ( const int  code)
private
Parameters
codeerror code

References myError.

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
onnew flag state
See Also
hideOnClick()

References myHideOnClick.

void QtxSplash::setMargin ( const int  margin)

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

Parameters
marginnew margin width
See Also
margin()

References myMargin, and repaint().

void QtxSplash::setMessage ( const QString &  msg,
const int  alignment,
const QColor &  color = QColor() 
)
slot
Parameters
msgstatus message
alignmentmessage text alignment flags (Qt::Alignment)
colormessage text color
See Also
message(), constantInfo(), setConstantInfo()

References myAlignment, myColor, myMessage, and repaint().

void QtxSplash::setMessage ( const QString &  msg)
slot

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
msgstatus message
See Also
message(), constantInfo(), setConstantInfo()

References myMessage, and repaint().

void QtxSplash::setMessageVisible ( const bool  on)
Parameters
onif true, status message will be enabled
See Also
messageVisible(), setProgressVisible()

References myShowMessage, and repaint().

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
opacitynew opacity value
See Also
opacity()

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

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
nameoption name
optionvalue
See Also
option(), setConstantInfo(), constantInfo()

References myOptions, and repaint().

void QtxSplash::setPercentageVisible ( const bool  enable)
Parameters
enableif true, percentage will be displayed
See Also
percentageVisible()

References myShowPercent, and repaint().

void QtxSplash::setPixmap ( const QPixmap &  pixmap)
Parameters
pixmapspash screen image pixmap
See Also
pixmap()

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

void QtxSplash::setProgress ( const int  progress)
Parameters
progresscurrent progress
See Also
progress(), setTotalSteps(), setTotalSteps(),

References myProgress, and repaint().

void QtxSplash::setProgress ( const int  progress,
const int  total 
)
Parameters
progresscurrent progress
totaltotal number of progress steps

References myProgress, myTotal, and repaint().

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
startColorstart gradient color (or mono-color)
endColorend gradient color
orientationgradient type (Qt::Orientation)
See Also
progressColors()

References 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
gradientcolor gradient to be used for progress bar coloring
See Also
progressColors()

References myGradient, and repaint().

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
flagsORed progress bar flags (QtxSplash::ProgressBarFlags)
See Also
progressFlags()

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

void QtxSplash::setProgressVisible ( const bool  on)
Parameters
onif true, progress bar will be enabled
See Also
progressVisible(), setMessageVisible()

References myShowProgress, and repaint().

void QtxSplash::setProgressWidth ( const int  width)
Parameters
widthnew progress bar width
See Also
progressWidth()

References myProgressWidth, and repaint().

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
msgprogress status message
progresscurrent progress
See Also
setMessage(), setProgress()

References mySplash.

void QtxSplash::setTextAlignment ( const int  alignment)

Default flags are Qt::AlignBottom | Qt::AlignRight.

Parameters
alignmentalignment flags (Qt::Alignment)
See Also
textAlignment()

References myAlignment, and repaint().

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
colormessage text color
shadowmessage text shadow color
See Also
textColors()

References OCCViewer::color(), myColor, myShadowColor, and repaint().

void QtxSplash::setTotalSteps ( const int  total)
Parameters
totaltotal number of progress steps
See Also
totalSteps(), setProgress(), progress()

References myTotal, and repaint().

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
pxsplash screen pixmap
Returns
splash screen widget
See Also
setPixmap(), pixmap()

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

int QtxSplash::textAlignment ( ) const
Returns
alignment flags (Qt::Alignment)
See Also
setTextAlignment()

References myAlignment.

void QtxSplash::textColors ( QColor &  color,
QColor &  shadow 
) const
Parameters
colormessage text color
shadowmessage text shadow color
See Also
setTextColors()

References myColor, and myShadowColor.

int QtxSplash::totalSteps ( ) const
Returns
total number of progress steps
See Also
setTotalSteps(), setProgress(), progress()

References myTotal.

Member Data Documentation

int QtxSplash::myAlignment
private
QColor QtxSplash::myColor
private
int QtxSplash::myError
private
QGradient QtxSplash::myGradient
private
bool QtxSplash::myHideOnClick
private
QString QtxSplash::myInfo
private
int QtxSplash::myMargin
private
QString QtxSplash::myMessage
private
double QtxSplash::myOpacity
private
OptMap QtxSplash::myOptions
private
QPixmap QtxSplash::myPixmap
private
int QtxSplash::myProgress
private
int QtxSplash::myProgressFlags
private
int QtxSplash::myProgressWidth
private
QColor QtxSplash::myShadowColor
private
bool QtxSplash::myShowMessage
private
bool QtxSplash::myShowPercent
private
bool QtxSplash::myShowProgress
private
QtxSplash * QtxSplash::mySplash = 0
staticprivate
int QtxSplash::myTotal
private

The documentation for this class was generated from the following files: