Window System
[Graphical display system]

Window system for organizing window elements in a graphical user interface (GUI). More...

Collaboration diagram for Window System:

Data Structures
struct	win_window
	Window control data. More...
struct	win_event_queue
	Event queue control struct. More...
struct	win_point
	Geometric type describing a point or vector on screen, relative or absolute. More...
struct	win_area
	Geometric type describing an area on screen. More...
struct	win_clip_region
	Geometric type describing a clipping region, used when drawing windows. More...
struct	win_pointer_event
	Event data for all pointer events, e.g. touch screen or mouse. More...
struct	win_keyboard_event
	Event data for all keyboard events, e.g. full keyboards or smaller matrices. More...
struct	win_command_event
	Event data for command events, e.g. a button widget action command. More...
struct	win_event
	Event data for all events. More...
struct	win_attributes
	Window attribute data. More...
Defines
#define	WIN_ATTR_POSITION (1 << 0)
	Attribute mask for updating window position.
#define	WIN_ATTR_SIZE (1 << 1)
	Attribute mask for updating window size.
#define	WIN_ATTR_BACKGROUND (1 << 2)
	Attribute mask for updating window background type and color/pixmap.
#define	WIN_ATTR_EVENTHANDLER (1 << 3)
	Attribute mask for updating window event handler.
#define	WIN_ATTR_BEHAVIOR (1 << 4)
	Attribute mask for updating window behavior flags.
#define	WIN_ATTR_CUSTOM (1 << 5)
	Attribute mask for updating window custom data.
#define	WIN_BEHAVIOR_RAISE_ON_PRESS (1 << 0)
	Behavior mask for raising a window if itself or children are pressed.
#define	WIN_BEHAVIOR_REDRAW_PARENT (1 << 1)
	Behavior mask for requiring redraw of parent, e.g. transparent windows.
#define	WIN_ROOT_COLOR GFX_COLOR(0, 0, 0)
	Background color of root window, ie. the desktop.
#define	WIN_SCREEN_COLOR GFX_COLOR(0, 0, 0)
	Screen background color used when root window is hidden.
#define	WIN_EVENT_QUEUE_SIZE 16
	Size of event queue.
#define	WIN_TOUCH_BUTTON (1 << 0)
	Button mask for touch screens.
Typedefs
typedef bool(*	win_event_handler_t )(struct win_window win, enum win_event_type type, const void data)
	Function pointer type for window event handlers.
typedef uint8_t	win_behavior_t
	Data type holding window behavior flags.
typedef uint8_t	win_attribute_mask_t
	Datatype holding attribute masks, used when updating attributes.
typedef uint8_t	win_button_mask_t
	Datatype holding button state mask for pointer input devices.
typedef uint8_t	win_keycode_t
	Datatype holding the key "scan" code for keyboard input devices.
typedef void *	win_command_t
	Custom data, can be used as a data pointer or data depending on the application.
typedef uint16_t	clock_jiffy_t
	Data type holding timestamp for events.
Enumerations
enum	win_pointer_event_type { WIN_POINTER_PRESS, WIN_POINTER_MOVE, WIN_POINTER_RELEASE }
	Valid pointer event types. More...
enum	win_keyboard_event_type { WIN_KEYBOARD_PRESS, WIN_KEYBOARD_RELEASE }
	Valid keyboard event types. More...
enum	win_event_type { WIN_EVENT_POINTER, WIN_EVENT_KEYBOARD, WIN_EVENT_COMMAND, WIN_EVENT_RAISE, WIN_EVENT_UNRAISE, WIN_EVENT_GETFOCUS, WIN_EVENT_LOSEFOCUS, WIN_EVENT_DRAW, WIN_EVENT_ATTRIBUTES, WIN_EVENT_DESTROY }
	Valid event types sent to a window event handler. More...
Functions
static bool	win_is_visible (const struct win_window *win)
	Return true if this window and all parents and grand parents are visible.
static void	win_draw (const struct win_window win, const struct win_area dirty_area)
	Draw the parts of the window covered by dirty_area, and all covering windows.
static void	win_draw_parent (const struct win_window child, const struct win_area dirty_area)
	Draw parent window, with all child windows, but limited to dirty area.
static void	win_draw_contents (const struct win_window win, const struct win_clip_region clip)
	Draw window background and contents, including children, limited to clip.
static void	win_draw_child (const struct win_window child, const struct win_clip_region parentClip)
	Draw a child window, automatically translating clipping region from parent.
static bool	win_translate_area_to_parent (struct win_area area, const struct win_window parent)
	Translate an area to coordinates relative to parent's origin.
static void	win_destroy_children (struct win_window *win)
	Destroy child windows, freeing allocated memory.
static void	win_unlink (struct win_window *win)
	Remove window from parent's linked list.
static void	win_add_top_child (struct win_window parent, struct win_window child)
	Add child window at the start of parent's linked list.
static void	win_process_pointer_event (struct win_pointer_event *event)
	Helper function to process pointer event, called from win_process_events().
static bool	win_handle_pointer_event (struct win_window win, const struct win_pointer_event event, const struct win_point *pos)
	Ask window to process pointer event, or pass it on to correct child.
static bool	win_handle_event (struct win_window win, enum win_event_type type, const void data)
	Call window event handler if any, return value from handler, or false.
static void	win_queue_event (const struct win_event *event)
	Add an event to the internal queue.
static void	win_event_worker (struct workqueue_task *task)
	Worker function to be added to main work queue, calls win_process_events().
