mado

README

About

Mado is an window/framebuffer client for Windows/Mac/Linux.

Based a lot on Gio UI.

Currently, WIP.

Purpose

• Intended to be a base layer for GUI toolkits and game engines.
• Transparent window control for various GUI desktops
  • Support for MS-Windows, Mac OS, X11 and Wayland
• Selectable hardware renderers
  • Support for OpenGL(ES), DirectX 11, Vulkan, Metal, CPU
• Transparent IME Text input support
• Provide glfw compatible API (a valid alternative from go-gl/glfw)
• Reduce cgo programs as much as possible and enable development in Go language

Means

The word 'Mado' is the Japanese word for '窓(まど)' and the meaning is Window.

Motivation

• I would like to see more GUI toolkits that support CJK Languages, e.g. Japanese.
• Solve the problem that IME text input is not supported in go-gl/glfw, which is widely used in Go language.

Aims for

• Achieve the purpose items
• Development by communities rather than individuals
• Provision of parts useful for GUI toolkit or game engines development
  • Events, OS Thread Managements, Common Drawing API

Not aims for

• Completed GUI toolkit and game engine

FAQ

License

MIT / The UNLICENSE

Documentation

Index

• Constants
• Variables
• func GlfwConfigInit()
• func WalkActions(actions system.Action, do func(system.Action))
• type Callbacks
• type Config
  • func (c *Config) Apply(m unit.Metric, options []Option)
• type ConfigEvent
  • func (ConfigEvent) ImplementsEvent()
• type Context
• type CtxConfig
• type DestroyEvent
  • func (DestroyEvent) ImplementsEvent()
• type Driver
• type EditorState
  • func (e *EditorState) Replace(r key.Range, text string)
  • func (e *EditorState) RunesIndex(chars int) int
  • func (e *EditorState) UTF16Index(runes int) int
• type FbConfig
  • func ChooseFBConfig(desired *FbConfig, alternatives []*FbConfig) *FbConfig
• type FrameEvent
  • func (FrameEvent) ImplementsEvent()
• type GlfwContext
  • func (c *GlfwContext) RefreshContextAttribs(ctxconfig *CtxConfig) error
• type Insets
• type Library
• type Option
  • func DecoHeightOpt(h unit.Dp) Option
• type Orientation
  • func (o Orientation) Option() Option
  • func (o Orientation) String() string
• type PlatformContextState
• type PlatformLibraryContextState
• type Stage
  • func (l Stage) String() string
• type StageEvent
  • func (StageEvent) ImplementsEvent()
• type ViewEvent
• type WakeupEvent
  • func (WakeupEvent) ImplementsEvent()
• type Window
• type WindowAndConfig
• type WindowMode
  • func (m WindowMode) Option() Option
  • func (m WindowMode) String() string
• type WindowRendezvous
  • func NewWindowRendezvous() *WindowRendezvous
• type WndConfig

Constants

const (
	GLFW_TRUE  = true
	GLFW_FALSE = false

	GLFW_DONT_CARE              = -1
	GLFW_NO_API                 = 0
	GLFW_OPENGL_API             = 0x00030001
	GLFW_OPENGL_ES_API          = 0x00030002
	GLFW_OPENGL_ANY_PROFILE     = 0
	GLFW_OPENGL_CORE_PROFILE    = 0x00032001
	GLFW_OPENGL_COMPAT_PROFILE  = 0x00032002
	GLFW_NO_ROBUSTNESS          = 0
	GLFW_NO_RESET_NOTIFICATION  = 0x00031001
	GLFW_LOSE_CONTEXT_ON_RESET  = 0x00031002
	GLFW_ANY_RELEASE_BEHAVIOR   = 0
	GLFW_RELEASE_BEHAVIOR_FLUSH = 0x00035001
	GLFW_RELEASE_BEHAVIOR_NONE  = 0x00035002
)

const (
	True     int = 1 // GL_TRUE
	False    int = 0 // GL_FALSE
	DontCare int = -1

	AnyReleaseBehavior   = 0
	CursorDisabled       = 0x00034003
	CursorHidden         = 0x00034002
	CursorNormal         = 0x00034001
	EGLContextAPI        = 0x00036002
	LoseContextOnReset   = 0x00031002
	NativeContextAPI     = 0x00036001
	NoAPI                = 0
	NoResetNotification  = 0x00031001
	NoRobustness         = 0
	OpenGLAPI            = 0x00030001
	OpenGLAnyProfile     = 0
	OpenGLCompatProfile  = 0x00032002
	OpenGLCoreProfile    = 0x00032001
	OpenGLESAPI          = 0x00030002
	OSMesaContextAPI     = 0x00036003
	ReleaseBehaviorFlush = 0x00035001
	ReleaseBehaviorNone  = 0x00035002

	WindowTypeWindows = 0x00040001
	WindowTypeMac     = 0x00040002
	WindowTypeX11     = 0x00040003
	WindowTypeWayland = 0x00040004
)

