#include <Pt/Forms/Screen.h>

Display root for top-level windows. More...

Inherits Widget.

Public Member Functions
	Screen (ApplicationImpl &app)
	Creates the screen and connects it to app.
virtual	~Screen ()
	Destructor.
void	addWindow (Window &w)
	Attaches w to this screen's window manager.
void	removeWindow (Window &w)
	Detaches w from this screen's window manager.
const std::vector< Window * > &	windows () const
	Returns the windows currently attached to this screen.
WindowManager &	windowManager ()
	Returns the window manager that presents this screen's windows.
Widget *	underPointer ()
	Returns the widget currently under the pointer, or null.
void	setPointer (Widget *widget)
	Makes widget the widget under the pointer.
void	setPointer (Widget &widget, bool isPointer)
	Sets or clears widget as the widget under the pointer.
ScreenImpl *	impl ()
	Returns the platform implementation backing this screen.
Pt::uint64_t	id () const
	Returns the application-unique ID of this live widget.
const std::string &	name () const
	Returns the optional name.
void	setName (const std::string &n)
	Sets the optional name immediately.
void	setNextResponder (Responder *r)
	Sets the next responder for unhandled input.
bool	isConnected () const
	Returns true when the widget is connected to a screen.
Screen *	screen ()
	Returns the connected screen, or 0 when disconnected.
const Screen *	screen () const
	Returns the connected screen, or 0 when disconnected.
Widget *	parent ()
	Returns the non-owning parent, or 0 when unparented.
const Widget *	parent () const
	Returns the non-owning parent, or 0 when unparented.
bool	isDescendantOf (const Widget &top) const
	Returns true when this widget is a strict descendant of top.
bool	isAncestorOf (const Widget &child) const
	Returns true when this widget is a strict ancestor of child.
Widget *	hitTest (const Gfx::PointF &pos)
	Returns the descendant hit at local position pos.
Gfx::PointF	toParent (const Gfx::PointF &pos) const
	Converts local position pos to parent coordinates.
Gfx::PointF	fromParent (const Gfx::PointF &pos) const
	Converts parent position pos to local coordinates.
Gfx::PointF	toGlobal (const Gfx::PointF &pos) const
	Converts local position pos to global coordinates.
Gfx::PointF	fromGlobal (const Gfx::PointF &pos) const
	Converts global position pos to local coordinates.
void	addPeer (Widget &peer)
	Adds a bidirectional, non-owning peer association with peer.
void	removePeer (Widget &peer)
	Removes the bidirectional peer association with peer.
void	invalidate ()
	Queues a coalesced invalidation.
virtual void	repaint (const Gfx::RectF &rect)
	Requests repainting local dirty rectangle rect.
virtual void	repaint ()
	Requests repainting the complete local bounds.
double	scaleFactor () const
	Returns the current logical-to-device scale factor.
const Gfx::Scaling &	scaling () const
	Returns the current logical-to-device scaling.
bool	isVisible () const
	Returns whether the last show event made the widget visible.
virtual void	show (bool b=true)
	Requests that the widget be shown or hidden.
bool	isEnabled () const
	Returns whether the last enable event made the widget enabled.
virtual void	enable (bool isEnable=true)
	Requests that the widget be enabled or disabled.
void	activate (bool active=true)
	Requests that the widget become active or inactive.
const Gfx::PointF &	position () const
	Returns the position in parent logical coordinates.
virtual void	move (const Gfx::PointF &pos)
	Requests a new parent-local position pos.
const Gfx::SizeF &	size () const
	Returns the size in local logical coordinates.
const Gfx::RectF &	bounds () const
	Returns local bounds, whose origin is always local zero.
const Gfx::SizeF &	minimumSize () const
	Returns the locally stored minimum size.
void	setMinimumSize (const Gfx::SizeF &s)
	Sets the local minimum size and notifies the size-limit hook.
void	setMinimumSize (double w, double h)
	Sets the local minimum width and height.
void	setMinimumWidth (double w)
	Sets the local minimum width.
void	setMinimumHeight (double h)
	Sets the local minimum height.
const Gfx::SizeF &	maximumSize () const
	Returns the locally stored maximum size.
void	setMaximumSize (const Gfx::SizeF &s)
	Sets the local maximum size and notifies the size-limit hook.
void	setMaximumSize (double w, double h)
	Sets the local maximum width and height.
void	setMaximumWidth (double w)
	Sets the local maximum width.
void	setMaximumHeight (double h)
	Sets the local maximum height.
virtual void	resize (const Gfx::SizeF &s)
	Requests a new local size s.
