element.h File Reference

#include <libbase/libbase.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <wayland-server-core.h>
#include <xkbcommon/xkbcommon.h>
#include <wlr/util/box.h>
#include "input.h"
#include <wlr/types/wlr_pointer.h>

Include dependency graph for element.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	wlmtk_element_events_t
struct	_wlmtk_element_vmt_t
struct	_wlmtk_element_t
struct	wlmtk_fake_element_t

Typedefs
typedef struct _wlmtk_element_t	wlmtk_element_t
typedef struct _wlmtk_element_vmt_t	wlmtk_element_vmt_t

Functions
bool	wlmtk_element_init (wlmtk_element_t *element_ptr)
wlmtk_element_vmt_t	wlmtk_element_extend (wlmtk_element_t *element_ptr, const wlmtk_element_vmt_t *element_vmt_ptr)
void	wlmtk_element_fini (wlmtk_element_t *element_ptr)
bs_dllist_node_t *	wlmtk_dlnode_from_element (wlmtk_element_t *element_ptr)
wlmtk_element_t *	wlmtk_element_from_dlnode (bs_dllist_node_t *dlnode_ptr)
void	wlmtk_element_set_parent_container (wlmtk_element_t *element_ptr, wlmtk_container_t *parent_container_ptr)
void	wlmtk_element_attach_to_scene_graph (wlmtk_element_t *element_ptr)
void	wlmtk_element_set_visible (wlmtk_element_t *element_ptr, bool visible)
void	wlmtk_element_get_position (wlmtk_element_t *element_ptr, int *x_ptr, int *y_ptr)
void	wlmtk_element_set_position (wlmtk_element_t *element_ptr, int x, int y)
static void	wlmtk_element_get_dimensions (wlmtk_element_t *element_ptr, int *left_ptr, int *top_ptr, int *right_ptr, int *bottom_ptr)
static struct wlr_box	wlmtk_element_get_dimensions_box (wlmtk_element_t *element_ptr)
bool	wlmtk_element_pointer_motion (wlmtk_element_t *element_ptr, wlmtk_pointer_motion_event_t *pointer_motion_ptr)
bool	wlmtk_element_pointer_button (wlmtk_element_t *element_ptr, const wlmtk_button_event_t *button_event_ptr)
bool	wlmtk_element_pointer_axis (wlmtk_element_t *element_ptr, struct wlr_pointer_axis_event *wlr_pointer_axis_event_ptr)
bool	wlmtk_element_pointer_focus (wlmtk_element_t *element_ptr, wlmtk_pointer_motion_event_t *motion_event_ptr)
void	wlmtk_element_pointer_blur (wlmtk_element_t *element_ptr)
void	wlmtk_element_pointer_grab_cancel (wlmtk_element_t *element_ptr)
static bool	wlmtk_element_keyboard_event (wlmtk_element_t *element_ptr, struct wlr_keyboard_key_event *wlr_keyboard_key_event_ptr)
static bool	wlmtk_element_keyboard_sym (wlmtk_element_t *element_ptr, xkb_keysym_t keysym, enum xkb_key_direction direction, uint32_t modifiers)
static void	wlmtk_element_keyboard_blur (wlmtk_element_t *element_ptr)
static void	wlmtk_element_destroy (wlmtk_element_t *element_ptr)
wlmtk_fake_element_t *	wlmtk_fake_element_create (void)
void	wlmtk_fake_element_set_dimensions (wlmtk_fake_element_t *fake_element_ptr, int width, int height)
void	wlmtk_fake_element_grab_keyboard (wlmtk_fake_element_t *fake_element_ptr)

Variables
const bs_test_case_t	wlmtk_element_test_cases []

Detailed Description

Copyright

Copyright 2023 Google LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Typedef Documentation

wlmtk_element_t

typedef struct _wlmtk_element_t wlmtk_element_t

Forward declaration: Element.

wlmtk_element_vmt_t

typedef struct _wlmtk_element_vmt_t wlmtk_element_vmt_t

Forward declaration: Element virtual method table.

Function Documentation

wlmtk_dlnode_from_element()

bs_dllist_node_t * wlmtk_dlnode_from_element

(

wlmtk_element_t *

element_ptr

)