Variables

var EnablePollEvents func()

var ErrOutOfDate = errors.New("app: GPU surface out of date")

errOutOfDate is reported when the GPU surface dimensions or properties no longer match the window.

var GetTimerFrequency func() uint64

var GetTimerValue func() uint64

var ID = ""

ID is the app id exposed to the platform.

On Android ID is the package property of AndroidManifest.xml, on iOS ID is the CFBundleIdentifier of the app Info.plist, on Wayland it is the toplevel app_id, on X11 it is the X11 XClassHint.

ID is set by the github.com/kanryu/mado/cmd/gogio tool or manually with the -X linker flag. For example,

go build -ldflags="-X 'github.com/kanryu/mado/app.ID=org.gioui.example.Kitchen'" .

Note that ID is treated as a constant, and that changing it at runtime is not supported. The default value of ID is filepath.Base(os.Args[0]).

var OsMain func()

var OsNewWindow func(window Callbacks, options []Option) error

var PollEvents func()

Functions

func GlfwConfigInit

func GlfwConfigInit()

func WalkActions

func WalkActions(actions system.Action, do func(system.Action))

Types

type Callbacks

type Callbacks interface {
	GetWindow() Window
	SetWindow(w Window)
	SetDriver(d Driver)
	Event(e event.Event) bool
	SemanticRoot() input.SemanticID
	LookupSemantic(semID input.SemanticID) (input.SemanticNode, bool)
	AppendSemanticDiffs(diffs []input.SemanticID) []input.SemanticID
	SemanticAt(pos f32.Point) (input.SemanticID, bool)
	EditorState() EditorState
	SetComposingRegion(r key.Range)
	EditorInsert(text string, preedit bool)
	EditorReplace(r key.Range, text string, preedit bool)
	SetEditorSelection(r key.Range)
	SetEditorSnippet(r key.Range)
	ClickFocus()
	ActionAt(p f32.Point) (system.Action, bool)
}

type Config

type Config struct {
	// Size is the window dimensions (Width, Height).
	Size image.Point
	// MaxSize is the window maximum allowed dimensions.
	MaxSize image.Point
	// MinSize is the window minimum allowed dimensions.
	MinSize image.Point
	// Title is the window title displayed in its decoration bar.
	Title string
	// WindowMode is the window mode.
	Mode WindowMode
	// StatusColor is the color of the Android status bar.
	StatusColor color.NRGBA
	// NavigationColor is the color of the navigation bar
	// on Android, or the address bar in browsers.
	NavigationColor color.NRGBA
	// Orientation is the current window orientation.
	Orientation Orientation
	// CustomRenderer is true when the window content is rendered by the
	// client.
	CustomRenderer bool
	// Decorated reports whether window decorations are provided automatically.
	Decorated bool
	// decoHeight is the height of the fallback decoration for platforms such
	// as Wayland that may need fallback client-side decorations.
	DecoHeight unit.Dp
}

Config describes a Window configuration.

func (*Config) Apply

func (c *Config) Apply(m unit.Metric, options []Option)

type ConfigEvent

type ConfigEvent struct {
	Config Config
}

ConfigEvent is sent whenever the configuration of a Window changes.

func (ConfigEvent) ImplementsEvent

func (ConfigEvent) ImplementsEvent()

type Context

type Context interface {
	API() gpu.API
	RenderTarget() (gpu.RenderTarget, error)
	Present() error
	Refresh() error
	Release()
	Lock() error
	Unlock()
	SwapBuffers() error
	SwapInterval(interval int)
}

type CtxConfig

type CtxConfig struct {
	Client     int
	Source     int
	Major      int
	Minor      int
	Forward    bool
	Debug      bool
	Noerror    bool
	Profile    int
	Robustness int
	Release    int

	Nsgl struct {
		Offline bool
	}
	// contains filtered or unexported fields
}

type DestroyEvent

type DestroyEvent struct {
	// Err is nil for normal window closures. If a
	// window is prematurely closed, Err is the cause.
	Err error
}

DestroyEvent is the last event sent through a window event channel.

func (DestroyEvent) ImplementsEvent

func (DestroyEvent) ImplementsEvent()

type Driver