void	setCapture (bool capture)
	Requests pointer input capture or release.
const Cursor *	cursor () const
	Returns this widget's cursor or the default cursor.
void	setCursor (const Cursor *c)
	Sets a local cursor override.
void	processEvent (const Pt::Event &ev)
	Processes ev through this widget's event dispatcher.
Pt::Signal< const Pt::Event & > &	eventReceived ()
	Returns the event dispatcher signal.
bool	mouseEvent (const MouseEvent &ev)
	Delivers ev along the mouse responder chain.
void	touchEvent (const TouchEvent &ev)
	Delivers ev along the touch responder chain.
void	scrollEvent (const ScrollEvent &ev)
	Delivers ev along the scroll responder chain.
void	enterEvent (const EnterEvent &ev)
	Delivers ev along the enter responder chain.
void	leaveEvent (const LeaveEvent &ev)
	Delivers ev along the leave responder chain.
void	keyEvent (const KeyEvent &ev)
	Delivers ev along the key responder chain.

Protected Member Functions
virtual void	onInit (ScreenImpl &s)
	Called after the platform implementation s has connected.
virtual void	onRelease (ScreenImpl &s)
	Called before the platform implementation s disconnects.
virtual void	onResize (ScreenImpl &s, const Gfx::SizeF &size)
	Dispatches a ResizeEvent for a platform resize of s to size.
virtual void	onShow (ScreenImpl &s, bool isShow)
	Dispatches a ShowEvent for a platform visibility change of s.
virtual Widget *	onHitTest (const Gfx::PointF &pos)
	Finds the deepest widget at pos, or this screen if none.
virtual Gfx::PointF	onToParent (const Gfx::PointF &pos) const
	Returns pos unchanged; the screen has no parent.
virtual Gfx::PointF	onFromParent (const Gfx::PointF &pos) const
	Returns pos unchanged; the screen has no parent.
virtual Gfx::PointF	onToGlobal (const Gfx::PointF &pos) const
	Returns pos unchanged; screen coordinates are global.
virtual Gfx::PointF	onFromGlobal (const Gfx::PointF &pos) const
	Returns pos unchanged; screen coordinates are global.
virtual void	onProcessEvent (const Event &ev)
	Forwards ev to the base Widget event processing.
virtual void	onRequestRepaint (const Gfx::RectF &rect)
	Unifies rect into the pending update and schedules one paint pass.
virtual void	onProcessRescaleEvent (const RescaleEvent &ev)
	Forwards ev to the base Widget, then to the platform implementation.
virtual void	onRescaleEvent (const RescaleEvent &ev)
	Forwards ev to the base Widget event handling.
virtual void	onRescale (double scaling)
	Forwards scaling to the base Widget event handling.
virtual void	onProcessPaintEvent (const PaintEvent &ev)
	Forwards the last coalesced update in ev to the platform implementation.
virtual void	onPaintEvent (const PaintEvent &ev)
	Forwards ev to the base Widget, then calls onPaint().
virtual void	onPaint (const Gfx::RectF &rect)
	Extension point for painting rect; does nothing by default.
virtual void	onProcessResizeEvent (const ResizeEvent &ev)
	Forwards ev to the base Widget, then to the platform implementation.
virtual void	onResizeEvent (const ResizeEvent &ev)
	Forwards ev to the base Widget event handling.
virtual void	onProcessMouseEvent (const MouseEvent &ev)
	Forwards ev to the platform implementation for hit-test routing.
virtual void	onProcessTouchEvent (const TouchEvent &ev)
	Forwards ev to the platform implementation for hit-test routing.
virtual void	onProcessScrollEvent (const ScrollEvent &ev)
	Routes ev to the widget under the pointer, or to the platform implementation.
virtual void	onProcessKeyEvent (const KeyEvent &ev)
	Forwards ev to the platform implementation for routing to the focused widget.
virtual bool	onMouseEvent (const MouseEvent &ev)
	Forwards ev to the base Widget responder chain.
virtual bool	onTouchEvent (const TouchEvent &ev)
	Forwards ev to the base Widget responder chain.
virtual bool	onScrollEvent (const ScrollEvent &ev)
	Forwards ev to the base Widget responder chain.
virtual bool	onKeyEvent (const KeyEvent &ev)
	Forwards ev to the base Widget responder chain.
virtual void	onShow (bool visible)
	Updates the local visibility state to visible.
virtual void	onSetParent (Widget *parent)
	Records the non-owning parent relationship.
virtual void	onConnect (Screen &screen)
	Records connection to screen.
virtual void	onDisconnect ()
	Clears the screen connection.
