![]() |
![]() |
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.
This documentation uses some terms that need to be defined, so that the description of the HyperContent Manager and it's uses are clear.
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.)
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.
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.
inUniqueCallerId
is an id that the manager uses at run-time to distinquish between multiple registered plug-ins, if the id is already in use by a plug-in registered for the same content type, the plug-in will not be registered and the method will return an error. Choosing the id can be done programmatically to avoid conflicts (if a value of 1 returns an error, try 2, if that returns an error try 3, and so on.)inContentTypePtr
designates the type of hypercontent that the plug-in will be working with (some content types are defined in the fileHCMDefs.h
or you may need to define your own type.).
Note: the content handler that is passed back will only work with the content type specified, to manage multiple types you must register for each type that you need, getting a seperate content handler for each type. The content types defined inHCMDefs.h
are "PDFMark" and "HTML DATA".CHandlerDeathProcPtr
is a pointer to a function, within your plug-in module, that allows HCM to notify the plug-in when the Content Handler is being removed - normally this is only called when the application is closed, but can also be called if the application is in a low memory situation.outCHandlerPtr
is a pointer to the Content Handler classCHcmPlugInContentHandler
.
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.
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 anHcmObjectCreateDescRec
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 foroutNamePtr
.)
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 useBoundingBoxHdrRecDestroy
)
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 withPubPrefsRead
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.
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 |