XSETTINGS Registry - extending the shared settings keys

Marius Bugge Monsen (mbm at trolltech.com)

Version 0.1

Introduction

XSETTINGS

XSETTINGS Registry

Toolkit Settings

Gtk+ Settings Keys

Qt Settings Keys

Overlapping Settings Keys

Additional Settings Keys

Colors

Gtk+ Style Colors

Qt Color Roles

Overlapping Color Roles

Additional Color Roles

States

Gtk+ States

Qt Palette States

Overlapping States

Additional States

Proposed New XSETTINGS Registry Keys

Proposed Color Registry Keys

Additional Proposed Registry Keys

Conclusion

References

Introduction

End users expect modern Linux desktop applications to conform with the look and feel of their desktop environment. To achieve this integration with the different Linux desktop environments, the application needs to respect the desktop settings.

Since the the Linux desktop is a heterogeneous environment consisting of several toolkits and desktops, a desktop- and toolkit-independent mechanism for reading these settings and a set of common settings keys needs to be agreed upon.

This paper will look at the settings keys used by two of the most popular toolkits for Linux desktop applications, Gtk+ and Qt, to find a common set of settings keys. Emphasis has been placed on trying to find a common set of keys for colors used to draw the application user interface.

The resulting set of desktop environment independent, cross-toolkit settings keys is proposed as additions to the existing shared XSETTINGS registry keys.

XSETTINGS

XSETTINGS is a mechanism, proposed by Owen Taylor (Red Hat Inc), for configuring desktop settings and propagating them to applications running on the desktop. The intention is that this mechanism should be independent of the toolkit used by the applications on the desktop. XSETTINGS is used by the Gtk+ toolkit and the GNOME desktop environment.

XSETTINGS Registry

XSETTINGS registry key names have the following restrictions:

Only the ASCII characters 'A'-'Z' 'a'-'z' '0'-'9' '_' and '/' can be used.
'/' cannot appear in the leading or trailing position of the name.
Occurrences of '/' may not be consecutive.
The first character of the name cannot be in the range '0'-'9'.
The first character after '/' cannot be in the range '0'-'9'.

Names beginning with 'Net/' (and case variants) are restricted and is used for cross toolkit. Here follows a list of the keys beginning with 'Net/' currently controlled by the XSETTINGS system.

Net/ThemeName	string
Net/IconThemeName	string
Net/DoubleClickTime	int
Net/DoubleClickDistance	int
Net/DndDragThreshold	int
Net/CursorBlinkTime	int
Net/CursorBlink	bool

There are settings that can be shared by Xft clients.

Xft/Antialias	int
Xft/Hinting	int
Xft/HintStyle	string
Xft/RGBA	string
Xft/DPI	int

There are also settings keys specific to the Gtk+ toolkit based desktops.

Gtk/ToobarStyle	enum
Gtk/KeyThemeName	string
Gtk/IMStatusStyle	enum
Gtk/IMPreeditStyle	enum
Gtk/FontName	string
Gtk/CanChangeAccels	bool
Gtk/ColorPalette	string
Gtk/IconSizes	string
Gtk/ToolbarIconSize	enum
Gtk/MenuImages	bool
Gtk/ButtonImages	bool
Gtk/MenuBarAccel	string

Toolkit Settings

Toolkit registry settings are commonly stored as key-value pairs. The keys are often toolkit-specific; but since desktop application toolkits often have to solve similar problems and deal with the same subsystems, many of these settings keys control the same aspects of the application's look and feel. When comparing the keys from the two toolkits, the type of the key is presented in the format used by the XSETTINGS documentation whenever possible. This is done to make it easier to find compatible keys.

Gtk+ Settings Keys

In Gtk+ 2.10.11, the GtkSettings object has the following properties:

