Supporting UI Scaling
GTK3 and above support integer scaling of UI components, most useful on HiDPI screens. In Xfce, this can be set in the Appearance settings panel. GTK3 will handle drawing widgets and windows at the new scale automatically, but care has to be taken to supply it with images and icons properly in order for them to be displayed at the correct resolution, without being blurry.
Basics
- Use
gtk_widget_get_scale_factor()
to get the scale factor. - If you don't have a widget handy, but for some reason have a
GdkWindow
, you can usegdk_window_get_scale_factor()
. - If you don't even have a window, you can use
gdk_monitor_get_scale_factor()
. - Scale factors are (unfortunately) integer-only. There's no such thing as a 1.5x scale, for example.
- You can connect to
notify::scale-factor
on aGtkWidget
orGdkMonitor
instance to know when you might need to reload icons at a new scale factor.
Things that work
- Any manually-loaded
GdkPixbuf
instances should be loaded at a width and height multiplied by the scale factor. Then, “wrap” the pixbuf in acairo_surface_t
usinggdk_cairo_surface_create_from_pixbuf()
, which takes the scale factor. It can also take aGdkWindow
, but it's fine to passNULL
there. - When loading themed icons, use the
_for_scale()
variants:gtk_icon_theme_lookup_icon_for_scale()
,gtk_icon_theme_load_icon_for_scale()
, andgtk_icon_theme_lookup_by_gicon_for_scale()
. Pass the unscaled size for thesize
parameter, and the UI scale factor for thescale
parameter. I also recommend passingGTK_ICON_LOOKUP_FORCE_SIZE
. GIcon
is a useful alternative in cases where it's awkward to pass around a scale factor (for example, in aGtkTreeModel
implementation, the model shouldn't really know “view” details like the UI scale factor).GIcon
has quite a few implementation types, likeGFileIcon
,GThemedIcon
, andGEmblemedIcon
. EvenGdkPixbuf
implementsGIcon
. There's alsoGLoadableIcon
, which you can fairly easily implement if you need to do something custom.- If using
GIcon
withGtkImage
, you can get arbitrary sizing (that is, other sizes beyond whatGTK_ICON_SIZE_
offers) by usinggtk_image_set_pixel_size()
. The code inGtkImage
ignores theGTK_ICON_SIZE_
sizes if the pixel size is specified. For the pixel size, you want to specify the unscaled size. - Most things that take a themed icon name will automatically handle the scale factor internally.
- Many things that take
GdkPixbuf
will also takeGIcon
orcairo_surface_t
, so look for another function variant when replacing existing calls.
Things that are problematic
- Loading
GdkPixbuf
instances manually will result in blurry icons without specifically handling the scale factor. GIcon
andGtkCellRendererPixbuf
work ok if you are only using “standard” GTK icon sizes (that is, theGTK_ICON_SIZE_
enum values). That should usually be fine for things likeGtkTreeView
, but might not work well forGtkIconView
, as those size types max out at 48×48.- Don't try to “outsmart”
GtkIconTheme
by writing your own size selection and loading code.GtkIconTheme
will nearly always do the right thing, and handles a lot of the complex rules that can be encoded into anindex.theme
file. Working around this can give results that aren't true to what the icon theme authors intended.