Foenix A2650 OS/f Library: control.h File Reference

Searching...

No Matches

#include <stdbool.h>
#include <mcp/syscalls.h>
#include "a2560k.h"

Data Structures
struct	Control
	This structure describes an instantiated control on a window. More...

Enumerations
enum	control_type { }

Functions
Control *	Control_New (ControlTemplate the_template, Window the_window, Rectangle *the_parent_rect, int16_t control_id, int16_t group_id)
	Allocate a Control object. More...

bool	Control_Destroy (Control **the_control)
	Frees all allocated memory associated with the passed object, and the object itself. More...

int16_t	Control_GetID (Control *the_control)
	Get the ID of the control. More...

control_type	Control_GetType (Control *the_control)
	Get the control type. More...

bool	Control_GetPressed (Control *the_control)
	Get the pressed/not pressed state. More...

Control *	Control_GetNextControl (Control *the_control)
	Get the next control in the chain. More...

bool	Control_SetNextControl (Control the_control, Control the_next_control)
	Links the control to the next control passed. More...

void	Control_SetActive (Control *the_control, bool is_active)
	Set the control's active/inactive state. More...

void	Control_SetPressed (Control *the_control, bool is_pressed)
	Set the control's pressed/unpressed state. More...

void	Control_MarkInvalidated (Control *the_control, bool invalidated)
	Mark the specified control is invalidated or validated Note: Marking a control as invalidated causes it to be added to the parent window's list of rects to be reblitted to the screen in next render pass. More...

void	Control_AlignToParentRect (Control *the_control)
	Set or uppdate the control's position and/or size as appropriate to the control's parent rect Call when parent window size has changed, when control is first created, etc. More...

bool	Control_IsRighter (Control the_control, int16_t x)
	Compare the control's right-edge coordinate to the passed value If the control is more to the right than the passed value, the passed value is updated with the control's right edge. More...

bool	Control_IsLefter (Control the_control, int16_t x)
	Compare the control's left-edge coordinate to the passed value If the control is more to the left than the passed value, the passed value is updated with the control's left edge. More...

bool	Control_UpdateFromTemplate (Control the_control, ControlTemplate the_template)
	Updates the passed control with new theme info from the passed control template Call this when the theme has been changed It allows existing controls to be updated in place, without having to free them and create new theme controls. More...

void	Control_Render (Control *the_control)
	Blits the control to the control's parent window if the control is visible, and if it is listed as invalidated Controls that are visible but not invalidated do not need redrawing. More...

Enumeration Type Documentation

◆ control_type

enum control_type

Enumerator
TEXT_BUTTON	for functions that return a control type, this value will be returned in the event of an error
TEXT_FIELD	flexible-width button with text caption
RADIO_BUTTON	flexible-width single-line text input field
CHECKBOX	mutually-exclusive radio button control, assign each control in the set the same group id
TITLEBAR	checkbox control. do not assign the same group id to each control, as checkboxes are not mutually exclusive.
TEXT_BOX	the titlebar of a window
IMAGE_BUTTON	multi-line text input field
CLOSE_WIDGET	a fixed height/width button control with no caption, up/down states, and a no defined shape in the theme, relying on the creating program to provide a bitmap.
SIZE_MINIMIZE	standard system control; the close widget of a window. do not add outside of the context of a window title bar.
SIZE_NORMAL	standard system control; the minimize widget of a window. do not add outside of the context of a window title bar.
SIZE_MAXIMIZE	standard system control; the normal-size widget of a window. do not add outside of the context of a window title bar.
H_SCROLLER	standard system control; the maximize widget of a window. do not add outside of the context of a window title bar.
V_SCROLLER	proportional control for handling horizontal scrolling within a defined area
LABEL	proportional control for handling vertical scrolling within a defined area
FUTURE_GROW_L	static text label
FUTURE_GROW_R	not sure these will be treated as generic controls, but reserving the id
FUTURE_GROW_UP	not sure these will be treated as generic controls, but reserving the id
FUTURE_GROW_DN	not sure these will be treated as generic controls, but reserving the id
RESERVED1x	not sure these will be treated as generic controls, but reserving the id
RESERVED2x	progress bar?
CUSTOM	image?

Function Documentation

◆ Control_AlignToParentRect()

void Control_AlignToParentRect ( Control * the_control )

Set or uppdate the control's position and/or size as appropriate to the control's parent rect Call when parent window size has changed, when control is first created, etc.

Parameters

the_control – a valid Control object

◆ Control_Destroy()

bool Control_Destroy ( Control ** the_control )

Frees all allocated memory associated with the passed object, and the object itself.

Parameters

the_control – pointer to the pointer for the Control object to be destroyed

Returns: Returns false if the pointer to the passed control was NULL

◆ Control_GetID()

int16_t Control_GetID ( Control * the_control )

Get the ID of the control.

Parameters

the_control – a valid Control object

Returns: Returns the ID of the passed control, or -1 in any error condition

◆ Control_GetNextControl()

Control * Control_GetNextControl ( Control * the_control )

