Display connection. More...

Data Structures
struct	display_t
	Opaque display structure. More...

Typedefs
typedef struct display	display_t

Functions
display_t *	display_new (void)
	Create a new display connection.

void	display_free (display_t *disp)
	Free a display connection.

bool	display_is_connected (display_t *disp)
	Check if the display connection is still connected.

void	display_disconnect (display_t *disp)
	Disconnect the display connection.

void *	display_cmd_alloc (display_t *disp, cmd_type_t type, uint64_t size)
	Allocate a section of the displays command buffer.

void	display_cmds_flush (display_t *disp)
	Flush the display's command buffer.

uint64_t	display_next (display_t disp, event_t event, clock_t timeout)
	Retrieve the next event from the display connection.

uint64_t	display_poll (display_t disp, pollfd_t fds, uint64_t nfds, clock_t timeout)
	Poll the display connection for events together with other file descriptors.

void	display_push (display_t disp, surface_id_t target, event_type_t type, void data, uint64_t size)
	Push an event to the display's internal event queue.

uint64_t	display_wait (display_t disp, event_t event, event_type_t expected)
	Wait for the display to receive an event of the expected type.

uint64_t	display_emit (display_t disp, surface_id_t target, event_type_t type, void data, uint64_t size)
	Emit an event to a target surface.

uint64_t	display_dispatch (display_t disp, const event_t event)
	Dispatch an event to the appropriate surface.

uint64_t	display_dispatch_pending (display_t *disp, event_type_t type, surface_id_t target)
	Dispatch all events currently in the display's internal event queue of a specific type and target.

uint64_t	display_subscribe (display_t *disp, event_type_t type)
	Subscribe to events of a specific type.

uint64_t	display_unsubscribe (display_t *disp, event_type_t type)
	Unsubscribe from events of a specific type.

uint64_t	display_get_surface_info (display_t disp, surface_id_t id, surface_info_t info)
	Get information about a surface.

uint64_t	display_set_focus (display_t *disp, surface_id_t id)
	Set the focus to a surface.

uint64_t	display_set_is_visible (display_t *disp, surface_id_t id, bool isVisible)
	Set the visibility of a surface.

uint64_t	display_get_screen (display_t disp, rect_t rect, uint64_t index)
	Get the rectangle of a screen.

Detailed Description

Display connection.

A display represents a connection to the Desktop Window Manager (DWM).

The display system IS thread safe, but the rest of the Patchwork library may not be. The display connection can thus be used to synchronize multiple threads when working with windows, etc.

There are two things of note for performance when using a display. First, commands are batched and sent together when display_cmds_flush() is called. Second, the display uses a internal pipe to store events that cant be processed immediately and this means that if a thread calls display_push() another thread blocking on display_next() will unblock since its blocking on both the displays DWM connection and the internal pipe.

Typedef Documentation

◆ display_t

typedef struct display display_t

Definition at line 39 of file display.h.

Function Documentation

◆ display_cmd_alloc()

void * display_cmd_alloc	(	display_t *	disp,
		cmd_type_t	type,
		uint64_t	size
	)

Allocate a section of the displays command buffer.

The display batches commands together in its command buffer, where each command is prefixed with a cmd_header_t and has a variable size.

Parameters

disp	The display connection.
type	Type of command to allocate.
size	Size of the command data to allocate.

Returns: Pointer to the allocated command data, or NULL on failure and errno is set.

Definition at line 173 of file display.c.

References cmd_buffer_t::amount, CMD_BUFFER_MAX_DATA, CMD_MAGIC, display_t::cmds, display_cmds_flush(), EINVAL, errno, cmd_header_t::magic, mtx_lock(), mtx_unlock(), display_t::mutex, NULL, cmd_header_t::size, cmd_buffer_t::size, and cmd_header_t::type.

Referenced by display_get_screen(), display_get_surface_info(), display_set_focus(), display_set_is_visible(), display_subscribe(), display_unsubscribe(), window_free(), window_invalidate_flush(), window_move(), window_new(), window_set_focus(), window_set_timer(), and window_set_visible().

◆ display_cmds_flush()

void display_cmds_flush ( display_t * disp )

Flush the display's command buffer.

This will send all queued commands to the DWM.