void	win_init (void)
	Initialize window system, set up root window, hook into touch driver.
struct win_window *	win_get_root (void)
	Get pointer to root window, i.e. desktop window.
struct win_window *	win_get_parent (const struct win_window *win)
	Get pointer to parent window, or NULL for root window.
void	win_reset_root_geometry (void)
	Reset root window geometry to fullscreen, in case screen orientation change.
void	win_set_attributes (struct win_window win, const struct win_attributes new_attributes, win_attribute_mask_t attribute_mask)
	Update window attributes, selected by the attribute mask.
void	win_set_area (struct win_window win, const struct win_area new_area, win_attribute_mask_t attribute_mask)
	Update window position and/or size.
struct win_attributes *	win_get_attributes (const struct win_window *win)
	Get a pointer to the window attribute struct.
struct win_area *	win_get_area (const struct win_window *win)
	Get a pointer to the window area struct.
void *	win_get_custom_data (const struct win_window *win)
	Get window custom data.
struct win_window *	win_create (struct win_window parent, const struct win_attributes attributes)
	Create a window and return its pointer. Use win_destroy() to free memory.
void	win_destroy (struct win_window *win)
	Destroy a window and its contents including children, freeing up memory.
void	win_reparent (struct win_window child, struct win_window new_parent)
	Change a window's parent.
void	win_show (struct win_window *win)
	Show window. Will draw it on screen if parent is visible as well.
void	win_redraw (const struct win_window *win)
	Redraw window and its contents, if visible.
void	win_hide (struct win_window *win)
	Hide a window, removing it from screen if is was visible.
void	win_raise (struct win_window *win)
	Raise window to top of all its siblings.
void	win_lower (struct win_window *win)
	Lower window to bottom of all its siblings.
void	win_queue_pointer_event (const struct win_pointer_event *event)
	Add a pointer event to the internal event queue.
void	win_queue_keyboard_event (const struct win_keyboard_event *event)
	Add a keyboard event to the internal event queue.
void	win_queue_command_event (const struct win_command_event *event)
	Add a command event to the internal event queue.
static void	win_process_keyboard_event (struct win_keyboard_event *kevent)
	Process a keyboard event.
static void	win_process_command_event (struct win_command_event *cevent)
	Process a command event.
void	win_process_events (void)
	Process all pending events from the internal queue.
void	win_set_keyboard_focus (struct win_window *win)
	Set keyboard focus window or NULL, i.e. receiver of keyboard events.
void	win_grab_pointer (struct win_window *win)
	Set pointer focus window or NULL, i.e. override pointer event receiver.
bool	win_is_inside_clip (const struct win_clip_region clip, const struct win_point point)
	Return true if point is inside clipping region.
bool	win_is_inside_area (const struct win_area area, const struct win_point point)
	Return true if point is inside area.
bool	win_is_inside_window (const struct win_window win, const struct win_point point)
	Return true if global point is inside window.
void	win_compute_union (struct win_area area, const struct win_area merge)
	Compute smallest box containing both areas, update first parameter.
bool	win_compute_intersection (struct win_clip_region clip, const struct win_area area)
	Compute the intersection of clipping region and area, update clip.
bool	win_compute_clipping (const struct win_window win, const struct win_area dirty_area, struct win_clip_region *clip)
	Compute clipping region in absolute coordinates from window and dirty area.
void	win_translate_win_to_root (struct win_window const start_win, struct win_point return_pos)
	Compute window position on root window.
Variables
static struct win_window	win_root
	Root window, i.e. desktop window.
static struct win_event_queue	win_event_queue
	Window event queue.
static uint32_t	win_num_dropped_events
	Diagnostic value counting number of dropped events due to event queue full.
static struct win_window *	win_pointer_grabber
	Current pointer grabbing window, or NULL. Grabber gets all pointer events.
static struct win_window *	win_keyboard_focus
	Current keyboard focus, or NULL. Keyboard focus gets all keyboard events.
static struct win_point	win_last_pointer_pos
	Stores last pointer event position, in absolute coordinates.
static struct gfx_bitmap	win_root_background
	Frame background bitmap.

Detailed Description

Window system for organizing window elements in a graphical user interface (GUI).

The window system is a module for organizing two dimensional windows. Windows are organized in a tree strcture where each window can have one parent but several children. The window system also allows events to be queued and handled by the event handler of the affected windows.

A window is defined with the following properties:

A position and area/size
Relation to parent and children
Visibility
Background
Behavior flags
Event handler

The window system can be used separately or together with the Widget toolkit.

Positioning and relations

The windows are organized in a tree structure. A window can be used for graphical user interface (GUI) elements drawn on a screen or display. These elements are often called widgets. The window system can be used to organize any built-in or custom widget. Some examples of widgets are frame, static text, button, checkbox or more advanced widgets like an analog clock.

Each window can have children, and the child windows must be contained within the area of the parent window. This means the child window can be as large as, but not be larger than the parent window. A root window filling the entire screen is created when the window system is initialized with win_init. If the screen orientation changes the root window can be re-initialized with win_reset_root_geometry. A pointer to the root window is returned from win_get_root.

The following figure shows the relations between windows that are used to represent some example widgets. In the figure we show the top_child and next_sibling pointers. The parent and prev_sibling pointers which point in the opposite direction are omitted to simplify the figure.

The figure also illustrates how the position and size affects how the windows could be represented on a display.

See also:: win_set_area; win_create; win_reparent; win_get_parent

Visibility

