KDE 4.9 PyKDE API Reference

- KDE's Python API

# KGlobalSettings Class Reference

`from PyKDE4.kdeui import *`

Inherits: QObject

## Detailed Description

Access the KDE global configuration.

Author:
  David Faure <faure@kde.org>

## Enumerations

ActivateOption | { ApplySettings, ListenForChanges }
ChangeType | { PaletteChanged, FontChanged, StyleChanged, SettingsChanged, IconChanged, CursorChanged, ToolbarStyleChanged, ClipboardConfigChanged, BlockShortcuts, NaturalSortingChanged }
Completion | { CompletionNone, CompletionAuto, CompletionMan, CompletionShell, CompletionPopup, CompletionPopupAuto }
GraphicEffect | { NoEffects, GradientEffects, SimpleAnimationEffects, ComplexAnimationEffects }
SettingsCategory | { SETTINGS_MOUSE, SETTINGS_COMPLETION, SETTINGS_PATHS, SETTINGS_POPUPMENU, SETTINGS_QT, SETTINGS_SHORTCUTS, SETTINGS_LOCALE, SETTINGS_STYLE }
TearOffHandle | { Disable, ApplicationLevel, Enable }

## Signals

| appearanceChanged ()
| blockShortcuts (int data)
| cursorChanged ()
| iconChanged (int group)
| kdisplayFontChanged ()
| kdisplayPaletteChanged ()
| kdisplayStyleChanged ()
| naturalSortingChanged ()
| settingsChanged (int category)
| toolbarAppearanceChanged (int a0)

## Methods

| __init__ (self)
| activate (self)
| activate (self, KGlobalSettings.ActivateOptions options)

## Static Methods

QColor | activeTextColor ()
QColor | activeTitleColor ()
bool | allowDefaultBackgroundImages ()
int | autoSelectDelay ()
QString | autostartPath ()
int | buttonLayout ()
bool | changeCursorOverIcon ()
KGlobalSettings.Completion | completionMode ()
int | contextMenuKey ()
int | contrast ()
float | contrastF (KSharedPtr<KSharedConfig> config=KSharedConfigPtr())
QPalette | createApplicationPalette (KSharedPtr<KSharedConfig> config=KSharedConfigPtr())
QPalette | createNewApplicationPalette (KSharedPtr<KSharedConfig> config=KSharedConfigPtr())
QRect | desktopGeometry (QPoint point)
QRect | desktopGeometry (QWidget w)
QString | desktopPath ()
int | dndEventDelay ()
QString | documentPath ()
QString | downloadPath ()
| emitChange (KGlobalSettings.ChangeType changeType, int arg=0)
QFont | fixedFont ()
QFont | generalFont ()
KGlobalSettings.GraphicEffects | graphicEffectsLevel ()
KGlobalSettings.GraphicEffects | graphicEffectsLevelDefault ()
QColor | inactiveTextColor ()
QColor | inactiveTitleColor ()
KGlobalSettings.TearOffHandle | insertTearOffHandle ()
bool | isMultiHead ()
QFont | largeFont (QString text=QString())
QFont | menuFont ()
KGlobalSettings.KMouseSettings | mouseSettings ()
QString | musicPath ()
bool | naturalSorting ()
bool | opaqueResize ()
QString | picturesPath ()
KGlobalSettings | self ()
bool | shadeSortColumn ()
bool | showContextMenusOnPress ()
bool | showFilePreview (KUrl a0)
bool | showIconsOnPushButtons ()
bool | singleClick ()
QFont | smallestReadableFont ()
bool | smoothScroll ()
QRect | splashScreenDesktopGeometry ()
QFont | taskbarFont ()
QFont | toolBarFont ()
QString | videosPath ()
bool | wheelMouseZooms ()
QFont | windowTitleFont ()

## Signal Documentation

appearanceChanged | ( |  | ) |

Emitted when the application has changed either its GUI style, its font or its palette in response to a kdisplay request. Normally, widgets will update their styles automatically, but you should connect to this to program special behavior.

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

blockShortcuts | ( | int | data
| ) |  |  |

Emitted by BlockShortcuts

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

cursorChanged | ( |  | ) |

Emitted when the cursor theme has been changed.

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

iconChanged | ( | int | group
| ) |  |  |

Emitted when the global icon settings have been changed.

Parameters:

  | group | the new group

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

kdisplayFontChanged | ( |  | ) |

Emitted when the application has changed its font in response to a KControl request.

Normally widgets will update their fonts automatically, but you should connect to this to monitor global font changes, especially if you are using explicit fonts.

Note: If you derive from a QWidget-based class, a faster method is to reimplement QWidget.changeEvent() and catch QEvent.FontChange. This is the preferred way to get informed about font updates.

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

