window

package module
v0.0.0-...-daee506 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 15, 2014 License: BSD-3-Clause Imports: 14 Imported by: 0

README

Azul3D gfx/window package.

See documentation online: http://www.azul3d.org/packages.html

Documentation

Overview

Package window is the easiest way to open a window and render graphics.

The window package effectively provides an easy cross-platform way to create and configure a window, as well as manipulate it and receive user input from it efficiently.

The window package lays the groundwork for developing applications that are truly cross-platform (i.e. desktop and mobile applications) using nearly the exact same API in the future. As such, the window package is mostly just an abstraction layer for GLFW on desktop operating systems.

If you truly need features not found in this package then you might be best using GLFW directly if you intend to just write desktop applications. Some features are not supported by this package intentionally, like multiple windows because mobile devices don't have them.

The goal of the window package is not to provide a one solution fits all, it is instead to abstract away the tedious parts of writing cross-device applications in the future.

The window package is also extremely simple to use: 

func gfxLoop(w window.Window, r gfx.Renderer) {
    // Initialization here.
    for {
        // Render loop here.
    }
}

func main() {
    window.Run(gfxLoop, nil)
}

Index

Constants

This section is empty.

Variables

View Source 
var DefaultProps = NewProps()

DefaultProps is the default set of window properties. You may modify them as you see fit.

They are used in place of nil properties (e.g. see the Run function).

Functions

func Run 

func Run(gfxLoop func(w Window, r gfx.Renderer), p *Props)

Run opens a window with the given properties and runs the given graphics loop in a separate goroutine.