Parameters

disp	The display connection.

Definition at line 198 of file display.c.

References cmd_buffer_t::amount, display_t::cmds, display_t::data, data, display_t::isConnected, mtx_lock(), mtx_unlock(), display_t::mutex, offsetof, cmd_buffer_t::size, and write().

Referenced by display_cmd_alloc(), display_dispatch(), display_get_screen(), display_get_surface_info(), display_set_focus(), display_set_is_visible(), display_subscribe(), display_unsubscribe(), window_free(), window_invalidate_flush(), window_move(), window_new(), window_set_focus(), window_set_timer(), and window_set_visible().

◆ display_disconnect()

void display_disconnect ( display_t * disp )

Disconnect the display connection.

After calling this function, the display connection will be marked as disconnected and no further commands or events will be processed.

Will not free the display connection, use display_free() for that.

Parameters

disp	The display connection.

Definition at line 161 of file display.c.

References display_t::isConnected, mtx_lock(), mtx_unlock(), display_t::mutex, and NULL.

Referenced by display_next(), display_poll(), popup_procedure(), procedure(), and terminal_procedure().

◆ display_dispatch()

uint64_t display_dispatch	(	display_t *	disp,
		const event_t *	event
	)

Dispatch an event to the appropriate surface.

Will flush the display's command buffer after dispatching the event.

Parameters

disp	The display connection.
event	The event to dispatch.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 440 of file display.c.

References display_cmds_flush(), EINVAL, ERR, errno, display_t::isConnected, LIST_FOR_EACH_SAFE, mtx_lock(), mtx_unlock(), display_t::mutex, NULL, window_t::surface, SURFACE_ID_NONE, event_t::target, window_dispatch(), and display_t::windows.

Referenced by display_dispatch_pending(), display_emit(), main(), popup_open(), and terminal_loop().

◆ display_dispatch_pending()

uint64_t display_dispatch_pending	(	display_t *	disp,
		event_type_t	type,
		surface_id_t	target
	)

Dispatch all events currently in the display's internal event queue of a specific type and target.

Parameters

disp	The display connection.
type	The event type to check for.
target	The target surface ID for the events, if `SURFACE_ID_NONE` all events are dispatched.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 472 of file display.c.

References display_dispatch(), display_events_pipe_read(), display_events_pipe_write(), EINVAL, ERR, errno, display_t::eventsInPipe, mtx_lock(), mtx_unlock(), display_t::mutex, NULL, SURFACE_ID_NONE, event_t::target, and event_t::type.

Referenced by window_set_visible().

◆ display_emit()

uint64_t display_emit	(	display_t *	disp,
		surface_id_t	target,
		event_type_t	type,
		void *	data,
		uint64_t	size
	)

Emit an event to a target surface.

This function will construct an event and dispatch it to the target surface.

Parameters

disp	The display connection.
target	Target surface ID for the event, if `SURFACE_ID_NONE` the event is sent to all surfaces.
type	Type of event.
data	Pointer to the event data, can be `NULL` if `size` is `0`.
size	Size of the event data, must be less than `EVENT_MAX_DATA`.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 419 of file display.c.

References data, display_dispatch(), EINVAL, ERR, errno, EVENT_MAX_DATA, memcpy(), MIN, NULL, and event_t::target.

◆ display_free()

void display_free ( display_t * disp )

Free a display connection.

Parameters

disp	The display connection.

Definition at line 113 of file display.c.

References close(), display_t::ctl, display_t::data, display_t::eventsPipe, font_free(), display_t::fonts, free(), image, image_free(), display_t::images, LIST_FOR_EACH_SAFE, mtx_destroy(), display_t::mutex, NULL, window_free(), and display_t::windows.

Referenced by main(), and popup_open().

◆ display_get_screen()

uint64_t display_get_screen	(	display_t *	disp,
		rect_t *	rect,
		uint64_t	index
	)

Get the rectangle of a screen.

Parameters

disp	The display connection.
rect	Output pointer to store the rectangle of the screen.
index	Index of the screen to query, only `0` is supported currently.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 603 of file display.c.

