diff --git a/CMakeLists.txt b/CMakeLists.txt --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -3,30 +3,31 @@ PROJECT(fltkc) # CMake doesn't like backslashes in path -STRING(REGEX REPLACE "\\\\" "/" FLTK_HOME ${FLTK_HOME}) +STRING("REGEX" "REPLACE" "\\\\" "/" "FLTK_HOME" "${FLTK_HOME}") -if(EXISTS "${FLTK_HOME}/lib/libfltk_z.a") - SET(FLTK_Z "${FLTK_HOME}/lib/libfltk_z.a") +if(EXISTS "${FLTK_HOME}/build/lib/libfltk_z.a") + SET(FLTK_Z "${FLTK_HOME}/build/lib/libfltk_z.a") else() find_library(HAVE_Z z) SET(FLTK_Z "${HAVE_Z}") endif() -if(EXISTS "${FLTK_HOME}/lib/libfltk_jpeg.a") - SET(FLTK_JPEG "${FLTK_HOME}/lib/libfltk_jpeg.a") +if(EXISTS "${FLTK_HOME}/build/lib/libfltk_jpeg.a") + SET(FLTK_JPEG "${FLTK_HOME}/build/lib/libfltk_jpeg.a") else() find_library(HAVE_JPEG jpeg) SET(FLTK_JPEG "${HAVE_JPEG}") endif() -if(EXISTS "${FLTK_HOME}/lib/libfltk_png.a") - SET(FLTK_PNG "${FLTK_HOME}/lib/libfltk_png.a") +if(EXISTS "${FLTK_HOME}/build/lib/libfltk_png.a") + SET(FLTK_PNG "${FLTK_HOME}/build/lib/libfltk_png.a") else() find_library(HAVE_PNG png) SET(FLTK_PNG "${HAVE_PNG}") endif() - +INCLUDE_DIRECTORIES(${FLTK_HOME}) +LINK_DIRECTORIES("${FLTK_HOME}/build/lib") SET(FLTKLINKFLAGS "-Wl,-Bstatic") SET(FLTKLINKFLAGS "${FLTKLINKFLAGS} -lfltk.a -lfltk_gl -lfltk_images.a ${FLTK_PNG} ${FLTK_JPEG} ${FLTK_Z} -lfltk_forms") SET(FLTKLINKFLAGS "${FLTKLINKFLAGS} -Wl,-Bdynamic") @@ -48,9 +49,7 @@ endif() -MESSAGE(STATUS "FLTKLINKFLAGS: ${FLTKLINKFLAGS}") - -SET(FLTKCONFIGCOMMAND "-Wl,-Bstatic,-whole-archive,-lfltkc,-no-whole-archive,-Bdynamic ${FLTKLINKFLAGS}") +SET(FLTKCONFIGCOMMAND "-Wl,-Bstatic,-whole-archive,-lfltkc,-no-whole-archive,-Bdynamic -L${FLTK_HOME}/build/lib -L${CMAKE_CURRENT_SOURCE_DIR}/c-lib ${FLTKLINKFLAGS}") CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/fltkhs.buildinfo.in ${CMAKE_CURRENT_SOURCE_DIR}/fltkhs.buildinfo) diff --git a/Makefile.in b/Makefile.in --- a/Makefile.in +++ b/Makefile.in @@ -4,8 +4,12 @@ SHARED_OBJECT_FILES = shared_object_files STATIC_OBJECT_FILES = static_object_files EXAMPLES = c-examples +CONFIGURE_CACHE = autom4te.cache +CONFIGURE_LOG = config.log +CONFIGURE_STATUS = config.status +FLTKHS_BUILDINFO = fltkhs.buildinfo DIRS = $(SRC) $(EXAMPLES) -CLEANUPDIRS = $(EXECUTABLEDIR) $(LIBDIR) $(OBJECT_FILES) $(SHARED_OBJECT_FILES) $(STATIC_OBJECT_FILES) +CLEANUP = $(EXECUTABLEDIR) $(LIBDIR) $(OBJECT_FILES) $(SHARED_OBJECT_FILES) $(STATIC_OBJECT_FILES) $(CONFIGURE_CACHE) $(CONFIGURE_LOG) $(CONFIGURE_STATUS) $(CONFIGURE_SCAN) $(FLTKHS_BUILDINFO) .SILENT: .PHONY: src all clean src: @@ -14,9 +18,7 @@ cd $(EXAMPLES); $(MAKE) all all: examples clean: - for dir in $(CLEANUPDIRS); do\ - echo "=== removing $$dir ===";\ - if [ -d "./$$dir" ];then \ - rm -rf $$dir; \ - fi \ + for f in $(CLEANUP); do\ + echo "=== removing $$f ===";\ + rm -rf $$f; \ done diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -25,10 +25,10 @@ The rest of the documentation (including installation instructions for Windows and API usage) is located in the [FLTKHS module] [3]. This is the primary module that needs to be imported by every Fltkhs app and the entry point into the application. -A number of demos are also available in the [fltkhs-demos] [4] and the [fltkhs-fluid-examples] [5] packages. +A number of demos are also available in the [fltkhs-demos] [4] and the [fltkhs-fluid-demos] [5] packages. [1]: http://www.fltk.org/index.php "FLTK" [2]: http://www.fltk.org/software.php [3]: http://hackage.haskell.org/package/fltkhs/docs/Graphics-UI-FLTK-LowLevel-FLTKHS.html [4]: http://hackage.haskell.org/package/fltkhs-demos - [5]: http://hackage.haskell.org/package/fltkhs-fluid-examples + [5]: http://hackage.haskell.org/package/fltkhs-fluid-demos diff --git a/Setup.hs b/Setup.hs --- a/Setup.hs +++ b/Setup.hs @@ -81,7 +81,11 @@ myBuildHook pkg_descr local_bld_info user_hooks bld_flags = do let compileC = do putStrLn "==Compiling C bindings==" - rawSystemExit normal "make" [] + case buildOS of + Windows -> rawSystemExit normal "make" [] + os | os `elem` [FreeBSD, OpenBSD, NetBSD, DragonFly] + -> rawSystemExit normal "gmake" [] + _ -> rawSystemExit normal "make" [] cdirexists <- doesDirectoryExist fltkcdir if cdirexists then @@ -91,9 +95,12 @@ else compileC case buildOS of Windows -> addToEnvironmentVariable "PATH" fltkcdir - _ -> do + Linux -> do addToEnvironmentVariable "LD_LIBRARY_PATH" fltkcdir addToEnvironmentVariable "LIBRARY_PATH" fltkcdir + _ -> do + addToEnvironmentVariable "DYLD_LIBRARY_PATH" fltkcdir + addToEnvironmentVariable "LIBRARY_PATH" fltkcdir buildHook defaultUserHooks pkg_descr local_bld_info user_hooks bld_flags copyCBindings :: PackageDescription -> LocalBuildInfo -> UserHooks -> CopyFlags -> IO () @@ -103,18 +110,22 @@ . fromFlag . copyDest $ flags rawSystemExit (fromFlag $ copyVerbosity flags) "cp" - ["c-lib/libfltkc.a", libPref] + ["c-lib" "libfltkc.a", libPref] case buildOS of - Linux -> rawSystemExit (fromFlag $ copyVerbosity flags) "cp" - ["c-lib/libfltkc.so", libPref] - Windows -> do - rawSystemExit (fromFlag $ copyVerbosity flags) "cp" - ["c-lib/libfltkc.dll.a", libPref] - rawSystemExit (fromFlag $ copyVerbosity flags) "cp" - ["c-lib/libfltkc.dll", libPref] + os | os `elem` [Linux, FreeBSD, OpenBSD, NetBSD, DragonFly] + -> rawSystemExit (fromFlag $ copyVerbosity flags) "cp" + ["c-lib" "libfltkc-dyn.so", libPref] + OSX -> rawSystemExit (fromFlag $ copyVerbosity flags) "cp" + ["c-lib" "libfltkc-dyn.dylib", libPref] + Windows -> + rawSystemExit (fromFlag $ copyVerbosity flags) "cp" + ["c-lib" "libfltkc-dyn.dll", libPref] myCleanHook pd x uh cf = do - rawSystemExit normal "make" ["clean"] + case buildOS of + os | os `elem` [FreeBSD, OpenBSD, NetBSD, DragonFly] + -> rawSystemExit normal "gmake" ["clean"] + _ -> rawSystemExit normal "make" ["clean"] cleanHook defaultUserHooks pd x uh cf -- Based on code in "Gtk2HsSetup.hs" from "gtk" package @@ -136,7 +147,11 @@ let installedPkgInfo = installedPkgInfoRaw { -- this is what this whole register code is all about - extraGHCiLibraries = ["fltkc"] } + extraGHCiLibraries = + case buildOS of + Windows -> ["libfltkc-dyn"] + _ -> ["fltkc-dyn"] + } -- Three different modes: case () of diff --git a/c-src/CMakeLists.txt b/c-src/CMakeLists.txt --- a/c-src/CMakeLists.txt +++ b/c-src/CMakeLists.txt @@ -99,18 +99,17 @@ Fl_WizardC.cpp ) -ADD_DEFINITIONS("${CXX_FLAGS} -DWIN32 -DUSE_OPENGL32 -D_LARGEFILE_SOURCE -D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64 -c -Wall -DINTERNAL_LINKAGE -g -Icpp -I\"${FLTK_HOME}/include\"") - -MESSAGE(STATUS ${CXX_FLAGS}) +ADD_DEFINITIONS("${CXX_FLAGS} -DWIN32 -DUSE_OPENGL32 -D_LARGEFILE_SOURCE -D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64 -c -Wall -DINTERNAL_LINKAGE -g -Icpp -I\"${FLTK_HOME}/\"") +# ADD_DEFINITIONS("${CXX_FLAGS} -DWIN32 -DUSE_OPENGL32 -D_LARGEFILE_SOURCE -D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64 -c -Wall -DINTERNAL_LINKAGE -g -Icpp -I\"${FLTK_HOME}/include\"") # first build object library so that we can reuse same objects for both static and shared library ADD_LIBRARY(fltkc_obj OBJECT ${SourceFiles}) -ADD_LIBRARY(fltkc SHARED $) +ADD_LIBRARY(fltkc-dyn SHARED $) -target_link_libraries(fltkc ${FLTKLINKFLAGS} -L${FLTK_HOME}/lib) +target_link_libraries(fltkc-dyn ${FLTKLINKFLAGS} -L${FLTK_HOME}/lib) -set_target_properties(fltkc PROPERTIES ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../c-lib +set_target_properties(fltkc-dyn PROPERTIES ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../c-lib RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../c-lib) diff --git a/c-src/Fl_RGB_ImageC.h b/c-src/Fl_RGB_ImageC.h --- a/c-src/Fl_RGB_ImageC.h +++ b/c-src/Fl_RGB_ImageC.h @@ -9,6 +9,7 @@ #include "Fl_CallbackC.h" EXPORT { #endif + #include FL_EXPORT_C(fl_RGB_Image, Fl_RGB_Image_New)(uchar* bits, int W, int H); FL_EXPORT_C(fl_RGB_Image, Fl_RGB_Image_New_With_D)(uchar* bits, int W, int H, int D); FL_EXPORT_C(fl_RGB_Image, Fl_RGB_Image_New_With_LD)(uchar* bits, int W, int H, int LD); diff --git a/c-src/Makefile.in b/c-src/Makefile.in --- a/c-src/Makefile.in +++ b/c-src/Makefile.in @@ -121,7 +121,7 @@ SONAME_FLAGS= -shared -Wl,-soname endif .SILENT: -all: libfltkc.a libfltkc.$(SHARED_EXT) +all: libfltkc.a libfltkc-dyn.$(SHARED_EXT) .SUFFIXES: .cpp .o .cpp.o: test -d $(STATIC_OBJECT_FILES) || mkdir $(STATIC_OBJECT_FILES) @@ -134,13 +134,16 @@ @echo "*** Linking $@..." (cd $(STATIC_OBJECT_FILES); \ ar rcs $(LIBDIR)/$@ $^;) -libfltkc.so : $(OBJECTS) +libfltkc-dyn.so : $(OBJECTS) test -d $(LIBDIR) || mkdir $(LIBDIR) @echo "*** Linking $@..." (cd $(SHARED_OBJECT_FILES); \ $(CXX) $(SONAME_FLAGS),$(LIBDIR)/$@ -o $(LIBDIR)/$@ $^ $(shell $(FLTKCONFIG) --use-images --use-glut --use-forms --use-gl --ldflags)); -libfltkc.dylib: $(OBJECTS) - @echo "*** Not linking $@ because of bugs in ./c-src/Makefile.in, help appreciated." +libfltkc-dyn.dylib: $(OBJECTS) + test -d $(LIBDIR) || mkdir $(LIBDIR) + @echo "*** Linking $@..." + (cd $(SHARED_OBJECT_FILES); \ + $(CXX) $(SONAME_FLAGS),$(LIBDIR)/$@ -o $(LIBDIR)/$@ $^ $(shell $(FLTKCONFIG) --use-images --use-glut --use-forms --use-gl --ldflags)); clean: test -d $(LIBDIR) && rm -rf $(LIBDIR) test -d $(SHARED_OBJECT_FILES) && rm -rf $(SHARED_OBJECT_FILES) diff --git a/c-src/UtilsC.cpp b/c-src/UtilsC.cpp --- a/c-src/UtilsC.cpp +++ b/c-src/UtilsC.cpp @@ -1,11 +1,16 @@ #include "UtilsC.h" #ifdef __cplusplus Fl_Menu_Item* convert(fl_Menu_Item* item, int size){ - int i = 0; - Fl_Menu_Item* current = new Fl_Menu_Item[size]; - for (;i(*(item + i))); + if (size == 0) { + return NULL; } - return current; + else { + int i = 0; + Fl_Menu_Item* current = new Fl_Menu_Item[size]; + for (;i(*(item + i))); + } + return current; + } } #endif diff --git a/fltkhs.cabal b/fltkhs.cabal --- a/fltkhs.cabal +++ b/fltkhs.cabal @@ -1,5 +1,5 @@ name : fltkhs -version : 0.4.0.2 +version : 0.4.0.3 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. @@ -127,17 +127,25 @@ Executable fltkhs-fluidtohs Main-Is: Main.hs Hs-Source-Dirs: src/Fluid + Other-modules: + Generate + Lookup + Parser + Types + Utils Build-Depends: base == 4.*, filepath, fltkhs, parsec >= 3.1.6, - directory >= 1.2.2.0, + directory >= 1.2.1.0, mtl default-language: Haskell2010 ghc-Options: -Wall -threaded if os(windows) ghc-Options: -optl-mwindows + if os(darwin) + ghc-Options: -pgml g++ "-optl-Wl,-lfltkc" if !os(darwin) && !os(windows) ghc-Options: -pgml g++ "-optl-Wl,--whole-archive" "-optl-Wl,-Bstatic" "-optl-Wl,-lfltkc" "-optl-Wl,-Bdynamic" "-optl-Wl,--no-whole-archive" @@ -151,5 +159,7 @@ ghc-Options: -Wall -threaded if os(windows) ghc-Options: -optl-mwindows + if os(darwin) + ghc-Options: -pgml g++ "-optl-Wl,-lfltkc" if !os(darwin) && !os(windows) ghc-Options: -pgml g++ "-optl-Wl,--whole-archive" "-optl-Wl,-Bstatic" "-optl-Wl,-lfltkc" "-optl-Wl,-Bdynamic" "-optl-Wl,--no-whole-archive" diff --git a/src/Graphics/UI/FLTK/LowLevel/FLTKHS.hs b/src/Graphics/UI/FLTK/LowLevel/FLTKHS.hs --- a/src/Graphics/UI/FLTK/LowLevel/FLTKHS.hs +++ b/src/Graphics/UI/FLTK/LowLevel/FLTKHS.hs @@ -8,22 +8,32 @@ -- -- $Goals - -- * Installation (Linux & Mac) + -- * Obstacles -- + -- $Obstacles + + -- * Installation + -- + -- ** Linux + -- -- $InstallationLinux - -- * Installation (Windows 64-bit) + -- ** Mac (Yosemite & El Capitan) -- - -- $InstallationWindows + -- $InstallationMac - -- * Getting Started + -- ** Installation (Windows 64-bit) -- - -- $GettingStarted + -- $InstallationWindows -- * Demos -- -- $Demos + -- * Getting Started + -- + -- $GettingStarted + -- * Fluid Support -- -- $FluidSupport @@ -40,7 +50,7 @@ -- -- $Compilation - -- * Cabal REPL Issues + -- * Running in the REPL -- -- $CabalREPLIssues @@ -222,8 +232,9 @@ import Graphics.UI.FLTK.LowLevel.PNMImage -- $Module Documentation --- This module re-exports all the available widgets and their core types. The types and list --- of widgets is listed under the __Core Types__ and __Widgets__ section below. +-- This module re-exports all the available widgets and +-- their core types. The types and list of widgets is listed under the __Core +-- Types__ and __Widgets__ section below. -- -- A general introduction to the library follows. -- @@ -231,17 +242,19 @@ -- $Motivation -- This library aims to make it easy for users to build native apps that work portably across platforms. -- --- The original author is also very interested the renewed interested in user interfaces in the --- programming community, whether the various kinds of functional reactive programming, meta-object protocol UI's, --- or something like React.js. +-- The original author is also very interested the renewed interested in user +-- interfaces in the programming community, whether the various kinds of +-- functional reactive programming, meta-object protocol UI's, 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 will make it more fun to play around with these great ideas --- using Haskell. +-- 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 useful to be able to make native apps. They are usually faster --- and have fewer security issues. +-- 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? -- - The original author chose FLTK because it was small enough that one person could bind the whole thing in an initial @@ -252,9 +265,11 @@ -- 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 at least one of criterion listed under the __Goals__ section below. +-- These are all great projects and produce really nice UI's, but they all fail +-- at least one of criterion listed under the __Goals__ section below. -- --- To the author's knowledge, as of the third quarter of 2015, no other package in the Haskell ecosystem meets all those constraints. +-- To the author's knowledge, as of the first quarter of 2016, no other package +-- in the Haskell ecosystem meets all those constraints. -- -- $Goals @@ -268,37 +283,115 @@ -- (6) includes a lot of complete working demos so that the user can get up and running faster. (see note below) -- (7) comes with GUI builder support to alleviate the tedium of laying out widgets by hand -- --- _Note_: As of version 0.4.0.1, the demos have been moved into their own package for reasons outlined in the =Demos= section of --- this document. +-- __Note__: As of version 0.4.0.1, the demos have been moved into their own +-- package for reasons +-- outlined in the =Demos= section of this document. -- $FluidSupport -- --- This package also comes with a utility (fltkhs-fluidtohs) that takes a user interface generated using the --- that ships with FLTK and generates Haskell code. +-- This package also comes with a utility (fltkhs-fluidtohs) that takes a user +-- interface generated using the +-- 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 wiring --- directly from Fluid. +-- 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 +-- wiring directly from Fluid. -- --- The quickest way to get started is to download the . --- The "Setup.hs" that comes with the skeleton is configured to use the 'fltkhs-fluidtohs' utility to automatically convert any Fluid in 'src' directory --- into a Haskell module of the same name during the preprocess step. This means using Fluid in a FLTKHS project is as simple --- as creating a Fluid interface and running 'cabal build' or 'cabal install'. +-- The quickest way to get started is to download the +-- . +-- The "Setup.hs" that comes with the skeleton is configured to use +-- the 'fltkhs-fluidtohs' utility to automatically convert any Fluid in 'src' +-- directory into a Haskell module of the same name during the preprocess step. +-- This means using Fluid in a FLTKHS project is as simple as creating a Fluid +-- interface and running 'cabal build' or 'cabal install'. -- --- Additionally the comes with --- a number of demos that show off how Fluid integrates with FLTKS. +-- Additionally the package +-- comes with a number of demos that show off how Fluid integrates with FLTKS. -- +-- $Obstacles +-- This section attempts to briefly highlight some possible dealbreakers users +-- might want to know about before proceeding. To be clear, building and deploying +-- portable static application binaries works well on all platforms which is why the +-- library is considered usable. And most of these issues are being aggressively +-- addressed but in the interests of full disclosure ... +-- +-- == Look & Feel (All users) +-- The look and feel of FLTK apps can be charitably described as /retro/. And since +-- FLTK has no support for theming it is also baked in. FLTK was designed for the +-- embedded domain and trades off slickness for speed, portability and +-- binary size. This is unlikely to change. +-- +-- == Compile Times (All users) +-- Currently a dense app (~ 160-180 widgets crammed into the same window) takes +-- 9-12 seconds to compile on a 32GB quad-core machine. Surprisingly it only goes up +-- to 10-15 seconds on a 8GB machine indicating that GHC pegs one processor and RAM +-- does not matter. Educated guess, most of the time is being spent traversing type-level lists +-- and chasing down orphan instances. The hope is that this will all go away onece GHC 8 has settled +-- in and all the type-level gymnastics can been replaced with OverloadedRecordFields. +-- +-- == GHCi (All users) +-- The GHC 7.10.x series has an unfortunate +-- that causes GHCi to +-- crash when loading the shared library that contains the C bindings to the C++ +-- API. The REPL loads fine in GHC 7.8.x. This means that each FLTKHS app needs a +-- special GHC environment just for running the REPL. This is achieved by bundling +-- another Stack file (arbitrarily called 'stack-repl.yaml') with sample apps +-- and skeletons specially for loading an app into GHCi but also means that users +-- have to do the following to load a GUI app into the REPL: +-- +-- @ +-- > STACK_YAML=stack-repl.yaml stack ghci ... +-- @ +-- +-- Furthermore once an app is launched via the REPL the app window does not respond +-- to close events. The user has to `:quit` GHCi in order to close the window. So +-- while the REPL is still useful for querying functions etc. it is not once the +-- application is actually launched. Hopefully the fix is simply a case of the +-- author knowing how GHCi and the FFI interact. +-- +-- == GHC 7.10.3 And Beyond (Windows only) +-- FLTKHS does not work with GHC 7.10.3 on Windows. Period. GHC 7.10.2 and 7.8.4 on +-- Windows work fine. The problem is the MinGW environment that comes bundled with +-- GHC 7.10.3 has brought to a light and unfortunate +-- in the `language-c` package +-- that C2HS depends on. Until this is fixed FLTKHS will not build. +-- +-- The workaround is bundling yet another special Stack file (arbitrarily called +-- "stack-windows.yaml") that allows Windows users to run FLTKHS with GHC 7.10.2. +-- Most importantly this pins all Windows users to 7.10.2 until the issue is +-- resolved and as an added inconvenience all Stack commands in Windows have to be +-- prefixed with the cheesy: +-- +-- @ +-- > STACK_YAML= stack-windows.yaml stack ... +-- @ +-- +-- == GHCi (Windows only) +-- GHCi does not work with FLTKHS on Windows at all. At least on Windows 7, attempting +-- load an app into the REPL generates a weird error message about not being able to +-- find `uuid.dll`. +-- +-- Hopefully this is just an issue of the author not understand GHCi on Windows and +-- will be resolved quickly. + -- $StackTrace -- --- 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'. +-- 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 flag is used when compiling FLTKHS. +-- For pre-7.10 GHCs stack traces will only be shown if the +-- flag is used when +-- compiling FLTKHS. -- --- If compiled with GHC > 7.10 a partial stack trace is transparently available to the user. The recently minted --- 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 example, in the following --- code: +-- If compiled with GHC > 7.10 a partial stack trace is transparently available +-- to the user. The recently minted +-- +-- 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 +-- example, in the following code: -- -- @ -- buttonCb :: Ref Button -> IO () @@ -340,45 +433,174 @@ -- -- $InstallationLinux +-- The steps are: -- --- - Make sure you have OpenGL installed --- - Download and install . --- - The recommended way of installing FLTK on Linux is from source. The reason is that some package managers seem to put the headers and libraries in a non-standard locations which will cause the Haskell bindings to throw compilation errors. On OSX and Linux it should build and install smoothly using the standard: +-- - Make sure to have OpenGL installed +-- - Download & install +-- - Download & install +-- - Download & install the +-- - Verify the install by running `fltkhs-hello-world` -- +-- == Download & Install Stack +-- Pick the that matches your distribution and install according the instructions. +-- +-- == Download & Install FLTK-1.3.3 +-- Please make sure to only download version +-- . +-- It should build and install smoothly with the standard: +-- -- @ -- > ./configure --enable-shared -- > make --- > make install +-- > sudo make install -- @ -- --- If you are customizing your `configure` step it is important to at least enable OpenGL and Cairo like so: +-- If you are customizing the `configure` step it is important to at least enable shared libraries, OpenGL and Cairo like so: -- --- > > ./configure --enable-shared --enable-gl --enable-cairo +-- > ./configure --enable-shared --enable-gl -- --- If you didn't install FLTK from source you will need to ensure that the FLTK headers are in the include path and, along with the standard FLTK library, `fltk_gl`, and `fltk_cairo` are also in the library path. You will also need the `make`, `autoconf`, and `autoheader` tools to build the Haskell bindings. +-- If you didn't install FLTK from source you can use the 'fltk-config' tool to ensure that version 1.3.3 is installed: -- --- - Make sure `c2hs` is installed with `cabal install c2hs`. +-- @ +-- > fltk-config --version +-- 1.3.3 +-- @ -- --- - Do +-- Additionally the FLTK headers should be in the include path and, 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. -- --- > > cabal install fltkhs -- --- or: +-- 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 +-- cause the Haskell bindings to throw compilation errors. -- - Make sure `c2hs` is +-- installed with `cabal install c2hs`. -- --- > > git clone https://github.com/deech/fltkhs --- > > cabal install + +-- == 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 -- --- __Note:__ If this step produces a flood of `undefined reference` errors please ensure that you have the right version of FLTK (1.3.3) 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. +-- Rename it: -- +-- @ +-- > cd \/Users\/\/Downloads\/ +-- > mv master.tar.gz fltkhs-hello-world.tar.gz +-- @ +-- +-- +-- Extract and enter the archive: +-- @ +-- > tar -zxvf fltkhs-hello-world.tar.gz +-- @ +-- +-- === Downloading With Git +-- If 'git' is available: +-- +-- @ +-- > git clone http://github.com/deech/fltkhs-hello-world +-- @ +-- +-- === Building +-- Build it with Stack: +-- @ +-- > cd fltkhs-hello-world +-- > stack setup +-- > stack install +-- @ +-- +-- __Note:__ If the `install` step produces a flood of `undefined reference` errors +-- please ensure that you have the right version of FLTK (1.3.3) 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 +-- is best to build from source. +-- +-- == Verify The Install -- - Test that the build completed successfully by invoking incredibly unimpressive -- --- > > fltkhs-buttons +-- > stack exec fltkhs-hello-world -- --- $InstallationWindows +-- $InstallationMac +-- Unfortunately Mac version older than El Capitan and Yosemite are not supported. -- --- _UPDATE_: This installation guide only works with MinGHC. Within the last month (January 2016) MinGHC has been deprecated and is no longer supported. If you have GHC 7.10.x, MinGHC will probably work for you but will not work for GHC 8. We are currently working on instructions for building on Windows with Stack. +-- The general steps are: -- +-- - Brew Install Stack +-- - Brew Install FLTK-1.3.3 (Yosemite) +-- - Brew Install FLTK-1.3.3 (El Capitan) +-- - Download & install the +-- - Verify the install by running `fltkhs-hello-world` +-- +-- == Brew Install Stack +-- This should be as simple as: +-- +-- @ +-- > brew install haskell-stack +-- @ +-- +-- == Brew Install FLTK-1.3.3 (Yosemite) +-- +-- @ +-- > brew install autoconf +-- > brew install fltk +-- @ +-- +-- Unfortunately 'autoconf' is required to build FLTKHS but has been removed +-- for the default XCode install since Yosemite so it is required here. +-- +-- == Brew Install FLTK-1.3.3 (El Capitan) +-- +-- @ +-- > brew install --devel fltk +-- @ +-- Unfortunately the version of Clang bundled with El Capitan does not compile the stable FLTK-1.3.3. +-- This installs the as-yet unreleased development version. Although FLTKHS only support 1.3.3 +-- it seems to work. +-- +-- == 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 +-- +-- Rename it: +-- +-- @ +-- > cd \/Users\/\/Downloads\/ +-- > mv master.tar.gz fltkhs-hello-world.tar.gz +-- @ +-- +-- +-- Extract the archive: +-- +-- @ +-- > tar -zxvf fltkhs-hello-world.tar.gz +-- @ +-- +-- === Downloading With Git +-- If 'git' is available: +-- +-- @ +-- > git clone http://github.com/deech/fltkhs-hello-world +-- @ +-- +-- === Building +-- Build it with Stack: +-- +-- @ +-- > cd fltkhs-hello-world +-- > stack setup +-- > stack install +-- @ +-- +-- == Verify The Install +-- Test that the build completed successfully by invoking incredibly unimpressive +-- +-- > stack exec fltkhs-hello-world +-- + +-- $InstallationWindows +-- -- Note: Currently this package only works on 64-bit Windows. -- -- This install guide has been tested on Windows 7 64-bit with 8GB of RAM. @@ -386,37 +608,97 @@ -- -- The general steps involved are: -- --- - Install and upgrade cabal-install +-- - Install -- - Install +-- - Install 'make' via MSYS2. +-- - Install +-- - Download the -- - Download & compile --- - Install this package +-- - Build & install the FLTKHS hello world skeleton project. +-- - Verify the install by running `fltkhs-hello-world` -- --- == Install MinGHC --- MinGHC installers are available . This package has been tested with GHC 7.8.4 64-bit and may work with newer versions. +-- This install process is certainly not smooth and there are a number of steps +-- that the user find mysterious and wonder why it is necessary. Each step below +-- starts off with the instructions, followed by a sentence or two that explains +-- why it is necessary. -- --- Once MinGHC is downloaded and installed per the instructions in the link above, install the newest version of cabal-install. This is an important step because the "Setup.hs" that ships with this package uses some of the newer features of the Cabal 1.2.x API. +-- == Install MSYS2 +-- MSYS2 installers are available +-- . Just +-- clicking through the installer wizard should be sufficient. -- --- @ --- > cabal update --- > cabal install cabal-install --- @ +-- MSYS2 provides a much nicer development environment compared to the standard +-- Windows CMD prompt. Additionally the install process needs some tools that are +-- easy to install via 'pacman', the package manager that ships with MSYS2. -- -- == Install CMake --- Simply click through the with the default options. Once this process is complete the `cmake` executable should be available at the CMD prompt: +-- Simply click through the +-- installer with +-- the default options. Once this process is complete the `cmake` executable should +-- be available at the MSYS2 prompt: -- -- @ -- > cmake --version --- cmake version 2.8.11.2 +-- cmake version 3.2.1 -- @ -- --- Your version will likely be `cmake version 3.2.x` but so long as it is above `cmake version 2.6.x` the install should proceed smoothly. +-- On Windows, CMake is used to generate Makefiles. Yes, CMake is available via +-- 'pacman' but unfortunately that version (as of this writing) does not have the +-- "MSYS Makefiles" generator required by the install process. -- +-- == Install GNU Make +-- The following should just work at the MSYS prompt: +-- +-- @ +-- > pacman -S make +-- @ +-- +-- GNU Make is required to build both FLTK and the C files in this package. +-- +-- == Install Stack +-- The default installation of +-- should also just +-- work. +-- +-- == Download the FLTKHS Hello World Skeleton +-- The latest version of the skeleton is available +-- . +-- +-- Extract it via MSYS as follows: +-- +-- @ +-- > pacman -S tar +-- > pacman -S gzip +-- > cd \ # This is usually \/C\/Users/\\/Downloads +-- > tar -zxvf master.tar.gz +-- > mv fltkhs-hello-world-master fltkhs-hello-world +-- @ +-- +-- There should now be a directory called 'fltkhs-hello-world' in the current +-- directory. We will need the path to this directory for the next step. +-- +-- Why is a skeleton project necessary? In the 'stack' world simply installing a +-- library globally does not work since each package is pinned down to a resolver, +-- GHC version etc. So in order to build this package we need to build and install +-- a package that depends on it. This skeleton is also the preferred way to get +-- started with a plain FLKTHS project, so two birds with one stone and all that ... +-- +-- -- == Download & compile FLTK-1.3.3 --- Please make sure to only download version . +-- Please make sure to only download version +-- . -- --- Once this is downloaded, since the `tar` and `gunzip` utilities ship with MinGHC, you should be able to unpack it at the command prompt: +-- If you haven't already installed 'tar' and 'gzip' at the MSYS prompt do: -- -- @ +-- > pacman -S tar +-- > pacman -S gzip +-- @ +-- +-- Extract the archive: +-- +-- @ +-- > cd \ # This is usually \/C\/Users/\\/Downloads -- > tar -zxvf fltk-1.3.3-source.tar.gz -- @ -- @@ -438,14 +720,20 @@ -- > cd build -- @ -- --- And run `cmake` telling it to work with the `make` utility that ships with MSYS: +-- And run `cmake` via `stack`: -- -- @ --- > cmake .. -G "MSYS Makefiles" +-- > STACK_YAML=\/stack-windows.yaml stack exec cmake -- -DOPTION_BUILD_SHARED_LIBS=On .. -G "MSYS Makefiles" -- @ -- --- Please note the `..` after `cmake` in the command. This is important because it tells CMake to build using the CMake specification found in the parent directory. +-- If you are confused about the 'STACK_YAML' environment variable please see the "GHC 7.10.3 And Beyond (Windows Only)" in the "Obstacles" section above. -- +-- Running the rest of the command via 'stack exec' gives 'cmake' access to the C/C++ compilers bundled with GHC. +-- +-- Please note the `..` after `-DOPTION_BUILD_SHARED_LIBS=On` in the command. +-- This is important because it tells CMake to build using the CMake specification +-- found in the parent directory. +-- -- Once these steps have been completed you should be able to compile the source: -- -- @ @@ -453,228 +741,344 @@ -- @ -- -- --- Each compile step may spit out a scary looking warning about a pointer to int cast, but this can be safely ignored. It seems to be an issue with the MinGW g++/gcc compiler. +-- Each compile step may spit out a scary looking warning about a pointer cast, +-- but this can be safely ignored. In the logic that sets up callbacks, FLTK casts +-- a 'long' argument to a '(void *)'. It can be ignored because it doesn't seem to +-- break anything. -- --- Also, the final demo `windowFocus` may fail to compile and complain about a symbol being redefined. This is again an issue with MinGW and can be safely ignored. +-- Compiling and linking on an 8GB machine seems to take about 5-6 minutes. -- +-- Also, the final demo may fail to compile and complain about a symbol being +-- redefined. This is again an issue with MinGW and can be safely ignored. +-- -- Now it is necessary to define the `FLTK_HOME` environment variable so this package knows where to look for header and library files: -- -- @ --- > set FLTK_HOME=\ +-- > export FLTK_HOME=\ -- @ -- +-- Why install from scratch? The user might have noticed that 'fltk' is +-- available via 'pacman' and wonder why we are building it ourselves and setting +-- some arbitrary environment variable to point to the location of the headers and +-- libraries. The issue is that for some reason CMake can't see the header files +-- and libraries when installed via 'pacman'. The linker throws weird errors about +-- types being defined in two places. The issue magically disappears when +-- installing from scratch and it's pretty easy to do. It's not ideal and we're +-- working on removing this step but for now this is the workaround. +-- -- == Install this package -- --- At this point it is highly likely that running `cabal --version` at the command line still invokes the old version even though `cabal` was updated. This is because the location of the newly installed `cabal` has not been added to the PATH variable. You can do so with this command: +-- At this point return to the directory containing the skeleton FLTKHS +-- application. If it was left in the 'Downloads' folder this should get back to +-- it: -- -- @ --- > set PATH=C:\\Users\\\\\AppData\\Roaming\\cabal\\bin;%PATH% +-- > cd \/C\/Users\/\\/Downloads\/fltkhs-hello-world -- @ -- --- Now you can finally install this package: +-- Now we can to build it: -- -- @ --- > > cabal install fltkhs +-- > STACK_YAML=stack-windows.yaml stack setup +-- > STACK_YAML=stack-windows.yaml stack install -- @ +-- If you are confused about the 'STACK_YAML' environment variable please see the "GHC 7.10.3 And Beyond (Windows Only)" in the "Obstacles" section above. -- --- Please note that compared to the Linux and Mac installs the compilation process takes a very long time. The reason for this is the MinGW gcc/g++ compilers are much slower. +-- __Note__: Installing FLTKHS takes a *long* time, almost 15 minutes on the +-- Windows 7, 8GB RAM test machine. The install will just sit at the `configure` +-- and `build` step with no feedback. This is happening because 1. the MinGW C\/C++ +-- compiler are way slower than gcc\/g++ and 2. the C2HS preprocess step seems to +-- take at least 3x as long on Windows. You only have to do this once (hopefully). +-- Please be patient. -- --- Once this has completed, you can test it by invoking the incredibly unimpressive: -- +-- == Verify The Install +-- +-- If all goes well there should be an incredibly unimpressive executable 'fltkhs-hello-world' in the 'stack' path. It can be invoked like: +-- -- @ --- > fltkhs-buttons +-- > STACK_YAML=stack-windows.yaml stack exec fltkhs-hello-world -- @ +-- If you are confused about the 'STACK_YAML' environment variable please see the "GHC 7.10.3 And Beyond (Windows Only)" in the "Obstacles" section above. +-- -- $Demos -- --- _Update_: As of version 0.4.0.1 all the demos have been moved to their own --- package . This speeds up installation of this package --- significantly and also allows the examples to be run interactively with `cabal --- repl`. This was an issue pre-0.4.0.1 because the REPL needed to link against the --- C library containing the C++ bindings and was having trouble finding it because --- it was just created by the Cabal build step but not yet installed. This seems --- like a better solution than hacking `Setup.hs` to make the library visible. +-- __Update__: As of version 0.4.0.1 all the demos have been moved to their own +-- package . This speeds +-- up installation of this package significantly and also allows the examples to +-- be run interactively with `cabal repl`. This was an issue pre-0.4.0.1 because +-- the REPL needed to link against the C library containing the C++ bindings and +-- was having trouble finding it because it was just created by the Cabal build +-- step but not yet installed. This seems like a better solution than hacking +-- `Setup.hs` to make the library visible. -- --- There are currently two sets of FLTKHS demos, the ones that are part of the package --- and ones that show off support. +-- There are currently two sets of FLTKHS demos, the ones that are part of the +-- package and ones that +-- show off +-- support. -- -- Please see the README in the package for more information. -- -- $GettingStarted -- --- It is assumed that by this point the user has successfully installed this library and demos in (see above). +-- It is assumed that by this point the user has successfully installed this +-- library and demos in (see +-- above). -- -- -- = Quick Start --- The quickest way to get started is to the download the . --- It is a simple `hello-world` program that shows the basics of widget creation and callbacks. --- The project's Cabal file comes pre-configured with the options necessary to produce a statically-linked executable so a simple --- 'cabal configure && cabal build' should result in an 'fltkhs-hello-world' executable in the 'dist' directory. +-- The quickest way to get started is to the download the +-- . It is a +-- simple `hello-world` program that shows the basics of widget creation and +-- callbacks. The project's Cabal file comes pre-configured with the options +-- necessary to produce a statically-linked executable so a simple 'cabal +-- configure && cabal build' should result in an 'fltkhs-hello-world' executable +-- in the 'dist' directory. -- -- Other demos that ship with this package 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 to those who have used object-oriented GUI toolkits before. +-- 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 +-- to those who have used object-oriented GUI toolkits before. -- -- -- $APIGuide -- -- = Guide to the Haddock Docs --- Convenient access to the underlying C++ is achieved using typeclasses and type-level programming to emulate --- classes and subclasses. 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 "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. -- +-- Convenient access to the underlying C++ is achieved using typeclasses and +-- type-level programming to emulate classes and subclasses. 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 +-- "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. -- --- The documentation provided with this API is not yet self-contained and is meant to be used in tandem --- with the . The rest of this document is about --- how the Haskell functions and datatypes map to the C++ ones. -- +-- The documentation provided with this API is not yet self-contained and is +-- meant to be used in tandem with the . +-- The rest of this document is about how the Haskell +-- 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 `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 that this reference is a pointer to a void --- pointer to a C++ object. +-- Each widget has its own module all of which are listed +-- below under the __Widgets__ heading . Most modules include a function named +-- `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 +-- 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 C++ object of type `Fl_Window`, --- the FLTK class that knows how to draw, display and handle window events. +-- For instance, 'windowNew' creates a 'Ref' 'Window' which is a pointer to a +-- C++ object of type `Fl_Window`, the FLTK class that knows how to draw, +-- 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 appropriate /Fl_Window/ instance method. +-- 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 +-- appropriate /Fl_Window/ instance method. -- -- == Widget Methods --- The Haskell functions that bind to the instance methods of an FLTK class are listed under the __Functions__ heading in that widget's module. --- It's worth remembering that these type signatures associated with the functions listed 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 reference --- compared to the artificial type under __Functions__ heading of "Graphics.UI.FLTK.LowLevel.Widget". -- --- Unfortunately to see this more helpful type signature the poor reader has to 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. The author is /very/ open to ideas on how to make this easier. +-- The Haskell functions that bind to the instance methods of an FLTK class are +-- listed under the __Functions__ heading in that widget's module. It's worth +-- remembering that these type signatures associated with the functions listed +-- 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 +-- reference compared to the artificial type under __Functions__ heading of +-- "Graphics.UI.FLTK.LowLevel.Widget". -- --- Carrying on the previous example from the __Widget Creation__ section, the methods on a 'Ref' 'Window' widget are documented in "Graphics.UI.FLTK.LowLevel.Window" --- under __Functions__. Each function takes the 'Ref' 'Window' reference as its first argument followed by whatever else it needs and --- delegates it appropriately. +-- Unfortunately to see this more helpful type signature the poor reader has to +-- 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. The author is /very/ +-- open to ideas on how to make this easier. -- --- 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 . +-- Carrying on the previous example from the __Widget Creation__ section, the +-- methods on a 'Ref' 'Window' widget are documented in +-- "Graphics.UI.FLTK.LowLevel.Window" under __Functions__. Each function takes +-- the 'Ref' 'Window' reference as its first argument followed by whatever else +-- it needs and delegates it appropriately. -- --- 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: +-- 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 +-- . -- --- (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. +-- 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: -- --- (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 "Graphics.UI.FLTK.LowLevel.Window". +-- (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. -- +-- (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 +-- "Graphics.UI.FLTK.LowLevel.Window". +-- -- (3) error codes are 'Either' types -- --- (4) function arguments which 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 'String'. +-- (4) function arguments which 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 'String'. -- -- --- It is hoped that until the documentation becomes more self-sustaining the user can use these heuristics (and the type signatures) --- along with the official FLTK documentation to "guess" what the binding functions do. +-- It is hoped that until the documentation becomes more self-sustaining the +-- user can use these heuristics (and the type signatures) along with the +-- official FLTK documentation to "guess" what the binding functions do. -- -- == Widget Hierarchy -- Every widget module in the API has a __Hierarchy__ heading that shows all its parents. -- --- The design of the API makes all the parent functions transparently available to that widget. This is also the reason why the actual type --- signatures are so complicated requiring the manual generation of artificial type signatures. +-- The design of the API makes all the parent functions transparently available +-- to that widget. This is also the reason why the actual type signatures are so +-- complicated requiring the manual generation of artificial type signatures. -- --- For instance, the __Functions__ section under "Graphics.UI.FLTK.LowLevel.Window" shows that a 'Ref' 'Window' can be passed 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. +-- For instance, the __Functions__ section under +-- "Graphics.UI.FLTK.LowLevel.Window" shows that a 'Ref' 'Window' can be passed +-- 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. -- --- The hierarchy corresponds almost exactly to the underlying C++ class hierarchy so, again, the user is able to take advantage of the --- to use the binding API. +-- The hierarchy corresponds almost exactly to the underlying C++ class +-- hierarchy so, again, the user is able to take advantage of the +-- to use the +-- binding API. -- -- === Overriding C++ methods --- The binding API provides a /very/ limited form of inheritance by allowing the user to provide Haskell implementations --- of certain key methods on a small set of classes. Which methods and which classes were determined by original author of this --- library based on a casual look at FLTK code in the wild and what was required for porting the demoes. If there is a --- pressing need for more methods or classes, please contact the maintainer. -- --- When providing custom methods the object constructor is no longer `New` but `Custom`, --- which, in addition the parameters taken by `New` also takes records of Haskell functions which are +-- The binding API provides a /very/ limited form of inheritance by allowing the +-- user to provide Haskell implementations of certain key methods on a small set +-- of classes. Which methods and which classes were determined by original +-- author of this library based on a casual look at FLTK code in the wild and +-- what was required for porting the demoes. If there is a pressing need for +-- more methods or classes, please contact the maintainer. +-- +-- When providing custom methods the object constructor is no longer +-- `New` but `Custom`, which, in addition the parameters +-- taken by `New` also takes records of Haskell functions which are -- then passed to the C++ side. -- --- Much like a callback, the Haskell functions are passed as function pointers to the C++ side and called whenever --- the event loop deems appropriate. Unlike callbacks, they can be set only on object instantiation. +-- Much like a callback, the Haskell functions are passed as function pointers +-- to the C++ side and called whenever the event loop deems appropriate. Unlike +-- callbacks, they can be set only on object instantiation. -- --- An example of this is "Graphics.UI.FLTK.LowLevel.Widget" which, since it is a base class for most widgets and doesn't have much --- functionality of its own, only allows custom construction using 'widgetCustom'. This constructor takes a 'CustomWidgetFuncs' --- datatype which is a record of functions which tells a "Graphics.UI.FLTK.LowLevel.Widget" how to handle events and draw, --- resize and display itself. +-- An example of this is "Graphics.UI.FLTK.LowLevel.Widget" which, since it is a +-- base class for most widgets and doesn't have much functionality of its own, +-- only allows custom construction using 'widgetCustom'. This constructor takes +-- a 'CustomWidgetFuncs' datatype which is a record of functions which tells a +-- "Graphics.UI.FLTK.LowLevel.Widget" how to handle events and draw, resize and +-- 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 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 in a Haskell function that uses low-level FLTK drawing routines by overriding the draw function --- of their "Graphics.UI.FLTK.LowLevel.Widget" parent. +-- 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 +-- 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 +-- in a Haskell function that uses low-level FLTK drawing routines by overriding +-- the draw function of their "Graphics.UI.FLTK.LowLevel.Widget" parent. -- --- Every widget that supports customizing also provides a default function 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 'defaultCustomWidgetFuncs' but with an overridden 'drawCustom'. +-- Every widget that supports customizing also provides a default function +-- 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 +-- 'defaultCustomWidgetFuncs' but with an overridden 'drawCustom'. -- --- Another case where customization comes up a lot is when using "Graphics.UI.FLTK.LowLevel.Table" which is a low-level table widget that needs --- to be told, for example, how to draw its cells. The demo /src\/Examples\/table-simple.hs/ (corresponding to the executable 'fltkhs-table-simple') --- shows this in action. +-- Another case where customization comes up a lot is when using +-- "Graphics.UI.FLTK.LowLevel.Table" which is a low-level table widget that +-- needs to be told, for example, how to draw its cells. The demo +-- /src\/Examples\/table-simple.hs/ (corresponding to the executable +-- '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. +-- 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. -- --- Additionally 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 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++ --- implementation. This comes in handy when the custom function is just setting up variables or logging and wants underlying --- implementation to take over at some point. +-- Additionally 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 +-- 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++ +-- implementation. This comes in handy when the custom function is just setting +-- up variables or logging and wants 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 automatically --- available to all subclasses of the widget. The author acknowledges 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 the author is --- open to removing this functionality. +-- __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. The author +-- acknowledges 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 the author +-- is 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 +-- 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 -- slowed down compilation of executables much more than expected. -- --- 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 runtime performance issues. This is only a compile time problem. +-- 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 +-- runtime performance issues. This is only a compile time problem. -- --- To preserve the user's and the author's sanity a flag `fastCompile` has been introduced to the and to the . --- This flag which tells the compiler to skip the specialising step 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 it is enabled by default, since the executables are just --- demos that are not meant to show off performance. To disable this flag, tell Cabal to ignore it during the `configure` step: +-- To preserve the user's and the author's sanity a flag `fastCompile` has been +-- introduced to the and +-- to the . +-- This flag which tells the compiler to skip the specialising step 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 +-- it is enabled by default, since the executables are just +-- demos that are not meant to show off performance. To disable this flag, tell +-- Stack to ignore it during the `build` step: -- -- @ --- cabal configure -f-fastCompile +-- > stack build --flag fltkhs-demos:-fastCompile -- @ -- --- In the and the project skeletons this flag is /disabled/ by --- default to provide the best runtime performance. To enable the flag for a smoother development workflow, tell Cabal to enable it during the `configure` step: +-- In the and the +-- project +-- 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: -- -- @ --- cabal configure -f fastCompile +-- > stack build --flag fltkhs-hello-world:fastCompile -- @ -- $CabalREPLIssues -- --- The recommended way to running the REPL in a `fltkhs` application is `cabal repl`. It works in GHC 7.8.x, but unfortunately will not work in GHC 7.10.x to due to a +-- The recommended way to load FLTKHS app into GHCi is the use the +-- `stack-repl.yaml` that comes bundled with the +-- . The +-- reasons are outlined in the "GHCi (All Users)" subsection of "Obstacles" above. -- +-- The REPL in the skeleton, for example, be run with: +-- +-- @ +-- > STACK_YAML=stack-repl.yaml stack setup --upgrade-cabal +-- > STACK_YAML=stack-repl.yaml stack ghci fltkhs-hello-world:exe:fltkhs-hello-world +-- @ +-- +-- The '--upgrade-cabal' flag above tells GHC to use the version in +-- 'stack-repl.yaml' (7.8.4) but upgrade the Cabal to 1.2.2. -- =File Layout -- @ diff --git a/stack-repl.yaml b/stack-repl.yaml new file mode 100644 --- /dev/null +++ b/stack-repl.yaml @@ -0,0 +1,25 @@ +# For more information, see: https://github.com/commercialhaskell/stack/blob/master/doc/yaml_configuration.md + +resolver: lts-2.22 + +# Local packages, usually specified by relative directory name +packages: +- '.' + +# Packages to be pulled from upstream that are not in the resolver (e.g., acme-missiles-0.3) +extra-deps: [] + +# Control whether we use the GHC we find on the path +# system-ghc: true + +# Require a specific version of stack, using version ranges +# require-stack-version: -any # Default +# require-stack-version: >= 0.1.4.0 + +# Override the architecture used by stack, especially useful on Windows +# arch: i386 +# arch: x86_64 + +# Extra directories used by stack for building +# extra-include-dirs: [/path/to/dir] +# extra-lib-dirs: [/path/to/dir] diff --git a/stack-windows.yaml b/stack-windows.yaml new file mode 100644 --- /dev/null +++ b/stack-windows.yaml @@ -0,0 +1,21 @@ +# For more information, see: https://github.com/commercialhaskell/stack/blob/master/doc/yaml_configuration.md + +resolver: lts-3.16 + +# Packages to be pulled from upstream that are not in the resolver (e.g., acme-missiles-0.3) +extra-deps: [] + +# Control whether we use the GHC we find on the path +# system-ghc: true + +# Require a specific version of stack, using version ranges +# require-stack-version: -any # Default +# require-stack-version: >= 0.1.4.0 + +# Override the architecture used by stack, especially useful on Windows +# arch: i386 +# arch: x86_64 + +# Extra directories used by stack for building +# extra-include-dirs: [/path/to/dir] +# extra-lib-dirs: [/path/to/dir] diff --git a/stack.yaml b/stack.yaml --- a/stack.yaml +++ b/stack.yaml @@ -1,7 +1,7 @@ -# For more information, see: https://github.com/commercialhaskell/stack/blob/master/doc/yaml_configuration.md +# For more information, see: http://docs.haskellstack.org/en/stable/yaml_configuration.html # Specifies the GHC version and set of packages available (e.g., lts-3.5, nightly-2015-09-21, ghc-7.10.2) -resolver: lts-3.8 +resolver: lts-5.3 # Local packages, usually specified by relative directory name packages: @@ -11,16 +11,17 @@ extra-deps: [] # Override default flag values for local packages and extra-deps -flags: - fltkhs: - fastcompile: true +flags: {} +# Extra package databases containing global packages +extra-package-dbs: [] + # Control whether we use the GHC we find on the path # system-ghc: true # Require a specific version of stack, using version ranges # require-stack-version: -any # Default -# require-stack-version: >= 0.1.4.0 +# require-stack-version: >= 1.0.0 # Override the architecture used by stack, especially useful on Windows # arch: i386 @@ -29,3 +30,6 @@ # Extra directories used by stack for building # extra-include-dirs: [/path/to/dir] # extra-lib-dirs: [/path/to/dir] + +# Allow a newer minor version of GHC than the snapshot specifies +# compiler-check: newer-minor