# Customizing the Workspace Manager

This chapter describes how to customize the desktop Workspace Manager.

SAG.WMCnf.div.3
SAG.WMCnf.div.8
SAG.WMCnf.div.13
SAG.WMCnf.div.18
SAG.WMCnf.div.22
SAG.WMCnf.div.26

The Workspace Manager is the window manager provided by the desktop. Like other window managers, it controls:

- The appearance of window frame components

- The behavior of windows, including their stacking order and focus behavior

- Key bindings and button bindings

- The appearance of minimized windows

- Workspace and Window menus

In addition, the Workspace Manager controls these desktop components:

- Workspaces. The Workspace Manager controls the number of workspaces, and keeps track of which windows are open in each workspace.

- Workspace backdrops. The user changes backdrops using Style Manager. However, backdrop management is a function of the Workspace Manager.

- The Front Panel. Although the Front Panel uses its own configuration files, it is created and managed by the Workspace Manager.

Many of these can be changed with Style Manager. Style Manager is able to make often-used changes quickly, with little effort on your part. Other resources must be set manually.

The Workspace Manager is `dtwm`. It is based on the Motif Window Manager.

## See Also

- For reference information about the Workspace Manager, see the `dtwm`(1) and `dtwmrc(4)` man pages.

- For information about setting Workspace Manager resources, see SAG.FACol.div.2.

- For information on Front Panel configuration files, see SAG.FrPC.mkr.1.

For additional information about setting resources, see SAG.FACol.div.2.

## Workspace Manager Configuration Files

The Workspace Manager gets information about the window menus, workspace menus, button bindings, and key bindings from a configuration file.

It uses one of the following files:

- Personal file: HomeDirectory`/.dt/
  dtwmrc`

- System custom file: `/etc/dt/config/`language`/
  sys.dtwmrc`

- Built-in file: `/usr/dt/config/`language`/sys.dtwmrc`

The Workspace Manager searches for a configuration file in the order shown above, and uses the first one it finds.

For users who use more than one session language, a personal, language- dependent configuration file HomeDirectory`/.dt`/language/`dtwrmc` can be created that takes precedence over HomeDirectory`/.dt/dtwmrc`.

### To Create or Modify a Personal Configuration File

The personal Workspace Manager configuration file is HomeDirectory`/.dt/dtwmrc`. If this file exists, it is the file used.

1. Double-click
   Edit Dtwmrc in the Desktop_Tools application group.

   If you already have a personal `dtwmrc` file, it is loaded into the editor. If not, `sys.dtwmrc` is copied to HomeDirectory`/.dt/dtwmrc`, which is then loaded into the editor.

2. Edit the file.

3. Exit the editor.

   The file is saved as your personal `dtwmrc`, regardless of its original source.

### To Create a System-Wide Configuration File

The system-wide Workspace Manager configuration file is `/etc/dt/config/`language`/sys.dtwmrc`.

1. Copy `/usr/dt/config/`language`/
   sys.dtwmrc` to `/etc/dt/config/`language`/sys.dtwmrc`.

This file is not used if HomeDirectory`/.dt/dtwmrc` exists.

### To Include (Source In) Other Files

1. Use the syntax:

       include
       {
           path
           path
         …
       }

For example, the following lines source in the file /`users/ellen/mymenu`:

    include
    {
       /users/ellen/mymenu
    }

Include statements are useful for providing additional functionality without copying the entire configuration file. For example, a user might want to create a new key binding without having to administer the entire configuration file. The user can create a file HomeDirectory`/.dt/dtwmrc` with this content:

    include
    {
     /etc/dt/config/C/sys.dtwmrc
    }
    Keys DtKeyBindings
    {
      Alt<Key>F5 root  f.menu  Applications
    }
    Menu Applications
    {
      “GraphicsApp” f.exec “/usr/bin/GraphicsApp/GApp”
      …
    }

### To Restart the Workspace Manager

The Workspace Manager must be restarted in order for changes made to the configuration file to take effect.

1. Choose Restart Workspace Manager from the Workspace menu (press mouse button 3 when the pointer is on the backdrop).

## Customizing Workspaces

Most workspace customization, such as changing workspace names and the number of workspaces, can be done by the user using the desktop's interface. However, the Workspace Manager provides resources for setting system-wide defaults.

