window.v2: azul3d.org/gfx/window.v2 Index | Files

package window

import "azul3d.org/gfx/window.v2"

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

Package Files

doc.go events.go glfwconvert.go glfwwindow.go props.go window.go

Variables

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).

func Run Uses

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.

type Close Uses

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 Uses

func (ev Close) String() string

String returns a string representation of this event.

func (Close) Time Uses

func (ev Close) Time() time.Time

Time implements the Event interface.

type CursorEnter Uses

type CursorEnter struct {
    T time.Time
}

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

func (CursorEnter) String Uses

func (ev CursorEnter) String() string

String returns a string representation of this event.

func (CursorEnter) Time Uses

func (ev CursorEnter) Time() time.Time

Time implements the Event interface.

type CursorExit Uses

type CursorExit struct {
    T time.Time
}

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

func (CursorExit) String Uses

func (ev CursorExit) String() string

String returns a string representation of this event.

func (CursorExit) Time Uses

func (ev CursorExit) Time() time.Time

Time implements the Event interface.

type CursorMoved Uses

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 Uses

func (ev CursorMoved) String() string

String returns a string representation of this event.

func (CursorMoved) Time Uses

func (ev CursorMoved) Time() time.Time

Time implements the Event interface.

type Damaged Uses

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 Uses

func (ev Damaged) String() string

String returns a string representation of this event.

func (Damaged) Time Uses

func (ev Damaged) Time() time.Time

Time implements the Event interface.

type Event Uses

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 Uses

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 Uses

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 Uses

func (ev FramebufferResized) String() string

String returns a string representation of this event.

func (FramebufferResized) Time Uses

func (ev FramebufferResized) Time() time.Time

Time implements the Event interface.

type GainedFocus Uses

type GainedFocus struct {
    T time.Time
}

GainedFocus is an event where the window has gained focus.

func (GainedFocus) String Uses

func (ev GainedFocus) String() string

String returns a string representation of this event.

func (GainedFocus) Time Uses

func (ev GainedFocus) Time() time.Time

Time implements the Event interface.

type ItemsDropped Uses

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 Uses

func (ev ItemsDropped) String() string

String returns a string representation of this event.

func (ItemsDropped) Time Uses

func (ev ItemsDropped) Time() time.Time

Time implements the Event interface.

type LostFocus Uses

type LostFocus struct {
    T time.Time
}

LostFocus is an event where the window has lost focus.

func (LostFocus) String Uses

func (ev LostFocus) String() string

String returns a string representation of this event.

func (LostFocus) Time Uses

func (ev LostFocus) Time() time.Time

Time implements the Event interface.

type Minimized Uses

type Minimized struct {
    T time.Time
}

Minimized is an event where the user minimized the window.

func (Minimized) String Uses

func (ev Minimized) String() string

String returns a string representation of this event.

func (Minimized) Time Uses

func (ev Minimized) Time() time.Time

Time implements the Event interface.

type Moved Uses

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 Uses

func (ev Moved) String() string

String returns a string representation of this event.

func (Moved) Time Uses

func (ev Moved) Time() time.Time

Time implements the Event interface.

type Props Uses

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

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

func NewProps Uses

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 Uses

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 Uses

func (p *Props) CursorGrabbed() bool

CursorGrabbed returns whether or not the cursor is grabbed.

func (*Props) CursorPos Uses

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

CursorPos returns the position of the mouse cursor.

func (*Props) Decorated Uses

func (p *Props) Decorated() bool

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

func (*Props) Focused Uses

func (p *Props) Focused() bool

Focused tells whether or not the window has focus.

func (*Props) FramebufferSize Uses

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

FramebufferSize returns the size of the framebuffer in pixels.

func (*Props) Fullscreen Uses

func (p *Props) Fullscreen() bool

Fullscreen tells whether or not the window is fullscreen.

func (*Props) Minimized Uses

func (p *Props) Minimized() bool

Minimized tells whether or not the window is minimized.

func (*Props) Pos Uses

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 Uses

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

Precision returns the requested framebuffer precision to be requested.

func (*Props) Resizable Uses

func (p *Props) Resizable() bool

Resizable tells whether or not the window can be resized.

func (*Props) SetAlwaysOnTop Uses

func (p *Props) SetAlwaysOnTop(alwaysOnTop bool)

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

func (*Props) SetCursorGrabbed Uses

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 Uses

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 Uses

func (p *Props) SetDecorated(decorated bool)

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

func (*Props) SetFocused Uses

func (p *Props) SetFocused(focused bool)

SetFocused sets whether or not the window has focus.

func (*Props) SetFramebufferSize Uses

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 Uses

func (p *Props) SetFullscreen(fullscreen bool)

SetFullscreen sets whether or not the window is fullscreen.

func (*Props) SetMinimized Uses

func (p *Props) SetMinimized(minimized bool)

SetMinimized sets whether or not the window is minimized.

func (*Props) SetPos Uses

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 Uses

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

SetPrecision sets the framebuffer precision to be requested.

func (*Props) SetResizable Uses

func (p *Props) SetResizable(resizable bool)

SetResizable sets whether or not the window can be resized.

func (*Props) SetShouldClose Uses

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 Uses

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 Uses

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 Uses

func (p *Props) SetVSync(vsync bool)

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

func (*Props) SetVisible Uses

func (p *Props) SetVisible(visible bool)

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

func (*Props) ShouldClose Uses

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 Uses

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

Size returns the size of the window in screen coordinates.

func (*Props) String Uses

func (p *Props) String() string

String returns a string like:

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

func (*Props) Title Uses

func (p *Props) Title() string

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

func (*Props) VSync Uses

func (p *Props) VSync() bool

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

func (*Props) Visible Uses

func (p *Props) Visible() bool

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

type Resized Uses

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 Uses

func (ev Resized) String() string

String returns a string representation of this event.

func (Resized) Time Uses

func (ev Resized) Time() time.Time

Time implements the Event interface.

type Restored Uses

type Restored struct {
    T time.Time
}

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

func (Restored) String Uses

func (ev Restored) String() string

String returns a string representation of this event.

func (Restored) Time Uses

func (ev Restored) Time() time.Time

Time implements the Event interface.

type Window Uses

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.

Package window imports 14 packages (graph) and is imported by 3 packages. Updated 2016-07-20. Refresh now. Tools for package owners.