References CMD_SCREEN_INFO, display_cmd_alloc(), display_cmds_flush(), display_wait(), EINVAL, ERR, errno, EVENT_SCREEN_INFO, event_screen_info_t::height, cmd_screen_info_t::index, NULL, RECT_INIT, event_t::screenInfo, and event_screen_info_t::width.

Referenced by main(), popup_open(), start_menu_new(), start_menu_open(), startmenu_procedure(), and taskbar_new().

◆ display_get_surface_info()

uint64_t display_get_surface_info	(	display_t *	disp,
		surface_id_t	id,
		surface_info_t *	info
	)

Get information about a surface.

Uses a CMD_SURFACE_REPORT command to request information about the specified surface from the DWM.

Parameters

disp	The display connection.
id	The surface ID to query.
info	Output pointer to store the surface information.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 547 of file display.c.

References CMD_SURFACE_REPORT, display_cmd_alloc(), display_cmds_flush(), display_wait(), EINVAL, ERR, errno, EVENT_REPORT, id, info, cmd_surface_report_t::isGlobal, mtx_unlock(), display_t::mutex, NULL, and cmd_surface_report_t::target.

◆ display_is_connected()

bool display_is_connected ( display_t * disp )

Check if the display connection is still connected.

Parameters

disp	The display connection.

Returns: true if connected, false otherwise.

Definition at line 148 of file display.c.

References display_t::isConnected, mtx_lock(), mtx_unlock(), display_t::mutex, and NULL.

Referenced by display_poll().

◆ display_new()

display_t * display_new ( void )

Create a new display connection.

Returns: On success, a The display connection. On failure, NULL and errno is set.

Definition at line 36 of file display.c.

References cmd_buffer_t::amount, close(), display_t::cmds, display_t::ctl, display_t::data, data, display_t::defaultFont, ENOMEM, ERR, errno, display_t::eventsInPipe, display_t::eventsPipe, font_free(), font_new(), display_t::fonts, free(), display_t::id, display_t::images, display_t::isConnected, list_init(), malloc(), MAX_NAME, memset(), mtx_init(), mtx_recursive, display_t::mutex, NULL, offsetof, open(), openf(), readfile(), cmd_buffer_t::size, thrd_error, display_t::windows, and writef().

Referenced by main(), and popup_open().

◆ display_next()

uint64_t display_next	(	display_t *	disp,
		event_t *	event,
		clock_t	timeout
	)

Retrieve the next event from the display connection.

Parameters

disp	The display connection.
event	Output pointer to store the retrieved event.
timeout	Maximum time to wait for an event, if `CLOCKS_NEVER` will wait indefinitely.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 213 of file display.c.

References display_t::data, display_disconnect(), display_events_pipe_read(), EINVAL, ENOTCONN, ERR, errno, ETIMEDOUT, display_t::eventsPipe, pollfd_t::fd, display_t::isConnected, mtx_lock(), mtx_unlock(), display_t::mutex, NULL, poll(), POLLERR, POLLIN, and read().

Referenced by main(), popup_open(), and terminal_loop().

◆ display_poll()

uint64_t display_poll	(	display_t *	disp,
		pollfd_t *	fds,
		uint64_t	nfds,
		clock_t	timeout
	)

Poll the display connection for events together with other file descriptors.

Parameters

disp	The display connection.
fds	Array of file descriptors to poll alongside the display connection.
nfds	Number of file descriptors in the array.
timeout	Maximum time to wait for an event, if `CLOCKS_NEVER` will wait indefinitely.

Returns: On success, number of file descriptors with events (not including the display connection). On failure, returns ERR and errno is set.

Definition at line 288 of file display.c.

References display_t::data, display_disconnect(), display_is_connected(), EINVAL, ENOMEM, ENOTCONN, ERR, errno, pollfd_t::events, display_t::eventsPipe, pollfd_t::fd, free(), malloc(), NULL, poll(), POLLERR, POLLIN, and pollfd_t::revents.

Referenced by terminal_loop().

◆ display_push()

void display_push	(	display_t *	disp,
		surface_id_t	target,
		event_type_t	type,
		void *	data,
		uint64_t	size
	)

Push an event to the display's internal event queue.

This will not send the event to the DWM, instead it will be stored in the display's internal event queue and can be retrieved using display_next().

Parameters

