A base class to implement access to internal driver components. More...

Inheritance diagram for Component:

Public Member Functions
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.

	Component ()
	Constructs a new unbound access object.

	Component (Component src)
	Constructs a new mvIMPACT.acquire.Component from an existing one.

	Component (int hObj)
	Constructs a new access object to a driver object.

synchronized void	delete ()

String	displayName ()
	Returns the display name of the component referenced by this object.

String	docString ()
	Returns a string containing general information about the component referenced by this object.

Component	firstChild ()
	Moves to the first child of this component(moves down one level).

Component	firstSibling ()
	Moves to the first sibling(the first feature in the current list of features).

int	flags ()
	Returns the flags associated with this component.

String	flagsAsString ()
	Returns the flags associated with this component as a string.

String	flagsAsString (String separator)
	Returns the flags associated with this component as a string.

int	hObj ()
	Returns a unique identifier for the component referenced by this object.

boolean	isDefault ()
	Checks if this component is currently referencing the default for this component.

boolean	isList ()
	Checks if this component is of type mvIMPACT.acquire.ComponentList.

boolean	isMeth ()
	Checks if this component is of type mvIMPACT.acquire.Method.

boolean	isProp ()
	Checks if this component is of type mvIMPACT.acquire.Property or a derived type.

boolean	isValid ()
	Checks if the internal component referenced by this object is still valid.

boolean	isVisible ()
	Checks if the component is currently shadowed due to a settings made elsewhere or not.

boolean	isWriteable ()
	Checks if the caller has write/modify access to the component.

Component	lastSibling ()
	Moves to the last sibling(the last feature in the current list of features).

String	name ()
	Returns the name of the component referenced by this object.

Component	nextSibling ()
	Moves to the next sibling(the next feature in the current list of features).

Component	parent ()
	Moves to the parent of this component(moves up one level).

int	representation ()
	Returns the recommended representation for this component.

String	representationAsString ()
	Returns the recommended representation of the referenced component as a string.

Component	restoreDefault ()
	Restores the default for the referenced component.

Component	selectedFeature (long index)
	Retrieves a component that is selected by the current one.

long	selectedFeatureCount ()
	Returns the number of features selected by the current one.

long	selectedFeatures (ComponentVector v)
	Retrieves the list of components that are selected by the current one.

Component	selectingFeature (long index)
	Retrieves a component that is selecting the current one.

long	selectingFeatureCount ()
	Returns the number of features selecting the current one.

long	selectingFeatures (ComponentVector v)
	Retrieves the list of components that are selecting the current one.

int	type ()
	Returns the type of the referenced component.

String	typeAsString ()
	Returns the type of the referenced component as a string.

int	visibility ()
	Returns the recommended visibility for this component.

String	visibilityAsString ()
	Returns the recommended visibility of the referenced component as a string.

Static Public Member Functions
static String	representationAsString (int representation)
	Returns the recommended representation converted to a string.

static int	type (int hObj)
	Returns the type of the component referenced by hObj.

static String	visibilityAsString (int visibility)
	Returns the recommended visibility converted to a string.

Protected Member Functions
	Component (long cPtr, boolean cMemoryOwn)

void	finalize ()

Static Protected Member Functions
static long	swigRelease (Component obj)

static long	swigRelease (ComponentAccess obj)

Protected Attributes
transient boolean	swigCMemOwn

Detailed Description

A base class to implement access to internal driver components.

Objects of this class can be constructed directly even if nothing is known about the type of driver object we are referring to. This class acts as a base class to provide access to internal properties, methods and component lists offered by the driver.

This object can be used to navigate through component lists of unknown content.

Consider the following structure:

LA
|-LB
|-LC
|  |-PE
|  |-PF
|  |-PG
|-PD

