Contents

KPageDialog Class

A dialog base class which can handle multiple pages. More...

Header: #include <KPageDialog>
CMake: find_package(KF6 REQUIRED COMPONENTS WidgetsAddons)
target_link_libraries(mytarget PRIVATE KF6::WidgetsAddons)
Inherits: QDialog
Inherited By:

KAssistantDialog

Public Types

enum FaceType { Auto, Plain, List, Tree, Tabbed, FlatList }

Public Functions

KPageDialog(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())
void addActionButton(QAbstractButton *button)
void addPage(KPageWidgetItem *item)
KPageWidgetItem *addPage(QWidget *widget, const QString &name)
void addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item)
KPageWidgetItem *addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name)
QPushButton *button(QDialogButtonBox::StandardButton which) const
KPageWidgetItem *currentPage() const
void insertPage(KPageWidgetItem *before, KPageWidgetItem *item)
KPageWidgetItem *insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name)
void removePage(KPageWidgetItem *item)
void setCurrentPage(KPageWidgetItem *item)
void setFaceType(KPageDialog::FaceType faceType)
void setStandardButtons(QDialogButtonBox::StandardButtons buttons)

Signals

void currentPageChanged(KPageWidgetItem *current, KPageWidgetItem *before)
void pageRemoved(KPageWidgetItem *page)

Protected Functions

KPageDialog(KPageWidget *widget, QWidget *parent, Qt::WindowFlags flags = Qt::WindowFlags())
QDialogButtonBox *buttonBox()
const QDialogButtonBox *buttonBox() const
KPageWidget *pageWidget()
const KPageWidget *pageWidget() const
void setButtonBox(QDialogButtonBox *box)
void setPageWidget(KPageWidget *widget)

Detailed Description

This class provides a dialog base class which handles multiple pages and allows the user to switch between these pages in different ways.

Currently, Auto, Plain, List, Tree and Tabbed face types are available (cmp. KPageView).

By default a QDialogButtonBox is added to the dialog with two buttons, OK (QDialogButtonBox::Ok) and Cancel (QDialogButtonBox::Cancel). You can customize which buttons are added to the dialog by using any of the available buttons-related methods.

Note that if there is a QDialogButtonBox (either the one added by default, or one you added manually) some logical connections are created:

this means that you shouldn't create these connections again (otherwise you would end up receiving two duplicate accepted() signals for example).

Example:

UrlDialog::UrlDialog( QWidget *parent )
  : KPageDialog( parent )
{
  setFaceType(List);

  QLabel *label = new QLabel("Test Page");
  addPage(label, i18n("My Test Page"));

  label = new QLabel("Second Test Page");
  KPageWidgetItem *page = new KPageWidgetItem(label, i18n("My Second Test Page"));
  page->setHeader(i18n("My header string"));
  page->setIcon(QIcon::fromTheme("file"));

  addPage(page);

  // Change the buttons added to the dialog
  setStandardButtons(QDialogButtonBox::Ok | QDialogButtonBox::Apply | QDialogButtonBox::Cancel);

  // Alternatively you can create a QDialogButtonBox, add the buttons you want to it,
  // then add that button box to the dialog
  QDialogButtonBox *btnBox = new QDialogButtonBox(QDialogButtonBox::Ok | QDialogButtonBox::Apply | QDialogButtonBox::Cancel,
                                                  Qt::Horizontal,
                                                  this);
  setButtonBox(btnBox);
}

Member Type Documentation

enum KPageDialog::FaceType

The face types supported.

ConstantValueDescription
KPageDialog::AutoKPageView::AutoA dialog with a face based on the structure of the available pages. If only a single page is added, the dialog behaves like in Plain mode, with multiple pages without sub pages it behaves like in List mode and like in Tree mode otherwise.
KPageDialog::PlainKPageView::PlainA normal dialog
KPageDialog::ListKPageView::ListA dialog with an icon list on the left side and a representation of the contents on the right side
KPageDialog::TreeKPageView::TreeA dialog with a tree on the left side and a representation of the contents on the right side
KPageDialog::TabbedKPageView::TabbedA dialog with a tab bar above the representation of the contents
KPageDialog::FlatListKPageView::FlatListA dialog with an flat list with small icons on the left side and a representation of the contents on the right side

Member Function Documentation

