Vai al contenuto principale
Le interfacce degli oggetti ABBYY FineReader Engine includono varie proprietà e metodi. In generale, le proprietà rappresentano informazioni su un oggetto, mentre i metodi rappresentano le azioni che un oggetto può eseguire.
Gli esempi in C# si applicano a Windows. Gli esempi in C++ si applicano a tutti i sistemi operativi supportati.
Per C++, una proprietà è una coppia di metodi (get e put per le proprietà in lettura-scrittura) oppure un singolo metodo get (per le proprietà di sola lettura).Le proprietà di ABBYY FineReader Engine possono essere dei seguenti tipi:
  • VARIANT_BOOL (con due valori: VARIANT_TRUE o VARIANT_FALSE)
  • int
  • double
  • BSTR, un puntatore a una stringa Unicode. Il valore zero indica una stringa vuota.
  • __int64
  • HANDLE*
  • interfaccia derivata da IUnknown
  • enum
Gli utenti di C# e Visual Basic hanno familiarità con il concetto di proprietà.Per un utente C++, una proprietà è una coppia di metodi (get e put per le proprietà in lettura-scrittura) oppure un singolo metodo get (per le proprietà di sola lettura).Tuttavia, la funzionalità “Native COM support” di Microsoft C++ fa sì che la gestione delle proprietà sia più simile a quella usata in C#.Le proprietà di ABBYY FineReader Engine possono essere dei seguenti tipi:
IDLC++C#Visual Basic .NET
VARIANT_BOOL (VARIANT_TRUE o VARIANT_FALSE)VARIANT_BOOL (VARIANT_TRUE o VARIANT_FALSE)bool (true o false)Boolean (True o False)
intintintInteger
doubledoubledoubleDouble
BSTR, un puntatore a una stringa Unicode. Il valore zero indica una stringa vuota.BSTRstringString
__int64__int64Int64Int64
HANDLE*void*IntPtrIntPtr
interfaccia derivata da IUnknowninterfaccia derivata da IUnknownobjectObject
enumenumenumEnum
Di seguito sono riportati i dettagli sull’uso dei diversi tipi di proprietà:
Useremo una proprietà Boolean come esempio di utilizzo delle proprietà semplici. La proprietà è descritta nella libreria dei tipi come segue:
interface IMyObject : IUnknown
{
  [propget]
  HRESULT MyProperty( [out, retval] VARIANT_BOOL* result );
  [propput]
  HRESULT MyProperty( [in] VARIANT_BOOL value );
};
if (MyObject.MyProperty != true)
 MyObject.MyProperty = true;
IMyObject* pMyObject;
VARIANT_BOOL res;
pMyObject->get_MyProperty(&res);
if( res != VARIANT_TRUE )
   pMyObject->put_MyProperty(VARIANT_TRUE);
IMyObjectPtr pMyObject;
if(pMyObject->MyProperty != VARIANT_TRUE)
   pMyObject->MyProperty = VARIANT_TRUE
Se la libreria dei tipi definisce solo il metodo “get” per una proprietà semplice, questa proprietà è detta di sola lettura. Il suo valore non può essere modificato dall’utente e può essere solo letto.Un utente C# gestisce una proprietà semplice come segue:Un utente C++, invece, usa due metodi per lavorare con questa proprietà. Questi metodi hanno i prefissi get_ e put_. Il codice C++ corrispondente dovrebbe avere il seguente aspetto:Tuttavia, il supporto COM nativo in Windows semplifica la procedura e il codice corrispondente dovrebbe avere il seguente aspetto:
Lavorare con le proprietà string è molto simile a lavorare con le proprietà semplici, ma presenta alcune particolarità. Un utente C++ che lavora con le proprietà string deve liberare le stringhe passate ai metodi set e quelle restituite dai metodi get.
  • In Windows, questa operazione viene eseguita automaticamente in C#, Visual Basic e in C++ con il supporto COM nativo.
  • In Linux, utilizzare le funzioni FREngineAllocString e FREngineFreeString per allocare e liberare la memoria per le stringhe.
