KWin::ScreenEdges Class Reference

Class for controlling screen edges. More...

#include <screenedge.h>

Inheritance diagram for KWin::ScreenEdges:

Public Slots
void	reconfigure ()
void	updateLayout ()
void	recreateEdges ()

Signals
void	approaching (ElectricBorder border, qreal factor, const QRect &geometry)
void	checkBlocking ()

Public Member Functions
	ScreenEdges ()
void	setConfig (KSharedConfig::Ptr config)
void	init ()
void	check (const QPoint &pos, const QDateTime &now, bool forceNoPushBack=false)
int	cornerOffset () const
void	reserve (ElectricBorder border, QObject *object, const char *callback)
void	unreserve (ElectricBorder border, QObject *object)
bool	reserve (KWin::Window *client, ElectricBorder border)
void	reserveTouch (ElectricBorder border, QAction *action, TouchCallback::CallbackFunction callback=nullptr)
void	unreserveTouch (ElectricBorder border, QAction *action)
void	reserveDesktopSwitching (bool isToReserve, Qt::Orientations o)
void	ensureOnTop ()
bool	isEntered (QMouseEvent *event)
QList< xcb_window_t >	windows () const
bool	isDesktopSwitching () const
bool	isDesktopSwitchingMovingClients () const
const QSize &	cursorPushBackDistance () const
int	timeThreshold () const
int	reActivationThreshold () const
ElectricBorderAction	actionTopLeft () const
ElectricBorderAction	actionTop () const
ElectricBorderAction	actionTopRight () const
ElectricBorderAction	actionRight () const
ElectricBorderAction	actionBottomRight () const
ElectricBorderAction	actionBottom () const
ElectricBorderAction	actionBottomLeft () const
ElectricBorderAction	actionLeft () const
ElectricBorderAction	actionForTouchBorder (ElectricBorder border) const
GestureRecognizer *	gestureRecognizer () const
bool	handleDndNotify (xcb_window_t window, const QPoint &point)
bool	handleEnterNotifiy (xcb_window_t window, const QPoint &point, const QDateTime &timestamp)
bool	remainActiveOnFullscreen () const
const std::vector< std::unique_ptr< Edge > > &	edges () const

Properties
bool	desktopSwitching
bool	desktopSwitchingMovingClients
QSize	cursorPushBackDistance
int	timeThreshold
int	reActivateThreshold
int	actionTopLeft
int	actionTop
int	actionTopRight
int	actionRight
int	actionBottomRight
int	actionBottom
int	actionBottomLeft
int	actionLeft

Detailed Description

Class for controlling screen edges.

The screen edge functionality is split into three parts:

• This manager class ScreenEdges
• abstract class Edge
• specific implementation of Edge, e.g. WindowBasedEdge

The ScreenEdges creates an Edge for each screen edge which is also an edge in the combination of all screens. E.g. if there are two screens, no Edge is created between the screens, but at all other edges even if the screens have a different dimension.

In addition at each corner of the overall display geometry an one-pixel large Edge is created. No matter how many screens there are, there will only be exactly four of these corner edges. This is motivated by Fitts's Law which show that it's easy to trigger such a corner, but it would be very difficult to trigger a corner between two screens (one pixel target not visually outlined).

The ScreenEdges are used for one of the following functionality:

• switch virtual desktop (see property desktopSwitching)
• switch virtual desktop when moving a window (see property desktopSwitchingMovingClients)
• trigger a pre-defined action (see properties actionTop and similar)
• trigger an externally configured action (e.g. Effect, Script, see reserve, unreserve)

An Edge is only active if there is at least one of the possible actions "reserved" for this edge. The idea is to not block the screen edge if nothing could be triggered there, so that the user e.g. can configure nothing on the top edge, which tends to interfere with full screen apps having a hidden panel there. On X11 (currently only supported backend) the Edge is represented by a WindowBasedEdge which creates an input only window for the geometry and reacts on enter notify events. If the edge gets reserved for the first time a window is created and mapped, once the edge gets unreserved again, the window gets destroyed.

When the mouse enters one of the screen edges the following values are used to determine whether the action should be triggered or the cursor be pushed back

• Time difference between two entering events is not larger than a certain threshold
• Time difference between two entering events is larger than timeThreshold
• Time difference between two activations is larger than reActivateThreshold
• Distance between two enter events is not larger than a defined pixel distance These checks are performed in Edge

Todo

change way how Effects/Scripts can reserve an edge and are notified.

Definition at line 221 of file screenedge.h.

Constructor & Destructor Documentation

ScreenEdges()

KWin::ScreenEdges::ScreenEdges ( )

explicit

Definition at line 771 of file screenedge.cpp.

Member Function Documentation

actionBottom()

ElectricBorderAction KWin::ScreenEdges::actionBottom

(

)

const

actionBottomLeft()

ElectricBorderAction KWin::ScreenEdges::actionBottomLeft

(

)

const

actionBottomRight()

ElectricBorderAction KWin::ScreenEdges::actionBottomRight

(

)

const

