IEntryField

The IEntryField class creates and manages entry field controls. An entry field control is a control window which allows a user to type and edit a single line of text.

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

AIX Considerations

The Open Class Library implements this class with the XmText widget (instead of XmTextField) to allow more uniformity between IEntryField and IMultiLineEdit.

You can implement specific keystroke processing, such as creating a numeric-only input field, by deriving a handler from IEditVerifyHandler and attaching your handler to the entry field object.


IEntryField - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IEntryField


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

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

id
An entry field control ID.
parent
The parent window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IEntryField(const IWindowHandle& handle)

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

handle
The window handle of an existing entry field control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IEntryField( 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 entry field 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.
IInvalidStyle Alignment styles specified were in conflict. You must specify only one alignment style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
protected:
IEntryField()

Constructs objects of this class. This is a protected constructor that can be used by derived classes. This is the default constructor and accepts no parameters.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Attributes

Use these members to query and change characteristics of the entry field control.


[view class]
alignment
public:
Alignment alignment() const

Returns the current alignment for this entry field object. The returned value is an enumerator provided by Alignment.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Left alignment is always returned.


[view class]
charType
public:
CharType charType() const

Returns the current type of character that this entry field accepts. The returned value is an enumerator provided by CharType.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

An IEntryField is always of type any.

Windows Considerations

An IEntryField is always of type any.


[view class]
setAlignment
public:
virtual IEntryField& setAlignment(Alignment alignment)

Sets the alignment of the entry field control.

alignment
Use the enumeration Alignment to specify the alignment of the entry field.

Exception

IInvalidParameter An invalid Alignment was specified. You must specify one of the valid Alignment values. Current valid values are left, center, and right.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

AIX Considerations

Alignment can only be set to left.

Windows Considerations

Alignment can be specified on the constructor, but cannot be changed dynamically.


[view class]
setCharType
public:
virtual IEntryField& setCharType(CharType type)

Sets the type of character the entry field control can accept.

type
Use the enumeration CharType to specify the type of characters in the entry field.

Exception

IInvalidParameter An invalid CharType was specified. You must specify one of the valid CharType values. Current valid values are sbcs, dbcs, any, and mixed.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

AIX Considerations

This platform only supports the CharType enumerator any. This type corresponds to the X multibyte character set (MBCS).


Auto Scroll

Use auto scroll members to query and change the autoScroll style of the entry field object. The autoScroll style determines if the entry field automatically scrolls in the appropriate direction if the user tries to move off the end of a line.


[view class]
disableAutoScroll
public:
virtual IEntryField& disableAutoScroll()

Disables the style autoScroll on an entry field control.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
enableAutoScroll
public:
virtual IEntryField& enableAutoScroll(bool enable = true)

Enables or disables the style autoScroll on an entry field control.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


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

If the entry field control has the style autoScroll set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Auto Tab

Use auto tab members to query and change the autoTab style of the entry field object. The autoTab style determines if the entry field will automatically generate a tab character when the field is filled by adding a character to the end of the text.


[view class]
disableAutoTab
public:
virtual IEntryField& disableAutoTab()

Disables the style autoTab on an entry field control.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
enableAutoTab
public:
virtual IEntryField& enableAutoTab(bool enable = true)

Enables or disables the style autoTab on an entry field control.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


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

If the entry field control has the style autoTab set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Clipboard Operations

Use these members to transfer data between the clipboard and the entry field control. Each of these operations deals with the selected text in the entry field control.


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

Replaces the selected text in the entry field 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 entry field is selected before making the call to clear.

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

Exception

IInvalidRequest The entry field has no text selected.

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.

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 Windows release does not use the timestamp parameter.


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

Copies the selected text 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 entry field is selected before making the call to copy.

Exception

IInvalidRequest The entry field has no text selected.
IAccessError The operating system's request to copy from the entry field 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.

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 Windows release does not use the timestamp parameter.


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

Removes the selected text from the entry field control and puts 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 entry field is selected before making the call to cut.

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

Exception

IInvalidRequest The entry field has no text selected.
IAccessError The operating system's request to cut from the entry field 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.

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 Windows release does not use the timestamp parameter.


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

Deletes the 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 entry field is selected before making the call to discard.

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

Exception

IInvalidRequest The entry field has no text selected.
IAccessError The operating system's request to discard the text from the entry field 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 IEntryField& paste()

Copies text from the clipboard to the entry field control, 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 entry field 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 entry field failed. See the exception text for further information about the failure.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Colors

Use these members to query, set, and reset colors of the entry field.


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

Returns the background color value of the entry field. If you have not set this color, the default is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

This member is overridden in this derived class for specific operating system behavior.


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

Returns the foreground color value of the entry field. If you have not set this color, the default is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

This member is overridden in this derived class for specific operating system behavior.


Commands

Use these members to query and change the command style of the entry field object. The command style identifies the entry field as a command entry field. This information can be used to provide command help if the user requests help for this field.


[view class]
disableCommand
public:
virtual IEntryField& disableCommand()

Disables the style command on an entry field control.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
enableCommand
public:
virtual IEntryField& enableCommand(bool enable = true)

Enables or disables the style command on an entry field control.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


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

If the entry field control has the style command set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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 entryfield 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]
initialize
protected:
IEntryField& initialize( unsigned long style, const IWindowHandle& wh )

