Game.Goatee.Ui.Gtk.Common

Common dependencies among all GTK+ UI code. Contains class definitions and some common data declarations.

UI Go monads

class MonadGo go => MonadUiGo go where

A class for monads that provide the features required to be used with a UiCtrl. The type must have a MonadGo instance and also provide access to some internal state, UiGoState.

Minimal complete definition

runUiGo, uiGoGetState, uiGoPutState, uiGoModifyState

Methods

runUiGo :: Cursor -> go a -> (a, Cursor, UiGoState)

Evaluates the Go monad, returning the final value and cursor as well as the internal UiGoState.

uiGoGetState :: go UiGoState

Retrieves the current internal state.

uiGoPutState :: UiGoState -> go ()

Assigns to the current internal state.

uiGoModifyState :: (UiGoState -> UiGoState) -> go ()

Modifies the current internal state with the given function.

uiGoUpdateView :: MonadUiGo go => ViewId -> go ()

Forces the view with the given ID to update after the Go action completes.

uiGoMakeDirty :: MonadUiGo go => go ()

Forces the UI to become dirty after the Go action completes. See setDirty.

data UiGoState

Internal state held by a type that implements MonadUiGo.

Constructors

UiGoState

Fields

• uiGoViewsToUpdate :: Set ViewId

  Keeps track of views that need updating after the Go action completes.

• uiGoMakesDirty :: Bool

  Whether the UI should be marked dirty as a result of running the Go action.

initialUiGoState :: UiGoState

The state with which a UI Go action should start executing.

UI controllers

class MonadUiGo go => UiCtrl go ui | ui -> go where

A controller for the GTK+ UI. A controller corresponds to a single open game.

The controller is agnostic to the type of Go monad it is used with, as long as it implements the functionality in MonadUiGo. The monad can have extra functionality, e.g. for testing or debugging.

Minimal complete definition

readModes, modifyModes, findTool, doUiGo, readCursor, isValidMove, playAt, register, unregister, unregisterAll, registeredHandlers, registerModesChangedHandler, unregisterModesChangedHandler, registeredModesChangedHandlers, getMainWindow, openBoard, fileOpen, fileSave, fileSaveAs, fileClose, fileCloseSilently, fileQuit, editCutNode, editCopyNode, editPasteNode, helpKeyBindings, helpAbout, getFilePath, setFilePath, registerFilePathChangedHandler, unregisterFilePathChangedHandler, registeredFilePathChangedHandlers, getDirty, setDirty, registerDirtyChangedHandler, unregisterDirtyChangedHandler, registeredDirtyChangedHandlers

Methods

readModes :: ui -> IO UiModes

Reads the current UI modes.

modifyModes :: ui -> (UiModes -> IO UiModes) -> IO ()

Modifies the controller's modes according to the given action, then fires a mode change event via fireViewModesChanged.

findTool :: ui -> ToolType -> IO (AnyTool go ui)

Looks up the tool bound to a ToolType.

readTool :: ui -> IO (AnyTool go ui)

Reads the active tool.

doUiGo :: ui -> go a -> IO a

Runs a Go monad on the current cursor, updating the cursor and firing handlers as necessary.

readCursor :: ui -> IO Cursor

Returns the current cursor.

isValidMove :: ui -> Coord -> IO Bool

Determines whether it is currently valid to play at the given point.

playAt :: ui -> Maybe Coord -> IO ()

Makes the current player place a stone at the given point, or pass in the case of Nothing.

register :: UiView go ui view => view -> [AnyEvent go] -> IO ()

Registers a view to update when any of the given Events fires. The controller will call viewUpdate after the Go action finishes running.

When the view is destroyed, it must call unregister or unregisterAll to free the handlers it has installed. viewDestroy calls this, and all views should call viewDestroy, so there is no need to call this manually.

unregister :: UiView go ui view => view -> AnyEvent go -> IO Bool

Stops the controller from updating the view when the Event fires. Returns true if there was a registration that was removed.

unregisterAll :: UiView go ui view => view -> IO ()

Stops the controller from updating the view entirely.

registeredHandlers :: ui -> IO [(String, String)]

Returns the currently registered handlers, as (owner, event name) pairs.

registerModesChangedHandler :: ui -> String -> ModesChangedHandler -> IO Registration

Registers a handler that will execute when UI modes change. The string is the name of the caller, used to keep track of what components registered what handlers.

unregisterModesChangedHandler :: ui -> Registration -> IO Bool

Unregisters the modes-changed handler for a Registration that was returned from registerModesChangedHandler. Returns true if such a handler was found and removed.