Si supponga che MyObject supporti anche una proprietà string denominata Name. Questa proprietà è descritta nella libreria dei tipi come segue:
interface IMyObject : IUnknown
{
  [propget]
  HRESULT Name([out, retval]BSTR* result);
  [propput]
  HRESULT Name([in]BSTR value);
};
IMyObject* pMyObject;
// metodo "get"
BSTR res;
pMyObject->get_Name(&res);
// Ora libera la stringa allocata in ABBYY FineReader Engine
::SysFreeString(res);
// metodo "put"
BSTR str = ::SysAllocString(L"New Name");
pMyObject->put_Name(str);
// Ora libera la stringa che abbiamo allocato
::SysFreeString(str);
IMyObject* pMyObject;
// metodo "get"
BSTR res;
pMyObject->get_Name(&res);
// Ora libera la stringa allocata in ABBYY FineReader Engine
::FREngineFreeString(res);
// metodo "put"
BSTR str = ::FREngineAllocString(L"New Name");
pMyObject->put_Name(str);
// Ora libera la stringa che abbiamo allocato
::FREngineFreeString(str);
Un utente C++ lavora con questa proprietà nel modo seguente:Windows:Linux:
Un utente C++ noterà che i parametri dei metodi “get” delle proprietà oggetto sono puntatori a un interface pointer dell’oggetto. Poiché le interfacce degli oggetti derivano da IUnknown, possono essere passate come puntatori IUnknown alle proprietà o ai metodi che accettano oggetti di più tipi come parametri di input o output (è tuttavia possibile ottenere l’interfaccia desiderata chiamando il metodo QueryInterface).Un metodo “put” per una proprietà oggetto, se presente, supporta il put diretto, descritto dalla parola chiave propput nella libreria dei tipi. Ciò significa che l’oggetto viene copiato (anziché passare un puntatore all’interfaccia di un oggetto esistente).Si supponga nuovamente che l’oggetto MyObject supporti la proprietà MyObjectProperty, che fa riferimento a un oggetto di tipo MyChildObject.
interface IMyObject : IUnknown
{
  [propget]
  HRESULT MyObjectProperty([out, retval]IMyChildObject** result);
  [propput]
  HRESULT MyObjectProperty([in]IMyChildObject* value);
};
IMyObject* pMyObject;
IMyChildObject* pChildObj=0;
// il metodo get_ può restituire 0 in determinati casi
pMyObject->get_MyObjectProperty(&pChildObj);
// Esegui alcune operazioni con l'oggetto
...
pMyObject->put_MyObjectProperty(pChildObj);
pChildObj->Release();
Un utente C++ scriverà questo codice come segue:Si noti che in C++ è necessario chiamare il metodo Release per un oggetto ottenuto tramite una proprietà. Il supporto COM nativo in Windows chiama automaticamente i metodi AddRef e Release tramite puntatori automatici.

​
Lavorare con le proprietà di sola lettura degli oggetti

Alcuni oggetti di ABBYY FineReader Engine (ad esempio, ILayout::Blocks) hanno proprietà di sola lettura. Questo non significa che tali proprietà non possano essere modificate, ma solo che non possono essere modificate sostituendo direttamente la proprietà con un altro oggetto, perché il metodo “put” non è supportato. Tuttavia, è possibile modificare le sottoproprietà di questi oggetti. In C++ (raw C++ in Windows), se si vuole modificare una proprietà di questo tipo, è necessario assegnare un riferimento all’oggetto proprietà a una nuova variabile e quindi usare questa variabile per modificarla. Di seguito è riportato un esempio in C++ per la proprietà ILayout::Blocks, rappresentata da una raccolta di sola lettura: 
// Si presuppone che una pagina sia già stata aperta
ILayout* pLayout = 0;
ILayoutBlocks* pLayoutBlocks = 0;
int blockIndex = 0;
// Recupera il layout dalla FRPage precedentemente aperta
pFRPage->get_Layout( &pLayout );
// La variabile pLayoutBlocks riceve un riferimento alla raccolta di blocchi dal Layout
pLayout->get_Blocks( &pLayoutBlocks );
// Rimuove un elemento dalla raccolta di blocchi
pLayoutBlocks->DeleteAt( blockIndex );
// Lavora con il layout modificato
...
// Rilascia gli oggetti
pLayoutBlocks->Release();
pLayout->Release();