diff --git a/app/doc.go b/app/doc.go index 339c1dd2..abfba20c 100644 --- a/app/doc.go +++ b/app/doc.go @@ -6,7 +6,7 @@ functionality for running graphical user interfaces. See https://gioui.org for instructions to set up and run Gio programs. -Windows +# 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 @@ -34,7 +34,7 @@ For example: A program must keep receiving events from the event channel until DestroyEvent is received. -Main +# 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. @@ -56,14 +56,13 @@ For example, to display a blank but otherwise functional window: app.Main() } - -Event queue +# Event queue A FrameEvent's Queue method returns an event.Queue implementation that distributes incoming events to the event handlers declared in the last frame. See the gioui.org/io/event package for more information about event handlers. -Permissions +# 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 diff --git a/app/os_x11.go b/app/os_x11.go index a6ba0ee8..6b6438f4 100644 --- a/app/os_x11.go +++ b/app/os_x11.go @@ -490,7 +490,6 @@ func (w *x11Window) destroy() { // atom is a wrapper around XInternAtom. Callers should cache the result // in order to limit round-trips to the X server. -// func (w *x11Window) atom(name string, onlyIfExists bool) C.Atom { cname := C.CString(name) defer C.free(unsafe.Pointer(cname)) @@ -504,7 +503,6 @@ func (w *x11Window) atom(name string, onlyIfExists bool) C.Atom { // x11EventHandler wraps static variables for the main event loop. // Its sole purpose is to prevent heap allocation and reduce clutter // in x11window.loop. -// type x11EventHandler struct { w *x11Window text []byte @@ -512,7 +510,6 @@ type x11EventHandler struct { } // handleEvents returns true if the window needs to be redrawn. -// func (h *x11EventHandler) handleEvents() bool { w := h.w xev := h.xev diff --git a/app/permission/bluetooth/main.go b/app/permission/bluetooth/main.go index 5ef16d5f..0997a330 100644 --- a/app/permission/bluetooth/main.go +++ b/app/permission/bluetooth/main.go @@ -4,15 +4,15 @@ Package bluetooth implements permissions to access Bluetooth and Bluetooth Low Energy hardware, including the ability to discover and pair devices. -Android +# Android The following entries will be added to AndroidManifest.xml: - - - - - + + + + + Note that ACCESS_FINE_LOCATION is required on Android before the Bluetooth device may be used. diff --git a/app/permission/camera/main.go b/app/permission/camera/main.go index bbb78fa6..87f294cc 100644 --- a/app/permission/camera/main.go +++ b/app/permission/camera/main.go @@ -3,12 +3,12 @@ /* Package camera implements permissions to access camera hardware. -Android +# Android The following entries will be added to AndroidManifest.xml: - - + + CAMERA is a "dangerous" permission. See documentation for package gioui.org/app/permission for more information. diff --git a/app/permission/doc.go b/app/permission/doc.go index 08ca9df7..952d1893 100644 --- a/app/permission/doc.go +++ b/app/permission/doc.go @@ -34,7 +34,7 @@ program's source code: _ "net" ) -Android -- Dangerous Permissions +# Android -- Dangerous Permissions Certain permissions on Android are marked with a protection level of "dangerous". This means that, in addition to including the relevant diff --git a/app/permission/networkstate/main.go b/app/permission/networkstate/main.go index c5942199..b32559e2 100644 --- a/app/permission/networkstate/main.go +++ b/app/permission/networkstate/main.go @@ -3,11 +3,10 @@ /* Package networkstate implements permissions to access network connectivity information. -Android +# Android The following entries will be added to AndroidManifest.xml: - - + */ package networkstate diff --git a/app/permission/storage/main.go b/app/permission/storage/main.go index ec7f6306..87a9e3ed 100644 --- a/app/permission/storage/main.go +++ b/app/permission/storage/main.go @@ -4,12 +4,12 @@ Package storage implements read and write storage permissions on mobile devices. -Android +# Android The following entries will be added to AndroidManifest.xml: - - + + READ_EXTERNAL_STORAGE and WRITE_EXTERNAL_STORAGE are "dangerous" permissions. See documentation for package gioui.org/app/permission for more information. diff --git a/app/permission/wakelock/wakelock.go b/app/permission/wakelock/wakelock.go index d8611f23..26ee7fbb 100644 --- a/app/permission/wakelock/wakelock.go +++ b/app/permission/wakelock/wakelock.go @@ -4,11 +4,10 @@ Package wakelock implements permission to acquire locks that keep the system from suspending. -Android +# Android The following entries will be added to AndroidManifest.xml: - - + */ package wakelock diff --git a/font/opentype/internal/shaping.go b/font/opentype/internal/shaping.go index 7abff196..66571d3a 100644 --- a/font/opentype/internal/shaping.go +++ b/font/opentype/internal/shaping.go @@ -263,14 +263,14 @@ func paragraph(shaper Shaper, face font.Face, ppem fixed.Int26_6, maxWidth int, // whenever it returns false. // // The parameters require some explanation: -// out - the shaping.Output that is being line-broken. -// runeToGlyph - a mapping where accessing the slice at the index of a rune -// int out will yield the index of the first glyph corresponding to that rune. -// lineStartRune - the index of the first rune in the line. -// b - the line break candidate under consideration. -// curLineWidth - the amount of space total in the current line. -// curLineUsed - the amount of space in the current line that is already used. -// nextLineWidth - the amount of space available on the next line. +// - out - the shaping.Output that is being line-broken. +// - runeToGlyph - a mapping where accessing the slice at the index of a rune +// into out will yield the index of the first glyph corresponding to that rune. +// - lineStartRune - the index of the first rune in the line. +// - b - the line break candidate under consideration. +// - curLineWidth - the amount of space total in the current line. +// - curLineUsed - the amount of space in the current line that is already used. +// - nextLineWidth - the amount of space available on the next line. // // This function returns both a valid shaping.Output broken at b and a boolean // indicating whether the returned output should be used. diff --git a/font/opentype/internal/shaping_test.go b/font/opentype/internal/shaping_test.go index f3eaa259..ecbd89e0 100644 --- a/font/opentype/internal/shaping_test.go +++ b/font/opentype/internal/shaping_test.go @@ -524,7 +524,7 @@ var ( } ) -//splitShapedAt splits a single shaped output into multiple. It splits +// splitShapedAt splits a single shaped output into multiple. It splits // on each provided glyph index in indices, with the index being the end of // a slice range (so it's exclusive). You can think of the index as the // first glyph of the next output. @@ -925,25 +925,25 @@ At risus viverra adipiscing at.` } // simpleGlyph returns a simple square glyph with the provided cluster -//value. +// value. func simpleGlyph(cluster int) shaping.Glyph { return complexGlyph(cluster, 1, 1) } // ligatureGlyph returns a simple square glyph with the provided cluster -//value and number of runes. +// value and number of runes. func ligatureGlyph(cluster, runes int) shaping.Glyph { return complexGlyph(cluster, runes, 1) } // expansionGlyph returns a simple square glyph with the provided cluster -//value and number of glyphs. +// value and number of glyphs. func expansionGlyph(cluster, glyphs int) shaping.Glyph { return complexGlyph(cluster, 1, glyphs) } // complexGlyph returns a simple square glyph with the provided cluster -//value, number of associated runes, and number of glyphs in the cluster. +// value, number of associated runes, and number of glyphs in the cluster. func complexGlyph(cluster, runes, glyphs int) shaping.Glyph { return shaping.Glyph{ Width: fixed.I(10), diff --git a/gpu/internal/rendertest/util_test.go b/gpu/internal/rendertest/util_test.go index 3725301e..f228321e 100644 --- a/gpu/internal/rendertest/util_test.go +++ b/gpu/internal/rendertest/util_test.go @@ -217,9 +217,9 @@ func alphaClose(c1, c2 color.RGBA) bool { // yiqEqApprox compares the colors of 2 pixels, in the NTSC YIQ color space, // as described in: // -// Measuring perceived color difference using YIQ NTSC -// transmission color space in mobile applications. -// Yuriy Kotsarenko, Fernando Ramos. +// Measuring perceived color difference using YIQ NTSC +// transmission color space in mobile applications. +// Yuriy Kotsarenko, Fernando Ramos. // // An electronic version is available at: // diff --git a/internal/stroke/stroke.go b/internal/stroke/stroke.go index 20fd5914..4e1ecd0f 100644 --- a/internal/stroke/stroke.go +++ b/internal/stroke/stroke.go @@ -376,7 +376,8 @@ func strokePathCurv(beg, ctl, end f32.Point, t float32) float32 { } // quadBezierSample returns the point on the Bézier curve at t. -// B(t) = (1-t)^2 P0 + 2(1-t)t P1 + t^2 P2 +// +// B(t) = (1-t)^2 P0 + 2(1-t)t P1 + t^2 P2 func quadBezierSample(p0, p1, p2 f32.Point, t float32) f32.Point { t1 := 1 - t c0 := t1 * t1 @@ -390,7 +391,8 @@ func quadBezierSample(p0, p1, p2 f32.Point, t float32) f32.Point { } // quadBezierD1 returns the first derivative of the Bézier curve with respect to t. -// B'(t) = 2(1-t)(P1 - P0) + 2t(P2 - P1) +// +// B'(t) = 2(1-t)(P1 - P0) + 2t(P2 - P1) func quadBezierD1(p0, p1, p2 f32.Point, t float32) f32.Point { p10 := p1.Sub(p0).Mul(2 * (1 - t)) p21 := p2.Sub(p1).Mul(2 * t) @@ -399,7 +401,8 @@ func quadBezierD1(p0, p1, p2 f32.Point, t float32) f32.Point { } // quadBezierD2 returns the second derivative of the Bézier curve with respect to t: -// B''(t) = 2(P2 - 2P1 + P0) +// +// B''(t) = 2(P2 - 2P1 + P0) func quadBezierD2(p0, p1, p2 f32.Point, t float32) f32.Point { p := p2.Sub(p1.Mul(2)).Add(p0) return p.Mul(2) @@ -534,10 +537,13 @@ func strokePathRoundCap(qs *StrokeQuads, hw float32, pivot, n0 f32.Point) { // curve approximations for an arc. // // The math is extracted from the following paper: -// "Drawing an elliptical arc using polylines, quadratic or -// cubic Bezier curves", L. Maisonobe +// +// "Drawing an elliptical arc using polylines, quadratic or +// cubic Bezier curves", L. Maisonobe +// // An electronic version may be found at: -// http://spaceroots.org/documents/ellipse/elliptical-arc.pdf +// +// http://spaceroots.org/documents/ellipse/elliptical-arc.pdf func ArcTransform(p, f1, f2 f32.Point, angle float32) (transform f32.Affine2D, segments int) { const segmentsPerCircle = 16 const anglePerSegment = 2 * math.Pi / segmentsPerCircle diff --git a/io/event/event.go b/io/event/event.go index 502275e2..7a6751f5 100644 --- a/io/event/event.go +++ b/io/event/event.go @@ -26,7 +26,6 @@ The following example declares a handler ready for key input: ops := new(op.Ops) var h *Handler = ... key.InputOp{Tag: h, Filter: ...}.Add(ops) - */ package event diff --git a/io/pointer/doc.go b/io/pointer/doc.go index 2f521c29..c4b50297 100644 --- a/io/pointer/doc.go +++ b/io/pointer/doc.go @@ -8,7 +8,7 @@ object such as a finger. The InputOp operation is used to declare a handler ready for pointer events. Use an event.Queue to receive events. -Types +# Types Only events that match a specified list of types are delivered to a handler. @@ -25,7 +25,7 @@ Leave, or Scroll): Cancel events are always delivered. -Hit areas +# Hit areas Clip operations from package op/clip are used for specifying hit areas where subsequent InputOps are active. @@ -43,7 +43,7 @@ of multiple area operations is the intersection of the areas. BUG: Clip operations other than clip.Rect and clip.Ellipse are approximated with their bounding boxes. -Matching events +# Matching events Areas form an implicit tree, with input handlers as leaves. The children of an area is every area and handler added between its Push and corresponding Pop. @@ -77,7 +77,7 @@ the matching repeats with the parent area. In the example above, all events will go to h2 because it and h1 are siblings and none are pass-through. -Pass-through +# Pass-through The PassOp operations controls the pass-through setting. All handlers added inside one or more PassOp scopes are marked pass-through. @@ -87,7 +87,7 @@ the user touches the side, both the (transparent) drawer handle and the interface below should receive pointer events. This effect is achieved by marking the drawer handle pass-through. -Disambiguation +# Disambiguation When more than one handler matches a pointer event, the event queue follows a set of rules for distributing the event. @@ -110,7 +110,7 @@ The losing handlers are notified by a Cancel event. For multiple grabbing handlers, the foremost handler wins. -Priorities +# Priorities Handlers know their position in a matching set of a pointer through event priorities. The Shared priority is for matching sets with diff --git a/io/transfer/transfer.go b/io/transfer/transfer.go index 85ab68c3..78e2b900 100644 --- a/io/transfer/transfer.go +++ b/io/transfer/transfer.go @@ -2,11 +2,11 @@ // // The transfer protocol is as follows: // -// - Data sources are registered with SourceOps, data targets with TargetOps. -// - A data source receives a RequestEvent when a transfer is initiated. -// It must respond with an OfferOp. -// - The target receives a DataEvent when transferring to it. It must close -// the event data after use. +// - Data sources are registered with SourceOps, data targets with TargetOps. +// - A data source receives a RequestEvent when a transfer is initiated. +// It must respond with an OfferOp. +// - The target receives a DataEvent when transferring to it. It must close +// the event data after use. // // When a user initiates a pointer-guided drag and drop transfer, the // source as well as all potential targets receive an InitiateEvent. diff --git a/layout/context.go b/layout/context.go index 3a1dbc22..46ea337f 100644 --- a/layout/context.go +++ b/layout/context.go @@ -37,13 +37,13 @@ type Context struct { // NewContext is a shorthand for // -// Context{ -// Ops: ops, -// Now: e.Now, -// Queue: e.Queue, -// Config: e.Config, -// Constraints: Exact(e.Size), -// } +// Context{ +// Ops: ops, +// Now: e.Now, +// Queue: e.Queue, +// Config: e.Config, +// Constraints: Exact(e.Size), +// } // // NewContext calls ops.Reset and adjusts ops for e.Insets. func NewContext(ops *op.Ops, e system.FrameEvent) Context { diff --git a/layout/doc.go b/layout/doc.go index 1eb7f1cb..45d5f393 100644 --- a/layout/doc.go +++ b/layout/doc.go @@ -3,7 +3,7 @@ /* Package layout implements layouts common to GUI programs. -Constraints and dimensions +# Constraints and dimensions Constraints and dimensions form the interface between layouts and interface child elements. This package operates on Widgets, functions @@ -45,6 +45,5 @@ This example both aligns and insets a child: More complex layouts such as Stack and Flex lay out multiple children, and stateful layouts such as List accept user input. - */ package layout diff --git a/op/op.go b/op/op.go index 2a231824..07947c59 100644 --- a/op/op.go +++ b/op/op.go @@ -1,7 +1,6 @@ // SPDX-License-Identifier: Unlicense OR MIT /* - Package op implements operations for updating a user interface. Gio programs use operations, or ops, for describing their user @@ -28,7 +27,7 @@ Drawing a colored square: paint.PaintOp{Rect: ...}.Add(ops) e.Frame(ops) -State +# State An Ops list can be viewed as a very simple virtual machine: it has state such as transformation and color and execution flow can be controlled with macros. @@ -61,7 +60,6 @@ The MacroOp records a list of operations to be executed later: // replay the recorded operations: call.Add(ops) - */ package op diff --git a/unit/unit.go b/unit/unit.go index b9ba62ce..58a43903 100644 --- a/unit/unit.go +++ b/unit/unit.go @@ -1,7 +1,6 @@ // SPDX-License-Identifier: Unlicense OR MIT /* - Package unit implements device independent units. Device independent pixel, or dp, is the unit for sizes independent of @@ -16,7 +15,6 @@ size vary between platforms and displays. To maintain a constant visual size across platforms and displays, always use dps or sps to define user interfaces. Only use pixels for derived values. - */ package unit diff --git a/widget/material/doc.go b/widget/material/doc.go index 715f5a07..4d2413d3 100644 --- a/widget/material/doc.go +++ b/widget/material/doc.go @@ -11,20 +11,20 @@ // // This snippet defines a button that prints a message when clicked: // -// var gtx layout.Context -// button := new(widget.Clickable) +// var gtx layout.Context +// button := new(widget.Clickable) // -// for button.Clicked(gtx) { -// fmt.Println("Clicked!") -// } +// for button.Clicked(gtx) { +// fmt.Println("Clicked!") +// } // // Use a Theme to draw the button: // -// theme := material.NewTheme(...) +// theme := material.NewTheme(...) // -// material.Button(theme, "Click me!").Layout(gtx, button) +// material.Button(theme, "Click me!").Layout(gtx, button) // -// Customization +// # Customization // // Quite often, a program needs to customize the theme-provided defaults. Several // options are available, depending on the nature of the change. @@ -36,22 +36,22 @@ // Theme-global parameters: For changing the look of all widgets drawn with a // particular theme, adjust the `Theme` fields: // -// theme.Color.Primary = color.NRGBA{...} +// theme.Color.Primary = color.NRGBA{...} // // Widget-local parameters: For changing the look of a particular widget, // adjust the widget specific theme object: // -// btn := material.Button(theme, "Click me!") -// btn.Font.Style = text.Italic -// btn.Layout(gtx, button) +// btn := material.Button(theme, "Click me!") +// btn.Font.Style = text.Italic +// btn.Layout(gtx, button) // // Widget variants: A widget can have several distinct representations even // though the underlying state is the same. A widget.Clickable can be drawn as a // round icon button: // -// icon := material.NewIcon(...) +// icon := material.NewIcon(...) // -// material.IconButton(theme, icon).Layout(gtx, button) +// material.IconButton(theme, icon).Layout(gtx, button) // // Specialized widgets: Theme both define a generic Label method // that takes a text size, and specialized methods for standard text