registeredModesChangedHandlers :: ui -> IO [String]

Returns the owners of the currently registered ModesChangedHandlers.

getMainWindow :: ui -> IO Window

Returns the Window for the game's MainWindow.

openBoard :: Maybe ui -> Maybe FilePath -> Node -> IO ui

openNewBoard :: Maybe ui -> Maybe (Int, Int) -> IO ui

openFile :: Maybe ui -> FilePath -> IO (Either String ui)

fileOpen :: ui -> IO ()

Prompts with an open file dialog for a game to open, then opens the selected game if the user picks one.

fileSave :: ui -> IO Bool

Saves the current game to a file. If the current game is not currently tied to a file, then this will act identically to fileSaveAs. Returns true iff the game was saved.

fileSaveAs :: ui -> IO Bool

Presents a file save dialog for the user to specify a file to write the current game to. If the user provides a filename, then the game is written. If the user names an existing file, then another dialog confirms overwriting the existing file. Returns true iff the user accepted the dialog(s) and the game was saved.

fileClose :: ui -> IO Bool

Closes the game and all UI windows, etc. attached to the given controller. If the game is dirty, then a dialog first prompts the user whether to save, throw away changes, or abort the closing.

fileCloseSilently :: ui -> IO ()

Hides and releases the game's UI window, and shut downs the UI controller (in effect closing the game, with no prompting). If this is the last board open, then the application will exit.

fileQuit :: ui -> IO Bool

Closes all open games and exits the program. If any games are dirty then we check if the user wants to save them. If the user clicks cancel at any point then shutdown is cancelled and no games are closed.

editCutNode :: ui -> IO ()

Performs a copy a la editCopyNode. If this copy succeeds, then we navigate to the parent of the current node, and delete the node we were just on from the tree.

editCopyNode :: ui -> IO ()

Copies an SGF representation of the subtree rooted at the current node onto the system clipboard. If the node fails to render, then an error dialog is displayed and the clipboard is left untouched.

editPasteNode :: ui -> IO ()

Attempts to parse text on the system clipboard as an SGF subtree and insert the parsed node below the current node.

helpKeyBindings :: ui -> IO ()

Presents the user with a dialog that shows the UI's key bindings.

helpAbout :: ui -> IO ()

Presents the user with an about dialog that shows general information about the application to the user (authorship, license, etc.).

getFilePath :: ui -> IO (Maybe FilePath)

Returns the path to the file that the UI is currently displaying, or nothing if the UI is displaying an unsaved game.

getFileName :: ui -> IO String

Returns the filename (base name, with no directories before it) that is currently open in the UI, or if the UI is showing an unsaved game, then a fallback "untitled" string. As this may not be a real filename, it should be used for display purposes only, and not for actually writing to.

setFilePath :: ui -> Maybe FilePath -> IO ()

Sets the path to the file that the UI is currently displaying. This changes the value returned by getFilePath but does not do any saving or loading.

registerFilePathChangedHandler :: ui -> String -> Bool -> FilePathChangedHandler -> IO Registration

Registers a handler that will execute when the file path the UI is bound to changes.

unregisterFilePathChangedHandler :: ui -> Registration -> IO Bool

Unregisters the handler for a Registration that was returned from registerFilePathChangedHandler. Returns true if such a handler was found and removed.

registeredFilePathChangedHandlers :: ui -> IO [String]

Returns the owners of the currently registered FilePathChangedHandlers.

getDirty :: ui -> IO Bool

Returns whether the UI is dirty, i.e. whether there are unsaved changes to the current game.

setDirty :: ui -> Bool -> IO ()

Sets the dirty state of the UI.

registerDirtyChangedHandler :: ui -> String -> Bool -> DirtyChangedHandler -> IO Registration

Registers a handler that will execute when the dirty state of the UI changes.

unregisterDirtyChangedHandler :: ui -> Registration -> IO Bool

Unregisters the handler for a Registration that was returned from registerDirtyChangedHandler. Returns true if such a handler was found and removed.

registeredDirtyChangedHandlers :: ui -> IO [String]

Returns the owners of the currently registered DirtyChangedHandlers.

data AnyUiCtrl

An existential type for all UI controllers.

Constructors

UiCtrl go ui => AnyUiCtrl ui

type Registration = Unique

A key that refers to registration of a handler with a UI controller, for non-Go-monad events. Used to unregister handlers.

type DirtyChangedHandler = Bool -> IO ()

A handler for when the dirty state of the UI changes. Passed the new dirty state. The old dirty state is the logical negation of the new state.

