GNUstep Configuration Guide

Mr. Dennis Leeuw

Pieter Bothstraat 32
3531 GZ
Utrecht
NL

Permission to use, copy, modify and distribute the GNUstep Configuration Guide and its accompanying documentation for any purpose and without fee is hereby granted in perpetuity, provided that the above copyright notice and this paragraph appear in all copies.

The copyright holders make no representation about the suitability of this Guide for any purpose. It is provided "as is" without expressed or implied warranty.


Table of Contents
Preface
Credits
1. Introduction
The defaults command
GNUstep Domains
GNUstep Daemons
2. Changing the backend
Setting the system default backend
Setting the backend per application
3. Localization
Local Time Zone
Language settings
Creating your local language support
Metrics used
4. Keyboard handling
Handling the control-key
Abort Key
Quote Key
Menu Keys
Keybindings
Keybinding file description
5. Default applications
Setting the Workspace application
Default PostScript previewer for printing
6. Displaying Files
Displaying directories
Hide dot-files
7. Icons
Freedesktop icons
Window Maker Dock
8. Styles
9. GNUstep color system
Application color names
Setting the colors per channel
10. Fonts
Anti-Aliased Fonts
Multi-byte and Unicode support
Font mask for X11
nfonts for libart
11. unknown
List of Tables
1. Credits
4-1. Keyboard Modifiers
9-1. Color names
9-2. GNUstep color keys
10-1. System Font Defaults
List of Examples
1-1. List all defaults features
1-2. List all available domains
2-1. GSBackend system
2-2. GSBackend application
3-1. Local Time Zone
3-2. NSLanguages
3-3. NSMeasurementUnit
4-1. GSInsertControlKeystrokes
4-2. GSAbortKey
4-3. GSQuoteKey
4-4. GSKeybindingsFiles
5-1. GSWorkspaceApplication
5-2. NSPreviewApp
6-1. GSBrowserCellFontify
6-2. GSFileBrowserHideDotFiles
9-1. Change color keys

Preface

Credits

Table 1. Credits

Adam FedorWriter of Defaults Summary
Nicola PeroWriter of Defaults Summary
Fred Kiefernsmapping.strings stuff
Adrian RobertExplained the way the new NSColorList works

Microsoft and Windows are trademarks of Microsoft, Inc., registered in the U.S. and other countries.

Apple, Mac and Mac OS are trademarks of Apple, Inc., registered in the U.S. and other countries.

Enterprise Objects, Enterprise Objects Framework, NeXT, NextStep, Objective-C and OpenStep are trademarks of NeXT Software, Inc., registered in the U.S. and other countries.


Chapter 1. Introduction

This guide is tries to document all the GNUstep configuration features.


The defaults command

The defaults command is used to set or change your settings. If you are on a multi-user system it is only possible to change the settings for your account, or with the -u <username> option the settings of a user for which you have write access to his or her database.

The defaults database is stored in a non-binary format in $GNUSTEP_USER_ROOT/Defaults/.GNUstepDefaults. It is thus not possible through the defaults command to set a default for all users on a system.

The generic syntax for defaults is:

defaults function domain key value

function. A function can be read, write or delete.

domain. The domain used with the defaults command is a section within the defaults database that you want to alter. This can be settings for a certain application or the NSGlobalDomain for a generic setting affecting all the applications.

key. The key is a certain setting you want to address.

value. The value is the setting you want to give to a key.

A couple of useful examples:

Example 1-1. List all defaults features

defaults help

Example 1-2. List all available domains

defaults domains


GNUstep Domains

Data, programs and libraries can be installed on a system in four different ways. First there is the stuff installed/ supplied by a vendor, second are the things that are installed by the local system administrator, third is the data that is shared over a network and last there is the user that can install his or her own applications, data and the like.

To decide which has presidence over what, it is defined within the GNUstep system that there is a search order. This definition says that everything installed in the User domain has precedence over the Network domain, which in turn has precendence over the Local domain, which has precedence over the System domain.

These different domains are defined in variables with the logical names: GNUSTEP_SYSTEM_ROOT, GNUSTEP_LOCAL_ROOT, GNUSTEP_NETWORK_ROOT and GNUSTEP_USER_ROOT. Which are actually paths to directories.

The order is expected throughout this document unless mentioned otherwise. Paths mentioned in this document are thus only addressed by the part that comes behind the domain paths mentioned.


GNUstep Daemons

Daemons are programs that run in memory and that supply a service. So you don't start them once in a while like a tool or and application, but they keep on running even when you don't use them.


Chapter 2. Changing the backend

