taffybar-4.0.2: A desktop bar similar to xmobar, but with more GUI

Copyright | (c) Ivan A. Malison
License | BSD3-style (see LICENSE)
Maintainer | Ivan A. Malison
Stability | unstable
Portability | unportable
Safe Haskell | Safe-Inferred
Language | Haskell2010

System.Taffybar.Context

Description

The System.Taffybar.Context module provides the core functionality of the taffybar library. It gets its name from the `Context` record, which stores runtime information and objects, which are used by many of the widgets that taffybar provides. `Context` is typically accessed through the `Reader` interface of `TaffyIO`.

Synopsis

- data Context = Context {
  - x11ContextVar :: MVar X11Context
  - listeners :: MVar SubscriptionList
  - contextState :: MVar (Map TypeRep Value)
  - existingWindows :: MVar [(BarConfig, Window)]
  - sessionDBusClient :: Client
  - systemDBusClient :: Client
  - getBarConfigs :: BarConfigGetter
  - contextBarConfig :: Maybe BarConfig
  }
- data TaffybarConfig = TaffybarConfig {
  - dbusClientParam :: Maybe Client
  - startupHook :: TaffyIO ()
  - getBarConfigsParam :: BarConfigGetter
  - cssPaths :: [FilePath]
  - errorMsg :: Maybe String
  }
- type Taffy m v = ReaderT Context m v
- type TaffyIO v = ReaderT Context IO v
- data BarConfig = BarConfig {
  - strutConfig :: StrutConfig
  - widgetSpacing :: Int32
  - startWidgets :: [TaffyIO Widget]
  - centerWidgets :: [TaffyIO Widget]
  - endWidgets :: [TaffyIO Widget]
  - barId :: Unique
  }
- type BarConfigGetter = TaffyIO [BarConfig]
- appendHook :: TaffyIO () -> TaffybarConfig -> TaffybarConfig
- buildContext :: TaffybarConfig -> IO Context
- buildEmptyContext :: IO Context
- defaultTaffybarConfig :: TaffybarConfig
- getState :: forall t. Typeable t => Taffy IO (Maybe t)
- getStateDefault :: Typeable t => Taffy IO t -> Taffy IO t
- putState :: forall t. Typeable t => Taffy IO t -> Taffy IO t
- forceRefreshTaffyWindows :: TaffyIO ()
- refreshTaffyWindows :: TaffyIO ()
- runX11 :: X11Property a -> TaffyIO a
- runX11Def :: a -> X11Property a -> TaffyIO a
- subscribeToAll :: Listener -> Taffy IO Unique
- subscribeToPropertyEvents :: [String] -> Listener -> Taffy IO Unique
- taffyFork :: ReaderT r IO () -> ReaderT r IO ()
- unsubscribe :: Unique -> Taffy IO ()

# Documentation

data Context Source #

A Context value holds all of the state associated with a single running instance of taffybar. It is typically accessed from a widget constructor through the TaffyIO monad transformer stack.

Constructors

Context |

Fields

- x11ContextVar :: MVar X11Context

  The X11Context that will be used to service X11Property requests.

- listeners :: MVar SubscriptionList

  The handlers which will be evaluated against incoming X11 events.

- contextState :: MVar (Map TypeRep Value)

  A collection of miscellaneous pieces of state which are keyed by their types. Most new pieces of state should go here, rather than in a new field in `Context`. State stored here is typically accessed through `getStateDefault`.

- existingWindows :: MVar [(BarConfig, Window)]

  Used to track the windows that taffybar is currently controlling, and which `BarConfig` objects they are associated with.

- sessionDBusClient :: Client

  The shared user session `Client`.

- systemDBusClient :: Client

  The shared system session `Client`.

- getBarConfigs :: BarConfigGetter

  The action that will be evaluated to get the bar configs associated with each active monitor taffybar should run on.

- contextBarConfig :: Maybe BarConfig

  Populated with the BarConfig that resulted in the creation of a given widget, when its constructor is called. This lets widgets access thing like who their neighbors are. Note that the value of `contextBarConfig` is different for widgets belonging to bar windows on different monitors.

data TaffybarConfig Source #

`TaffybarConfig` provides an advanced interface for configuring taffybar. Through the `getBarConfigsParam`, it is possible to specify different taffybar configurations depending on the number of monitors present, and even to specify different taffybar configurations for each monitor.

Constructors

TaffybarConfig |

Fields

