Редактирование: 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?

===Пример "Книга заказов парома"===
Мы будем использовать мастер заказов паромной переправы, чтобы проилюстрировать различные концепции нового каркаса мастеров. Пять используемых страниц, умышленно сделаны очень простыми: Страница для выбора даты отплытия, страница для ввода имени единственного пассажира, страница для выбора типа каюты, страница для указания госномера автомобиля, в случае если вы хотите перевести ваш автомобиль и, наконец, страница ввода номера кредитной карты.

Следующая диаграмма изображает возможные пути навигации с помощью мастера:

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

Исходная реализация выглядит подобно этой:
<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> 
Следующий фрагмент кода показывает как открыть мастер и собрать результаты из него:
<source lang="cpp-qt">
BookingWizard wizard;
if (wizard.exec()) {
    qDebug() << "booking accepted";
    qDebug() << "sailing date:" << wizard.sailingDate();
    qDebug() << "passenger:" << wizard.passengerName();
    ...
}
</source> 
Обратите внимание, как класс <tt>BookingWizard</tt> должен хранить указатели на виджеты ввода всех страниц для того, чтобы реализовать открытый интерфейс. Кроме того, если страница нуждается в доступе к виджету ввода с другой страницы, то указатель на виджет ввода должен быть передан обоим страницам.

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

Чтобы решить проблему идентификации, указанную выше, мы можем использовать механизм полей [[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> 
А что со свойством и сигналом изменения? Они могут быть переданы, как третий и четвертый аргументы в <tt>registerField()</tt>, но опуская их (в действительности передавая нулевой указатель), мы говорим [[Qt:Документация_4.3.2/qwizardpage  | QWizardPage]], что мы хотели бы использовать здесь значение по умолчанию. [[Qt:Документация_4.3.2/qwizardpage  | QWizardPage]] знает о наиболее общих типах виджетов ввода. Так как [[Qt:Документация_4.3.2/qlineedit  | QLineEdit]] из числа таких счастливчиков (и подкласс тоже), свойство <tt>text</tt> и сигнал <tt>textChanged()</tt> используются автоматически.

В качестве альтернативы, мы могли бы добавить [[Qt:Документация_4.3.2/qcalendarwidget  | QCalendarWidget]] в список распознаваемых типов полей [[Qt:Документация_4.3.2/qwizard  | QWizard]]'а, раз и на всегда:
<source lang="cpp-qt">
setDefaultProperty("QCalendarWidget", "selectedDate", SIGNAL(selectionChanged()));
</source>

===Проверяйте, пока это не слишком поздно===

Если какая-то информация в мастере не верна или недопустима (например, неуказано имя пассажира), она, в данный момент, не обнаруживается до тех пор пока мастер небудет закрыт. Мастер затем должен быть вновь открыт, и вся информация, включая поля, которые были не верны в первый раз, должны быть введены снова. Это очень утомительный, подверженный ошибкам, и повторяющийся процесс, который делает бессмысленной цель использования мастера.

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.

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

Сейчас мы собираемся поддержать другую особенность паромной компании: по субботам автомобили на паром не допускаются. Если пользователь выбирает субботу для отплытия, страница '''Car''' (Автомобиль) пропускается полностью.

[[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_Издания]]