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:
| Item | Description |
|---|---|
| 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.
| Item | Description |
|---|---|
| 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:
| Item | Description |
|---|---|
| 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.
Position: 0123456789
InpBuf: AB cde 12Z
Position: 0123456789
OutBuf: AB 12 zyxZ
Position: 0123456789
ToTarget: 0128765349
Position: 0123456789
ToSource: 0127865439
Position: 0123456789
BidiLevel: 0001111220