struct Espresso::WindowBuilder

Overview

Simplifies creation of windows with the numerous options (hints) available.

Included Modules

Extended Modules

Defined in:

espresso/window/window_builder.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new #

[View source]

Instance Method Detail

def accum_alpha_bits=(accum_alpha_bits : Int | Nil) #

Specifies the desired bit depths of the alpha component of the accumulation buffer. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).

Accumulation buffers are a legacy OpenGL feature and should not be used in new code.


[View source]
def accum_blue_bits=(accum_blue_bits : Int | Nil) #

Specifies the desired bit depths of the blue component of the accumulation buffer. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).

Accumulation buffers are a legacy OpenGL feature and should not be used in new code.


[View source]
def accum_green_bits=(accum_green_bits : Int | Nil) #

Specifies the desired bit depths of the green component of the accumulation buffer. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).

Accumulation buffers are a legacy OpenGL feature and should not be used in new code.


[View source]
def accum_red_bits=(accum_red_bits : Int | Nil) #

Specifies the desired bit depths of the red component of the accumulation buffer. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).

Accumulation buffers are a legacy OpenGL feature and should not be used in new code.


[View source]
def alpha_bits=(alpha_bits : Int | Nil) #

Specifies the desired bit depth of the alpha color component for the default framebuffer. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).


[View source]
def auto_iconify : self #

Specifies whether the full screen window will automatically iconify and restore the previous video mode on input focus loss. Possible values are true and false. This hint is ignored for windowed mode windows.


[View source]
def auto_iconify=(auto_iconify : Bool) #

Specifies whether the full screen window will automatically iconify and restore the previous video mode on input focus loss. Possible values are true and false. This hint is ignored for windowed mode windows.


[View source]
def aux_buffers=(aux_buffers : Int | Nil) #

Specifies the desired number of auxiliary buffers. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).

Auxiliary buffers are a legacy OpenGL feature and should not be used in new code.


[View source]
def blue_bits=(blue_bits : Int | Nil) #

Specifies the desired bit depth of the blue color component for the default framebuffer. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).


[View source]
def build(width : Int32, height : Int32, title : String, share : Window | Nil = nil) : Window #

Creates the window with all previously specified hints.

The width argument is the desired width, in screen coordinates, of the window. This must be greater than zero. The height argument is the desired height, in screen coordinates, of the window. This must be greater than zero. The title is the initial, UTF-8 encoded window title. The share argument is the window whose context to share resources with.

Possible errors that could be raised are: NotInitializedError, InvalidEnumError, InvalidValueError, APIUnavailableError, VersionUnavailableError, FormatUnavailableError, and PlatformError.


[View source]
def build(width : Int32, height : Int32, title : String, share : Window | Nil = nil, & : Window -> _) #

Creates the window with all previously specified hints. The window is yielded to the block and automatically destroyed when the block completes. Additionally, the window's context is made current on the calling thread.

The width argument is the desired width, in screen coordinates, of the window. This must be greater than zero. The height argument is the desired height, in screen coordinates, of the window. This must be greater than zero. The title is the initial, UTF-8 encoded window title. The share argument is the window whose context to share resources with.

Possible errors that could be raised are: NotInitializedError, InvalidEnumError, InvalidValueError, APIUnavailableError, VersionUnavailableError, FormatUnavailableError, and PlatformError.


[View source]
def build_full_screen(title : String, monitor : Monitor = Monitor.primary, share : Window | Nil = nil) : Window #

Creates the window as full screen with all previously specified hints.

The title is the initial, UTF-8 encoded window title. The monitor is the display device to place the fullscreen window on. The width and height specify the desired size of the window on the monitor.

Possible errors that could be raised are: NotInitializedError, InvalidEnumError, InvalidValueError, APIUnavailableError, VersionUnavailableError, FormatUnavailableError, and PlatformError.


[View source]
def build_full_screen(title : String, width : Int32, height : Int32, monitor : Monitor = Monitor.primary, share : Window | Nil = nil) : Window #

Creates the window as full screen with all previously specified hints.

The title is the initial, UTF-8 encoded window title. The monitor is the display device to place the fullscreen window on. The width and height specify the desired size of the window on the monitor. The share argument is the window whose context to share resources with.

Possible errors that could be raised are: NotInitializedError, InvalidEnumError, InvalidValueError, APIUnavailableError, VersionUnavailableError, FormatUnavailableError, and PlatformError.


[View source]
def build_full_screen(title : String, monitor : Monitor = Monitor.primary, share : Window | Nil = nil, & : Window -> _) #

Creates the window as full screen with all previously specified hints. The window is yielded to the block and automatically destroyed when the block completes. Additionally, the window's context is made current on the calling thread.

