Home

Contact Us

General

Initiative B@bel

WSI Guidelines

Encoding

Principles

Unicode

Training

Tutorials

PUA

Conversion

Resources

Utilities

TECkit

Maps

Resources

Input

Principles

Utilities

Tutorials

Resources

Type Design

Principles

Design Tools

Formats

Resources

Font Downloads

Gentium

Doulos

IPA

Rendering

Principles

Technologies

OpenType

Graphite

Resources

Font FAQ

Links

Glossary


Computers & Writing Systems

SIL HOME | SIL SOFTWARE | SUPPORT | DONATE | PRIVACY POLICY

You are here: Encoding > Conversion > Utilities
Short URL: https://scripts.sil.org/SILConverters22_Conf

Auto Select and Configuration with SIL Converters

Bob Eaton, 2007-02-23

Return to SIL Converters Home.

Several new functions have been added to the EncConverters interface, as of version 2.2, through which Transduction Engine plug-ins provide their own user-interface for adding and configuring converters. This greatly simplifies adding support for EncConverter to different client applications.

This article shows the new functions, some snippets of code to invoke them, and the resulting user-interface dialog boxes.

Note

The interface has not changed since version 2.2, so even if you have SILConverters 2.5 or newer installed, you will want to use “SilEncConverters22” in the strings given in the snippets of code below.

This document is primarily for developers who are interested in adding EncConverter support to their application.

AutoSelect

The AutoSelect function is now available (on the EncConverters interface) for client applications that want to provide a simple means for users to select an EncConverter to use in their application.

Calling the AutoSelect function causes the Select Converter dialog box to be displayed:

Select Converter Dialog




In this dialog box, the user can select the desired converter from the list of available converters in the System Repository and also select the Conversion Options, such as Direction, Normalization of the output data, and Debug mode for getting feedback about what data was sent and received by the underlying conversion engine.

Once configured, the user clicks  OK , and the selected IEncConverter object is returned to the client application for use. This figure shows the function prototype:

-

IEncConverter AutoSelect(ConvType eConversionTypeFilter)

The ConvType parameter can be used to have the Select Converter dialog filter the list of converters being displayed. Depending on the needs of the client app, you can limit the list to only Legacy to Unicode Encoding converters, for example, by passing in the value:

ConvType.Legacy_to_from_Unicode

If your application only supports Unicode encodings on both sides of a transduction process, then you can use:

ConvType.Unicode_to_from_Unicode

To have the Select Converters dialog box display all of the converters in the repository, use:

ConvType.Unknown

The following code snippets show how to call the AutoSelect function in various different programming environments.

// C# snippet
using SilEncConverters22; // Add Reference to SilEncConverters22.dll
...
public void TestAutoSelect()
{
    // get an instance of the repository object
    EncConverters aECs = new EncConverters();
 
    // call AutoSelect to query the user for the converter
    IEncConverter aEC = aECs.AutoSelect(ConvType.Unknown);

    // Always check the return in case the user Cancelled the dialog 
    if (aEC != null)
    {
        // call the 'Convert' function to do a conversion
        string strIn = "bccdèéêfg";
        string strOut = aEC.Convert(strIn);
 
        MessageBox.Show(String.Format("'{1}' became '{0}'", strOut, strIn));
    }
}

' VB.Net snippet
Imports SilEncConverters22     ' Add Reference to SilEncConverters22.dll
...
Public Sub TestAutoSelect()
 
    ' get an instance of the repository object
    Dim aECs As New EncConverters
 
    ' call AutoSelect to query the user for the converter
    Dim aEC As IEncConverter = aECs.AutoSelect(ConvType.Unknown)
 
    ' Always check the return in case the user Cancelled the dialog
    If (Not aEC Is Nothing) Then
 
        ' call the 'Convert' function to do a conversion
        Dim strIn As String = "bccdèéêfg"
        Dim strOut As String = aEC.Convert(strIn)
        MessageBox.Show(String.Format("'{0}' becomes '{1}'", strIn, strOut))

    End If
 
End Sub

' VBA snippet (for Word, Excel, Access, Publisher, etc, macros)
' Be sure to Add a Reference to the SilEncConverters22.tlb file
' via Tools, References, and then Browse for the .tlb file
 
