Atmel Software Framework

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages

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

See "AVR1614: Widget Toolkit - Getting Started".

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:

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.

gfx_win_overview.png
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:

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). Pending events in the event queue can be processed by calling the win_process_events function in the main application loop.

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

Dependencies

This component driver depends on the following modules:

Data Structures

struct  win_area
 Geometric type describing an area on screen. More...
 
struct  win_attributes
 Window attribute data. More...
 
struct  win_clip_region
 Geometric type describing a clipping region, used when drawing windows. More...
 
struct  win_command_event
 Event data for command events, e.g. More...
 
struct  win_event
 Event data for all events. More...
 
struct  win_event_queue
 Event queue control struct. More...
 
struct  win_keyboard_event
 Event data for all keyboard events, e.g. More...
 
struct  win_point
 Geometric type describing a point or vector on screen, relative or absolute. More...
 
struct  win_pointer_event
 Event data for all pointer events, e.g. More...
 
struct  win_window
 Window control data. More...
 

Macros

#define WIN_ATTR_BACKGROUND   (1 << 2)
 Attribute mask for updating window background type and color/pixmap. More...
 
#define WIN_ATTR_BEHAVIOR   (1 << 4)
 Attribute mask for updating window behavior flags. More...
 
#define WIN_ATTR_CUSTOM   (1 << 5)
 Attribute mask for updating window custom data. More...
 
#define WIN_ATTR_EVENTHANDLER   (1 << 3)
 Attribute mask for updating window event handler. More...
 
#define WIN_ATTR_POSITION   (1 << 0)
 Attribute mask for updating window position. More...
 
#define WIN_ATTR_SIZE   (1 << 1)
 Attribute mask for updating window size. More...
 
#define WIN_BEHAVIOR_RAISE_ON_PRESS   (1 << 0)
 Behavior mask for raising a window if itself or children are pressed. More...
 
#define WIN_BEHAVIOR_REDRAW_PARENT   (1 << 1)
 Behavior mask for requiring redraw of parent, e.g. More...
 

Typedefs

typedef uint8_t win_attribute_mask_t
 Datatype holding attribute masks, used when updating attributes. More...
 
typedef uint8_t win_behavior_t
 Data type holding window behavior flags. More...
 
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. More...
 

Enumerations

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...
 
enum  win_keyboard_event_type {
  WIN_KEYBOARD_PRESS,
  WIN_KEYBOARD_RELEASE
}
 Valid keyboard event types. More...
 
enum  win_pointer_event_type {
  WIN_POINTER_PRESS,
  WIN_POINTER_MOVE,
  WIN_POINTER_RELEASE
}
 Valid pointer event types. More...
 

Functions

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 coords from window and dirty area. More...
 
bool win_compute_intersection (struct win_clip_region *clip, const struct win_area *area)
 Compute the intersection of clipping region and area. More...
 
void win_compute_union (struct win_area *area, const struct win_area *merge)
 Compute the smallest square containing two areas. More...
 
struct win_windowwin_create (struct win_window *parent, const struct win_attributes *attributes)
 Create a window and return its pointer. More...
 
void win_destroy (struct win_window *win)
 Destroy a window, its contents and children to free up memory. More...
 
struct win_areawin_get_area (const struct win_window *win)
 Get a pointer to the window area struct. More...
 
struct win_attributeswin_get_attributes (const struct win_window *win)
 Get a pointer to the window attribute struct. More...
 
void * win_get_custom_data (const struct win_window *win)
 Get window custom data. More...
 
struct win_windowwin_get_parent (const struct win_window *win)
 Get pointer to parent window, or NULL for root window. More...
 
struct win_windowwin_get_root (void)
 Get pointer to root window, i.e. More...
 
void win_grab_pointer (struct win_window *win)
 Set pointer focus window or NULL, i.e. More...
 
void win_hide (struct win_window *win)
 Hide window, clear it from screen if it was visible. More...
 
void win_inflate_area (struct win_area *area, int16_t size)
 Expands a given area in all directions by a given amount. More...
 
void win_init (void)
 Initialize window system, set up root window, hook into touch driver. More...
 
bool win_is_inside_area (const struct win_area *area, const struct win_point *point)
 Check if point is inside area. More...
 
bool win_is_inside_clip (const struct win_clip_region *clip, const struct win_point *point)
 Check if point is inside clipping region. More...
 