kdisplayPaletteChanged | ( |  | ) |

Emitted when the application has changed its palette due to a KControl request.

Normally, widgets will update their palette automatically, but you should connect to this to program special behavior.

Note: If you derive from a QWidget-based class, a faster method is to reimplement QWidget.changeEvent() and catch QEvent.PaletteChange. This is the preferred way to get informed about palette updates.

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

kdisplayStyleChanged | ( |  | ) |

Emitted when the application has changed its GUI style in response to a KControl request.

Normally, widgets will update their styles automatically (as they would respond to an explicit setGUIStyle() call), but you should connect to this to program special behavior.

Note: If you derive from a QWidget-based class, a faster method is to reimplement QWidget.changeEvent() and catch QEvent.StyleChange. This is the preferred way to get informed about style updates.

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

naturalSortingChanged | ( |  | ) |

Emitted when the natural sorting has been changed.

Since:
  4.4

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

settingsChanged | ( | int | category
| ) |  |  |

Emitted when the global settings have been changed. KGlobalSettings takes care of calling reparseConfiguration on KGlobal.config() so that applications/classes using this only have to re-read the configuration

Parameters:

  | category | the category among the SettingsCategory enum.

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

toolbarAppearanceChanged | ( | int | a0
| ) |  |  |

Emitted when the settings for toolbars have been changed. KToolBar will know what to do.

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

## Method Documentation

__init__ | ( |  | self ) |

activate | ( |  | self ) |

Since:
  4.6

activate | ( | self, |
|  | KGlobalSettings.ActivateOptions | options
| ) |  |  |

Since:
  4.6

## Static Method Documentation

QColor activeTextColor | ( |  | ) |

The default color to use for active texts.

Returns:
  the active text color

QColor activeTitleColor | ( |  | ) |

The default color to use for active titles.

Returns:
  the active title color

bool allowDefaultBackgroundImages | ( |  | ) |

Returns if default background images are allowed by the color scheme. A "default" background image is just that, i.e. the user has not actively selected a background image to use.

Returns:
  true if default background images may be used

int autoSelectDelay | ( |  | ) |

Returns the KDE setting for the auto-select option.

Returns:
  the auto-select delay or -1 if auto-select is disabled.

QString autostartPath | ( |  | ) |

The path to the autostart directory of the current user.

Returns:
  the path of the autostart directory

int buttonLayout | ( |  | ) |

The layout scheme to use for dialog buttons

Returns:
  Returns the number of the scheme to use.

bool changeCursorOverIcon | ( |  | ) |

Checks whether the cursor changes over icons.

Returns:
  the KDE setting for "change cursor over icon"

KGlobalSettings.Completion completionMode | ( |  | ) |

Returns the preferred completion mode setting.

Returns:
  Completion. Default is CompletionPopup.

int contextMenuKey | ( |  | ) |

Returns the KDE setting for the shortcut key to open context menus.

Returns:
  the key that pops up context menus.

Deprecated:
  Simply reimplement QWidget.contextMenuEvent() instead.

int contrast | ( |  | ) |

Returns the contrast for borders.

Returns:
  the contrast (between 0 for minimum and 10 for maximum contrast)

float contrastF | ( | KSharedPtr<KSharedConfig> | config=KSharedConfigPtr()
| ) |  |  |

Returns the contrast for borders as a floating point value.

Parameters:

  | config | pointer to the config from which to read the contrast setting (the default is to use KGlobal.config())

Returns:
  the contrast (between 0.0 for minimum and 1.0 for maximum contrast)

QPalette createApplicationPalette | ( | KSharedPtr<KSharedConfig> | config=KSharedConfigPtr()
| ) |  |  |

Used to obtain the QPalette that will be used to set the application palette.

This is only useful for configuration modules such as krdb and should not be used in normal circumstances.

Parameters:

  | config | KConfig from which to load the colors (passed as-is to .KColorScheme).

Returns:
  the QPalette

QPalette createNewApplicationPalette | ( | KSharedPtr<KSharedConfig> | config=KSharedConfigPtr()
| ) |  |  |

Used to obtain the QPalette that will be used to set the application palette.

This is only useful for configuration modules such as krdb and should not be used in normal circumstances.

Parameters:

  | config | KConfig from which to load the colors (passed as-is to .KColorScheme).

Note:
  The difference between this and the previous is that this never caches.

Since:
  4.6.3

Returns:
  the QPalette

QRect desktopGeometry | ( | QPoint | point
| ) |  |  |

This function returns the desktop geometry for an application that needs to set the geometry of a widget on the screen manually. It takes into account the user's display settings (number of screens, Xinerama, etc), and the user's preferences (if KDE should be Xinerama aware).

