Documentation
¶
Overview ¶
Package app provides a platform-independent interface to operating system functionality for running graphical user interfaces.
See https://gioui.org for instructions to set up and run Gio programs.
Windows ¶
A Window is run by calling its Event method in a loop. The first time a method on Window is called, a new GUI window is created and shown. On mobile platforms or when Gio is embedded in another project, Window merely connects with a previously created GUI window.
The most important event is FrameEvent that prompts an update of the window contents.
For example:
w := new(app.Window)
for {
e := w.Event()
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 "gioui.org/app"
func main() {
go func() {
w := app.NewWindow()
for {
w.Event()
}
}()
app.Main()
}
Permissions ¶
The packages under gioui.org/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 gioui.org/app/permission for more information.
SPDX-License-Identifier: Unlicense OR MIT
Index ¶
Constants ¶
This section is empty.
Variables ¶
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 gioui.org/cmd/gogio tool or manually with the -X linker flag. For example,
go build -ldflags="-X 'gioui.org/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]).
Functions ¶
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 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 NewContext ¶ added in v0.5.0
func NewContext(ops *op.Ops, e FrameEvent) layout.Context
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.
Types ¶
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
// 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
// Focused reports whether has the keyboard focus.
Focused bool
// contains filtered or unexported fields
}
Config describes a Window configuration.
type ConfigEvent ¶
type ConfigEvent struct {
Config Config
}
ConfigEvent is sent whenever the configuration of a Window changes.
func (ConfigEvent) ImplementsEvent ¶
func (ConfigEvent) ImplementsEvent()
type DestroyEvent ¶ added in v0.5.0
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 ¶ added in v0.5.0
func (DestroyEvent) ImplementsEvent()
type FrameEvent ¶ added in v0.5.0
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
}
A FrameEvent requests a new frame in the form of a list of operations that describes the window content.
func (FrameEvent) ImplementsEvent ¶ added in v0.5.0
func (FrameEvent) ImplementsEvent()
type Insets ¶ added in v0.5.0
Insets is the space taken up by system decoration such as translucent system bars and software keyboards.
type Option ¶
Option configures a window.
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 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 NavigationColor ¶
NavigationColor sets the color of the navigation bar on Android, or the address bar in browsers.
func StatusColor ¶
StatusColor sets the color of the Android status bar.
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 ViewEvent ¶
type ViewEvent interface {
ImplementsEvent()
// Valid will return true when the ViewEvent does contains valid handles.
// If a window receives an invalid ViewEvent, it should deinitialize any
// state referring to handles from a previous ViewEvent.
Valid() bool
// contains filtered or unexported methods
}
ViewEvent provides handles to the underlying window objects for the current display protocol.
type WaylandViewEvent ¶
type WaylandViewEvent struct {
// Display is the *wl_display returned by wl_display_connect.
Display unsafe.Pointer
// Surface is the *wl_surface returned by wl_compositor_create_surface.
Surface unsafe.Pointer
}
func (WaylandViewEvent) ImplementsEvent ¶
func (WaylandViewEvent) ImplementsEvent()
func (WaylandViewEvent) Valid ¶ added in v0.7.1
func (w WaylandViewEvent) Valid() bool
type Window ¶
type Window struct {
// contains filtered or unexported fields
}
Window represents an operating system window.
The zero-value Window is useful; the GUI window is created and shown the first time the [Event] method is called. On iOS or Android, the first Window represents the window previously created by the platform.
More than one Window is not supported on iOS, Android, WebAssembly.
func (*Window) Event ¶ added in v0.6.0
Event blocks until an event is received from the window, such as FrameEvent, or until [Invalidate] is called. The window is created and shown the first time Event is called.
func (*Window) Invalidate ¶
func (w *Window) Invalidate()
Invalidate the window such that a FrameEvent will be generated immediately. If the window is inactive, an unspecified event is sent instead.
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) Option ¶
Option applies the options to the window. The options are hints; the platform is free to ignore or adjust them.
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. If the window has not yet been created, Run calls f directly.
Note that most programs should not call Run; configuring a Window with CustomRenderer is a notable exception.
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 ( // Windowed is the normal window mode with OS specific window decorations. Windowed WindowMode = iota // 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 )
type X11ViewEvent ¶
type X11ViewEvent struct {
// Display is a pointer to the X11 Display created by XOpenDisplay.
Display unsafe.Pointer
// Window is the X11 window ID as returned by XCreateWindow.
Window uintptr
}
func (X11ViewEvent) ImplementsEvent ¶
func (X11ViewEvent) ImplementsEvent()
func (X11ViewEvent) Valid ¶ added in v0.7.1
func (x X11ViewEvent) Valid() bool
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
xkb
Package xkb implements a Go interface for the X Keyboard Extension library.
|
Package xkb implements a Go interface for the X Keyboard Extension library. |
|
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. |