virtual void	onAttachPeer (Widget &peer)
	Attaches non-owning peer peer.
virtual void	onDetachPeer (Widget &peer)
	Detaches non-owning peer peer.
virtual void	onRequestShow (bool e)
	Forwards a request to show or hide the widget.
virtual void	onRequestEnable (bool isEnable)
	Forwards a request to enable or disable the widget.
virtual void	onRequestActivate (bool active)
	Forwards a request to activate or deactivate the widget.
virtual void	onRequestMove (const Gfx::PointF &pos)
	Forwards a request for parent-local position pos.
virtual void	onSetSizeLimits (const Gfx::SizeF &minSize, const Gfx::SizeF &maxSize)
	Notifies that locally stored size limits changed.
virtual void	onRequestResize (const Gfx::SizeF &s)
	Forwards a request for local size s.
virtual void	onRequestCapture (bool capture)
	Requests application-managed pointer capture or release.
virtual void	onProcessInvalidateEvent (const InvalidateEvent &ev)
	Coalesces and dispatches an invalidation event.
virtual void	onInvalidateEvent (const InvalidateEvent &ev)
	Handles the final coalesced invalidation event.
virtual void	onInvalidate ()
	Updates derived state after invalidation.
virtual void	onProcessShowEvent (const ShowEvent &ev)
	Ignores redundant show events and dispatches other ones.
virtual void	onShowEvent (const ShowEvent &ev)
	Handles a show event.
virtual void	onProcessEnableEvent (const EnableEvent &ev)
	Dispatches an enable event.
virtual void	onEnableEvent (const EnableEvent &ev)
	Updates the enabled state and handles an enable event.
virtual void	onEnable (bool e)
	Performs behavior associated with enabled state e.
virtual void	onProcessMoveEvent (const MoveEvent &ev)
	Dispatches a move event.
virtual void	onMoveEvent (const MoveEvent &ev)
	Updates the parent-local position from a move event.
virtual void	onProcessEnterEvent (const EnterEvent &ev)
	Delivers an enter event through the responder chain.
virtual void	onProcessLeaveEvent (const LeaveEvent &ev)
	Delivers a leave event through the responder chain.
virtual Responder *	onNextResponder ()
	Returns the non-owning next responder, or 0.
virtual bool	onEnterEvent (const EnterEvent &ev)
	Handles pointer entry and installs the widget cursor.
virtual bool	onLeaveEvent (const LeaveEvent &ev)
	Handles pointer leave and restores the default cursor.
virtual bool	onMousePress (const MouseEvent &ev)
	Handles a mouse press. The default returns false.
virtual bool	onMouseRelease (const MouseEvent &ev)
	Handles a mouse release. The default returns false.
virtual bool	onMouseMove (const MouseEvent &ev)
	Handles a mouse move. The default returns false.

Detailed Description

A Screen is the runtime root for the top-level windows on one display. Application provides the primary screen and connects it to the platform. The screen tracks attached Window objects, routes input to the widget below the pointer, and requests drawing of changed regions. Applications normally use the screen through Application::screen() rather than creating one directly.

A screen provides the top-level WindowManager for its display. Showing an unparented Window attaches it through that manager. The manager and screen use non-owning relationships to the windows, so the application must keep every attached window alive and detach it before destruction. Use a Workspace when an application needs a window manager within a control instead of another platform display.

Screen coordinates are global Forms coordinates. The screen hit-tests windows and their content to choose the input target. When that target changes, setPointer() delivers a leave event to the old widget before an enter event is delivered to the new one. Pointer capture and transient popups can override normal hit-test routing through Application.

Repaint requests from the hierarchy reach the screen as dirty rectangles. The screen combines pending rectangles and schedules one paint pass, then passes the resulting update to the platform implementation. Screen is a backend extension point; applications should use its window manager and should not call its protected event and platform hooks.

Member Function Documentation

◆ setPointer() [1/2]

void setPointer ( Widget * widget )

Sends a leave event to the previous widget under the pointer, if any, then makes widget the new one and sends it an enter event. Pass null to clear the widget under the pointer.

◆ setPointer() [2/2]

void setPointer	(	Widget &	widget,
		bool	isPointer )

Equivalent to calling setPointer(&widget) when isPointer is true, or clearing the widget under the pointer when it is widget and isPointer is false.

◆ impl()

ScreenImpl * impl ( )

Intended for backend and platform implementation code, not for application use.

◆ onRequestRepaint()

virtual void onRequestRepaint ( const Gfx::RectF & rect )

protectedvirtual

