Assets

Icons

There are two kinds of icons:

• Full color icons, that will be displayed as-is
• Symbolic icons, that will be recolored to the text color, allowing them to adapt to any style

It's almost always recommended to use symbolic icons. GTK knows that an icon is symbolic if its name is suffixed with -symbolic.

The preferred format is SVG, so they can be scaled to any size.

Icons can be installed system-wide, for example, next to the application icon in which case they must be stored in a specific hierarchy, respecting the Icon Theme specification: $ICON_THEME/$SIZE/$CONTEXT/. The default icon theme is hicolor, for scalable SVG the size is scalable, and the context is one of the contexts defined in the Icon Naming specification.

# install with meson
install_data(
   'data' / 'icons' / 'hicolor',
  install_dir: prefix / datadir / 'icons' / 'hicolor',
)

Icons can also be bundled with the application in which case they do not have to follow the icon theme specification. Gtk will register them on startup when the application id is given.

# bundle using the cli
gnim bundle -i data/icons --id com.example.MyApp src/main.tsx

const app = new Gtk.Application({
  applicaitonId: "com.example.MyApp",
})

During development the dev server will append $PWD/data/icons to Gtk's icon theme search paths. For example, you'd put icons at data/icons/hicolor/scalable/actions/my-icon-symbolic.svg for system-wide, or data/icons/my-icon-symbolic for bundled icons.

<Gtk.Image iconName="my-icon-symbolic" />

CSS

Gnim supports importing .css and .scss files. CSS is transpiled using lightningcss and SCSS is transpiled using grass.

import "./style.css"
import "./style.scss"

function MyApp() {
  return <></>
}

Inferring GTK version for imported CSS modules

Importing CSS requires knowing the GTK version ahead of time, which is inferred from the codebase. Make sure to have at least one versioned import anywhere in the codebase.

import "gi://Gtk?version=4.0"
import { render } from "ags/gtk4" // this also counts

Files

Gnim supports importing files with a ?file suffix, which gives you a Gio.File pointing to the file.

import image from "./image.png?file"

function Image() {
  return <Gtk.Picture file={image} />
}

During development using gnim dev the file will point to the file on the filesystem and its URI will have a file:// prefix.

After bundling with gnim bundle the file will point to the resource location and its URI will have a resource:// prefix.

import image from "./image.png?file"

function Image() {
  function init(self: Gtk.Image) {
    const uri = image.get_uri()
    if (uri.startsWith("file://")) {
      self.set_from_file(uri.replace("file://", ""))
    }
    if (uri.startsWith("resource://")) {
      self.set_from_resource(uri.replace("resource://", ""))
    }
  }

  return <Gtk.Image ref={init} />

  // alternatively use Gio.FileIcon
  return <Gtk.Image gicon={Gio.FileIcon.new(image)} />
}