Unicode Software Development Kit for OPL (for UniFEP V2)
========================================================

	Enfour (c) 2000

This kit allows OPL authors to write applications with user interface
and text processing in scripts supported by Unicode.  

From the point of view of the OPL author, the OPX "uniopx.opx"
provides a number of new functions.  The OPX is automatically
installed as part of UniFEP (the WINS version is part of the UniFEP
emulator version).

This SDK is mainly for UniFEP V2. For a UniFEP 1.x specific version see:
http://www.enfour.co.jp/psion/development/download/unisdk_opl/OPLSDK_for_1.x.txt

UniOpx
======

EPOC machines that have UniFEP V2 or higher installed have a modified
EPOC graphics system, and text in the menus, dialogs, and toolbar
buttons automatically uses UTF8 encoded Unicode.  This means that
ordinary OPL programs (using normal OPL commands for display of text,
menus and dialogs, and the Toolbar.opo module for the toolbar) can
correctly handle text in Japanese, Chinese, or Korean.  

In current release of UniFEP, it is not possible to display Unicode in
info messages or busy messages by using BUSY or gIPRINT in OPL.

Note: The previous version of the Unicode environment, UniFEP 1.X,
made Unicode available only in the ROM applications.  OPL programs are
not automatically enabled, but can use Unicode after calling a special
function (UOEnableUtf8:) in UniOPX.  The function is available, but
does nothing in the version of UniOPX distributed with UniFEP V2.
     
In UniFEP 1.X, the UniOPX was necessary to write Unicode-capable OPL
programs.  In UniFEP V2 this is no longer the case.  The OPX is still
useful, as it provides services for easier handling of the UTF-8
encoding, as well as code conversion to and from other encodings.

In its current version, UniOPX is directed at the porting and creating
of OPL applications for the Japanese market.  Since it is completely
Unicode based, it is also applicable for Korean and Chinese
localization (as well as other languages that use scripts available in
Unicode).

Note that OPL programs with text in UTF8 encoding can be entered
directly into the OPL program editor using UniFEP.


Overview
========

UniOPX needs to be declared in the OPL source with the line:

INCLUDE "UniOpx.oxh"

The OPX provides functions to convert text to and from several coding
systems, so file in- and output can be done in any supported coding
system.  Internally, text can be stored as you prefer, as long as it
is converted to Unicode for display.

Which coding systems are available depends on the system
installation. Each coding system is realized as a DLL in the directory
\System\UniFEP\Encoding.

Unicode text entry through UniFEP is supported through dialogs (the
dEDIT and dEDITMULTI commands).

OPL programs can also exchange text with other applications through
the clipboard.  For instance, to implement the "paste" command, the
program should react to the keypress Ctrl+V and read the clipboard
using UOCopyFromClip&:

The font installed with UniFEP provides the glyphs for a Unicode
subset.  Characters not in the subset are displayed as boxes.  Two
Latin-1 fonts are provided that fit the Unicode font better in their
design than the built-in fonts: TB Gothic, and TBG Mono (a monospaced
font).

UniOpx.oxh defines the following constants to be used with gFONT:

const KFontTBGothicNano = &1000184a
const KFontTBGothicMicro = &10001849
const KFontTBGothicTiny& = &10004351
const KFontTBGothicSmall& = &10004352
const KFontTBGothicNormal& = &10004353
const KFontTBGothicLarge& = &10004354

const KFontTBGothicMonoNano = &10001854
const KFontTBGothicMonoMicro = &1000184b
const KFontTBGothicMonoTiny& = &10004355
const KFontTBGothicMonoSmall& = &10004356
const KFontTBGothicMonoNormal& = &10004357
const KFontTBGothicMonoLarge& = &10004358


Version information
===================

As of September 2000, there are two major releases of UniFEP, i.e.
UniFEP 1.X (UniFEP for EPOC 1.0/1.1, UniFEP for 5mx and for Revo)
and UniFEP V2.

The OPX documented here is version 1.50, which comes with UniFEP V2
and higher.  It is compatible with earlier versions of the OPX.
Most applications written for UniFEP 1.X will run unmodified, and vice versa.

Note that the header file UniOpx.txh declares the OPX as Version
1.0. This is done so that OPL programs written with this version will
still run with UniFEP 1.X.  Of course you need to avoid the features
of V2 not available under 1.X. 
For a better compatibility with the older UniFEP systems, several 
points should be taken into account:

 * UniFEP 1.X OPL programs can only use Unicode in OPL output
   commands like gPRINT after calling the function (UOEnableUtf8:) in
   UniOPX.  The function does nothing in UniFEP V2.

 * The Nano and Micro font sizes are not available in UniFEP 1.X.

 * UOEncodingUid&: is not available in UniFEP 1.X.

 * In UniFEP 1.X OPL programs, it is possible to use KUOHuge7% or
   KUOHuge8% as a parameter for  UOFontMetric: and UOTextWidth&:,
   while these are not available any more in UniFEP V2 programs.

 * In OXH file for UniFEP 1.X, no constants for UIDs of encoding dlls
   is defined. This makes it impossible to translate the source
   code of an OPL program that uses these constants with UniFEP 1.X
   OXH file. However, once translated with UniFEP V2 OXH file, it
   should be possible to run the OPL binary even under UniFEP 1.X
   environment.

 * There might be some difference in the design of the fonts between
   different releases of UniFEP. See UOFontMetric:.

