The QtxSplash widget provides a splash screen that can be shown during application startup. More...
#include <QtxSplash.h>
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 QtxSplash * | splash (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 QtxSplash * | mySplash = 0 |
The only one instance of splash screen. More... | |
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,
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.
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.
|
private |
|
private |
Construct a splash screen that will display the pixmap.
pixmap | splash screen pixmap |
References setPixmap().
|
virtual |
References mySplash.
|
slot |
This is equivalent to setMessage("");
QString QtxSplash::constantInfo | ( | ) | const |
|
protectedvirtual |
ce | custom event |
References clear(), ProgressEvent::id(), ProgressEvent::message(), ProgressEvent::progress(), setMessage(), and setProgress().
|
protectedvirtual |
p | painter |
References drawMessage(), drawProgressBar(), fullMessage(), messageVisible(), myTotal, and progressVisible().
|
private |
References myPixmap.
|
protectedvirtual |
p | painter |
References BottomSide, fullMessage(), LeftSide, margin(), myAlignment, myColor, myOpacity, myProgressFlags, myShadowColor, progressVisible(), progressWidth(), RightSide, and TopSide.
|
protectedvirtual |
p | painter |
References BottomSide, checkGradient(), OCCViewer::color(), LeftSide, margin(), myColor, myOpacity, myProgress, myProgressFlags, myShadowColor, myShowPercent, myTotal, progressColors(), progressWidth(), RightSide, RightToLeft, and TopSide.
int QtxSplash::error | ( | ) | const |
This function returns error code, set previously with setError() method. If no error code has been set, 0 is returned.
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.
mainWin | application main window |
|
private |
bool QtxSplash::hideOnClick | ( | ) | const |
int QtxSplash::margin | ( | ) | const |
QString QtxSplash::message | ( | ) | const |
bool QtxSplash::messageVisible | ( | ) | const |
|
protectedvirtual |
Hides splash screen if the 'hide on mouse click' flag is set.
me | mouse event (not used) |
References myHideOnClick.
double QtxSplash::opacity | ( | ) | const |
QString QtxSplash::option | ( | const QString & | name | ) | const |
name | option name |
References myOptions.
|
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.
pe | paint event (not used) |
bool QtxSplash::percentageVisible | ( | ) | const |
true
if percentage displaying is enabled References myShowPercent.
QPixmap QtxSplash::pixmap | ( | ) | const |
int QtxSplash::progress | ( | ) | const |
References myProgress.
const QGradient * QtxSplash::progressColors | ( | ) | const |
References myGradient.
int QtxSplash::progressFlags | ( | ) | const |
References myProgressFlags.
bool QtxSplash::progressVisible | ( | ) | const |
int QtxSplash::progressWidth | ( | ) | const |
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()resMgr | resources manager |
section | resources 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().
info | constant info text |
|
static |
error | error message |
title | message box title |
code | error code |
References error(), mySplash, and setError().
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
.
on | new flag state |
References myHideOnClick.
void QtxSplash::setMargin | ( | const int | margin | ) |
|
slot |
msg | status message |
alignment | message text alignment flags (Qt::Alignment) |
color | message text color |
References myAlignment, myColor, myMessage, and repaint().
|
slot |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
msg | status message |
void QtxSplash::setMessageVisible | ( | const bool | on | ) |
on | if true , status message will be enabled |
References myShowMessage, and repaint().
void QtxSplash::setOpacity | ( | const double | opacity | ) |
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 informationFor example,
name | option name |
option | value |
void QtxSplash::setPercentageVisible | ( | const bool | enable | ) |
enable | if true , percentage will be displayed |
References myShowPercent, and repaint().
void QtxSplash::setPixmap | ( | const QPixmap & | pixmap | ) |
pixmap | spash screen image pixmap |
References drawContents(), myPixmap, pixmap(), and repaint().
void QtxSplash::setProgress | ( | const int | progress | ) |
progress | current progress |
References myProgress, and repaint().
progress | current progress |
total | total 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.
startColor | start gradient color (or mono-color) |
endColor | end gradient color |
orientation | gradient type (Qt::Orientation) |
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:
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.
gradient | color gradient to be used for progress bar coloring |
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.
flags | ORed progress bar flags (QtxSplash::ProgressBarFlags) |
References BottomSide, LeftSide, LeftToRight, myProgressFlags, repaint(), RightSide, RightToLeft, and TopSide.
void QtxSplash::setProgressVisible | ( | const bool | on | ) |
on | if true , progress bar will be enabled |
References myShowProgress, and repaint().
void QtxSplash::setProgressWidth | ( | const int | width | ) |
width | new progress bar width |
References myProgressWidth, and repaint().
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.
msg | progress status message |
progress | current progress |
References mySplash.
void QtxSplash::setTextAlignment | ( | const int | alignment | ) |
Default flags are Qt::AlignBottom | Qt::AlignRight.
alignment | alignment flags (Qt::Alignment) |
References myAlignment, and repaint().
If shadow parameter is invalid color, the simple one-colored text is drawn. Otherwise, second parameter is used to draw the text shadow.
color | message text color |
shadow | message text shadow color |
References OCCViewer::color(), myColor, myShadowColor, and repaint().
void QtxSplash::setTotalSteps | ( | const int | total | ) |
total | total number of progress steps |
If the splash screen widget does not exist yet, it is created with specified pixmap. Otherwise, pixmap px is set to existing widget.
px | splash screen pixmap |
References mySplash, QtxSplash(), and setPixmap().
int QtxSplash::textAlignment | ( | ) | const |
void QtxSplash::textColors | ( | QColor & | color, |
QColor & | shadow | ||
) | const |
color | message text color |
shadow | message text shadow color |
References myColor, and myShadowColor.
int QtxSplash::totalSteps | ( | ) | const |
References myTotal.
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
staticprivate |
|
private |