CyberTrench

The installation script creates a modular project structure. Let’s see what we’re working with:

gi-gtk-test/
├── gi-gtk-test.cabal    # Build configuration
├── src/
│   └── UI/
│       ├── Shared.hs      # Reusable UI components
│       ├── Layout.hs      # Layout management
│       ├── StatusPage.hs  # Status page window
│       └── MainWindow.hs # Main application window
└── app/
    └── Main.hs           # Application entry point

This structure follows a solid Haskell practice: separation of concerns. Each module has a specific responsibility, making the code easier to understand, test, and maintain.

Before we dive into the Haskell code, let’s understand the project configuration. The .cabal file tells Cabal how to build our project:

cabal-version:      3.12
name:               gi-gtk-test
version:            0.1.0.0
build-type:         Simple

common shared-props
  default-language: Haskell2010
  build-depends:    
    base >=4 && <5
    , gi-gtk4 >=4.0
    , haskell-gi-base
    , text
  ghc-options: -Wall -Wmissing-home-modules -threaded

Key Points:

• common shared-props: Defines shared properties used by both library and executable
• build-depends: Lists all required packages
• ghc-options: Compiler flags
  • -Wall = all warnings
  • -threaded = multi-threaded runtime (We will delve way more into this)

library
    import: shared-props
    exposed-modules:
      UI.StatusPage
      UI.Shared
      UI.MainWindow
    hs-source-dirs: src

The library section exposes modules that can be reused by other projects or within the executable.

How the library matches the directory layout:

The module names in exposed-modules directly correspond to the file structure:

• UI.StatusPage → src/UI/StatusPage.hs
• UI.Shared → src/UI/Shared.hs
• UI.MainWindow → src/UI/MainWindow.hs

The hs-source-dirs: src tells Cabal to look in the src/ directory for these modules. When Cabal sees UI.StatusPage, it follows these steps:

1. Takes the module path: UI.StatusPage
2. Converts dots to directory separators: UI/StatusPage
3. Looks in src/ (from hs-source-dirs): src/UI/StatusPage
4. Adds the .hs extension: src/UI/StatusPage.hs

This is why the module declaration in each file (module UI.StatusPage where) must match both the file path and the name in the .cabal file!

executable gi-gtk-test
    import:           shared-props
    main-is:          Main.hs
    hs-source-dirs:   src, app
    other-modules:
      UI.Layout
      UI.MainWindow
      UI.Shared
      UI.StatusPage

The executable section defines the main program. A few important points:

1. hs-source-dirs: src, app: The executable can look for modules in both directories. This is why Main.hs can be in app/ while the UI modules are in src/UI/.

2. other-modules vs exposed modules

Understanding the difference: - UI.Layout must be listed here because it’s not exposed in the library - UI.MainWindow, UI.Shared, and UI.StatusPage are already exposed in the library, so they could be imported without being listed here - However, listing them in other-modules is also valid (and makes it explicit which modules the executable uses)

3. Why list exposed modules?

While technically redundant: - Explicitly listing all modules the executable uses makes the dependencies clear and can help with build optimization - It’s a matter of preference - some prefer explicit lists, others rely on the library’s exposed modules

Let’s start with the simplest module - UI.Shared.hs. This module provides reusable UI components:

module UI.Shared (createButton) where

import GI.Gtk as Gtk
import qualified Data.Text as T

createButton :: String -> IO Gtk.Button
createButton label = Gtk.buttonNewWithLabel (T.pack label)

Breaking it down:

1. Module Declaration: module UI.Shared (createButton) where

• Exports only createButton (explicit export list = good practice!)

2. Imports

Required dependencies: - GI.Gtk as Gtk: GTK4 bindings (the GI stands for “GObject Introspection”) - qualified Data.Text as T: Text handling (GTK uses Text, not String)

3. Function Signature: createButton :: String -> IO Gtk.Button

