# kio Library API Documentation

Overview | Class Hierarchy | Classes | Classes (annotated) | Members | Source Files

# KURLBar Class Reference

KURLBar is a widget that displays icons together with a description. A URL-bar widget, as used in the KFileDialog. More...

`#include <kurlbar.h>`

Inheritance diagram for KURLBar:

[legend]
Collaboration diagram for KURLBar:

[legend]
List of all members.

## Public Slots

virtual void | setCurrentItem (const KURL &url)
| Makes the item with the url `url` the current item.

## Signals

void | activated (const KURL &url)
| This signal is emitted when the user activated an item, e.g by clicking on it.

## Public Member Functions

| KURLBar (bool useGlobalItems, QWidget *parent=0, const char *name=0, WFlags f=0)
| Constructs a KURLBar.
| ~KURLBar ()
| Destroys the KURLBar.
virtual KURLBarItem * | insertItem (const KURL &url, const QString &description, bool applicationLocal=true, const QString &icon=QString::null, KIcon::Group group=KIcon::Panel)
| Inserts a new item into the KURLBar and returns the created KURLBarItem.
virtual void | setOrientation (Qt::Orientation orient)
| The items can be arranged either vertically in one column or horizontally in one row.
Orientation | orientation () const
virtual void | setListBox (KURLBarListBox *)
| Allows to set a custom KURLBarListBox.
KURLBarListBox * | listBox () const
virtual void | setIconSize (int size)
| Sets the default iconsize to be used for items inserted with insertItem.
int | iconSize () const
virtual void | clear ()
| Clears the view, removes all items.
virtual QSize | sizeHint () const
virtual QSize | minimumSizeHint () const
virtual void | readConfig (KConfig *config, const QString &itemGroup)
| Call this method to read a saved configuration from `config`, inside the group `itemGroup`.
virtual void | writeConfig (KConfig *config, const QString &itemGroup)
| Call this method to save the current configuration into `config`, inside the group `iconGroup`.
virtual void | readItem (int i, KConfig *config, bool applicationLocal)
| Called from readConfig() to read the i'th from `config`.
virtual void | writeItem (KURLBarItem *item, int i, KConfig *, bool global)
| Called from writeConfig() to save the KURLBarItem `item` as the i'th entry in the config-object.
KURLBarItem * | currentItem () const
KURL | currentURL () const
bool | isModified () const
bool | isImmutable () const
bool | isVertical () const

## Protected Slots

virtual void | slotContextMenuRequested (QListBoxItem *, const QPoint &pos)
| Reimplemented to show a contextmenu, allowing the user to add, edit or remove items, or change the iconsize.
virtual void | slotSelected (QListBoxItem *)
| Called when an item has been selected.
virtual void | slotDropped (QDropEvent *)
| Called when a url was dropped onto the bar to show a KURLBarItemDialog.

## Protected Member Functions

virtual bool | addNewItem ()
| Pops up a KURLBarItemDialog to let the user add a new item.
virtual bool | editItem (KURLBarItem *item)
| Pops up a KURLBarItemDialog to let the user edit the properties of `item`.
virtual void | resizeEvent (QResizeEvent *)
virtual void | virtual_hook (int id, void *data)

## Protected Attributes

