fltkhs 0.5.4.1 → 0.5.4.2

raw patch · 3 files changed

+135/−135 lines, 3 files

Files

• fltkhs.cabal +1/−1
• src/Graphics/UI/FLTK/LowLevel/FLTKHS.hs +128/−128
• src/Graphics/UI/FLTK/LowLevel/Widget.chs +6/−6

@@ -1,5 +1,5 @@ name : fltkhs-version : 0.5.4.1+version : 0.5.4.2 synopsis : FLTK bindings description: Low level bindings for the FLTK GUI toolkit. For installation and quick start instruction please scroll all the way down to the README. license : MIT

@@ -260,29 +260,29 @@ -- $Motivation -- This library aims to make it easy for users to build native apps that work portably across platforms. ----- I'm also very interested the user interface renaissance in the programming community,--- whether the various kinds of functional reactive programming, meta-object protocol UI's,+-- I'm also very interested in the user interface renaissance in the programming community,+-- whether the various kinds of functional reactive programming, meta-object protocol UIs, -- or something like React.js. ----- The hope is that a low-cost hassle-free way of getting a UI up and running--- without having to deal with browser, authentication and compilation issues+-- The hope is that a low-cost, hassle-free way of getting a UI up and running+-- without having to deal with browser, authentication, and compilation issues -- will make it more fun to play around with these great ideas using Haskell. -- -- == Why a native toolkit?--- Even in this era of web interfaces it is still+-- Even in this era of web interfaces, it is still -- useful to be able to make native apps. They are usually faster and have fewer -- security issues. -- -- == Why FLTK? -- - I chose FLTK because it was small enough that one person could bind the whole thing in an initial--- pass. Larger toolkits like QT, although way slicker, would require many man-years of effort.--- - FLTK is quite featureful--- - FLTK is mature and maintained, the project is about 20 years old and I have had good experiences with the community+-- pass. Larger toolkits like QT, although much slicker, would require many man-years of effort.+-- - FLTK is quite featureful.+-- - FLTK is mature and maintained. The project is about 20 years old, and I have had good experiences with the community. -- - FLTK comes with a simple but quite useful GUI builder, <https://en.wikipedia.org/wiki/FLUID Fluid> which is now able to --   generate Haskell code. See the `Fluid Support` section for more details. -- -- == What about HsQML\/WxHaskell/Gtk2Hs?--- These are all great projects and produce really nice UI's, but they all fail+-- These are all great projects and produce really nice UIs, but they all fail -- at least one of criterion listed under the __Goals__ section below. -- -- To my knowledge, as of the second quarter of 2017, no other package@@ -290,16 +290,16 @@ --  -- $Goals--- The goals of this library are to provide a low level API to the <http://fltk.org FLTK> that:+-- The goals of this library are to provide a low-level API to the <http://fltk.org FLTK> that: ----- (1) provides full coverage of the toolkit allowing the user to write GUI's in pure Haskell.--- (2) feels like it has polymorphic dispatch, meaning a single function dispatches to the right implementation based on the type of widget it is given--- (3) is /not/ monolithic, meaning new widgets can be incorporated the user's application without needing to recompile this library+-- (1) provides full coverage of the toolkit allowing the user to write GUIs in pure Haskell.+-- (2) feels like it has polymorphic dispatch, meaning a single function dispatches to the right implementation based on the type of widget it is given.+-- (3) is /not/ monolithic, meaning new widgets can be incorporated the user's application without needing to recompile this library. -- (4) is easy to install. This library has a minimum of dependencies and <http://fltk.org FLTK> itself compiles cleanly on most architectures.---     And now there is even a <https://hackage.haskell.org/package/fltkhs/docs/Graphics-UI-FLTK-LowLevel-FLTKHS.html#g:4 bundled option> where Cabal/Stack build FLTK for you behind the scenes.--- (5) allows the user to produce statically linked binaries with a minimum of external dependencies+--     And now there is a <https://hackage.haskell.org/package/fltkhs/docs/Graphics-UI-FLTK-LowLevel-FLTKHS.html#g:4 bundled option> where Cabal/Stack build FLTK for you behind the scenes.+-- (5) allows the user to produce statically linked binaries with a minimum of external dependencies. -- (6) includes a lot of <https://github.com/deech/fltkhs-demos complete> <https://github.com/deech/fltkhs-fluid-demos working> demos so that you can get up and running faster.--- (7) comes with <https://hackage.haskell.org/package/fltkhs/docs/Graphics-UI-FLTK-LowLevel-FLTKHS.html#g:15 GUI builder support> to alleviate the tedium of laying out widgets by hand+-- (7) comes with <https://hackage.haskell.org/package/fltkhs/docs/Graphics-UI-FLTK-LowLevel-FLTKHS.html#g:15 GUI builder support> to alleviate the tedium of laying out widgets by hand. -- -- $FluidSupport --@@ -308,8 +308,8 @@ -- that ships with FLTK and generates Haskell code. -- -- Now the user can drag and drop widgets into place instead of having to--- calculate coordinates and sizes by hand. Additionally arbitrary Haskell code--- can be inserted into Fluid interfaces allowing user to do most of callback+-- calculate coordinates and sizes by hand. Additionally, arbitrary Haskell code+-- can be inserted into Fluid interfaces, allowing the user to do most of the callback -- wiring directly from Fluid. -- -- The quickest way to get started is to download the@@ -320,8 +320,8 @@ -- This means using Fluid in a FLTKHS project is as simple as creating a Fluid -- interface and running 'stack build --flag fltkhs:bundled' or 'stack install --flag fltkhs:bundled'. ----- Additionally the <https://github.com/deech/fltkhs-fluid-demos fltkhs-fluid-demos> package--- comes with a number of demos that show off how Fluid integrates with FLTKS.+-- Additionally, the <https://github.com/deech/fltkhs-fluid-demos fltkhs-fluid-demos> package+-- comes with a number of demos that show how Fluid integrates with FLTKS. --  -- $Obstacles@@ -332,13 +332,13 @@ -- addressed but in the interests of full disclosure ... -- -- == Look & Feel--- The default look FLTK apps can be charitably described as /retro/. And+-- The default look of FLTK apps can be charitably described as /retro/. And -- FLTK has no support for theming since it was designed for the -- embedded domain and trades off slickness for speed, portability and -- binary size. -- -- But that doesn't mean the user is limited to the default! FLTK is quite flexible--- and it is pretty easy to change the way a widget looks and behaves but there is no+-- and it is pretty easy to change the way a widget looks and behaves, but there is no -- "theme file" that applies uniformly to all widgets in the app. -- -- == Compile Times@@ -348,19 +348,19 @@ -- -- $StackTrace ----- In a traditional callback-heavy API such as FLTKHS null pointers happen which+-- In a traditional callback-heavy API such as FLTKHS, null pointers happen, which -- is why FLTKHS supports partial stack traces. All FLTK functions throw an -- error along with a stack trace when given a null 'Ref'. ----- For pre-7.10 GHCs stack traces will only be shown if the+-- For pre-7.10 GHCs, stack traces will only be shown if the -- <https://wiki.haskell.org/Debugging#General_usage 'xc'> flag is used when -- compiling FLTKHS. ----- If compiled with GHC > 7.10 a partial stack trace is transparently available+-- If compiled with GHC > 7.10, a partial stack trace is transparently available -- to the user. The recently minted -- <https://hackage.haskell.org/package/base-4.8.1.0/docs/GHC-Stack.html#g:3 'CallStack'> -- implicit parameter is used to get a trace of the function that--- made the offending call along with a file name and line number. So, for+-- made the offending call along with a file name and line number. For -- example, in the following code: -- -- @@@ -379,8 +379,8 @@ --  ... -- @ ----- a button is placed inside a window in the main method but the first time it is clicked the callback will delete it and then try--- the extract the label from the null 'Ref'.+-- a button is placed inside a window in the main method, but the first time it is clicked, the callback will delete it and then try+-- to extract the label from the null 'Ref'. -- The resulting stack trace will look something like: -- -- @@@ -390,9 +390,9 @@ --   getLabel, called at src\/Main.hs:11:10 in main:Main -- @ ----- It says that the null pointer was originally detected in the library function 'toRefPtr' function which was called by the library function 'withRef', which+-- It says that the null pointer was originally detected in the library function 'toRefPtr' function, which was called by the library function 'withRef', which -- was called by 'getLabel' on line 11 of 'src/Main.hs'. Notice, however, that the trace stops there. It does not tell you 'getLabel' was invoked from 'buttonCb'.--- For a more detailed trace the 'CallStack' implicit parameter needs to be passed to each function in the chain like:+-- For a more detailed trace, the 'CallStack' implicit parameter needs to be passed to each function in the chain like: -- -- @ -- buttonCb :: (?loc :: CallStack) => Ref Button ...@@ -410,17 +410,17 @@ --  The steps are: -- -- - Make sure to have OpenGL installed if you need it.--- - Ensure that 'make', 'autoconf' and 'autoheader' are available on your system--- - Download & install <http://docs.haskellstack.org/en/stable/README/#how-to-install Stack>--- - Download & install the <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz FLTKHS hello world skeleton>--- - Verify the install by running `fltkhs-hello-world`+-- - Ensure that 'make', 'autoconf' and 'autoheader' are available on your system.+-- - Download & install <http://docs.haskellstack.org/en/stable/README/#how-to-install Stack>.+-- - Download & install the <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz FLTKHS hello world skeleton>.+-- - Verify the install by running `fltkhs-hello-world`. -- -- == Download & Install Stack--- Pick the <http://docs.haskellstack.org/en/stable/README/#how-to-install Stack installer> that matches your distribution and install according the instructions.+-- Pick the <http://docs.haskellstack.org/en/stable/README/#how-to-install Stack installer> that matches your distribution and install according to the instructions. -- -- == Download & Install the FLTKHS Hello World Skeleton -- === Downloading Without Git--- If 'git' is not installed download the latest version of the fltkhs-hello-world application skeleton from <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz here>+-- If 'git' is not installed, download the latest version of the fltkhs-hello-world application skeleton from <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz here>. -- -- -- Extract and rename the archive:@@ -449,24 +449,24 @@ -- @ -- -- == Verify The Install--- Test that the build completed successfully by invoking incredibly unimpressive+-- Test that the build completed successfully by invoking: -- -- @ -- > stack exec fltkhs-hello-world -- @ ----- You will be greeted by an incredibly boring little window with a button that says "Hello world",--- if you click it, it will change to "Goodbye world."+-- You will be greeted by an incredibly boring little window with a button that says "Hello world".+-- If you click it, it will change to "Goodbye world". -- -- -- $InstallationLinux --  The steps are: ----- - Make sure to have OpenGL installed if you need it--- - Download & install <http://docs.haskellstack.org/en/stable/README/#how-to-install Stack>--- - Download & install <http://www.fltk.org/software.php?VERSION=1.3.4-1&FILE=fltk/1.3.4-1/fltk-1.3.4-1-source.tar.gz FLTK 1.3.4-1>--- - Download & install the <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz FLTKHS hello world skeleton>--- - Verify the install by running `fltkhs-hello-world`+-- - Make sure you have OpenGL installed.+-- - Download & install <http://docs.haskellstack.org/en/stable/README/#how-to-install Stack>.+-- - Download & install <http://www.fltk.org/software.php?VERSION=1.3.4-1&FILE=fltk/1.3.4-1/fltk-1.3.4-1-source.tar.gz FLTK 1.3.4-1>.+-- - Download & install the <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz FLTKHS hello world skeleton>.+-- - Verify the install by running `fltkhs-hello-world`. -- -- == Download & Install Stack -- Pick the <http://docs.haskellstack.org/en/stable/README/#how-to-install Stack installer> that matches your distribution and install according the instructions.@@ -485,27 +485,27 @@ -- @ -- ----- If you didn't install FLTK from source you can use the 'fltk-config' tool to ensure that version 1.3.4-1 is installed:+-- If you didn't install FLTK from source, you can use the 'fltk-config' tool to ensure that version 1.3.4-1 is installed: -- -- @ -- > fltk-config --version -- 1.3.4-1 -- @ ----- Additionally the FLTK headers should be in the include path and, along with+-- The FLTK headers should be in the include path, along with -- the standard FLTK libraries, `fltk_images`, and `fltk_gl`. You will also need -- the `make`, `autoconf`, and `autoheader` tools to build the Haskell bindings. -- -- -- The reason we install from source is that some package managers seem to be -- behind on versions (as of this writing Ubuntu 14.04 is still on 1.3.2) and--- others put the headers and libraries in a non-standard locations which will+-- others put the headers and libraries in nonstandard locations, which will -- cause the Haskell bindings to throw compilation errors. -- -- -- == Download & Install the FLTKHS Hello World Skeleton -- === Downloading Without Git--- If 'git' is not installed download the latest version of the fltkhs-hello-world application skeleton from <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz here>+-- If 'git' is not installed, download the latest version of the `fltkhs-hello-world` application skeleton from <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz here>. -- -- Extract and enter the archive: --@@ -532,30 +532,30 @@ -- > stack install --flag fltkhs:opengl -- @ ----- __Note:__ If the `install` step produces a flood of `undefined reference` errors+-- __Note:__ If the `install` step produces a flood of `undefined reference` errors, -- please ensure that you have the right version of FLTK (1.3.4-1) installed and--- that the headers are in the expected locations. It seems as though some--- package managers put the libraries and headers in non-standard places so it+-- that the headers are in the expected locations. Some package +-- managers put the libraries and headers in nonstandard places, so it -- is best to build from source. -- -- == Verify The Install--- Test that the build completed successfully by invoking incredibly unimpressive+-- Test that the build completed successfully by invoking: -- -- @ -- > stack exec fltkhs-hello-world -- @ ----- You will be greeted by an incredibly boring little window with a button that says "Hello world",--- if you click it, it will change to "Goodbye world."+-- You will be greeted by an incredibly boring little window with a button that says "Hello world". +-- If you click it, it will change to "Goodbye world."  -- $InstallationMacBundled -- Mac versions older than El Capitan and Yosemite are not supported. -- -- The general steps are: ----- - Brew Install Stack--- - Download & install the <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz FLTKHS hello world skeleton>--- - Verify the install by running `fltkhs-hello-world`+-- - Brew Install Stack.+-- - Download & install the <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz FLTKHS hello world skeleton>.+-- - Verify the install by running `fltkhs-hello-world`. -- -- == Brew Install Stack -- This should be as simple as:@@ -572,7 +572,7 @@ -- -- == Download & Install the FLTKHS Hello World Skeleton -- === Downloading Without Git--- If 'git' is not installed download the latest version of the fltkhs-hello-world application skeleton from <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz here>+-- If 'git' is not installed, download the latest version of the fltkhs-hello-world application skeleton from <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz here>. -- -- Extract the archive: --@@ -601,7 +601,7 @@ -- @ -- -- == Verify The Install--- Test that the build completed successfully by invoking incredibly unimpressive+-- Test that the build completed successfully by invoking: -- -- @ -- > stack exec fltkhs-hello-world@@ -611,13 +611,13 @@ -- if you click it, it will change to "Goodbye world."  -- $InstallationMac--- Unfortunately Mac version older than El Capitan and Yosemite are not supported.+-- Unfortunately Mac versions older than El Capitan and Yosemite are not supported. -- -- The general steps are: ----- - Brew Install Stack--- - Download & install the <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz FLTKHS hello world skeleton>--- - Verify the install by running `fltkhs-hello-world`+-- - Brew Install Stack.+-- - Download & install the <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz FLTKHS hello world skeleton>.+-- - Verify the install by running `fltkhs-hello-world`. -- -- == Brew Install Stack -- This should be as simple as:@@ -651,7 +651,7 @@ -- -- == Download & Install the FLTKHS Hello World Skeleton -- === Downloading Without Git--- If 'git' is not installed download the latest version of the fltkhs-hello-world application skeleton from <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz here>+-- If 'git' is not installed, download the latest version of the fltkhs-hello-world application skeleton from <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz here>. -- -- -- Extract the archive:@@ -681,14 +681,14 @@ -- @ -- -- == Verify The Install--- Test that the build completed successfully by invoking incredibly unimpressive+-- Test that the build completed successfully by invoking: -- -- @ -- > stack exec fltkhs-hello-world -- @ ----- You will be greeted by an incredibly boring little window with a button that says "Hello world",--- if you click it, it will change to "Goodbye world."+-- You will be greeted by an incredibly boring little window with a button that says "Hello world".+-- If you click it, it will change to "Goodbye world".  -- $InstallationWindowsBundled --@@ -910,12 +910,12 @@ -- > stack exec fltkhs-hello-world -- @ ----- You will be greeted by an incredibly boring little window with a button that says "Hello world",--- if you click it, it will change to "Goodbye world."+-- You will be greeted by an incredibly boring little window with a button that says "Hello world".+-- If you click it, it will change to "Goodbye world". -- -- == Packaging A Windows Executable ----- While the 'fltkhs-hello-world' application is mostly stand-alone the MSYS2 environment bundled with 'stack' seems to require 3 runtime DLLs. The DLLs are bundled with 'stack' so it's easy to zip them up with the executable and deploy. The required DLLs are: 'libstdc++-6.dll', 'libgcc_s_seh-1.dll' and 'libwinpthread-1.dll'.+-- While the 'fltkhs-hello-world' application can mostly stand alone, the MSYS2 environment bundled with 'stack' seems to require 3 runtime DLLs. The DLLs are bundled with 'stack', so you can zip them up with the executable and deploy. The required DLLs are: 'libstdc++-6.dll', 'libgcc_s_seh-1.dll' and 'libwinpthread-1.dll'. -- -- --@@ -931,7 +931,7 @@ -- > cp `which fltkhs-hello-world` \/tmp\/fltkhs-hello-world -- @ ----- Copy over the DLLs. They are usually located in '../<ghc-version>/mingw/bin' but to make the process slightly less fragile we specify the directory relative to whatever 'ghc' is currently in 'stack' 's context:+-- Copy over the DLLs. They are usually located in '../<ghc-version>/mingw/bin', but to make the process slightly less fragile we specify the directory relative to whatever 'ghc' is currently in Stack's context: -- -- @ -- > cp `dirname $(which ghc)`..\/mingw\/bin\/libstdc++-6.dll \/tmp\/fltkhs-hello-world@@ -939,7 +939,7 @@ -- > cp `dirname $(which ghc)`..\/mingw\/bin\/libwinpthread-1.dll \/tmp\/fltkhs-hello-world -- @ ----- Zip up archive:+-- Zip up the archive: -- -- @ -- > cd /tmp@@ -951,11 +951,11 @@  -- $Demos ----- FLTKHS has a almost 25 end-to-end demo applications to help the user get started. They are--- split into two sets, those <http://github.com/deech/fltkhs-demos written manually> and those+-- FLTKHS has almost 25 end-to-end demo applications to help you get started. They are+-- split into two sets: those <http://github.com/deech/fltkhs-demos written manually> and those -- that <http://github.com/deech/fltkhs-fluid-demos show how to use FLUID>. ----- The READMEs in the repos have installation instructions but they assume that the user has+-- The READMEs in the repos have installation instructions, but they assume that you have -- successfully installed FLTK and the 'fltkhs-hello-world' app (see platform specific instructions above). -- @@ -968,13 +968,13 @@ -- = Quick Start -- The quickest way to get started is to look at the source for the -- <http://github.com/deech/fltkhs-hello-world FLTKHS project skeleton>. Though it is a--- simple app it shows the basics of widget creation and+-- simple app, it shows the basics of widget creation and -- callbacks. -- -- Other <https://github.com/deech/fltkhs-demos demo> <https://github.com/deech/fltkhs-fluid-demos packages> show more complicated usage of the API. -- -- Since the API is a low-level binding, code using it takes on the imperative--- style of the underlying toolkit. Fortunately it should look pretty familiar+-- style of the underlying toolkit. Fortunately, it should look pretty familiar -- to those who have used object-oriented GUI toolkits before. -- --@@ -986,10 +986,10 @@ -- Convenient access to the underlying C++ is achieved using typeclasses and -- type-level programming to emulate OO classes and multiple dispatch. This approach makes -- Haddock very unhappy and the generated documentation is frequently unhelpful.--- For instance, newcomers to this library are urged not to look at+-- For instance, I urge newcomers to this library not to look at -- "Graphics.UI.FLTK.LowLevel.Dispatch" or -- "Graphics.UI.FLTK.LowLevel.Hierarchy". The purpose of this guide is to point--- users in a more useful direction.+-- you in a more useful direction. -- -- -- The documentation provided with this API is not yet self-contained and is@@ -998,18 +998,18 @@ -- functions and datatypes map to the C++ ones. -- -- == Widget Construction--- Each widget has its own module all of which are listed--- below under the __Widgets__ heading . Most modules include a function named--- `<widgetName>New` that returns a reference to that widget. Although the user--- does not have to deal with raw pointers directly it might help to understand+-- Each widget has its own module, all of which are listed+-- below under the __Widgets__ heading. Most modules include a function named+-- `<widgetName>New` that returns a reference to that widget. Although you+-- do not have to deal with raw pointers directly, it might help to understand -- that this reference is a pointer to a void pointer to a C++ object. ----- For instance, 'windowNew' creates a 'Ref' 'Window' which is a pointer to a+-- For instance, 'windowNew' creates a 'Ref' 'Window', which is a pointer to a -- C++ object of type <http://www.fltk.org/doc-1.3/classFl__Window.html `Fl_Window`>, the FLTK class that knows how to draw,--- display and handle window events.+-- display, and handle window events. -- -- This value of type 'Ref' 'Window' is then passed along to various functions--- which, transparent to the user, extract the pointer and pass it to the+-- which transparently extract the pointer and pass it to the -- appropriate <http://www.fltk.org/doc-1.3/classFl__Window.html `Fl_Window`> instance method. -- -- == Widget Methods@@ -1020,7 +1020,7 @@ -- under the __Functions__ heading are not the real ones but are artifically -- generated because they are much more helpful to users. For instance, the -- actual type of 'activate' exposes all the type level arithmetic required so--- it can be used by subclasses of 'Widget' but is pretty unhelpful as a+-- it can be used by subclasses of 'Widget' but is unhelpful as a -- reference compared to the artificial type under __Functions__ heading of -- "Graphics.UI.FLTK.LowLevel.Widget". --@@ -1028,7 +1028,7 @@ -- navigate to the corresponding widget's module, find the __Functions__ header -- and scroll down to the desired function. Haddock, unfortunately, does not -- support anchors that link to a named point in the page. I'm /very/--- open to ideas on how to make this easier.+-- open to ideas on how to make this easier. -- JULIE HAS A QUESTION: wait, so which signatures are listed where exactly? like, what is this opposed to? -- -- Carrying on the previous example from the __Widget Creation__ section, the -- methods on a 'Ref' 'Window' widget are documented in@@ -1036,7 +1036,7 @@ -- the 'Ref' 'Window' reference as its first argument followed by whatever else -- it needs and delegates it appropriately. ----- As this is a low-level binding the Haskell functions are kept as close as+-- As this is a low-level binding, the Haskell functions are kept as close as -- possible in name and argument list to the underlying C++. This allows users -- familiar with the FLTK API to use this library with less learning overhead -- and it lets newcomers to FLTK take advantage of the already extensive@@ -1045,22 +1045,22 @@ -- Functions are named to make it as easy as possible to find the corresponding -- C++ function, however there are some naming conventions to keep in mind: ----- (1) setters and getters are prefixed with /set/ and /get/ respectively. In+-- (1) Setters and getters are prefixed with /set/ and /get/ respectively. In -- C++ both have the same name; the setter takes an argument while the getter--- does not. Since Haskell does not support overloading this convention is used.+-- does not. Since Haskell does not support overloading, this convention is used. ----- (2) in many cases C++ uses overloading to provide default values to+-- (2) In many cases C++ uses overloading to provide default values to -- arguments. Since Haskell does not support overloading, these arguments are--- 'Maybe' types eg. the `hotspot` function in--- "Graphics.UI.FLTK.LowLevel.Window". In other cases where the common use case--- leaves the default arguments unspecified the binding provides two functions,--- a longer less-convenient-to-type one that takes the default argument and a--- short one that does not eg. `drawBox` and `drawBoxWithBoxtype`, also in+-- 'Maybe' types, e.g., the `hotspot` function in+-- "Graphics.UI.FLTK.LowLevel.Window". In other cases, where the common use case+-- leaves the default arguments unspecified, the binding provides two functions:+-- a longer less-convenient-to-type one that takes the default argument, and a+-- short one that does not, e.g., `drawBox` and `drawBoxWithBoxtype`, also in -- "Graphics.UI.FLTK.LowLevel.Window". ----- (3) error codes are 'Either' types+-- (3) Error codes are 'Either' types. ----- (4) function arguments which are pointers to be filled are not exposed to the+-- (4) Function arguments that are pointers to be filled are not exposed to the -- API user. For instance, a common C++ idiom is to return a string by taking a -- pointer to some initialized but empty chunk of memory and filling it up. The -- corresponding Haskell function just returns a 'Data.Text'.@@ -1082,10 +1082,10 @@ -- to /getModal/ to check if the window is modal, but it can also be passed to -- /children/ in "Graphics.UI.FLTK.LowLevel.Group" which counts up the number of -- widgets inside the 'Window' and /getX/ in "Graphics.UI.FLTK.LowLevel.Widget"--- which returns the X coordinate of the 'Window''s top-left hand corner.+-- which returns the X coordinate of the 'Window''s top-left hand corner. JULIE: should these emph'd words be straight-quoted? -- -- The hierarchy corresponds almost exactly to the underlying C++ class--- hierarchy so, again, the user is able to take advantage of the+-- hierarchy so, again, you should be able to take advantage of the -- <http://www.fltk.org/doc-1.3/classes.html C++ documentation> to use the -- binding API. --@@ -1098,12 +1098,12 @@ -- now allow Haskell <https://hackage.haskell.org/package/fltkhs-0.5.1.3/docs/Graphics-UI-FLTK-LowLevel-Widget.html#g:2 functions> to be passed at -- widget construction time that give Haskell complete control on <https://hackage.haskell.org/package/fltkhs-0.5.1.3/docs/Graphics-UI-FLTK-LowLevel-Widget.html#v:widgetCustom drawing>, -- <https://hackage.haskell.org/package/fltkhs-0.5.1.3/docs/Graphics-UI-FLTK-LowLevel-Widget.html#t:CustomWidgetFuncs handling, resizing and other key functions>. This means that the Haskell user has--- complete control of look-and-feel and the event loop. The <https://github.com/deech/fltkhs-demos/blob/master/src/Examples/table-as-container.hs#L105 table> demos are+-- complete control of the look and feel as well as the event loop. The <https://github.com/deech/fltkhs-demos/blob/master/src/Examples/table-as-container.hs#L105 table> demos are -- an example of drawing in Haskell. An example of taking over the event loop is an FLTKHS <https://github.com/deech/fltkhs-reflex-host proof-of-concept> that <https://github.com/deech/fltkhs-reflex-host/blob/master/src/reflex-host.hs#L33 overrides> -- the FLTKHS event loop with the <https://hackage.haskell.org/package/reflex Reflex FRP> allowing -- native functional reactive programming. The sky is the limit! ----- When providing custom methods the object constructor is no longer+-- When providing custom methods, the object constructor is no longer -- `<widgetName>New` but `<widgetName>Custom`, which, in addition to the parameters -- taken by `<widgetName>New` also takes records of Haskell functions which are -- then passed to the C++ side.@@ -1120,10 +1120,10 @@ -- display itself. -- -- Again "Graphics.UI.FLTK.LowLevel.Window" can be used a motivating example.--- Its custom constructor 'windowCustom', in fact, takes two records. A--- 'CustomWidgetFuncs' which allows the user to override methods in its--- "Graphics.UI.FLTK.LowLevel.Widget" parent class and also a--- 'CustomWindowFuncs' record which allows the user to override /flush/, a+-- Its custom constructor 'windowCustom', in fact, takes two records: a+-- 'CustomWidgetFuncs' which allows you to override methods in its+-- "Graphics.UI.FLTK.LowLevel.Widget" parent class, and also a+-- 'CustomWindowFuncs' record which allows you to override /flush/, a -- method on the Window class which tells the window how to force a redraw. For -- example, the demo /src\/Examples\/doublebuffer.hs/ (which corresponds to the -- executable 'ftlkhs-doublebuffer') tells both windows how to draw themselves@@ -1134,7 +1134,7 @@ -- record that can be passed to the constructor. For example, -- "Graphics.UI.FLTK.LowLevel.Widget" provides 'defaultCustomWidgetFuncs' and -- "Graphics.UI.FLTK.LowLevel.Window" has 'defaultCustomWindowFuncs'. In the--- demo mentioned above the 'singleWindowCustom' function is given+-- demo mentioned above, the 'singleWindowCustom' function is given -- 'defaultCustomWidgetFuncs' but with an overridden 'drawCustom'. -- -- Another case where customization comes up a lot is when using@@ -1144,47 +1144,47 @@ -- 'fltkhs-table-simple') shows this in action. -- -- Hopefully the demos just mentioned and others included with this library show--- that even though customizing is limited it is possible to do a lot.+-- that, even though customizing is limited, it is possible to do a lot. ----- Additionally for most customizable functions a widget provides a+-- For most customizable functions, a widget provides a -- corresponding function that calls the default C++ implementation as the--- function name suffixed with \"Super\". For instance, the user can provide a+-- function name suffixed with \"Super\". For instance, you can provide a -- custom implementation of /handle/ on "Graphics.UI.FLTK.LowLevel.Window" via -- the constructor and every call to /handle/ invokes that implementation, but--- the user can also call /handleSuper/ to get at the default C+++-- you can also call /handleSuper/ to get at the default C++ -- implementation. This comes in handy when the custom function is just setting--- up variables or logging and wants underlying implementation to take over at+-- up variables or logging and you want the underlying implementation to take over at -- some point. ----- __Warning__: since calls to the default implementation of the function,--- /handleSuper/, for example, are available to the widget they are+-- __Warning__: Since calls to the default implementation of the function+-- /handleSuper/, for example, are available to the widget, they are -- automatically available to all subclasses of the widget. I--- acknowledge this is a confusing aspect of the library's design but hopes the--- benefit of being able to get at the default implementation out-weighs the--- trap the user might fall into. If this becomes a pervasive problem I'm+-- acknowledge this is a confusing aspect of the library's design but hope the+-- benefit of being able to get at the default implementation outweighs the+-- trap users might fall into. If this becomes a pervasive problem, I'm -- open to removing this functionality. --  -- $Compilation -- -- As described above, the API emulates multiple dispatch using type-level--- programming, closed type families and typeclasses. While this is makes for a--- nice API it has also+-- programming, closed type families, and typeclasses. While this makes for a+-- nice API, it has also -- slowed down compilation of executables much more than expected. ----- To clarify the time taken to compile the library itself has not changed, but+-- To clarify, the time taken to compile the library itself has not changed, but -- applications that use the library to create executables are taking a lot--- longer to compile. To further emphasize, there does not appear to be any+-- longer to compile. To further emphasize, there do not appear to be any -- runtime performance issues. This is only a compile time problem. ----- To preserve the user's sanity and mine a flag `fastCompile` has been--- introduced to the <https://github.com/deech/fltkhs-hello-world skeleton> <https://github.com/deech/fltkhs-fluid-hello-world projects>, the <https://github.com/deech/fltkhs-demos fltkhs-demos> and--- to the <https://github.com/deech/fltkhs-fluid-demos fltkhs-fluid-demos>.--- This flag which tells the compiler to skip some steps when+-- To preserve your and my sanity, a flag `fastCompile` has been+-- introduced to the <https://github.com/deech/fltkhs-hello-world skeleton>, the <https://github.com/deech/fltkhs-fluid-hello-world projects>, the <https://github.com/deech/fltkhs-demos fltkhs-demos>, and+-- the <https://github.com/deech/fltkhs-fluid-demos fltkhs-fluid-demos>.+-- This flag, which tells the compiler to skip some steps when -- compiling executables, dramatically decreases compile time but also bloats -- the resulting executable size and probably makes runtime performance much -- slower. In this package and <https://github.com/deech/fltkhs-fluid-demos fltkhs-fluid-demos>--- it is enabled by default, since the executables are just+-- it is enabled by default since the executables are  -- demos that are not meant to show off performance. To disable this flag, tell -- Stack to ignore it during the `build` step: --@@ -1194,7 +1194,7 @@ -- -- In the <https://github.com/deech/fltkhs-hello-world fltkhs> and the -- <https://github.com/deech/fltkhs-fluid-hello-world fltkhs-fluid> project--- skeletons this flag is /disabled/ by default to provide the best runtime+-- skeletons, this flag is /disabled/ by default to provide the best runtime -- performance. To enable the flag for a smoother development workflow, tell -- Stack to enable it during the `configure` step: --

