XMonad.Prompt

A module for writing graphical prompts for XMonad

Usage

For usage examples see XMonad.Prompt.Shell, XMonad.Prompt.XMonad or XMonad.Prompt.Ssh

TODO:

• scrolling the completions that don't fit in the window (?)

mkXPrompt :: XPrompt p => p -> XPConfig -> ComplFunction -> (String -> X ()) -> X ()

Creates a prompt given:

• a prompt type, instance of the XPrompt class.
• a prompt configuration (def can be used as a starting point)
• a completion function (mkComplFunFromList can be used to create a completions function given a list of possible completions)
• an action to be run: the action must take a string and return X ()

mkXPromptWithReturn :: XPrompt p => p -> XPConfig -> ComplFunction -> (String -> X a) -> X (Maybe a)

Same as mkXPrompt, except that the action function can have type String -> X a, for any a, and the final action returned by mkXPromptWithReturn will have type X (Maybe a). Nothing is yielded if the user cancels the prompt (by e.g. hitting Esc or Ctrl-G). For an example of use, see the Input module.

mkXPromptWithModes :: [XPType] -> XPConfig -> X ()

Creates a prompt with multiple modes given:

• A non-empty list of modes
• A prompt configuration

The created prompt allows to switch between modes with changeModeKey in conf. The modes are instances of XPrompt. See XMonad.Actions.Launcher for more details

The argument supplied to the action to execute is always the current highlighted item, that means that this prompt overrides the value alwaysHighlight for its configuration to True.

def :: Default a => a

The default value for this type.

amberXPConfig :: XPConfig

defaultXPConfig :: XPConfig

Deprecated: Use def (from Data.Default, and re-exported from XMonad.Prompt) instead.

greenXPConfig :: XPConfig

type XPMode = XPType

data XPType

Constructors

forall p . XPrompt p => XPT p

Instances

Show XPType

XPrompt XPType

data XPPosition

Constructors

Top

Bottom

Instances

Read XPPosition

Show XPPosition

data XPConfig

Constructors

XPC

Fields

font :: String

Font

bgColor :: String

Background color

fgColor :: String

Font color

fgHLight :: String

Font color of a highlighted completion entry

bgHLight :: String

Background color of a highlighted completion entry

borderColor :: String

Border color

promptBorderWidth :: !Dimension

Border width

position :: XPPosition

Position: Top or Bottom

alwaysHighlight :: !Bool

Always highlight an item, overriden to True with multiple modes. This implies having *one* column of autocompletions only.

height :: !Dimension

Window height

maxComplRows :: Maybe Dimension

Just x: maximum number of rows to show in completion window

historySize :: !Int

The number of history entries to be saved

historyFilter :: [String] -> [String]

a filter to determine which history entries to remember

promptKeymap :: Map (KeyMask, KeySym) (XP ())

Mapping from key combinations to actions

completionKey :: KeySym

Key that should trigger completion

changeModeKey :: KeySym

Key to change mode (when the prompt has multiple modes)

defaultText :: String

The text by default in the prompt line

autoComplete :: Maybe Int

Just x: if only one completion remains, auto-select it,

showCompletionOnTab :: Bool

Only show list of completions when Tab was pressed and delay by x microseconds

searchPredicate :: String -> String -> Bool

Given the typed string and a possible completion, is the completion valid?

Instances

Default XPConfig

class XPrompt t where

The class prompt types must be an instance of. In order to create a prompt you need to create a data type, without parameters, and make it an instance of this class, by implementing a simple method, showXPrompt, which will be used to print the string to be displayed in the command line window.

This is an example of a XPrompt instance definition:

    instance XPrompt Shell where
         showXPrompt Shell = "Run: "

Minimal complete definition

showXPrompt

Methods

showXPrompt :: t -> String

This method is used to print the string to be displayed in the command line window.

nextCompletion :: t -> String -> [String] -> String

This method is used to generate the next completion to be printed in the command line when tab is pressed, given the string presently in the command line and the list of completion. This function is not used when in multiple modes (because alwaysHighlight in XPConfig is True)

commandToComplete :: t -> String -> String