KURLBarItem * | m_activeItem
| The currently active item.
bool | m_useGlobal:1
| Whether we support global entries or just local ones.
bool | m_isModified:1
| Whether the urlbar was modified by the user (e.g.
bool | m_isImmutable:1
| Whether the urlbar may be modified by the user.

## Detailed Description

KURLBar is a widget that displays icons together with a description. A URL-bar widget, as used in the KFileDialog.

They can be arranged either horizontally or vertically. Clicking on an item will make the activated() signal being emitted. The user can edit existing items by choosing "Edit entry" in the contextmenu. He can also remove or add new entries (via drag&drop or the context menu).

KURLBar offers the methods readConfig() and writeConfig() to read and write the configuration of all the entries. It can differentiate between global and local entries -- global entries will be saved in the global configuration (kdeglobals), while local entries will be saved in your application's KConfig object.

Due to the configurability, you usually only insert some default entries once and then solely use the read and writeConfig methods to preserve the user's configuration.

The widget has a "current" item, that is visualized to differentiate it from others.

Author:
  Carsten Pfeiffer <pfeiffer@kde.org>

Definition at line 198 of file kurlbar.h.

## Constructor & Destructor Documentation

KURLBar::KURLBar | ( | bool | useGlobalItems,
|  | QWidget * | parent = 0,
|  | const char * | name = 0,
|  | WFlags | f = 0
| ) |

| Constructs a KURLBar. Set `useGlobalItems` to true if you want to allow global/local item separation. Definition at line 239 of file kurlbar.cpp. References QWhatsThis::add(), isVertical(), m_activeItem, m_isImmutable, m_isModified, m_useGlobal, KStdAccel::name(), and setListBox().

KURLBar::~KURLBar | ( |  | ) |

| Destroys the KURLBar. Definition at line 262 of file kurlbar.cpp.

## Member Function Documentation

KURLBarItem * KURLBar::insertItem | ( | const KURL & | url,
|  | const QString & | description,
|  | bool | applicationLocal = true,
|  | const QString & | icon = QString::null,
|  | KIcon::Group | group = KIcon::Panel
| ) | `[virtual]`

Inserts a new item into the KURLBar and returns the created KURLBarItem.

`url` the url of the item `description` the description of the item (shown in the view) `applicationLocal` whether this should be a global or a local item `icon` an icon -- if empty, the default icon for the url will be used `group` the icon-group for using icon-effects

Definition at line 267 of file kurlbar.cpp.

References KStdAccel::description(), QListBox::insertItem(), and KURLBarItem::setApplicationLocal().

Referenced by readItem(), and slotDropped().

void KURLBar::setOrientation | ( | Qt::Orientation | orient | ) | `[virtual]`

The items can be arranged either vertically in one column or horizontally in one row.

See also:
  orientation

Definition at line 277 of file kurlbar.cpp.

References isVertical(), and KURLBarListBox::setOrientation().

Referenced by setListBox().

Qt::Orientation KURLBar::orientation | ( |  | ) | const

Returns:
  the current orientation mode.

See also:
  setOrientation

Definition at line 288 of file kurlbar.cpp.

References KURLBarListBox::orientation().

Referenced by isVertical().

void KURLBar::setListBox | ( | KURLBarListBox * |  | ) | `[virtual]`

Allows to set a custom KURLBarListBox.

Note: The previous listbox will be deleted. Items of the previous listbox will not be moved to the new box.

See also:
  listBox

Definition at line 293 of file kurlbar.cpp.

References QPalette::color(), QPalette::setColor(), setOrientation(), QListBox::setSelectionMode(), slotContextMenuRequested(), slotDropped(), and slotSelected().

Referenced by KURLBar().

KURLBarListBox* KURLBar::listBox | ( |  | ) | const`[inline]`

Returns:
  the KURLBarListBox that is used.

See also:
  setListBox

Definition at line 252 of file kurlbar.h.

void KURLBar::setIconSize | ( | int | size | ) | `[virtual]`

Sets the default iconsize to be used for items inserted with insertItem.

By default KIcon::SizeMedium.

See also:
  #iconsize

Definition at line 330 of file kurlbar.cpp.

References QListBox::firstItem(), KURLBarItem::icon(), KURLBarItem::iconGroup(), KURLBarItem::setIcon(), and sizeHint().

Referenced by slotContextMenuRequested().

int KURLBar::iconSize | ( |  | ) | const`[inline]`

Returns:
  the default iconsize used for items inserted with insertItem. By default KIcon::SizeMedium

See also:
  setIconSize

Definition at line 265 of file kurlbar.h.

Referenced by KURLBarItem::sizeHint().

void KURLBar::clear | ( |  | ) | `[virtual]`

| Clears the view, removes all items. Definition at line 348 of file kurlbar.cpp. References QListBox::clear().

QSize KURLBar::sizeHint | ( |  | ) | const`[virtual]`

Returns:
  a proper sizehint, depending on the orientation and number of items available.

Definition at line 359 of file kurlbar.cpp.

References QListBox::firstItem(), QSize::height(), isVertical(), KURLBarItem::sizeHint(), and QSize::width().

Referenced by minimumSizeHint(), and setIconSize().

QSize KURLBar::minimumSizeHint | ( |  | ) | const`[virtual]`

| Definition at line 401 of file kurlbar.cpp. References QSize::height(), sizeHint(), and QSize::width().

void KURLBar::readConfig | ( | KConfig * | config,
|  | const QString & | itemGroup
| ) | `[virtual]`

| Call this method to read a saved configuration from `config`, inside the group `itemGroup`. All items in there will be restored. The reading of every item is delegated to the readItem() method. Definition at line 470 of file kurlbar.cpp. References KGlobal::config(), KConfigBase::groupIsImmutable(), m_isImmutable, m_useGlobal, readItem(), and KConfigBase::readNumEntry().

void KURLBar::writeConfig | ( | KConfig * | config,
|  | const QString & | itemGroup
| ) | `[virtual]`

| Call this method to save the current configuration into `config`, inside the group `iconGroup`. The writeItem() method is used to save each item. Definition at line 528 of file kurlbar.cpp. References KURLBarItem::applicationLocal(), QListBox::firstItem(), m_isModified, m_useGlobal, KConfigBase::setGroup(), KConfigBase::writeEntry(), and writeItem().

void KURLBar::readItem | ( | int | i,
|  | KConfig * | config,
|  | bool | applicationLocal
| ) | `[virtual]`

Called from readConfig() to read the i'th from `config`.

After reading a KURLBarItem is created and initialized with the read values (as well as the given `applicationLocal`).

Definition at line 513 of file kurlbar.cpp.

References insertItem(), KProtocolInfo::isKnownProtocol(), KURL::isMalformed(), QString::number(), KIO::number(), KConfigBase::readEntry(), and KConfigBase::readNumEntry().

Referenced by readConfig().

void KURLBar::writeItem | ( | KURLBarItem * | item,
|  | int | i,
|  | KConfig * | ,
|  | bool | global
| ) | `[virtual]`

Called from writeConfig() to save the KURLBarItem `item` as the i'th entry in the config-object.

`global` tell whether it should be saved in the global configuration or not (using KConfig::writeEntry( key, value, true, global ) ).

Definition at line 574 of file kurlbar.cpp.

References KURLBarItem::description(), KURLBarItem::icon(), KURLBarItem::iconGroup(), KURL::isLocalFile(), QString::number(), KIO::number(), KURL::path(), KURL::prettyURL(), KURLBarItem::url(), KConfigBase::writeEntry(), and KConfigBase::writePathEntry().

Referenced by writeConfig().

KURLBarItem * KURLBar::currentItem | ( |  | ) | const

Returns:
  the current KURLBarItem, or 0L if none.

See also:
  setCurrentItem

  currentURL

Definition at line 456 of file kurlbar.cpp.

References QListBox::currentItem(), and QListBox::item().

Referenced by currentURL().

KURL KURLBar::currentURL | ( |  | ) | const

Returns:
  the url of the current item or an invalid url, if there is no current item.

See also:
  currentItem

  setCurrentItem

Definition at line 464 of file kurlbar.cpp.

References currentItem(), and KURLBarItem::url().

bool KURLBar::isModified | ( |  | ) | const`[inline]`

Returns:
  true when the urlbar was modified by the user (e.g. by editing/adding/removing one or more entries). Will be reset to false after calling writeConfig().

Definition at line 328 of file kurlbar.h.

References m_isModified.

bool KURLBar::isImmutable | ( |  | ) | const`[inline]`

Returns:
  true when the urlbar may not be modified by the user

Definition at line 333 of file kurlbar.h.

References m_isImmutable.

bool KURLBar::isVertical | ( |  | ) | const`[inline]`

Returns:
  true if the bar is in vertical mode.

Definition at line 338 of file kurlbar.h.

References orientation().

Referenced by KURLBar(), setOrientation(), and sizeHint().

void KURLBar::setCurrentItem | ( | const KURL & | url | ) | `[virtual, slot]`

Makes the item with the url `url` the current item.

Does nothing if no item with that url is available.

See also:
  currentItem

  currentURL

Definition at line 428 of file kurlbar.cpp.

References QListBox::clearSelection(), QListBox::firstItem(), m_activeItem, QListBoxItem::next(), QListBox::setCurrentItem(), QListBox::setSelected(), KURLBarItem::url(), and KURL::url().

Referenced by slotContextMenuRequested().

void KURLBar::activated | ( | const KURL & | url | ) | `[signal]`

| This signal is emitted when the user activated an item, e.g by clicking on it. Referenced by slotSelected().

bool KURLBar::addNewItem | ( |  | ) | `[protected, virtual]`

Pops up a KURLBarItemDialog to let the user add a new item.

Uses editItem() to do the job.

Returns:
  false if the user aborted the dialog and no item is added.

Definition at line 669 of file kurlbar.cpp.

References editItem(), and QListBox::insertItem().

Referenced by slotContextMenuRequested().

bool KURLBar::editItem | ( | KURLBarItem * | item | ) | `[protected, virtual]`

Pops up a KURLBarItemDialog to let the user edit the properties of `item`.

Invoked e.g. by addNewItem(), when the user drops a url onto the bar or from the contextmenu.

Returns:
  false if the user aborted the dialog and `item` is not changed.

Definition at line 682 of file kurlbar.cpp.

References KURLBarItem::applicationLocal(), KURLBarItem::description(), KStdAccel::description(), KURLBarItemDialog::getInformation(), KURLBarItem::icon(), m_isModified, m_useGlobal, KURLBarItem::setApplicationLocal(), KURLBarItem::setDescription(), KURLBarItem::setIcon(), KURLBarItem::setURL(), QListBox::triggerUpdate(), and KURLBarItem::url().

Referenced by addNewItem(), and slotContextMenuRequested().

void KURLBar::resizeEvent | ( | QResizeEvent * |  | ) | `[protected, virtual]`

| Reimplemented from QFrame. Definition at line 353 of file kurlbar.cpp. References QFrame::resizeEvent().

void KURLBar::slotContextMenuRequested | ( | QListBoxItem * | ,
|  | const QPoint & | pos
| ) | `[protected, virtual, slot]`

Reimplemented to show a contextmenu, allowing the user to add, edit or remove items, or change the iconsize.

Definition at line 618 of file kurlbar.cpp.

References addNewItem(), editItem(), QPopupMenu::exec(), QPopupMenu::insertItem(), QPopupMenu::insertSeparator(), m_activeItem, m_isImmutable, m_isModified, setCurrentItem(), setIconSize(), QPopupMenu::setItemEnabled(), KIcon::SizeMedium, KIcon::SizeSmall, QListBox::triggerUpdate(), and KURLBarItem::url().

Referenced by setListBox().

void KURLBar::slotSelected | ( | QListBoxItem * |  | ) | `[protected, virtual, slot]`

| Called when an item has been selected. Emits the activated() signal. Definition at line 417 of file kurlbar.cpp. References activated(), m_activeItem, QListBox::setCurrentItem(), and KURLBarItem::url(). Referenced by setListBox().

void KURLBar::slotDropped | ( | QDropEvent * |  | ) | `[protected, virtual, slot]`

| Called when a url was dropped onto the bar to show a KURLBarItemDialog. Definition at line 594 of file kurlbar.cpp. References QValueList< KURL >::begin(), KURLDrag::decode(), KStdAccel::description(), QValueList< KURL >::end(), KURLBarItemDialog::getInformation(), insertItem(), QValueList< KURL >::Iterator(), m_isModified, and m_useGlobal. Referenced by setListBox().

## Member Data Documentation

KURLBarItem* KURLBar::m_activeItem `[protected]`

| The currently active item. Definition at line 379 of file kurlbar.h. Referenced by KURLBar(), setCurrentItem(), slotContextMenuRequested(), and slotSelected().

bool KURLBar::m_useGlobal `[protected]`

| Whether we support global entries or just local ones. Definition at line 383 of file kurlbar.h. Referenced by editItem(), KURLBar(), readConfig(), slotDropped(), and writeConfig().

bool KURLBar::m_isModified `[protected]`

| Whether the urlbar was modified by the user (e.g. by editing/adding/removing an item). Definition at line 389 of file kurlbar.h. Referenced by editItem(), isModified(), KURLBar(), slotContextMenuRequested(), slotDropped(), and writeConfig().

bool KURLBar::m_isImmutable `[protected]`

| Whether the urlbar may be modified by the user. If immutable is true, the urlbar can not be modified. Definition at line 395 of file kurlbar.h. Referenced by isImmutable(), KURLBar(), readConfig(), and slotContextMenuRequested().

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

- kurlbar.h
- kurlbar.cpp

This file is part of the documentation for kdelibs Version 3.1.5.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Jan 28 13:23:40 2004 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001