KDE 4.7 PyKDE API Reference

- KDE's Python API

# KBookmarkManager Class Reference

`from PyKDE4.kio import *`

Inherits: QObject

## Detailed Description

This class implements the reading/writing of bookmarks in XML. The bookmarks file is read and written using the XBEL standard (http://pyxml.sourceforge.net/topics/xbel/)

A sample file looks like this :

     <xbel>
       <bookmark href="http://techbase.kde.org"><title>Developer Web Site</title></bookmark>
       <folder folded="no">
         <title>Title of this folder</title>
         <bookmark icon="kde" href="http://www.kde.org"><title>KDE Web Site</title></bookmark>
         <folder toolbar="yes">
           <title>My own bookmarks</title>
           <bookmark href="http://www.koffice.org"><title>KOffice Web Site</title></bookmark>
           <separator/>
           <bookmark href="http://www.kdevelop.org"><title>KDevelop Web Site</title></bookmark>
         </folder>
       </folder>
     </xbel>

## Signals

| bookmarkCompleteChange (QString caller)
| bookmarkConfigChanged ()
| bookmarksChanged (QString groupAddress)
| changed (QString groupAddress, QString caller)
| configChanged ()
| error (QString errorMessage)

## Methods

| __init__ (self, QString bookmarksFile, QString dbusObjectName)
| __init__ (self, QString bookmarksFile)
| __init__ (self)
bool | autoErrorHandlingEnabled (self)
| emitChanged (self)
| emitChanged (self, KBookmarkGroup group)
| emitConfigChanged (self)
KBookmark | findByAddress (self, QString address)
QDomDocument | internalDocument (self)
| notifyCompleteChange (self, QString caller)
| notifyConfigChanged (self)
QString | path (self)
KBookmarkGroup | root (self)
bool | save (self, bool toolbarCache=1)
bool | saveAs (self, QString filename, bool toolbarCache=1)
| setAutoErrorHandlingEnabled (self, bool enable, QWidget parent)
| setEditorOptions (self, QString caption, bool browser)
| setUpdate (self, bool update)
| slotEditBookmarks (self)
| slotEditBookmarksAtAddress (self, QString address)
KBookmarkGroup | toolbar (self)
bool | updateAccessMetadata (self, QString url)
| updateFavicon (self, QString url, QString faviconurl)

## Static Methods

KBookmarkManager | createTempManager ()
KBookmarkManager | managerForExternalFile (QString bookmarksFile)
KBookmarkManager | managerForFile (QString bookmarksFile, QString dbusObjectName)
KBookmarkManager | userBookmarksManager ()

## Signal Documentation

bookmarkCompleteChange | ( | QString | caller
| ) |  |  |

Signal send over DBUS

Signal syntax:
  `QObject.connect(source, SIGNAL("bookmarkCompleteChange(QString)"), target_slot)`

bookmarkConfigChanged | ( |  | ) |

Signal send over DBUS

Signal syntax:
  `QObject.connect(source, SIGNAL("bookmarkConfigChanged()"), target_slot)`

bookmarksChanged | ( | QString | groupAddress
| ) |  |  |

Signal send over DBUS

Signal syntax:
  `QObject.connect(source, SIGNAL("bookmarksChanged(QString)"), target_slot)`

changed | ( | QString | groupAddress,
|  | QString | caller
| ) |  |  |

Signals that the group (or any of its children) with the address groupAddress (e.g. "/4/5") has been modified by the caller caller. connect to this

Signal syntax:
  `QObject.connect(source, SIGNAL("changed(const QString&, const QString&)"), target_slot)`

configChanged | ( |  | ) |

Signals that the config changed

Signal syntax:
  `QObject.connect(source, SIGNAL("configChanged()"), target_slot)`

error | ( | QString | errorMessage
| ) |  |  |

Emitted when an error occurs. Contains the translated error message.

Since:
  4.6

Signal syntax:
  `QObject.connect(source, SIGNAL("error(const QString&)"), target_slot)`

## Method Documentation

__init__ | ( | self, |
|  | QString | bookmarksFile,
|  | QString | dbusObjectName
| ) |  |  |

Creates a bookmark manager with a path to the bookmarks. By default, it will use the KDE standard dirs to find and create the correct location. If you are using your own app-specific bookmarks directory, you must instantiate this class with your own path <em>before</em> KBookmarkManager.managerForFile() is ever called.

Parameters:

  | bookmarksFile | full path to the bookmarks file, Use ~/.kde/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
  | dbusObjectName | a unique name that represents this bookmark collection, usually your kinstance (e.g. kapplication) name. This is "konqueror" for the konqueror bookmarks, "kfile" for KFileDialog bookmarks, etc. The final DBus object path is /KBookmarkManager/dbusObjectName An empty dbusObjectName disables the registration to dbus (used for temporary managers)

__init__ | ( | self, |
|  | QString | bookmarksFile
| ) |  |  |

Creates a bookmark manager for an external file (Using KDirWatch for change monitoring)

Since:
  4.1

__init__ | ( |  | self ) |

Creates a temp bookmark manager

bool autoErrorHandlingEnabled | ( |  | self ) |

Check whether auto error handling is enabled. If enabled, it will show an error dialog to the user when an error occurs. It is turned on by default.

Returns:
  true if auto error handling is enabled, false otherwise

Note:
  dialogs will only be displayed if the current thread is the gui thread

Since:
  4.6

See also:
  setAutoErrorHandlingEnabled()

emitChanged | ( |  | self ) |

Saves the bookmark file and notifies everyone.

Parameters:

  | group | the parent of all changed bookmarks

emitChanged | ( | self, |
|  | KBookmarkGroup | group
| ) |  |  |

Saves the bookmark file and notifies everyone.

Parameters:

  | group | the parent of all changed bookmarks

emitConfigChanged | ( |  | self ) |

KBookmark findByAddress | ( | self, |
|  | QString | address
| ) |  |  |

Returns:
  the bookmark designated by address

Parameters:

  | address | the address belonging to the bookmark you're looking for
  | tolerate | when true tries to find the most tolerable bookmark position

See also:
  KBookmark.address

QDomDocument internalDocument | ( |  | self ) |

Internal:

notifyCompleteChange | ( | self, |
|  | QString | caller
| ) |  |  |

Reparse the whole bookmarks file and notify about the change Doesn't send signal over DBUS to the other Bookmark Managers You probably want to use emitChanged()

notifyConfigChanged | ( |  | self ) |

QString path | ( |  | self ) |

This will return the path that this manager is using to read the bookmarks.

Internal:

Returns:
  the path containing the bookmarks

KBookmarkGroup root | ( |  | self ) |

This will return the root bookmark. It is used to iterate through the bookmarks manually. It is mostly used internally.

Returns:
  the root (top-level) bookmark

bool save | ( | self, |
|  | bool | toolbarCache=1
| ) |  |  |

Save the bookmarks to an XML file on disk. You should use emitChanged() instead of this function, it saves and notifies everyone that the file has changed. Only use this if you don't want the emitChanged signal.

Parameters:

  | toolbarCache | iff true save a cache of the toolbar folder, too

Returns:
  true if saving was successful

bool saveAs | ( | self, |
|  | QString | filename,
|  | bool | toolbarCache=1
| ) |  |  |

Save the bookmarks to the given XML file on disk.

Parameters:

  | filename | full path to the desired bookmarks file location
  | toolbarCache | iff true save a cache of the toolbar folder, too

Returns:
  true if saving was successful

setAutoErrorHandlingEnabled | ( | self, |
|  | bool | enable,
|  | QWidget | parent
| ) |  |  |

Enable or disable auto error handling is enabled. If enabled, it will show an error dialog to the user when an error occurs. It is turned on by default. If disabled, the application should react on the error() signal.

Parameters:

  | enable | true to enable auto error handling, false to disable
  | parent | the parent widget for the error dialogs, can be 0 for top-level

Since:
  4.6

See also:
  autoErrorHandlingEnabled()

setEditorOptions | ( | self, |
|  | QString | caption,
|  | bool | browser
| ) |  |  |

Set options with which slotEditBookmarks called keditbookmarks this can be used to change the appearance of the keditbookmarks in order to provide a slightly differing outer shell depending on the bookmarks file / app which calls it.

Parameters:

  | caption | the --caption string, for instance "Konsole"
  | browser | iff false display no browser specific menu items in keditbookmarks . --nobrowser

setUpdate | ( | self, |
|  | bool | update
| ) |  |  |

Set the update flag. Defaults to true.

Parameters:

  | update | if true then KBookmarkManager will listen to DBUS update requests.

slotEditBookmarks | ( |  | self ) |

slotEditBookmarksAtAddress | ( | self, |
|  | QString | address
| ) |  |  |

KBookmarkGroup toolbar | ( |  | self ) |

This returns the root of the toolbar menu. In the XML, this is the group with the attribute toolbar=yes

Returns:
  the toolbar group

bool updateAccessMetadata | ( | self, |
|  | QString | url
| ) |  |  |

Update access time stamps for a given url.

Parameters:

  | url | the viewed url

Returns:
  true if any metadata was modified (bookmarks file is not saved automatically)

updateFavicon | ( | self, |
|  | QString | url,
|  | QString | faviconurl
| ) |  |  |

## Static Method Documentation

KBookmarkManager createTempManager | ( |  | ) |

only used for KBookmarkBar

KBookmarkManager managerForExternalFile | ( | QString | bookmarksFile
| ) |  |  |

Returns a KBookmarkManager, which will use KDirWatch for change detection This is important when sharing bookmarks with other Desktops.

Parameters:

  | bookmarksFile | full path to the bookmarks file

Since:
  4.1

KBookmarkManager managerForFile | ( | QString | bookmarksFile,
|  | QString | dbusObjectName
| ) |  |  |

You need to pass a dbusObjectName as the second parameter In kde 3 managerForFile had the parameters (const QString &, bool) We want old calls which pass a bool as a second parameter to fail. Unfortunately C++ can convert a bool to a QString, via QString(char(bool)) This private overloaded method prevents this, as it is a better match, and thus old calls fail at compile time.

KBookmarkManager userBookmarksManager | ( |  | ) |

Returns a pointer to the user's main (konqueror) bookmark collection.