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.
Defines the help section in an IMDF file. Must be child of the ImageAcquisitionInfo node.
Defines the online help for a property. The Help node can contain one or more AdaptorHelp nodes.
property=name, where name is a text string specifying the property name
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 text string that identifies a particular device
Defines the see also line in property help. This element is optional. An AdaptorHelp node can contain multiple SeeAlso nodes.
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.
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.
<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>
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>