Accumulated rectangles from repeated calls are merged into a single dirty area, and a PaintEvent is committed to the application loop for each call. onProcessPaintEvent() later collapses the resulting coalesced events into one paint pass.

Reimplemented from Widget.

◆ onProcessPaintEvent()

virtual void onProcessPaintEvent ( const PaintEvent & ev )

protectedvirtual

Every onRequestRepaint() call commits one event to the loop, but only the last of a batch of coalesced events reaches this method with pending updates; earlier ones are skipped here.

Reimplemented from Widget.

◆ onProcessScrollEvent()

virtual void onProcessScrollEvent ( const ScrollEvent & ev )

protectedvirtual

Unlike other input events, a scroll event bypasses the platform hit test when a widget is currently under the pointer.

Reimplemented from Widget.

◆ setNextResponder()

void setNextResponder ( Responder * r )

inherited

The widget does not own r. Do not create a responder cycle.

◆ hitTest()

Widget * hitTest ( const Gfx::PointF & pos )

inherited

Returns 0 when no descendant is hit. Derived classes implement their child hit-testing policy in onHitTest().

◆ toGlobal()

Gfx::PointF toGlobal ( const Gfx::PointF & pos ) const

inherited

The default conversion walks the parent chain.

◆ fromGlobal()

Gfx::PointF fromGlobal ( const Gfx::PointF & pos ) const

inherited

The default conversion walks the parent chain.

◆ addPeer()

void addPeer ( Widget & peer )

inherited

Peers are not a parent, child, or screen connection and do not transfer ownership. Add a relationship only once. Both endpoints receive onAttachPeer().

◆ removePeer()

void removePeer ( Widget & peer )

inherited

Both endpoints receive onDetachPeer().

◆ invalidate()

void invalidate ( )

inherited

The Forms event loop eventually calls onInvalidateEvent() after all pending invalidation requests for this widget have coalesced.

◆ repaint()

virtual void repaint ( const Gfx::RectF & rect )

virtualinherited

The containing view, frame, or backend converts and forwards the rectangle. This does not paint synchronously.

◆ show()

virtual void show ( bool b = true )

virtualinherited

isVisible() changes only when the request is confirmed by a ShowEvent.

◆ enable()

virtual void enable ( bool isEnable = true )

virtualinherited

isEnabled() changes only when the request is confirmed by an EnableEvent.

◆ activate()

void activate ( bool active = true )

inherited

Activation is defined by the receiving parent, frame, or backend.

◆ move()

virtual void move ( const Gfx::PointF & pos )

virtualinherited

position() changes only when a MoveEvent confirms the request.

◆ minimumSize()

const Gfx::SizeF & minimumSize ( ) const

inherited

New widgets use (0, 0).

◆ setMinimumSize()

void setMinimumSize ( const Gfx::SizeF & s )

inherited

This does not resize the widget or validate it against the maximum size. The receiver of onSetSizeLimits() applies the limits.

◆ maximumSize()

const Gfx::SizeF & maximumSize ( ) const

inherited

New widgets use (64000, 64000).

◆ setMaximumSize()

void setMaximumSize ( const Gfx::SizeF & s )

inherited

This does not resize the widget or validate it against the minimum size. The receiver of onSetSizeLimits() applies the limits.

◆ resize()

virtual void resize ( const Gfx::SizeF & s )

virtualinherited

size() and bounds() change only when a ResizeEvent confirms the request.

◆ setCapture()

void setCapture ( bool capture )

inherited

Capture is owned by the application and routes pointer input to this widget until released. It is released during destruction.

◆ cursor()

const Cursor * cursor ( ) const

inherited

The returned cursor is always non-null and is owned by the widget or the Forms runtime.

◆ setCursor()

void setCursor ( const Cursor * c )

inherited

Pass 0 to remove the override and restore the default cursor. The cursor is copied, so the caller retains ownership of c. When this widget is under the pointer, the platform cursor is updated immediately.

◆ processEvent()

void processEvent ( const Pt::Event & ev )

inherited

Use the state-request APIs for ordinary operation. This method is for backends, tests, and code that deliberately injects events.

◆ eventReceived()

Pt::Signal< const Pt::Event & > & eventReceived ( )

inherited

Internal event-processing slots are connected to this signal. Additional slots can observe or process deliberately dispatched widget events.

◆ onSetParent()

virtual void onSetParent ( Widget * parent )

protectedvirtualinherited

Container classes call this while attaching or detaching the widget. Overrides that retain the base relationship must call this implementation.

◆ onConnect()

virtual void onConnect ( Screen & screen )

