home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v1.zip
/
IBMCPP
/
IBMCLASS
/
ICNROBJ.HPP
< prev
next >
Wrap
C/C++ Source or Header
|
1993-10-22
|
23KB
|
421 lines
#ifndef _ICNROBJ_
#define _ICNROBJ_
/*******************************************************************************
* FILE NAME: icnrobj.hpp *
* *
* DESCRIPTION: *
* Declaration of the class(es): *
* IContainerObject - Base container object class *
* *
* COPYRIGHT: *
* (C) Copyright IBM Corporation 1992 *
* All Rights Reserved *
* Licensed Materials * Property of IBM *
* *
* HISTORY: *
*******************************************************************************/
#if !defined(_IVBASE_)
#include <ivbase.hpp>
#endif
#if !defined(_ISTRING_)
#include <istring.hpp>
#endif
#if !defined(_IBITFLAG_)
#include <ibitflag.hpp>
#endif
#if !defined(_IHANDLE_)
#include <ihandle.hpp>
#endif
/*----------------------------------------------------------------------------*/
/* Align classes on four byte boundary. */
/*----------------------------------------------------------------------------*/
#pragma pack(4)
// Class Forward Declarations
class IContainerObject;
class IMiniCnrRecord;
class IContainerControl;
class IResourceId;
class IContainerObject : public IVBase
{
typedef IVBase
Inherited;
/*******************************************************************************
* IContainerObject is the base class of all objects stored in a container. *
* This object is required to be subclassed to support additional data in the *
* details view but can be used as is in other views. All instances of *
* this class must be created using operator new, which is overloaded here *
* to provide the storage allocation required by the underlying OS/2 container *
* control. *
* *
* If this object is subclassed and data is added for the details view, the *
* data must be contiguous with the data of this class and be one of the *
* supported types defined in IContainerColumn. It is important to note that *
* only the string type can be edited. The IString class is the recommended *
* way to store text data in an object subclass. *
* *
* Container initialization normally occurs when the first IContainerControl *
* is instantiated. If container objects need to be instantiated earlier, the *
* IContainerControl::initialize function should be called prior to the first *
* instantiation, but after the presentation environment has been initialized. *
* *
* It is recommended that you use a Resource Library to load icons as it *
* is capable of satisfying multiple requests for the same icon with a *
* single load and will manage multiple references to the same object. Actual *
* icon deletion occurs when the use count reaches zero. *
* *
* IContainerObjects can be added to multiple containers at the same time. When *
* functions in this class modify an object's characteristics, they do so in *
* all containers that hold the object. Functions exist in IContainerControl *
* that can be used to modify certain attributes of an object in a single *
* container. *
* *
* EXAMPLE: *
* *
* *
* class Customer : public IContainerObject *
* { *
* public: *
* Customer(const IString& Name, *
* const IPointerHandle& Icon = 0, *
* const IString& Address = IString(), *
* const IString& Phone = IString(), *
* unsigned long Age = 0) *
* : IContainerObject(Name, hptrIcon), *
* strCustomerAddress(Address), *
* strCustomerPhone(Phone), *
* ulCustomerAge(Age) { } *
* *
* private: *
* IString strCustomerAddress; *
* IString strCustomerPhone; *
* unsigned long ulCustomerAge; *
* }; *
* *
* *
* Customer ski("Blacky Diamond", 10, "Park City, Utah", "1-800-SKI-JUMP", 39); *
* *
* *
* *
*******************************************************************************/
friend class IContainerControl;
friend class IMiniCnrRecord;
friend IMiniCnrRecord* IRecFromObj( const IContainerObject* pcnrobj);
public:
/*----------------------- Related Types ----------------------------------------
| The following IContainerObject types are defined: |
| Emphasis - A visible indication of the condition of an object that can |
| affect the ability of a user to interact with that object. |
| The types of emphasis are: |
| |
| none - Used when no visible indication is required. |
| cursored - A visible indication of where user interaction |
| with the keyboard will appear. |
| inuse - A visible indication that the object has been |
| opened. |
| selected - A visible indication that the object has been |
| selected by the user. |
------------------------------------------------------------------------------*/
enum Emphasis { none=0, cursored=1, inuse=2, selected=4};
/*------------------------ Constructors ----------------------------------------
| You can construct an instance of this class in the following ways: |
| - The default with no arguments. |
| |
| - By providing an IString for text and an IPointerHandle for the icon. |
| |
| - By providing an IString for text and an IResourceId for the icon. |
| |
| - By providing resource IDs for both the text and icon. |
| |
| - From a copy of an existing object. If the object is subclassed, this |
| copy constructor must be overloaded to ensure that the object is copied |
| correctly. |
| |
| - By providing an IString for text and an unsigned long that is used |
| as a resource ID. This constructor is provided to resolve a potential |
| ambiguity since both IResourceIds and IPointerHandles can be built |
| implicitly from an unsigned long integer. |
------------------------------------------------------------------------------*/
IContainerObject ( );
IContainerObject ( const IString& string,
const IPointerHandle& iconHandle = 0);
IContainerObject ( const IString& string,
const IResourceId& iconId);
IContainerObject ( const IResourceId& nameID,
const IResourceId& iconId);
IContainerObject ( const IContainerObject& object);
IContainerObject ( const IString& string,
unsigned long iconId);
virtual
~IContainerObject ( );
/*-------------------------------- Accessors -----------------------------------
| These functions provide means of getting and setting the accessible |
| attributes of instances of this class. Note: Since an object may 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. |
| setIcon - Sets a new icon for an object. |
| setIconText - Sets the new text for an object. |
| icon - Returns the icon handle of an object. |
| iconText - Returns the text of an object. |
| setInUse - Sets the in-use emphasis for this object. |
| removeInUse - Removes the in-use emphasis for this object. |
| enableDataUpdate - Enables this object to be updated. |
| disableDataUpdate - Disables update of this object. |
| refresh - Refreshes this object. |
| show - Makes this object visible. |
| hide - Makes this object invisible by filtering it out. |
| enableDrop - Allows other objects to be dropped on this object. |
| disableDrop - Prevents any object from being dropped on this |
| object. |
| setRefreshOn - Sets this object's state to be refreshable. |
| setRefreshOff - Inhibits refresh of this object. |
| isInUse - Returns true if this object has in-use emphasis. |
| isReadOnly - Returns true if this object is read-only. |
| isDropOnAble - Returns true if this object can accept a drop. |
| isVisible - Returns true if this object is visible. |
| isRefreshOn - Returns true if this object is in refreshable |
| state. |
| iconOffset - Returns the offset of the object's IPointerHandle |
| for the icon. This allows the icon to be used in a |
| column of the details view. |
| iconTextOffset - Returns the offset of the object's IString. This |
| allows the IString to be used in a |
| column of the details view. |
| setOpen - Sets the open emphasis. |
| setClosed - Removes the open emphasis in all containers. |
| isOpen - Returns true if this object is open. |
------------------------------------------------------------------------------*/
virtual IContainerObject
&setIcon ( const IPointerHandle& iconHandle),
&setIcon ( const IResourceId& iconId),
&setIcon ( unsigned long iconId),
&setIconText ( const char* iconText),
&setIconText ( const IString& iconText),
&setIconText ( const IResourceId& iconTextId);
virtual IPointerHandle
icon ( ) const;
virtual IString
iconText ( ) const;
virtual IContainerObject
&setInUse ( Boolean inUse = true,
IContainerControl* container = 0),
&removeInUse ( IContainerControl* container = 0),
&enableDataUpdate ( Boolean enable = true,
IContainerControl* container = 0),
&disableDataUpdate ( IContainerControl* container = 0),
&enableDrop ( Boolean enable = true,
IContainerControl* container = 0),
&disableDrop ( IContainerControl* container = 0),
&show ( Boolean show = true,
IContainerControl* container = 0),
&hide ( IContainerControl* container = 0),
&refresh ( IContainerControl* container = 0),
&setRefreshOn ( Boolean refreshOn = true),
&setRefreshOff ( );
virtual Boolean
isInUse ( IContainerControl* container = 0) const,
isReadOnly ( IContainerControl* container = 0) const,
isDropOnAble ( IContainerControl* container = 0) const,
isVisible ( IContainerControl* container = 0) const,
isRefreshOn ( ) const;
static unsigned long
iconOffset ( ),
iconTextOffset ( );
virtual IContainerObject
&setOpen ( Boolean open = true),
&setClosed ( );
virtual Boolean
isOpen ( ) const;
/*------------------------ Object Allocation -----------------------------------
| These functions provide all object allocation and deallocation for instances |
| of the class. Stack and static instances of this class are not allowed. |
| operator new - Allocates storage for a class instance. |
| operator delete - Deallocates the storage of a class instance. |
------------------------------------------------------------------------------*/
#ifdef __DEBUG_ALLOC__
void
*operator new ( size_t size,
const char* fileName,
size_t lineNumber),
operator delete ( void*,
const char* fileName,
size_t lineNumber );
#else
void
*operator new ( size_t size),
operator delete ( void* );
#endif
/*------------------------ Subclass Provided Functions -------------------------
| These functions must be provided by the subclass if the behavior is |
| required: |
| handleOpen - Called when Enter is pressed on an object or a mouse |
| double click occurs on an object and the |
| IContainerControl that contains the object has been |
| provided with an ICnrHandler. |
| handleInuseChange - Called when in-use emphasis changes on an object and |
| the IContainerControl that contains the object has |
| been provided with an ICnrHandler. If the object |
| has just acquired in-use emphasis, acquired is set |
| to true. |
| handleCursoredChange - Called when cursored emphasis changes on an object |
| and the IContainerControl that contains the object |
| has been provided with an ICnrHandler. If the |
| object has just acquired cursored emphasis, acquired |
| is set to true. |
| handleSelectedChange - Called when selection emphasis changes on an object |
| and the IContainerControl that contains the object |
| has been provided with an ICnrHandler. If the |
| object has just acquired selection emphasis, |
| acquired is set to true. |
| handleTreeCollapse - 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 that |
| contains the object has been provided with an |
| ICnrHandler. |
| handleTreeExpand - 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 that |
| contains the object has been provided with an |
| ICnrHandler. |
| helpId - Called when an ICnrHelpEvent is dispatched to |
| ICnrHandler. The default behavior is to return 0. |
| If the identifier returned is greater than 0, the |
| default behavior of the container's help handler is |
| to display the help panel. |
| objectCopy - Called when it is necessary to make a copy of an |
| object. This occurs when |
| IContainerControl::copyObjectTo is called. |
| operator == - Returns true if the objects are at the same storage |
| location. |
------------------------------------------------------------------------------*/
virtual void
handleOpen ( IContainerControl* container),
handleInuseChange ( IContainerControl* container,
Boolean acquired),
handleCursoredChange ( IContainerControl* container,
Boolean acquired),
handleSelectedChange ( IContainerControl* container,
Boolean acquired),
handleTreeCollapse ( IContainerControl* container),
handleTreeExpand ( IContainerControl* container);
virtual unsigned long
helpId ( ) const;
virtual IContainerObject
*objectCopy ( );
Boolean
operator== ( const IContainerObject& object);
protected:
/*----------------------------- Implementation ---------------------------------
| The following functions are used in the implementation of the class: |
| setEmphasis - Sets the passed emphasis attribute On or Off. If a |
| container is not specified, the changes are made to |
| all containers that hold this object. |
| setAttributes - Sets some attributes Off while setting others On. It |
| is used to toggle the state of mutually exclusive |
| attributes. If a container is not specified, the |
| changes are made to all containers that hold this |
| object. |
| incrementUseCount - Increases the count of containers with this object. |
| decrementUseCount - Decreases the count of containers with this object. |
| setBase - Stores the address of the real base of this object. |
| initialize - Initializes an object after construction. |
| baseRecord - Returns the address of the real base of this object. |
| useCount - Returns the number of containers with this object. |
| isAttribute - Returns true if the passed attribute is On. |
------------------------------------------------------------------------------*/
virtual IContainerObject
&setEmphasis ( unsigned long emphasisAttribute,
Boolean turnOn = true,
IContainerControl* container = 0),
&setAttributes ( unsigned long attributeTurnedOff,
unsigned long attributeTurnedOn,
IContainerControl* container = 0),
&incrementUseCount ( ),
&decrementUseCount ( ),
&setBase ( const IMiniCnrRecord* baseRecord),
&initialize ( );
IMiniCnrRecord
*baseRecord ( );
unsigned long
useCount ( ) const;
virtual Boolean
isAttribute ( unsigned long attribute,
IContainerControl* container ) const;
private:
/*--------------------------------- PRIVATE ----------------------------------*/
enum State { ok=1, opened=2, noInvalidate=4, hasDescendents=8,
noRefresh=16, invalid=32, subclassed=64, deleteInProcess=128,
nestedDelete=256};
unsigned long
iconTextLength() const;
static void
*newRecord(size_t size),
deleteRecord(void* precord);
int
flClState;
unsigned long
ulClUseCount;
IContainerObject
*pcnrobjClParent;
IMiniCnrRecord
*pbase;
} ;
/*----------------------------------------------------------------------------*/
/* Resume compiler default packing. */
/*----------------------------------------------------------------------------*/
#pragma pack()
/*--------------------------------- INLINES ----------------------------------*/
#ifndef I_NO_INLINES
#include <icnrobj.inl>
#endif
#endif /* _ICNROBJ_ */