bool win_is_inside_window (const struct win_window *win, const struct win_point *point)
 Check if global point is inside window. More...
 
void win_lower (struct win_window *win)
 Lower window to bottom of all its siblings. More...
 
static void win_process_command_event (struct win_command_event *cevent)
 Process a command event. More...
 
void win_process_events (void)
 Process all pending events from the internal queue. More...
 
static void win_process_keyboard_event (struct win_keyboard_event *kevent)
 Process a keyboard event. More...
 
void win_queue_command_event (const struct win_command_event *event)
 Add a command event to the internal event queue. More...
 
void win_queue_keyboard_event (const struct win_keyboard_event *event)
 Add a keyboard event to the internal event queue. More...
 
void win_queue_pointer_event (const struct win_pointer_event *event)
 Add a pointer event to the internal event queue. More...
 
void win_raise (struct win_window *win)
 Raise window to top of all its siblings. More...
 
void win_redraw (struct win_window *win)
 Redraw window and its contents, if visible. More...
 
void win_reparent (struct win_window *child, struct win_window *new_parent)
 Change a window's parent. More...
 
void win_reset_root_geometry (void)
 Reset root window geometry to fullscreen. More...
 
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. More...
 
void win_set_attributes (struct win_window *win, const struct win_attributes *new_attributes, win_attribute_mask_t attribute_mask)
 Update window attributes specified in attribute mask. More...
 
void win_set_keyboard_focus (struct win_window *win)
 Set keyboard focus window or NULL, i.e., receiver of keyboard events. More...
 
void win_show (struct win_window *win)
 Show window, draw it to screen if parent is visible. More...
 
void win_translate_win_to_root (struct win_window const *start_win, struct win_point *return_pos)
 Compute window position on root window. More...
 

Internal functions

Note
Due to circular references, these functions need private prototypes.
static bool win_is_visible (const struct win_window *win)
 Check if window and all parents, grand parents, etc. More...
 
static void win_draw (struct win_window *win, const struct win_area *dirty_area)
 Draw window, all its siblings and parents within dirty area. More...
 
static void win_draw_parent (struct win_window *child, const struct win_area *dirty_area)
 Draw parent window, with all child windows, within dirty area. More...
 
static void win_draw_contents (struct win_window *win, const struct win_clip_region *clip)
 Draw window background and contents, including children, within clip. More...
 
static void win_draw_child (struct win_window *child, const struct win_clip_region *parent_clip)
 Draw child window, with automatic translation of parent's clip region. More...
 
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. More...
 
static void win_destroy_children (struct win_window *win)
 Destroy child windows, freeing allocated memory. More...
 
static void win_unlink (struct win_window *win)
 Remove window from parent's linked list. More...
 
static void win_add_top_child (struct win_window *parent, struct win_window *child)
 Add window as first child in parent's linked list. More...
 
static void win_process_pointer_event (struct win_pointer_event *event)
 Helper function for processing pointer events. More...
 
static bool win_handle_pointer_event (struct win_window *win, const struct win_pointer_event *event, const struct win_point *pos)
 Handle pointer event in the window at the pointer coordinates. More...
 
static bool win_handle_event (struct win_window *win, enum win_event_type type, const void *data)
 Call window's event handler, if one is set. More...
 
static void win_queue_event (const struct win_event *event)
 Add an event to the internal queue. More...
 
static void win_pop_front_event (void)
 Remove front event from internal queue. More...
 
static bool win_are_events_pending (void)
 Check if internal queue has pending events. More...
 

Internal variables

static struct win_window win_root
 Root window, i.e. More...
 
static struct win_event win_event_queue_buffer [WIN_EVENT_QUEUE_SIZE]
 Event queue data buffer. More...
 
static struct win_event_queue win_event_queue
 Window event queue. More...
 
static uint32_t win_num_dropped_events
 Diagnostic value counting number of dropped events due to event queue full. More...
 
static struct win_windowwin_pointer_grabber
 Current pointer grabbing window, or NULL. More...
 
static struct win_windowwin_keyboard_focus
 Current keyboard focus, or NULL. More...
 
static struct win_point win_last_pointer_pos
 Stores last pointer event position, in absolute coordinates. More...
 
static struct gfx_bitmap win_root_background
 Frame background bitmap. More...
 