"color-hash"	GHashTable
"gtk-alternative-button-order"	bool
"gtk-button-images"	bool
"gtk-can-change-accels"	bool
"gtk-color-palette"	string
"gtk-color-scheme"	string
"gtk-cursor-blink"	bool
"gtk-cursor-blink-time"	int
"gtk-cursor-theme-name"	string
"gtk-cursor-theme-size"	int
"gtk-dnd-drag-threshold"	int
"gtk-double-click-distance"	int
"gtk-double-click-time"	int
"gtk-enable-animations"	bool
"gtk-entry-password-hint-timeout"	int
"gtk-entry-select-on-focus"	bool
"gtk-fallback-icon-theme"	string
"gtk-font-name"	string
"gtk-icon-sizes"	string
"gtk-icon-theme-name"	string
"gtk-key-theme-name"	string
"gtk-label-select-on-focus"	bool
"gtk-menu-bar-accel"	string
"gtk-menu-bar-popup-delay"	int
"gtk-menu-images"	bool
"gtk-menu-popdown-delay"	int
"gtk-menu-popup-delay"	int
"gtk-modules"	string
"gtk-scrolled-window-placement"	GtkCornerType
"gtk-show-input-method-menu"	bool
"gtk-show-unicode-menu"	bool
"gtk-split-cursor"	bool
"gtk-theme-name"	string
"gtk-timeout-expand"	int
"gtk-timeout-initial"	int
"gtk-timeout-repeat"	int
"gtk-toolbar-icon-size"	GtkIconSize
"gtk-toolbar-style"	GtkToolbarStyle
"gtk-touchscreen-mode"	bool
"gtk-xft-antialias"	int
"gtk-xft-dpi"	int
"gtk-xft-hinting"	int
"gtk-xft-hintstyle"	string
"gtk-xft-rgba"	string

Qt Settings Keys

The Qt 4.2.3 settings file contains the following entries (ignoring font substitutions):

font	string
Palette/Active	string
Palette/Inactive	string
Palette/Disabled	string
fontPath	string
embeddedFonts	bool
style	string
doubleClickInterval	int
cursorFlashTime	int
wheelScrollLines	int
resolveSymlinks	bool
globalStrut/width	int
globalStrut/height	int
useRtlExtensions	bool
XIMInputStyle	string
GUIEffects	string

Overlapping Settings Keys

From the two lists of keys from the two toolkits and the existing XSETTINGS registry, the following overlapping settings keys are found:

Gtk+	Qt	XSETTINGS	type
"color-hash"	Palette
"gtk-font-name"	font	Gtk/FontName	string
"gtk-theme-name"	style	Net/ThemeName	string
"gtk-double-click-time"	doubleClickInterval	Net/DoubleClickTime	int
"gtk-cursor-blink-time"	cursorFlashTime	Net/CursorBlinkTime	int

As the font name is a common settings value in both toolkits, it makes sense to promote the Gtk/FontName key to Net/FontName.

Additional Settings Keys

Some additional keys are defined to allow the application to adopt the current desktop look and feel.

Gtk+	Qt	XSETTINGS	type
“gtk-enable-animations”		Net/EnableAnimations	bool
“gtk-toolbar-icon-size”		Net/ToolbarIconSize	int

Colors

Modern toolkits operate with sets of colors to draw the graphical user interface. Each color in such a set is used when drawing specific elements of the user interface. This will be referred to as a color role.

Both Gtk+ and Qt have palette entries in their respective toolkit settings, and both settings use a string to define the palette. However, to ensure that the palette is defined in a cross-toolkit format, this paper proposes to define each color role as a separate settings key.

Gtk+ Style Colors

Gtk+ 2.10.11 manages the color sets in the GtkStyle structure. This structure has the following GtkColor members:

GdkColor fg[StateType]

GdkColor bg[StateType]

GdkColor light[StateType]

GdkColor dark[StateType]

GdkColor mid[StateType]

GdkColor text[StateType]

GdkColor base[StateType]

GdkColor text_aa[StateType]

GdkColor black

GdkColor white

Qt Color Roles

Qt 4.2.3 refers to the sets of colors as color groups. Each QColor in a QColorGroup fills a specific role, defined by the QPalette::ColorRole enum.

QPalette::Window

QPalette::Background (obsolete)

QPalette::WindowText

QPalette::Foreground (obsolete)

QPalette::Base

QPalette::AlternateBase

QPalette::Text

QPalette::Button

QPalette::ButtonText

QPalette::BrightText

QPalette::Light

QPalette::Midlight

QPalette::Dark

QPalette::Mid

QPalette::Shadow

QPalette::Highlight

QPalette::HighlightedText

QPalette::Link

QPalette::LinkVisited

Overlapping Color Roles

Comparing the color roles found in the two toolkits, we find the following common roles:

