Safe Haskell | None |
---|
This module provides support for user interface items.
UI items are the building blocks of user interfaces. Typical items are widgets and windows. A UI item may contain another item or a UI circuit which is a system of UI items. An example of the former case is a window which contains a single widget. An example of the latter case is a box widget which contains an arbitrary number of other widgets.
- data UIItem item uiBackend era i o
- item :: (nativeItem -> IO ()) -> (Placement item uiBackend -> IO nativeItem) -> Interfacing nativeItem era i o -> UIItem item uiBackend era i o
- data Brick item uiBackend iOptRecord oRecord
- brick :: (Item item, OptRecord iOptRecord, Record SignalKind (All iOptRecord), Record SignalKind oRecord) => ContextConsumerRecord nativeItem (All (CommonInputOptRecord item)) -> ContextProducerRecord nativeItem (CommonOutputRecord item) -> (nativeItem -> IO ()) -> (Placement item uiBackend -> IO nativeItem) -> ContextConsumerRecord nativeItem (All iOptRecord) -> ContextProducerRecord nativeItem oRecord -> Brick item uiBackend iOptRecord oRecord
- just :: (Record SignalKind extIRecord, Record SignalKind extORecord, Subrecord extIRecord (All iOptRecord `Cat` All (CommonInputOptRecord item)), Subrecord (Required iOptRecord `Cat` Required (CommonInputOptRecord item)) extIRecord, Subrecord extORecord (oRecord `Cat` CommonOutputRecord item), UIComp uiComp) => Brick item uiBackend iOptRecord oRecord -> uiComp item uiBackend era (SignalRecord era extIRecord) (SignalRecord era extORecord)
- data Box innerUIComp innerItem item uiBackend iOptRecord oRecord
- box :: (UIComp innerUIComp, Item item, OptRecord iOptRecord, Record SignalKind (All iOptRecord), Record SignalKind oRecord) => ContextConsumerRecord nativeItem (All (CommonInputOptRecord item)) -> ContextProducerRecord nativeItem (CommonOutputRecord item) -> (nativeItem -> IO ()) -> (Placement item uiBackend -> IO nativeItem) -> (nativeItem -> Placement innerItem uiBackend) -> ContextConsumerRecord nativeItem (All iOptRecord) -> ContextProducerRecord nativeItem oRecord -> Box innerUIComp innerItem item uiBackend iOptRecord oRecord
- with :: (Record SignalKind extIRecord, Record SignalKind extORecord, Subrecord extIRecord (All iOptRecord `Cat` All (CommonInputOptRecord item)), Subrecord (Required iOptRecord `Cat` Required (CommonInputOptRecord item)) extIRecord, Subrecord extORecord (oRecord `Cat` CommonOutputRecord item), UIComp uiComp) => Box innerUIComp innerItem item uiBackend iOptRecord oRecord -> innerUIComp innerItem uiBackend era innerI innerO -> uiComp item uiBackend era (SignalRecord era extIRecord `With` innerI) (SignalRecord era extORecord `With` innerO)
- data With base inner = base With inner
- class (OptRecord (CommonInputOptRecord item), Record SignalKind (All (CommonInputOptRecord item)), Record SignalKind (CommonOutputRecord item)) => Item item where
- type CommonInputOptRecord item :: * -> *
- type CommonOutputRecord item :: * -> *
- type family Placement item uiBackend :: *
- data Widget
- data Window
- data IsEnabled = IsEnabled
User interface items in general
data UIItem item uiBackend era i o Source
The type of user interface items.
The item
parameter is a phantom parameter which denotes the kind of the item. It should
be an instance of Item
.
:: (nativeItem -> IO ()) | an action which makes a native item visible |
-> (Placement item uiBackend -> IO nativeItem) | an action which creates a native item depending on a placement for the item |
-> Interfacing nativeItem era i o | the interface specification for the item |
-> UIItem item uiBackend era i o |
Constructs an item using functionality of an underlying imperative library.
The nativeItem
type variable represents an item type of the underlying library.
Bricks
data Brick item uiBackend iOptRecord oRecord Source
A brick is an era-independent item with a comfortable record-based interface.
The parameter iOptRecord
is an optionality record and therefore specifies a set of
required and a set of optional fields. When the brick is used, the input fields can be given
in any order and optional fields can be left out. Similarily, oRecord
specifies a set of
fields (without optionalities) of whom not all have to be utilized by the user of the brick.
A brick has additional input and output fields which are not explicitely mentioned in its
type. For an item kind item
, they are given by
and
CommonInputOptRecord
item
. Therefore, it is possible to have inputs and outputs common
for all bricks of a certain item kind.
CommonOutputRecord
item
:: (Item item, OptRecord iOptRecord, Record SignalKind (All iOptRecord), Record SignalKind oRecord) | |
=> ContextConsumerRecord nativeItem (All (CommonInputOptRecord item)) | consumers of those inputs which are common to all bricks of the respective item kind |
-> ContextProducerRecord nativeItem (CommonOutputRecord item) | producers of those outputs which are common to all bricks of the respective item kind |
-> (nativeItem -> IO ()) | an action which makes a native item visible |
-> (Placement item uiBackend -> IO nativeItem) | an action which creates a native item depending on a placement for the item |
-> ContextConsumerRecord nativeItem (All iOptRecord) | consumers of those inputs which are specific to this brick |
-> ContextProducerRecord nativeItem oRecord | producers of those outputs which are specific to this brick |
-> Brick item uiBackend iOptRecord oRecord |
Constructs a brick.
just :: (Record SignalKind extIRecord, Record SignalKind extORecord, Subrecord extIRecord (All iOptRecord `Cat` All (CommonInputOptRecord item)), Subrecord (Required iOptRecord `Cat` Required (CommonInputOptRecord item)) extIRecord, Subrecord extORecord (oRecord `Cat` CommonOutputRecord item), UIComp uiComp) => Brick item uiBackend iOptRecord oRecord -> uiComp item uiBackend era (SignalRecord era extIRecord) (SignalRecord era extORecord)Source
Converts a brick into an ordinary user interface component.
The brick is first converted into a UI item which is then converted into the resulting
component by applying fromUIItem
.
The type of just
states the following properties of the resulting component:
- The input record covers only fields which are input fields according to the type of the brick or are common input fields of all items of the respective kind.
- The input record covers all input fields which are marked as required.
- The output record covers only fields which are output fields according to the type of the brick or are common output fields of all items of the respective kind.
- The order of fields is arbitrary.
- The component is not tied to a specific era.
- All input and output signals use the same era as the component.
Dropping certain input or output fields results in the corresponding connectors not being executed.
To make the type variables extIRecord
and extORecord
non-ambiguous, the lists of input
and output field names have to be known at the call site. For the output field names, this
is usually done via pattern matching.
Boxes
data Box innerUIComp innerItem item uiBackend iOptRecord oRecord Source
A box is a container which can be transformed into an item by putting a user interface component into it.
The component which is put into a box is called the inner component of that box. The
parameters innerItem
and item
tell the type of the inner component and the item kind, it
is based on.
The interface of an item made from a box is similar to that of an item made from a brick. The only difference is that the interface of the box item covers also the input and the output of the inner component.
:: (UIComp innerUIComp, Item item, OptRecord iOptRecord, Record SignalKind (All iOptRecord), Record SignalKind oRecord) | |
=> ContextConsumerRecord nativeItem (All (CommonInputOptRecord item)) | consumers of those inputs which are common to all bricks of the respective item kind |
-> ContextProducerRecord nativeItem (CommonOutputRecord item) | producers of those outputs which are common to all bricks of the respective item kind |
-> (nativeItem -> IO ()) | an action which makes a native item visible |
-> (Placement item uiBackend -> IO nativeItem) | an action which creates a native item depending on a placement for the item |
-> (nativeItem -> Placement innerItem uiBackend) | conversion from a native item into the placement for its inner items |
-> ContextConsumerRecord nativeItem (All iOptRecord) | consumers of those inputs which are specific to this box |
-> ContextProducerRecord nativeItem oRecord | producers of those outputs which are specific to this box |
-> Box innerUIComp innerItem item uiBackend iOptRecord oRecord |
Constructs a box.
with :: (Record SignalKind extIRecord, Record SignalKind extORecord, Subrecord extIRecord (All iOptRecord `Cat` All (CommonInputOptRecord item)), Subrecord (Required iOptRecord `Cat` Required (CommonInputOptRecord item)) extIRecord, Subrecord extORecord (oRecord `Cat` CommonOutputRecord item), UIComp uiComp) => Box innerUIComp innerItem item uiBackend iOptRecord oRecord -> innerUIComp innerItem uiBackend era innerI innerO -> uiComp item uiBackend era (SignalRecord era extIRecord `With` innerI) (SignalRecord era extORecord `With` innerO)Source
Puts an inner component into a box and converts the result into an ordinary user interface component.
This function is very similar to just
. In contrast to just
, it takes the inner component
as an additional argument and extends the input and output of the resulting component with
the input and output of the inner component. Note that the era of the inner component equals
the era of the resulting component.
Applications of with
are usually written infix.
An input or output, extended with the input or output of an inner component.
base With inner |
Kinds of items
class (OptRecord (CommonInputOptRecord item), Record SignalKind (All (CommonInputOptRecord item)), Record SignalKind (CommonOutputRecord item)) => Item item Source
The class of all kinds of items.
Instances of this class serve as phantom parameters of UIItem
, UICircuit
and others.
type CommonInputOptRecord item :: * -> *Source
Inputs which are shared by all items of the respective kind.
type CommonOutputRecord item :: * -> *Source
Outputs which are shared by all items of the respective kind.
type family Placement item uiBackend :: *Source
The family of item placement types.
A placement says where to place a user interface item, for example, to place a widget in a
certain box or a window at the top level. Graphics.UI.Grapefruit.Item
declares two
instances of Placement
. Placement
is equivalent to
Widget
uiBackend
and WidgetPlacement
uiBackendPlacement
is equivalent to
Window
uiBackend
.
WindowPlacement
uiBackend
The widget item kind.
A widget is an item which resides inside a window. Examples of widgets are push buttons, labels and boxes (which contain other widgets themselves).
The window item kind.
A window is an item which resides directly on the desktop and typically has a frame with a title and some control buttons. Examples of windows are application windows and dialogs.