type FilePathChangedHandler = Maybe FilePath -> Maybe FilePath -> IO ()

A handler for taking action when the file path for the current game changes. Passed the old path and the new path, in that order.

type ModesChangedHandler = UiModes -> UiModes -> IO ()

A handler for taking action when UI modes change. Passed the old modes and the new modes, in that order.

modifyModesPure :: UiCtrl go ui => ui -> (UiModes -> UiModes) -> IO ()

setTool :: UiCtrl go ui => ui -> ToolType -> IO ()

Assigns to the current tool within the modes of ui (firing any relevant change handlers).

UI views

class UiCtrl go ui => UiView go ui view | view -> ui where

A UI widget that listens to the state of a UiCtrl. This class makes it easy to ask to be updated on relevant changes with register.

Minimal complete definition

viewName, viewCtrl, viewState, viewUpdate

Methods

viewName :: view -> String

A printable name of the view; usually just the data type name.

viewCtrl :: view -> ui

A reference to the view's controller.

viewState :: view -> ViewState

Internal housekeeping data for the view. Create with viewStateNew. A ViewState may only be used with a single view.

viewUpdate :: view -> IO ()

Updates the UI state of the view based on the current state of data that backs it in the model.

data AnyView

An existential type over all views. Provides Eq and Ord instances that use each view's ViewId, and a Show instance that returns a view's name.

Constructors

UiView go ui view => AnyView view

Instances

Eq AnyView

Methods

(==) :: AnyView -> AnyView -> Bool

(/=) :: AnyView -> AnyView -> Bool

Ord AnyView

Methods

compare :: AnyView -> AnyView -> Ordering

(<) :: AnyView -> AnyView -> Bool

(<=) :: AnyView -> AnyView -> Bool

(>) :: AnyView -> AnyView -> Bool

(>=) :: AnyView -> AnyView -> Bool

max :: AnyView -> AnyView -> AnyView

min :: AnyView -> AnyView -> AnyView

Show AnyView

Methods

showsPrec :: Int -> AnyView -> ShowS

show :: AnyView -> String

showList :: [AnyView] -> ShowS

data ViewId

A application-wide unique identifier for referring to an instance of a view.

Instances

Eq ViewId

Methods

(==) :: ViewId -> ViewId -> Bool

(/=) :: ViewId -> ViewId -> Bool

Ord ViewId

Methods

compare :: ViewId -> ViewId -> Ordering

(<) :: ViewId -> ViewId -> Bool

(<=) :: ViewId -> ViewId -> Bool

(>) :: ViewId -> ViewId -> Bool

(>=) :: ViewId -> ViewId -> Bool

max :: ViewId -> ViewId -> ViewId

min :: ViewId -> ViewId -> ViewId

data ViewState

Internal controller housekeeping data for a view.

viewStateNew :: IO ViewState

Creates a new ViewState.

viewDestroy :: UiView go ui view => view -> IO ()

Cleans up the internal state of a view, and releases registered Go event handlers for the view. Views should call this when destroying themselves; this does not force a view to destroy itself.

viewId :: UiView go ui view => view -> ViewId

Returns a view's unique ID.

UI modes

data UiModes

Constructors

UiModes

Fields

• uiViewStonesMode :: ViewStonesMode
• uiViewStonesOneColorModeColor :: Color
• uiHighlightCurrentMovesMode :: Bool

  Whether to draw an indicator on the game board for moves on the current node.

• uiToolType :: ToolType

Instances

Eq UiModes

Methods

(==) :: UiModes -> UiModes -> Bool

(/=) :: UiModes -> UiModes -> Bool

Show UiModes

Methods

showsPrec :: Int -> UiModes -> ShowS

show :: UiModes -> String

showList :: [UiModes] -> ShowS

data ViewStonesMode

Constructors

ViewStonesRegularMode

ViewStonesOneColorMode

ViewStonesBlindMode

Instances

Bounded ViewStonesMode

Methods

minBound :: ViewStonesMode

maxBound :: ViewStonesMode

Enum ViewStonesMode

Methods

succ :: ViewStonesMode -> ViewStonesMode

pred :: ViewStonesMode -> ViewStonesMode

toEnum :: Int -> ViewStonesMode

fromEnum :: ViewStonesMode -> Int

enumFrom :: ViewStonesMode -> [ViewStonesMode]

enumFromThen :: ViewStonesMode -> ViewStonesMode -> [ViewStonesMode]

enumFromTo :: ViewStonesMode -> ViewStonesMode -> [ViewStonesMode]

