test

International Language Environments Guide

Changes in Motif to Support CTL Technology

The following changes to Motif support the CTL technology:

XmNlayoutDirection

Controls object layout

XmStringDirection

Specifies the direction in which the system displays characters of a string

XmRendition

Adds new pseudo resources to XmRendition

XmText and XmTextField

Affects the layout behavior of the text associated with the XmRendition

XmTextFieldGetLayoutModifier

Returns the layout modifier string of a rendition layout object

XmTextGetLayoutModifier

Returns the value of the current layout object settings of the rendition associated with the widget

XmTextFieldSetLayoutModifier

Sets the layout modifier values for the layout object tied to its rendition

XmTextSetLayoutModifier

Modifies the layout object settings of a rendition associated with the widget

XmStringDirectionCreate

Creates a compound string

XmNlayoutDirection Resource

The XmNlayoutDirection resource controls object layout. This resource interacts with the orientation value of the LayoutObject in the manner described below.

See section 11.3 of the Motif Programmer's Guide (Release 2.1) for an overview of XmNlayoutDirection, and especially for a description of the interaction between XmStringDirection and XmNlayoutDirection.

Determining the Layout Direction

When the XmNlayoutDirection is specified as XmDEFAULT_DIRECTION, the layout direction of the widget is set at creation time from the governing pseudo-XOC. In the case of dynamic text (XmText and XmTextField), the governing pseudo-XOC is the one that is associated with the XmRendition used for the widget. In the case of static text (XmList, XmLabel, XmLabelG), the layout direction is set from the first compound string component that specifies a direction. This specification happens in one of two ways:

When XmNlayoutDirection is not specified as XmDEFAULT_DIRECTION and the XmNlayoutModifier @ls orientation value is not specified explicitly in the layout modifier string, then the XmNlayoutDirection value is passed through to the XOC and its LayoutObject.

If both XmNlayoutDirection and the XmNlayoutModifier @ls orientation value are explicitly specified, then the behavior is mixed. The XmNlayoutDirection controls widget object layout, and the XmNlayoutModifier @ls orientation value controls layout transformations.

See CAE Specification: Portable Layout Services: Context-dependent and Directional Text (The Open Group: Feb 1997; ISBN 1-85912-142-X; document number C616) for a description of portable functions for handling context-dependent and bidirectional text transformations as a logical extension to the existing POSIX locale model. The document is intended for system and application programmers who want to provide support for complex-text languages.

XmStringDirection Resource

XmStringDirection is the data type used to specify the direction in which the system displays characters of a string.

The XmNlayoutDirection resource sets a default rendering direction for any compound string (XmString) that does not have a component specifying the direction of that string. Therefore, to set the layout direction, you need to set the appropriate value for the XmNlayoutDirection resource. You do not need to create compound strings with specific direction components. When the application renders an XmString, the application should check whether the string was created with an explicit direction (XmStringDirection). If the string does not provide a direction component, the application should check the value of the XmNlayoutDirection resource for the current widget and use that value as the default rendering direction for the XmString.

XmRendition Resource

CTL adds the new pseudo resources listed in the following table to XmRendition. Descriptions of the pseudo resources follow the table.

Table 6–1 New Resources in XmRendition

Name 

Class/Type 

Access 

Default Value 

XmNfontType

XmCFontType/XmFontType

CSG 

XmAS_IS

XmNlayoutAttrObject

XmClayoutAttrObject/String

CG 

NULL

XmNlayoutModifier

XmClayoutModifier/String

CSG 

NULL

XmNfontType

Specifies the type of the Rendition font object. For CTL, the value of this resource must be the XmFONT_IS_XOC value. If the value does not match, then the XmNlayoutAttrObject and XmNlayoutModifier resources are ignored.

When the value of this resource is XmFont_IS_XOC and the XmNfont resource is not specified, then at create time the value of the XmNfontName resource is converted into an XOC object in either the locale specified by the XmNlayoutAttrObject resource or the current locale. Furthermore, the value of the XmNlayoutModifier resource is passed through to any layout object associated with the XOC.

XmNlayoutAttrObject

Specifies the layout AttrObject argument. This resource is used to create the layout object associated with the XOC associated with this XmRendition. Refer to the layout services m_create_layout() specification for the syntax and semantics of this string. See the description of XmNfontType for an explanation of the interaction between the Layout Modifier Orientation output value and the XmNlayoutDirection widget resource.

XmNlayoutModifier

Specifies the layout values to be passed through to the layout object used with the XOC for this XmRendition. For the syntax and semantics of this string, see CAE Specification.

