DeviceComponentLocator Class Reference

A class to locate components within the driver. More...

Inheritance diagram for DeviceComponentLocator:

Public Member Functions
bool	bindComponent (Component access, String name)
	Binds an access object to an internal driver object.
bool	bindComponent (Component access, String name, int maxSearchDepth)
	Binds an access object to an internal driver object.
int	bindSearchBase (int baselist)
	Assign a new search base to the locator.
int	bindSearchBase (int baselist, String pathToSearchBase)
	Assign a new search base to the locator.
int	bindSearchBaseList (Device device, TDeviceListType deviceListType)
	Assign a new search base to the locator.
int	bindSearchBaseList (Device device, TDeviceListType deviceListType, String sublistName)
	Assign a new search base to the locator.
	DeviceComponentLocator (Device device, TDeviceListType deviceListType)
	Constructs a new locator and bind the search base to the specified list type of the device.
	DeviceComponentLocator (Device device, TDeviceListType deviceListType, String sublistName)
	Constructs a new locator and bind the search base to the specified list type of the device.
	DeviceComponentLocator (int baselist)
	Constructs a new bound to the specified base list locator.
int	findComponent (String name)
	Tries to locate a certain component in a hierarchy of components.
int	findComponent (String name, int maxSearchDepth)
	Tries to locate a certain component in a hierarchy of components.

Properties
uint	changedCounter [get]
	Returns the current changed counter for the component referenced by this object.
uint	changedCounterAttr [get]
	Returns the current attribute changed counter for the component referenced by this object.
String	displayName [get]
	Returns the display name of the component referenced by this object.
int	hObj [get]
	Returns a unique identifier for the component referenced by this object.
String	name [get]
	Returns the name of the component referenced by this object.
int	searchbase_id [get]
	Returns the unique identifier of the base list from where to start searching for a component.

Detailed Description

A class to locate components within the driver.

Every driver will offer a set of properties, methods and component lists. mv.impact.acquire.Property objects contain data such as the current gain in dB, the state of a digital input, etc.. mv.impact.acquire.Method objects can be executed like a normal function and mv.impact.acquire.ComponentList objects are used to group certain objects together to form a logical unit.

When it's necessary to locate one or more of these objects without knowing exactly where to look for them this locator class can be used to look for the component.

In general the properties interesting for the user can be found in one of the classes offered by this interface, but when a special property is needed or a new property that hasn't been embedded into the interface, this class offers a way to get hold of its handle.

Example

// assuming a new property 'MyProp' has been added to the setting of a 
// device driver whose product string is 'MyDevice' and it has not been 
// added to the corresponding class or the property shall be accessed
// without rebuilding the application.
// The latter situation will require some kind of interpreter that
// can pass the required information to the device driver
//-----------------------------------------------------------------------------
public enum TMyEnumType
//-----------------------------------------------------------------------------
{
  metOne = 0,
  metTwo,
  metThree
};
 
//-----------------------------------------------------------------------------
public void fn( void )
//-----------------------------------------------------------------------------
{
  Device pDev = DeviceManager.getDeviceByProduct( "MyDev*" );
  if( pDev != null )
  {
    // get access to the base setting
    DeviceComponentLocator locator = new DeviceComponentLocator(pDev, dltSetting, "Base");
    Property prop = new Property();
    locator.bindComponent( prop, "MyProp" );
    // set the value by string
    prop.writeS( "MyVal" );
    if( prop.type == TComponentType.ctPropInt )
    {
      PropertyI iProp = new PropertyI(prop.hObj);
      int myVal = 666;
      iProp.write( myVal );
    }
    // if the type is known this test can be omitted:
    PropertyF fProp = new PropertyF();
    locator.bindComponent( fProp, "MyFloatProperty" );
    fProp.write( 3.14 );
 
    // When it's an enumerated property this is legal as well:
    EnumPropertyI<TMyEnumType> eProp = new EnumPropertyI<TMyEnumType>();
    locator.bindComponent( eProp, "MyEnumeratedProperty" );
    prop.write( TMyEnumType.metOne );
  }
}

Examples

Properties.cs.

Constructor & Destructor Documentation

DeviceComponentLocator() [1/3]

DeviceComponentLocator ( int baselist )

inline

Constructs a new bound to the specified base list locator.

Parameters

[in]

baselist

A unique identifier to the base list from where to start to search for the search base.

DeviceComponentLocator() [2/3]

DeviceComponentLocator ( Device device, TDeviceListType deviceListType )

inline

Constructs a new locator and bind the search base to the specified list type of the device.

Parameters

[in]	device	A pointer to a mv.impact.acquire.Device object obtained from a mv.impact.acquire.DeviceManager object.
[in]	deviceListType	The type list to locate

DeviceComponentLocator() [3/3]

DeviceComponentLocator ( Device device, TDeviceListType deviceListType, String sublistName )

inline

Constructs a new locator and bind the search base to the specified list type of the device.

Parameters

[in]	device	A pointer to a mv.impact.acquire.Device object obtained from a mv.impact.acquire.DeviceManager object.
[in]	deviceListType	The type list to locate
[in]	sublistName	A string that can contain the name of the list if there is more than one candidate (e.g. when looking for settings)

Member Function Documentation

bindComponent() [1/2]

bool bindComponent ( Component access, String name )

inlineinherited

Binds an access object to an internal driver object.

Returns

• true if successful
• false otherwise. In case false is returned by this function the component could not be bound, which means subsequent calls using access will fail or throw an exception.

Parameters

[in]	access	The access object to bind to the driver object.
[in]	name	The name of the driver object to locate.

bindComponent() [2/2]

bool bindComponent ( Component access, String name, int maxSearchDepth )