[explicit] KPageDialog::KPageDialog(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())

Creates a new page dialog.

[protected] KPageDialog::KPageDialog(KPageWidget *widget, QWidget *parent, Qt::WindowFlags flags = Qt::WindowFlags())

This constructor can be used by subclasses to provide a custom page widget.

widget The KPageWidget object will be reparented to this object, so you can create it without parent and you are not allowed to delete it.

void KPageDialog::addActionButton(QAbstractButton *button)

Set an action button.

void KPageDialog::addPage(KPageWidgetItem *item)

Adds a new top level page to the dialog.

item The KPageWidgetItem which describes the page.

KPageWidgetItem *KPageDialog::addPage(QWidget *widget, const QString &name)

Adds a new top level page to the dialog.

widget The widget of the page.

name The name which is displayed in the navigation view.

Returns the associated KPageWidgetItem.

void KPageDialog::addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item)

Inserts a new sub page in the dialog.

parent The new page will be insert as child of this KPageWidgetItem.

item The KPageWidgetItem which describes the page.

KPageWidgetItem *KPageDialog::addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name)

Inserts a new sub page in the dialog.

parent The new page will be insert as child of this KPageWidgetItem.

widget The widget of the page.

name The name which is displayed in the navigation view.

Returns the associated KPageWidgetItem.

QPushButton *KPageDialog::button(QDialogButtonBox::StandardButton which) const

Returns the QPushButton corresponding to the standard button which, or a null pointer if the standard button doesn't exist in this dialog.

[protected] QDialogButtonBox *KPageDialog::buttonBox()

Returns the button box of the dialog or a null pointer if no button box is set.

See also setButtonBox().

[protected] const QDialogButtonBox *KPageDialog::buttonBox() const

Returns the button box of the dialog or a null pointer if no button box is set.

KPageWidgetItem *KPageDialog::currentPage() const

Returns the KPageWidgetItem for the current page or a null pointer if there is no current page.

See also setCurrentPage().

[signal] void KPageDialog::currentPageChanged(KPageWidgetItem *current, KPageWidgetItem *before)

This signal is emitted whenever the current page has changed.

current The new current page or a null pointer if no current page is available.

before The page that was current before the new current page has changed.

void KPageDialog::insertPage(KPageWidgetItem *before, KPageWidgetItem *item)

Inserts a new page in the dialog.

before The new page will be insert before this KPageWidgetItem on the same level in hierarchy.

item The KPageWidgetItem which describes the page.

KPageWidgetItem *KPageDialog::insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name)

Inserts a new page in the dialog.

before the new page will be insert before this KPageWidgetItem on the same level in hierarchy.

widget the widget of the page.

name the name which is displayed in the navigation view.

Returns the associated KPageWidgetItem.

[signal] void KPageDialog::pageRemoved(KPageWidgetItem *page)

This signal is emitted whenever a page has been removed.

page The page which has been removed

[protected] KPageWidget *KPageDialog::pageWidget()

Returns the page widget of the dialog or a null pointer if no page widget is set.

See also setPageWidget().

[protected] const KPageWidget *KPageDialog::pageWidget() const

Returns the page widget of the dialog or a null pointer if no page widget is set.

void KPageDialog::removePage(KPageWidgetItem *item)

Removes the page associated with the given KPageWidgetItem.

[protected] void KPageDialog::setButtonBox(QDialogButtonBox *box)

Set the button box of the dialog

Note: the previous buttonBox will be deleted.

box The QDialogButtonBox object will be reparented to this object, so you can create it without parent and you are not allowed to delete it.

See also buttonBox().

void KPageDialog::setCurrentPage(KPageWidgetItem *item)

Sets the page which is associated with the given KPageWidgetItem to be the current page and emits the currentPageChanged() signal.

See also currentPage().

void KPageDialog::setFaceType(KPageDialog::FaceType faceType)

Sets the face type of the dialog.

[protected] void KPageDialog::setPageWidget(KPageWidget *widget)

Set the page widget of the dialog.

Note: the previous pageWidget will be deleted.

widget The KPageWidget object will be reparented to this object, so you can create it without parent and you are not allowed to delete it.

See also pageWidget().

void KPageDialog::setStandardButtons(QDialogButtonBox::StandardButtons buttons)

Sets the collection of standard buttons displayed by this dialog.