IBidiSettings

The IBidiSettings class identifies information about the bidirectional national language support for a window or graphic context. You can create objects of this class to query and set the bidirectional attributes of a window or a graphic context. An IBidiSettings object identifies the bidirectional attributes of a window or graphic context at one point in time, and is not updated if the bidirectional attributes of the window or graphic context change. Changes you make to an IBidiSettings object are not reflected in the window until you call IBidiSettings::apply.

AIX Considerations

IBidiSettings does not support querying and setting the bidirectional attributes of a graphics port or graphic context. Additionally, you cannot change the bidirectional attributes of a window after it has been created.

Windows Considerations

IBidiSettings does not support querying and setting the bidirectional attributes of a graphics port or graphic context. Additionally, you can only control the settings of two bidirectional attributes of a window: the window layout and its text orientation.


IBidiSettings - Member Functions and Data by Group

Constructors & Destructor

You can construct, copy, assign, and delete objects of the IBidiSettings class. However, you can construct an IBidiSettings object only if the function IBidiSettings::isBidiSupported returns true.


[view class]
~IBidiSettings
public:
virtual ~IBidiSettings()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IBidiSettings


Overload 1
public:
IBidiSettings(const IGrafPort& port)

Use this constructor to query the bidirectional attributes of the graphics port.

Exception

IInvalidRequest IBidiSettings::isBidiSupported indicates that your application is not running in an environment that supports bidirectional languages.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


Overload 2
public:
IBidiSettings(const IWindow& window)

Use this constructor to query the bidirectional attributes of the specified window.

Exception

IInvalidRequest IBidiSettings::isBidiSupported indicates that your application is not running in an environment that supports bidirectional languages.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IBidiSettings(const IBidiSettings& settings)

Use this copy constructor to create an IBidiSettings object with the same values as the specified one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IBidiSettings(const IWindowHandle& windowHandle)

Use this constructor to query the bidirectional attributes of the specified window.

Exception

IInvalidRequest IBidiSettings::isBidiSupported indicates that your application is not running in an environment that supports bidirectional languages.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IBidiSettings(const IPresSpaceHandle& presSpace)

Use this constructor to query the bidirectional attributes of the specified presentation space.

Exception

IInvalidRequest IBidiSettings::isBidiSupported indicates that your application is not running in an environment that supports bidirectional languages.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


Overload 6
protected:
IBidiSettings()

The IBidiSettings class uses this default constructor to implement the applicationDefaults and setApplicationDefaults functions.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =
public:
IBidiSettings& operator =(const IBidiSettings& settings)

Use this assignment operator to initialize an IBidiSettings object using the values of the specified object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Application Support

These functions allow you to set and query the default bidirectional characteristics for the application. Open Class Library (or the operating system) uses these defaults to set the bidirectional attributes of a window when it creates it.

When Open Class Library (or the operating system) creates a window with either no parent window or the desktop window as its parent, it will apply the bidirectional attributes you set with this call to that window. For example, if you use the IFrameWindow class to create a primary or secondary frame window, that frame window will inherit the application bidirectional attributes.

A window with a parent other than the desktop window inherits the bidirectional attributes of its parent window.

Wrappering an existing window with an IWindow or IWindow-derived object will not cause Open Class Library to change the bidirectional attributes of the window.

After creating a window, you can change its bidirectional attributes using IBidiSettings::apply.

OS/2 Considerations

To give bidirectional attributes to a dialog that you load from a resource file, specify the BIDIPARAM keyword in the dialog template.

Windows Considerations

The bidirectional attributes for the application do not affect dialogs that you load from a resource file. To create a dialog with a right-to-left layout, specify the extended styles WS_EX_RIGHT and WS_EX_RTLREADING in the dialog template.


[view class]
applicationDefaults
public:
static IBidiSettings applicationDefaults()

Use this function to query the bidirectional attributes for the application.

Exception

IInvalidRequest IBidiSettings::isBidiSupported indicates that your application is not running in an environment that supports bidirectional languages.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The object returned by this function does not reflect the setting of any Motif bidirectional resources, such as XmNSymmetricSwap.

OS/2 Considerations

The object returned by this function reflects the setting of the OS/2 BIDIATTR environment variable and any prior calls to WinSetLangInfo that have set process-level attributes.

Windows Considerations

The default layout direction is left-to-right.