Where the prefix 'L' means this is a list, 'P' that this is a property. Assuming that we have and iterator referencing list 'C', calling mvIMPACT.acquire.Component.firstChild e.g. would return a new iterator referencing object 'PE', while calling mvIMPACT.acquire.Component.nextSibling would have returned a reference to 'PD' and mvIMPACT.acquire.Component.parent would have returned a reference to object 'LA'.

"EXAMPLE 1":

A new mvIMPACT.acquire.Component is created with the ID of list 'C':

Component it = new Component(ID_of_list_C);
it = it.firstChild();    // now we are referencing 'PE'
it = it.lastSibling();   // moves to 'PG'
it = it.firstSibling();  // moves back to PE'
it = it.nextSibling();   // moves to 'PF'
it = it.firstSibling();  // moves back to PE'
it = it.parent();        // we are referencing 'LC' again

"EXAMPLE 2":

Iterate over a complete list including sub lists. This will result in a list of all lists and properties that reside in the list the iterator currently is moving through to be written to the standard output. The name of the component and every parent component will be printed into the standard output:

//-----------------------------------------------------------------------------
public class FeatureListParser
//-----------------------------------------------------------------------------
{
  static
  {
    try
    {
      System.loadLibrary( "mvIMPACT_Acquire.java" );
    }
    catch( UnsatisfiedLinkError e )
    {
      System.err.println( "Native code library failed to load. Make sure the 'mvIMPACT_Acquire.java' library can be found in the systems search path.\n" + e );
      System.exit( 1 );
    }
 }
 
 //-----------------------------------------------------------------------------
 public static void ParseList( Component iter, final String path )
 //-----------------------------------------------------------------------------
 {
   while( iter.isValid() )
   {
     if( iter.isVisible() )
     {
       if( iter.isList() )
       {
         // do some list specific stuff
         System.out.println( String.format( "List     %s%s/", path, iter.name() ) );
         // move down into the list and append its name to the path
         ParseList( iter.firstChild(), path + iter.name() + "/" );
       }
       else if( iter.isProp() )
       {
         // do property specific stuff e.g. read the value
         Property prop = new Property(iter.hObj());
         StringBuilder values = new StringBuilder();
 
         final long valCount = prop.valCount();
         for( long i=0; i<valCount; i++ )
         {
           values.append( prop.readS( ( int )i ) );
           if( i < valCount - 1 )
           {
             values.append( ", " );
           }
         }
         System.out.println( String.format( "Property %s%s(value(s): %s)", path, prop.name(), values.toString() ) );
       }
     }
     iter = iter.nextSibling();
   }
 }
 
 //-----------------------------------------------------------------------------
 public static void main( String[] args )
 //-----------------------------------------------------------------------------
 {
   // ....
   Component baselist( gethObjOfListToParse() );
   ParseList( it );
   // ....
 }
}

Constructor & Destructor Documentation

◆ Component() [1/4]

Component	(	long	cPtr,
		boolean	cMemoryOwn )

protected

◆ Component() [2/4]

Component ( int hObj )

Constructs a new access object to a driver object.

Parameters

hObj	[in] A valid handle to a component object

◆ Component() [3/4]

Component ( )

Constructs a new unbound access object.

◆ Component() [4/4]

Component ( Component src )

Constructs a new mvIMPACT.acquire.Component from an existing one.

Parameters

src	[in] A constant reference to the mvIMPACT.acquire.Component object, this object shall be created from

Member Function Documentation

◆ 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 ComponentAccess.

Reimplemented in ComponentList, Method, Property, PropertyF, PropertyI, PropertyI64, PropertyPtr, and PropertyS.

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

◆ docString()

String docString ( )

Returns a string containing general information about the component referenced by this object.

Returns: A string containing general information about the component referenced by this object.

◆ finalize()

void finalize ( )

protected

Reimplemented from ComponentAccess.

Reimplemented in ComponentList, Method, Property, PropertyF, PropertyI, PropertyI64, PropertyPtr, and PropertyS.

◆ firstChild()

Component firstChild ( )

Moves to the first child of this component(moves down one level).

