API Window

Gambaran Umum

API Window menyediakan metode untuk mengontrol tampilan, perilaku, dan lifecycle window. Akses melalui instance window atau manajer app.Window.

Window adalah antarmuka yang dipenuhi oleh *application.WebviewWindow; signature metode di bawah ini ada di *WebviewWindow. Banyak mutator mengembalikan Window untuk memungkinkan chaining — nilai kembalian didokumentasikan per metode.

Operasi umum:

Membuat dan menampilkan window
Mengontrol ukuran, posisi, dan status
Menangani event window
Mengelola konten window
Mengonfigurasi tampilan dan perilaku

Visibilitas

Show()

Menampilkan window. Jika window disembunyikan, window menjadi terlihat. Mengembalikan receiver untuk chaining.

func (w *WebviewWindow) Show() Window

Contoh:

window := app.Window.New()
window.Show()

Hide()

Menyembunyikan window tanpa menutupnya. Window tetap di memori dan dapat ditampilkan lagi. Mengembalikan receiver untuk chaining.

func (w *WebviewWindow) Hide() Window

Contoh:

// Sembunyikan window sementara
window.Hide()

// Tampilkan lagi nanti
window.Show()

Kasus penggunaan:

Aplikasi system tray yang disembunyikan ke tray
Alur wizard di mana window digunakan kembali
Penyembunyian sementara selama operasi

Close()

Menutup window. Ini memicu event WindowClosing.

func (w *WebviewWindow) Close()

Contoh:

window.Close()

Catatan: Jika hook terdaftar memanggil event.Cancel(), penutupan akan dicegah.

Properti Window

SetTitle()

Mengatur teks title bar window. Mengembalikan receiver untuk chaining.

func (w *WebviewWindow) SetTitle(title string) Window

Parameter:

title - Judul window baru

Contoh:

window.SetTitle("My Application - Document.txt")

Name()

Mengembalikan pengenal nama unik window.

func (w *WebviewWindow) Name() string

Contoh:

name := window.Name()
fmt.Println("Window name:", name)

// Ambil window berdasarkan nama nanti
if w, ok := app.Window.GetByName(name); ok {
    w.Focus()
}

Ukuran dan Posisi

SetSize()

Mengatur dimensi window dalam piksel. Mengembalikan receiver untuk chaining.

func (w *WebviewWindow) SetSize(width, height int) Window

Parameter:

width - Lebar window dalam piksel
height - Tinggi window dalam piksel

Contoh:

window.SetSize(1024, 768)

Size()

Mengembalikan dimensi window saat ini.

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

Contoh:

width, height := window.Size()
fmt.Printf("Window is %dx%d\n", width, height)

SetMinSize() / SetMaxSize()

Mengatur dimensi minimum dan maksimum window. Keduanya mengembalikan receiver untuk chaining.

func (w *WebviewWindow) SetMinSize(width, height int) Window
func (w *WebviewWindow) SetMaxSize(width, height int) Window

Contoh:

// Cegah window terlalu kecil
window.SetMinSize(800, 600)

// Cegah window terlalu besar
window.SetMaxSize(1920, 1080)

SetPosition()

Mengatur posisi window relatif terhadap sudut kiri atas layar.

func (w *WebviewWindow) SetPosition(x, y int)

Parameter:

x - Posisi horizontal dalam piksel
y - Posisi vertikal dalam piksel

Contoh:

// Posisikan window di kiri atas
window.SetPosition(0, 0)

// Posisikan window 100px dari kiri atas
window.SetPosition(100, 100)

Position()

Mengembalikan posisi window saat ini.

func (w *WebviewWindow) Position() (x, y int)

Contoh:

x, y := window.Position()
fmt.Printf("Window is at (%d, %d)\n", x, y)

Center()

Memusatkan window di layar.

func (w *WebviewWindow) Center()

Contoh:

window := app.Window.New()
window.Center()
window.Show()

Catatan: Memusatkan di monitor utama. Untuk setup multi-monitor, lihat API screen.

Focus()