protectedvirtualinherited

A container calls this when the hierarchy joins a screen. Overrides that retain the base connection state must call this implementation.

Reimplemented in Control, Form, Label, View, Window, WindowManager, Workspace, and WorkspaceManager.

◆ onDisconnect()

virtual void onDisconnect ( )

protectedvirtualinherited

A container calls this when the hierarchy leaves its screen. Overrides that retain the base connection state must call this implementation.

Reimplemented in Control, Form, View, Window, WindowManager, Workspace, and WorkspaceManager.

◆ onAttachPeer()

virtual void onAttachPeer ( Widget & peer )

protectedvirtualinherited

The base implementation stores the peer. Overrides that retain the association must call this implementation.

Reimplemented in Popup.

◆ onDetachPeer()

virtual void onDetachPeer ( Widget & peer )

protectedvirtualinherited

The base implementation removes one stored association. Overrides that retain the association must call this implementation.

Reimplemented in Popup.

◆ onSetSizeLimits()

virtual void onSetSizeLimits	(	const Gfx::SizeF &	minSize,
		const Gfx::SizeF &	maxSize )

protectedvirtualinherited

The base implementation does nothing. A parent, frame, or backend can apply minSize and maxSize to its geometry policy.

Reimplemented in Control, and Window.

◆ onInvalidateEvent()

virtual void onInvalidateEvent ( const InvalidateEvent & ev )

protectedvirtualinherited

The base implementation calls onInvalidate().

Reimplemented in Control, Form, and Window.

◆ onInvalidate()

virtual void onInvalidate ( )

protectedvirtualinherited

The base implementation clears pending invalidation bookkeeping.

Reimplemented in CheckBox, ComboBox, Control, Form, Label, LineEdit, ListBox, ListBoxItem, Menu, MenuBar, MenuItemBase, Panel, ProgressBar, PushButton, ScrollBar, Slider, SpinBox, SpinBoxButton, TabView, and Window.

◆ onShowEvent()

virtual void onShowEvent ( const ShowEvent & ev )

protectedvirtualinherited

The base implementation calls onShow().

Reimplemented in Control, Form, Menu, Popup, and Window.

◆ onEnableEvent()

virtual void onEnableEvent ( const EnableEvent & ev )

protectedvirtualinherited

The base implementation updates isEnabled() before calling onEnable().

Reimplemented in Control, Form, and Window.

◆ onEnterEvent()

virtual bool onEnterEvent ( const EnterEvent & ev )

protectedvirtualinherited

The base implementation consumes the event. Override and return false only when it should continue through the responder chain.

Reimplemented from Responder.

Reimplemented in Button, ComboBox, Control, Form, LineEdit, ListBoxItem, Menu, MenuItemBase, ScrollBar, Slider, SpinBox, and Window.

◆ onLeaveEvent()

virtual bool onLeaveEvent ( const LeaveEvent & ev )

protectedvirtualinherited

The base implementation consumes the event. Override and return false only when it should continue through the responder chain.

Reimplemented from Responder.

Reimplemented in Button, ComboBox, Control, Form, LineEdit, ListBoxItem, Menu, MenuItemBase, ScrollBar, Slider, SpinBox, and Window.

◆ mouseEvent()

bool mouseEvent ( const MouseEvent & ev )

inherited

Converts the position to each responder's local coordinates. Returns true when a responder handles the event.

◆ touchEvent()

void touchEvent ( const TouchEvent & ev )

inherited

Converts the position to each responder's local coordinates.

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ setPointer() [1/2]

◆ setPointer() [2/2]

◆ impl()

◆ onRequestRepaint()

◆ onProcessPaintEvent()

◆ onProcessScrollEvent()

◆ setNextResponder()

◆ hitTest()

◆ toGlobal()

◆ fromGlobal()

◆ addPeer()

◆ removePeer()

◆ invalidate()

◆ repaint()

◆ show()

◆ enable()

◆ activate()

◆ move()

◆ minimumSize()

◆ setMinimumSize()

◆ maximumSize()

◆ setMaximumSize()

◆ resize()

◆ setCapture()

◆ cursor()

◆ setCursor()

◆ processEvent()

◆ eventReceived()

◆ onSetParent()

◆ onConnect()

◆ onDisconnect()

◆ onAttachPeer()

◆ onDetachPeer()

◆ onSetSizeLimits()

◆ onInvalidateEvent()

◆ onInvalidate()

◆ onShowEvent()

◆ onEnableEvent()

◆ onEnterEvent()

◆ onLeaveEvent()

◆ mouseEvent()

◆ touchEvent()