A window can only be shown if it has been mapped to the screen with the win_show function and that the parent windows are also mapped to the screen.

When a window is drawn, the following happens:

If WIN_BEHAVIOR_REDRAW_PARENT attribute is set the parent will be drawn.
Background for window will be drawn
Event handler for window will be called to draw the window/widget.
Children will be drawn starting with the bottom child and ending with the top child.

See also:: win_redraw; win_show; win_hide; win_raise; win_lower

Event handling

Propagation of events are an important part of the window system. Events are added to the event queue with one of queue functions (win_queue_pointer_event, win_queue_keyboard_event, win_queue_command_event). When an event is queued, the win_process_events function is automatically added to the main main workqueue. This ensures that the event is handled after the current workqueue item is completed.

The events are handled differently depending on the event. Valid event types are defined by win_event_type.

See also:: win_create; win_get_attributes; win_set_attributes

Keyboard events are sent to the window which has focus. See win_set_keyboard_focus. This means that the event handler for that window will be called. If the event handler does not accept the event (ie the event handler returns false), the event will be sent to the parent window. It will continue propagating to all parents until accepted. If no window accepts the event or no window has focus, the event will be discarded.

Command events are sent to the window which is set as recipient of the event struct win_command_event. It will propagate up to parents in the same way as the keyboard events.

Pointer events are handled a bit differently. If a window has requested to get all pointer events with the win_grab_pointer function, the event handler for that window is called. The return value of this event handler is ignored. If no window has grabbed the pointer, the pointer event will start from the root window. It will then search the children to find the window that is under the pointer. win_is_inside_area If no window is found or the window under the pointer does not accept the event, it will search the recursively through the children.
See also:
win_process_pointer_event.
Window draw events are sent to the window to allow it to draw itself after the window system has drawn the background for the window. See window visibility

Define Documentation

#define WIN_ATTR_BACKGROUND (1 << 2)

Attribute mask for updating window background type and color/pixmap.

Definition at line 175 of file win.h.

#define WIN_ATTR_BEHAVIOR (1 << 4)

Attribute mask for updating window behavior flags.

Definition at line 179 of file win.h.

#define WIN_ATTR_CUSTOM (1 << 5)

Attribute mask for updating window custom data.

Definition at line 181 of file win.h.

#define WIN_ATTR_EVENTHANDLER (1 << 3)

Attribute mask for updating window event handler.

Definition at line 177 of file win.h.

#define WIN_ATTR_POSITION (1 << 0)

Attribute mask for updating window position.

Definition at line 171 of file win.h.

Referenced by wtk_handle_frame_release(), and wtk_resize_frame().

#define WIN_ATTR_SIZE (1 << 1)

Attribute mask for updating window size.

Definition at line 173 of file win.h.

Referenced by wtk_resize_frame().

#define WIN_BEHAVIOR_RAISE_ON_PRESS (1 << 0)

Behavior mask for raising a window if itself or children are pressed.

Definition at line 184 of file win.h.

Referenced by win_handle_pointer_event(), and wtk_frame_create().

#define WIN_BEHAVIOR_REDRAW_PARENT (1 << 1)

Behavior mask for requiring redraw of parent, e.g. transparent windows.

Definition at line 186 of file win.h.

Referenced by win_draw(), wtk_basic_frame_create(), wtk_check_box_create(), wtk_frame_create(), wtk_label_create(), and wtk_radio_button_create().

#define WIN_EVENT_QUEUE_SIZE 16

Size of event queue.

The event queue holds both input and command events.

Note:: The size of the event queue must be a power of two.

Definition at line 77 of file win.h.

#define WIN_ROOT_COLOR GFX_COLOR(0, 0, 0)

Background color of root window, ie. the desktop.

Definition at line 65 of file win.h.

#define WIN_SCREEN_COLOR GFX_COLOR(0, 0, 0)

Screen background color used when root window is hidden.

Definition at line 68 of file win.h.

#define WIN_TOUCH_BUTTON (1 << 0)

Button mask for touch screens.

Definition at line 80 of file win.h.

Typedef Documentation

typedef uint16_t clock_jiffy_t

Data type holding timestamp for events.

Definition at line 62 of file win.h.

typedef uint8_t win_attribute_mask_t

Datatype holding attribute masks, used when updating attributes.

Definition at line 325 of file win.h.

typedef uint8_t win_behavior_t

Data type holding window behavior flags.

Definition at line 306 of file win.h.

typedef uint8_t win_button_mask_t

Datatype holding button state mask for pointer input devices.

Definition at line 50 of file win.h.

typedef void* win_command_t

Custom data, can be used as a data pointer or data depending on the application.

Definition at line 59 of file win.h.

typedef bool(* win_event_handler_t)(struct win_window *win, enum win_event_type type, const void *data)

Function pointer type for window event handlers.

Todo:: Document the parameters and return value.

Definition at line 300 of file win.h.

typedef uint8_t win_keycode_t

Datatype holding the key "scan" code for keyboard input devices.

Definition at line 53 of file win.h.

Enumeration Type Documentation

enum win_event_type

Valid event types sent to a window event handler.

Enumerator:

