Working with Properties

Work with ABBYY FineReader Engine properties — VARIANT_BOOL, integer, string, and object types — using get/put methods in C++ on Linux/macOS or property syntax on Windows.

The interfaces of ABBYY FineReader Engine objects have various properties and methods. In general, properties represent information about an object, whereas methods represent actions an object can take.

C# samples apply to Windows. C++ samples apply to all supported operating systems.

Linux and macOS property types

For C++, a property is a pair of methods (get and put for read-write properties) or a single get method (for read-only properties).

The ABBYY FineReader Engine properties may be of the following types:

• VARIANT_BOOL (with two values VARIANT_TRUE or VARIANT_FALSE)
• int
• double
• BSTR, a pointer to Unicode string. Zero value specifies an empty string.
• __int64
• HANDLE*
• IUnknown-derived interface
• enum

Windows property types

C# and Visual Basic users are familiar with the notion of property.

For a C++ user, a property is a pair 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 C++ makes the way the properties are handled more like the one used in C#.

The ABBYY FineReader Engine properties may be of the following types:

IDL	C++	C#	Visual Basic .NET
VARIANT_BOOL (VARIANT\_TRUE or VARIANT\_FALSE)	VARIANT_BOOL (VARIANT\_TRUE or VARIANT\_FALSE)	bool (true or false)	Boolean (True or False)
int	int	int	Integer
double	double	double	Double
BSTR, a pointer to Unicode string. Zero value specifies an empty string.	BSTR	string	String
\_\_int64	\_\_int64	Int64	Int64
HANDLE\*	void\*	IntPtr	IntPtr
IUnknown-derived interface	IUnknown-derived interface	object	Object
enum	enum	enum	Enum

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

Working with simple properties

We will use a Boolean property as an example of how simple properties are used. The property is described in the type library as follows:

interface IMyObject : IUnknown
{
  [propget]
  HRESULT MyProperty( [out, retval] VARIANT_BOOL* result );
  [propput]
  HRESULT MyProperty( [in] VARIANT_BOOL value );
};

If the type library only defines the “get” method for a simple property, this property is called read-only. Its value cannot be changed by the user, it may only be accessed for “reading.”

A C# user handles a simple property as follows:

if (MyObject.MyProperty != true)
 MyObject.MyProperty = true;

A C++ user, on the other hand, uses two methods to work with this property. These methods have get_ and put_ prefixes. The respective C++ code should look as follows:

IMyObject* pMyObject;
VARIANT_BOOL res;
pMyObject->get_MyProperty(&res);
if( res != VARIANT_TRUE )
   pMyObject->put_MyProperty(VARIANT_TRUE);

However, the Native COM support in Windows makes the procedure simpler, and the respective code should look as follows:

IMyObjectPtr pMyObject;
if(pMyObject->MyProperty != VARIANT_TRUE)
   pMyObject->MyProperty = VARIANT_TRUE

Working with string properties

Working with string properties is very similar to working with simple properties, but has its own specifics. A C++ user working with string properties must free the strings that are passed to set-methods, and also those that are returned by get-methods.

• In Windows, this is done automatically in C#, Visual Basic, and in C++ with the Native COM support.
• In Linux, use the FREngineAllocString and FREngineFreeString functions to allocate and free the memory for the strings.

Suppose MyObject also supports a string property called Name. This property is described in the type library as follows:

interface IMyObject : IUnknown
{
  [propget]
  HRESULT Name([out, retval]BSTR* result);
  [propput]
  HRESULT Name([in]BSTR value);
};

A C++ user works with this property like this:

Windows

IMyObject* pMyObject;
// "get" method
BSTR res;
pMyObject->get_Name(&res);
// Now free the string allocated in ABBYY FineReader Engine
::SysFreeString(res);
// "put" method
BSTR str = ::SysAllocString(L"New Name");
pMyObject->put_Name(str);
// Now free the string that we allocated
::SysFreeString(str);

Linux

IMyObject* pMyObject;
// "get" method
BSTR res;
pMyObject->get_Name(&res);
// Now free the string allocated in ABBYY FineReader Engine
::FREngineFreeString(res);
// "put" method
BSTR str = ::FREngineAllocString(L"New Name");
pMyObject->put_Name(str);
// Now free the string that we allocated
::FREngineFreeString(str);

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

A “put” method for an object property, if any, supports clear put, described by the propput keyword in the type library. This means that the object is copied (instead of passing a pointer to an existing object’s interface).

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** result);
  [propput]
  HRESULT MyObjectProperty([in]IMyChildObject* value);
};

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. Native COM support in Windows calls AddRef and Release methods automatically using auto pointers.

Working with read-only object properties

Certain ABBYY FineReader Engine objects (for example, ILayout::Blocks) have read-only object properties. This does not mean that such properties cannot be changed, this only means that they cannot be changed by directly replacing the object property with another object, because “put” method is not supported. However, you can change the sub-properties of these objects.

In C++ (raw C++ if Windows), 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 ILayout::Blocks property which is represented by a read-only collection:

// We assume that a page has been already opened
ILayout* pLayout = 0;
ILayoutBlocks* pLayoutBlocks = 0;
int blockIndex = 0;
// Receive the layout from the previously opened FRPage
pFRPage->get_Layout( &pLayout );
// The pLayoutBlocks variable receives a reference to the blocks collection from Layout
pLayout->get_Blocks( &pLayoutBlocks );
// Remove an element from the block collection
pLayoutBlocks->DeleteAt( blockIndex );
// Work with modified layout
...
// Release the objects
pLayoutBlocks->Release();
pLayout->Release();