Gtk+	Qt
GtkStyle.fg	QPalette::WindowText	Foreground	widget foreground color
GtkStyle.bg	QPalette::Window	Background	widget background color
GtkStyle.light	QPalette::Light	Light	color used for the lighted edges of 3D bevel effects
GtkStyle.dark	QPalette::Dark	Dark	color used for the darkened edges of 3D bevel effects
GtkStyle.mid	QPalette::Mid	Mid	color between light and dark
GtkStyle.text	QPalette::Text	Text	foreground color used for text in text entry widgets, lists, tables and trees
GtkStyle.base	QPalette::Base	Base	background color for text entry widgets, lists, tables and trees

Modern toolkit themes are often pixmap based, and may ignore many of the color role settings.

Color roles like Light, Mid and Dark are still useful for defining high contrast color schemes.

Additional Color Roles

To allow common user interface elements like text entry widgets and list items to use the desktop defined colors, color roles for drawing selected text and items should also be defined.

Gtk+	Qt
	QPalette::Highlight	SelectedBase	background color for selected items
	QPalette::HighlightedText	SelectedText	foreground color for selected items

States

A desktop application can have widgets in different states (active, disabled, etc.). The toolkit has to be able to draw all user interface elements for each defined state. Toolkits therefore keep a set of colors for each state.

The actual color value assigned to each role, in each state, are typically decided by the theme used by the application.

Gtk+ States

In Gtk+ 2.10.11, GtkStateType defines the following states, also used for palettes:

Gtk::STATE_NORMAL	the widget accepts user actions
Gtk::STATE_ACTIVE	the widget is the currently active widget
Gtk::STATE_PRELIGHT	mouse pointer is hovering over a widget that is responsive to user action
Gtk::STATE_SELECTED	a selected item in a list
Gtk::STATE_INSENSITIVE	the widget is unresponsive to user actions

Qt Palette States

In Qt 4.2.3, colors for different states in a QPalette are organized in color groups, represented by the QColorGroup class. A palette in Qt contains color groups for the following states:

QPalette::Disabled	the widget is unresponsive to user action
QPalette::Active	the widget is active; widget has keyboard focus
QPalette::Inactive	the widget does not have keyboard focus
QPalette::Normal	same as Active

Overlapping States

Based on the two lists of palette states, the following common states were found:

Gtk+	Qt
Gtk::STATE_ACTIVE	QPalette::Active	Active
Gtk::STATE_NORMAL	QPalette::Inactive	Normal
Gtk::STATE_INSENSITIVE	QPalette::Disabled	Disabled

Additional States

Many themes paint widgets slightly differently when the mouse cursor is hovering over them. To accommodate for this, a Hover state is also defined.

Gtk+	Qt
Gtk::STATE_PRELIGHT		Hover

There is no Selected state defined. Defining the SelectedBase and SelectedText color roles instead of a Selected state allows widgets in any state to show selected items.

Proposed New XSETTINGS Keys

The intention of this paper is to find a common set of cross-toolkit settings keys, with emphasis on finding a set of keys for colors used to draw the application user interface. The proposed keys are therefor divided into two groups: proposed color registry keys and additional proposed registry keys.

Proposed Color Registry Keys

After comparing the color roles found in Gtk+ and Qt, the following set of color roles are used to construct the proposed XSETTINGS color registry keys:

Foreground	color used to draw the foreground in a widget
Background	color used to draw the background in a widget
Base	color used to draw the base of a widget
Light	color used to draw the lighted elements
Dark	color used to draw the darkened elements
Mid	color between light and dark
Text	color used to draw the text in a widget
SelectedBase	color used to draw the background of selected text or items
SelectedText	color used to draw the selected text or items

The toolkits also operate with different states that have different color values for the color roles.

These states are also used as part of the color registry keys:

Normal	the widget does not have keyboard focus
Active	the widget has keyboard focus
Disabled	the widget is unresponsive to user action
Hover	the mouse cursor is hovering over a widget that will respond to user action

By combining the color roles and states under the Net/Color/ namespace, the following list of keys are proposed as common, toolkit-independent role color settings keys in the XSETTINGS registry.