WIN_EVENT_POINTER	Pointer event, more details in the event itself.
WIN_EVENT_KEYBOARD	Keyboard event, more details in the event itself.
WIN_EVENT_COMMAND	Command event, more details in the event itself.
WIN_EVENT_RAISE	Window was just raised to top inside its parent.
WIN_EVENT_UNRAISE	Another window just raised to top.
WIN_EVENT_GETFOCUS	Just got keyboard focus.
WIN_EVENT_LOSEFOCUS	Just lost keyboard focus.
WIN_EVENT_DRAW	Request to draw contents, after background.
WIN_EVENT_ATTRIBUTES	Attributes updated, attribute mask included.
WIN_EVENT_DESTROY	Request to free all allocated memory.

Definition at line 258 of file win.h.

enum win_keyboard_event_type

Valid keyboard event types.

Enumerator:

WIN_KEYBOARD_PRESS	A key has been pressed.
WIN_KEYBOARD_RELEASE	A key has been released.

Definition at line 239 of file win.h.

enum win_pointer_event_type

Valid pointer event types.

Enumerator:

WIN_POINTER_PRESS	One or more buttons have been pressed somewhere.
WIN_POINTER_MOVE	Pointer has moved, with or without buttons.
WIN_POINTER_RELEASE	One or more buttons have been released somewhere.

Definition at line 215 of file win.h.

Function Documentation

static void win_add_top_child	(	struct win_window *	parent,
		struct win_window *	child
	)			`[static]`

Add child window at the start of parent's linked list.

This function adds a child window as the top window of a parent.

Parameters:

	parent	Parent window for this child.
	child	Child window to add to parent.

Definition at line 1545 of file win.c.

References win_window::next_sibling, win_window::parent, win_window::prev_sibling, and win_window::top_child.

bool win_compute_clipping	(	const struct win_window *	win,
		const struct win_area *	dirty_area,
		struct win_clip_region *	clip
	)

Compute clipping region in absolute coordinates from window and dirty area.

This function computes a clipping region given a window and an area given in that window's coordinate system. The area is translated to screen coordinates by translating from parent to parent until the root window is reached. Also, the area is clipped to fit, inside the window, and its parents. Use this function to compute a clipping region for updating parts of a window. If the resulting region is an empty set, the function returns false.

The dirty_area parameter is given in the same coordinate system as the window's area struct. This means that if you provide a pointer to the window's area as the dirty_area parameter, you get a clipping region covering the entire window.

Parameters:

	win	The window to start from.
	dirty_area	Area to be clipped, same coordinate system as window.
	clip	Resulting clipping region, global coordinates.

Return values:

	true	The resulting region is valid.
	false	The resulting region is an empty set.

Referenced by win_draw().

bool win_compute_intersection	(	struct win_clip_region *	clip,
		const struct win_area *	area
	)

Compute the intersection of clipping region and area, update clip.

This function computes the intersection of a clipping region and an area. The clipping region is updated with the result, so that the new region only contains the area common to both the original region and the area. If the clipping region and the area did not share any areas, i.e. the result is empty set, then the function returns false.

Parameters:

	clip	Original clipping region, and also where the result is stored.
	area	Area to compute intersection with.

Return values:

	true	The resulting area is valid.
	false	The resulting area is an empty set.

void win_compute_union	(	struct win_area *	area,
		const struct win_area *	merge
	)

Compute smallest box containing both areas, update first parameter.

This function computes the smallest area the will fit both areas. The new area is copied into the first parameter.

Parameters:

	area	First area, and also where the result is stored.
	merge	Second area, which is "merged" with the first.

struct win_window * win_create	(	struct win_window *	parent,
		const struct win_attributes *	attributes
	)			`[read]`

Create a window and return its pointer. Use win_destroy() to free memory.

This function attempts to allocate memory for a new window from the dynamic memory pool. If successful, it initializes the window and attaches it to the parent, raising it to the top of all siblings, and returns the window pointer. If it fails, the function returns NULL.

Use win_destroy() to properly free the allocated memory. Refer to the win_destroy() function for more details on the destroy procedure.

Parameters:

	parent	Pointer to parent window.
	attributes	Pointer to initial attributes.

Returns:: Pointer to allocated window struct, or NULL.

Referenced by app_memgame_launch(), slide_launch_helper(), wtk_basic_frame_create(), wtk_button_create(), wtk_check_box_create(), wtk_frame_create(), wtk_label_create(), wtk_progress_bar_create(), wtk_radio_button_create(), and wtk_slider_create().

void win_destroy ( struct win_window * win )

Destroy a window and its contents including children, freeing up memory.

This function hides a window, detaches it from its parent. It then frees all memory allocated by all its children, grand children etc, and itself. Before freeing the memory, a DESTROY event is sent to each window's event handler. Use this event to free memory and resources allocated by e.g. widget toolkits. Since each window is detached from its parent before sending the DESTROY event, the event handling should never attempt to refer to parent windows.

Parameters:

win

Pointer to window.

Referenced by app_fonts_load(), app_fonts_load_worker(), app_memgame_launch(), app_tank_launch(), memgame_draw_piece(), memgame_handle_command_event(), slide_launch_helper(), slide_window_handler(), tank_loader(), wtk_basic_frame_handler(), wtk_frame_create(), and wtk_frame_handler().

static void win_destroy_children ( struct win_window * win ) [static]

Destroy child windows, freeing allocated memory.

This function is a helper function for the win_destroy() function. For every child window, it asks it to destroy its children, then it send a DESTROY event to the child, and finally frees the allocated memory. The window's DESTROY event handler should free any other memory or resources allocated by e.g. widgets.

Warning:: This function is recursive, so ensure that your application has plenty of stack space before calling this function.

Parameters:

win

Window whose children should be destroyed.

Definition at line 1491 of file win.c.

