Редактирование: The Wizard Magically Reappears

{{Панель навигации по Qt Quarterly|Выпуск 22}}

by Jo Asplin

'''После исчезновения в клубах дыма, с выходом Qt4, QWizard сново часть Qt. QWizard и его нвоый подмастерье, QWizardPage, отработавшие свое краткое время в Qt4 Solutions, и теперь насыщенные возможностями, которые сделают работу програмиста мастеров легче, чем когда либо.'''

__TOC__

[[Qt:Документация_4.3.2/qwizard  | QWizard]] provides a framework for writing wizards (also calledassistants). The purpose of a wizard is to guide the user through aprocess step by step. Compared with the [[Qt:Документация_4.3.2/qwizard  | QWizard]] class foundin Qt 3 and the <tt>Q3Wizard</tt> compatibility class of Qt 4, the newwizard provides the following features:

* '''Естественный внешний вид и поведение на всех платформах'''<br />[[Qt:Документация_4.3.2/qwizard  | QWizard]] supports four different looks &mdash; Classic (Windows 95 and X11), Modern(Windows 98 to XP), Aero (Windows Vista), and Mac (Mac OS X). By default,[[Qt:Документация_4.3.2/qwizard  | QWizard]] automatically chooses the most appropriate style for theuser's platform, but this can be overridden.<br />
[[Image:qq22-wizard-styles.png|center]]

* '''Более мощьный и удобный API'''<br />The new API makes iteasy to enable or disable the '''Next''' and '''Finish''' buttonsbased on the dialog's contents, and to exchange information betweenpages.<br />
* '''Поддержка нелинейных мастеров'''<br />Non-linear wizards allow different traversal pathsbased on the information provided by the user. <br />

In this article, we will focus on the control and data flow aspectsof wizards: What happens when the user navigates between pages, whenis the user allowed to navigate between pages, and how do we accessdata on which to base these decisions?

===A Ferry Booking Example===
We will use a ferry trip booking wizard to illustrate a number ofthe concepts of the new wizard framework. The five pages involved areintentionally very simple: A page for selecting a sailing date, apage for entering the name of a single passenger, a page for choosinga cabin type, a page for specifying a car registration number in caseyou want to bring your car, and finally a page for entering a creditcard number.

The following diagram depicts the possible navigation paths throughthe wizard:

[[Image:qq22-ferryexample.png|center]]

The initial implementation looks like this:
<source lang="cpp-qt">
class BookingWizard : public QWizard
{
public:
    BookingWizard();

    QString sailingDate() const
        { return sailing->selectedDate().toString(); }
    QString passengerName() const
        { return passenger->text(); }
    ...

private:
    QCalendarWidget *sailing;
    QLineEdit *passenger;
    ...
};

class SailingPage : public QWizardPage
{
public:
    SailingPage(QCalendarWidget *sailing) {
        setTitle(tr("Sailing"));
        setLayout(new QVBoxLayout);
        sailing->setMinimumDate(
                QDate::currentDate().addDays(1));
        layout()->addWidget(sailing);
    }
};

...

BookingWizard::BookingWizard()
{
    setWindowTitle(tr("Ferry Trip Booking Wizard"));

    sailing = new QCalendarWidget;
    addPage(new SailingPage(sailing));

    passenger = new QLineEdit;
    addPage(new PassengerPage(passenger));

    ...
}
</source> 
The following code snippet shows how to open the wizard and collectresults from it:
<source lang="cpp-qt">
BookingWizard wizard;
if (wizard.exec()) {
    qDebug() << "booking accepted";
    qDebug() << "sailing date:" << wizard.sailingDate();
    qDebug() << "passenger:" << wizard.passengerName();
    ...
}
</source> 
Notice how the <tt>BookingWizard</tt> class has to keep pointers to theinput widgets of all the pages in order to implement its publicinterface. In addition, if a page needs to access an input widget ofanother page, the pointer to the input widget would have to be passedto both pages.


===Регистрация и использование полей===

Чтобы решить проблему идентификации, указанную выше, мы можем использовать механизм полей [[Qt:Документация_4.3.2/qwizard  | QWizard]]'а. Поле состоит из из экземпляра объекта, одного из свойств виджета (представляющее значение виджета), сигнала информирующего нас об изменении свойства (обычно имеется только один такой сигнал) и, наконец, имя, которое должно быть уникальным в пределах мастера.

Обращаясь к имени поля и зная как преобразовать его значение из [[Qt:Документация_4.3.2/qvariant  | QVariant]], мы можем без труда получать доступ к полям в одинаковой форме через мастр. Механизм полей также позволяет нам хранить подробности создания виджетов ввода локально на соответствующих страницах мастера.

Вот как масетер заказов (booking) преобразован, чтобы представить его виджеты ввода как поля:
<source lang="cpp-qt">
class BookingWizard : public QWizard
{
public:
    BookingWizard();

    QString sailingDate() const
        { return field("sailing").toString(); }
    QString passengerName() const
        { return field("passenger").toString(); }
    ...
};

