Changes in this Release of Open Class

The sections that follow describe the major changes in this release and identify deprecated classes and functions.

AIX Changes

These features are now implemented on AIX:

Toolbar and Related Changes

New Styles for Direct Manipulation Support

For performance reasons, dragdrop support is no longer enabled by default. This change necessitated the addition of a new style and deprecation of an existing style. The style IToolBar::dragdrop enables dragging and dropping of the tool bar items. This style is not part of classDefaultStyle. It replaces the style IToolbarButton::noDragDrop, which has been deprecated.

The style IToolBarButton::dragDelete enables the dragging and dropping of toolbar buttons to the shredder; the drag handler queries this style. This style is part of classDefaultStyle. It replaces the style IToolbarButton::noDragDelete, which has been marked as deprecated. Specifying this deprecated style has no effect. Although buttons could originally be dropped on the shredder, to get this style, you must now use the classDefaultStyle or specify the style explicitly.

There is a new override of IToolBar::layout.

There is a new performance setting, IPerformanceSettings::dynamicToolBarButtons. The setting effects the behavior of the following toolbar button functions:

With the setting enabled, these functions will dynamically change the settings of all IToolBarButtons created with the IToolBarButton::standardFormat style. Calling these functions causes existing tool bar buttons to adopt the new settings immediately. Each button will resize and redraw with the new settings.

Without this setting enabled, calling these functions causes default settings to be used during the creation of any toolbar buttons that are subsequently created with the IToolBarButton::standardFormat style. This does not affect existing toolbar buttons. By default, this setting is not enabled, which provides for better tool bar performance.

New Default Tool Bar Buttons

The new Lotus toolbar buttons with Open Class Library is included with this product.

IToolBar::Style and IToolBarContainer::Style changes

IToolBar::Style and IToolBarContainer::Style has been changed so that you can no longer combine style objects of these types with ISetCanvas::Style objects. Today, if you do specify an orientation or alignment via ISetCanvas::Style objects when constructing an IToolBar or IToolBarContainer, these values are essentially ignored because both IToolBar and IToolBarContainer explicitly set the orientation and alignment themselves. The only ISetCanvas styles that you can effectively set are the packing styles. The packing styles can also be set by calling ISetCanvas::setPackType, and ISetCanvas::decksByGroup. which IToolBarContainer gives you by default.

The ability to use IWindow, ICanvas, and ISetCanvas styles on the IToolBar constructor has been deprecated. IToolBar currently does not pass IWindow styles to the public ISetCanvas constructor it calls, and it essentially ignores extended styles. This is because it explicitly configures the ISetCanvas using function calls. Using application-specified IWindow, ICanvas, and ISetCanvas styles could break existing code. This behavior also applies to IToolBarContainer::Style.

Transparency in Tool Bars

To optimize performance, this product no longer supports transparency by default. The product added the IToolBarButton::transparentBitmap to provide transparency support. Here are the two places in which transparent bitmaps are used within toolbar buttons:

To avoid transparency overhead, this product introduces a new style for IToolbarButtons buttons called IToolBarButton::transparentButton. This style is not set on as the default.

For the IOC supplied bitmaps (IC_ID_OPEN, etc), this product supplies non-transparent bitmaps, and skips any transparency related code. If you want to use the existing transparency function, this product ships the existing IOC bitmaps under new IDs, such as IC_ID_OPEN_WITH_TRANSPARENCY, and requires you to use the new bitmap IDs and set the IToolBarButton::transparentButton style for the button. For user supplied bitmaps, the default is that transparency is turned off. If you want transparency and you supply a transparent bitmap, you must turn the style on for those buttons.

The transparentButton style affects both buttons drawn in an up state and those drawn in a latched state. Without the style set for a button, if the button is drawn in the latched state when the button view is bitmap only, you see the non-transparent latched look. The button is painted as if in the down state, with a slight half-toned look just inside the border and around the bitmap.

When the button view is bitmap and text, the button background color around the text area, which you can configure, might not match the non-transparent gray of the bitmap. In this case, you have the option to use a transparent bitmap for up state and latched buttons. You must make this choice at button creation, or use the function, IToolBarButton::enableTransparency(bool enable = true).

IWindow Changes

Reparenting of windows is not supported on Motif. This is a Motif-only restriction requiring that any window added to a toolbar must be a child of that toolbar.

You can still add previously created windows to a toolbar on OS/2 and Windows since IOC will reparent the window automatically.

Canvas Classes

This product added the following function to ICanvas to determine if windows have been added to the canvas.You may need to override this function in your own ICanvas derived classes.

virtual bool
  hasChildrenToLayout ( ) const;

New Protected Constructor for ISetCanvas

This product added the following protected functions to ISetCanvas to simplify the construction of derived classes and support delayed window creation:

