Basic frame widget

Basic frame widget provides a frame with only a background color.

Data Structures
struct	wtk_basic_frame
	Basic frame control struct. More...

Typedefs
typedef bool(*	wtk_basic_frame_command_handler_t )(struct wtk_basic_frame *basic_frame, win_command_t command_data)
	Basic frame command event handler callback. More...
typedef void(*	wtk_basic_frame_draw_handler_t )(struct win_window *win, struct win_clip_region const *clip)
	Basic frame draw event handler callback. More...

Functions
struct win_window *	wtk_basic_frame_as_child (struct wtk_basic_frame *basic_frame)
	Get reference to basic frame window. More...
struct wtk_basic_frame *	wtk_basic_frame_create (struct win_window *parent, const struct win_area *area, struct gfx_bitmap *background, wtk_basic_frame_draw_handler_t draw_handler, wtk_basic_frame_command_handler_t frame_handler, void *custom_data)
	Create basic frame widget. More...
void *	wtk_basic_frame_get_custom_data (const struct wtk_basic_frame *basic_frame)
	Get basic frame custom data. More...
static bool	wtk_basic_frame_handler (struct win_window *win, enum win_event_type type, const void *data)
	Basic frame event handler. More...

typedef bool(* wtk_basic_frame_command_handler_t)(struct wtk_basic_frame *basic_frame, win_command_t command_data)

Basic frame command event handler callback.

The basic frame command event handler callback is used to handle command events from widgets inside the basic frame. Command events are typically queued when the user has given some input to a widget. Examples are pushing a button widget or checking a check box widget.

Note

The maximum stack usage can be affected by the implementation of the event handler. The handler will be called from within the event handling of the window system. This event handling is done recursively to traverse all child windows connected to the window root.

Parameters

basic_frame	Pointer to the basic frame which contains the widget that generated the event.
command_data	The command data that was set for the specific widget. This is typically an ID for the widget or a pointer to data needed by the widget. This is widget-specific.

Returns

True if the basic frame and it's children should be destroyed, false otherwise.

typedef void(* wtk_basic_frame_draw_handler_t)(struct win_window *win, struct win_clip_region const *clip)

Basic frame draw event handler callback.

The basic frame draw event handler callback can be used to draw simple graphical display elements without the need for implementing a custom widget. The handler is called to redraw the full or a subregion of basic frame after the background for the widget has been drawn.

If CONFIG_GFX_USE_CLIPPING has been set the clipping region is set before the handler is called.

Note

The maximum stack usage can be affected by the implementation of the event handler. The handler will be called from within the event handling of the window system. This event handling is done recursively to traverse all child windows connected to the window root.

Parameters

win	Pointer to the window of the basic frame widget to be drawn.
clip	Region of the basic frame to be drawn in global display coordinates.

struct win_window* wtk_basic_frame_as_child

(

struct wtk_basic_frame *

basic_frame

)

Get reference to basic frame window.

This function returns a reference to the window that should be used when managing the widget, such as move, resize, destroy and reparenting.

Parameters

basic_frame

Basic frame widget to manage.

Returns

Window to be used for managing the basic frame.

References Assert, and wtk_basic_frame::win.

Referenced by app_widget_launch().

struct wtk_basic_frame* wtk_basic_frame_create	(	struct win_window *	parent,
		const struct win_area *	area,
		struct gfx_bitmap *	background,
		wtk_basic_frame_draw_handler_t	draw_handler,
		wtk_basic_frame_command_handler_t	frame_handler,
		void *	custom_data
	)

Create basic frame widget.

This function creates a new basic frame widget. It allocates required memory and intializes necessary windows to create the widget. If there is not enough memory, the function returns NULL.

To destroy the widget and all its contents, and free its memory, call win_destroy() on the basic frame's child reference, given by wtk_basic_frame_as_child(), like this: "win_destroy(wtk_basic_frame_as_child(my_frame_ptr));".

Parameters

parent	Parent window.
area	Area of the internal contents.
background	Pointer to background bitmap for frame. NULL for transparent background. When background is transparent the parent window will automatically be redrawn when the basic frame is drawn.
draw_handler	Draw event handler. NULL for no handler.
frame_handler	Command event handler. NULL for no handler.
custom_data	Optional custom data link for application's command events.

Returns

Pointer to basic frame, or NULL if failed.

References win_attributes::area, Assert, win_attributes::background, win_attributes::behavior, win_attributes::custom, wtk_basic_frame::custom_data, wtk_basic_frame::draw_handler, win_attributes::event_handler, wtk_basic_frame::frame_handler, membag_alloc(), membag_free(), wtk_basic_frame::win, WIN_BEHAVIOR_REDRAW_PARENT, win_create(), and wtk_basic_frame_handler().

Referenced by app_widget_launch().

void* wtk_basic_frame_get_custom_data

(

const struct wtk_basic_frame *

basic_frame

)

Get basic frame custom data.

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

Parameters

basic_frame

Pointer to basic frame.

Returns

Copy of the custom data.

References Assert, and wtk_basic_frame::custom_data.

Referenced by app_calc_handler(), and widget_frame_command_handler().

static bool wtk_basic_frame_handler ( struct win_window *  win, enum win_event_type  type, const void *  data  )

static

Basic frame event handler.

This function is the window event handler for basic frame widgets. It handles all events sent to the windows composing the widget.

Parameters

win	Window receiving the event.
type	The event type.
data	Custom data, depending on event type.

Returns

True if the event was recognized and accepted.

References wtk_basic_frame::draw_handler, wtk_basic_frame::frame_handler, membag_free(), wtk_basic_frame::win, win_destroy(), WIN_EVENT_COMMAND, WIN_EVENT_DESTROY, WIN_EVENT_DRAW, WIN_EVENT_POINTER, and win_get_custom_data().

Referenced by wtk_basic_frame_create().