class SailingPage : public QWizardPage
{
public:
    SailingPage()
    {
        QCalendarWidget *sailing = new QCalendarWidget;
        registerField("sailing", sailing, "selectedDate",
                      SIGNAL(selectionChanged()));
        ...
    }
};

class PassengerPage : public QWizardPage
{
public:
    PassengerPage()
    {
        QLineEdit *passenger = new QLineEdit;
        registerField("passenger", passenger);
        ...
    }
};

...
</source> 
Для страницы '''Sailing''' (Отплытие), чтобы её [[Qt:Документация_4.3.2/qcalendarwidget  | QCalendarWidget]] был корректно распознан как поле, мы вызываем <tt>registerField()</tt> в конструкторе <tt>SailingPage</tt>:
<source lang="cpp-qt">
registerField( "sailing", sailing, "selectedDate",
               SIGNAL(selectionChanged()));
</source> 
Для страницы '''Passenger''' (Пасажир), мы просто вызываем:
<source lang="cpp-qt">
registerField("passenger", passenger);
</source> 
What about the property and the change signal? These could have beenpassed as the third and fourth arguments to <tt>registerField()</tt>, butby omitting them (effectively passing null pointers instead), we tell[[Qt:Документация_4.3.2/qwizardpage  | QWizardPage]] that we would like to use default values here.[[Qt:Документация_4.3.2/qwizardpage  | QWizardPage]] knows about the most common types of input widgets.Since [[Qt:Документация_4.3.2/qlineedit  | QLineEdit]] is among the lucky ones (a subclass would alsodo), the text property and the <tt>textChanged()</tt> signal isautomatically used.

Alternatively, we could have added [[Qt:Документация_4.3.2/qcalendarwidget  | QCalendarWidget]] to[[Qt:Документация_4.3.2/qwizard  | QWizard]]'s list of recognized field types once and for all:
<source lang="cpp-qt">
setDefaultProperty("QCalendarWidget", "selectedDate", SIGNAL(selectionChanged()));
</source>

===Validate Before It's Too Late===

If some information in the wizard is invalid or inconsistent (e.g.,the passenger name is empty), it is currently not detected untilafter the wizard is closed. The wizard would then have to bereopened, and all the information, including the field that was incorrectin the first place, would have to be entered again. This is a verytedious, error-prone, and repetitive process that defeats thepurpose of using a wizard.

When hitting '''Next''' or '''Finish''' to accept the currentstate of a wizard, the user would intuitively expect the result to beacceptable. We would like errors to be caught and dealt with as earlyas possible.