disp	The display connection.
target	Target surface ID for the event.
type	Type of event.
data	Pointer to the event data, can be `NULL` if `size` is `0`.
size	Size of the event data, must be less than `EVENT_MAX_DATA`.

Definition at line 349 of file display.c.

References data, display_events_pipe_write(), EVENT_MAX_DATA, memcpy(), MIN, mtx_lock(), mtx_unlock(), display_t::mutex, NULL, and event_t::target.

Referenced by button_send_action(), element_force_action(), element_redraw(), start_menu_close(), terminal_loop(), window_deco_action(), and window_dispatch().

◆ display_set_focus()

uint64_t display_set_focus	(	display_t *	disp,
		surface_id_t	id
	)

Set the focus to a surface.

Can apply to any surface, not just ones owned by the client.

Parameters

disp	The display connection.
id	The surface ID to set focus to.

Definition at line 574 of file display.c.

References CMD_SURFACE_FOCUS_SET, display_cmd_alloc(), display_cmds_flush(), ERR, id, cmd_surface_focus_set_t::isGlobal, mtx_unlock(), display_t::mutex, NULL, and cmd_surface_focus_set_t::target.

◆ display_set_is_visible()

uint64_t display_set_is_visible	(	display_t *	disp,
		surface_id_t	id,
		bool	isVisible
	)

Set the visibility of a surface.

Can apply to any surface, not just ones owned by the client.

Parameters

disp	The display connection.
id	The surface ID to set visibility for.
isVisible	Whether the surface should be visible.

Definition at line 588 of file display.c.

References CMD_SURFACE_VISIBLE_SET, display_cmd_alloc(), display_cmds_flush(), ERR, id, cmd_surface_visible_set_t::isGlobal, cmd_surface_visible_set_t::isVisible, NULL, and cmd_surface_visible_set_t::target.

Referenced by taskbar_procedure(), and window_deco_action().

◆ display_subscribe()

uint64_t display_subscribe	(	display_t *	disp,
		event_type_t	type
	)

Subscribe to events of a specific type.

Should only be used for events sent by the DWM.

Parameters

disp	The display connection.
type	The event type to subscribe to.

Definition at line 509 of file display.c.

References CMD_SUBSCRIBE, display_cmd_alloc(), display_cmds_flush(), EINVAL, ERR, errno, cmd_subscribe_t::event, mtx_unlock(), display_t::mutex, and NULL.

Referenced by taskbar_new().

◆ display_unsubscribe()

uint64_t display_unsubscribe	(	display_t *	disp,
		event_type_t	type
	)

Unsubscribe from events of a specific type.

Should only be used for events sent by the DWM.

Parameters

disp	The display connection.
type	The event type to unsubscribe from.

Definition at line 528 of file display.c.

References CMD_UNSUBSCRIBE, display_cmd_alloc(), display_cmds_flush(), EINVAL, ERR, errno, cmd_unsubscribe_t::event, mtx_unlock(), display_t::mutex, and NULL.

Referenced by main().

◆ display_wait()

uint64_t display_wait	(	display_t *	disp,
		event_t *	event,
		event_type_t	expected
	)

Wait for the display to receive an event of the expected type.

This function will block until an event of the expected type is received.

Any other events received while waiting will be pushed back to the display's internal event queue.

Parameters

disp	The display connection.
event	Output pointer to store the retrieved event.
expected	The expected event type to wait for.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 367 of file display.c.

References display_t::data, display_events_pipe_read(), display_events_pipe_write(), EINVAL, ERR, errno, display_t::eventsInPipe, display_t::isConnected, mtx_lock(), mtx_unlock(), display_t::mutex, NULL, read(), and event_t::type.

Referenced by display_get_screen(), display_get_surface_info(), and window_new().

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ display_t

Function Documentation

◆ display_cmd_alloc()

◆ display_cmds_flush()

◆ display_disconnect()

◆ display_dispatch()

◆ display_dispatch_pending()

◆ display_emit()

◆ display_free()

◆ display_get_screen()

◆ display_get_surface_info()

◆ display_is_connected()

◆ display_new()

◆ display_next()

◆ display_poll()

◆ display_push()

◆ display_set_focus()

◆ display_set_is_visible()

◆ display_subscribe()

◆ display_unsubscribe()

◆ display_wait()