type Driver interface {
	// SetAnimating sets the animation flag. When the window is animating,
	// FrameEvents are delivered as fast as the display can handle them.
	SetAnimating(anim bool)
	// ShowTextInput updates the virtual keyboard state.
	ShowTextInput(show bool)
	SetInputHint(mode key.InputHint)
	NewContext() (Context, error)
	// ReadClipboard requests the clipboard content.
	ReadClipboard()
	// WriteClipboard requests a clipboard write.
	WriteClipboard(mime string, s []byte)
	// Configure the window.
	Configure([]Option)
	// SetCursor updates the current cursor to name.
	SetCursor(cursor pointer.Cursor)
	// Wakeup wakes up the event loop and sends a WakeupEvent.
	Wakeup()
	// Perform actions on the window.
	Perform(system.Action)
	// EditorStateChanged notifies the driver that the editor state changed.
	EditorStateChanged(old, new EditorState)
	GetFrameBufferSize() image.Point
}

Driver is the interface for the platform implementation of a window.

type EditorState

type EditorState struct {
	input.EditorState
	Compose key.Range
}

func (*EditorState) Replace

func (e *EditorState) Replace(r key.Range, text string)

func (*EditorState) RunesIndex

func (e *EditorState) RunesIndex(chars int) int

RunesIndex converts the given index in utf16 characters to an index in runes.

func (*EditorState) UTF16Index

func (e *EditorState) UTF16Index(runes int) int

UTF16Index converts the given index in runes into an index in utf16 characters.

type FbConfig

type FbConfig struct {
	RedBits        int
	GreenBits      int
	BlueBits       int
	AlphaBits      int
	DepthBits      int
	StencilBits    int
	AccumRedBits   int
	AccumGreenBits int
	AccumBlueBits  int
	AccumAlphaBits int
	AuxBuffers     int
	Stereo         bool
	Samples        int
	SRGB           bool
	Doublebuffer   bool
	Transparent    bool
	Handle         uintptr
}

func ChooseFBConfig

func ChooseFBConfig(desired *FbConfig, alternatives []*FbConfig) *FbConfig

type FrameEvent

type FrameEvent struct {
	// Now is the current animation. Use Now instead of time.Now to
	// synchronize animation and to avoid the time.Now call overhead.
	Now time.Time
	// Metric converts device independent dp and sp to device pixels.
	Metric unit.Metric
	// Size is the dimensions of the window.
	Size image.Point
	// Insets represent the space occupied by system decorations and controls.
	Insets Insets
	// Frame completes the FrameEvent by drawing the graphical operations
	// from ops into the window.
	Frame func(frame *op.Ops)
	// Source is the interface between the window and widgets.
	Source input.Source

	Sync bool
}

A FrameEvent requests a new frame in the form of a list of operations that describes the window content.

func (FrameEvent) ImplementsEvent

func (FrameEvent) ImplementsEvent()

type GlfwContext

type GlfwContext struct {
	Client     int
	Source     int
	Major      int
	Minor      int
	Revision   int
	Forward    bool
	Debug      bool
	Noerror    bool
	Profile    int
	Robustness int
	Release    int

	// TODO: Put these functions in an interface type.
	MakeCurrent        func(*Window) error
	SwapBuffers        func(*Window) error
	SwapInterval       func(int) error
	ExtensionSupported func(string) bool
	GetProcAddress     func(string) uintptr
	Destroy            func(*Window) error
	GetString          func(gl.Enum) string
	GetInteger         func(gl.Enum) int

	Platform PlatformContextState
}

func (*GlfwContext) RefreshContextAttribs

func (c *GlfwContext) RefreshContextAttribs(ctxconfig *CtxConfig) error

type Insets

type Insets struct {
	// Values are in pixels.
	Top, Bottom, Left, Right unit.Dp
}

Insets is the space taken up by system decoration such as translucent system bars and software keyboards.

type Library

type Library struct {
	Initialized bool
	Enable      bool
	WindowType  int

	Hints struct {
		Framebuffer FbConfig
		Window      WndConfig
		Context     CtxConfig
		RefreshRate int
		// contains filtered or unexported fields
	}

	// platformWindow  platformLibraryWindowState
	PlatformContext PlatformLibraryContextState
	// contains filtered or unexported fields
}

var GlfwConfig Library

type Option

type Option func(unit.Metric, *Config)

Option configures a window.

func DecoHeightOpt

func DecoHeightOpt(h unit.Dp) Option

type Orientation

type Orientation uint8

Orientation is the orientation of the app (Orientation.Option sets it).

Supported platforms are Android and JS.

