IMultiLineEdit

The IMultiLineEdit class creates and manages multiline edit (MLE) controls. This control is similar to an entry field, but it lets the user enter multiple lines of text rather than just one.

You derive classes from the following handlers and attach them to an MLE control:

The MLE control can enable screen refreshes during its member functions processing. In doing so, it negates any previous use of IMultiLineEdit::disableUpdate.
Note: Do not load text containing nulls or any other embedded nonprintable characters into an IMultiLineEdit object. Because the user cannot see these characters, the user is likely to type over or delete them.

Portability Considerations

The Motif XmText widget does not support embedded NULLs or embedded nonprintable characters. Only the text preceding the first NULL is loaded into the control.

For a portable application, do not load text containing embedded NULLs or nonprintable characters into an IMultiLineEdit object. Additionally, remember that end-of-line characters are different on different systems.

AIX Considerations

The Open Class Library implements this class with the XmText widget. The XmText widget does not support embedded NULLs or embedded nonprintable characters. Only the text preceding the first NULL is loaded into the control.

AIX only supports the noTran format enumerator. If you specify any other EOLFormat, the member functions ignore it and use noTran instead.

The Motif XmText widget does not support line-oriented functions; the Open Class Library has added this support. However, it does not make fine adjustments for a proportional font (to ensure good performance). This means that if a proportional font is used in the control, the number of a line on the screen might not match the calculated line number used internally by the line-oriented functions. Therefore, if you use a proportional font in the control, use character, position-oriented functions instead.

Line-oriented functions may not work if tab characters are used. Typically, Motif converts tabs as 10 blank characters, but if a line ends with a tab, it might cause an incorrect line count.

Handlers derived from IEditVerifyHandler can be attached to IMultiLineEdit objects.

OS/2 Considerations

When exporting a file with a format of cfText, a CR-LF sequence is counted as one character. However, importFromFile reads the file in binary so that the CR-LF is counted as two bytes. This makes the size of the imported files larger than the exported file. This can create a problem for very small MLEs. An exception is thrown indicating that the string being inserted into the MLE is larger than the set limit.

You should use the noTran format of the EOLFormat or derive customized import or export functions to handle this condition.


IMultiLineEdit - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IMultiLineEdit


Overload 1
public:
IMultiLineEdit(unsigned long id, IWindow* parent)

You can construct objects of this class by using the parent window.

id
An MLE control ID.
parent
The parent window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IMultiLineEdit(const IWindowHandle& handle)

You can construct objects of this class by using the handle of an existing MLE.

handle
The window handle of an existing MLE control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IMultiLineEdit( unsigned long id, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )

You can construct objects of this class by using the parent window, owner window, optional size and location, and optional style parameters.

id
An MLE control ID.
parent
The parent window.
owner
The owner window.
initial
A rectangle for the control. It specifies the initial position and size of the object you are constructing. Optional.
style
The initial style for the control. The default is classDefaultStyle. Optional.

Exception

IInvalidParameter The parent window pointer specified was invalid. You must specify a valid IWindow pointer as the parent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Change Operations

Use these members to track changes for the MLE.


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

If any changes have been made to the MLE since the last time the changed flag was reset, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetTextChangedFlag
public:
virtual IMultiLineEdit& resetTextChangedFlag()

Resets the changed flag so that from this point forward changes to the MLE can be detected. This is the same as IMultiLineEdit::setTextChangedFlag(false).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTextChangedFlag
public:
virtual IMultiLineEdit& setTextChangedFlag( bool changed = true )

Sets a flag indicating the changed status of the MLE. If changed=true, a flag is set to indicate the MLE contents have changed. if changed=false, a flag is set to indicate the MLE contents have not changed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Clipboard Operations

Use these members to transfer data between the clipboard and the multiline edit (MLE) control. Each of these operations deals with the selected text in the MLE control.

AIX Considerations

Motif-specific: the cut, copy, and clear operations allow the use of a timestamp to avoid race conditions. The optional parameter timestamp on these functions is provided to allow this timestamp to be provided when these functions are called from an event handler. The timestamp to use can be found in the time member of the XEvent structure. The default value is interpreted as "CurrentTime". This parameter is ignored on other platforms.


