system

type App interface {

	// Platform returns the platform type, which can be used
	// for conditionalizing behavior
	Platform() Platforms

	// SystemPlatform returns the platform type of the underlying
	// system, which can be used for conditionalizing behavior. On platforms
	// other than [Web], this is the same as [App.Platform]. On [Web], it
	// returns the platform of the underlying operating system.
	SystemPlatform() Platforms

	// SystemInfo returns any additional information about the underlying system
	// that is not otherwise given. It is used in crash logs.
	SystemInfo() string

	// Name is the overall name of the application -- used for specifying an
	// application-specific preferences directory, etc
	Name() string

	// SetName sets the application name -- defaults to Cogent Core if not otherwise set
	SetName(name string)

	// GetScreens gets the current list of screens
	GetScreens()

	// NScreens returns the number of different logical and/or physical
	// screens managed under this overall screen hardware
	NScreens() int

	// Screen returns screen for given screen number, or nil if not a
	// valid screen number.
	Screen(n int) *Screen

	// ScreenByName returns screen for given screen name, or nil if not a
	// valid screen name.
	ScreenByName(name string) *Screen

	// NWindows returns the number of windows open for this app.
	NWindows() int

	// Window returns given window in list of windows opened under this screen
	// -- list is not in any guaranteed order, but typically in order of
	// creation (see also WindowByName) -- returns nil for invalid index.
	Window(win int) Window

	// WindowByName returns given window in list of windows opened under this
	// screen, by name -- nil if not found.
	WindowByName(name string) Window

	// WindowInFocus returns the window currently in focus (receiving keyboard
	// input) -- could be nil if none are.
	WindowInFocus() Window

	// ContextWindow returns the window passed as context for clipboard, cursor, etc calls.
	ContextWindow() Window

	// NewWindow returns a new Window for this screen. A nil opts is valid and
	// means to use the default option values.
	NewWindow(opts *NewWindowOptions) (Window, error)

	// RemoveWindow removes the given Window from the app's list of windows.
	// It does not actually close it; see [Window.Close] for that.
	RemoveWindow(win Window)

	// Clipboard returns the [Clipboard] handler for the system,
	// in context of given window, which is optional (can be nil)
	// but can provide useful context on some systems.
	Clipboard(win Window) Clipboard

	// Cursor returns the [Cursor] handler for the system, in the context
	// of the given window.
	Cursor(win Window) Cursor

	// DataDir returns the OS-specific data directory: Mac: ~/Library,
	// Linux: ~/.config, Windows: ~/AppData/Roaming
	DataDir() string

	// AppDataDir returns the application-specific data directory: [App.DataDir] +
	// [App.Name]. It ensures that the directory exists first.
	AppDataDir() string

	// CogentCoreDataDir returns the Cogent Core data directory: [App.DataDir] +
	// "Cogent Core". It ensures that the directory exists first.
	CogentCoreDataDir() string

	// OpenURL opens the given URL in the user's default browser.  On Linux
	// this requires that xdg-utils package has been installed, since it uses
	// the xdg-open command.
	OpenURL(url string)

	// OpenFiles returns file names that have been set to be open at startup.
	OpenFiles() []string

	// SetQuitReqFunc sets the function that is called whenever there is a
	// request to quit the app (via a OS or a call to QuitReq() method).  That
	// function can then adjudicate whether and when to actually call Quit.
	SetQuitReqFunc(fun func())

	// AddQuitCleanFunc adds the given function to a list that is called whenever
	// app is actually about to quit (irrevocably). Can do any necessary
	// last-minute cleanup here.
	AddQuitCleanFunc(fun func())

	// QuitReq is a quit request, triggered either by OS or user call (e.g.,
	// via Quit menu action) -- calls function previously registered by
	// SetQuitReqFunc, which is then solely responsible for actually calling
	// Quit.
	QuitReq()

	// IsQuitting returns true when the app is actually quitting -- it is set
	// to true just before the QuitClean function is called, and before all
	// the windows are closed.
	IsQuitting() bool

	// QuitClean calls the function setup in SetQuitCleanFunc and does other
	// app cleanup -- called on way to quitting. If it returns false, then
	// the app should not quit.
	QuitClean() bool

	// Quit closes all windows and exits the program.
	Quit()

	// MainLoop runs the main loop of the app.
	MainLoop()

	// RunOnMain runs given function on main thread (where [App.MainLoop] is running).
	// Some functions (GUI-specific etc) must run on this initial main thread for the
	// overall app. If [App.MainLoop] has not been called yet, RunOnMain assumes that
	// it is being called from the main thread and thus just calls the given function
	// directly.
	RunOnMain(f func())

	// SendEmptyEvent sends an empty, blank event to global event processing
	// system, which has the effect of pushing the system along during cases when
	// the event loop needs to be "pinged" to get things moving along.
	// See also similar method on Window.
	SendEmptyEvent()

	// ShowVirtualKeyboard shows a virtual keyboard of the given type.
	// ShowVirtualKeyboard only has an effect on mobile platforms (iOS, Android, and Web).
	// It should not be called with [styles.NoKeyboard].
	ShowVirtualKeyboard(typ styles.VirtualKeyboards)

	// HideVirtualKeyboard hides the virtual keyboard.
	// HideVirtualKeyboard only has an effect on mobile platforms (iOS, Android, and Web).
	HideVirtualKeyboard()

	// IsDark returns whether the system color theme is dark (as oppposed to light).
	IsDark() bool
}

