Documentation
¶
Overview ¶
Package app provides a platform-independent interface to operating system functionality for running graphical user interfaces.
See https://github.com/kanryu/mado for instructions to set up and run Gio programs.
Windows ¶
Create a new Window by calling NewWindow. On mobile platforms or when Gio is embedded in another project, NewWindow merely connects with a previously created window.
A Window is run by calling its NextEvent method in a loop. The most important event is [FrameEvent] that prompts an update of the window contents.
For example:
w := app.NewWindow()
for {
e := w.NextEvent()
if e, ok := e.(app.FrameEvent); ok {
ops.Reset()
// Add operations to ops.
...
// Completely replace the window contents and state.
e.Frame(ops)
}
}
A program must keep receiving events from the event channel until [DestroyEvent] is received.
Main ¶
The Main function must be called from a program's main function, to hand over control of the main thread to operating systems that need it.
Because Main is also blocking on some platforms, the event loop of a Window must run in a goroutine.
For example, to display a blank but otherwise functional window:
package main
import "github.com/kanryu/mado/app"
func main() {
go func() {
w := app.NewWindow()
for {
w.NextEvent()
}
}()
app.Main()
}
Permissions ¶
The packages under github.com/kanryu/mado/app/permission should be imported by a Gio program or by one of its dependencies to indicate that specific operating-system permissions are required. Please see documentation for package github.com/kanryu/mado/app/permission for more information.
Index ¶
- func CustomRenderer(custom bool) mado.Option
- func DataDir() (string, error)
- func Decorated(enabled bool) mado.Option
- func Main()
- func MaxSize(w, h unit.Dp) mado.Option
- func MinSize(w, h unit.Dp) mado.Option
- func NavigationColor(color color.NRGBA) mado.Option
- func NewContext(ops *op.Ops, e mado.FrameEvent) layout.Context
- func Size(w, h unit.Dp) mado.Option
- func StatusColor(color color.NRGBA) mado.Option
- func Title(t string) mado.Option
- type Callbacks
- func (c *Callbacks) ActionAt(p f32.Point) (system.Action, bool)
- func (c *Callbacks) AppendSemanticDiffs(diffs []input.SemanticID) []input.SemanticID
- func (c *Callbacks) ClickFocus()
- func (c *Callbacks) EditorInsert(text string, preedit bool)
- func (c *Callbacks) EditorReplace(r key.Range, text string, preedit bool)
- func (c *Callbacks) EditorState() mado.EditorState
- func (c *Callbacks) Event(e event.Event) bool
- func (c *Callbacks) GetWindow() mado.Window
- func (c *Callbacks) LookupSemantic(semID input.SemanticID) (input.SemanticNode, bool)
- func (c *Callbacks) SemanticAt(pos f32.Point) (input.SemanticID, bool)
- func (c *Callbacks) SemanticRoot() input.SemanticID
- func (c *Callbacks) SetComposingRegion(r key.Range)
- func (c *Callbacks) SetDriver(d mado.Driver)
- func (c *Callbacks) SetEditorSelection(r key.Range)
- func (c *Callbacks) SetEditorSnippet(r key.Range)
- func (c *Callbacks) SetWindow(w mado.Window)
- type Window
- func (w *Window) CollectSemanticDiffs(diffs *[]input.SemanticID, n input.SemanticNode)
- func (w *Window) Decorate(d mado.Driver, e mado.FrameEvent, o *op.Ops) (size, offset image.Point)
- func (w *Window) DestroyGPU()
- func (w *Window) DriverDefer(f func(d mado.Driver))
- func (w *Window) EffectiveConfig() mado.Config
- func (w *Window) FallbackDecorate() bool
- func (w *Window) Frame(frame *op.Ops, viewport image.Point) error
- func (w *Window) Invalidate()
- func (w *Window) NextEvent() event.Event
- func (w *Window) Option(opts ...mado.Option)
- func (w *Window) Perform(actions system.Action)
- func (w *Window) ProcessEvent(d mado.Driver, e event.Event) bool
- func (w *Window) ProcessFrame(d mado.Driver)
- func (w *Window) Run(f func())
- func (w *Window) SetNextFrame(at time.Time)
- func (w *Window) Update(frame *op.Ops)
- func (w *Window) UpdateAnimation(d mado.Driver)
- func (w *Window) UpdateCursor(d mado.Driver)
- func (w *Window) UpdateSemantics()
- func (w *Window) UpdateState(d mado.Driver)
- func (w *Window) ValidateAndProcess(d mado.Driver, size image.Point, sync bool, frame *op.Ops, ...) error
- func (w *Window) WaitAck(d mado.Driver)
- func (w *Window) Wakeup()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CustomRenderer ¶
CustomRenderer controls whether the window contents is rendered by the client. If true, no GPU context is created.
Caller must assume responsibility for rendering which includes initializing the render backend, swapping the framebuffer and handling frame pacing.
func DataDir ¶
DataDir returns a path to use for application-specific configuration data. On desktop systems, DataDir use os.UserConfigDir. On iOS NSDocumentDirectory is queried. For Android Context.getFilesDir is used.
BUG: DataDir blocks on Android until init functions have completed.
func Decorated ¶
Decorated controls whether Gio and/or the platform are responsible for drawing window decorations. Providing false indicates that the application will either be undecorated or will draw its own decorations.
func Main ¶
func Main()
Main must be called last from the program main function. On most platforms Main blocks forever, for Android and iOS it returns immediately to give control of the main thread back to the system.
Calling Main is necessary because some operating systems require control of the main thread of the program for running windows.
func NavigationColor ¶
NavigationColor sets the color of the navigation bar on Android, or the address bar in browsers.
func NewContext ¶
NewContext is shorthand for
layout.Context{
Ops: ops,
Now: e.Now,
Source: e.Source,
Metric: e.Metric,
Constraints: layout.Exact(e.Size),
}
NewContext calls ops.Reset and adjusts ops for e.Insets.
func StatusColor ¶
StatusColor sets the color of the Android status bar.
Types ¶
type Callbacks ¶
type Callbacks struct {
// contains filtered or unexported fields
}
func (*Callbacks) AppendSemanticDiffs ¶
func (c *Callbacks) AppendSemanticDiffs(diffs []input.SemanticID) []input.SemanticID
func (*Callbacks) ClickFocus ¶
func (c *Callbacks) ClickFocus()
func (*Callbacks) EditorInsert ¶
func (*Callbacks) EditorReplace ¶
func (*Callbacks) EditorState ¶
func (c *Callbacks) EditorState() mado.EditorState
func (*Callbacks) LookupSemantic ¶
func (c *Callbacks) LookupSemantic(semID input.SemanticID) (input.SemanticNode, bool)
LookupSemantic looks up a semantic node from an ID. The zero ID denotes the root.
func (*Callbacks) SemanticAt ¶
func (*Callbacks) SemanticRoot ¶
func (c *Callbacks) SemanticRoot() input.SemanticID
SemanticRoot returns the ID of the semantic root.
func (*Callbacks) SetComposingRegion ¶
func (*Callbacks) SetEditorSelection ¶
func (*Callbacks) SetEditorSnippet ¶
type Window ¶
type Window struct {
// wakeupFuncs is sent wakeup functions when the driver changes.
WakeupFuncs chan func()
// options are the options waiting to be applied.
Options chan []mado.Option
// actions are the actions waiting to be performed.
Actions chan system.Action
Destroy chan struct{}
// metric is the metric from the most recent frame.
Metric unit.Metric
Queue input.Router
Decorations struct {
op.Ops
// enabled tracks the Decorated option as
// given to the Option method. It may differ
// from Config.Decorated depending on platform
// capability.
Enabled bool
mado.Config
Height unit.Dp
CurrentHeight int
*material.Theme
*widget.Decorations
}
// semantic data, lazily evaluated if requested by a backend to speed up
// the cases where semantic data is not needed.
Semantic struct {
// uptodate tracks whether the fields below are up to date.
Uptodate bool
Root input.SemanticID
PrevTree []input.SemanticNode
Tree []input.SemanticNode
Ids map[input.SemanticID]input.SemanticNode
}
ImeState mado.EditorState
// event stores the state required for processing and delivering events
// from NextEvent. If we had support for range over func, this would
// be the iterator state.
EventState struct {
Created bool
InitialOpts []mado.Option
Wakeup func()
Timer *time.Timer
}
// contains filtered or unexported fields
}
Window represents an operating system window.
func NewWindow ¶
NewWindow creates a new window for a set of window options. The options are hints; the platform is free to ignore or adjust them.
If the current program is running on iOS or Android, NewWindow returns the window previously created by the platform.
Calling NewWindow more than once is not supported on iOS, Android, WebAssembly.
func (*Window) CollectSemanticDiffs ¶
func (w *Window) CollectSemanticDiffs(diffs *[]input.SemanticID, n input.SemanticNode)
CollectSemanticDiffs traverses the previous semantic tree, noting changed nodes.
func (*Window) DestroyGPU ¶
func (w *Window) DestroyGPU()
func (*Window) DriverDefer ¶
driverDefer is like Run but can be run from any context. It doesn't wait for f to return.
func (*Window) EffectiveConfig ¶
func (*Window) FallbackDecorate ¶
func (*Window) Invalidate ¶
func (w *Window) Invalidate()
Invalidate the window such that a [FrameEvent] will be generated immediately. If the window is inactive, the event is sent when the window becomes active.
Note that Invalidate is intended for externally triggered updates, such as a response from a network request. The op.InvalidateCmd command is more efficient for animation.
Invalidate is safe for concurrent use.
func (*Window) NextEvent ¶
NextEvent blocks until an event is received from the window, such as [FrameEvent]. It blocks forever if called after [DestroyEvent] has been returned.
func (*Window) ProcessFrame ¶
func (*Window) Run ¶
func (w *Window) Run(f func())
Run f in the same thread as the native window event loop, and wait for f to return or the window to close. Run is guaranteed not to deadlock if it is invoked during the handling of a [ViewEvent], [FrameEvent], [StageEvent]; call Run in a separate goroutine to avoid deadlock in all other cases.
Note that most programs should not call Run; configuring a Window with CustomRenderer is a notable exception.
func (*Window) SetNextFrame ¶
func (*Window) Update ¶
update the window contents, input operations declare input handlers, and so on. The supplied operations list completely replaces the window state from previous calls.
func (*Window) UpdateAnimation ¶
func (*Window) UpdateCursor ¶
func (*Window) UpdateSemantics ¶
func (w *Window) UpdateSemantics()
updateSemantics refreshes the semantics tree, the id to node map and the ids of updated nodes.
func (*Window) UpdateState ¶
func (*Window) ValidateAndProcess ¶
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
log
Package points standard output, standard error and the standard library package log to the platform logger.
|
Package points standard output, standard error and the standard library package log to the platform logger. |
|
Package permission includes sub-packages that should be imported by a Gio program or by one of its dependencies to indicate that specific operating-system permissions are required.
|
Package permission includes sub-packages that should be imported by a Gio program or by one of its dependencies to indicate that specific operating-system permissions are required. |
|
bluetooth
Package bluetooth implements permissions to access Bluetooth and Bluetooth Low Energy hardware, including the ability to discover and pair devices.
|
Package bluetooth implements permissions to access Bluetooth and Bluetooth Low Energy hardware, including the ability to discover and pair devices. |
|
camera
Package camera implements permissions to access camera hardware.
|
Package camera implements permissions to access camera hardware. |
|
networkstate
Package networkstate implements permissions to access network connectivity information.
|
Package networkstate implements permissions to access network connectivity information. |
|
storage
Package storage implements read and write storage permissions on mobile devices.
|
Package storage implements read and write storage permissions on mobile devices. |
|
wakelock
Package wakelock implements permission to acquire locks that keep the system from suspending.
|
Package wakelock implements permission to acquire locks that keep the system from suspending. |