enumFromThenTo :: ViewStonesMode -> ViewStonesMode -> ViewStonesMode -> [ViewStonesMode]

Eq ViewStonesMode

Methods

(==) :: ViewStonesMode -> ViewStonesMode -> Bool

(/=) :: ViewStonesMode -> ViewStonesMode -> Bool

Show ViewStonesMode

Methods

showsPrec :: Int -> ViewStonesMode -> ShowS

show :: ViewStonesMode -> String

showList :: [ViewStonesMode] -> ShowS

defaultUiModes :: UiModes

Tools

data ToolType

Selectable tools for operating on the board. See UiTool.

Constructors

ToolPlay

Game tool.

ToolJump

Game tool.

ToolScore

Game tool.

ToolAssignBlack

Editing tool.

ToolAssignWhite

Editing tool.

ToolAssignEmpty

Editing tool.

ToolMarkCircle

Markup tool.

ToolMarkSelected

Markup tool.

ToolMarkSquare

Markup tool.

ToolMarkTriangle

Markup tool.

ToolMarkX

Markup tool.

ToolArrow

Markup tool.

ToolLine

Markup tool.

ToolLabel

Markup tool.

ToolVisible

Visibility tool.

ToolDim

Visibility tool.

Instances

Bounded ToolType

Methods

minBound :: ToolType

maxBound :: ToolType

Enum ToolType

Methods

succ :: ToolType -> ToolType

pred :: ToolType -> ToolType

toEnum :: Int -> ToolType

fromEnum :: ToolType -> Int

enumFrom :: ToolType -> [ToolType]

enumFromThen :: ToolType -> ToolType -> [ToolType]

enumFromTo :: ToolType -> ToolType -> [ToolType]

enumFromThenTo :: ToolType -> ToolType -> ToolType -> [ToolType]

Eq ToolType

Methods

(==) :: ToolType -> ToolType -> Bool

(/=) :: ToolType -> ToolType -> Bool

Ord ToolType

Methods

compare :: ToolType -> ToolType -> Ordering

(<) :: ToolType -> ToolType -> Bool

(<=) :: ToolType -> ToolType -> Bool

(>) :: ToolType -> ToolType -> Bool

(>=) :: ToolType -> ToolType -> Bool

max :: ToolType -> ToolType -> ToolType

min :: ToolType -> ToolType -> ToolType

Show ToolType

Methods

showsPrec :: Int -> ToolType -> ShowS

show :: ToolType -> String

showList :: [ToolType] -> ShowS

class UiView go ui tool => UiTool go ui tool where

A tool is a mode of interaction between the user and the board, that determines what actions the user can perform to the game. A tool interacts with the goban and controls how mouse events are responded to. A tool can also provide a widget (or container of widgets) that will be inserted into the side panel while the tool is active.

The ToolType enum contains an entry for each tool. This UiTool class is used to define the implementation of a tool. A UiCtrl manages tools, and maps ToolTypes to UiTools. These can be accessed with findTool and readTool.

The goban sends events to the active tool as they occur, via toolGobanHandleEvent. The tool can then affect what the goban displays by overriding toolGobanRenderGetBoard and/or toolGobanRenderModifyCoords.

Minimal complete definition

toolState

Methods

toolState :: tool -> ToolState

Internal housekeeping data for the tool. Create with toolStateNew. A ToolState may only be used with a single tool.

toolIsImplemented :: tool -> Bool

By default, this returns true. An implementation can override this to return false if the implementation is a stub and the tool should not be visible in the UI.

TODO Remove this once all tools are implemented.

toolPanelWidget :: tool -> Maybe Widget

A tool can provide a widget (or container of widgets) to display in the side panel by returning it from this function.

toolOnDestroy :: tool -> IO ()

A handler that is called when the tool is being destroyed as part of UI shutdown. The default handler does nothing. This does not need to call viewDestroy, which is already called after this handler.

toolOnActivating :: tool -> IO ()

A handler that is called when the user activates the tool. Runs before the tool becomes active and before the tool's widgets are displayed. The default implementation just calls toolGobanInvalidate.

toolOnDeactivated :: tool -> IO ()

A handler that is called after the user deactivates the tool. The default implementation does nothing.

toolGobanHandleEvent :: tool -> GobanEvent -> IO Bool

Called by the goban when an event occurs. Override this to implement custom event handling. The default implementation does basic click and drag tracking for a single mouse button, and calls toolGobanClickComplete when a click/drag completes.

Returning true causes the goban to redraw.

The tool can also query the state of the mouse with toolGetGobanState.