References membag_free(), win_window::next_sibling, win_window::top_child, WIN_EVENT_DESTROY, and win_handle_event().

static void win_draw	(	const struct win_window *	win,
		const struct win_area *	dirty_area
	)			`[static]`

Draw the parts of the window covered by dirty_area, and all covering windows.

This function takes care of the actual drawing of all or parts of a window. If the window is not the top window, i.e. obscured by other windows, these other windows are also redrawn in the proper order. Only the parts of the windows that need to will be redrawn.

The dirty_area parameter dictates which areas of the window to draw or redraw. The area is given in the same coordinate system as the window itself, which means that providing the window's own area struct will result in drawing the entire window. If only smaller parts of the window needs to be drawn, make a copy of the window's area struct and update to your liking before passing to this function.

For windows that are partly transparent, e.g. drop shadows or round corners, the parent is asked to redraw all its child windows, in order to provide a fresh background for the window to draw upon. This applies to windows with the behavior flag REDRAW_PARENT set.

Parameters:

	win	Window to draw or redraw.
	dirty_area	Area dictating which parts to draw.

Definition at line 1223 of file win.c.

References win_attributes::area, win_window::attributes, win_attributes::behavior, win_window::is_mapped, win_clip_region::origin, win_window::parent, win_area::pos, win_window::prev_sibling, win_window::top_child, WIN_BEHAVIOR_REDRAW_PARENT, win_compute_clipping(), win_draw_child(), win_draw_contents(), win_draw_parent(), and win_root.

Referenced by win_draw_parent().

static void win_draw_child	(	const struct win_window *	child,
		const struct win_clip_region *	parent_clip
	)			`[static]`

Draw a child window, automatically translating clipping region from parent.

This function is a helper function for the win_draw() and win_draw_contents() functions. It takes care of updating the clipping region, intersecting it with the child window area. Then it draws the child window's contents.

Parameters:

	child	Child window to draw.
	parent_clip	Clipping region, in global coordinates.

Definition at line 1353 of file win.c.

References win_attributes::area, win_window::attributes, win_clip_region::NW, win_clip_region::origin, win_area::pos, win_clip_region::SE, win_area::size, and win_draw_contents().

Referenced by win_draw(), and win_draw_contents().

static void win_draw_contents	(	const struct win_window *	win,
		const struct win_clip_region *	clip
	)			`[static]`

Draw window background and contents, including children, limited to clip.

This function is a helper function for the win_draw() function. It draws the actual contents of a window, given a clipping region. First, it draws the window background itself, depending on the type. Then it sends a DRAW event to the window, so that e.g. widgets or other handlers can draw the rest of the window contents. Finally, it asks all mapped children, if any, to draw themselves.

Note that when the DRAW event is sent to the window, the TFT clipping region is already set, so all TFT graphics functions called from the event handler will be subject to proper clipping automatically.

Parameters:

	win	The window to draw.
	clip	Clipping region, in global coordinates.

Todo:: Either de-constify win or constify the parameter to win_handle_event(). The code below looks dangerous.

Definition at line 1312 of file win.c.

References win_window::attributes, win_attributes::background, gfx_draw_bitmap_tiled(), gfx_set_clipping(), win_window::is_mapped, win_clip_region::NW, win_clip_region::origin, win_window::prev_sibling, win_clip_region::SE, win_window::top_child, win_draw_child(), WIN_EVENT_DRAW, and win_handle_event().

Referenced by win_draw(), and win_draw_child().

static void win_draw_parent	(	const struct win_window *	child,
		const struct win_area *	dirty_area
	)			`[static]`

Draw parent window, with all child windows, but limited to dirty area.

This function is a shortcut to ask a window's parent to draw all its children. However, the area to draw is given in the same coordinate system as the child window, i.e. point 0,0 is top left corner of the parent window. This function is used e.g. when rearranging child windows or to draw partly transparent windows.

Parameters:

	child	Child window.
	dirty_area	The area, given in same coordinate system as the child.

Definition at line 1284 of file win.c.

References win_window::parent, win_draw(), and win_translate_area_to_parent().

Referenced by win_draw().

static void win_event_worker ( struct workqueue_task * task ) [static]

Worker function to be added to main work queue, calls win_process_events().

This function will be used as the work item callback when new events are added to the queue.

Parameters:

task

Pointer to the task being run, not used in function.

Definition at line 1810 of file win.c.

References win_process_events().

struct win_area * win_get_area ( const struct win_window * win ) [read]

Get a pointer to the window area struct.

This function returns a pointer to the internal area struct of a window. It cannot be modified, but could be copied from.

Parameters:

win

Pointer to window.

Returns:: Pointer to area struct.

Referenced by wtk_button_handler(), wtk_frame_handler(), wtk_handle_frame_release(), wtk_handle_resize_release(), wtk_label_handler(), wtk_progress_bar_handler(), wtk_progress_bar_set_value(), wtk_resize_frame(), wtk_slider_handler(), and wtk_slider_set_value().

struct win_attributes * win_get_attributes ( const struct win_window * win ) [read]

Get a pointer to the window attribute struct.

This function returns a pointer to the internal attribute struct of a window. It cannot be modified, but could be copied from.

Parameters:

win

Pointer to window.

Returns:: Pointer to attribute struct.

void * win_get_custom_data ( const struct win_window * win )

Get window custom data.

This function returns the custom data from the window's attributes. The custom data can be used for e.g. linking to associated widgets.

Parameters:

win

Pointer to window.