@@ -279,14 +279,14 @@ {# fun Fl_Widget_set_labelsize as setLabelsize' { id `Ptr ()',id `CInt' } -> `()' supressWarningAboutRes #} instance (impl ~ ( FontSize ->  IO ())) => Op (SetLabelsize ()) Widget orig impl where   runOp _ _ widget (FontSize pix) = withRef widget $ \widgetPtr -> setLabelsize' widgetPtr pix-{# fun Fl_Widget_image as image' { id `Ptr ()' } -> `(Ref Image)' unsafeToRef #}-instance (impl ~ (IO (Ref Image))) => Op (GetImage ()) Widget orig impl where+{# fun Fl_Widget_image as image' { id `Ptr ()' } -> `Maybe (Ref Image)' unsafeToMaybeRef #}+instance (impl ~ (IO (Maybe (Ref Image)))) => Op (GetImage ()) Widget orig impl where   runOp _ _ widget = withRef widget $ \widgetPtr -> image' widgetPtr {# fun Fl_Widget_set_image as setImage' { id `Ptr ()',id `Ptr ()'} -> `()' supressWarningAboutRes #} instance (Parent a Image, impl ~ (Maybe( Ref a ) ->  IO ())) => Op (SetImage ()) Widget orig impl where   runOp _ _ widget pix = withRef widget $ \widgetPtr -> withMaybeRef pix $ \pixPtr -> setImage' widgetPtr pixPtr-{# fun Fl_Widget_deimage as deimage' { id `Ptr ()' } -> `(Ref Image)' unsafeToRef #}-instance (impl ~ (IO (Ref Image))) => Op (GetDeimage ()) Widget orig impl where+{# fun Fl_Widget_deimage as deimage' { id `Ptr ()' } -> `Maybe (Ref Image)' unsafeToMaybeRef #}+instance (impl ~ (IO (Maybe (Ref Image)))) => Op (GetDeimage ()) Widget orig impl where   runOp _ _ widget = withRef widget $ \widgetPtr -> deimage' widgetPtr {# fun Fl_Widget_set_deimage as setDeimage' { id `Ptr ()',id `Ptr ()'} -> `()' supressWarningAboutRes #} instance (Parent a Image, impl ~ (Maybe( Ref a ) ->  IO ())) => Op (SetDeimage ()) Widget orig impl where@@ -533,11 +533,11 @@ -- -- getDamage :: 'Ref' 'Widget' -> 'IO' (['Damage')] ----- getDeimage :: 'Ref' 'Widget' -> 'IO' ('Ref' 'Image')+-- getDeimage :: 'Ref' 'Widget' -> 'IO' ('Maybe' ('Ref' 'Image')) -- -- getH :: 'Ref' 'Widget' -> 'IO' ('Int') ----- getImage :: 'Ref' 'Widget' -> 'IO' ('Ref' 'Image')+-- getImage :: 'Ref' 'Widget' -> 'IO' ('Maybe' ('Ref' 'Image')) -- -- getLabel :: 'Ref' 'Widget' -> 'IO' 'T.Text' --