プロパティの操作

ABBYY FineReader Engine オブジェクトのインターフェイスには、さまざまなプロパティとメソッドがあります。一般に、プロパティはオブジェクトに関する情報を表し、メソッドはオブジェクトが実行できる操作を表します。

C# のサンプルは Windows に対応しています。C++ のサンプルは、サポートされているすべてのオペレーティングシステムに対応しています。

Linux および macOS のプロパティ型

C++ では、プロパティは一対のメソッド (読み書き可能なプロパティの場合は get と put) または単一の get メソッド (読み取り専用プロパティの場合) として扱われます。

ABBYY FineReader Engine のプロパティには、次の型があります。

• VARIANT_BOOL (値は VARIANT_TRUE または VARIANT_FALSE のいずれか)
• int
• double
• BSTR (Unicode 文字列へのポインター) 。値が 0 の場合は空の string を示します。
• __int64
• HANDLE*
• IUnknown 派生インターフェイス
• enum

Windows のプロパティ型

C# および Visual Basic のユーザーには、プロパティの概念はよく知られています。

C++ ユーザーにとって、プロパティは一対のメソッド (読み書き可能なプロパティの場合は get と put) または単一の get メソッド (読み取り専用プロパティの場合) です。

ただし、Microsoft C++ の “Native COM support” を使用すると、プロパティの扱い方は C# に近くなります。

ABBYY FineReader Engine のプロパティには、次の型があります。

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

以下では、さまざまな型のプロパティの操作方法について詳しく説明します。

単純なプロパティの操作

単純なプロパティの使い方の例として、Boolean プロパティを使用します。このプロパティは、型ライブラリでは次のように記述されています。

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

型ライブラリで単純なプロパティに対して “get” メソッドだけが定義されている場合、このプロパティは読み取り専用と呼ばれます。その値はユーザーが変更できず、「読み取り」のためにアクセスすることしかできません。

C# ユーザーは、単純なプロパティを次のように扱います。

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

一方、C++ ユーザーはこのプロパティを操作するために 2 つのメソッドを使用します。これらのメソッドには、get_ および put_ の接頭辞が付きます。対応する C++ コードは次のようになります。

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

ただし、Windows の Native COM support を使用すると手順はさらに簡単になり、対応するコードは次のようになります。

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

string プロパティの扱い

string プロパティの扱いは単純なプロパティの場合とよく似ていますが、固有の注意点があります。string プロパティを扱う C++ ユーザーは、set メソッドに渡す文字列と、get メソッドから返される文字列の両方を解放する必要があります。

• Windows では、これは C#、Visual Basic、および Native COM support を使用する C++ では自動的に行われます。
• Linux では、文字列用のメモリの確保と解放に FREngineAllocString 関数および FREngineFreeString 関数を使用します。

たとえば、MyObject が Name という string プロパティもサポートしているとします。このプロパティは、型ライブラリでは次のように記述されます。

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

C++ ユーザーは、このプロパティを次のように扱います。

Windows

IMyObject* pMyObject;
// "get" メソッド
BSTR res;
pMyObject->get_Name(&res);
// ABBYY FineReader Engine で確保された文字列を解放する
::SysFreeString(res);
// "put" メソッド
BSTR str = ::SysAllocString(L"New Name");
pMyObject->put_Name(str);
// 自分で確保した文字列を解放する
::SysFreeString(str);

Linux

IMyObject* pMyObject;
// "get" メソッド
BSTR res;
pMyObject->get_Name(&res);
// ABBYY FineReader Engine で確保された文字列を解放する
::FREngineFreeString(res);
// "put" メソッド
BSTR str = ::FREngineAllocString(L"New Name");
pMyObject->put_Name(str);
// 自分で確保した文字列を解放する
::FREngineFreeString(str);

object プロパティの扱い

C++ ユーザーの観点では、object プロパティの “get” メソッドの parameters は、オブジェクトの interface pointer へのポインターです。オブジェクトのインターフェイスは IUnknown から派生しているため、複数の型のオブジェクトを入力または出力 parameters として扱うプロパティやメソッドには、IUnknown ポインターとして渡すことができます (ただし、必要なインターフェイスは QueryInterface メソッドを呼び出して取得できます) 。

object プロパティの “put” メソッドが存在する場合、そのメソッドは型ライブラリで propput キーワードにより記述される clear put をサポートします。これは、既存オブジェクトのインターフェイスへのポインターを渡すのではなく、オブジェクトがコピーされることを意味します。

ここでも、MyObject オブジェクトが、MyChildObject 型のオブジェクトを参照する MyObjectProperty プロパティをサポートしているとします。

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

C++ ユーザーは、次のようにコードを記述します。

IMyObject* pMyObject;
IMyChildObject* pChildObj=0;
// get_ メソッドは、場合によっては 0 を返すことがあります
pMyObject->get_MyObjectProperty(&pChildObj);
// オブジェクトに対して何らかの処理を行う
...
pMyObject->put_MyObjectProperty(pChildObj);
pChildObj->Release();

C++ では、プロパティ経由で取得したオブジェクトに対して Release メソッドを呼び出す必要がある点に注意してください。Windows の Native COM support では、auto pointers を使用して AddRef メソッドと Release メソッドが自動的に呼び出されます。

​

読み取り専用オブジェクトプロパティの扱い

一部の ABBYY FineReader Engine オブジェクト (たとえば、ILayout::Blocks) には、読み取り専用のオブジェクトプロパティがあります。これは、そのようなプロパティが変更できないという意味ではなく、put メソッドがサポートされていないため、オブジェクトプロパティを別のオブジェクトで直接置き換えて変更することはできない、という意味です。ただし、これらのオブジェクトのサブプロパティは変更できます。

C++ (Windows の場合は raw C++) でこのようなプロパティを変更するには、プロパティオブジェクトへの参照を新しい変数に渡し、その変数を使って変更する必要があります。以下に、読み取り専用のコレクションとして表される ILayout::Blocks プロパティの C++ サンプルを示します。

// ページはすでに開かれていると仮定します
ILayout* pLayout = 0;
ILayoutBlocks* pLayoutBlocks = 0;
int blockIndex = 0;
// 以前に開いたFRPageからlayoutを取得します
pFRPage->get_Layout( &pLayout );
// pLayoutBlocks変数にLayoutからブロックコレクションへの参照を格納します
pLayout->get_Blocks( &pLayoutBlocks );
// ブロックコレクションから要素を削除します
pLayoutBlocks->DeleteAt( blockIndex );
// 変更されたlayoutを操作します
...
// オブジェクトを解放します
pLayoutBlocks->Release();
pLayout->Release();