Introduction
PAL 2 consists of a number of components that allows the user to create windows and interact with the user system. These interfaces are designed to work cross-platform. But sometimes there are functions and settings that are so platform specific that these is no good cross-platform API for them. These settings can either be accessed through the ToolkitOptions class when calling Toolkit.Init(), or they are platform specific APIs that can be accessed through platform specific interfaces.
Platform specifc ToolkitOptions
The platform specific settings in TookitOptions can be accessed from the Windows, X11, MacOS members. The settings will only affect the current platform, so writing values for each platform is a convenient way to
ToolkitOptions options = new ToolkitOptions();
// Will only take effect when running on windows.
options.Windows.EnableVisualStyles = false;
// Will only take effect when running on macOS.
options.MacOS.ActiveAppOnStart = false;
Windows
ToolkitOptions.Windows.EnableVisualStyles
This setting decides if OpenTK should enable Visual Styles on initialization or not. Defaults to true. OpenTK requires Visual Styles to be enabled for the message box API to work. This option exists to allow Visual Styles to be enabled through a manifest file.
ToolkitOptions.Windows.IsDPIAware
This setting sets whether OpenTK will mark the process as DPI aware or not. Default is true. By setting this to false windows will scale your application up on high DPI monitors with a significant loss in image clarity, as such it is recommended to keep this property set to true.
Linux X11
There are no X11 specific ToolkitOptions at the moment.
macOS
ToolkitOptions.MacOS.ActiveAppOnStart
This setting decides if OpenTK should force the OpenTK application to become the currently active window on start. Default is true. Forcing the application to become the active application is not the "normal" application behavior on macOS but many developers expect their application to become the active one on start. Setting this setting depending on debug or release mode could be appropriate.
Platform specific APIs
Platform specific component APIs can be accessed by casting the component interface to it's concrete platform type. For example, Toolkit.Clipboard has windows specific settings related to cloud clipboard syncing and history, which can be accessed like follows:
// By using 'as' and ?. we can run this code on all platforms
// but the effects will only take effect on windows.
(Toolkit.Clipboard as Native.Windows.WindowComponent)?.CanUploadToCloudClipboard = false;
(Toolkit.Clipboard as Native.Windows.WindowComponent)?.CanIncludeInClipboardHistory = true;
Windows
The following is a list of windows specific settings and functions.
| Function | Description |
|---|---|
WindowComponent |
|
WindowComponent.GetHWND |
Gets the native Win32 HWND handle for the window. |
OpenGLComponent |
|
OpenGLComponent.UseDwmFlushIfApplicable |
Sets if SwapBuffers should call DwmFlush() to sync if DWM compositing is enabled. |
OpenGLComponent.GetHGLRC |
Gets the native Win32 HGLRC handle for the OpenGL context. |
DisplayComponent |
|
DisplayComponent.GetAdapter |
Gets the native Win32 adapter name (e.g. \\.\DISPLAY1) for the display handle. |
DisplayComponent.GetMonitor |
Gets the native Win32 monitor name (e.g. \\.\DISPLAY1\Monitor0) for the display handle. |
ShellComponent |
|
ShellComponent.SetImmersiveDarkMode |
Sets the DWMWA_USE_IMMERSIVE_DARK_MODE flag on the window causing the titlebar be rendered in dark mode colors. This is only officially supported from Window 11 Build 220000, but can sometimes work on Windows 10. |
ShellComponent.SetCaptionTextColor |
Used to set the text color in the windows titlebar. This is only officially supported from Window 11 Build 220000, but can sometimes work on Windows 10. |
ShellComponent.SetCaptionColor |
Used to set the color of the window titlebar. This is only officially supported from Window 11 Build 220000, but can sometimes work on Windows 10. |
ShellComponent.SetWindowCornerPreference |
Used to set the rounded corner preference on Windows 11. |
IconComponent |
|
IconComponent.CreateFromIcoFile |
Used to create an IconHandle from a .ico file. An icon created using this function will be able to dynamically pick resolution if the file contains multiple resolutions. |
IconComponent.CreateFromIcoResource(byte[]) |
Used to create an IconHandle from a .ico file embedded as a .resx resource. An Icon created using this function will not be able to dynamically pick resolution. |
IconComponent.CreateFromIcoResource(String) |
Used to create an IconHandle from a win32 embedded resource created using an .rc file and <Win32Resource>. |
IconComponent.GetBitmapData |
Allows for extracting icon data. Works with system icons. |
IconComponent.GetBitmapByteSize |
Returns the size in bytes of the bitmap data. For use with IconComponent.GetBitmapData. |
CursorComponent |
|
CursorComponent.CreateFromCurFile |
Used to create a CursorHandle from a .cur file. |
CursorComponent.CreateFromCurResorce(byte[]) |
Used to create a CursorHandle from a .cur file embedded in a .resx file. Does not support .ani files. |
CursorComponent.CreateFromCurResorce(String) |
Used to create a CursorHandle from a .cur file embedded in a .rc file and using <Win32Resource>. |
CursorComponent.GetImage |
Allows for extracting cursor data. Works with system cursors. |
ClipboardComponent |
|
ClipboardComponent.CanIncludeInClipboardHistory |
Toggles whether clipboard data set using SetClipboardText is allowed to be stored in the clipboard history. |
ClipboardComponent.CanUploadToCloudClipboard |
Toggles whether clipboard data set using SetClipboardText can be by synced between the users devices. |
ClipboardComponent.SetClipboardAudio |
Allows uploading audio data to the clipboard. Audio clipboard support is generally poorly supported by audio applications. |
ClipboardComponent.SetClipboardBitmap |
Allows uploading image data to the clipboard. |
Linux X11
The following is a list of linux x11 specific settings and functions.
| Function | Description |
|---|---|
WindowComponent |
|
X11WindowComponent.GetIconifiedTitle |
Gets the iconified window title. |
X11WindowComponent.SetIconifiedTitle |
Sets the iconified window title. |
X11WindowComponent.DemandAttention |
Shows a popup to the user that the window is ready. |
X11WindowComponent.GetX11Display |
Gets the X11 Display used by OpenTK. |
X11WindowComponent.GetX11Window |
Gets the X11 Window for this window handle. |
X11OpenGLComponent |
|
X11OpenGLComponent.EXT_swap_control_GetMaxSwapInterval |
Queries EXT_swap_control for the maximum supported swap interval. |
X11OpenGLComponent.GetGLXContext |
Get the GLX GLXContext for the OpenGL context. |
X11OpenGLComponent.GetGLXWindow |
Get the GLX GLXWindow for the OpenGL context. |
X11DisplayComponent |
|
X11DisplayComponent.GetRRCrtc |
Get the X11 RandR RRCrtc for the display handle. |
X11DisplayComponent.GetRROutput |
Get the X11 RandR RROutput for the display handle. |
X11IconComponent |
|
X11IconComponent.Create(int, int, IconImage[]) |
Used to create multi-resolution icons. |
macOS
The following is a list of macOS specific settings and functions.
| Function | Description |
|---|---|
MacOSWindowComponent |
|
MacOSWindowComponent.SetDockIcon |
Sets the dock icon of the application |
MacOSWindowComponent.SetFullscreenDisplayNoSpace |
Make the window fullscreen without creating a new space for the window. |
MacOSWindowComponent.GetNSWindow |
Gets the NSWindow of the window handle. This is an instance of the NSOpenTKWindow subclass of NSWindow. |
MacOSWindowComponent.GetNSView |
Gets the NSView of the window handle. This is an instance of the NSOpenTKView subclass of NSView. |
MacOSOpenGLComponent |
|
MacOSOpenGLComponent.GetNSOpenGLContext |
Gets the NSOpenGLContext of the OpenGL context handle. |
MacOSIconComponent |
|
MacOSIconComponent.CreateSFSymbol |
Creates a IconHandle from a SF symbol name. |
MacOSDisplayComponent |
|
MacOSDisplayComponent.GetSafeArea |
Gets the area of the screen that is not covered by things like camera housings. |
MacOSDisplayComponent.GetSafeLeftAuxArea |
Gets the visible area of the screen to the left of the camera housing or an empty area if there is no camera housing. |
MacOSDisplayComponent.GetSafeRightAuxArea |
Gets the visible area of the screen to the right of the camera housing or an empty area of there is no camera housing. |
MacOSDisplayComponent.GetDirectDisplayID |
Gets the CGDirectDisplayID for the display handle. |
MacOSCursorComponent |
|
MacOSCursorComponent.Create(Frame[] frames, float delay) |
Used to create an animated cursor. |
MacOSCursorComponent.IsAnimatedCursor |
Used to check if a given cursor is animated. |
MacOSCursorComponent.UpdateAnimation |
Used to update the animation of a given cursor. |
ANGLE
When using ANGLE to create OpenGL contexts ANGLEOpenGLComponent exposes a few ANGLE specific functions.
| Function | Description |
|---|---|
ANGLEOpenGLComponent |
|
ANGLEOpenGLComponent.GetEglDisplay |
Gets the EGLDisplay used by OpenTK. |
ANGLEOpenGLComponent.GetEglContext |
Gets the EGLContext for the OpenGL context. |
ANGLEOpenGLComponent.GetEglSurface |
Gets the EGLSurface for the OpenGL context. |