KJanusWidget Class Reference

Easy to use widget with many layouts. More...

#include <kjanuswidget.h>

Inheritance diagram for KJanusWidget:

[legend]

List of all members.

Public Types
enum	Face {   TreeList = 0, Tabbed, Plain, Swallow,   IconList }
Public Slots
virtual void	setFocus ()
Signals
void	aboutToShowPage (QWidget *page)
Public Member Functions
virtual int	activePageIndex () const
void	addButtonBelowList (const KGuiItem &guiitem, QObject *recv, const char *slot)
void	addButtonBelowList (const QString &text, QObject *recv, const char *slot)
virtual QGrid *	addGridPage (int n, Orientation dir, const QStringList &items, const QString &header=QString::null, const QPixmap &pixmap=QPixmap())
virtual QGrid *	addGridPage (int n, Orientation dir, const QString &itemName, const QString &header=QString::null, const QPixmap &pixmap=QPixmap())
virtual QHBox *	addHBoxPage (const QStringList &items, const QString &header=QString::null, const QPixmap &pixmap=QPixmap())
virtual QHBox *	addHBoxPage (const QString &itemName, const QString &header=QString::null, const QPixmap &pixmap=QPixmap())
virtual QFrame *	addPage (const QStringList &items, const QString &header=QString::null, const QPixmap &pixmap=QPixmap())
virtual QFrame *	addPage (const QString &item, const QString &header=QString::null, const QPixmap &pixmap=QPixmap())
virtual QVBox *	addVBoxPage (const QStringList &items, const QString &header=QString::null, const QPixmap &pixmap=QPixmap())
virtual QVBox *	addVBoxPage (const QString &item, const QString &header=QString::null, const QPixmap &pixmap=QPixmap())
void	addWidgetBelowList (QWidget *widget)
virtual int	face () const
virtual bool	isValid () const
	KJanusWidget (QWidget *parent=0, const char *name=0, int face=Plain)
virtual QSize	minimumSizeHint () const
virtual int	pageIndex (QWidget *widget) const
QString	pageTitle (int index) const
QWidget *	pageWidget (int index) const
virtual QFrame *	plainPage ()
void	removePage (QWidget *page)
virtual void	setFolderIcon (const QStringList &path, const QPixmap &pixmap)
virtual void	setIconListAllVisible (bool state)
virtual void	setRootIsDecorated (bool state)
virtual void	setShowIconsInTreeList (bool state)
virtual bool	setSwallowedWidget (QWidget *widget)
virtual void	setTreeListAutoResize (bool state)
virtual bool	showPage (int index)
virtual QSize	sizeHint () const
void	unfoldTreeList (bool persist=false)
	~KJanusWidget ()
Protected Member Functions
void	addPageWidget (QFrame *page, const QStringList &items, const QString &header, const QPixmap &pixmap)
virtual bool	eventFilter (QObject *o, QEvent *e)
QWidget *	FindParent ()
void	InsertTreeListItem (const QStringList &items, const QPixmap &pixmap, QFrame *page)
virtual void	showEvent (QShowEvent *)
bool	showPage (QWidget *w)
virtual void	virtual_hook (int id, void *data)

---

Detailed Description

Easy to use widget with many layouts.

Provides a number of ready to use layouts (faces). It is used as an internal widget in KDialogBase, but can also used as a widget of its own.

This class provides KJanusWidget::TreeList, KJanusWidget::IconList, KJanusWidget::Tabbed, KJanusWidget::Plain and KJanusWidget::Swallow layouts.

For all modes it is important that you specify the QWidget::minimumSize() on the page, plain widget or the swallowed widget. If you use a QLayout on the page, plain widget or the swallowed widget this will be taken care of automatically. The size is used when the KJanusWidget determines its own minimum size. You get the minimum size by using the minimumSizeHint() or sizeHint() methods.

Pages that have been added in TreeList, IconList or Tabbed mode can be removed by simply deleting the page. However, it would be preferable to use the QObject::deleteLater() function on the page as the main event loop may have optimized UI update events of the page by scheduling them for later.

Author:

Espen Sand (espen@kde.org)

Definition at line 67 of file kjanuswidget.h.

---

Member Enumeration Documentation

enum KJanusWidget::Face

Enumerator:

TreeList	The TreeList face provides a list in the left area and pages in the right. The area are separated by a movable splitter. The style is somewhat similar to the layout in the Control Center. A page is raised by selecting the corresponding tree list item.
Tabbed	The Tabbed face is a common tabbed widget. The procedure for creating a page is similar for creating a TreeList. This has the advantage that if your widget contain too many pages it is trivial to convert it into a TreeList. Just change the face in the KJanusWidget constructor to KJanusWidget::TreeList and you have a tree list layout instead.
Plain	The Plain face provides an empty widget (QFrame) where you can place your widgets. The KJanusWidget makes no assumptions regarding the contents so you are free to add whatever you want.
Swallow	The Swallow face is provided in order to simplify the usage of existing widgets and to allow changing the visible widget. You specify the widget to be displayed by setSwallowedWidget(). Your widget will be reparented inside the widget. You can specify a Null (0) widget. A empty space is then displayed.
IconList	The IconList face provides an icon list in the left area and pages in the right. For each entry the Icon is on top with the text below. The style is somewhat similar to the layout of the Eudora configuation dialog box. A page is raised by selecting the corresponding icon list item. The preferred icon size is 32x32 pixels.

Definition at line 89 of file kjanuswidget.h.

---

Constructor & Destructor Documentation

KJanusWidget::KJanusWidget	(	QWidget *	parent = 0,
		const char *	name = 0,
		int	face = Plain
	)

Constructor where you specify the face.

Parameters:

	parent	Parent of the widget.
	name	Widget name.
	face	The kind of dialog, Use TreeList, Tabbed, Plain or Swallow.

Definition at line 87 of file kjanuswidget.cpp.

KJanusWidget::~KJanusWidget

(

)

Destructor.

Definition at line 202 of file kjanuswidget.cpp.

---

Member Function Documentation

void KJanusWidget::aboutToShowPage

(

QWidget *

page

)

[signal]

This signal is emitted whenever the current page changes.

Parameters:

page

the new page.

Since:

3.4

int KJanusWidget::activePageIndex

(

)

const [virtual]

Returns the index of the page that are currently displayed.

Returns:

The index or -1 if the face is not Tabbed, TreeList or IconList.

Definition at line 641 of file kjanuswidget.cpp.

void KJanusWidget::addButtonBelowList	(	const KGuiItem &	guiitem,
		QObject *	recv,
		const char *	slot
	)

The same as the above function, but with a KGuiItem providing the text and icon for the button at the bottom of the TreeList/IconList.

Parameters:

	guiitem	The text and icon on the PushButton.
	recv	The object that is to receive the signal when the button is clicked.
	slot	The slot to connect to the clicked signal of the button.

Since:

3.2

Definition at line 874 of file kjanuswidget.cpp.

void KJanusWidget::addButtonBelowList	(	const QString &	text,
		QObject *	recv,
		const char *	slot
	)

Add a button at the bottom of the TreeList/IconList.

Parameters:

	text	The text on the PushButton.
	recv	The object that is to receive the signal when the button is clicked.
	slot	The slot to connect to the clicked signal of the button.

Since:

3.2

Definition at line 865 of file kjanuswidget.cpp.

QGrid * KJanusWidget::addGridPage	(	int	n,
		Orientation	dir,
		const QStringList &	items,
		const QString &	header = QString::null,
		const QPixmap &	pixmap = QPixmap()
	)			[virtual]

This is like addGridPage just above, with the difference that the first element is a list of strings.

These strings are used to form a path of folders down to the given page. The initial elements are names for the folders, while the last element is the name of the page. Note: This does yet only work for the TreeList face. Later this may be added for the IconList face too. In other faces than the TreeList, all the strings except the last one is ignored.

