Documentation ¶
Overview ¶
Package widget implements state tracking and event handling of common user interface controls. To draw widgets, use a theme packages such as package github.com/utopiagio/gio/widget/material.
Index ¶
- type Bool
- type Border
- type ChangeEvent
- type Click
- type Clickable
- func (b *Clickable) Click()
- func (b *Clickable) Clicked(gtx layout.Context) bool
- func (b *Clickable) History() []Press
- func (b *Clickable) Hovered() bool
- func (b *Clickable) Layout(gtx layout.Context, w layout.Widget) layout.Dimensions
- func (b *Clickable) Pressed() bool
- func (b *Clickable) Update(gtx layout.Context) (Click, bool)
- type Decorations
- func (d *Decorations) Clickable(action system.Action) *Clickable
- func (d *Decorations) LayoutMove(gtx layout.Context, w layout.Widget) layout.Dimensions
- func (d *Decorations) Maximized() bool
- func (d *Decorations) Perform(actions system.Action)
- func (d *Decorations) Update(gtx layout.Context) system.Action
- type Draggable
- func (d *Draggable) Dragging() bool
- func (d *Draggable) Layout(gtx layout.Context, w, drag layout.Widget) layout.Dimensions
- func (d *Draggable) Offer(gtx layout.Context, mime string, data io.ReadCloser)
- func (d *Draggable) Pos() f32.Point
- func (d *Draggable) Update(gtx layout.Context) (mime string, requested bool)
- type Editor
- func (e *Editor) CaretCoords() f32.Point
- func (e *Editor) CaretPos() (line, col int)
- func (e *Editor) ClearSelection()
- func (e *Editor) Delete(graphemeClusters int) (deletedRunes int)
- func (e *Editor) Insert(s string) (insertedRunes int)
- func (e *Editor) Layout(gtx layout.Context, lt *text.Shaper, font font.Font, size unit.Sp, ...) layout.Dimensions
- func (e *Editor) Len() int
- func (e *Editor) MoveCaret(startDelta, endDelta int)
- func (e *Editor) Read(p []byte) (int, error)
- func (e *Editor) Regions(start, end int, regions []Region) []Region
- func (e *Editor) Seek(offset int64, whence int) (int64, error)
- func (e *Editor) SelectedText() string
- func (e *Editor) Selection() (start, end int)
- func (e *Editor) SelectionLen() int
- func (e *Editor) SetCaret(start, end int)
- func (e *Editor) SetText(s string)
- func (e *Editor) Text() string
- func (e *Editor) Update(gtx layout.Context) (EditorEvent, bool)
- func (e *Editor) WriteTo(w io.Writer) (int64, error)
- type EditorEvent
- type Enum
- type Fit
- type Float
- type Icon
- type Image
- type Label
- type List
- type Press
- type Region
- type Scrollbar
- func (s *Scrollbar) AddDrag(ops *op.Ops)
- func (s *Scrollbar) AddIndicator(ops *op.Ops)
- func (s *Scrollbar) AddTrack(ops *op.Ops)
- func (s *Scrollbar) Dragging() bool
- func (s *Scrollbar) IndicatorHovered() bool
- func (s *Scrollbar) ScrollDistance() float32
- func (s *Scrollbar) TrackHovered() bool
- func (s *Scrollbar) Update(gtx layout.Context, axis layout.Axis, viewportStart, viewportEnd float32)
- type SelectEvent
- type Selectable
- func (l *Selectable) ClearSelection()
- func (l *Selectable) Focused() bool
- func (l *Selectable) Layout(gtx layout.Context, lt *text.Shaper, font font.Font, size unit.Sp, ...) layout.Dimensions
- func (l *Selectable) Regions(start, end int, regions []Region) []Region
- func (l *Selectable) SelectedText() string
- func (l *Selectable) Selection() (start, end int)
- func (l *Selectable) SelectionLen() int
- func (l *Selectable) SetCaret(start, end int)
- func (l *Selectable) SetText(s string)
- func (l *Selectable) Text() string
- func (l *Selectable) Truncated() bool
- func (l *Selectable) Update(gtx layout.Context) bool
- type SubmitEvent
- type TextInfo
- Bugs
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bool ¶
type Bool struct { Value bool // contains filtered or unexported fields }
type ChangeEvent ¶
type ChangeEvent struct{}
A ChangeEvent is generated for every user change to the text.
type Clickable ¶
type Clickable struct {
// contains filtered or unexported fields
}
Clickable represents a clickable area.
Example (Passthrough) ¶
package main import ( "fmt" "image" "github.com/utopiagio/gio/f32" "github.com/utopiagio/gio/io/input" "github.com/utopiagio/gio/io/pointer" "github.com/utopiagio/gio/layout" "github.com/utopiagio/gio/op" "github.com/utopiagio/gio/widget" ) func main() { // When laying out clickable widgets on top of each other, // pointer events can be passed down for the underlying // widgets to pick them up. var button1, button2 widget.Clickable var r input.Router gtx := layout.Context{ Ops: new(op.Ops), Constraints: layout.Exact(image.Pt(100, 100)), Source: r.Source(), } // widget lays out two buttons on top of each other. widget := func() { content := func(gtx layout.Context) layout.Dimensions { return layout.Dimensions{Size: gtx.Constraints.Min} } button1.Layout(gtx, content) // button2 completely covers button1, but pass-through allows pointer // events to pass through to button1. defer pointer.PassOp{}.Push(gtx.Ops).Pop() button2.Layout(gtx, content) } // The first layout and call to Frame declare the Clickable handlers // to the input router, so the following pointer events are propagated. widget() r.Frame(gtx.Ops) // Simulate one click on the buttons by sending a Press and Release event. r.Queue( pointer.Event{ Source: pointer.Mouse, Buttons: pointer.ButtonPrimary, Kind: pointer.Press, Position: f32.Pt(50, 50), }, pointer.Event{ Source: pointer.Mouse, Buttons: pointer.ButtonPrimary, Kind: pointer.Release, Position: f32.Pt(50, 50), }, ) if button1.Clicked(gtx) { fmt.Println("button1 clicked!") } if button2.Clicked(gtx) { fmt.Println("button2 clicked!") } }
Output: button1 clicked! button2 clicked!
func (*Clickable) History ¶
History is the past pointer presses useful for drawing markers. History is retained for a short duration (about a second).
type Decorations ¶
type Decorations struct {
// contains filtered or unexported fields
}
Decorations handles the states of window decorations.
func (*Decorations) Clickable ¶
func (d *Decorations) Clickable(action system.Action) *Clickable
Clickable returns the clickable for the given single action.
func (*Decorations) LayoutMove ¶
func (d *Decorations) LayoutMove(gtx layout.Context, w layout.Widget) layout.Dimensions
LayoutMove lays out the widget that makes a window movable.
func (*Decorations) Maximized ¶
func (d *Decorations) Maximized() bool
Maximized returns whether the window is maximized.
func (*Decorations) Perform ¶
func (d *Decorations) Perform(actions system.Action)
Perform updates the decorations as if the specified actions were performed by the user.
type Draggable ¶
type Draggable struct { // Type contains the MIME type and matches transfer.SourceOp. Type string // contains filtered or unexported fields }
Draggable makes a widget draggable.
func (*Draggable) Layout ¶
Example ¶
package main import ( "fmt" "image" "io" "strings" "github.com/utopiagio/gio/f32" "github.com/utopiagio/gio/io/event" "github.com/utopiagio/gio/io/input" "github.com/utopiagio/gio/io/pointer" "github.com/utopiagio/gio/io/transfer" "github.com/utopiagio/gio/layout" "github.com/utopiagio/gio/op" "github.com/utopiagio/gio/op/clip" "github.com/utopiagio/gio/widget" ) func main() { var r input.Router gtx := layout.Context{ Ops: new(op.Ops), Constraints: layout.Exact(image.Pt(100, 100)), Source: r.Source(), } // mime is the type used to match drag and drop operations. // It could be left empty in this example. const mime = "MyMime" drag := &widget.Draggable{Type: mime} var drop int // widget lays out the drag and drop handlers and processes // the transfer events. widget := func() { // Setup the draggable widget. w := func(gtx layout.Context) layout.Dimensions { sz := image.Pt(10, 10) // drag area return layout.Dimensions{Size: sz} } drag.Layout(gtx, w, w) // drag must respond with an Offer event when requested. // Use the drag method for this. if m, ok := drag.Update(gtx); ok { drag.Offer(gtx, m, io.NopCloser(strings.NewReader("hello world"))) } // Setup the area for drops. ds := clip.Rect{ Min: image.Pt(20, 20), Max: image.Pt(40, 40), }.Push(gtx.Ops) event.Op(gtx.Ops, &drop) ds.Pop() // Check for the received data. for { ev, ok := gtx.Event(transfer.TargetFilter{Target: &drop, Type: mime}) if !ok { break } switch e := ev.(type) { case transfer.DataEvent: data := e.Open() defer data.Close() content, _ := io.ReadAll(data) fmt.Println(string(content)) } } } // Register and lay out the widget. widget() r.Frame(gtx.Ops) // Send drag and drop gesture events. r.Queue( pointer.Event{ Kind: pointer.Press, Position: f32.Pt(5, 5), // in the drag area }, pointer.Event{ Kind: pointer.Move, Position: f32.Pt(5, 5), // in the drop area }, pointer.Event{ Kind: pointer.Release, Position: f32.Pt(30, 30), // in the drop area }, ) // Let the widget process the events. widget() r.Frame(gtx.Ops) // Process the transfer.DataEvent. widget() }
Output: hello world
func (*Draggable) Offer ¶
Offer the data ready for a drop. Must be called after being Requested. The mime must be one in the requested list.
type Editor ¶
type Editor struct { // Alignment controls the alignment of text within the editor. Alignment text.Alignment // LineHeight determines the gap between baselines of text. If zero, a sensible // default will be used. LineHeight unit.Sp // LineHeightScale is multiplied by LineHeight to determine the final gap // between baselines. If zero, a sensible default will be used. LineHeightScale float32 // SingleLine force the text to stay on a single line. // SingleLine also sets the scrolling direction to // horizontal. SingleLine bool // ReadOnly controls whether the contents of the editor can be altered by // user interaction. If set to true, the editor will allow selecting text // and copying it interactively, but not modifying it. ReadOnly bool // Submit enabled translation of carriage return keys to SubmitEvents. // If not enabled, carriage returns are inserted as newlines in the text. Submit bool // Mask replaces the visual display of each rune in the contents with the given rune. // Newline characters are not masked. When non-zero, the unmasked contents // are accessed by Len, Text, and SetText. Mask rune // InputHint specifies the type of on-screen keyboard to be displayed. InputHint key.InputHint // MaxLen limits the editor content to a maximum length. Zero means no limit. MaxLen int // Filter is the list of characters allowed in the Editor. If Filter is empty, // all characters are allowed. Filter string // WrapPolicy configures how displayed text will be broken into lines. WrapPolicy text.WrapPolicy // contains filtered or unexported fields }
Editor implements an editable and scrollable text area.
func (*Editor) CaretCoords ¶
CaretCoords returns the coordinates of the caret, relative to the editor itself.
func (*Editor) ClearSelection ¶
func (e *Editor) ClearSelection()
ClearSelection clears the selection, by setting the selection end equal to the selection start.
func (*Editor) Delete ¶
Delete runes from the caret position. The sign of the argument specifies the direction to delete: positive is forward, negative is backward.
If there is a selection, it is deleted and counts as a single grapheme cluster.
func (*Editor) Layout ¶
func (e *Editor) Layout(gtx layout.Context, lt *text.Shaper, font font.Font, size unit.Sp, textMaterial, selectMaterial op.CallOp) layout.Dimensions
Layout lays out the editor using the provided textMaterial as the paint material for the text glyphs+caret and the selectMaterial as the paint material for the selection rectangle.
func (*Editor) MoveCaret ¶
MoveCaret moves the caret (aka selection start) and the selection end relative to their current positions. Positive distances moves forward, negative distances moves backward. Distances are in grapheme clusters, which closely match what users perceive as "characters" even when the characters are multiple code points long.
func (*Editor) SelectedText ¶
SelectedText returns the currently selected text (if any) from the editor.
func (*Editor) Selection ¶
Selection returns the start and end of the selection, as rune offsets. start can be > end.
func (*Editor) SelectionLen ¶
SelectionLen returns the length of the selection, in runes; it is equivalent to utf8.RuneCountInString(e.SelectedText()).
func (*Editor) SetCaret ¶
SetCaret moves the caret to start, and sets the selection end to end. start and end are in runes, and represent offsets into the editor text.
func (*Editor) Update ¶
func (e *Editor) Update(gtx layout.Context) (EditorEvent, bool)
Update the state of the editor in response to input events. Update consumes editor input events until there are no remaining events or an editor event is generated. To fully update the state of the editor, callers should call Update until it returns false.
type EditorEvent ¶
type EditorEvent interface {
// contains filtered or unexported methods
}
type Enum ¶
type Enum struct { Value string // contains filtered or unexported fields }
type Fit ¶
type Fit uint8
Fit scales a widget to fit and clip to the constraints.
const ( // Unscaled does not alter the scale of a widget. Unscaled Fit = iota // Contain scales widget as large as possible without cropping // and it preserves aspect-ratio. Contain // Cover scales the widget to cover the constraint area and // preserves aspect-ratio. Cover // ScaleDown scales the widget smaller without cropping, // when it exceeds the constraint area. // It preserves aspect-ratio. ScaleDown // Fill stretches the widget to the constraints and does not // preserve aspect-ratio. Fill )
type Float ¶
type Float struct { // Value is the value of the Float, in the [0; 1] range. Value float32 // contains filtered or unexported fields }
Float is for selecting a value in a range.
type Icon ¶
type Icon struct {
// contains filtered or unexported fields
}
type Image ¶
type Image struct { // Src is the image to display. Src paint.ImageOp // Fit specifies how to scale the image to the constraints. // By default it does not do any scaling. Fit Fit // Position specifies where to position the image within // the constraints. Position layout.Direction // Scale is the factor used for converting image pixels to dp. // If Scale is zero it defaults to 1. // // To map one image pixel to one output pixel, set Scale to 1.0 / gtx.Metric.PxPerDp. Scale float32 }
Image is a widget that displays an image.
type Label ¶
type Label struct { // Alignment specifies the text alignment. Alignment text.Alignment // MaxLines limits the number of lines. Zero means no limit. MaxLines int // Truncator is the text that will be shown at the end of the final // line if MaxLines is exceeded. Defaults to "…" if empty. Truncator string // WrapPolicy configures how displayed text will be broken into lines. WrapPolicy text.WrapPolicy // LineHeight controls the distance between the baselines of lines of text. // If zero, a sensible default will be used. LineHeight unit.Sp // LineHeightScale applies a scaling factor to the LineHeight. If zero, a // sensible default will be used. LineHeightScale float32 }
Label is a widget for laying out and drawing text. Labels are always non-interactive text. They cannot be selected or copied.
func (Label) Layout ¶
func (l Label) Layout(gtx layout.Context, lt *text.Shaper, font font.Font, size unit.Sp, txt string, textMaterial op.CallOp) layout.Dimensions
Layout the label with the given shaper, font, size, text, and material.
func (Label) LayoutDetailed ¶
func (l Label) LayoutDetailed(gtx layout.Context, lt *text.Shaper, font font.Font, size unit.Sp, txt string, textMaterial op.CallOp) (layout.Dimensions, TextInfo)
Layout the label with the given shaper, font, size, text, and material, returning metadata about the shaped text.
type Press ¶
type Press struct { // Position of the press. Position image.Point // Start is when the press began. Start time.Time // End is when the press was ended by a release or cancel. // A zero End means it hasn't ended yet. End time.Time // Cancelled is true for cancelled presses. Cancelled bool }
Press represents a past pointer press.
type Region ¶
type Region struct { // Bounds is the coordinates of the bounding box relative to the containing // widget. Bounds image.Rectangle // Baseline is the quantity of vertical pixels between the baseline and // the bottom of bounds. Baseline int }
Region describes the position and baseline of an area of interest within shaped text.
type Scrollbar ¶
type Scrollbar struct {
// contains filtered or unexported fields
}
Scrollbar holds the persistent state for an area that can display a scrollbar. In particular, it tracks the position of a viewport along a one-dimensional region of content. The viewport's position can be adjusted by drag operations along the display area, or by clicks within the display area.
Scrollbar additionally detects when a scroll indicator region is hovered.
func (*Scrollbar) AddDrag ¶
AddDrag configures the drag listener for the scrollbar to use the current clip area.
func (*Scrollbar) AddIndicator ¶
AddIndicator configures the indicator click listener for the scrollbar to use the current clip area.
func (*Scrollbar) AddTrack ¶
AddTrack configures the track click listener for the scrollbar to use the current clip area.
func (*Scrollbar) Dragging ¶
Dragging reports whether the user is currently performing a drag gesture on the indicator. Note that this can return false while ScrollDistance is nonzero if the user scrolls using a different control than the scrollbar (like a mouse wheel).
func (*Scrollbar) IndicatorHovered ¶
IndicatorHovered reports whether the scroll indicator is currently being hovered by the pointer.
func (*Scrollbar) ScrollDistance ¶
ScrollDistance returns the normalized distance that the scrollbar moved during the last call to Layout as a value in the range [-1,1].
func (*Scrollbar) TrackHovered ¶
TrackHovered reports whether the scroll track is being hovered by the pointer.
func (*Scrollbar) Update ¶
func (s *Scrollbar) Update(gtx layout.Context, axis layout.Axis, viewportStart, viewportEnd float32)
Update updates the internal state of the scrollbar based on events since the previous call to Update. The provided axis will be used to normalize input event coordinates and constraints into an axis- independent format. viewportStart is the position of the beginning of the scrollable viewport relative to the underlying content expressed as a value in the range [0,1]. viewportEnd is the position of the end of the viewport relative to the underlying content, also expressed as a value in the range [0,1]. For example, if viewportStart is 0.25 and viewportEnd is .5, the viewport described by the scrollbar is currently showing the second quarter of the underlying content.
type SelectEvent ¶
type SelectEvent struct{}
A SelectEvent is generated when the user selects some text, or changes the selection (e.g. with a shift-click), including if they remove the selection. The selected text is not part of the event, on the theory that it could be a relatively expensive operation (for a large editor), most applications won't actually care about it, and those that do can call Editor.SelectedText() (which can be empty).
type Selectable ¶
type Selectable struct { // Alignment controls the alignment of the text. Alignment text.Alignment // MaxLines is the maximum number of lines of text to be displayed. MaxLines int // Truncator is the symbol to use at the end of the final line of text // if text was cut off. Defaults to "…" if left empty. Truncator string // WrapPolicy configures how displayed text will be broken into lines. WrapPolicy text.WrapPolicy // LineHeight controls the distance between the baselines of lines of text. // If zero, a sensible default will be used. LineHeight unit.Sp // LineHeightScale applies a scaling factor to the LineHeight. If zero, a // sensible default will be used. LineHeightScale float32 // contains filtered or unexported fields }
Selectable displays selectable text.
func (*Selectable) ClearSelection ¶
func (l *Selectable) ClearSelection()
ClearSelection clears the selection, by setting the selection end equal to the selection start.
func (*Selectable) Focused ¶
func (l *Selectable) Focused() bool
Focused returns whether the label is focused or not.
func (*Selectable) Layout ¶
func (l *Selectable) Layout(gtx layout.Context, lt *text.Shaper, font font.Font, size unit.Sp, textMaterial, selectionMaterial op.CallOp) layout.Dimensions
Layout clips to the dimensions of the selectable, updates the shaped text, configures input handling, and paints the text and selection rectangles. The provided textMaterial and selectionMaterial ops are used to set the paint material for the text and selection rectangles, respectively.
func (*Selectable) Regions ¶
func (l *Selectable) Regions(start, end int, regions []Region) []Region
Regions returns visible regions covering the rune range [start,end).
func (*Selectable) SelectedText ¶
func (l *Selectable) SelectedText() string
SelectedText returns the currently selected text (if any) from the editor.
func (*Selectable) Selection ¶
func (l *Selectable) Selection() (start, end int)
Selection returns the start and end of the selection, as rune offsets. start can be > end.
func (*Selectable) SelectionLen ¶
func (l *Selectable) SelectionLen() int
SelectionLen returns the length of the selection, in runes; it is equivalent to utf8.RuneCountInString(e.SelectedText()).
func (*Selectable) SetCaret ¶
func (l *Selectable) SetCaret(start, end int)
SetCaret moves the caret to start, and sets the selection end to end. start and end are in runes, and represent offsets into the editor text.
func (*Selectable) SetText ¶
func (l *Selectable) SetText(s string)
SetText updates the text to s if it does not already contain s. Updating the text will clear the selection unless the selectable already contains s.
func (*Selectable) Text ¶
func (l *Selectable) Text() string
Text returns the contents of the label.
func (*Selectable) Truncated ¶
func (l *Selectable) Truncated() bool
Truncated returns whether the text has been truncated by the text shaper to fit within available constraints.
type SubmitEvent ¶
type SubmitEvent struct {
Text string
}
A SubmitEvent is generated when Submit is set and a carriage return key is pressed.
Notes ¶
Bugs ¶
this method's definition of a "word" is currently whitespace-delimited. Languages that do not use whitespace to delimit words will experience counter-intuitive behavior when navigating by word.