GNUstep can run on a variaty of systems with a variaty of display engines. To accompany all those systems the GNUstep developers where smart enough to invent a system called a backend. This means that you only have to install the backend that you need for your displaying engine, which keeps things lean and mean. And it makes it easier to port a GNUstep system to a new displaying engine.

With a simple setting one can choose which backend to use. This can be done for the entire system or for a single application.


Setting the system default backend

To set the system to use a certain backend as a default use:

Example 2-1. GSBackend system

defaults write NSGlobalDomain GSBackend libgnustep-back

The default setting is libgnustep-back.

Dependend on how gnustep-back was configured there are different names for the backend. However the current situation is such that there is a backend that uses X11, libart, cairo or Microsoft® Windows®.


Setting the backend per application

If you want to change the backend for a certain application and you have more then one backend installed, you can set the backend like this:

Example 2-2. GSBackend application

defaults write ApplicationName GSBackend libgnustep-back

The default setting is identical to the backend set in NSGlobalDomain.


Chapter 3. Localization

Localization means that the system is set to use your native language, currency, metric system, time zone, etc. This chapter will describe all the settings available to adjust the system to your situation.

The major part of the localization can be done within the GNUSTEP_SYSTEM_ROOTLibrary/Libraries/Resources/gnustep-base/Languages/ directory. Within that directory you will find a file per English name of a certain language. Adjusting the file for your language gives you the opportunity to almost completely localize your system.


Local Time Zone

GNUstep comes with its own time zone files, this might seem redundant, but it isn't. GNUstep runs on a lot of different systems with a lot of different ways of handling time. With GNUstep provided time zone solution, this problem is solved without the need of adding code for every possible system in the universe to the code base.

The time zone files are located in the GNUSTEP_SYSTEM_ROOT/Library/Libraries/Resources/gnustep-base/NSTimeZones/, with all needed documention and code available. The real zones are in a subdirectory called zones/.

Example 3-1. Local Time Zone

defaults write NSGlobalDomain "Local Time Zone" Europe/Amsterdam

as you can see the entire path is not needed just the file Europe/Amsterdam within the zones/ directory.


Language settings

To set the system to use your local language use the NSLanguages key. If the system and/ or an application is able to use your language it will do so. If it can not then it will use the default.

You could also specify a string of languages where you decide what language should be used next. When you for instance specify Dutch,English the system will first try the Dutch translation, then English and then the default.

To setup your system to use a certain language use:

Example 3-2. NSLanguages

defaults write NSGlobalDomain NSLanguages "(Dutch,English)"
By replacing the NSGlobalDomain with the name of an application, you could specify per application which language order it should use.


Creating your local language support

If you want to change an application to support your language you can find within Resources/ directory of the Application a .lproj file. If you copy e.g. the English.lproj directory to the English name of your language e.g Dutch.lproj. You then have to adjust the Localizeable.strings file and start Gorm to adjust the .gorm file.


Metrics used

The NSMeasurementUnit is a string describing the measurement unit for rulers. The default is Centimeters. Other possible values are Inches, Points, and Picas.

Example 3-3. NSMeasurementUnit

defaults write NSGlobalDomain NSMeasurementUnit Points


Chapter 4. Keyboard handling

Your keyboard has several so called modifier keys, like Ctrl, Shift, Alt, etc. Those keys, when pressed together with one of the default keys like a or w, have a special meaning. They modify the behaviour of a key. Like when you press Shift-a you get A.

The OpenStep specification requires 3 different keyboard modifiers: CONTROL, ALTERNATE, and COMMAND. These modifiers are defined through the GSFirstControlKey, GSSecondControlKey, GSFirstAlternateKey, GSSecondAlternateKey, GSFirstCommandKey and GSSecondCommandKey.

Table 4-1. Keyboard Modifiers

KeyDefault value
GSFirstControlKeyControl_L
GSSecondControlKeyControl_R
GSFirstAlternateKeyALT_R
GSSecondAlternateKeyNoSymbol
GSFirstCommandKeyALT_L
GSSecondCommandKeyNoSymbol

Because the CONTROL, ALTERNATE and COMMAND keys are now mapped to special functions, one needs a way to escape them so you can use them in e.g. a text document. There are three settings that determine how the escaping is done: GSInsertControlKeystrokes, GSAbortKey, and GSQuoteKey.


Handling the control-key

The GSInsertControlKeystrokes setting tells the system to insert any keystroke containing the control-key into the text if set to YES note that you then also loose the CONTROL functionality. This boolean is per default set to NO which results in a beep when a keystroke without a binding is detected.