inlineinherited

Binds an access object to an internal driver object.

Returns

• true if successful
• false otherwise. In case false is returned by this function the component could not be bound, which means subsequent calls using access will fail or throw an exception.

Parameters

[in,out]	access	The access object to bind to the driver object.
[in]	name	The name of the driver object to locate.
[in]	maxSearchDepth	The maximum number of sub list levels to search for the component.

bindSearchBase() [1/2]

int bindSearchBase ( int baselist )

inlineinherited

Assign a new search base to the locator.

This new search base will be searched starting from the base list specified.

Returns

The unique identifier of the new search base.

Parameters

[in]

baselist

A unique identifier for the base list used to start searching the search base.

bindSearchBase() [2/2]

int bindSearchBase ( int baselist, String pathToSearchBase )

inlineinherited

Assign a new search base to the locator.

This new search base will be searched starting from the base list specified.

Returns

The unique identifier of the new search base.

Parameters

[in]	baselist	A unique identifier for the base list used to start searching the search base.
[in]	pathToSearchBase	The name or path to the search base.

bindSearchBaseList() [1/2]

int bindSearchBaseList ( Device device, TDeviceListType deviceListType )

inline

Assign a new search base to the locator.

This new search base will be search starting from the base list specified.

Returns

The unique identifier of the new search base.

Parameters

[in]	device	A pointer to a mv.impact.acquire.Device object obtained from a mv.impact.acquire.DeviceManager object.
[in]	deviceListType	The type list to locate

bindSearchBaseList() [2/2]

int bindSearchBaseList ( Device device, TDeviceListType deviceListType, String sublistName )

inline

Assign a new search base to the locator.

This new search base will be search starting from the base list specified.

Returns

The unique identifier of the new search base.

Parameters

[in]	device	A pointer to a mv.impact.acquire.Device object obtained from a mv.impact.acquire.DeviceManager object.
[in]	deviceListType	The type list to locate
[in]	sublistName	The name or path to the search base.

findComponent() [1/2]

int findComponent ( String name )

inlineinherited

Tries to locate a certain component in a hierarchy of components.

Returns

A unique identifier to the component if found or mv.impact.acquire.Device.INVALID_ID if the component couldn't be found.

Parameters

[in]

name

The name of the component to search for.

findComponent() [2/2]

int findComponent ( String name, int maxSearchDepth )

inlineinherited

Tries to locate a certain component in a hierarchy of components.

Returns

A unique identifier to the component if found or mv.impact.acquire.Device.INVALID_ID if the component couldn't be found.

Parameters

[in]	name	The name of the component to search for.
[in]	maxSearchDepth	The maximum number of sub list levels to search for the component.

Property Documentation

changedCounter

uint changedCounter

getinherited

Returns the current changed counter for the component referenced by this object.

This changed counter is incremented internally each time the component is modified. To check if this component has been modified since the last time, this check has been performed, keep track of the last return value of this function and compare it with the new value. This can be helpful e.g. to keep a GUI up to date. The value returned by this function will always be larger than or equal to the value returned by mv.impact.acquire.ComponentAccess.changedCounterAttr (except in case of a wrap around) when called at the same time for the same object as it's always incremented when the component has been modified in any way while the latter one will only be incremented if the attributes (e.g. the flags) but NOT if e.g. the value(s) of a property has been modified.

Example

//-----------------------------------------------------------------------------
public struct ComponentRef
//-----------------------------------------------------------------------------
{
  mv.impact.acquire.Component m_pc;
  uint m_lastChangedCount;
  public ComponentRef( mv.impact.acquire.Component* pc ) : m_pc(pc), m_lastChangedCount(0) {}
};
 
//-----------------------------------------------------------------------------
public void fn( ComponentRef cr )
//-----------------------------------------------------------------------------
{
  if( cr.m_pc )
  {
    uint currentChangedCount = cr.m_pc.changedCounter;
    if( currentChangedCount != cr.m_lastChangedCount ) )
    {
      // something has happened since the last check.
      doWhatNeedsToBeDone();
      // and remember the current changed counter
      cr.m_lastChangedCount = currentChangedCount;
    }
  }
}

Returns

The current changed counter of this object.

changedCounterAttr

uint changedCounterAttr

getinherited

Returns the current attribute changed counter for the component referenced by this object.

This changed counter is incremented internally each time the components attributes have been modified. To check if this components attributes have been modified since the last time, this check has been performed, keep track of the last return value of this function and compare it with the new value. This can be helpful e.g. to keep a GUI up to date.

Note

Attributes changes are e.g. a modification to a property's translation dictionary, but NOT a property's value. Because of this the value returned by this function will always be less or equal than the value returned by the function mv.impact.acquire.ComponentAccess.changedCounter (except in case of a wrap around) when called at the same time for the same object.

See also

mv.impact.acquire.ComponentAccess.changedCounter

Returns

The current attributes changed counter of this object.

displayName

String displayName

getinherited

Returns the display name of the component referenced by this object.

Returns

The display name of the component referenced by this object. This might be an empty string if no display name has been specified.

hObj

int hObj

getinherited

Returns a unique identifier for the component referenced by this object.

Returns

A unique identifier for the component referenced by this object.

Examples

GenICamCallbackOnEvent.cs, and Properties.cs.

name

String name

getinherited

Returns the name of the component referenced by this object.

Returns

The name of the component referenced by this object.

Examples

Callback.cs, GenICamCallbackOnEvent.cs, and Properties.cs.

searchbase_id

int searchbase_id

getinherited

Returns the unique identifier of the base list from where to start searching for a component.

Returns

The unique identifier of the base list from where searching for a component will start currently.

Examples

Properties.cs.