Updated documentation and removed unused fields

ihaskell-display/ihaskell-widgets/LICENSE

-Copyright (c) 2015 Sumit Sahrawat
+The MIT License (MIT)
+
+Copyright (c) 2021 David Davó
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

ihaskell-display/ihaskell-widgets/ihaskell-widgets.cabal

@@ -28,15 +28,17 @@ license:             MIT
 license-file:        LICENSE
 
 -- The package author(s).
-author:              Sumit Sahrawat
+author:              David Davó
+                     Sumit Sahrawat
 
 -- An email address to which users can send suggestions, bug reports, and
 -- patches.
-maintainer:          Sumit Sahrawat <sumit.sahrawat.apm13@iitbhu.ac.in>,
+maintainer:          David Davó <david@ddavo.me>
+                     Sumit Sahrawat <sumit.sahrawat.apm13@iitbhu.ac.in>,
                      Andrew Gibiansky <andrew.gibiansky@gmail.com>
 
 -- A copyright notice.
--- copyright:
+copyright:           Copyright (c) 2021 David Davó
 
 -- category:
 

ihaskell-display/ihaskell-widgets/src/IHaskell/Display/Widgets.hs

+{-|
+Module      : ihaskell-widgets
+Description : Jupyter Widgets implementation for the IHaskell kernel
+Copyright   : (c) Sumit Shrawat, 2015
+                  David Davó, 2021
+License     : MIT
+Maintainer  : david@ddavo.me
+Stability   : experimental
+-}
 module IHaskell.Display.Widgets (module X) where
 
 import           IHaskell.Display.Widgets.Button as X

ihaskell-display/ihaskell-widgets/src/IHaskell/Display/Widgets/Common.hs

@@ -25,104 +25,190 @@ import           IHaskell.Eval.Widgets (widgetSendClose)
 
 import qualified IHaskell.Display.Widgets.Singletons as S
 
+-- | The view module string
 pattern ViewModule = S.SViewModule
+-- | The view module version
 pattern ViewModuleVersion = S.SViewModuleVersion
+-- | The view name
 pattern ViewName = S.SViewName
+-- | The model module string
 pattern ModelModule = S.SModelModule
+-- | The model module version
 pattern ModelModuleVersion = S.SModelModuleVersion
+-- | The model name
 pattern ModelName = S.SModelName
+-- | A method to be called on display
 pattern DisplayHandler = S.SDisplayHandler
+-- | CSS classes applied to widget DOM element
 pattern DOMClasses = S.SDOMClasses
+-- | Reference to a Layout widget
 pattern Layout = S.SLayout
+-- | Width of the video/image in pixels
 pattern Width = S.SWidth
+-- | Height of the video/image in pixels
 pattern Height = S.SHeight
+-- | Description of the control
 pattern Description = S.SDescription
+-- | Method to be called on click
 pattern ClickHandler = S.SClickHandler
+-- | Method to be called on submit
 pattern SubmitHandler = S.SSubmitHandler
+-- | Whether the widget appears as disabled on the frontend
 pattern Disabled = S.SDisabled
+-- | The value of the widget, of type string
 pattern StringValue = S.SStringValue
+-- | Placeholder text to display if nothing has been typed yet
 pattern Placeholder = S.SPlaceholder
+-- | Tooltip for the description
 pattern Tooltip = S.STooltip
+-- | The font-awesome icon without the fa-
 pattern Icon = S.SIcon
+-- | Predefined styling for the button
 pattern ButtonStyle = S.SButtonStyle
+-- | Value of the widget of type bytestring
 pattern BSValue = S.SBSValue
+-- | The format of the image
 pattern ImageFormat = S.SImageFormat
+-- | The value of the widget of type bool
 pattern BoolValue = S.SBoolValue
+-- | The labels for the options
 pattern OptionsLabels = S.SOptionsLabels
+-- | Selected index, can be Nothing
 pattern OptionalIndex = S.SOptionalIndex