Interpretation of the given properties is left strictly up to the platform dependant implementation (for instance, on Android you cannot set the window's size so it is simply ignored).

Requesting a specific framebuffer configuration via Props.SetPrecision is just a request. You may be given some other configuration (most likely one closest to it). You can check what you received by looking at: 

r.Canvas.Precision()

If the properties are nil, DefaultProps is used instead.

Types

type Close 

type Close struct {
	T time.Time
}

Close is sent when the user requests that the application window be closed, using the exit button or a quick-key combination like Alt + F4, etc.

func (Close) String 

func (ev Close) String() string

String returns a string representation of this event.

func (Close) Time 

func (ev Close) Time() time.Time

Time implements the Event interface.

type CursorEnter 

type CursorEnter struct {
	T time.Time
}

CursorEnter is an event where the user moved the mouse cursor inside of the window.

func (CursorEnter) String 

func (ev CursorEnter) String() string

String returns a string representation of this event.

func (CursorEnter) Time 

func (ev CursorEnter) Time() time.Time

Time implements the Event interface.

type CursorExit 

type CursorExit struct {
	T time.Time
}

CursorExit is an event where the user moved the mouse cursor outside of the window.

func (CursorExit) String 

func (ev CursorExit) String() string

String returns a string representation of this event.

func (CursorExit) Time 

func (ev CursorExit) Time() time.Time

Time implements the Event interface.

type CursorMoved 

type CursorMoved struct {
	// Position of cursor relative to the upper-left corner of the window.
	X, Y float64

	// Whether or not the event's X and Y values are actually relative delta
	// values (e.g. for a FPS style camera).
	Delta bool

	T time.Time
}

CursorMoved is sent when the user has moved the mouse cursor.

func (CursorMoved) String 

func (ev CursorMoved) String() string

String returns a string representation of this event.

func (CursorMoved) Time 

func (ev CursorMoved) Time() time.Time

Time implements the Event interface.

type Damaged 

type Damaged struct {
	T time.Time
}

Damaged is sent when the window's client area has been damaged and the window needs to be redrawn.

func (Damaged) String 

func (ev Damaged) String() string

String returns a string representation of this event.

func (Damaged) Time 

func (ev Damaged) Time() time.Time

Time implements the Event interface.

type Event 

type Event interface {
	Time() time.Time
}

Event represents an event of some sort. The only requirement is that the event specify the point in time at which it happened.

Using a type assertion or a type switch you can determine the actualy type of event which contains much more information: 

select ev := event.(type){
case *keyboard.StateEvent:
    fmt.Println("The keyboard button", ev.Key, "is now", ev.State)
    // example: "The keyboard button keyboard.A is now keyboard.Down"
}

type EventMask 

type EventMask uint32

EventMask is a bitmask of event types. They can be combined, for instance: 

mask := GenericEvents
mask |= MouseEvents
mask |= KeyboardEvents

would select generic, mouse, and keyboard events. 

const (
	// Event mask matching no events at all.
	NoEvents EventMask = 0

	// Each event mask below matches it's corresponding event (defined in this
	// package) without the `Events` suffix.
	CloseEvents              EventMask = 1 << 0
	DamagedEvents            EventMask = 1 << 1
	CursorMovedEvents        EventMask = 1 << 2
	CursorEnterEvents        EventMask = 1 << 3
	CursorExitEvents         EventMask = 1 << 4
	MinimizedEvents          EventMask = 1 << 5
	RestoredEvents           EventMask = 1 << 6
	GainedFocusEvents        EventMask = 1 << 7
	LostFocusEvents          EventMask = 1 << 8
	MovedEvents              EventMask = 1 << 9
	ResizedEvents            EventMask = 1 << 10
	FramebufferResizedEvents EventMask = 1 << 11
	ItemsDroppedEvents       EventMask = 1 << 12

	// Event mask for the mouse.Event event type.
	MouseEvents EventMask = 1 << 13

	// Event mask for the mouse.Scrolled event type.
	MouseScrolledEvents EventMask = 1 << 14

	// Event mask for the keyboard.TypedEvent event type.
	KeyboardTypedEvents EventMask = 1 << 15

	// Event mask for the keyboard.StateEvent event type.
	KeyboardStateEvents EventMask = 1 << 16

	// Event mask matching all possible events.
	AllEvents = EventMask(math.MaxUint32)
)

type FramebufferResized 

type FramebufferResized struct {
	// Size of the framebuffer in pixels.
	Width, Height int

	T time.Time
}

FramebufferResized is an event where the framebuffer of the window has been resized.

func (FramebufferResized) String 

func (ev FramebufferResized) String() string

String returns a string representation of this event.

func (FramebufferResized) Time 

func (ev FramebufferResized) Time() time.Time

Time implements the Event interface.

type GainedFocus 

type GainedFocus struct {
	T time.Time
}

GainedFocus is an event where the window has gained focus.

func (GainedFocus) String 

func (ev GainedFocus) String() string

String returns a string representation of this event.

func (GainedFocus) Time 

func (ev GainedFocus) Time() time.Time

Time implements the Event interface.

type ItemsDropped 

type ItemsDropped struct {
	Items []string

	T time.Time
}

ItemsDropped is an event where the user dropped an item (or multiple items) onto the window.

func (ItemsDropped) String 

func (ev ItemsDropped) String() string

String returns a string representation of this event.

func (ItemsDropped) Time 

func (ev ItemsDropped) Time() time.Time

Time implements the Event interface.

type LostFocus 

type LostFocus struct {
	T time.Time
}

LostFocus is an event where the window has lost focus.

func (LostFocus) String 

func (ev LostFocus) String() string

String returns a string representation of this event.

func (LostFocus) Time 

func (ev LostFocus) Time() time.Time

Time implements the Event interface.

type Minimized 

type Minimized struct {
	T time.Time
}

Minimized is an event where the user minimized the window.

func (Minimized) String 

func (ev Minimized) String() string

String returns a string representation of this event.

func (Minimized) Time 

func (ev Minimized) Time() time.Time

Time implements the Event interface.

type Moved 

type Moved struct {
	// Position of the window's client area, relative to the top-left of the
	// screen.
	X, Y int

	T time.Time
}

Moved is an event where the user changed the position of the window.

func (Moved) String 

func (ev Moved) String() string

String returns a string representation of this event.

func (Moved) Time 

func (ev Moved) Time() time.Time

Time implements the Event interface.

type Props 

type Props struct {
	// contains filtered or unexported fields
}

Props represents window properties. Properties are safe for use concurrently from multiple goroutines.

func NewProps 

func NewProps() *Props

NewProps returns a new initialized set of window properties. The default values for each property are as follows: 

Title: "Azul3D - {FPS}"
Size: 800x450
Pos: -1, -1 (centered on screen)
CursorPos: -1.0, -1.0 (current position)
ShouldClose: true
Visible: true
Minimized: false
Fullscreen: false
Focused: true
VSync: true
Resizable: true
Decorated: true
AlwaysOnTop: false
CursorGrabbed: false
FramebufferSize: 1x1 (set via window owner)
Precision: gfx.Precision{
    RedBits: 8, GreenBits: 8, BlueBits: 8, AlphaBits: 0,
    DepthBits: 24,
    StencilBits: 0,
    Samples: 2,
}

func (*Props) AlwaysOnTop 

func (p *Props) AlwaysOnTop() bool

AlwaysOnTop tells whether or not the window is set to be always on top of other windows.

func (*Props) CursorGrabbed 

func (p *Props) CursorGrabbed() bool

CursorGrabbed returns whether or not the cursor is grabbed.

func (*Props) CursorPos 

func (p *Props) CursorPos() (x, y float64)

CursorPos returns the position of the mouse cursor.

func (*Props) Decorated 

func (p *Props) Decorated() bool

Decorated tells whether or not the window has it's decorations shown.

func (*Props) Focused 

func (p *Props) Focused() bool

Focused tells whether or not the window has focus.

func (*Props) FramebufferSize 

func (p *Props) FramebufferSize() (width, height int)

FramebufferSize returns the size of the framebuffer in pixels.

func (*Props) Fullscreen 

func (p *Props) Fullscreen() bool

Fullscreen tells whether or not the window is fullscreen.

func (*Props) Minimized 

func (p *Props) Minimized() bool

Minimized tells whether or not the window is minimized.

func (*Props) Pos 

func (p *Props) Pos() (x, y int)

Pos returns the position of the upper-left corner of the client area of the window in screen coordinates.

func (*Props) Precision 

func (p *Props) Precision() gfx.Precision

Precision returns the requested framebuffer precision to be requested.

func (*Props) Resizable 

func (p *Props) Resizable() bool

Resizable tells whether or not the window can be resized.

func (*Props) SetAlwaysOnTop 

func (p *Props) SetAlwaysOnTop(alwaysOnTop bool)

SetAlwaysOnTop sets whether or not the window is always on top of other windows.

func (*Props) SetCursorGrabbed 

func (p *Props) SetCursorGrabbed(grabbed bool)

SetCursorGrabbed sets whether or not the cursor should be grabbed. If the cursor is grabbed, it is hidden from sight and cannot leave the window.

When grabbed, a window generates CursorMoved events with Delta=true, this is useful for e.g. FPS style cameras.

func (*Props) SetCursorPos 

func (p *Props) SetCursorPos(x, y float64)

SetCursorPos sets the position of the mouse cursor.

A special value of x=-1.0, y=-1.0 means to not move the mouse cursor at all.

func (*Props) SetDecorated 

func (p *Props) SetDecorated(decorated bool)

SetDecorated sets whether or not the window has it's decorations shown.

func (*Props) SetFocused 

func (p *Props) SetFocused(focused bool)

SetFocused sets whether or not the window has focus.

func (*Props) SetFramebufferSize 

func (p *Props) SetFramebufferSize(width, height int)

SetFramebufferSize sets the size of the framebuffer in pixels. Each value is clamped to at least a value of 1.

Only the window owner should ever set the framebuffer size.

func (*Props) SetFullscreen 

func (p *Props) SetFullscreen(fullscreen bool)

SetFullscreen sets whether or not the window is fullscreen.

func (*Props) SetMinimized 

func (p *Props) SetMinimized(minimized bool)

SetMinimized sets whether or not the window is minimized.

func (*Props) SetPos 

func (p *Props) SetPos(x, y int)

SetPos sets the position of the upper-left corner of the client area of the window in screen coordinates.

A special value of x=-1, y=-1 means to center the window on the screen.

func (*Props) SetPrecision 

func (p *Props) SetPrecision(precision gfx.Precision)

SetPrecision sets the framebuffer precision to be requested.

func (*Props) SetResizable 

func (p *Props) SetResizable(resizable bool)

SetResizable sets whether or not the window can be resized.

func (*Props) SetShouldClose 

func (p *Props) SetShouldClose(shouldClose bool)

SetShouldClose sets whether the window should close or not when the user tries to close the window.

func (*Props) SetSize 

func (p *Props) SetSize(width, height int)

SetSize sets the size of the window in screen coordinates. Each value is clamped to at least a value of 1.

func (*Props) SetTitle 

func (p *Props) SetTitle(title string)

SetTitle sets the title of the window. The backend will replace the first string in the title matching "{FPS}" with the actual frames per second.

For example, a title "Hello World - {FPS}" would end up as: 

"Hello world - 60FPS"

func (*Props) SetVSync 

func (p *Props) SetVSync(vsync bool)

SetVSync turns on or off vertical refresh rate synchronization (vsync).

func (*Props) SetVisible 

func (p *Props) SetVisible(visible bool)

SetVisible sets whether or not the window is visible or hidden.

func (*Props) ShouldClose 

func (p *Props) ShouldClose() bool

ShouldClose tells if the window will close or not when the user tries to close the window.

func (*Props) Size 

func (p *Props) Size() (width, height int)

Size returns the size of the window in screen coordinates.

func (*Props) String 

func (p *Props) String() string

String returns a string like: 

"Window(Title="Hello World!", Fullscreen=false)"

func (*Props) Title 

func (p *Props) Title() string

Title returns the title of the window, as previously set via SetTitle.

func (*Props) VSync 

func (p *Props) VSync() bool

VSync tells if vertical refresh rate synchronization (vsync) is on or off.

func (*Props) Visible 

func (p *Props) Visible() bool

Visible tells whether or not the window is visible or hidden.

type Resized 

type Resized struct {
	// Size of the window in screen coordinates.
	Width, Height int

	T time.Time
}

Resized is an event where the user changed the size of the window.

func (Resized) String 

func (ev Resized) String() string

String returns a string representation of this event.

func (Resized) Time 

func (ev Resized) Time() time.Time

Time implements the Event interface.

type Restored 

type Restored struct {
	T time.Time
}

Restored is an event where the user restored (un-minimized) the window.

func (Restored) String 

func (ev Restored) String() string

String returns a string representation of this event.

func (Restored) Time 

func (ev Restored) Time() time.Time

Time implements the Event interface.

type Window 

type Window interface {
	// Props returns the window's properties.
	Props() *Props

	// Request makes a request to use a new set of properties, p. It is then
	// reccomended to make changes to the window using something like:
	//  props := window.Props()
	//  props.SetTitle("Hello World!")
	//  props.SetSize(640, 480)
	//  window.Request(props)
	//
	// Interpretation of the given properties is left strictly up to the
	// platform dependant implementation (for instance, on Android you cannot
	// set the window's size, so instead a request for this is simply ignored.
	Request(p *Props)

	// Keyboard returns a keyboard watcher for the window. It can be used to
	// tell if certain keyboard buttons are currently held down, for instance:
	//
	//  if w.Keyboard().Down(keyboard.W) {
	//      fmt.Println("The W key is currently held down")
	//  }
	Keyboard() *keyboard.Watcher

	// Mouse returns a mouse watcher for the window. It can be used to tell if
	// certain mouse buttons are currently held down, for instance:
	//
	//  if w.Mouse().Down(mouse.Left) {
	//      fmt.Println("The left mouse button is currently held down")
	//  }
	Mouse() *mouse.Watcher

	// SetClipboard sets the clipboard string.
	SetClipboard(clipboard string)

	// Clipboard returns the clipboard string.
	Clipboard() string

	// Notify causes the window to relay window events to ch based on the event
	// mask.
	//
	// The special event mask NoEvents causes the window to stop relaying any
	// events to the given channel. You should always perform this action when
	// you are done using the event channel.
	//
	// The window will not block sending events to ch: the caller must ensure
	// that ch has a sufficient amount of buffer space to keep up with the
	// event rate.
	//
	// If you only expect to receive a single event like Close then a buffer
	// size of one is acceptable.
	//
	// You are allowed to make multiple calls to this method with the same
	// channel, if you do then the same event will be sent over the channel
	// multiple times. When you no longer want the channel to receive events
	// then call this function again with NoEvents:
	//  w.Notify(ch, NoEvents)
	//
	// Multiple calls to Events with different channels works as you would
	// expect, each channel receives a copy of the events independant of other
	// ones.
	//
	// Warning: Many people use high-precision mice, some which can reach well
	// above 1000hz, so for cursor events a generous buffer size (256, etc) is
	// highly recommended.
	//
	// Warning: Depending on the operating system, window manager, etc, some of
	// the events may never be sent or may only be sent sporiadically, so plan
	// for this.
	Notify(ch chan<- Event, m EventMask)

	// Close closes the window, and causes Run() to return.
	Close()
}

Window represents a single window that graphics can be rendered to. The window is safe for use concurrently from multiple goroutines.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.