ParaScripting::ParaUI Class Reference
[ParaUI]

List of all members.

---

Detailed Description

ParaUI namespace contains a list of HAPI functions to create user interface controls, such as windows, buttons, as well as event triggers.

The main difference between the two is that (1) 2D GUI object are not tested against view frustum, instead it¡¯s controlled by visibility tag automatically or through user input. (2) 2D GUI object generally does not obey the physical law of 3D world. (3) GUI object are generally specified by screen coordinates, instead of 3D position. (4) GUI object may be frequently created and discarded. If a object is discarded, so will its child objects. E.g. if one delete a window, all buttons, sensors, etc attach to it will also be discarded.

Static Public Member Functions
static void	PlaySound (const char *strSoundAssetName, bool bLoop)
	Play a sound file.
static void	StopSound (const char *strSoundAssetName)
	stop playing a sound file.
static void	Destroy (const char *strObjectName)
	delete a GUI object as well as all its child objects, by it name.
static void	Destroy1 (int nID)
	delete a GUI object as well as all its child objects, by it name.
static void	DestroyUIObject (ParaUIObject &obj)
	destroy an UI object
static void	PostDestroy (const char *strObjectName)
	delete at the end of frame.
static ParaUIObject	GetUIObject (const char *strObjectName)
	Get the first GUI object that matches the name.
static ParaUIObject	GetUIObject1 (int nID)
	get UI object by its ID.
static ParaUIObject	GetUIObjectAtPoint (int x, int y)
	Get the first GUI object at the given coordinates x: x coordinate y: y coordinate.
static void	GetMousePosition (float &x, float &y)
	get the current mouse position.
static bool	IsKeyPressed (int nDikScanCode)
static ParaUIObject	CreateUIObject (const char *strType, const char *strObjectName, const char *alignment, int x, int y, int width, int height)
	Create a GUI object based on the default template object.
static ParaUIObject	GetTopLevelControl ()
	get the top level control at level 0
static ParaUIObject	GetDefaultObject (const char *strType)
	get the default template object from which all sub-sequent controls of the same type are cloned(created).
static void	SetCursorFont (const char *fontname, const char *strColor, DWORD transparency)
	@ obsoleted.
static void	SetCursorTexture (const char *texturename, const char *strColor, DWORD transparency)
	.
static void	SetCursorText (const char *strText)
	.
static void	SetCursorFromFile (const char *szCursor, int XHotSpot, int YHotSpot)
	Set the current cursor to use.
static void	SetCursorFromFile_ (const char *szCursor)
	same as above, with hot spot (0,0)
static const char *	GetCursorFile ()
static void	SetUseSystemCursor (bool bUseSystem)
	whether to use system cursor.
static bool	GetUseSystemCursor ()
	get whether to use system cursor
static string	ToScript ()
	to NPL script.
static bool	SaveLayout (const char *filename)
	save current layout to file
static void	SetDesignTime (bool bDesign)
	whether to enable edit mode for all controls.
static void	ShowCursor (bool bShow)
	show cursor
static void	LockMouse (bool bLock)
	Lock Mouse so that mouse move will not change the mouse position.
static bool	IsMouseLocked ()
	check whether Mouse is locked.
static void	ResetUI ()
	clear all UI objects.
static void	AddDragReceiver (const char *sName)
	add an receiver to the current receiver list during an drag operation.
static void	SetToolTipBehavior (const char *behavior)
	How tooltip is displayed.
static ParaToolTip	GetToolTip ()
	get tool tip object
static bool	SetHighlightParam (const char *szEffectName, const char *szParamName, const char *szParamValue)
	Set Highlight Param.
static ParaUIGraphics	CreateGraphics (string name)
	create a new graphics object for drawing primitives on to a render target
static ParaUIGraphics	GetGraphics (string name)
	get the graphics object with a given name
static ParaFlashPlayer	GetFlashPlayer (const char *sFileName)
	get flash player pointer by name.
static ParaFlashPlayer	GetFlashPlayer1 (int nIndex)
	get flash player pointer by index.

---

Member Function Documentation

void ParaScripting::ParaUI::PlaySound	(	const char *	strSoundAssetName,
		bool	bLoop
	)			[static]

Play a sound file.

Parameters:

strObjectName,:

the sound object name

void ParaScripting::ParaUI::StopSound

(

const char *

strSoundAssetName

)