+-- | The index of the controller
 pattern Index = S.SIndex
+-- | Method to be called when something is chosen
 pattern SelectionHandler = S.SSelectionHandler
+-- | Tooltips for each button
 pattern Tooltips = S.STooltips
+-- | Icons names for each button (FontAwesome names without the fa- prefix)
 pattern Icons = S.SIcons
+-- | Selected indices
 pattern Indices = S.SIndices
+-- | The value of the widget of type int
 pattern IntValue = S.SIntValue
+-- | Minimum step to increment the value
 pattern StepInt = S.SStepInt
+-- | Max value
 pattern MaxInt = S.SMaxInt
+-- | Min value
 pattern MinInt = S.SMinInt
+-- | The value of the widget as an int pair
 pattern IntPairValue = S.SIntPairValue
+-- | Min value on a range widget
 pattern LowerInt = S.SLowerInt
+-- | Max value on a range widget
 pattern UpperInt = S.SUpperInt
+-- | Value of the widget (float)
 pattern FloatValue = S.SFloatValue
+-- | Minimum step to increment the value
 pattern StepFloat = S.SStepFloat
+-- | Max value
 pattern MaxFloat = S.SMaxFloat
+-- | Min value
 pattern MinFloat = S.SMinFloat
+-- | Value of the widget as a float pair
 pattern FloatPairValue = S.SFloatPairValue
+-- | Min value of a range widget
 pattern LowerFloat = S.SLowerFloat
+-- | Max value of a range widget
 pattern UpperFloat = S.SUpperFloat
+-- | Orientation of the widget
 pattern Orientation = S.SOrientation
+-- | The logarithmic base of the widget
 pattern BaseFloat = S.SBaseFloat
+-- | Whether to display the current value of the widget next to it
 pattern ReadOut = S.SReadOut
+-- | The format of the readout
 pattern ReadOutFormat = S.SReadOutFormat
+-- | Use a predefined styling for the bar
 pattern BarStyle = S.SBarStyle
+-- | A method called when the value changes in the fronted
 pattern ChangeHandler = S.SChangeHandler
+-- | List of widget children
 pattern Children = S.SChildren
+-- | Use a predefined styling for the box
 pattern BoxStyle = S.SBoxStyle
-pattern Pack = S.SPack
-pattern Align = S.SAlign
+-- | Titles of the pages
 pattern Titles = S.STitles
+-- | The index of the selected page. Is nothing if no widgets are selected.
 pattern SelectedIndex = S.SSelectedIndex
+-- | Message displayed when the value is false
 pattern ReadOutMsg = S.SReadOutMsg
+-- | Indent the control to align with other controls with a description
 pattern Indent = S.SIndent
-pattern Child = S.SChild
-pattern Selector = S.SSelector
+-- | Update the value as the user types. If false, update on submission.
 pattern ContinuousUpdate = S.SContinuousUpdate
-pattern Tabbable = S.STabbable
+-- | The number of rows to display
 pattern Rows = S.SRows
+-- | The format of the audio
 pattern AudioFormat = S.SAudioFormat
+-- | The format of the image
 pattern VideoFormat = S.SVideoFormat
+-- | When true, the video starts on display
 pattern AutoPlay = S.SAutoPlay
+-- | When true, the video starts from the beginning after finishing
 pattern Loop = S.SLoop
+-- | Specifies that video controls should be displayed
 pattern Controls = S.SControls
+-- | Dropdown options for the combobox
 pattern Options = S.SOptions
+-- | If set, ensure the value is in options
 pattern EnsureOption = S.SEnsureOption
+-- | Whether the control is currently playing
 pattern Playing = S.SPlaying
+-- | Whether the control will repeat in a continuous loop
 pattern Repeat = S.SRepeat
+-- | The maximum interval for the play control
 pattern Interval = S.SInterval
+-- | Show the repeat toggle button on the widget
 pattern ShowRepeat = S.SShowRepeat