Example 4-1. GSInsertControlKeystrokes

defaults write NSGlobalDomain GSInsertControlKeystrokes YES


Abort Key

The GSAbortKey setting is used to abort the insertion of multi-stroke keybinding. The default is Control-g. To change this setting use:

Example 4-2. GSAbortKey

defaults write NSGlobalDomain GSAbortKey 'Control-g'


Quote Key

The GSQuoteKey key defines which keystroke is used to indicate that the next keystroke should be quoted (escaped). The key(s) pressed after the GSQuoteKey will thus not be handled as a keybinding, but inserted in the text as is.

To change the setting use:

Example 4-3. GSQuoteKey

defaults write NSGlobalDomain GSQuoteKey 'Control-q'
The default for this setting is Control-q


Menu Keys

The NSCommandKeys dictionary consists of the name of the menu item and the value of the associated command key. E.g "Copy" and "C"

[META] Find more and write example.


Keybindings

A keybinding is the relationship between an action and a keystroke, where a keystroke can mean a single key on your keyboard like a or w, but is can also be Ctrl-a or Ctrl-w. Thus keystrokes can also be a combination of keys pressed at the same time.

The keybindings for GNUstep are defined in .dict files. These files are searched for in the default Library/Keybindigs/ directories, with the last one found overwriting definitions described in previous ones.

The file for defining the default keybindings is called DefaultKeybindings.dict.

Thus to overwrite the system default create your own DefaultKeyBindings.dict file in $GNUSTEP_USER_ROOT/Library/Keybindings/.

The GSKeybindingsFiles setting is an array of strings containing the filenames without the .dict extension. The order of the array is the order in which the library tries to load the files from the default domains.

The default value for GSKeybindingsFiles is (DefaultKeyBindings), and this value should only be changed if you want to load other files then the default one, for e.g. testing purposes.

Example 4-4. GSKeybindingsFiles

defaults write NSGlobalDomain GSKeybindingsFiles (DefaultKeyBindings)

If you only have a couple of keybindings that you want to set or overwrite, the GSKeyBindings dictionary is the place to be. It is always advised to use a file to store your keybinding settings if you have more then just a couple.

The GSKeyBindings dictionary is loaded after the default ones.

[META] write example


Keybinding file description

[META] Explain how this works some day

{
   /* examples */
   "UpArrow" = "moveUp:";
   "Control-a" = "moveToBeginningOfLine:";
}


Chapter 5. Default applications

Setting the Workspace application

The NSWorkspace needs an application to connect to when some operations require an external application. The application called by NSWorkspace can be set through the GSWorkspaceApplication setting. Default this is set to GWorkspace.

Example 5-1. GSWorkspaceApplication

defaults write NSGlobalDomain GSWorkspaceApplication GWorkspace


Default PostScript previewer for printing

The default application that the NSPrintOperation uses to preview PostScript® files is controlled by NSPreviewApp. This defaults to gv, unless there is already an application registed as a viewer of PostScript® files.

Example 5-2. NSPreviewApp

defaults write NSGlobalDomain NSPreviewApp gv


Chapter 6. Displaying Files

Displaying directories

To make directory names stand out compared to filenames one can set the boolean value of GSBrowserCellFontify to YES. Per default this setting is set to NO, which means that the font used for filenames and directory names in e.g. the filebrowser are drawn in a non-bold font. To set the behaviour so that directories are drawn in a bold font use:

Example 6-1. GSBrowserCellFontify

defaults write NSGlobalDomain GSBrowserCellFontify YES


Hide dot-files

Per default files starting with a dot ('.') are not hidden. On Unix-like systems this might clutter the users home directory. The GSFileBrowserHideDotFiles setting changes this for the save and open panels.

The setting is a boolean, default set to NO. To change this use:

Example 6-2. GSFileBrowserHideDotFiles

defaults write NSGlobalDomain GSFileBrowserHideDotFiles YES


Chapter 7. Icons

You may change most icons, by editing the nsmapping.strings file. This file can be found in the $GNUSTEP_SYSTEM_ROOT/Library/Images/ directory per default. To change your personal settings use the $GNUSTEP_USER_ROOT/Library/Images/nsmappings.strings.

The syntaxt of the file looks like this:

/* Examples */
NSSwitch = common_SwitchOff;
NSHighlightedSwitch = common_SwitchOn;
NSRadioButton = common_RadioOff;
The lefthand part is the OPENSTEP name, and the left hand part is the filename without the extensions. The images must be found in the same directory as the nsmapping.strings file.


Freedesktop icons