[view class]
clear
public:
virtual IMultiLineEdit& clear(unsigned long timestamp = 0)

Replaces the selected text in the MLE with blanks.

The user can select text or your code can call selectRange. The code can call hasSelectedText to determine if any text in the MLE is selected before making the call to clear.

To remove the text contents of the MLE, regardless of whether any text is selected, call setText, passing it a 0-length string, or removeAll.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The optional parameter timestamp allows a time stamp value to be passed when this function is called from an event handler. This parameter specifies the time at which the selection value is to be modified. This must be the time of the event that triggered the request. One source of a valid timestamp is the XtLastTimestampProcessed function.

In AIX, get the value for timestamp from the time member of the XEvent structure. The default value is interpreted as CurrentTime.

OS/2 Considerations

The OS/2 release does not use the timestamp parameter.


[view class]
copy
public:
virtual IMultiLineEdit& copy(unsigned long timestamp = 0)

Copies the currently selected text from the MLE to the clipboard.

The user can select text or your code can call selectRange. The code can call hasSelectedText to determine if any text in the MLE is selected before making the call to copy.

Exception

IInvalidRequest The MLE has no selected text.
IAccessError The operating system's request to copy from the MLE failed. See the exception text for further information about the failure.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The optional parameter timestamp allows a time stamp value to be passed when this function is called from an event handler. This parameter specifies the time at which the selection value is to be modified. This must be the time of the event that triggered the request. One source of a valid timestamp is the XtLastTimestampProcessed function.

In AIX, get the value for timestamp from the time member of the XEvent structure. The default value is interpreted as CurrentTime.

OS/2 Considerations

The OS/2 release does not use the timestamp parameter.


[view class]
cut
public:
virtual IMultiLineEdit& cut(unsigned long timestamp = 0)

Removes the currently selected text from the MLE control and places it in the clipboard.

The user can select text or your code can call selectRange. The code can call hasSelectedText to determine if any text in the MLE is selected before making the call to cut.

To remove the text contents of the MLE, regardless of whether any text is selected, call setText, passing it a 0-length string, or removeAll.

Exception

IInvalidRequest The MLE has no selected text.
IAccessError The operating system's request to cut from the MLE failed. See the exception text for further information about the failure.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The optional parameter timestamp allows a time stamp value to be passed when this function is called from an event handler. This parameter specifies the time at which the selection value is to be modified. This must be the time of the event that triggered the request. One source of a valid timestamp is the XtLastTimestampProcessed function.

In AIX, get the value for timestamp from the time member of the XEvent structure. The default value is interpreted as CurrentTime.

OS/2 Considerations

The OS/2 release does not use the timestamp parameter.

Windows Considerations

The CR-LF combination is not deleted if a request is made to delete one complete line from the MLE. This behavior results in a blank line in the MLE.


[view class]
discard
public:
virtual IMultiLineEdit& discard()

Deletes all currently selected text.

The user can select text or your code can call selectRange. The code can call hasSelectedText to determine if any text in the MLE is selected before making the call to discard.

To remove the text contents of the MLE, regardless of whether any text is selected, call setText, passing it a 0-length string, or removeAll.

Exception

IInvalidRequest The MLE has no selected text.
IAccessError The operating system's request to discard the selected text failed. See the exception text for further information about the failure.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
paste
public:
virtual IMultiLineEdit& paste()

Inserts the contents of the clipboard into the MLE at the cursor position, replacing any selected text.

The user can select text or your code can call selectRange. The code can call hasSelectedText to determine if any text in the MLE is selected before making the call to paste.

Exception

IInvalidRequest The clipboard does not contain any text.
IAccessError The operating system's request to paste to the MLE failed. See the exception text for further information about the failure.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support embedded NULLs. This function only loads the text up to the first NULL. AIX only supports the noTran format enumerator.


Colors

Use these members to query the current colors of the MLE.


[view class]
backgroundColor
public:
virtual IColor backgroundColor() const