Gets the dlnode from the element.

wlmtk_element_attach_to_scene_graph()

void wlmtk_element_attach_to_scene_graph

(

wlmtk_element_t *

element_ptr

)

Attaches or detaches the element to the parent's wlroots scene tree.

If the element has a parent, and that parent is itself attached to the wlroots scene tree, this will either re-parent an already existing node, or invoke wlmtk_element_vmt_t::create_scene_node to create and attach a new node to the paren'ts tree. Otherwise, it will clear any existing node.

The function is idempotent.

Private: Should only called by wlmtk_container_t methods, when there are changes to wlmtk_container_t::wlr_scene_tree.

Parameters

element_ptr

wlmtk_element_destroy()

void wlmtk_element_destroy ( wlmtk_element_t * element_ptr )

inlinestatic

Virtual method: Calls the dtor of the element's implementation.

The implementation is required to call wlmtk_element_fini().

Parameters

element_ptr

wlmtk_element_extend()

wlmtk_element_vmt_t wlmtk_element_extend	(	wlmtk_element_t *	element_ptr,
		const wlmtk_element_vmt_t *	element_vmt_ptr )

Extends the element's virtual methods.

Parameters

element_ptr
element_vmt_ptr

Returns

The previous virtual method table.

wlmtk_element_fini()

void wlmtk_element_fini

(

wlmtk_element_t *

element_ptr

)

Cleans up the element.

Parameters

element_ptr

wlmtk_element_from_dlnode()

wlmtk_element_t * wlmtk_element_from_dlnode

(

bs_dllist_node_t *

dlnode_ptr

)

Gets the element from the dlnode.

wlmtk_element_get_dimensions()

void wlmtk_element_get_dimensions ( wlmtk_element_t * element_ptr, int * left_ptr, int * top_ptr, int * right_ptr, int * bottom_ptr )

inlinestatic

Gets the dimensions of the element in pixels, relative to the position.

Parameters

element_ptr
left_ptr	Leftmost position. May be NULL.
top_ptr	Topmost position. May be NULL.
right_ptr	Rightmost position. Ma be NULL.
bottom_ptr	Bottommost position. May be NULL.

wlmtk_element_get_dimensions_box()

struct wlr_box wlmtk_element_get_dimensions_box ( wlmtk_element_t * element_ptr )

inlinestatic

Gets the element's dimensions in pixel as wlr_box, relative to the position.

Parameters

element_ptr

Returns

A struct wlr_box that specifies the top-left corner of the element relative to it's position, and the element's total width and height.

wlmtk_element_get_position()

void wlmtk_element_get_position	(	wlmtk_element_t *	element_ptr,
		int *	x_ptr,
		int *	y_ptr )

Returns the position of the element.

Parameters

element_ptr
x_ptr	Optional, may be NULL.
y_ptr	Optional, may be NULL.

wlmtk_element_init()

bool wlmtk_element_init

(

wlmtk_element_t *

element_ptr

)

Initializes the element.

Parameters

element_ptr

Returns

true on success.

wlmtk_element_keyboard_blur()

void wlmtk_element_keyboard_blur ( wlmtk_element_t * element_ptr )

inlinestatic

Calls wlmtk_element_vmt_t::keyboard_blur.

wlmtk_element_keyboard_event()

bool wlmtk_element_keyboard_event ( wlmtk_element_t * element_ptr, struct wlr_keyboard_key_event * wlr_keyboard_key_event_ptr )

inlinestatic

Calls wlmtk_element_vmt_t::keyboard_event.

wlmtk_element_keyboard_sym()

bool wlmtk_element_keyboard_sym ( wlmtk_element_t * element_ptr, xkb_keysym_t keysym, enum xkb_key_direction direction, uint32_t modifiers )

inlinestatic

Calls wlmtk_element_vmt_t::keyboard_sym.

wlmtk_element_pointer_axis()

bool wlmtk_element_pointer_axis	(	wlmtk_element_t *	element_ptr,
		struct wlr_pointer_axis_event *	wlr_pointer_axis_event_ptr )

Processes the axis event. Calls wlmtk_element_vmt_t::pointer_axis.

Parameters

element_ptr
wlr_pointer_axis_event_ptr

