Module GUI

This library contains definitions and functions to implement graphical user interfaces for Curry programs. It is based on Tcl/Tk and its basic ideas are described in detail in this paper

Version: January 2017

Summary of exported operations:

row
                  ::  [Widget] -> Widget

Horizontal alignment of widgets.

col
                  ::  [Widget] -> Widget

Vertical alignment of widgets.

matrix
                  ::  [[Widget]] -> Widget

Matrix alignment of widgets.

debugTcl
                  ::  Widget -> IO ()

Prints the generated Tcl commands of a main widget (useful for debugging).

runPassiveGUI
                  ::  String -> Widget -> IO GuiPort

IO action to show a Widget in a new GUI window in passive mode, i.e., ignore all GUI events.

runGUI
                  ::  String -> Widget -> IO ()

IO action to run a Widget in a new window.

runGUIwithParams
                  ::  String -> String -> Widget -> IO ()

IO action to run a Widget in a new window.

runInitGUI
                  ::  String -> Widget -> (GuiPort -> IO [ReconfigureItem]) -> IO ()

IO action to run a Widget in a new window.

runInitGUIwithParams
                  ::  String -> String -> Widget -> (GuiPort -> IO [ReconfigureItem]) -> IO ()

IO action to run a Widget in a new window.

runControlledGUI
                  ::  String -> (Widget,String -> GuiPort -> IO ()) -> Handle -> IO ()

Runs a Widget in a new GUI window and process GUI events.

runConfigControlledGUI
                  ::  String -> (Widget,String -> GuiPort -> IO [ReconfigureItem]) -> Handle -> IO ()

Runs a Widget in a new GUI window and process GUI events.

runInitControlledGUI
                  ::  String -> (Widget,String -> GuiPort -> IO ()) -> (GuiPort -> IO [ReconfigureItem]) -> Handle -> IO ()

Runs a Widget in a new GUI window and process GUI events after executing an initial action on the GUI window.

runHandlesControlledGUI
                  ::  String -> (Widget,[Handle -> GuiPort -> IO [ReconfigureItem]]) -> [Handle] -> IO ()

Runs a Widget in a new GUI window and process GUI events.

runInitHandlesControlledGUI
                  ::  String -> (Widget,[Handle -> GuiPort -> IO [ReconfigureItem]]) -> (GuiPort -> IO [ReconfigureItem]) -> [Handle] -> IO ()

Runs a Widget in a new GUI window and process GUI events after executing an initial action on the GUI window.

setConfig
                  ::  WidgetRef -> ConfItem -> GuiPort -> IO ()

Changes the current configuration of a widget (deprecated operation, only included for backward compatibility).

exitGUI
                  ::  GuiPort -> IO ()

An event handler for terminating the GUI.

getValue
                  ::  WidgetRef -> GuiPort -> IO String

Gets the (String) value of a variable in a GUI.

setValue
                  ::  WidgetRef -> String -> GuiPort -> IO ()

Sets the (String) value of a variable in a GUI.

updateValue
                  ::  (String -> String) -> WidgetRef -> GuiPort -> IO ()

Updates the (String) value of a variable w.r.t.

appendValue
                  ::  WidgetRef -> String -> GuiPort -> IO ()

Appends a String value to the contents of a TextEdit widget and adjust the view to the end of the TextEdit widget.

appendStyledValue
                  ::  WidgetRef -> String -> [Style] -> GuiPort -> IO ()

Appends a String value with style tags to the contents of a TextEdit widget and adjust the view to the end of the TextEdit widget.

addRegionStyle
                  ::  WidgetRef -> (Int,Int) -> (Int,Int) -> Style -> GuiPort -> IO ()

Adds a style value in a region of a TextEdit widget.

removeRegionStyle
                  ::  WidgetRef -> (Int,Int) -> (Int,Int) -> Style -> GuiPort -> IO ()

Removes a style value in a region of a TextEdit widget.

getCursorPosition
                  ::  WidgetRef -> GuiPort -> IO (Int,Int)

Get the position (line,column) of the insertion cursor in a TextEdit widget.

seeText
                  ::  WidgetRef -> (Int,Int) -> GuiPort -> IO ()

Adjust the view of a TextEdit widget so that the specified line/column character is visible.

focusInput
                  ::  WidgetRef -> GuiPort -> IO ()

Sets the input focus of this GUI to the widget referred by the first argument.

addCanvas
                  ::  WidgetRef -> [CanvasItem] -> GuiPort -> IO ()

Adds a list of canvas items to a canvas referred by the first argument.

popupMessage
                  ::  String -> IO ()

A simple popup message.