### To Change the Number of Workspaces on a System-Wide Basis

The default desktop configuration provides four workspaces. The user can add and delete workspaces using the pop-up menu associated with the Workspace switch.

The Workspace Manager provides a resource for changing the default number of workspaces.

1. Use the `workspaceCount` resource to set the number of workspaces:

   `Dtwm*workspaceCount: number`

For information about setting Workspace Manager resources, see SAG.FACol.div.2.

For example, the following resource sets the number of workspaces to six:

    Dtwm*workspaceCount: 6

### To Provide System-Wide Workspace Names

Internally, the workspaces are numbered by the numbering convention `ws` n, where n is 0, 1, 2, and so on. For example, the default four workspaces are numbered internally `ws0` through `ws3`.

1. Use the `title` resource to change the name of a specified workspace:

       Dtwm*wsn: name

       Dtwm*wsn.title: name

For information about setting Workspace Manager resources, see SAG.FACol.div.2.

For example, the following resources set the default four workspaces to the specified names:

    Dtwm*ws0*title:  Anna
    Dtwm*ws1*title:  Don
    Dtwm*ws2*title   Julia
    Dtwm*ws3*title   Patti

### To Create Additional Backdrops

1. Create the backdrop images. They can be bitmap or pixmap files.

2. Place the backdrops in one of the following directories. (You may have to create the directory.)

   - System-wide backdrops: `/etc/dt/backdrops`

   - Personal backdrops: HomeDirectory`/.dt/backdrops`

3. Choose Restart Workspace Manager from the Workspace menu.

The system-wide and personal backdrops are added to the built-in backdrops in `/usr/dt/backdrops`.

You can replace an existing built-in backdrop by creating a personal or system- wide backdrop with the same name.

### To Replace the Backdrop With a Graphics Image

The backdrops are layered over the display's
root window. The Style Manager Backdrop dialog box provides a
NoBackdrop setting in which the backdrop is transparent.

There is only one root window behind all the workspace backdrops. Thus, a graphics image placed on the root window persists across all workspaces. You can specify which workspaces cover up the root window with a backdrop. However, the image visible when NoBackdrop is in effect will be the same for every workspace.

1. Create the graphics image. It must be in a format for which a tool exists to display the image on the root window. For example, if you intend to use `xsetroot`, you must create a bitmap file.

2. If it doesn't already exist, create an executable file HomeDirectory`/.dt/sessions/sessionetc.` The `sessionetc` file is run each time the user logs in.

3. Place the command to display the image in the `sessionetc` file.

   For example, the following command tiles the root window with the specified bitmap:

       xsetroot -bitmap /users/ellen/.dt/icons/root.bm

## Workspace Manager Menus

Workspace Manager has three default menus:

Workspace menu | Also called the root menu. Displayed when the user presses mouse button 3 when the pointer is on the backdrop. The menu is associated with the mouse button through a button binding.
Window menu | The menu displayed when the user presses mouse buttons 1 or 3 when the pointer is on the Window menu button (upper left corner of the window frame). The menu is associated with the button by the `windowMenu` resource.
Front Panel menu | The menu displayed when the user presses mouse buttons 1 or 3 when the pointer is over the Front Panel's Window menu button.

### Workspace Manager Menu Syntax

Workspace Manager menus have the syntax:

    Menu MenuName
    {
        selection1 [mnemonic] [accelerator] function [argument]
        selection2 [mnemonic] [accelerator] function [argument]
        …
    }

where:

selection | The text or bitmap that appears on the menu. If the text includes spaces, enclose the text in quotation marks. For bitmaps, use the syntax @/path.
mnemonic | A single character that acts as a keyboard shortcut when the menu is displayed. It is specified in the form `_`character.
accelerator | A keyboard shortcut that is active whether or not the menu is displayed. Accelerators have the syntax modifier`<Key>` Keyname where modifier is `Ctrl`, `Shift`, `Alt` (Extend char), or `Lock`. For a list of all possible key names, refer to the `keysymdef.h` file in your “X11 include” directory.
function | The function to be performed when this selection is made. Refer to the `dtwmrc(4)` man page for a list of functions.
argument | Function arguments. Refer to the `dtwmrc(4)` man page for more details.

