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:
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.
You can construct and destruct objects of this class.
![]() |
public:
virtual ~IContainerObject()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IContainerObject()
This provides the default constructor, which accepts no parameters.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IContainerObject( const IResourceId& nameID, const IResourceId& iconId )
Construct an IContainerObject object by providing resource IDs for both the text and the icon.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
IContainerObject( const IString& string, const IResourceId& iconId )
Construct an IContainerObject object by providing an IString for text and an IResourceId for the icon.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IContainerObject& operator =( const IContainerObject& object )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
These members implement the class.
![]() |
protected:
IMiniCnrRecord* baseRecord()
Returns the address of the real base of this object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual IContainerObject& decrementUseCount()
Decreases the count of containers having this object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual IContainerObject& incrementUseCount()
Increases the count of containers having this object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual IContainerObject& initialize()
Initializes an object after construction.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool isAttribute( unsigned long attribute, IContainerControl* container ) const
If the specified attribute is set to on, true is returned.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual IContainerObject& setBase( const IMiniCnrRecord* baseRecord )
Stores the address of the real base of this object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
unsigned long useCount() const
Returns the number of containers having this object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
These members must be provided by a derived class if the behavior is required.
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IContainerObject* objectCopy()
Called when it is necessary to make a copy of an object. This occurs when you call IContainerControl::copyObjectTo.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool operator ==(const IContainerObject& object)
If the objects are at the same storage location, true is returned.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
These members provide all object allocation and deallocation for instances of the class. Stack and static instances of this class are not allowed.
![]() |
Deallocates the storage of an object of this class.
public:
void operator delete( void*, const char* fileName, size_t lineNumber )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
void operator delete(void*)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
Allocates storage for an object of this class.
public:
void* operator new(size_t size)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
void* operator new( size_t size, const char* fileName, size_t lineNumber, ICnrAllocator& allocator )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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);
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
void* operator new( size_t size, const char* fileName, size_t lineNumber )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Use these members to get and set the accessible attributes of this class.
Note:
![]() |
public:
virtual IContainerObject& disableDataUpdate( IContainerControl* container = 0 )
Disables user updates of this object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IContainerObject& disableDrop( IContainerControl* container = 0 )
Prevents any object from being dropped on this object.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IContainerObject& enableDrop( bool enable = true, IContainerControl* container = 0 )
Allows other objects to be dropped on this object.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
![]() |
public:
virtual IContainerObject& hide( IContainerControl* container = 0 )
Makes this object invisible by filtering it out.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The native Windows containers (that is, containers constructed without the pmCompatible style) do not support filtering of objects.
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IString iconText() const
Returns the text of an object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isOpen() const
If this object is open, true is returned.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual bool isRefreshOn() const
If this object is in a refreshable state, true is returned.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The native Windows containers (that is, containers constructed without the pmCompatible style) do not support filtering of columns.
![]() |
public:
virtual bool isWriteable( IContainerControl* container = 0 ) const
Returns true if the data in the object can be edited.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IContainerObject& removeInUse( IContainerControl* container = 0 )
Removes the in-use emphasis for this object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IContainerObject& setClosed()
Removes the open emphasis in all containers.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
Sets a new icon for an object.
public:
virtual IContainerObject& setIcon( const IResourceId& iconId )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
virtual IContainerObject& setIcon( const IPointerHandle& iconHandle )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
virtual IContainerObject& setIcon(unsigned long iconId)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
Sets the new text for an object.
public:
virtual IContainerObject& setIconText( const IString& iconText )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
virtual IContainerObject& setIconText(const char* iconText)
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
virtual IContainerObject& setIconText( const IResourceId& iconTextId )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IContainerObject& setInUse( bool inUse = true, IContainerControl* container = 0 )
Sets the in-use emphasis for this object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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.
![]() |
Sets the icon that is used when the object has in use emphasis.
public:
virtual IContainerObject& setInUseIcon( const IPointerHandle& iconHandle )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The icon is used in addition to the hashing shown for objects that are in use.
public:
virtual IContainerObject& setInUseIcon( unsigned long iconId )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
public:
virtual IContainerObject& setInUseIcon( const IResourceId& iconId )
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IContainerObject& setRefreshOff()
Prevents refreshing of this object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IContainerObject& setRefreshOn( bool refreshOn = true )
Allows refreshing of this object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IContainerObject& show( bool show = true, IContainerControl* container = 0 )
Makes this object visible.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The native Windows containers (that is, containers constructed without the pmCompatible style) do not support filtering of objects.
![]() |
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:
Windows | OS/2 | AIX |
Yes | Yes | Yes |