ISetCanvas ( );
ISetCanvas
&initialize ( unsigned long windowId,
	     IWindow* parent,
	     IWindow* owner,
             const IRectangle& initialRect,
	     unsigned long style,
             unsigned long extendedStyle );

Calling the protected constructor does not create a presentation system window. However, you can create a canvas presentation system window by calling initialize. The style arguments are of type unsigned long so that styles defined by a class derived from ISetCanvas can also be used.

IToolBar and IToolBarContainer call this protected constructor, which gives a set canvas with a default configuration but no underlying presentation system window. IToolBar and IToolBarContainer later call ICanvas::initialize to create the presentation system window.

Border Support

ICanvas now has the capability to draw a border with text. Previously, ISetCanvas was the only canvas class with this support. ICanvas provides the following public members to provide this support:

static const Style
 ICanvas::border;
static INotificationId const
 ICanvas::borderTextId;
virtual ICanvas&addBorder ( ),
 &removeBorder ( ),
 &setBorderText ( const IText& borderText, bool showBorder=true),
 &setBorderText ( const IResourceId& borderText, bool showBorder=true), 
 &setBorderColor ( const IColor& borderColor),
 &resetBorderColor ( );
virtual bool
 hasBorder ( ) const; 
IText
 borderText ( ) const;
 virtual IColor
borderColor ( ) const;

Notes:

You can query and set the color or font of the border text using the IText class.

The following protected members were added to ICanvas for derived classes to implement layout within a border:

IPoint
 topLeftLayoutOffset ( ) const,
 bottomRightLayoutOffset ( ) const;
IRectangle
 rectangleInsideBorder ( const ISize& sizeWithBorder ) const;
ISize
 sizeWithBorder ( const ISize& sizeWithoutBorder ) const;

The following member from ISetCanvas was removed:

static const Style
ISetCanvas::border;

The following member of ISetCanvas has changed its behavior::

ISetCanvas::setText(); // if specifying text, change to call setBorderText(text, true), else 
		       // change to call removeBorder.
ISetCanvas::text()    // change to call borderText

The following member of ISetCanvas was deprecated:

static INotificationId const
ISetCanvas::textId; // Replaced by ICanvas::borderTextId.

Explicitly Adding and Removing Child Windows from ISetCanvas

An interface that allows you to add and remove child windows from the layout of a set canvas was added. This feature allows:

To simplify layout processing in ISetCanvas, tthe application should specify at construction time whether it is using the add/remove interface. Use the following style to do this:

 ISetCanvas::explicitAddsNeeded 

The following interface for the application to add/remove child windows to the layout of the canvas was added:

virtual ISetCanvas
 &add ( IWindow* child ),
 &remove ( IWindowl* child),
 &replaceChildWith ( IWindow* existingChild IWindow* newChild );

bool
 areExplicitAddsNeeded() const

Notes:

To query whether a set canvas is managing the size and position of a child window, the following was added:

virtual bool
 isInLayout ( IWindow* child ) const;

This function returns true for a child window if you

This function returns false for a child window if you

IViewPort Performance

The following added interface improves IViewPort performance by allowing the viewport child (view window) to be set:

virtual IViewPort
 &setViewWindow ( const IWindowHandle& viewWindow );

This portable interface boosts IViewPort performance on both OS/2 and Windows by avoiding the child window lookup currently required to find the view window to scroll on each scroll message. This interface also allows you to easily change the window that a view port scrolls.

Note: The restriction of allowing only a single view window per viewport is removed and an exception is no longer thrown when mutiple view windows exist. If setViewWindow is not called, the first view window found is used as the viewports' view window. In order to replace a view window with a different view window, you must issue setViewWindow. The previous view window is hidden.

IWINDOW Changes

Window Owner versus Parent

The usage of an owner different from the parent is discouraged in child windows. In top level windows (IFrameWindows, typically), owner and parent remain distinct and are supported portably as such. A top level window owned by another top level window remains above its owner in the Z order and will be closed when its owner is closed. Modality is also with respect to the owner. In IFrameWindow, the parent window is the one that is less portable. An IFrameWindow usually has a parent of 0 or IWindow::desktopWindow, which is the portable variant. Setting the parent of an IFrameWindow to another window can be useful in some scenarios but is less portable. In particular, an IFrameWindow child of another IFrameWindow will behave differently on the three platforms.

From an API perspective, there is no change - constructors which took both a parent and an owner continue to do so, even if the owner is ignored. This product does not provide parent-only-required constructors. In essence, the change here is one of documentation. The additional parameters are not needed and will be ignored but behavioural changes may occur on OS/2 if specific behaviour was expected when the parent was different from the owner.

Changes to IObjectWindow and IWindow for Support of "bound" Windows

In previous releases, the notion of a primary window as defined by the operating system, and the concept of a window requiring that the message queue persist for the lifetime of that window, were treated as a single concept. Both concepts are useful, and they are now treated as distinct in the interface, as follows:

/* New interface in IObjectWindow */