Returns the background color value of the MLE or the default if no color for the area has been set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Returns the default background color value of the MLE


[view class]
foregroundColor
public:
virtual IColor foregroundColor() const

Returns the foreground color value of the MLE or the default if no color for the area has been set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Returns the default foreground color value of the MLE


Drag and Drop Support

Use these members to customize the conditions for detecting a drag operation.


[view class]
isDragStarting
protected:
virtual bool isDragStarting(IEvent& event)

Request the start of a drag operation. A drag operation will occur if the MLE contains selected text and the mouse pointer was over that selection area when the button was pressed.

Supported Platforms

Windows OS/2 AIX
Yes No No


Event-Handling Implementation

Event-handling implementation members perform processing needed to allow handlers to properly receive GUI events and to route these events.


[view class]
passEventToOwner
protected:
virtual bool passEventToOwner(IEvent& event)

Determines if the event is passed on to the owner.

Supported Platforms

Windows OS/2 AIX
Yes No Yes


Fonts

Use these members to modify the font in the MLE.


[view class]
setFont
public:
virtual IMultiLineEdit& setFont(const IFont& font)

Changes the font of the displayed text.

Exception

IAccessError The operating system's request to set the MLE font failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Import and Export Operations

Use these members to import and export text to a file.


[view class]
exportSelectedTextToFile
public:
virtual unsigned long exportSelectedTextToFile( const char* fileName, EOLFormat type = cfText )

Saves the currently marked text to the specified file and returns the number of bytes written to the file.

fileName
The name of the file you want the text saved to.
type
Use the enumeration EOLFormat to specify the type of format. The default is cfText.

Exception

IInvalidRequest The MLE has no selected text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX only supports the noTran format enumerator.


[view class]
exportToFile
public:
virtual unsigned long exportToFile( const char* fileName, EOLFormat type = cfText )

Saves the contents of the MLE to the specified file and returns the number of bytes written to the file. If the file cannot be opened, zero is returned.

fileName
The name of the file you want the text saved to.
type
Use the enumeration EOLFormat to specify the type of format. The default is cfText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX only supports the noTran format enumerator.


[view class]
importFromFile
public:
virtual unsigned long importFromFile( const char* fileName, EOLFormat type = cfText )

Inserts the contents of the specified file into the MLE at the current cursor position and returns the number of bytes imported.

fileName
The name of the file you want the text imported from.
type
Use the enumeration EOLFormat to specify the type of format. The default is cfText.

Exception

IAccessError An attempt to open or read from a file has failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support embedded NULLs. This function only loads the text up to the first NULL. AIX only supports the noTran format enumerator.


Layout Support


[view class]
setLayoutDistorted
protected:
virtual IMultiLineEdit& setLayoutDistorted( unsigned long layoutAttributeOn, unsigned long layoutAttributeOff )

Indicates that changes have occurred in the window causing the layout of the window in a canvas to be updated.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Line Operations

These members use the terms line and line number as the arguments or the returns from these members. A line is a line on the display after the application of word-wrap. It does not mean a line as defined by the CR-LF line-break sequence.


[view class]
addLine
public:
virtual IMultiLineEdit& addLine( const char* text, unsigned long lineNumber, EOLFormat type = cfText )

Inserts the specified NULL-terminated text at the specified line number.

text
The text you want to insert into the MLE.
lineNumber
The line number where you want to insert the text.
type
Use the enumeration EOLFormat to specify the type of format. The default is cfText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support embedded NULLs. This function only loads the text up to the first NULL. AIX only supports the noTran format enumerator.

If you use a proportional font in the control, line numbers cannot be calculated accurately. Use character-oriented functions instead.


[view class]
addLineAsLast
public:
virtual IMultiLineEdit& addLineAsLast( const char* text, EOLFormat type = cfText )

Inserts the specified NULL-terminated text as the last line in the MLE.

text
The text you want to insert into the MLE.
type
Use the enumeration EOLFormat to specify the type of format. The default is cfText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support embedded NULLs. This function only loads the text up to the first NULL. AIX only supports the noTran format enumerator.

