CGUIScriptedInput is used to simulate user-input via scripted or randomized events. More...

#include <GUIScriptedInput.h>

Inheritance diagram for CGUIScriptedInput:

Classes
struct	ScriptedInputEvent_t
	Struct which holds the information for each event in the list. More...

Public Member Functions
virtual void	PollEvent ()

virtual void	StopIdle ()

Public Member Functions inherited from CGUIInputMedia
void	AddEvent (CGUIEvent *pkEvent)

eC_Bool	GetDebugMode () const

CGUIEvent *	GetEvent (eC_UInt uiIdleTime)

eC_UInt	GetMaxEventThreshold () const

eC_UInt	GetMinEventThreshold () const

virtual eC_Bool	GetMulitpleTouches () const

virtual void	GetOffset (eC_Int &riOffsetX, eC_Int &riOffsetY) const

Rotation_t	GetRotation () const

virtual void	GetSize (eC_Int &riSizeX, eC_Int &riSizeY) const

eC_UInt	GetSleepInterval () const

virtual void	PollEvent ()

CGUIEvent *	RetrieveEvent ()

void	SetDebugMode (const eC_Bool &bDebugMode)

void	SetMaxEventThreshold (const eC_UInt &uiMaxEventThreshold)

void	SetMinEventThreshold (const eC_UInt &uiMinEventThreshold)

virtual void	SetMultipleTouches (const eC_Bool &bMultipleTouches)

virtual void	SetOffset (const eC_Int &iOffsetX, const eC_Int &iOffsetY)

void	SetRotation (const Rotation_t &eRotation)

virtual void	SetSize (const eC_Int &iSizeX, const eC_Int &iSizeY)

void	SetSleepInterval (const eC_UInt &uiInterval)

virtual void	StopIdle ()

Static Public Member Functions
static void	AddGestureEvent (const eC_Int &iMouseXPos, const eC_Int &iMouseYPos, const eC_Value &vSpan, const eC_UInt &uiTime=0, const eC_Bool &bImmediate=false)

static void	AddKeyboardEvent (const EventType_t &eEventType, const eC_UInt &uiKey, const GUIKeyIdentifier_t &eGUIKey, const eC_UInt &uiTime=0, const eC_Bool &bImmediate=false)

static void	AddMouseEvent (const EventType_t eEventType, const eC_Int iMouseXPos, const eC_Int iMouseYPos, const eC_UInt uiTime=0, const eC_Bool bImmediate=false)

static void	AddMouseMovement (const eC_Int iMouseStartXPos, const eC_Int iMouseStartYPos, const eC_Int iMouseEndXPos, const eC_Int iMouseEndYPos, const eC_UInt uiDuration, const eC_Bool bDrag, const eC_UInt uiTime=0, const eC_Bool bImmediate=false)

static void	AddMouseWheel (const eC_Int &iMouseXPos, const eC_Int &iMouseYPos, const eC_Value &vDistance, const eC_UInt &uiModifiers, const eC_UInt &uiTime=0, const eC_Bool &bImmediate=false)

static void	ClearEventQueue ()
	Clears the internal event queue, removing all scripted events.

static void	CreateInstance (const eC_UInt uiStartDelay=5000)

static void	DeleteInstance ()

static void	EnableRunOnceMode (const eC_Bool bRunOnceMode)

static void	EnableStressTest (const eC_Bool bStressTestActive)

static void	EnableVirtualMouseCursor (const eC_Bool bShowMouseCursor)

static eC_Bool	IsEventQueueEmpty ()

static void	ReadFromFile (const eC_String &kPath)

static eC_Bool	SimulateKeyPress (const GUIKeyIdentifier_t &eKeyIdentifier)

static eC_Bool	SimulateLeftButtonClick (CGUIObject *pkObject)

Static Public Member Functions inherited from CGUIInputMedia
static void	DeleteInstance ()

Protected Member Functions
	CGUIScriptedInput (const eC_UInt uiStartTime)

CGUIEvent *	CreateRandomEvent ()

Protected Member Functions inherited from CGUIInputMedia
	CGUIInputMedia (const eC_Bool &bQueuedEvents=false, const AcquisitionType_t &eType=Polling)

