xmonad-contrib-0.10: Third party extensions for xmonad

Portability | unportable
Stability | stable
Maintainer | <byorgey@gmail.com>

XMonad.Prompt.Input

Contents

- Usage

Description

A generic framework for prompting the user for input and passing it along to some other action.

Synopsis

- inputPrompt :: XPConfig -> String -> X (Maybe String)
- inputPromptWithCompl :: XPConfig -> String -> ComplFunction -> X (Maybe String)
- (?+) :: Monad m => m (Maybe a) -> (a -> m ()) -> m ()
- data InputPrompt

# Usage

To use this module, import it along with XMonad.Prompt:

     import XMonad.Prompt
     import XMonad.Prompt.Input

This module provides no useful functionality in isolation, but is intended for use in building other actions which require user input.

For example, suppose Mr. Big wants a way to easily fire his employees. We'll assume that he already has a function

     fireEmployee :: String -> X ()

which takes as input the name of an employee, and fires them. He just wants a convenient way to provide the input for this function from within xmonad. Here is where the XMonad.Prompt.Input module comes into play. He can use the `inputPrompt` function to create a prompt, and the `?+` operator to compose the prompt with the `fireEmployee` action, like so:

     firingPrompt :: X ()
     firingPrompt = inputPrompt defaultXPConfig \"Fire\" ?+ fireEmployee

If `employees` contains a list of all his employees, he could also create an autocompleting version, like this:

     firingPrompt' = inputPromptWithCompl defaultXPConfig \"Fire\"
                         (mkComplFunFromList employees) ?+ fireEmployee

Now all he has to do is add a keybinding to `firingPrompt` (or `firingPrompt'`), such as

      , ((modm .|. controlMask, xK_f),  firingPrompt)

Now when Mr. Big hits mod-ctrl-f, a prompt will pop up saying "Fire: ", waiting for him to type the name of someone to fire. If he thinks better of it after hitting mod-ctrl-f and cancels the prompt (e.g. by hitting Esc), the `fireEmployee` action will not be invoked.

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

XMonad.Prompt.Input is also intended to ease the process of developing other modules which require user input. For an example of a module developed using this functionality, see XMonad.Prompt.Email, which prompts the user for a recipient, subject, and one-line body, and sends a quick email.

inputPrompt :: XPConfig -> String -> X (Maybe String)

Given a prompt configuration and some prompt text, create an X action which pops up a prompt waiting for user input, and returns whatever they type. Note that the type of the action is `X (Maybe String)`, which reflects the fact that the user might cancel the prompt (resulting in `Nothing`), or enter an input string `s` (resulting in `Just s`).

inputPromptWithCompl :: XPConfig -> String -> ComplFunction -> X (Maybe String)

The same as `inputPrompt`, but with a completion function. The type `ComplFunction` is `String -> IO [String]`, as defined in XMonad.Prompt. The `mkComplFunFromList` utility function, also defined in XMonad.Prompt, is useful for creating such a function from a known list of possibilities.

(?+) :: Monad m => m (Maybe a) -> (a -> m ()) -> m ()

A combinator for hooking up an input prompt action to a function which can take the result of the input prompt and produce another action. If the user cancels the input prompt, the second function will not be run.

The astute student of types will note that this is actually a very general combinator and has nothing in particular to do with input prompts. If you find a more general use for it and want to move it to a different module, be my guest.

data InputPrompt

Instances

XPrompt InputPrompt |