GetDescription method

Description

VWorks software calls the GetDescription method to get the description for the specified task from the plugin. Depending on the value of the Verbose parameter, the plugin returns one of following:

•	A short description of the task to display in the protocol editor under the icon associated with the task

•	A full, dynamic description of the task to enter in the Main Log

VWorks software calls the GetDescription method whenever it needs to render the task description. This enables the description to change dynamically. However, if the GetDescription method is not implemented, VWorks software gets the task description by calling the GetMetaData method. The description returned with this method call is static. See “GetMetaData method” .

The following figure shows a task icon, along with its associated task description, in the protocol editor:

Figure Task icon and its associated description

 

 

Item	Description	Purpose
1	Task icon	Represents a task The task icon is returned with a call to the Get32x32Bitmap method. See “Get32x32Bitmap method” .
2	Task description	Describes the task associated with the icon

Syntax

 

HRESULT GetDescription( [in] BSTR CommandXML, [in] VARIANT_BOOL Verbose, [out,retval] BSTR *Description );

Parameters

 

CommandXML	[in] A Command XML block that describes the task.
Verbose	[in] Indicates whether VWorks software is asking for a short description or a full, dynamic description. Possible values: VARIANT_TRUE = VWorks software is requesting a full, dynamic description of the task VARIANT_FALSE = VWorks software is requesting a short description of the task
Description	[out, retval] The description of the specified task. If the value of the Verbose parameter is VARIANT_TRUE, this parameter contains a full, dynamic description of the specified task. If the value is VARIANT_FALSE, this parameter contains a short description of the specified task.

GetDescription method input

VWorks software passes a Boolean value into the Verbose parameter of the GetDescription method to tell the plugin which type of description to send: dynamic or short. VWorks software also passes a Command XML block into the CommandXML parameter.

Command XML block

The Command XML block contains the Command element and all its children. This XML block describes the specified task.

When the plugin receives the Command XML block, it only needs to check the following attributes:

•	Name attribute of the Command element

•	Name and Value attributes of each Parameter element

These attributes are designated by bold text in the following XML structure and input example.

Although VWorks software passes other XML metadata in the Command XML block, this information is of no interest to the plugin.

XML structure

The value of the file attribute for the Velocity11 element is MetaData. See “Velocity11 element” .

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11> <Command ... Name='' ... > <Parameters> <Parameter ... Name='' ... Value=''> <Ranges> <Range> ... </Ranges> </Parameter> ... </Parameters> </Command> </Velocity11>

Command element

The Command element contains one Parameters element and has the following attributes:

 

Name	Value
Compiler	See “Compiler attribute” .
Description	The description of the task.
Editor	See “Editor attribute” .
Name	The name of the task.
NextTaskToExecute	See “NextTaskToExecute attribute” .
RequiresRefresh	See “RequiresRefresh attribute” .
TaskRequiresLocation	See “TaskRequiresLocation attribute” .
VisibleAvailability	See “VisibleAvailability attribute” .

Parameters element

The Parameters element contains one or more Parameter elements.

Parameter element

The Parameter element can contain one Ranges elements and has the following attributes:

 

Name	Value
Description	The description of the parameter.
Name	The name of the parameter.
Scriptable	See “Scriptable attribute” .
Style	See “Style attribute” .
Type	See “Type attribute” .
Value	See “Value attribute” .

Example of GetDescription method input

The following code is a Command XML block that is received by the plugin from VWorks software as a string in the CommandXML parameter of the GetDescription method. VWorks software asks the plugin for a description of the Execute a method task. If the value of the Verbose parameter is VARIANT_TRUE, VWorks software is requesting a full, dynamic description of the task. If the value is VARIANT_FALSE, VWorks software is requesting a short description of the task.

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11 file='MetaData' md5sum='4122f65abc7c2fae10b8ba5b02ba18c1' version='1.0' > <Command Compiler='0' Description='Execute a method' Editor='2' →Name='Execute a method' NextTaskToExecute='1' RequiresRefresh='0' →TaskRequiresLocation='1' VisibleAvailability='1' > <Parameters > <Parameter Description='Method name' Name='Method name' Scriptable='1' →Style='0' Type='2' Value='a.lmeth' > <Ranges > <Range Value='a.lmeth' /> </Ranges> </Parameter> </Parameters> </Command> </Velocity11>

Related information

 

For information about...	See...
Command XML block	“Command XML block”
Get32x32Bitmap method	“Get32x32Bitmap method”
GetMetaData method	“GetMetaData method”