toolGobanClickComplete :: tool -> Maybe Coord -> Maybe Coord -> IO ()

The default toolGobanHandleEvent calls this when a click or drag that started on the goban completes. The two coordinates are the board points at which the click started and ended, or nothing if the mouse was not over a board point.

toolGobanInvalidate :: tool -> IO ()

The default toolGobanHandleEvent calls this when the tool should invalidate its state because something has changed via e.g. a navigation event, properties modified event, or modes changed event.

toolGobanRenderGetBoard :: tool -> Cursor -> IO BoardState

When rendering, the goban calls this function to let the active tool extract a BoardState from a Cursor for rendering. The tool is free to modify the cursor before returning a state.

toolGobanRenderModifyCoords :: tool -> BoardState -> [[RenderedCoord]] -> IO [[RenderedCoord]]

When rendering, the goban calls this function to let the active tool modify the final RenderedCoords before they are drawn.

data AnyTool go ui

An existential type for any tool under a specific UI controller.

Constructors

UiTool go ui tool => AnyTool tool

toolDestroy :: UiTool go ui tool => tool -> IO ()

Performs tool-specific clean-up during UiCtrl shutdown.

toolType :: UiTool go ui tool => tool -> ToolType

Returns the ToolType that a UiCtrl was instantiated for.

toolLabel :: UiTool go ui tool => tool -> String

Returns the UI text that names a tool.

data ToolState

Internal state of a UiTool.

toolStateNew :: ToolType -> String -> IO ToolState

Creates a new ToolState for a tool instiantiated for the given ToolType and with the given UI label.

toolStateType :: ToolState -> ToolType

toolStateLabel :: ToolState -> String

data ToolGobanState

The state of the mouse with respect to the goban.

Constructors

ToolGobanHovering (Maybe Coord)

There is no click in process. The mouse is over the point on the board, if present.

ToolGobanDragging MouseButton (Maybe Coord) (Maybe Coord)

There is a click in progress. The given button was pressed down, over the first board point if present, and is currently over the second board point if present, or elsewhere if absent.

toolGetGobanState :: UiTool go ui tool => tool -> IO ToolGobanState

When toolGobanHandleEvent is the default implementation, this method returns the current state of the mouse with respect to the goban.

toolGobanStateStartCoord :: ToolGobanState -> Maybe Coord

Returns the board point where an in-progress drag started, or the current board point if there is no drag.

toolGobanStateCurrentCoord :: ToolGobanState -> Maybe Coord

Returns the board point that the mouse is over, according to a ToolGobanState.

data GobanEvent

Event notifications that can be sent from the goban to a tool.

Constructors

GobanMouseMove (Maybe Coord)

The mouse was moved over the goban. The Coord is the current mouse location, or nothing if the mouse is not currently over a board point.

GobanClickStart MouseButton (Maybe Coord)

A mouse button was pressed down, over the given board point if present.

GobanClickFinish MouseButton (Maybe Coord)

A mouse button was released, over the given point if present.

GobanInvalidate

The tool should invalidate cached state, abandon any existing drag, and read the cursor and modes from the UiCtrl anew, because something changed (examples: game navigation, game modification, modes change).

data RenderedCoord

Augments a CoordState with data that is used for rendering purposes.

Constructors

RenderedCoord

Fields

• renderedCoordState :: CoordState
• renderedCoordCurrent :: Bool

  True if the point had a stone played on it in the current node.

• renderedCoordVariation :: Maybe Color

  If a variation move exists at this point, then this will be the color of the move.

Instances

Show RenderedCoord

Methods

showsPrec :: Int -> RenderedCoord -> ShowS

show :: RenderedCoord -> String

showList :: [RenderedCoord] -> ShowS

initialToolType :: ToolType

The tool that should be selected when a board first opens in the UI.

toolOrdering :: [[ToolType]]

The ordering and grouping of tools as they should appear in the UI.

toolToColor :: ToolType -> Color

Converts ToolAssignBlack and ToolAssignWhite into Colors. Does not accept any other tools.

Miscellaneous

fileFiltersForSgf :: IO [FileFilter]

Creates a list of FileFilters that should be used in FileChoosers that are working with SGF files.

coordRange :: Coord -> Coord -> [Coord]

coordRange coord0 coord1 returns a list of all the coordinates in the rectangle with coord0 and coord1 as opposite corners.

toggle :: Eq a => a -> Maybe a -> Maybe a

toggle value toggles value in a Maybe, returning Nothing if the maybe already holds the value, and Just value otherwise.