key	type	default value	documentation
Net/Color/Normal/Foreground	int	-1	Color used to draw the foreground in a widget without keyboard focus.
Net/Color/Normal/Background	int	-1	Color used to draw the background in a widget without keyboard focus.
Net/Color/Normal/Base	int	-1	Color used to draw the base of a widget without keyboard focus.
Net/Color/Normal/Text	int	-1	Color used to draw the text in a widget without keyboard focus.
Net/Color/Normal/Light	int	-1	Color used to draw the light elements of a widget without keyboard focus.
Net/Color/Normal/Mid	int	-1	Color between light and dark of a widget without keyboard focus.
Net/Color/Normal/Dark	int	-1	Color used to draw the dark elements of a widget without keyboard focus.
Net/Color/Normal/SelectedBase	int	-1	Color used to draw the background of a selected item or text entry in a widget without keyboard focus.
Net/Color/Normal/SelectedText	int	-1	Color used to draw the foreground of a selected item or text entry in a widget without keyboard focus.

key	type	default value	documentation
Net/Color/Active/Foreground	int	-1	Color used to draw the foreground in a widget with keyboard focus.
Net/Color/Active/Background	int	-1	Color used to draw the background in a widget with keyboard focus.
Net/Color/Active/Base	int	-1	Color used to draw the base of a widget with keyboard focus.
Net/Color/Active/Text	int	-1	Color used to draw the text in a widget with keyboard focus.
Net/Color/Active/Light	int	-1	Color used to draw the light elements of a widget with keyboard focus.
Net/Color/Active/Mid	int	-1	Color between light and dark of a widget with keyboard focus.
Net/Color/Active/Dark	int	-1	Color used to draw the dark elements of a widget with keyboard focus.
Net/Color/Active/SelectedBase	int	-1	Color used to draw the background of a selected item or text entry in a widget with keyboard focus.
Net/Color/Active/SelectedText	int	-1	Color used to draw the foreground of a selected item or text entry in a widget with keyboard focus.

key	type	default value	documentation
Net/Color/Disabled/Foreground	int	-1	Color used to draw the foreground in a disabled widget.
Net/Color/Disabled/Background	int	-1	Color used to draw the background in a disabled widget.
Net/Color/Disabled/Base	int	-1	Color used to draw the base of a disabled widget.
Net/Color/Disabled/Text	int	-1	Color used to draw the text in a disabled widget.
Net/Color/Disabled/Light	int	-1	Color used to draw the light elements of a disabled widget.
Net/Color/Disabled/Mid	int	-1	Color between light and dark of a disabled widget.
Net/Color/Disabled/Dark	int	-1	Color used to draw the dark elements of a disabled widget.
Net/Color/Disabled/SelectedBase	int	-1	Color used to draw the background of a selected item or text entry in a disabled widget.
Net/Color/Disabled/SelectedText	int	-1	Color used to draw the foreground of a selected item or text entry in a disabled widget.

key	type	default value	documentation
Net/Color/Hover/Foreground	int	-1	Color used to draw the foreground in the widget under the mouse cursor.
Net/Color/Hover/Background	int	-1	Color used to draw the background in the widget under the mouse cursor.
Net/Color/Hover/Base	int	-1	Color used to draw the base of the widget under the mouse cursor.
Net/Color/Hover/Text	int	-1	Color used to draw the text in the widget under the mouse cursor.
Net/Color/Hover/Light	int	-1	Color used to draw the light elements of the widget under the mouse cursor.
Net/Color/Hover/Mid	int	-1	Color between light and dark of the widget under the mouse cursor.
Net/Color/Hover/Dark	int	-1	Color used to draw the dark elements of the widget under the mouse cursor.
Net/Color/Hover/SelectedBase	int	-1	Color used to draw the background of a selected item or text entry in the widget under the mouse cursor.
Net/Color/Hover/SelectedText	int	-1	Color used to draw the foreground of a selected item or text entry in the widget under the mouse cursor.

Additional Proposed Settings Keys

In addition to the proposed registry keys, the following XSETTINGS registry keys are also proposed:

key	type	default value	documentation
Net/FontName	string	"Sans 10"	Name of default font to use.
Net/EnableAnimations	bool	false	Whether animation effects are enabled.
Net/ToolbarIconSize	int	-1	The size of the icons in the toolbar.

Conclusion

This paper proposes a set of cross-toolkit desktop settings keys to ensure that applications will integrate better with the desktop they are running on. The proposed new keys are based on the existing XSETTINGS registry keys and common settings keys found in two of the most popular toolkits on the Linux desktop.

The next course of action, if the proposed registry keys are accepted, will be to implement support for the proposed settings keys in the toolkits and in the XSETTINGS manager.

Feedback on this proposal is encouraged.