LaoScript 8 Add-In for Microsoft Access - User Guide
The LaoScript 8 Add-In for Microsoft Access is an Application Programming Interface (API) providing a set of functions and subroutines that can be called from queries or VBA code to help automate Access applications using Lao language and/or convert between character coding conventions.
The Add-In requires LaoScript 8 Version 8.1.4 or later.
Installing the Add-In
During the installation of LaoScript 8, both 32-bit (x86) and 64-bit (x64) versions of the Add-In are copied to the application folder. The version appropriate for the installed edition of Microsoft Access is then copied to the user's Microsoft\AddIns folder when LaoScript 8 is next started.
You must register and enable the Add-In before you can use Add-In functions with any Access database.
Register the Add-In (the first time it is used)Under Tools - Add-Ins (Access 2003) or Database Tools - Add-ins (Access 2007 or later), select Add-In Manager, then select the entry for LaoScript8AddIn and click Install. If LaoScript8AddIn is not listed, use Browse to locate and select either LaoScript8AddIn.mde (for 32-bit Access) or LaoScript8AddIn64.mde (64-bit Access), then click Install.
Enable the Add-In (the first time each database uses it)After registering the Add-In, the entry Enable LaoScript8 Add-In will appear in the list of Add-Ins. Select this menu entry to complete enabling the LaoScript 8 Add-In for the currently active database. This will start the LaoScript8 application (if it is not already executing), and then display a small notication window confirming that the Add-In is ready, with a button linking to this Help file.
See Alternative Initialization for another way to enable use of the LaoScript 8 Add-In by an Access database application.
Lao Add-In API Functions and Subroutines
The purpose and calling conventions for each API function or subroutine is described briefly below.
Lao text-processing functions
Lao text-processing functions take one or more of the following arguments (passed by value) and return the result as a string. The first argument (the string to process) is required, but the remaining arguments are optional. For most functions, strings are assumed to be Unicode unless otherwise indicated.
| Argument | Type | Description |
|---|---|---|
| sLao | string | Lao text string to be processed |
| sThai | string | Thai text string to translate |
| sKey | string | sorting key string |
| fontName | string or integer | font name or font code for text (see note) |
| sortMethod | integer | sorting priority (see note) |
The following table lists the Lao text-processing functions in the API, all of which may be called either from SQL queries or from VBA code:
| Function | Description |
|---|---|
| LS8_JoinLao(sLao,[fontName]) | Remove breaks from (unwrap) Lao text. |
| LS8_BreakLao(sLao,[fontName]) | Insert breaks in Lao text to allow automatic wrapping at word-boundaries at the end of each line. |
| LS8_CheckLao(sLao,[fontName]) | Insert two break codes at each spelling error in the Lao text string. |
| LS8_RomanizeLao(sLao,[fontName]) | Return Lao text in latin script (romanized) form. |
| LS8_ToUnicode(sLao,[fontName]) | Convert Lao string from old coding convention to Unicode. |
| LS8_ToOldCode(sLao,[fontName]) | Convert Lao Unicode string into old coding convention (see note). |
| LS8_ThaiToLao(sLao,[fontName]) | Translate the Thai text string into Lao (Unicode only - second argument is ignored) |
| LS8_SortKey(sLao,[fontName],[sortMethod]) | Return a string that allows Lao text to be correctly sorted in Lao alphabetic order. |
| LS8_WordFromKey(sKey,[fontName],[sortMethod]) | Return a Lao syllable string that corresponds to a given sorting key string. |
Notes:
- The fontName argument may be either an integer, specifying the font code or the name of the font associated with the text string. If not specified, text strings are assumed to be Unicode except by LS8_ToUnicode and LS8_ToOldCode, for which the input and output strings respectively are assumed to be Saysettha Lao-coded (font code 1).
- For LS8_ToOldCode, LS8_WordFromKey and LS8_ThaiToLao the fontName argument applies to the coding of the output string rather than the input string. If specified, it can only be the code value 0 (Unicode), 1 (LSWin) or 2 (Lao95), or the name of a font with one of those coding conventions.
-
Lao alphabetic sorting (unlike Thai) is usually phonetic rather than orthographic. The sortMethod
argument value provides for the two different methods for sorting Lao syllables that are most commonly used:
Value Name Description 1 IFVT Order by initial consonant, final consonant, vowel, tone 2 IVFT Order by initial consonant, vowel, final consonant, tone 0 (default) Use method set in LaoScript 8 User Settings
Control and helper functions
A number of other functions and subroutines can be called from VBA code to control keyboard mapping and other behavior in forms for managing Lao text:
| Function | Description |
|---|---|
| LS8_Start(showStatus) | Start LaoScript 8 automatically. (Display progress bar if showStatus is True.) |
| LS8_Terminate() | Terminate LaoScript 8 application. |
| LS8_StartMeter(maxValue,minValue) | Initialize progress bar with maximum value, or reset if maxValue <= minValue. |
| LS8_UpdateMeter(Value) | Set length of progress bar to Value as percentage of maxValue. |
| LS8_SetMeterCaption(caption) | Set text to display above progress bar. |
| LS8_CloseMeter() | Close the progress bar window. |
| LS8_EnableLao(bEnable,[bUnicode]) | Enable or disable Lao keyboard mapping and set mode (Unicode by default). |
| LS8_SetBreakMode(mode) | Set hyphenation mode (mode: integer, 0-3). |
| LS8_SetMappingState(strState) | Directly set the keyboard mode, coding, and break mode. |
| LS8_OpenWordList() | Open the Lao word list dialog. |
| LS8_AddWordToList(sLao) | Add a Lao word to the user dictionary. (Returns true if added.) |
| LS8_OpenThaiWordList() | Open the Thai-Lao dictionary dialog. |
| LS8_OptionsDialog() | Open the LaoScript 8 settings dialog. |
| LS8_ErrorMode(bMode) | Break (True, default) or continue (False) on IPC errors. |
| LS8_Help() | Open the User Guide for LaoScript 8. |
Information functions
The following information functions are also provided:
| Function | Description |
|---|---|
| LS8_About() | Open the LaoScript 8 About window ("splash screen"). |
| LS8_Build() | Return the LaoScript 8 build version (as a string). |
| LS8_CountErrors(sLao) | Return the number of marked spelling errors in the Lao Unicode text string. |
| LS8_FontQuery(fontName) | Return the relevant font properties as a string array (see below). |
| LS8_FontType(fontName) | Return the (integer) coding convention for the specified font. |
| LS8_FontTypes() | Return a list of recognized font coding types. |
| LS8_GetBreakMode() | Return the (integer) hyphenation mode. |
| LS8_GetMappingState() | Return the (string) keyboard mapping state. |
| LS8_GetOption(optNo) | Return value of selected option (or all option values, if optNo=0). |
Lao Font Types
LaoScript 8 identifies Lao Unicode fonts by the character set used, and all other types of Lao font by the font name, which must be listed in the LaoScript 8 reference data. Conversion of Lao text is supported for fonts using any of the coding conventions indicated in the table below, but other processing is only supported for text using Unicode, LSWin or Lao95 coding. Many older conventions cannot support word wrap, and most cannot represent all Lao and Latin script characters, making it not possible to reliably convert text into strings using those conventions. (See the User Settings dialog and User Guide for more information.)
Recognized coding conventions for Lao fonts are as follows:
| Type | Coding name | Sample Font |
|---|---|---|
| 0 | Unicode | Saysettha OT |
| 1 | LSWin | Saysettha Lao |
| 2 | Lao 95 | Saysettha 95 |
| 3 | Lao 2000 | Saysettha 2000 |
| 4 | IBM-STENO | Saysettha LS |
| 5 | Alice | alice_0 |
| 6 | SengChanh | SengChanh |
| 7 | SengChanh US | SengChanh US |
| 3 | Sayawath | Xayawath |
| -1 | (undefined) | (all unlisted fonts) |
User Settings
The various user settings shown in the LaoScript 8 User Settings dialog can be read or set using the functions LS8_GetOption(optNo) and LS8_SetOption(optNo,value), according to the following table:
| optNo | Setting | Value type |
|---|---|---|
| 1 | Unicode coding | Boolean |
| 2 | Wrap Lao text | Boolean |
| 3 | Help prevent errors | Boolean |
| 4 | Phonetic entry | Boolean |
| 5 | HotKey Code | Integer |
| 6 | Word Lists | Integer (bit mask) |
| 7 | Hyphenation | Integer |
| 8 | Sorting Method | Integer |
| 9 | Romanization Mode | Integer |
| 10 | Romanized text fonts | 4 comma-separated strings |
| 11 | Unicode default font | String |
| 12 | LSWin default font | String |
| 13 | Lao95 old-code input | Boolean |
| 14 | Always use ZWSP as break | Boolean |
| 0 | (show all) | Comma-separated strings |
How it works...
Most functions and subroutines in the API pass string text (or data) to the LaoScript 8 application and receive a processed string back, using piped exchanges. Pipes are used rather than DLL calls, since pipes allow both 32-bit and 64-bit processes to communicate with LaoScript 8.exe (which is a 32-bit application).
NoteBe careful if searching or indexing on Lao text fields. The Jet database engine does not correctly distinguish between different diacritic vowel and tone mark combinations in Lao Unicode character strings. This can sometimes result in selection (or deletion) of unwanted text, and may prevent using a Lao word field as a primary index. A number of work-arounds are possible, such as using binary/blob fields rather than strings, indexing or matching using a re-coded copy of the word,or using VBA with Option Compare Binary to disambiguate matching words. For more information, please contact Dr Durdin using the Lao Script for Windows Contact Form.
Alternative Initialization
Another way to enable the use of the Add-In functions for any Access databse is simply to open the Visual Basic IDE, select the database project, then under Tools- References either select LaoScript8AddIn (if listed), or browse to the Add-In file in the users Add-Ins folder then select it to add it to the VB references. Once added to the list of references, the functions can be called from any query or VB code module.