#define WIN_ATTR_BACKGROUND   (1 << 2)

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

Referenced by win_set_attributes().

#define WIN_ATTR_BEHAVIOR   (1 << 4)

Attribute mask for updating window behavior flags.

Referenced by win_set_attributes().

#define WIN_ATTR_CUSTOM   (1 << 5)

Attribute mask for updating window custom data.

Referenced by win_set_attributes().

#define WIN_ATTR_EVENTHANDLER   (1 << 3)

Attribute mask for updating window event handler.

Referenced by win_set_attributes().

#define WIN_ATTR_POSITION   (1 << 0)

Attribute mask for updating window position.

Referenced by win_set_area(), win_set_attributes(), wtk_handle_frame_release(), and wtk_resize_frame().

#define WIN_ATTR_SIZE   (1 << 1)

Attribute mask for updating window size.

Referenced by win_reset_root_geometry(), win_set_area(), win_set_attributes(), and wtk_resize_frame().

#define WIN_BEHAVIOR_RAISE_ON_PRESS   (1 << 0)

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

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.

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

typedef uint8_t win_attribute_mask_t

Datatype holding attribute masks, used when updating attributes.

typedef uint8_t win_behavior_t

Data type holding window behavior flags.

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.

Parameters
winPointer to window to handle the event for.
typeEvent type specifier.
dataPointer to event-specific data.
Return values
trueif event was accepted by the window.
falseif event was rejected by the window.

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.

Valid keyboard event types.

Enumerator
WIN_KEYBOARD_PRESS 

A key has been pressed.

WIN_KEYBOARD_RELEASE 

A key has been released.

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.

static void win_add_top_child ( struct win_window parent,
struct win_window child 
)
static

Add window as first child in parent's linked list.

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

Parameters
parentParent window for this child.
childChild window to add to parent.

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

Referenced by win_create(), win_lower(), win_raise(), and win_reparent().

static bool win_are_events_pending ( void  )
static

Check if internal queue has pending events.

This function returns true if the internal event queue is not empty.

Returns
True if events are pending.

References cpu_irq_restore(), cpu_irq_save(), and win_event_queue::used.

Referenced by win_process_events().

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 coords 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
winThe window to start from.
dirty_areaArea to be clipped, same coordinate system as window.
clipResulting clipping region, global coordinates.
Return values
trueThe resulting region is valid.
falseThe resulting region is an empty set.

References win_attributes::area, win_window::attributes, win_clip_region::NW, win_clip_region::origin, win_window::parent, win_area::pos, win_clip_region::SE, win_area::size, win_compute_intersection(), win_root, win_point::x, and win_point::y.

Referenced by win_draw(), and win_is_inside_window().

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

Compute the intersection of clipping region and area.

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
clipOriginal clipping region, and also where the result is stored.
areaArea to compute intersection with.
Return values
trueThe resulting area is valid.
falseThe resulting area is an empty set.

References win_clip_region::NW, win_area::pos, win_clip_region::SE, win_area::size, win_point::x, and win_point::y.

Referenced by win_compute_clipping().

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

Compute the smallest square containing two areas.

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

Parameters
areaFirst area, and also where the result is stored.
mergeSecond area, which is "merged" with the first.

References win_area::pos, win_area::size, win_point::x, and win_point::y.

Referenced by win_set_area().

struct win_window * win_create ( struct win_window parent,
const struct win_attributes attributes 
)

Create a window and return its pointer.

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
parentPointer to parent window.
attributesPointer to initial attributes.
Returns
Pointer to allocated window struct, or NULL.
Note
Use win_destroy() to free the memory used by a window.

References Assert, win_window::attributes, win_window::is_mapped, membag_alloc(), NULL, win_window::top_child, and win_add_top_child().

Referenced by wtk_basic_frame_create(), wtk_button_create(), wtk_check_box_create(), wtk_frame_create(), wtk_icon_button_create(), wtk_label_create(), wtk_plot_create(), wtk_progress_bar_create(), wtk_radio_button_create(), and wtk_slider_create().

void win_destroy ( struct win_window win)

Destroy a window, its contents and children to free 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
winPointer to window.

References Assert, win_window::is_mapped, membag_free(), NULL, win_destroy_children(), WIN_EVENT_DESTROY, win_handle_event(), win_hide(), win_root, and win_unlink().