Sub TestAutoSelect()
    Dim aEC As IEncConverter    ' variable for the converter
    Dim aECs As EncConverters   ' variable for the repository
    
    ' get an instance of the repository object
    Set aECs = CreateObject("SilEncConverters22.EncConverters")
    
    ' call AutoSelect to query the user for the converter
    Set aEC = aECs.AutoSelect
    
    ' Always check the return in case the user Cancelled the dialog
    If (Not aEC Is Nothing) Then
        
        ' call the 'Convert' function to do a conversion
        Dim strIn, strOut As String
        strIn = "bccdèéêfg"
        strOut = aEC.Convert(strIn)
        strRes = "/" & strIn & "/ became /" & strOut & "/"
        MsgBox strRes
 
    End If
    
End Sub

// C++ snippet (using ATL's CComPtr and CComBSTR helper classes)

// add SilEncConverters22.tlb to the local project folder
#import "SilEncConverters22.tlb"  raw_interfaces_only
using namespace SilEncConverters22;

void TestAutoSelect()
{
    // get an instance of the repository object
    CComPtr<IEncConverters> aECs;
    aECs.CoCreateInstance(L"SilEncConverters22.EncConverters");

    // if it worked, call AutoSelect to query the user for the converter
    CComPtr<IEncConverter> aEC;
    if( !!aECs && (aECs->AutoSelect(ConvType_Unknown, &aEC) == S_OK) )
    {
        // Always check the return in case the user Cancelled the dialog
        if( !!aEC )
        {
            // call the 'Convert' function to do a conversion
            CComBSTR strIn = L"bccdèéêfg";
            CComBSTR strOut;
            if( aEC->Convert(strIn, &strOut) == S_OK )
            {
                CString strFormat;
                strFormat.Format(_T("'%s' becomes '%s'"), 
                    (LPCTSTR)strIn, (LPCTSTR)strOut);
                MessageBox(0, strFormat, _T("TestAutoSelect"), MB_OK);
            }
        }
    }
}

AutoSelectWithTitle

The AutoSelectWithTitle method is the same as AutoSelect described above, but allows the client application to provide a string which will be used in the Choose Converter dialog box frame. This is useful, for example, if your application queries the user for several different converters and you want the dialog box frame (top bar) to display some text to inform the user of which one to select for a given occurrence.

This method is available on the EncConverters interface.

-

IEncConverter AutoSelectWithTitle(ConvType eConversionTypeFilter, string strChooseConverterDialogTitle)

As above, the ConvType parameter can be used to have the Select Converter dialog filter the list of converters being displayed. Depending on the needs of the client app, you can limit the list to only Legacy to Unicode Encoding converters, for example, by passing in the value:

ConvType.Legacy_to_from_Unicode

If your application only supports Unicode encodings on both sides of a transduction process, then you can use:

ConvType.Unicode_to_from_Unicode

To have the Select Converters dialog box display all of the converters in the repository, use:

ConvType.Unknown

The string strChooseConverterDialogTitle parameter is the string that will be displayed in the Choose Converter dialog box frame.

Configure

While most client applications will probably want to use the AutoSelect function discussed above, there is another interface that can be used when you know exactly which transduction engine implementation you want your users to use.

That is, one of the main advantages of using EncConverters is that your client application doesn't have to concern itself with whether the underlying conversion engine is a CC Table, TECkit map, Perl Expression, etc. With exactly the same interface (i.e. nominally the Convert call), your client application can get the converted value back regardless of the underlying process.

However, if for whatever reason, you want to limit your users to a particular implementation type, you can use the Configure method (of the IEncConverterConfig interface) to acquire a converter of a particular type.

Calling the Configure method will cause a three-tab About / Setup / Test Area dialog box to be displayed for the corresponding converter. For example, here is the dialog box for the Perl Expression EncConverter implementation:

Perl Expression Converter Setup dialog



Each EncConverter implementation has its own version of this dialog box to query for whatever information is necessary to its operation. Each implementation differs in complexity. So, for example, the TECkit Setup tab has only a browse button for TECkit map file and an edit control for showing the file spec.

The dialog box also has an About help tab explaining the details of the converter and its configuration details and a Test Area tab for checking the converter with sample data.

Once configured, the user clicks  OK , and the selected IEncConverter object is returned to the client application for use.

In addition to the Configure method there's another helper method available (from the EncConverters interface) for acquiring an unconfigured IEncConverter object of the appropriate implementation type: NewEncConverterByImplementationType.