Returns:: Copy of the custom data.

Referenced by wtk_basic_frame_handler(), wtk_button_handler(), wtk_check_box_handler(), wtk_frame_handler(), wtk_label_handler(), wtk_progress_bar_handler(), wtk_radio_button_handler(), and wtk_slider_handler().

struct win_window * win_get_parent ( const struct win_window * win ) [read]

Get pointer to parent window, or NULL for root window.

Return pointer to parent window, or NULL for root window.

Parameters:

win

Child window.

Returns:: Pointer to parent window.

Referenced by wtk_handle_frame_release(), and wtk_handle_resize_release().

struct win_window * win_get_root ( void ) [read]

Get pointer to root window, i.e. desktop window.

Return a pointer to the root window. Use this to change the attributes of the root window, or use the root window as a parent for new windows.

Returns:: Pointer to root window.

Referenced by app_memgame_launch(), app_tank_launch(), load_desktop(), and slide_launch_helper().

void win_grab_pointer ( struct win_window * win )

Set pointer focus window or NULL, i.e. override pointer event receiver.

This function sets a pointer grabber window. The window that has grabbed the pointer will receive all further pointer events until another window grabs to pointer, or the pointer is ungrabbed by setting the grabbing window to NULL. Use this function to grab the pointer to widgets that in certain states needs to get all pointer events, e.g. dragging.

Parameters:

win

Pointer to grabbing window, or NULL.

Referenced by wtk_button_handler(), wtk_check_box_handler(), wtk_handle_frame_press(), wtk_handle_frame_release(), wtk_handle_resize_press(), wtk_handle_resize_release(), wtk_radio_button_handler(), and wtk_slider_handler().

static bool win_handle_event	(	struct win_window *	win,
		enum win_event_type	type,
		const void *	data
	)			`[static]`

Call window event handler if any, return value from handler, or false.

This function is a small helper function that checks if a window has an event handler at all, and in that case, sends it an event for handling. If an event handler is present, and accepts the event, this function returns true. If the event handler rejects it, or there's no event handler present, this function returns false.

Parameters:

	win	Window to handle event.
	type	Event type.
	data	Custom data, dependent on event type.

Return values:

	true	Event handler present and accepts event
	false	No event handler present or event handler doesn't accept event.

Definition at line 1707 of file win.c.

References win_window::attributes, and win_attributes::event_handler.

Referenced by win_destroy_children(), win_draw_contents(), win_handle_pointer_event(), win_process_command_event(), win_process_keyboard_event(), and win_process_pointer_event().

static bool win_handle_pointer_event	(	struct win_window *	win,
		const struct win_pointer_event *	event,
		const struct win_point *	pos
	)			`[static]`

Ask window to process pointer event, or pass it on to correct child.

This function is a helper function for the win_process_pointer_event() function. The pointer event is already processed, so this function searches through its child windows to find the one beneath the pointer. If no suitable child windows are found, the window handles the pointer event itself. If either a child or this window accepts the event, this function returns true.

Any window encountered with the RAISE_ON_BUTTON behavior flag set will be raised to the top inside it's parent, if the event was a POINTER_PRESS.

Warning:: This function is recursive, so ensure that your application has plenty of stack space before calling this function.

Parameters:

	win	Window to handle the event itself, or pass on to children.
	event	Pointer event to handle.
	pos	Absolute position, translated to window's own coordinates.

Returns:: True if child or window itself accepted the event.

Definition at line 1629 of file win.c.

References win_attributes::area, win_window::attributes, win_attributes::behavior, win_window::is_mapped, win_window::next_sibling, win_area::pos, win_window::top_child, win_pointer_event::type, WIN_BEHAVIOR_RAISE_ON_PRESS, WIN_EVENT_POINTER, win_handle_event(), win_is_inside_area(), WIN_POINTER_PRESS, and win_raise().

Referenced by win_process_pointer_event().

void win_hide ( struct win_window * win )

Hide a window, removing it from screen if is was visible.

This function unmaps a window from its parent. If it was visible, it will be removed from the screen. If the root window is hidden, the screen background will be erased to the color WIN_SCREEN_COLOR.

Parameters:

win

Pointer to window.

void win_init ( void )

Initialize window system, set up root window, hook into touch driver.

This function initializes the windowing system. Call this function before any other window system operations, as this initializes the root window, internal queues and other internals.

bool win_is_inside_area	(	const struct win_area *	area,
		const struct win_point *	point
	)

Return true if point is inside area.

This function checks if a point is inside a given area.

Parameters:

	area	Pointer to area.
	point	Pointer to point to check.

Returns:: True if point is inside area.

Referenced by win_handle_pointer_event().

bool win_is_inside_clip	(	const struct win_clip_region *	clip,
		const struct win_point *	point
	)

Return true if point is inside clipping region.

This function checks if a point is inside the clipping region. The origin field of the clipping region is not relevant, only the corners of the clipping region itself.

Parameters:

	clip	Pointer to clipping region.
	point	Pointer to point to check.

Returns:: True if point is inside clipping region.

bool win_is_inside_window	(	const struct win_window *	win,
		const struct win_point *	point
	)

Return true if global point is inside window.

This function checks if point given in global coordinates is inside a given window.

Parameters:

	win	Window to check.
	point	Point in global coordinates.

Return values:

	true	if point is inside win.
	false	if point is not inside win.

Referenced by wtk_button_handler(), wtk_check_box_handler(), wtk_handle_frame_release(), wtk_handle_resize_release(), and wtk_radio_button_handler().