Let's see how we can improve our booking wizard. How can we ensurethat the passenger name is not empty before proceeding to the'''Cabin''' page? It turns out that we get the validation we'reafter almost for free when we represent the passenger name as afield. All it takes is to register the field as a mandatory field byappending an asterisk to the name:
<source lang="cpp-qt">
registerField("passenger*", passenger);
</source> 
When we query its value, the field is still referred to using itsregular name (without the asterisk), but being a mandatory field, itis required to be filled (i.e., have a value different from the one ithad at the time of registration) before the '''Next''' button isenabled. The default value of a [[Qt:Документация_4.3.2/qlineedit  | QLineEdit]] is an empty string, sowe are not allowed to proceed to the '''Cabin''' page until weenter a non-empty passenger name.

But how does the wizard know when to check a mandatory field forupdates? Simple: [[Qt:Документация_4.3.2/qwizard  | QWizard]] automatically connects to the changenotification signal associated with the field; e.g.,<tt>textChanged()</tt> for  [[Qt:Документация_4.3.2/qlineedit  | QLineEdit]]. This ensures that the'''Next''' or '''Finish''' button is in the correct "enabled"state at all times.

What if a simple update check is not sufficient to validate a page?Assume for example that there are no departures on Sundays. How can weensure that it is impossible to proceed to the '''Passenger''' page aslong as a Sunday is selected as sailing date? A mandatory field would notwork in this case, because there are many invalidvalues (i.e., all Sundays), and there is no way we could have all ofthese represent the invalid initial value to compare the fieldagainst.

We essentially need a way to program the validation ruleourselves. This is achieved by reimplementing the virtual function,[http://www.crossplatform.ru/documentation/qtdoc4.3/qwizardpage.php#isComplete QWizardPage::isComplete()]:
<source lang="cpp-qt">
bool SailingPage::isComplete() const
{
    return field("sailing").toDate().dayOfWeek()
           != Qt::Sunday;
}
</source> 
We also need to emit the [http://www.crossplatform.ru/documentation/qtdoc4.3/qwizardpage.php#completeChanged QWizardPage::completeChanged()] signalevery time <tt>isComplete()</tt> may potentially return a different value,so that the wizard knows that it must refresh the '''Next''' button.This requires us to add the following <tt>connect()</tt> call to the<tt>SailingPage</tt> constructor:
<source lang="cpp-qt">
connect(sailing, SIGNAL(selectionChanged()),
        this, SIGNAL(completeChanged()));
</source>

===Инициализация страницы===

We would now like to ensure that the contents of a page isfilled with sensible values every time the page is entered. Let'sassume that an additional, slightly more expensive cabin type isavailable on Saturdays. By reimplementing the virtual function[http://www.crossplatform.ru/documentation/qtdoc4.3/qwizardpage.php#initializePage QWizardPage::initializePage()], we can populate the [[Qt:Документация_4.3.2/qcombobox  | QComboBox]]representing the cabin types whenever we enter the '''Cabin''' (Каюта) page(assuming the <tt>cabin</tt> combobox is a private member of<tt>SailingPage</tt>):
<source lang="cpp-qt">
void CabinPage::initializePage()
{
    cabin->clear();
    cabin->addItem(tr("Cabin without window"));
    cabin->addItem(tr("Cabin with window"));
    if (field("sailing").toDate().dayOfWeek()
            == Qt::Saturday)
        cabin->addItem(tr("Luxury cabin with window and "
                          "champagne"));
}
</source> 
Notice how the <tt>CabinPage</tt> accesses a field registered by aprevious page ("sailing") to determine the day of the week.

===Пропуск страницы в середине===

We are now going to support another peculiarity of the ferry company:Cars are not allowed on Saturdays. If the user has selected Saturdayas the sailing date, the '''Car''' page is skipped altogether.

[[Image:qq22-skipcar.png|center]]

By default, the wizard pages are presented in a strictly linearorder: For any given page, there is only one possible page thatcan be arrived from, and only one possible page to proceed to.For instance, the '''Payment''' page of our ferry example canonly be arrived at from the '''Car''' page, and the '''Car'''page is the only page we can proceed to from the '''Cabin''' page.

We will now relax this restriction so that pushing the '''Next'''button on the '''Cabin''' page takes us to either the '''Car''' pageor straight to the '''Payment''' page depending on the selectedsailing date. As a consequence, the '''Payment''' page may be reacheddirectly from either the '''Cabin''' page or the '''Car''' page.

The non-linear behavior is achieved by reimplementing thevirtual function, [http://www.crossplatform.ru/documentation/qtdoc4.3/qwizardpage.php#nextId QWizardPage::nextId()]. This function is evaluated bythe wizard when the '''Next''' button is pressed to determine which page toenter. In order for this to work, we need to associate a unique IDwith each page. The way a unique ID is assigned to a page depends onhow the page is registered in the wizard: <tt>addPage()</tt> assigns an IDthat is greater than any other ID so far, while <tt>setPage()</tt> accepts theID as an argument.

The base implementation of <tt>nextId()</tt> simply returns the next ID inthe increasing sequence of registered IDs. Reimplementing<tt>nextId()</tt> works best in combination with <tt>setPage()</tt> asillustrated by the following example:
<source lang="cpp-qt">
class BookingWizard : public QWizard
{
public:
    enum { Sailing, Passenger, Cabin, Car, Payment };
    ...
};
int CabinPage::nextId() const
{
    if (field("sailing").toDate().dayOfWeek()
            == Qt::Saturday) {
        return BookingWizard::Payment;
    } else {
        return BookingWizard::Car;
    }
}
BookingWizard::BookingWizard()
{
    ...
    setPage(Car, new CarPage);
    setPage(Payment, new PaymentPage);
    ...
}
</source> 
Use <tt>nextId()</tt> with care to avoid cycles and non-existent page IDs.Fortunately, [[Qt:Документация_4.3.2/qwizard  | QWizard]] will warn about these cases at run-time.


===Пропуск последней страницы===

To illustrate a slightly different use of <tt>nextId()</tt>, let's drop therule about Saturdays from the previous section and assume instead thatpassengers whose name contains "wizard" don't have to pay for the tripat all &mdash; for them, the '''Car''' page should be the final page.

[[Image:qq22-skippayment.png|center]]

We achieve this by letting <tt>nextId()</tt> return {-}1 if the'''Payment''' page should be skipped. As it happens, <tt>nextId()</tt>is not only evaluated when the '''Next''' button is pressed to determine whichpage is the next page, but also upon entering a new page to find outwhether there is a next page at all. If there is no next page, the'''Finish''' button should replace the '''Next''' button. Here isthe code:
<source lang="cpp-qt">
int CarPage::nextId() const
{
    if (field("passenger").toString()
           .contains(tr("wizard"), Qt::CaseInsensitive)) {
        return -1;
    } else {
        return BookingWizard::Payment;
    }
}
</source> 
This of course assumes that the passenger field doesn't change as longas we're on the '''Car''' page.


===Резюме===
The bare bones example we have shown demonstrates how easily wizardnavigation can be programmed using the new [[Qt:Документация_4.3.2/qwizard  | QWizard]] and[[Qt:Документация_4.3.2/qwizardpage  | QWizardPage]] classes. Most importantly, we have seen howreimplementing virtual functions lets us answer some commonquestions about wizard navigation: When is the user allowed to moveto the next page, which page is to be considered the next one, andon which page can the user accept the current input and close thewizard?In addition to providing easy access to data across the wizard, thefield mechanism we have used offers a basic but extremely convenienttype of page validation through mandatory fields.


[[Категория:Qt_Издания]]