Creating Device Properties

To define properties for a device, follow this procedure:

Create the property using the appropriate IPropFactory member function for the data type. The engine passes in a handle to a IPropFactory object to the getDeviceAttributes() function.
For example, to create a property of type double, use the createDoubleProperty() method of the IPropFactory object, specifying the property name and default value as arguments.
```
hprop = devicePropFact->createDoubleProperty("Brightness",100)
```
The IPropFactory class supports functions to create properties of various data types — see Selecting the Property Creation Function.
Specify if a user can modify the property, using the setPropReadOnly() method of the IPropFactory object. Use one of the following constants (defined in IEngine.h): READONLY_ALWAYS, READONLY_NEVER, and READONLY_WHILE_RUNNING. For example,
```
devicePropFact->setPropReadOnly(hProp, 
                 imaqkit::propreadonly::READONLY_WHILE_RUNNING);
```
Add the property to the device-specific property container, using the addProperty() method of the IPropFactory object. For example,
```
devicePropFact->addProperty(hProp);
```
where hProp is a handle to the property you created in step 1.

Selecting the Property Creation Function

The IPropFactory() object supports functions that you can use to create properties of various data types, including:

int
double
character vector
Enumerated types

For example, use the createDoubleProperty() function to create a property whose value is of type double.

hprop = devicePropFact->createDoubleProperty("MyDoubleProp",2.5)

For the int and double types, you can also specify properties that have pairs of values or values within a defined range. For example, this code creates an integer property with upper and lower bounds.

hprop = devicePropFact->createIntProperty("MyBoundedIntProp", 
                                    0,100,50)

To create a property with enumerated values, use createEnumProperty(), specifying the property name, and one enumeration, for example,

hprop = devicePropFact->createEnumProperty("MyEnum", 
                                    "green",1)

You then add additional properties using addEnumValue().

For more information about the IPropFactory class, see the Image Acquisition Toolbox™ Adaptor Kit API Reference documentation.

Creating Property Help

You can use IMDF files to define help text for the device-specific properties you create. For more information, see Specifying Help in an IMDF File.

Example getDeviceAttributes() Function

The following example presents a skeletal implementation of a getDeviceAttributes() function. The intent of this example is to show how to use adaptor kit objects to specify video sources and properties of various types.

This code does not read source, property, or trigger information from an IMDF file. For information about this topic, see Using the IMDF Markup Language.

Add the following code to the getDeviceAttributes() function in the adaptor. You created a skeletal version of this function in Identifying Video Sources. This code creates several properties of various types.

    void* hProp;  // Declare a handle to a property object.

	// Create a property of type double with a default value
	hProp = devicePropFact->createDoubleProperty("MyDoubleProp",2.5);

	//  Specify when the property value can be modified.
	devicePropFact->setPropReadOnly(hProp,
                               imaqkit::imaqengine::READONLY_ALWAYS);

	// Add the property to the device-specific property container.
	devicePropFact->addProperty(hProp);

	// Create a bounded int property with maximum and minimum values
	hProp = devicePropFact->createIntProperty("MyBoundedIntProp",
                                              0, 100, 50);

	//  Specify when the property value can be modified.
	devicePropFact->setPropReadOnly(hProp,
                                imaqkit::imaqengine::READONLY_NEVER);

	// Add the property to the device-specific property container.
	devicePropFact->addProperty(hProp);

	// Create an enumerated property
	hProp = devicePropFact->createEnumProperty("MyEnumeratedProp",
                                               "green", 1);
    
	// Add additional enumerations
	devicePropFact->addEnumValue(hProp, "blue", 2);
	devicePropFact->addEnumValue(hProp, "red", 3);
	
	// Specify when the property value can be modified.
  	devicePropFact->setPropReadOnly(hProp,
                         imaqkit::imaqengine::READONLY_WHILE_RUNNING);

 // Add the property to the device-specific property container.
	devicePropFact->addProperty(hProp);

Compile and link your adaptor to create the DLL.
Start the MATLAB^® software.
Create a video input object for your adaptor.
```
vid = videoinput('mydevice',1)
```

Use the getselectedsource function to get a handle to the video source object and view the device-specific properties you created.

src = getselectedsource(vid);
get(vid)
General Settings:
    Parent = [1x1 videoinput]
    Selected = on
    SourceName = input1
    Tag = 
    Type = videosource

  Device Specific Properties:
    MyDoubleProp = 2.5
MyBoundedIntProp = 100
MyEnumeratedProp = green

Documentation