• Takes a String (Haskell’s basic string type)
• Returns IO Gtk.Button (an action that creates a button)
• The IO monad is necessary because creating GTK widgets has side effects

4. Function Body: Gtk.buttonNewWithLabel (T.pack label)

• T.pack: Converts String to Text (GTK’s preferred type)
• Gtk.buttonNewWithLabel: Creates a new button with the given label

Why this matters: This abstraction lets us create buttons consistently throughout the app. If we need to change button creation (add styling, set properties, etc.), we only change it in one place!

Next up is UI.Layout.hs - this module handles widget positioning using GTK’s Grid layout:

{-# LANGUAGE OverloadedLabels, OverloadedStrings #-}

module UI.Layout where

import qualified GI.Gtk as Gtk
import Control.Monad (zipWithM_)

setupGrid :: [(Gtk.Widget, (Int, Int))] -> IO Gtk.Grid
setupGrid widgetPositions = do 
    grid <- Gtk.gridNew
    zipWithM_ (\(widget, (col, row)) _ -> 
        Gtk.gridAttach grid widget (fromIntegral col) (fromIntegral row) 1 1
    ) widgetPositions ([1..] :: [Int])
    return grid

Breaking it down:

1. Language Extensions

Required for this module: - OverloadedLabels: Allows using #label syntax (we’ll see this later) - OverloadedStrings: Allows string literals to be Text automatically

2. Function Signature: setupGrid :: [(Gtk.Widget, (Int, Int))] -> IO Gtk.Grid

• Takes a list of tuples: (Widget, (Column, Row))
• Returns a configured Grid widget

3. Grid Creation: grid <- Gtk.gridNew

• Creates a new empty grid container
• The <- binds the result from the IO action

4. The Magic - zipWithM_

This function attaches widgets to the grid: zipWithM_ (\(widget, (col, row)) _ -> Gtk.gridAttach grid widget (fromIntegral col) (fromIntegral row) 1 1 ) widgetPositions [1..] - zipWithM_: Combines two lists, applying a function to each pair - widgetPositions: Our list of (Widget, (col, row)) tuples - [1..]: Infinite list [1, 2, 3, ...] (we ignore it with _) - Gtk.gridAttach: Attaches widget to grid at position (col, row) with size 1x1 - fromIntegral: Converts Int to the type GTK expects

Why this pattern? This function lets us declaratively position widgets: “put this widget at column 1, row 1; that widget at column 2, row 1”, etc. Much cleaner than manually calling gridAttach for each widget!

UI.StatusPage.hs creates a secondary window with a text view. This demonstrates opening new windows from button clicks:

{-# LANGUAGE OverloadedStrings #-}

module UI.StatusPage where

import qualified GI.Gtk as Gtk

createStatusPage :: IO ()
createStatusPage = do
    win <- Gtk.windowNew
    Gtk.setWindowTitle win "Testing GUI Dev on Windows"
    Gtk.setWindowDefaultWidth win 300
    Gtk.setWindowDefaultHeight win 100

   -- Set a text buffer (Testing, no real use for this yet)
    textView <- Gtk.textViewNew
    buffer   <- Gtk.textViewGetBuffer textView

    Gtk.textViewSetBuffer textView ( Just buffer )
    scrolledWindow <- Gtk.scrolledWindowNew
    Gtk.scrolledWindowSetChild scrolledWindow (Just textView)
    Gtk.windowSetChild win (Just scrolledWindow)
    Gtk.widgetSetVisible win True

Breaking it down:

1. Window Creation: win <- Gtk.windowNew

• In GTK4, windowNew creates a top-level window by default (no type parameter needed)
• Simpler API than GTK3!

2. Window Configuration

Setting window properties: Gtk.setWindowTitle win "Testing GUI Dev on Windows" Gtk.setWindowDefaultWidth win 300 Gtk.setWindowDefaultHeight win 100 - setWindowTitle: Sets the window title - setWindowDefaultWidth and setWindowDefaultHeight: Set window dimensions separately - Note: setContainerBorderWidth and setWindowWindowPosition were removed in GTK4

3. Text View Setup

Creating the text editing widget: textView <- Gtk.textViewNew buffer <- Gtk.textViewGetBuffer textView - textViewNew: Creates an editable text area - textViewGetBuffer: Gets the underlying text buffer (where text is stored)

4. Scrolled Window

Adding scrollable container: scrolledWindow <- Gtk.scrolledWindowNew - In GTK4, scrolledWindowNew takes no parameters (simpler than GTK3!)

5. Widget Hierarchy (GTK4 Style)

The parent-child structure: Window └── ScrolledWindow └── TextView - GTK4 uses a different API: setChild instead of containerAdd - scrolledWindowSetChild: Sets the child of the scrolled window - windowSetChild: Sets the child of the window - This is more explicit and type-safe than GTK3’s containerAdd

6. Display: Gtk.widgetSetVisible win True

• In GTK4, widgetShow and widgetShowAll were deprecated
• Use widgetSetVisible widget True to show widgets (GTK4 shows children automatically when parent is shown)

Now for the star of the show - UI.MainWindow.hs. This creates the main window and wires everything together:

{-# LANGUAGE OverloadedStrings, OverloadedLabels, TupleSections #-}

module UI.MainWindow where

import qualified GI.Gtk as Gtk
import UI.Shared (createButton)
import UI.StatusPage (createStatusPage)
import UI.Layout (setupGrid)

createMainWindow :: IO Gtk.Window
createMainWindow = do
    win <- Gtk.windowNew
    Gtk.setWindowTitle win "Testing GUI Dev on Windows"
    Gtk.setWindowDefaultWidth win 300
    Gtk.setWindowDefaultHeight win 100

    testButton <- createButton "Just another button"

    _ <- Gtk.on testButton #clicked createStatusPage

    widgetPositions <- sequence
        [ (, (1, 1)) <$> Gtk.toWidget testButton ]

    grid <- setupGrid widgetPositions
    Gtk.windowSetChild win (Just grid)

    return win

Breaking it down:

1. Language Extensions

Required for this module: - OverloadedLabels: Enables #clicked syntax (more on this below) - TupleSections: Allows (, (1, 1)) syntax (partial tuple construction)

2. Window Setup

Same GTK4 pattern as StatusPage - windowNew with no parameters, setWindowDefaultWidth and setWindowDefaultHeight for dimensions

3. Button Creation: testButton <- createButton "Just another button"

• Uses our reusable createButton function from UI.Shared

4. Event Handling - The Magic Line

Connecting button clicks to actions: _ <- Gtk.on testButton #clicked createStatusPage - Gtk.on: Connects a signal (event) to a handler function - #clicked: The “clicked” signal using overloaded labels syntax - createStatusPage: The function to call when clicked - This is functional event handling - no callbacks, just function composition!

5. Widget Positioning

Arranging widgets in the grid: widgetPositions <- sequence [ (, (1, 1)) <$> Gtk.toWidget testButton ] Let’s break this down step by step: - Gtk.toWidget testButton: Converts button to generic Widget type - (, (1, 1)) <$> ...: Uses <$> (fmap) to create (Widget, (1, 1)) tuple - sequence: Converts [IO (Widget, (Int, Int))] to IO [(Widget, (Int, Int))] - Result: A list with one tuple: [(buttonWidget, (1, 1))]

6. Grid Setup: grid <- setupGrid widgetPositions

• Uses our setupGrid function to create a positioned grid
• The button will be at column 1, row 1

7. Add Grid to Window: Gtk.windowSetChild win (Just grid)

• GTK4 uses windowSetChild instead of containerAdd
• The Just wrapper is required (GTK4’s API is more explicit about optional values)

8. Return the Window: return win

• Returns the configured window so Main.hs can use it

Finally, Main.hs - where it all starts:

{-# LANGUAGE OverloadedStrings, OverloadedLabels #-}

module Main (Main.main) where

import qualified GI.Gtk as Gtk 
import qualified GI.Gio as Gio
import UI.MainWindow (createMainWindow)

main :: IO ()
main = do 
   -- Create application
    app <- Gtk.applicationNew (Just "com.example.gi-gtk-test") []
    
   -- Handle application activation
    _ <- Gtk.on app #activate $ do
        mainWin <- createMainWindow
        Gtk.windowSetApplication mainWin (Just app)
        _ <- Gtk.on mainWin #closeRequest $ do
            Gio.applicationQuit app
            return False
        Gtk.widgetSetVisible mainWin True
    
   -- Run the application (this handles GTK initialization)
    _ <- Gio.applicationRun app Nothing
    return ()

Breaking it down:

1. Create Application: app <- Gtk.applicationNew (Just "com.example.gi-gtk-test") []

• In GTK4, we use Application to manage the app lifecycle
• The first parameter is the application ID (reverse domain name format)
• The second parameter is application flags (empty list = no special flags)
• No need for Gtk.init! The application handles initialization

2. Application Activation Handler: _ <- Gtk.on app #activate $ do ...

• The #activate signal fires when the application starts
• This is where we create and show our main window
• All window creation happens inside this handler

3. Create and Configure Window:

   mainWin <- createMainWindow
   Gtk.windowSetApplication mainWin (Just app)

• Creates the main window using our function
• Associates the window with the application (important for proper lifecycle management)

4. Close Request Handler: _ <- Gtk.on mainWin #closeRequest $ do ...

• In GTK4, windows use #closeRequest instead of #destroy
• Gio.applicationQuit app: Quits the application
• return False: Tells GTK “I handled the close, don’t do default behavior”
• This is the modern GTK4 way to handle window closing

5. Show Window: Gtk.widgetSetVisible mainWin True

• Makes the window visible
• GTK4 automatically shows children when parent is shown

6. Run Application: Gio.applicationRun app Nothing

• This blocks! Starts the application’s main event loop
• Handles all events (clicks, keypresses, window management, etc.)
• The Nothing parameter means “no command-line arguments to process”
• Only exits when applicationQuit is called

Let’s trace the execution flow:

1. Program starts → Main.main runs
2. Application created → Gtk.applicationNew
3. Activation handler connected → #activate signal
4. Application runs → Gio.applicationRun (handles GTK initialization)
5. Activation fires → Handler executes:

• Creates main window using createMainWindow
• Associates window with application
• Connects close handler → Gio.applicationQuit
• Shows window

6. Event loop running → Application processes events
7. User clicks button → createStatusPage runs → New window appears!
8. User closes window → #closeRequest → Gio.applicationQuit → Program exits

The Flow:

Main.main
  └── Gtk.applicationNew
  └── Gtk.on app #activate
      └── createMainWindow
          ├── UI.Shared.createButton
          ├── UI.Layout.setupGrid
          └── Event: clicked → UI.StatusPage.createStatusPage
      └── Event: closeRequest → Gio.applicationQuit
  └── Gio.applicationRun (event loop)

1. The IO Monad

Almost everything returns IO something because GUI operations have side effects: - Creating widgets - Showing windows - Handling events

Haskell’s type system forces us to be explicit about side effects!

2. Do Notation

The do blocks let us sequence IO actions:

main = do
    action1
    result <- action2
    action3 result

3. Function Composition

Notice how functions compose:

testButton <- createButton "Just another button"
_ <- Gtk.on testButton #clicked createStatusPage

We create a button, then immediately attach a handler. Clean and functional!

4. Type Safety

GTK’s Haskell bindings are type-safe. The compiler catches errors: - Wrong widget type? Compile error! - Missing required parameter? Compile error! - Wrong signal name? Compile error!