CResource

Heritage

Description

Usage

Enums

PwrResourceType

Protected Data Members

Public Methods

Constructor and Destructor

Resource State Methods

Resource Item Methods

Protected Methods

Copy and Assignment

Heritage

Subclasses: CResourceWindow, CResourceMenu

Description

CResource is an abstract class which encapsulates resource handling. CResource defines a common interface to URL-defined XVT-Power++ resources. Menu and window resources are already derived with CResourceMenu and CResourceWindow. You can derive similar resources for string list and dialog.

For instance, when you load a window from the resource file using a given resource ID, the window and its contents are loaded in memory. The contents might represent a set of controls, subsequently providing several resources with one single window resource ID.

XVT-Power++ puts in place a mechanism that lets you load the URL resource in memory once, and then request access to any particular resource item at any time without having to reload that resource from the URL file. This in done automatically in XVT-Power++. For a given resource ID (window or menu), CResource maintains a counter representing the number of XVT-Power++ objects using that particular resource. The CResource::Hold method loads an XVT resource into memory and increments the resource counter. It then parses the XVT resource into a structure that can be traversed later in the program using the CResource methods FirstItem and NextItem. The CResource::Release method decreases the counter and releases the memory associated with a resource when no other XVT-Power++ object is using this resource (i.e., when the counter reaches zero). CResourceItems is provided as a convenience class that calls the Hold and Release methods automatically.

See Also: For more information, see CResourceItems. For details on using resources with XVT-Power++, see the "Resources" chapter in the Guide to XVT Development Solution for C++.

Usage

const short kResErrBase = 5150;
CResource *theRes = new CResourceWindow(WIN_ID);
PwrAssert(theRes, kResErrBase + 1, "Unable to 
	bake resource.");
 	 
theRes->Hold();
theRes->FirstItem();  // reset iterator
 
long theId;
while (theId = theRes->NextItem()) { 
	CObjectRWC *theObject = NULL;
	switch (theRes->GetItemType(theId)) {
	case WC_BUTTON:
		theObject = new NButton(itsEnclosure, 
			WIN_ID, theId);
		break;
	case WC_EDIT:
		theObject = new NEdit(itsEnclosure, 
			WIN_ID, theId);
		break;
	}
	PwrAssert(theObject, kResErrBase + 2, 
		"Unable to bake resource item.");
	theRes->IObject(theId, theObject);
	CastPtr(CView, theObject)->SetCommand(theId);
}
theRes->Release();
 
delete theRes;

Protected Data Members

Public Methods

CResource(PwrResourceType theType, long theId, 
	long theEndId = 0L);

The constructor. theType is one of the enums defined above. (Only PwrWindow and PwrMenuBar are implemented in this release. The types PwrDialog and PwrStringList are reserved for a later release.) theId is the URL resource ID. In this release,theEndId is not used; it represents the last resource ID for a CResource that would need to be represented by a list of resource IDs (such as a string list resource).

virtual ~CResource(void);

The destructor.

virtual BOOLEAN Hold(void) = 0;

This pure virtual function must be overridden. Hold must be implemented by any generalized or specialized type of resource. The first time Hold is called, it loads the resource into an internal structure to be traversed later and increments the resource counter (CResource::itsHoldCount) by one. The subsequent times Hold is called it just increments the resource counter since the resource is already in memory. Each CResource derived object has its own way of loading

resources from URL. It is up to each type of resource to define how to load themselves from URL. Returns TRUE upon success (FALSE if the resource could not be loaded from URL).

virtual void Release(void) = 0;

This pure virtual function must be overridden. Release checks whether the counter itsHoldCount is zero which means that no object in XVT-Power++ is using that particular resource therefore the internal memory associated with that resource should be freed. It is up to each CResource derives object to specify how the memory should be freed and which associated pointers should be set to NULL.

virtual long GetId(void) const;

Returns the URL resource ID (itsId).

virtual void SetId(long theID);

Sets itsId to theId.

virtual long GetEndId(void) const;

Returns the URL resource ID for the last resource in a list of resources (such as a CStringCollectionRWC resource).

virtual void SetEndId(long theId);

Set itsEndId to theId.

virtual PwrResourceType GetType(void) const;

Returns the resource type (see "Enums".)

virtual void SetType(PwrResourceType theType);

Sets itsType to theType.

virtual BOOLEAN IObject(long theId, 
		CObjectRWC *theObject) = 0;

The initializer. This pure virtual function must be overridden. This is where a CResource derived object would specify how to initialize this type of resource. For instance CResourceWindow defines how to initialize a CResourceWindow object given the resource ID theId.

virtual long FirstItem(void) = 0;

This pure virtual function must be overridden. This is where a CResource derived object would define how to access the first resource ID from its list of resources. This is also a way to reset the resource iterator to return the first resource in the list of resources.

virtual long NextItem(void) = 0;

This pure virtual function must be overridden. This is where a CResource derived object would define how to access the next resource ID in its list of resources.

Note: The first time NextItem is called by CResourceWindow, it returns the window ID itself.

virtual long GetItemType(long theId) = 0;

This pure virtual function must be overridden. This is where a CResource derived object would define the type of resource theId represents.

See Also: When you iterate through a list of resources using NextItem, there is no provision for nested loops referring to the same resource ID. Therefore you should complete the iteration before you start another one.

CResource(const CResource &theResource);

A copy constructor, which copies one resource into another.

CResource & operator=(const CResource &theResource);

An assignment operator, which allows you to set one resource equal to another.