type Clipboard interface {

	// IsEmpty returns true if there is nothing on the clipboard to read.
	// Can be used for disabling a Paste menu.
	IsEmpty() bool

	// Read attempts to read data of the given MIME type(s), in preference
	// order, from the clipboard, returning mimedata.Mimes which can
	// potentially have multiple types / multiple items, etc. If the first type
	// listed is a text type, then text-based retrieval is assumed; always
	// put the most specific desired type first; anything else present will
	// be returned
	Read(types []string) mimedata.Mimes

	// Write writes given mimedata to the clipboard; in general having a
	// text/plain representation of the data in addition to a more specific
	// format is a good idea for anything more complex than plain text; if
	// data has > 1 element, it is all encoded as a multipart MIME text string
	Write(data mimedata.Mimes) error

	// Clear clears the clipboard.
	Clear()
}

type ClipboardBase struct{}

type Cursor interface {

	// Current returns the current cursor as an enum, which is a
	// [cogentcore.org/core/cursors.Cursor]
	// by default, but could be something else if you are extending
	// the default cursor set.
	Current() enums.Enum

	// Set sets the active cursor to the given cursor as an enum, which is typically
	// a [cursors.Cursor], unless you are extending the default cursor set, in
	// which case it should be a type you defined. The string version of the
	// enum value must correspond to a filename of the form "name.svg" in
	// [cogentcore.org/core/cursors.Cursors]; this will be satisfied automatically by all
	// [cursor.Cursor] values.
	Set(cursor enums.Enum) error

	// IsVisible returns whether cursor is currently visible (according to [Cursor.Hide] and [Cursor.Show] actions)
	IsVisible() bool

	// Hide hides the cursor if it is not already hidden.
	Hide()

	// Show shows the cursor after a hide if it is hidden.
	Show()

	// SetSize sets the size that cursors are rendered at.
	SetSize(size int)
}

type CursorBase struct {
	// Cur is the current cursor, which is maintained by the standard methods.
	Cur enums.Enum

	// Vis is whether the cursor is visible; be sure to initialize to true!
	Vis bool

	// Size is the size that cursors are rendered at
	Size int
}

