xmonad-contrib-0.17.1: Community-maintained extensions for xmonad

Copyright | (c) -- Quentin Moser <moserq@gmail.com> 2018 Yclept Nemo
License | BSD3
Maintainer | orphaned
Stability | unstable
Portability | unportable
Safe Haskell | Safe-Inferred
Language | Haskell2010

XMonad.Actions.MessageFeedback

Contents

- Usage
- Messaging variants
  - `SomeMessage`
  - `Message`
- Utility Functions
  - Send All
  - Send Until
  - Aliases
- Backwards Compatibility

Description

Alternative to `sendMessage` that provides knowledge of whether the message was handled, and utility functions based on this facility.

Synopsis

- sendSomeMessageB :: SomeMessage -> X Bool
- sendSomeMessage :: SomeMessage -> X ()
- sendSomeMessageWithNoRefreshB :: SomeMessage -> Workspace WorkspaceId (Layout Window) Window -> X Bool
- sendSomeMessageWithNoRefresh :: SomeMessage -> Workspace WorkspaceId (Layout Window) Window -> X ()
- sendSomeMessageWithNoRefreshToCurrentB :: SomeMessage -> X Bool
- sendSomeMessageWithNoRefreshToCurrent :: SomeMessage -> X ()
- sendMessageB :: Message a => a -> X Bool
- sendMessageWithNoRefreshB :: Message a => a -> Workspace WorkspaceId (Layout Window) Window -> X Bool
- sendMessageWithNoRefreshToCurrentB :: Message a => a -> X Bool
- sendMessageWithNoRefreshToCurrent :: Message a => a -> X ()
- sendSomeMessagesB :: [SomeMessage] -> X [Bool]
- sendSomeMessages :: [SomeMessage] -> X ()
- sendMessagesB :: Message a => [a] -> X [Bool]
- sendMessages :: Message a => [a] -> X ()
- tryInOrderB :: (SomeMessage -> X Bool) -> [SomeMessage] -> X Bool
- tryInOrderWithNoRefreshToCurrentB :: [SomeMessage] -> X Bool
- tryInOrderWithNoRefreshToCurrent :: [SomeMessage] -> X ()
- tryMessageB :: (Message a, Message b) => (SomeMessage -> X Bool) -> a -> b -> X Bool
- tryMessageWithNoRefreshToCurrentB :: (Message a, Message b) => a -> b -> X Bool
- tryMessageWithNoRefreshToCurrent :: (Message a, Message b) => a -> b -> X ()
- sm :: Message a => a -> SomeMessage
- send :: Message a => a -> X Bool
- sendSM :: SomeMessage -> X Bool
- sendSM_ :: SomeMessage -> X ()
- tryInOrder :: [SomeMessage] -> X Bool
- tryInOrder_ :: [SomeMessage] -> X ()
- tryMessage :: (Message a, Message b) => a -> b -> X Bool
- tryMessage_ :: (Message a, Message b) => a -> b -> X ()

# Usage

You can use this module with the following in your `~/.xmonad/xmonad.hs`:

    import XMonad.Actions.MessageFeedback

You can then use this module's functions wherever an action is expected. All feedback variants are supported:

- message to any workspace with no refresh
- message to current workspace with no refresh
- message to current workspace with refresh

Except "message to any workspace with refresh" which makes little sense.

Note that most functions in this module have a return type of `X Bool` whereas configuration options will expect a `X ()` action. For example, the key binding:

    -- Shrink the master area of a tiled layout, or move the focused window
    -- to the left in a WindowArranger-based layout
    ((modKey, xK_Left), tryMessageWithNoRefreshToCurrentB Shrink (MoveLeft 50))

is mis-typed. For this reason, this module provides alternatives (not ending with an uppercase "B", e.g. `sendMessage` rather than `sendMessageB`) that discard their boolean result and return an `X ()`. For example, to correct the previous example:

    ((modKey, xK_Left), tryMessageWithNoRefreshToCurrent Shrink (MoveLeft 50))

This module also provides `SomeMessage` variants of each `Message` function for when the messages are of differing types (but still instances of `Message`). First box each message using `SomeMessage` or the convenience alias `sm`. Then, for example, to send each message:

    sendSomeMessages [sm messageOfTypeA, sm messageOfTypeB]

This is not equivalent to the following example, which will not refresh the workspace unless the last message is handled:

    sendMessageWithNoRefreshToCurrent messageOfTypeA >> sendMessage messageOfTypeB

# Messaging variants

## `SomeMessage`

sendSomeMessageB :: SomeMessage -> X Bool #

Variant of `sendMessage`. Accepts `SomeMessage`; to use `Message` see `sendMessageB`. Returns `True` if the message was handled, `False` otherwise. Instead of using `sendSomeMessageWithNoRefreshToCurrentB` for efficiency this is pretty much an exact copy of the `sendMessage` code - foregoes the O(n) `updateLayout`.

sendSomeMessage :: SomeMessage -> X () #

Variant of `sendSomeMessageB` that discards the result.

sendSomeMessageWithNoRefreshB :: SomeMessage -> Workspace WorkspaceId (Layout Window) Window -> X Bool #

Variant of `sendMessageWithNoRefresh`. Accepts `SomeMessage`; to use `Message` see `sendMessageWithNoRefreshB`. Returns `True` if the message was handled, `False` otherwise.

