README

import "aqwari.net/exp/display"

This is a small library that focuses on getting an OpenGL-enabled
window and receiving input. The API is still unstable and evolving.
The library has a few goals:

  · go-gettable: only use libraries installed by default
  · focused: only events and window creation. use whatever GL lib you like
  · idiomatic: Events received on a channel, no callbacks
Expand ▾ Collapse ▴

Documentation

Overview

    Package display provides functions for creating OpenGL windows and receiving input events.

    The display package is cross-platform, and should work on Linux and OSX.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type Buffer

    type Buffer struct {
    	Event <-chan Event
    	// contains filtered or unexported fields
    }

      A Buffer is an OpenGL canvas displayed within an OS window. Events can be received on the Buffer's Event channel.

      func Open

      func Open(c Config) (*Buffer, error)

        Open creates a new Buffer on the screen.

        func (*Buffer) CheckEvent

        func (w *Buffer) CheckEvent() error

          CheckEvents checks the event system for new input without blocking. A Buffer's Event channel will not be populated with new Events unless CheckEvent or WaitEvent is called.

          func (*Buffer) Close

          func (w *Buffer) Close()

            Close() closes a window and releases any resources associated with it.

            func (*Buffer) Flip

            func (w *Buffer) Flip()

              Flip swaps the background buffer with the foregroud buffer. All drawing is done to the background buffer.

              func (*Buffer) Resize

              func (w *Buffer) Resize(width, height int) error

                Resize changes the width and height of a window to the specified dimensions in pixels. Note that height and width are only suggestions; especially in fullscreen mode, window system or hardware restrictions may prevent the desired height and width from being set. The actual screen size may be retrieved with the Size() method.

                func (*Buffer) SetTitle

                func (w *Buffer) SetTitle(title string)

                  SetTitle changes a window's title string to a new value. The maximum length of a window title is an unspecified value over 255 characters.

                  func (*Buffer) Size

                  func (w *Buffer) Size() (width, height int)

                    Size returns the window's width and height in pixels

                    func (*Buffer) Title

                    func (w *Buffer) Title() string

                      Title retrieves the current title of a window

                      func (*Buffer) WaitEvent

                      func (w *Buffer) WaitEvent() error

                        WaitEvent blocks until a new Event occurs. New Events will be available on the Buffer's Event channel.

                        type Button

                        type Button int

                          A Button is a bitwise OR mask of all pressed mouse buttons. This format makes it easy to compare mouse state between sequential events with bitwise operations:

                          var (
                          	prev = Mouse1 | Mouse2 | Mouse5
                          	next = Mouse2 | Mouse3
                          )
                          pressed := (prev ^ next) & next // => Mouse3
                          released := (prev ^ next) & prev // => Mouse1 | Mouse5
                          holding := prev & next // => Mouse2
                          
                          const (
                          	Mouse1 Button = 1 << iota
                          	Mouse2
                          	Mouse3
                          	Mouse4
                          	Mouse5
                          	Mouse6
                          	Mouse7
                          	Mouse8
                          )

                          func (Button) String

                          func (btn Button) String() string

                          type Config

                          type Config map[string]string

                            A Config is used to choose the settings of a window display. Different systems may support different configurations. Most configuration settings should be considered hints rather than requirements. The implementation will make the best effort to provide a window matching the specifications. Keys common to all implementations are:

                            	Title:          A window's initial title
                            	Geometry:       A window's size and position (WxH@x,y)
                             OpenGL Version: An OpenGL version string ("3.2")
                            

                            type Cursor

                            type Cursor struct {
                            	X, Y int
                            	When time.Time
                            }

                              A Cursor event occurs when the cursor position, usually controlled by the mouse, is changed. Cursor events contain the X and Y position of the cursor in pixels, where the origin is the top left corner of the screen.

                              func (Cursor) Src

                              func (Cursor) Src() Device

                              func (Cursor) String

                              func (m Cursor) String() string

                              func (Cursor) Time

                              func (e Cursor) Time() time.Time

                              type Damage

                              type Damage struct {
                              	When time.Time
                              }

                                Damage events occur when the window needs to be redisplayed. This can happen when part of the window is covered by another and the window system does not restore it.

                                func (Damage) Src

                                func (Damage) Src() Device

                                func (Damage) Time

                                func (e Damage) Time() time.Time

                                type Device

                                type Device uint32

                                  All input events must have a globally unique device identifier number, which can be retrieved from an Event throught the Src() method. Note that the underlying window system may not be able to distinguish between individual keyboards or mice. Events from a single device are guaranteed to arrive in chronological order. The window package reserves device ids 0-100 for use by system devices. By convention, the device id 0 is used when the origin device is not important.

                                  type Edit

                                  type Edit struct {
                                  	Text string
                                  	When time.Time
                                  }

                                    An Edit event occurs when a user begins inputting candidate text. This is most notably used when the user is using an input method to input characters that require multiple key presses. The string Text contains the non-commited text the user has typed so far.

                                    func (Edit) Src

                                    func (Edit) Src() Device

                                    func (Edit) String

                                    func (t Edit) String() string

                                    func (Edit) Time

                                    func (e Edit) Time() time.Time

                                    type Event

                                    type Event interface {
                                    	Src() Device
                                    	Time() time.Time
                                    }

                                      All user and system events satisfy the Event interface, which must provide a unique device identifier and an event time.

                                      type Focus

                                      type Focus struct {
                                      	Focused bool
                                      	When    time.Time
                                      }

                                        A Focus event occurs when a window receives or loses focus. In most window systems, a single active window is in focus, and will receive user input.

                                        func (Focus) Src

                                        func (Focus) Src() Device

                                        func (Focus) Time

                                        func (e Focus) Time() time.Time

                                        type Key

                                        type Key int

                                          Keys are named after the character of the key on a standard US keyboard, and may not map to the user's actual keyboard layout.

                                          const (
                                          	KeyUnknown Key = iota
                                          	KeyA
                                          	KeyB
                                          	KeyC
                                          	KeyD
                                          	KeyE
                                          	KeyF
                                          	KeyG
                                          	KeyH
                                          	KeyI
                                          	KeyJ
                                          	KeyK
                                          	KeyL
                                          	KeyM
                                          	KeyN
                                          	KeyO
                                          	KeyP
                                          	KeyQ
                                          	KeyR
                                          	KeyS
                                          	KeyT
                                          	KeyU
                                          	KeyV
                                          	KeyW
                                          	KeyX
                                          	KeyY
                                          	KeyZ
                                          	Key1
                                          	Key2
                                          	Key3
                                          	Key4
                                          	Key5
                                          	Key6
                                          	Key7
                                          	Key8
                                          	Key9
                                          	Key0
                                          	KeyEnter
                                          	KeyEscape
                                          	KeyBackspace
                                          	KeyTab
                                          	KeySpace
                                          	KeyMinus
                                          	KeyEquals
                                          	KeyLeftBracket
                                          	KeyRightBracket
                                          	KeyBackslash
                                          	KeyNonUShash
                                          	KeySemicolon
                                          	KeyApostrophe
                                          	KeyGrave
                                          	KeyComma
                                          	KeyPeriod
                                          	KeySlash
                                          	KeyCapsLock
                                          	KeyF1
                                          	KeyF2
                                          	KeyF3
                                          	KeyF4
                                          	KeyF5
                                          	KeyF6
                                          	KeyF7
                                          	KeyF8
                                          	KeyF9
                                          	KeyF10
                                          	KeyF11
                                          	KeyF12
                                          	KeyPrintScreen
                                          	KeyScrollLock
                                          	KeyPause
                                          	KeyInsert
                                          	KeyHome
                                          	KeyPageUp
                                          	KeyDelete
                                          	KeyEnd
                                          	KeyPageDown
                                          	KeyRight
                                          	KeyLeft
                                          	KeyDown
                                          	KeyUp
                                          	KeyNumLockClear
                                          	KeyPadDivide
                                          	KeyPadMultiply
                                          	KeyPadMinus
                                          	KeyPadPlus
                                          	KeyPadEnter
                                          	KeyPad1
                                          	KeyPad2
                                          	KeyPad3
                                          	KeyPad4
                                          	KeyPad5
                                          	KeyPad6
                                          	KeyPad7
                                          	KeyPad8
                                          	KeyPad9
                                          	KeyPad0
                                          	KeyPadPeriod
                                          	KeyNonUSBackslash
                                          	KeyApplication
                                          	KeyPower
                                          	KeyPadEquals
                                          	KeyF13
                                          	KeyF14
                                          	KeyF15
                                          	KeyF16
                                          	KeyF17
                                          	KeyF18
                                          	KeyF19
                                          	KeyF20
                                          	KeyF21
                                          	KeyF22
                                          	KeyF23
                                          	KeyF24
                                          	KeyExecute
                                          	KeyHelp
                                          	KeyMenu
                                          	KeySelect
                                          	KeyStop
                                          	KeyAgain
                                          	KeyUndo
                                          	KeyCut
                                          	KeyCopy
                                          	KeyPaste
                                          	KeyFind
                                          	KeyMute
                                          	KeyVolumeUp
                                          	KeyVolumeDown
                                          	KeyLockingCapsLock
                                          	KeyLockingNumLock
                                          	KeyLockingScrollLock
                                          	KeyPadComma
                                          	KeyPadEqualsAs400
                                          	KeyInternational1
                                          	KeyInternational2
                                          	KeyInternational3
                                          	KeyInternational4
                                          	KeyInternational5
                                          	KeyInternational6
                                          	KeyInternational7
                                          	KeyInternational8
                                          	KeyInternational9
                                          	KeyLang1
                                          	KeyLang2
                                          	KeyLang3
                                          	KeyLang4
                                          	KeyLang5
                                          	KeyLang6
                                          	KeyLang7
                                          	KeyLang8
                                          	KeyLang9
                                          	KeyAlterase
                                          	KeySysreq
                                          	KeyCancel
                                          	KeyClear
                                          	KeyPrior
                                          	KeyReturn2
                                          	KeySeparator
                                          	KeyOut
                                          	KeyOper
                                          	KeyClearAgain
                                          	KeyCrsel
                                          	KeyExsel
                                          	KeyPad00
                                          	KeyPad000
                                          	KeyThousandsSeparator
                                          	KeyDecimalSeparator
                                          	KeyCurrencyUnit
                                          	KeyCurrencySubUnit
                                          	KeyPadLeftParen
                                          	KeyPadRightParen
                                          	KeyPadLeftBrace
                                          	KeyPadRightBrace
                                          	KeyPadTab
                                          	KeyPadBackspace
                                          	KeyPadA
                                          	KeyPadB
                                          	KeyPadC
                                          	KeyPadD
                                          	KeyPadE
                                          	KeyPadF
                                          	KeyPadXOR
                                          	KeyPadPower
                                          	KeyPadPercent
                                          	KeyPadLess
                                          	KeyPadGreater
                                          	KeyPadAmpersand
                                          	KeyPadDblampersand
                                          	KeyPadVerticalbar
                                          	KeyPadDblverticalbar
                                          	KeyPadColon
                                          	KeyPadHash
                                          	KeyPadSpace
                                          	KeyPadAt
                                          	KeyPadExclam
                                          	KeyPadMemstore
                                          	KeyPadMemrecall
                                          	KeyPadMemclear
                                          	KeyPadMemadd
                                          	KeyPadMemsubtract
                                          	KeyPadMemmultiply
                                          	KeyPadMemdivide
                                          	KeyPadPlusminus
                                          	KeyPadClear
                                          	KeyPadClearentry
                                          	KeyPadBinary
                                          	KeyPadOctal
                                          	KeyPadDecimal
                                          	KeyPadHexadecimal
                                          	KeyLeftControl
                                          	KeyLeftShift
                                          	KeyLeftAlt
                                          	KeyLeftSuper
                                          	KeyRightControl
                                          	KeyRightShift
                                          	KeyRightAlt
                                          	KeyRightSuper
                                          	KeyMode
                                          	KeyAudioNext
                                          	KeyAudioPrev
                                          	KeyAudioStop
                                          	KeyAudioPlay
                                          	KeyAudioMute
                                          	KeyMediaSelect
                                          	KeyWWW
                                          	KeyMail
                                          	KeyCalculator
                                          	KeyComputer
                                          	KeyACSearch
                                          	KeyACHome
                                          	KeyACBack
                                          	KeyACForward
                                          	KeyACStop
                                          	KeyACRefresh
                                          	KeyACBookmarks
                                          	KeyBrightnessDown
                                          	KeyBrightnessUp
                                          	KeyDisplaySwitch
                                          	KeyKbdIllumToggle
                                          	KeyKbdIllumDown
                                          	KeyKbdIllumUp
                                          	KeyEject
                                          	KeySleep
                                          )

                                          func (Key) String

                                          func (k Key) String() string

                                          type KeyPress

                                          type KeyPress struct {
                                          	Mod  Modifier
                                          	Code Key
                                          	Down bool
                                          	When time.Time
                                          }

                                            KeyPress events occur when a user presses or releases a keyboard key. Mod is the bitwise OR mask of all pressed modifiers.

                                            func (KeyPress) Src

                                            func (KeyPress) Src() Device

                                            func (KeyPress) String

                                            func (key KeyPress) String() string

                                            func (KeyPress) Time

                                            func (e KeyPress) Time() time.Time

                                            type Modifier

                                            type Modifier int

                                              A modifier is a bitwise OR mask of all key modifiers which are currently held down. Valid modifiers are any combination of Alt, Shift, Control, or Super. Super may refer to the Windows key on Microsoft Windows, or the Command key on OSX.

                                              const (
                                              	ModAlt Modifier = 1 << iota
                                              	ModShift
                                              	ModCtrl
                                              	ModSuper
                                              	ModHyper
                                              )

                                              func (Modifier) String

                                              func (mod Modifier) String() string

                                              type Mouse

                                              type Mouse struct {
                                              	Btn  Button
                                              	Mod  Modifier
                                              	When time.Time
                                              }

                                                Mouse events occur when a mouse button is pressed or released. Btn is the bitwise OR mask of all pressed mouse buttons. Like a KeyPress, mouse presses may be associated with Modifiers.

                                                func (Mouse) Src

                                                func (Mouse) Src() Device

                                                func (Mouse) String

                                                func (m Mouse) String() string

                                                func (Mouse) Time

                                                func (e Mouse) Time() time.Time

                                                type Resize

                                                type Resize struct {
                                                	Width, Height int
                                                	When          time.Time
                                                }

                                                  Resize events occur when a window is resized. Width and Height represent the new size of the window, in pixels.

                                                  func (Resize) Src

                                                  func (Resize) Src() Device

                                                  func (Resize) String

                                                  func (r Resize) String() string

                                                  func (Resize) Time

                                                  func (e Resize) Time() time.Time

                                                  type Scroll

                                                  type Scroll struct {
                                                  	X, Y int
                                                  	When time.Time
                                                  }

                                                    A Scroll event occurs when a user scrolls the window, using a mouse wheel, track pad or otherwise. X and Y represent the relative horizontal and vertical scroll, respectively. Scrolling down and to the right produces positive offsets on both axes.

                                                    func (Scroll) Src

                                                    func (Scroll) Src() Device

                                                    func (Scroll) String

                                                    func (s Scroll) String() string

                                                    func (Scroll) Time

                                                    func (e Scroll) Time() time.Time

                                                    type Text

                                                    type Text struct {
                                                    	Text string
                                                    	When time.Time
                                                    }

                                                      Text events contain a string of UTF-8 encoded text that the user has input, either directly by pressing a keyboard key, or indirectly by commiting candidate text through an input method.

                                                      func (Text) Src

                                                      func (Text) Src() Device

                                                      func (Text) String

                                                      func (t Text) String() string

                                                      func (Text) Time

                                                      func (e Text) Time() time.Time

                                                      Notes

                                                      Bugs

                                                        • This library is still experimental. Its API is subject to change.