Cmd
                  ::  (GuiPort -> IO ()) -> ConfItem

A simple event handler that can be associated to a widget.

Command
                  ::  (GuiPort -> IO [ReconfigureItem]) -> ConfItem

An event handler that can be associated to a widget.

Button
                  ::  (GuiPort -> IO ()) -> [ConfItem] -> Widget

A button with an associated event handler which is activated if the button is pressed.

ConfigButton
                  ::  (GuiPort -> IO [ReconfigureItem]) -> [ConfItem] -> Widget

A button with an associated event handler which is activated if the button is pressed.

TextEditScroll
                  ::  [ConfItem] -> Widget

A text edit widget with vertical and horizontal scrollbars.

ListBoxScroll
                  ::  [ConfItem] -> Widget

A list box widget with vertical and horizontal scrollbars.

CanvasScroll
                  ::  [ConfItem] -> Widget

A canvas widget with vertical and horizontal scrollbars.

EntryScroll
                  ::  [ConfItem] -> Widget

An entry widget with a horizontal scrollbar.

getOpenFile
                  ::  IO String

Pops up a GUI for selecting an existing file.

getOpenFileWithTypes
                  ::  [(String,String)] -> IO String

Pops up a GUI for selecting an existing file.

getSaveFile
                  ::  IO String

Pops up a GUI for choosing a file to save some data.

getSaveFileWithTypes
                  ::  [(String,String)] -> IO String

Pops up a GUI for choosing a file to save some data.

chooseColor
                  ::  IO String

Pops up a GUI dialog box to select a color.

Exported datatypes:

GuiPort

The port to a GUI is just the stream connection to a GUI where Tcl/Tk communication is done.

Constructors:

The type of possible widgets in a GUI.

Constructors:

PlainButton :: [ConfItem] -> Widget : a button in a GUI whose event handler is activated if the user presses the button
Canvas :: [ConfItem] -> Widget : a canvas to draw pictures containing CanvasItems
CheckButton :: [ConfItem] -> Widget : a check button: it has value "0" if it is unchecked and value "1" if it is checked
Entry :: [ConfItem] -> Widget : an entry widget for entering single lines
Label :: [ConfItem] -> Widget : a label for showing a text
ListBox :: [ConfItem] -> Widget : a widget containing a list of items for selection
Message :: [ConfItem] -> Widget : a message for showing simple string values
MenuButton :: [ConfItem] -> Widget : a button with a pull-down menu
Scale :: Int -> Int -> [ConfItem] -> Widget : a scale widget to input values by a slider
ScrollH :: WidgetRef -> [ConfItem] -> Widget : a horizontal scroll bar
ScrollV :: WidgetRef -> [ConfItem] -> Widget : a vertical scroll bar
TextEdit :: [ConfItem] -> Widget : a text editor widget to show and manipulate larger text paragraphs
Row :: [ConfCollection] -> [Widget] -> Widget : a horizontal alignment of widgets
Col :: [ConfCollection] -> [Widget] -> Widget : a vertical alignment of widgets
Matrix :: [ConfCollection] -> [[Widget]] -> Widget : a 2-dimensional (matrix) alignment of widgets

ConfItem

The data type for possible configurations of a widget.

Constructors:

Active :: Bool -> ConfItem : define the active state for buttons, entries, etc.
Anchor :: String -> ConfItem : alignment of information inside a widget where the argument must be: n, ne, e, se, s, sw, w, nw, or center
Background :: String -> ConfItem : the background color
Foreground :: String -> ConfItem : the foreground color
Handler :: Event -> (GuiPort -> IO [ReconfigureItem]) -> ConfItem : an event handler associated to a widget. The event handler returns a list of widget ref/configuration pairs that are applied after the handler in order to configure GUI widgets
Height :: Int -> ConfItem : the height of a widget (chars for text, pixels for graphics)
CheckInit :: String -> ConfItem : initial value for checkbuttons
CanvasItems :: [CanvasItem] -> ConfItem : list of items contained in a canvas
List :: [String] -> ConfItem : list of values shown in a listbox
Menu :: [MenuItem] -> ConfItem : the items of a menu button
WRef :: WidgetRef -> ConfItem : a reference to this widget
Text :: String -> ConfItem : an initial text contents
Width :: Int -> ConfItem : the width of a widget (chars for text, pixels for graphics)
Fill :: ConfItem : fill widget in both directions
FillX :: ConfItem : fill widget in horizontal direction
FillY :: ConfItem : fill widget in vertical direction
TclOption :: String -> ConfItem : further options in Tcl syntax (unsafe!)

ReconfigureItem

Data type for describing configurations that are applied to a widget or GUI by some event handler.

