IContainerObject

The IContainerObject class is a required base class for all objects stored in a container. You must create all objects of this class using operator new, which is overloaded in this class to provide the storage allocation required by the underlying operating system's container control.

You can use an IContainerObject object, as is, for all container views except the details view. For the details view, you must derive a class from IContainerObject to support additional data. If you do, the additional data must be the following:


Note: You can only edit the string type. We recommend that you use the class IString to store text data in a derived object class.

We also recommend that you use a resource library to load icons because a resource library can do the following:

You can add IContainerObjects to multiple containers at the same time. When using functions in this class to modify an object's characteristics, the functions do so in all containers that hold the object. This is true only when the IContainerControl parameter for these functions is 0. IContainerControl provides functions that you can use to modify certain attributes of an object in a single container.

You cannot add the same container object twice in a container. Open Class Library keeps pointers to place the record in the container relative to other records. An IGUIErrorInfo exception is thrown if you try. You can create another copy of this container object using the IContainer copy constructor and add that object to the container.

On OS/2 and on Windows when using the pmCompatible container, the IContainerObject class wrappers the actual container item. When you update container column data, changes are immediately reflected on the screen. On Windows and AIX, the IContainerObject class is separate from the native container item. Changes to your container column data will not take effect until you call the IContainerControl::refresh member function.


IContainerObject - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IContainerObject


Overload 1
public:
IContainerObject(const IContainerObject& object)

Construct an IContainerObject object by copying an existing IContainerObject or a class derived from IContainerObject. If you derive from IContainerObject, provide a copy constructor in the class to ensure that the object is copied correctly.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IContainerObject( const IString& string, const IPointerHandle& iconHandle = 0 )

Construct an IContainerObject object by providing an IString for text and an IPointerHandle for the icon.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IContainerObject()

This provides the default constructor, which accepts no parameters.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IContainerObject( const IResourceId& nameID, const IResourceId& iconId )

Construct an IContainerObject object by providing resource IDs for both the text and the icon.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IContainerObject( const IString& string, unsigned long iconId )

Construct an IContainerObject object by providing an IString for text and an unsigned long to use as a resource ID for the icon.
Note: The Open Class Library provides this constructor to resolve a potential ambiguity because both IResourceIds and IPointerHandles can be built implicitly from an unsigned long integer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
IContainerObject( const IString& string, const IResourceId& iconId )

Construct an IContainerObject object by providing an IString for text and an IResourceId for the icon.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =
public:
IContainerObject& operator =( const IContainerObject& object )
Assigns the member data of an object of this class to another object of this class.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Attributes

These members implement the class.


[view class]
baseRecord
protected:
IMiniCnrRecord* baseRecord()

Returns the address of the real base of this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
decrementUseCount
protected:
virtual IContainerObject& decrementUseCount()

Decreases the count of containers having this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
incrementUseCount
protected:
virtual IContainerObject& incrementUseCount()

Increases the count of containers having this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
initialize
protected:
virtual IContainerObject& initialize()

Initializes an object after construction.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isAttribute
protected:
virtual bool isAttribute( unsigned long attribute, IContainerControl* container ) const

If the specified attribute is set to on, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAttributes
protected:
virtual IContainerObject& setAttributes( unsigned long attributeTurnedOff, unsigned long attributeTurnedOn, IContainerControl* container = 0 )

Sets some attributes to off while setting others to on. Use this function to toggle the state of mutually exclusive attributes. If you do not specify a container, the changes are made to all containers that have this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setBase
protected:
virtual IContainerObject& setBase( const IMiniCnrRecord* baseRecord )

Stores the address of the real base of this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setEmphasis
protected:
virtual IContainerObject& setEmphasis( unsigned long emphasisAttribute, bool turnOn = true, IContainerControl* container = 0 )

Sets the specified emphasis attribute to on or off. If you do not specify a container, the changes are made to all containers that have this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
useCount
protected:
unsigned long useCount() const

Returns the number of containers having this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Derived Class Provided Members

These members must be provided by a derived class if the behavior is required.


[view class]
handleCursoredChange
public:
virtual void handleCursoredChange( IContainerControl* container, bool acquired )