Referenced by 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
winWindow whose children should be destroyed.

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

Referenced by win_destroy().

static void win_draw ( struct win_window win,
const struct win_area dirty_area 
)
static

Draw window, all its siblings and parents within dirty area.

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
winWindow to draw or redraw.
dirty_areaArea dictating which parts to draw.

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(), win_root, win_point::x, and win_point::y.

Referenced by win_draw_parent(), win_lower(), win_raise(), win_redraw(), win_set_area(), and win_set_attributes().

static void win_draw_child ( struct win_window child,
const struct win_clip_region parent_clip 
)
static

Draw child window, with automatic translation of parent's clip region.

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
childChild window to draw.
parent_clipClipping region, in global coordinates.

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, win_draw_contents(), win_point::x, and win_point::y.

Referenced by win_draw(), and win_draw_contents().

static void win_draw_contents ( struct win_window win,
const struct win_clip_region clip 
)
static

Draw window background and contents, including children, within 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
winThe window to draw.
clipClipping region, in global coordinates.

References win_window::attributes, win_attributes::background, gfx_draw_bitmap_tiled(), gfx_set_clipping(), win_window::is_mapped, NULL, 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, win_handle_event(), win_point::x, and win_point::y.

Referenced by win_draw(), and win_draw_child().

static void win_draw_parent ( struct win_window child,
const struct win_area dirty_area 
)
static

Draw parent window, with all child windows, within 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
childChild window.
dirty_areaThe area, given in same coordinate system as the child.

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

Referenced by win_draw(), win_hide(), and win_set_area().

struct win_area * win_get_area ( const struct win_window win)

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
winPointer to window.
Returns
Pointer to area struct.

References win_attributes::area, Assert, win_window::attributes, and NULL.

Referenced by wtk_button_handler(), wtk_frame_handler(), wtk_handle_frame_release(), wtk_handle_resize_release(), wtk_icon_button_handler(), wtk_label_handler(), wtk_plot_add_value(), wtk_plot_handler(), wtk_plot_set_grid(), 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)

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
winPointer to window.
Returns
Pointer to attribute struct.

References Assert, win_window::attributes, and NULL.

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
winPointer to window.
Returns
Copy of the custom data.

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

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

struct win_window * win_get_parent ( const struct win_window win)

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

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

Parameters
winChild window.
Returns
Pointer to parent window.

References win_window::parent.

Referenced by wtk_handle_frame_release(), and wtk_handle_resize_release().

struct win_window * win_get_root ( void  )

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.

References win_root.

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
winPointer 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_icon_button_handler(), 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's event handler, if one is set.

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
winWindow to handle event.
typeEvent type.
dataCustom data, dependent on event type.
Return values
trueEvent handler present and accepts event
falseNo event handler present or event handler doesn't accept event.

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

Referenced by win_destroy(), win_destroy_children(), win_draw_contents(), win_handle_pointer_event(), win_lower(), win_process_command_event(), win_process_keyboard_event(), win_process_pointer_event(), win_raise(), win_reset_root_geometry(), win_set_area(), win_set_attributes(), and win_set_keyboard_focus().

static bool win_handle_pointer_event ( struct win_window win,
const struct win_pointer_event event,
const struct win_point pos 
)
static

Handle pointer event in the window at the pointer coordinates.

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
winWindow to handle the event itself, or pass on to children.
eventPointer event to handle.
posAbsolute position, translated to window's own coordinates.
Returns
True if child or window itself accepted the event.

References win_attributes::area, win_window::attributes, win_attributes::behavior, win_window::is_mapped, win_window::next_sibling, NULL, 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, win_raise(), win_point::x, and win_point::y.

Referenced by win_process_pointer_event().

void win_hide ( struct win_window win)

Hide window, clear it from screen if it 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
winPointer to window.

References win_attributes::area, Assert, win_window::attributes, gfx_draw_filled_rect, gfx_get_height(), gfx_get_width(), gfx_set_clipping(), win_window::is_mapped, NULL, win_draw_parent(), win_is_visible(), and win_root.

Referenced by win_destroy(), and win_reparent().

void win_inflate_area ( struct win_area area,
int16_t  size 
)

Expands a given area in all directions by a given amount.

This function expands a given area in all directions by a given amount, keeping the area's center point fixed in the same location (i.e. the logical position of the center point does not move). Negative values can be specified to shrink an area by a given amount.

