goatee-gtk-0.3.1: A monadic take on a 2,500-year-old board game - GTK+ UI.

Safe HaskellNone
LanguageHaskell98

Game.Goatee.Ui.Gtk.Common

Contents

Description

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

Synopsis

UI Go monads

class MonadGo go => MonadUiGo go where Source

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.

Methods

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

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

uiGoGetState :: go UiGoState Source

Retrieves the current internal state.

uiGoPutState :: UiGoState -> go () Source

Assigns to the current internal state.

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

Modifies the current internal state with the given function.

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

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

uiGoMakeDirty :: MonadUiGo go => go () Source

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

data UiGoState Source

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 Source

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

UI controllers

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

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.

Methods

readModes :: ui -> IO UiModes Source

Reads the current UI modes.

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

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

Looks up the tool bound to a ToolType.

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

Reads the active tool.

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

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

readCursor :: ui -> IO Cursor Source

Returns the current cursor.

isValidMove :: ui -> Coord -> IO Bool Source

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

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

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

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 Source

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

Stops the controller from updating the view entirely.

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

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

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

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 Source

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] Source

Returns the owners of the currently registered ModesChangedHandlers.

getMainWindow :: ui -> IO Window Source

Returns the Window for the game's MainWindow.

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

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

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

fileOpen :: ui -> IO () Source

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 Source

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 Source

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 Source

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

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 Source

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

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

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

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

helpKeyBindings :: ui -> IO () Source

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

helpAbout :: ui -> IO () Source

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

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 Source

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

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 Source

Arguments

:: ui 
-> String

The name of the caller, used to track what components registered what handlers.

-> Bool

If true, the handler will be called immediately after registration.

-> FilePathChangedHandler 
-> IO Registration 

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

unregisterFilePathChangedHandler :: ui -> Registration -> IO Bool Source

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] Source

Returns the owners of the currently registered FilePathChangedHandlers.

getDirty :: ui -> IO Bool Source

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

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

Sets the dirty state of the UI.

registerDirtyChangedHandler Source

Arguments

:: ui 
-> String

The name of the caller, used to track what components registered what handlers.

-> Bool

If true, the handler will be called immediately after registration.

-> DirtyChangedHandler 
-> IO Registration 

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

unregisterDirtyChangedHandler :: ui -> Registration -> IO Bool Source

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] Source

Returns the owners of the currently registered DirtyChangedHandlers.

data AnyUiCtrl Source

An existential type for all UI controllers.

Constructors

forall go ui . UiCtrl go ui => AnyUiCtrl ui 

type Registration = Unique Source

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

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

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

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

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

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 Source

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.

Methods

viewName :: view -> String Source

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

viewCtrl :: view -> ui Source

A reference to the view's controller.

viewState :: view -> ViewState Source

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

viewUpdate :: view -> IO () Source

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

data AnyView Source

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

forall go ui view . UiView go ui view => AnyView view 

data ViewId Source

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

data ViewState Source

Internal controller housekeeping data for a view.

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

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 Source

Returns a view's unique ID.

UI modes

data UiModes Source

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
 

Tools

data ToolType Source

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.

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

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 Source

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

toolIsImplemented :: tool -> Bool Source

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 Source

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

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

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

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

toolGobanHandleEvent :: tool -> GobanEvent -> IO Bool Source

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

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

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 Source

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]] Source

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

data AnyTool go ui Source

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

Constructors

forall tool . UiTool go ui tool => AnyTool tool 

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

Performs tool-specific clean-up during UiCtrl shutdown.

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

Returns the ToolType that a UiCtrl was instantiated for.

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

Returns the UI text that names a tool.

data ToolState Source

Internal state of a UiTool.

toolStateNew :: ToolType -> String -> IO ToolState Source

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

data ToolGobanState Source

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 Source

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

toolGobanStateStartCoord :: ToolGobanState -> Maybe Coord Source

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

toolGobanStateCurrentCoord :: ToolGobanState -> Maybe Coord Source

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

data GobanEvent Source

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 Source

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.

initialToolType :: ToolType Source

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

toolOrdering :: [[ToolType]] Source

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

toolToColor :: ToolType -> Color Source

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

Miscellaneous

fileFiltersForSgf :: IO [FileFilter] Source

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

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

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 Source

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