static bool win_is_visible ( const struct win_window * win ) [static]

Return true if this window and all parents and grand parents are visible.

This function checks if the window should be visible on screen, or at least drawn on screen but maybe obscured by other windows. If a window's parent is visible, all mapped children are also visible. If any parent on the path up to, and including, the root window is unmapped, the window is not visible. Once again, note that even if a window is "visible", i.e. this function returns true, it might be obscured by other windows on top.

Parameters:

win

Window to check.

Return values:

	true	win is visible.
	false	win is not visible.

Definition at line 1182 of file win.c.

References win_window::is_mapped, and win_window::parent.

void win_lower ( struct win_window * win )

Lower window to bottom of all its siblings.

This function lowers a window to the bottom of the Z-stack of child windows. Proper redraw calls are issued to update graphics. Before rearranging windows, this window is sent an UNRAISE event, and the window the gets to be on top after rearranging is sent a RAISE event. Use these events to update any focus and highlight related graphics.

Parameters:

win

Pointer to window.

static void win_process_command_event ( struct win_command_event * cevent ) [static]

Process a command event.

This function is only called by win_process_events().

Parameters:

cevent

The command event being processed.

Definition at line 792 of file win.c.

References assert, win_command_event::data, win_window::parent, win_command_event::recipient, WIN_EVENT_COMMAND, and win_handle_event().

void win_process_events ( void )

Process all pending events from the internal queue.

This function processes all pending events from the internal queue. In order for the window system to work properly, this function should be called as often as possible, to process new events. In this implementation, whenever a new event is added to the queue, the system automatically adds a work item to the main application work queue. This work item refers to win_event_worker() which in turn will call this function to process all pending events.

Warning:: This function is recursive, so ensure that your application has plenty of stack space before calling this function.

Referenced by win_event_worker().

static void win_process_keyboard_event ( struct win_keyboard_event * kevent ) [static]

Process a keyboard event.

This function is only called by win_process_events().

Parameters:

kevent

The keyboard event being processed.

Definition at line 764 of file win.c.

References win_window::parent, WIN_EVENT_KEYBOARD, and win_handle_event().

static void win_process_pointer_event ( struct win_pointer_event * event ) [static]

Helper function to process pointer event, called from win_process_events().

This function is a helper function for the win_process_events() function. It processes a pointer event by sending it to either the current pointer grabbing window or into the window tree to find the window that is directly beneath the pointer. The function also converts any relative coordinates to absolute screen coordinates.

Parameters:

event

Pointer event data to process.

Definition at line 1577 of file win.c.

References win_pointer_event::is_relative, WIN_EVENT_POINTER, win_handle_event(), win_handle_pointer_event(), win_last_pointer_pos, and win_root.

void win_queue_command_event ( const struct win_command_event * event )

Add a command event to the internal event queue.

This function creates a struct win_event from the command event and adds it to the internal event queue. The event data is copied, so there is no need to keep the event variable alive after calling this function.

Parameters:

event

Pointer to command event data.

Referenced by wtk_button_handler(), wtk_check_box_handler(), wtk_radio_button_handler(), and wtk_slider_handler().

static void win_queue_event ( const struct win_event * event ) [static]

Add an event to the internal queue.

This function adds a window event to the internal queue, taking care of the internals of updating the circular queue. This function is reentrant and protected from interrupts, so it can be called at any time from anywhere without concern for concurrency. The event data is copied into the queue, so there is no need to keep the event variable alive after calling this function. This function also takes care of adding a work item to the main work queue of the application once new events arrive. If there are already events in the queue, no extra work items will be added.

Todo:: Set a timestamp for each event.

Parameters:

event

Event to add to the queue.

Definition at line 1780 of file win.c.

References cpu_irq_restore(), cpu_irq_save(), main_workqueue, win_num_dropped_events, and workqueue_add_task().

void win_queue_keyboard_event ( const struct win_keyboard_event * event )

Add a keyboard event to the internal event queue.

This function creates a struct win_event from the keyboard event and adds it to the internal event queue. The event data is copied, so there is no need to keep the event variable alive after calling this function.

Parameters:

event

Pointer to keyboard event data.

void win_queue_pointer_event ( const struct win_pointer_event * event )

Add a pointer event to the internal event queue.

This function creates a struct win_event from the pointer event and adds it to the internal event queue. The event data is copied, so there is no need to keep the event variable alive after calling this function.

Parameters:

event

Pointer to pointer event data.

void win_raise ( struct win_window * win )

Raise window to top of all its siblings.

This function raises a window to the top of the Z-stack of child windows. Proper redraw calls are issued to update graphics. Before rearranging windows, the current top window is sent an UNRAISE event, and after putting this window on top, this gets a RAISE event. Use these events to update any focus and highlight related graphics.

Parameters:

win

Pointer to window.

Referenced by win_handle_pointer_event().

void win_redraw ( const struct win_window * win )

Redraw window and its contents, if visible.

This function redraws a window, if it is mapped and visible. Use this function to refresh graphics if e.g. a widget's state is changed.

Parameters:

win

Pointer to window.

Referenced by app_files_frame_command_handler(), app_fonts_frame_command_handler(), app_fonts_load_worker(), app_widget_update_colors(), load_desktop(), memgame_start_new_game(), wtk_button_handler(), wtk_check_box_handler(), wtk_check_box_set(), wtk_check_box_toggle(), wtk_label_change(), wtk_progress_bar_set_value(), wtk_radio_button_create(), wtk_radio_button_handler(), wtk_radio_button_select(), wtk_slider_handler(), and wtk_slider_set_value().