When you want to use the thumbnail files as specified by the Freedesktop you should set the boolean GSUseFreedesktopThumbnails setting to YES, default this setting is set to NO.

This setting is used in [NSWorkspace iconForFile:]


Window Maker Dock

To make GNUstep applications dockable in Window Maker UseWindowMakerIcons should be set to YES (the default). If Window Maker isn't used this setting has no effect.

If set to YES the application icon window is placed in the one that is provided by Window Maker (on the Dock). If the value is NO the application icon window is controlled by the application itself.


Chapter 8. Styles

NSInterfaceStyleDefault can be used to change the interface style. This is described somewhere... [META]

Styles: NSNextStepInterfaceStyle, NSMacintoshInterfaceStyl, NSWindows95InterfaceStyle, GSWindowMakerInterfaceStyle

Default: NSNoInterfaceStyle

An interface style specific to menu operation. If not set the NSInterfaceStyleDefault value is used.


Chapter 9. GNUstep color system

Internally GNUstep uses names to address colors. These names are defined in externs.m and NSColor.m. The system grey scales are described in externs.m which is used and completed by NSColor.m to result in the following table:

Table 9-1. Color names

ColornameRed valueGreen valueBlue ValueAlpha Value
black0.00.00.01.0
blue0.00.01.01.0
brown0.60.40.21.0
clear0.00.00.00.0
cyan0.01.01.01.0
darkGray0.3330.3330.3331.0
gray0.50.50.51.0
green0.01.00.01.0
lightGray0.6670.6670.6671.0
magenta1.00.01.01.0
orange1.00.50.01.0
purple0.50.00.51.0
red1.00.00.01.0
white0.00.00.01.0
yellow1.01.00.01.0

The first time a GNUstep application is started a system color file called System.clr is created in the GNUSTEP_USER_ROOT/Library/Colors/ directory. This is a binary file, and thus not easily adjustable. To change the system colors one needs the defaults command.

The values of Red, Green and Blue are not X11 RGB values, those have to be calculate using a formula of decimal-color-value devided by 255. A value of #505075 (as used by webpages) is hexadecimal, which means you have 80 decimal for red, 80 for green and 117 for blue. Which results in the following values:

Red = 80/255 = 0.313

Green = 80/255 = 0.313

Blue = 117/255 = 0.418

If you would like to change the colors of your system, you need to calculate the values for the keys defined in the system. The following keys are defined and can be used to change the GNUstep-looks:

Table 9-2. GNUstep color keys

KeyDescriptionDefault
controlBackgroundColorThe color used for buttons, sliders, and the background of non-filled browser space.lightGray
selectedMenuItemColorThe color for a selected menu item.white
selectedMenuItemTextColorThe color of the text on a selected menu item.black
controlColor lightGray
controlHighlightColor lightGray
controlLightHighlightColor white
controlShadowColorThe shadow color around buttonsdarkGrey
controlDarkShadowColor black
controlTextColor black
disabledControlTextColor darkGray
gridColor gray
headerColor lightGray
headerTextColor black
highlightColor white
keyboardFocusIndicatorColor black
knobColor lightGray
scrollBarColor gray
selectedControlColor white
selectedControlTextColor black
selectedKnobColor lightGrey
selectedTextBackgroundColor lightGrey
selectedTextColor black
shadowColor black
textBackgroundColor white
textColor black
windowBackgroundColor lightGray
windowFrameColor black
windowFrameTextColor white

To change the keys use:

Example 9-1. Change color keys

defaults write NSGlobalDomain controlBackgroundColor "0.313 0.313 0.418"


Application color names

Within an application it is possible to use ones own list of named colors. This list is loaded by NSColorList and can be created as an ASCII configuration file with the .scr extension. Such a file might look like this:

3
0 1.000 0.980 0.980 1.0 snow
0 0.972 0.972 1.000 1.0 ghost white
0 0.972 0.972 1.000 1.0 GhostWhite
The first line tells the system the amount of colors it can expect. In this case 3 new entries.

The first element of a line describes the type of color that is defined. In this case the 0 says RGB+Alpha since that is currently the only supported one.

The next three elements are the Red, Green, and Blue values.

The 1.0 entry is the value for alpha.

And finally there is the name that is given to the color entry.


Setting the colors per channel

NSColorsPerChannel defines the maximum number of colors to display. The default value is ???. This option is only available when using an X11 backend.

On pseudo-color displays this would limit the amount of colors available.

On true-color displays it limits the amount of red, green and blue ranges.


Chapter 10. Fonts

