Module Graphics.UI

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: November 2020

Summary of exported operations:

row :: [Widget] -> Widget  Deterministic 
Horizontal alignment of widgets.
col :: [Widget] -> Widget  Deterministic 
Vertical alignment of widgets.
matrix :: [[Widget]] -> Widget  Deterministic 
Matrix alignment of widgets.
debugTcl :: Widget -> IO ()  Non-deterministic 
Prints the generated Tcl commands of a main widget (useful for debugging).
runPassiveGUI :: String -> Widget -> IO GuiPort  Non-deterministic 
IO action to show a Widget in a new GUI window in passive mode, i.e., ignore all GUI events.
runGUI :: String -> Widget -> IO ()  Non-deterministic 
IO action to run a Widget in a new window.
runGUIwithParams :: String -> String -> Widget -> IO ()  Non-deterministic 
IO action to run a Widget in a new window.
runInitGUI :: String -> Widget -> (GuiPort -> IO [ReconfigureItem]) -> IO ()  Non-deterministic 
IO action to run a Widget in a new window.
runInitGUIwithParams :: String -> String -> Widget -> (GuiPort -> IO [ReconfigureItem]) -> IO ()  Non-deterministic 
IO action to run a Widget in a new window.
runControlledGUI :: String -> (Widget,String -> GuiPort -> IO ()) -> Handle -> IO ()  Non-deterministic 
Runs a Widget in a new GUI window and process GUI events.
runConfigControlledGUI :: String -> (Widget,String -> GuiPort -> IO [ReconfigureItem]) -> Handle -> IO ()  Non-deterministic 
Runs a Widget in a new GUI window and process GUI events.
runInitControlledGUI :: String -> (Widget,String -> GuiPort -> IO ()) -> (GuiPort -> IO [ReconfigureItem]) -> Handle -> IO ()  Non-deterministic 
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 ()  Non-deterministic 
Runs a Widget in a new GUI window and process GUI events.
runInitHandlesControlledGUI :: String -> (Widget,[Handle -> GuiPort -> IO [ReconfigureItem]]) -> (GuiPort -> IO [ReconfigureItem]) -> [Handle] -> IO ()  Non-deterministic 
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 ()  Non-deterministic 
Changes the current configuration of a widget (deprecated operation, only included for backward compatibility).
exitGUI :: GuiPort -> IO ()  Deterministic 
An event handler for terminating the GUI.
getValue :: WidgetRef -> GuiPort -> IO String  Non-deterministic 
Gets the (String) value of a variable in a GUI.
setValue :: WidgetRef -> String -> GuiPort -> IO ()  Deterministic 
Sets the (String) value of a variable in a GUI.
updateValue :: (String -> String) -> WidgetRef -> GuiPort -> IO ()  Non-deterministic 
Updates the (String) value of a variable w.r.t.
appendValue :: WidgetRef -> String -> GuiPort -> IO ()  Deterministic 
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 ()  Deterministic 
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 ()  Deterministic 
Adds a style value in a region of a TextEdit widget.
removeRegionStyle :: WidgetRef -> (Int,Int) -> (Int,Int) -> Style -> GuiPort -> IO ()  Deterministic 
Removes a style value in a region of a TextEdit widget.
getCursorPosition :: WidgetRef -> GuiPort -> IO (Int,Int)  Non-deterministic 
Get the position (line,column) of the insertion cursor in a TextEdit widget.
seeText :: WidgetRef -> (Int,Int) -> GuiPort -> IO ()  Deterministic 
Adjust the view of a TextEdit widget so that the specified line/column character is visible.
focusInput :: WidgetRef -> GuiPort -> IO ()  Deterministic 
Sets the input focus of this GUI to the widget referred by the first argument.
addCanvas :: WidgetRef -> [CanvasItem] -> GuiPort -> IO ()  Non-deterministic 
Adds a list of canvas items to a canvas referred by the first argument.
popupMessage :: String -> IO ()  Non-deterministic 
A simple popup message.
Cmd :: (GuiPort -> IO ()) -> ConfItem  Deterministic 
A simple event handler that can be associated to a widget.
Command :: (GuiPort -> IO [ReconfigureItem]) -> ConfItem  Deterministic 
An event handler that can be associated to a widget.
Button :: (GuiPort -> IO ()) -> [ConfItem] -> Widget  Deterministic 
A button with an associated event handler which is activated if the button is pressed.
ConfigButton :: (GuiPort -> IO [ReconfigureItem]) -> [ConfItem] -> Widget  Deterministic 
A button with an associated event handler which is activated if the button is pressed.
TextEditScroll :: [ConfItem] -> Widget  Non-deterministic 
A text edit widget with vertical and horizontal scrollbars.
ListBoxScroll :: [ConfItem] -> Widget  Non-deterministic 
A list box widget with vertical and horizontal scrollbars.
CanvasScroll :: [ConfItem] -> Widget  Non-deterministic 
A canvas widget with vertical and horizontal scrollbars.
EntryScroll :: [ConfItem] -> Widget  Non-deterministic 
An entry widget with a horizontal scrollbar.
getOpenFile :: IO String  Deterministic 
Pops up a GUI for selecting an existing file.
getOpenFileWithTypes :: [(String,String)] -> IO String  Deterministic 
Pops up a GUI for selecting an existing file.
getSaveFile :: IO String  Deterministic 
Pops up a GUI for choosing a file to save some data.
getSaveFileWithTypes :: [(String,String)] -> IO String  Deterministic 
Pops up a GUI for choosing a file to save some data.
chooseColor :: IO String  Deterministic 
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  Deterministic 

Horizontal alignment of widgets.

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

col :: [Widget] -> Widget  Deterministic 

Vertical alignment of widgets.

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

matrix :: [[Widget]] -> Widget  Deterministic 

Matrix alignment of widgets.

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

debugTcl :: Widget -> IO ()  Non-deterministic 

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

runPassiveGUI :: String -> Widget -> IO GuiPort  Non-deterministic 

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

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

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

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

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

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

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

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

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

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

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

exitGUI :: GuiPort -> IO ()  Deterministic 

An event handler for terminating the GUI.

getValue :: WidgetRef -> GuiPort -> IO String  Non-deterministic 

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

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

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

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

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

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

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

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 codeBold/code, codeItalic/code and codeUnderline/code 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 ()  Deterministic 

Adds a style value in a region of a TextEdit widget. The region is specified a start and end position similarly to codegetCursorPosition/code. Different styles can be combined, e.g., to get bold blue text on a red background. If codeBold/code, codeItalic/code and codeUnderline/code 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 ()  Deterministic 

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

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

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

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

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

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

popupMessage :: String -> IO ()  Non-deterministic 

A simple popup message.

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

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  Deterministic 

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  Deterministic 

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

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

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  Non-deterministic 

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

ListBoxScroll :: [ConfItem] -> Widget  Non-deterministic 

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

CanvasScroll :: [ConfItem] -> Widget  Non-deterministic 

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

EntryScroll :: [ConfItem] -> Widget  Non-deterministic 

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

getOpenFile :: IO String  Deterministic 

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  Deterministic 

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  Deterministic 

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  Deterministic 

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  Deterministic 

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