System.Taffybar.Context

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.

Configuration

data TaffybarConfig

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

Default TaffybarConfig

Defined in System.Taffybar.Context

Methods

def :: TaffybarConfig

defaultTaffybarConfig :: TaffybarConfig

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

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

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

Bars

data BarConfig

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

Eq BarConfig

Defined in System.Taffybar.Context

Methods

(==) :: BarConfig -> BarConfig -> Bool

(/=) :: BarConfig -> BarConfig -> Bool

type BarConfigGetter = TaffyIO [BarConfig]

showBarId :: BarConfig -> String

Format the barId as a numeric string.

Taffy monad

type Taffy m v = ReaderT Context m v

Taffy is a monad transformer that provides ReaderT for Context.

type TaffyIO v = ReaderT Context IO v

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

Context

data Context

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.

buildContext :: TaffybarConfig -> IO Context

Build the Context for a taffybar process.

buildEmptyContext :: IO Context

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

Context State

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

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

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

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

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.

Control

refreshTaffyWindows :: TaffyIO ()

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.

exitTaffybar :: Context -> IO ()

Destroys all top-level windows belonging to Taffybar, then requests the GTK main loop to exit.

This ensures that the windows disappear promptly. For GTK windows to be destroyed, the main loop still needs to be running.

X11

runX11 :: X11Property a -> TaffyIO a

Run a function needing an X11 connection in TaffyIO.

runX11Def :: a -> X11Property a -> TaffyIO a

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

Event subscription

subscribeToAll :: Listener -> Taffy IO Unique

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

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

unsubscribe :: Unique -> Taffy IO ()

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

Threading

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

A version of forkIO in TaffyIO.