> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  C# samples apply to Windows. C++ samples apply to all supported operating systems.
</Note>

<Accordion title="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
</Accordion>

<Accordion title="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                    |
</Accordion>

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

<Accordion title="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:

  ```cpp theme={null}
  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:

  ```csharp theme={null}
  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:

  ```cpp theme={null}
  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:

  ```cpp theme={null}
  IMyObjectPtr pMyObject;
  if(pMyObject->MyProperty != VARIANT_TRUE)
     pMyObject->MyProperty = VARIANT_TRUE
  ```
</Accordion>

<Accordion title="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:

  ```cpp theme={null}
  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**

  ```cpp theme={null}
  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**

  ```cpp theme={null}
  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);
  ```
</Accordion>

<Accordion title="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.

  ```cpp theme={null}
  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:

  ```cpp theme={null}
  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.
</Accordion>

## Working with read-only object properties

Certain ABBYY FineReader Engine objects (for example, [ILayout::Blocks](/fine-reader/engine/api-reference/layout-related-objects/layout#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:

```cpp theme={null}
// 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();
```