IStaticText

The IStaticText class creates and manages static text control windows. Static text controls are simple text fields that do not accept user input. For example,

  IStaticText sttxtText(ID_TEXT, this, this, IRectangle(10,10,70,24)));
  sttxtText.setText("It is a wonderful day");
You can use the classes derived from IStaticText to display bitmaps and icons.

You can use IStaticText to create text prompts and labels. You can give the static text a background color so that it has the appearance of a box. By using a background color and no text, you can create a solid box with nothing inside it.

You can attach the following handlers to this control:

Portability Considerations

OS/2 applications can use the IStaticText control to create boxes that label, box, or frame other controls.

The IStaticText control can be parent, child, or owner of these other controls. However, for portable applications, you should use IFrameWindow, IOutlineBox, or the canvas classes instead of IStaticText.

OS/2 Considerations

If you do not set a fill color, the background color is used as the fill color.


IStaticText - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of the IStaticText class. You cannot copy or assign IStaticText objects because both the copy and assignment operator are private functions. You can construct objects of this class in the following ways:


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IStaticText


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

Creates an object for a static text control that exists in a dialog window.

id
The ID of the existing static text control.
parent
The parent window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IStaticText(const IWindowHandle& handle)

Creates an object for an existing static text control.

handle
The window handle of an existing static text control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Creates a static text control and an object for it.

id
A static text control ID.
parent
The parent window.
owner
The owner window.
initial
The initial position and size of the control you are constructing. Optional.
style
The control's characteristics. 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


Alignment

Use these members to query and set the alignment of the static text control.


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

Returns the current alignment for this static text object. The returned value is an Alignment enumerator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAlignment
public:
virtual IStaticText& setAlignment( Alignment alignment = IStaticText::topLeft )

Sets the alignment of the static text.

Exception

IInvalidParameter The alignment value specified is invalid. See the documentation for the Alignment group under IStaticText for valid alignment values.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Bidirectional Language Support

These members allow a window to support bidirectional languages, such as Arabic and Hebrew. These languages are written and read right-to-left, but text in these languages may also contain strings that are written and read left-to-right.


[view class]
setBidiSettings
protected:
virtual IStaticText& setBidiSettings( const IBidiSettings& bidiSettings, bool childInherit, bool refresh )

This function allows a static text control object to provide special processing to support a change in its bidirectional characteristics. This function is called just before the bidirectional characteristics of the static text object change. This function is not called when you create a static text object.

bidiSettings
The new bidirectional settings for the static text object.
childInherit
This flag specifies if the child windows of the static text control will inherit the new bidirectional attributes.
refresh
This flag specifies if the static text control will paint after receiving the new directional attributes.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

This function is not provided because you cannot change the bidirectional attributes of a window on that platform after you create it.

OS/2 Considerations

IStaticText does not override IWindow::setBidiSettings on this platform.

Windows Considerations

If the window layout direction is changing, the static text object may call setAlignment to change how it aligns its text.


Colors

Use these members to query, set, and reset colors for the static text control. You can query the foreground and background colors. You can query and set the fill color for the static text.


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

Returns the background color of the static text object. If you do not set a color for this area, 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.

AIX Considerations

In AIX, the backgroundColor functions inherited from IWindow is used.

OS/2 Considerations

The default is from the owner window chain or color scheme on the OS/2 platform.


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

Returns the fill color value of the static text. If you do not set the fill color, the default is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Fill color and background color are identical in the AIX environment. Therefore, this function returns the background color in this environment.


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

Returns the foreground color value of the static text. If you do not set the color for the area, 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]
resetFillColor
public:
virtual IStaticText& resetFillColor()

Resets the fill color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function is the same as resetBackgroundColor in the AIX environment.


[view class]
setFillColor
public:
virtual IStaticText& setFillColor(const IColor& color)

Sets the color for the area of the static text control window that does not have text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function is equivalent to setBackgroundColor in the AIX environment.


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


Fill Background

Use these members to query and set the fill background of the static text control. If fill background is enabled, the background of the static text control is erased before the text is drawn.


[view class]
disableFillBackground
public:
virtual IStaticText& disableFillBackground()

Draws text over the current background.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The fillBackground style is always enabled in AIX; therefore, this function has no effect.


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

Erases the background before the text is drawn.
Note: If you call this function on an object of a derived class, such as IBitmapControl or IIconControl, the graphic is overlaid by the background color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The fillBackground style is ignored in AIX; therefore, this function has no effect.


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

If the background is erased before any text is drawn, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The fillBackground style is ignored in AIX. This function returns false.


Layout Support

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


[view class]
addDrawingHandler
protected:
IStaticText& addDrawingHandler()

Adds the drawing handler to the static text object. This will occur automatically if style settings warrant.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

Returns a size based on the text limit value, the current font, and whether or not the wordBreak style is set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the recommended minimum size for this static text control. The size is based on the following:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Minimum Size Adjustment

Use these members to set and query the number of characters that the minimum size can be based on.


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

Returns the number of characters set by setLimit. You can use this limit or calcMinimumSize to determine a minimum limit for the static text control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setLimit
public:
virtual IStaticText& setLimit(unsigned long limit = 0)

Sets the minimum number of characters in a maximum size static text control.

Use this for static text controls that change the text displayed on an ISetCanvas or IMultiCellCanvas to avoid causing the canvas to update the layout of its child windows with each change to the static text contents.

calcLimitSize uses a nonzero limit value to calculate a minimum size for this window. The size can be larger than the actual size needed to hold the currently displayed text.

The minimum size used is the larger of either of the following:

If this function is not called, the minimum size needed to display the current text is the default.

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]
fillBackgroundId
public:
static INotificationId const fillBackgroundId