type Drawer interface {
	// DestBounds returns the bounds of the render destination
	DestBounds() image.Rectangle

	// Start starts recording a sequence of draw / fill actions,
	// which will be performed on the GPU at End().
	// This must be called prior to any Drawer operations.
	Start()

	// End ends image drawing rendering process on render target.
	End()

	// Copy copies the given Go source image to the render target, with the
	// same semantics as golang.org/x/image/draw.Copy, with the destination
	// implicit in the Drawer target.
	//   - Must have called Start first!
	//   - dp is the destination point.
	//   - src is the source image. If an image.Uniform, fast Fill is done.
	//   - sr is the source region, if zero full src is used; must have for Uniform.
	//   - op is the drawing operation: Src = copy source directly (blit),
	//     Over = alpha blend with existing.
	//   - unchanged should be true if caller knows that this image is unchanged
	//     from the last time it was used -- saves re-uploading to gpu.
	Copy(dp image.Point, src image.Image, sr image.Rectangle, op draw.Op, unchanged bool)

	// Scale copies the given Go source image to the render target,
	// scaling the region defined by src and sr to the destination
	// such that sr in src-space is mapped to dr in dst-space,
	// and applying an optional rotation of the source image.
	// Has the same general semantics as golang.org/x/image/draw.Scale, with the
	// destination implicit in the Drawer target.
	// If src image is an
	//   - Must have called Start first!
	//   - dr is the destination rectangle; if zero uses full dest image.
	//   - src is the source image. Uniform does not work (or make sense) here.
	//   - sr is the source region, if zero full src is used; must have for Uniform.
	//   - rotateDeg = rotation degrees to apply in the mapping:
	//     90 = left, -90 = right, 180 = invert.
	//   - op is the drawing operation: Src = copy source directly (blit),
	//     Over = alpha blend with existing.
	//   - unchanged should be true if caller knows that this image is unchanged
	//     from the last time it was used -- saves re-uploading to gpu.
	Scale(dr image.Rectangle, src image.Image, sr image.Rectangle, rotateDeg float32, op draw.Op, unchanged bool)

	// Transform copies the given Go source image to the render target,
	// with the same semantics as golang.org/x/image/draw.Transform, with the
	// destination implicit in the Drawer target.
	//   - xform is the transform mapping source to destination coordinates.
	//   - src is the source image. Uniform does not work (or make sense) here.
	//   - sr is the source region, if zero full src is used; must have for Uniform.
	//   - op is the drawing operation: Src = copy source directly (blit),
	//     Over = alpha blend with existing.
	//   - unchanged should be true if caller knows that this image is unchanged
	//     from the last time it was used -- saves re-uploading to gpu.
	Transform(xform math32.Matrix3, src image.Image, sr image.Rectangle, op draw.Op, unchanged bool)

	// Renderer is the gpu device being drawn to.
	// Could be nil on unsupported devices (such as offscreen).
	Renderer() any
}

type DrawerBase struct {
	// Image is the target render image
	Image *image.RGBA
}

type NewWindowOptions struct {
	// Size specifies the dimensions of the new window, either in raw pixels
	// or std 96 dpi pixels depending on StdPixels. If Width or Height are
	// zero, a driver-dependent default will be used for each zero value
	// dimension
	Size image.Point

	// StdPixels means use standardized "pixel" units for the window size (96
	// per inch), not the actual underlying raw display dot pixels
	StdPixels bool

	// Pos specifies the position of the window, if non-zero -- always in
	// device-specific raw pixels
	Pos image.Point

	// Title specifies the window title.
	Title string

	// Icon specifies the window icon (see [Window.SetIcon] for more info).
	Icon []image.Image

	// Flags can be set using WindowFlags to request different types of windows
	Flags WindowFlags
}

type Platforms int32 //enums:enum

