layout_object_editshape or wcslayout_object

Base Operating System and Extensions Technical Reference, Volume 1

layout_object_editshape or wcslayout_object_editshape Subroutine

Purpose

Edits the shape of the context text.

Library

Layout library (libi18n.a)

Syntax

#include <sys/lc_layout.h>

int layout_editshape (layout_object, EditType, index, InpBuf, Inpsize, OutBuf, OutSize)
LayoutObject layout_object;
BooleanValue EditType;
size_t *index;
const char *InpBuf;
size_t *Inpsize;
void *OutBuf;
size_t *OutSize;

int wcslayout_object_editshape(layout_object, EditType, index, InpBuf, Inpsize, OutBuf, OutSize)
LayoutObject layout_object;
BooleanValue EditType;
size_t *index; 
const wchar t *InpBuf;
size_t *InpSize; 
void *OutBuf;
size_t *OutSize;

Description

The layout_object_editshape and wcslayout_object_editshape subroutines provide the shapes of the context text. The shapes are defined by the code element specified by the index parameter and any surrounding code elements specified by the ShapeContextSize layout value of the LayoutObject structure. The layout_object parameter specifies this LayoutObject structure.

Use the layout_object_editshape subroutine when editing code elements of one byte. Use the wcslayout_object_editshape subroutine when editing single code elements of multibytes. These subroutines do not affect any state maintained by the layout_object_transform or wcslayout_object_transform subroutine.

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.
EditType	Specifies the type of edit shaping. When the EditType parameter stipulates the `EditInput` field, the subroutine reads the current code element defined by the index parameter and any preceding code elements defined by ShapeContextSize layout value of the LayoutObject structure. When the EditType parameter stipulates the `EditReplace` field, the subroutine reads the current code element defined by the index parameter and any surrounding code elements defined by ShapeContextSize layout value of the LayoutObject structure. Note: The editing direction defined by the Orientation and TEXT_VISUAL of the TypeOfText layout values of the LayoutObject structure determines which code elements are preceding and succeeding. When the ActiveShapeEditing layout value of the LayoutObject structure is set to True, the LayoutObject structure maintains the state of the `EditInput` field that may affect subsequent calls to these subroutines with the `EditInput` field defined by the EditType parameter. The state of the `EditInput` field of LayoutObject structure is not affected when the EditType parameter is set to the `EditReplace` field. To reset the state of the `EditInput` field to its initial state, call these subroutines with the InpBuf parameter set to NULL. The state of the `EditInput` field is not affected if errors occur within the subroutines.
index	Specifies an offset (in bytes) to the start of a code element in the InpBuf parameter on input. The InpBuf parameter provides the base text to be edited. In addition, the context of the surrounding code elements is considered where the minimum set of code elements needed for the specific context dependent script(s) is identified by the ShapeContextSize layout value. If the set of surrounding code elements defined by the index, InpBuf, and InpSize parameters is less than the size of front and back of the ShapeContextSize layout value, these subroutines assume there is no additional context available. The caller must provide the minimum context if it is available. The index parameter is in units associated with the type of the InpBuf parameter. On return, the index parameter is modified to indicate the offset to the first code element of the InpBuf parameter that required shaping. The number of code elements that required shaping is indicated on return by the InpSize parameter.
InpBuf	Specifies the source to be processed. A Null value with the `EditInput` field in the EditType parameter indicates a request to reset the state of the `EditInput` field to its initial state. Any portion of the InpBuf parameter indicates the necessity for redrawing or shaping.
InpSize	Specifies the number of code elements to be processed in units on input. These units are associated with the types for these 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 needed by the InpBuf parameter. A value of 0 when the value of the EditType parameter is the `EditInput` field indicates that the state of the `EditInput` field is reset to its initial state. If the OutBuf parameter is not NULL, the respective shaped code elements are written into the OutBuf parameter.
OutBuf	Contains the shaped output text. You can specify this parameter as a Null pointer to indicate that no transformed text is required. If Null, the subroutines return the index and InpSize parameters, which specify the amount of text required, to be redrawn. The encoding of the OutBuf parameter depends on the ShapeCharset layout value defined in layout_object parameter. If the ActiveShapeEditing layout value is set to False, the encoding of the OutBuf parameter is to be the same as the code set of the locale associated with the specified LayoutObject structure.
OutSize	Specifies the size of the output buffer on input in number of bytes. Only the code elements required to be shaped are written into the OutBuf parameter. The output buffer should be large enough to contain the shaped result; otherwise, only partial shaping 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 in the InpBuf parameter multiplied by the value of the ShapeCharsetSize layout value. On return, the OutSize parameter is modified to the actual number of bytes placed in the output buffer. When the OutSize parameter is specified as 0, the subroutines calculate the size of an output buffer large enough to contain the transformed text from the input buffer. The result will be returned in this field. The content of the buffers specifies by the InpBuf and OutBuf parameters, and the value of the InpSize parameter, remain unchanged.

Return Values

Upon successful completion, these subroutines return a value of 0. The index and InpSize parameters return the minimum set of code elements required to be redrawn.

Error Codes

If these subroutines fail, they return the following error codes:

LAYOUT_EILSEQ	Shaping stopped due to an input code element that cannot be shaped. The index parameter indicates the code element that caused the error. This code element is either a valid code element that cannot be shaped according to the ShapeCharset layout value or an invalid code element not defined by the code set defined in the LayoutObject structure. Use the mbtowc or wctomb subroutine in the same locale as the LayoutObject structure to determine if the code element is valid.
LAYOUT_E2BIG	The output buffer is too small and the source text was not processed. The index and InpSize parameters are not guaranteed on return.
LAYOUT_EINVAL	Shaping stopped due to an incomplete code element or shift sequence at the end of input buffer. The InpSize parameter indicates the number of code elements successfully transformed. Note: You can use this error code to determine the code element causing the error.
LAYOUT_ERANGE	Either the index parameter is outside the range as defined by the InpSize parameter, more than 15 embedding levels are in the source text, or the InpBuf parameter contains unbalanced Directional Format (Push/Pop).

Implementation Specifics

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

Related Information

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

Bidirectionality and Arabic 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.