CIText

By using the CIText interface you can retrieve the text from a story, find inline graphics, or get a variety of other information about the stories within a PageMaker publication.


CIText Interfaces

You will find the structures that you need to use the CIText interface in the CIText.h header file. Most of the CIText methods use those structures, for the methods that do, you must create a variable using the appropriate structure, that the method will fill in. Many of the terms used in this document, such as Story, Text Run, and Text Block are defined in the PageMaker SDK Guide.

PMErr GetTextBlockInfo(PMOBJ_REC* pObjRec, PMTextBlockInfo* pTextBlockInfo);

PageMaker will fill in a PMTextBlock structure with the settings from the text block specified by the PMOBJ_REC, you need to pass in a pointer to a structure that you have already declared.

PMErr GetTextLineBreakInfo(unsigned long storyID, unsigned long lineNumber, PMLineInfo* pLineBreakInfo);

Returns line break and format information in a PMLineInfo structure that you provide.

PMErr GetTextStoryInfo(unsigned long storyID, PMStoryInfo* pStoryInfo);

Fills the PMStoryInfo structure with the information on how many characters, lines, and text blocks are in the story indicated in storyID as well as the ObjectID for the first text block in the story.

PMErr GetStoryFirstILG(unsigned long storyID, PMOBJ_REC* pILGObjRec);

This method, in combination with the GetStoryNextILG, allows you to retrieve the object records (PMOBJ_REC *) for the inline graphics within the story that you specify in storyID. This interface returns the first inline graphic, after which you would use the GetStoryNextILG method to cycle through the rest of the inline graphics in the story, storyID.If there are no inline graphics in the story, then the method returns a CQ_NO_MORE_ILGS error.

PMErr GetStoryNextILG(PMOBJ_REC* pILGObjRec);

This method is only valid after you have called GetStoryFirstILG, then subsequent calls to this method will give you the object record for each inline graphic in the story that you specified when you called GetStoryFirstILG. This method will return a CQ_NO_MORE_ILGS when there are no more in line graphics in the story. Each time you call GetStoryNextILG, the interface is incremented to the next inline graphic automatically.

PMErr ReadStoryTextRaw(unsigned long storyID, unsigned short nFormat, unsigned long offset, unsigned long numChars, char** ppTextBuf, unsigned long* bufSize);

Gets a copy of the text from a story. The text will not be formatted at all, and the buffer is allocated automattically. When you have finished with the buffer, free the memory by calling FreeTextMemory. Subsequent calls to any of the ReadStoryTextXXX methods will free the memory allocated by the previous call, so you should copy or consume the text in the buffer before doing another read.
storyID is the ID for the story to copy.
nFormat is used to specify what you want to do with non-printing characters.
0 to keep all non-printing characters
1 to delete all non-printing characters
2 to replace all non-printing characters with spaces
3 to substitute all non-printing characters the way the ASCII import filter does
offset is the offset from the beginning of the story to start copying text from (0 to start at the beginning of the story.)
numChars is the number of characters to copy.
ppTextBuf is returned as a pointer to the buffer that contains the requested text.
bufSize is returned as the size of the buffer returned.

PMErr ReadStoryTextTagged(unsigned long storyID, unsigned short nFormat, unsigned long offset, unsigned long numChars, char** ppTextBuf, unsigned long* bufSize);

This method is like the ReadStoryTextRaw, but it includes style-tags for the text. A style tag is the name of the PageMaker style in brackets <>, at the beginning of the paragraph. For a paragraph that does not have a style attached, the style tag is empty (<>). For a description of the parameters, see the comments under ReadStoryTextRaw, above.

PMErr ReadStoryTextRTF(unsigned long storyID, unsigned short nFormat, unsigned long offset, unsigned long numChars, char** ppTextBuf, unsigned long* bufSize);

Returns a copy of the text within the story, but unlike ReadStoryTextRaw, and ReadStoryTextTagged, the text is formatted, in the RTF format. The nFormat value is ignored by this method, but it is included in the pararmeter list to be consistent with the other methods.

void FreeTextMemory();

This method is used to free the memory block that is allocated by a call to one of the ReadStoryTextXXX() methods. You should use this interface after the last call to either ReadStoryTextRaw, ReadStoryTextTagged, or ReadStoryTextRTF.

