#include <Pt/Forms/Widget.h>

Common type of every visual Forms object. More...

Inherited by Screen, View, and .

Public Member Functions
virtual	~Widget ()
	Releases pointer capture and peer associations.
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
	Widget ()
	Creates and registers a widget with the Forms application.
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 Widget *	onHitTest (const Gfx::PointF &pos)
	Returns the descendant hit at local position pos.
virtual Gfx::PointF	onToParent (const Gfx::PointF &pos) const =0
	Converts local position pos to parent coordinates.
virtual Gfx::PointF	onFromParent (const Gfx::PointF &pos) const =0
	Converts parent position pos to local coordinates.
virtual Gfx::PointF	onToGlobal (const Gfx::PointF &pos) const
	Converts local position pos to global coordinates.
virtual Gfx::PointF	onFromGlobal (const Gfx::PointF &pos) const
	Converts global position pos to local coordinates.
virtual void	onAttachPeer (Widget &peer)
	Attaches non-owning peer peer.
virtual void	onDetachPeer (Widget &peer)
	Detaches non-owning peer peer.
virtual void	onRequestRepaint (const Gfx::RectF &rect)
	Forwards a repaint request for local rectangle rect.
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	onProcessEvent (const Pt::Event &ev)
	Sends ev to the widget event dispatcher.
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	onProcessPaintEvent (const PaintEvent &ev)
	Filters and dispatches a paint event.
virtual void	onPaintEvent (const PaintEvent &ev)
	Handles a paint event with a non-empty dirty rectangle.
virtual void	onProcessRescaleEvent (const RescaleEvent &ev)
	Dispatches a rescale event.
virtual void	onRescaleEvent (const RescaleEvent &ev)
	Handles a rescale event.
virtual void	onRescale (double scaling)
	Updates the local scaling to scaling.
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	onShow (bool visible)
	Updates the local visibility state to visible.
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	onProcessResizeEvent (const ResizeEvent &ev)
	Dispatches a resize event.
virtual void	onResizeEvent (const ResizeEvent &ev)
	Updates the local size and bounds from a resize event.
virtual void	onProcessMouseEvent (const MouseEvent &ev)
	Updates pointer tracking and delivers a mouse event.
virtual void	onProcessTouchEvent (const TouchEvent &ev)
	Updates pointer tracking and delivers a touch event.
virtual void	onProcessScrollEvent (const ScrollEvent &ev)
	Delivers a scroll event through the responder chain.
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 void	onProcessKeyEvent (const KeyEvent &ev)
	Delivers a key event through the responder chain.
virtual Responder *	onNextResponder ()
	Returns the non-owning next responder, or 0.
virtual bool	onMouseEvent (const MouseEvent &ev)
	Handles a mouse event in local coordinates.
virtual bool	onTouchEvent (const TouchEvent &ev)
	Handles a touch event in local coordinates.
virtual bool	onScrollEvent (const ScrollEvent &ev)
	Handles a scroll event.
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	onKeyEvent (const KeyEvent &ev)
	Handles a key event.
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

Every visual Forms object is a Widget. Application is not. A widget supplies identity, screen connection, parent relationships, geometry, visibility, enabled state, scaling, coordinate conversion, repaint requests, event dispatch, and pointer capture. Derive ordinary visual content from Control. Derive directly from Widget only for a runtime or host base with its own parent coordinate system; derived classes must implement onToParent() and onFromParent().

Construct widgets only after an Application exists. The application gives each widget an ID, registers it for event routing, and removes that entry during destruction. A name is optional metadata, not an identifier. Parent and screen pointers are non-owning runtime relationships. A widget is connected when its parent hierarchy reaches a screen, independent of its visibility. Containers attach and detach widgets through their public APIs; callers keep attached widgets alive.

Geometry uses logical coordinates. position() is in parent coordinates, while size() and bounds() are local and bounds() starts at the local origin. toParent(), fromParent(), toGlobal(), and fromGlobal() convert between these systems. The default global conversion walks the parent chain. Coordinate hooks must agree with hit testing, painting, and input delivery.

show(), enable(), activate(), move(), and resize() are requests. A parent, frame, or backend confirms them by sending Forms events, which then update the observable state. Names, size limits, cursor overrides, and the next responder change local state immediately. invalidate() queues coalesced deferred work; repaint() asks to redraw a local dirty region.

A widget is a Responder. Unhandled input continues to the next responder, with mouse and touch coordinates converted locally.

Peers are non-hierarchical, bidirectional associations. They do not establish ownership, parenting, or screen connection. A widget can also provide a Cursor while it is under the pointer; clearing the override restores the default cursor.

Constructor & Destructor Documentation

◆ ~Widget()

virtual ~Widget ( )

virtual

The widget unregisters itself from the Forms application. It does not destroy a parent, screen, peer, or next responder.

Member Function Documentation

◆ setNextResponder()

void setNextResponder ( Responder * r )

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

◆ hitTest()

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

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

The default conversion walks the parent chain.

◆ fromGlobal()

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

The default conversion walks the parent chain.

◆ addPeer()

void addPeer ( Widget & peer )

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 )

Both endpoints receive onDetachPeer().

◆ invalidate()

void invalidate ( )

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 )

virtual

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

◆ show()

