@@ -1,11 +1,11 @@
11-- Copyright Corey O'Connor
2−-- General philosophy is: MonadIO is for equations exposed to clients.
32{-# LANGUAGE BangPatterns #-}
43{-# LANGUAGE RankNTypes #-}
54{-# LANGUAGE ExistentialQuantification #-}
65{-# LANGUAGE GADTs #-}
76{-# 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'.
99module Graphics.Vty.Output.Interface
1010 ( Output(..)
1111 , AssumedState(..)
@@ -46,55 +46,51 @@ data Mode = Mouse
4646 -- events on OS pastes)
4747 deriving (Eq, Read, Show)
4848
49+-- | The Vty terminal output interface.
4950data Output = Output
5051 { -- | Text identifier for the output device. Used for debugging.
5152 terminalID :: String
53+ -- | Release the terminal just prior to application exit and reset
54+ -- it to its state prior to application startup.
5255 , releaseTerminal :: forall m. MonadIO m => m ()
53− -- | Clear the display and initialize the terminal to some initial
54− -- display state.
55− --
56− -- The expectation of a program is that the display starts in some
57− -- The initial state. initial state would consist of fixed values:
58− --
59− -- - cursor at top left
60− -- - UTF-8 character encoding
61− -- - drawing characteristics are the default
62− --
63− -- The abstract operation I think all these behaviors are instances
64− -- of is reserving exclusive access to a display such that:
65− --
66− -- - The previous state cannot be determined
67− -- - When exclusive access to a display is released the display
68− -- returns to the previous state.
56+ -- | Clear the display and initialize the terminal to some initial
57+ -- display state.
58+ --
59+ -- The expectation of a program is that the display starts in some
60+ -- The initial state. initial state would consist of fixed values:
61+ --
62+ -- - cursor at top left
63+ -- - UTF-8 character encoding
64+ -- - drawing characteristics are the default
6965 , reserveDisplay :: forall m. MonadIO m => m ()
70− -- | Return the display to the state before `reserveDisplay`
71− -- If no previous state then set the display state to the initial
72− -- state.
66+ -- | Return the display to the state before `reserveDisplay` If no
67+ -- previous state then set the display state to the initial state.
7368 , releaseDisplay :: forall m. MonadIO m => m ()
74− -- | Returns the current display bounds.
69+ -- | Returns the current display bounds.
7570 , displayBounds :: forall m. MonadIO m => m DisplayRegion
76− -- | Output the byte string to the terminal device.
71+ -- | Output the bytestring to the terminal device.
7772 , outputByteBuffer :: BS.ByteString -> IO ()
78− -- | Maximum number of colors supported by the context.
73+ -- | Specifies the maximum number of colors supported by the
74+ -- context.
7975 , contextColorCount :: Int
80− -- | if the cursor can be shown / hidden
76+ -- | Specifies whether the cursor can be shown / hidden.
8177 , supportsCursorVisibility :: Bool
82− -- | Indicates support for terminal modes for this output device
78+ -- | Indicates support for terminal modes for this output device.
8379 , supportsMode :: Mode -> Bool
84− -- | Enables or disables a mode (does nothing if the mode is
85− -- unsupported)
80+ -- | Enables or disables a mode (does nothing if the mode is
81+ -- unsupported).
8682 , setMode :: forall m. MonadIO m => Mode -> Bool -> m ()
87− -- | Returns whether a mode is enabled
83+ -- | Returns whether a mode is enabled.
8884 , getModeStatus :: forall m. MonadIO m => Mode -> m Bool
8985 , assumedStateRef :: IORef AssumedState
90− -- | Acquire display access to the given region of the display.
91− -- Currently all regions have the upper left corner of (0,0) and
92− -- the lower right corner at (max displayWidth providedWidth, max
93− -- displayHeight providedHeight)
86+ -- | Acquire display access to the given region of the display.
87+ -- Currently all regions have the upper left corner of (0,0) and
88+ -- the lower right corner at (max displayWidth providedWidth, max
89+ -- displayHeight providedHeight)
9490 , mkDisplayContext :: forall m. MonadIO m => Output -> DisplayRegion -> m DisplayContext
95− -- | Ring the terminal bell if supported.
91+ -- | Ring the terminal bell if supported.
9692 , 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.
9894 , supportsBell :: forall m. MonadIO m => m Bool
9995 }
10096
@@ -113,16 +109,16 @@ data DisplayContext = DisplayContext
113109 { contextDevice :: Output
114110 -- | Provide the bounds of the display context.
115111 , contextRegion :: DisplayRegion
116− -- | sets the output position to the specified row and column.
117− -- Where the number of bytes required for the control codes can be
112+ -- | Sets the output position to the specified row and column
113+ -- where the number of bytes required for the control codes can be
118114 -- specified seperate from the actual byte sequence.
119115 , writeMoveCursor :: Int -> Int -> Write
120116 , writeShowCursor :: Write
121117 , writeHideCursor :: Write
122− -- | Assure the specified output attributes will be applied to
123− -- all the following text until the next output attribute change.
124− -- Where the number of bytes required for the control codes can be
125− -- specified seperate from the actual byte sequence. The required
118+ -- Ensure that the specified output attributes will be applied to
119+ -- all the following text until the next output attribute change
120+ -- where the number of bytes required for the control codes can be
121+ -- specified seperately from the actual byte sequence. The required
126122 -- number of bytes must be at least the maximum number of bytes
127123 -- required by any attribute changes. The serialization equations
128124 -- must provide the ptr to the next byte to be specified in the
@@ -135,7 +131,7 @@ data DisplayContext = DisplayContext
135131 -- required. In addition it may be possible to optimize the state
136132 -- changes based off the currently applied display attributes.
137133 , 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.
139135 , writeDefaultAttr :: Write
140136 , writeRowEnd :: Write
141137 -- | See `Graphics.Vty.Output.XTermColor.inlineHack`
@@ -149,15 +145,15 @@ writeUtf8Text = writeByteString
149145
150146-- | Displays the given `Picture`.
151147--
152−-- 0. The image is cropped to the display size.
148+-- 1. The image is cropped to the display size.
153149--
154−-- 1. Converted into a sequence of attribute changes and text spans.
150+-- 2. Converted into a sequence of attribute changes and text spans.
155151--
156−-- 2. The cursor is hidden.
152+-- 3. The cursor is hidden.
157153--
158−-- 3. Serialized to the display.
154+-- 4. Serialized to the display.
159155--
160−-- 4. The cursor is then shown and positioned or kept hidden.
156+-- 5. The cursor is then shown and positioned or kept hidden.
161157outputPicture :: MonadIO m => DisplayContext -> Picture -> m ()
162158outputPicture dc pic = liftIO $ do
163159 as <- readIORef (assumedStateRef $ contextDevice dc)