The HyperContent Manager

The HyperContent Manager gives you with the ability to create, manage, edit and delete hypercontent. There are three basic types of hypercontent that Adobe PageMaker understands: sources (or hyperlinks), destinations (or anchors), and storage only. A hyperlink source is a page item that the user can click on and jump to an anchor, and an anchor is an item on a page that the viewing application (in this case PageMaker) can jump to. Storage only hypercontent contains additional information about a page item, this information is associated with a specific page item, but is simply stored in another location by the HyperContent Manager. Storage only hypercontent can contain information such as HTML code that would replace the page item when creating a web page, pdfmarks that are used when creating an Adobe Acrobat PDF, or any other type of information that you wish to define.


Definitions.

This documentation uses some terms that need to be defined, so that the description of the HyperContent Manager and it's uses are clear.

Note:

Hypercontent objects can be attached to either an object (image, box, text block, etc...) or to the text within a text block. The PageMaker item that the hypercontent is going to be attached to, or associated with, must be selected. For objects, the object must be the only thing selected. For text, the text must have either an insertion point (typical for anchors) or some text must be selected (required for a text source.)


HCMPlugs.h

The HCMPlugs.h header file contains two class declarations, the CHcmPlugInRegistry class and the CHcmPlugInContentHandler class. The CHcmPlugInRegistry class is acquired, as the other interfaces are, through CIInterfaceManager::AcquirePMInterface but the CHcmPlugInContentHandler is acquired through the registry class.

CHcmPlugInRegistry Methods

This interface is the interface that is acquired with the PMIID_HYPERCONTENTMANAGER id.

HcmErr ContentTypeRegister( const HcmCallerIdEnum inUniqueCallerId, const char * inContentTypePtr, CHandlerDeathProcPtr inNotifyProcPtr, CHcmPlugInContentHandler ** outCHandlerPtr );

Registers the plug-in with the HyperContent Manager, and retrieves a pointer to the Content Handler.

HcmErr ContentTypeUnregister( const HcmCallerIdEnum inUniqueCallerId, const char * inContentTypePtr );

Removes the plug-in from the Hyper Content Manager registry, for notes on the arguments, see ContentTypeRegister.



CHcmPlugInContentHandler Methods

These methods are used to create and manipulate hypercontent. When using these methods it is important to remember that a single content handler will only work with and return information about the hypercontent of a single type. (Working with multiple types requires multiple instances of the Content Handler.)

void BoundingBoxHdrRecDestroy( HcmBoundingBoxHdrRec *  inPtr );

Destroys (or deletes) the bounding box structure for a hypercontent object. The bounding box itself is unaffected, but the memory allocated for the record is freed. This method is used to delete the structures that are created by the PageMakerLocationGet methods.

HcmErr Create( HcmObjectCreateDescRec * inObjectDescriptionPtr, HcmObjectId *  outCreatedObjectId );

Creates new hypercontent information, and returns the HcmObjectId for the content. The method receives an HcmObjectCreateDescRec as a description of the hypercontent object to create.

HcmErr Delete( const HcmObjectId  inObjectId );

Deletes the hypercontent object.

HcmErr Delete( HcmPmUniqueRec * inObjectToDeletePtr, HcmObjectTypeEnum inKindOfObject );

Deletes the hypercontent object associated with the given page item (inObjectToDeletePtr). You must specify the type of hypercontent object to delete, since the page item can have multiple kinds of hypercontent associated with it.

HcmErr DisplayNameBufferDestroy( char * inBufferPtr );

Deletes the buffer that was used in passing the display name to your plug-in.

HcmErr DisplayNameGet( const HcmObjectId inObjectId, char ** outNamePtr );

Returns the display name for the hypercontent object. (You must call DisplayNameBufferDestroy, above, to deallocate the memory allocated for outNamePtr.)

HcmErr DisplayNameSet( const HcmObjectId inObjectId, char * inNewNamePtr );

Gives the hypercontent object a new display name.

HcmErr HcmObjectIdGet( HcmPmUniqueRec * inPmUniqueRecPtr, HcmObjectId * outAnchorObjectIdPtr, HcmObjectId * outHyperlinkObjectIdPtr, HcmObjectId * outStorageOnlyObjectIdPtr );

Retrieves the hypercontent objects for the given page item. A page item can be a storage, an anchor, and a hyperlink, or any combination of the three.

HcmErr HcmObjectIdGet( char * inName, HcmObjectId * outObjectId );

Returns the hypercontent object that has the display name given in inName.

HcmErr HyperContentTypeGet( const HcmObjectId inObjectId, HcmObjectTypeEnum * outObjectType );

Returns the hypercontent type for the given hypercontent object. See the definition of HyperObjectTypeEnum for details.

HcmErr IsPmTextSegment( const HcmObjectId inObjectId, PMBool * outIsTextSegment );

If the hypercontent is associated with a portion of text, the outIsTextSegment is set to true.

PMBool IsValidAnchorType( HcmObjectTypeEnum inType );

Tests inType for a valid anchor type.

PMBool IsValidHyperlinkType( HcmObjectTypeEnum inType );

Tests for a valid hyperlink type.

PMBool IsValidStorageOnlyType( HcmObjectTypeEnum inType );

