-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Library which aids constructing generic (SYB3-based) widgets
--   
--   Basic building block for creating libraries which can generically
--   construct widgets. That is, the library cannot by it self construct
--   any widgets, but makes it easier to build libraries which can. This
--   also means that the library is not dependent on any particular GUI
--   library.
@package SybWidget
@version 0.4.0


-- | PriLabels are labels with a priority.
--   
--   PriLabels are usefull when widgets can have their label set multiple
--   times. This happens with genericcally created widgets. For example in:
--   
--   data Foo = Foo { someName :: Bar } data Bar = Bar Int
--   
--   widgets created from Bar instances can have labels set due it's
--   constructor name and the fieldName in Foo (someName). A GUI
--   application programmer may also set the widgets label.
--   
--   When a widget has set it's label multiple times, the priority can be
--   used to decide which label should be chosen.
module Graphics.UI.SybWidget.PriLabel

-- | Prioritized label. If two <a>PriLabel</a> can be used for some
--   component, then the one with highest priority is used.
data PriLabel
PriLabel :: Priority -> String -> PriLabel
priority :: PriLabel -> Priority
labelString :: PriLabel -> String

-- | The label priority.
data Priority
BadConstr :: Priority
GoodConstr :: Priority
FieldName :: Priority
UserDefined :: Priority
badConstrLabel :: String -> PriLabel
goodConstrLabel :: String -> PriLabel
fieldNameLabel :: String -> PriLabel
userDefinedLabel :: String -> PriLabel

-- | Choose label with highest priority. If equal then choose the left
--   |(first parameter) label.
bestLabel :: PriLabel -> PriLabel -> PriLabel

-- | Humanized label strings, by turning labels like <a>someLabelName</a>
--   into <a>Some label name</a>.
humanizeLabel :: PriLabel -> PriLabel

-- | Creates a default (lowest priority) PriLabel
defaultLabel :: String -> PriLabel
labelless :: PriLabel
instance Show Priority
instance Ord Priority
instance Eq Priority
instance Bounded Priority
instance Enum Priority
instance Show PriLabel
instance Eq PriLabel


-- | This module reexports the SYB3 library.
--   
--   It also makes some extensions to SYB3, namely getFieldFun and
--   setFieldFun.
module Graphics.UI.SybWidget.MySYB

-- | Returns a set of constructors. This function is undefined for Int,
--   Float, Double and Char
constructors :: (Data ctx a) => Proxy ctx -> a -> [Constr]

-- | A get field fun: parent -&gt; child
getFieldFun :: (Typeable a, Data ctx m) => Proxy ctx -> Int -> m -> a

-- | A set field fun: parent -&gt; child -&gt; parent
setFieldFun :: (Data ctx m, Typeable a) => Proxy ctx -> Int -> m -> a -> m

-- | Function is similar to show, except that strings are shown without
--   escaped ".
gToString :: (Show a, Typeable a) => a -> String


-- | Contains functions to automatically create instances from data type
--   definitions.
module Graphics.UI.SybWidget.InstanceCreator

-- | Generates all possible instances of a, while using no more than n
--   levels of recursion. Each subtype requires another level of recursion.
--   For example:
--   
--   Branch (Branch Leaf 17) (Leaf 3)
--   
--   would require 4 levels of recursion. One for the first branch, one for
--   second branch, one for the left Leaf, and one for the Int (the
--   seventeen). The right part of the first branch (Left 3) would be done
--   in two recursions.
gGenUpTo :: (Data ctx a) => Proxy ctx -> Int -> [a]

-- | Creates an instance of a Haskell type. For this to work the compiler
--   must be able to deduce the type from the callee's context.
createInstance :: (Data ctx a) => Proxy ctx -> Maybe a

-- | Like <a>createInstance</a> excepts it uses a phantom type to elicit
--   the correct type to return.
createInstance' :: (Data ctx a) => Proxy ctx -> a -> Maybe a

-- | Creates an instance with a specific constructor.
instanceFromConstr :: (Data ctx a) => Proxy ctx -> Constr -> Maybe a


-- | Helper functions to creates generic widgets.
--   
--   The <i>parent type</i>, which is refered thoughout the module
--   documentation, could also be called the enclosing type. For example
--   given:
--   
--   data Foo = Foo Bar Boo
--   
--   then the parent type of Bar and Boo will be Foo.
module Graphics.UI.SybWidget.SybOuter
class OuterWidget outer
updateLabel :: (OuterWidget outer) => (PriLabel -> PriLabel) -> outer a -> outer a

-- | Widget with getter and setter.
data FullPart wid parent b
FullPart :: wid b -> (parent -> b) -> (parent -> b -> parent) -> FullPart wid parent b
partWidget :: FullPart wid parent b -> wid b

-- | Extracts this parts value from the parent type
partGetter :: FullPart wid parent b -> parent -> b

-- | Sets this value on a parent type
partSetter :: FullPart wid parent b -> parent -> b -> parent

-- | Creates getter and setter command for a Spliter. That is, it will
--   create two function which sets/gets all the parts of the Spliter.
mkGetterSetter :: (Monad getM, Monad setM, Data ctx parent) => Proxy ctx -> (forall a. wid a -> getM a) -> (forall a. wid a -> a -> setM ()) -> Spliter wid parent parent -> (getM parent, parent -> setM ())

-- | Creates a Spliter containing <a>FullPart</a>-s.
mkFullSpliter :: (Data ctx parent) => Proxy ctx -> Spliter part parent parent -> Spliter (FullPart part parent) parent parent