[view class]
setApplicationDefaults
public:
static void setApplicationDefaults( const IBidiSettings& applicationSettings )

Use this function to set the bidirectional attributes for the application.

The easiest way to pass an object to this function is to call IBidiSettings::applicationDefaults, and then modify the returned object by calling functions like IBidiSettings::setWindowLayout and setTextOrientation.

Exception

IInvalidRequest IBidiSettings::isBidiSupported indicates that your application is not running in an environment that supports bidirectional languages.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

By setting specific bidirectional attributes for the application, you override the setting of the corresponding Motif bidirectional resources, such as XmNtextMode or XmNnssMode.

You can maintain the use of Motif bidirectional resources by calling IBidiSettings::applicationDefaults to create an IBidiSettings object, then calling functions on the object to change only the attributes you want to control, before calling setApplicationDefaults. The attributes you do not change will continue to be determined through resources. For example, by calling IBidiSettings::setTextType, the XmNtextMode will not be used to define the bidirectional attributes of your windows.

OS/2 Considerations

Calling this function overrides the OS/2 BIDIATTR environment variable and any prior calls to WinSetLangInfo that have set process-level attributes.


Attributes

Use these members to query and set bidirectional attributes.


[view class]
disableSymmetricSwapping
public:
virtual IBidiSettings& disableSymmetricSwapping()

Disables the swapping of directional characters.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
disableWordByWordReordering
public:
virtual IBidiSettings& disableWordByWordReordering()

Disables word-by-word reordering.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
enableSymmetricSwapping
public:
virtual IBidiSettings& enableSymmetricSwapping( bool enable = true )

Enables the swapping of directional characters.

Directional characters are characters, such as parentheses, brackets, and braces. In left-to-right text, an "open" bracket is a left bracket, while for right-to-left text an "open" bracket is a right bracket.

When symmetric swapping is enabled, the system automatically swaps between the symmetrical characters if right-to-left text orientation is used.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
enableWordByWordReordering
public:
virtual IBidiSettings& enableWordByWordReordering( bool enable = true )

Enables word-by-word reordering.

When word-by-word reordering is enabled, each word is evaluated for text reordering. Text reordering includes the reversal of text for display and the swapping of directional characters when using right-to-left text orientation.

When word-by-word reordering is disabled, only the first word is evaluated for text reordering, and the entire text uses the result.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
isSymmetricSwappingEnabled
public:
bool isSymmetricSwappingEnabled() const

If symmetric swapping is enabled, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isWordByWordReorderingEnabled
public:
bool isWordByWordReorderingEnabled() const

If word-by-word reordering is enabled, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
numeralDisplay
public:
BidiNumeralType numeralDisplay() const

Returns the bidirectional attribute that specifies how numerals (digits) are processed for display.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setNumeralDisplay
public:
virtual IBidiSettings& setNumeralDisplay( BidiNumeralType numeralDisplay )

Sets the bidirectional attribute that specifies how numerals (digits) are processed for display.

Exception

IInvalidParameter You specified an uninitialized IBidiSettings::BidiNumeralType value.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
setTextOrientation
public:
virtual IBidiSettings& setTextOrientation( BidiTextOrientation textOrientation )

Sets the bidirectional attribute that specifies how bidirectional text is oriented for display.

Exception

IInvalidParameter You specified an uninitialized IBidiSettings::BidiTextOrientation value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Setting the text orientation to right-to-left effectively sets the window layout to right-to-left as well, because both attributes are represented by the same Motif resource. See IBidiSettings::asArgList for details.


[view class]
setTextShape
public:
virtual IBidiSettings& setTextShape( BidiTextShape textShape )

Sets the bidirectional attribute that specifies how Arabic text is processed for display and how new text typed by the user is stored.

Exception

IInvalidParameter You specified an uninitialized IBidiSettings::BidiTextShape value.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
setTextType
public:
virtual IBidiSettings& setTextType(BidiTextType textType)

Sets the bidirectional attribute that specifies how bidirectional text is detected and processed.

Exception

IInvalidParameter You specified an uninitialized IBidiSettings::BidiTextType value.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
setWindowLayout
public:
virtual IBidiSettings& setWindowLayout( BidiLayout windowLayout )

Sets the bidirectional attribute that specifies how objects in a window or dialog are positioned and justified.

Exception