+-- | Display the short version of the selector
 pattern Concise = S.SConcise
+-- | The value of the widget in date format
 pattern DateValue = S.SDateValue
+-- | Whether the button is pressed
 pattern Pressed = S.SPressed
+-- | The name of the controller
 pattern Name = S.SName
+-- | The name of the control mapping
 pattern Mapping = S.SMapping
+-- | Whether the gamepad is connected
 pattern Connected = S.SConnected
+-- | The last time the data from this gamepad was updated
 pattern Timestamp = S.STimestamp
+-- | The button widgets on the gamepad
 pattern Buttons = S.SButtons
+-- | The axes on the gamepad
 pattern Axes = S.SAxes
+-- | Color of the button
 pattern ButtonColor = S.SButtonColor
+-- | The font weight of the text
 pattern FontWeight = S.SFontWeight
+-- | Width of the description to the side of the control
 pattern DescriptionWidth = S.SDescriptionWidth
+-- | Color of the progress bar
 pattern BarColor = S.SBarColor
+-- | Color of the slider handle
 pattern HandleColor = S.SHandleColor
+-- | The width of each button
 pattern ButtonWidth = S.SButtonWidth
+-- | The target (widget,field) pair
 pattern Target = S.STarget
+-- | The source (widget,field) pair
 pattern Source = S.SSource
+-- | Parent message id of messages to capture
 pattern MsgID = S.SMsgID
+-- | The output messages synced from the frontend
 pattern Outputs = S.SOutputs
+-- | Reference to a Style widget with styling customizations
 pattern Style = S.SStyle
+
 -- | Close a widget's comm
 closeWidget :: IHaskellWidget w => w -> IO ()
 closeWidget w = widgetSendClose w emptyObject
 
+-- | Transforms the Integer to a String of pixels
 newtype PixCount = PixCount Integer
   deriving (Num, Ord, Eq, Enum, Typeable)
 
@@ -216,6 +302,7 @@ data ImageFormatValue = PNG
                       | IURL
   deriving (Eq, Typeable)
 
+-- | Image formats for ImageWidget
 instance Show ImageFormatValue where
   show PNG = "png"
   show SVG = "svg"
@@ -247,6 +334,7 @@ instance ToJSON OrientationValue where
   toJSON HorizontalOrientation = "horizontal"
   toJSON VerticalOrientation = "vertical"
 
+-- | Predefined styles for box widgets
 data BoxStyleValue = SuccessBox
                    | InfoBox
                    | WarningBox
@@ -260,20 +348,8 @@ instance ToJSON BoxStyleValue where
   toJSON DangerBox = "danger"
   toJSON DefaultBox = ""
 
-data LocationValue = StartLocation
-                   | CenterLocation
-                   | EndLocation
-                   | BaselineLocation
-                   | StretchLocation
-
-instance ToJSON LocationValue where
-  toJSON StartLocation = "start"
-  toJSON CenterLocation = "center"
-  toJSON EndLocation = "end"
-  toJSON BaselineLocation = "baseline"
-  toJSON StretchLocation = "stretch"
-
 -- Could use 'lens-aeson' here but this is easier to read.
+-- | Makes a lookup on a value given a path of strings to follow
 nestedObjectLookup :: Value -> [Text] -> Maybe Value
 nestedObjectLookup val [] = Just val
 nestedObjectLookup val (x:xs) =

ihaskell-display/ihaskell-widgets/src/IHaskell/Display/Widgets/Output.hs

@@ -66,15 +66,18 @@ mkOutput = do
   -- Return the image widget
   return widget
 
+-- | Appends the Text to the given Stream
 appendStd :: StreamType -> OutputWidget -> Text -> IO ()
 appendStd n out t = do
   getField out Outputs >>= setField out Outputs . updateOutputs
   where updateOutputs :: [OutputMsg] -> [OutputMsg]
         updateOutputs = (++[OutputStream n t])
 
