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:


Widget

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 ()   

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:
(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.

Further infos:
  • solution complete, i.e., able to compute all solutions

ListBoxScroll :: [ConfItem] -> Widget   

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

Further infos:
  • solution complete, i.e., able to compute all solutions

CanvasScroll :: [ConfItem] -> Widget   

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

Further infos:
  • solution complete, i.e., able to compute all solutions

EntryScroll :: [ConfItem] -> Widget   

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

Further infos:
  • solution complete, i.e., able to compute all solutions

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).