gioui.org/ui@v0.0.0-20190926171558-ce74bc0cbaea/doc.go (about)

     1  // SPDX-License-Identifier: Unlicense OR MIT
     2  
     3  /*
     4  Package ui defines operations buffers, units and common operations
     5  for GUI programs written with the Gio module.
     6  
     7  See https://gioui.org for instructions to setup and run Gio programs.
     8  
     9  Operations
    10  
    11  Gio programs use operations, or ops, for describing their user
    12  interfaces. There are operations for drawing, defining input
    13  handlers, changing window properties as well as operations for
    14  controlling the execution of other operations.
    15  
    16  Ops represents a list of operations. The most important use
    17  for an Ops list is to describe a complete user interface update
    18  to a ui/app.Window's Update method.
    19  
    20  Drawing a colored square:
    21  
    22  	import "gioui.org/ui"
    23  	import "gioui.org/ui/app"
    24  	import "gioui.org/ui/paint"
    25  
    26  	var w app.Window
    27  	ops := new(ui.Ops)
    28  	...
    29  	ops.Reset()
    30  	paint.ColorOp{Color: ...}.Add(ops)
    31  	paint.PaintOp{Rect: ...}.Add(ops)
    32  	w.Update(ops)
    33  
    34  State
    35  
    36  An Ops list can be viewed as a very simple virtual machine: it has an implicit
    37  mutable state stack and execution flow can be controlled with macros.
    38  
    39  The StackOp saves the current state to the state stack and restores it later:
    40  
    41  	ops := new(ui.Ops)
    42  	var stack ui.StackOp
    43  	// Save the current state, in particular the transform.
    44  	stack.Push(ops)
    45  	// Apply a transform to subsequent operations.
    46  	ui.TransformOp{}.Offset(...).Add(ops)
    47  	...
    48  	// Restore the previous transform.
    49  	stack.Pop()
    50  
    51  The MacroOp records a list of operations to be executed later:
    52  
    53  	ops := new(ui.Ops)
    54  	var macro ui.MacroOp
    55  	macro.Record()
    56  	// Record operations by adding them.
    57  	ui.InvalidateOp{}.Add(ops)
    58  	...
    59  	macro.Stop()
    60  	...
    61  	// Execute the recorded operations.
    62  	macro.Add(ops)
    63  
    64  Note that operations added between Record and Stop are not executed until
    65  the macro is Added.
    66  
    67  Units
    68  
    69  A Value is a value with a Unit attached.
    70  
    71  Device independent pixel, or dp, is the unit for sizes independent of
    72  the underlying display device.
    73  
    74  Scaled pixels, or sp, is the unit for text sizes. An sp is like dp with
    75  text scaling applied.
    76  
    77  Finally, pixels, or px, is the unit for display dependent pixels. Their
    78  size vary between platforms and displays.
    79  
    80  To maintain a constant visual size across platforms and displays, always
    81  use dps or sps to define user interfaces. Only use pixels for derived
    82  values.
    83  
    84  Events
    85  
    86  The Queue interface is the protocol for receiving external events.
    87  
    88  For example:
    89  
    90  	var queue ui.Queue = ...
    91  
    92  	for _, e := range queue.Events(h) {
    93  		switch e.(type) {
    94  			...
    95  		}
    96  	}
    97  
    98  In general, handlers must be declared before events become
    99  available. Other packages such as pointer and key provide
   100  the means for declaring handlers for specific event types.
   101  
   102  The following example declares a handler ready for key input:
   103  
   104  	import gioui.org/ui/key
   105  
   106  	ops := new(ui.Ops)
   107  	var h *Handler = ...
   108  	key.InputOp{Key: h}.Add(ops)
   109  
   110  */
   111  package ui