DeviceComponentLocator Class Reference

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

Inheritance diagram for DeviceComponentLocator:

Public Member Functions
boolean	bindComponent (Component access, String name)
	Binds an access object to an internal driver object.
boolean	bindComponent (Component access, String name, int searchMode)
	Binds an access object to an internal driver object.
boolean	bindComponent (Component access, String name, int searchMode, 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 pDev, int deviceListType)
	Assign a new search base to the locator.
int	bindSearchBaseList (Device pDev, int deviceListType, String sublistName)
	Assign a new search base to the locator.
long	changedCounter ()
	Returns the current changed counter for the component referenced by this object.
long	changedCounterAttr ()
	Returns the current attribute changed counter for the component referenced by this object.
synchronized void	delete ()
	DeviceComponentLocator ()
	Constructs a new unbound locator.
	DeviceComponentLocator (Device pDev, int deviceListType)
	Constructs a new locator and bind the search base to the specified list type of the device.
	DeviceComponentLocator (Device pDev, int 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.
	DeviceComponentLocator (int baselist, String pathToSearchBase)
	Constructs a new locator and searches the search base list.
String	displayName ()
	Returns the display name of the component referenced by this object.
int	findComponent (String name)
	Tries to locate a certain component in a hierarchy of components.
int	findComponent (String name, int searchMode)
	Tries to locate a certain component in a hierarchy of components.
int	findComponent (String name, int searchMode, int maxSearchDepth)
	Tries to locate a certain component in a hierarchy of components.
int	hObj ()
	Returns a unique identifier for the component referenced by this object.
String	name ()
	Returns the name of the component referenced by this object.
int	searchbase_id ()
	Returns the unique identifier of the base list from where to start searching for a component.

Protected Member Functions
	DeviceComponentLocator (long cPtr, boolean cMemoryOwn)
void	finalize ()

Static Protected Member Functions
static long	swigRelease (ComponentAccess obj)
static long	swigRelease (ComponentLocatorBase obj)
static long	swigRelease (DeviceComponentLocator obj)

Protected Attributes
transient boolean	swigCMemOwn

Detailed Description

A class to locate components within the driver.

Every driver will offer a set of properties, methods and component lists. mvIMPACT.acquire.Property objects contain data such as the current gain in dB, the state of a digital input, etc.. mvIMPACT.acquire.Method objects can be executed like a normal function and mvIMPACT.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 C++ interface, this class offers a way to get hold of its handle.

//-----------------------------------------------------------------------------
public static void fn( void )
//-----------------------------------------------------------------------------
{
  DeviceManager devMgr = new DeviceManager();
  Device pDev = devMgr.getDeviceByProduct( "MyDev*" );
  if( pDev != null )
  {
    DeviceComponentLocator locator = new DeviceComponentLocator( pDev, TDeviceListType.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:
    PropertyI eProp = new PropertyI();
    locator.bindComponent( eProp, "MyBooleanProperty" );
    eProp.write( TBoolean.bTrue );
  }
}

Constructor & Destructor Documentation

DeviceComponentLocator() [1/6]

DeviceComponentLocator ( long cPtr, boolean cMemoryOwn )

protected

DeviceComponentLocator() [2/6]

DeviceComponentLocator

(

)

Constructs a new unbound locator.

DeviceComponentLocator() [3/6]

DeviceComponentLocator

(

int

baselist

)

Constructs a new bound to the specified base list locator.

Parameters

baselist

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

DeviceComponentLocator() [4/6]

DeviceComponentLocator	(	int	baselist,
		String	pathToSearchBase )

Constructs a new locator and searches the search base list.

Parameters

baselist	[in] A unique identifier to the base list from where to start to search for the search base.
pathToSearchBase	[in] The name or path ('/' separated) to the search base.

DeviceComponentLocator() [5/6]

DeviceComponentLocator	(	Device	pDev,
		int	deviceListType,
		String	sublistName )

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

Parameters

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

DeviceComponentLocator() [6/6]

DeviceComponentLocator	(	Device	pDev,
		int	deviceListType )

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

Parameters

pDev	[in] A pointer to a mvIMPACT.acquire.Device object obtained from a mvIMPACT.acquire.DeviceManager object.
deviceListType	[in] The type list to locate is more than one candidate (e.g. when looking for settings)

Member Function Documentation

bindComponent() [1/3]

boolean bindComponent ( Component access, String name )

inherited

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

access	[in,out] The access object to bind to the driver object.
name	[in] The path and/or name of the object to be located. are: smIgnoreLists smIgnoreMethods smIgnoreProperties By e.g. setting this value to 2, the current list and all its sub lists will be searched for the object, but no sublists of sub lists. -1 will search in ALL sub lists.

bindComponent() [2/3]

boolean bindComponent ( Component access, String name, int searchMode )

inherited

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

access	[in,out] The access object to bind to the driver object.
name	[in] The path and/or name of the object to be located.
searchMode	[in] Specifies how and what to search for. Valid flags(these flags can be combined using the '|' operator) for this parameter are: smIgnoreLists smIgnoreMethods smIgnoreProperties By e.g. setting this value to 2, the current list and all its sub lists will be searched for the object, but no sublists of sub lists. -1 will search in ALL sub lists.

bindComponent() [3/3]

boolean bindComponent ( Component access, String name, int searchMode, int maxSearchDepth )

inherited

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

access	[in,out] The access object to bind to the driver object.
name	[in] The path and/or name of the object to be located.
searchMode	[in] Specifies how and what to search for. Valid flags(these flags can be combined using the '|' operator) for this parameter are: smIgnoreLists smIgnoreMethods smIgnoreProperties
maxSearchDepth	[in] The maximum depth (in lists) where to search for the component. By e.g. setting this value to 2, the current list and all its sub lists will be searched for the object, but no sublists of sub lists. -1 will search in ALL sub lists.

bindSearchBase() [1/2]

int bindSearchBase ( int baselist )

inherited

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

baselist

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

bindSearchBase() [2/2]

int bindSearchBase ( int baselist, String pathToSearchBase )

inherited

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

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

bindSearchBaseList() [1/2]

int bindSearchBaseList	(	Device	pDev,
		int	deviceListType )

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

pDev	[in] A pointer to a mvIMPACT.acquire.Device object obtained from a mvIMPACT.acquire.DeviceManager object.
deviceListType	[in] The type list to locate

bindSearchBaseList() [2/2]

int bindSearchBaseList	(	Device	pDev,
		int	deviceListType,
		String	sublistName )

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

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

changedCounter()

long changedCounter ( )

inherited

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 mvIMPACT.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.

import mvIMPACT.acquire.*;
 
//-----------------------------------------------------------------------------
public class ComponentRef
//-----------------------------------------------------------------------------
{
  private Component c_;
  private long lastChangedCount_;
  public ComponentRef( Component c ) : c_( c ), lastChangedCount_( 0 ) {}
  public Component getComponent()
  {
    return c_;
  }
  public long getLastChangedCounter()
  {
    return lastChangedCount_;
  }
  public void setLastChangedCounter( long changedCounter )
  {
    lastChangedCount_ = lastChangedCount;
  }
}
 
// ...more code, class definition etc.
 
//-----------------------------------------------------------------------------
public static void fn( ComponentRef cr )
//-----------------------------------------------------------------------------
{
  if( cr.c_.isValid() )
  {
    final long currentChangedCount = cr.getComponent().changedCounter();
    if( currentChangedCount != cr.getLastChangedCounter() )
    {
      // something has happened since the last check!
      doWhatNeedsToBeDone();
      // and remember the current changed counter
      cr.setLastChangedCounter( currentChangedCount );
    }
  }
}

Returns

The current changed counter of this object.

changedCounterAttr()

long changedCounterAttr ( )

inherited

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 mvIMPACT.acquire.ComponentAccess.changedCounter (except in case of a wrap around) when called at the same time for the same object.

See also

mvIMPACT.acquire.ComponentAccess.changedCounter

Returns

The current attributes changed counter of this object.

delete()

synchronized void delete

(

)

Reimplemented from ComponentLocatorBase.

displayName()

String displayName ( )

inherited

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

Since

1.11.20

Returns

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

finalize()

void finalize ( )

protected

Reimplemented from ComponentLocatorBase.

findComponent() [1/3]

int findComponent ( String name )

inherited

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

Returns

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

Parameters

name	[in] The path and/or name of the object to be located. are: smIgnoreLists smIgnoreMethods smIgnoreProperties By e.g. setting this value to 2, the current list and all its sub lists will be searched for the object, but no sublists of sub lists. -1 will search in ALL sub lists.

findComponent() [2/3]

int findComponent ( String name, int searchMode )

inherited

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

Returns

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

Parameters

name	[in] The path and/or name of the object to be located.
searchMode	[in] Specifies how and what to search for. Valid flags(these flags can be combined using the '|' operator) for this parameter are: smIgnoreLists smIgnoreMethods smIgnoreProperties By e.g. setting this value to 2, the current list and all its sub lists will be searched for the object, but no sublists of sub lists. -1 will search in ALL sub lists.

findComponent() [3/3]

int findComponent ( String name, int searchMode, int maxSearchDepth )

inherited

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

Returns

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

Parameters

name	[in] The path and/or name of the object to be located.
searchMode	[in] Specifies how and what to search for. Valid flags(these flags can be combined using the '|' operator) for this parameter are: smIgnoreLists smIgnoreMethods smIgnoreProperties
maxSearchDepth	[in] The maximum depth (in lists) where to search for the component. By e.g. setting this value to 2, the current list and all its sub lists will be searched for the object, but no sublists of sub lists. -1 will search in ALL sub lists.

hObj()

int hObj ( )

inherited

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

Returns

A unique identifier for the component referenced by this object.

name()

String name ( )

inherited

Returns the name of the component referenced by this object.

Returns

The name of the component referenced by this object.

searchbase_id()

int searchbase_id ( )

inherited

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.

swigRelease() [1/3]

static long swigRelease ( ComponentAccess obj )

staticprotectedinherited

swigRelease() [2/3]

static long swigRelease ( ComponentLocatorBase obj )

staticprotectedinherited

swigRelease() [3/3]

static long swigRelease ( DeviceComponentLocator obj )

staticprotected

Member Data Documentation

swigCMemOwn

transient boolean swigCMemOwn

protectedinherited