
@node Customization, Frequently Asked Questions, Usage, Top
@comment  node-name,  next,  previous,  up
@chapter Customization

The preferences file is preprocessed with @b{cpp} before being
read, so you can use cpp features, like @file{#define}, @file{#include}
and comments (@file{//})

@menu
* The C Pre-Processor (CPP)::   
* The preferences file::        
@end menu

@node The C Pre-Processor (CPP), The preferences file, Customization, Customization
@comment  node-name,  next,  previous,  up
@section The C Pre-Processor (CPP)

@menu
* Pre-defined symbols::         
@end menu

@node Pre-defined symbols,  , The C Pre-Processor (CPP), The C Pre-Processor (CPP)
@comment  node-name,  next,  previous,  up
@subsection Pre-defined symbols

@noindent WindowMaker defines the following symbols for cpp:

@table @asis
@item @var{HOST} @kbd{hostname}           
name of the host where wmaker is running
@item @var{USER} @kbd{username}           
the login name of the user running wmaker
@item @var{DISPLAY}  @kbd{display-name}   
display name wmaker is using
@item @var{UID} @kbd{user-id}         
user id of the user running wmaker

@iftex
@item @var{WM@_VERSION} @kbd{version}      
the version number string of WindowMaker
@item @var{MAJ@_VERSION}  @kbd{version}    
major version number of WindowMaker
@item @var{MIN@_VERSION}  @kbd{version}    
minor version number of WindowMaker
@end iftex

@ifinfo
@item @var{WM_VERSION} @kbd{version}      
the version number string of WindowMaker
@item @var{MAJ_VERSION}  @kbd{version}    
major version number of WindowMaker
@item @var{MIN_VERSION}  @kbd{version}    
minor version number of WindowMaker
@end ifinfo

@item @var{VISUAL}   @kbd{visual-class}    
the visual class of the default screen
@item @var{DEPTH}   @kbd{depth}           
the color depth of the default screen

@iftex
@item @var{SCR@_WIDTH} @kbd{width}         
width of default screen
@item @var{SCR@_HEIGHT} @kbd{height}       
height of default screen
@end iftex

@ifinfo
@item @var{SCR_WIDTH} @kbd{width}         
width of default screen
@item @var{SCR_HEIGHT} @kbd{height}       
height of default screen
@end ifinfo

@item @var{XPM}                     
@* defined if XPM is supported
@item @var{DITHERING}               
defined if dithering is supported
@end table

@node The preferences file,  , The C Pre-Processor (CPP), Customization
@comment  node-name,  next,  previous,  up
@section The preferences file

The preference options define some appearance and behaviour parameters for
WindowMaker. They are read at startup from the
@file{~/gnustep/Library/WindowMaker/preferences} file or equivalent system wide
location. 

If you do not have such file, you should make the @file{~/gnustep/Library/WindowMaker}
directory and copy the configuration files there.

The preferences file is divided into 4 sections, each starting with a keyword enclosed in
square brackets. The @emph{order} of the sections must be obeyed, but the order of each option
within a section does not mattter.

@menu
* Preferences section::         
* Style Section::               
* Keyboard shortcut section::   
* Specific Window Attributes::  
@end menu

@node Preferences section, Style Section, The preferences file, The preferences file
@comment  node-name,  next,  previous,  up
@subsection [Preferences]
	
@noindent This section defines general behaviour parameters for WindowMaker.

@table @asis
@item @emph{Pixmap Search Path}
Defines the paths to look for pixmap files to be used for icons and miniwindows. Each path
must be separated by a : and must have a slash (@file{/}) appended.

@itemize @minus
@item @b{Syntax:}
@t{PixmapPath=path:path:...}

@item @b{Example:}
@t{PixmapPath=/usr/include/X11/pixmaps/:~/pixmaps/}
@end itemize



@item @emph{Dithering}
@* Defines whether pixmaps should be dithered. Dithering allows the "simulation" of some
colors that can not be displayed by your video hardware so that any color image can be
displayed. The problem is that dithered images tend to look less smooth than their
originals.

@itemize @minus
@item @b{Syntax:}
@t{Dithering=<boolean>}

where @t{<boolean>} can be yes or no
@end itemize

Dithering should be enabled for 8bpp, 15bpp and 16bpp display users.  16bpp users will not
notice much difference, unless they use gradients.  8bpp users should definitely want to
enable dithering, otherwise your display will run out of colors and programs like Netscape
will not work properly (looking pretty ugly at best).

@strong{How to verify your display depth?}

Run the @file{xwininfo} command.  When it asks to click on a window, click in the
workspace. It will display a series of informations and the value of Depth says how many
bits per pixel (bpp) your display is capable of.

@item @emph{Dither Colormap}

@dfn{DitherColormap} specifies how much colors should be used for dithering in
@dfn{PseudoColor} (usually 8bpp) displays. The more colors you reserve for dithering, the
less colors will be left for applications.  This options has no effect for @dfn{TrueColor}
displays.

@itemize @minus
@item @b{Syntax:}
@t{DitherColormap=<red weight>/<green weight>/<blue weight>}

Where red, green and blue weights define how many of each of these components should be
used during dithering. They must be greater than 1 and their product must be smaller than
the maximum number of colors your X server can display. This is 256 for 8bpp.

@item @b{Example:}
@t{DitherColormap=3/4/3}
@end itemize

This will reserve 36 colors for dithering, which leaves enough
colors for most applications.


@item @emph{Extra Color Saving}
If you're really having problems with shortage of color cells, you can enable
SaveColors. You usually will not nead to worry about this option and can safely set it to
no.

@itemize @minus
@item @b{Syntax:}
@t{SaveColors=<boolean>}
@end itemize


@item @emph{Submenu alignment}
	This options specifies whether submenus should be aligned
in the top with their parents or not.

@itemize @minus
@item @b{Syntax:}
@t{AlignSubmenus=<boolean>}
@end itemize
	
@item @emph{Type of window geometry displays}

These specify how to display window geometry (size or position) information. They can be
changed by hitting the @kbd{<Shift>} key during resize of move.

@itemize @minus
@item @b{Syntax:}

@t{ResizeDisplay=<resize display type>}

@t{MoveDisplay=<move display type>}

Where resize display type can be one of:

@itemize @bullet 
@item center 
Displays a little window with the window size in the center of the screen

@item corner 
Displays the window in the top left corner of the screen

@item floating
Display sthe window in the center of the window being moved

@item line	
Displays a technical drawing style line indicating the dimensions of the window
@end itemize

The same display types apply to MoveDisplay, except the line type.
@end itemize


@item @emph{Type of keyboard input focusing}

The window where keyboard input goes is called the keywindow or focused window (as it has
the keyboard focus). It is highlighted in black or some other color, depending on your
configuration.  The main way to select the current keywindow is with the pointer.

@itemize @minus
@item @b{Syntax:}
@t{FocusMode=<focus type>}

@itemize @bullet  
@item manual or ClickToFocus
To select a window to be the keywindow, you must click with the mouse in the desired
window.

@item auto or FocusFollowsMouse
The window currently under the mouse pointer is the Key Window.

@item semiAuto or SloppyFocus
As above, but windows don't lose focus when you move the pointer over the root window
@end itemize
@end itemize

@item @emph{Raise on focus}
Specifies if the window should be raised (brought to front) when it is focused. This
option has no effect for manual FocusMode.

@itemize @minus
@item @b{Syntax:}
@t{RaiseOnFocus=<boolean>}
@end itemize


@item @emph{Ignore focus click}
In manual FocusMode, the mouse click used to focus a window is generally passed to the
application. If you want that applications ignore this mouse click, set this option to
true. This option does not have effect on auto or semiauto FocusMode.

@itemize @minus
@item @b{Syntax:}
@t{IgnoreFocusClick=<boolean>}
@end itemize

@item @emph{Window placement}
Specifies how new windows should be placed on screen.

@itemize @minus
@item @b{Syntax:}
@t{WindowPlacement=<placement mode>}

Where placement mode can be:

@itemize @bullet 
@item manual
Interactively lay down new windows
@item cascade
Cascading of new windows
@end itemize
@end itemize

@item @emph{Menu lowering}
Specifies whether menus should be allowed to be placed under normal windows, through
@kbd{Meta-Click}.

@itemize @minus
@item @b{Syntax:}
@t{AllowMenuLowering=<boolean>}
@end itemize

@item @emph{Start with opened root menu}
Whether the root menu should be opened at startup and where to open it. If you want the
menu not to start opened, remove this option from the preferences file.

@itemize @minus
@item @b{Syntax:}
@t{RootMenuPosition=<x>,<y>}

@item @b{Example:}
@example
RootMenuPosition=10,20
@end example
@end itemize


@item @emph{Enable SaveUnders}
Some apps like Netscape have problems with redrawing if a window with SaveUnders (e.g.: a
menu) is laying over them.  Turning UseSaveUnders off may fix this, but will make things a
little slower and add some flickering.

@itemize @minus
@item @b{Syntax:}
@t{UseSaveUnders=<boolean>}
@end itemize
@end table

@node Style Section, Keyboard shortcut section, Preferences section, The preferences file
@comment  node-name,  next,  previous,  up
@subsection [Style]
	
@noindent This section defines how WindowMaker will look. Details like
font, colors and textures may be specified.  You may leave most of this section blank to
get the original NEXTSTEP(tm) look, based on black, white and gray.

@table @asis
@item @emph{IconBackPixmap}
Specifies the tile pixmap to be used in the background of icons and miniwindows. This
pixmap must be in the XPM format and have 64x64 pixels of size.

@itemize @minus
@item @b{Syntax:}
@t{IconBackPixmap=<xpm file>}
@end itemize

@item @emph{IconDotsPixmap}
Specifies the pixmap to be used for indicating that a docked application is not yet
running. Leaving this out, makes an internal pixmap be used. The pixmap must have
transparent pixels or it will cover the whole icon image. The pixmap must be 64x64 pixels.

@itemize @minus
@item @b{Syntax:}
@t{IconDotsPixmap=<xpm file>}
@end itemize

@item @emph{LogoPixmap}
Specifies the pixmap to be used in the first dock icon. Must be a XPM file of at most
48x48 pixels.

@itemize @minus
@item @b{Syntax:}
@t{LogoPixmap=<xpm file>}
@end itemize

@item @emph{Titlebar text justification}
Specifies the justification to apply to titlebar text.

@itemize @minus
@item @b{Syntax:}
@t{TitleTextJustify=<justification>}

Justicfication may be either
@itemize @asis
@item center
@item left
@item right.
@end itemize
@end itemize

@item @emph{Titlebar text font}
Specifies the font to use in window titlebar text.

@itemize @minus
@item @b{Syntax:}
@t{WindowTitleFont=<font specification>}

Where font specification is a complete font specification. You can choose
fonts with the @file{xfontsel} utility.

@item @b{Example:}
@t{WindowTitleFont= -adobe-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*}
@end itemize

@item @emph{Menu font}
@* Specifies the font to use in menu titlebar and item text.

@itemize @minus
@item @b{Syntax:}
@t{MenuTitleFont=<font specification>}

@t{MenuTextFont=<font specification>}
@end itemize


@item @emph{Miniwindow font}
Font for the miniwindow (or icon) title.

@itemize @minus
@item @b{Syntax:}
@t{IconTitleFont=<font specification>}
@end itemize

@item @emph{Resize/Move display text}
Font for the resize/move display.

@itemize @minus
@item @b{Syntax:}
@t{DisplayFont=<font specification>}
@end itemize

@item @emph{Dialog title font}
Font for the title of dialog boxes.

@itemize @minus
@item @b{Syntax:}
@t{DialogFont=<font specification>}
@end itemize

@item @emph{Dialog message font}
Font for dialog messages.

@itemize @minus
@item @b{Syntax:}
@t{DialogMessageFont=<font specification>}
@end itemize

@item @emph{Text colors}
Specifies which color to use for text. Color may be either a color name found on the
output of the showrgb command or a RGB color specification in the @kbd{#RRGGBB} format.

@item @emph{Keywindow titlebar text}

@itemize @minus
@item @b{Syntax:}
@t{FTitleForeColor=<color>}
@end itemize

@item @emph{Unfocused main window titlebar text}

@itemize @minus
@item @b{Syntax:}
@t{PTitleForeColor=<color>}
@end itemize

@item @emph{Text color for unfocused window titlebars}

@itemize @minus
@item @b{Syntax:}
@t{UTitleForeColor=<color>}
@end itemize

@item @emph{Text color for menu titlebars}

@itemize @minus
@item @b{Syntax:}
@t{MenuTitleForeColor=<color>}
@end itemize

@item @emph{Menu Entry color}

@itemize @minus
@item @b{Syntax:}
@t{MenuTextForeColor=<color>}
@end itemize

@item @emph{Disabled menu entry color}

@itemize @minus
@item @b{Syntax:}
@t{MenuTextDisabledColor=<color>}
@end itemize


@item @emph{Texture specification}

There are currently 4 types of textures available: solid and 3 styles of gradients. 8bpp
users should use solid textures. Although gradients are supported in 8bpp mode, they look
very bad.

@item @emph{Texture types}
@noindent Texture types can be:

@itemize @asis
@item @b{solid}
for a plain solid color
@item @b{hgradient}
for a gradient that varies horizontally
@item @b{vgradient}
for a gradient that varies vertically
@item @b{dgradient}
for a gradient that varies diagonally
@end itemize

@item @emph{Texture type for keywindow titlebar}

@itemize @minus
@item @b{Syntax:}
@t{FTitleTexture=<texture type>}
@end itemize

@item @emph{Texture type for unfocused mainwindow titlebars}

@itemize @minus
@item @b{Syntax:}
@t{PTitleTexture=<texture type>}
@end itemize

@item @emph{Texture type for unfocused titlebars}

@itemize @minus
@item @b{Syntax:}
@t{UTitleTexture=<texture type>}
@end itemize

@item @emph{Texture type for menu titlebars}

@itemize @minus
@item @b{Syntax:}
@t{MenuTitleTexture=<texture type>}
@end itemize

@item @emph{Texture type for menu entries}

@itemize @minus
@item @b{Syntax:}
@t{MenuTextTexture=<texture type>}
@end itemize

@item @emph{Color for keywindow titlebar}

@itemize @minus
@item @b{Syntax:}
@t{FTitleBackColor=<color>}
@end itemize

@item @emph{Color for unfocused mainwindow titlebar}

@itemize @minus
@item @b{Syntax:}
@t{PTitleBackColor=<color>}
@end itemize

@item @emph{Color for unfocused titlebar}

@itemize @minus
@item @b{Syntax:}
@t{UTitleBackColor=<color>}
@end itemize
    
@item @emph{Color for menu titlebars}

@itemize @minus
@item @b{Syntax:}
@t{MenuTitleBackColor=<color>}
@end itemize

@item @emph{Color for menu items}

@itemize @minus
@item @b{Syntax:}
@t{MenuTextBackColor=<color>}
@end itemize

@item @emph{Gradient colors for keywindow titlebar}

@itemize @minus
@item @b{Syntax:}
@t{FTitleGradient=<from_color>,<to_color>}
@end itemize

@item @emph{Gradient colors for unfocused titlebars}

@itemize @minus
@item @b{Syntax:}
@t{PTitleGradient=<from_color>,<to_color>}
@end itemize

@item @emph{Gradient colors for unfocused titlebar}

@itemize @minus
@item @b{Syntax:}
@t{UTitleGradient=<from_color>,<to_color>}
@end itemize

@item @emph{Gradient colors for menu titlebar  }

@itemize @minus
@item @b{Syntax:}
@t{MenuTitleGradient=<from_color>,<to_color>}
@end itemize

@item @emph{Gradient colors for menu entries}

@itemize @minus
@item @b{Syntax:}
@t{MenuTextGradient=<from_color>,<to_color>}
@end itemize
@end table

@node Keyboard shortcut section, Specific Window Attributes, Style Section, The preferences file
@comment  node-name,  next,  previous,  up
@subsection [Shortcuts]

@noindent Key specifiers are in the format:
@example
@kbd{<Modifier>+<KeySym>}
@end example

Where @dfn{modifier} is any number of modifiers separated by @file{+}. The modifiers are: 
@itemize @asis
@item Shift
@item Control
@item Alt
@item Meta
@item Super
@item Hyper
@end itemize

Valid @dfn{KeySym} values can be found in @file{/usr/include/X11/keysymdef.h} (the leading
XK_ must be removed) 

@table @asis
@item @emph{Open/Close or raise root menu}

@itemize @minus
@item @b{Syntax:}
@t{RootMenu=<key combination>}
@end itemize

@item @emph{Miniaturize focused window}

@itemize @minus
@item @b{Syntax:}
@t{Miniaturize=<key combination>}
@end itemize

@item @emph{Hide focused application }

@itemize @minus
@item @b{Syntax:}
@t{Hide=<key combination>}
@end itemize

@item @emph{Maximize focused window}

@itemize @minus
@item @b{Syntax:}
@t{Maximize=<key combination>}
@end itemize

@item @emph{Close focused window}

@itemize @minus
@item @b{Syntax:}
@t{Close=<key combination>}
@end itemize

@item @emph{Raise focused window}

@itemize @minus
@item @b{Syntax:}
@t{Raise=<key combination>}
@end itemize
  
@item @emph{Lower focused window}

@itemize @minus
@item @b{Syntax:}
@t{Lower=<key combination>}
@end itemize

@item @emph{Raise or Lower focused window}

@itemize @minus
@item @b{Syntax:}
@t{RaiseLower=<key combination>}
@end itemize

@item @emph{Shade/unshade focused window}

@itemize @minus
@item @b{Syntax:}
@t{Shade=<key combination>}
@end itemize

@item @emph{Set focus to next window}

@itemize @minus
@item @b{Syntax:}
@t{FocusNext=<key combination>}
@end itemize

@item @emph{Set focus to previous window}

@itemize @minus
@item @b{Syntax:}
@t{FocusPrev=<key combination>}
@end itemize

@item @emph{Switch to next workspace}

@itemize @minus
@item @b{Syntax:}
@t{NextWorkspace=<key combination>}
@end itemize
  
@item @emph{Switch to previous workspace}

@itemize @minus
@item @b{Syntax:}
@t{PrevWorkspace=<key combination>}
@end itemize

@item @emph{Switch to workspace}

@itemize @minus
@item @b{Syntax:}
@*@t{Workspace1=<key combination>}
@*@t{Workspace2=<key combination>}
@*@t{Workspace3=<key combination>}
@*@t{Workspace4=<key combination>}
@*@t{Workspace5=<key combination>}
@*@t{Workspace6=<key combination>}
@*@t{Workspace7=<key combination>}
@*@t{Workspace8=<key combination>}
@*@t{Workspace9=<key combination>}
@end itemize
@end table

@node Specific Window Attributes,  , Keyboard shortcut section, The preferences file
@comment  node-name,  next,  previous,  up
@subsection [Window Attributes]

@noindent This section defines special attributes to specific windows, like their icon
images and window decorations. 

To specify a given window you must get the class and instance information about the
window. You can get this information by double clicking the titlebar of the target window
with the 3rd mouse button.  This will give dump a string of the following format to the
console:

@example
instance.class
@end example

@noindent This is the string you must use to specify attributes for that window, like:

@example
instance.class.icon:	my_icon_pixmap_file.xpm
@end example

@noindent You can also use the text displayed in the titlebar for that, but you should avoid it.  If
you want to set a global default, like the default icon for windows, use @kbd{*} as the
window specification, as in:

@example
*.icon: my_icon_pixmap_file.xpm
@end example

@table @asis
@item @emph{Icon Images}
Specify the pixmap or bitmap to be used for the window's miniwindow. If the window is the
application's main window, it will also be used as the application icon image. Pixmap files must be in some path specified by PixmapPath

@itemize @minus
@item @b{Syntax:}
@t{window_spec.icon:<xpm file>}
@end itemize

@item @emph{Titlebar}
@* Whether the window has a titlebar

@itemize @minus
@item @b{Syntax:}
@t{window_spec.titlebar:<boolean>}
@end itemize

@item @emph{Miniaturizable}
@* Whether the window can be miniaturized

@itemize @minus
@item @b{Syntax:}
@t{window_spec.miniaturizable:<boolean>}
@end itemize

@item @emph{Closable}
@* Whether the window should get a close button

@itemize @minus
@item @b{Syntax:}
@t{window_spec.closable:<boolean>}
@end itemize

@item @emph{Resizable}
@* Whether the window should get a resizebar

@itemize @minus
@item @b{Syntax:}
@t{window_spec.resizable:<boolean>}
@end itemize

@item @emph{Shadeable}
@* Whether the window can be shaded

@itemize @minus
@item @b{Syntax:}
@t{window_spec.shadeable:<boolean>}
@end itemize

@item @emph{Floating}
@* Whether the window should be placed on top of normal windows.

@itemize @minus
@item @b{Syntax:}
@t{window_spec.floating:<boolean>}
@end itemize

@item @emph{Omnipresent}
Whether the window should be present at all workspaces

@itemize @minus
@item @b{Syntax:}
@t{window_spec.omnipresent:<boolean>}
@end itemize

@item @emph{Focusable}
@* Whether the window should never become the keywindow

@itemize @minus
@item @b{Syntax:}
@t{window_spec.focusabled:<boolean>}
@end itemize

@item @emph{Full Keyboard Event Access}
Whether WindowMaker should allow all keyboard events to go to the application. This will
make keyboard shortcuts not work.

@itemize @minus
@item @b{Syntax:}
@t{window_spec.controlKeyboard:<boolean>}
@end itemize

@item @emph{Full Mouse Event Access}
Whether WindowMaker should not "steal" certain mouse events, like meta-click on the
window.

@itemize @minus
@item @b{Syntax:}
@t{window_spec.controlMouse:<boolean>}
@end itemize

@item @emph{Ignore HideOthers}
Whether the window should not be hidden when issuing a HideOthers command.

@itemize @minus
@item @b{Syntax:}
@t{window_spec.ignoreHideOthers:<boolean>}
@end itemize

@item @emph{No App Icon}
Do not make an application icon

@itemize @minus
@item @b{Syntax:}
@t{window_spec.noAppIcon:<boolean>}
@end itemize

@item @emph{Start Withdrawn}
Whether the window should be started in the WithdrawnState.

@itemize @minus
@item @b{Syntax:}
@t{window_spec.startWithdrawn:<boolean>}
@end itemize
@end table