+-- | Appends text to the stdout of an output widget
 appendStdout :: OutputWidget -> Text -> IO ()
 appendStdout = appendStd Stdout
 
+-- | Appends text to the stderr of an output widget
 appendStderr :: OutputWidget -> Text -> IO ()
 appendStderr = appendStd Stderr
 
@@ -85,6 +88,7 @@ clearOutput' w = do
   _ <- setField w MsgID ""
   return ()
 
+-- | Appends anything displayable to an output widget
 appendDisplay :: IHaskellDisplay a => OutputWidget -> a -> IO ()
 appendDisplay o d = do
   outputs <- getField o Outputs

ihaskell-display/ihaskell-widgets/src/IHaskell/Display/Widgets/Singletons.hs

@@ -88,16 +88,11 @@ singletons
              | ChangeHandler
              | Children
              | BoxStyle
-             | Pack
-             | Align
              | Titles
              | SelectedIndex
              | ReadOutMsg
              | Indent
-             | Child
-             | Selector
              | ContinuousUpdate
-             | Tabbable
              | Rows
              | AudioFormat
              | VideoFormat
@@ -229,16 +224,11 @@ promote
     toKey ChangeHandler = "" -- Not sent to the frontend
     toKey Children = "children"
     toKey BoxStyle = "box_style"
-    toKey Pack = "pack"
-    toKey Align = "align"
     toKey Titles = "_titles"
     toKey SelectedIndex = "selected_index"
     toKey ReadOutMsg = "readout"
     toKey Indent = "indent"
-    toKey Child = "child"
-    toKey Selector = "selector"
     toKey ContinuousUpdate = "continuous_update"
-    toKey Tabbable = "tabbable"
     toKey Rows = "rows"
     toKey AutoPlay = "autoplay"
     toKey Loop = "loop"

ihaskell-display/ihaskell-widgets/src/IHaskell/Display/Widgets/Types.hs

@@ -130,7 +130,7 @@ type (a :++ b) = a ++ b
 -- Classes from IPython's widget hierarchy. Defined as such to reduce code duplication.
 type CoreWidgetClass = ['S.ViewModule, 'S.ViewModuleVersion, 'S.ModelModule, 'S.ModelModuleVersion ]
 