If you use a proportional font in the control, line numbers cannot be calculated accurately. Use character-oriented functions instead.


[view class]
cursorLinePosition
public:
unsigned long cursorLinePosition() const

Returns the line number of the line that contains the cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
cursorPosition
public:
unsigned long cursorPosition() const

Returns the character position from the start of the MLE to the current cursor location.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
numberOfLines
public:
unsigned long numberOfLines() const

Returns the number of lines in the MLE, including word breaks. The number of lines is based on the scrollable size of the MLE. You must set the size of the MLE before using this function. Otherwise, the returned value is not correct.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

If you use a proportional font in the control, line numbers cannot be calculated accurately. Use character-oriented functions instead.


[view class]
removeLine
public:
virtual IMultiLineEdit& removeLine( unsigned long lineNumber )

Deletes the specified line of text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

If you use a proportional font in the control, line numbers cannot be calculated accurately. Use character-oriented functions instead.


[view class]
setCursorLinePosition
public:
virtual IMultiLineEdit& setCursorLinePosition( unsigned long lineNumber )

Moves the cursor position to the first position of the specified line. The values you pass are 0 based.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

If you use a proportional font in the control, line numbers cannot be calculated accurately. Use character-oriented functions instead.


[view class]
setCursorPosition
public:
virtual IMultiLineEdit& setCursorPosition( unsigned long cursorPosition )

Moves the cursor to a specific position in the MLE. The count begins at the first position in the MLE, not at the cursor's current position. The values you pass are 0 based.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTop
public:
virtual IMultiLineEdit& setTop(unsigned long lineNumber)

Makes the specified line the topmost visible line on the screen. The values you pass are 0 based. This function is ignored if the MLE is not scrollable on the screen.

Exception

IAccessError The operating system's request to set the top line of the MLE failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
top
public:
unsigned long top() const

Returns the line number of the line currently visible at the top of the screen.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
visibleLines
public:
unsigned long visibleLines() const

Returns the number of lines that completely fits inside the edit region of the MLE. This value is based on the current font.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

If you use a proportional font in the control, line numbers cannot be calculated accurately. Use character-oriented functions instead.


Notification Members

Use these members to identify and enable notifications sent to observer objects.


[view class]
enableNotification
public:
virtual IMultiLineEdit& enableNotification( bool enable = true )

Enables or disables the MLE control to send notifications to any observer objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dataUpdateId
public:
static INotificationId const dataUpdateId

Notification identifier provided to observers when the data update mode of the MLE changes. IMultiLineEdit provides a boolean value in the eventData field of the INotificationEvent. This value is true if data update is now enabled, and false if data update is disabled.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
limitId
public:
static INotificationId const limitId

Notification identifier provided to observers when the text limit of the MLE changes. IMultiLineEdit provides the new text limit value in the eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Read-Only Operations

Use these members to set and query the read-only style.


[view class]
disableDataUpdate
public:
virtual IMultiLineEdit& disableDataUpdate()

Prevents inserting or changing characters in the MLE's text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableDataUpdate
public:
virtual IMultiLineEdit& enableDataUpdate( bool update = true )

Enables or disables the read-only mode of the MLE control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If the contents of the MLE can be modified, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Refresh Operations

Use these members to enable and disable screen updates.


[view class]
disableUpdate
public:
virtual IMultiLineEdit& disableUpdate()

Disables screen updates. Use this function when your application makes changes throughout an MLE. Doing so avoids unnecessary overhead caused by attempts to keep the screen display updated. While update is disabled, mouse and keyboard messages are processed by beeping and ignoring them. The mouse pointer changes to the standard system "wait" pointer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Enabling and disabling screen refreshes is not typically done in Motif because screen refresh management is handled automatically by X. However, to ensure the portability of logic that requires disabling of input temporarily whenever refresh is disabled, the Open Class Library disables input in Motif, also. Screen refresh is always enabled.


[view class]
enableUpdate
public:
virtual IMultiLineEdit& enableUpdate(bool update = true)