type Screen struct {
	// ScreenNumber is the index of this screen in the list of screens
	// maintained under Screen.
	ScreenNumber int

	// Geometry contains the geometry of the screen in window manager
	// size units, which may not be same as raw pixels (dots)
	Geometry image.Rectangle

	// DevicePixelRatio is a factor that scales the screen's
	// "natural" pixel coordinates into actual device pixels.
	// On OS-X, it is backingScaleFactor = 2.0 on "retina"
	DevicePixelRatio float32

	// PixSize is the number of actual pixels in the screen
	// (raw display dots), computed as Size * DevicePixelRatio
	PixSize image.Point

	// PhysicalSize is the actual physical size of the screen, in mm.
	PhysicalSize image.Point

	// LogicalDPI is the logical dots per inch of the screen,
	// which is used for all rendering.
	// It is: transient zoom factor * screen-specific multiplier * PhysicalDPI
	LogicalDPI float32

	// PhysicalDPI is the physical dots per inch of the screen,
	// for generating true-to-physical-size output.
	// It is computed as 25.4 * (PixSize.X / PhysicalSize.X)
	// where 25.4 is the number of mm per inch.
	PhysicalDPI float32

	// Color depth of the screen, in bits.
	Depth int

	// Refresh rate in Hz
	RefreshRate float32

	Orientation        ScreenOrientation
	NativeOrientation  ScreenOrientation
	PrimaryOrientation ScreenOrientation

	Name         string
	Manufacturer string
	Model        string
	SerialNumber string
}

type ScreenOrientation int32 //enums:enum

