Monomer.Widgets.Container

Helper for creating widgets with children elements.

Re-exported modules

module Monomer.Core

module Monomer.Core.Combinators

module Monomer.Event

module Monomer.Graphics

module Monomer.Widgets.Util

Configuration

type ContainerGetBaseStyle s e

Arguments

 = GetBaseStyle s e

The base style for a new node.

Returns the base style for this type of widget.

Usually this style comes from the active theme.

type ContainerGetCurrentStyle s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> StyleState

The active style for the node.

Returns the active style for this type of widget. It depends on the state of the widget, which can be:

• Basic
• Hovered
• Focused
• Hovered and Focused
• Active
• Disabled

In general there's no needed to override it, except when the widget does not use the full content rect.

An example can be found in Monomer.Widgets.Containers.Tooltip.

type ContainerUpdateCWenvHandler s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> WidgetNode s e

The child node.

-> Int

The index of the node.

-> WidgetEnv s e

The updated widget environment.

Updates the widget environment before passing it down to children. This function is called during the execution of all the widget functions. Useful for restricting viewport or modifying other kind of contextual information.

An example can be found in Monomer.Widgets.Containers.ThemeSwitch.

type ContainerInitHandler s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> WidgetResult s e

The result of the init operation.

Initializes the given node. This could include rebuilding the widget in case internal state needs to use model/environment information, generate user events or make requests to the runtime.

An example can be found in Monomer.Widgets.Containers.SelectList.

Most of the current containers serve layout purposes and don't need a custom init.

type ContainerInitPostHandler s e a

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> a

The current state of the widget node.

-> WidgetResult s e

The result after children have been initialized.

-> WidgetResult s e

The result of the init post operation.

Allows making further operations after children have been initialized.

Note: if state was modified on containerInit, you should use the new state provided as an argument, since the state referenced in the closure will be outdated.

type ContainerMergeChildrenReqHandler s e a

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> WidgetNode s e

The previous widget node.

-> a

The state of the previous widget node.

-> Bool

True if widget is needed.

Returns whether merge is required for children. It's mostly used for performance optimization.

An example can be found in Monomer.Widgets.Containers.SelectList.

type ContainerMergeHandler s e a

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> WidgetNode s e

The previous widget node.

-> a

The state of the previous widget node.

-> WidgetResult s e

The result of the merge operation.

Merges the current node with the node it matched with during the merge process. Receives the newly created node (whose *init* function is not called), the previous node and the state extracted from that node. This process is widget dependent, and may use or ignore the previous state depending on newly available information.

In general, you want to at least keep the previous state unless the widget is stateless or only consumes model/environment information.

Examples can be found in Monomer.Widgets.Containers.Fade and Monomer.Widgets.Containers.Tooltip. On the other hand, Monomer.Widgets.Containers.Grid does not need to override merge since it's stateless.

type ContainerMergePostHandler s e a

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> WidgetNode s e

The previous widget node.

-> a

The state of the previous widget node.

-> a

The current state of the widget node.

-> WidgetResult s e

The result after children have been merged.

-> WidgetResult s e

The result of the merge post operation.

Allows making further operations after children have been merged.

Examples can be found in Monomer.Widgets.Containers.SelectList and Monomer.Widgets.Containers.ZStack.

Note: if state was modified during merge, you should use the new state provided as an argument, since the state referenced in the closure will be outdated.

type ContainerDisposeHandler s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> WidgetResult s e

The result of the dispose operation.

Disposes the current node. Only used by widgets which allocate resources during init or merge, and will usually involve requests to the runtime.

An example can be found Monomer.Widgets.Containers.Dropdown.

type ContainerFindNextFocusHandler s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> FocusDirection

The direction in which focus is moving.

-> Path

The start path from which to search.

-> Seq (WidgetNode s e)

The next focusable node info.

Returns the next focusable node. What next/previous is, depends on how the container works. Moving right -> bottom is usually considered forward.

type ContainerFindByPointHandler s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> Path

The start path from which to search.

-> Point

The point to test for.

-> Maybe Int

The hovered child index, if any.

Returns the currently hovered widget, if any. If the widget is rectangular and uses the full content area, there is not need to override this function.

An example can be found Monomer.Widgets.Containers.Dropdown.

type ContainerFilterHandler s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> Path

The target path of the event.

-> SystemEvent

The SystemEvent to handle.

-> Maybe (Path, SystemEvent)

The optional modified event/target.

Receives a System event and, optionally, modifies the event, its target, or cancels the event propagation by returning null.

Examples can be found in Monomer.Widgets.Containers.Base.LabeledItem.

type ContainerEventHandler s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> Path

The target path of the event.

-> SystemEvent

The SystemEvent to handle.

-> Maybe (WidgetResult s e)

The result of handling the event, if any.

Receives a System event and, optionally, returns a result. This can include an updated version of the widget (in case it has internal state), user events or requests to the runtime.

Examples can be found in Monomer.Widgets.Containers.Draggable and Monomer.Widgets.Containers.Keystroke.

type ContainerMessageHandler s e

Arguments

 = forall i. Typeable i

=> WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> Path

The target path of the message.

-> i

The message to handle.

-> Maybe (WidgetResult s e)

The result of handling the message, if any.

Receives a message and, optionally, returns a result. This can include an updated version of the widget (in case it has internal state), user events or requests to the runtime. There is no validation regarding the message type, and the widget should take care of _casting_ to the correct type using "Data.Typeable.cast"