const (
	// AnyOrientation allows the window to be freely orientated.
	AnyOrientation Orientation = iota
	// LandscapeOrientation constrains the window to landscape orientations.
	LandscapeOrientation
	// PortraitOrientation constrains the window to portrait orientations.
	PortraitOrientation
)

func (Orientation) Option

func (o Orientation) Option() Option

func (Orientation) String

func (o Orientation) String() string

type PlatformContextState

type PlatformContextState struct {
}

type PlatformLibraryContextState

type PlatformLibraryContextState struct {
	Inited bool
	Major  int
	Minor  int

	EGL_KHR_create_context      bool
	KHR_create_context_no_error bool
	KHR_gl_colorspace           bool
	KHR_get_all_proc_addresses  bool
	KHR_context_flush_control   bool
	EXT_present_opaque          bool
}

type Stage

type Stage uint8

Stage of a Window.

const (
	// StagePaused is the stage for windows that have no on-screen representation.
	// Paused windows don't receive frames.
	StagePaused Stage = iota
	// StageInactive is the stage for windows that are visible, but not active.
	// Inactive windows receive frames.
	StageInactive
	// StageRunning is for active and visible Windows.
	// Running windows receive frames.
	StageRunning
)

func (Stage) String

func (l Stage) String() string

String implements fmt.Stringer.

type StageEvent

type StageEvent struct {
	Stage      Stage
	WindowMode WindowMode
}

A StageEvent is generated whenever the stage of a Window changes.

func (StageEvent) ImplementsEvent

func (StageEvent) ImplementsEvent()

type ViewEvent

type ViewEvent interface {
	ImplementsViewEvent()
	ImplementsEvent()
}

ViewEvent provides handles to the underlying window objects for the current display protocol.

type WakeupEvent

type WakeupEvent struct{}

func (WakeupEvent) ImplementsEvent

func (WakeupEvent) ImplementsEvent()

type Window

type Window interface {
	Update(frame *op.Ops)
	ValidateAndProcess(d Driver, size image.Point, sync bool, frame *op.Ops, sigChan chan<- struct{}) error
	Frame(frame *op.Ops, viewport image.Point) error
	ProcessFrame(d Driver)
	Invalidate()
	Option(opts ...Option)
	Run(f func())
	DriverDefer(f func(d Driver))
	UpdateAnimation(d Driver)
	Wakeup()
	SetNextFrame(at time.Time)
	WaitAck(d Driver)
	DestroyGPU()
	UpdateSemantics()
	CollectSemanticDiffs(diffs *[]input.SemanticID, n input.SemanticNode)
	UpdateState(d Driver)
	ProcessEvent(d Driver, e event.Event) bool
	NextEvent() event.Event
	UpdateCursor(d Driver)
	FallbackDecorate() bool
	Decorate(d Driver, e FrameEvent, o *op.Ops) (size, offset image.Point)
	EffectiveConfig() Config
	Perform(actions system.Action)
}

type WindowAndConfig

type WindowAndConfig struct {
	Window  *Callbacks
	Options []Option
}

type WindowMode

type WindowMode uint8

WindowMode is the window mode (WindowMode.Option sets it). Note that mode can be changed programatically as well as by the user clicking on the minimize/maximize buttons on the window's title bar.

const (
	Noop WindowMode = iota
	// Windowed is the normal window mode with OS specific window decorations.
	Windowed
	// Fullscreen is the full screen window mode.
	Fullscreen
	// Minimized is for systems where the window can be minimized to an icon.
	Minimized
	// Maximized is for systems where the window can be made to fill the available monitor area.
	Maximized
)

func (WindowMode) Option

func (m WindowMode) Option() Option

Option changes the mode of a Window.

func (WindowMode) String

func (m WindowMode) String() string

String returns the mode name.

type WindowRendezvous

type WindowRendezvous struct {
	// contains filtered or unexported fields
}

Make it possible to update the options into Callbacks in a pseudo-windowless OS such as Android or iOS

func NewWindowRendezvous

func NewWindowRendezvous() *WindowRendezvous

type WndConfig

type WndConfig struct {
	Width            int
	Height           int
	Title            string
	Resizable        bool
	Visible          bool
	Decorated        bool
	Focused          bool
	AutoIconify      bool
	Floating         bool
	Maximized        bool
	CenterCursor     bool
	FocusOnShow      bool
	MousePassthrough bool
	ScaleToMonitor   bool
	Ns               struct {
		Retina    bool
		FrameName string
	}
	X11 struct {
		ClassName    string
		InstanceName string
	}
}