### 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:

  - Contiguous with the data of this class
  - One of the supported types defined by IContainerColumn
  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:

  - Satisfy multiple requests for the same icon with a single load
  - Manage multiple references to the same object, such that actual icon deletion occurs when the use count reaches 0

  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.

~IContainerObject

      public:
      virtual ~IContainerObject()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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.

baseRecord

      protected:
      IMiniCnrRecord* baseRecord()

  Returns the address of the real base of this object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

decrementUseCount

      protected:
      virtual IContainerObject& decrementUseCount()

  Decreases the count of containers having this object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

incrementUseCount

      protected:
      virtual IContainerObject& incrementUseCount()

  Increases the count of containers having this object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

initialize

      protected:
      virtual IContainerObject& initialize()

  Initializes an object after construction.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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

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

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.

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

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

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

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

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

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

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

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

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.

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

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.

disableDataUpdate

      public:
      virtual IContainerObject&
        disableDataUpdate( IContainerControl* container = 0 )

  Disables user updates of this object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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

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.

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

iconText

      public:
      virtual IString iconText() const

  Returns the text of an object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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

isOpen

      public:
      virtual bool isOpen() const

  If this object is open, true is returned.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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.

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

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

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

setClosed

      public:
      virtual IContainerObject& setClosed()

  Removes the open emphasis in all containers.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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.

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

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

setRefreshOff

      public:
      virtual IContainerObject& setRefreshOff()

  Prevents refreshing of this object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setRefreshOn

      public:
      virtual IContainerObject&
        setRefreshOn( bool refreshOn = true )

  Allows refreshing of this object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None