[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, 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 Version 4.3 General Programming Concepts: Writing and Debugging Programs

Parameters

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:
  1. Uppercase represent left-to-right characters; lowercase represent right-to-left characters.

  1. 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

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The layout_object_create subroutine, layout_object_editshape subroutine, layout_object_free subroutine, layout_object_getvalue subroutine, layout_object_setvalue subroutine, layout_object_shapeboxchars subroutine.

Bidirectionality and Character Shaping Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

National Language Support Overview for Programming in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]