Note that the area boundaries are expanded on all sides by the given amount, thus the size expansion is twice the specified amount.

Parameters
areaPointer to the area to expand.
sizeSigned amount to expand the area by.

References Assert, win_area::pos, win_area::size, win_point::x, and win_point::y.

Referenced by wtk_slider_handler().

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.

References win_attributes::area, win_window::attributes, win_event_queue::back, win_attributes::background, win_event_queue::end, win_event_queue::free, win_event_queue::front, gfx_get_height(), gfx_get_width(), win_area::size, win_event_queue::start, win_event_queue_buffer, win_last_pointer_pos, win_root, win_root_background, win_point::x, and win_point::y.

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

Check if point is inside area.

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

Parameters
areaPointer to area.
pointPointer to point to check.
Returns
True if point is inside area.

References win_area::pos, win_area::size, win_point::x, and win_point::y.

Referenced by win_handle_pointer_event().

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

Check 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
clipPointer to clipping region.
pointPointer to point to check.
Returns
True if point is inside clipping region.

References win_clip_region::NW, win_clip_region::SE, win_point::x, and win_point::y.

Referenced by win_is_inside_window().

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

Check if global point is inside window.

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

Parameters
winWindow to check.
pointPoint in global coordinates.
Return values
trueif point is inside win.
falseif point is not inside win.

References win_attributes::area, win_window::attributes, win_compute_clipping(), and win_is_inside_clip().

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

static bool win_is_visible ( const struct win_window win)
static

Check if window and all parents, grand parents, etc.

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
winWindow to check.
Return values
truewin is visible.
falsewin is not visible.

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

Referenced by win_hide(), win_lower(), win_raise(), win_redraw(), win_set_area(), and win_set_attributes().

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
winPointer to window.

References win_attributes::area, Assert, win_window::attributes, win_window::next_sibling, NULL, win_window::parent, win_window::prev_sibling, win_window::top_child, win_add_top_child(), win_draw(), WIN_EVENT_RAISE, WIN_EVENT_UNRAISE, win_handle_event(), win_is_visible(), win_root, and win_unlink().

static void win_pop_front_event ( void  )
static

Remove front event from internal queue.

This function will remove the front event from the internal queue. This function will be called once an event has been processed. That way, the event will live in the queue while being processed, hence no copying of data required.

References cpu_irq_restore(), cpu_irq_save(), win_event_queue::end, win_event_queue::free, win_event_queue::front, win_event_queue::start, and win_event_queue::used.

Referenced by win_process_events().

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
ceventThe command event being processed.

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

Referenced by win_process_events().

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.

References Assert, win_event_queue::front, win_are_events_pending(), WIN_EVENT_COMMAND, WIN_EVENT_KEYBOARD, WIN_EVENT_POINTER, win_pop_front_event(), win_process_command_event(), win_process_keyboard_event(), and win_process_pointer_event().

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
keventThe keyboard event being processed.

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

Referenced by win_process_events().

static void win_process_pointer_event ( struct win_pointer_event event)
static

Helper function for processing pointer 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
eventPointer event data to process.

References win_pointer_event::is_relative, NULL, WIN_EVENT_POINTER, win_handle_event(), win_handle_pointer_event(), win_last_pointer_pos, win_root, win_point::x, and win_point::y.

Referenced by win_process_events().

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
eventPointer to command event data.

References win_event::command, win_event::type, WIN_EVENT_COMMAND, and win_queue_event().

Referenced by wtk_button_handler(), wtk_check_box_handler(), wtk_icon_button_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.

Parameters
eventEvent to add to the queue.

References win_event_queue::back, cpu_irq_restore(), cpu_irq_save(), win_event_queue::end, win_event_queue::free, win_event_queue::start, win_event::timestamp, win_event_queue::used, and win_num_dropped_events.

Referenced by win_queue_command_event(), win_queue_keyboard_event(), and win_queue_pointer_event().

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
eventPointer to keyboard event data.

References win_event::keyboard, win_event::type, WIN_EVENT_KEYBOARD, and win_queue_event().

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
eventPointer to pointer event data.

References win_event::pointer, win_event::type, WIN_EVENT_POINTER, and win_queue_event().

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
winPointer to window.