Calling this function will only succeed, if the current mvIMPACT.acquire.Component references a list.

Returns: A new mvIMPACT.acquire.Component object

◆ firstSibling()

Component firstSibling ( )

Moves to the first sibling(the first feature in the current list of features).

Returns: A new mvIMPACT.acquire.Component object

◆ flags()

int flags ( )

Returns the flags associated with this component.

Returns: The flags associated with this component.

◆ flagsAsString() [1/2]

String flagsAsString ( )

Returns the flags associated with this component as a string.

Returns: The flags associated with this component as a string.

◆ flagsAsString() [2/2]

String flagsAsString ( String separator )

Returns the flags associated with this component as a string.

Returns: The flags associated with this component as a string.

Parameters

separator [in] A user definable string to separate the individual flags. The default value is ' | ' resulting in the string to look e.g. like this: 'cfWriteAccess | cfReadAccess'

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

◆ isDefault()

boolean isDefault ( )

Checks if this component is currently referencing the default for this component.

This function will return true only for derived components that have not been modified.

Returns

true if the component is currently set to its default value
false otherwise.

◆ isList()

boolean isList ( )

Checks if this component is of type mvIMPACT.acquire.ComponentList.

Returns

true if the component references a list
false otherwise

◆ isMeth()

boolean isMeth ( )

Checks if this component is of type mvIMPACT.acquire.Method.

Returns

true if the component references a method
false otherwise

◆ isProp()

boolean isProp ( )

Checks if this component is of type mvIMPACT.acquire.Property or a derived type.

Returns

true if the component references a property
false otherwise

◆ isValid()

boolean isValid ( )

Checks if the internal component referenced by this object is still valid.

This function can be used to verify whether a referenced component is still valid or not. When e.g. referencing a driver property after mvIMPACT.acquire.Device.close has been called this function would return false. Calling any other function that tries to access the referenced component in that case would raise an exception.

Returns

true if this object currently references a valid component
false otherwise.

◆ isVisible()

boolean isVisible ( )

Checks if the component is currently shadowed due to a settings made elsewhere or not.

Settings applied to certain components might affect the behaviour of others. For example an activated automatic gain control might shadow the value written to the gain property by the user as the gain is calculated internally. In order to check if modifying the actual component will affect the behaviour of the system this function may be used. When it returns true, the mvIMPACT.acquire.Component will have an impact on the system, if false is returned, the feature might be modified, but this will currently NOT influence the acquisition process or the overall behaviour of the device or driver.

This is what is called visibility. The user still might modify or read the current mvIMPACT.acquire.Component when it's not visible however the actual data will be used only if the Component is visible (mvIMPACT.acquire.TComponentFlag.cfInvisible must NOT be set).

The visibility of a mvIMPACT.acquire.Component object will change only if other mvIMPACT.acquire.Component objects are modified and NEVER when a program runs but does not change any mvIMPACT.acquire.Component.

◆ isWriteable()

boolean isWriteable ( )

Checks if the caller has write/modify access to the component.

Returns

true if the caller is allowed to call write/modify operation for this component.
false otherwise.

◆ lastSibling()

Component lastSibling ( )

Moves to the last sibling(the last feature in the current list of features).

Since: 1.10.64

Returns: A new mvIMPACT.acquire.Component 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.

◆ nextSibling()

Component nextSibling ( )

Moves to the next sibling(the next feature in the current list of features).

Returns: A new mvIMPACT.acquire.Component object

◆ parent()

Component parent ( )

Moves to the parent of this component(moves up one level).

Returns: A new mvIMPACT.acquire.Component object

◆ representation()

int representation ( )

Returns the recommended representation for this component.

The representation can be used e.g. to develop a GUI that creates convenient controls for certain features.

Valid values for this property are defined by the enumeration mvIMPACT.acquire.TComponentRepresentation.

Since: 2.14.0

Returns: The recommended representation for this component.

◆ representationAsString() [1/2]