Setting this resource using XmRendition{Retrieve,Update} causes the string to be passed through to the layout object associated with the XOC associated with this rendition. This mechanism enables you to configure layout services dynamically. Unpredictable behavior can result if the Orientation, Context, TypeOfText, TextShaping, or ShapeCharset are changed.

Additional Layout Behavior

The XmNlayoutModifier affects the layout behavior of the text associated with the XmRendition. For example, if the layout default treatment of numerals is NUMERALS_NOMINAL, you change to NUMERALS_NATIONAL by setting XmNlayoutModifier to @ls numerals=nominal:national, or @ls numerals=:national.

The layout values can be classified into the following groups:

XmText and XmTextField Resource

Xm CTL extends XmText and XmTextField by adding a parallel set of movement and deletion actions that operate visually, patterned after the Motif 2.0 CSText widget. The standard Motif 2.1 Text and TextField do not distinguish between logical and physical order: next and forward mean “to the right,” while previous and backward mean “to the left.” CSText, however, makes the proper distinction and defines a new set of actions with strictly physical names (for example, left-character(), delete-right-word(), and so on). These action routines are defined to be sensitive to the XmNlayoutDirection of the widget and to call the appropriate next- or previous- action.

The Xm CTL extensions are slightly more complex than the CSText extensions. The Xm CTL extensions are sensitive not to the global orientation of the widget, but to the specific directionality of the physical characters surrounding the cursor, as determined by the pseudo-XOC, including neutral stabilization.

The new resource name enables you to control selection policy, to provide a rendition tag, and to control alignment.

The set of new Xm CTL actions is roughly the cross product of {Move,Delete,Kill} by {Left,Right} by {Character,Word}. The action set is listed in the following table.

Table 6–2 New Resources in Xm CTL

Name 

Class/Type 

Access 

Default Value 

XmNrenditionTag

XmCRenditionTag/XmRString

CSG 

XmFONTLIST_DEFAULT_TAG

XmNalignment

XmCAlignment/XmRAlignment

CSG 

XmALIGNMENT_BEGINNING

XmNeditPolicy

XmCEditPolicy/XmREditPolicy

CSG 

XmEDIT_LOGICAL

XmNrenditionTag

Specifies the rendition tag of the XmRendition that is in the XmNrenderTable resource, used for a widget.

XmNalignment

Specifies the text alignment used in the widget. Only XmALIGNMENT_END and XmALIGNMENT_CENTER are supported.

XmNeditPolicy

Specifies the editing policy used for the widget, either XmEDIT_LOGICAL or XmEDIT_VISUAL. In the case of XmEDIT_VISUAL, selection, cursor movement, and deletion are in a visual style. Setting this resource also changes the translations for the standard keyboard movement and deletion events either to the new “visual” actions list or to the existing logical actions.

Character Orientation Action Routines

The forward-cell() and backward-cell() actions query the orientation of the character in the direction specified. If the direction is left-to-right, these actions call the corresponding next-/forward- or previous-/backward- variants.

Character Orientation Additional Behavior

The actions determine the orientation of characters by using the Layout Services transformation OutToInp and Property buffers for the nesting level. The widget's behavior is therefore dependent on the locale-specific transformation. If the information in the OutToInp or, especially, Property buffers is inaccurate, the widget might behave unexpectedly. Moreover, as the locale-specific modules fall outside of the scope of this specification, bidirectional editing behavior can differ from platform to platform for the same text, application, resource values, and LayoutObject configuration.

The visual mode actions result in a display of cell-based behavior. The logical mode actions result in logical character-based behavior. For example, the delete-right-character() operation deletes the input buffer characters that correspond to the display cell. That is, one input buffer character whole LayoutObject transformation “property” byte “new cell indicator” is 1, and all succeeding characters whose “new cell indicator” is 0.

For more information on the Property buffer, see the specification for m_transform_layout() in CAE Specification.

Similarly, for backward-character(), the insertion point is moved backward one character in the input buffer, and the cursor is redrawn at the visual location corresponding to the associated output buffer character. Therefore, several keystrokes are required to move across a composite display cell. The cursor does not actually change display location as the insertion point moves across input buffer characters such as diacritics or ligature fragments whose “new cell indicator” is 0.

This behavior means that deletion operates either from the logical/input buffer side, or from the display cell level of the physical/output side. No mode exists for a strict, physical character-by-character deletion because no one-to-one correspondence exists between the input and output buffers. A given physical character can represent only a fragment of a logical character, for example.

XmText Action Routines