Initializes private data for the entry field control. Both the IEntryField constructors and the derived classes' constructors call this function. This function can only be called after IWindow::startHandlingEventsFor or IWindow::create has been called.

Supported Platforms

Windows OS/2 AIX
No No Yes


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

This member function is use to determine if an event should continue to be dispatched up the owner chain.

Supported Platforms

Windows OS/2 AIX
Yes No Yes

AIX Considerations

This override stops mouse down, up and click events and most key events that are dispatched to an IEntryField object from propagating up the owner chain. The override does allow the enter key event to propagate up the owner chain so the IFrameWindow object that is up the owner chain can handle the enter key for default button behavior.

Windows Considerations

This override stops mouse down, up and click events that are dispatched to an IEntryField object from propagating up the owner chain.


Implementation

These members provide utilities used to implement this class.


[view class]
setStyle
protected:
virtual IEntryField& setStyle(unsigned long style)

Replaces the style of an entry field control, while preserving the cursor position and selected text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Insert Mode

Use these members to set and query the insert mode for the entry field. The insert mode determines whether characters are inserted or replaced at the cursor position.


[view class]
disableInsertMode
public:
virtual IEntryField& disableInsertMode()

Enables the entry field for overtype mode and changes the cursor's appearance.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
enableInsertMode
public:
virtual IEntryField& enableInsertMode(bool insert = true)

Enables the entry field for insert mode and changes the cursor's appearance.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


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

Queries whether the entry field is in insert mode.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Layout Support

Layout support members supply information used by the canvas classes to provide dialog-like behavior.


[view class]
calcMinimumSize
protected:
virtual ISize calcMinimumSize() const

Returns the minimum size that this entry field control can be, based on the text string length limit and the current font.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setLayoutDistorted
protected:
virtual IEntryField& 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


Left Index

Use these members to set and query the left index of the entry field. The left index is the index of the first displayed character at the left edge of the entry field.


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

Returns the index of the first character displayed at the left edge of the entry field control. The index is 0-based. This function is ignored unless the field is visibly scrollable.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

Windows Considerations

This member is not supported on Windows. It will always return 0 on this platform.


[view class]
setLeftIndex
public:
virtual IEntryField& setLeftIndex(unsigned long index)

Sets the first displayed character at the left edge of the entry field control. The index is 0-based.

Exception

IAccessError The operating system's request to set the left index failed. See the exception text for further information about the failure.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Margins

Use margin members to query and change the margin style of the entry field object. The margin style determines if the entry field control will be drawn with a border around the editable text.


[view class]
disableMargin
public:
virtual IEntryField& disableMargin()

Disables the style margin on an entry field control. As a result, the entry field will not have a border surrounding its edit rectangle.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
enableMargin
public:
virtual IEntryField& enableMargin(bool enable = true)

Enables or disables the style margin on an entry field control. As a result, this function adds or removes a border from the edit area.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


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

If the entry field control has the style margin set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

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


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

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
characterTypeId
public:
static INotificationId const characterTypeId