Get the next control in the chain.

Parameters

the_control – a valid Control object

Returns: Returns the control object linked as the next control of the passed control. Returns NULL if there is no next control, or if the next control is itself NULL, or on any error. The last control in a chain will return NULL.

◆ Control_GetPressed()

bool Control_GetPressed ( Control * the_control )

Get the pressed/not pressed state.

Parameters

the_control – a valid Control object

Returns: Returns true if control is pressed (down), false if up

◆ Control_GetType()

control_type Control_GetType ( Control * the_control )

Get the control type.

Parameters

the_control – a valid Control object

Returns: Returns the control_type value of the passed control, or CONTROL_TYPE_ERROR (-1) on any error

◆ Control_IsLefter()

bool Control_IsLefter	(	Control *	the_control,
		int16_t *	x
	)

Compare the control's left-edge coordinate to the passed value If the control is more to the left than the passed value, the passed value is updated with the control's left edge.

Parameters

the_control	– a valid Control object
x	– a pointer to a bitmap horizontal position. May be changed by the function.

Returns: Returns true if the control is further to the left than the passed value.

◆ Control_IsRighter()

bool Control_IsRighter	(	Control *	the_control,
		int16_t *	x
	)

Compare the control's right-edge coordinate to the passed value If the control is more to the right than the passed value, the passed value is updated with the control's right edge.

Parameters

the_control	– a valid Control object
x	– a pointer to a bitmap horizontal position. May be changed by the function.

Returns: Returns true if the control is further to the right than the passed value.

◆ Control_MarkInvalidated()

void Control_MarkInvalidated	(	Control *	the_control,
		bool	invalidated
	)

Mark the specified control is invalidated or validated Note: Marking a control as invalidated causes it to be added to the parent window's list of rects to be reblitted to the screen in next render pass.

Parameters

the_control	– a valid Control object
invalidated	– set to true to set control state to invalidated (will need redraw), false to set to not-invalidated

◆ Control_New()

Control * Control_New	(	ControlTemplate *	the_template,
		Window *	the_window,
		Rectangle *	the_parent_rect,
		int16_t	control_id,
		int16_t	group_id
	)

Allocate a Control object.

Parameters

the_template	– reference to a valid, populated ControlTemplate object. The created control will take most of its properties from this template.
the_window	– reference to a valid Window object. The newly-created control will not be added to the window's list of controls, but the control will remember this window as its parent
the_parent_rect	– Reference to rect object that the control will position itself relative to. This rect must remain valid throughout the life of the control.
control_id	– the unique ID (within the specified window) to be assigned to the control. WARNING: assigning multiple controls the same ID will result in undefined behavior.
group_id	– group ID value to be assigned to the control. Pass CONTROL_NO_GROUP if the control is not to be part of a group.

Returns: Returns a new Control object that has been localized to the passed parent rect. Returns NULL on any error condition.

◆ Control_Render()

void Control_Render ( Control * the_control )

Blits the control to the control's parent window if the control is visible, and if it is listed as invalidated Controls that are visible but not invalidated do not need redrawing.

Also draws the caption of the control, if it has one. Marks control as no longer invalidated.

Parameters

the_control – a valid Control object

◆ Control_SetActive()

void Control_SetActive	(	Control *	the_control,
		bool	is_active
	)

Set the control's active/inactive state.

Parameters

the_control	– a valid Control object
is_active	– set to true to set control to active, false to set to inactive

◆ Control_SetNextControl()

bool Control_SetNextControl	(	Control *	the_control,
		Control *	the_next_control
	)

Links the control to the next control passed.

Parameters

the_control	– a valid Control object
the_next_control	– a valid Control object to be set as the next control from the_control. Can be NULL.

Returns: Returns false on any error

◆ Control_SetPressed()

void Control_SetPressed	(	Control *	the_control,
		bool	is_pressed
	)

Set the control's pressed/unpressed state.

Parameters

the_control	– a valid Control object
is_pressed	– set to true to set control state to pressed, false to set to not-pressed

◆ Control_UpdateFromTemplate()

bool Control_UpdateFromTemplate	(	Control *	the_control,
		ControlTemplate *	the_template
	)

Updates the passed control with new theme info from the passed control template Call this when the theme has been changed It allows existing controls to be updated in place, without having to free them and create new theme controls.

Parameters

the_control	– a valid Control object
the_template	– a valid ControlTemplate object to update the Control object from.

Returns: Returns false on any error

Data Structures

Enumerations

Functions

Enumeration Type Documentation

◆ control_type

Function Documentation

◆ Control_AlignToParentRect()

◆ Control_Destroy()

◆ Control_GetID()

◆ Control_GetNextControl()

◆ Control_GetPressed()

◆ Control_GetType()

◆ Control_IsLefter()

◆ Control_IsRighter()

◆ Control_MarkInvalidated()

◆ Control_New()

◆ Control_Render()

◆ Control_SetActive()

◆ Control_SetNextControl()

◆ Control_SetPressed()

◆ Control_UpdateFromTemplate()