public:
class Style;
IObjectWindow ( const IObjectWindow::Style& style = defaultStyle() );

INESTEDBITFLAGCLASSDEF0( Style, IObjectWindow );
static const Style
 IC_IMPORTU classDefaultStyle,
 IC_IMPORTU boundToMessageQueue,
 IC_IMPORTU noStyle;
static Style
 defaultStyle ( );
 
static void
 setDefaultStyle ( const Style& style ); 
private:

INESTEDBITFLAGCLASSFUNCS(Style, IFrameWindow);
static Style 
 fCurrentDefaultStyle;

 

/* New interface in IWindow */
protected:
IWindow
 &bindMessageQueue ( );
bool
 isBoundToMessageQueue ( ) const; 

In several classes (the canvases), collections of objects are created that are nothing more than a pointer to an IWindow and a bit of extra data needed by the class that is specific to the IWindow. These collections are needed because there is no way to extend the data of an IWindow from outside the object. Keeping these collections of objects have their own problems because they must be kept up to date so that they accurately represent not only the child windows of a parent object but they typically need to do so in sibling order. This requirement is difficult enough that ISetCanvas rebuilds the collection each time it does layout so that it is accurate.

Extensions to the data of an IWindow are now allowed. IWindow is updated to store an array of pointers to objects. Any class that needs to store data in an IWindow object first queries to receive a magic token which it uses to store and retrieve data from an IWindow object (the magic token is implemented as an index into the array of pointers). Instead of creating collections of objects to represent additional data, classes like the canvases define and create an object that they store as additional IWindow data. They then use IWindow::ChildCursor to walk through the IWindow children and retrieve their extended data. Support has been added to IWindow::ChildCursor to allow it to visit only IWindow children.

The following classes and members have been implemented:

A new version of IWindow::create that takes an IWindow* for parent and owner instead of IWindowHandles has been added. Use this new create when you subclass an IWindow object. The library then ensures that the correct handle for the creation ( parent->handleForChildCreation) of the control is used.

The use of handle on Motif was different from its use on Windows and OS/2. If an aggregate could have children, such as IFrameWindow and IViewPort, handle was used as the parent of the child. Windows and OS/2 get around this problem by using a setParent to change the parent of the child to the correct control. Motif can not use this technique because reparenting is not available. Motif had a topHandle and a handle so that children of a control can have a different parent handle than the handle used for geometry management. In Motif, the topHandle was the handle of the control ( widget ) that encompassed all of the widgets of the aggregate. The topHandle was used for geometry management of the control such as moving and sizing the control. The problem with topHandle is that it was Motif only and had the same meaning as handle does on OS/2 and Windows.

A new member function returns the handle that a child of a control should use as their parent. When a control is created and an IWindow* is specified as the parent, handleForChildsParent is used instead of handle. The default implementation of handleForChildsParent just returns handle. Any subclass that needs a different implementation, like IViewPort, overrides this member function and returns the appropriate handle.

Here are the changes to IWindow:

#ifdef IC_PMWIN
virtual IWindowHandle
 create ( unsigned long id,
	  const char* text, 
          unsigned long style,
          const char* windowClass,
          const IWindowHandle& parent,
	  const IWindowHandle& owner,
          const IRectangle& initRect,
          const void* ctlData,
          const void* presParams,
          IWindow::SiblingOrder ordering = defaultOrdering(),
          unsigned long extendedStyle = 0 );
virtual IWindowHandle
  create ( unsigned long id,
           const char* text,
           unsigned long style,
           const char* windowClass,
           const IWindow* parent,
           const IWindow* owner,
           const IRectangle& initRect,
           const void* ctlData,
           const void* presParams,
           IWindow::SiblingOrder ordering = defaultOrdering(),
           unsigned long extendedStyle = 0 );
#endif
#ifdef IC_MOTIF
virtual IWindowHandle
create ( unsigned long id,
	 const char* text,
	 unsigned long style,
	 IXmCreateFunction createFunction,
	 const IWindowHandle& parent,
	 const IWindowHandle& owner,
         const IRectangle& initRect,
         const void* callerArgList,
         const unsigned int callerNumberArguments,
         IWindow::SiblingOrder ordering = defaultOrdering(),
         unsigned long extendedStyle = 0 );
virtual IWindowHandle
create ( unsigned long id,
	 const char* text,
         unsigned long style,
         IXmCreateFunction createFunction,
       	 const IWindow* parent,
         const IWindow* owner,
         const IRectangle& initRect,
         const void* callerArgList,
         const unsigned int callerNumberArguments,
         IWindow::SiblingOrder ordering = defaultOrdering(),
         unsigned long extendedStyle = 0 );
#endif //IC_MOTIF

The implementation of the new create just uses the old create passing through the correct handles.

For example:

| IWindow::create |
| This create will take care of the using correct parent's handle for the creation of children.
------------------------------------------------------------------------------*/
IWindowHandle IWindow::create( unsigned long id,
			  	const char* text,
				unsigned long style,
				IXmCreateFunction createFunction,
				const IWindow* parent,
				const IWindow* owner,
				const IRectangle& initRect,
				const void* callerArgList,
				const unsigned int callerNumberArguments,
				IWindow::SiblingOrder ordering,
				unsigned long extendedStyle )
{
return this->create( id,
		text,
		style
		createFunction,
		parent->handleForChildsParent(),
		owner->handle(),
		initRect,
		callerArgList,
		callerNumberArguments,
		ordering,
		extendedStyle );
}

Summary

Motif

topHandle is replaced with handle ; topHandle is deprecated . Do not call addRelated or rely on windowWithHandle working on anything but the registered handle.

All Platforms
Override handleForChildCreation if you are an aggregate that can have children.
Call IWindow::create with your parent's handleForChildCreation ( instead of handle ) or use the new IWindow::create override.

Keyboard

The following data types are deprecated as they provide little utility and are nonportable:

public:
#ifdef IC_MOTIF
static unsigned long
IC_IMPORTU ulShiftMask,
IC_IMPORTU ulAltMask,
IC_IMPORTU ulCtrlMask;
#endif
protected:
#ifndef IC_WIN_FLAGNOP
static const unsigned long
IC_IMPORTU ulCharacterFlag,
IC_IMPORTU ulScanCodeFlag,
IC_IMPORTU ulVirtualFlag,
IC_IMPORTU ulRepeatFlag,
IC_IMPORTU ulUncombinedFlag,
IC_IMPORTU ulShiftFlag,
IC_IMPORTU ulCtrlFlag,
IC_IMPORTU ulForCompositeFlag,
IC_IMPORTU ulCompositeFlag,
IC_IMPORTU ulInvalidCompositeFlag;
#endif
static const unsigned long
 IC_IMPORTU ulUpTransitionFlag,
 IC_IMPORTU ulAltFlag;

Frame Window

Users who wish only to set the title text on a frame window now have a simple, straightforward, portable way to do this. You no longer have to create an ITitle object to have title text on a frame window.

The following new functions have been added to IFrameWindow:

virtual IFrameWindow& 
 setTitleText ( const IString& titleText ),
 setTitleText ( const IResourceId& titleResId );
virtual IString
 titleText ( ) const;

A notification to IFrameWindow for text changes has also been added:

static INotificationId const
IC_IMPORTU titleTextId;

Inheritance

Classes that inherit from either IBase or IVBase no longer exist.

These new classes and functions have been added::

There is a new member function on a GrafPort, that allows you to get the transformation matrix that converts from GCoordinates to pixels, for example:

aPort.GetDeviceTransform(IGrafMatrix &aGrafMatrix);

However, it is not necessary to know this in order to convert back and forth between ideal coordinates and device coordinates (pixels).

Summary of new function:

Color

New color support has merged with the existing IColor class. The following changes have occurred:

The IBaseColor class had replaced IBasicColor and IColor became a subclass of IBaseColor. IBasicColor still exists for backward compatibility.

Threads

A GUI thread class and a non-GUI thread class are now available. The new classes are:

Menus

In the past, you could call any IWindow function on an IMenu even though the function did not do anything under Windows. For this release, you can only call IWindow methods by first calling IMenu::window() to get the underlying window; this method is only supported under OS2 and Motif. Selected IWindow methods have been added to IMenu or one of its derived classes and implemented there in a portable way. The menu hierarchy has changed. IMenu no longer derives from IWindow.

foregroundColor and backgroundColor have been added to the new menu headers. Since these two colors on Win32 actually apply to all menus in the system, this product does not support setXXXColor.

Version Number

Use of the IVersion::libraryVersion() method is the preferred way of querying library version number.

IC_MAJOR_VERSION is set to 360 and IC_OBSOLETE is set to 400 for IC_PM, IC_WIN, and IC_AIX. IC_MINOR_VERSION is set to 0.

ICONTROL

The group and tabStop styles and their associated functions have moved from IControl to IWindow.

Container

New interface for IContainerObject

The following functions set a special in-use icon to be used for this particular object in all containers it exists in:

The behavior is as follows:

Graphics

The 2D graphics provided in VisualAge for C++ Version 3.0 and 3.5 has been deprecated. The product now provides Taligent 2D graphics.

ICoordinateSystem and Application Origin:

To provide the capability to write portable applications, this product does the following:

  1. If an application does not call ICoordinateSystem::setApplicationOrientation(),
    then the orientation defaults to upper-left. This behavior differs from previous releases, where the application
    orientation was upper-left for Windows and lower-left for OS/2.
  2. For the AIX release:

Examples:

function() {
	ICoordinateSystem::setApplicationOrientation(ICoordinateSystem::kOriginLowerLeft);
	IExtendedRootGrafPort aPort(hps); // origin defaults to appOrientation, lower left
}
function() {
	ICoordinateSystem::setApplicationOrientation(ICoordinateSystem::kOriginUpperLeft);
	IExtendedRootGrafPort aPort(hps); // origin defaults to appOrientation, upper left
}

function() {
	IExtendedRootGrafPort aPort(hps); // origin defaults to upper left
}

function() {
	IExtendedRootGrafPort aPort(hps, ICoordinateSystem::kOriginUpperLeft); // origin always upper left
									       // regardless of SetApplicationOrientation()
}


function() {
	IExtendedRootGrafPort aPort(hps, ICoordinateSystem::kOriginLowerLeft); // origin always lower left
									       // regardless of SetApplicationOrientation()
}

Combobox

The current combo box can not drop down past its parent's area. This limitation has been removed by parenting the listbox portion of a drop down combo box to a shell. This enhancement has been implemented to support toolbars. This is an AIX-specific enhancement (it already behaves this way on OS/2 and Windows).

Boolean Type Definition

Boolean has been changed to bool to meet ANSI standards.

Scroll Bar

The IScrollBar class currently contains the autoSize style. This style is supported on PM and Motif, but is not supported in Windows. In PM, specification of the autoSize style results in a vertical scrollbar that will be automatically sized to the system scrollbar width if a width of 0 is specified, or a horizontal scrollbar that will be automatically sized to the system scrollbar height if a height of 0 is specified. In Motif, this style was implemented in the class library to always force the scrollbar width (height) to the (hardcoded) system default dimension.

The IScrollBar::autoSize style in PM has been deprecated and removed from Motif for the following reasons, which assume vertical scrollbar:

ICUSTOMBUTTON

IToolBarButton inherits from ICustomButton. The default protected ICustomButton constructor attaches a default ICustomButtonDrawHandler handler. The current implementation of IToolbarButton makes the ICustomButton default handler unnecessary. IAnimatedButton also uses this ICustomButton constructor and also does not need the default ICustomButtonDrawHandler. Each tool bar button incurred the overhead of the additional handler attached to it. For performance reasons, this handler has now been removed and the following changes made. This product has

You cannot override the default paint handler for custom buttons. Use the two new functions or if the class derived from ICustomButton wants to use the default paint handler, call the addDefaultDrawHandler function to add the handler. This is a change in behavior because such a class used to get the handler added automatically. However, a derived class that has its own paint handler derived from the ICustomButtonDrawHandler will not see any behavior changes and might see some performance improvements.

IMOUSEPOINTERHANDLER

This class is ignored on Motif (it will override no event-handling callback functions). IMousePointerHandler still overrides mousePointerChange on Windows and OS/2.

New Classes

IManagedPresSpaceHandle

Due to the circular dependencies between Open Class and the new graphics classes, this product has removed IWindowHandle from the interface of graphics and replaced it with a new class, IManagedPresSpaceHandle.

IManagedPresSpaceHandle puts the responsibility for managing the lifetime of the handle on the client. The class contains constructors, from both an IWindow* and const IWindowHandle&, that acquire the handle. It also contains a destructor to free the handle and an operator IPresSpaceHandle so an object of the class can be passed to any function that takes an IPresSpaceHandle.

This new class is implemented in imngpres.* and the new interface is as follows:

class IManagedPresSpaceHandle
{
  public:
  IManagedPresSpaceHandle ( IWindow* window);
  IManagedPresSpaceHandle ( const IWIndowHandle& windowHandle);
  ~IManagedPresSpaceHandle ( );
  operator IPresSpaceHandle ( );
}

New Interface in IWindow for Event Dispatching & Associated Changes to IMouseHandler

Our enhanced mouse handler now supports mouse move messages, whereas the original Motif implementation did not. This handler does not work on Motif today because none of the Widgets request move messages(limited exceptions to this rule, like sash widget in ISplitCanvas). We cannot use our current handler philosophy on Motif, which basically states that we register all callbacks that a handler may be interested in seeing.

Motif is designed to be a server client and is set up to work over a network. This design forces Motif applications to try to cut down on network traffic by asking an application to register only the necessary events on a per widget basis. We have to be selective in what events we request especially with an event that occurs as often as a mouse move. We have enhanced the current interface to specify which controls (widgets) we want to see mouse move events for.

New interface on IWindow for Event Dispatching

The following functions to allow event handlers for a window to receive or not receive certain messages have been added:

where EventMask is a nested class that derives from IBitFlag. The public static event masks that IWindow provides are:

On OS/2 and Windows, someMouseMoves and allMouseMoves are equivalent. Specifying mouseEntersLeaves causes someMouseMoves to be enabled as well on some platforms ( Windows NT). Calling stopHandling prevents any handlers from being called for that window to process the specified type of event. Conversely, calling startHandling allows handlers to be called for the event.