The following list describes the XmText action routines.

left-character(extend)

If the XmNeditPolicy is XmEDIT_LOGICAL and it is called without arguments, the insertion cursor moves back logically by a character. If the insertion cursor is at the beginning of the line, the insertion cursor moves to the logical last character of the previous line, if one exists. Otherwise, the insertion cursor position doesn't change.

If the XmNeditPolicy is XmEDIT_VISUAL, then the cursor moves to the left of the cursor position. If the insertion cursor is at the beginning of the line, then it moves to the end character of the previous line, if one exists.

If left-character() is called with an extend argument, the insertion cursor moves as in the case of no argument, and extends the current selection.

The left-character() action produces calls to the XmNmotionVerifyCallback procedures with the reason value XmCR_MOVING_INSERT_CURSOR. If called with an extend argument, this action can produce calls to the XmNgainPrimaryCallback procedures. See the callback description in the Motif Programmer's Reference for more information.

right-character(extend)

If the XmNeditPolicy is XmEDIT_LOGICAL and it is called without any arguments, the insertion cursor moves logically forward by a character. If the insertion cursor is at the logical end of the line, this action moves the insertion cursor to the logical start of the next line, if one exists.

If the XmNeditPolicy is XmEDIT_VISUAL, then the cursor moves to the right of the cursor position. If the insertion cursor is at the end of the line, it moves the insertion cursor to the starting of the next line, if one exists.

If called with an argument of extend, XmNeditPolicy moves the insertion cursor as in the case of no argument, and extends the current selection.

The right-character() action produces calls to the XmNmotionVerifyCallback procedures with the reason value XmCR_MOVING_INSERT_CURSOR. If called with extend argument, this action can produce calls to the XmNgainPrimaryCallback procedures. See the callback description in the Motif Programmer's Reference for more information.

right-word(extend)

If the XmNeditPolicy is XmEDIT_LOGICAL and it is called without any arguments, the insertion cursor moves to the logical starting character of the logical succeeding word, if one exists. Otherwise, the cursor moves to the logical end of the current word. If the insertion cursor is at the logical end of the line or in the logical last word of the line, the cursor moves to the logical first word in the next line, if one exists. Otherwise, the cursor moves to the logical end of the current word.

If the XmNeditPolicy is XmEDIT_VISUAL and it is called without arguments, the insertion cursor moves to the first non whitespace character after the first white space character to the right or after the end of the line.

If called with an argument of extend, the insertion cursor moves as in the case of no argument and extends the current selection.

The left-word() action produces calls to the XmNmotionVerifyCallback procedures with the reason value XmCR_MOVING_INSERT_CURSOR. If called with extend argument, this action can produce calls to the XmNgainPrimaryCallback procedures. See the callback description in the Motif Programmer's Reference for more information.

delete-left-character()

If the XmNeditPolicy is XmEDIT_LOGICAL, it is equivalent to delete-previous-char(). If the XmNeditPolicy is XmEDIT_VISUAL, then in normal mode, if the selection is non-null, it deletes the selection. Otherwise this action deletes the character to the left of the insertion cursor. In add mode, if the selection is non-null, the cursor is not disjointed from the selection, and XmNpendingDelete is set to True, this action deletes the selection. Otherwise, the action deletes the character to the left of the insertion cursor, which can affect the selection.

The delete-left-character() action produces calls to the XmNmodifyVerifyCallback procedures with the reason value XmCR_MODIFYING_TEXT_VALUE and the XmNvalueChangedCallback procedures with the reason value XmCR_VALUE_CHANGED.

delete-right-character()

If the XmNeditPolicy is XmEDIT_VISUAL, it is equivalent to delete-next-character(). If the XmNeditPolicy is XmEDIT_VISUAL, then in normal mode, if the selection is a non-null, it deletes the selection. Otherwise, it deletes the character to the right of the insertion cursor. In add mode, if there is a non-null selection and the cursor is not disjointed from the selection, the XmNpendingDelete is set to True and the selection is deleted. Otherwise, the character to the right of the insertion cursor is deleted. This action can affect the selection.

The delete-right-character() action produces calls to the XmNmodifyVerify-Callback procedures with reason value XmCR_MODIFYING_TEXT_VALUE, and the XmNvalue-ChangedCallback procedures with reason value XmCR_VALUE_CHANGED.

A few cell-based routines are implemented to support character composition, ligatures, and diacritics. In other words, two or more characters might be represented by a single glyph occupying one presentation cell.

The XmText cell action routines are as described in the following list.

backward-cell(extend)