-- | Has this type exactly one constructor? This function is undefined for
--   Int, Float, Double and Char.
isSingleConstructor :: (Data ctx a) => Proxy ctx -> a -> Bool

-- | Constructs a Spliter using the constructor in the input type
--   (<tt>y</tt>). If <tt>y</tt> has field labels, the individual parts are
--   updated with the field label names.
mkSpliterSingleConstr :: (Data ctx a, OuterWidget outer) => Proxy ctx -> (forall a1. (Data ctx a1) => a1 -> outer a1) -> a -> Spliter outer a a

-- | The Splitter type contains the splitting of a type into a Constructor
--   and Parts.
--   
--   The Spliter structure is reverse, in the sense that a type C a b c,
--   where C is a constructor and a, b and c is values to the constructor,
--   will be represented as (Splitter type in brackets):
--   
--   (Part (part c) { C a b c } (Part (part b) { c -&gt; C a b c } (Part
--   (part a) { b -&gt; c -&gt; C a b c } (Constructor C)))) { a -&gt; b
--   -&gt; c -&gt; C a b c }
data Spliter part parent a
Constructor :: a -> Spliter part parent a
Part :: (part b) -> (Spliter part parent (b -> a)) -> Spliter part parent a

-- | Maps each part in a Spliter type.
mapParts :: (forall q. (Typeable q) => partA q -> partB q) -> Spliter partA parent parent -> Spliter partB parent parent

-- | Monadic version of mapParts. The mapping is done deep first. It is
--   done deep first as we will then process the elements in the field
--   order. E.g. if the spliter is based on the:
--   
--   data Foo = Foo Int Double
--   
--   then the Int will be processed first, then the Double.
mapPartsM :: (Monad m) => (forall q. (Typeable q) => partA q -> m (partB q)) -> Spliter partA parent parent -> m (Spliter partB parent parent)

-- | Like mapPartsM, except that processing of certain parts can be
--   delayed. The first parameter decides which parts processing should be
--   delayed.
--   
--   This is usefull when fine grained control of execution order is
--   desired.
mapPartsMDelay :: (Monad m) => (forall q. (Typeable q) => partA q -> Bool) -> (forall q. (Typeable q) => partA q -> m (partB q)) -> Spliter partA parent parent -> m (Spliter partB parent parent)

-- | Transforms a spiltter to a list. The list will follow the constructor
--   fields order.
spliterToList :: (forall c. (Typeable c) => part c -> abstractPart) -> Spliter part a b -> [abstractPart]

-- | Zips a list with a spliter using <tt>f</tt>. The list members are
--   zipped in the order of the constructor fields. If not enough list
--   members are present the rest of the spilter is un-mapped.
zipSpliterWithList :: (forall q. (Typeable q) => a -> part q -> part q) -> [a] -> Spliter part m n -> Spliter part m n

-- | A map from from constructors to values. Used as memory when creating
--   multi-constructor widgtes. This way each time the constructor is
--   changed, we can look in the map to see if we had a privious value for
--   the new constructor.
mkConstrValMap :: (Data ctx a, RefMonad m ref) => Proxy ctx -> a -> m (ConstrValMap ref ctx a)

-- | Updates the map with a new value.
updateConstrValMap :: (Data ctx a, RefMonad m ref) => ConstrValMap ref ctx a -> a -> m ()

-- | Look in the map to see if we have a value for the constructor.
lookupValue :: (Data ctx a, RefMonad m ref) => ConstrValMap ref ctx a -> Constr -> m (Maybe a)

-- | Like <a>lookupValue</a>, except if it cannot find a value in the map
--   one will be created using <a>createInstance</a>.
alwaysValue :: (Data ctx a, RefMonad m ref) => ConstrValMap ref ctx a -> Constr -> m a
data ConstrValMap ref ctx a

-- | Returns a getter and setter command for numeric types. The getter and
--   setter are applicable when numeric types are represented using String.
--   The function uses <a>sybRead</a> and <a>sybShow</a> to parse and
--   construct strings. In this way we avoid dependency on Show and Read
--   type classes.
--   
--   It is generally a good idea to avoid dependencies. And it can be
--   essential to avoid dependency on Show and Read, if we want to
--   implement generic widgets for functions, as we cannot define Show and
--   Read for those.
--   
--   It could be argued that Int, Double, Float, .. all are instances of
--   Read and Show, and it therefore unneccesary to avoid using these
--   classes. However, SYB will force any dependencies for these types on
--   all types for which we want generic functionality. SYB does that as we
--   make one piece of code handling all integer-like types, and one
--   handling all real-numbered types. Thus, we only have access to the
--   classes that are in the generic class's context.
--   
--   The getter uses the last legitimate value when the input string is
--   non-parseable.
numericGetSet :: (Data ctx a, RefMonad m ref) => Proxy ctx -> a -> m (String -> m a, a -> m String)

-- | Avoid dependency on the Read class, by using SYB to read a value. It
--   has _only_ been tested for numeric types.
--   
--   See also <a>numericGetSet</a>.
sybRead :: (Data ctx a) => Proxy ctx -> a -> String -> Maybe a

-- | Avoid dependency on the Show class, by using SYB to show a value. It
--   has _only_ been tested for numeric types.
--   
--   See also <a>numericGetSet</a>.
sybShow :: (Data ctx a) => Proxy ctx -> a -> String

-- | Creates a default label for a type.
typeLabel :: (Data ctx a) => Proxy ctx -> a -> PriLabel


-- | Reexports all the SybWidget modules.
module Graphics.UI.SybWidget