virtual	~CGUIInputMedia ()

Additional Inherited Members
Public Types inherited from CGUIInputMedia
enum	AcquisitionType_t { Polling , Callback }
	how events are collected

enum	Rotation_t { ROTATION_0 , ROTATION_90 , ROTATION_180 , ROTATION_270 }
	rotation of input-device

Protected Attributes inherited from CGUIInputMedia
eC_Bool	m_bDebugMode
	debug-mode for input-device

eC_Bool	m_bMultipleTouches
	supports multiple touches

eC_Bool	m_bStopIdle
	stop idle when waiting for events

Rotation_t	m_eRotation
	current rotation used for input-device

eC_Int	m_iOffsetX
	x-offset

eC_Int	m_iOffsetY
	y-offset

eC_Int	m_iSizeX
	width

eC_Int	m_iSizeY
	height

eC_UInt	m_uiIdleTime
	maximum time to spend

eC_UInt	m_uiSleepInterval
	sleep interval

Detailed Description

CGUIScriptedInput is used to simulate user-input via scripted or randomized events.

The "scripted input" Module offers the possibility to create the GUI events by an xml file. One use case for this is to create automated user interface tests (Class: CGUIScriptedInput).

The GUIScriptedInput class can be operated in three modes:

Read scripted events from an XML File
Simulate events via C++ code
Generate random events (e.g. for Testing)

Use this class as follows: 1. Create an instance of your "normal" Input media as always. 2. Create an instance of CGUIScriptedInput

Note that the CGUIScriptedInput will begin processing of the internal event queue after the uiStartTime milliseconds have passed, this delay defaults to 5 seconds to allow for GUI startup including e.g., image loading on slow target devices.

Example:

CGUIInputWindows::CreateInstance(hWnd);

CGUIScriptedInput::CreateInstance(0);

CGUIInputWindows::CreateInstance

static void CreateInstance(const HWND &hWnd, const eC_Bool &bEmulateTouchScreen=false)

CGUIScriptedInput::CreateInstance

static void CreateInstance(const eC_UInt uiStartDelay=5000)

After events have been added - either by streaming them from an XML file, or by scripting them directly from code - they are held in an internal queue. This queue is continuously processed, so that an endless sequence of events is generated (unless the queue is empty, of course). The processing will restart with the first event after the delay time of the last event has passed.

Example: Events can be added from code by using the functions AddMouseEvent(), AddMouseMovement() or AddKeyboardEvent().

// Simulate a Button down -> Move -> Button Up (=dragging) event
CGUIScriptedInput::AddMouseEvent(ET_LBUTTONDOWN, 200,100);
CGUIScriptedInput::AddMouseMovement(200, 100, 80, 80, 1000, true);
CGUIScriptedInput::AddMouseEvent(ET_LBUTTONUP, 80,80);
 
// Simulate a key press on Escape
CGUIScriptedInput::AddKeyboardEvent(ET_KEYDOWN, 0, GK_ESCAPE);

Alternatively, in case an event is to be processed immediately as the next event and deleted afterwards, setting bImmediate of AddMouseEvent(), AddMouseMovement() or AddKeyboardEvent() to true will force the event to be placed in front of the next event to be handled. It will then be deleted after handling.

Note: Placing immediate events into the queue will delay the queue by the time required to process the newly added event. Adding multiple immediate events will cause the last added event to be executed first (FILO).

ONLY IF YOU USE GUILIANI_STREAM_GUI: Use the function ReadFromFile(Filename) to add events from file. The file should look like this:

    <EventScript>
        <NumEvents>2</NumEvents>            // This is the number of events. It must always fit the number of entries in the script.
        <Event>                             // Example for a mouse event:
            <Source>0</Source>              // This is the source for differ between a mouse (0) or keyboard (1) event.
            <Type>6</Type>                  // The number of the event enum from Event_t.
            <XPos>23</XPos>                 // The X position of the mouse cursor.
            <YPos>277</YPos>                // The Y position of the mouse cursor.
            <Time>200</Time>                // The time until the next event occurs.
        </Event>
        <Event>                             // Example for a keyboard event:
            <Source>1</Source>
            <Type>0</Type>
            <Key>0</Key>                    // The keycode number.
            <GUIKey>1</GUIKey>              // The Guiliani key enum number.
            <Time>5000</Time>
        </Event>
    </EventScript>