actionForTouchBorder()

ElectricBorderAction KWin::ScreenEdges::actionForTouchBorder

(

ElectricBorder

border

)

const

Definition at line 1255 of file screenedge.cpp.

actionLeft()

ElectricBorderAction KWin::ScreenEdges::actionLeft

(

)

const

actionRight()

ElectricBorderAction KWin::ScreenEdges::actionRight

(

)

const

actionTop()

ElectricBorderAction KWin::ScreenEdges::actionTop

(

)

const

actionTopLeft()

ElectricBorderAction KWin::ScreenEdges::actionTopLeft

(

)

const

actionTopRight()

ElectricBorderAction KWin::ScreenEdges::actionTopRight

(

)

const

approaching

void KWin::ScreenEdges::approaching ( ElectricBorder border, qreal factor, const QRect & geometry )

signal

Signal emitted during approaching of mouse towards border. The factor indicates how far away the mouse is from the approaching area. The values are clamped into [0.0,1.0] with 0.0 meaning far away from the border, 1.0 in trigger distance.

check()

void KWin::ScreenEdges::check	(	const QPoint &	pos,
		const QDateTime &	now,
		bool	forceNoPushBack = false )

Check, if a screen edge is entered and trigger the appropriate action if one is enabled for the current region and the timeout is satisfied

Parameters

pos	the position of the mouse pointer
now	the time when the function is called
forceNoPushBack	needs to be called to workaround some DnD clients, don't use unless you want to chek on a DnD event

Definition at line 1398 of file screenedge.cpp.

checkBlocking

void KWin::ScreenEdges::checkBlocking ( )

signal

cornerOffset()

int KWin::ScreenEdges::cornerOffset ( ) const

inline

The (dpi dependent) length, reserved for the active corners of each edge - 1/3"

Definition at line 539 of file screenedge.h.

cursorPushBackDistance()

const QSize & KWin::ScreenEdges::cursorPushBackDistance ( ) const

inline

Definition at line 544 of file screenedge.h.

edges()

const std::vector< std::unique_ptr< Edge > > & KWin::ScreenEdges::edges

(

)

const

Definition at line 1547 of file screenedge.cpp.

ensureOnTop()

void KWin::ScreenEdges::ensureOnTop

(

)

Raise electric border windows to the real top of the screen. We only need to do this if an effect input window is active.

Definition at line 1520 of file screenedge.cpp.

gestureRecognizer()

GestureRecognizer * KWin::ScreenEdges::gestureRecognizer ( ) const

inline

Definition at line 362 of file screenedge.h.

handleDndNotify()

bool KWin::ScreenEdges::handleDndNotify	(	xcb_window_t	window,
		const QPoint &	point )

Definition at line 1505 of file screenedge.cpp.

handleEnterNotifiy()

bool KWin::ScreenEdges::handleEnterNotifiy	(	xcb_window_t	window,
		const QPoint &	point,
		const QDateTime &	timestamp )

Definition at line 1466 of file screenedge.cpp.

init()

void KWin::ScreenEdges::init

(

)

Initialize the screen edges.

Definition at line 793 of file screenedge.cpp.

isDesktopSwitching()

bool KWin::ScreenEdges::isDesktopSwitching ( ) const

inline

Definition at line 549 of file screenedge.h.

isDesktopSwitchingMovingClients()

bool KWin::ScreenEdges::isDesktopSwitchingMovingClients ( ) const

inline

Definition at line 554 of file screenedge.h.

isEntered()

bool KWin::ScreenEdges::isEntered

(

QMouseEvent *

event

)

Definition at line 1423 of file screenedge.cpp.

reActivationThreshold()

int KWin::ScreenEdges::reActivationThreshold ( ) const

inline

Minimum time between triggers

Definition at line 559 of file screenedge.h.

reconfigure

void KWin::ScreenEdges::reconfigure ( )

slot

Definition at line 816 of file screenedge.cpp.

recreateEdges

void KWin::ScreenEdges::recreateEdges ( )

slot

Recreates all edges e.g. after the screen size changes.

Definition at line 1070 of file screenedge.cpp.

remainActiveOnFullscreen()

bool KWin::ScreenEdges::remainActiveOnFullscreen

(

)

const

Definition at line 1065 of file screenedge.cpp.

reserve() [1/2]

void KWin::ScreenEdges::reserve	(	ElectricBorder	border,
		QObject *	object,
		const char *	callback )

Mark the specified screen edge as reserved. This method is provided for external activation like effects and scripts. When the effect/script does no longer need the edge it is supposed to call unreserve.

Parameters

border	the screen edge to mark as reserved
object	The object on which the callback needs to be invoked
callback	The method name to be invoked - uses QMetaObject::invokeMethod

See also

unreserve

Todo

: add pointer to script/effect

Definition at line 1279 of file screenedge.cpp.

reserve() [2/2]

bool KWin::ScreenEdges::reserve	(	KWin::Window *	client,
		ElectricBorder	border )

Reserves an edge for the client. The idea behind this is to show the client if the screen edge which the client borders gets triggered.

