Monomer.Widgets.Composite

Composite widget. Main glue between all the other widgets, also acts as the main app widget. Composite allows to split an application into reusable parts without the need to implement a lower level widget. It can comunicate with its parent component by reporting events.

Requires two functions:

• UI Builder: creates the widget tree based on the provided Widget Environment and model. This widget tree is made of other widgets, in general combinations of containers and singles.
• Event Handler: processes user defined events which are raised by the widgets created when building the UI.

Composite is discussed in detail in the tutorials.

Re-exported modules

module Monomer.Core

module Monomer.Event

module Monomer.Widgets.Util

Configuration

data CompositeCfg s e sp ep

Configuration options for composite:

• onInit: event to raise when the widget is created. Useful for initializing required resources.
• onDispose: event to raise when the widget is disposed. Useful for freeing acquired resources.
• onResize: event to raise when the size of the widget changes.
• onChange: event to raise when the model changes. The value passed to the provided event is the previous version of the model. The current version of the model is always available as a parameter in the _handleEvent_ function.
• onChangeReq: WidgetRequest to generate when the model changes.
• onEnabledChange: event to raise when the enabled status changes.
• onVisibleChange: event to raise when the visibility changes.
• mergeRequired: indicates if merging is necessary for this widget. In case the UI build process references information outside the model, it can be used to signal that merging is required even if the model has not changed. It can also be used as a performance tweak if the changes do not require rebuilding the UI.
• compositeMergeReqs: functions to generate WidgetRequests during the merge process. Since merge is already handled by Composite (by merging its tree), this is complementary for the cases when more control, and the previous version of the widget tree, is required. For example, it is used in Confirm to set the focus on its Accept button when visibility is restored (this usually means it was brought to the front in a zstack, and the visibility flag of the previous version needs to be checked).
• compositeMergeModel: Allows updating the composite model with information from the parent model. Useful when the composite needs a more complex model than what the user is binding.

Instances

Monoid (CompositeCfg s e sp ep)

Defined in Monomer.Widgets.Composite

Methods

mempty :: CompositeCfg s e sp ep

mappend :: CompositeCfg s e sp ep -> CompositeCfg s e sp ep -> CompositeCfg s e sp ep

mconcat :: [CompositeCfg s e sp ep] -> CompositeCfg s e sp ep

Semigroup (CompositeCfg s e sp ep)

Defined in Monomer.Widgets.Composite

Methods

(<>) :: CompositeCfg s e sp ep -> CompositeCfg s e sp ep -> CompositeCfg s e sp ep

sconcat :: NonEmpty (CompositeCfg s e sp ep) -> CompositeCfg s e sp ep

stimes :: Integral b => b -> CompositeCfg s e sp ep -> CompositeCfg s e sp ep

Default (CompositeCfg s e sp ep)

Defined in Monomer.Widgets.Composite

Methods

def :: CompositeCfg s e sp ep

WidgetEvent e => CmbOnDispose (CompositeCfg s e sp ep) e

Defined in Monomer.Widgets.Composite

Methods

onDispose :: e -> CompositeCfg s e sp ep

CmbOnEnabledChange (CompositeCfg s e sp ep) e

Defined in Monomer.Widgets.Composite

Methods

onEnabledChange :: e -> CompositeCfg s e sp ep

WidgetEvent e => CmbOnInit (CompositeCfg s e sp ep) e

Defined in Monomer.Widgets.Composite

Methods

onInit :: e -> CompositeCfg s e sp ep

CmbOnVisibleChange (CompositeCfg s e sp ep) e

Defined in Monomer.Widgets.Composite

Methods

onVisibleChange :: e -> CompositeCfg s e sp ep

WidgetEvent e => CmbOnChange (CompositeCfg s e sp ep) s e

Defined in Monomer.Widgets.Composite

Methods

onChange :: (s -> e) -> CompositeCfg s e sp ep

CmbOnDisposeReq (CompositeCfg s e sp ep) s e

Defined in Monomer.Widgets.Composite

Methods

onDisposeReq :: WidgetRequest s e -> CompositeCfg s e sp ep

CmbOnInitReq (CompositeCfg s e sp ep) s e

Defined in Monomer.Widgets.Composite

Methods

onInitReq :: WidgetRequest s e -> CompositeCfg s e sp ep

CmbOnResize (CompositeCfg s e sp ep) e Rect

Defined in Monomer.Widgets.Composite

Methods

onResize :: (Rect -> e) -> CompositeCfg s e sp ep

CmbOnChangeReq (CompositeCfg s e sp ep) s e s

Defined in Monomer.Widgets.Composite

Methods

onChangeReq :: (s -> WidgetRequest s e) -> CompositeCfg s e sp ep

CmbMergeRequired (CompositeCfg s e sp ep) (WidgetEnv s e) s

Defined in Monomer.Widgets.Composite

Methods

mergeRequired :: (WidgetEnv s e -> s -> s -> Bool) -> CompositeCfg s e sp ep

data EventResponse s e sp ep

Response options for an event handler.

Constructors

Model s

Modifies the current model, prompting a merge.

Event e

Raises a new event, which will be handled in the same cycle.

Report ep

Raises an event that will be handled by the parent Composite.

Request (WidgetRequest s e)

Generates a WidgetRequest.

RequestParent (WidgetRequest sp ep)

Generates a WidgetRequest matching the parent Composite's type. Useful when receiving requests as configuration from the parent, since the types will not match otherwise.

SetFocusOnKey WidgetKey

Generates a request to set focus on the widget with the matching key. If the key does not exist, focus remains on the currently focused widget.

