Chapter 9. Configuring the menus

Table of Contents
9.1. Basic Menu Syntax
9.2. Menu Keywords
9.3. Custom Menus
9.4. Dynamic Menus

The root menu is what you get when you (by default- See the Mouse Bindings section) left-click on the root window (also called the desktop). You can also configure the window menu, which you get when you right-click on a window title.

9.1. Basic Menu Syntax

As previously indicated, the root and window menus follow the rules defined in Common Syntax. There aren't many possible options, and they're all either within the main menu, or within a submenu. This is all handled by a single file.

As addition to the default menu types, RootMenu and WindowMenu, user can define any number of new menus following the same syntax.

Here's an example ~/.pekwm/menu file, where we have the usual RootMenu and WindowMenu and our own most used applications menu called MyOwnMenuName:

# Menu config for pekwm

# Variables
$TERM = "xterm -fn fixed +sb -bg black -fg white"

RootMenu = "Pekwm" {
    Entry = "Term" { Actions = "Exec $TERM &" }
    Entry = "Emacs" { Icon = "emacs.png"; Actions = "Exec $TERM -title emacs -e emacs -nw &" }
    Entry = "Vim" { Actions = "Exec $TERM -title vim -e vi &" }

    Separator {}

    Submenu = "Utils" {
        Entry = "XCalc" { Actions = "Exec xcalc &" }
        Entry = "XMan" { Actions = "Exec xman &" }
    }

    Separator {}

    Submenu = "Pekwm" {
        Entry = "Reload" { Actions = "Reload" }
        Entry = "Restart" { Actions = "Restart" }
        Entry = "Exit" { Actions = "Exit" }
        Submenu = "Others" {
            Entry = "Xterm" { Actions = "RestartOther xterm" }
            Entry = "Twm" { Actions = "RestartOther twm" }
        }
        Submenu = "Themes" {
            Entry { Actions = "Dynamic ~/.pekwm/scripts/pekwm_themeset.pl" }
        }
    }
}

WindowMenu = "Window Menu" {
    Entry = "(Un)Stick" { Actions = "Toggle Sticky" }
    Entry = "(Un)Shade" { Actions = "Toggle Shaded" }

    ...

    SubMenu = "Send To" {
        Entry = "Workspace 1" { Actions = "SendToWorkspace 1" }
        Entry = "Workspace 2" { Actions = "SendToWorkspace 2" }
        Entry = "Workspace 3" { Actions = "SendToWorkspace 3" }
        Entry = "Workspace 4" { Actions = "SendToWorkspace 4; GoToWorkspace 4" }
    }
    
    ...

    Entry = "Close" { Actions = "Close" }
}

MyOwnMenuName = "Most used apps" {
	Entry = "Term" { Actions = "Exec $TERM &" }
	Entry = "XCalc" { Actions = "Exec xcalc &" }
	Entry = "Dillo" { Actions = "Exec dillo &" }
}

9.2. Menu Keywords

Here are the different elements that can be used in your root menu file.

Root Menu Elements:

Submenu (Name)

Begins a submenu. 'name' is what will appear in the root menu for the entry.

Entry (Name)

Begins a menu entry. 'Name' is the text shown in the menu for this entry.

Actions (Action)

Run an action. 'Action' is the action(s) to run. Most actions listed in Keys/mouse actions will also work from the root and window menus.

Icon (Image)

Set icon left of entry from image in icon path.

Separator

Adds a separator to the menu.

Menu Actions:

Exec

Exec makes pekwm to execute the command that follows it. Make sure the program gets backgrounded. Put an '&' at the end of the action if it doesn't do this on it's own.

Reload

When this is called, pekwm will re-read all configuration files without exiting.

Restart

This will cause pekwm to exit and re-start completely.

RestartOther

Quits pekwm and starts another application. The application to run is given as a parameter.

Exit

Exits pekwm. Under a normal X setup, This will end your X session.

Of course, in addition to these, many actions found from Keys/mouse actions also work.

9.3. Custom Menus

User can also define an unlimited amount of custom menus. They are called with the ShowMenu action much like the Root and Window menus are (see Keys/mouse actions).

In the example menu on this documentation, we created your own menu, called 'MyOwnMenuName'. Basically, outside of the RootMenu and WindowMenu sections, we open our own section called 'MyOwnMenuName'. This can of course be called whatever you want it to be called, but do note that the menu names are case insensitive. This means you can't have one menu called 'MyMostUsedApps' and one called 'mymostusedapps'.

Lets see that example again, simplified:

RootMenu = "Pekwm" { ... }
WindowMenu = "Window Menu" { ... }
MyOwnMenuName = "Most used apps" {
	Entry = "Term" { Actions = "Exec $TERM &" }
	Entry = "XCalc" { Actions = "Exec xcalc &" }
	Entry = "Dillo" { Actions = "Exec dillo &" }
}

We would call this new menu using the action 'ShowMenu MyOwnMenuName', The menu would show 'Most used apps' as the menu title and list 'Term', 'XCalc' and 'Dillo' in the menu ready to be executed.

9.4. Dynamic Menus

It is possible to use dynamic menus in pekwm, that is menus that regenerate themselves whenever the menu is viewed. This is done with the Dynamic keyword.

To use this feature, you need to put a dynamic entry in the ~/.pekwm/menu file with a parameter that tells pekwm what file to execute to get the menu. This file can be of any language you prefer, the main thing is that it outputs valid pekwm menu syntax inside a Dynamic {} section. The syntax of dynamic entry looks like this:

Entry = "" { Actions = "Dynamic /path/to/filename" }

The input from a program that creates the dynamic content should follow the general menu syntax encapsulated inside a Dynamic {} section. Variables have to be included inside the dynamic menu for them to work. A simple script to give pekwm dynamic menu content would look like this:

#!/bin/bash
output=$RANDOM # gets a random number

echo "Dynamic {"
echo " Entry = \"$output\" { Actions = \"Exec xmessage $output\" }"
echo "}"

This script would output something like:

Dynamic {
 Entry = "31549" { Actions = "Exec xmessage 31549" }
}

Clients can access the PID and Window that was active when the script was executed via the environment variables $CLIENT_PID and $CLIENT_WINDOW. $CLIENT_PID is only available if the client is being run on the same host as pekwm.