UI

User Interface Top Level control. More...

Data Structures
struct	T_UIGroupStruct
struct	T_UIObjectStruct

Macros
#define	GROUP_FOCUS_BAD   (-1)
#define	MAX_UI_OBJECTS_IN_GROUP   20

Functions
T_void	UIGroupAttachUIObject (T_UIGroup group, T_UIObject object)
T_UIGroup	UIGroupCreate (T_void)
T_void	UIGroupDestroy (T_UIGroup group)
T_void	UIGroupDraw (T_void)
T_void	UIGroupSetBackground (T_UIGroup group, T_resource background)
T_void	UIGroupSetScreen (T_UIGroup group, T_screen screen)
T_UIObject	UIObjectCreate (T_word16 size)
T_word16	UIObjectGetBottomPosition (T_UIObject object)
T_word16	UIObjectGetLeftPosition (T_UIObject object)
T_word16	UIObjectGetRightPosition (T_UIObject object)
T_word16	UIObjectGetTopPosition (T_UIObject object)
T_void	UIObjectSetArea (T_UIObject object, T_word16 left, T_word16 top, T_word16 right, T_word16 bottom)
T_void	UIObjectSetEventHandler (T_UIObject object, T_uiEventHandler uiEventHandler)
T_void	UISetActiveGroup (T_UIGroup group)

Detailed Description

User Interface Top Level control.

All UI components are collected here in one place regardless if it is a form or banner object. This handles the layering of the objects and events.

See Also

http://www.amuletsandarmor.com/AALicense.txt

Macro Definition Documentation

#define GROUP_FOCUS_BAD   (-1)

#define MAX_UI_OBJECTS_IN_GROUP   20

Function Documentation

T_void UIGroupAttachUIObject	(	T_UIGroup	group,
		T_UIObject	object
	)

UIGroupAttachUIObject is used to add objects to a UI Group. Each added object represents another piece of UI on the screen that will be passed UI Events.

NOTE: I can't really tell if the group and object are truly legal, but as long as they are not BAD, you should be ok.

Parameters

group	– Group to add object to
object	– Object to add

T_UIGroup UIGroupCreate

(

T_void

)

UIGroupCreate is used to allocate memory for a new UI Group. If there is not enough memory, a UI_GROUP_BAD is returned.

NOTE: Make sure that when you are returned a T_UIGroup that you check to see if it is UI_GROUP_BAD. In many cases, it is best just to bomb.

Returns

UIGroup or UI_GROUP_BAD if out of memory.

T_void UIGroupDestroy

(

T_UIGroup

group)

UIGroupDestroy detaches, deallocates, and cleans up all the objects under and including the UI Group. This routine is a all in one technique.

NOTE: The UIGroup being destroy MUST NOT be the active UI Group. Make to call UISetActiveGroup(UI_GROUP_BAD) before executing this command.

Parameters

group

– Group you want destroyed

T_void UIGroupDraw

(

T_void

)

UIGroupDraw draws the background image and all the objects that are part of this group. Note that it only does this to the active group.

NOTE: Be sure to call UISetActiveGroup and UIGroupSetScreen before using this command.

T_void UIGroupSetBackground	(	T_UIGroup	group,
		T_resource	background
	)

UIGroupSetBackground declares the background of the group you passed.

NOTE: Note that the background is not drawn until a UIGroupDraw command is issued.

Parameters

group	– Group to change background of
background	– Background resource to use

T_void UIGroupSetScreen	(	T_UIGroup	group,
		T_screen	screen
	)

UIGroupSetScreen tells what screen to draw all the objects to under a UI Group. Usually this will be a screen that was allocated for the purpose of being drawn once before being displayed.

NOTE: Screen must not be a NULL or SCREEN_BAD.

Parameters

group	– Group to change screen
screen	– Screen to use

T_UIObject UIObjectCreate

(

T_word16

size)

UIObjectCreate creates a general object that can be added to a UI Group. In addition, you can allocate additional memory for whatever use you see fit (usually for the specific UI objects like buttons). Just tell it how much space you need.

Parameters

size	– Size for ui object to allocate in addition to the normal amount.

Returns

Pointer to whole object. Returns UI_OBJECT_BAD if it count not allocate enough memory.

T_word16 UIObjectGetBottomPosition

(

T_UIObject

object)

UIObjectGetBottomPosition returns the bottom location of the UI Object.

Parameters

object

– Object to get bottom of

T_word16 UIObjectGetLeftPosition

(

T_UIObject

object)

UIObjectGetLeftPosition returns the left location of the UI Object.

Parameters

object

– Object to get left of

T_word16 UIObjectGetRightPosition

(

T_UIObject

object)

UIObjectGetRightPosition returns the right location of the UI Object.

Parameters

object

– Object to get right of

T_word16 UIObjectGetTopPosition

(

T_UIObject

object)

UIObjectGetTopPosition returns the top location of the UI Object.

Parameters

object

– Object to get top of

T_void UIObjectSetArea	(	T_UIObject	object,
		T_word16	left,
		T_word16	top,
		T_word16	right,
		T_word16	bottom
	)

UIObjectSetArea declares the region in which the UI object exists. In general, UI objects should never overlap, and if they do, they will have unpredictable results. Think of the ui objects as tiles, and just keep them that way. For this routine, pass the bounds of the rectangle along with the object handle to change.

NOTE: Make sure all sides are inside the screen and that left is left of right and top is above bottom.

Parameters

object	– Object to change bounds of
left	– Left edge of object
top	– Top edge of object
right	– Right edge of object
bottom	– Bottom edge of object

T_void UIObjectSetEventHandler	(	T_UIObject	object,
		T_uiEventHandler	uiEventHandler
	)

Most objects will need an event handler to control the functionality of the UI object. For example, buttons need to press inward when clicked and windows need to scroll. This routine declares the handler for the ui object. Passing a NULL will also turn off the event handler.

Parameters

object	– UI Object
uiEventHandler	– Routine to handle UI events.

T_void UISetActiveGroup

(

T_UIGroup

group)

Once a UIGroup object has been declared and set-up with all of its UIObjects, you can declare the UIGroup to be the active group. Use this routine to make the UIGroup connect into the system and receive mouse and keyboard events. If you no longer need to have an active UIGroup, send UI_GROUP_BAD to this routine.

Parameters

group

– Group to make active or use UI_GROUP_BAD for none.