This method is used to generate the string to be passed to the completion function.

completionToCommand :: t -> String -> String

This method is used to process each completion in order to generate the string that will be compared with the command presently displayed in the command line. If the prompt is using getNextOfLastWord for implementing nextCompletion (the default implementation), this method is also used to generate, from the returned completion, the string that will form the next command line when tab is pressed.

completionFunction :: t -> ComplFunction

When the prompt has multiple modes, this is the function used to generate the autocompletion list. The argument passed to this function is given by commandToComplete The default implementation shows an error message.

modeAction :: t -> String -> String -> X ()

When the prompt has multiple modes (created with mkXPromptWithModes), this function is called when the user picks an item from the autocompletion list. The first argument is the prompt (or mode) on which the item was picked The first string argument is the autocompleted item's text. The second string argument is the query made by the user (written in the prompt's buffer). See XMonadActionsLauncher.hs for a usage example.

Instances

XPrompt XPType

XPrompt Wor

XPrompt WSGPrompt

XPrompt Dir

XPrompt Shell

XPrompt Search

XPrompt TagPrompt

XPrompt Ssh

XPrompt ThemePrompt

XPrompt AppendFile

XPrompt AppPrompt

XPrompt EnterPrompt

XPrompt DirExec

XPrompt InputPrompt

XPrompt Man

XPrompt RunOrRaisePrompt

XPrompt WindowPrompt

XPrompt XMonad

type XP = StateT XPState IO

defaultXPKeymap :: Map (KeyMask, KeySym) (XP ())

Default key bindings for prompts. Click on the "Source" link to the right to see the complete list. See also defaultXPKeymap'.

defaultXPKeymap' :: (Char -> Bool) -> Map (KeyMask, KeySym) (XP ())

A variant of defaultXPKeymap which lets you specify a custom predicate for identifying non-word characters, which affects all the word-oriented commands (move/kill word). The default is isSpace. For example, by default a path like foo/bar/baz would be considered as a single word. You could use a predicate like (\c -> isSpace c || c == '/') to move through or delete components of the path one at a time.

emacsLikeXPKeymap :: Map (KeyMask, KeySym) (XP ())

A keymap with many emacs-like key bindings. Click on the "Source" link to the right to see the complete list. See also emacsLikeXPKeymap'.

emacsLikeXPKeymap' :: (Char -> Bool) -> Map (KeyMask, KeySym) (XP ())

A variant of emacsLikeXPKeymap which lets you specify a custom predicate for identifying non-word characters, which affects all the word-oriented commands (move/kill word). The default is isSpace. For example, by default a path like foo/bar/baz would be considered as a single word. You could use a predicate like (\c -> isSpace c || c == '/') to move through or delete components of the path one at a time.

quit :: XP ()

Quit.

killBefore :: XP ()

Kill the portion of the command before the cursor

killAfter :: XP ()

Kill the portion of the command including and after the cursor

startOfLine :: XP ()

Put the cursor at the start of line

endOfLine :: XP ()

Put the cursor at the end of line

pasteString :: XP ()

Insert the current X selection string at the cursor position.

moveCursor :: Direction1D -> XP ()

move the cursor one position

setInput :: String -> XP ()

Sets the input string to the given value.

getInput :: XP String

Returns the current input string. Intented for use in custom keymaps where the get or similar can't be used to retrieve it.

moveWord :: Direction1D -> XP ()

Move the cursor one word, using isSpace as the default predicate for non-word characters. See moveWord'.

moveWord' :: (Char -> Bool) -> Direction1D -> XP ()

Move the cursor one word, given a predicate to identify non-word characters. First move past any consecutive non-word characters; then move to just before the next non-word character.

killWord :: Direction1D -> XP ()

Kill the next/previous word, using isSpace as the default predicate for non-word characters. See killWord'.

killWord' :: (Char -> Bool) -> Direction1D -> XP ()

Kill the next/previous word, given a predicate to identify non-word characters. First delete any consecutive non-word characters; then delete consecutive word characters, stopping just before the next non-word character.