Constructors:

WidgetConf :: WidgetRef -> ConfItem -> ReconfigureItem : reconfigure the widget referred by wref with configuration item conf
StreamHandler :: Handle -> (Handle -> GuiPort -> IO [ReconfigureItem]) -> ReconfigureItem : add a new handler to the GUI that processes inputs on an input stream referred by hdl
RemoveStreamHandler :: Handle -> ReconfigureItem : remove a handler for an input stream referred by hdl from the GUI (usually used to remove handlers for closed streams)

Event

The data type of possible events on which handlers can react. This list is still incomplete and might be extended or restructured in future releases of this library.

Constructors:

DefaultEvent :: Event : the default event of the widget
MouseButton1 :: Event : left mouse button pressed
MouseButton2 :: Event : middle mouse button pressed
MouseButton3 :: Event : right mouse button pressed
KeyPress :: Event : any key is pressed
Return :: Event : return key is pressed

ConfCollection

The data type for possible configurations of widget collections (e.g., columns, rows).

Constructors:

CenterAlign :: ConfCollection : centered alignment
LeftAlign :: ConfCollection : left alignment
RightAlign :: ConfCollection : right alignment
TopAlign :: ConfCollection : top alignment
BottomAlign :: ConfCollection : bottom alignment

MenuItem

The data type for specifying items in a menu.

Constructors:

MButton :: (GuiPort -> IO [ReconfigureItem]) -> String -> MenuItem : a button with an associated command and a label string
MSeparator :: MenuItem : a separator between menu entries
MMenuButton :: String -> [MenuItem] -> MenuItem : a submenu with a label string

CanvasItem

The data type of items in a canvas. The last argument are further options in Tcl/Tk (for testing).

Constructors:

CLine :: [(Int,Int)] -> String -> CanvasItem
CPolygon :: [(Int,Int)] -> String -> CanvasItem
CRectangle :: (Int,Int) -> (Int,Int) -> String -> CanvasItem
COval :: (Int,Int) -> (Int,Int) -> String -> CanvasItem
CText :: (Int,Int) -> String -> String -> CanvasItem

WidgetRef

The (hidden) data type of references to a widget in a GUI window. Note that the constructor WRefLabel will not be exported so that values can only be created inside this module.

Constructors:

Style

The data type of possible text styles.

Constructors:

Bold :: Style : text in bold font
Italic :: Style : text in italic font
Underline :: Style : underline text
Fg :: Color -> Style : foreground color, i.e., color of the text font
Bg :: Color -> Style : background color of the text

Color

The data type of possible colors.

Constructors:

Black :: Color
Blue :: Color
Brown :: Color
Cyan :: Color
Gold :: Color
Gray :: Color
Green :: Color
Magenta :: Color
Navy :: Color
Orange :: Color
Pink :: Color
Purple :: Color
Red :: Color
Tomato :: Color
Turquoise :: Color
Violet :: Color
White :: Color
Yellow :: Color

Exported operations:

row :: [Widget] -> Widget

Horizontal alignment of widgets.

Further infos:

solution complete, i.e., able to compute all solutions

col :: [Widget] -> Widget

Vertical alignment of widgets.

Further infos:

solution complete, i.e., able to compute all solutions

matrix :: [[Widget]] -> Widget

Matrix alignment of widgets.

Further infos:

solution complete, i.e., able to compute all solutions

debugTcl :: Widget -> IO ()

Prints the generated Tcl commands of a main widget (useful for debugging).

runPassiveGUI :: String -> Widget -> IO GuiPort

IO action to show a Widget in a new GUI window in passive mode, i.e., ignore all GUI events.

Example call:: (runPassiveGUI title widget)

Parameters:

title : the title of the main window containing the widget
widget : the widget shown in the new window

runGUI :: String -> Widget -> IO ()

IO action to run a Widget in a new window.

Example call:: (runGUI title widget)

Parameters:

title : the title of the main window containing the widget
widget : the widget shown in the new window

runGUIwithParams :: String -> String -> Widget -> IO ()

IO action to run a Widget in a new window.

Example call:: (runGUIwithParams title params widget)

Parameters:

title : the title of the main window containing the widget
params : parameter string passed to the initial wish command
widget : the widget shown in the new window

runInitGUI :: String -> Widget -> (GuiPort -> IO [ReconfigureItem]) -> IO ()

IO action to run a Widget in a new window. The GUI events are processed after executing an initial action on the GUI.

Example call:: (runInitGUI title widget initcmd)

Parameters:

title : the title of the main GUI window
widget : the widget shown in the new GUI window
initcmd : the initial command executed before activating the GUI

