Frame widget implementation.

#include <compiler.h>
#include <stdint.h>
#include <stdlib.h>
#include <membag.h>
#include <string.h>
#include <wtk.h>

Data Structures
struct	wtk_frame
	Frame control struct. More...

enum	wtk_frame_state { WTK_FRAME_NORMAL, WTK_FRAME_AWAITING_MOVE, WTK_FRAME_MOVING, WTK_FRAME_AWAITING_RESIZE, WTK_FRAME_RESIZING }
	Valid states for frame, relevant to pointer and keyboard operations. More...

static struct win_point	wtk_drag_origin
	Drag origin position during drag operations. More...

static gfx_color_t *	wtk_drag_origin_pixmap
	Storage for saved screen beneath drag origin, NULL when not dragging. More...

static gfx_color_t *	wtk_drag_target_pixmap
	Storage for saved screen beneath drag target, NULL when not dragging. More...

static struct gfx_bitmap	wtk_frame_background
	Frame background bitmap. More...

static bool	wtk_frame_handler (struct win_window win, enum win_event_type type, void const data)
	This function is the window event handler for frame widgets. More...

static void	wtk_handle_frame_press (struct wtk_frame frame, struct win_pointer_event const event)
	This function is a helper function for the wtk_frame_handler() function. More...

static void	wtk_handle_frame_move (struct wtk_frame frame, struct win_pointer_event const event)
	This function is a helper function for the wtk_frame_handler() function. More...

static void	wtk_handle_frame_release (struct wtk_frame frame, struct win_pointer_event const event)
	This function is a helper function for the wtk_frame_handler() function. More...

static void	wtk_handle_resize_press (struct wtk_frame frame, struct win_pointer_event const event)
	This function is a helper function for the wtk_frame_handler() function. More...

static void	wtk_handle_resize_move (struct wtk_frame frame, struct win_pointer_event const event)
	This function is a helper function for the wtk_frame_handler() function. More...

static void	wtk_handle_resize_release (struct wtk_frame frame, struct win_pointer_event const event)
	This function is a helper function for the wtk_frame_handler() function. More...

static void	wtk_resize_frame (struct wtk_frame frame, struct win_area const contents_area)
	This function is a helper function used when creating a frame widget and when handling resize events. More...

static void	wtk_prepare_drag (struct win_point const *pos)
	This function prepares for a drag operation. More...

static bool	wtk_is_drag_threshold_exceeded (struct win_point const *pos)
	This function compares a given position with the drag origin prepared by the wtk_prepare_drag() function. More...

static void	wtk_start_drag (struct win_point const *pos)
	This function starts the drag operation. More...

static void	wtk_continue_drag (struct win_point const last_pos, struct win_point const pos)
	This function updated the drag target handle graphics. More...

static void	wtk_stop_drag (struct win_point const *last_pos)
	This function stops an ongoing drag operation. More...

struct win_window *	wtk_frame_as_parent (struct wtk_frame *frame)
	This function returns a reference to the window that should be used as a parent for child widgets and windows. More...

struct win_window *	wtk_frame_as_child (struct wtk_frame *frame)
	This function returns a reference to the window that should be used when managing the widget, such as move, resize, destroy and reparenting. More...

void *	wtk_frame_get_custom_data (struct wtk_frame const *frame)
	This function returns the custom data from the frame's attributes. More...

struct wtk_frame *	wtk_frame_create (struct win_window parent, struct win_area const area, char const caption, bool allow_resize, wtk_frame_handler_t frame_handler, void custom_data)
	This function creates a new frame widget. More...

enum wtk_frame_state

Valid states for frame, relevant to pointer and keyboard operations.

Enumerator
WTK_FRAME_NORMAL	Normal state, no moving or resizing.
WTK_FRAME_AWAITING_MOVE	Waiting for move, from key or drag.
WTK_FRAME_MOVING	Currently moving.
WTK_FRAME_AWAITING_RESIZE	Waiting for resize, from key or drag.
WTK_FRAME_RESIZING	Currently resizing.

static void wtk_continue_drag	(	struct win_point const *	last_pos,
		struct win_point const *	pos
	)

static

This function updated the drag target handle graphics.

Call this function from the MOVE event handler of the dragging widget. This function needs both the current position and the last used position. The last position will be either the position handed to wtk_start_drag() or the "pos" parameter of the last call to wtk_continue_drag(). The pointer event struct will keep this value for you. No need to store it yourself.

Parameters

last_pos	Last position.
pos	Current position.

References gfx_draw_filled_circle, gfx_get_height(), gfx_get_pixmap, gfx_get_width(), gfx_put_pixmap, gfx_set_clipping(), GFX_WHOLE, WTK_DRAG_HANDLE_RADIUS, wtk_drag_origin_pixmap, WTK_DRAG_PIXMAP_SIZE, WTK_DRAG_TARGET_COLOR, wtk_drag_target_pixmap, win_point::x, and win_point::y.