The title is the initial, UTF-8 encoded window title. The monitor is the display device to place the fullscreen window on. The share argument is the window whose context to share resources with.

The width and height of the window match the size of the monitor's current display mode.

Possible errors that could be raised are: NotInitializedError, InvalidEnumError, InvalidValueError, APIUnavailableError, VersionUnavailableError, FormatUnavailableError, and PlatformError.


[View source]
def build_full_screen(title : String, width : Int32, height : Int32, monitor : Monitor = Monitor.primary, share : Window | Nil = nil, & : Window -> _) #

Creates the window as full screen with all previously specified hints. The window is yielded to the block and automatically destroyed when the block completes. Additionally, the window's context is made current on the calling thread.

The title is the initial, UTF-8 encoded window title. The monitor is the display device to place the fullscreen window on. The width and height specify the desired size of the window on the monitor. The share argument is the window whose context to share resources with.

Possible errors that could be raised are: NotInitializedError, InvalidEnumError, InvalidValueError, APIUnavailableError, VersionUnavailableError, FormatUnavailableError, and PlatformError.


[View source]
def center_cursor : self #

Specifies whether the cursor should be centered over newly created full screen windows. Possible values are true and false. This hint is ignored for windowed mode windows.


[View source]
def center_cursor=(center_cursor : Bool) #

Specifies whether the cursor should be centered over newly created full screen windows. Possible values are true and false. This hint is ignored for windowed mode windows.


[View source]
def client_api=(client_api : Espresso::ClientAPI) #

Specifies which client API to create the context for. Possible values are in the ClientAPI enum. This is a hard constraint.


[View source]
def cocoa_frame_name=(cocoa_frame_name : String) #

Specifies the UTF-8 encoded name to use for autosaving the window frame, or if empty disables frame autosaving for the window. This is applicable only on macOS platforms.


[View source]
def cocoa_graphics_switching : self #

Specifies whether to in Automatic Graphics Switching, i.e. to allow the system to choose the integrated GPU for the OpenGL context and move it between GPUs if necessary or whether to force it to always run on the discrete GPU. This only affects systems with both integrated and discrete GPUs. Possible values are true and false. This is applicable only on macOS platforms.

Simpler programs and tools may want to enable this to save power, while games and other applications performing advanced rendering will want to leave it disabled.

A bundled application that wishes to participate in Automatic Graphics Switching should also declare this in its Info.plist by setting the NSSupportsAutomaticGraphicsSwitching key to true.


[View source]
def cocoa_graphics_switching=(cocoa_graphics_switching : Bool) #

Specifies whether to in Automatic Graphics Switching, i.e. to allow the system to choose the integrated GPU for the OpenGL context and move it between GPUs if necessary or whether to force it to always run on the discrete GPU. This only affects systems with both integrated and discrete GPUs. Possible values are true and false. This is applicable only on macOS platforms.

Simpler programs and tools may want to enable this to save power, while games and other applications performing advanced rendering will want to leave it disabled.

A bundled application that wishes to participate in Automatic Graphics Switching should also declare this in its Info.plist by setting the NSSupportsAutomaticGraphicsSwitching key to true.


[View source]
def cocoa_retina_framebuffer : self #

Specifies whether to use full resolution framebuffers on Retina displays. Possible values are true and false. This is applicable only on macOS platforms.


[View source]
def cocoa_retina_framebuffer=(cocoa_retina_framebuffer : Bool) #

Specifies whether to use full resolution framebuffers on Retina displays. Possible values are true and false. This is applicable only on macOS platforms.


[View source]
def context_creation_api=(context_creation_api : Espresso::ContextCreationAPI) #