PMErr GetTextSelection(unsigned long *pBlockID, unsigned long *pStoryID, unsigned long *pOffset, unsigned long *pNumChars )

Returns information about the current text selection.
pBlockID The object ID for the text block.
pStoryID The story ID for the story that contains the text.
pOffset The number of characters from the beginning of the story.
pNumChars The number of characters in the selection.

void RecomposeAllStories();

This will recompose all the stories in a publication. You would want to use this method after making changes that would cause all the stories in a publication to need recomposing. Changing the definition of one of the styles in the style palette, or using the PChangeAll command, are examples of changes that you may want to follow with a call to this method.

void SetupStoryInlines();

This is an obsolete method, it was implemented as a work-around to a problem that has been fixed in the PageMaker application.

void RecomposeStory(BOOL bEndofPub);

The RecomposeStory method is used to recompose all the stories on the current page. If bEndofPub is true, the text blocks for those stories will also be recomposed on any following pages. If bEndofPub is false, only the current page will be recomposed.

PMErr GetCharFormatInfo(unsigned long storyID, long targetCharOffset, PMCharFormatInfo *pCharFormatInfo);

Fills the PMCharFormatInfo sturcture with the character formatting information for the text run specified by the targetCharOffset. A text run is any number of contiguous characters that have the same formatting, and do not contain a hard break.

PMErr GetParaFormatInfo(unsigned long storyID, long targetCharOffset, PMParaFormatInfo *pParaFormatInfo);

Gets the paragraph formatting information for the paragraph in which the targetCharOffset falls. You supply the PMParaFormatInfo structure that this interface will return the information in.

PMErr GetTabFormatInfo(unsigned long storyID, long targetCharOffset, PMTabFormatInfo *pTabFormatInfo);

Gets the tab information for the current text run.

PMErr GetLineBreakInfo(unsigned long storyID, long targetCharOffset, PMLineInfo *pLineInfo)

You would use this method to get the line break information for the line of text that targetCharcterOffset indicates.

PMErr GetStyleNameInfo(char *pStyleName, PMTabFormatInfo *pTabFormatInfo, PMParaFormatInfo *pParaFormatInfo, PMCharFormatInfo *pCharFormatInfo);

Gets the formatting information from a paragraph style. The information returned will reflect the style as it is defined in the style palette, and not any overrides to the style that exist in the text of a publication. The style name in pStyleName should be just as it appears in the style menu, or returned by the PGetStyleNames query.


Example

In this example we search through a story, looking for any text that has 'loose' tracking. When we find text that is set to 'loose' tracking, we make it 'bold'.

CIInterfaceManager	*mgr;		
CIText 				*textPtr;
PMXErr 				result;
PMStoryInfo			story;
PMCharFormatInfo		run;
unsigned long 		storyID;

// We've already set up a pointer to the PMMessage struct (sPMMessage)	
mgr = sPMMessage->pInterfaceMgr;

// Here we acquire the CIText interface.
result = mgr->AcquirePMInterface((unsigned long) PMIID_TEXT, (void **) &textPtr);
if ( result != CQ_SUCCESS )
{
	// if we couldn't get the interface, this plug-in won't work
	throw result;
}

//This would only work if the text cursor is already in the story we want to 
// parse through.	
PGetTextRun myTextRun(7);		// Gets information about the text run.

// Here we get the Story's ID which we need in the CIText methods.
storyID = myTextRun.nStoryID;  

// Before we work our way through the story, we need to know its length
textPtr->GetTextStoryInfo( storyID, &story);
textPtr->GetCharFormatInfo( storyID, 0, &run);


//story.nNumChars is the length of the story (in characters), and
//  run.nNumChars is the length of the current text run.
for (int i = 0; i<story.nNumChars ; i += run.nNumChars )
{
	// Each time through, we get the next run and check it for loose tracking
	textPtr->GetCharFormatInfo(storyID, i, &run);
	if ( run.loose ) 
	{	
		// Since CIText will only get information about text and not
		//  change it, we need to use the PageMaker Class Library.
		PSetTextCursor( storyID, i, i + run.nNumChars);
		PTypeStyle( style_bold );
	}
}


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