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.

• 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 use gdk_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 a GtkWidget or GdkMonitor instance to know when you might need to reload icons at a new scale factor.

• Any manually-loaded GdkPixbuf instances should be loaded at a width and height multiplied by the scale factor. Then, “wrap” the pixbuf in a cairo_surface_t using gdk_cairo_surface_create_from_pixbuf(), which takes the scale factor. It can also take a GdkWindow, but it's fine to pass NULL there.
• When loading themed icons, use the _for_scale() variants: gtk_icon_theme_lookup_icon_for_scale(), gtk_icon_theme_load_icon_for_scale(), and gtk_icon_theme_lookup_by_gicon_for_scale(). Pass the unscaled size for the size parameter, and the UI scale factor for the scale parameter. I also recommend passing GTK_ICON_LOOKUP_FORCE_SIZE.
• GIcon is a useful alternative in cases where it's awkward to pass around a scale factor (for example, in a GtkTreeModel implementation, the model shouldn't really know “view” details like the UI scale factor). GIcon has quite a few implementation types, like GFileIcon, GThemedIcon, and GEmblemedIcon. Even GdkPixbuf implements GIcon. There's also GLoadableIcon, which you can fairly easily implement if you need to do something custom.
• If using GIcon with GtkImage, you can get arbitrary sizing (that is, other sizes beyond what GTK_ICON_SIZE_ offers) by using gtk_image_set_pixel_size(). The code in GtkImage ignores the GTK_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 take GIcon or cairo_surface_t, so look for another function variant when replacing existing calls.

• Loading GdkPixbuf instances manually will result in blurry icons without specifically handling the scale factor.
• GIcon and GtkCellRendererPixbuf work ok if you are only using “standard” GTK icon sizes (that is, the GTK_ICON_SIZE_ enum values). That should usually be fine for things like GtkTreeView, but might not work well for GtkIconView, 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 an index.theme file. Working around this can give results that aren't true to what the icon theme authors intended.