Constructor & Destructor Documentation

◆ CGUIScriptedInput()

CGUIScriptedInput::CGUIScriptedInput ( const eC_UInt uiStartTime )

protected

Constructor

Parameters

uiStartTime Start time

Member Function Documentation

◆ AddGestureEvent()

static void CGUIScriptedInput::AddGestureEvent	(	const eC_Int &	iMouseXPos,
		const eC_Int &	iMouseYPos,
		const eC_Value &	vSpan,
		const eC_UInt &	uiTime = `0`,
		const eC_Bool &	bImmediate = `false`
	)

static

Adds a gesture event to events list.

Parameters

iMouseXPos	x-position
iMouseYPos	y-position
vSpan	span
uiTime	Time in ms until the next event will be executed.
bImmediate	Whether the event is "immediate", i.e. to be executed independently of the queue and then deleted.

◆ AddKeyboardEvent()

static void CGUIScriptedInput::AddKeyboardEvent	(	const EventType_t &	eEventType,
		const eC_UInt &	uiKey,
		const GUIKeyIdentifier_t &	eGUIKey,
		const eC_UInt &	uiTime = `0`,
		const eC_Bool &	bImmediate = `false`
	)

static

Adds a keyboard event to events list.

Parameters

eEventType	Type of event.
uiKey	Key code to be executed.
eGUIKey	Name of Guiliani key identifier to be executed.
uiTime	Time in ms until the next event will be executed.
bImmediate	Whether the event is "immediate", i.e. to be executed independently of the queue and then deleted.

◆ AddMouseEvent()

static void CGUIScriptedInput::AddMouseEvent	(	const EventType_t	eEventType,
		const eC_Int	iMouseXPos,
		const eC_Int	iMouseYPos,
		const eC_UInt	uiTime = `0`,
		const eC_Bool	bImmediate = `false`
	)

static

Adds a mouse event to events list.

Parameters

eEventType	Type of event.
iMouseXPos	X position of mouse where the event will be executed.
iMouseYPos	Y position of mouse where the event will be executed.
uiTime	Time in ms until the next event will be executed.
bImmediate	Whether the event is "immediate", i.e. to be executed independently of the queue and then deleted.

◆ AddMouseMovement()

static void CGUIScriptedInput::AddMouseMovement	(	const eC_Int	iMouseStartXPos,
		const eC_Int	iMouseStartYPos,
		const eC_Int	iMouseEndXPos,
		const eC_Int	iMouseEndYPos,
		const eC_UInt	uiDuration,
		const eC_Bool	bDrag,
		const eC_UInt	uiTime = `0`,
		const eC_Bool	bImmediate = `false`
	)

static

Convenience method for adding a series of mouse events, simulating a movement of the mouse from the given start position to the end position. This will generate mouse events every 10 ms for the requested time.

Parameters

iMouseStartXPos	X position of mouse where the mouse movement starts.
iMouseStartYPos	Y position of mouse where the mouse movement starts.
iMouseEndXPos	X position of mouse where the mouse movement ends.
iMouseEndYPos	Y position of mouse where the mouse movement ends.
uiDuration	Time in ms for the mouse move event sequence.
bDrag	If true the left mouse button will be pressed for the movement.
uiTime	Time in ms from the last event in the mouse move sequence until the next event in the queue will be executed.
bImmediate	Whether the events generated are"immediate", i.e. to be executed independently of the queue and then deleted.

◆ AddMouseWheel()

static void CGUIScriptedInput::AddMouseWheel	(	const eC_Int &	iMouseXPos,
		const eC_Int &	iMouseYPos,
		const eC_Value &	vDistance,
		const eC_UInt &	uiModifiers,
		const eC_UInt &	uiTime = `0`,
		const eC_Bool &	bImmediate = `false`
	)

static

Adds a mouse wheel event to events list.

Parameters

iMouseXPos	X position of mouse where the event will be executed.
iMouseYPos	Y position of mouse where the event will be executed.
vDistance	distance for wheel
uiModifiers	modifiers
uiTime	Time in ms until the next event will be executed.
bImmediate	Whether the event is "immediate", i.e. to be executed independently of the queue and then deleted.