This figure shows the function prototype of both methods:

-

IEncConverter NewEncConverterByImplementationType(String strImplType)

The strImplType parameter indicates the Implementation Type of the converter being requested. The values it takes may change as new implementations are added to the EncConverters suite, but as of v2.20, the following implementation types are available:

"SIL.cc" (i.e. CC Table)

"SIL.tec" (i.e. TECkit map)

"SIL.tecForm" (i.e. TECkit for converting between UTF flavors)

"SIL.map" (i.e. TECkit map – auto-compiling)

"cp" (i.e. Code Page Converter)

"SIL.comp" (i.e. Compound (daisy-chained) Converter)

"ICU.trans" (i.e. ICU Transliterator)

"ICU.conv" (i.e. ICU Converter)

"ICU.regex" (i.e. Regular Expression Find and Replace (ICU))

"SIL.PyScript" (i.e. Python Script)

"SIL.PerlExpression" (i.e. Perl Expression)

"SIL.fallback" (i.e. Primary-Fallback Converter)

"SIL.AdaptItKB" (i.e. AdaptIt Knowledge Base Lookup Converter)

Each of these strings is available as public string constant of the EncConverters' interface (e.g. EncConverters.strTypeSILcc). You can also look in the registry key, HKEY_LOCAL_MACHINESOFTWARESILSilEncConverters22ConvertersSupported, to see the supported implementation types.

Boolean Configure (IEncConverters aECs, String strFriendlyName, ConvType eConversionType, String strLhsEncodingID, String strRhsEncodingID)

The parameters, most of which can be left default, are as follows:

IEncConverters aECs

This is the interface pointer for the repository object, through which dialog box will add any newly created converters. Required.

String strFriendlyName

This is the friendly name to give the converter (if the client app wants to specify it; otherwise, it can be null to allow the user to choose the name).

ConvType eConversionType

If the client application only deals with Unicode to Unicode conversions, for example, you can provide the appropriate ConvType value and then the radio buttons for specifying the type will be left out of the dialog box (i.e. to simplify the dialog). Otherwise, use ConvType.Unknown

String strLhsEncodingID

This allows the client app to specify what the encoding ID of the left-hand side of the conversion is (e.g. UNICODE). Can be null.

String strRhsEncodingID

This allows the client app to specify what the encoding ID of the right-hand side of the conversion is (e.g. UNICODE). Can be null.

The following code snippets show how to call the Configure function in C#:

// C# snippet
using SilEncConverters22; // Add Reference to SilEncConverters22.dll
...
public void TestConfigure()
{
    // get an instance of the repository
    EncConverters aECs = new EncConverters();
 
    // get a new, empty IEncConverter object of the correct implementation type
    IEncConverter aEC = aECs.NewEncConverterByImplementationType(
                                    EncConverters.strTypeSILtec);

    // get the configuration interface for this type
    IEncConverterConfig aConfigurator = aEC.Configurator;

    // there may be some implementation types that don't provide their 
    // own user-interface, so always check before using it
    if( aConfigurator != null )
    {
        // call its Configure method to do the UI
        if(aConfigurator.Configure(aECs, null, ConvType.Unknown, null, null))
        {
            // if we reach here, then the converter must have been 
            // configured; though, in fact, it might not have been
            // added to the System Repository (i.e. it might just 
            // be a temporary converter). You can use the 
            // rConfigurator.IsInRepository method to detect if it
            // was added or not
            // now, call the 'Convert' function to do a conversion
            string strIn = "bccdèéêfg";
            string strOut = aEC.Convert(strIn);
 
            MessageBox.Show(String.Format("'{1}' became '{0}'", 
                        strOut, strIn));
        }
    }
}

Custom transduction engines

In addition to providing support in client applications for accessing different transduction engines, it is possible to plug any arbitrary transduction engine into the SILConverter’s paradigm so that it becomes available to any of the EncConverter’s clients. This can be done by implementing the IEncConverter interface as defined in the SilEncConverters22.dll .Net assembly.

If your transduction engine is in an exe which processes text via standard in/out or in a DLL, there are several sub-classes in that assembly that simplify the process of adding a transduction engine.

Contact for further details.


© 2003-2021 SIL International, all rights reserved, unless otherwise noted elsewhere on this page.
Provided by SIL's Writing Systems Technology team (formerly known as NRSI). Read our Privacy Policy. Contact us here.