GNUstep can make use of the by the system supplied fonts, e.g. de fonts already installed on Windows®, or the ones supplied by X11, or GNUstep could use the specific fonts located in the Library/Fonts/ directories.

Every font key, like NSBoldFont, also has a size element, NSBoldFontSize. Within the following table the size component is mentioned in the Size column. If there is no setting for a certain key it defaults to the value corresponding with the key mentioned in the Value or Size column.

Table 10-1. System Font Defaults

KeyValueSize
NSBoldFontHelvetica-BoldNSFontSize
NSControlContentFontNSFontNSFontSize
NSFontHelvetica12
NSLabelFontNSFontNSFontSize
NSMenuFontNSFontNSFontSize
NSMessageFontNSFontNSFontSize
NSPaletteFontNSBoldFontNSFontSize
NSTitleBarFontNSBoldFontNSFontSize
NSToolTipsFontNSFontNSFontSize
NSUserFixedPitchFontCourierNSFontSize
NSUserFontNSFontNSFontSize
An exception to the rule is NSSmallFontSize, which only has a size, which per default is set to 9.


Anti-Aliased Fonts

GSFontAntiAlias sets the anti-aliasing of fonts. It's a boolean value containing YES or NO.

If this setting is YES for the X11 backend and X11 has the XFT extension then anti-aliased fonts are used.

If this setting is YES for the libart backend text is anti-aliased at small sizes (9-16 pixels).


Multi-byte and Unicode support

To enable Multi-byte/Unicode support, which is useful for many East Asian languages set the GSXEnableFontSet to YES. It's default value is NO since the backend is somewhat slower with GSXEnableFontSet enabled.


Font mask for X11

Normally all fonts available in the X-server will be used with GNUstep, the default for GSFontMask is thus "*". If there are enormous amounts of fonts installed it might happen that the font_cacher is having problems with the X-server. To solve that problem you could select a mask of fonts to be used, e.g. "*-iso8859-1" so only the ISO Western fonts are loaded.


nfonts for libart

The libart based backend can use the fonts using the .nfont extension. An .nfont is a directory containing a single, complete font family. It also contains a FontInfo.plist with information about the family, and any files needed to render the faces in the family, referenced from FontInfo.plist.

The official specification of an .nfont can be found at http://w1.423.telia.com/~u42308495/alex/GNUspec/nfont_packages.txt


Chapter 11. unknown

When the GSSavePanelShowProgress is set to YES the open and save panels will show a progress indicator when reading the contents of a directory to be displayed. This setting is default set to NO.

The GSAppKitUserBundles contains an array containing bundles. These bundles will be loaded into each application at startup. The most useful function is to load "theme" bundles.

The GSLogWorkspaceTimeout is a boolean value that defaults to NO. This is a obscure and probably not useful default. NSWorkspace tries to receive distributed notifications, but if a distributed objects server cannot be found or some other error occurs, it raises an exception which normally terminates the program. Setting this default causes NSWorkspace to just log the problem without raising an exception.

NSHost is used by the NSPasteboard to find the host that the pastboard server is running on.

NSDefaultVisual: An integer that specifies the X-Windows visual class to use in the application. For instance one could display the application using the PsuedoColor visual class by setting the value to the id of this class. The default is the X-Windows default visual class.

GSAppOwnsMiniwindow: GSAppOwnsMiniwindow is for miniwindows (not app icons). If it's YES or absent, GNUstep handles miniaturization itself and doesn't let the window manager do it. If it's NO, the window manager is allowed to do its own iconification. This does not affect app icons at all.

GSUseWMTaskBar: [W32 backend only] A string value which defaults to YES. If enabled, the backend assumes that miniwindows are displayed in a task bar. In this case, the app icon is not shown and the main menu behavior is changed so it is not ordered out, but minimized, so clicking on the minimized menu will activate the application.

GSXIMInputMethodStyle: A string value used to specify the XIM input method for entering characters. Valid values are RootWindow, OffTheSpot, or OverTheSpot.

GraphicCompositing: [Xlib backend only] A boolean value which defaults to YES. If set to YES, then the application uses various tricks to get alpha colors to work when compositing images. This may slow down drawing of images, but it is generally recommended anyway, particularly on fast systems.

XGPS-Shm: A boolean value which defaults to YES (as long as shared memory is available). If set to NO, shared memory is not used for various display specific operations.

GSOldClipboard: [X backends only] A boolean value which defaults to NO. If set to YES the old GNUstep way of X clipboard interaction will be used. That is PRIMARY as the general pasteboard and CLIPBOARD for the selection. Whereas the new X standard is the other way around. This setting may be needed for interaction in an old X enviornment.