XMonad.Actions.DynamicProjects

xmonad-contrib-0.12: Third party extensions for xmonad

Copyright | (c) Peter J. Jones
License | BSD3-style (see LICENSE)
Maintainer | Peter Jones <pjones@devalot.com>
Stability | unstable
Portability | not portable
Safe Haskell | None
Language | Haskell98

XMonad.Actions.DynamicProjects

Contents

- Overview
- Usage
- Types
- Hooks
- Bindings
- Helper Functions

Description

Imbues workspaces with additional features so they can be treated as individual project areas.

Synopsis

- data Project = Project {
  - projectName :: !ProjectName
  - projectDirectory :: !FilePath
  - projectStartHook :: !(Maybe (X ()))
  }
- type ProjectName = String
- dynamicProjects :: [Project] -> XConfig a -> XConfig a
- switchProjectPrompt :: XPConfig -> X ()
- shiftToProjectPrompt :: XPConfig -> X ()
- renameProjectPrompt :: XPConfig -> X ()
- switchProject :: Project -> X ()
- shiftToProject :: Project -> X ()
- lookupProject :: ProjectName -> X (Maybe Project)
- currentProject :: X Project
- activateProject :: Project -> X ()

# Overview

Inspired by `TopicSpace`, `DynamicWorkspaces`, and `WorkspaceDir`, `DynamicProjects` treats workspaces as projects while maintaining compatibility with all existing workspace-related functionality in XMonad.

Instead of using generic workspace names such as `3` or `work`, `DynamicProjects` allows you to dedicate workspaces to specific projects and then switch between projects easily.

A project is made up of a name, working directory, and a start-up hook. When you switch to a workspace, `DynamicProjects` changes the working directory to the one configured for the matching project. If the workspace doesn't have any windows, the project's start-up hook is executed. This allows you to launch applications or further configure the workspace/project.

When using the `switchProjectPrompt` function, workspaces are created as needed. This means you can create new project spaces (and therefore workspaces) on the fly. (These dynamic projects are not preserved across restarts.)

Additionally, frequently used projects can be configured statically in your XMonad configuration. Doing so allows you to configure the per-project start-up hook.

# Usage

To use `DynamicProjects` you need to add it to your XMonad configuration and then configure some optional key bindings.

    import XMonad.Actions.DynamicProjects

Start by defining some projects:

    projects :: [Project]
    projects =
      [ Project { projectName      = "scratch"
                , projectDirectory = "~/"
                , projectStartHook = Nothing
                }

      , Project { projectName      = "browser"
                , projectDirectory = "~/download"
                , projectStartHook = Just $ do spawn "conkeror"
                                               spawn "chromium"
                }
      ]

Then inject `DynamicProjects` into your XMonad configuration:

    main = xmonad $ dynamicProjects projects def

And finally, configure some optional key bindings:

     , ((modm, xK_space), switchProjectPrompt)
     , ((modm, xK_slash), shiftToProjectPrompt)

For detailed instructions on editing your key bindings, see XMonad.Doc.Extending.

# Types

data Project

Details about a workspace that represents a project.

Constructors

Project |
Fields projectName :: !ProjectName Workspace name. projectDirectory :: !FilePath Working directory. projectStartHook :: !(Maybe (X ())) Optional start-up hook.

type ProjectName = String

# Hooks

dynamicProjects :: [Project] -> XConfig a -> XConfig a

Add dynamic projects support to the given config.

# Bindings

switchProjectPrompt :: XPConfig -> X ()

Prompt for a project name and then switch to it. Automatically creates a project if a new name is returned from the prompt.

shiftToProjectPrompt :: XPConfig -> X ()

Prompts for a project name and then shifts the currently focused window to that project.

renameProjectPrompt :: XPConfig -> X ()

Rename the current project.

# Helper Functions

switchProject :: Project -> X ()

Switch to the given project.

shiftToProject :: Project -> X ()

Shift the currently focused window to the given project.

lookupProject :: ProjectName -> X (Maybe Project)

Find a project based on its name.

currentProject :: X Project

Fetch the current project (the one being used for the currently active workspace).

activateProject :: Project -> X ()

Activate a project by updating the working directory and possibly running its start-up hook. This function is automatically invoked when the workspace changes.