Notification identifier provided to observers when the character type of the entry field control changes. IEntryField provides the character type in the INotificationEvent::eventData field of the INotificationEvent. This value is one of the predefined CharType enum values defined in this class.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

This notification identifier is ignored on Windows.


[view class]
dataUpdateId
public:
static INotificationId const dataUpdateId

Notification identifier provided to observers when the data update mode of the entry field control changes. IEntryField provides a boolean value in the INotificationEvent::eventData field of the INotificationEvent. This value is true if the user can now update the data, and false if the user cannot update the data.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
insertModeId
public:
static INotificationId const insertModeId

Notification identifier provided to observers when the insert mode of the entry field control changes. IEntryField provides a boolean value in the INotificationEvent::eventData field of the INotificationEvent. This value is true if insert mode is now enabled, and false if replace mode is enabled.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
limitId
public:
static INotificationId const limitId

Notification identifier provided to observers when the text limit of the entry field control changes. IEntryField provides the new text limit value in the INotificationEvent::eventData field of the INotificationEvent. This value will be the new text limit.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overrides

These members are overloaded to ensure a disabled entry field is set to a read-only state to prevent user input.


[view class]
disable
public:
virtual IEntryField& disable()

Disables an entry field control. When you disable the entry field, the entry field has the following characteristics:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Enables or disables an entry field control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setText

Overwrites the current contents of the entry field with the specified text.

text
The resource ID containing the new text.

If the text length exceeds the text limit of the entry field, the text is truncated.


Overload 1
public:
virtual IEntryField& setText(const IResourceId& text)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the text of the entry field's control window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This override is added for a Motif-unreadable style.


Read-Only Operations

These members query and modify the read-only mode in the entry field, which specifies if the user can change the entry field text.


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

Prevents inserting or changing characters in the entry field's text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Enables or disables the read-only mode on an entry field control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Selected Text

Use these members to manipulate selected text.


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

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

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

Exception

IInvalidRequest The entry field has no text selected.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the selected text string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the size of the selected area in bytes. The length does not include the NULL terminator. 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 IEntryField& selectRange( const IRange& range = IRange ( 0 , end ), unsigned long timestamp = 0 )

Selects a range of text.

range
The range is the index of the first character selected and the index of the last character selected. The index is 0-based. If you do not specify range, the default selects all of the text. If you specify a range with equivalent lower and upper values (n, n), the insertion point (cursor) is positioned after the single character selected.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setCursorPosition
public:
virtual IEntryField& setCursorPosition( unsigned long newCursorPos )

Moves the cursor to a specific position in the entry field. The count begins at the first position in the entry field, not at the cursor's current position.

Exception

IAccessError The operating system's request to set the cursor position failed. See the exception text for further information about the failure.

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


Styles

These style members provide a set of valid styles for this class. Use these members to query and set the entry field 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 entry fields.

style
Use the styles provided by IEntryField 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]
anyData
public:
static const Style anyData

Sets the entry field to accept text that is a mixture of single-byte character set (SBCS) and double-byte character set (DBCS) characters.

If the text contains both SBCS and DBCS characters and will be converted from an ASCII code page to an EBCDIC code page, this style causes an entry field to ignore accounting for shift-in and shift-out characters that would be introduced into its text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
autoScroll
public:
static const Style autoScroll

If the user tries to move off the end of a line, the entry field automatically scrolls one-third the width of the window in the appropriate direction.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
autoTab
public:
static const Style autoTab

Causes a tab key to be generated when the entry field is filled by adding a character at the text limit of the entry field text.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
border3D
public:
static const Style border3D

Adds an etched 3D border to the control.

Supported Platforms

Windows OS/2 AIX
Yes Ignored Ignored


[view class]
centerAlign
public:
static const Style centerAlign

Sets the text in the entry field to be centered.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

Windows Considerations

This style cannot be mixed with the autoScroll or unreadable styles.


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Provides the original default style for this class, which is the following: IWindow::visible | IEntryField::margin | IEntryField::autoScroll | IEntryField::leftAlign | IEntryField::anyData | IEntryField::border3D.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
command
public:
static const Style command