[static]

stop playing a sound file.

one can use this function to stop playing looping sound such as a background music.

Parameters:

strObjectName,:

the sound object name

void ParaScripting::ParaUI::Destroy

(

const char *

strObjectName

)

[static]

delete a GUI object as well as all its child objects, by it name.

If there are several objects who have the same id, only the last attached one is deleted.

Parameters:

strObjectName,:

the object name

void ParaScripting::ParaUI::Destroy1

(

int

nID

)

[static]

delete a GUI object as well as all its child objects, by it name.

If there are several objects who have the same id, only the last attached one is deleted.

Parameters:

nID,:

id.

ParaUIObject ParaScripting::ParaUI::GetUIObject

(

const char *

strObjectName

)

[static]

Get the first GUI object that matches the name.

Parameters:

strObjectName,:

the name of the control. If this is "root", the root object is returned.

ParaScripting::ParaUIObject ParaScripting::ParaUI::GetUIObject1

(

int

nID

)

[static]

get UI object by its ID.

Parameters:

nID,:

this is id property value or result of GetID() from a UI object. If this is 0, the root object is returned.

Returns:

: the control with the given id. return NULL if not find.

void ParaScripting::ParaUI::GetMousePosition	(	float &	x,
		float &	y
	)			[static]

get the current mouse position.

e.g. local x,y = ParaUI.GetMousePosition();

Parameters:

	&x	screen x
	&y	screen y

ParaUIObject ParaScripting::ParaUI::CreateUIObject	(	const char *	strType,
		const char *	strObjectName,
		const char *	alignment,
		int	x,
		int	y,
		int	width,
		int	height
	)			[static]

Create a GUI object based on the default template object.

All default template object is defined in "script/config.lua", which will be loaded when GUI engine is loaded. One can change template object at runtime by GetDefaultObject().

See also:

GetDefaultObject() Although it is possible to create many objects with the same name, we do not advice you to do so.

Parameters:

	strType,:	type of the new object. It can be "container", "button", "scrollbar", "editbox", "imeeditbox","slider", "video", "3dcanvas", "listbox", "painter" and "text". "container" is the only type of control that can contain other objects
	strObjectName,:	the new object's name
	alignment,:	can be one of the following strings or nil or left out entirely: "_lt" align to left top of the screen "_lb" align to left bottom of the screen "_ct" align to center of the screen "_ctt": align to center top of the screen "_ctb": align to center bottom of the screen "_ctl": align to center left of the screen "_ctr": align to center right of the screen "_rt" align to right top of the screen "_rb" align to right bottom of the screen "_mt": align to middle top "_ml": align to middle left "_mr": align to middle right "_mb": align to middle bottom "_fi": align to left top and right bottom. This is like fill in the parent window.

the layout is given below:
_lt _mt _rt
_ml _ct _mr
_lb _mb _rb

Parameters:

	x,:	screen coordinate x, for _m? alignments, the meaning is different, see remark
	y,:	screen coordinate y, for _m? alignments, the meaning is different, see remark
	width,:	screen coordinate width or right, depending on alignment mode, for _m? alignments, the meaning is different, see remark
	height,:	screen coordinate height or bottom, depending on alignment mode, for _m? alignments, the meaning is different, see remark

Remarks:

: we design _m? alignment types. _mt: x is coordinate from the left. y is coordinate from the top, width is the coordinate from the right and height is the height _mb: x is coordinate from the left. y is coordinate from the bottom, width is the coordinate from the right and height is the height _ml: x is coordinate from the left. y is coordinate from the top, width is the width and height is the coordinate from the bottom _mr: x is coordinate from the right. y is coordinate from the top, width is the width and height is the coordinate from the bottom

ParaUIObject ParaScripting::ParaUI::GetDefaultObject

(

const char *

strType

)

[static]

get the default template object from which all sub-sequent controls of the same type are cloned(created).

one can modify the template object at runtime to change of the theme of all controls created subsequently. All default template object is defined in "script/config.lua", which will be loaded when GUI engine is loaded

Parameters:

strType,:

It can be "container", "button", "scrollbar", "editbox", "imeeditbox","slider" and "text".

Returns:

the template object is returned.

void ParaScripting::ParaUI::SetCursorFont	(	const char *	fontname,
		const char *	strColor,
		DWORD	transparency
	)			[static]

