@@ -1,11 +1,11 @@
1-- Copyright Corey O'Connor
1-- Copyright Corey O'Connor
2−-- General philosophy is: MonadIO is for equations exposed to clients.
3{-# LANGUAGE BangPatterns #-}
2{-# LANGUAGE BangPatterns #-}
4{-# LANGUAGE RankNTypes #-}
3{-# LANGUAGE RankNTypes #-}
5{-# LANGUAGE ExistentialQuantification #-}
4{-# LANGUAGE ExistentialQuantification #-}
6{-# LANGUAGE GADTs #-}
5{-# LANGUAGE GADTs #-}
7{-# LANGUAGE FlexibleContexts #-}
6{-# LANGUAGE FlexibleContexts #-}
8−
7+-- | This module provides an abstract interface for performing terminal
8+-- output. The only user-facing part of this API is 'Output'.
9module Graphics.Vty.Output.Interface
9module Graphics.Vty.Output.Interface
10 ( Output(..)
10 ( Output(..)
11 , AssumedState(..)
11 , AssumedState(..)
@@ -46,55 +46,51 @@ data Mode = Mouse
46 -- events on OS pastes)
46 -- events on OS pastes)
47 deriving (Eq, Read, Show)
47 deriving (Eq, Read, Show)
49+-- | The Vty terminal output interface.
49data Output = Output
50data Output = Output
50 { -- | Text identifier for the output device. Used for debugging.
51 { -- | Text identifier for the output device. Used for debugging.
51 terminalID :: String
52 terminalID :: String
53+ -- | Release the terminal just prior to application exit and reset
54+ -- it to its state prior to application startup.
52 , releaseTerminal :: forall m. MonadIO m => m ()
55 , releaseTerminal :: forall m. MonadIO m => m ()
53− -- | Clear the display and initialize the terminal to some initial
56+ -- | Clear the display and initialize the terminal to some initial
54− -- display state.
57+ -- display state.
56− -- The expectation of a program is that the display starts in some
59+ -- The expectation of a program is that the display starts in some
57− -- The initial state. initial state would consist of fixed values:
60+ -- The initial state. initial state would consist of fixed values:
59− -- - cursor at top left
62+ -- - cursor at top left
60− -- - UTF-8 character encoding
63+ -- - UTF-8 character encoding
61− -- - drawing characteristics are the default
64+ -- - drawing characteristics are the default
63− -- The abstract operation I think all these behaviors are instances
64− -- of is reserving exclusive access to a display such that:
66− -- - The previous state cannot be determined
67− -- - When exclusive access to a display is released the display
68− -- returns to the previous state.
69 , reserveDisplay :: forall m. MonadIO m => m ()
65 , reserveDisplay :: forall m. MonadIO m => m ()
70− -- | Return the display to the state before `reserveDisplay`
66+ -- | Return the display to the state before `reserveDisplay` If no
71− -- If no previous state then set the display state to the initial
67+ -- previous state then set the display state to the initial state.
73 , releaseDisplay :: forall m. MonadIO m => m ()
68 , releaseDisplay :: forall m. MonadIO m => m ()
74− -- | Returns the current display bounds.
69+ -- | Returns the current display bounds.
75 , displayBounds :: forall m. MonadIO m => m DisplayRegion
70 , displayBounds :: forall m. MonadIO m => m DisplayRegion
76− -- | Output the byte string to the terminal device.
71+ -- | Output the bytestring to the terminal device.
77 , outputByteBuffer :: BS.ByteString -> IO ()
72 , outputByteBuffer :: BS.ByteString -> IO ()
78− -- | Maximum number of colors supported by the context.
73+ -- | Specifies the maximum number of colors supported by the
79 , contextColorCount :: Int
75 , contextColorCount :: Int
80− -- | if the cursor can be shown / hidden
76+ -- | Specifies whether the cursor can be shown / hidden.
81 , supportsCursorVisibility :: Bool
77 , supportsCursorVisibility :: Bool
82− -- | Indicates support for terminal modes for this output device
78+ -- | Indicates support for terminal modes for this output device.
83 , supportsMode :: Mode -> Bool
79 , supportsMode :: Mode -> Bool
84− -- | Enables or disables a mode (does nothing if the mode is
80+ -- | Enables or disables a mode (does nothing if the mode is
85− -- unsupported)
81+ -- unsupported).
86 , setMode :: forall m. MonadIO m => Mode -> Bool -> m ()
82 , setMode :: forall m. MonadIO m => Mode -> Bool -> m ()
87− -- | Returns whether a mode is enabled
83+ -- | Returns whether a mode is enabled.
88 , getModeStatus :: forall m. MonadIO m => Mode -> m Bool
84 , getModeStatus :: forall m. MonadIO m => Mode -> m Bool
89 , assumedStateRef :: IORef AssumedState
85 , assumedStateRef :: IORef AssumedState
90− -- | Acquire display access to the given region of the display.
86+ -- | Acquire display access to the given region of the display.
91− -- Currently all regions have the upper left corner of (0,0) and
87+ -- Currently all regions have the upper left corner of (0,0) and
92− -- the lower right corner at (max displayWidth providedWidth, max
88+ -- the lower right corner at (max displayWidth providedWidth, max
93− -- displayHeight providedHeight)
89+ -- displayHeight providedHeight)
94 , mkDisplayContext :: forall m. MonadIO m => Output -> DisplayRegion -> m DisplayContext
90 , mkDisplayContext :: forall m. MonadIO m => Output -> DisplayRegion -> m DisplayContext
95− -- | Ring the terminal bell if supported.
91+ -- | Ring the terminal bell if supported.
96 , ringTerminalBell :: forall m. MonadIO m => m ()
92 , ringTerminalBell :: forall m. MonadIO m => m ()
97− -- | Returns whether the terminal has an audio bell feature.
93+ -- | Returns whether the terminal has an audio bell feature.
98 , supportsBell :: forall m. MonadIO m => m Bool
94 , supportsBell :: forall m. MonadIO m => m Bool
@@ -113,16 +109,16 @@ data DisplayContext = DisplayContext
113 { contextDevice :: Output
109 { contextDevice :: Output
114 -- | Provide the bounds of the display context.
110 -- | Provide the bounds of the display context.
115 , contextRegion :: DisplayRegion
111 , contextRegion :: DisplayRegion
116− -- | sets the output position to the specified row and column.
112+ -- | Sets the output position to the specified row and column
117− -- Where the number of bytes required for the control codes can be
113+ -- where the number of bytes required for the control codes can be
118 -- specified seperate from the actual byte sequence.
114 -- specified seperate from the actual byte sequence.
119 , writeMoveCursor :: Int -> Int -> Write
115 , writeMoveCursor :: Int -> Int -> Write
120 , writeShowCursor :: Write
116 , writeShowCursor :: Write
121 , writeHideCursor :: Write
117 , writeHideCursor :: Write
122− -- | Assure the specified output attributes will be applied to
118+ -- Ensure that the specified output attributes will be applied to
123− -- all the following text until the next output attribute change.
119+ -- all the following text until the next output attribute change
124− -- Where the number of bytes required for the control codes can be
120+ -- where the number of bytes required for the control codes can be
125− -- specified seperate from the actual byte sequence. The required
121+ -- specified seperately from the actual byte sequence. The required
126 -- number of bytes must be at least the maximum number of bytes
122 -- number of bytes must be at least the maximum number of bytes
127 -- required by any attribute changes. The serialization equations
123 -- required by any attribute changes. The serialization equations
128 -- must provide the ptr to the next byte to be specified in the
124 -- must provide the ptr to the next byte to be specified in the
@@ -135,7 +131,7 @@ data DisplayContext = DisplayContext
135 -- required. In addition it may be possible to optimize the state
131 -- required. In addition it may be possible to optimize the state
136 -- changes based off the currently applied display attributes.
132 -- changes based off the currently applied display attributes.
137 , writeSetAttr :: FixedAttr -> Attr -> DisplayAttrDiff -> Write
133 , writeSetAttr :: FixedAttr -> Attr -> DisplayAttrDiff -> Write
138− -- | Reset the display attributes to the default display attributes
134+ -- | Reset the display attributes to the default display attributes.
139 , writeDefaultAttr :: Write
135 , writeDefaultAttr :: Write
140 , writeRowEnd :: Write
136 , writeRowEnd :: Write
141 -- | See `Graphics.Vty.Output.XTermColor.inlineHack`
137 -- | See `Graphics.Vty.Output.XTermColor.inlineHack`
@@ -149,15 +145,15 @@ writeUtf8Text = writeByteString
150-- | Displays the given `Picture`.
146-- | Displays the given `Picture`.
152−-- 0. The image is cropped to the display size.
148+-- 1. The image is cropped to the display size.
154−-- 1. Converted into a sequence of attribute changes and text spans.
150+-- 2. Converted into a sequence of attribute changes and text spans.
156−-- 2. The cursor is hidden.
152+-- 3. The cursor is hidden.
158−-- 3. Serialized to the display.
154+-- 4. Serialized to the display.
160−-- 4. The cursor is then shown and positioned or kept hidden.
156+-- 5. The cursor is then shown and positioned or kept hidden.
161outputPicture :: MonadIO m => DisplayContext -> Picture -> m ()
157outputPicture :: MonadIO m => DisplayContext -> Picture -> m ()
162outputPicture dc pic = liftIO $ do
158outputPicture dc pic = liftIO $ do
163 as <- readIORef (assumedStateRef $ contextDevice dc)
159 as <- readIORef (assumedStateRef $ contextDevice dc)