diff --git a/theme/theme.go b/theme/theme.go index 769c8b7..eff93a3 100644 --- a/theme/theme.go +++ b/theme/theme.go @@ -47,27 +47,32 @@ func (id Color) RGBA () (r, g, b, a uint32) { // Theme is an object that can apply a visual style to different objects. type Theme interface { + // A word on textures: + // + // Because textures can be linked to some resource that is outside of + // the control of Go's garbage collector, methods of Theme must not + // allocate new copies of a texture each time they are called. It is + // fine to lazily load textures and save them for later use, but the + // same texture must never be allocated multiple times as this could + // cause a memory leak. + // + // As such, textures returned by these methods must be protected. + // Apply applies the theme to the given object, according to the given // role. This may register event listeners with the given object; - // closing the returned cookie will remove them. + // closing the returned cookie must remove them. Apply (tomo.Object, Role) event.Cookie // RGBA returns the RGBA values of the corresponding color ID. RGBA (Color) (r, g, b, a uint32) - // Icon returns a texture of the corresponding icon ID. This texture - // should be protected, unless a new copy of it is returned with each - // subsequent call. + // Icon returns a texture of the corresponding icon ID. Icon (Icon, IconSize) canvas.Texture - // MimeIcon returns an icon corresponding to a MIME type. This texture - // should be protected, unless a new copy of it is returned with each - // subsequent call. + // MimeIcon returns an icon corresponding to a MIME type. MimeIcon (data.Mime, IconSize) canvas.Texture - // ApplicationIcon returns an icon corresponding to an application. This - // texture should be protected, unless a new copy of it is returned with - // each subsequent call. + // ApplicationIcon returns an icon corresponding to an application. ApplicationIcon (ApplicationIcon, IconSize) canvas.Texture }