Referenced by wtk_handle_frame_move(), and wtk_handle_resize_move().

static void wtk_handle_frame_move	(	struct wtk_frame *	frame,
		struct win_pointer_event const *	event
	)

static

This function is a helper function for the wtk_frame_handler() function.

It is called when a pointer MOVE event is sent to the container window. This function either starts or continues a drag operation, depending on current state.

Parameters

frame	Frame the received the event.
event	Pointer event information.

References win_pointer_event::last_pos, win_pointer_event::pos, wtk_frame::state, wtk_continue_drag(), WTK_FRAME_AWAITING_MOVE, WTK_FRAME_MOVING, wtk_is_drag_threshold_exceeded(), and wtk_start_drag().

Referenced by wtk_frame_handler().

static void wtk_handle_frame_press	(	struct wtk_frame *	frame,
		struct win_pointer_event const *	event
	)

static

This function is a helper function for the wtk_frame_handler() function.

It is called when a pointer PRESS event is sent to the container window. This function prepares a drag operation.

Parameters

frame	Frame the received the event.
event	Pointer event information.

References wtk_frame::container, win_pointer_event::pos, wtk_frame::state, win_grab_pointer(), WTK_FRAME_AWAITING_MOVE, WTK_FRAME_NORMAL, and wtk_prepare_drag().

Referenced by wtk_frame_handler().

static void wtk_handle_frame_release	(	struct wtk_frame *	frame,
		struct win_pointer_event const *	event
	)

static

This function is a helper function for the wtk_frame_handler() function.

It is called when a pointer RELEASE event is sent to the container window. This function completes the move operation if the RELEASE event was inside the parent window's boundaries.

Parameters

frame	Frame the received the event.
event	Pointer event information.

References wtk_frame::container, win_pointer_event::last_pos, win_pointer_event::pos, win_area::pos, wtk_frame::state, WIN_ATTR_POSITION, win_get_area(), win_get_parent(), win_grab_pointer(), win_is_inside_window(), win_set_area(), wtk_drag_origin, WTK_FRAME_MOVING, WTK_FRAME_NORMAL, wtk_stop_drag(), win_point::x, and win_point::y.

Referenced by wtk_frame_handler().

static void wtk_handle_resize_move	(	struct wtk_frame *	frame,
		struct win_pointer_event const *	event
	)

static

This function is a helper function for the wtk_frame_handler() function.

It is called when a pointer MOVE event is sent to the resize window. This function either starts or continues a drag operation, depending on current state.

Parameters

frame	Frame the received the event.
event	Pointer event information.

References win_pointer_event::last_pos, win_pointer_event::pos, wtk_frame::state, wtk_continue_drag(), WTK_FRAME_AWAITING_RESIZE, WTK_FRAME_RESIZING, wtk_is_drag_threshold_exceeded(), and wtk_start_drag().

Referenced by wtk_frame_handler().

static void wtk_handle_resize_press	(	struct wtk_frame *	frame,
		struct win_pointer_event const *	event
	)

static

This function is a helper function for the wtk_frame_handler() function.

It is called when a pointer PRESS event is sent to the resize window. This function prepares a drag operation.

Parameters

frame	Frame the received the event.
event	Pointer event information.

References win_pointer_event::pos, wtk_frame::resize, wtk_frame::state, win_grab_pointer(), WTK_FRAME_AWAITING_RESIZE, WTK_FRAME_NORMAL, and wtk_prepare_drag().

Referenced by wtk_frame_handler().

static void wtk_handle_resize_release	(	struct wtk_frame *	frame,
		struct win_pointer_event const *	event
	)

static

This function is a helper function for the wtk_frame_handler() function.

It is called when a pointer RELEASE event is sent to the resize window. This function completes the resize operation if the RELEASE event was inside the parent window's boundaries.

Parameters

frame	Frame the received the event.
event	Pointer event information.

References wtk_frame::contents, win_pointer_event::last_pos, win_pointer_event::pos, win_area::size, wtk_frame::state, win_get_area(), win_get_parent(), win_grab_pointer(), win_is_inside_window(), wtk_drag_origin, WTK_FRAME_NORMAL, WTK_FRAME_RESIZING, wtk_resize_frame(), wtk_stop_drag(), win_point::x, and win_point::y.

Referenced by wtk_frame_handler().

static bool wtk_is_drag_threshold_exceeded ( struct win_point const * pos )

static

This function compares a given position with the drag origin prepared by the wtk_prepare_drag() function.