◆ CreateInstance()

static void CGUIScriptedInput::CreateInstance ( const eC_UInt uiStartDelay = 5000 )

static

Creates the singleton instance.

Parameters

uiStartDelay Time in ms until the first event will be executed.

◆ CreateRandomEvent()

CGUIEvent * CGUIScriptedInput::CreateRandomEvent ( )

protected

Creates a single random mouse or keyboard event Warning: It is the caller's responsibility to delete the returned pointer!

Returns: A newly allocated random event

◆ DeleteInstance()

static void CGUIScriptedInput::DeleteInstance ( )

static

Delete the instance

◆ EnableRunOnceMode()

static void CGUIScriptedInput::EnableRunOnceMode ( const eC_Bool bRunOnceMode )

static

Enables / Disables the "Demo-loop" mode of the queue. When in RunOnce-Mode, all scripted events in the queue will be deleted after handling.

Parameters

bRunOnceMode TRUE to enable run once mode, False otherwise (Demo-loop mode)

◆ EnableStressTest()

static void CGUIScriptedInput::EnableStressTest ( const eC_Bool bStressTestActive )

static

Enables / Disables generation of random events. Enabling stress test will generate random user input events and forward them to the GUI just as if a user was randomly operating it.

Parameters

bStressTestActive TRUE to enable stress test, False otherwise

◆ EnableVirtualMouseCursor()

static void CGUIScriptedInput::EnableVirtualMouseCursor ( const eC_Bool bShowMouseCursor )

static

Enables / Disables the virtual mouse cursor. A simulated mouse cursor will be moved to the scripted / generated mouse positions to indicate the current mouse position on the screen

Parameters

bShowMouseCursor TRUE if the mouse cursor shall be shown, False otherwise

◆ IsEventQueueEmpty()

static eC_Bool CGUIScriptedInput::IsEventQueueEmpty ( )

inlinestatic

Checks if the event queue is empty.

Returns: True if empty

◆ PollEvent()

virtual void CGUIScriptedInput::PollEvent ( )

virtual

this method will be called if the input device uses polling to receive events

Reimplemented from CGUIInputMedia.

◆ ReadFromFile()

static void CGUIScriptedInput::ReadFromFile ( const eC_String & kPath )

static

Read the events script file.

Parameters

kPath Path of the script file (needs the resource file handler).

◆ SimulateKeyPress()

static eC_Bool CGUIScriptedInput::SimulateKeyPress ( const GUIKeyIdentifier_t & eKeyIdentifier )

static

Helper method that creates/simulate keypress and release-events.

Parameters

eKeyIdentifier the used key.

Returns: True if successful, False otherwise

◆ SimulateLeftButtonClick()

static eC_Bool CGUIScriptedInput::SimulateLeftButtonClick ( CGUIObject * pkObject )

static

Helper method that creates/simulate the left button click (button down, followed by button up) events

Parameters

pkObject object where the mouse click should executed.

Returns: True if successful, False otherwise

◆ StopIdle()

virtual void CGUIScriptedInput::StopIdle ( )

inlinevirtual

Forces the input media to quit idling immediately. Called by the framework if the input media is requested to stop idling immediately. Classes derived from GUIInputMedia should implement StopIdle in such a way, that it interrupts any idling/sleeping code in GetEvent(). virtual is needed if sub-classes need to do extra stuff

Reimplemented from CGUIInputMedia.

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

GUIScriptedInput.h

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ CGUIScriptedInput()

Member Function Documentation

◆ AddGestureEvent()

◆ AddKeyboardEvent()

◆ AddMouseEvent()

◆ AddMouseMovement()

◆ AddMouseWheel()

◆ CreateInstance()

◆ CreateRandomEvent()

◆ DeleteInstance()

◆ EnableRunOnceMode()

◆ EnableStressTest()

◆ EnableVirtualMouseCursor()

◆ IsEventQueueEmpty()

◆ PollEvent()

◆ ReadFromFile()

◆ SimulateKeyPress()

◆ SimulateLeftButtonClick()

◆ StopIdle()