runInitGUIwithParams :: String -> String -> Widget -> (GuiPort -> IO [ReconfigureItem]) -> IO ()

IO action to run a Widget in a new window. The GUI events are processed after executing an initial action on the GUI.

Example call:: (runInitGUIwithParams title params widget initcmd)

Parameters:

title : the title of the main GUI window
params : parameter string passed to the initial wish command
widget : the widget shown in the new GUI window
initcmd : the initial command executed before activating the GUI

runControlledGUI :: String -> (Widget,String -> GuiPort -> IO ()) -> Handle -> IO ()

Runs a Widget in a new GUI window and process GUI events. In addition, an event handler is provided that process messages received from an external stream identified by a handle (third argument). This operation is useful to run a GUI that should react on user events as well as messages written to the given handle.

Example call:: (runControlledGUI title th hdl)

Parameters:

title : the title of the main window containing the widget
th : a pair (widget,exth) where widget is the widget shown in the new window and exth is the event handler for external messages
hdl : the handle of the stream of external messages

runConfigControlledGUI :: String -> (Widget,String -> GuiPort -> IO [ReconfigureItem]) -> Handle -> IO ()

Example call:: (runConfigControlledGUI title th hdl)

Parameters:

title : the title of the main window containing the widget
th : a pair (widget,exth) where widget is the widget shown in the new window and exth is the event handler for external messages that returns a list of widget reference/configuration pairs which is applied after the handler in order to configure some GUI widgets
hdl : the handle of the stream of external messages

runInitControlledGUI :: String -> (Widget,String -> GuiPort -> IO ()) -> (GuiPort -> IO [ReconfigureItem]) -> Handle -> IO ()

Runs a Widget in a new GUI window and process GUI events after executing an initial action on the GUI window. In addition, an event handler is provided that process messages received from an external message stream. This operation is useful to run a GUI that should react on user events as well as messages written to the given handle.

Example call:: (runInitControlledGUI title th initcmd hdl)

Parameters:

title : the title of the main window containing the widget
th : a pair (widget,exth) where widget is the widget shown in the new window and exth is the event handler for external messages
initcmd : the initial command executed before starting the GUI
hdl : the handle of the stream of external messages

runHandlesControlledGUI :: String -> (Widget,[Handle -> GuiPort -> IO [ReconfigureItem]]) -> [Handle] -> IO ()

Runs a Widget in a new GUI window and process GUI events. In addition, a list of event handlers is provided that process inputs received from a corresponding list of handles to input streams. Thus, if the i-th handle has some data available, the i-th event handler is executed with the i-th handle as a parameter. This operation is useful to run a GUI that should react on inputs provided by other processes, e.g., via sockets.

Example call:: (runHandlesControlledGUI title th handles)

Parameters:

title : the title of the main window containing the widget
th : a pair (widget,handlers) where widget is the widget shown in the new window and handlers is a list of event handler for external inputs
handles : a list of handles to the external input streams for the corresponding event handlers

runInitHandlesControlledGUI :: String -> (Widget,[Handle -> GuiPort -> IO [ReconfigureItem]]) -> (GuiPort -> IO [ReconfigureItem]) -> [Handle] -> IO ()

Runs a Widget in a new GUI window and process GUI events after executing an initial action on the GUI window. In addition, a list of event handlers is provided that process inputs received from a corresponding list of handles to input streams. Thus, if the i-th handle has some data available, the i-th event handler is executed with the i-th handle as a parameter. This operation is useful to run a GUI that should react on inputs provided by other processes, e.g., via sockets.

Example call:: (runInitHandlesControlledGUI title th initcmd handles)

Parameters:

title : the title of the main window containing the widget
th : a pair (widget,handlers) where widget is the widget shown in the new window and handlers is a list of event handler for external inputs
initcmd : the initial command executed before starting the GUI
handles : a list of handles to the external input streams for the corresponding event handlers

setConfig :: WidgetRef -> ConfItem -> GuiPort -> IO ()

Changes the current configuration of a widget (deprecated operation, only included for backward compatibility). Warning: does not work for Command options!

exitGUI :: GuiPort -> IO ()

An event handler for terminating the GUI.

getValue :: WidgetRef -> GuiPort -> IO String

Gets the (String) value of a variable in a GUI.

setValue :: WidgetRef -> String -> GuiPort -> IO ()

Sets the (String) value of a variable in a GUI.

updateValue :: (String -> String) -> WidgetRef -> GuiPort -> IO ()

Updates the (String) value of a variable w.r.t. to an update function.

appendValue :: WidgetRef -> String -> GuiPort -> IO ()