void win_reparent	(	struct win_window *	child,
		struct win_window *	new_parent
	)

Change a window's parent.

This function detaches a window from its parent and attaches it to a new parent, as the top child window. This essentially moves a window from one parent to another. If the window is not mapped, it will still be unmapped at the new parent.

Parameters:

	child	Pointer to child window to reparent.
	new_parent	Pointer to new parent.

void win_reset_root_geometry ( void )

Reset root window geometry to fullscreen, in case screen orientation change.

This function resets the root window size to fill the entire screen. Use this function to reconfigure the root window after a change in screen orientation.

void win_set_area	(	struct win_window *	win,
		const struct win_area *	new_area,
		win_attribute_mask_t	attribute_mask
	)

Update window position and/or size.

This function updates the window position and/or size. The flags of the attribute mask decides what to update. Note that you cannot change the position or size of the root window, since the root window is always fullscreen.

Parameters:

	win	Pointer to window that will be updated.
	new_area	Pointer to new area attributes.
	attribute_mask	Attribute flags selecting which attributes to update.

Referenced by wtk_handle_frame_release(), and wtk_resize_frame().

void win_set_attributes	(	struct win_window *	win,
		const struct win_attributes *	new_attributes,
		win_attribute_mask_t	attribute_mask
	)

Update window attributes, selected by the attribute mask.

This function updates one or more of a window's attributes. Only the the attributes corresponding to the flags of the attribute mask are updated. The others are left untouched.

Parameters:

	win	Pointer to window that will be updated.
	new_attributes	Pointer to new attribute values.
	attribute_mask	Attribute flags selecting which attributes to update.

void win_set_keyboard_focus ( struct win_window * win )

Set keyboard focus window or NULL, i.e. receiver of keyboard events.

This function changes the keyboard focus window. The current keyboard focus window is sent a LOSEFOCUS event, and the new focus window is sent a GETFOCUS event. The keyboard focus window will receive all keyboard events. Set the focus window to NULL to remove the focus.

Parameters:

win

Pointer to the new keyboard focus window, or NULL.

void win_show ( struct win_window * win )

Show window. Will draw it on screen if parent is visible as well.

This function maps a window to its parent. Mapping means that the window will be visible and drawn if the parent is visible, unless obscured by other windows of course.

Parameters:

win

Pointer to window.

Referenced by app_files_load_worker(), app_fonts_load_worker(), app_memgame_launch(), app_tank_launch(), slide_launch_helper(), tank_loader(), and wtk_frame_create().

static bool win_translate_area_to_parent	(	struct win_area *	area,
		const struct win_window *	parent
	)			`[static]`

Translate an area to coordinates relative to parent's origin.

This function is a helper function for the win_draw_parent() function. It translates an area given in the same coordinate system as the child window, to the same system as the parent window. The area is clipped inside the parent extents if required. If the resulting area is en empty set, the function returns false.

Parameters:

	area	The area to translate.
	parent	Parent window.

Return values:

	true	The resulting area is valid.
	false	The resulting area is an empty set.

Definition at line 1445 of file win.c.

References win_attributes::area, win_window::attributes, win_area::pos, and win_area::size.

Referenced by win_draw_parent().

void win_translate_win_to_root	(	struct win_window const *	start_win,
		struct win_point *	return_pos
	)

Compute window position on root window.

This function calculates the position of a window on the root window. It traverses all parent windows and adds their position to get the position of the given window.

Parameters:

start_win

The window of which to find absolute position.

Return values:

return_pos

The absolute position of the window

Referenced by wtk_slider_create(), and wtk_slider_handler().

static void win_unlink ( struct win_window * win ) [static]

Remove window from parent's linked list.

This function pulls out a window from the parent window's linked list of of child windows. This function is used when rearranging child windows.

Parameters:

win

Window to be unlinked from parent.

Definition at line 1517 of file win.c.

References win_window::next_sibling, win_window::parent, win_window::prev_sibling, and win_window::top_child.

Variable Documentation

struct win_event_queue win_event_queue [static]

Window event queue.

Definition at line 176 of file win.c.

struct win_window* win_keyboard_focus [static]

Current keyboard focus, or NULL. Keyboard focus gets all keyboard events.

Definition at line 184 of file win.c.

struct win_point win_last_pointer_pos [static]

Stores last pointer event position, in absolute coordinates.

Definition at line 187 of file win.c.

Referenced by win_process_pointer_event().

uint32_t win_num_dropped_events [static]

Diagnostic value counting number of dropped events due to event queue full.

Definition at line 179 of file win.c.

Referenced by win_queue_event().

struct win_window* win_pointer_grabber [static]

Current pointer grabbing window, or NULL. Grabber gets all pointer events.

Definition at line 182 of file win.c.

struct win_window win_root [static]

Root window, i.e. desktop window.

Definition at line 173 of file win.c.

Referenced by win_draw(), and win_process_pointer_event().

struct gfx_bitmap win_root_background [static]

Initial value:

 {
                .type = BITMAP_SOLID,
                .data.color = GFX_COLOR(0, 0, 0),
}

Frame background bitmap.

Definition at line 190 of file win.c.

Window System [Graphical display system]

Data Structures

Defines

Typedefs

Enumerations

Functions

Variables

Detailed Description

Positioning and relations

Visibility

Event handling

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation

Window System
[Graphical display system]