IInvalidParameter You specified an uninitialized IBidiSettings::BidiLayout value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Setting the window layout to right-to-left effectively sets the text orientatation to right-to-left as well, because both attributes are represented by the same Motif resource. See IBidiSettings::asArgList for details.


[view class]
textOrientation
public:
BidiTextOrientation textOrientation() const

Returns the bidirectional attribute that specifies how bidirectional text is oriented for display.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
textShape
public:
BidiTextShape textShape() const

Returns the bidirectional attribute that specifies how Arabic text is processed for display and how new text typed by the user is stored.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
textType
public:
BidiTextType textType() const

Returns the bidirectional attribute that specifies how bidirectional text is detected and processed for display.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
windowLayout
public:
BidiLayout windowLayout() const

Returns the bidirectional attribute that specifies how objects in the window or dialog are positioned and justified.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Bidirectional Support

Use these members to query bidirectional support and set bidirectional attributes for a window or graphic context.

Reading and writing of Arabic or Hebrew text is done from right to left. Thus, the starting point of an Arabic or Hebrew text is on the right side of the page or screen while the ending of the text is on the left. Arabic and Hebrew text can also contain embedded text that is written and read from left to right (such as numbers or embedded Latin text). Having left-to-right text embedded in right-to-left text is the reason we refer to Arabic and Hebrew languages as bidirectional languages.

Applications that are developed for Arabic and Hebrew languages must accommodate bidirectional data. Bidirectional attributes query and set information about how text is stored and displayed on Arabic or Hebrew systems.


[view class]
apply

Changes the bidirectional attributes.


Overload 1
public:
virtual void apply(const IPresSpaceHandle& presSpace) const

Assigns the bidirectional attributes defined in the IBidiSettings object to the specified presentation space.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


Overload 2
public:
virtual void apply(IGrafPort& port) const

Assigns the bidirectional attributes defined in the IBidiSettings object to the specified graphics port.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


Overload 3
public:
virtual void apply( IWindow& window, bool childInherit = true, bool refresh = true ) const

Assigns the bidirectional attributes defined in the IBidiSettings object to the specified window. If childInherit is set to true, the bidirectional attributes of all child windows are also changed. If refresh is set to true, the window is invalidated. The window can then repaint itself to reflect its new bidirectional attributes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

Portability Considerations

Some windows may choose to ignore changes you make to their bidirectional attributes.

AIX Considerations

You cannot change the bidirectional attributes of a window after creating it.

OS/2 Considerations

This function calls IWindow::setBidiSettings.

Windows Considerations

If a child window does not have an IWindow object, this function will not propagate the changes to the child windows of the child window.

This function calls IWindow::setBidiSettings.


Overload 4
public:
virtual void apply( const IWindowHandle& windowHandle, bool childInherit = true, bool refresh = true ) const

Assigns the bidirectional attributes defined in the IBidiSettings object to the specified window. If childInherit is set to true, the bidirectional attributes of all child windows are also changed. If refresh is set to true, the window is invalidated. The window can then repaint itself to reflect its new bidirectional attributes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

Portability Considerations

Some windows may choose to ignore changes you make to their bidirectional attributes.

AIX Considerations

You cannot change the bidirectional attributes of a window after creating it.

OS/2 Considerations

If the window has an IWindow object, this function calls IWindow::setBidiSettings.

Windows Considerations

If you are changing the bidirectional attributes of a window that has no IWindow object, childInherit is ignored and no child windows are changed. Otherwise, if childInherit is true, this function propagates the new bidirectional attributes to all of the window's child windows. However, if a child window does not have an IWindow object, this function will not propagate the changes to the child windows of the child window.

If the window has an IWindow object, this function calls IWindow::setBidiSettings.


[view class]
isBidiSupported
public:
static bool isBidiSupported()

If the operating system supports querying and setting of bidirectional attributes, true is returned. Otherwise, false is returned.

You cannot construct an IBidiSettings object if this function returns false.

Exception

IAccessError An error occurred while querying system environment information.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparisons

These functions indicate if one object is equivalent to another.


[view class]
operator ==
public:
bool operator ==(const IBidiSettings& settings) const

This operator returns true if two IBidiSettings objects are equivalent. Otherwise it returns false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Conversions

These functions allow you to convert an IBidiSettings object into an a different type.


[view class]
asArgList
public:
IArgList asArgList() const