Called when cursored emphasis changes on an object and the IContainerControl containing the object has an ICnrHandler. If the object has just acquired cursored emphasis, acquired is set to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handleInuseChange
public:
virtual void handleInuseChange( IContainerControl* container, bool acquired )

Called when in-use emphasis changes on an object and the IContainerControl containing the object has an ICnrHandler. If the object has just acquired in-use emphasis, acquired is set to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handleOpen
public:
virtual void handleOpen(IContainerControl* container)

Called when the user either selects the Enter key when an object has the cursor or double-clicks the mouse select button on an object, and the IContainerControl containing the object has an ICnrHandler.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handleSelectedChange
public:
virtual void handleSelectedChange( IContainerControl* container, bool acquired )

Called when selection emphasis changes on an object and the IContainerControl containing the object has an ICnrHandler. If the object has just acquired selection emphasis, acquired is set to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handleTreeCollapse
public:
virtual void handleTreeCollapse( IContainerControl* container )

Called when this object is a parent in the tree view and the descendent objects have been collapsed. This is only called when the IContainerControl containing the object has an ICnrHandler.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handleTreeExpand
public:
virtual void handleTreeExpand(IContainerControl* container)

Called when this object is a parent in the tree view and the descendent objects have been expanded. This is only called when the IContainerControl containing the object has an ICnrHandler.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Called when an ICnrHelpEvent is dispatched to ICnrHandler. By default, this function returns 0. If the ID returned is greater than 0, the default behavior of the container's help handler is to display the help panel.

You can override this function in your classes that inherit from IContainerObject to provide the ID of a help panel to display when help is requested for this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
objectCopy
public:
virtual IContainerObject* objectCopy()

Called when it is necessary to make a copy of an object. This occurs when you call IContainerControl::copyObjectTo.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ==
public:
bool operator ==(const IContainerObject& object)

If the objects are at the same storage location, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Object Allocation

These members provide all object allocation and deallocation for instances of the class. Stack and static instances of this class are not allowed.


[view class]
operator delete

Deallocates the storage of an object of this class.


Overload 1
public:
void operator delete( void*, const char* fileName, size_t lineNumber )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
void operator delete(void*)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator new

Allocates storage for an object of this class.


Overload 1
public:
void* operator new(size_t size)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
void* operator new( size_t size, const char* fileName, size_t lineNumber, ICnrAllocator& allocator )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
void* operator new(size_t size, ICnrAllocator& allocator)

For example, if class ListItem is derived from class IContainerObject, you can create and add multiple objects to an IContainerControl using the following code :

ICnrAllocator allocator = new ICnrAllocator(itemCnt, sizeof(ListItem));

for (ix=0; ix < itemCnt; ix++) new (*allocator) ListItem(ix, someData);

container->addObjects(*allocator);

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
void* operator new( size_t size, const char* fileName, size_t lineNumber )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Object Information

Use these members to get and set the accessible attributes of this class.
Note: Because an object can exist in more than one container, many of these functions accept a container as an optional parameter. If the container is not specified, the function is applied to all containers that this object is in.


[view class]
disableDataUpdate
public:
virtual IContainerObject& disableDataUpdate( IContainerControl* container = 0 )

Disables user updates of this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
disableDrop
public:
virtual IContainerObject& disableDrop( IContainerControl* container = 0 )

Prevents any object from being dropped on this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
enableDataUpdate
public:
virtual IContainerObject& enableDataUpdate( bool enable = true, IContainerControl* container = 0 )

Enables user updates of this object if the container in which this object resides is enabled for direct editing.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableDrop
public:
virtual IContainerObject& enableDrop( bool enable = true, IContainerControl* container = 0 )

Allows other objects to be dropped on this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
hide
public:
virtual IContainerObject& hide( IContainerControl* container = 0 )

Makes this object invisible by filtering it out.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

The native Windows containers (that is, containers constructed without the pmCompatible style) do not support filtering of objects.


[view class]
icon
public:
virtual IPointerHandle icon() const

Returns the icon handle of an object. If this object does not have an icon, the icon handle is zero.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the text of an object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
inUseIcon
public:
virtual IPointerHandle inUseIcon() const

Returns the icon that is used when the object has in use emphasis. If no icon has been set using setInUseIcon, then the normal icon for the object is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isDropOnAble
public:
virtual bool isDropOnAble( IContainerControl* container = 0 ) const