Examples can be found in Monomer.Widgets.Containers.Fade and Monomer.Widgets.Containers.Scroll.

type ContainerGetSizeReqHandler s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> Seq (WidgetNode s e)

The children widgets

-> (SizeReq, SizeReq)

The horizontal and vertical requirements.

Returns the preferred size for the widget. This size should not include border and padding; those are added automatically by Container.

This is called to update WidgetNodeInfo only at specific times.

Examples can be found in Monomer.Widgets.Containers.Grid and Monomer.Widgets.Containers.Stack.

type ContainerResizeHandler s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> Rect

The new viewport.

-> Seq (WidgetNode s e)

The children widgets

-> (WidgetResult s e, Seq Rect)

The result of resizing the widget.

Resizes the widget to the provided size. If the widget state does not depend on the viewport size, this function does not need to be overriden.

Examples can be found in Monomer.Widgets.Containers.Grid and Monomer.Widgets.Containers.Stack.

type ContainerRenderHandler s e

Arguments

 = WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> Renderer

The renderer, providing low level drawing functions.

-> IO ()

The IO action with rendering instructions.

Renders the widget's content using the given Renderer. In general, this method needs to be overriden. There are two render methods: one runs before children, the other one after.

Examples can be found in Monomer.Widgets.Containers.Draggable and Monomer.Widgets.Containers.Scroll.

data Container s e a

Interface for Container widgets.

Constructors

Container

Fields

• containerAddStyleReq :: Bool

  True if border and padding should be added to size requirement. Defaults to True.

• containerChildrenOffset :: Maybe Point

  Offset to apply to children. This not only includes rendering, but also updating SystemEvents and all coordinate related functions.

• containerChildrenScissor :: Maybe Rect

  Scissor to apply to child widgets. This is not the same as the widget enabled by containerUseScissor

• containerDrawDecorations :: Bool

  If True, the container will render its background and border. In some cases passing rendering control to children is useful. Defaults to True.

• containerLayoutDirection :: LayoutDirection

  The layout direction generated by this widget. If one is indicated, it can be used by widgets such as Monomer.Widgets.Singles.Spacer

• containerIgnoreEmptyArea :: Bool

  If True, when none of the children is found under the pointer, indicates an event will not be handled. If False, the parent (i.e., current) widget will be returned. This is useful when using zstack and wanting for events to be handled in lower layers.

• containerUseCustomCursor :: Bool

  True if style cursor should be ignored. If it's False, cursor changes need to be handled in custom code. Defaults to False.

• containerUseCustomSize :: Bool

  If true, it will ignore extra space assigned by the parent container, but it will not use more space than assigned. Defaults to False.

• containerUseChildrenSizes :: Bool

  If true, it will accept the size requested by children, restricted to the space already assigned.

• containerUseScissor :: Bool

  True if automatic scissoring needs to be applied. Defaults to False.

• containerGetBaseStyle :: ContainerGetBaseStyle s e

  Returns the base style for this type of widget.

• containerGetCurrentStyle :: ContainerGetCurrentStyle s e

  Returns the current style, depending on the status of the widget.

• containerUpdateCWenv :: ContainerUpdateCWenvHandler s e

  Updates the widget environment before passing it down to children.

• containerInit :: ContainerInitHandler s e

  Initializes the given node.

• containerInitPost :: ContainerInitPostHandler s e a

  Allow for extra steps after children are initialized.

• containerMergeChildrenReq :: ContainerMergeChildrenReqHandler s e a

  Returns whether merge is required for children.

• containerMerge :: ContainerMergeHandler s e a

  Merges the node with the node it matched with during the merge process.

• containerMergePost :: ContainerMergePostHandler s e a

  Allow for extra steps after children are merged.

• containerDispose :: ContainerDisposeHandler s e

  Disposes the current node.

• containerFindNextFocus :: ContainerFindNextFocusHandler s e

  Returns the next focusable node.

• containerFindByPoint :: ContainerFindByPointHandler s e

  Returns the currently hovered widget, if any.

• containerFilterEvent :: ContainerFilterHandler s e

  Receives a System event and, optionally, filters/modifies it.

• containerHandleEvent :: ContainerEventHandler s e

  Receives a System event and, optionally, returns a result.

• containerHandleMessage :: ContainerMessageHandler s e

  Receives a message and, optionally, returns a result.

• containerGetSizeReq :: ContainerGetSizeReqHandler s e

  Returns the preferred size for the widget.

• containerResize :: ContainerResizeHandler s e

  Resizes the widget to the provided size.

• containerRender :: ContainerRenderHandler s e

  Renders the widget's content. This runs before childrens' render.

• containerRenderAfter :: ContainerRenderHandler s e

  Renders the widget's content. This runs after childrens' render.

Instances

Default (Container s e a)

Defined in Monomer.Widgets.Container

Methods

def :: Container s e a

updateWenvOffset

Arguments

:: Container s e a

The container config

-> WidgetEnv s e

The widget environment.

-> WidgetNode s e

The widget node.

-> Rect

The target viewport.

-> WidgetEnv s e

THe updated widget environment.

Helper function that updates widget environment based on current container information. In case the created container needs to pass information down using wenv, it should call this function first and update the resulting wenv.

Constructors

createContainer :: WidgetModel a => a -> Container s e a -> Widget s e

Creates a widget based on the Container infrastructure. An initial state and the Container definition need to be provided. In case internal state is not needed, () can be provided. Using the def instance as a starting point is recommended to focus on overriding only what is needed:

widget = createContainer () def {
  containerRender = ...
}