Returns

true if the axis event was consumed.

wlmtk_element_pointer_blur()

void wlmtk_element_pointer_blur

(

wlmtk_element_t *

element_ptr

)

Informs the element that it does not (or no longer) have pointer focus.

Raises wlmtk_element_events_t::pointer_leave, if it had pointer focus, and calls wlmtk_element_pointer_blur on the parent (if available).

Parameters

element_ptr

wlmtk_element_pointer_button()

bool wlmtk_element_pointer_button	(	wlmtk_element_t *	element_ptr,
		const wlmtk_button_event_t *	button_event_ptr )

Processes the button event. Calls wlmtk_element_vmt_t::pointer_button.

Parameters

element_ptr
button_event_ptr

Returns

true if the button event was consumed.

wlmtk_element_pointer_focus()

bool wlmtk_element_pointer_focus	(	wlmtk_element_t *	element_ptr,
		wlmtk_pointer_motion_event_t *	motion_event_ptr )

Sets pointer focus for the element.

If not focussed already: Request pointer focus from the parent through wlmtk_container_request_pointer_focus. If that succeeds, will raise wlmtk_element_events_t::pointer_enter.

Parameters

element_ptr
motion_event_ptr

Returns

true if the element obtained focus.

wlmtk_element_pointer_grab_cancel()

void wlmtk_element_pointer_grab_cancel

(

wlmtk_element_t *

element_ptr

)

Cancels pointer grab. Calls wlmtk_element_vmt_t::pointer_grab_cancel.

Parameters

element_ptr

wlmtk_element_pointer_motion()

bool wlmtk_element_pointer_motion	(	wlmtk_element_t *	element_ptr,
		wlmtk_pointer_motion_event_t *	pointer_motion_ptr )

Moves the pointer to the new position.

Calls wlmtk_element_vmt_t::pointer_accepts_motion, if the element is visible. Triggers wlmtk_element_events_t::pointer_enter or wlmtk_element_events_t::pointer_leave if the motion is accepted.

Returns

true if the element is visible and the motion is within the element's "pointer focus area", ie. in the area it accepts pointer events.

wlmtk_element_set_parent_container()

void wlmtk_element_set_parent_container	(	wlmtk_element_t *	element_ptr,
		wlmtk_container_t *	parent_container_ptr )

Sets the parent container for the element.

Will call wlmtk_element_attach_to_scene_graph to align the scene graph with the new (or deleted) parent.

Private: Should only be called by wlmtk_container_add_element, respectively wlmtk_container_remove_element ("friends").

Parameters

element_ptr
parent_container_ptr	Pointer to the parent container, or NULL if the parent should be cleared.

wlmtk_element_set_position()

void wlmtk_element_set_position	(	wlmtk_element_t *	element_ptr,
		int	x,
		int	y )

Sets the position of the element.

Parameters

element_ptr
x
y

wlmtk_element_set_visible()

void wlmtk_element_set_visible	(	wlmtk_element_t *	element_ptr,
		bool	visible )

Sets the element's visibility.

Parameters

element_ptr
visible

wlmtk_fake_element_create()

wlmtk_fake_element_t * wlmtk_fake_element_create

(

void

)

Ctor for the fake element, useful for tests.

Returns

A pointer to wlmtk_fake_element_t. Should be destroyed via wlmtk_element_destroy, by passing the pointer to wlmtk_fake_element_t::element as argument.

wlmtk_fake_element_grab_keyboard()

void wlmtk_fake_element_grab_keyboard

(

wlmtk_fake_element_t *

fake_element_ptr

)

Sets wlmtk_fake_element_t::has_keyboard_focus and calls wlmtk_container_set_keyboard_focus_element for the parent (if set).

Parameters

fake_element_ptr

wlmtk_fake_element_set_dimensions()

void wlmtk_fake_element_set_dimensions	(	wlmtk_fake_element_t *	fake_element_ptr,
		int	width,
		int	height )

Updates wlmtk_fake_element_t::dimensions and propagates the layout changes to the parent (if set).

Parameters

fake_element_ptr
width
height

Variable Documentation

wlmtk_element_test_cases

const bs_test_case_t wlmtk_element_test_cases[]

extern

Unit tests for the element.