stone/backend.go

package stone

import "image"
import "errors"

// Backend represents a backend for stone. Backends can be registered for use
// with the RegisterBackend() function. All of the below methods MUST be thread
// safe!
type Backend interface {
	// Run is the backend's event loop. It must cleanly exit when the user
	// closes the window, but not before calling the OnQuit event. Run
	// must call event handlers within its own event loop in a
	// non-concurrent fashion.
	//
	// The OnStart event handler must run after the backend has been fully
	// initialized, and right before updates are first pushed to the screen.
	// Whatever the application draws from within this event handler must be
	// the first thing that appears on-screen.
	//
	// The OnResize event handler must run whenever the window is resized.
	// The backend must push updates to the screen after OnResize has been
	// run.
	//
	// The backend must not push updates to the screen in any other case,
	// except when its Draw() method is specifically called.
	//
	// The OnPress, OnRelease, OnMouseMove, and OnMouseScroll events are to
	// be called when such events happen. It is reccommended to compress
	// resize, mouse move, and mouse scroll events whenever possible to
	// reduce the likelihood of event buildup.
	Run ()

	// SetTitle sets the application title. This will most often be the
	// window title. This method may not always produce an effect, depending
	// on the backend.
	SetTitle (title string) (err error)

	// SetIcon takes in a set of images of different sizes and sets the
	// window's icon to them. This method may not always produce an effect,
	// depending on the backend.
	SetIcon (icons []image.Image) (err error)

	// Draw pushes all updates made to the application's buffer to the
	// screen.
	Draw ()
}

// BackendFactory must completely initialize a backend, and return it. If
// anything goes wrong, it must stop, clean up any resources and return an
// error so another backend can be chosen.
type BackendFactory func (
	application *Application,
	callbackManager *CallbackManager,
) (
	backend Backend,
	err error,
)

var factories []BackendFactory

// RegisterBackend registers a backend factory.
func RegisterBackend (factory BackendFactory) {
	factories = append(factories, factory)
}

func instantiateBackend (application *Application) (backend Backend, err error) {
	// find a suitable backend
	for _, factory := range factories {
		backend, err = factory(application, &application.callbackManager)
		if err == nil && backend != nil { return }
	}

	// if none were found, but there was no error produced, produce an
	// error
	if err == nil {
		err = errors.New("no available backends")
	}

	return
}