@ obsoleted.

Set Mouse Cursor appearance

void ParaScripting::ParaUI::SetCursorTexture	(	const char *	texturename,
		const char *	strColor,
		DWORD	transparency
	)			[static]

.

Set Mouse Cursor appearance

void ParaScripting::ParaUI::SetCursorText

(

const char *

strText

)

[static]

.

Set Mouse Cursor appearance

void ParaScripting::ParaUI::SetCursorFromFile	(	const char *	szCursor,
		int	XHotSpot,
		int	YHotSpot
	)			[static]

Set the current cursor to use.

One can call very often, since it will does nothing with identical cursor file and hot spot. Typically, hardware supports only 32x32 cursors and, when windowed, the system might support only 32x32 cursors.

Parameters:

	szCursor	cursor file name: The contents of this texture will be copied and potentially format-converted into an internal buffer from which the cursor is displayed. The dimensions of this surface must be less than the dimensions of the display mode, and must be a power of two in each direction, although not necessarily the same power of two. The alpha channel must be either 0.0 or 1.0.
	XHotSpot	[in] X-coordinate offset (in pixels) that marks the center of the cursor. The offset is relative to the upper-left corner of the cursor. When the cursor is given a new position, the image is drawn at an offset from this new position determined by subtracting the hot spot coordinates from the position.
	YHotSpot	[in] Y-coordinate offset (in pixels) that marks the center of the cursor. The offset is relative to the upper-left corner of the cursor. When the cursor is given a new position, the image is drawn at an offset from this new position determined by subtracting the hot spot coordinates from the position.

void ParaScripting::ParaUI::SetUseSystemCursor

(

bool

bUseSystem

)

[static]

whether to use system cursor.

If this is true, d3d hardware cursor is not shown, even you have loaded an cursor icon using SetCursorFromFile.

string ParaScripting::ParaUI::ToScript

(

)

[static]

to NPL script.

bool ParaScripting::ParaUI::SaveLayout

(

const char *

filename

)

[static]

save current layout to file

Parameters:

*filename

Returns:

void ParaScripting::ParaUI::SetDesignTime

(

bool

bDesign

)

[static]

whether to enable edit mode for all controls.

Parameters:

bDesign

void ParaScripting::ParaUI::ShowCursor

(

bool

bShow

)

[static]

show cursor

Parameters:

bShow

void ParaScripting::ParaUI::LockMouse

(

bool

bLock

)

[static]

Lock Mouse so that mouse move will not change the mouse position.

this is useful when user is changing camera view during mouse drag operation.

Parameters:

bLock,:

true to lock

bool ParaScripting::ParaUI::IsMouseLocked

(

)

[static]

check whether Mouse is locked.

When mouse is locked, mouse move will not change the mouse position. this is useful when user is changing camera view during mouse drag operation.

void ParaScripting::ParaUI::ResetUI

(

)

[static]

clear all UI objects.

void ParaScripting::ParaUI::AddDragReceiver

(

const char *

sName

)

[static]

add an receiver to the current receiver list during an drag operation.

call this function on an dragable UI object's Begin Drag event handler.

Parameters:

sName,:

name. if this is "root", the dragging object can always to reattached.

void ParaScripting::ParaUI::SetToolTipBehavior

(

const char *

behavior

)

[static]

How tooltip is displayed.

Parameters:

behavior

"normal" or "flashing". default is "normal"

bool ParaScripting::ParaUI::SetHighlightParam	(	const char *	szEffectName,
		const char *	szParamName,
		const char *	szParamValue
	)			[static]

Set Highlight Param.

this is usually called in the start up configuration file.

Parameters:

	szEffectName
	szParamName
	szParamValue

Returns:

ParaScripting::ParaUIGraphics ParaScripting::ParaUI::CreateGraphics

(

string

name

)

[static]

create a new graphics object for drawing primitives on to a render target

Parameters:

name

the name of the graphics object

Returns:

ParaScripting::ParaFlashPlayer ParaScripting::ParaUI::GetFlashPlayer

(

const char *

sFileName

)

[static]

get flash player pointer by name.

this function does not create any player if there is no player with the given name.

ParaScripting::ParaFlashPlayer ParaScripting::ParaUI::GetFlashPlayer1

(

int

nIndex

)

[static]

get flash player pointer by index.

this function does not create any player if there is no player at the given index.

---