- dbusClientParam :: Maybe Client

  An optional dbus client to use.

- startupHook :: TaffyIO ()

  Hooks that should be executed at taffybar startup.

- getBarConfigsParam :: BarConfigGetter

  A `TaffyIO` action that returns a list of `BarConfig` where each element describes a taffybar window that should be spawned.

- cssPaths :: [FilePath]

  A list of `FilePath` each of which should be loaded as css files at startup.

- errorMsg :: Maybe String

  A field used (only) by dyre to provide an error message.

#### Instances

Instances details

Default TaffybarConfig Source # |
Instance details Defined in System.Taffybar.Context Methods def :: TaffybarConfig #

type Taffy m v = ReaderT Context m v Source #

`Taffy` is a monad transformer that provides `Reader` for `Context`.

type TaffyIO v = ReaderT Context IO v Source #

`TaffyIO` is `IO` wrapped with a `ReaderT` providing `Context`. This is the type of most widgets and callback in taffybar.

data BarConfig Source #

`BarConfig` specifies the configuration for a single taffybar window.

Constructors

BarConfig |

Fields

- strutConfig :: StrutConfig

  The strut configuration to use for the bar

- widgetSpacing :: Int32

  The amount of spacing in pixels between bar widgets

- startWidgets :: [TaffyIO Widget]

  Constructors for widgets that should be placed at the beginning of the bar.

- centerWidgets :: [TaffyIO Widget]

  Constructors for widgets that should be placed in the center of the bar.

- endWidgets :: [TaffyIO Widget]

  Constructors for widgets that should be placed at the end of the bar.

- barId :: Unique

  A unique identifier for the bar, that can be used e.g. when toggling.

#### Instances

Instances details

Eq BarConfig Source # |
Instance details Defined in System.Taffybar.Context Methods (==) :: BarConfig -> BarConfig -> Bool Source # (/=) :: BarConfig -> BarConfig -> Bool Source #

type BarConfigGetter = TaffyIO [BarConfig] Source #

appendHook :: TaffyIO () -> TaffybarConfig -> TaffybarConfig Source #

Append the provided `TaffyIO` hook to the `startupHook` of the given `TaffybarConfig`.

buildContext :: TaffybarConfig -> IO Context Source #

Build the Context for a taffybar process.

buildEmptyContext :: IO Context Source #

Build an empty taffybar context. This function is mostly useful for invoking functions that yield `TaffyIO` values in a testing setting (e.g. in a repl).

defaultTaffybarConfig :: TaffybarConfig Source #

Default values for a `TaffybarConfig`. Not usuable without at least properly setting `getBarConfigsParam`.

getState :: forall t. Typeable t => Taffy IO (Maybe t) Source #

Get a state value by type from the `contextState` field of `Context`.

getStateDefault :: Typeable t => Taffy IO t -> Taffy IO t Source #

Like "putState", but avoids aquiring a lock if the value is already in the map.

putState :: forall t. Typeable t => Taffy IO t -> Taffy IO t Source #

Get a value of the type returned by the provided action from the the current taffybar state, unless the state does not exist, in which case the action will be called to populate the state map.

forceRefreshTaffyWindows :: TaffyIO () Source #

Forcibly refresh taffybar windows, even if there are existing windows that correspond to the uniques in the bar configs yielded by `barConfigGetter`.

refreshTaffyWindows :: TaffyIO () Source #

Use the "barConfigGetter" field of Context to get the set of taffybar windows that should active. Will avoid recreating windows if there is already a window with the appropriate geometry and BarConfig.

runX11 :: X11Property a -> TaffyIO a Source #

Run a function needing an X11 connection in `TaffyIO`.

runX11Def :: a -> X11Property a -> TaffyIO a Source #

Use `runX11` together with `postX11RequestSyncProp` on the provided property. Return the provided default if `Nothing` is returned `postX11RequestSyncProp`.

subscribeToAll :: Listener -> Taffy IO Unique Source #

Subscribe to all incoming events on the X11 event loop. The returned Unique value can be used to unregister the listener using "unsuscribe".

subscribeToPropertyEvents :: [String] -> Listener -> Taffy IO Unique Source #

Subscribe to X11 PropertyEvents where the property changed is in the provided list.

taffyFork :: ReaderT r IO () -> ReaderT r IO () Source #

A version of "forkIO" in TaffyIO.

unsubscribe :: Unique -> Taffy IO () Source #

Remove the listener associated with the provided Unique from the collection of listeners.