If you wish to restrict your OPL programs to UniFEP V2 and higher,
change KUOVersion% to $150 in UniOpx.txh.


Functions in UniOpx:
====================


UOSupported&:
=============

Returns 1 if UniFEP is installed and activated on the system, 0
otherwise. 


UOFontMetric:(size%, BYREF height&, BYREF descent&)
===================================================

This version of Enfour Unicode library supports 10 different sizes of
Unicode text. Suitable constants KUOTiny%, KUOSmall%, KUONormal%,
KUOLarge%, etc., are defined in UniOpx.oxh.  This function allows you
to find the height of a character cell and the descent in pixels.  

Programmers should not assume that the size parameters (height,
descent, width etc.) of a font with some UID in some release of UniFEP
(e.g. a font with the uid of KFontTBGothicMonoNormal& in UniFEP for
EPOC32) are the same with those of a font with the same UID in another
release of UniFEP (e.g. UniFEP V2). 
There may or may not be some differences, e.g. something due to the
change in the design for a better fit to a specific hardware etc.


UOTextWidth&:(size%, str$)
==========================

Return the width of the string in pixels if displayed using the
Unicode font of size%.


UOCopyFromClip&:(buf&, buflen&, lf%)
====================================

Copies rich text in UTF8, UniFEP or KEdit format from clipboard to
UTF8 buffer, returning length of text. Lf% determines the style of
linefeed (Unix, DOS, Mac, see UniOpx.oxh).  The buffer has to be
allocated using ALLOC before calling this function.


UOCopyToClip:(buf&, buflen&)
============================

Copy UTF8 buffer to clipboard (in UTF8). 
    

UOBufferAsString$:(buf&, len&)
UOBufferFromString&:(buf&, len&, str$)
======================================

These two functions make dealing with buffers easier, as they convert
between buffers and OPL strings.  Be careful: OPL strings cannot
contain more than 255 characters, and that is only 85 Japanese
characters!

UOBufferAsString$ creates a string with the contents of the buffer.

UOBufferFromString& puts the string in the buffer, returning the
length.


UONumEncodings%:
UOEncodingName$:(num%)
UOEncodingUid&:(num%)
======================

UONumEncodings% returns the number of installed encoding systems. The
other two functions return the name and UID of each encoding.  If you
need a particular encoding, look for its UID, as the name can change
in different locales/versions of UniFEP.  The name is meant to be used
when you make a dCHOICE to let the user select an encoding.
Constants for the UID's are defined in the header file, like this:

const KUOEncodingShiftJis& = &10000e26
const KUOEncodingUtf8& = &10001852
const KUOEncodingJIS& = &10000e28
const KUOEncodingUcs2& = &10000e27
const KUOEncodingEucJp& = &10000e29
const KUOEncodingMacRoman& = &10001851
const KUOEncodingCP1252& = &10001850
const KUOEncodingLatin1& = &10001853


UOReleaseEncoding:(num%)
========================

The encoding with the given index is no longer needed and will be
unloaded, if it is not used by another program.


UOEncodeChar&:(uni&, enc%)
UODecodeChar&:(ch&, enc%)
==========================

Convert a single character between Unicode and a national
encoding, given by its index.


UOEncode&:(frombuf&, fromlen&, tobuf&, tolen&, enc%)
UODecode&:(frombuf&, fromlen&, tobuf&, tolen&, enc%)
====================================================

Convert a whole buffer between Unicode (in UTF8) and a national
encoding system. Both functions return the length of the output text.


UOWChar&:(buf&, BYREF pos&)
UOUtf$:(uni&)
===========================
 
These two functions make it easier to deal with the UTF8
encoding. UOUtf$:(uni&) returns a string with the UTF8 encoding of the
Unicode character uni&.  UOWChar& interprets the buffer contents at
position pos& as the beginning of a UTF8 encoded character, and
returns the Unicode codepoint of the character. The position pos& is
updated to point to the next UTF8 character.


UOEnableUtf8:  OBSOLETE!!
=============

Sets up UniFEP 1.X to modify the EPOC graphics system so that text displayed 
by gPRINT as well as in the menus, dialogs, and toolbar buttons uses UTF8 
encoded Unicode.  You can now use ordinary OPL commands for text display,
menus and dialogs, and the Toolbar.opo module for the toolbar.

This is no longer needed for versions of UniFEP after 1.X.


UOPrint:(win&, BYREF x&, y&, size%, str$) OBSOLETE!!
=========================================

This function was originally implemented in UniFEP 1.X to allow the
program to display Unicode characters without using UOEnableUtf8:.
This was handy if the programmer didn't want to use Unicode in menus,
dialogs etc., but still wanted to draw Unicode characters on OPL 
windows occasionally.
You can now use gPRINT to print Unicode characters without using this
function.

win& is the id of the OPL window, x& and y& are the coordinates on the 
window, size% is the size of the font to be used (KUOLarge% etc.), and
str$ is the UTF8 encoded Unicode string.
Unlike gPRINT, UOPrint: doesn't change the current position after 
printing. Rather, the parameter x& is updated to the value which 
represents the new position.

This function still works, but is no longer needed, for versions of 
UniFEP after 1.X.