virtual void show ( bool b = true )

virtual

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

◆ enable()

virtual void enable ( bool isEnable = true )

virtual

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

◆ activate()

void activate ( bool active = true )

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

◆ move()

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

virtual

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

◆ minimumSize()

const Gfx::SizeF & minimumSize ( ) const

New widgets use (0, 0).

◆ setMinimumSize()

void setMinimumSize ( const Gfx::SizeF & s )

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

New widgets use (64000, 64000).

◆ setMaximumSize()

void setMaximumSize ( const Gfx::SizeF & s )

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 )

virtual

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

◆ setCapture()

void setCapture ( bool capture )

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

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

◆ setCursor()

void setCursor ( const Cursor * c )

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 )

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 ( )

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 )

protectedvirtual

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 )

protectedvirtual

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 ( )

protectedvirtual

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.

◆ onHitTest()

virtual Widget * onHitTest ( const Gfx::PointF & pos )

protectedvirtual

The base implementation returns 0. Derived containers define their child hit-testing order, visibility rules, and coordinate mapping.

Reimplemented in Control, Form, Screen, Window, Workspace, and WorkspaceManager.

◆ onToParent()

virtual Gfx::PointF onToParent ( const Gfx::PointF & pos ) const

protectedpure virtual

Every direct Widget subclass must implement this mapping.

Implemented in Control, Screen, Window, and WorkspaceManager.

◆ onFromParent()

virtual Gfx::PointF onFromParent ( const Gfx::PointF & pos ) const

protectedpure virtual

Every direct Widget subclass must implement this mapping.

Implemented in Control, Screen, Window, and WorkspaceManager.

◆ onToGlobal()

virtual Gfx::PointF onToGlobal ( const Gfx::PointF & pos ) const

protectedvirtual

The base implementation walks the parent chain through onToParent().

Implements Responder.

Reimplemented in Screen.

◆ onFromGlobal()

virtual Gfx::PointF onFromGlobal ( const Gfx::PointF & pos ) const

protectedvirtual

The base implementation walks the parent chain through onFromParent().

Implements Responder.

Reimplemented in Screen.

◆ onAttachPeer()

virtual void onAttachPeer ( Widget & peer )

protectedvirtual

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

Reimplemented in Popup.

◆ onDetachPeer()

virtual void onDetachPeer ( Widget & peer )

protectedvirtual

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 )

protectedvirtual

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 )

protectedvirtual

The base implementation calls onInvalidate().

Reimplemented in Control, Form, and Window.

◆ onInvalidate()

virtual void onInvalidate ( )

protectedvirtual

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.

◆ onProcessPaintEvent()

virtual void onProcessPaintEvent ( const PaintEvent & ev )

protectedvirtual

Empty dirty rectangles are ignored.

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

◆ onRescaleEvent()

virtual void onRescaleEvent ( const RescaleEvent & ev )

protectedvirtual

The base implementation calls onRescale() with the event scale.

Reimplemented in Control, Form, Label, Panel, PushButton, Screen, and Window.

◆ onShowEvent()

virtual void onShowEvent ( const ShowEvent & ev )

protectedvirtual

The base implementation calls onShow().

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

◆ onEnableEvent()

virtual void onEnableEvent ( const EnableEvent & ev )

protectedvirtual

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

Reimplemented in Control, Form, and Window.

◆ onMouseEvent()

virtual bool onMouseEvent ( const MouseEvent & ev )

protectedvirtual

Return true to consume it. Returning false forwards the original event to the next responder.

Reimplemented from Responder.

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

◆ onTouchEvent()

virtual bool onTouchEvent ( const TouchEvent & ev )

protectedvirtual

Return true to consume it. Returning false forwards the original event to the next responder.

Reimplemented from Responder.

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

◆ onScrollEvent()

virtual bool onScrollEvent ( const ScrollEvent & ev )

protectedvirtual

Return true to consume it; otherwise it is forwarded to the next responder.

Reimplemented from Responder.

Reimplemented in Button, Control, Form, ListBoxItem, Screen, ScrollLayout, and Window.

◆ onEnterEvent()

virtual bool onEnterEvent ( const EnterEvent & ev )

protectedvirtual

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 )

protectedvirtual

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.

◆ onKeyEvent()

virtual bool onKeyEvent ( const KeyEvent & ev )

protectedvirtual

Return true to consume it; otherwise it is forwarded to the next responder.

Reimplemented from Responder.

Reimplemented in ComboBox, Control, Form, LineEdit, Screen, 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

Constructor & Destructor Documentation

◆ ~Widget()

Member Function Documentation

◆ 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()

◆ onHitTest()

◆ onToParent()

◆ onFromParent()

◆ onToGlobal()

◆ onFromGlobal()

◆ onAttachPeer()

◆ onDetachPeer()

◆ onSetSizeLimits()

◆ onInvalidateEvent()

◆ onInvalidate()

◆ onProcessPaintEvent()

◆ onRescaleEvent()

◆ onShowEvent()

◆ onEnableEvent()

◆ onMouseEvent()

◆ onTouchEvent()

◆ onScrollEvent()

◆ onEnterEvent()

◆ onLeaveEvent()

◆ onKeyEvent()

◆ mouseEvent()

◆ touchEvent()