If this object can accept a drop, true is returned. If container is 0 and this object is shared amongst multiple containers, this function returns true only if the object can be dropped-on in all of the containers. If you specify a container, this function only queries this object's state in the specified container.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
isInUse
public:
virtual bool isInUse( IContainerControl* container = 0 ) const

If this object has in-use emphasis, true is returned. If container is 0 and this object is shared amongst multiple containers, this function returns true only if the object is in use in all of the containers. If you specify a container, this function only queries this object's state in the specified container.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If this object is open, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If this object is in a refreshable state, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isVisible
public:
virtual bool isVisible( IContainerControl* container = 0 ) const

If this object is visible, true is returned. If container is 0 and this object is shared amongst multiple containers, this function returns true only if the object is visible in all of the containers. If you specify a container, this function only queries this object's state in the specified container.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

The native Windows containers (that is, containers constructed without the pmCompatible style) do not support filtering of columns.


[view class]
isWriteable
public:
virtual bool isWriteable( IContainerControl* container = 0 ) const

Returns true if the data in the object can be edited.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
refresh
public:
virtual IContainerObject& refresh( IContainerControl* container = 0, bool immediate = false )

Refreshes this object. The object's and container's refresh state must be set to on for this function to be valid. You can call IContainerObject::setRefreshOn to do so.

If immediate is set to true, the painting is done synchronously; that is, all container painting is completed before this function returns to the caller. If immediate is false, the container painting occurs asynchronously, and painting may not be completed when the function returns to the caller.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeInUse
public:
virtual IContainerObject& removeInUse( IContainerControl* container = 0 )

Removes the in-use emphasis for this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setClosed
public:
virtual IContainerObject& setClosed()

Removes the open emphasis in all containers.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setIcon

Sets a new icon for an object.


Overload 1
public:
virtual IContainerObject& setIcon( const IResourceId& iconId )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IContainerObject& setIcon( const IPointerHandle& iconHandle )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IContainerObject& setIcon(unsigned long iconId)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setIconText

Sets the new text for an object.


Overload 1
public:
virtual IContainerObject& setIconText( const IString& iconText )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IContainerObject& setIconText(const char* iconText)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IContainerObject& setIconText( const IResourceId& iconTextId )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setInUse
public:
virtual IContainerObject& setInUse( bool inUse = true, IContainerControl* container = 0 )

Sets the in-use emphasis for this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

The native Windows containers (that is, containers constructed without the pmCompatible style) do support the in-use emphasis but require that the icon have transparency. The hashed background is only displayed where the object's icon has transparency.


[view class]
setInUseIcon

Sets the icon that is used when the object has in use emphasis.


Overload 1
public:
virtual IContainerObject& setInUseIcon( const IPointerHandle& iconHandle )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

The icon is used in addition to the hashing shown for objects that are in use.


Overload 2
public:
virtual IContainerObject& setInUseIcon( unsigned long iconId )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IContainerObject& setInUseIcon( const IResourceId& iconId )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setOpen
public:
virtual IContainerObject& setOpen(bool open = true)

Sets the open emphasis. This function can be overridden by the application to provide specialized behavior for an enter event at the object level. By default, this function calls setInUse to set the in-use emphasis.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setRefreshOff
public:
virtual IContainerObject& setRefreshOff()

Prevents refreshing of this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setRefreshOn
public:
virtual IContainerObject& setRefreshOn( bool refreshOn = true )

Allows refreshing of this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
show
public:
virtual IContainerObject& show( bool show = true, IContainerControl* container = 0 )

Makes this object visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

The native Windows containers (that is, containers constructed without the pmCompatible style) do not support filtering of objects.


IContainerObject - Enumerations


[view class]
Emphasis
enum Emphasis { none=0, 
                cursored=1, 
                inuse=2, 
                selected=4 }

These enumerators specify a visible indication of the condition of an object affecting the ability of a user to interact with that object:

none
Provides no emphasis. Use this enumerator when no emphasis is required.
cursored
Provides a visible indication that the object contains the cursor.
inuse
Provides a visible indication that an object has been opened.
selected
Provides a visible indication that an object has been selected by the user.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IContainerObject - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data