sendSomeMessageWithNoRefresh :: SomeMessage -> Workspace WorkspaceId (Layout Window) Window -> X () #

Variant of `sendSomeMessageWithNoRefreshB` that discards the result.

sendSomeMessageWithNoRefreshToCurrentB :: SomeMessage -> X Bool #

Variant of `sendMessageWithNoRefresh` that sends the message to the current layout. Accepts `SomeMessage`; to use `Message` see `sendMessageWithNoRefreshToCurrentB`. Returns `True` if the message was handled, `False` otherwise. This function is somewhat of a cross between `sendMessage` (sends to the current layout) and `sendMessageWithNoRefresh` (does not refresh).

sendSomeMessageWithNoRefreshToCurrent :: SomeMessage -> X () #

Variant of `sendSomeMessageWithNoRefreshToCurrentB` that discards the result.

## `Message`

sendMessageB :: Message a => a -> X Bool #

Variant of `sendSomeMessageB` which like `sendMessage` accepts `Message` rather than `SomeMessage`. Returns `True` if the message was handled, `False` otherwise.

sendMessageWithNoRefreshB :: Message a => a -> Workspace WorkspaceId (Layout Window) Window -> X Bool #

Variant of `sendSomeMessageWithNoRefreshB` which like `sendMessageWithNoRefresh` accepts `Message` rather than `SomeMessage`. Returns `True` if the message was handled, `False` otherwise.

sendMessageWithNoRefreshToCurrentB :: Message a => a -> X Bool #

Variant of `sendSomeMessageWithNoRefreshToCurrentB` which accepts `Message` rather than `SomeMessage`. Returns `True` if the message was handled, `False` otherwise.

sendMessageWithNoRefreshToCurrent :: Message a => a -> X () #

Variant of `sendMessageWithNoRefreshToCurrentB` that discards the result.

# Utility Functions

## Send All

sendSomeMessagesB :: [SomeMessage] -> X [Bool] #

Send each `SomeMessage` to the current layout without refresh (using `sendSomeMessageWithNoRefreshToCurrentB`) and collect the results. If any message was handled, refresh. If you want to sequence a series of messages that would have otherwise used `sendMessage` while minimizing refreshes, use this.

sendSomeMessages :: [SomeMessage] -> X () #

Variant of `sendSomeMessagesB` that discards the results.

sendMessagesB :: Message a => [a] -> X [Bool] #

Variant of `sendSomeMessagesB` which accepts `Message` rather than `SomeMessage`. Use this if all the messages are of the same type.

sendMessages :: Message a => [a] -> X () #

Variant of `sendMessagesB` that discards the results.

## Send Until

tryInOrderB :: (SomeMessage -> X Bool) -> [SomeMessage] -> X Bool #

Apply the dispatch function in order to each message of the list until one is handled. Returns `True` if so, `False` otherwise.

tryInOrderWithNoRefreshToCurrentB :: [SomeMessage] -> X Bool #

Variant of `tryInOrderB` that sends messages to the current layout without refresh using `sendSomeMessageWithNoRefreshToCurrentB`.

tryInOrderWithNoRefreshToCurrent :: [SomeMessage] -> X () #

Variant of `tryInOrderWithNoRefreshToCurrent` that discards the results.

tryMessageB :: (Message a, Message b) => (SomeMessage -> X Bool) -> a -> b -> X Bool #

Apply the dispatch function to the first message, and if it was not handled, apply it to the second. Returns `True` if either message was handled, `False` otherwise.

tryMessageWithNoRefreshToCurrentB :: (Message a, Message b) => a -> b -> X Bool #

Variant of `tryMessageB` that sends messages to the current layout without refresh using `sendMessageWithNoRefreshToCurrentB`.

tryMessageWithNoRefreshToCurrent :: (Message a, Message b) => a -> b -> X () #

Variant of `tryMessage` that discards the results.

## Aliases

sm :: Message a => a -> SomeMessage #

Convenience shorthand for `SomeMessage`.

# Backwards Compatibility

The following functions exist solely for compatibility with pre-0.14 releases.

send :: Message a => a -> X Bool #

Deprecated: Use sendMessageB instead.

See `sendMessageWithNoRefreshToCurrentB`.

sendSM :: SomeMessage -> X Bool #

Deprecated: Use sendSomeMessageB instead.

See `sendSomeMessageWithNoRefreshToCurrentB`.

sendSM_ :: SomeMessage -> X () #

Deprecated: Use sendSomeMessage instead.

See `sendSomeMessageWithNoRefreshToCurrent`.

tryInOrder :: [SomeMessage] -> X Bool #

Deprecated: Use tryInOrderWithNoRefreshToCurrentB instead.

See `tryInOrderWithNoRefreshToCurrentB`.

tryInOrder_ :: [SomeMessage] -> X () #

Deprecated: Use tryInOrderWithNoRefreshToCurrent instead.

See `tryInOrderWithNoRefreshToCurrent`.

tryMessage :: (Message a, Message b) => a -> b -> X Bool #

Deprecated: Use tryMessageWithNoRefreshToCurrentB instead.

See `tryMessageWithNoRefreshToCurrentB`.

tryMessage_ :: (Message a, Message b) => a -> b -> X () #

Deprecated: Use tryMessageWithNoRefreshToCurrent instead.

See `tryMessageWithNoRefreshToCurrent`.