monomer

A GUI library for writing native Haskell applications.

https://github.com/fjvallarino/monomer#readme

Version on this page:1.5.0.0@rev:1
LTS Haskell 20.10:1.5.0.0@rev:1
Stackage Nightly 2022-11-17:1.5.0.0@rev:1
Latest on Hackage:1.5.1.0

See all snapshots monomer appears in

BSD-3-Clause licensed by Francisco Vallarino
Maintained by fjvallarino@gmail.com
This version can be pinned in stack with:monomer-1.5.0.0@sha256:7504b598ba1edc95d85236bc7e6c69b54fec85073ca22b09460bea4c151be9c5,15801

Module documentation for 1.5.0.0

An easy to use, cross platform, GUI library for writing native Haskell applications.

Monomer provides a framework similar to the Elm Architecture, allowing the creation of GUIs using an extensible set of widgets with pure Haskell.

Objectives

  • Be easy to learn and use.
  • Be extensible with custom widgets.
  • Run on Windows, Linux and macOS.
  • Have good documentation.
  • Have good examples.

These are not objectives for this project

  • Have a native look and feel.

Why would you want to use this library?

  • You want to write your application in Haskell.
  • You want to write a native, not web based, application.

Documentation

Setup

You can read how to setup your environment here.

Tutorials

Introductory tutorials are available:

Examples

Beyond the tutorials, a few real world like examples are available:

Haddock

You can read the source code’s documentation here.

Design decisions

In case you wonder why some choices were made, you can read here.

Roadmap

  • Stability and performance.
  • Mobile support.

Contributing

PRs are welcome!

If possible, keep them small and focused. If you are planning on making a large change, please submit an issue first so we can agree on a solution.

License

This library is licensed under the BSD-3 license.

Fonts used in the examples:

Acknowledgments

Changes

1.5.0.0