MoveFocusFromKey (Maybe WidgetKey) FocusDirection

Generates a request to move focus forward/backward, optionally indicating the key of the starting widget.

forall i.Typeable i => Message WidgetKey i

Sends a message to the given key. If the key does not exist, the message will not be delivered.

Task (TaskHandler e)

Runs an asynchronous task that will return a single result. The task is responsible for reporting errors using the expected event type. If the task crashes without returning a value, the composite will not know about it.

Producer (ProducerHandler e)

Runs an asynchronous task that will produce unlimited result. The producer is responsible for reporting errors using the expected event type. If the producer crashes without sending a value, composite will not know about it.

type CompParentModel sp = Typeable sp

Type of the parent's model

type CompositeModel s = (Eq s, WidgetModel s)

Type of the composite's model

type CompositeEvent e = WidgetEvent e

Type of the composite's event

type MergeRequired s e

Arguments

 = WidgetEnv s e

Widget environment.

-> s

Old composite model.

-> s

New composite model

-> Bool

True if merge is required.

Checks if merging the composite is required.

type MergeReqsHandler s e sp

Arguments

 = WidgetEnv s e

Widget environment.

-> WidgetNode s e

New widget node.

-> WidgetNode s e

Old widget node.

-> sp

Parent model.

-> s

Old composite model.

-> s

New composite model.

-> [WidgetRequest s e]

The list of requests.

Generates requests during the merge process.

type MergeEventsHandler s e sp

Arguments

 = WidgetEnv s e

Widget environment.

-> WidgetNode s e

New widget node.

-> WidgetNode s e

Old widget node.

-> sp

Parent model.

-> s

Old composite model.

-> s

New composite model.

-> [e]

The list of events.

Generates events during the merge process.

type MergeModelHandler s e sp

Arguments

 = WidgetEnv s e

Widget environment.

-> sp

Parent model.

-> s

Old composite model.

-> s

New composite model.

-> s

Updated composite model.

Allows updating the composite model with information from the parent model.

type EventHandler s e sp ep = WidgetEnv s e -> WidgetNode s e -> s -> e -> [EventResponse s e sp ep]

Handles a composite event and returns a set of responses.

type UIBuilder s e = WidgetEnv s e -> s -> WidgetNode s e

Creates the widget tree based on the given model.

type TaskHandler e = IO e

Asynchronous task generating a single event.

type ProducerHandler e = (e -> IO ()) -> IO ()

Asynchronous task generating multiple events.

data CompMsgUpdate

Model update function wrapped as a message.

compositeMergeReqs :: MergeReqsHandler s e sp -> CompositeCfg s e sp ep

Generate WidgetRequests during the merge process.

This function is not called during initialization; onInitReq can be used.

compositeMergeEvents :: WidgetEvent e => MergeEventsHandler s e sp -> CompositeCfg s e sp ep

Generate events during the merge process.

This function is not called during initialization; onInit can be used.

compositeMergeModel :: MergeModelHandler s e sp -> CompositeCfg s e sp ep

Allows updating the composite model with information from the parent model. Useful when the composite needs a more complex model than what the user is binding.

For example, a database record may be binded as the model from the parent, but the composite needs its own boolean flags to toggle visibility on different sections.

This function is called during both merge and init. On init, the oldModel will be equal to the current model.

Constructors

composite

Arguments

:: (CompositeModel s, CompositeEvent e, CompositeEvent ep, CompParentModel sp)

=> WidgetType

The name of the composite.

-> ALens' sp s

The lens into the parent's model.

-> UIBuilder s e

The UI builder function.

-> EventHandler s e sp ep

The event handler.

-> WidgetNode sp ep

The resulting widget.

Creates a composite taking its model from a lens into the parent model.

composite_

Arguments

:: (CompositeModel s, CompositeEvent e, CompositeEvent ep, CompParentModel sp)

=> WidgetType

The name of the composite.

-> ALens' sp s

The lens into the parent's model.

-> UIBuilder s e

The UI builder function.

-> EventHandler s e sp ep

The event handler.

-> [CompositeCfg s e sp ep]

The config options.

-> WidgetNode sp ep

The resulting widget.

Creates a composite taking its model from a lens into the parent model. Accepts config.

compositeV

Arguments

:: (CompositeModel s, CompositeEvent e, CompositeEvent ep, CompParentModel sp)

=> WidgetType

The name of the composite.

-> s

The model.

-> (s -> e)

The event to report when model changes.

-> UIBuilder s e

The UI builder function.

-> EventHandler s e sp ep

The event handler.

-> WidgetNode sp ep

The resulting widget.

Creates a composite using the given model and onChange event handler.

compositeV_

Arguments

:: (CompositeModel s, CompositeEvent e, CompositeEvent ep, CompParentModel sp)

=> WidgetType

The name of the composite.

-> s

The model.

-> (s -> e)

The event to report when model changes.

-> UIBuilder s e

The UI builder function.

-> EventHandler s e sp ep

The event handler.

-> [CompositeCfg s e sp ep]

The config options.

-> WidgetNode sp ep

The resulting widget.

Creates a composite using the given model and onChange event handler. Accepts config.

compositeD_

Arguments

:: (CompositeModel s, CompositeEvent e, CompositeEvent ep, CompParentModel sp)

=> WidgetType

The name of the composite.

-> WidgetData sp s

The model.

-> UIBuilder s e

The UI builder function.

-> EventHandler s e sp ep

The event handler.

-> [CompositeCfg s e sp ep]

The config options.

-> WidgetNode sp ep

The resulting widget.

Creates a composite providing a WidgetData instance and config.