Appends a String value to the contents of a TextEdit widget and adjust the view to the end of the TextEdit widget.

appendStyledValue :: WidgetRef -> String -> [Style] -> GuiPort -> IO ()

Appends a String value with style tags to the contents of a TextEdit widget and adjust the view to the end of the TextEdit widget. Different styles can be combined, e.g., to get bold blue text on a red background. If Bold, Italic and Underline are combined, currently all but one of these are ignored. This is an experimental function and might be changed in the future.

addRegionStyle :: WidgetRef -> (Int,Int) -> (Int,Int) -> Style -> GuiPort -> IO ()

Adds a style value in a region of a TextEdit widget. The region is specified a start and end position similarly to getCursorPosition. Different styles can be combined, e.g., to get bold blue text on a red background. If Bold, Italic and Underline are combined, currently all but one of these are ignored. This is an experimental function and might be changed in the future.

removeRegionStyle :: WidgetRef -> (Int,Int) -> (Int,Int) -> Style -> GuiPort -> IO ()

Removes a style value in a region of a TextEdit widget. The region is specified a start and end position similarly to getCursorPosition. This is an experimental function and might be changed in the future.

getCursorPosition :: WidgetRef -> GuiPort -> IO (Int,Int)

Get the position (line,column) of the insertion cursor in a TextEdit widget. Lines are numbered from 1 and columns are numbered from 0.

seeText :: WidgetRef -> (Int,Int) -> GuiPort -> IO ()

Adjust the view of a TextEdit widget so that the specified line/column character is visible. Lines are numbered from 1 and columns are numbered from 0.

focusInput :: WidgetRef -> GuiPort -> IO ()

Sets the input focus of this GUI to the widget referred by the first argument. This is useful for automatically selecting input entries in an application.

addCanvas :: WidgetRef -> [CanvasItem] -> GuiPort -> IO ()

Adds a list of canvas items to a canvas referred by the first argument.

popupMessage :: String -> IO ()

A simple popup message.

Cmd :: (GuiPort -> IO ()) -> ConfItem

A simple event handler that can be associated to a widget. The event handler takes a GUI port as parameter in order to read or write values from/into the GUI.

Command :: (GuiPort -> IO [ReconfigureItem]) -> ConfItem

An event handler that can be associated to a widget. The event handler takes a GUI port as parameter (in order to read or write values from/into the GUI) and returns a list of widget reference/configuration pairs which is applied after the handler in order to configure some GUI widgets.

Further infos:

solution complete, i.e., able to compute all solutions

Button :: (GuiPort -> IO ()) -> [ConfItem] -> Widget

A button with an associated event handler which is activated if the button is pressed.

ConfigButton :: (GuiPort -> IO [ReconfigureItem]) -> [ConfItem] -> Widget

A button with an associated event handler which is activated if the button is pressed. The event handler is a configuration handler (see Command) that allows the configuration of some widgets.

Further infos:

solution complete, i.e., able to compute all solutions

TextEditScroll :: [ConfItem] -> Widget

A text edit widget with vertical and horizontal scrollbars. The argument contains the configuration options for the text edit widget.

ListBoxScroll :: [ConfItem] -> Widget

A list box widget with vertical and horizontal scrollbars. The argument contains the configuration options for the list box widget.

CanvasScroll :: [ConfItem] -> Widget

A canvas widget with vertical and horizontal scrollbars. The argument contains the configuration options for the text edit widget.

EntryScroll :: [ConfItem] -> Widget

An entry widget with a horizontal scrollbar. The argument contains the configuration options for the entry widget.

getOpenFile :: IO String

Pops up a GUI for selecting an existing file. The file with its full path name will be returned (or "" if the user cancels the selection).

getOpenFileWithTypes :: [(String,String)] -> IO String

Pops up a GUI for selecting an existing file. The parameter is a list of pairs of file types that could be selected. A file type pair consists of a name and an extension for that file type. The file with its full path name will be returned (or "" if the user cancels the selection).

getSaveFile :: IO String

Pops up a GUI for choosing a file to save some data. If the user chooses an existing file, she/he will asked to confirm to overwrite it. The file with its full path name will be returned (or "" if the user cancels the selection).

getSaveFileWithTypes :: [(String,String)] -> IO String

Pops up a GUI for choosing a file to save some data. The parameter is a list of pairs of file types that could be selected. A file type pair consists of a name and an extension for that file type. If the user chooses an existing file, she/he will asked to confirm to overwrite it. The file with its full path name will be returned (or "" if the user cancels the selection).

chooseColor :: IO String

Pops up a GUI dialog box to select a color. The name of the color will be returned (or "" if the user cancels the selection).