Creates information used by the Help Manager to provide command help if the user requests help for this entry field. No more than one entry field on each window should be given this style.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
dbcsData
public:
static const Style dbcsData

Sets the entry field to accept double-byte text only.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
leftAlign
public:
static const Style leftAlign

Set the text in the entry field to be left-justified.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
margin
public:
static const Style margin

Causes a border to be drawn around the entry field, with a margin between the border and the entry field. The margin's size is determined by the current font being used for entry field text (half a character-width wide and half a character-height high).

Because the margin and border are drawn around the entry field, using the margin style does not change the position of the entry field itself.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
mixedData
public:
static const Style mixedData

Sets the entry field to accept text that is a mixture of SBCS and DBCS characters. Conversion from an ASCII DBCS code page to an EBCDIC DBCS code page can result in a possible increase in the length of the data because of the addition of shift-in and shift-out characters, but it will not exceed the text limit of the entry field.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
readOnly
public:
static const Style readOnly

Prevents insertions or changes to the text in the entry field.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rightAlign
public:
static const Style rightAlign

Sets the text in the entry field to be right-justified.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

Windows Considerations

This style cannot be mixed with the autoScroll or unreadable styles.


[view class]
sbcsData
public:
static const Style sbcsData

Sets the entry field to accept single-byte text only.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
unreadable
public:
static const Style unreadable

Causes the text in the entry field to be displayed using an asterisk for each character.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Test Operations

Use these members to query the entry field.


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

If any of the entry field text is selected, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If any changes have been made to the entry field 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]
isEmpty
public:
bool isEmpty() const

If the entry field is empty, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Text Limit

Use these members to set and query the text limit of the entry field.


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

Returns the length, in bytes, of the longest text the entry field can hold.
Note: The default value for the limit differs from system to system in accordance with the look-and-feel of that system. If your application requires a specific limit for an entry field, you must set that limit using setLimit to ensure portability of your application.

Exception

IAccessError The operating system's request to query the entry field limit failed. See the exception text for further information about the failure.

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.

OS/2 Considerations

The default text limit in the OS/2 operating system environment is 32.


[view class]
setLimit

Sets the maximum number of bytes the entry field can contain.

The calcMinimumSize function uses the text limit to determine the minimum size of the entry field.
Note: The default value for the limit differs from system to system in accordance with the look-and-feel of that system. If your application requires a specific limit for an entry field, you must set that limit using setLimit to ensure portability of your application.


Overload 1
public:
virtual IEntryField& setLimit(const IResourceId& textLimit)

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.

OS/2 Considerations

The default text limit in the OS/2 operating system environment is 32.


Overload 2
public:
virtual IEntryField& setLimit(unsigned long textLimit)

Exception

IInvalidRequest The entry field already contains more characters than the proposed limit.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Text Removal

These members remove text from the entry field.


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

Deletes the entire contents of the entry field control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IEntryField - Enumerations


[view class]
Alignment
enum Alignment { left, 
                 center, 
                 right }

Use these enumerators to specify the alignment of text in the entry field:

left
Left-justifies the text in the control.
center
Centers the text in the control.
right
Right-justifies the text in the control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Alignment enumeration is ignored. All entry fields have left alignment.


[view class]
CharType
enum CharType { any, 
                sbcs, 
                dbcs, 
                mixed }

Use these enumerators to specify the type of character data allowed in the entry field:

sbcs
Accepts single-byte (SBCS) text only.
dbcs
Accepts double-byte (DBCS) text only.
mixed
Accepts text that is a mixture of SBCS and DBCS characters. Conversion from an ASCII DBCS code page to an EBCDIC DBCS code page can result in an increase in the length of the text because of the addition of shift-in and shift-out characters. Using this enumerator prevents the overflow of EBCDIC string buffers.
any
Accepts text that is a mixture of SBCS and DBCS characters.
Note: If the text contains both single-byte and double-byte characters and is to be converted from an ASCII code page into an EBCDIC code page, this enumerator causes an entry field to not account for shift-in and shift-out characters that are introduced into its text. An overflow of EBCDIC string buffers might occur.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

CharType enumeration is ignored. All entry fields are of type any.


IEntryField - 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