When first called it is tried to create an Edge for the client. This is only done if the client borders with a screen edge specified by border. If the client doesn't border the screen edge, no Edge gets created and the client is shown again. Otherwise there would not be a possibility to show the client again.

On subsequent calls for the client no new Edge is created, but the existing one gets reused and if the client is already hidden, the Edge gets reserved.

Once the Edge for the client triggers, the client gets shown again and the Edge unreserved. The idea is that the Edge can only get activated if the client is currently hidden.

The Edge gets automatically destroyed if the client gets released.

Parameters

client	The Client for which an Edge should be reserved
border	The border which the client wants to use, only proper borders are supported (no corners)

Definition at line 1297 of file screenedge.cpp.

reserveDesktopSwitching()

void KWin::ScreenEdges::reserveDesktopSwitching	(	bool	isToReserve,
		Qt::Orientations	o )

Reserve desktop switching for screen edges, if isToReserve is true. Unreserve otherwise.

Parameters

isToReserve	indicated whether desktop switching should be reserved or unreseved
o	Qt orientations

Definition at line 1260 of file screenedge.cpp.

reserveTouch()

void KWin::ScreenEdges::reserveTouch	(	ElectricBorder	border,
		QAction *	action,
		TouchCallback::CallbackFunction	callback = nullptr )

Mark the specified screen edge as reserved for touch gestures. This method is provided for external activation like effects and scripts. When the effect/script does no longer need the edge it is supposed to call unreserveTouch.

Parameters

border	the screen edge to mark as reserved
action	The action which gets triggered

See also

unreserveTouch

Since

5.10

Definition at line 1312 of file screenedge.cpp.

setConfig()

void KWin::ScreenEdges::setConfig ( KSharedConfig::Ptr config )

inline

Definition at line 534 of file screenedge.h.

timeThreshold()

int KWin::ScreenEdges::timeThreshold ( ) const

inline

Minimum time between the push back of the cursor and the activation by re-entering the edge.

Definition at line 564 of file screenedge.h.

unreserve()

void KWin::ScreenEdges::unreserve	(	ElectricBorder	border,
		QObject *	object )

Mark the specified screen edge as unreserved. This method is provided for external activation like effects and scripts. This method is only allowed to be called if reserve had been called before for the same border. An unbalanced calling of reserve/unreserve leads to the edge never being active or never being able to deactivate again.

Parameters

border	the screen edge to mark as unreserved
object	the object on which the callback had been invoked

See also

reserve

Todo

: add pointer to script/effect

Definition at line 1288 of file screenedge.cpp.

unreserveTouch()

void KWin::ScreenEdges::unreserveTouch	(	ElectricBorder	border,
		QAction *	action )

Unreserves the specified border from activating the action for touch gestures.

See also

reserveTouch

Since

5.10

Definition at line 1321 of file screenedge.cpp.

updateLayout

void KWin::ScreenEdges::updateLayout ( )

slot

Updates the layout of virtual desktops and adjust the reserved borders in case of virtual desktop switching on edges.

Definition at line 935 of file screenedge.cpp.

windows()

QList< xcb_window_t > KWin::ScreenEdges::windows

(

)

const

Returns a QList of all existing screen edge windows

Returns

all existing screen edge windows in a QList

Definition at line 1525 of file screenedge.cpp.

Property Documentation

actionBottom

int KWin::ScreenEdges::actionBottom

read

Definition at line 234 of file screenedge.h.

actionBottomLeft

int KWin::ScreenEdges::actionBottomLeft

read

Definition at line 235 of file screenedge.h.

actionBottomRight

int KWin::ScreenEdges::actionBottomRight

read

Definition at line 233 of file screenedge.h.

actionLeft

int KWin::ScreenEdges::actionLeft

read

Definition at line 236 of file screenedge.h.

actionRight

int KWin::ScreenEdges::actionRight

read

Definition at line 232 of file screenedge.h.

actionTop

int KWin::ScreenEdges::actionTop

read

Definition at line 230 of file screenedge.h.

actionTopLeft

int KWin::ScreenEdges::actionTopLeft

read

Definition at line 229 of file screenedge.h.

actionTopRight

int KWin::ScreenEdges::actionTopRight

read

Definition at line 231 of file screenedge.h.

cursorPushBackDistance

QSize KWin::ScreenEdges::cursorPushBackDistance

read

Definition at line 226 of file screenedge.h.

desktopSwitching

bool KWin::ScreenEdges::desktopSwitching

read

Definition at line 224 of file screenedge.h.

desktopSwitchingMovingClients

bool KWin::ScreenEdges::desktopSwitchingMovingClients

read

Definition at line 225 of file screenedge.h.

reActivateThreshold

int KWin::ScreenEdges::reActivateThreshold

read

Definition at line 228 of file screenedge.h.

timeThreshold

int KWin::ScreenEdges::timeThreshold

read

Definition at line 227 of file screenedge.h.

---

The documentation for this class was generated from the following files:

• src/screenedge.h
• src/screenedge.cpp