K2 GTK GUI Documentation

K2 GTK GUI is a powerful library that allows you to create native, cross-platform graphical user interfaces using the K2 programming language. Built on top of GTK4, it provides a simple and intuitive API while leveraging the power and flexibility of one of the most popular GUI toolkits.

Features

  • Native performance on Linux, Windows, and macOS
  • Simple, intuitive API designed specifically for K2
  • Comprehensive set of UI components and layouts
  • Event-driven programming with callbacks
  • Dialog and file operation support
  • Cross-platform compatibility

Installation

Prerequisites

Before installing K2 GTK GUI, make sure you have the following prerequisites:

  • K2 programming language
  • GTK4 development libraries

On Debian/Ubuntu-based systems, you can install the GTK4 development libraries with:

sudo apt-get install libgtk-4-dev

Building from Source

# Clone the repository
git clone https://github.com/k2lang/k2-gtk-gui.git

# Build and install
cd k2-gtk-gui
./install.sh

Using Pre-built Packages

You can also download pre-built packages for your platform:

Getting Started

Here's a simple "Hello World" example to get you started with K2 GTK GUI:

# K2 GTK GUI - Hello World Example
import GtkGui

# Create a new application
app = GtkGui.Application.new("org.k2lang.gtkgui.hello", "Hello World")

# Create a window
window = GtkGui.Window.new(app, "Hello World", 400, 300)

# Create a vertical layout container
layout = GtkGui.Box.new()
layout.setOrientation(GtkGui.ORIENTATION_VERTICAL)
layout.setSpacing(20)
layout.setMargin(20)

# Create a heading label
heading = GtkGui.Label.new()
heading.setText("Hello, World!")
heading.setProperty("markup", "<span size='xx-large' weight='bold'>Hello, World!</span>")

# Create a button
button = GtkGui.Button.new()
button.setLabel("Click Me")

# Add event listener to the button
button.setCallback("clicked", function(widget) {
  GtkGui.Dialog.showMessage(window, "Hello", "You clicked the button!")
})

# Add components to the layout
layout.add(heading)
layout.add(button)

# Set the window content
window.setContent(layout)

# Show the window
window.show()

# Start the application
app.run()

Save this code to a file (e.g., hello_world.k2) and run it with the K2 interpreter:

k2 hello_world.k2

Application

The GtkGui.Application class is the entry point for creating a GTK GUI application. It manages the application lifecycle and provides methods for creating windows and handling application-level events.

Creating an Application

# Create a new application
app = GtkGui.Application.new(appId, appName)

Parameters:

  • appId - A unique identifier for the application (e.g., "org.k2lang.myapp")
  • appName - The display name of the application

Running the Application

# Start the application main loop
app.run()

Quitting the Application

# Quit the application
app.quit()

Window

The GtkGui.Window class represents a top-level window in your application. You can create multiple windows in a single application.

Creating a Window

# Create a new window
window = GtkGui.Window.new(app, title, width, height)

Parameters:

  • app - The GtkGui.Application instance
  • title - The window title
  • width - The window width in pixels
  • height - The window height in pixels

Window Methods

# Set the window title
window.setTitle(title)

# Set the window size
window.setSize(width, height)

# Set whether the window is resizable
window.setResizable(boolean)

# Set the window content
window.setContent(widget)

# Show the window
window.show()

# Hide the window
window.hide()

# Close the window
window.close()

Layouts

K2 GTK GUI provides several layout containers for organizing widgets in your user interface.

Box Layout

The GtkGui.Box class is a layout container that arranges widgets in a single row or column.

# Create a new box layout
box = GtkGui.Box.new()

# Set the orientation (vertical or horizontal)
box.setOrientation(GtkGui.ORIENTATION_VERTICAL)  # or ORIENTATION_HORIZONTAL

# Set the spacing between widgets
box.setSpacing(pixels)

# Set the margin around the box
box.setMargin(pixels)

# Add a widget to the box
box.add(widget)

# Remove a widget from the box
box.remove(widget)

Grid Layout

The GtkGui.Grid class is a layout container that arranges widgets in a grid of rows and columns.

# Create a new grid layout
grid = GtkGui.Grid.new()

# Set the spacing between columns
grid.setColumnSpacing(pixels)

