ControlView

Whether to cache all controls’ contents as a bitmap.

This increases memory usage and reduces quality of controls in scaled scenarios, but reduces CPU usage when re-rendering controls that had no state change.

Can be overridden on a per-instance basis with ControlView.cacheAsBitmap.

A shared value that is inspected by all ControlView instances to control how big a cached bitmap can be, in case bitmap caching is enabled via ControlView.cacheAsBitmap or ControlView.globallyCacheAsBitmap.

When a control’s bounds exceed this value, the cache is erased and further render operations redraw the whole control until its bounds shrink a size smaller than this value.

May not take effect until the next time any control view attempts to resize its internal bitmap cache.

Defaults to UIIntSize(width: 4096, height: 4096).

Values set to be negative reset the value back to UIIntSize.zero and issues a runtime warning via ImagineUILogger.

Overrides the default ControlView.globallyCacheAsBitmap value with a specified boolean value. If nil, the global value is used, instead.

Bitmap caching only stores the contents produced by renderBackground() and renderForeground(), ignoring any subview content, and the size used is the size returned by boundsForRedraw().

Defaults to nil on creation.

Returns whether this control is the first responder on the responder chain associated with the current control system.

If no control system can be found for this view, this property should always returns false.

Returns whether this control view can become first responder, if requested.

Assigning first responder status to controls make it so that they are the first event handler for keyboard inputs.

Returns whether this control view can resign its first responder status.

Resigning first responder status resets the first responder chain back to the default state, and this control no longer receives keyboard events first.

Returns the next event handler on this control’s view hierarchy. By default, returns the first superview of ControlView type that is found, recursively.

Overrides default bounds handling to respond to resize events by issuing a resize event and clearing bitmap caches, if available.

Gets or sets whether this control is in a “selected” state.

Gets or sets whether this control is enabled.

The semantics of what happens when a control is enabled or disabled is implemented in a per-control basis, but control systems may use this property to decide whether to ignore this control when handling user interface events.

Gets or sets whether this control is in a highlighted state.

The semantics of a control that is highlighted is implemented on a per-control basis. For example, buttons and sliders might respond to mouse over events by enabling highlighting to change their display state to indicate they are responsive to mouse events.

Gets the internally computed control view state.

Control view states are calculated automatically based on self.isHighlighted, self.isEnabled, self.isHighlighted, and self.isFirstResponder, and the final state is computed by a priority checklist of states, setting the state based on the first condition on the following list that matches, and ignoring subsequent states:

1. If isEnabled == false, returns .disabled;
2. If isFirstResponder == true, returns .focused;
3. If isSelected == true, returns .selected;
4. If isHighlighted == true, returns .highlighted;
5. Otherwise, returns .normal.

If true, highlighted is automatically toggled on and off whenever the user enters and exits this control with the mouse.

Defaults to true.

If true, selected is automatically toggled on and off whenever the user holds down the mouse button on this control with the mouse.

Defaults to false.

This view’s neutral background color.

This view’s foreground color.

Corner radius for this control’s corners (does not affect clipping region).

Stroke color around the bounds of the control view.

Stroke width.

Event raised whenever a client requests that this view redraw itself on screen or to a buffer.

This event is raised after the view’s contents have been painted.

Event raised whenever this control view’s currentState value is changed

Event raised whenever this control view’s bounds have been updated to a different value

Event raised whenever the user clicks this control view while enabled.

Mouse location in event args is relative to the control view’s bounds.

Event raised whenever the user holds down on this control view with any mouse button.

Mouse location in event args is relative to the control view’s bounds.

Event raised whenever the user releases the mouse button they had held down previously on top of this control view.

Mouse location in event args is relative to the control view’s bounds.

Event raised whenever the user moves the mouse on top of this control view’s area.

Mouse location in event args is relative to the control view’s bounds.

Event raised when the user scrolls the mouse wheel while on top of this control.

Mouse location in event args is relative to the control view’s bounds.

Event raised whenever the user enters this control view’s area with the mouse cursor.

Event may be delayed by a control system if the mouse cursor is entered after a mouse button was held down while on top of a different control, being raised instantly as soon as the mouse button is released while on top of this control.

Event raised whenever the user leaves this control view’s area with the mouse cursor.

Event may be delayed by a control system if the mouse cursor exits after pressing a mouse button on top of this control, being raised instantly as soon as the mouse button is released while not on top of this control anymore.

Event raised whenever the user presses a keyboard key while this view is the currently active first responder

Event raised whenever the user presses a keyboard key while this view is the currently active first responder

Event raised whenever the user depresses a keyboard key while this view is the currently active first responder

Event raised whenever the user presses a keyboard key while this view is the currently active first responder

Controls whether the view should display a tooltip on mouse hover.

Gets the current tooltip value.

Gets a reference for the view that a tooltip should be located next to.

ControlView returns self by default.

Event called whenever the contents of the tooltip have been updated.

The preferred location to display tooltips from this control.

Defaults to PreferredTooltipLocation.systemDefined.

Gets the conditions under which a tooltip from this tooltip provider should be displayed.

Defaults to .always.

Preferred delay before a mouse hover event displays this control view’s tooltip.

Undocumented

Raises the resized event

Raises the stateChanged event

Paints this control view on a given render context

Renders this view’s background

Renders this view’s foreground content (not drawn on top of child views)

Returns a rectangle on this control view’s coordinate system that should be used for fill/stroke operations in renderBackground.

Defaults to self.bounds.

The bounds that this control view renders into, taking into account the current back/fore/stroke color configuration, self.strokerWidth and self.boundsForFillOrStroke() values.

Queries whether this control view can handle a given event request, passing the event request to self.next if it wishes not to handle the event.

This method is called initially by a control system while examining a control to respond to an event, and is passed along to self.next until either a control accepts the event via eventRequest.accept(handler:), or the end of the responder chain is reached (self.next == nil).

Returns whether this control can handle a specified event request.

By default, controls only respond to mouse events, except for mouse wheel, and ignore any other event type.

Can be overridden by a subclass to customize event handling behaviour.

Requests that this control view become first responder on the responder chain, returning whether the control is successfully a first responder after the method returns.

The control checks self.canBecomeFirstResponder and later requests that it be set as a first responder by an associated control system, returning false if it fails either query.

Requests that this control system resign its first responder status by requesting resignation from an associated control system.

Raises the mouseDown event.

Raises the mouseMoved event.

Raises the mouseUp event.

Raises the mouseEntered event.

Raises the mouseExited event.

Raises the mouseClicked event.

Raises the mouseWheelScrolled event.

Raises the keyPressed event.

Raises the keyDown event.

Raises the keyUp event

Raises the previewKeyDown event.

Returns the first control view under a given point on this control view.

Returns nil, if no control was found.

Returns the first control view under a given point on this control view which is willing to respond to a given event request.

Controls found are queried with ControlView.canHandle before being accepted.

Note: Controls should not accept the passed event request at the point of this query, as this is handled by the control system after que hit test query is completed.

Returns nil, if no control was found.

A value store that can store different values depending on the state of the control.

When requesting a value for a state that is not specified, the ControlViewState.normal‘s version of the value is returned. If that state is not present, the default type for T is finally returned, instead.