Enables or disables screen updates.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Enabling and disabling screen refreshes is not typically done in Motif, because screen refresh management is handled automatically by X. However, to ensure the portability of logic that requires disabling of input temporarily whenever refresh is disabled, the Open Class Library disables input in Motif, also.


Selected Text

Use these members to access the currently selected text of the MLE.


[view class]
hasSelectedText
public:
virtual bool hasSelectedText() const

If any of the MLE's text is selected, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
selectedRange
public:
virtual IRange selectedRange() const

Returns the range of the selected text. If no text is selected, an exception is thrown. The selected range is the index of the first character selected and the index of the last character selected. The index is 0-based.

Exception

IInvalidRequest The MLE has no selected text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
selectedText
public:
virtual IString selectedText() const

Returns the selected text string. No exception is thrown if there is no text selected; a NULL IString is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
selectedTextLength
public:
virtual unsigned long selectedTextLength() const

Returns the size of the selected area, in bytes. The length includes CR-LFs, but not NULL terminators. No exception is thrown if there is no text selected; 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
selectRange
public:
virtual IMultiLineEdit& selectRange( const IRange& range = IRange ( 0 , end ), unsigned long timestamp = 0 )

Selects a range of text.

range
The selected range is the index of the first character selected (or to be selected) and the index of the last character selected (or to be selected). The index is 0-based. If you do not specify range, the default selects all of the text. If you specify the range to be IMultiLineEdit::deselect, then the multi line edit will be deselected.
timestamp
In AIX, a value within the time member of the XEvent structure.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The optional parameter timestamp allows a time stamp value to be passed when this function is called from an event handler. This parameter specifies the time at which the selection value is to be modified. This must be the time of the event that triggered the request. One source of a valid timestamp is the XtLastTimestampProcessed function.

In AIX, get the value for timestamp from the time member of the XEvent structure. The default value is interpreted as CurrentTime.


[view class]
deselect
public:
static const long deselect

Denotes that the text should be deselected when calling IMultiLineEdit::selectRange.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
end
public:
static const long end

Denotes the end of the text for selecting text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Size Operations

Use these members to set and query the edit region.


[view class]
editRegionHeight
public:
unsigned long editRegionHeight() const

Returns the height of the edit region. The edit region is the rectangular area in which the text is displayed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
editRegionWidth
public:
unsigned long editRegionWidth() const

Returns the width of the edit region. The edit region is the rectangular area in which the text is displayed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setEditRegion

Sets the size of the edit region so that it covers the entire MLE window. The edit region is the rectangular area in which the text is displayed.


Overload 1
public:
virtual IMultiLineEdit& setEditRegion()

Exception

IAccessError The operating system's request to set the region failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In Motif, if the window is too small to show all of the text, it is not an error. In this situation, this function does not throw an exception.


Overload 2
public:
virtual IMultiLineEdit& setEditRegion( const ISize& sizeEditRegion )

Exception

IInvalidParameter The operating system's request to set the region width and height failed. The sizeEditRegion parameter is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In Motif, if the window is too small to show all of the text, it is not an error. In this situation, this function does not throw an exception.


[view class]
setEditRegionHeight
public:
virtual IMultiLineEdit& setEditRegionHeight(long height)

Sets the height of the edit region. The edit region is the rectangular area in which the text is displayed.

Exception

IInvalidParameter The operating system's request to set the region height failed. The height parameter is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In Motif, if the window is too small to show all of the text, it is not an error. In this situation, this function does not throw an exception.


[view class]
setEditRegionWidth
public:
virtual IMultiLineEdit& setEditRegionWidth(long width)

Sets the width of the edit region. The edit region is the rectangular area in which the text is displayed.

Exception

IInvalidParameter The operating system's request to set the region width failed. The width parameter is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In Motif, if the window is too small to show all of the text, it is not an error. In this situation, this function does not throw an exception.


Styles

These style members provide a set of valid styles for this class. Use these members to query and set the MLE styles. You can use these styles with the styles in the IWindow Styles class.


[view class]
convertToGUIStyle
public:
virtual unsigned long convertToGUIStyle( const IBitFlag& style, bool extendedOnly = false ) const

