Specifying Help in an IMDF File

To define help text for adaptor properties in an IMDF file, use the Help element. You can include only one Help node in an IMDF file and it must be a child of the root node.

As children of the Help node, you create AdaptorHelp nodes that contain the help text for a particular property. You use the name attribute of the AdaptorHelp element to specify which property the help is associated with.

You can optionally include device-specific content in the help text. This text appears only when a particular device is selected. Use one or more DeviceHelp nodes to add device-specific help to an AdaptorHelp node. You use the device attribute of the DeviceHelp element to specify when the text should appear. You can also create see also references for your property help using SeeAlso nodes.

The following example outlines how to use these elements to create property help. The words in italics represent text that you must define.

<ImageAcquisitionInfo>
	<Help>
		<AdaptorHelp property=propertyname>
			Help text
			<DeviceHelp device=devicename>
				Device-specific help text
			</DeviceHelp>
			<SeeAlso>
				References to other properties
			</SeeAlso
		</AdaptorHelp>
	.
	.
	.
	</Help>
</ImageAcquisitionInfo>

The following table summarizes the tags you can use to define help. For more information, see these topics.

Element	Description	Attributes
`<Help>`	Defines the help section in an IMDF file. Must be child of the `ImageAcquisitionInfo` node.	None
`<AdaptorHelp>`	Defines the online help for a property. The Help node can contain one or more AdaptorHelp nodes.	`property=`name, where name is a character vector specifying the property name
`<DeviceHelp>`	Specifies device-specific text in property help. This element is optional. An `AdaptorHelp` node can contain multiple `DeviceHelp` nodes.	`device=`name, where name is a character vector that identifies a particular device
`<SeeAlso>`	Defines the see also line in property help. This element is optional. An `AdaptorHelp` node can contain multiple `SeeAlso` nodes.	None

User Scenario: Viewing Property Help

The purpose of using a Help element in an IMDF file is to create help text for device-specific properties. A user of your adaptor can display the help text at the command line using the imaqhelp command.

The following example shows how a user displays the help text for a device-specific property using the imaqhelp command. To see how to create this help in an IMDF file, see Creating AdaptorHelp Nodes.

The items in this list correspond to the numbered elements above.

Device-specific properties are properties of the video source object. The example creates the video input object and then uses the getselectedsource function to get a handle to the video source object.
The example uses the get function to display a list of device-specific properties.
Use the imaqhelp function to display help for one of the properties of the video source object.
The first line of the help lists the name of the property with its constraints, such as range and permission.
The text of the help appears exactly as you enter it in the IMDF file. You include the text after the AdaptorHelp tag.
The See Also line is created by the SeeAlso node.

Creating AdaptorHelp Nodes

This section describes how to create help text for a property using the set of help tags defined by the IMDF DTD. The following example shows the IMDF entry for the Brightness property, displayed in User Scenario: Viewing Property Help. The example sets the property attribute of the AdaptorHelp tag to the name of a property.

Note

Help text must start with a one-line summary. Make sure that each line of text is no longer than 80 characters.

<AdaptorHelp property="Brightness">
Specify the brightness, also called the black level.
    
Brightness describes the difference in intensity of light reflected from 
or transmitted through an image independent of its hue and saturation. 
For some devices, the value is expressed in IRE units * 100. For other 
devices, the units are arbitrary. Refer to the device's documentation for 
information.

Depending on the acquisition device, this property may have an associated 
mode property allowing this value to be controlled automatically by the 
device, or for it to be manually configured.

<SeeAlso>BrightnessMode.</SeeAlso>

</AdaptorHelp>

Including Device-Specific Help Text

To include help text that only appears for specific devices, use DeviceHelp elements.

In this example, the help text contains three device-specific sections. Note how the example sets the device attribute of the DeviceHelp property to the name of a device.

<AdaptorHelp property="StrobeEnable">
Enables the strobe output and its timer.  

Upon enabling the strobe output, it will start detection
of triggers and generate output as appropriate.  Consult your
hardware manual for a detailed description of the strobe output.

<DeviceHelp device="PC2Vision">See also StrobeMode,
StrobeDuration, StrobeDelay, StrobePolarity,
StrobeAlignOnHs.
</DeviceHelp>

<DeviceHelp device="PCVisionPlus">See also StrobeMode,
StrobeDelay, StrobePolarity.
</DeviceHelp>

<DeviceHelp device="PCRGB">For the PC-RGB, StrobeEnable only 
enables the timing circuitry.  The strobe output must still be 
enabled with the StrobeOutputEnable property.

See also StrobeMode, StrobePolarity, StrobeDelay, 
StrobeOutputEnable.
</DeviceHelp>

</AdaptorHelp>