Notification identifier provided to observers when the fill background style of a static text control changes. IStaticText provides a boolean value in the INotificationEvent::eventData field of the INotificationEvent. This value is true if fillBackground is now enabled, and false if fillBackground is disabled.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
fillColorId
public:
static INotificationId const fillColorId

Notification identifier provided to observers when the fill color of a static text control changes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
halftoneId
public:
static INotificationId const halftoneId

Notification identifier provided to observers when the halftone style of a static text control changes. IStaticText provides a boolean value in the INotificationEvent::eventData field of the INotificationEvent. This value is true if halftone is now enabled, and false if halftone is disabled.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
limitId
public:
static INotificationId const limitId

Notification identifier provided to observers when the text limit of a static text control changes. IStaticText provides the new limit value in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
strikeoutId
public:
static INotificationId const strikeoutId

Notification identifier provided to observers when the strikeout style of a static text control changes. IStaticText provides a boolean value in the INotificationEvent::eventData field of the INotificationEvent. This value is true if strikeout is now enabled, and false if strikeout is disabled.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
underscoreId
public:
static INotificationId const underscoreId

Notification identifier provided to observers when the underscore style of a static text control changes. IStaticText provides a boolean value in the INotificationEvent::eventData field of the INotificationEvent. This value will be true if underscore is now enabled, and false if underscore is disabled.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


Styles

These style members provide a set of valid styles for the IStaticText class. You can use these styles with the styles in IWindow.

AIX Considerations

AIX does not support the following styles:


[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 it 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 static text controls.

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

Aligns the text at the bottom of the window

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
center
public:
static const Style center

Centers the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Provides the original default style for this class, which is the following: IStaticText::left | IStaticText::top | IStaticText::fillBackground | IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
fillBackground
public:
static const Style fillBackground

Erases the background, using the currently set fill color, before drawing the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In AIX, the background is always painted regardless of this style setting.


[view class]
halftone
public:
static const Style halftone

Draws the text in halftone color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
left
public:
static const Style left

Left-justifies the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
mnemonic
public:
static const Style mnemonic

If a mnemonic prefix character (the tilde) is found, the character following the prefix character is drawn with mnemonic emphasis. Without the mnemonic style, the tilde is displayed in the text of the IStaticText object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
right
public:
static const Style right

Right-justifies the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
strikeout
public:
static const Style strikeout

Draws the text with a line through it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
top
public:
static const Style top

Aligns the text at the top of the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
underscore
public:
static const Style underscore

Underlines the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
vertCenter
public:
static const Style vertCenter

Aligns the text vertically in the center of the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
wordBreak
public:
static const Style wordBreak

Word-wraps, at ends of lines, text that has multiple lines. You can only use this style when you also specify the left and top styles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The Open Class Library creates objects of the IStaticText class using XmLabel widgets.

The wordBreak style is ignored when the text contains multi-byte character set (MBCS) or double-byte character set (DBCS) data.


Text Processing

Use these members to set the text, to query the text, and to modify how the text is displayed for the static text control.


[view class]
disableHalftone
public:
virtual IStaticText& disableHalftone()

Removes the halftone from the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The halftone style is not available in AIX; therefore, this function has no effect.


[view class]
disableStrikeout
public:
virtual IStaticText& disableStrikeout()

Removes the line drawn through the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The strikeout style is not available in AIX; therefore, this function has no effect.


[view class]
disableUnderscore
public:
virtual IStaticText& disableUnderscore()

Removes the line beneath the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The underscore style is not available in AIX; therefore, this function has no effect.


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

Draws the text using the style halftone.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The halftone style is not available in AIX; therefore, this function has no effect.


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

Draws a line through the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The strikeout style is not available in AIX; therefore, this function has no effect.


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

Draws a line beneath the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The underscore style is not available in AIX; therefore, this function has no effect.


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

If the text has the style halftone set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The halftone style is not available in AIX. This function returns false.


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

If the text has the style strikeout set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The strikeout style is not available in AIX. This function returns false.


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

If the text has the style underscore set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The underscore style is not available in AIX. This function returns false.


[view class]
setText

Sets the text for the control. Overrides the inherited setText. If appropriate, this function also notifies a parent canvas to update the layout for its children.


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

Use this function to set the text in the static text control using an IResourceId.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Use this function to set the text in the static text control using a character string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the control window's text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IStaticText - Enumerations


[view class]
Alignment
enum Alignment { topLeft, 
                 topLeftWrapped, 
                 topCenter, 
                 topRight, 
                 centerLeft, 
                 centerCenter, 
                 centerRight, 
                 bottomLeft, 
                 bottomCenter, 
                 bottomRight }

Use these enumerators to specify the alignment of the static text:

topLeft
Aligns the text at the top of the window and left-justifies the text.
topLeftWrapped
Aligns the text at the top of the window, left-justifies the text, and wraps the text into multiple lines using word-wrapping at the end of the lines.
topCenter
Aligns text at the top of the window and centers it.
topRight
Aligns text at the top of the window and right-justifies it.
centerLeft
Aligns text vertically in the center of the window and left-justifies it.
centerCenter
Aligns text vertically in the center of the window and centers it.
centerRight
Aligns text vertically in the center of the window and right-justifies it.
bottomLeft
Aligns text at the bottom of the window and left-justifies it.
bottomCenter
Aligns text at the bottom of the window and centers it.
bottomRight
Aligns text at the bottom of the window and right-justifies it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The topLeftWrapped enumerator is equivalent to the topLeft enumerator when the text contains multi-byte character set (MBCS) or double-byte character set (DBCS) data.


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