diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Revision history for brick-panes +## 1.0.0.3 -- 2022-12-18 + +* Bump upper bound for brick to allow brick 1.5. +* Updated haddocks to describe default methods for `focusable` and + `handlePaneEvent` and enhance other descriptions. +* Use `putCursor` in example application to indicate focus (helps screen + readers). Thanks due to Mario Lang. + ## 1.0.0.2 -- 2022-11-01 * Bump upper bound for brick to allow brick 1.4. diff --git a/README.org b/README.org --- a/README.org +++ b/README.org @@ -269,7 +269,7 @@ #+begin_src haskell {-# LANGUAGE DataKinds #-} - type MyWorkState = Panel Wname MyWorkEvent MyWorkCore + type MyWorkState = Panel WName MyWorkEvent MyWorkCore '[ SummaryPane , Projects , OperationsPane @@ -433,7 +433,7 @@ initialization call, the ~i~ parameter will be: #+begin_src haskell - Panel Wname MyWorkEvent MyWorkCore '[ Projects, OperationsPane ] + Panel WName MyWorkEvent MyWorkCore '[ Projects, OperationsPane ] #+end_src Recall that this is the same as MyWorkState except it is missing the SummaryPanel diff --git a/brick-panes.cabal b/brick-panes.cabal --- a/brick-panes.cabal +++ b/brick-panes.cabal @@ -1,6 +1,6 @@ cabal-version: 3.0 name: brick-panes -version: 1.0.0.2 +version: 1.0.0.3 synopsis: Panes library for Brick providing composition and isolation for TUI apps. @@ -37,7 +37,6 @@ -Wincomplete-uni-patterns -Wsimplifiable-class-constraints -Wpartial-fields - -fprint-potential-instances -fhide-source-paths library @@ -46,7 +45,7 @@ default-language: Haskell2010 exposed-modules: Brick.Panes build-depends: base >= 4.13 && < 4.18 - , brick >= 1.0 && < 1.5 + , brick >= 1.0 && < 1.6 , containers , microlens >= 0.4.11.2 && < 0.5 , vty >= 5.35 && < 5.38 @@ -67,7 +66,7 @@ Paths_brick_panes autogen-modules: Paths_brick_panes build-depends: base >= 4.13 && < 4.18 - , brick >= 1.0 && < 1.5 + , brick , brick-panes , aeson >= 2.0 && < 2.2 , bytestring >= 0.10 && < 0.13 diff --git a/samples/mywork/Main.hs b/samples/mywork/Main.hs --- a/samples/mywork/Main.hs +++ b/samples/mywork/Main.hs @@ -24,6 +24,7 @@ import Lens.Micro import Defs +-- import InitialData import Panes.Location () import Panes.Operations import Panes.Projects () @@ -31,9 +32,6 @@ import Panes.FileMgr import Paths_brick_panes ( version ) --- import InitialData --- import Data.ByteString.Lazy as BS --- import Data.Aeson ( encode ) type MyWorkState = Panel WName MyWorkEvent MyWorkCore '[ SummaryPane @@ -45,7 +43,7 @@ main :: IO () main = defaultMain myworkApp initialState >> return () --- main = BS.writeFile "projects.json" (encode $ initial_projects) + myworkApp :: App MyWorkState MyWorkEvent WName myworkApp = App { appDraw = drawMyWork diff --git a/samples/mywork/Panes/FileMgr.hs b/samples/mywork/Panes/FileMgr.hs --- a/samples/mywork/Panes/FileMgr.hs +++ b/samples/mywork/Panes/FileMgr.hs @@ -18,6 +18,7 @@ where import Brick hiding ( Location ) +import qualified Brick (Location(..)) import Brick.Panes import Brick.Widgets.Center import qualified Brick.Widgets.Core as BC @@ -110,7 +111,8 @@ $ strWrap $ X.displayException e savePane = (if fcsd == Just WFSaveBtn - then withAttr (attrName "Selected") + then withAttr (attrName "Selected") . + putCursor WFSaveBtn (Brick.Location (1,0)) else id) $ str "[SAVE]" in centerLayer (browserPane b <=> errDisplay b <=> savePane <=> helpPane) diff --git a/src/Brick/Panes.hs b/src/Brick/Panes.hs --- a/src/Brick/Panes.hs +++ b/src/Brick/Panes.hs @@ -39,11 +39,13 @@ > type EventType pane n appEv > focusable :: (EventConstraints pane eventcontext, Eq n) > => eventcontext -> PaneState pane appEv -> Seq.Seq n + > focusable _ _ = mempty > handlePaneEvent :: (EventConstraints pane eventcontext, Eq n) > => eventcontext > -> EventType pane n appEv > -> PaneState pane appEv > -> EventM n es (PaneState pane appEv) + > handlePaneEvent _ _ = return > > type UpdateType pane > updatePane :: UpdateType pane @@ -53,7 +55,7 @@ Each 'Pane' can be added to an overall 'Panel', where the 'Panel' provides appropriate focus management and consolidates event and draw dispatching to the (appropriate) panes. The 'Panel' can support modal panes which grab focus (and - are not visible wheen not active and focused), panes which participate in a + are not visible when not active and focused), panes which participate in a normal focus ring, and panes which are never focused. The 'Panel' is represented by a recursive data structure that is initialized by calling the 'basePanel' function with the global application state and passing that result @@ -174,7 +176,11 @@ -- | State information associated with this pane data PaneState pane appEv - -- | Type of data provided to updatePane + -- | Type of data provided to updatePane. + -- + -- The default is @()@, indicating that this Pane does not receive any external + -- data during an update (which usually indicates that the Pane does not update + -- once created). type UpdateType pane -- | Constraints on argument passed to 'initPaneState'. If there are no @@ -184,7 +190,12 @@ -- | Function called to initialize the internal 'PaneState' initPaneState :: (InitConstraints pane i) => i -> PaneState pane appEv - -- | Constraints on the @drawcontext@ parameter passed to 'drawPane'. + -- | Constraints on the @drawcontext@ parameter passed to 'drawPane'. This is + -- usually used when the Pane must establish class constraints on the + -- @drawcontext@ that it is passed, since this class definition is fully + -- polymorphic. The default is @()@ which indicate there are no constraints on + -- the Pane's 'draw' function (meaning the Pane can be fully drawn using only + -- the internal 'PaneState'). type DrawConstraints pane drwctxt n :: Constraint -- | Function called to draw the 'Pane' as a Brick 'Widget', or 'Nothing' if -- this 'Pane' should not be drawn at the current time. @@ -192,7 +203,11 @@ => PaneState pane appEv -> drawcontext -> Maybe (Widget n) -- | The constraints that should exist on the 'eventcontext' argment passed to - -- 'focusable' and 'handlePaneEvent'. + -- 'focusable' and 'handlePaneEvent'. This is usually used when the Pane must + -- establish class constraints on the @eventcontext@, since this class + -- definition is fully polymorphic. The default is @()@ which indicate there + -- are no constraints on the Pane's 'focusable' and 'handlePaneEvent' functions + -- (meaning the Pane can be fully drawn using only the internal 'PaneState'). type EventConstraints pane evctxt :: Constraint -- | The type of the event argument delivered to 'handlePaneEvent'. This -- should either be 'Vty.Event' or 'BrickEvent', depending on what level of @@ -200,6 +215,9 @@ type EventType pane n appEv -- | The 'focusable' method is called to determine which Widget targets should -- be part of the Brick 'FocusRing'. + -- + -- The default is @mempty@, which indicates that no part of this Pane is ever + -- focusable. focusable :: (EventConstraints pane eventcontext, Eq n) => eventcontext -> PaneState pane appEv -> Seq.Seq n -- | Called to handle an 'EventType' event for the 'Pane'. This is typically @@ -213,6 +231,9 @@ -- is especially important when the pane is used as part of a panel: the Panel -- itself is passed as the eventcontext, but the panel may not be modified -- because the panel event dispatching will discard any changes on completion. + -- + -- The default is to return the pane state unmodified, indicating that this + -- Pane never responds to any events. handlePaneEvent :: (EventConstraints pane eventcontext, Eq n) => eventcontext -> EventType pane n appEv @@ -220,6 +241,9 @@ -> EventM n es (PaneState pane appEv) -- | Function called to update the internal 'PaneState', using the passed -- 'updateType' argument. + -- + -- The default is to return the pane state unmodified, indicating that this + -- Pane cannot have its internal state changed after creation. updatePane :: UpdateType pane -> PaneState pane appEv -> PaneState pane appEv