[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, Volume 1
layout_object_transform or wcslayout_object_transform Subroutine
Purpose
Transforms text according to the current layout values
of a LayoutObject structure.
Library
Layout Library (libi18n.a)
Syntax
#include <sys/lc_layout.h>
int layout_object_transform( layout_object, InpBuf, InpSize, OutBuf, OutSize, InpToOut, OutToInp, BidiLvl)
LayoutObject layout_object;
const char *InpBuf;
size_t *InpSize;
void * OutBuf;
size_t *OutSize;
size_t *InpToOut;
size_t *OutToInp;
unsigned char *BidiLvl;
int wcslayout_object_transform (layout_object, InpBuf, InpSize, OutBuf, OutSize, InpToOut, OutToInp, BidiLvl)
LayoutObject layout_object;
const char *InpBuf;
size_t *InpSize;
void *OutBuf;
Size_t *OutSize;
size_t *InpToOut;
size_t *OutToInp;
unsigned char *BidiLvl;
|
Description
The layout_object_transform and wcslayout_object_transform subroutines transform the text
specified by the InpBuf parameter according to the
current layout values in the LayoutObject structure.
Any layout value whose type is LayoutTextDescriptor describes the attributes
within the InpBuf and OutBuf parameters.
If the attributes are the same as the InpBuf and OutBuf parameters themselves, a null transformation is
done with respect to that specific layout value.
The output of these subroutines may be one or more
of the following results depending on the setting of the respective parameters:
|
OutBuf, OutSize |
Any transformed data is stored in the OutBuf parameter. |
|
InpToOut |
A cross reference from each code element of the InpBuf parameter to the transformed data. |
|
OutToInp |
A cross reference to each code element of the InpBuf parameter from the transformed data. |
|
BidiLvl |
A weighted value that represents the directional level of each code
element of the InpBuf parameter. The level is dependent
on the internal directional algorithm of the LayoutObject structure. |
You can specify each of these output parameters as
Null to indicate that no output is needed for the specific parameter. However,
you should set at least one of these parameters to a nonNULL value to perform
any significant work.
To perform shaping of a text string without reordering
of code elements, set the TypeOfText layout value to TEXT_VISUAL and the in and out values of the Orientation layout value alike. These
layout values are in the LayoutObject structure.
Note
If you are developing internationalized applications that
may support multibyte locales, please see
Use of
the libcur Package in
AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging ProgramsParameters
|
layout_object |
Specifies the LayoutObject structure created
by the layout_object_create subroutine. |
|
InpBuf |
Specifies the source text to be processed. This parameter cannot
be null. |
|
InpSize |
Specifies the units of code elements processed associated with the
bytes for the layout_object_transform and wcslayout_object_transform subroutines. A value of -1 indicates that
the input is delimited by a null code element. On return, the value is modified
to the actual number of code elements processed in the InBuf parameter. However, if the value in the OutSize parameter is zero, the value of the InpSize parameter
is not changed. |
|
OutBuf |
Contains the transformed data. You can specify this parameter as
a null pointer to indicate that no transformed data is required.
The encoding of the OutBuf parameter depends on the
ShapeCharset layout value defined in the LayoutObject structure.
If the ActiveShapeEditing layout value is set to True, the encoding of the OutBuf parameter is the same as the code set of the locale
associated with the LayoutObject structure. |
|
OutSize |
Specifies the size of the output buffer in number of bytes. The output
buffer should be large enough to contain the transformed result; otherwise,
only a partial transformation is performed. If the ActiveShapeEditing layout
value is set to True, the OutBuf parameter should
be allocated to contain at least the number of code elements multiplied by
the ShapeCharsetSize layout value.
On return, the OutSize parameter is modified to the actual number of
bytes placed in this parameter.
When you specify
the OutSize parameter as 0, the subroutine calculates
the size of an output buffer to be large enough to contain the transformed
text. The result is returned in this field. The content of the buffers specified
by the InpBuf and OutBuf parameters,
and a value of the InpSize parameter remains unchanged. |
|
InpToOut |
Represents an array of values with the same number of code elements
as the InpBuf parameter if InpToOut parameter is not a null pointer.
On output, the nth value in InpToOut parameter
corresponds to the nth code element in InpBuf parameter. This value is the index in OutBuf parameter which identifies the transformed ShapeCharset element of the nth code element in InpBuf parameter.
You can specify the InpToOut parameter as null if
no index array from the InpBuf to OutBuf parameters is desired. |
|
OutTolnp |
Represents an array of values with the same number of code elements
as contained in the OutBuf parameter if the OutToInp parameter is not a null pointer.
On output,
the nth value in the OutTolnp parameter
corresponds to the nth ShapeCharset element in the OutBuf parameter. This value is the index in the InpBuf parameter which identifies the original code element
of the nth ShapeCharset element in the OutBuf parameter. You can specify the OutTolnp parameter
as NULL if no index array from the OutBuf to InpBuf parameters is desired. |
|
BidiLvl |
Represents an array of values with the same number of elements as
the source text if the BidiLvl parameter is not a
null pointer. The nth value in the BidiLvl parameter corresponds to the nth code
element in the InpBuf parameter. This value is the
level of this code element as determined by the bidirectional algorithm. You
can specify the BidiLvl parameter as null if a levels
array is not desired. |
Return Values
Upon successful completion, these subroutines return
a value of 0.
Error Codes
If these subroutines fail, they return the following
values:
|
LAYOUT_EILSEQ |
Transformation stopped due to an input code element that cannot be
shaped or is invalid. The InpSize parameter indicates
the number of the code element successfully transformed.
Note
You can use this error code to determine the code element causing the error.
This 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 code set of the locale of the LayoutObject structure. You can use the mbtowc and wctomb subroutines to determine if the
code element is valid when used in the same locale as the LayoutObject structure. |
|
LAYOUT_E2BIG |
The output buffer is full and the source text is not entirely processed. |
|
LAYOUT_EINVAL |
Transformation stopped due to an incomplete code element or shift
sequence at the end of the input buffer. The InpSize parameter
indicates the number of the code elements successfully transformed.
Note
You can use this error code to determine the code element causing
the error. |
|
LAYOUT_ERANGE |
More than 15 embedding levels are in the source text or the InpBuf parameter contains unbalanced Directional Format (Push/Pop).
When the size of OutBuf parameter
is not large enough to contain the entire transformed text, the input text
state at the end of the LAYOUT_E2BIG error code is returned.
To resume the transformation on the remaining text, the application calls
the layout_object_transform subroutine with the same LayoutObject structure, the same InpBuf parameter, and InpSize parameter set to 0. |
Examples
The following is an example of transformation of both
directional re-ordering and shaping.
Notes:
- Uppercase represent left-to-right characters; lowercase represent right-to-left
characters.
- xyz represent
the shapes of cde.
Position: 0123456789
InpBuf: AB cde 12Z
Position: 0123456789
OutBuf: AB 12 zyxZ
Position: 0123456789
ToTarget: 0128765349
Position: 0123456789
ToSource: 0127865439
Position: 0123456789
BidiLevel: 0001111220
Related Information
The layout_object_create Subroutine, layout_object_editshape or wcslayout_object_editshape Subroutine, layout_object_free Subroutine, layout_object_getvalue Subroutine, layout_object_setvalue Subroutine,
and layout_object_shapeboxchars Subroutine.
Bidirectionality and Character
Shaping and National Language Support Overview in AIX 5L Version 5.2 National Language Support Guide and Reference.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]