Parameters:

  | w | the widget in question. This is used to determine which screen to use in Xinerama or multi-head mode.

Returns:
  the geometry to use for the desktop. Note that it might not start at (0,0).

QRect desktopGeometry | ( | QWidget | w
| ) |  |  |

This function returns the desktop geometry for an application that needs to set the geometry of a widget on the screen manually. It takes into account the user's display settings (number of screens, Xinerama, etc), and the user's preferences (if KDE should be Xinerama aware).

Parameters:

  | w | the widget in question. This is used to determine which screen to use in Xinerama or multi-head mode.

Returns:
  the geometry to use for the desktop. Note that it might not start at (0,0).

QString desktopPath | ( |  | ) |

The path to the desktop directory of the current user.

Returns:
  the user's desktop directory

int dndEventDelay | ( |  | ) |

Returns a threshold in pixels for drag & drop operations. As long as the mouse movement has not exceeded this number of pixels in either X or Y direction no drag operation may be started. This prevents spurious drags when the user intended to click on something but moved the mouse a bit while doing so.

For this to work you must save the position of the mouse (oldPos) in the QWidget.mousePressEvent(). When the position of the mouse (newPos) in a QWidget.mouseMoveEvent() exceeds this threshold you may start a drag which should originate from oldPos.

Example code:

     void KColorCells.mousePressEvent( QMouseEvent *e )
     {
        mOldPos = e->pos();
     }

     void KColorCells.mouseMoveEvent( QMouseEvent *e )
     {
        if( !(e->state() && LeftButton)) return;

        int delay = KGlobalSettings.dndEventDelay();
        QPoint newPos = e->pos();
        if(newPos.x() > mOldPos.x()+delay || newPos.x() < mOldPos.x()-delay ||
           newPos.y() > mOldPos.y()+delay || newPos.y() < mOldPos.y()-delay)
        {
           // Drag color object
           int cell = posToCell(mOldPos); // Find color at mOldPos
           if ((cell != -1) && colors[cell].isValid())
           {
              KColorDrag *d = KColorDrag.makeDrag( colors[cell], this);
              d->dragCopy();
           }
        }
     }

Returns:
  the threshold for drag & drop in pixels

QString documentPath | ( |  | ) |

The path where documents are stored of the current user.

Returns:
  the path of the document directory

QString downloadPath | ( |  | ) |

The path where download are stored of the current user.

Returns:
  the path of the download directory

emitChange | ( | KGlobalSettings.ChangeType | changeType,
|  | int | arg=0
| ) |  |  |

Notifies all KDE applications on the current display of a change.

This is typically called by kcontrol modules after changing the corresponding config file. Do not call this from a normal KDE application.

QFont fixedFont | ( |  | ) |

Returns the default fixed font.

Returns:
  the default fixed font.

QFont generalFont | ( |  | ) |

Returns the default general font.

Returns:
  the default general font.

KGlobalSettings.GraphicEffects graphicEffectsLevel | ( |  | ) |

This function determines the desired level of effects on the GUI.

Since:
  4.1

KGlobalSettings.GraphicEffects graphicEffectsLevelDefault | ( |  | ) |

This function determines the default level of effects on the GUI depending on the system capabilities.

Since:
  4.1

QColor inactiveTextColor | ( |  | ) |

The default color to use for inactive texts.

Returns:
  the inactive text color

QColor inactiveTitleColor | ( |  | ) |

The default color to use for inactive titles.

Returns:
  the inactive title color

KGlobalSettings.TearOffHandle insertTearOffHandle | ( |  | ) |

Returns whether tear-off handles are inserted in KMenus.

Returns:
  whether tear-off handles are inserted in KMenus.

bool isMultiHead | ( |  | ) |

Returns if the user specified multihead. In case the display has multiple screens, the return value of this function specifies if the user wants KDE to run on all of them or just on the primary On Windows, settings are retrieved from the system.

Returns:
  true if the user chose multi head

QFont largeFont | ( | QString | text=QString()
| ) |  |  |

Returns a font of approx. 48 pt. capable of showing text.

Parameters:

  | text | the text to test

Returns:
  the font that is capable to show the text with 48 pt

QFont menuFont | ( |  | ) |

Returns the default menu font.

Returns:
  the default menu font.

KGlobalSettings.KMouseSettings mouseSettings | ( |  | ) |

This returns the current mouse settings. On Windows, settings are retrieved from the system.

Returns:
  the current mouse settings

QString musicPath | ( |  | ) |

The path where music are stored of the current user.

Returns:
  the path of the music directory

bool naturalSorting | ( |  | ) |