String representationAsString ( )

Returns the recommended representation of the referenced component as a string.

Since: 2.14.0

Returns: The recommended representation of the referenced component as a string.

◆ representationAsString() [2/2]

static String representationAsString ( int representation )

static

Returns the recommended representation converted to a string.

Since: 2.14.0

Returns: The recommended representation converted to a string.

Parameters

representation [in] The representation to query the string representation for

◆ restoreDefault()

Component restoreDefault ( )

Restores the default for the referenced component.

Calling this function will restore the default value for the component referenced by this object.

If this function is called for an object of type mvIMPACT.acquire.ComponentList every component in that list is restored to the default value.

Note: The caller must have the right to modify the component. Otherwise an exception will be thrown.

Returns: A const reference to the component.

◆ selectedFeature()

Component selectedFeature ( long index )

Retrieves a component that is selected by the current one.

This function retrieves a component that is selected by the current one. This information is mainly useful for GUI applications that want to arrange features in a way that dependencies between features can easily been spotted.

When a component 'selects' other components, this indicates that selected components may change whenever the selecting component changes. An example for a selector might be a property defining the index within a LUT while the value of a particular LUT entry could be a selected feature. Assuming 2 properties LUTIndex and LUTValue then changing LUTIndex will invalidate and possibly change LUTValue.

To find out how many mvIMPACT.acquire.Component objects are selected by the current one call mvIMPACT.acquire.Component.selectedFeatureCount. This value minus 1 will also be the max. value for index.

See also: mvIMPACT.acquire.Component.selectedFeatureCount,
mvIMPACT.acquire.Component.selectedFeatures

Since: 1.11.20

Returns: A mvIMPACT.acquire.Component that is selected by the current one.

Parameters

index [in] The index for the component to query.

◆ selectedFeatureCount()

long selectedFeatureCount ( )

Returns the number of features selected by the current one.

See also: mvIMPACT.acquire.Component.selectedFeatures,
mvIMPACT.acquire.Component.selectedFeature

Since: 1.11.20

Returns: The number of features selected by the current one.

◆ selectedFeatures()

long selectedFeatures ( ComponentVector v )

Retrieves the list of components that are selected by the current one.

This function retrieves the list of components that are selected by the current one. This information is mainly useful for GUI applications that want to arrange features in a way that dependencies between features can easily been spotted.

When a component 'selects' other components, this indicates that selected components may change whenever the selecting component changes. An example for a selector might be a property defining the index within a LUT while the value of a particular LUT entry could be a selected feature. Assuming 2 properties LUTIndex and LUTValue then changing LUTIndex will invalidate and possibly change LUTValue.

See also: mvIMPACT.acquire.Component.selectedFeatureCount,
mvIMPACT.acquire.Component.selectedFeature

Since: 1.11.20

Returns: The number of features selected by the current one.

Parameters

v	[out] An array that will retrieve the list of components that are selected by the current one.

◆ selectingFeature()

Component selectingFeature ( long index )

Retrieves a component that is selecting the current one.

This function retrieves a component that is selecting the current one. This information is mainly useful for GUI applications that want to arrange features in a way that dependencies between features can easily been spotted.

When a component 'selects' other components, this indicates that selected components may change whenever the selecting component changes. An example for a selector might be a property defining the index within a LUT while the value of a particular LUT entry could be a selected feature. Assuming 2 properties LUTIndex and LUTValue then changing LUTIndex will invalidate and possibly change LUTValue.

To find out how many mvIMPACT.acquire.Component objects are selecting the current one call mvIMPACT.acquire.Component.selectingFeatureCount. This value minus 1 will also be the max. value for index.

See also: mvIMPACT.acquire.Component.selectingFeatureCount,
mvIMPACT.acquire.Component.selectingFeatures

Since: 1.11.20

Returns: A mvIMPACT.acquire.Component that is selecting the current one.

Parameters

index [in] The index for the component to query.