Converts a style object into a value appropriate for the presentation system. The default action is to return the base GUI styles for the platform. Extended styles, those defined by the application and the Open Class Library, are returned if you set extendedOnly to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the default style. The default style is classDefaultStyle unless you have changed the style using setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent MLEs.

style
Use the styles provided by IMultiLineEdit Styles to specify the default style.

This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.

When you create a window class and do not specifically specify window styles in the constructor, the Open Class Library queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create windows are active.

Another way to avoid a conflict in a multithreaded application is to specifically specify window styles on window construction, rather than calling this member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
border
public:
static const Style border

Causes a thin border to be drawn around the MLE.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
border3D
public:
static const Style border3D

Adds an etched 3D border to the control. This style is ignored if border is not specified.

Supported Platforms

Windows OS/2 AIX
Yes Ignored Ignored


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Provides the original default style for this class, which is the following: IMultiLineEdit::border | IMultiLineEdit::verticalScroll | IMultiLineEdit::wordWrap | IMultiLineEdit::border3D | IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
horizontalScroll
public:
static const Style horizontalScroll

Adds a horizontal scroll bar to the MLE.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ignoreTab
public:
static const Style ignoreTab

Causes the MLE to ignore tab keystrokes. The function sends a keyboard event to the owner of the MLE.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
readOnly
public:
static const Style readOnly

Restricts the user from entering any data.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
verticalScroll
public:
static const Style verticalScroll

Adds a vertical scroll bar to the MLE.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
wordWrap
public:
static const Style wordWrap

Causes text word-wrap at the end of a line.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Tab Stops

Use these members to manipulate characteristics of the tab operation.


[view class]
setTab
public:
virtual IMultiLineEdit& setTab( unsigned long tabPixelInterval )

Sets the interval at which tab stops are placed in the MLE. This interval is expressed in pixels.

Exception

IAccessError The operating system's request to set the tab failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


Text Operations

Use these members to access the text of the MLE.


[view class]
add
public:
virtual IMultiLineEdit& add( const char* text, unsigned long textSize = 0, EOLFormat type = cfText )

Inserts the specified text into the MLE at the current cursor position and positions the cursor at the end of the inserted text.
Note: This function strips the last CR-LF characters. Therefore, if you need to explicitly use CR-LF, do one of the following:

text
The text you want to insert into the MLE.
textSize
If you want to add text containing more than one NULL character, specify textSize. If you use the default, this function adds the characters up to the first NULL character.
type
Use the enumeration EOLFormat to specify the type of format. The default is cfText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support embedded NULLs. This function only loads the text up to the first NULL. AIX only supports the noTran format enumerator.


[view class]
addAsLast
public:
virtual IMultiLineEdit& addAsLast( const char* text, unsigned long textSize = 0, EOLFormat type = cfText )

Inserts the specified text into the MLE at the end of the current text but does not change the cursor position.

text
The text you want to insert into the MLE.
textSize
If you want to add text containing more than one NULL character, specify textSize. If you use the default, this function adds the characters up to the first NULL character.
type
Use the enumeration EOLFormat to specify the type of format. The default is cfText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support embedded NULLs. This function only loads the text up to the first NULL. AIX only supports the noTran format enumerator.


[view class]
addAtOffset
public:
virtual IMultiLineEdit& addAtOffset( const char* text, unsigned long offset, unsigned long textSize = 0, EOLFormat type = cfText )

Inserts the specified text into the MLE at the point specified. At the conclusion of this insert, this function positions the cursor at the same character as it was before the insert.

text
The text you want to insert into the MLE.
charnumber
The number of the character after which you want to insert text. This is a 0-based index.
textSize
If you want to add text containing more than one NULL character, specify textSize. If you use the default, this function adds the characters up to the first NULL character.
type
Use the enumeration EOLFormat to specify the type of format. The default is cfText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support embedded NULLs. This function only loads the text up to the first NULL. AIX only supports the noTran format enumerator.


[view class]
limit
public:
unsigned long limit() const

Returns the currently set number of bytes that the MLE can hold.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Returns the value of the current maximum allowable length of a string entered from the keyboard.


