github.com/cybriq/giocore@v0.0.7-0.20210703034601-cfb9cb5f3900/io/system/system.go (about)

     1  // SPDX-License-Identifier: Unlicense OR MIT
     2  
     3  // Package system contains events usually handled at the top-level
     4  // program level.
     5  package system
     6  
     7  import (
     8  	"image"
     9  	"time"
    10  
    11  	"github.com/cybriq/giocore/io/event"
    12  	"github.com/cybriq/giocore/op"
    13  	"github.com/cybriq/giocore/unit"
    14  )
    15  
    16  // A FrameEvent requests a new frame in the form of a list of
    17  // operations that describes what to display and how to handle
    18  // input.
    19  type FrameEvent struct {
    20  	// Now is the current animation. Use Now instead of time.Now to
    21  	// synchronize animation and to avoid the time.Now call overhead.
    22  	Now time.Time
    23  	// Metric converts device independent dp and sp to device pixels.
    24  	Metric unit.Metric
    25  	// Size is the dimensions of the window.
    26  	Size image.Point
    27  	// Insets is the insets to apply.
    28  	Insets Insets
    29  	// Frame is the callback to supply the list of
    30  	// operations to complete the FrameEvent.
    31  	//
    32  	// Note that the operation list and the operations themselves
    33  	// may not be mutated until another FrameEvent is received from
    34  	// the same event source.
    35  	// That means that calls to frame.Reset and changes to referenced
    36  	// data such as ImageOp backing images should happen between
    37  	// receiving a FrameEvent and calling Frame.
    38  	//
    39  	// Example:
    40  	//
    41  	//  var w *app.Window
    42  	//  var frame *op.Ops
    43  	//  for e := range w.Events() {
    44  	//      if e, ok := e.(system.FrameEvent); ok {
    45  	//          // Call frame.Reset and manipulate images for ImageOps
    46  	//          // here.
    47  	//          e.Frame(frame)
    48  	//      }
    49  	//  }
    50  	Frame func(frame *op.Ops)
    51  	// Queue supplies the events for event handlers.
    52  	Queue event.Queue
    53  }
    54  
    55  // DestroyEvent is the last event sent through
    56  // a window event channel.
    57  type DestroyEvent struct {
    58  	// Err is nil for normal window closures. If a
    59  	// window is prematurely closed, Err is the cause.
    60  	Err error
    61  }
    62  
    63  // Insets is the space taken up by
    64  // system decoration such as translucent
    65  // system bars and software keyboards.
    66  type Insets struct {
    67  	Top, Bottom, Left, Right unit.Value
    68  }
    69  
    70  // A StageEvent is generated whenever the stage of a
    71  // Window changes.
    72  type StageEvent struct {
    73  	Stage Stage
    74  }
    75  
    76  // CommandEvent is a system event. Unlike most other events, CommandEvent is
    77  // delivered as a pointer to allow Cancel to suppress it.
    78  type CommandEvent struct {
    79  	Type CommandType
    80  	// Cancel suppress the default action of the command.
    81  	Cancel bool
    82  }
    83  
    84  // Stage of a Window.
    85  type Stage uint8
    86  
    87  // CommandType is the type of a CommandEvent.
    88  type CommandType uint8
    89  
    90  const (
    91  	// StagePaused is the Stage for inactive Windows.
    92  	// Inactive Windows don't receive FrameEvents.
    93  	StagePaused Stage = iota
    94  	// StateRunning is for active Windows.
    95  	StageRunning
    96  )
    97  
    98  const (
    99  	// CommandBack is the command for a back action
   100  	// such as the Android back button.
   101  	CommandBack CommandType = iota
   102  )
   103  
   104  func (l Stage) String() string {
   105  	switch l {
   106  	case StagePaused:
   107  		return "StagePaused"
   108  	case StageRunning:
   109  		return "StageRunning"
   110  	default:
   111  		panic("unexpected Stage value")
   112  	}
   113  }
   114  
   115  func (FrameEvent) ImplementsEvent()    {}
   116  func (StageEvent) ImplementsEvent()    {}
   117  func (*CommandEvent) ImplementsEvent() {}
   118  func (DestroyEvent) ImplementsEvent()  {}