Specifies which context creation API to use to create the context. Possible values are in the ContextCreationAPI enum. This is a hard constraint. If no client API is requested (via #client_api), this hint is ignored.

macOS: The EGL API is not available on this platform and requests to use it will fail.

Wayland: The EGL API is the native context creation API, so this hint will have no effect.

OSMesa: As its name implies, an OpenGL context created with OSMesa does not update the window contents when its buffers are swapped. Use OpenGL functions or the OSMesa native access functions glfwGetOSMesaColorBuffer and glfwGetOSMesaDepthBuffer to retrieve the framebuffer contents.


[View source]
def context_version(major : Int, minor : Int) : Nil #

Specifies the client API version that the created context must be compatible with. The exact behavior of these hints depend on the request client API.

OpenGL: These hints are not hard constraints, but creation will fail if the OpenGL version of the created context is less than the one requested. It is therefore perfectly safe to use the default of version 1.0 for legacy code and you will still get backwards-compatible contexts of version 3.0 and above when available.

While there is no way to ask the driver for a context of the highest supported version, GLFW will attempt to provide this when you ask for a version 1.0 context, which is the default for these hints.

OpenGL ES: These hints are not hard constraints, but creation will fail if the OpenGL ES version of the created context is less than the one requested. Additionally, OpenGL ES 1.x cannot be returned if 2.0 or later was requested, and vice versa. This is because OpenGL ES 3.x is backward compatible with 2.0, but OpenGL ES 2.0 is not backward compatible with 1.x.


[View source]
def debug : self #

Specifies whether to create a debug OpenGL context, which may have additional error and performance issue reporting functionality. Possible values are true and false. If OpenGL ES is requested, this hint is ignored.


[View source]
def debug=(debug : Bool) #

Specifies whether to create a debug OpenGL context, which may have additional error and performance issue reporting functionality. Possible values are true and false. If OpenGL ES is requested, this hint is ignored.


[View source]
def decorated : self #

Specifies whether the windowed mode window will have window decorations such as a border, a close widget, etc. An undecorated window will not be resizable by the user, but will still allow the user to generate close events on some platforms. Possible values are true and false. This hint is ignored for full screen windows.


[View source]
def decorated=(decorated : Bool) #

Specifies whether the windowed mode window will have window decorations such as a border, a close widget, etc. An undecorated window will not be resizable by the user, but will still allow the user to generate close events on some platforms. Possible values are true and false. This hint is ignored for full screen windows.


[View source]
def depth_bits=(depth_bits : Int | Nil) #

Specifies the desired bits used for the depth buffer of the default framebuffer. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).


[View source]
def double_buffer : self #

Specifies whether the framebuffer should be double buffered. You nearly always want to use double buffering. This is a hard constraint. Possible values are true and false.


[View source]
def double_buffer=(double_buffer : Bool) #

Specifies whether the framebuffer should be double buffered. You nearly always want to use double buffering. This is a hard constraint. Possible values are true and false.


[View source]
def floating : self #

Specifies whether the windowed mode window will be floating above other regular windows, also called topmost or always-on-top. This is intended primarily for debugging purposes and cannot be used to implement proper full screen windows. Possible values are true and false. This hint is ignored for full screen windows.


[View source]
def floating=(floating : Bool) #

Specifies whether the windowed mode window will be floating above other regular windows, also called topmost or always-on-top. This is intended primarily for debugging purposes and cannot be used to implement proper full screen windows. Possible values are true and false. This hint is ignored for full screen windows.


[View source]
def focus_on_show : self #

Specifies whether the window will be given input focus when Window#show is called. Possible values are true and false.


[View source]
def focus_on_show=(focus_on_show : Bool) #

Specifies whether the window will be given input focus when Window#show is called. Possible values are true and false.


[View source]
def focused : self #

Specifies whether the windowed mode window will be given input focus when created. Possible values are true and false. This hint is ignored for full screen and initially hidden windows.


[View source]
def focused=(focused : Bool) #

Specifies whether the windowed mode window will be given input focus when created. Possible values are true and false. This hint is ignored for full screen and initially hidden windows.


[View source]
def forward_compatible : self #

Specifies whether the OpenGL context should be forward-compatible, i.e. one where all functionality deprecated in the requested version of OpenGL is removed. This must only be used if the requested OpenGL version is 3.0 or above. If OpenGL ES is requested, this hint is ignored.


[View source]
def forward_compatible=(forward_compatible : Bool) #

Specifies whether the OpenGL context should be forward-compatible, i.e. one where all functionality deprecated in the requested version of OpenGL is removed. This must only be used if the requested OpenGL version is 3.0 or above. If OpenGL ES is requested, this hint is ignored.


[View source]
def green_bits=(green_bits : Int | Nil) #

Specifies the desired bit depth of the green color component for the default framebuffer. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).


[View source]
def initialize #

[View source]
def maximized : self #

Specifies whether the windowed mode window will be maximized when created. Possible values are true and false. This hint is ignored for full screen windows.


[View source]
def maximized=(maximized : Bool) #

Specifies whether the windowed mode window will be maximized when created. Possible values are true and false. This hint is ignored for full screen windows.


[View source]
def no_error : self #

Specifies whether errors should be generated by the context. Possible values are true and false. If enabled, situations that would have generated errors instead cause undefined behavior.


[View source]
def no_error=(no_error : Bool) #

Specifies whether errors should be generated by the context. Possible values are true and false. If enabled, situations that would have generated errors instead cause undefined behavior.


[View source]
def profile=(profile : Espresso::OpenGLProfile) #

Specifies which OpenGL profile to create the context for. Possible values are in the OpenGLProfile enum. If requesting an OpenGL version below 3.2, OpenGLProfile::Any must be used. If OpenGL ES is requested, this hint is ignored.