References win_attributes::area, Assert, win_window::attributes, NULL, win_window::parent, win_window::top_child, win_add_top_child(), win_draw(), WIN_EVENT_RAISE, WIN_EVENT_UNRAISE, win_handle_event(), win_is_visible(), win_root, and win_unlink().

Referenced by win_handle_pointer_event().

void win_redraw ( 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
winPointer to window.

References win_attributes::area, win_window::attributes, win_draw(), and win_is_visible().

Referenced by win_reset_root_geometry(), win_show(), wtk_button_handler(), wtk_check_box_handler(), wtk_check_box_set(), wtk_check_box_toggle(), wtk_icon_button_handler(), wtk_icon_button_select(), wtk_label_change(), wtk_progress_bar_set_value(), 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
childPointer to child window to reparent.
new_parentPointer to new parent.

References Assert, win_window::is_mapped, NULL, win_add_top_child(), win_hide(), win_root, win_show(), and win_unlink().

void win_reset_root_geometry ( void  )

Reset root window geometry to fullscreen.

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.

References win_attributes::area, win_window::attributes, gfx_get_height(), gfx_get_width(), win_area::size, WIN_ATTR_SIZE, WIN_EVENT_ATTRIBUTES, win_handle_event(), win_redraw(), win_root, win_point::x, and win_point::y.

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
winPointer to window that will be updated.
new_areaPointer to new area attributes.
attribute_maskAttribute flags selecting which attributes to update.

References win_attributes::area, Assert, win_window::attributes, NULL, win_area::pos, win_area::size, WIN_ATTR_POSITION, WIN_ATTR_SIZE, win_compute_union(), win_draw(), win_draw_parent(), WIN_EVENT_ATTRIBUTES, win_handle_event(), win_is_visible(), win_root, win_point::x, and win_point::y.

Referenced by win_set_attributes(), 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 specified in 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
winPointer to window that will be updated.
new_attributesPointer to new attribute values.
attribute_maskAttribute flags selecting which attributes to update.

References win_attributes::area, Assert, win_window::attributes, win_attributes::background, win_attributes::behavior, win_attributes::custom, win_attributes::event_handler, NULL, WIN_ATTR_BACKGROUND, WIN_ATTR_BEHAVIOR, WIN_ATTR_CUSTOM, WIN_ATTR_EVENTHANDLER, WIN_ATTR_POSITION, WIN_ATTR_SIZE, win_draw(), WIN_EVENT_ATTRIBUTES, win_handle_event(), win_is_visible(), and win_set_area().

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
winPointer to the new keyboard focus window, or NULL.

References NULL, WIN_EVENT_GETFOCUS, WIN_EVENT_LOSEFOCUS, and win_handle_event().

void win_show ( struct win_window win)

Show window, draw it to screen if parent is visible.

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
winPointer to window.

References Assert, win_window::is_mapped, NULL, and win_redraw().

Referenced by win_reparent(), 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
areaThe area to translate.
parentParent window.
Return values
trueThe resulting area is valid.
falseThe resulting area is an empty set.

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

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_winThe window of which to find absolute position.
Return values
return_posThe absolute position of the window

References win_attributes::area, Assert, win_window::attributes, win_window::parent, win_area::pos, win_point::x, and win_point::y.

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
winWindow to be unlinked from parent.

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

Referenced by win_destroy(), win_lower(), win_raise(), and win_reparent().

Window event queue.

struct win_event win_event_queue_buffer[WIN_EVENT_QUEUE_SIZE]
static

Event queue data buffer.

Referenced by win_init().

struct win_window* win_keyboard_focus
static

Current keyboard focus, or NULL.

Keyboard focus gets all keyboard events.

Referenced by win_process_keyboard_event().

struct win_point win_last_pointer_pos
static

Stores last pointer event position, in absolute coordinates.

Referenced by win_init(), and win_process_pointer_event().

uint32_t win_num_dropped_events
static

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

Referenced by win_queue_event().

struct win_window* win_pointer_grabber
static

Current pointer grabbing window, or NULL.

Grabber gets all pointer events.

struct gfx_bitmap win_root_background
static
Initial value:
= {
.data.color = GFX_COLOR_BLACK,
}
#define GFX_COLOR_BLACK
Definition: gfx.h:158
Definition: gfx_generic.h:69

Frame background bitmap.

Referenced by win_init().