ui: Add function aliases *OnUnfocused for *InBackground

Now a window can be floating with SetWindowFloating, the functions
that have suffix 'IsBackground' seems misleading. However, we
cannot rename them due to backward compatibility. Then, let's add
aliases and revisit them when updating the major version of Ebiten.

Fixes #1102

examples/audio/main.go

@@ -163,9 +163,9 @@ func (p *Player) update() error {
 	p.playSEIfNeeded()
 	p.updateVolumeIfNeeded()
 
-	if inpututil.IsKeyJustPressed(ebiten.KeyB) {
-		b := ebiten.IsRunnableInBackground()
-		ebiten.SetRunnableInBackground(!b)
+	if inpututil.IsKeyJustPressed(ebiten.KeyU) {
+		b := ebiten.IsRunnableOnUnfocused()
+		ebiten.SetRunnableOnUnfocused(!b)
 	}
 	return nil
 }
@@ -252,7 +252,7 @@ func (p *Player) draw(screen *ebiten.Image) {
 Press S to toggle Play/Pause
 Press P to play SE
 Press Z or X to change volume of the music
-Press B to switch the run-in-background state
+Press U to switch the runnable-on-unfocused state
 Press A to switch Ogg and MP3
 Current Time: %s
 Current Volume: %d/128

examples/windowsize/main.go

@@ -131,7 +131,7 @@ func (g *game) Update(screen *ebiten.Image) error {
 	}
 
 	fullscreen := ebiten.IsFullscreen()
-	runnableInBackground := ebiten.IsRunnableInBackground()
+	runnableOnUnfocused := ebiten.IsRunnableOnUnfocused()
 	cursorVisible := ebiten.IsCursorVisible()
 	vsyncEnabled := ebiten.IsVsyncEnabled()
 	tps := ebiten.MaxTPS()
@@ -194,8 +194,8 @@ func (g *game) Update(screen *ebiten.Image) error {
 	if inpututil.IsKeyJustPressed(ebiten.KeyF) {
 		fullscreen = !fullscreen
 	}
-	if inpututil.IsKeyJustPressed(ebiten.KeyB) {
-		runnableInBackground = !runnableInBackground
+	if inpututil.IsKeyJustPressed(ebiten.KeyU) {
+		runnableOnUnfocused = !runnableOnUnfocused
 	}
 	if inpututil.IsKeyJustPressed(ebiten.KeyC) {
 		cursorVisible = !cursorVisible
@@ -238,7 +238,7 @@ func (g *game) Update(screen *ebiten.Image) error {
 		}
 	}
 	ebiten.SetFullscreen(fullscreen)
-	ebiten.SetRunnableInBackground(runnableInBackground)
+	ebiten.SetRunnableOnUnfocused(runnableOnUnfocused)
 	ebiten.SetCursorVisible(cursorVisible)
 	ebiten.SetVsyncEnabled(vsyncEnabled)
 	ebiten.SetMaxTPS(tps)
@@ -294,7 +294,7 @@ func (g *game) Update(screen *ebiten.Image) error {
 	msg := fmt.Sprintf(`Press arrow keys to move the window
 Press shift + arrow keys to change the window size
 %sPress F key to switch the fullscreen state (only for desktops)
-Press B key to switch the run-in-background state
+Press U key to switch the runnable-on-unfocused state
 Press C key to switch the cursor visibility
 Press I key to change the window icon (only for desktops)
 Press V key to switch vsync

internal/driver/ui.go

@@ -38,7 +38,7 @@ type UI interface {
 	CursorMode() CursorMode
 	IsFullscreen() bool
 	IsFocused() bool
-	IsRunnableInBackground() bool
+	IsRunnableOnUnfocused() bool
 	IsVsyncEnabled() bool
 	ScreenSizeInFullscreen() (int, int)
 	IsScreenTransparent() bool
@@ -46,7 +46,7 @@ type UI interface {
 
 	SetCursorMode(mode CursorMode)
 	SetFullscreen(fullscreen bool)
-	SetRunnableInBackground(runnableInBackground bool)
+	SetRunnableOnUnfocused(runnableOnUnfocused bool)
 	SetVsyncEnabled(enabled bool)
 	SetScreenTransparent(transparent bool)
 

internal/uidriver/glfw/ui.go

@@ -49,7 +49,7 @@ type UserInterface struct {
 	toChangeSize        bool
 	origPosX            int
 	origPosY            int
-	runnableInBackground bool
+	runnableOnUnfocused bool
 	vsync               bool
 
 	lastDeviceScaleFactor float64
@@ -253,16 +253,16 @@ func (u *UserInterface) setInitWindowDecorated(decorated bool) {
 	u.m.Unlock()
 }
 
-func (u *UserInterface) isRunnableInBackground() bool {
+func (u *UserInterface) isRunnableOnUnfocused() bool {
 	u.m.RLock()
-	v := u.runnableInBackground
+	v := u.runnableOnUnfocused
 	u.m.RUnlock()
 	return v
 }
 
-func (u *UserInterface) setRunnableInBackground(runnableInBackground bool) {
+func (u *UserInterface) setRunnableOnUnfocused(runnableOnUnfocused bool) {
 	u.m.Lock()
-	u.runnableInBackground = runnableInBackground
+	u.runnableOnUnfocused = runnableOnUnfocused
 	u.m.Unlock()
 }
 
@@ -429,12 +429,12 @@ func (u *UserInterface) IsFocused() bool {
 	return focused
 }
 
-func (u *UserInterface) SetRunnableInBackground(runnableInBackground bool) {
-	u.setRunnableInBackground(runnableInBackground)
+func (u *UserInterface) SetRunnableOnUnfocused(runnableOnUnfocused bool) {
+	u.setRunnableOnUnfocused(runnableOnUnfocused)
 }
 
-func (u *UserInterface) IsRunnableInBackground() bool {
-	return u.isRunnableInBackground()
+func (u *UserInterface) IsRunnableOnUnfocused() bool {
+	return u.isRunnableOnUnfocused()
 }
 
 func (u *UserInterface) SetVsyncEnabled(enabled bool) {
@@ -757,7 +757,7 @@ func (u *UserInterface) update(context driver.UIContext) error {
 	_ = u.t.Call(func() error {
 		defer hooks.ResumeAudio()
 
-		for !u.isRunnableInBackground() && u.window.GetAttrib(glfw.Focused) == 0 {
+		for !u.isRunnableOnUnfocused() && u.window.GetAttrib(glfw.Focused) == 0 {
 			hooks.SuspendAudio()
 			// Wait for an arbitrary period to avoid busy loop.
 			time.Sleep(time.Second / 60)

internal/uidriver/js/ui.go

@@ -30,7 +30,7 @@ import (
 )
 
 type UserInterface struct {
-	runnableInBackground bool
+	runnableOnUnfocused bool
 	vsync               bool
 	running             bool
 
@@ -80,12 +80,12 @@ func (u *UserInterface) IsFocused() bool {
 	return u.isFocused()
 }
 
-func (u *UserInterface) SetRunnableInBackground(runnableInBackground bool) {
-	u.runnableInBackground = runnableInBackground
+func (u *UserInterface) SetRunnableOnUnfocused(runnableOnUnfocused bool) {
+	u.runnableOnUnfocused = runnableOnUnfocused
 }
 
-func (u *UserInterface) IsRunnableInBackground() bool {
-	return u.runnableInBackground
+func (u *UserInterface) IsRunnableOnUnfocused() bool {
+	return u.runnableOnUnfocused
 }
 
 func (u *UserInterface) SetVsyncEnabled(enabled bool) {
@@ -142,7 +142,7 @@ func (u *UserInterface) updateSize() {
 }
 
 func (u *UserInterface) suspended() bool {
-	if u.runnableInBackground {
+	if u.runnableOnUnfocused {
 		return false
 	}
 	return !u.isFocused()

internal/uidriver/mobile/ui.go

@@ -405,11 +405,11 @@ func (u *UserInterface) IsFocused() bool {
 	return fg
 }
 
-func (u *UserInterface) IsRunnableInBackground() bool {
+func (u *UserInterface) IsRunnableOnUnfocused() bool {
 	return false
 }
 
-func (u *UserInterface) SetRunnableInBackground(runnableInBackground bool) {
+func (u *UserInterface) SetRunnableOnUnfocused(runnableOnUnfocused bool) {
 	// Do nothing
 }
 

run.go

@@ -138,7 +138,7 @@ func IsRunningSlowly() bool {
 // This is not related to framerate (display's refresh rate).
 //
 // f is not called when the window is in background by default.
-// This setting is configurable with SetRunnableInBackground.
+// This setting is configurable with SetRunnableOnUnfocused.
 //
 // The given scale is ignored on fullscreen mode or gomobile-build mode.
 //
@@ -208,7 +208,7 @@ func (i *imageDumperGame) Layout(outsideWidth, outsideHeight int) (screenWidth,
 // This is not related to framerate (display's refresh rate).
 //
 // game's Update is not called when the window is in background by default.
-// This setting is configurable with SetRunnableInBackground.
+// This setting is configurable with SetRunnableOnUnfocused.
 //
 // The given scale is ignored on fullscreen mode or gomobile-build mode.
 //
@@ -362,22 +362,27 @@ func SetFullscreen(fullscreen bool) {
 // IsFocused returns a boolean value indicating whether
 // the game is in focus or in the foreground.
 //
-// IsFocused will only return true if IsRunnableInBackground is false.
+// IsFocused will only return true if IsRunnableOnUnfocused is false.
 //
 // IsFocused is concurrent-safe.
 func IsFocused() bool {
 	return uiDriver().IsFocused()
 }
 
-// IsRunnableInBackground returns a boolean value indicating whether
+// IsRunnableOnUnfocused returns a boolean value indicating whether
 // the game runs even in background.
 //
-// IsRunnableInBackground is concurrent-safe.
-func IsRunnableInBackground() bool {
-	return uiDriver().IsRunnableInBackground()
+// IsRunnableOnUnfocused is concurrent-safe.
+func IsRunnableOnUnfocused() bool {
+	return uiDriver().IsRunnableOnUnfocused()
 }
 
-// SetRunnableInBackground sets the state if the game runs even in background.
+// IsRunnableInBackground is deprecated as of 1.11.0-alpha. Use IsRunnableOnUnfocused instead.
+func IsRunnableInBackground() bool {
+	return IsRunnableOnUnfocused()
+}
+
+// SetRunnableOnUnfocused sets the state if the game runs even in background.
 //
 // If the given value is true, the game runs in background e.g. when losing focus.
 // The initial state is false.
@@ -385,11 +390,16 @@ func IsRunnableInBackground() bool {
 // Known issue: On browsers, even if the state is on, the game doesn't run in background tabs.
 // This is because browsers throttles background tabs not to often update.
 //
-// SetRunnableInBackground does nothing on mobiles so far.
+// SetRunnableOnUnfocused does nothing on mobiles so far.
 //
-// SetRunnableInBackground is concurrent-safe.
+// SetRunnableOnUnfocused is concurrent-safe.
+func SetRunnableOnUnfocused(runnableOnUnfocused bool) {
+	uiDriver().SetRunnableOnUnfocused(runnableOnUnfocused)
+}
+
+// SetRunnableInBackground is deprecated as of 1.11.0-alpha. Use SetRunnableOnUnfocused instead.
 func SetRunnableInBackground(runnableInBackground bool) {
-	uiDriver().SetRunnableInBackground(runnableInBackground)
+	SetRunnableOnUnfocused(runnableInBackground)
 }
 
 // DeviceScaleFactor returns a device scale factor value of the current monitor which the window belongs to.