Calling stopHandling does not prevent IWindow::defaultProcedure from being called. No attempt is made, however, to call private default handlers of a window. Therefore, turning off receipt of messages can change default behavior of a window. For example, it can prevent the user from being able to move split bar of an ISplitCanvas on OS/2 or Windows.

Reference counting to allow multiple calls to startHandling and stopHandling for an event type is used. A default bool argument to stopHandling to force off receipt of messages to handlers, regardless of the reference counting state has been implemented. By default, handlers of all windows will receive all events on OS/2 and Windows. For performance reasons, Motif handlers will not receive mouse move or mouse enter/leave events by default. Note that generally an application should not need to call these functions. To cover the most common case where these functions need to be called, we are enhancing IMouseHandler to call them on the application's behalf.

Cases where an application will need to call IWindow::startHandling or stopHandling include:

Style Added to IMouseHandler

An optional style argument to the IMouseHandler constructor has been added. These styles dictate the type of mouse messages that the handlers of the window can receive. As a result, they actually affect more than just the single mouse handler. The constructor now looks like:

MouseHandler ( const Style& style = defaultStyle() );

where Style is a nested class that derives from IBitFlag. The public static styles that IMouseHandler provides are:

The default style is someMouseMoves. This supports backward compatibility with existing mouse handlers written for OS/2 and Windows by requesting a portion of the mouse move events for the window's handlers. On OS/2 and Windows, someMouseMoves and allMouseMoves are equivalent. The IMouseHandler constructor calls IWindow::startHandling or stopHandling as appropriate (these styles map to the EventMask flags). If the application constructs the handler with the noMouseMoves style, then code to be added to IMouseHandler::dispatchHandlerEvent prevents its mouseMoved virtual function from being called even if the handler does receive a mouse move event. The same rule applies to not specifying the mouseEnters or mouseLeaves style. In this case the new mouseEnter and mouseLeave virtual functions described at the bottom of this document are never called.

The following standard auxiliary style members are added to IMouseHandler:

Deprecated IMouseHandler::mousePointerChange

In order to increase performance on Motif with processing mouse messages, this product has deprecated IMouseHandler::mousePointerChange. This functionality can be better handled by calling IFrameWindow::setMousePointer. To be able to change the mouse pointer dynamically based on what portion of the window the mouse is over, override IMouseHandler::mouseMoved to call IWindow::setMousePointer (mouseMoved is the best place for determining that the mouse changed and its location). You could get inconsistent behavior if you use both IWindow::setMousePointer and an IMouseHandler to change the mouse pointer for a window, depending on the order that you call setMousePointer and attach the handler (and whether the handler returns true or false).The product does not implement this virtual function on Motif.

Pointer Enter/Leave Support

The following protected virtual functions in IMouseHandler are new:

virtual bool
IMouseHandler::mouseEnter ( IEvent& event ),
IMouseHandler::mouseLeave ( IEvent& event );

IMouseHandler calls these virtual functions when the mouse pointer crosses the dispatching window's boundary.

The return value from processing the mouseEnter and mouseLeave virtual function has no effect on whether the mouseMoved virtual function gets called. The same is true the other way around as well. IMouseHandler does not support a time delay (your application can use ITimer to achieve this support).

Make IMousePointerEvent Available on OS/2 and Windows Only

This class is not implemented on Motif, but it is not deprecated either. In the class library it is only used by the deprecated IMouseHandler::mousePointerChange function and the IC_PMWIN-only IMousePointer class.

IMouseConnectionTo Deprecated

This class template has been deprecated and it is not implemented on Motif. Replace all usage of IMouseConnectionTo with one of the following two classes, as appropriate:

IMouseClickConnectionTo
IMouseMoveConnectionTo

Toolbar on Motif

This release of the Open Class Library now contains IToolBar, IToolBarButton and the other toolbar related classes with limited functionality.The following Motif toolbar functionality is provided at this time:

Due to Motif system restrictions, certain toolbar movements are restricted. (A new function IToolBar::isMoveValid() has been created to verify toolbar movements. See the Open Class Reference for details on this function as well at toolbar movement restrictions.)

The following Motif toolbar functionality has not been implemented at this time, but is planned for the next release:

The following sections define deprecated and ignored functions and explain how to use these functions in the Open Class Library. To develop portable applications, you should be aware of these conventions.

Deprecated Functions

As the Open Class Library functionality increases, there are situations where we must change the interface to improve the quality and design. We identify the interface that is deprecated and provide this information so you can migrate to replacement classes and functions.

There are several important guidelines regarding deprecated functions:

The following are changes in the language/methods/enums/types in this release of the IBM Open Class Library:

