:: printable version ::

Rating label widget

::description ::changelog ::requirements ::features ::usage ::tech ::


A trivial rating label.

The widget has been completely rewritten, but you can still find older versions on the Sourceforge file release page. The new version is now completely mouse controlled. You don't need to attach another widget like a slider to set the rating. Just move the mouse over the widget and click to set the desired value. Here is a (somewhat buggy ;) animated example, showing the rating label and (below) a standard QLabel with some information for the user:

Please note that the text label is not part of the widget itself. Take a look to the usage example below to see how you can use the widget's signals to display such a status text.

The current release can not be controlled by keyboard. Sorry but this will be fixed in some future release.





Usage example

The class can be used like any other standard widget. You can use the setPixmap() method to set up to three pixmaps that will be used for the rated values, unrated values and the currently highlighted (mouse over!) value. There are a few slots to set the current, minumum and maximum value. A valueChanged() and a hovered() signal provide some more control on the widget.

The following code snippet is from the example application that comes with the source code.

// main.cpp
#include "ratingform.h" #include <QApplication> int main(int argc, char** argv) { QApplication a( argc, argv ); RatingForm w; w.show(); a.connect( &a, SIGNAL( lastWindowClosed() ), &a, SLOT( quit() ) ); return a.exec(); }
// Excerpt from ratingform.h
/* Ui::RatingForm is a simple Qt Designer form with a RatingLabel called label and a QLabel called status. */
#include "ui_ratingform.h" class RatingForm : public QWidget, protected Ui::RatingForm { Q_OBJECT public: RatingForm(QWidget* parent = 0) : QWidget(parent) { setupUi(this); setWindowTitle("OSDaB RatingLabel"); rating->setMaximum(5); rating->setPixmap(RatingLabel::RatedRole, QPixmap(":/img/rated.png")); rating->setPixmap(RatingLabel::UnratedRole, QPixmap(":/img/unrated.png")); rating->setPixmap(RatingLabel::HoveredRole, QPixmap(":/img/hovered.png"));
// Initialize the QLabel status text.
ratingHovered(-1); connect (status, SIGNAL(linkActivated(const QString&)), this, SLOT(linkActivated(const QString&)) ); connect (rating, SIGNAL(hovered(int)), this, SLOT(ratingHovered(int)) ); } private slots: void linkActivated(const QString& url) {
// We only have one label and one url here ;)
Q_UNUSED(url); rating->setValue(0); } void ratingHovered(int rating) { switch (rating) { case 1: status->setText(tr("1 - Awful movie.")); break; case 2: status->setText(tr("2 - Disappointing movie.")); break; case 3: status->setText(tr("3 - Mediocre movie.")); break; case 4: status->setText(tr("4 - Good movie.")); break; case 5: status->setText(tr("5 - Outstanding movie.")); break; default: status->setText(tr("Click on a star to set the desired rating or click here to clear it.")); } } };

That's all. You don't need all this code if you don't want to set a status text when the mouse enters the widget, of course. Nevertheless, this you better do it or you provide some different form of feedback to the user.

Technical details

Using the widget from Qt Designer

The latest release no longer inherits from QLabel (as there is no need to do so) and this means that you cannot use it directly from the Qt Designer. As of version 4.2, the Designer only allows to "promote" existing widgets to custom widgets.

The example application contains a "hacked" .ui file: a QLabel has been used as placeholder for the RatingLabel, it has been promoted to a custom RatingLabel widget and the resulting .ui file has been edited with a text editor to remove the "text" property from the QLabel node (or Qt will generate some code that calls QLabel::setText(), which obviously does not exist in RatingLabel).

:: index :: top ::