Layout Service Library Functions mwtransformlayout(3LAYOUT)
NAME
mwtransformlayout - layout transformation for wide charac-
ter strings
SYNOPSIS
cc [ flag... ] file... -llayout [ library... ]
#include
int mwtransformlayout(LayoutObject layoutobject,
const wchart *InpBuf, const sizet ImpSize, const void *OutBuf,
sizet *Outsize, sizet *InpToOut, sizet *OutToInp,
unsignedchar *Property, sizet *InpBufIndex);
DESCRIPTION
The mwtransformlayout() function performs layout transfor-
mations (reordering, shaping, cell determination) or pro-
vides additional information needed for layout transforma-
tion (such as the expected size of the transformed layout,
the nesting level of different segments in the text and
cross-references between the locations of the corresponding
elements before and after the layout transformation). Both
the input text and output text are wide character strings.
The mwtransformlayout() function transforms the input text
in InpBuf according to the current layout values in
layoutobject. Any layout value whose value type is Layout-
TextDescriptor describes the attributes of the InpBuf and
OutBuf arguments. If the attributes are the same for both
InpBuf and OutBuf, a null transformation is performed with
respect to that specific layout value.
The InpBuf argument specifies the source text to be pro-
cessed. The InpBuf may not be NUL, unless there is a need
to reset the internal state.
The InpSize argument is the number of bytes within InpBuf to
be processed by the transformation. Its value will not
change after return from the transformation. InpSize set to
-1 indicates that the text in InpBuf is delimited by a null
code element. If InpSize is not set to -1, it is possible to
have some null elements in the input buffer. This might be
used, for example, for a "one shot" transformation of
several strings, separated by nulls.
SunOS 5.11 Last change: 7 Aug 2006 1
Layout Service Library Functions mwtransformlayout(3LAYOUT)
Output of this function may be one or more of the following
depending on the setting of the arguments:
OutBuf Any transformed data is stored in OutBuf, con-
verted to ShapeCharset.
Outsize The number of wide characters in OutBuf.
InpToOut A cross-reference from each InpBuf code element
to the transformed data. The cross-reference
relates to the data in InpBuf starting with the
first element that InpBufIndex points to (and
not necessarily starting from the beginning of
the InpBuf).
OutToInp A cross-reference to each InpBuf code element
from the transformed data. The cross-reference
relates to the data in InpBuf starting with the
first element that InpBufIndex points to (and
not necessarily starting from the beginning of
the InpBuf).
Property A weighted value that represents peculiar input
string transformation properties with different
connotations as explained below. If this argu-
ment is not a nullpointer, it represents an
array of values with the same number of elements
as the source substring text before the
transformation. Each byte will contain relevant
"property" information of the corresponding ele-
ment in InpBuf starting from the element pointed
by InpBufIndex. The four rightmost bits of each
"property" byte will contain information for
bidirectional environments (when ActiveDirec-
tional is True) and they will mean "NestingLev-
els." The possible value from 0 to 15 represents
the nesting level of the corresponding element
in the InpBuf starting from the element pointed
by InpBufIndex. If ActiveDirectional is false
the content of NestingLevel bits will be
ignored. The leftmost bit of each "property"
byte will contain a "new cell indicator" for
composed character environments, and will have a
value of either 1 (for an element in InpBuf that
is transformed to the beginning of a new cell)
or 0 (for the "zero-length" composing character
elements, when these are grouped into the same
presentation cell with a non- composing
SunOS 5.11 Last change: 7 Aug 2006 2
Layout Service Library Functions mwtransformlayout(3LAYOUT)
character). Here again, each element of "pro-
perty" pertains to the elements in the InpBuf
starting from the element pointed by InpBufIn-
dex. (Remember that this is not necessarily the
beginning of InpBuf). If none of the transforma-
tion properties is required, the argument Pro-
perty can be NUL. The use of "property" can be
enhanced in the future to pertain to other pos-
sible usage in other environments.
The InpBufIndex argument is an offset value to the location
of the transformed text. When mwtransformlayout() is
called, InpBufIndex contains the offset to the element in
InpBuf that will be transformed first. (Note that this is
not necessarily the first element in InpBuf). At the return
from the transformation, InpBufIndex contains the offset to
the first element in the InpBuf that has not been
transformed. If the entire substring has been transformed
successfully, InpBufIndex will be incremented by the amount
defined by InpSize.
Each of these output arguments may be null to specify that
no output is desired for the specific argument, but at least
one of them should be set to a non-null value to perform any
significant work.
In addition to the possible outputs above, layoutobject
maintains a directional state across calls to the transform
functions. The directional state is reset to its initial
state whenever any of the layout values TypeOfText, Orienta-
tion, or ImplicitAlg is modified by means of a call to
msetvalueslayout().
The layoutobject argument specifies a LayoutObject returned
by the mcreatelayout() function.
The OutBufargument contains the transformed data. This argu-
ment can be specified as a null pointer to indicate that no
transformed data is required.
The encoding of the OutBuf argument depends on the
ShapeCharset layout value defined in layoutobject. If the
ActiveShapeEditing layout value is not set (False), the
encoding of OutBuf is guaranteed to be the same as the
codeset of the locale associated with the LayoutObject
SunOS 5.11 Last change: 7 Aug 2006 3
Layout Service Library Functions mwtransformlayout(3LAYOUT)
defined by layoutobject.
On input, the OutSize argument specifies the size of the
output buffer in number of wide characters. The output
buffer should be large enough to contain the transformed
result; otherwise, only a partial transformation is per-
formed. If the ActiveShapeEditing layout value is set (True)
the OutBuf should be allocated to contain at least the Inp-
Size multiplied by ShapeCharsetSize.
On return, the OutSize argument is modified to the actual
number of code elements in OutBuf.
When the OutSize argument is specified as zero, the function
calculates the size of an output buffer large enough to con-
tain the transformed text, and the result is returned in
this field. The content of the buffers specified by InpBuf
and OutBuf, and the value of InpBufIndex, remain unchanged.
If OutSize = NUL, the EINVAL error condition should be
returned.
If the InpToOut argument is not a null pointer, it points to
an array of values with the same number of wide characters
in InpBuf starting with the one pointed by InpBufIndex and
up to the end of the substring in the buffer. On output, the
nth value in InpToOut corresponds to the nth byte in InpBuf.
This value is the index (in units of wide characters) in
OutBufthat identifies the transformed ShapeCharset element
of the nth byte in InpBuf.
InpToOut may be specified as NUL if no index array from
InpBuf to OutBuf is desired.
If the OutToInp argument is not a null pointer, it points to
an array of values with the same number of wide characters
as contained in OutBuf. On output, the nth value in OutToInp
corresponds to the nth byte in OutBuf. This value is the
index in InpBuf, starting with wide character byte pointed
to by InpBufIndex, that identifies the logical code element
of the nth wide character in OutBuf.
OutToInp may be specified as NUL if no index array from
OutBuf to InpBuf is desired.
SunOS 5.11 Last change: 7 Aug 2006 4
Layout Service Library Functions mwtransformlayout(3LAYOUT)
To perform shaping of a text string without reordering of
code elements, the layoutobject should be set with input
and output layout value TypeOfText set to TEXTVISUAL and
both in and out of Orientation set to the same value.
RETURN VALUES
If successful, the mwtransformlayout() function returns 0.
If unsuccessful, the returned value is -1 and the errno is
set to indicate the source of error. When the size of OutBuf
is not large enough to contain the entire transformed text,
the input text state at the end of the uncompleted transfor-
mation is saved internally and the error condition E2BIG is
returned in errno.
ERORS
The mwtransformlayout() function may fail if:
E2BIG The output buffer is full and the source text is
not entirely processed.
EBADF The layout values are set to a meaningless combi-
nation or the layout object is not valid.
EILSEQ Transformation stopped due to an input code ele-
ment that cannot be shaped or is invalid. The Inp-
BufIndex argument is set to indicate the code ele-
ment causing the error. The suspect code element
is either a valid code element but cannot be
shaped into the ShapeCharset layout value, or is
an invalid code element not defined by the codeset
of the locale of layoutobject. The mbtowc() and
wctomb() functions, when used in the same locale
as the LayoutObject, can be used to determine if
the code element is valid.
EINVAL Transformation stopped due to an incomplete compo-
site sequence at the end of the input buffer, or
OutSize contains NUL.
ERANGE More than 15 embedding levels are in source text
or InpBuf contain unbalanced directional layout
information (push/pop) or an incomplete composite
sequence has been detected in the input buffer at
the beginning of the string pointed to by Inp-
BufIndex.
An incomplete composite sequence at the end of the
input buffer is not always detectable. Sometimes
SunOS 5.11 Last change: 7 Aug 2006 5
Layout Service Library Functions mwtransformlayout(3LAYOUT)
the fact that the sequence is incomplete will only
be detected when additional character elements
belonging to the composite sequence are found at
the beginning of the next input buffer.
USAGE
A LayoutObject will have a meaningful combination of default
layout values. Whoever chooses to change the default layout
values is responsible for making sure that the combination
of layout values is meaningful. Otherwise, the result of
mwtransformlayout() might be unpredictable or
implementation-specific with errno set to EBADF.
EXAMPLES
Example 1 Shaping and reordering input string into output
buffer
The following example illustrated what the different argu-
ments of mwtransformlayout() look like when a string in
InpBuf is shaped and reordered into OutBuf. Upper-case
letters in the example represent left-to-right letters while
lower-case letters represent right-to-left letters. xyz
represents the shapes of cde.
Position: 0123456789
InpBuf: AB cde 12z
Position: 0123456789
OutBuf: AB 12 zyxZ
Position: 0123456789
OutToInp: 0127865439
Position: 0123456789
Property.NestLevel: 0001111220
Property.CelBdry: 1111111111
The values (encoded in bianry) returned in the Property
argument define the directionality of each code element in
the source text as defined by the type of algorithm used
within the layoutobject. Whlie the algorithm may be imple-
mentation dependent, the resulting values and levels are
defined such as to allow a single method to be used in
determining the directionality of the sourece text. The base
rules are:
SunOS 5.11 Last change: 7 Aug 2006 6
Layout Service Library Functions mwtransformlayout(3LAYOUT)
o Odd levels are always RTL.
o Even levels are always LTR.
o The Orientation layout value setting determines the
initial level (0 or 1) used.
Within a Property array each increment in the level indi-
cates the corresponding code elements should be presented in
the opposite direction. Callers of this function should
realize that the Property values for certain code elements
is dependent on the context of the given character and the
layout values: Orientation and ImplicitAlg. Callers should
not assume that a given code element always has the same
Property value in all cases.
Example 2 Algorithm to handle nesting
The following is an example of a standard presentation algo-
rithm that handles nesting correctly. The goal of this algo-
rithm is ultimately to return to a zero nest level. Note
that more efficient algorithms do exist; the following is
provided for clarity rather than for efficiency.
1. Search for the highest next level in the string.
2. Reverse all surrounding code elements of the same
level. Reduce the nest level of these code elements
by 1.
3. Repeat 1 and 2 until all code elements are of level
0.
The following shows the progression of the example from
above:
Position: 0123456789 0123456789 0123456789
InpBuf: AB cde 12Z AB cde 21Z AB 12 edcZ
Property.NestLevel: 0001111220 0001111110 0000000000
Property.CellBdry: 1111111111 1111111111 1111111111
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 7 Aug 2006 7
Layout Service Library Functions mwtransformlayout(3LAYOUT)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level MT-Safe
SEE ALSO
attributes(5), standards(5)
SunOS 5.11 Last change: 7 Aug 2006 8
|