Membawa window ke depan dan memberikan fokus keyboard.

func (w *WebviewWindow) Focus()

Contoh:

// Bawa window ke depan
window.Focus()

Status Window

Minimise() / UnMinimise()

Meminimalkan window ke taskbar/dock atau memulihkannya. Minimise() mengembalikan receiver untuk chaining; UnMinimise() tidak mengembalikan nilai.

func (w *WebviewWindow) Minimise() Window
func (w *WebviewWindow) UnMinimise()

Contoh:

// Minimalkan window
window.Minimise()

// Pulihkan dari status diminimalkan
window.UnMinimise()

Maximise() / UnMaximise()

Memaksimalkan window untuk mengisi layar atau memulihkan ke ukuran sebelumnya. Maximise() mengembalikan receiver untuk chaining; UnMaximise() tidak mengembalikan nilai.

func (w *WebviewWindow) Maximise() Window
func (w *WebviewWindow) UnMaximise()

Contoh:

// Maksimalkan window
window.Maximise()

// Pulihkan ke ukuran sebelumnya
window.UnMaximise()

Fullscreen() / UnFullscreen() / ToggleFullscreen()

Memasuki atau keluar dari mode fullscreen. Fullscreen() mengembalikan receiver untuk chaining.

func (w *WebviewWindow) Fullscreen() Window
func (w *WebviewWindow) UnFullscreen()
func (w *WebviewWindow) ToggleFullscreen()

Contoh:

// Masuk fullscreen
window.Fullscreen()

// Keluar fullscreen
window.UnFullscreen()

// Atau toggle
window.ToggleFullscreen()

Tidak ada metode SetFullscreen(bool).

IsMinimised() / IsMaximised() / IsFullscreen()

Memeriksa status window saat ini.

func (w *WebviewWindow) IsMinimised() bool
func (w *WebviewWindow) IsMaximised() bool
func (w *WebviewWindow) IsFullscreen() bool

Contoh:

if window.IsMinimised() {
    window.UnMinimise()
}

if window.IsMaximised() {
    fmt.Println("Window is maximised")
}

if window.IsFullscreen() {
    window.UnFullscreen()
}

Konten Window

SetURL()

Menavigasi ke URL tertentu dalam window. Mengembalikan receiver untuk chaining.

func (w *WebviewWindow) SetURL(url string) Window

Parameter:

url - URL untuk dinavigasi (dapat berupa http://wails.localhost/ untuk aset tertanam)

Contoh:

// Navigasi ke halaman tertanam
window.SetURL("http://wails.localhost/settings.html")

// Navigasi ke URL eksternal (jika diizinkan)
window.SetURL("https://wails.io")

SetHTML()

Mengatur konten window langsung dari string HTML. Mengembalikan receiver untuk chaining.

func (w *WebviewWindow) SetHTML(html string) Window

Parameter:

html - Konten HTML untuk ditampilkan

Contoh:

html := `
<!DOCTYPE html>
<html>
<head><title>Dynamic Content</title></head>
<body>
    <h1>Hello from Go!</h1>
    <p>This content was generated dynamically.</p>
</body>
</html>
`
window.SetHTML(html)

Kasus penggunaan:

Generasi konten dinamis
Window sederhana tanpa proses build frontend
Halaman error atau splash screen

Reload()

Memuat ulang konten window saat ini.

func (w *WebviewWindow) Reload()

Contoh:

// Muat ulang halaman saat ini
window.Reload()

Catatan: Berguna selama pengembangan atau saat konten perlu diperbarui.

Event Window

Wails menyediakan dua metode untuk menangani event window:

OnWindowEvent() - Mendengarkan event window (tidak dapat mencegahnya).
RegisterHook() - Hook ke event window (dapat mencegahnya dengan memanggil event.Cancel()).

OnWindowEvent()

Mendaftarkan callback untuk event window. Mengembalikan fungsi unsubscribe.

func (w *WebviewWindow) OnWindowEvent(
    eventType events.WindowEventType,
    callback func(event *WindowEvent),
) func()

Contoh:

import "github.com/wailsapp/wails/v3/pkg/events"

// Dengarkan fokus window
window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
    app.Logger.Info("Window gained focus")
})

