Working with Properties

The interfaces of ABBYY FlexiCapture SDK objects have various properties and methods. As Visual Basic users are familiar with the notion of property, we will discuss the way the properties are handled in C++.

For a C++ user, a property is a couple of methods (get and put for read-write properties) or a single get method (for read-only properties). However, the "Native COM support" featured by Microsoft Visual C++ makes the way the properties are handled more like the one used in Visual Basic. This is the way implied by the sense on the noun "property."

The ABBYY FlexiCapture SDK properties may be of the following types:

IDL	Visual Basic type	C++ type	C#
VARIANT_BOOL (VARIANT_TRUE or VARIANT_FALSE)	Boolean (with two values, True and False)	VARIANT_BOOL (with two values VARIANT_TRUE and VARIANT_FALSE)	bool (true or false)
int	Integer	int	int
double	Double	double	int
BSTR, a pointer to Unicode string. Zero value specifies an empty string.	String	BSTR, a pointer to Unicode string. Zero value specifies an empty string.	string
__int64	Int64	__int64	Int64
HANDLE*
IUnknown-derived interface	Object	IUnknown-derived interface	object
enum	Enumeration	Enumeration	enum

See the details of working with different types of properties below:

Working with simple properties

Working with string properties

Working with object properties

A C++ user will say that the parameters of "get" methods of "Object" properties are pointers to an object's interface pointer. As the interfaces of the objects are derived from IUnknown, they may be passed as IUnknown pointers to the properties or methods, which use objects of several types as input or output parameters (you may, however, get the interface you need by calling the QueryInterface method).

There are two different types of "put" methods for object properties — clear put, described by the propput keyword in the type library (the object is copied in this case); and put by reference, described by the propputref keyword in the type library (only a pointer to an existing object's interface is stored in the property in this case). A property may support only one of these put methods; most of ABBYY FlexiCapture SDK object properties clear put. In Visual Basic put by reference is performed using the Set statement, while clear put is performed without this keyword.

Suppose again the MyObject object supports MyObjectProperty property that refers to an object of MyChildObject type.

interface IMyObject : IUnknown {
...
[propget]
HRESULT MyObjectProperty([out, retval]IMyChildObject** pVal);
[propputref]
HRESULT MyObjectProperty([in]IMyChildObject* newVal);
...
};

The same property is accessed as follows in Visual Basic:

Dim ChildObj As MyChildObject
Set ChildObj=MyObject.MyObjectProperty
' Do something with the object
...
' Clear put (If it were put by reference, we would write
' Set MyObject.MyObjectProperty=ChildObj)
MyObject.MyObjectProperty=ChildObj

A C++ user will write this code as follows:

IMyObject* pMyObject;
...
IMyChildObject* pChildObj=0;
// get_ method may return 0 in certain cases
pMyObject->get_MyObjectProperty(&pChildObj);
// Do something with the object
...
pMyObject->put_MyObjectProperty(pChildObj);
...
pChildObj->Release();

Note that in C++ you should call the Release method for an object got via a property. The Native COM support calls AddRef and Release methods automatically using auto pointers.

Important! If an object property refers to a child object of the object that exposes this property, a pointer to the child object's interface is valid until its parent object exists. An attempt to access a child object after its parent object is destroyed may result in an error.

Working with read-only object properties

Certain ABBYY FlexiCapture SDK objects have read-only object properties. This does not mean that such properties cannot be changed, this only means that they cannot be changed directly. In raw C++, if you want to change such a property, you need to pass a reference to the property object to a new variable, and then use this variable to change it. Below you can see a C++ sample for the IProject::Batches property which is represented by a read-only collection:

IProject* pProject = 0;
IBatches* pBatches = 0;
IBatch* pBatch = 0;
...
// The pBatches variable receives a reference to the batches collection from the Project
pProject->get_Batches( &pBatches );
// Add one more element to the batches collection
pBatches->AddNew( L"BatchName", &pBatch );
...

Your use of this site is conditioned on Your continued compliance with the Terms of Use.

Terms of Use

Disclaimer of Warranty

Limitation of Liability

Transmission and Submission of Information

Downloads

Use of Content

Trademarks

Links to Third-Party Sites

Foreign Legislation

Subscription Terms

Partner Subscription Terms

Working with Properties

Working with simple properties

Working with string properties

Working with object properties

Working with read-only object properties

See also