type Window interface {

	// Name returns the name of the window -- name is used strictly for
	// internal tracking and finding of windows -- see Title for the displayed
	// title of the window.
	Name() string

	// SetName sets the name of the window.
	SetName(name string)

	// Title returns the current title of the window, which is displayed in the GUI.
	Title() string

	// SetTitle sets the current title of the window, which is displayed in the GUI.
	SetTitle(title string)

	// SetIcon sets the icon of the window, which is displayed in the title bar
	// and taskbar on Windows. It takes a list of candidate images and uses the
	// one closest to the required size. Good sizes are 16x16, 32x32, and 48x48.
	SetIcon(images []image.Image)

	// Size returns the current size of the window, in raw underlying dots / pixels.
	// This includes any high DPI factors that may not be used in OS window sizing
	//  (see WinSize for that size).
	Size() image.Point

	// WinSize returns the current size of the window, in OS-specific window manager
	// units that may not include any high DPI factors.
	WinSize() image.Point

	// Position returns the current left-top position of the window relative to
	// underlying screen, in OS-specific window manager coordinates.
	Position() image.Point

	// RenderGeom returns the actual effective geometry of the window used
	// for rendering content, which may be different from {0, [Window.Size]}
	// due to insets caused by things like status bars and button overlays.
	RenderGeom() math32.Geom2DInt

	// SetWinSize sets the size of the window, in OS-specific window manager
	// units that may not include any high DPI factors (DevPixRatio)
	// (i.e., the same units as returned in WinSize())
	SetWinSize(sz image.Point)

	// SetSize sets the size of the window, in actual pixel units
	// (i.e., the same units as returned by Size())
	// Divides by DevPixRatio before calling SetWinSize.
	SetSize(sz image.Point)

	// SetPos sets the position of the window, in OS window manager
	// coordinates, which may be different from Size() coordinates
	// that reflect high DPI
	SetPos(pos image.Point)

	// SetGeom sets the position and size in one call -- use this if doing
	// both because sequential calls to SetPos and SetSize might fail on some
	// platforms.  Size is in actual pixel units (i.e., same units as returned by Size()),
	// and Pos is in OS-specific window manager units (i.e., as returned in Pos())
	SetGeom(pos image.Point, sz image.Point)

	// Raise requests that the window be at the top of the stack of windows,
	// and receive focus.  If it is iconified, it will be de-iconified.  This
	// is the only supported mechanism for de-iconifying.
	Raise()

	// Minimize requests that the window be iconified, making it no longer
	// visible or active -- rendering should not occur for minimized windows.
	Minimize()

	// PhysicalDPI is the physical dots per inch of the window, for generating
	// true-to-physical-size output, for example -- see the gi/units package for
	// translating into various other units.
	PhysicalDPI() float32

	// LogicalDPI returns the current logical dots-per-inch resolution of the
	// window, which should be used for most conversion of standard units --
	// physical DPI can be found in the Screen.
	LogicalDPI() float32

	// SetLogicalDPI sets the current logical dots-per-inch resolution of the
	// window, which should be used for most conversion of standard units --
	// physical DPI can be found in the Screen.
	SetLogicalDPI(dpi float32)

	// Screen returns the screen for this window, with all the relevant
	// information about its properties.
	Screen() *Screen

	// Flags returns the bit flags for this window's properties set according
	// to WindowFlags bits.
	Flags() WindowFlags

	// Is returns whether the window has the given flag.
	Is(flag WindowFlags) bool

	// IsClosed returns true if this window has been closed (but some threads
	// may have not received the news yet)
	IsClosed() bool

	// IsVisible returns true if this window is not closed or minimized and
	// there are active screens
	IsVisible() bool

	// SetCloseReqFunc sets the function that is called whenever there is a
	// request to close the window (via a OS or a call to CloseReq() method).  That
	// function can then adjudicate whether and when to actually call Close.
	SetCloseReqFunc(fun func(win Window))

	// SetCloseCleanFunc sets the function that is called whenever window is
	// actually about to close (irrevocably) -- can do any necessary
	// last-minute cleanup here.
	SetCloseCleanFunc(fun func(win Window))

	// CloseReq is a close request, triggered either by OS or user call (e.g.,
	// via Close menu action) -- calls function previously registered by
	// SetCloseReqFunc, which is then solely responsible for actually calling
	// Close.
	CloseReq()

	// CloseClean calls the function setup in SetCloseCleanFunc and does other
	// window cleanup -- called on way to closing.
	CloseClean()

	// Close requests that the window be closed. The behavior of the Window
	// after this, whether calling its methods or passing it as an argument,
	// is undefined.  See App.Quit methods to quit overall app.
	Close()

	// Sets the mouse position to given values
	SetMousePos(x, y float64)

	// Sets the mouse cursor to be enabled (true by default) or disabled (false).
	// If disabled, setting raw to true will enable raw mouse movement
	// which can provide better control in a game environment (not avail on Mac).
	SetCursorEnabled(enabled, raw bool)

	// IsCursorEnabled returns true or false if cursor is enabled
	IsCursorEnabled() bool

	// Drawer returns the drawing system attached to this window surface.
	// This is typically used for high-performance rendering to the surface.
	// Wrap access in Lock() / Unlock() calls.
	Drawer() Drawer

	// Lock attempts to grab the overall window Mutex lock
	// and returns true if the window is still open and ready for business.
	// Otherwise, it might have been closed and any further use should be
	// abandoned.  Do this before any use of window resources
	// (eg. rendering to the Drawer).
	Lock() bool

	// Unlock unlocks the Mutex.  Must be called after Lock() is done.
	Unlock()

	// SetDestroyGPUResourcesFunc sets the given function
	// that will be called on the main thread just prior
	// to destroying the drawer and surface.
	SetDestroyGPUResourcesFunc(f func())

	// SetFPS sets the frames per second for Paint events that drive
	// updating of the window at regular intervals.  60 is default.
	// 0 disables -- no regular Paint events are sent.
	// This only takes effect prior to opening a new window.
	SetFPS(fps int)

	// SetTitleBarIsDark sets whether the color theme of the window
	// title bar is dark (as opposed to light).
	SetTitleBarIsDark(isDark bool)

	// Events returns the [events.Source] for this window,
	// which manages all of the event sending.
	Events() *events.Source
}

type WindowFlags int64 //enums:bitflag