If either the X or Y distance exceeds the WTK_DRAG_THRESHOLD value, this function returns true. That is when the widget event handler should call wtk_start_drag().

Parameters

pos	Position to compare.

Returns: True if threshold exceeded.

References wtk_drag_origin, WTK_DRAG_THRESHOLD, win_point::x, and win_point::y.

Referenced by wtk_handle_frame_move(), and wtk_handle_resize_move().

static void wtk_prepare_drag ( struct win_point const * pos )

static

This function prepares for a drag operation.

No drag is started yet, but the drag origin is stored. To start a drag operation, one would repeatedly check if the drag threshold is exceeded, then call the wtk_start_drag() function.

Parameters

pos	Pointer position for drag origin.

References pos, and wtk_drag_origin.

Referenced by wtk_handle_frame_press(), and wtk_handle_resize_press().

static void wtk_resize_frame	(	struct wtk_frame *	frame,
		struct win_area const *	contents_area
	)

static

This function is a helper function used when creating a frame widget and when handling resize events.

Given a new size for the contents window, it resizes and rearranges the windows composing the frame so that the frame decorations are properly sized and positioned.

Parameters

frame	Frame to resize.
contents_area	New size for the contents window.

References wtk_frame::container, wtk_frame::contents, win_area::pos, wtk_frame::resize, win_area::size, WIN_ATTR_POSITION, WIN_ATTR_SIZE, win_get_area(), win_set_area(), WTK_FRAME_BOTTOMBORDER, WTK_FRAME_LEFTBORDER, WTK_FRAME_MIN_HEIGHT, WTK_FRAME_MIN_WIDTH, WTK_FRAME_RESIZE_HEIGHT, WTK_FRAME_RESIZE_WIDTH, WTK_FRAME_RIGHTBORDER, WTK_FRAME_TITLEBAR_HEIGHT, WTK_FRAME_TOPBORDER, win_point::x, and win_point::y.

Referenced by wtk_frame_create(), and wtk_handle_resize_release().

static void wtk_start_drag ( struct win_point const * pos )

static

This function starts the drag operation.

It will allocate memory to store the screen behind the drag handles and draw the handles themselves. Do not call this function unless wtk_prepare_drag() has been called first with the drag origin position. If there is not enough memory, this function will no draw anything, but it is still safe to call wtk_continue_drag() and wtk_stop_drag().

Parameters

pos	Current position of drag target.

References gfx_draw_filled_circle, gfx_get_height(), gfx_get_pixmap, gfx_get_width(), gfx_set_clipping(), GFX_WHOLE, membag_alloc(), membag_free(), WTK_DRAG_HANDLE_RADIUS, wtk_drag_origin, WTK_DRAG_ORIGIN_COLOR, wtk_drag_origin_pixmap, WTK_DRAG_PIXMAP_SIZE, WTK_DRAG_TARGET_COLOR, wtk_drag_target_pixmap, win_point::x, and win_point::y.

Referenced by wtk_handle_frame_move(), and wtk_handle_resize_move().

static void wtk_stop_drag ( struct win_point const * last_pos )

static

This function stops an ongoing drag operation.

Do not call this unless dragging has been started with wtk_start_drag() first. This function erases the drag handles and frees any allocated memory.

Parameters

last_pos Last position, as for wtk_continue_drag().

References gfx_get_height(), gfx_get_width(), gfx_put_pixmap, gfx_set_clipping(), membag_free(), WTK_DRAG_HANDLE_RADIUS, wtk_drag_origin, wtk_drag_origin_pixmap, WTK_DRAG_PIXMAP_SIZE, wtk_drag_target_pixmap, win_point::x, and win_point::y.

Referenced by wtk_handle_frame_release(), and wtk_handle_resize_release().

struct win_point wtk_drag_origin

static

Drag origin position during drag operations.

Referenced by wtk_handle_frame_release(), wtk_handle_resize_release(), wtk_is_drag_threshold_exceeded(), wtk_prepare_drag(), wtk_start_drag(), and wtk_stop_drag().

gfx_color_t* wtk_drag_origin_pixmap

static

Storage for saved screen beneath drag origin, NULL when not dragging.

Referenced by wtk_continue_drag(), wtk_start_drag(), and wtk_stop_drag().

gfx_color_t* wtk_drag_target_pixmap

static

Storage for saved screen beneath drag target, NULL when not dragging.

Referenced by wtk_continue_drag(), wtk_start_drag(), and wtk_stop_drag().

struct gfx_bitmap wtk_frame_background

static

Initial value:

= {
    .type = GFX_BITMAP_SOLID,
    .data.color = WTK_FRAME_BACKGROUND_COLOR,
}

Frame background bitmap.

Referenced by wtk_frame_create().

Microchip® Advanced Software Framework

Data Structures