◆ selectingFeatureCount()

long selectingFeatureCount ( )

Returns the number of features selecting the current one.

See also: mvIMPACT.acquire.Component.selectingFeatures,
mvIMPACT.acquire.Component.selectingFeature

Since: 1.11.20

Returns: The number of features selecting the current one.

◆ selectingFeatures()

long selectingFeatures ( ComponentVector v )

Retrieves the list of components that are selecting the current one.

This function retrieves the list of components that are selecting the current one. This information is mainly useful for GUI applications that want to arrange features in a way that dependencies between features can easily been spotted.

When a component 'selects' other components, this indicates that selected components may change whenever the selecting component changes. An example for a selector might be a property defining the index within a LUT while the value of a particular LUT entry could be a selected feature. Assuming 2 properties LUTIndex and LUTValue then changing LUTIndex will invalidate and possibly change LUTValue.

See also: mvIMPACT.acquire.Component.selectingFeatureCount,
mvIMPACT.acquire.Component.selectingFeature

Since: 1.11.20

Returns: The number of features selecting the current one.

Parameters

v	[out] An array that will retrieve the list of components that are selecting the current one.

◆ swigRelease() [1/2]

static long swigRelease ( Component obj )

staticprotected

◆ swigRelease() [2/2]

static long swigRelease ( ComponentAccess obj )

staticprotectedinherited

◆ type() [1/2]

int type ( )

Returns the type of the referenced component.

Returns: The type of the referenced component.

◆ type() [2/2]

static int type ( int hObj )

static

Returns the type of the component referenced by hObj.

Returns: The type of the component referenced by hObj.

Parameters

hObj	[in] The component the type shall be retrieved for

◆ typeAsString()

String typeAsString ( )

Returns the type of the referenced component as a string.

Returns: The type of the referenced component as a string.

◆ visibility()

int visibility ( )

Returns the recommended visibility for this component.

The visibility can be used e.g. to develop a GUI that displays a crucial subset of features only.

Valid values for this property are defined by the enumeration mvIMPACT.acquire.TComponentVisibility.

Returns: The recommended visibility for this component.

◆ visibilityAsString() [1/2]

String visibilityAsString ( )

Returns the recommended visibility of the referenced component as a string.

Returns: The recommended visibility of the referenced component as a string.

◆ visibilityAsString() [2/2]

static String visibilityAsString ( int visibility )

static

Returns the recommended visibility converted to a string.

Returns: The recommended visibility converted to a string.

Parameters

visibility [in] The visibility to query the string representation for

Member Data Documentation

◆ swigCMemOwn

transient boolean swigCMemOwn

protectedinherited

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Component() [1/4]

◆ Component() [2/4]

◆ Component() [3/4]

◆ Component() [4/4]

Member Function Documentation

◆ changedCounter()

◆ changedCounterAttr()

◆ delete()

◆ displayName()

◆ docString()

◆ finalize()

◆ firstChild()

◆ firstSibling()

◆ flags()

◆ flagsAsString() [1/2]

◆ flagsAsString() [2/2]

◆ hObj()

◆ isDefault()

◆ isList()

◆ isMeth()

◆ isProp()

◆ isValid()

◆ isVisible()

◆ isWriteable()

◆ lastSibling()

◆ name()

◆ nextSibling()

◆ parent()

◆ representation()

◆ representationAsString() [1/2]

◆ representationAsString() [2/2]

◆ restoreDefault()

◆ selectedFeature()

◆ selectedFeatureCount()

◆ selectedFeatures()

◆ selectingFeature()

◆ selectingFeatureCount()

◆ selectingFeatures()

◆ swigRelease() [1/2]

◆ swigRelease() [2/2]

◆ type() [1/2]

◆ type() [2/2]

◆ typeAsString()

◆ visibility()

◆ visibilityAsString() [1/2]

◆ visibilityAsString() [2/2]

Member Data Documentation

◆ swigCMemOwn