// Dengarkan kehilangan fokus window
window.OnWindowEvent(events.Common.WindowLostFocus, func(e *application.WindowEvent) {
    app.Logger.Info("Window lost focus")
})

// Dengarkan resize window
window.OnWindowEvent(events.Common.WindowDidResize, func(e *application.WindowEvent) {
    app.Logger.Info("Window resized")
})

Event Window Umum:

events.Common.WindowClosing - Window akan ditutup
events.Common.WindowFocus - Window mendapat fokus
events.Common.WindowLostFocus - Window kehilangan fokus
events.Common.WindowDidMove - Window dipindahkan
events.Common.WindowDidResize - Window diubah ukurannya
events.Common.WindowMinimise - Window diminimalkan
events.Common.WindowMaximise - Window dimaksimalkan
events.Common.WindowFullscreen - Window masuk fullscreen
events.Common.WindowRuntimeReady - Runtime dalam window diinisialisasi

RegisterHook()

Mendaftarkan hook untuk event window. Hook berjalan sebelum listener dan dapat mencegah event dengan memanggil event.Cancel(). Mengembalikan fungsi unsubscribe.

func (w *WebviewWindow) RegisterHook(
    eventType events.WindowEventType,
    callback func(event *WindowEvent),
) func()

Contoh - Cegah penutupan window:

import "github.com/wailsapp/wails/v3/pkg/events"

window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    confirm := app.Dialog.Question().
        SetTitle("Confirm Close").
        SetMessage("Are you sure you want to close this window?")

    yes := confirm.AddButton("Yes")
    no := confirm.AddButton("No")
    confirm.SetDefaultButton(yes)
    confirm.SetCancelButton(no)

    no.OnClick(func() {
        e.Cancel() // Cegah window ditutup
    })

    confirm.Show()
})

Contoh - Simpan sebelum menutup:

window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    if !hasUnsavedChanges {
        return
    }

    dlg := app.Dialog.Question().
        SetTitle("Unsaved Changes").
        SetMessage("Save changes before closing?")

    save := dlg.AddButton("Save")
    discard := dlg.AddButton("Don't Save")
    cancel := dlg.AddButton("Cancel")
    dlg.SetDefaultButton(save)
    dlg.SetCancelButton(cancel)

    save.OnClick(func() { saveData() })
    cancel.OnClick(func() { e.Cancel() })
    _ = discard // izinkan penutupan

    dlg.Show()
})

EmitEvent()

Mengirim event kustom ke frontend window. Mengembalikan true jika emit dibatalkan oleh hook.

func (w *WebviewWindow) EmitEvent(name string, data ...any) bool

Parameter:

name - Nama event
data - Data opsional untuk dikirim dengan event

Contoh:

// Kirim data ke window tertentu
window.EmitEvent("data-updated", map[string]any{
    "count":  42,
    "status": "success",
})

Frontend (JavaScript):

import { Events } from '@wailsio/runtime'

Events.On('data-updated', (data) => {
    console.log('Count:', data.count)
    console.log('Status:', data.status)
})

Metode Lainnya

SetEnabled()

Mengaktifkan atau menonaktifkan interaksi pengguna dengan window.

func (w *WebviewWindow) SetEnabled(enabled bool)

Contoh:

// Nonaktifkan window selama operasi panjang
window.SetEnabled(false)

// Lakukan operasi
performLongOperation()

// Aktifkan kembali window
window.SetEnabled(true)

SetBackgroundColour()

Mengatur warna latar belakang window (ditampilkan sebelum konten dimuat). Mengembalikan receiver untuk chaining.

func (w *WebviewWindow) SetBackgroundColour(colour RGBA) Window

RGBA adalah application.RGBA{Red, Green, Blue, Alpha uint8}. Gunakan helper application.NewRGB(r, g, b) (alpha 255) atau application.NewRGBA(r, g, b, a).

Contoh:

// Latar belakang putih
window.SetBackgroundColour(application.NewRGB(255, 255, 255))

// Latar belakang gelap dengan alpha penuh
window.SetBackgroundColour(application.NewRGBA(30, 30, 30, 255))

SetResizable()

Mengontrol apakah window dapat diubah ukurannya oleh pengguna. Mengembalikan receiver untuk chaining.

func (w *WebviewWindow) SetResizable(resizable bool) Window

Contoh:

// Buat window ukuran tetap
window.SetResizable(false)

SetAlwaysOnTop()

Mengatur apakah window tetap di atas window lain. Mengembalikan receiver untuk chaining.

func (w *WebviewWindow) SetAlwaysOnTop(alwaysOnTop bool) Window

Contoh:

// Jaga window tetap di atas
window.SetAlwaysOnTop(true)

Print()

Membuka dialog cetak native untuk konten window.

func (w *WebviewWindow) Print() error

Mengembalikan: Error jika pencetakan gagal.

Contoh:

if err := window.Print(); err != nil {
    log.Println("Print failed:", err)
}

AttachModal()

Melampirkan window kedua sebagai sheet modal.

func (w *WebviewWindow) AttachModal(modalWindow Window)

Parameter:

modalWindow - Window yang dilampirkan sebagai modal

Dukungan platform:

macOS: Dukungan penuh (ditampilkan sebagai sheet)
Windows: Tidak didukung
Linux: Tidak didukung

Contoh:

modalWindow := app.Window.New()
window.AttachModal(modalWindow)

Opsi Khusus Platform

Linux

Window Linux mendukung opsi khusus platform berikut melalui LinuxWindow:

MenuStyle

Mengontrol bagaimana menu aplikasi ditampilkan. Opsi ini tersedia pada build GTK4 default dan diabaikan pada build legacy -tags gtk3.

Nilai	Deskripsi
`LinuxMenuStyleMenuBar`	Menu bar tradisional di bawah title bar (default)
`LinuxMenuStylePrimaryMenu`	Tombol menu utama di header bar (gaya GNOME)

Contoh:

window := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title: "My Application",
    Linux: application.LinuxWindow{
        MenuStyle: application.LinuxMenuStylePrimaryMenu,
    },
})
window.SetMenu(menu)

Catatan: Gaya menu utama menampilkan tombol hamburger (☰) di header bar, mengikuti GNOME Human Interface Guidelines. Ini adalah gaya yang direkomendasikan untuk aplikasi GNOME modern.

Contoh Lengkap

package main

import (
    "github.com/wailsapp/wails/v3/pkg/application"
    "github.com/wailsapp/wails/v3/pkg/events"
)

func main() {
    app := application.New(application.Options{
        Name: "Window API Demo",
    })

    // Buat window dengan opsi
    window := app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title:            "My Application",
        Width:            1024,
        Height:           768,
        MinWidth:         800,
        MinHeight:        600,
        BackgroundColour: application.NewRGB(255, 255, 255),
        URL:              "http://wails.localhost/",
    })

    // Konfigurasi perilaku window
    window.SetResizable(true)
    window.SetMinSize(800, 600)
    window.SetMaxSize(1920, 1080)

    // Hook konfirmasi sebelum menutup
    window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
        dlg := app.Dialog.Question().
            SetTitle("Confirm Close").
            SetMessage("Are you sure you want to close this window?")

        yes := dlg.AddButton("Yes")
        no := dlg.AddButton("No")
        dlg.SetDefaultButton(yes)
        dlg.SetCancelButton(no)
        no.OnClick(func() { e.Cancel() })

        dlg.Show()
    })

    // Dengarkan event window
    window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
        window.SetTitle("My Application (Active)")
        app.Logger.Info("Window gained focus")
    })

    window.OnWindowEvent(events.Common.WindowLostFocus, func(e *application.WindowEvent) {
        window.SetTitle("My Application")
        app.Logger.Info("Window lost focus")
    })

    // Posisikan dan tampilkan window
    window.Center()
    window.Show()

    app.Run()
}