Documentation

Main Monomer monad.

Messages received by the rendering thread.

Result from attempting to set up the secondary rendering thread.

Requirements for periodic rendering by a widget. Start time is stored to calculate next frame based on the step ms. A maximum number of repetitions may be provided.

Drag action started by WidgetId, with an associated message.

Asynchronous widget task. Results must be provided as user defined, Typeable, types. Error handling should be done inside the task and reporting handled as part of the user type.

Current state of the Monomer runtime.

Requests for main window size.

Main application config.

Initial size of the main window.

Title of the main window.

Whether the main window is resizable.

Whether the main window has a border.

Path to an icon file in BMP format.

Performs rendering on the main thread. On macOS and Windows this also disables continuous rendering on window resize, but in some Linux configurations it still works.

This configuration option was originally available to handle:

• OpenGL driver issues which prevented normal startup showing the "Unable to make GL context current" error.
• Single threaded applications (without -threaded) which cannot use forkOS.

This flag is no longer necessary for those cases, since the library will:

• Attempt to fall back to rendering on the main thread if setting up a secondary rendering thread fails.
• Will not attempt to set up a secondary rendering thread if the runtime does not support bound threads (i.e. compiled without the -threaded flag).

Max number of FPS the application will run on. It does not necessarily mean rendering will happen every frame, but events and schedules will be checked at this rate and may cause it.

Scale factor to apply to the viewport. This factor only affects the content, not the size of the window. It is applied in addition to the detected display scale factor, and can be useful if the detected value is not the desired.

Whether display scaling detection should not be attempted. If set to True, the display scale will be set to 1. This flag does not cause an effect on macOS.

Disabling auto scaling also affects window size on Linux and Windows in the cases where the library would have applied scaling. This happens because window and viewport size are the same in those operating systems. Window size can be adjusted with appWindowState.

The logic for detecting display scaling varies depending on the platform:

macOS

Scaling can be detected based on the window size and viewport size; the ratio between these two give the scaling factor.

Using window and viewport size for detecting DPI only works on macOS; both Windows and Linux return the same value for window and viewport size.

Windows

SDL_GetDisplayDPI returns the DPI of the screen, and dividing by 96 gives the scaling factor. This factor is used to scale the window size and the content.

Linux

The situation is more complex, since SDL_GetDisplayDPI does not always return valid information. There is not a practical DPI/scale detection solution that works for all combinations of Linux display servers and window managers. Even when using the most popular window managers, the scaling factor may be handled differently by the distribution (GNOME in Ubuntu). For a reference of some of the existing options for DPI scaling detection, check here: https:/wiki.archlinux.orgtitle/HiDPI.

Considering the above, when SDL_GetDisplayDPI fails, the library assumes that a screen width larger than 1920 belongs to an HiDPI display and uses a scale factor of 2. This factor is used to scale the window size and the content.

Available fonts to the application, loaded from the specified path. Specifying no fonts will make it impossible to render text.

Available fonts to the application, loaded from the bytes in memory. Specifying no fonts will make it impossible to render text.

One use case for this function is to embed fonts in the application, without the need to distribute the font files. The file-embed library can be used for this. appFontDefMemory "memoryFont" $(embedFile "dirName/fileName")

Initial theme.

Initial event, useful for loading resources.

Dispose event, useful for closing resources.

Exit event, useful for cancelling an application close event.

Resize event handler.

Defines which mouse button is considered main.

Defines which mouse button is considered secondary or context button.

Whether the horizontal wheel/trackpad movement should be inverted. In general platform detection should do the right thing.

Whether the vertical wheel/trackpad movement should be inverted. In general platform detection should do the right thing.

Whether compositing should be disabled. Linux only, ignored in other platforms. Defaults to False.

Desktop applications should leave compositing as is since disabling it may cause visual glitches in other programs. When creating games or full-screen applications, disabling compositing may improve performance.

Whether the screensaver should be disabled. Defaults to False.

Desktop applications should leave the screensaver as is since disabling it also affects power saving features, including turning off the screen. When creating games or full-screen applications, disabling the screensaver may make sense.

Generates a fingerprint from the application's model. This is used to identify whether the application should attempt to reuse the model between reloads when running in interpreted mode. Since Monomer uses the model to build the UI, reusing the old model allows for quicker iteration as the application will be restored to its previous state before being reloaded. By default, unless a fingerprint function is provided, the model will not be reused and the application will start from scratch.

The fingerprint function is applied to the user provided model on application's startup only, not on subsequent updates during the application's lifetime. When a reload occurs, the original fingerprint of the model is compared against the fingerprint of the newly provided version of the model; if they match, it is assumed that the latest version of the original model can be reused. If the fingerprint changed because its data or data type changed, the new model will be used. The rationale is that, since the model is provided by the developer at startup, if the fingerprints match then only changes to business logic/UI have been made.

A fingerprint function is used because trying to compare two different versions of a data type using its Eq instance will result in ghci crashing. Creating a string based fingerprint as soon as the instance is available is a workaround for this issue. Ideally, the fingerprint would incorporate enough information to detect type and data changes.

A simple approach is using the show function to generate the fingerprint, although in some cases it may not be possible, maybe because the type does not implement it or it does not include enough information.

An alternative to show is <https://hackage.haskell.org/package/recover-rtti recover-rtti>'s anythingToString. This function returns a string representation of the data, although it does not include the name of record fields. In general this is not an issue, but changing a field's type from Int to Long will go undetected and cause a crash.

Ideally, we could use GHC.Fingerprint.Fingerprint to detect changes in the model's type, but unfortunately this is not reliable since this fingerprint is based on the type's name only.

GHC issue with more details: https://gitlab.haskell.org/ghc/ghc/-/issues/7897. Related Hint issue: https://github.com/haskell-hint/hint/issues/31.