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
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
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
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
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
Defines the online help for a property. The Help node can contain one or more AdaptorHelp nodes.
Specifies device-specific text in property help. This
element is optional. An
Defines the see also line in property help. This element is
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
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
getselectedsourcefunction to get a handle to the video source object.
The example uses the
getfunction to display a list of device-specific properties.
imaqhelpfunction 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
The See Also line is created by the
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
Brightness property, displayed in User Scenario: Viewing Property Help. The example
property attribute of the
tag to the name of a property.
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
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>