layout_object_transform 或 wcslayout_object_transform 子例程
用途
根据 LayoutObject 结构的当前布局值变换文本。
库
布局库 (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;描述
layout_object_transform 和 wcslayout_object_transform 子例程根据 LayoutObject 结构中的当前布局值来变换由 InpBuf 参数指定的文本。 任何类型为LayoutTextDescriptor的布局值都会描述 InpBuf和OutBuf参数中的属性。 如果属性与 InpBuf 和 OutBuf 参数本身相同，那么将针对该特定布局值执行空变换。
这些子例程的输出可能是下列其中一个或多个结果，具体取决于各自参数的设置:
| 项 | 描述 |
|---|---|
| OutBuf、OutSize | 任何转换后的数据都存储在 OutBuf 参数中。 |
| InpToOut | 从 InpBuf 参数的每个代码元素到转换后的数据的交叉引用。 |
| OutToInp | 对转换后数据中 InpBuf 参数的每个代码元素的交叉引用。 |
| BidiLvl | 表示 InpBuf 参数的每个代码元素的方向级别的加权值。 级别取决于 LayoutObject 结构的内部方向算法。 |
您可以将这些输出参数中的每个参数指定为 Null ，以指示特定参数不需要任何输出。 但是，您应该至少将其中一个参数设置为 nonNULL 值以执行任何重要工作。
要对文本字符串进行整形而不对代码元素重新排序，可将 "TypeOfText布局值设置为 "文字视觉，并将 "方向 "布局值的 "入 "和 "出 "值设置为相同的值。 这些布局值位于 LayoutObject 结构中。
参数
| 项 | 描述 |
|---|---|
| layout_object | 指定由 layout_object_create 子例程创建的 LayoutObject 结构。 |
| InpBuf | 指定要处理的源文本。 此参数不能为空。 |
| InpSize | 指定与 layout_object_transform 和 wcslayout_object_transform 子例程的字节相关联的已处理代码元素的单位。 如果值为-1，则表示输入以空码元素分隔。 返回时，该值将被修改为InBuf参数中已处理的代码元素的实际数量。 但是，如果OutSize参数的值为零，则InpSize参数的值不会改变。 |
| OutBuf | 包含已转换的数据。 您可以将此参数指定为空指针，以指示不需要变换数据。 OutBuf 参数的编码取决于 LayoutObject 结构中定义的 ShapeCharset 布局值。 如果ActiveShapeEditing布局值设置为 True，则OutBuf参数的编码与LayoutObject结构相关联的本地编码集相同。 |
| OutSize | 指定输出缓冲区的大小 (以字节为单位)。 输出缓冲区应该足够大，以包含转换后的结果; 否则，只执行部分转换。 如果ActiveShapeEditing布局值设置为 True，则应分配OutBuf参数，使其至少包含ShapeCharsetSize布局值乘以代码元素数。 返回时，会将 OutSize 参数修改为该参数中放置的实际字节数。 当您将 OutSize 参数指定为 0 时，子例程会将输出缓冲区的大小计算为足以包含转换后的文本。 结果将在此字段中返回。 由 InpBuf 和 OutBuf 参数指定的缓冲区的内容以及 InpSize 参数的值保持不变。 |
| InpToOut | 如果InpToOut参数不是空指针，则代表一个数值数组，其代码元素数目与InpBuf参数相同。 输出时，InpToOut参数中的第 n 个值与InpBuf参数中的第 n 个代码元素相对应。 此值是 OutBuf 参数中的索引，用于标识 InpBuf 参数中 nth 代码元素的已变换 ShapeCharset 元素。 You can specify the InpToOut parameter as null if no index array from the InpBuf to OutBuf parameters is desired. |
| OutTolnp | 如果OutToInp参数不是空指针，则代表与OutBuf参数中所含代码元素数目相同的数值数组。 在输出时， OutTolnp 参数中的 n值对应于 OutBuf 参数中的 nth ShapeCharset 元素。 此值是 InpBuf 参数中的索引，用于标识 OutBuf 参数中 nth ShapeCharset 元素的原始代码元素。 如果不需要从 OutBuf 到 InpBuf 参数的索引数组，那么可以将 OutTolnp 参数指定为 NULL。 |
| BidiLvl | 如果 BidiLvl 参数不是空指针，那么表示具有与源文本相同的元素数量的值的数组。 BidiLvl 参数中的 n值对应于 InpBuf 参数中的 n代码元素。 此值是此代码元素的级别 (由双向算法确定)。 如果不需要级别数组，那么可以将 BidiLvl 参数指定为空。 |
返回值
成功完成后，这些子例程将返回值 0。
错误代码
如果这些子例程失败，那么它们将返回以下值:
| 项 | 描述 |
|---|---|
| LAYOUT_EILSEQ | 由于输入代码元素无法形成或无效，因此变换已停止。 InpSize 参数指示已成功变换的代码元素的编号。 注: 您可以使用此错误代码来确定导致错误的代码元素。
此代码元素是有效的代码元素，但不能形成 ShapeCharset 布局值，或者是 LayoutObject 结构的语言环境的代码集未定义的无效代码元素。 您可以使用 mbTowc 和 wctomb 子例程来确定在与 LayoutObject 结构相同的语言环境中使用时代码元素是否有效。 |
| LAYOUT_E2BIG | 输出缓冲区已满，且未完全处理源文本。 |
| LAYOUT_EINVAL | 由于输入缓冲区末尾的代码元素或移位序列不完整，因此变换已停止。 InpSize 参数指示成功变换的代码元素数。 注: 您可以使用此错误代码来确定导致错误的代码元素。
|
| LAYOUT_ERANGE | 源文本中包含超过 15 个嵌入级别，或者 InpBuf 参数包含不平衡的方向格式 (Push/Pop)。 当 OutBuf 参数的大小不足以包含整个转换后的文本时，将返回 LAYOUT_E2BIG 错误代码末尾的输入文本状态。 要恢复对剩余文本的变换，应用程序将使用相同的 LayoutObject 结构，相同的 InpBuf 参数和设置为 0 的 InpSize 参数来调用 layout_object_transform 子例程。 |
示例
以下是两个方向重新排序和整形的变换示例。
- 大写表示从左到右的字符; 小写表示从右到左的字符。
- xyz表示形状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