Tests for a valid storage type.

HcmErr PageMakerInfoGet( const HcmObjectId inObjectId, HcmPmUniqueRec * outPmUniqueRecPtr );

Returns a structure that describes the page item or text token for the given hypercontent object.

HcmErr PageMakerInfoSet( const HcmObjectId inObjectId, HcmPmUniqueRec * inPmUniqueRecPtr );

Assignes the page item or text token to the given hypercontent object.

HcmErr PageMakerLocationGet( const HcmObjectId inObjectId, HcmPmLocationEnum * outLocation );

Returns the page number, or identifier for the page which contains the page item that the hypercontent object describes.

HcmErr PageMakerLocationGet( const HcmObjectId inObjectId, HcmPmLocationEnum * outLocation, INT32 * outItemTop, INT32 * outItemLeft );

Returns both the page, and coordinates for the page item associated with the hypercontent object.

HcmErr PageMakerLocationGet( const HcmObjectId inObjectId, HcmBoundingBoxHdrRec ** outBBoxHdrRecPtr );

Returns the location of the page item, using an HcmBoundingBoxHdrRec. This method allocates the memory for the bounding box structure, which must be freed by your plug-in (to free the memory use BoundingBoxHdrRecDestroy)

PMBool PageMakerSegmentHasAnchorInfo( HcmPmUniqueRec * inPmUniqueRecPtr );

Tests the PageMaker page item or text token for an attached anchor.

PMBool PageMakerSegmentHasHyperlinkInfo( HcmPmUniqueRec * inPmUniqueRecPtr );

Tests the PageMaker page item or text token for an attached hyperlink.

PMBool PageMakerSegmentHasStorageOnlyInfo( HcmPmUniqueRec * inPmUniqueRecPtr );

Tests the PageMaker page item or text token for an attached storage.

PMBool PageMakerSegmentHasHyperContent( HcmPmUniqueRec * inPmUniqueRecPtr );

Tests the PageMaker page item or text token for any attached hypercontent.

HcmErr PrivateDataRead( const HcmObjectId inObjectId, char * outBuffer, UINT32 * inoutHowMuchToRead );

Fills the buffer, outBuffer, with the private data associated with a hypercontent object.

HcmErr PrivateDataSizeGet( const HcmObjectId inObjectId, UINT32 * outHowBig );

Returns the size, in bytes, of the private data that the hypercontent object holds.

HcmErr PrivateDataWrite( const HcmObjectId inObjectId, char * inBuffer, UINT32 * inoutHowMuchToWrite );

Writes the given private data to the hypercontent storage, the size of the buffer is specified in inoutHowMuchToWrite. The size is given in bytes.
Note: there are no methods for reading or writing a portion of the private data. To modify existing data, you must read the entire block, modify it, and then write the entire new block (which will replace the old.)

HcmErr PubPrefsRead( char * outBuffer, UINT32 * inoutHowMuchToRead );

Reads the publication preferences for the content type.

HcmErr PubPrefsSizeGet( UINT32 * outHowBig );

Returns the size (in bytes) of the publication preferences for the hypercontent type that the content manager is registered for.

HcmErr PubPrefsWrite( char * inBuffer, UINT32 * inoutHowMuchToWrite );

Writes the information in the buffer, inBuffer, to the publication preferences. This method, along with PubPrefsRead apply to the content type that the plug-in registered when it acquired the content handler.

HcmErr RelationshipBreakAll( const HcmObjectId inDestination );

Breaks all the links to the given hypercontent object.

HcmErr RelationshipBreakOne( const HcmObjectId inSource, const HcmObjectId inDestination );

Breaks the relationship between the given hypercontent objects. The objects passed to this method may be given in either order; anchor and hyperlink, or hyperlink and anchor.

HcmErr RelationshipArrayDestroy( HcmObjectId * inDestinationArray );

Deletes a relationship array. The RelationshipGet method allocates an array of unsigned 32-bit integers but the array is not deleted unless you use this method. The relationships between the hypercontent objects are unaffected.

HcmErr RelationshipGet( const HcmObjectId inSource, HcmObjectId ** outDestinationArray );

Returns a pointer to an array of hypercontent object ids. The first element in the array is actually a count of the ids in the array. The ID given in inSource can be either a hyperlink or an anchor, and the relationship array will contain the related hypercontent objects.



virtual HcmErr RelationshipGet( HcmPmUniqueRec * inPmUniqueRecPtr, HcmObjectId ** outDestinationArray );

Returns a pointer to an array of hypercontent object ids. The first element in the array is actually a count of the ids in the array. The page item given in inPmUniqueRecPtr can be either a hyperlink, an anchor, or both, and the relationship array will contain all of the related hypercontent objects. You should test each object in the array to determine whether it is an anchor or a hyperlink.



HcmErr RelationshipMake( const HcmObjectId inSource, const HcmObjectId inDestination );

Creates a hyperlink relationship between a hyperlink and an anchor. The hypercontent objects may be passed to this method in either order.


Example

See the PDFNotes sample project.


Comments or suggestions? Contact Adobe Developer Support
Copyright © 1997 - 2001 Adobe Systems Incorporated. All rights reserved.
Legal notices and trademark attributions