AGtk

AGtk is a library of helper classes for GTK 4 in C#.

Well, actually at the moment there's only one helper class: AGtk.ColView, plus some useful methods for working with actions and resources. But perhaps I'll add more classes in the future.

AGtk.ColView

AGtk.ColView is a subclass of the Gtk.ColumnView class, which displays a multi-column list. Gtk.ColumnView has a complicated API, so AGtk.ColView exists to make it much easier to use. Here's a brief code sample to show how easy it is:

AGtk.ColView col_view = new(["year", "title", "director"]);

col_view.Add([1981, "Raiders of the Lost Ark", "Steven Spielberg"]);
col_view.Add([1994, "The Shawshank Redemption", "Frank Darabont"]);
col_view.Add([1995, "Clueless", "Amy Heckerling"]);
...

my_window.Child = col_view;

That will produce a column view that looks like this:

You can sort on any column by clicking on the column's header. AGtk.ColView compares objects by casting them to IComparable. For this reason, currently all objects added to a visible column must implement the IComparable interface. This is not too restrictive, since many useful types such as int and string do implement IComparable.

If a column name is null, the column is invisible and you can add any object you like to it. This can be useful for storing data that you want to retrieve along with the selected column.

Adding filtering

AGtk.ColView supports dynamic filtering. Typically you'll use this with a search box: as the user types in the box, rows will be filtered. Here's how to do this in code:

// specify the column to use for filtering
col_view.FilterColumn = 1;   // title

SearchEntry entry = new();
entry.OnSearchChanged += on_search_changed;

...

void on_search_changed(SearchEntry sender, EventArgs args) {
    col_view.FilterText = entry.GetText();
}

A larger example

My page Introduction to GTK 4 in C# contains a complete example of a program using AGtk.ColView.

Extension methods for actions

AGtk includes a couple of convenient extension methods for adding actions to a GtkWindow or GtkApplication. For example, in a GtkWindow subclass you can call

this.AddAction("open", on_open);

This call will add an action "open" that will call on_open() when activated.

this.AddToggleAction("show_statusbar", true, on_show_statusbar);

This call will add a toggle action called "show_statusbar". The corresponding menu item will display a checkbox, which will be initially checked since the second argument is 'true'. on_show_statusbar() will be called when the user toggles the checkbox, and will receive a boolean indicating the current toggle state.

To make these extension methods available, you must use the AGtk namespace:

using AGtk;

My page Introduction to GTK 4 in C# contains a complete example of a program using these extension methods.

Using the library

AGtk is available as a nuget package:

$ dotnet add package AGtk

The current version number is 0.5.0.

API reference

All members listed below are public.

ColView

ColView(params string?[] names)

Create a ColView with the given column names. A column name that is null represents an invisible column.

void Add(params object[] values)

Append a row of values to the view. Any value added to a visible column must be comparable, i.e. be an instance of IComparable.

void Clear()

Remove all rows from the view.

void DeleteRow(uint index)

Delete a row by index.

int? FilterColumn {get; set; }

The 0-based index of the column used for filtering.

string FilterText {get; set; }

The text to use for filtering. Only rows whose filter column contains this text will be shown. If the value is "", all rows will be displayed.

event RightClick? OnRightClick

An event that fires when the user right clicks the mouse on a row.

uint RowCount { get; }

The number of rows in this ColView.

RowList Rows {get;}

A list of rows in this ColView.

uint SelectedIndex {get; set;}

The index of the row that is currently selected.

event SelectionChanged? OnSelectionChanged

An event that fires whenever the selection changes.

Resources

A static class with useful methods for working with resources in a .NET assembly. (These are not the same thing as GLib resources, which are not so convenient to use in C#.)

static Gdk.Texture? GetTexture(string name)

Retrieve a Gdk.Texture from a named resource in the application's assembly. Returns null if the resource is not found.

RightClick

A delegate type for a right mouse click event.

delegate void RightClick(int x, int y, uint rowIndex)

(x, y) is the position where the user clicked. rowIndex is the index of the row below the mouse click.

Row

A row in a ColView.

public ValueList Values { get; }

An list of values in the row.

RowList

A list of rows.

Row this[uint i] { get; }

An indexer to retrieve a Row.

SelectedChanged

A delegate type for a selection change event.

delegate void SelectionChanged(uint rowIndex)

rowIndex is the index of the currently selected row.

ValueList

A list of values in a row.

object this[int col] { get; set; }

An indexer to get or set a value.

Helpers

Extension methods for actions.

static Gio.SimpleAction AddAction(this Gio.ActionMap map, string name, Action f)

Add a named action with a function to be called on activation.

static Gio.SimpleAction AddToggleAction(this Gio.ActionMap map, string name, bool initial, Action<bool>? f)

Add a named toggle action. The corresponding menu item will display a checkbox, which will be initially checked if initial is true. If f is non-null, it will be called when the user toggles the checkbox, and will receive a boolean value indicating the current toggle state.

static bool GetToggled(this Gio.SimpleAction action)

Retrieve the boolean state of a toggle action.

static void SetToggled(this Gio.SimpleAction action, bool b)

Set the boolean state of a toggle action.