Added

  • Do not disable screensaver unless explicitly requested; add configuration flag (PR #189).
  • Conditional helpers for lists of widgets, styles and configuration options (PR #185).
  • Popup widget (PR #191).
  • Loading fonts from memory (PR #199). Thanks @klausweiss!
  • BoxShadow component (PR #205). Thanks @Dretch!

Fixed

  • Issue in selectList, which would ignore WidgetRequests made by child widgets (PR #157).
  • Compatibility with GHC 9.2.2 (PR #162). Thanks @Dretch!
  • Consider padding, border and sizeReqs in addition to textStyle when checking if resize is needed for label (PR #169).
  • Hide tooltip when a button action is detected on its child widget (PR #170).
  • Fix Composite’s onDispose event handler (PR #176).
  • Catch exception when trying to write to stderr and try stdout instead (PR #190).

Changed

  • Do not exit application if icon image is missing or fails to load (PR #171).
  • Use stderr for diagnostic and error messages (PR #172).
  • Allow using any file type for the application icon (PR #186).

1.4.1.0

Added

  • Support for switching vertical wheel scrolling to horizontal in scroll widget by pressing the shift key (PR #137).
  • Drawing and theme utility functions (PR #138).
  • boxFilterEvent config option, exposing Container’s filterEvent functionality (PR #146).
  • pointToLineDistance utility function (PR #150).

Fixed

  • Bug where memory based image widget would not render their new state after a merge (PR #147). Thanks @CamdenKuwahara!
  • Fix memory leak in NanoVGRenderer’s image initialization. Dispose unused images in image widget (PR #149).

Changed

  • Restricts toggleButton’s type argument for configuration options to Bool (the only valid type) (PR #150).
  • Avoids drawing borders if width == 0 (PR #150).
  • Updates default style for tooltip widget (PR #150).

1.4.0.0

Breaking changes

  • Added style...Set family of functions (PR #104).
  • Composite’s onChange event is now sent to its handleEvent function, not to its parent; the type of the generated event was updated to reflect this change. The rationale is that since onInit is sent to handleEvent, having onChange sent to its parent was confusing. At the same time there was not an easy way in handleEvent to know when the model changed. Widgets that want to report model changes to its parent can use Report/RequestParent; an example can be found in ColorPicker (PR #71).
  • Timestamp is now a newtype. Enforce use of this type instead of Int when appropriate (PR #103).
  • Timestamp was renamed to Millisecond. The rationale is that since both timestamps and durations are used frequently in calculations (and in the context of Monomer timestamps and durations indeed represent time in milliseconds), having separate types for Timestamp and Duration caused more harm than good (PR #107).
  • compositeMergeModel (previously customModelBuilder) now receives WidgetEnv as its first parameter (PR #114).
  • compositeMergeReqs now receives parentModel and oldModel too (PR #114).
  • mergeRequired now receives an extra value as its first parameter, usually WidgetEnv (PR #122).

Fixed

  • Properly handle SetFocusOnKey for textArea (#80).
  • Lens tutorial sample code (PR #95 and PR #98). Thanks @Clindbergh!
  • ColorPicker’s numericFields vertical alignment (PR #108).
  • Differences in glyphs positions used by FontManager and nanovg; temporary workaround (PR #105).
  • nodeInfoFromKey relies on nodeInfoFromPath to retrieve information instead of fetching it directly from WidgetEnv’s widgetKeyMap, which can be stale (PR #110).
  • Glyph positioning issues in FontManager; removed workaround added in #105 (PR #125).
  • Will attempt to fall back to rendering on the main thread if threaded rendering setup fails (PR #131).
  • Space leak in StyleUtil’s mergeNodeStyleState (PR #132).

Added

  • Utility functions rectFromPoints, nodeInfoFromKey, nodeInfoFromPath and findParentNodeInfoByType.
  • Allow setting the window icon via AppConfig (PR #79). Thanks @Dretch!
  • Support for breaking text lines at character boundaries (PR #86). Thanks @toku-sa-n!
  • Read-only mode for textField, numericField, dateField, timeField and textArea (PR #93). Thanks @Dretch!
  • The scroll widget now supports a thumbMinSize configuration option that allows setting a minimum thumb size (PR #100).
  • New field _weAppStartTs in WidgetEnv, complementary to _weTimestamp, representing the time in milliseconds when the application started. Added utility function currentTimeMs that returns their sum with a polymorphic type (PR #103).
  • Several sizeReq helpers (PR #106).
  • compositeMergeEvents, for completeness (PR #114).
  • Support for symbols and other keys in keystroke (PR #117).
  • New constructor (buttonD_) and ignoreParentEvts configuration option to button (PR #123).
  • Allow disabling auto scale detection with appDisableAutoScale (PR #128).

Changed

  • The keystroke widget now supports the Backspace key (PR #74).
  • style... family of functions now combine new attributes with the existing ones (PR #104).
  • radio and optionButton now only trigger onChange when their value changes. onClick was can be used to replicate the previous onChange behavior (PR #134).

Renamed

  • Utility functions for retrieving WidgetNode information (PR #75)
    • findWidgetByPath -> findChildNodeInfoByPath.
    • findWidgetBranchByPath -> findChildBranchByPath.
    • findWidgetIdFromPath -> widgetIdFromPath.
  • Composite merge related (PR #114)
    • customModelBuilder -> compositeMergeModel
    • CompositeCustomModelBuilder -> MergeModelHandler.

Removed

  • Dependencies on OpenGL, Safe, scientific, unordered-containers, directory, HUnit and silently (PR #70).

1.3.0.0

Added

  • Export drawArrowUp from Drawing module.
  • The image widget now supports a fitEither option (PR #56). Thanks @Kyarigwo!
  • The scroll widget now raises onChange events, providing the current ScrollStatus (PR #51).
  • The grid, stack, labeledCheckbox and labeledRadio widgets now support a childSpacing/childSpacing_ option (PR #67). Thanks @Dretch!

Fixed

  • Widgets that receive polymorphic types now append the handled type to their WidgetType. This is done to avoid issues if the handled type is later changed (#46).
  • If the WidgetType of the root item in a Composite changes during merge, initialize the new widget instead of merging with the old one (#50).
  • The arrow position in dropdown is now correct when a dropdown is taller than one line (PR #55). Thanks @Dretch!
  • The middle button click is now handled by convertEvents, and in turn reported to widgets (#63).
  • Add tolerance to width comparison in text clipping functions (#54).
  • Call pumpEvents before pollEvents. The pumpEvents call is implied by pollEvent, but starting on SDL2 2.0.20 it seems to be required to call it explicitly (#66). Thanks @JD95!

Changed

  • Relaxed upper bounds of dependencies for Stackage inclusion.

1.2.0.1

Fixed

  • The scroll and split widgets now avoid unexpected behaviour when visibility is toggled.

1.2.0.0

Added

  • Add customModelBuilder in Composite, for custom models support. These can consume information from the parent model.
  • Add containerCreateContainerFromModel to workaround issue when updating offset during merge.
  • Add appDisableCompositing to allow requesting compositing to be disabled on startup.
  • Add optionButton and toggleButton widgets.
  • Add SetFocusOnKey and MoveFocusFromKey actions in Composite. Deprecate setFocusOnKey function. This function depended on information in WidgetEnv, which can become stale if several actions are returned at once. This change reduces confusion regarding order of operations and widget tree state.

Fixed

  • Keep old Composite root if model has not changed. This does not affect previous code, it is only relevant with new features.
  • Generate IgnoreParentEvents request from widgets that handle Wheel event (avoids issues with scroll widget moving the content).
  • Do not run tests which depend on SDL’s video subsystem to be available unless an environment variable is defined. This allows for (hopefully) running tests on Hackage and, later on, deploying to Stackage.

Changed

  • Composite requests RenderOnce when model changes.
  • Composite now renders decorations if a style is set.
  • ZStack’s onlyTopActive now follows the same pattern as other boolean combinators.
  • Shortened labels for ColorPicker.
  • Changed _weFindByPath to _weFindBranchByPath, now returning the complete branch up to the given path.
  • Change SDL’s default of requesting compositing to be disabled on startup (compositing is now left unchanged).
  • Filter following TextInput event if a single letter binding matched previously on keystroke.

1.1.1.0

Added

  • appInvertWheelX and appInvertWheelY configuration options.

Fixed

  • Horizontal wheel/trackpad scrolling on Linux.
  • Scroll: do not use direction argument to modify wheel/trackpad direction (event provides correct value).
  • Only replace composite model with user model on init and merge.

1.1.0.0

Added

  • sizeUpdater helpers. Support multiple handlers in box, grid and stack.
  • dpr field to WidgetEnv.
  • RunInRenderThread to support initialization of low level OpenGL resources.
  • OpenGL example.
  • containerDrawDecorations. Simplify button/externalLink internals.
  • ThemeState entries for future optionButton and toggleButton widgets.
  • singleDrawDecorations. Make it consistent with Container.

Fixed

  • Reduce memory usage by sharing wreq session among image widget instances.
  • Set correct WidgetEnv viewport from scroll (it looked good because of scissoring).
  • Fix issue with scrollbars using child coordinates for detecting clicks.

1.0.0.3

Added

  • Add Nix and GitHub Actions support (thanks @smunix!).

Fixed

  • Consume and forward all available messages from Producers on each cycle.
  • Fix space leak when rebuilding the UI or handling events.

1.0.0.2

Added

  • Add appRenderOnMainThread option.

Changed

  • Use the recently published nanovg-0.8.0.0 from Hackage, instead of the version from the PR’s commit.

1.0.0.1

Fixed

  • Fix Haddocks for widget configuration types.

1.0.0.0

Initial public release

  • Supports Windows, Linux and macOS