Type Name Replaced by
class IBase  
structure IBase::Version IVersion
function IBase::asString() const IStringGenerator::stringFor() const (where the IStringGenerator was constructed passing in an instance of an IStringGeneratorasString generator function)
class IBasicColor IBaseColor
class IGArc IGCurve2D
class IGBitmap IGImage, IImage
class IGEllipse IGEllipse2D, IEllipse
class IGLine IGLine2D, ILine
class IGList IGraphicGroup
class IGPie IGPie2D, ICurve
class IGPolyline IGPolyline2D, IGPolyline
class IGraphic IMGraphic
class IGraphicBundle IGrafBundle
class IGraphicContext IGrafPort
class IGRectangle IGRect2D, IPolygon
class IGRegion IGArea, IArea
class IGString IGraphicText
class IRootGrafPort IExtendedRootGrafPort
class ITransformMatrix  
class IWindow::BidiSettings IBidiSettings
class IMouseConnectionTo IMouseClickConnectionTo and IMouseMoveConnectionTo
typedef Boolean bool
typedef IBaseErrorInfo::IErrorInfo IBaseErrorInfo
typedef IColor::SysColor IColor::SystemColor
typedef IContextHandle IAnchorBlockHandle
typedef ICoordinateSystem::Orientation ICoordinateSystem::EOrientation
enum IColor::Color IBaseColor::EPredefinedColor
enum IColor::SystemColor IColor::ESystemColor
enum EDeviceCoordinateSystem ICoordinateSystem::EOrientation
enum IImage::EDitherType IGImagePixelAccessor::EDitherType
enum IImage::EImageFormat IGImagePixelAccessor::EImageFormat
enum INonGUIApplication::PriorityClass INonGUIApplication::EProcessPriority
enum IWindow::BidiLayout IBidiSettings::BidiLayout
enum IWindow::BidiNumeralType IBidiSettings::BidiNumeralType
enum IWindow::BidiTextOrientation IBidiSettings::BidiTextOrientation
enum IWindow::BidiTextShape IBidiSettings::BidiTextShape
enum IWindow::BidiTextType IBidiSettings::BidiTextType
constructor IBidiSettings (const IGraphicContext&) IBidiSettings(const IGrafPort&)
constructor IBitFlag (unsigned long) IBitFlag(unsigned long, const unsigned long[])
constructor IBitFlag (unsigned long, unsigned long) IBitFlag(unsigned long, const unsigned long[])
constructor IColor(Color color) IColor(IColor::EPredefinedColor)
constructor IColor(SystemColor value) IColor(IColor::ESystemColor)
constructor IColor(unsigned long pixel) IColor(long index)
constructor IImage(IPresSpaceHandle psh, int , int)  
constructor IImage(const IString& .....) IGImagePixelAccessor
data IEntryField::lowerCase Create a handler to convert characters to lowercase
data IEntryField::upperCase Create a handler to convert characters to uppercase
data IKeyboardEvent::ulAltFlag  
data IKeyboardEvent::ulAltMask  
data IKeyboardEvent::ulCharacterFlag  
data IKeyboardEvent::ulCompositeFlag  
data IKeyboardEvent::ulCtrlFlag  
data IKeyboardEvent::ulCtrlMask  
data IKeyboardEvent::ulForCompositeFlag  
data IKeyboardEvent::ulInvalidCompositeFlag  
data IKeyboardEvent::ulRepeatedFlag  
data IKeyboardEvent::ulScanCodeFlag  
data IKeyboardEvent::ulShiftFlag  
data IKeyboardEvent::ulShiftMask  
data IKeyboardEvent::ulUncombinedFlag  
data IKeyboardEvent::ulUpTransitionFlag  
data IKeyboardEvent::ulVirtualFlag  
constructor INonGUIThread(const IReference<IThreadFn>&) INonGUIThread(IThreadFn*)
function IBidiSettings::apply(const IGraphicContext&) apply(const IGrafPort&)
function IBitFlag::asExtendedUnsignedLong ( ) const No true replacement. Classes using IBitFlag objects must provide their own mapping logic (IWindow::convertToGUIStyle is an example).
function IBitFlag::asUnsignedLong ( ) const No true replacement. Classes using IBitFlag objects must provide their own mapping logic (IWindow::convertToGUIStyle is an example)
function IBitFlag::setValue(unsigned long, unsigned long) IBitFlag::setValue(const IBitFlag&)
function ICanvas::defaultPushButton ( ) const IWindow::defaultEmphasisButton
function ICanvas::origDefaultButtonHandle ( ) const IWindow::defaultPushButton
function IClipboard::setOwner Specify the owner when constructing the IClipboard (construct a new IClipboard object if necessary)
function IColor::asPixel() const IColor::index()
function IColor::systemColor() const IColor::runtimeGuiColor()
function IColor::value() const IColor::predefinedColor
function ICurrentThread::appContext ICurrentThread::anchorBlock
function ICurrentThread::appShell IThread::applicationShell or IWindow::desktopWindow()->handle()
function ICustomButtonDrawEvent::graphicContext ICustomButtonDrawEvent::grafPort
function IDrawingCanvas::graphicContext IDrawingCanvas::grafPort
function IDrawingCanvas::graphicList IDrawingCanvas::graphicGroup
function IDrawingCanvas::setGraphicContext IDrawingCanvas::setGrafPort
function IDrawingCanvas::setGraphicList IDrawingCanvas::setGraphicGroup
function IEntryField::hasChanged IEntryField::hasTextChanged
function IEntryField::setChangedFlag IEntryField::setTextChangedFlag
function IImage::loadFromFile IGImagePixelAccessor::loadFromFile
function IImage::writeToFile IGImagePixelAccessor::writeToFile
function IInfoArea::handleEventsFor IInfoArea::startShowingMenuInfoFor
function IInfoArea::inactiveText disabledText
function IInfoArea::setInactiveText setDisabledText
function IInfoArea::stopHandlingEventsFor IInfoArea::stopShowingMenuInfoFor
function IMouseHandler::mousePointerChange IMouseHandler::mouseEnter and mouseLeave (or mouseMoved), calling IFrameWindow::setMousePointer
function IMultiLineEdit::setChangedFlag IMultiLineEdit::setTextChangedFlag
function IMultiLineEdit::resetChangedFlag IMultiLineEdit::resetTextChangedFlag
function IMultiLineEdit::isChanged IMultiLineEdit::hasTextChanged
function INonGUIApplication::adjustPriority INonGUIApplication::setProcessPriority
function INonGUIApplication::setPriority INonGUIApplication::setProcessPriority
function INonGUIThread::priorityLevel INonGUIThread::threadPriority
function INonGUIThread::setPriority INonGUIThread::setThreadPriority
function INonGUIThread::  
function INotificationEvent::setNotifierAttrChanged(booltrue)  
function INotificationEvent::setEventData(const IEventData&)  
function INotificationEvent::setObserverData(const IEventData&)  
function INotificationEvent::hasNotifierAttrChanged  
function INotificationEvent::eventData  
function INotificationEvent::observerData  
function INotificationEvent::notifier  
function INotifier::addObserver( IObserver&, const IEventData&)  
function IPaintEvent::setGraphicContext IPaintEvent::setGrafPort
function IResourceLibrary::loadAccelTable(unsigned long, const IWindowHandle&) IResourceLibrary::loadAccelTable(unsigned long)
function ISetCanvas::setText ICanvas::setBorderText
function ISetCanvas::text ICanvas::borderText
function IStandardNotifier::addObserver(IObserver&, const IEventData&)  
function IWindow::addObserver( IObserver&, const IEventData&)  
function IWindow::applyBidiSettings IBidiSettings::apply
function IWindow::enableFastWindowWithHandle(bool enable = true) IWindow::reserveUserWindowWord
function IWindow::isBidiSupported IBidiSettings::isBidiSupported
function IWindow::isFastWindowWithHandleEnabled() IWindow::isUserWindowWordReserved
constant True true
constant False false
constant ICommand::kCopyToId kSaveAsId
constant ICoordinateSystem::originLowerLeft ICoordinateSystem::kOriginLowerLeft
constant ICoordinateSystem::originUpperLeft ICoordinateSystem::kOriginUpperLeft
constant IEntryField::lowerCase  
constant IEntryField::upperCase  
constant IHelpWindow::using usingHelp
constant IKeyboardEvent::ulAltFlag  
constant IKeyboardEvent::ulAltMask isAltDown()
constant IKeyboardEvent::ulCharacterFlag  
constant IKeyboardEvent::ulCompositeFlag  
constant IKeyboardEvent::ulCtrlFlag  
constant IKeyboardEvent::ulCtrlMask isCtrlDown()
constant IKeyboardEvent::ulForCompositeFlag  
constant IKeyboardEvent::ulInvalidCompositeFlag  
constant IKeyboardEvent::ulRepeatFlag  
constant IKeyboardEvent::ulScanCodeFlag  
constant IKeyboardEvent::ulShiftFlag  
constant IKeyboardEvent::ulShiftMask isShiftDown()
constant IKeyboardEvent::ulUncombinedFlag  
constant IKeyboardEvent::ulUpTransitionFlag  
constant IKeyboardEvent::ulVirtualFlag  
constant IProgressIndicator::armTickOffsetId armChangeId
constant IProgressIndicator::armPixelOffsetId armChangeId
constant IScrollBar::autoSize  
constant IScrollBar::scrollBoxPositionId scrollBoxChangeId,
scrollBoxTrackId
constant IString::and bitAnd
constant IString::or bitOr
constant IString::exclusiveOr bitExclusiveOr
constant IToolBar::hidden  
constant IToolBar::noDragDrop  
constant IToolBarButton::noDragDelete  
constant kLeftHand ICoordinateSystem::kOriginUpperLeft
constant kRightHand ICoordinateSystem::kOriginLowerLeft