[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, Volume 1
Transforms text according to the
current layout values of a LayoutObject structure.
Layout Library
(libi18n.a)
|
#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;
|
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.1 General Programming Concepts: Writing and
Debugging Programs
| 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.
|
Upon successful completion, these
subroutines return a value of 0.
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.
|
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
This subroutine is part of Base
Operating System (BOS) Runtime.
The
layout_object_create (layout_object_create Subroutine) subroutine,
layout_object_editshape (layout_object_editshape or wcslayout_object_editshape Subroutine) subroutine, layout_object_free (layout_object_free Subroutine) subroutine,
layout_object_getvalue (layout_object_getvalue Subroutine) subroutine, layout_object_setvalue (layout_object_setvalue Subroutine) subroutine,
layout_object_shapeboxchars (layout_object_shapeboxchars Subroutine) subroutine.
Bidirectionality
and Character Shaping Overview in AIX 5L Version 5.1 General
Programming Concepts: Writing and Debugging Programs.
National Language Support Overview for Programming in
AIX 5L Version 5.1 General Programming Concepts: Writing and
Debugging Programs.
[ Previous | Next | Table of Contents | Index |
Library Home |
Legal |
Search ]