-type DOMWidgetClass = ['S.ModelName, 'S.ViewName, 'S.DOMClasses, 'S.Tabbable, 'S.Tooltip, 'S.Layout, 'S.DisplayHandler]
+type DOMWidgetClass = ['S.ModelName, 'S.ViewName, 'S.DOMClasses, 'S.Tooltip, 'S.Layout, 'S.DisplayHandler]
 
 type StyleWidgetClass = ['S.ModelName, 'S.ViewName] :++ CoreWidgetClass
 
@@ -231,16 +231,11 @@ type instance FieldType 'S.FloatPairValue = (Double, Double)
 type instance FieldType 'S.ChangeHandler = IO ()
 type instance FieldType 'S.Children = [ChildWidget]
 type instance FieldType 'S.BoxStyle = BoxStyleValue
-type instance FieldType 'S.Pack = LocationValue
-type instance FieldType 'S.Align = LocationValue
 type instance FieldType 'S.Titles = [Text]
 type instance FieldType 'S.SelectedIndex = Maybe Integer
 type instance FieldType 'S.ReadOutMsg = Text
 type instance FieldType 'S.Indent = Bool
-type instance FieldType 'S.Child = Maybe ChildWidget
-type instance FieldType 'S.Selector = Text
 type instance FieldType 'S.ContinuousUpdate = Bool
-type instance FieldType 'S.Tabbable = Maybe Bool
 type instance FieldType 'S.Rows = Maybe Integer
 type instance FieldType 'S.AudioFormat = AudioFormatValue
 type instance FieldType 'S.VideoFormat = VideoFormatValue
@@ -276,6 +271,8 @@ type instance FieldType 'S.Style = StyleWidget
 
 -- | Can be used to put different widgets in a list. Useful for dealing with children widgets.
 data ChildWidget = forall w. RecAll Attr (WidgetFields w) ToPairs => ChildWidget (IPythonWidget w)
+
+-- | Can be used to put different styles in a same FieldType.
 data StyleWidget = forall w. RecAll Attr (WidgetFields w) ToPairs => StyleWidget (IPythonWidget w)
 
 instance ToJSON (IPythonWidget w) where
@@ -578,7 +575,6 @@ defaultDOMWidget :: FieldType 'S.ViewName -> FieldType 'S.ModelName -> IPythonWi
 defaultDOMWidget viewName modelName layout = (ModelName =:! modelName)
                                       :& (ViewName =:! viewName)
                                       :& (DOMClasses =:: [])
-                                      :& (Tabbable =:: Nothing)
                                       :& (Tooltip =:: Nothing)
                                       :& (Layout =:: layout)
                                       :& (DisplayHandler =:: return ())
@@ -890,6 +886,7 @@ getField widget sfield = unwrap . _value <$> getAttr widget sfield
 str :: String -> String
 str = id
 
+-- | Displays on stdout the properties (and its types) of a given widget
 properties :: IPythonWidget w -> IO ()
 properties widget = do
   st <- readIORef $ state widget
@@ -914,22 +911,27 @@ noStdin action =
     void action
     void $ dupTo oldStdin stdInput
 
--- Trigger events
+-- | Common function for the different trigger events
 triggerEvent :: (FieldType f ~ IO (), f ∈ WidgetFields w) => SField f -> IPythonWidget w -> IO ()
 triggerEvent sfield w = noStdin . join $ getField w sfield
 
+-- | Called when the value of an attribute is changed on the front-end
 triggerChange :: ('S.ChangeHandler ∈ WidgetFields w) => IPythonWidget w -> IO ()
 triggerChange = triggerEvent ChangeHandler
 
+-- | Called when the button is clicked
 triggerClick :: ('S.ClickHandler ∈ WidgetFields w) => IPythonWidget w -> IO ()
 triggerClick = triggerEvent ClickHandler
 
+-- | Called when a selection is made in a selection widget
 triggerSelection :: ('S.SelectionHandler ∈ WidgetFields w) => IPythonWidget w -> IO ()
 triggerSelection = triggerEvent SelectionHandler
 
+-- | Called when the text is submited in a text widget (or combobox/password)
 triggerSubmit :: ('S.SubmitHandler ∈ WidgetFields w) => IPythonWidget w -> IO ()
 triggerSubmit = triggerEvent SubmitHandler
 
+-- | Called when the widget is displayed on the notebook
 triggerDisplay :: ('S.DisplayHandler ∈ WidgetFields w) => IPythonWidget w -> IO ()
 triggerDisplay = triggerEvent DisplayHandler
 

src/IHaskell/Types.hs

@@ -295,11 +295,13 @@ dupHeader hdr messageType = do
   uuid <- liftIO random
   return hdr { mhMessageId = uuid, mhMsgType = messageType }
 
--- | Modyfies a header and appends the version of the Widget Messaging Protocol as metadata
+-- | Modifies a header and appends the version of the Widget Messaging Protocol as metadata
 setVersion :: MessageHeader  -- ^ The header to modify
            -> String         -- ^ The version to set
            -> MessageHeader  -- ^ The modified header
-setVersion hdr v = hdr { mhMetadata = Metadata (HashMap.fromList [("version", String $ pack v)]) } 
+-- We use the 'fromList' function from "Data.HashMap.Strict" instead of the 'object' function from
+-- "Data.Aeson" because 'object' returns a 'Value', but metadata needs an 'Object'.
+setVersion hdr v = hdr { mhMetadata = Metadata (HashMap.fromList [("version", String $ pack v)]) }
 
 -- | Whether or not an error occurred.
 data ErrorOccurred = Success