[view class]
setLimit
public:
virtual IMultiLineEdit& setLimit(unsigned long newLimit)

Sets a limit on the number of bytes that can be input into the MLE.

Exception

IAccessError The operating system's request to set the text limit failed, or the MLE already contains more text than the proposed limit.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Sets the value of the current maximum allowable length of a string entered from the keyboard. Text set into the control programmatically will ignore this limit on AIX.


[view class]
setText

Sets the contents of the MLE to the text specified.


Overload 1
public:
virtual IMultiLineEdit& setText( const char* buffer, unsigned long bufferSize )

Overwrites the current contents of the MLE with the specified text.

buffer
The input buffer containing the new text. The input buffer can contain NULL characters.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support embedded NULLs. This function only loads the text up to the first NULL.


Overload 2
public:
virtual IMultiLineEdit& setText(const char* text)

Overwrites the current contents of the MLE with the specified text.

text
The text to insert into the MLE.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support embedded NULLs. This function only loads the text up to the first NULL.


Overload 3
public:
virtual IMultiLineEdit& setText(const IResourceId& text)

Overwrites the current contents of the MLE with the specified text.

text
The resource ID specifying the text to insert into the MLE.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support embedded NULLs. This function only loads the text up to the first NULL.


[view class]
text

Returns the current contents of the MLE.


Overload 1
public:
virtual IString text() const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IString text(unsigned long lineNumber) const

If you do not specify lineNumber, this function returns the current contents of the MLE. If you do specify lineNumber, this function returns the current MLE text at the specified line.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
textLength
public:
virtual unsigned long textLength() const

Returns the current length of the MLE text, in bytes. The length includes any CR-LFs present.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Text Removal

These members remove text from the MLE.


[view class]
removeAll
public:
virtual IMultiLineEdit& removeAll()

Deletes the entire contents of the MLE.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Undo Operations

These members provide undo capabilities.


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

If any undoable actions have been performed on the contents of the MLE, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This function always returns false.


[view class]
undo
public:
virtual IMultiLineEdit& undo()

Restores the MLE's content to the state it was in before the last change. If the undo fails, the change flag is reset.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


Word-Wrap Operations

These members provide for word-wrap in the MLE.


[view class]
disableWordWrap
public:
virtual IMultiLineEdit& disableWordWrap()

Disables word-wrap mode in the MLE.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
enableWordWrap
public:
virtual IMultiLineEdit& enableWordWrap(bool enable = true)

Enables or disables word-wrap mode in the MLE. Word-wrap breaks the text at word boundaries to keep all of the text in a line visible, even if the text is wider than the MLE's window. The text is still one line of text. No carriage-control or line-feed characters are added.

Exception

IAccessError The operating system's request to enable word-wrapping failed.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


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

If the MLE is in word-wrap mode, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IMultiLineEdit - Enumerations


[view class]
EOLFormat
enum EOLFormat { cfText, 
                 noTran, 
                 MLEFormat }

Use these enumerators to specify the format for the end-of-line characters when importing and exporting text:

cfText
Ends each line with a CR-LF combination. Tab characters separate fields within a line. A NULL character signals the end of the data.
noTran
Uses LF for line delineation and guarantees any text imported into the MLE in this format can be recovered in exactly the same form when exported.
MLEFormat
On import, recognizes CR-LF as denoting hard line-breaks and ignores the sequence CR-CR-LF. On export, uses CR-LF to denote a hard line-break and CR-CR-LF to denote a soft line-break caused by word-wrapping.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX only supports the noTran format enumerator. If you specify any other EOLFormat, the member functions ignore it and use noTran instead.

Windows Considerations
The noTran enumerator is not supported in Windows. The MLEFormat enumerator is used instead.


IMultiLineEdit - Inherited Member Functions and Data

Inherited Public Functions

IControl
INotifier
ITextControl
IWindow

Inherited Public Data

IWindow
INotifier
ITextControl

Inherited Protected Functions

IWindow
INotifier
IControl
ITextControl

Inherited Protected Data