For example, the following menu item labeled Restore normalizes the window. When the menu is displayed, typing “R” will also restore the window. Pressing Extend char F5 will also restore the window.

    Restore    _R    Alt<Key> F5    f.normalize

For complete information on Workspace Manager menu syntax, see the `dtwmrc(4)` man page.

### To Modify the Existing Workspace (Root) Menu

1. Open the appropriate file for editing:

   - Personal: HomeDirectory`/.dt/dtwmrc`

   - System-wide: `/etc/dt/config/`language`/sys.dtwmrc`

   For information on creating these files, see SAG.WMCnf.mkr.2.

2. Edit the description of the Workspace menu.

   The default Workspace menu is named
   DtRootMenu.

       Menu DtRootMenu
       {
           “Workspace Menu”   f.title
           “Shuffle Up”       f.circle_up
           “Shuffle Down”     f.circle_down
           …
       }

### To Create a New Workspace (Root) Menu

1. Open the appropriate file for editing:

   - Personal: HomeDirectory`/.dt/dtwmrc`

   - System-wide: `/etc/dt/config/`language`/sys.dtwmrc`

   For information on creating these files, see SAG.WMCnf.mkr.2.

2. Create the new menu:

       Menu menu_name
       {
               …
       }

   See SAG.WMCnf.mkr.9.

3. Create or edit the button binding to display the new menu.

   If the menu replaces the existing menu, edit the button binding that displays the Workspace menu.

       <Btn3Down> root f.menu  menu_name

   If the menu is an additional menu, create a new mouse button binding. For example, the following button binding displays the menu when Shift-mouse button 3 is pressed over the backdrop:

       Shift<Btn3Down> root f.menu  menu_name

4. Choose Restart Workspace Manager from the Workspace menu.

### To Create a New Window Menu

The Window menu is built into the Workspace Manager, and ordinarily is not customized. To keep window behavior consistent between applications, you should avoid extensive modification to the Window menu.

1. Open the appropriate file for editing:

   - Personal: HomeDirectory`/.dt/dtwmrc`

   - System-wide: `/etc/dt/config/`language`/sys.dtwmrc`

   For information on creating these files, see SAG.WMCnf.mkr.2.

2. Create the new menu:

       Menu menu_name
       {
               …
       }

3. Use the `windowMenu` resource to specify the new menu:

       Dtwm*windowMenu: menu_name

4. Choose Restart Workspace Manager from the Workspace menu.

## Customizing Button Bindings

A button binding associates a mouse button operation and possible keyboard modifier key with a window manager function. Button bindings apply to all workspaces.

The desktop default button bindings are defined in the Workspace Manager configuration file in a button binding set named `
DtButtonBindings`:

    Buttons DtButtonBindings
    {
      …
    }

### Button Binding Syntax