Returns true, if user visible strings should be sorted in a natural way: image 1.jpg image 2.jpg image 10.jpg image 11.jpg If false is returned, the strings are sorted by their unicode values: image 1.jpg image 10.jpg image 11.jpg image 2.jpg

Since:
  4.4

bool opaqueResize | ( |  | ) |

Whether the user wishes to use opaque resizing. Primarily intended for QSplitter.setOpaqueResize()

Returns:
  Returns true if user wants to use opaque resizing.

QString picturesPath | ( |  | ) |

The path where pictures are stored of the current user.

Returns:
  the path of the pictures directory

KGlobalSettings self | ( |  | ) |

Return the KGlobalSettings singleton. This is used to connect to its signals, to be notified of changes.

bool shadeSortColumn | ( |  | ) |

Returns if the sorted column in a K3ListView shall be drawn with a shaded background color.

Returns:
  true if the sorted column shall be shaded

bool showContextMenusOnPress | ( |  | ) |

Returns the KDE setting for context menus.

Returns:
  whether context menus should be shown on button press or button release (click).

bool showFilePreview | ( | KUrl | a0
| ) |  |  |

This function determines if the user wishes to see previews for the selected url

Returns:
  Returns true if user wants to show previews.

bool showIconsOnPushButtons | ( |  | ) |

This function determines if the user wishes to see icons on the push buttons.

Returns:
  Returns true if user wants to show icons.

bool singleClick | ( |  | ) |

Returns whether KDE runs in single (default) or double click mode. see http://developer.kde.org/documentation/standards/kde/style/mouse/index.html

Returns:
  true if single click mode, or false if double click mode.

QFont smallestReadableFont | ( |  | ) |

Returns the smallest readable font. This can be used in dockers, rulers and other places where space is at a premium.

bool smoothScroll | ( |  | ) |

Returns if item views should force smooth scrolling.

Returns:
  true if smooth scrolling is enabled for item view, false otherwise.

Since:
  4.2

QRect splashScreenDesktopGeometry | ( |  | ) |

This function returns the desktop geometry for an application's splash screen. It takes into account the user's display settings (number of screens, Xinerama, etc), and the user's preferences (if KDE should be Xinerama aware).

Returns:
  the geometry to use for the desktop. Note that it might not start at (0,0).

QFont taskbarFont | ( |  | ) |

Returns the default taskbar font.

Returns:
  the default taskbar font.

QFont toolBarFont | ( |  | ) |

Returns the default toolbar font.

Returns:
  the default toolbar font.

QString videosPath | ( |  | ) |

The path where videos are stored of the current user.

Returns:
  the path of the video directory

bool wheelMouseZooms | ( |  | ) |

Typically, QScrollView derived classes can be scrolled fast by holding down the Ctrl-button during wheel-scrolling. But QTextEdit and derived classes perform zooming instead of fast scrolling.

This value determines whether the user wants to zoom or scroll fast with Ctrl-wheelscroll.

Returns:
  true if the user wishes to zoom with the mouse wheel, false for scrolling

QFont windowTitleFont | ( |  | ) |

Returns the default window title font.

Returns:
  the default window title font.

## Enumeration Documentation

ActivateOption

Specifies options passed to activate().

Since:
  4.6

Enumerator:

  ApplySettings = 0x1 |
  ListenForChanges = 0x2 |

ChangeType

An identifier for change signals.

See also:
  emitChange

Enumerator:

  PaletteChanged = 0 |
  FontChanged |
  StyleChanged |
  SettingsChanged |
  IconChanged |
  CursorChanged |
  ToolbarStyleChanged |
  ClipboardConfigChanged |
  BlockShortcuts |
  NaturalSortingChanged |

Completion

This enum describes the completion mode used for by the KCompletion class. See the styleguide.

Enumerator:

  CompletionNone = 1 |
  CompletionAuto |
  CompletionMan |
  CompletionShell |
  CompletionPopup |
  CompletionPopupAuto |

GraphicEffect

Enumerator:

  NoEffects = 0x0000 |
  GradientEffects = 0x0001 |
  SimpleAnimationEffects = 0x0002 |
  ComplexAnimationEffects = 0x0006 |

SettingsCategory

Valid values for the settingsChanged signal

Enumerator:

  SETTINGS_MOUSE |
  SETTINGS_COMPLETION |
  SETTINGS_PATHS |
  SETTINGS_POPUPMENU |
  SETTINGS_QT |
  SETTINGS_SHORTCUTS |
  SETTINGS_LOCALE |
  SETTINGS_STYLE |

TearOffHandle

This enum describes the return type for insertTearOffHandle() whether to insert a handle or not. Applications who independently want to use handles in their popup menus should test for Application level before calling the appropriate function in KMenu.

Enumerator:

  Disable = 0 |
  ApplicationLevel |
  Enable |