Deleting the returned frame will cause the listitem or tab to be removed (you can re-add a page with the same name later.

Definition at line 322 of file kjanuswidget.cpp.

QGrid * KJanusWidget::addGridPage	(	int	n,
		Orientation	dir,
		const QString &	itemName,
		const QString &	header = QString::null,
		const QPixmap &	pixmap = QPixmap()
	)			[virtual]

Add a new page when the class is used in either TreeList or Tabbed mode.

The returned widget is empty and you must add your widgets as children to this widget. The returned widget is a QGrid so it contains a QGridLayout layout that places up the child widgets in a grid.

Deleting the returned frame will cause the listitem or tab to be removed (you can re-add a page with the same name later.

Parameters:

	n	Specifies the number of columns if 'dir' is QGrid::Horizontal or the number of rows if 'dir' is QGrid::Vertical.
	dir	Can be QGrid::Horizontal or QGrid::Vertical.
	itemName	String used in the list or Tab item.
	header	A longer string used in TreeList and IconList mode to describe the contents of a page. If empty, the item string will be used instead.
	pixmap	Used in IconList mode or in TreeList mode. You should prefer a pixmap with size 32x32 pixels.

Returns:

The empty page or 0 if the face is not TreeList, IconList or Tabbed.

Definition at line 341 of file kjanuswidget.cpp.

QHBox * KJanusWidget::addHBoxPage	(	const QStringList &	items,
		const QString &	header = QString::null,
		const QPixmap &	pixmap = QPixmap()
	)			[virtual]

This is like addHBoxPage just above, with the difference that the first element is a list of strings.

These strings are used to form a path of folders down to the given page. The initial elements are names for the folders, while the last element is the name of the page. Note: This does yet only work for the TreeList face. Later this may be added for the IconList face too. In other faces than the TreeList, all the strings except the last one is ignored.

Deleting the returned frame will cause the listitem or tab to be removed (you can re-add a page with the same name later.

Definition at line 297 of file kjanuswidget.cpp.

QHBox * KJanusWidget::addHBoxPage	(	const QString &	itemName,
		const QString &	header = QString::null,
		const QPixmap &	pixmap = QPixmap()
	)			[virtual]

Add a new page when the class is used in TreeList, IconList or Tabbed mode.

The returned widget is empty and you must add your widgets as children to this widget. The returned widget is a QHBox so it contains a QHBoxLayout layout that lines up the child widgets are horizontally.

Deleting the returned frame will cause the listitem or tab to be removed (you can re-add a page with the same name later.

Parameters:

	itemName	String used in the list or Tab item.
	header	A longer string used in TreeList and IconList mode to describe the contents of a page. If empty, the item string will be used instead.
	pixmap	Used in IconList mode or in TreeList mode. You should prefer a pixmap with size 32x32 pixels.

Returns:

The empty page or 0 if the face is not TreeList, IconList or Tabbed.

Definition at line 313 of file kjanuswidget.cpp.

QFrame * KJanusWidget::addPage	(	const QStringList &	items,
		const QString &	header = QString::null,
		const QPixmap &	pixmap = QPixmap()
	)			[virtual]

This is like addPage just above, with the difference that the first element is a list of strings.

These strings are used to form a path of folders down to the given page. The initial elements are names for the folders, while the last element is the name of the page. Note: This does yet only work for the TreeList face. Later this may be added for the IconList face too. In other faces than the TreeList, all the strings except the last one is ignored. Deleting the returned frame will cause the listitem or tab to be removed (you can re-add a page with the same name later.

Deleting the returned frame will cause the listitem or tab to be removed (you can re-add a page with the same name later.

Definition at line 235 of file kjanuswidget.cpp.

QFrame * KJanusWidget::addPage	(	const QString &	item,
		const QString &	header = QString::null,
		const QPixmap &	pixmap = QPixmap()
	)			[virtual]

Add a new page when the class is used in TreeList, IconList or Tabbed mode.

The returned widget is empty and you must add your widgets as children to this widget. In most cases you must create a layout manager and associate it with this widget as well.

Deleting the returned frame will cause the listitem or tab to be removed (you can re-add a page with the same name later.

Parameters:

	item	String used in the list or Tab item.
	header	A longer string used in TreeList and IconList mode to describe the contents of a page. If empty, the item string will be used instead.
	pixmap	Used in IconList mode or in TreeList mode. You should prefer a pixmap with size 32x32 pixels.

Returns:

The empty page or 0 if the face is not TreeList, IconList or Tabbed.

Definition at line 261 of file kjanuswidget.cpp.

void KJanusWidget::addPageWidget	(	QFrame *	page,
		const QStringList &	items,
		const QString &	header,
		const QPixmap &	pixmap
	)			[protected]

Definition at line 425 of file kjanuswidget.cpp.

QVBox * KJanusWidget::addVBoxPage	(	const QStringList &	items,
		const QString &	header = QString::null,
		const QPixmap &	pixmap = QPixmap()
	)			[virtual]

This is like addVBoxPage just above, with the difference that the first element is a list of strings.

These strings are used to form a path of folders down to the given page. The initial elements are names for the folders, while the last element is the name of the page. Note: This does yet only work for the TreeList face. Later this may be added for the IconList face too. In other faces than the TreeList, all the strings except the last one is ignored.

Deleting the returned frame will cause the listitem or tab to be removed (you can re-add a page with the same name later.

Definition at line 271 of file kjanuswidget.cpp.

QVBox * KJanusWidget::addVBoxPage	(	const QString &	item,
		const QString &	header = QString::null,
		const QPixmap &	pixmap = QPixmap()
	)			[virtual]

Add a new page when the class is used in TreeList, IconList or Tabbed mode.

The returned widget is empty and you must add your widgets as children to this widget. The returned widget is a QVBox so it contains a QVBoxLayout layout that lines up the child widgets are vertically.

Deleting the returned frame will cause the listitem or tab to be removed (you can re-add a page with the same name later.

Parameters:

	item	String used in the list or Tab item.
	header	A longer string used in TreeList and IconList mode to describe the contents of a page. If empty, the item string will be used instead.
	pixmap	Used in IconList mode or in TreeList mode. You should prefer a pixmap with size 32x32 pixels.

Returns:

The empty page or 0 if the face is not TreeList, IconList or Tabbed.

Definition at line 288 of file kjanuswidget.cpp.

void KJanusWidget::addWidgetBelowList

(

QWidget *

widget

)

Add a widget at the bottom of the TreeList/IconList.

Parameters:

widget

The widget to be added. It will be reparented into the KJanusWidget, therefor it will be deleted with the KJanusWidget, too. To be on the save side just don't keep the pointer to this widget.

Definition at line 857 of file kjanuswidget.cpp.

bool KJanusWidget::eventFilter	(	QObject *	o,
		QEvent *	e
	)			[protected, virtual]

This function is used internally when in IconList mode.

If you reimplement this class a make your own event filter, make sure to call this function from your filter.

Parameters:

	o	Object that has received an event.
	e	The event.

Definition at line 898 of file kjanuswidget.cpp.

int KJanusWidget::face

(

)

const [virtual]

Returns the face type.

Returns:

The face type.

Definition at line 220 of file kjanuswidget.cpp.

QWidget * KJanusWidget::FindParent

(

)

[protected]

Definition at line 225 of file kjanuswidget.cpp.

void KJanusWidget::InsertTreeListItem	(	const QStringList &	items,
		const QPixmap &	pixmap,
		QFrame *	page
	)			[protected]

Definition at line 351 of file kjanuswidget.cpp.

bool KJanusWidget::isValid

(

)

const [virtual]

Use this to verify that no memory allocation failed.

Returns:

true if the widget was properly created.

Definition at line 208 of file kjanuswidget.cpp.

QSize KJanusWidget::minimumSizeHint

(

void

)

const [virtual]

Returns the minimum size that must be made available for the widget so that UIs can be displayed properly.

Returns:

The minimum size.

Reimplemented from QWidget.

Definition at line 750 of file kjanuswidget.cpp.

int KJanusWidget::pageIndex

(

QWidget *

widget

)

const [virtual]

Returns the index of a page created with addPage , addVBoxPage , addHBoxPage or addGridPage .

You can can compare this index with the value returned from activePageIndex if you need to do some page specific actions in your code.

The returned index will never change so you can safely use this function once and save the value.

Parameters:

widget

The widget returned by addPage , addVBoxPage , addHBoxPage or addGridPage .

Returns:

The index or -1 if the face is not Tabbed, TreeList or IconList

Definition at line 665 of file kjanuswidget.cpp.

QString KJanusWidget::pageTitle

(

int

index

)

const

Returns the title string associated with a page index in TreeList or IconList mode.

Parameters:

index

The index of the page or null if there is no such page.

See also:

pageIndex()

Since:

3.2

Definition at line 1132 of file kjanuswidget.cpp.

QWidget * KJanusWidget::pageWidget

(

int

index

)

const

Returns the page widget associated with a page index or null if there is no such page.

Parameters:

index

The index of the page.

See also:

pageIndex()

Since:

3.2

Definition at line 1140 of file kjanuswidget.cpp.

QFrame * KJanusWidget::plainPage

(

)

[virtual]

Returns the empty widget that is available in Plain mode.

Returns:

The widget or 0 if the face in not Plain.

Definition at line 214 of file kjanuswidget.cpp.

void KJanusWidget::removePage

(

QWidget *

page

)

Removes a page created with addPage, addVBoxPage, addHBoxPage or addGridPage.

If the page has already been deleted or has already been removed, nothing happens. The widget itself is not deleted.

Parameters:

page

The widget returned by addPage , addVBoxPage , addHBoxPage or addGridPage .

Definition at line 1087 of file kjanuswidget.cpp.

void KJanusWidget::setFocus

(

)

[virtual, slot]

Give the keyboard input focus to the widget.

Reimplemented from QWidget.

Definition at line 724 of file kjanuswidget.cpp.

void KJanusWidget::setFolderIcon	(	const QStringList &	path,
		const QPixmap &	pixmap
	)			[virtual]

Sets the icon used in TreeList Mode for the given path.

Parameters:

	path	The path for which this icon should be shown.
	pixmap	The icon used.

Definition at line 488 of file kjanuswidget.cpp.

void KJanusWidget::setIconListAllVisible

(

bool

state

)

[virtual]

This function has only effect in IconList mode.

Defines how the icon list widget is displayed. By default it is the widgets in the pages that decide the minimum height of the toplevel widget. A vertical scrollbar can be used in the icon list area.

Parameters:

state

The visibility mode. If true, the minimum height is adjusted so that every icon in the list is visible at the same time. The vertical scrollbar will never be visible.

Definition at line 823 of file kjanuswidget.cpp.

void KJanusWidget::setRootIsDecorated

(

bool

state

)

[virtual]

This function has only effect in TreeList mode.

This tells the widgets whether the root should be decorated. For details see QListView::setRootIsDecorated

Parameters:

state

Root will be decorated if true.

Definition at line 836 of file kjanuswidget.cpp.

void KJanusWidget::setShowIconsInTreeList

(

bool

state

)

[virtual]

This function has only effect in TreeList mode.

This tells the widgets whether the icons given in the addPage, addVBoxPage, addHBoxPage, or addGridPage methods should be shown in the TreeList.

Note: This method must be called before calling any of the methods which add icons to the page.

Parameters:

state

If true the icons are shown.

Definition at line 831 of file kjanuswidget.cpp.

bool KJanusWidget::setSwallowedWidget

(

QWidget *

widget

)

[virtual]

Defines the widget to be swallowed.

This method can be used several times. Only the latest defined widget will be shown.

Parameters:

widget

The widget to be swallowed. If 0, then an empty rectangle is displayed.

Definition at line 496 of file kjanuswidget.cpp.

void KJanusWidget::setTreeListAutoResize

(

bool

state

)

[virtual]

This function has only effect in TreeList mode.

Defines how the tree list is resized when the widget is resized horizontally. By default the tree list keeps its width when the widget becomes wider.

Parameters:

state

The resize mode. If false (default) the TreeList keeps its current width when the widget becomes wider.

Definition at line 811 of file kjanuswidget.cpp.

void KJanusWidget::showEvent

(

QShowEvent *

)

[protected, virtual]

Reimplemented to handle the splitter width when the the face is TreeList.

Reimplemented from QWidget.

Definition at line 883 of file kjanuswidget.cpp.

bool KJanusWidget::showPage

(

QWidget *

w

)

[protected]

Definition at line 588 of file kjanuswidget.cpp.

bool KJanusWidget::showPage

(

int

index

)

[virtual]

Raises the page which was added by addPage().

Parameters:

index

The index of the page you want to raise.

Definition at line 575 of file kjanuswidget.cpp.

QSize KJanusWidget::sizeHint

(

void

)

const [virtual]

Returns the recommended size for the widget in order to be displayed properly.

Returns:

The recommended size.

Reimplemented from QWidget.

Definition at line 805 of file kjanuswidget.cpp.

void KJanusWidget::unfoldTreeList

(

bool

persist = false

)

This function has only effect in TreeList mode.

This tells the TreeList to unfold the whole tree so that all entries are visible.

If the list is empty when you call this method newly created entries will not automatically be opened. If the persist flag is set opened entries cannot be closed again, though.

Parameters:

persist

If true the tree always stays unfolded.

Since:

3.2

Definition at line 843 of file kjanuswidget.cpp.

void KJanusWidget::virtual_hook	(	int	id,
		void *	data
	)			[protected, virtual]

Definition at line 1082 of file kjanuswidget.cpp.

---

The documentation for this class was generated from the following files:

• kjanuswidget.h
• kjanuswidget.cpp