@@ -1,3 +1,25 @@
1+-- | The inline module provides a limited interface to changing the style of terminal output. The
2+-- intention is for this interface to be used inline with other output systems.
3+--
4+-- The changes specified by the InlineM monad are applied to the terminals display attributes. These
5+-- display attributes effect the display of all following text output to the terminal file
6+-- descriptor.
7+--
8+-- For example, in an IO monad the following code with print the text \"Not styled. \" Followed by the
9+-- text \" Styled! \" drawn over a red background and underlined.
10+--
11+-- @
12+-- t <- terminal_handle
13+-- putStr \"Not styled. \"
14+-- put_attr_change t $ do
15+-- back_color red
16+-- apply_style underline
17+-- putStr \" Styled! \"
18+-- put_attr_change t $ default_all
19+-- putStrLn \"Not styled.\"
20+-- release_terminal t
21+-- @
22+--
123-- Copyright 2009-2010 Corey O'Connor
224{-# LANGUAGE BangPatterns #-}
325module Graphics.Vty.Inline ( module Graphics.Vty.Inline
@@ -20,15 +42,24 @@ import System.IO
2042
2143type InlineM v = State Attr v
2244
45+-- | Set the background color to the provided 'Color'
2346back_color :: Color -> InlineM ()
2447back_color c = modify $ flip mappend ( current_attr `with_back_color` c )
2548
49+-- | Set the foreground color to the provided 'Color'
2650fore_color :: Color -> InlineM ()
2751fore_color c = modify $ flip mappend ( current_attr `with_fore_color` c )
2852
53+-- | Attempt to change the 'Style' of the following text.
54+--
55+-- If the terminal does not support the style change no error is produced. The style can still be
56+-- removed.
2957apply_style :: Style -> InlineM ()
3058apply_style s = modify $ flip mappend ( current_attr `with_style` s )
3159
60+-- | Attempt to remove the specified 'Style' from the display of the following text.
61+--
62+-- This will fail if apply_style for the given style has not been previously called.
3263remove_style :: Style -> InlineM ()
3364remove_style s_mask = modify $ \attr ->
3465 let style' = case attr_style attr of
@@ -37,9 +68,13 @@ remove_style s_mask = modify $ \attr ->
3768 SetTo s -> s .&. complement s_mask
3869 in attr { attr_style = SetTo style' }
3970
71+-- | Reset the display attributes
4072default_all :: InlineM ()
4173default_all = put def_attr
4274
75+-- | Apply the provided display attribute changes to the terminal.
76+--
77+-- This also flushes the 'stdout' handle.
4378put_attr_change :: ( Applicative m, MonadIO m ) => TerminalHandle -> InlineM () -> m ()
4479put_attr_change t c = do
4580 bounds <- display_bounds t
@@ -60,10 +95,3 @@ put_attr_change t c = do
6095 liftIO $ modifyIORef ( state_ref t ) $ \s -> s { known_fattr = Just fattr' }
6196 inline_hack d
6297
63−put_string :: ( Applicative m, MonadIO m ) => TerminalHandle -> String -> m ()
64−put_string t s = do
65− let s_utf8 = UTF8.fromString s
66− liftIO $ hFlush stdout
67− liftIO $ marshall_to_terminal t ( utf8_text_required_bytes s_utf8)
68− ( serialize_utf8_text s_utf8 )
69−