For example, by default (using killWord) a path like foo/bar/baz would be deleted in its entirety. Instead you can use something like killWord' (\c -> isSpace c || c == '/') to delete the path one component at a time.

deleteString :: Direction1D -> XP ()

Remove a character at the cursor position

moveHistory :: (Stack String -> Stack String) -> XP ()

setSuccess :: Bool -> XP ()

setDone :: Bool -> XP ()

data Direction1D

One-dimensional directions:

Constructors

Next

Prev

Instances

Eq Direction1D

Read Direction1D

Show Direction1D

type ComplFunction = String -> IO [String]

X Utilities

mkUnmanagedWindow :: Display -> Screen -> Window -> Position -> Position -> Dimension -> Dimension -> IO Window

Creates a window with the attribute override_redirect set to True. Windows Managers should not touch this kind of windows.

fillDrawable :: Display -> Drawable -> GC -> Pixel -> Pixel -> Dimension -> Dimension -> Dimension -> IO ()

Fills a Drawable with a rectangle and a border

Other Utilities

mkComplFunFromList :: [String] -> String -> IO [String]

This function takes a list of possible completions and returns a completions function to be used with mkXPrompt

mkComplFunFromList' :: [String] -> String -> IO [String]

This function takes a list of possible completions and returns a completions function to be used with mkXPrompt. If the string is null it will return all completions.

nextCompletion implementations

getNextOfLastWord :: XPrompt t => t -> String -> [String] -> String

Given the prompt type, the command line and the completion list, return the next completion in the list for the last word of the command line. This is the default nextCompletion implementation.

getNextCompletion :: String -> [String] -> String

An alternative nextCompletion implementation: given a command and a completion list, get the next completion in the list matching the whole command line.

List utilities

getLastWord :: String -> String

Gets the last word of a string or the whole string if formed by only one word

skipLastWord :: String -> String

Skips the last word of the string, if the string is composed by more then one word. Otherwise returns the string.

splitInSubListsAt :: Int -> [a] -> [[a]]

Given a maximum length, splits a list into sublists

breakAtSpace :: String -> (String, String)

uniqSort :: Ord a => [a] -> [a]

Sort a list and remove duplicates. Like deleteAllDuplicates, but trades off laziness and stability for efficiency.

historyCompletion :: ComplFunction

historyCompletion provides a canned completion function much like getShellCompl; you pass it to mkXPrompt, and it will make completions work from the query history stored in ~/.xmonad/history.

historyCompletionP :: (String -> Bool) -> ComplFunction

Like historyCompletion but only uses history data from Prompts whose name satisfies the given predicate.

History filters

deleteAllDuplicates :: [String] -> [String]

Functions to be used with the historyFilter setting. deleteAllDuplicates will remove all duplicate entries. deleteConsecutive will only remove duplicate elements immediately next to each other.

deleteConsecutive :: [String] -> [String]

Functions to be used with the historyFilter setting. deleteAllDuplicates will remove all duplicate entries. deleteConsecutive will only remove duplicate elements immediately next to each other.

data HistoryMatches

initMatches :: (Functor m, MonadIO m) => m HistoryMatches

Initializes a new HistoryMatches structure to be passed to historyUpMatching

historyUpMatching :: HistoryMatches -> XP ()

Retrieve the next history element that starts with the current input. Pass it the result of initMatches when creating the prompt. Example:

..
((modMask,xK_p), shellPrompt . myPrompt =<< initMatches)
..
myPrompt ref = def
  { promptKeymap = M.union [((0,xK_Up), historyUpMatching ref)
                           ,((0,xK_Down), historyDownMatching ref)]
                           (promptKeymap def)
  , .. }

historyDownMatching :: HistoryMatches -> XP ()

Retrieve the next history element that starts with the current input. Pass it the result of initMatches when creating the prompt. Example:

..
((modMask,xK_p), shellPrompt . myPrompt =<< initMatches)
..
myPrompt ref = def
  { promptKeymap = M.union [((0,xK_Up), historyUpMatching ref)
                           ,((0,xK_Down), historyDownMatching ref)]
                           (promptKeymap def)
  , .. }

Types

data XPState