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

#include <ParaScriptingGUI.h>

Static Public Member Functions
static void	PlaySound (const char *strSoundAssetName, bool bLoop)
	Play a sound file. More...

static void	StopSound (const char *strSoundAssetName)
	stop playing a sound file. More...

static void	Destroy (const char *strObjectName)
	delete a GUI object as well as all its child objects, by it name. More...

static void	Destroy1 (int nID)
	delete a GUI object as well as all its child objects, by it name. More...

static void	DestroyUIObject (ParaUIObject &obj)
	destroy an UI object

static void	PostDestroy (const char *strObjectName)
	delete at the end of frame.

static ParaUIObject	GetUIObject_any (const object &NameOrID)
	Get GUI object by name or ID. More...

static ParaUIObject	GetUIObject (const char *Name)

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. More...

static void	SetMousePosition (float x, float y)

static bool	IsKeyPressed (int nDikScanCode)

static bool	IsMousePressed (int nButton)

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. More...

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). More...

static void	SetCursorFont (const char fontname, const char strColor, DWORD transparency)
	@ obsoleted. More...

static void	SetCursorTexture (const char texturename, const char strColor, DWORD transparency)
	. More...

static void	SetCursorText (const char *strText)
	. More...

static void	SetCursorFromFile (const char *szCursor, int XHotSpot, int YHotSpot)
	Set the current cursor to use. More...

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. More...

static bool	GetUseSystemCursor ()
	get whether to use system cursor

static string	ToScript ()
	to NPL script. More...

static bool	SaveLayout (const char *filename)
	save current layout to file More...

static void	SetDesignTime (bool bDesign)
	whether to enable edit mode for all controls. More...

static void	ShowCursor (bool bShow)
	show cursor More...

static void	LockMouse (bool bLock)
	Lock Mouse so that mouse move will not change the mouse position. More...

static bool	IsMouseLocked ()
	check whether Mouse is locked. More...

static void	ResetUI ()
	clear all UI objects. More...

static void	SetIMEOpenStatus (bool bOpen)
	This function opens or closes the IME programmtically. More...

static bool	GetIMEOpenStatus ()
	Check if IME status is opened. More...

static void	SetUIScale (float fScalingX, float fScalingY)
	set the UI scaling. More...

static void	SetMinimumScreenSize (int nWidth, int nHeight, bool bAutoUIScaling)
	the minimum screen size. More...

static void	AddDragReceiver (const char *sName)
	add an receiver to the current receiver list during an drag operation. More...

static void	SetToolTipBehavior (const char *behavior)
	How tooltip is displayed. More...

static bool	SetHighlightParam (const char szEffectName, const char szParamName, const char *szParamValue)
	Set Highlight Param. More...

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.

Member Function Documentation

§ AddDragReceiver()

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.

§ CreateUIObject()

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

§ Destroy()

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

§ Destroy1()

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.

§ GetDefaultObject()

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.

§ GetIMEOpenStatus()

bool ParaScripting::ParaUI::GetIMEOpenStatus ( )

static

Check if IME status is opened.

§ GetMousePosition()

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

§ GetUIObject_any()

ParaUIObject ParaScripting::ParaUI::GetUIObject_any ( const object & NameOrID )

static

Get GUI object by name or ID.

Parameters

NameOrID if it is string, we will get the first GUI object that matches the name. If name is "root", the root object is returned. if it is number , we will get the object by its ID. NameOrID is then the id property value or result of GetID() from a UI object. If this is 0, the root object is returned.

§ IsMouseLocked()

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.

§ LockMouse()

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

§ PlaySound()

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

static

Play a sound file.

Parameters

strObjectName the sound object name

§ ResetUI()

void ParaScripting::ParaUI::ResetUI ( )

static

clear all UI objects.

§ SaveLayout()

bool ParaScripting::ParaUI::SaveLayout ( const char * filename )

static

save current layout to file

Parameters

*filename

Returns

§ SetCursorFont()

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

static

@ obsoleted.

Set Mouse Cursor appearance

§ SetCursorFromFile()

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.

§ SetCursorText()

void ParaScripting::ParaUI::SetCursorText ( const char * strText )

static

.

Set Mouse Cursor appearance

§ SetCursorTexture()

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

static

.

Set Mouse Cursor appearance

§ SetDesignTime()

void ParaScripting::ParaUI::SetDesignTime ( bool bDesign )

static

whether to enable edit mode for all controls.

Parameters

bDesign

§ SetHighlightParam()

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

§ SetIMEOpenStatus()

void ParaScripting::ParaUI::SetIMEOpenStatus ( bool bOpen )

static

This function opens or closes the IME programmtically.

In most cases, we should never programmatically open or closes IME, instead the user usually pressed Ctrl+Space to change it. however, in some rare cases, such as we are opening a windowed mode flash window, and wants to disable IME programmatically.

Parameters

bOpen true to open.

§ SetMinimumScreenSize()

void ParaScripting::ParaUI::SetMinimumScreenSize	(	int	nWidth,
		int	nHeight,
		bool	bAutoUIScaling
	)

static

the minimum screen size.

if the backbuffer is smaller than this, we will use automatically use UI scaling for example, if minimum width is 1024, and backbuffer it 800, then m_fUIScalingX will be automatically set to 1024/800.

Parameters

nWidth	the new width.
nHeight	the new height.
bAutoUIScaling	usually set to true. whether we will automatically recalculate the UI scaling accordingly with regard to current backbuffer size.

§ SetToolTipBehavior()

void ParaScripting::ParaUI::SetToolTipBehavior ( const char * behavior )

static

How tooltip is displayed.

Parameters

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

§ SetUIScale()

void ParaScripting::ParaUI::SetUIScale	(	float	fScalingX,
		float	fScalingY
	)

static

set the UI scaling.

This can be useful to render 1024*768 to a 800*600 surface; we can set to fScalingX to 800/1024 and fScalingY to 600/768 calling this function will cause OnSize() and UpdateBackbufferSize() to be called.

Parameters

fScalingX	x defaults to 1.0
fScalingY	y defaults to 1.0

§ SetUseSystemCursor()

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.

§ ShowCursor()

void ParaScripting::ParaUI::ShowCursor ( bool bShow )

static

show cursor

Parameters

bShow

§ StopSound()

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

§ ToScript()

string ParaScripting::ParaUI::ToScript ( )

static

to NPL script.

The documentation for this class was generated from the following files:

Client/trunk/ParaEngineClient/ParaScriptBindings/ParaScriptingGUI.h
Client/trunk/ParaEngineClient/ParaScriptBindings/ParaScriptingGUI.cpp

Static Public Member Functions

Detailed Description

Member Function Documentation

§ AddDragReceiver()

§ CreateUIObject()

§ Destroy()

§ Destroy1()

§ GetDefaultObject()

§ GetIMEOpenStatus()

§ GetMousePosition()

§ GetUIObject_any()

§ IsMouseLocked()

§ LockMouse()

§ PlaySound()

§ ResetUI()

§ SaveLayout()

§ SetCursorFont()

§ SetCursorFromFile()

§ SetCursorText()

§ SetCursorTexture()

§ SetDesignTime()

§ SetHighlightParam()

§ SetIMEOpenStatus()

§ SetMinimumScreenSize()

§ SetToolTipBehavior()

§ SetUIScale()

§ SetUseSystemCursor()

§ ShowCursor()

§ StopSound()

§ ToScript()