xmonad-contrib-0.17.1: Community-maintained 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 | Safe-Inferred
Language | Haskell2010

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 ()
- changeProjectDirPrompt :: XPConfig -> X ()
- switchProject :: Project -> X ()
- shiftToProject :: Project -> X ()
- lookupProject :: ProjectName -> X (Maybe Project)
- currentProject :: X Project
- activateProject :: Project -> X ()
- modifyProject :: (Project -> 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 def)
     , ((modm, xK_slash), shiftToProjectPrompt def)

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.

changeProjectDirPrompt :: XPConfig -> X () #

Change the working directory used for the current project.

NOTE: This will only affect new processed started in this project. Existing processes will maintain the previous working directory.

# 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.

modifyProject :: (Project -> Project) -> X () #

Modify the current project using a pure function.