[View source]
def red_bits=(red_bits : Int | Nil) #

Specifies the desired bit depth of the red color component for the default framebuffer. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).


[View source]
def refresh_rate=(refresh_rate : Int | Nil) #

Specifies the desired refresh rate for full screen windows. A value of nil means the highest available refresh rate will be used. This hint is ignored for windowed mode windows.


[View source]
def release_behavior=(release_behavior : Espresso::ReleaseBehavior) #

Specifies the release behavior to be used by the context. Possible values are in the ReleaseBehavior enum.


[View source]
def resizable : self #

Specifies whether the windowed mode window will be resizable by the user. The window will still be resizable using the Window.size= setter. Possible values are true and false. This hint is ignored for full screen and undecorated windows.


[View source]
def resizable=(resizable : Bool) #

Specifies whether the windowed mode window will be resizable by the user. The window will still be resizable using the Window.size= setter. Possible values are true and false. This hint is ignored for full screen and undecorated windows.


[View source]
def robustness=(robustness : Espresso::ContextRobustness) #

Specifies the robustness strategy to be used by the context. This can be one of values from the ContextRobustness enum.


[View source]
def samples=(samples : Int | Nil) #

Specifies the desired number of samples to use for multisampling. Zero disables multisampling. A value of nil means the application has no preference (don't care).


[View source]
def scale_to_monitor : self #

Specifies whether the window content area should be resized based on the monitor content scale of any monitor it is placed on. This includes the initial placement when the window is created. Possible values are true and false.

This hint only has an effect on platforms where screen coordinates and pixels always map 1:1 such as Windows and X11. On platforms like macOS the resolution of the framebuffer is changed independently of the window size.


[View source]
def scale_to_monitor=(scale_to_monitor : Bool) #

Specifies whether the window content area should be resized based on the monitor content scale of any monitor it is placed on. This includes the initial placement when the window is created. Possible values are true and false.

This hint only has an effect on platforms where screen coordinates and pixels always map 1:1 such as Windows and X11. On platforms like macOS the resolution of the framebuffer is changed independently of the window size.


[View source]
def srgb_capable : self #

Specifies whether the framebuffer should be sRGB capable. Possible values are true and false.

OpenGL: If enabled and supported by the system, the GL_FRAMEBUFFER_SRGB enable will control sRGB rendering. By default, sRGB rendering will be disabled.

OpenGL ES: If enabled and supported by the system, the context will always have sRGB rendering enabled.


[View source]
def srgb_capable=(srgb_capable : Bool) #

Specifies whether the framebuffer should be sRGB capable. Possible values are true and false.

OpenGL: If enabled and supported by the system, the GL_FRAMEBUFFER_SRGB enable will control sRGB rendering. By default, sRGB rendering will be disabled.

OpenGL ES: If enabled and supported by the system, the context will always have sRGB rendering enabled.


[View source]
def stencil_bits=(stencil_bits : Int | Nil) #

Specifies the desired bits used for the stencil buffer of the default framebuffer. Possible values are non-negative integers and nil. Providing nil means the application has no preference (don't care).


[View source]
def stereo : self #

Specifies whether to use OpenGL stereoscopic rendering. Possible values are true and false. This is a hard constraint.


[View source]
def stereo=(stereo : Bool) #

Specifies whether to use OpenGL stereoscopic rendering. Possible values are true and false. This is a hard constraint.


[View source]
def transparent_framebuffer : self #

Specifies whether the window framebuffer will be transparent. If enabled and supported by the system, the window framebuffer alpha channel will be used to combine the framebuffer with the background. This does not affect window decorations. Possible values are true and false.


[View source]
def transparent_framebuffer=(transparent_framebuffer : Bool) #

Specifies whether the window framebuffer will be transparent. If enabled and supported by the system, the window framebuffer alpha channel will be used to combine the framebuffer with the background. This does not affect window decorations. Possible values are true and false.


[View source]
def visible : self #

Specifies whether the windowed mode window will be initially visible. Possible values are true and false. This hint is ignored for full screen windows.


[View source]
def visible=(visible : Bool) #

Specifies whether the windowed mode window will be initially visible. Possible values are true and false. This hint is ignored for full screen windows.


[View source]
def x11_class_name=(x11_class_name : String) #

Specifies the desired ASCII encoded class part the ICCCM WM_CLASS window property. This is applicable only on X11 platforms.


[View source]
def x11_instance_name=(x11_instance_name : String) #

Specifies the desired ASCII encoded instance part of the ICCCM WM_CLASS window property. This is applicable only on X11 platforms.


[View source]