# Set the spacing between rows
grid.setRowSpacing(pixels)

# Attach a widget to the grid
grid.attach(widget, column, row, width, height)

# Remove a widget from the grid
grid.remove(widget)

Widgets

K2 GTK GUI provides a variety of widgets for building user interfaces.

Label

The GtkGui.Label class displays text.

# Create a new label
label = GtkGui.Label.new()

# Set the label text
label.setText(text)

# Set markup (HTML-like formatting)
label.setProperty("markup", "<span size='large' weight='bold'>Bold Text</span>")

Button

The GtkGui.Button class is a clickable button.

# Create a new button
button = GtkGui.Button.new()

# Set the button label
button.setLabel(text)

# Set a click callback
button.setCallback("clicked", function(widget) {
  # Handle button click
})

Entry

The GtkGui.Entry class is a single-line text input field.

# Create a new entry
entry = GtkGui.Entry.new()

# Set the entry text
entry.setText(text)

# Get the entry text
text = entry.getText()

# Set a placeholder text
entry.setProperty("placeholder-text", "Enter text here...")

# Set a change callback
entry.setCallback("changed", function(widget) {
  # Handle text change
})

TextArea

The GtkGui.TextArea class is a multi-line text input field.

# Create a new text area
textArea = GtkGui.TextArea.new()

# Set the text area content
textArea.setText(text)

# Get the text area content
text = textArea.getText()

# Set monospace font
textArea.setProperty("monospace", "true")

# Set word wrap mode
textArea.setProperty("wrapMode", "word")

Image

The GtkGui.Image class displays an image.

# Create a new image
image = GtkGui.Image.new()

# Load an image from file
image.loadFromFile(filePath)

# Set the image size
image.setSize(width, height)

Event Handling

K2 GTK GUI uses a callback-based event handling system. You can register callback functions to be called when specific events occur.

# Set a callback for an event
widget.setCallback(eventName, callbackFunction)

# Example: Button click event
button.setCallback("clicked", function(widget) {
  # This function will be called when the button is clicked
  print("Button clicked!")
})

# Example: Entry text change event
entry.setCallback("changed", function(widget) {
  # This function will be called when the entry text changes
  print("Text changed: " + entry.getText())
})

Common Events

  • clicked - Button click
  • changed - Text input change
  • activate - Entry activation (e.g., pressing Enter)
  • focus-in-event - Widget gains focus
  • focus-out-event - Widget loses focus

Dialogs

K2 GTK GUI provides several dialog types for interacting with the user.

Message Dialog

# Show a message dialog
GtkGui.Dialog.showMessage(parentWindow, title, message)

Question Dialog

# Show a question dialog
result = GtkGui.Dialog.showQuestion(parentWindow, title, message)

# result is true if the user clicked "Yes", false otherwise
if (result) {
  # User clicked "Yes"
} else {
  # User clicked "No"
}

Input Dialog

# Show an input dialog
text = GtkGui.Dialog.showInput(parentWindow, title, message, defaultValue)

# text is the entered text, or null if the user cancelled
if (text != null) {
  # User entered text
} else {
  # User cancelled
}

File Operations

K2 GTK GUI provides dialogs for file operations.

File Open Dialog

# Show a file open dialog
filePath = GtkGui.Dialog.showFileOpen(parentWindow, title)

# filePath is the selected file path, or null if the user cancelled
if (filePath != null) {
  # User selected a file
  content = FileSystem.readFile(filePath)
} else {
  # User cancelled
}

File Save Dialog

# Show a file save dialog
filePath = GtkGui.Dialog.showFileSave(parentWindow, title, defaultName)

# filePath is the selected file path, or null if the user cancelled
if (filePath != null) {
  # User selected a file
  FileSystem.writeFile(filePath, content)
} else {
  # User cancelled
}

Styling

You can customize the appearance of widgets using properties.

# Set a widget property
widget.setProperty(propertyName, value)

# Examples
label.setProperty("color", "#ff0000")  # Red text
button.setProperty("background", "#4CAF50")  # Green background
button.setProperty("foreground", "white")  # White text
entry.setProperty("font", "Sans 14")  # Custom font

Examples

Check out these examples to learn more about K2 GTK GUI:

For more examples, visit the Examples page.