Returns the bidi attributes as a list of Motif resource names and values.

Supported Platforms

Windows OS/2 AIX
No No Yes

AIX Considerations

Both window layout and text orientation map to the XmStringDirection Motif resource. This function sets this resource to XmSTRING_DIRECTION_R_TO_L if either window layout or text orientation is right-to-left.

IWindow::create calls this function to build the argument list it uses to create a widget.


IBidiSettings - Enumerations


[view class]
BidiLayout
enum BidiLayout { layoutLeftToRight, 
                  layoutRightToLeft }

Use these enumerations to specify how objects within a window or dialog are positioned (layed out) and how objects are justified:

layoutLeftToRight
Objects within a window or dialog are positioned with the origin at the bottom-left of the window, and the default justification is on the left side of the object.
layoutRightToLeft
Objects within a window or dialog are positioned with the origin at the bottom-right of the window, and the default justification is on the right side of the object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
BidiNumeralType
enum BidiNumeralType { arabic, 
                       asStored, 
                       national, 
                       contextual }

Use these enumerations to specify how numerals (digits) are processed for display:

arabic
Only Arabic numerals are displayed.
asStored
Numerals are displayed in the order that they are stored in memory.
national
Only national (Hindi) numerals are displayed.
contextual
Numerals are displayed according to surrounding text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
BidiTextOrientation
enum BidiTextOrientation { textLeftToRight, 
                           textRightToLeft, 
                           textContextual }

Use these enumerations to specify how bidirectional text is oriented for display:

textLeftToRight
Text that has a BidiTextType of visual is displayed as it is stored (text starts at the left and ends at the right). Text that has a BidiTextType of implicit is displayed so that Latin text retains its order, while Arabic or Hebrew text is reordered (reversed) for display.
textRightToLeft
Text that has a BidiTextType of visual is displayed in the reverse order from how it is stored (text starts at the right and ends at the left). Text that has a BidiTextType of implicit is displayed so that Arabic or Hebrew text retains its order, while Latin text is reordered (reversed) for display.
textContextual
The orientation of the text for display is determined by the first strong (nonneutral) character in the text. If the first character is an English character, the orientation is left to right. If the first character is an Arabic or Hebrew character, the orientation is right to left. If the first character is a neutral character (such as a space or punctuation mark), then the orientation is determined by the next character in the storage buffer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
BidiTextShape
enum BidiTextShape { displayShaped, 
                     saveShaped, 
                     nominalShape, 
                     initialShape, 
                     middleShape, 
                     finalShape, 
                     isolatedShape }

Use these enumerations to specify how Arabic text is processed for display and how new text typed by the user is stored.

displayShaped
Text is stored in nominal shapes (one codepoint per letter) and is shaped upon display. New text typed by the user is stored in nominal shapes (one codepoint per letter).
saveShaped
Text is already shaped and is not shaped upon display. New text typed by the user is shaped by the control before being stored or displayed. This mode is valid only when the BidiTextType is visual.
nominalShape
Text is stored in nominal shapes (one codepoint per letter) and is not shaped upon display. New text typed by the user is stored in nominal shapes. This mode is not commonly used and is supported to be compatible with a "shaping-off" state used on host platforms.
initialShape
Text is already shaped and is not shaped upon display. New text typed by the user is shaped as if it came at the beginning of a word before being stored or displayed. This mode is valid only when the BidiTextType is visual.
middleShape
Text is already shaped and is not shaped upon display. New text typed by the user is shaped as if it came in the middle of a word before being stored or displayed. This mode is valid only when the BidiTextType is visual.
finalShape
Text is already shaped and is not shaped upon display. New text typed by the user is shaped as if it came at the end of a word before being stored or displayed. This mode is valid only when the BidiTextType is visual.
isolatedShape
Text is already shaped and is not shaped upon display. New text typed by the user is shaped as if isolated (a single character word) before being stored or displayed. This mode is valid only when the BidiTextType is visual.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
BidiTextType
enum BidiTextType { visual, 
                    implicit }

Use these enumerations to specify how bidirectional text is detected and processed:

visual
The whole text has the same direction. Whether it is left-to-right or right-to-left is determined by the text orientation attribute. Whether the text contains digits, English, Arabic, or Hebrew characters does not change the sequence of characters within the given text.
implicit
The determination of text direction is based on the actual sequence of characters in the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IBidiSettings - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data