The syntax for button bindings is:

    Buttons ButtonBindingSetName
    {
        [modifier]<button_nameMouse_action> context  function [argument]
        [modifier]<button_nameMouse_action> context  function [argument]

where:

button_name | `Btn1—`Left mouse button `Btn2—`Middle button (3-button mouse) or both buttons (2-button mouse) `Btn3—`Right button `Btn4—`Buttons 1 and 2 together on a 3-button mouse `Btn5—`Buttons 2 and 3 together on a 3-button mouse
modifier | `Ctrl,` `Shift,` `Alt,` `Lock`
mouse_action | `Down`—Holding down a mouse button `Up`—Releasing a mouse button `Click`—Pressing and releasing a mouse button `Click2`—Double-clicking a mouse button `Drag`—Dragging the mouse while holding down the mouse button
context | Indicates where the pointer must be for the binding to be effective. If necessary, separate multiple contents with the “`|`” character. `root`—The workspace window `window`—Client window or window frame `frame—`Window frame, excluding the contents `icon—`Icon `title—`Title bar `app—`Client window (excluding the frame)
function | One of the window manager functions. Refer to the `dtwmrc(4)` man page for a list of valid functions.
argument | Any window manager function arguments that are required. Refer to the `dtwmrc(4)` man page for details.

For example, the following line causes the menu described in `DtRootMenu` to be displayed when mouse button 3 is pressed while the pointer is in the workspace window (but not within client windows).

    <Btn3Down>     root    f.menu    DtRootMenu

For complete information on button binding syntax, see the `dtwmrc(4)` man page.

### To Add a Button Binding

1. Open the appropriate file for editing:

   - Personal: HomeDirectory`/.dt/dtwmrc`

   - System-wide: `/etc/dt/config/`language`/sys.dtwmrc`

   For information on creating these files, see SAG.WMCnf.mkr.2.

2. Add the button binding to the `DtButtonBindings` definition.

   Do not bind the same button to different functions for the click and press operations, and do not bind more than one function to the same button and context.

3. Choose Restart Workspace Manager from the Workspace menu.

### To Create a New Button Binding Set

1. Open the appropriate file for editing:

   - Personal: HomeDirectory`/.dt/dtwmrc`

   - System-wide: `/etc/dt/config/`language`/sys.dtwmrc`

   For information on creating these files, see SAG.WMCnf.mkr.2.

2. Create the new button binding set. See SAG.WMCnf.mkr.13.

3. Set the `
   buttonBindings` resource to the new name:

       Dtwm*buttonBindings: ButtonBindingsSetName

4. Choose Restart Workspace Manager from the Workspace menu.

The new button bindings replace your existing button bindings. Copy any button bindings you want to keep from `DtButtonBindings`.

## Customizing Key Bindings

A keyboard binding, also known as a key binding, associates combination of keys with Workspace Manager functions. Key bindings apply to all workspaces.

Be careful about using a common key combination as a keyboard binding. For example, Shift-A normally puts the letter “A” into your current window. If you bind Shift-A to a function, you lose its normal usage.

### Default Desktop Key Bindings

The desktop default key bindings are defined in the Workspace Manager configuration file in a key binding set named `DtKeyBindings`:

    Keys DtKeyBindings
    {
     …
    }

### Key Binding Syntax

The syntax for key bindings is:

    Keys KeyBindingSetName
    {
        [Modifiers]<Key>key_name   context   function [argument]
        [Modifiers]<Key>key_name   context   function [argument]
       …
    }

where:

Modifiers | `Ctrl`, `Shift`. `Alt`, and `Lock`. Multiple modifiers are allowed; separate them with spaces.
key_name | The key to which the function is mapped. For keys with letters or numbers, the key_name name is usually printed on the key. For instance the name of the “a” key is “a”, and the “2” key is named “2”. The “Tab” key is named “Tab”. The “F3” key is named “F3”.

For other keys, the name is spelled out—for example, `plus` for the “+” key. The file `keysymdef.h`, located in a system-dependent directory, contains additional information about key names.

context | The element that must have the keyboard focus for this action to be effective. These can be concatenated together if the binding applies to more than one context. Multiple contexts are separated by the “`|`” character. `root—`Workspace backdrop `window—`Client window `icon—`Icon
function | A window manager function. Refer to the `dtwmrc(4)` man page for a list of valid functions.
argument | Any window manager function arguments that are required. Refer to the `dtwmrc(4)` man page for details.

For example, the following key binding lets the user to switch the keyboard focus to the next transient window in an application by pressing Alt+F6.

    Alt<Key>F6    window    f.next_key    transient

For complete information on key binding syntax, see the `dtwmrc(4)` man page.

### To Create a Custom Key Binding Set

1. Open the appropriate file for editing:

   - Personal: HomeDirectory`/.dt/dtwmrc`

   - System-wide: `/etc/dt/config/`language`/sys.dtwmrc`

     For information on creating these files, see SAG.WMCnf.mkr.2.

2. Create a new key binding set with a unique KeyBindingSetName. Use the desktop default key binding set, `DtKeyBindings`, as a guide.

3. Set the `
   keyBindings` resource to the new set name:

       Dtwm*keyBindings: KeyBindingSetName

4. Choose Restart Workspace Manager from the Workspace menu.

The new key bindings replace your existing key bindings. Copy any key bindings you want to keep from `DtKeyBindings` into your new set.

## Switching Between Default and Custom Behavior

To toggle between Motif default and CDE desktop window behavior:

1. Press Alt+Shift+Ctrl+!

2. Click OK in the dialog box.

Switching to default behavior removes the Front Panel and any custom key and button bindings.