Moves the insertion cursor back one cell. If the XmNeditPolicy is XmEDIT_LOGICAL, then the insertion cursor is moved to the start of the cell that precedes the current cell logically, if one exists. Otherwise, the cursor moves to the start of the current cell.

If the XmNeditPolicy is XmEDIT_VISUAL, then the cursor moves to the start of cell to the left of the cursor, if one exists. The prev-cell() action produces calls to the XmNmotionVerifyCallback procedures with the reason value XmCR_MOVING_INSERT_CURSOR. If called with an extend argument, this action can produce calls to the XmNgainPrimaryCallback procedures. See the callback description in the Motif Programmer's Reference for more information.

forward-cell(extend)

Moves the insertion cursor to the start of the logical next cell, if one exists. Otherwise this action moves the cursor to the end of the cell. If the XmNeditPolicy is XmEDIT_LOGICAL, then the cursor moves forward one cell.

If the XmNeditPolicy is XmEDIT_VISUAL, then the cursor moves to the start of the cell to the right of the cursor position, if one exists; otherwise, it moves to the end of the current cell. The forward-cell() action produces calls to the XmNmotionVerifyCallback procedures with the reason value XmCR_MOVING_INSERT_CURSOR. If called with an extend argument, this action can produce calls to the XmNgainPrimaryCallback procedures. See the callback description in the Motif Programmer's Reference for more information.

XmTextFieldGetLayoutModifier Resource

XmTextFieldGetLayoutModifier() returns the layout modifier string that reflects the state of the layout object tied to its rendition.

The syntax for XmTextFieldGetLayoutModifier() is:

#include <Xm/TextF.h>string XmTextFieldGetLayoutModifier(Widget widget)

XmTextFieldGetLayoutModifier() accesses the value of the current layout object settings of the rendition associated with the widget. When the layout object modifier values are changed using a convenience function, the XmTextFieldGetLayoutModifier function returns the complete state of the layout object, not the changed values only.

XmTextFieldGetLayoutModifier() returns the layout object modifier values in the form of a string value.

XmTextGetLayoutModifier Resource

XmTextGetLayoutModifier() returns the layout modifier string that reflects the state of the layout object tied to its rendition.

The syntax for XmTextGetLayoutModifier() is:

#include <Xm/Text.h>String XmTextGetLayoutModifier(Widget widget)

XmTextGetLayoutModifier accesses the value of the current layout object settings of the rendition associated with the widget. When the layout object modifier values are changed using a convenience function, the XmTextGetLayoutModifier function returns the complete state of the layout object, not just the changed values.

XmTextGetLayoutModifier returns the layout object modifier values in the form of a string value.

XmTextFieldSetLayoutModifier Resource

XmTextFieldSetLayoutModifier() sets the layout modifier values, which changes the behavior of the layout object tied to its rendition.

The syntax for XmTextFieldSetLayoutModifier() is:

#include <Xm/TextF.h> \
void XmTextFieldSetLayoutModifier(Widget \
widgetstring layout_modifier)

XmTextFieldSetLayoutModifier modifies the layout object settings of a rendition associated with the widget. When the layout object modifier values are set using this convenience function, only the attributes specified in the input parameter are changed. The rest of the attributes remain untouched.

XmTextSetLayoutModifier Resource

XmTextSetLayoutModifier() sets the layout modifier values, which changes the behavior of the layout object tied to its rendition.

The syntax for XmTextSetLayoutModifier() is:

#include <Xm/Text.h>void XmTextSetLayoutModifier(Widget widget,string layout_modifier)

XmTextSetLayoutModifier modifies the layout object settings of a rendition associated with the widget. When the layout object modifier values are set using this convenience function, only the attributes specified in the input parameter are changed; the rest of the attributes are left untouched.

XmStringDirectionCreate Resource

XmStringDirectionCreate creates a compound string.

The syntax for XmTextSetLayoutModifier() is:

#include <Xm/Xm.h>XmString XmStringDirectionCreate(direction)XmStringDirection direction

XmStringDirectionCreate creates a compound string with a single component, a direction with the given value. On the other hand, the XmNlayoutDirection resource sets a default rendering direction for any compound string (XmString) that does not have a component specifying the direction for that string. Therefore, to set the layout direction, you set the appropriate value for the XmNlayoutDirection resource. You need not create compound strings with specific direction components.

When the application renders an XmString, the application should check whether the string was created with an explicit direction (XmStringDirection). If the application was provided no direction component, the application should check the value of the XmNlayoutDirection resource for the current widget and use that value as the default rendering direction for the XmString.