Home

14 - Docu + Design Daube

1. FP_FirstPgf FP_FirstCellInRow FO_Row FO_Cell S FO_Pgf FP_LastPgf ry x A E Before straddle 8 3 oO a 4 ra a T Y FP_FirstPgf gt FO_Cell FO_Pegf gt FP_LastPgf FP_FirstPgf FP_FirstCellInRow gt FO_Row em FO Cell FO_Pegf ry T z gt FP_NextPgfInFlow 6 6 ir FP_PrevPgfInFlow After straddle 5 3 y x a Z FO_Pgf za T Y FP_FirstPgf 0 p FO_Cell p FP_LastPgf 0 FP_FirstPgf FP_FirstCellInRow ge FO_Row FO_Cell FO_Pef 1 T z gt FP_NextPgfInFlow FP_PrevPgfInFlow After unstraddle 3 3 y 3 Z 1 FO_Pgf amp i y f FP_FirstPgf gt FO_Cell FO_Pegf a FP_LastPef FIGURE 14 34 Table cells before and after straddle Colors You can assign spot colors to text and objects in a document and you can print process color separations You can also set up color views to specify which colors are visible in a document 338 FDK Programmer s Guide Frame Document Architecture What the user sees FrameMaker provides a set of default colors You can also define your own colors and store them in the document s Color Catalog The FrameMaker product provides three color models for creating your own colors CMYK RGB and HLS It also provides e
2. Add the Code format change list to the format rule clause F_ApiSetString docId clauses val 0 FP_FmtChangeListTag Code Format change list Code Default font properties Family Courier Pair kerning No FIGURE 8 2 Code format change list Creating tables The API provides the following functions for creating tables e F_ApiNewTable is usually easier to use because it allows you to specify a format and the number of rows and columns e F_ApiNewAnchoredObject creates a table with a single column and a single body row For instructions on using F_ApiNewAnchoredOb ject see Creating anchored objects on page 148 The syntax for F_ApiNewTable is FDK Programmer s Guide Creating and Deleting API Objects a F_ObjHandleT F_ApiNewTable F_ObjHandleT doclId StringT format IntT numCols IntT numBodyRows IntT numHeaderRows IntT numFooterRows TextLocT textLocp This argument Means docId The ID of the document format The table format tag for example FormatA or Wide Table To use the default format specify NULL The default format is the format of the last table the user inserted numCols The number of columns in the table To use the default number of columns from the Table Catalog format specify 1 numBodyRows The number of rows in the table To use the default number of body rows from the Table Catalog format specify 1 numHeaderRows The
3. F_Printf NULL StringT n n EXPORT FILTERS n n exportFilters F_ApiGetStrings 0 FV_SessionId FP_ExportFilters for i 0 i lt exportFilters len i F_Printf NULL StringT s n exportFilters val i F_ApiDeallocateStrings amp importFilters F_ApiDeallocateStrings amp exportFilters Associating a file format with signature bytes Some file formats have signature bytes Signature bytes are a set of bytes with a unique value and location in a particular file format FrameMaker can use signature bytes to automatically identify a file s format The documentation for the file format your client converts may contain information on the signature bytes for that format FrameMaker allows you to associate a set of signature bytes with a specific file format When the FrameMaker product opens a file containing the signature bytes it assumes the file has the specified file format and calls the appropriate filter for that format For more information on registering signature bytes see the FDK Platform Guide for your platform FDK Programmer s Guide 255 12 Using Imported Files and Insets Writing graphic inset editors 256 Graphic In addition to creating graphic insets by calling F_ApiImport you can create and maintain graphic insets with a client or application called a graphic inset editor A graphic inset editor saves graphics in a format that FrameMaker
4. E a ol F_ApiSetTextRang FV_SessionId docId FP_TextSelection The following code selects all the text in a cell F_ObjHandlel tr dociId celllid F_TextRangeT Get document and cell IDs here tr beg objId tr end objId cellld tr beg offset 0 tr end offset F_ApiSetTextRang FV_OBJ_END_OF FSET FV_SessionId docId FP_TextSelection FDK Programmer s Guide amp tr amp tr 117 o 6 Manipulating Text 118 Getting the text in a text range To get the text in a specific text range use F_ApiGetTextForRange The syntax for F_ApiGetTextForRange is F_TextItemsT F_ApiGetTextForRange F_ObjHandleT doclId F_TextRangeT tr IntT flags This argument Means docId The ID of the document containing the text range tr The text range containing the text you want to get flags Bit flags that specify the type of text items to retrieve For a complete list of the constants that represent text item types see F_ApiGetText on page 164 of the FDK Programmer s Reference For example the following code gets the selected text in the active document F_ObjHandleT docId F_TextRangeT tr F_TextItemsT tis docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection If there s just an insertion point no text is selected if tr beg objId tr end o
5. FrameMaker recognizes this syntax and interpret the descriptions of the dialog box and its items as special Frame graphic objects Figure 10 3 shows the object properties for the OK button described in the previous example FDK Programmer s Guide 179 Creating Custom Dialog Boxes for Your Client Dialog Item Properties 2220p FiGuRE 10 3 Object properties for a button in a dialog box By moving and resizing these special objects and changing their properties within FrameMaker you modify the dialog description in the DRE file When you save a DRE file the changes that you make are saved back to the file in the special DRE syntax DRE files and platform specific views of dialog boxes You can open and edit a DRE file in any version Windows Macintosh UNIX of FrameMaker Since the geometry of a dialog box is different on each platform the Frame DRE file format uses separate statements to store the geometry information for each platform lt DialogBox lt MBrect 1 1 358 350 gt Dialog box size on the Macintosh lt WBRect 1 1 477 465 gt Dialog box size in Windows lt XBRect 1 1 367 388 gt Dialog box size in X Windows lt Platforms MWX gt Geometry info stored for these platforms At a given time FrameMaker uses geometry information for a specific platform to display a dialog box The geometry information specific to one platform is called the platform view of a dialog box Since a DRE file can
6. This argument Means docId The ID of the document to which to add the element elemDefId The ID of the element definition for the new element textLocp The text location at which to insert the new element The syntax for F_ApiNewElementInHierarchy is F_ObjHandleT F_ApiNewElement InHierarchy F_ObjHandleT docId F_ObjHandleT elemDefId F_ElementLocT elemLocp This argument Means docId The ID of the document or book to which to add the element elemDefId The ID of the element definition for the new element elemLocp The location at which the element is inserted You can t use F_ApiNewElementInHierarchy to add elements to an unstructured document You must structure the document first by adding a root element with F_ApiNewElement Examples The following code adds a Para element at the insertion point F_ElementRangeT elemSelect F_ObjHandleT docId elemId paraEdefId Get ID of active document and the Para element definition docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc paraEdefId F_ApiGetNamedObject docId FO_ElementDef Para Get current elemen elemSelect F_ApiGet FP_ selection in active document lementRange FV_SessionId docId lement Selection tT S CI if elemSelect beg parentId 0 paraEdefId 0 return Insert the new element elemId F_ApiNewElementInHierarchy docId paraEdef
7. tabs val tabs len 1 leader F_StrCopyString Set paragraph format s tabs property to the array of tabs F_ApiSetTabs docId pgfFmtId FP_Tabs amp tabs FDK Programmer s Guide Getting and Setting Properties 5 F_ApiDeallocateTabs amp tabs Getting and setting book properties To rearrange book components you change their FP_PrevComponentInBook and FP_NextComponent InBook properties For example to move the first component in a book down one position you can use the following code F_ObjHandleT bookId firstC nextC bookId F_ApiGetId 0 FV_SessionId FP_ActiveBook firstC F_ApiGetId FV_SessionId bookId FP_FirstComponent InBook nextC F_ApiGetId bookId firstC FP_NextComponentInBook if nextC F_ApiSetId bookId firstC FP_PrevComponentInBook nextC else F_ApiAlert Only one component FF_ALERT_CONTINUE_NOTE Getting and setting FrameMaker properties There are some special issues involved in getting and setting properties in structured FrameMaker documents The following sections discuss some of these issues Traversing elements To traverse the elements in a structured FrameMaker document you use slightly different code than you would use to traverse other objects such as paragraphs If you want to traverse all the elements in a document you can t query only FP_NextSiblingElement properties You must also recursively traverse
8. F_ApiAlert Couldn t compare FF_ALERT_CONTINUE_NOTE FDK Programmer s Guide 69 a Executing Commands with API Functions Compare Documents Comparison Options GPREFACE FM FIGURE 4 2 Specifications for Compare Documents Updating and generating documents and books The API provides a variety of functions that allow you to generate update and reformat documents and books The following sections discuss these functions Updating the files in a book To update the numbering text insets cross references etc in all the files in a book and to programmatically specify responses to warnings and messages that the FrameMaker product issues use F_ApiUpdateBook You can specify all aspects of the operation or you can specify some aspects and allow the user to decide others For example you can instruct the FrameMaker product to update view only files or to abort the update when it encounters a view only file To use F_ApiUpdateBook you should first understand property lists and how to manipulate them directly For more information on this subject see Representing object characteristics with properties on page 270 and Manipulating property lists directly on page 93 The syntax for F_ApiUpdateBook is ErrorT F_ApiOpen F_ObjHandleT bookId F_PropValsT updateParamsp F_PropValsT updateReturnParamspp 70 FDK Programmer s Guide Executing Commands with API Functions 4
9. Language FrameMaker internal encoding names Roman FrameRoman Japanese JISX0208 ShiftJIS Traditional Chinese Big5 Simplified Chinese GB2312 80 EUC Korean KSC5601 1992 FrameMaker Roman encoding 8 bit Roman character sets all share the same 7 bit ASCII characters FrameMaker also uses the characters in the x80 xFF range for special characters such as non breaking hyphens or em spaces Asian fonts cannot be expected to support the same special characters As a result if the FP_DialogEncodingName is set to an Asian encoding the user cannot type these special characters in text boxes or other parts of the user interface that are controlled by this setting However the user can type these characters in document text whenever the current font is a Roman font that supports them FDK Programmer s Guide 133 Manipulating Asian Text Using encoding data The FDE provides functions to operate on strings and characters of a specified internal encoding To use font encoding information you must first initialize the font encoding data Then you can get the internal encoding for a given character or string set the encoding or convert from the FrameMaker internal encoding to a different one from Shift JIS to EUC for example Initializing encoding data and setting the U I encoding The API uses F_FdeInitFontEncs to e initialize the font encoding data e set the encoding for your client s user interface Initializing the e
10. The code reads the input file and write MIF to the output file This isn t a useful exampl you would need to parse the input in order to find reasonable paragraph boundaries xf while F_ChannelEof inChan count F_ReadBytes buf BUFSIZE 1 inChan buf count 0 F_MifBegin Para F_MifBegin ParaLine F_MifBegin String F_MifTextString StringT buf FM F_M FM ifEnd String LfEnd ParaLine ifEnd Para Now the code frees memory and sets the return value to success F_FilePathFree F_ChannelClose F_FilePathFree F_ChannelClose inPath inChan outPath r outChan F_ApiReturnValue 0 Registering filters For the FrameMaker product to call your client to filter files you must register the client and the formats it filters IMPORTANT When you register a filter the client name and the display name the name that appears in the Open or Save As dialog box must be the same On UNIX and Windows platforms you specify the filename extensions of the formats your client filters in the client s entry in the registration file On Macintosh platforms you specify the file types of the formats your client filters in the client s resource fork To identify your filter to the FrameMaker product you specify a vendor ID and format ID when you register it The format ID is a four
11. Paragraph Catalog formats Each document has a Paragraph Catalog containing one or more Paragraph Catalog formats What the user sees Each Paragraph Catalog format specifies aspects of a paragraph s appearance such as its indents line spacing and default font Each format has a name or tag which usually corresponds to a type of paragraph such as title body or heading To make a paragraph s appearance conform to a format you apply the format to the paragraph You can apply the same format to multiple paragraphs to ensure consistency in your document FDK Programmer s Guide Frame Document Architecture CE You can add formats to the Paragraph Catalog or modify or delete formats that are already in it How the API represents Paragraph Catalog formats FrameMaker represents each Paragraph Catalog format with an FO_PgfFmt object whose properties provide the following information e The name of the paragraph format e Formatting information e The ID of the next FO_PgfFmt object in the document Suppose you create the paragraph format described in the Paragraph Designer in Figure 14 13 Paragraph Tag M Autonumber Format Step M Properties fene gt At Numbering Building Blocks Character Format Default 4q Font Apply To Selection Update All Formats Tagged Step Position Start of Paragraph Commands rp FIGURE 14 13 Paragraph Designer The API represents this paragraph
12. F_ApiSetString menulId cmdlid FP_HelpLink my hlp Opens my hlp and jumps to mylink when help is requested F_ApiSetString menuld cmd2Id FP_HelpLink my hlp mylink IMPORTANT Do not set the FP_HelpLink property to a hypertext command such as gotopage or nextpage 176 FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client This chapter describes how to use FrameMaker to create and modify custom dialog boxes that you can use in your client s user interface You can create a dialog box that contains the following items e Boxes Buttons Checkboxes Pop up menus with a standard appearance or drawn from bitmap images Radio buttons Scroll bars Scroll lists Text boxes with one or more lines If your client s user interface requires only simple modal dialog boxes you may not need to create custom dialog boxes The API provides several simple ready made modal dialog boxes For information on using these dialog boxes see Using API dialog boxes to prompt the user for input on page 17 Overview The process of including a custom dialog box in your client involves the following general steps 1 Create the custom dialog box Creating a dialog box involves designing its layout and items and saving this information in a file format that can be used to build your FDK client Instructions for this step are presented in this chapter 2 Write the code in you
13. FrameMaker products assign an identifier ID to each object in a session You use this ID to identify an object when you call API functions An object s characteristics are called properties Each type of object has a particular set of properties or a property list For example an FO_Rectangle object s property list includes properties named FP_Width and FP_Height which represent its height and width An FO_Pgf object s property list includes properties named FP_LeftIndent and FP_Leading which represent its left indent and its leading Each property has a predetermined data type such as IntT integer Boolean or ordinal St ringT string or F_ObjHandleT object ID Each of an individual object s properties has a value This value describes the property for that particular object For example suppose a document contains a smoothed rectangle that is 20 points wide and 10 points high The Frame API represents the rectangle as an FO_Rectangle object with the following properties and values TABLE 1 1 Property Data Type Value FP_Width Met ricT 20 65536 FP_Height Met ricT 10 65536 FP_RectangleIsSmoothed IntT True 1 Frame API objects should not be confused with the graphic objects that you create with the Tools palette object elements in structured documents or the objects of object oriented programming languages FDK Programmer s Guide re Introduction to the Frame API TABLE 1 1 Property Data Type
14. Get the document current page and page frame IDs The F_ApiGet property_type and F_ApiSet property_type functions are explained in Chapter 5 y docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc pageId F_ApiGetId FV_SessionId docId FP_CurrentPage pFrameId F_ApiGetId docId pageId FP_PageFrame Create the circle on the page frame circleId F_ApiNewGraphicObject docId FO Ellipse pFrameld Change the size of the circle to 1 inch FDK Programmer s Guide 147 az Creating and Deleting API Objects 148 F_ApiSetMetric docId circleId FP_Height in F_ApiSetMetric docId circleId FP_Width in Move the circle toward the center of the page F_ApiSetMetric docId circleId FP_LocX 2 in F_ApiSetMetric docId circleId FP_LocY 3 in Creating anchored objects An anchored object is an object such as a cross reference table or anchored frame that the user can insert in text The API provides the following functions to create anchored objects e Tocreate tables use F_ApiNewTable e To create variables and cross references use F_ApiNewAnchoredFormattedObject e To create other anchored objects use F_ApiNewAnchoredObject F_ApiNewTable is discussed in Creating tables on page 154 The syntax for F_ApiNewAnchoredFormattedOb ject and F_ApiNewAnchoredObject is F_ObjHandleT F_ApiNewAnchoredFormattedObject F_ObjHandleT docId
15. VoidT F_Apilnitialize initialization IntT initialization F_ObjHandleT specialMenuld Get the ID of the special menu specialMenulId F_ApiGetNamedObject FV_SessionId FO Menu SpecialMenu Define the commands and add them to the Special menu F_ApiDefineAndAddCommand LOAD specialMenuld LoadDatabase Load Database F_ApiDefineAndAddCommand QUERY specialMenulId QueryDatabase Query Database VoidT F_ApiCommand command IntT command switch command case LOAD Code to load database goes here break case QUERY Code to query database goes here break FDK Programmer s Guide 29 a Creating Your Client s User Interface 30 Replacing FrameMaker product menus and commands You can replace FrameMaker product menus and commands with your own menus and commands by calling F_ApiDefineAndAddCommand and F_ApiDefineAndAddMenu with the name parameter set to the name of a FrameMaker product menu or command For example the following code replaces the FrameMaker product Print command define PRINT_C 223 F_ObjHandleT fileMenulId printCmdId fileMenuId F_ApiGetNamedObject FV_SessionId FO Menu FileMenu F_ApiDefineAndAddCommand PRINT_CMD fileMenuld Print Print fp printCmdId If you use this code the Print command appears on the File menu exactly as it normally would However when the us
16. 2 2 20 20 0 00040 17 Making I O and Memory Calls Portable Initializing the FDE 2 2 a ET a ee A Using platform independent representations of pathnames Making I O portable with channels 00 Assertion handler functions 0000005 Making memory allocation portable Error and progress reporting 000 e ee eee 18 FDE Utility Libraries String library 2 ee The string list library s a s s s acses ee adka Character library ooa ee The I O library aoaaa The hash library 2 a Metric library 2 ee MIF data structures and macros 0004 The MIF library lt cc ea tiea ee Simple MIF library oaa ee FDK Programmer s Guide Using Frame Developer Tools The Frame Developer s Kit The Frame Developer s Kit FDK provides tools for developers to enhance the functionality of FrameMaker This chapter provides an overview of the FDK and other aspects of FrameMaker that are useful for developers It also discusses the FDK documentation The principal parts of the FDK are e Frame Application Program Interface API e Frame Development Environment FDE e Frame Structure Import Export Application Program Interface Structure Import Export API The following sections describe these parts and discuss how you can use them Frame API The Frame API allows you to write C language programs called FDK clien
17. Dialog boxes on page 531 of the FDK Programmer s Reference For instructions on getting and setting properties see Chapter 5 Getting and Setting Properties If you set the text of a label in your client code you must make sure that the DRE file defines an adequate space for the text Otherwise the text set by your client may appear truncated For example suppose you add a label to a DRE file and specify String as the text in the label In your client code if you set this label to String of text the actual label in the dialog box only displays the word String and truncates the rest of the label of text To prevent this select the label and type the longest string of text set by your client code If you do not want this string of text to appear when the dialog box is displayed you can initialize the value of the label in your client code so that the long string is not displayed by default For examples of initializing the values of dialog items see Initializing items in a dialog box on page 218 For information on setting the basic properties for this dialog item see the section Setting basic dialog item properties on page 197 Scroll bars A scroll bar allows the user to choose a value within a specified range Each end of the scroll bar represents one end of the range You specify a scroll bar s range in your client code To do this set the minimum and maximum value properties on the API object representing
18. FF_INSERT_BELOW_RIGHT Add columns to the right ofthe F_ApiPaste current column or below the current row FF_VISIBLE_ONLY Cut copy paste or clear only All Clipboard functions the visible portion of the selection FF_REPLACE_CELLS Replace selected cells with cells FF_DONT_APPLY_ALL_ ROWS on the Clipboard Don t apply condition setting on the Clipboard to all rows If whole table is selected and Clipboard contains condition setting cancel the paste F_ApiPaste F_ApiPaste The FF_INTERACTIVE flag takes precedence over other flags So if you specify FF_INTERACTIVE 128 FF_DONT_DELETE_HIDDEN_TEXT and the selection contains hidden FDK Programmer s Guide Manipulating Text text the FrameMaker product prompts the user and allows the user to choose whether to delete the hidden text Saving the Clipboard contents In some cases you may want to use the Clipboard and then restore its original contents when you are done The API provides a Clipboard stack which allows you to do this To manipulate the Clipboard stack use F_ApiPushClipboard and F_ApiPopClipboard The syntax for these functions is IntT F_ApiPushClipboard VoidT IntT F_ApiPopClipboard VoidT F_ApiPushClipboard pushes the current Clipboard contents onto the Clipboard stack F_ApiPopClipboard pops the set of Clipboard contents on the top of the Clipboard stack to the Clipboard For example the following code ex
19. FIGURE 3 5 File selection dialog box Using scroll list dialog boxes To display a scroll list dialog box use F_ApiScrollBox F_ApiScrollBox displays an array of items that you provide and allows the user to choose one The syntax for F_ApiScrol1lBox is IntT F_ApiScrollBox IntT selected_item StringT title F_StringsT stringslist IntT default This argument Means selected_item The index of the selected item when the user clicks OK or double clicks an item The index of the first item is 0 title The title that appears on the dialog box FDK Programmer s Guide Creating Your Client s User Interface a This argument Means stringslist The list of items that appears in the scroll list default The index of the item that is selected when the dialog box first appears For no default specify 1 F_StringsT is defined as typedef struct UIntT len Number of strings StringT val Array of strings F_StringsT The F_ApiScrollBox function returns a nonzero value if the user clicks Cancel or an error occurs or 0 if the user clicks OK Example To create the dialog box shown in Figure 3 6 add the following code to your client include futils h IntT err choice listLen 3 UCharT msg 256 F_StringsT colors colors val StringT F_Alloc listLen sizeof StringT NO_ DSE if colors val colors len UIntT listLen colors va
20. GEM GIF HPGL IAF IGES IMG4 MOOV vs Gg nj PCX Y PICT PNTIG RIF SNRE TIFF Description Autodesk CAD Enhanced Metafile Windows Encapsulated PostScript Binary Windows Encapsulated PostScript DCS Encapsulated PostScript Macintosh Encapsulated PostScript Interchange Frame Vector CCITT Group 4 to Image GEM Windows Graphic Image File Format CompuServe Hewlett Packard Graphics Language Interleaf compound document CAD format Image to CCITT Group 4 UNIX QuickTime Movie MIF to IAF export Maker Markup Language MML MIF to RTF export MIF to WordPerfect export Object Linking and Embedding Client Microsoft PC Paintbrush QuickDraw PICT MacPaint Microsoft s RTF compound document Sun Raster File Tag Image File Format TROFF to MIF UNIX only Windows Metafile MS Word compound document FDK Programmer s Guide Using Imported Files and Insets 12 Value Description WPBN WordPerfect compound document WPG WordPerfect Graphics XWD X Windows bitmap FrameMaker does not supply filters for all of these formats on all platforms However you should not use one of these format IDs unless your client filters the corresponding file format For the complete syntax of import hint strings see Syntax of FP_ImportHint strings on page 600 of the FDK
21. To do this Use this shortcut Test the dialog box as modeless UNIX and Windows only Esc d T View the dialog box as it appears in the Macintosh versions Escdm View the dialog box as it appears in the Windows versions Esc d w View the dialog box as it appears in the UNIX versions Esc d x Clear the geometry information for the current platform view from local Escdr memory FDK Programmer s Guide Handling Custom Dialog Box Events This chapter describes how to use custom dialog boxes in your client s user interface For instructions on creating custom dialog boxes see Chapter 10 Creating Custom Dialog Boxes for Your Client If your client s user interface requires only simple modal dialog boxes you may not need to create or use custom dialog boxes The API provides several simple ready made modal dialog boxes For information on using these dialog boxes see Using API dialog boxes to prompt the user for input on page 17 How the API represents dialog boxes The API uses an FO_DialogResource object to represent each dialog resource in a FrameMaker product session It also uses an object to represent each item in a dialog resource The following table lists the types of dialog items and the types of objects the API uses to represent them Dialog item API object type Box FO_D1lgBox Button FO_DlgButton Checkbox FO_DlgCheckBox Image pop up menu FO_DlgImage Label FO DlgLabel Pop up menu FO_DlgPopUp Radio
22. if F_ApiCheckStatus returnParamsp FV_FileWasInuUse F_ApiAlert Save cancelled file is in use FF_ALERT CONTINUE _NOTE Deallocate property lists F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp The API provides a utility function named F_ApiPrintSaveStatus which prints the save error values to the console on UNIX platforms the FrameMaker console on Windows and the error log window on the Macintosh For more information see F_ApiPrintSaveStatus on page 253 of the FDK Programmer s Reference Example The following code opens tmp my doc and saves it as a View Only document named tmp viewonly doc It gets the name of the saved file from the returned property list and displays it FDK Programmer s Guide 65 a Executing Commands with API Functions include futils h IntT i UCharT msg 1024 F_PropValsT params returnParamsp NULL F_ObjHandleT mydocId viewonlydocId params F_ApiAllocatePropVals 1 mydocId F_ApiSimpleOpen tmp my doc False if mydocId return Set file type to View Only params val 0 propIdent num FS_FileType Ss Ss params val 0 propVal valType FT_Integer params val 0 propVal u ival FV_SaveFmtViewOnly Save document as viewonly doc viewonlydocId F_ApiSave mydocId tmp viewonly doc amp params amp returnParamsp Get inde
23. FP_AutoNumString property FO_FmtChangeList G 347 R 584 FP_AutoNumString property FO_Pgf G 303 R 613 FP_AutoNumString property FO_PgfFmt R 623 FP_AutoSave property FO_Session R 632 FP_AutoSaveSeconds property FO_Session G 82 R 632 FP_BaseFamily property FO_CombinedFontDefn R 522 FP_BaselineOffset property FO_AFrame R 596 FDK Programmer s Reference amp Guide Index Reserved Names a FP_BasePointX property FO_Math R 603 FP_BasePointX property FO_TextLine R 606 FP_BasePointY property FO_Math R 603 FP_BasePointY property FO_TextLine R 607 FP_Black property FO_Color R 519 FP_BlockLines property FO_FmtChangeList R 588 FP_BlockLines property FO_Pgf R 619 FP_BlockLines property FO_PgfFmt R 627 FP_BookComponent property FO_Element R 642 FP_BookComponentIsGeneratable property FO_BookComponent R 508 FP_BookComponentMissing property FO_Element R 643 FP_BookComponentType property FO_BookComponent R 508 FP_BookDontUpdateReferences property FO_Book R 495 FP_BookIsModified property FO_Book R 495 FP_BooklsSelected property FO_Book R 495 FP_BookIsViewOnly property FO_Book R 507 FP_BookParent property FO_BookComponent R 508 FP_BookTreeRoot property FO_Book G 355 FP_BorderWidth property FO_GraphicObject R 593 FP_BottomMargin property FO_Doc R 559 FP_BottomRowSelection property FO_Tbl G 87 R 656 FP_BottomSeparator property FO_FmtChangeList R 582 FP_BottomSep
24. FP_FirstCellInRow FP_FirstPef FO_Cell RI Cl Lael FP_NextCellInRow FP_PrevCellInRow y FP_LastPgf FP_FirstPgf FO_Pgf FO_Cell R1 C2 FP_NextRowInTbl y I FP_PrevRowInTbl FO_Row Footer Row FP_FirstCellInRow FP_LastPgf FP_FirstPgf FO_Pgf FO_Cell R2 Cl r FP_PrevCellInRow FP_NextCellInRow y FP_LastPgf FP_FirstPgf FO_Pgf FO_Cell R2 C2 FP_LastPgf FP_FirstPef FO_Pgf FO_Cell R3 Cl r FP_PrevCellInRow FP_NextCellInRow y FO_Cell R3 C2 FP_LastPgf FP_FirstPgf FO_Pgf FP_LastPgf FO_Pgf 335 14 Frame Document Architecture The following table lists some of the FO_Tb1 object s properties 336 Property FP_TblTag FP_TblTopRuling FP_Tb1HFSeparatorRuling FP_Tb1BodyRowRuling ny j FP_TblBodyFirstFill P_FirstRowInTbl P_LastRowInTbl Type StringT F_ObjHandleT F_ObjHandleT F_ObjHandleT IntT F_ObjHandleT F_ObjHandleT Value Format A NULL ID of FO_RulingFmt that represents Double line ID of FO_RulingFmt that represents Thin line 0 ID of FO_Row that represents the heading row row 1 ID of FO_Row that represents t
25. FP_PageNumComputeMethod property FO_Doc R 548 R 560 FP_PageNumString property FO_BodyPage R 611 FDK Programmer s Reference amp Guide FP_PageNumStyle property FO_BookComponent R 512 FP_PageNumStyle property FO_Doc R 560 FP_PagePrefix property FO_BookComponent R 512 FP_PagePrev property FO_BodyPage G 291 FP_PagePrev property FO_HiddenPage R 611 FP_PagePrev property FO_MasterPage G 291 R 612 FP_PagePrev property FO_RefPage G 291 R 612 FP_PageRounding property FO_Doc R 560 FP_PageSide property FO_BookComponent R 512 FP_PageSuffix property FO_BookComponent R 512 FP_PageWidth property FO_BodyPage R 611 FP_PageWidth property FO_Doc R 560 FP_PageWidth property FO_HiddenPage R 612 FP_PageWidth property FO_MasterPage R 612 FP_PageWidth property FO_RefPage R 612 FP_PairKern property FO_CharFmt R 517 FP_PairKern property FO_Doc R 575 FP_PairKern property FO_FmtChangeList R 587 FP_PairKern property FO_Pgf R 615 FP_PairKern property FO_PgfFmt R 624 FP_PairKern property text location R 671 FP_ParentElement property FO_Element R 642 FP_ParentTextFrame property FO_SubCol G 299 R 521 FP_Path property FO_Session R 635 FP_PDFBookmark property FO_Book R 499 FP_PDFBookmark property FO_Doc R 543 FP_PDFBookmarksOpenLevel property FO_Book R 500 FP_PDFBookmarksOpenLevel property FO_Doc R 543 FP_PDFConvertCMY KtoRGB property FO_Book R 500 FP_PDFConvertCMYKtoRGB property FO_Doc
26. This argument Means bookId The ID of the book you will update updateParamsp A property list script that tells the FrameMaker product how to update the book and how to respond to errors and other conditions that arise Use F_ApiGetUpdat eBookDefaultParams or F_ApiAllocatePropVals to create and allocate memory for this property list To use the default list specify NULL updateReturnParamspp A property list that provides information on how the FrameMaker product updated the book IMPORTANT Always initialize the pointer to the property list that you specify for openReturnParamspp to NULL before you call F_ApiUpdateBook If F_ApiUpdateBook is successful it returns FE_Success Otherwise it returns an error which has the same value as FA_errno To call F_ApiUpdateBook do the following 1 Initialize the pointer to the updateReturnParamspp property list to NULL 2 Create an updateParamsp property list You can get a default list by calling F_ApiGetUpdateBookDefaultParams or you can create a list from scratch 3 Call F_ApiUpdateBook 4 Check the Update status Check the returned values in the updateReturnParamspp list for the name of the opened file and other information about how the FrameMaker product opened the file 5 Deallocate memory for the updateParamsp and updateReturnParamspp property lists Use F_ApiDeallocatePropVals to deallocate memory for the lists Generating files for a book
27. UIntT len The number of text items F_TextItemT val Array of text items F_TextItemsT The API represents an individual text item with an F_TextItemT structure which is defined as typedef struct IntT offset Characters from the beginning IntT dataType The type of text item e g FTI_String union StringT sdata String if type is FTI_String IntT idata An ID if the item specifies an object u F_TextItemT The offset value specifies the distance between the start of the text item and the beginning of the text line or paragraph This distance is measured in the number of characters both regular characters and anchor symbols Each of the following constitutes a separate text item e A string of characters with common text properties A text item can contain a string that is as long as a line of text However the API uses a separate text item for each section of the text that has different text properties If a single property such as the font weight font angle or condition format is different the API starts a new text item So a single line of text may require several text items to represent it e The beginning or end of a line paragraph flow column page or structural element The API uses text items to indicate the beginning or end of the various entities that organize text Most of these text items specify the ID of an object Text items that indicate the end
28. UlLanguage represents the user interface language such as usenglish for US English and Productinterface is the name of the product interface either maker or structured For information on where the menus are listed on other platforms see the FDK Platform Guide for your platform The following table lists some FrameMaker product menus and the names you use to specify them Menu title Edit Element File Format Graphics Special Table View Help Name EditMenu ElementMenu FileMenu FormatMenu GraphicsMenu SpecialMenu TableMenu ViewMenu HelpMenu The following table lists the names of some FrameMaker product menu bars Menu bar names starting with an exclamation point can t be removed by the user FrameMaker product menu bar Menu bar for documents complete menus Menu bar for documents quick menus Menu bar for books complete menus Menu bar for books quick menus Name MakerMainMenu QuickMakerMainMenu BookMainMenu QuickBookMainMenu FDK Programmer s Guide 25 a Creating Your Client s User Interface 26 FrameMaker product menu bar Name View only menu bar ViewOnlyMainMenu Example The following code gets the ID of the Edit menu and the view only menu bar F_ObjHandleT editMenulId viewOnlyMenuBarlId editMenuld F_ApiGetNamedObject FV_SessionId FO_Menu EditMenu viewOnlyMenuBarId F_ApiGetNamedOb ject FV_SessionId FO_Menu Vi
29. e Display properties such as book window size and location text to show for each component and text in the book s status line e Whether or not the book is view only and view only display properties e Selection state whether the book icon is selected the first selected component or the range of selected structure elements in the book e Properties that determine how to print the book and save it as PDF e For structured books structure properties such as the element catalog for the book and the ID of the highest level element in the book An FO_BookComponent object represents an individual book component It has properties that provide the following information e The name of the document represented by the component e The IDs of the next and previous component in the book and the next selected component in the book e Whether the component is generated and the type of generated file in other words whether the component is a specific type of list or index e Whether to include the component in print update and import formats operations e The list of paragraph format tags the product uses to generate a list from this component e The ID of the parent book e Numbering and pagination properties for the component these properties may differ from the document s specific set of numbering properties e For structured books the structural element representing the book component Suppose you create the book in Figure 15 1 The
30. All types of API graphic objects also have several properties that are specific to them For example FO_Arc objects have a property named FP_Theta that specifies an arc s theta value Suppose you create the arrow shown in Figure 14 6 H i A RENE EAA Pet E EEA AARAA PEER DETE SAE AAAA AERA LPE ERA PE EATE i FIGURE 14 6 Arrow in an unanchored frame 2 This manual uses the term API graphic object to refer to objects suchas FO_Polygon and FO_TextFrame objects that the API uses to represent the graphic objects such as polygons and text frames that appear on a page 294 FDK Programmer s Guide Frame Document Architecture CE The API represents the arrow with an FO_Line object whose properties include those shown in the following table Property Type Value FP_FrameParent F_ObjHandleT ID of the frame containing the arrow FP_Pen IntT FV_FILL_BLACK FP_LocxX MetricT 250 in FP_Locy MetricT 1 125 2n FP_HeadArrow IntI True FP_ArrowType IntT FV_ARROW_HOLLOW How the API organizes graphic objects The API maintains each API graphic object in at least two linked lists e The list of all the API graphic objects in the document For convenience the API maintains a linked list of all the API graphic objects in a document The FO_Doc property FP_FirstGraphicInDoc specifies the ID of the first object in the list API graphic objects have a property named FP_NextGraphicInDoc which specifies the ID of the next API grap
31. Called when cell is deleted VoidT removeNotify GenericT Converts key to string Void T stringifyMe PtrT UCharT e Use minSize to suggest the amount of space the FDE should allocate for the hash table You can pass a value of 0 which notifies the FDE to use its own calculations for memory allocation e For non string keys you specify a value for the size of key For keys that are strings you specify KEY_IS_STRING in that case each key is a nul terminated string e F_HashGet is a routine that searches for a key and returns the associated data If it can t find the specified key it still must return a value the notFound argument specifies what value to return when F_HashGet doesn t find the key e deadQuery specifies a callback to give you the opportunity to determine the validity of a cell You should only specify a function for this argument if your code can make this determination if the function returns True the cell will be marked for deletion As the FDE hash routines maintain the table they will call this function to determine whether they can delete the cell s contents Normally it is best to specify 0 for this arument letting the FDE manage the hash table on its own e removeNotify specifies a callback to invoke whenever an F_Hash function or the FDE removes a cell A typical use for this is to deallocate structures that were allocated for the cell s data If you don t need to c
32. Handling user actions in multiple modeless dialog boxes The API allows you to have multiple modeless dialog boxes open at the same time To handle user actions in multiple dialog boxes you must keep track of each dialog resource s number and ID The API does not pass a dialog resource s ID to F_ApiDialogEvent so you must store each dialog resource s ID to a global variable that you associate with the dialog resource s number For example the following code opens two dialog boxes and handles user actions in them define DLG1_NUM 1 define DLG2_NUM 2 F_ObjHandleT dlglId dlg2Id Global variables digliId essDial F_ApiMode F_ApiMode essDial og D og D FDK Programmer s Guide F_ApiOpenResource FO_DialogResource dialogl dig2Id F_ApiOpenResource FO_DialogResource dialog2 G1_NUM dl G2_NUM dl glid g2Id 225 E Handling Custom Dialog Box Events VoidT F_ApiDialogEvent dlgNum itemNum modifiers IntT dlgNum IntT itemNum IntT modifiers F_ObjHandleT itemId if itemNum FV_DlgClose return switch dlgNum case DLG1_NUM itemId F_ApiDialogItemId dlglId itemNum Code to get item properties goes here break case DLG2_NUM itemId F_ApiDialogItemId dlg2Id itemNum Code to get item properties goes here break Handling special events in a modeless dialog box There are several special dialog bo
33. e Its attributes e The ID of the object that represents its element definition e The IDs of its parent and immediate sibling elements e The IDs of the first and last FO_Element objects in the linked list of its child FO_Element objects e Whether the element is collapsed e Whether the element is valid and if it is invalid the reasons it is invalid e The ID of the object associated with the FO_Element object if the element is a noncontainer element such as a marker or a system variable e The element s context label e The format rule clauses that apply to the element How the API represents a structural element s validity An element can be invalid in several ways For example its parent s content rule may not allow it or it may contain a child element that is not allowed FO_Element objects have validation properties that indicate the extent of an element s validity For example an element has a property named FP_ElementIsInvalidInParent which is setto True if the element is not allowed by its parent element Changing an element When using FrameMaker an author can select elements and wrap merge or change them The API provides functions to wrap and merge elements directly for example F_ApiMergeIntoFirst However there is no corresponding function to directly change an element Changing an element corresponds to a user selecting an element in the document selecting an element name in the Element catalog and t
34. function R 4 F_ApiCopyMetrics function R 69 F_ApiCopyPoints function R 4 R 69 F_ApiCopyProp function R 69 F_ApiCopyPropVal function R 4 F_ApiCopyPropVals function R 4 R 69 F_ApiCopyString function R 4 R 69 F_ApiCopyStrings function R 4 R 69 F_ApiCopySt ructureType functions R 69 F_ApiCopyTabQ function R 4 R 69 F_ApiCopyTabs function R 4 R 69 F_ApiCopyTextItem function R 4 F_ApiCopyTextltem function R 70 F_ApiCopyTextltems function R 4 R 70 F_ApiCopyUBytes function R 4 R 70 F_ApiCopyUInts function R 4 R 70 F_ApiCopyVal function R 4 R 70 F_ApiCustomDoc function G 53 G 55 G 372 R 6 R 70 F_ApiCut function G 127 R 3 R 23 R 72 F_ApiDeallocateAttribute function R 74 F_ApiDeallocateAttributeDef function R 74 F_ApiDeallocateAttributeDefs function R 74 F_ApiDeallocateAttributes function R 74 F_ApiDeallocateElementCatalogEntries function R 74 F_ApiDeallocateFonts function R 11 R 74 F_ApiDeallocateInts function R 74 F_ApiDeallocateInts function R 11 F_ApiDeallocateMetrics function G 95 R 11 F_ApiDeallocatePoints function R 74 F_ApiDeallocatePoints function R 11 F_ApiDeallocateProp function R 11 F_ApiDeallocatePropVal function G 124 R 74 F_ApiDeallocatePropVals function G 52 G 92 G 95 G 124 G 232 R 11 R 74 F_ApiDeallocateString function R 11 R 74 F_ApiDeallocateStrings function G 95 R 11 R 74 F_ApiDeallocateSt ructureType functions R 74 index 36
35. returnParamsp NULL F_ObjHandleT docId F_TextRangeT tr IntT i Get default import list Return if it can t be allocated params F_ApiGetImportDefaultParams if params len 0 return Get current insertion point Return if there isn t one FDK Programmer s Guide Using Imported Files and Insets docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection if tr beg objId 0 return Change properties to import text into a table i F_ApiGetPropIndex amp params FS_FileIsText params val i propVal u ival FV_DoImportAsTable The following specifies the file format as ISO encoded text ali PropIndex amp params FS _FileTypeHint i propVal u sval F_ApiCopyString ConStringT O001PGRETXIS i F_ApiGetPropIndex amp params FS_DisallowMIF params val i propVal u ival True i F_ApiGetPropiIndex amp params FS_DisallowDoc params val i propVal u ival True i F_ApiGetPropIndex amp params FS_DisallowGraphicTypes params val i propVal u ival True i F_ApiGetPropIndex amp params FS_ImportTblTag params val i propVal u sval StringT F_StrCopyString Format A i F_ApiGetPropIndex amp params FS_CellSeparator params val propVal u sval StringT F_StrCopyString t H F_ApiImport
36. t in a paragraph or flow for more information on text lines see Text on page 311 e A text frame which is a container for text in a flow for more information on text frames see Text on page 311 e An imported graphic such as a bitmap or a PostScript file created with another application e An inset or imported graphic e A math equation which describes a formatted equation You can draw a graphic object directly on a page in a document A graphic object drawn directly on a page doesn t move as you edit the text around it You can also draw a graphic object inside an anchored or unanchored frame When you move a frame all the graphic objects inside it move with it You can nest frames that is you can draw a frame within a frame within a frame Draw order The graphic objects in a frame have a back to front order or draw order that specifies the order in which the FrameMaker product draws them By default the draw order is the same as the order in which you created the objects When graphic objects overlap the ones in front at the end of the draw order obscure those in back You can change the draw order by selecting a graphic object and choosing Front or Back from the Tools palette Groups You can create a group from one or more graphic objects This allows you to manipulate them as a single object When you resize the group the FrameMaker product automatically resizes the group s component objects proportion
37. 1 Write an initialization function Most clients need to define an F_ApilInitialize callback function When the FrameMaker product starts it calls your client s F_ApiInitialize function Normally you will want to include code in F_ApiInitialize to set up your client s menus and request notification for particular events For more information on creating an F_ApiInitialize callback see Chapter 2 API Client Initialization 2 Set up the client s user interface Your client probably needs to interact with the user To respond to user actions you can define the following callback functions in your client e F_ApiNotify to respond to the user initiating FrameMaker product operations such as Open and Save e F_ApiCommand to respond to the user choosing menu items created by your client e F_ApiMessage to respond to the user clicking hypertext markers that contain the message apiclient command e F_ApiDialogEvent to respond to the user manipulating items in a dialog box created by your client You can also display notices and prompt the user for input by using API dialog box functions suchas F_ApiAlert and F_ApiPromptString For more information on setting up your client s user interface see Chapter 3 Creating Your Client s User Interface 3 Add code to programmatically execute FrameMaker product commands Your client probably needs to execute some FrameMaker product commands suc
38. FDK 7 0 Programmer s Adobe Guide 2002 Adobe Systems Incorporated All rights reserved Adobe FrameMaker 7 0 User Guide for Windows Macintosh and UNIX This manual as well as the software described in it is furnished under license and may be used or copied only in accordance with the terms of such license The content of this manual is furnished for informational use only is subject to change without notice and should not be construed as a commitment by Adobe Systems Incorporated Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in this book Except as permitted by such license no part of this publication may be reproduced stored in a retrieval system or transmitted in any form or by any means electronic mechanical recording or otherwise without the prior written permission of Adobe Systems Incorporated Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner Please be sure to obtain any permission required from the copyright owner Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization Adobe the Adobe logo Acrobat Acrobat Reader Adobe Type Manager ATM Display PostScript D
39. FDK Programmer s Reference amp Guide Index Subjects a properties of G 10 G 83 G 275 G 276 to G 277 R 631 to R 638 getting and setting G 95 to G 97 quitting Frame sessions G 67 function for R 17 setting attribute definitions R 278 to R 280 attributes R 280 to R 282 byte ordering on I O channels G 382 channel offsets R 357 R 358 dash patterns R 294 R 595 element range R 282 to R 284 fill patterns G 11 the insertion point G 114 to G 117 properties G 7 G 37 G 45 G 89 to G 92 G 95 to G 105 G 162 property lists G 92 to G 94 text properties G 93 G 124 to G 126 G 317 text selections G 114 to G 117 type in properties G 126 SGML attributes G 348 shift menu items G 174 to G 175 shortcuts See keyboard shortcuts shorts 2 bytes FDE function for reading and swapping R 430 FDE function for writing and swapping R 491 sibling elements structural traversing G 121 simple functions API G 45 simple MIF functions G 381 G 387 simple MIF library FDE See simple MIF functions single interaction dialog boxes G 223 handling user actions in G 223 single sided documents master pages for G 289 G 292 sleep functions R 17 R 328 R 344 to R 345 special characters specifying G 121 G 316 to G 317 R 41 Special menu adding commands to G 29 name used to specify G 25 R 76 specified persistent identifiers See UIDs unique IDs spell checking paragraphs property for R 618 spot color views bit positions representing illust
40. FP_UseOutline property FO_CharFmt R 518 FP_UseOverline property FO_CharFmt R 518 FP_UsePairKern property FO_CharFmt R 518 FP_UsePosition property FO_CharFmt R 518 FP_UserHomeDir property FO_Session R 637 FP_UserLogin property FO_Session R 637 FP_UserName property FO_Session R 637 FP_UserString property G 110 FP_UserString property FO_CombinedFontDefn R 522 FP_UserString property FO_Element R 640 FP_UseSepOverride property FO_CondFmt R 529 FP_UseSepOverride property FO_Doc R 575 FP_UseSepOverride property FO_Row R 652 FP_UseSepOverride property text location R 671 FP_UseShadow property FO_CharFmt R 518 FP_UseSpread property FO_CharFmt R 518 FP_UseStretch property FO_CharFmt R 518 FP_UseStrikethrough property FO_CharFmt R 518 FP_UseTracking property FO_CharFmt R 518 FP_UseUnderlining property FO_CharFmt R 518 FP_Validating property G 110 FDK Programmer s Reference amp Guide Index Reserved Names as FP_Validating property FO_Session G 110 R 637 FP_ValidationFlags property FO_Element R 645 FP_ValidHighestLevel property FO_ElementDef R 647 FP_VarFmt property FO_Var G 327 R 672 FP_Variables property FO_Doc R 551 FP_VersionMajor property FO_Session R 637 FP_VersionMinor property FO_Session R 637 FP_VerticalTrackingLarge property FO_Doc R 551 FP_VerticalTrackingMedium property FO_Doc R 551 FP_VerticalTrackingSmall property FO_Doc R 551 FP_ViewBorders property FO_Do
41. F_ApiPromptInt or F_ApiPromptMet ric These functions all allow you to provide a default value for the entry field Their syntax is Inti Int l F_ApiPromptString StringT stringp StringT StringT message stuffVal message stuffVal T F_ApiPromptInt IntT intp StringT StringT FDK Programmer s Guide Creating Your Client s User Interface a IntT F_ApiPromptMetric MetricT metricp StringT message StringT stuffVal MetricT defaultunit This argument Means stringp intp A pointer to the user variable that gets the return value from the input field or metricp when the user clicks OK message The message that appears in the dialog box stuffVal The default value that appears in the input field when the dialog box is first displayed It must be a string for integer and metric prompts as well as string prompts defaultunit The metric unit to use if the user doesn t specify one For example to use inches as the default unit specify 4718592 For more information on metric values see MetricT values on page 675 of the FDK Programmer s Reference These functions all return 0 if the user clicks OK Otherwise they return a nonzero error value If the user clicks Cancel the API does not assign a value to stringp intp or metricp If the user types alphabetic text after a number in an F_ApiPromptInt dialog box the API ignores the text and just returns th
42. F_PropValsT importParamsp F_PropValsT importReturnParamspp The syntax for F_Apilmport is This argument Means enclosingDocId The ID of the document into which to import the file textLocP The text location at which to import the file filename The full pathname of the file to import For information on how to specify pathnames on different platforms see the FDK Platform Guide for your platform importParamsp A property list telling the FrameMaker product how to import the file and how to respond to errors and other conditions To use the default list specify NULL importReturnParamspp A property list that provides information about how the FrameMaker product imported the file It must be initialized before you call F_ApiImport For a list of properties in this property list see F_Apilmport on page 192 of the FDK Programmer s Reference IMPORTANT Always initialize the pointer to the property list that you specify for importReturnParamspp to NULL before you call F_Apilmport If you import a text file by reference F_ApilImport creates a text inset and returns its ID Otherwise it returns 0 The steps for using F_ApiImport are similar to the steps for calling F_ApiOpen and F_ApiSave To call F_Apilmport do the following 1 Initialize the pointer to the importReturnParamspp property list to NULL 2 Create an importParamsp property list You can get a default
43. Frame Document Architecture 14 FP_FirstTextFramelnFlow FP_FirstFlowInDoc FO_Flow gt Unnamed flow FO_TextFrame FP_LastTextFramelnFlow FO_Doc O 8 7 Q FP_FirstTextFramelnFlow p FO_TextFrame 8 Le A oO zZ gt a Y 5 FO_Flow E E a Hy FP_MainFlowInDoc Flow A k 2 zZz a a LL WL y p gt FO_TextFrame FP_LastTextFramelnFlow FIGURE 14 10 Objects that represent a document with two flows Although the FP_FirstFlowInDoc property specifies the FO_Flow object for the unnamed flow in Figure 14 10 it could also specify the FO_Flow object that represents Flow A The determination of which flow is first in the list is completely random The API uses FO_SubCol objects to represent the column formatting of text as follows e Contiguous paragraphs in each column of a text frame are within a single FO_SubCol object e Contiguous paragraphs within sidehead area are within a single FO_SubCol e Each contiguous series of paragraphs that spans columns and or sideheads is represented by a single FO_SubCol object Following paragraphs that do not span columns and sideheads begin a new group of FO_SubCol objects For example Figure 14 11 shows a page that has seven FO_SubCo1l objects two groups of three plus one for the heading that spans all collumns FIGURE 14 11
44. IntT objType StringT format F_TextLocT textLocp F_ObjHandleT F_ApiNewAnchoredObject F_ObjHandleT doclId IntT objType F_TextLocT textLocp This argument Means docId The ID of the document to which to add the object objType The type of object to create for example FO_Marker or FO_XRef format The string that specifies the object s format for example Heading amp Page or Current Date Long textLocp The text location at which to insert the anchored object F_ApiNewAnchoredObject and F_ApiNewAnchoredFormattedOb ject use a set of arbitrary default properties to create new objects For example the default width and height of a new anchored frame is 0 25 inches Example The following code adds a Filename Long variable at the insertion point or the beginning of the text selection of the active document FDK Programmer s Guide Creating and Deleting API Objects Ba F_TextRangeT tr F_ObjHandleT docId variablelId Get the insertion point docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection Return if there is no selection or IP if tr beg objId return Insert the variable variableId F_ApiNewAnchoredFormattedObject docId FO Var Filename Long amp tr beg Creating series objects A series object is any object other than a graphic object that occurs in an ordered series Paragraphs an
45. R 292 F_ApiSetMetrics function G 90 R 16 R 293 F_ApiSetPoints function G 90 G 100 R 16 R 295 F_ApiSetPrinterState function R 297 F_ApiSetPropertyType functions G 7 G 89 G 126 G 213 G 263 F_ApiSetProps function G 92 G 102 G 126 R 16 R 297 F_ApiSetPropVal function R 16 R 300 F_ApiSetString function G 7 G 90 G 94 G 217 R 6 R 15 R 16 R 301 F_ApiSetStrings function G 90 R 16 R 303 F_ApiSetTabs function G 90 G 103 R 16 R 305 F_ApiSetTextLoc function G 90 R 16 R 308 F_ApiSetTextProp function G 125 F_ApiSetTextProps function G 124 R 17 R 23 R 309 R 669 F_ApiSetTextPropVal function G 124 R 23 R 311 F_ApiSetTextRange function G 90 G 115 R 17 R 23 R 313 F_ApiSetTextVal function R 23 R 314 F_ApiSetUBytesByName function G 264 G 265 R 9 R 316 F_ApiShortcutExists function R 318 F_ApiShutDown function R 318 F_ApiSilentPrintDoc function G 7 G 57 R 2 R 6 R 15 R 319 F_ApiSimpleGenerate function G 71 G 356 R 2 R 321 F_ApiSimpleImportElementDefs function G 77 R 322 F_ApiSimpleImportFormats function G 72 R 2 R 7 R 322 F_ApiSimpleNewDoc function G 53 G 84 R 6 R 325 F_ApiSimpleOpen function G 7 G 45 G 46 G 84 R 2 R 6 R 326 F_ApiSimpleSave function G 41 G 46 G 59 R 2 R 6 R 327 F_ApiSleepQ function R 17 R 25 R 328 F_ApiSplitElement function R 329 F_ApiStartUp function R 329 F_ApiStraddleCells function G
46. R 506 FP_XmlStyleSheet property FO_Doc R 571 FP_XmlStyleSheetList property FO_Book R 506 FP_XmlStyleSheetList property FO_Doc R 571 FP_XmlSystemld property FO_Book R 506 R 571 index 66 FP_XmlUseBOM property FO_Book R 507 R 571 FP_XmlVersion property FO_Book R 507 FP_XmlVersion property FO_Doc R 572 FP_Xm1WellFormed property FO_Book R 507 R 572 FP_XRefFile property FO_XRef G 324 R 530 FP_XRefFmt property FO_XRef G 324 R 530 FP_XRefSrcIsElem property FO_XRef R 530 FP_XRefSrcText property FO_XRef R 530 FP_YakumonoType property FO_FmtChangeList R 583 FP_YakumonoType property FO_Pgf R 613 FP_YakumonoType property FO_PgfFmt R 623 FP_Yellow property FO_Color R 520 FP_Zoom property FO_Doc R 578 FR_CancelOperation return value F_ApiReturnValue R 269 FR_DialogStayUp return value F_ApiReturnValue R 270 FR_DisplayedTiDialog return value F_ApiReturnValueQ R 269 FrameProduct G 25 free function G 369 FS_ FS_AlertUserAboutFailure property F_ApiGetImportDefaultParams R 121 FS_AlertUserAboutFailure property F_ApiGetOpenDefaultParams R 139 FS_AlertUserAboutFailure property F_ApiGetSaveDefaultParams G 62 R 153 FS_AlertUserAboutFailure property F_ApiGetUpdateBookDefaultParams G 358 R 187 FS_AllowInconsistentNumProps property F_ApiGetUpdateBookDefaultParams R 187 FS_AllowNonFMFiles property F_ApiGetUpdateBookDefaultParams R 188 FS_AllowViewOnlyFiles proper
47. R 604 properties of R 604 FO_Row objects G 281 G 332 G 333 R 83 R 651 properties of R 651 FO_Rubi objects G 282 R 630 properties of R 630 index 46 FO_RulingFmt objects G 270 G 281 G 329 R 630 properties of R 630 FO_Session objects G 10 G 83 G 274 G 306 R 84 R 631 properties of R 631 FO_SubCol objects G 111 G 280 G 299 R 520 FO_Tbl objects G 281 G 312 G 332 R 652 properties of R 652 FO_TblFmt objects G 270 G 281 G 330 R 658 properties of R 658 FO_TextFrame objects G 111 G 280 G 290 G 298 G 299 G 304 R 605 properties of R 605 FO_TextLine objects G 111 G 280 R 606 properties of R 606 FO_TiApiClient objects G 230 G 281 R 666 properties of R 666 FO_TiFlow objects G 229 G 270 G 281 R 667 properties of R 667 FO_TiText objects G 229 G 270 G 281 R 667 property of R 667 FO_TiTextTable objects G 229 G 281 R 668 properties of R 668 FO_UnanchoredFrame objects G 270 G 280 G 290 G 295 R 84 R 608 properties of R 608 FO_Var objects G 111 G 281 G 326 R 672 properties of R 672 FO_VarFmt objects G 270 G 281 G 325 R 84 R 672 properties of R 672 FO_XRef objects G 281 G 323 R 530 properties of R 530 FO_XRefFmt objects G 270 G 281 G 322 R 531 properties of R 531 FontEncldT data type R 675 fopenQ function G 369 FP_ FP_AcrobatBookmarkDisplayTags property FO_Book R 498 FP_AcrobatBookmarkDisplayTags property FO_Doc R 542 FP_AcrobatLevel property FO_PgfFmt R 622 FP_ActiveBook prope
48. The user can type text into a text line or a paragraph in a text frame table cell or footnote What the user sees FrameMaker allows you to insert things such as anchored frames footnotes tables and cross references into text The point at which you insert these things is called an anchor FrameMaker represents an anchor with an anchor symbol L on the screen This symbol is not visible if the Text Symbols view option is turned off The anchor moves with the text to which it is attached All text has a set of properties that specify the following information about it e A tag or the name of a character format stored in the Character Catalog e Formatting information the same information that a Character Catalog format provides such as the font family and size e A set of conditional text formats that apply to it These properties are called text properties Just as you can override a Paragraph Catalog tag by changing an individual paragraph s format you can also override a Character Catalog tag by changing the properties of a selection of text You can also apply one or more conditions to a selection of text This allows you to hide or display the text for particular versions of a document FDK Programmer s Guide 311 14 Frame Document Architecture 312 How the API represents text The API represents the text in each paragraph or graphic text line with an F_TextItemsT structure which is defined as typedef struct
49. To generate and update files for a book use F_ApiSimpleGenerate The book and its generated files must be set up before you call F_ApiSimpleGenerate The syntax for F_ApiSimpleGenerate is IntT F_ApiSimpleGenerate F_ObjHandleT bookId IntT interactive IntT makeVisible FDK Programmer s Guide 71 a Executing Commands with API Functions 72 This argument Means bookId The ID of the book for which to generate files interactive Specifies whether to display warnings and messages to the user True displays messages and warnings makeVisible Specifies whether to display generated files True displays the files Importing formats To import formats from a document to all the documents in a book or from one document to another document use F_ApiSimpleImportFormats The syntax for F_ApiSimpleImportFormats is IntT F_ApiSimpleImportFormats F_ObjHandleT bookId F_ObjHandleT fromDocId IntT formatFlags This argument Means bookId The ID of the book or document to which to import formats fromDocId The ID of the document from which to import formats formatFlags Bit field that specifies the formats to import You can OR the values in the following table into the formatFlags parameter to specify which formats to import This value Means FF_UFF_COLOR Import colors FF_UFF_COMBINED_FONTS Import combined font definitions FF_UFF_COND Import conditional
50. changeListId FP_Pairkern False Set up list with FP_FontSize property to set size to 10 props F_ApiAllocatePropVals 1 props val 0 propIdent num FP_FontSize props val 0 propVal valType FT_Metric props val 0 propVal u ival 10 pts F_ApiSetProps docId changeListId amp props Note that the F_ApiSetProps call in the code above only adds the FP_FontSize property It does not affect the other properties of the format change list Removing properties from a format change list To remove a property from a format change list call F_ApiDeletePropByName For example the following code removes the FP_PairKern property from the Code format change list F_ObjHandleT docId changeListId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc changeListId F_ApiGetNamedObject docId FO_FmtChangeList Code if changeListId return F_ApiDeletePropByName docId changeListId FP_PairKern Setting format rule clause properties Format rule clauses FO_FmtRuleClause objects have several properties that are only indirectly settable For example you can t set the FP_RuleClauseType property directly You can only set it indirectly by setting one of the following properties e FP_FormatName e FP_FmtChangeListTag e FP_FmtChangeList FP_SubFmtRule For example if you set FP_FmtChangeListTag to Code FrameMaker automatically sets FP_RuleClauseType to FV_RC_CHANGELIST_TAG FDK Progra
51. char ch the compiler issues an error message similar to the following rror Non_FDE_token char ch To avoid these error messages you can e Use the FDE substitute for the platform dependent data type or function For example use UCharT instead of char e Add the following code above the include fdetypes h statement define DONT_REDEFINE This prevents the FDE from redefining any data types or functions e Use undef to undefine the specific types or functions that you want to use For example add the following line after the include fdetypes h statement undef char This allows the FDE to generate errors if your client uses any other platform specific types Replacing I O and memory calls The following table lists some commonly used I O and memory calls and the FDE functions you can replace them with Function FDE substitute fclose F_ChannelClose Fopen F_ChannelOpen fwrite F_ChannelWrite alloc F_Alloc free F_Free printf F_Printf sprintf F_Sprintf Some FDE functions have slightly different parameters or return values than the corresponding platform specific I O and memory functions For example F_Alloc has a parameter that alloc doesn t have Before using an FDE I O or memory function look it up in Chapter 2 FDK Function Reference of the FDK Programmer s Reference FDK Programmer s Guide 369 1
52. compile your client use your platform s make or build utility For more information on using FDK makefiles or project files on a specific platform see the FDK Platform Guide for that platform 7 Register your client with the FrameMaker product The FrameMaker product needs to know about your client to initialize it To let the FrameMaker product know about your client you must make some changes to the environment under which the client runs e On UNIX platforms when you start FrameMaker it looks for a text only file named fminit UILanguage APIArea apiclients where UlLanguage is the user interface language such as usenglish for US English It looks in the directory from which it was started in your home directory and in SFMHOME To register your client create an fminit UILanguage APIArea apiclients file in your home directory or the directory from which you intend to start the FrameMaker product Add the following lines to the file lt APIclient lt Name client_name gt lt Directory Clientdir lt CommandLine FAPIDIR executable_name gt gt The path clientdir specifies the full path of the directory containing your client s executable file and other resources client_name is the name that FrameMaker and other clients use to reference your client and executable_name is the name of your client s executable file The FDK sets the environment variable SFAPIDIR to clientdir e On Macintosh computers copy or move yo
53. control clients The chosen document report Clients that have bailed out and are waiting for an event menu choice or hypertext command to occur First initialization When the user starts the FrameMaker product the product calls the F_ApiInitialize function of each registered client unless it s a document report or filter with initialization setto FA_Init_First Take control initialization The FDK allows you to set up clients to receive a special initialization called a take control or FA_Init_TakeControl FA_Init_TakeControl initialization The FrameMaker product issues the initialization after it has issued the FA_Init_First initialization and all clients have returned control This initialization is useful if you want your client to conduct some batch processing after other clients have initialized but before the interactive user has control FDK Programmer s Guide API Client Initialization ae On UNIX platforms the FrameMaker product issues the FA_Init_TakeControl initialization to only one client The user specifies this client by starting the FrameMaker product with the apiclient client_name option where client_name is the registered name of the client On Windows and Macintosh platforms the FrameMaker product can issue the FA_Init_TakeControl initialization to several clients To set up a client to receive FA_Init_TakeControl initializations on Windows set the client s type to TakeControl i
54. docId amp tr beg tmp mydata txt amp params amp returnParamsp if F_ApiCheckStatus returnParamsp FV_BadImportFileType F_ApiAlert File isn t importable FF_ALERT_CONTINUE_NOTE FA Snak Deallocate property lists F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp Updating text insets To update text insets call F_ApiUpdateText Inset The syntax for F_ApiUpdateTextInset is IntT F_ApiUpdateText Inset F_ObjHandleT docId F_ObjHandleT textInsetId This argument Means docId The ID of the document containing the inset textInsetId The ID of the text inset to update To update all the insets in the specified document specify 0 FDK Programmer s Guide 235 12 Using Imported Files and Insets 236 F_ApiUpdateTextInset updates a text inset only if it is stale The FrameMaker product determines whether a text inset is stale by comparing the modification date of the inset s source file with the inset s FP_LastUpdate property To force F_ApiUpdateTextInset to update an inset set the insets FP_LastUpdate property to 0 before calling it You do not need to unlock any insets when you call F_ApiUpdateTextInset Client text insets Client text insets allow your client to display and dynamically update segments of locked text in a Frame document The following sections describe how to create and update
55. docId insetId FP_InsetFile tmp myinset fi F_ApiSetString docId insetId FP_InsetEditor myeditor Responding to the user double clicking a graphic inset When the user double clicks a graphic inset for which the FP_InsetEditor property specifies your graphic inset editor the FrameMaker product calls the editor s F_ApiMessage callback with objId set to the inset s ID Include code in F_ApiMessage that allows the user to update the inset If the inset is an internal inset you update it by setting its facets Although your API graphic inset editor should respond when the user selects it from the Inset Editors scroll list or when the user clicks a graphic inset it can create or update insets at any time For example you may want to update a document s insets whenever the user opens the document or chooses a particular menu item FDK Programmer s Guide Using Imported Files and Insets 12 If a graphic inset is an external graphic inset you update it by editing the file specified by FP_InsetFile The FrameMaker product periodically refreshes external insets against the files that describe them If you want to ensure that the inset is refreshed immediately you must reset the FO_Inset object s FP_InsetFile FP_Height or FP_Width property FrameMaker product doesn t call F_ApiMessage only when the user double clicks a graphic inset It also calls F_ApiMessage when the user clicks a hypertext marker Therefore
56. if buf NULL 27 28 F_ApiBailOut 29 F_ApiReturnValue 0 30 return 31 32 33 path F_PathNameToFilePath sparm NULL FDefaultPath 34 if path NULL return 35 if chan F_ChannelOpen path r NULL return 36 37 docId F_ApiCustomDoc F_MetricFractMul in 17 2 38 11 in 1 F_MetricFractMul in 1 4 in 39 in in in FF_Custom_SingleSided False 40 41 tl objId F_ApiGetId FV_SessionId docId FP_MainFlowInDoc 42 tl offset 0 43 44 while F_ChannelEof chan 45 46 count F_ReadBytes buf BUFFERSIZE 1 chan 47 buf count 0 48 tl F_ApiAddText docId amp tl buf 49 50 51 F_ApiReturnValue docId 52 F_FilePathFree path 53 F_Free buf 54 F_ChannelClose chan 55 F_ApiBailOut 56 Lines 1 to 11 These lines include header files and define constants for the client Lines 12 to 56 These lines define the F_ApiNotify callback which the FrameMaker product calls when the user attempts to open or import a filterable file You specify which file types are filterable when you register the filter For more information on registering the filter see Compiling and running the example FDE filter on page 373 When the user or a client attempts to open or import a filterable file the FrameMaker product calls the F_ApiNotify callback with notification setto FA_Note_FilterIn and filename set to the nam
57. make sure that the object specified by objId is a graphic inset and not a hypertext marker For example the following code updates a graphic inset when the user clicks it VoidT F_ApiMessage message docId objId StringT message F_ObjHandleT docId F_ObjHandleT objid if objId Code to create a new inset goes here else Make sure clicked object is a graphic inset if F_ApiGetObjectType docId objId FO_Inset Code to edit or update facets with F_ApiGet PropertyType ByName and F_ApiSet PropertyType ByName goes here Getting and setting graphic inset properties To get and set individual graphic inset properties identified by property numbers you use F_ApiGetPropertyType and F_ApiSetPropertyType functions just as you would with any other object properties For example to get and set FP_InsetDpi you use F_ApiGetInt and F_ApiSetInt To get and set facets and FO_Inset property lists follow the procedures discussed in the following sections Getting and setting facets To get and set facets use the following functions To Use Query an integer facet F_ApiGet IntByName Query a metric facet F_ApiGetMet ricByName FDK Programmer s Guide 263 12 Using Imported Files and Insets To Use Query an F_UBytes facet F_ApiGetUBytesByName Set an integer facet F_ApiSet IntByName Set a metric facet F_ApiSetMet ricByName Setan
58. naming convention for properties of G xii R xix setting properties using G 93 FDK Programmer s Reference amp Guide scripts G 46 See also property lists scroll bars changing orientation of G 202 changing the length of G 202 in dialog boxes G 201 displaying the value of G 201 properties of G 201 R 536 resizing G 201 scroll list dialog boxes displaying G 22 to G 24 function for R 5 R 274 to R 276 getting setting the state of function for R 5 illustrated G 24 scroll lists in dialog boxes G 202 properties of R 536 to R 537 selected objects getting the IDs of G 86 to G 87 selected structural elements API representation of G 286 deleting R 337 demoting function for R 92 to R 93 getting the IDs of G 120 merging into the first element function for R 204 to R 205 merging into the last element function for R 205 traversing G 120 selected text See text selections selection properties See document properties selections API functions applicable to R 17 properties applicable to G 285 to G 286 series objects G 149 to G 150 R 220 creating G 11 G 149 to G 150 function for R 14 R 220 to R 221 defined G 391 sessions G 274 G 391 active documents and books in G 275 to G 276 API representation of G 274 to G 277 illustrated G 276 connecting the calling process to functions for R 67 R 95 R 106 determining menu configuration of G 164 to G 166 only ID of G 11 G 82 open documents and books in G 275 illustrated G 275 to G 276
59. or the left subcolumn For example the following code also sets the insertion point at the beginning of the first paragraph on the page shown in Figure 6 1 FDK Programmer s Guide F_ObjHandlel F_TextRangeT docId f EE Get document and f lowld low IDs here tr beg objId tr end objId flowld tr beg offset tr end offset 0 Set document s insertion point F_ApiSetTextRang FV_SessionId docId FP_TextSelection Manipulating Text 6 amp tr The beg offset and end offset fields of the F_TextRangeT structure returned by F_ApiGetTextRange always specify offsets relative to the beginning of a paragraph or text line object The beg offset and end offset fields of the F_TextRangeT structure that you pass to F_ApiSetTextRange can specify offsets relative to the beginning of an object but they can also use the special value FV_OBJ_END_OFFSET FV_OBJ_END_OFFSET specifies the offset of the last character in the object containing the text range To specify offsets near the end of an object you can add or subtract integers from FV_OBJ_END_OFFSET For example the following code selects the last five characters in a paragraph and the end of paragraph symbol F_ObjHandlel tr doclId pgfid F_TextRangeT Get document and paragraph IDs here tr beg objId tr end objId pgfId tr beg offset FV_OBJ_END_OFFSET 6 tr end offset FV_OBJ_END_OFFS
60. provides FDK reference information such as error codes and data structure function and property descriptions Structure Import Export API Programmer s Guide The Structure Import Export API Programmer s Guide provides instructions and reference information for using the Structure Import Export API Naming conventions To help you identify the structures constants and functions defined by the FDK this manual and the FDK adhere to the following naming conventions Type Naming convention Example API error codes Begin with FE_ FE_NotPgf API functions Begin with F_Api F_ApiGet Int API scriptable function Begin with FS_ FS_NewDoc property names FDE functions Begin with F_ F_StrNew xii FDK Programmer s Guide Using Frame Developer Tools a Type Naming convention Example Flags used by API functions Begin with FF_ and all letters FF_UFF_VAR are uppercase Initialization constants Begin with FA_Init FA_Init_First Notification constants Begin with FA_Note FA_Note_PreFileType Object property names Begin with FP_ FP_Fill Object types Begin with FO_ FO_Doc Property value constants Begin with FV_ FV_Doc_Type_MIF Typedefs End with T MetricT This manual uses the term API graphic object to refer to objects such as FO_Polygon and FO_TextFrame objects that the API uses to represent the graphic objects such as polygons and text frames that appear on a page Style conventions FDK manuals dis
61. s type in properties do not have to match the text properties of the character to the left of the insertion point You can change them with the F_ApiSetPropertyType and F_ApiSetProps functions For example the following code sets the active document s type in properties so that text the user types appears in uppercase and is underlined F_ObjHandleT doclId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc F_ApiSetInt FV_SessionId doclId FP_Capitalization FV_CAPITAL CASE UPPER F_ApiSetInt FV_SessionId doclId FP_Underlining FV_CB_SINGLE_UNDERLINBE Executing Clipboard functions The API provides functions that programmatically execute Frame Clipboard functions It also provides a Clipboard stack which allows you to save the Clipboard contents Executing Frame Clipboard functions The API provides the following functions to programmatically execute Frame Clipboard functions e F_ApiCut cuts the current selection to the Clipboard e F_ApiCopy copies the current selection to the Clipboard e F_ApiPaste pastes Clipboard contents to the insertion point or current selection e F_ApiClear clears the current selection All these functions work only on the active document They use the Frame Clipboard and the current selection or insertion point in a document They work with text table cells and graphic objects You can allow the user to set the selection or insertion point or y
62. to create a MIF file use code similar to the following include fdetypes h include fapi h include fchannel h include futils h include fioutils h include fmifstmt h FilePathT path ChannelT chan path F_PathNameToFilePath StringT my mif NULL FDefaultPath if chan F_ChannelOpen path w NULL return _MifSetOutputChannel chan MifSetIndent 0 _MifMIFFile 5 0 _MifComment StringT Generated by KurtWrite MifNewLine _ChannelClose chan E EF EF F E F This code creates a MIF file named my mif in the default directory the current directory on UNIX the FrameMaker product directory on Windows or the FrameMaker product Modules folder on the Macintosh with the following contents lt MIFFile 7 00 gt Generated by KurtWrite Some MIF library functions use the type MifUnitT which is an enumerated type specifying measurement units It can have the following values TABLE 18 1 MifUnitT value Measurement unit MIFUnitIn Inches MIFUnitCm Centimeters FDK Programmer s Guide TABLE 18 1 FDE Utility Libraries 18 MifUnitT value IFUnitMm IFUnitPt IFUnitDd IFUnitCce IFUnitDef Measurement unit Millimeters IFUnitPica Picas Points Didots Ciceros Default unit The FDE uses Mii MIFUnitDe fUnitT to generate MIF statements that include decimal values If
63. ve manually grouped e Bring to Front e Send to Back e Align e Distribute e Scale see the previous caveats about resizing e Object Properties e Snap Note that you cannot ungroup a single dialog item into smaller components For example you cannot ungroup a checkbox into a box and a label For example you can use the Align command to align dialog box items When aligning the bottoms of dialog items note that the bottom of any item containing text is defined by the baseline of its text line Some commands affect the display of graphic objects in a DRE file but have no effect on the actual dialog box that you create from the file e You can use the Group command to group dialog items for convenience while laying out the dialog box Although the grouping works when you are modifying the file the grouping information is not saved in the DRE file In other words grouping has no effect on the appearance or functionality in the actual dialog box For example if you group checkboxes together the grouping does not affect the way the checkboxes work e Although you can change the line fill and color properties of graphic objects in the DRE file this does not change the appearance of items in the actual dialog box FDK Programmer s Guide 191 a Creating Custom Dialog Boxes for Your Client 192 e The Bring to Front and Send to Back commands do not change the appearance of items in the actual dialog box Although you can use th
64. whereas each API function stores an error code to FA_errno when it fails It is also difficult to debug lengthy f code sequences The following code uses f codes to enter the string HI select the text and then make it bold static IntT fcodes CSR_TOP H I HIGH_WORD_PREV TXT_BOLD F_ApiFcodes sizeof fcodes sizeof IntT fcodes Straddling table cells To straddle and unstraddle table cells use F_ApiStraddleCells and F_ApiUnStraddleCells The syntax for these functions is IntT F_ApiStraddleCells F_ObjHandleT doclId F_ObjHandleT cellld IntT heightInRows IntT widthInCols IntT F_ApiUnStraddleCells F_ObjHandleT docId F_ObjHandleT cellld IntT heightInRows IntT widthInCols This argument Means docId The ID of the document containing the table celliId The ID of the first leftmost and uppermost cell to straddle or unstraddle height InRows The number of cells to straddle or unstraddle vertically widthInCols The number of cells to straddle or unstraddle horizontally Both heightInRows and widthInCols must be greater than 0 At least one of them must be greater than 1 The cells you straddle must all be from the same type of row You can t for example straddle a set of cells that are in both heading and body rows You also can t straddle cells that are already straddled If the cells you specify include cells that are already straddled F_ApiStraddleCells returns
65. 0001IMAGPNG 0001FRAMPNTG 0O001FRAMSNRF OOQO1FRAMTIFF 0001F OOO1IMAG FDK Programmer s Guide 251 12 Using Imported Files and Insets 252 To use this import filter WordPerfect Graphics XWD MIF MML Text Ventura Publisher Microsoft Word for Windows 6 0 7 0 Microsoft Word for Windows 2 0 Microsoft Word for Windows 1 0 Microsoft Word Macintosh 6 0 Microsoft Word DOS 5 0 6 0 Microsoft Word DOS 4 0 Microsoft Word DOS 3 0 3 1 Microsoft Word Mac 5 x Microsoft Word Mac 4 x Microsoft Word Mac 3 x Microsoft RTF WordPerfect DOS Win 7 0 WordPerfect DOS Win 6 1 WordPerfect DOS Win 6 0 WordPerfect DOS Win 5 1 WordPerfect DOS Win 5 0 WordPerfect Mac 3 0 3 5 WordPerfect Mac 2 0 2 1 WordPerfect Mac 1 0 InterLeaf ASCII Format DCA Revisable Form Text DCA RFT Display Write 5 Ami Professional 2 3 1 Use this hint string 0001 IMAGWPG 0001FRAMXWD 0001FRAMMIF 0001FRAMMML 0O001FRAMTEXT 0O001FFLTCVBN 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 0001AW4 w0490 wo441 w0440 W049m w0052 w0051 w0050 w0542 wo541 w0540 WwO191 Ww0482 wo481 w0480 w0071 w0070 wo601 w0600 Ww0590 Ww0460 Ww0150 WwO151 W0331 FDK Programm
66. 196 fwrite function G 369 G H GenericT data type G 367 R 675 HandleT structure R 677 HashT structure R 678 I J K L importing files PDF G 230 SGML G 230 XML G 230 in metric constant for inches G 271 IntT data type G 3 G 90 G 271 G 367 R 16 R 675 KBD_ALIGN f code G 39 KBD_INPUT f code G 39 KBD_OPEN f code G 39 index 74 Makes R 468 markup filte importing G 230 message apiclient hypertext command G 7 G 31 responding to G 32 function for R 1 R 206 syntax for G 32 MetricT data type G 4 G 90 G 271 G 367 G 384 R 675 MifUnitT data type G 386 values of table G 386 N O NativeCharT data type G 368 NativeDoubleT data type G 367 NativeIntT data type G 368 NativeLongT data type G 368 NativeULongT data type G 368 NO_DSE flag FDE functions G 372 G 379 P Q R PByteT data type G 368 PCharT data type G 368 PDF files importing G 230 PGF_APPLY_TAG f code G 39 PRealT data type G 368 printf function G 369 ProcedureT data type G 368 PShortT data type G 368 PtrT data type G 368 pts metric constant for points G 271 PUByteT data type G 368 PUCharT data type G 368 PUShortT data type G 368 QSort C library function R 27 RealT data type G 368 S T SGML files importing G 230 ShortT data type G 368 R 675 sleep C library function R 328 sprintf function G 369 sqrt C library function R 491 FDK Programmer s Reference amp Guide Index Reserved Names a StrBuffT data type
67. 2 A FrameMaker session with open documents and books FP_FirstOpenBook FO_Book gt Manual book FP_NextOpenBookinSession FO_Book Manual2 book FO_Doc 2Chapter FP_FirstOpenDoc FP_NextOpenDocinSession FO_Doc z FP_ActiveDoc 1Chapter FIGURE 13 3 API representation of a session with open documents and books Although Manual book is iconified the API still considers it open Although FP_FirstOpenDoc specifies 2Chapter it is not necessarily the first document that was opened How the API indicates which fonts are available in a session The following FO_Session properties specify which fonts are available in the current session e FP_FontFamilyNames specifies the available families for example Helvetica and Times e FP_FontVariationNames specifies the available variations for example Narrow and Oblique FDK Programmer s Guide Frame Session Architecture 13 e FP_FontWeightNames specifies the available weights for example Bold and Regular e FP_FontAngleNames specifies the available angles for example Italic and Regular The FP_FontFamilyNames FP_FontVariationNames FP_FontWeightNames and FP_FontAngleNames properties determine which choices appear in the Family Weight Angle and Variation fields of the Character Designer and Paragraph Designer and the pull right menu items in the Format menu Each of the properties specifies an F_StringsT structure which is de
68. 227 to R 232 numbering paragraphs See paragraph numbering O object IDs See IDs of API objects object pointer properties See document properties object properties See properties object types G 3 getting G 84 function for R 24 R 138 naming convention for G xiii R xix index 21 os Index Subjects See also individual object types in the FDK Reserved Names Index objects API G 3 R 495 to R 673 automatic updating of G 81 G 160 child G 295 child graphic G 389 color property of G 339 creating G 7 G 143 to G 158 functions for tables G 143 to G 145 R 14 data type for IDs of G 3 G 6 G 271 G 390 default G 279 defined G 390 deleting G 158 to G 159 functions for R 14 R 83 to R 90 determining if valid function for R 24 R 237 document lists of G 284 document properties for G 282 to G 284 frame G 295 getting text in function for R 23 getting the IDs of G 82 to G 89 G 269 to G 270 functions for R 15 getting the IDs of selected G 86 to G 87 G 285 grouping G 101 identifying G 269 to G 270 moving between frames R 286 named G 145 G 269 to G 270 G 390 nondeletable G 158 listed R 84 order of in linked lists G 84 as organized in documents G 82 G 84 G 282 to G 284 properties of R 495 to R 673 selection state of properties for G 285 to G 286 series G 11 G 149 to G 150 G 391 R 220 session G 10 traversing lists of G 84 to G 86 unnamed G 270 validating IDs for function for R 24 R 237 See also graphic
69. 229 FA_Note_PreSaveBookMIF notification constant R 229 FA_Note_PreSaveDoc notification constant G 35 R 228 FA_Note_PreSaveMIF notification constant R 228 FA_Note_PreSaveSGML notification constant R 228 FA_Note_PreSaveXML notification constant R 228 FA_Note_PreSetAttrValue notification constant R 232 R 235 FA_Note_PreWrapElement notification constant R 232 FA_Note_PreWrapElementt notification constant R 235 FA_Note_UpdateAllClientTi notification constant G 237 R 230 FA_Note_UpdateClientTi notification constant G 237 R 230 R 236 FA_PreNotificationPoint notification G 37 R 269 Facets properties FO_Inset R 599 fclose Q function G 369 FDEsqrt function R 491 FDEstrtod function R 492 FDEstrtol function R 493 FdeSuccess error code G 379 FDIPath path type _G 376 FDOSPath path type G 376 FE_ FE_AsianSystemRequired error code R 693 FE_BadBaseColor error code R 693 FE_BadCompare error code R 693 FE_BadDelete error code R 693 FE_BadDocld error code R 693 FE_BadElementDefld error code R 693 FE_BadElementld error code R 693 FE_BadElementSelection error code R 693 FE_BadFamilyName error code R 693 FE_BadFileType error code R 693 FE_BadInkName error code R 693 FE_BadMenuBar error code R 693 FE_BadName error code R 693 FE_BadNew error code R 694 FE_BadNewFrame error code R 694 FE_BadNewGroup error code R 694 FE_BadNewSibling error code R 694 FE_BadNotificationNum error code R 694 FDK Programmer s Refere
70. 233 filters for G 241 to G 250 R 600 to R 602 function for R 192 to R 197 printing imported G 258 properties of imported G 247 to G 250 R 125 R 599 to R 602 See also graphic insets Graphics menu name used to specify G 25 R 76 using commands with dialog boxes G 191 to G 192 Group command Graphics menu grouping dialog box items G 191 grouping dialog box items G 191 graphic objects G 101 groups of graphic objects API representation of G 296 defined G 293 properties of G 296 R 599 resizing G 293 index 15 os Index Subjects H handles functions for G 379 R 370 R 372 R 377 allocating and deallocating memory with G 379 R 432 allocating and returning for directories R 380 allocating new G 379 clearing the data of G 379 R 370 closing a file handle R 377 copying the contents of R 372 determining if contents equal R 389 determining size of R 389 freeing memory allocated to G 379 R 386 locking R 399 resetting R 435 returning size of R 389 unlocking R 488 using in memory management G 378 to G 379 hash functions G 381 G 383 R 390 to R 397 hash library FDE See hash functions hash tables functions for R 390 adding entries to G 383 creating G 383 R 390 deleting R 392 enumerating entry keys and data R 393 finding and printing specified entries R 395 getting entries from G 383 R 394 removing R 394 header files including in clients G 8 G 367 See also individual header files help See context sensitive hel
71. 334 R 650 FP_CellUseOverrideTRuling property FO_Cell R 650 FP_CellVAlignment property FO_FmtChangeList R 589 FP_CellVAlignment property FO_Pgf R 617 FP_CellVAlignment property FO_PgfFmt R 629 FP_ChangeBar property FO_CharFmt R 515 FP_ChangeBar property FO_Doc R 573 FP_ChangeBar property FO_FmtChangeList R 585 FP_ChangeBar property FO_Pgf R 614 FP_ChangeBar property FO_PgfFmt R 623 FP_ChangeBar property text location R 669 FP_ChangeBarColor property FO_Doc R 549 FP_ChangeBarDistance property FO_Doc R 549 FP_ChangeBarPosition property FO_Doc R 549 FP_ChangeBarThickness property FO_Doc R 550 FP_ChapNumComputeMethod property FO_BookComponent R 509 FP_ChapNumComputeMethod property FO_Doc R 546 FP_ChapterNumber property FO_BookComponent R 509 FP_ChapterNumber property FO_Doc R 546 FP_ChapterNumStyle property FO_BookComponent R 509 FP_ChapterNumStyle property FO_Doc R 546 FP_ChapterNumText property FO_BookComponent R 509 FP_ChapterNumText property FO_Doc R 546 FP_Characteristic properties FO_CharFmt G 308 FDK Programmer s Reference amp Guide FP_CharTag property FO_CharFmt R 515 FP_CharTag property FO_Doc R 573 FP_CharTag property text location G 317 R 669 FP_CheckMarkIsOn property FO_Command G 173 R 524 FP_ColGap property FO_Doc R 559 FP_ColGapWidth property FO_TextFrame R 605 FP_Color property FO_CharFmt R 515 FP_Color property FO_Doc R 573 F
72. 45 G 46 G 93 R xix simple G 45 topical listing of R 1 to R 24 utility R 24 to R 25 See also individual API functions in the FDK Reserved Names Index API graphic objects See graphic objects API header file including in API clients G 8 API objects See objects API API scriptable functions G 45 G 46 properties of naming convention for G xii R xix setting G 93 API simple functions G 45 API structures See data structures API utility functions R 24 to R 25 apiclient client_name command line option G 15 apiclients file G 8 Apple event handlers determining if installed R 28 to R 29 installing R 29 to R 30 removing R 30 to R 31 applications See API clients FDE clients arc properties R 598 As Is settings Character Designer G 306 API representation of G 308 to G 309 ASCII characters special and higher specifying G 316 to G 317 ASClITemplate G 279 assertion failure handlers registering R 437 to R 438 assertion handler functions G 378 R 437 to R 438 attribute definitions G 342 function for getting G 90 attribute definitions of structural element definitions function for getting R 108 to R 110 function for setting R 278 to R 280 attributes function for getting G 90 attributes of structural element definitions function for getting R 110 to R 112 function for setting R 280 to R 282 attributes in markup G 348 Autoconnect setting for flows G 297 automatic updating of objects and properties G 81 G 160 autonumbering p
73. 555 FV_CmdNewLink constant FP_HypertextParsedCmdCode R 555 FV_CmdNextPage constant FP_HypertextParsedCmdCode R 555 FV_CmdNoop constant FP_HypertextParsedCmdCode R 555 FV_CmdOpenLink constant FP_HypertextParsedCmdCode R 556 FV_CmdOpenLinkFitWin constant FP_HypertextParsedCmdCode R 556 FV_CmdOpenNew constant FP_HypertextParsedCmdCode R 556 FV_CmdOpenObjectld constant FP_HypertextParsedCmdCode R 556 FV_CmdOpenObjectIdFitWin constant FP_HypertextParsedCmdCode R 556 FV_CmdOpenPage constant FP_HypertextParsedCmdCode R 556 FV_CmdPopup constant FP_HypertextParsedCmdCode R 556 FV_CmdPreviousLink constant FP_HypertextParsedCmdCode R 556 FV_CmdPreviousLinkFitWin constant FP_HypertextParsedCmdCode R 556 FDK Programmer s Reference amp Guide Index Reserved Names a FV_CmdPreviousPage constant FP_HypertextParsedCmdCode R 556 FV_CmdQuit constant FP_HypertextParsedCmdCode R 556 FV_CmdQuitAll constant FP_HypertextParsedCmdCode R 556 FV_CmdUnknown constant FP_HypertextParsedCmdCode R 555 FV_DestFirstPage constant FP_HypertextParsedCmdDest R 556 FV_DestFluidFlow constant FP_HypertextParsedCmdDest R 556 FV_DestLastPage constant FP_HypertextParsedCmdDest R 556 FV_DestMarker constant FP_HypertextParsedCmdDest R 556 FV_DestMarkerNewLink constant FP_HypertextParsedCmdDest R 556 FV_DestNowhere constant FP_HypertextParsedCmdDest R 556 FV_De
74. 687 API representation of the end of G 314 R 687 API representation of the validity of G 348 creating G 145 G 150 to G 151 R 213 R 347 functions for R 213 R 347 to R 348 deleting function for R 337 to R 338 demoting function for R 92 to R 93 determining formatting G 108 determining if text nodes R 96 document properties for G 284 R 566 FDK Programmer s Reference amp Guide Index Subjects a getting the IDs of selected function for R 113 to R 115 manipulating G 76 to G 77 NoName R 347 preventing validation of G 110 promoting function for R 256 to R 257 properties of G 348 R 638 to R 644 selecting G 120 setting the IDs of selected function for R 282 to R 284 specifying client data for G 110 traversing G 105 structure properties R 566 structured books API representation of G 355 structured documents G 342 structured flows G 300 Structured FrameMaker documents G 347 improving the performance of G 110 Structured FrameMaker commands executing G 76 to G 77 structured properties G 284 structures See data structures stuff items dialog items as G 203 to G 204 G 213 style conventions as used in this manual G xiii to G xiv R xix to R xxi system resources freeing G 15 G 43 to G 44 table anchors API representation of G 312 G 313 R 167 R 687 Table Catalog G 330 Table Catalog formats G 281 G 330 to G 331 API representation of G 281 G 330 to G 331 illustrated G 331 as organized in documents G 331 overriding
75. 74 to G 75 user interfaces setting up for API clients G 7 G 17 to G 44 user configuration of G 30 to G 31 using hypertext commands in G 31 to G 34 R 192 user initiated events responding to G 34 to G 42 users configuring the user interface G 30 to G 31 f codes for common actions of tables G 74 prompting for input G 7 G 17 to G 24 functions for R 257 to R 261 responding to actions of G 7 G 29 FDK Programmer s Reference amp Guide Index Subjects a returning control to function for R 25 R 96 simulating the input of G 74 to G 75 utility functions See API utility functions FDE utility library functions utility libraries See FDE utility libraries V valid elements function for getting R 112 valType constants tables of G 273 R 690 values See property values variable format building blocks G 324 to G 325 variable formats G 281 G 324 to G 326 API representation of G 281 G 325 to G 326 building blocks for G 324 to G 325 classes of G 325 definitions of illustrated G 325 properties of G 325 R 672 See also variables variables G 281 G 326 to G 327 API representation of G 281 G 326 to G 327 API representation of the beginning of G 314 R 167 R 687 API representation of the end of G 314 R 167 R 687 creating G 148 to G 149 function for R 209 to R 210 illustrated G 326 inserting G 324 G 326 properties of G 326 to G 327 R 672 restrictions on inserting G 326 updating function for R 7 R 342 See a
76. 9 ScrallBox 23 also selected in _ fom oc aor FIGURE 10 12 Item selected in the Item Order scroll list and the DRE file If you assign a keyboard shortcut to an item make sure that the label containing the shortcut and the item are in sequential order Move the label item so that it precedes the item in the Item Order scroll list If you do not assign keyboard shortcuts the label and the item do not need to be in sequential order If you use a box item to group other items make sure the items it contains appear immediately after it in the Item Order scroll list Note that this order is important only if the box contains other items if the box does not contain any items or if the box is used as a separator see Boxes on page 198 the item order is not important Item Order 0 Label 1 Label 2 TextBox 5 CheckBox 6 CheckBox 7 Button Items contained in a box appear right after the box in the Item Order scroll list FiGurRE 10 13 Order of items in the Item Order scroll list FDK Programmer s Guide 195 a Creating Custom Dialog Boxes for Your Client Identifying basic items Each dialog box requires some basic items You need to specify these items as part of the properties of the dialog box These items include e Title label The title label is a label that appears in the title bar of the dialog box e First focus The first focus of a dialog box is the item selected when the user fi
77. A 4 J k a 2 ap a eS s a B B 2 F e 2 EIJ j3 jjs Virtual Environment Real Machine Platform specific code FDE Platform independent code clients and libraries FiGURE 16 1 Relationship of the FDE to a client FDK Programmer s Guide 365 16 Introduction to FDE 366 The virtual environment The FDE s virtual environment abstracts the functionality of platform dependent compilers operating systems and C language libraries It provides the following facilities to replace platform dependent schemes e I O channels Channels are an abstraction of I O streams Instead of directly using the input output and temporary files of a particular environment you use the virtual environment s channels e Memory handling The virtual environment provides platform independent memory allocation and deallocation functions for pointers and handles Utility libraries The FDE utility libraries provide the following types of functions e Platform independent replacements for C language library functions such as strcpy or strlen MetricT type functions for converting and manipulating FrameMaker product Met ricT values The MetricT data type is used in the API to express measurements such as font sizes and line widths It is also used in MIF lt MathFullForm gt statements For more information on the MetricT data type see MetricT values on page 675 of the FDK Programmer s Ref
78. API represents global document information with FO_Doc object properties How the API represents the selection in a document The API uses several properties to specify what is selected in a document e FP_TextSelection specifies a structure that provides the location of the insertion point or the beginning and end of a text selection e FP_FirstSelectedGraphicInDoc specifies the ID of the first graphic in the list of selected graphics in a document e FP_SelectedTbl specifies the ID of a table that contains the insertion point or some selected cells e FP_ElementSelection specifies the range of elements selected if the document is a structured document in a FrameMaker session The following table summarizes the different types of selection in an unstructured document and how these properties are set to represent them Selection state How selection properties are set bral No object is selected There FP_TextSelection specifiesan F_TextRangeT structure is no text selection or for which the objId and offset fields of insertion point F_TextRangeT beg and F_TextRangeT end are setto 0 bral FP_FirstSelectedGraphiciInDoc is 0 FP_SelectedTbl is 0 aval One or more graphic objects FP_TextSelection specifiesan F_TextRangeT structure are selected for which the objId and offset fields of F_TextRangeT beg and F_TextRangeT end are setto 0 bral FP_FirstSelectedGraphicInDoc specifies the ID of the first selected gra
79. Couldn t open FF_ALERT_CONTINUE_NOTE else F_Sprintf msg StringT my doc s ID is 0x x docId F_ApiAlert msg FF_ALERT_CONTINUE_NOTE 1 Examples in this manual use UNIX pathnames For information on specifying pathnames on other platforms see the FDK Platform Guide for that platform FDK Programmer s Guide 47 a Executing Commands with API Functions 48 Opening a document or book with F_ApiOpen To open a document or book and programmatically specify responses to warnings and messages that the FrameMaker product issues use F_ApiOpen With F_ApiOpen you can specify aspects of the Open operation such as whether to make a document visible and whether to use an Autosave file You can specify all aspects of the operation or you can specify some aspects and allow the user to decide others For example you can instruct the FrameMaker product to only open a MIF file but allow the user to choose the file To use F_ApiOpen you should first understand property lists and how to manipulate them directly For more information on this subject see Representing object characteristics with properties on page 270 and Manipulating property lists directly on page 93 The syntax for F_ApiOpen is F_ObjHandleT F_ApiOpen StringT fileName F_PropValsT openParamsp F_PropValsT openReturnParamspp This argument Means fileName The absolute pathname of the file to
80. FDK Programmer s Guide 317 14 Frame Document Architecture 318 How the API represents hidden conditional text The user can choose to hide all the text with a specified condition format If a document has hidden conditional text the FrameMaker product automatically adds a hidden page to it This hidden page is completely invisible to the user It has a single flow named HIDDEN When the user chooses to hide text with a condition format the FrameMaker product removes each block of text with that condition format and inserts a Conditional Text marker type 10 in its place This marker text consists of a plus sign and a five digit integer The FrameMaker product places the blocks of hidden text in the HIDDEN text flow on the hidden page The text begins with a Conditional Text marker containing a minus sign and the integer It ends with another Conditional Text marker containing an equal sign and the integer If the hidden conditional text doesn t span paragraphs it appears in one paragraph If the hidden conditional text spans paragraphs each paragraph of conditional text constitutes a separate paragraph in the HIDDEN flow Suppose you have a body page with some conditional text and some unconditional text The condition tag s format overrides specify that the text appears underlined as shown in Figure 14 21 This sentence contains conditional text This paragraph is also conditional This is a normal parag
81. FO_BodyPage and FO_BookComponent objects session Each time you start FrameMaker you are starting a session type in properties Font characteristics and conditional text properties that apply to new text typed at the insertion point unique persistent An integer that uniquely identifies an object within a document An identifier UID object s UID remains the same from one FrameMaker session to the next virtual environment FDE functionality that abstracts the functionality of platform dependent compilers operating systems and C libraries FDK Programmer s Guide 391 Symbols FMHOME directory getting G 96 plus sign conditional text marker prefix G 318 minus sign conditional text marker prefix G 318 dlg files Windows G 181 G 182 x files UNIX G 181 G 182 G 185 xdi files Windows G 181 G 182 lt endtrange R 407 equal sign conditional text marker prefix G 318 Escape symbol G 26 anchor symbol G 294 G 311 G 332 G 389 dagger symbol indicating read only properties R 495 A aborting commands G 37 active books G 274 API indication of G 275 active documents G 274 API indication of G 275 getting the IDs of G 10 getting the pathname of G 97 Adobe Acrobat book properties governing R 498 R 507 document properties governing R 541 alert boxes G 17 to G 18 displaying G 7 G 11 G 17 to G 18 function for R 5 R 43 to R 44 illustrated G 18 R 43 to R 44 type constants for table G 18
82. FO_Command R 524 FP_HeadArrow property FO_GraphicObject R 593 FP_Height property F_ApiSetMetric G 97 G 99 FP_Height property FO_GraphicObject G 3 G 263 R 593 FP_Height property FO_Rectangle G 3 FP_Height property FO_Row R 651 FP_Height property FO_SubCol R 521 FP_Height property text location R 670 FP_HelpLink property G 176 FP_HelpLink property FO_Command R 525 FP_HelpLink property FO_DialogResource R 532 FP_HiddenPage property FO_Doc G 283 G 292 R 540 FP_HighestLevelElement property FO_Book R 504 FP_HighestLevelElement property FO_Cell R 650 FP_HighestLevelElement property FO_Flow R 581 FP_HighestLevelElement property FO_Tbl R 657 FP_HoleBeforeElement property FO_Element R 644 FP_HostName property FO_Session R 634 FP_HypertextCommandText property FO_Doc R 552 FP_HypertextDoValidate property FO_Doc R 551 FP_HypertextParseBadParam property FO_Doc R 552 FP_HypertextParsedArgs property FO_Doc R 552 FDK Programmer s Reference amp Guide Index Reserved Names a FP_HypertextParsedClientName property FO_Doc R 553 FP_HypertextParsedCmdCode property FO_Doc R 552 R 555 FP_HypertextParsedCmdDest property FO_Doc R 552 FP_HypertextParsedCmdDestObjID property FO_Doc R 552 FP_HypertextParsedCmdDestObjType property FO_Doc R 552 FP_HypertextParsedCmdMatrixColumns property FO_Doc R 552 FP_HypertextParsedCmdMatrixRows property FO_Doc R 552 FP_HypertextParsedFlowName property
83. FO_Doc R 553 FP_HypertextParsedLinkName property FO_Doc R 553 FP_HypertextParsedMessage property FO_Doc R 553 FP_HypertextParsedPageName property FO_Doc R 553 FP_HypertextParsedTitle property FO_Doc R 553 FP_HypertextParseErr property FO_Doc R 552 FP_HypertextParseErrMsg property FO_Doc R 552 FP_HypertextValidateErr property FO_Doc R 552 FP_Hyphenate property FO_FmtChangeList R 583 FP_Hyphenate property FO_Pgf R 617 FP_Hyphenate property FO_PgfFmt R 625 FP_HyphMinPrefix property FO_FmtChangeList R 583 FP_HyphMinPrefix property FO_Pgf R 617 FP_HyphMinPrefix property FO_PgfFmt R 625 FP_HyphMinSuffix property FO_FmtChangeList R 583 FP_HyphMinSuffix property FO_Pgf R 617 FP_HyphMinSuffix property FO_PgfFmt R 625 FP_HyphMinWord property FO_FmtChangeList R 583 FP_HyphMinWord property FO_Pgf R 617 FP_HyphMinWord property FO_PgfFmt R 625 FP_IconBarOn property FO_Session R 634 FP_Iconified property FO_Doc G 97 FP_ImportFilters property FO_Session R 634 FP_ImportFmtInclude property FO_BookComponent R 511 FP_ImportHint property FO_Inset R 599 syntax of FP_ImportHint strings G 247 R 600 FP_ImportHint property FO_TextInset R 662 index 53 os Index Reserved Names syntax of FP_ImportHint strings R 663 FP_Inclusions property FO_ElementDef R 647 FP_InCond property FO_Doc R 574 FP_InCond property FO_Row G 333 R 651 FP_InCond property text location G 126 G 317 R 670 FP_IncrVa
84. FO_PgfFmt R 623 FP_FontFamily property FO_CharFmt R 515 FP_FontFamily property FO_Doc R 574 FP_FontFamily property FO_FmtChangeList R 586 FP_FontFamily property FO_Pgf R 614 FP_FontFamily property FO_PgfFmt R 624 FP_FontFamily property text location G 317 R 669 FP_FontFamilyAttributes property FO_Session R 633 index 52 FP_FontFamilyNames property FO_Session G 276 R 633 FP_FontPlatformName property G 306 FP_FontPlatformName property FO_CharFmt R 515 FP_FontPlatformName property FO_Doc R 574 FP_FontPlatformName property FO_Pgf R 614 FP_FontPlatformName property FO_PgfFmt R 624 FP_FontPlatformName property text location R 669 FP_FontPostScriptName property G 307 G 308 FP_FontPostScriptName property FO_CharFmt R 515 FP_FontPostScriptName property FO_Doc R 574 FP_FontPostScriptName property FO_Pgf R 614 FP_FontPostScriptName property FO_PgfFmt R 624 FP_FontPostScriptName property text location R 669 FP_FontSize property FO_CharFmt R 516 FP_FontSize property FO_Doc R 574 FP_FontSize property FO_FmtChangeList R 586 FP_FontSize property FO_Pgf R 614 FP_FontSize property FO_PgfFmt R 624 FP_FontSize property text location R 669 FP_FontSizeChange property FO_FmtChangeList R 586 FP_FontVariation property FO_CharFmt R 516 FP_FontVariation property FO_Doc R 574 FP_FontVariation property FO_FmtChangeList R 586 FP_FontVariation property FO_Pgf R 615 FP_FontVar
85. FO_Pof FP_FirstPgf Paragraph 1 m F_TextltemsT A FP_FirstTextFramelnFlow FO_TextFrame gt Left text frame 2 3 L WL i gt a E gt z 2 a a a 3 E uy L WL E E p FO_Pof e e FP_LastPgf Paragraph 2 FO_Flow E Le FP_FirstPgf F_TextltemsT E 3 3 D Z ai i a ft y FO_TextFrame r r Ri 5 FP_LastTextFramelnFlow Right text frame om Ea 2 l a ty iL FO_Pof Paragraph 3 m FP_LastPgf F_TextltemsT FIGURE 14 16 Objects that represent a flow with text frames and paragraphs Like text frames subcolumns FO_SubCol objects have FP_FirstPgf and FP_LastPgf properties which specify the first and last paragraphs in them If a paragraph begins in one text column and ends in another the paragraph s ID is specified by the FP_LastPgf property of the subcolumn in which it begins and the FP_FirstPgf property of the subcolumn in which it ends Character Catalog formats Each document has a Character Catalog containing one or more character formats What the user sees Each character format has a name or tag which usually corresponds to a type of text such as Emphasis Usertype or Booktitle It also contains information about how text should look FDK Programmer s Guide 305 14 Frame Document Architecture such as its font family weight and angle To make the appearance of a set of characters conform to a Character Catalog format you apply the
86. FO_Rectangle objects and anchored frames FO_AFrame objects are all in the same list To determine objects types as you traverse them use F_ApiGetObjectType The syntax for F_ApiGetObjectType is UIntT F_ApiGetObjectType F_ObjHandleT docId F_ObjHandleT objId This argument Means docId The ID of the document book or session containing the object objid The ID of the object whose type you want to get For example the following code counts the number of anchored frames in the active document include futils h IntT numFrames 0 F_ObjHandleT docId objId UCharT msg 256 docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Get ID of first graphic in the list of graphics objId F_ApiGetId FV_SessionId doclId FP_FirstGraphicInDoc Traverse list of graphics counting anchored frames while objId if F_ApiGetObjectType docId objId FO_AFrame numFramest objId F_ApiGetId docId objId FP_NextGraphicInDoc F_Sprintf msg The document has d anchored frames numF rames F_ApiAlert msg FF_ALERT_CONTINUE_NOTE Traversing ordered lists of objects Traversing the list of all the objects of a certain type in a document is useful if you want to get every object of that type and the order doesn t matter to you However it isn t very useful if you want the objects in some kind of order such as the order in which they appear on a docume
87. FO_TextFrame FO_TextLine or FO_Var containing the text flags Bit flags that specify the type of text items to retrieve To get specific types of text items OR the constants that represent them for example FTI_FlowBegin and FTI_String into flags To get all types of text items specify 1 For a complete list of the constants that represent text item types see F_ApiGetText on page 164 of the FDK Programmer s Reference FDK Programmer s Guide 111 o 6 Manipulating Text 112 The F_TextItemsT structure contains an array of text items Each string of characters with common character and condition properties each anchor and each line or column break in the text constitutes a separate text item F_TextItemsT is defined as typedef struct UIntT len The number of text items F_TextItemT val Array of text items F_TextItemsT The API represents each text item with an F_TextItemT structure F_TextItemT is defined as typedef struct IntT offset Characters from beginning IntT dataType Text item type e g FTI_String union StringT sdata String if the type is FTI_String F_ObjHandleT idata ID if item is an anchor u F_TextItemT If a text item represents a string of characters F_TextItemT dataType is set to FTI_String and F_TextItemT u sdata contains the string If the text item represents an anchor F_Text ItemT dataType is set to a constant indica
88. FP_Overflowed property FO_Cell R 650 FP_Overflowed property FO_Fn R 581 FP_OverFlowed property FO_SubCol R 521 FP_OverFlowed property FO_Tbl R 653 FP_Overline property FO_CharFmt R 517 FP_Overline property FO_Doc R 575 FP_Overline property FO_FmtChangeList R 587 FP_Overline property FO_Pgf R 615 FP_Overline property FO_PgfFmt R 624 FP_Overline property text location R 671 FP_Overprint property FO_GraphicObject R 594 FP_OyamojiTextRange property FO_Rubi R 630 FP_PageBackground property FO_BodyPage R 611 FP_PageFrame property FO_BodyPage G 290 R 611 FP_PageFrame property FO_HiddenPage G 290 R 611 FP_PageFrame property FO_MasterPage G 290 R 612 FP_PageFrame property FO_RefPage G 290 R 612 FP_PageFramePage property FO_UnanchoredFrame R 608 FP_PageHeight property FO_BodyPage R 611 FP_PageHeight property FO_Doc R 559 FP_PageHeight property FO_HiddenPage R 611 FP_PageHeight property FO_MasterPage R 612 FP_PageHeight property FO_RefPage R 612 FP_PagelsRecto property FO_BodyPage R 611 FP_PageNext property FO_BodyPage G 291 R 611 FP_PageNext property FO_MasterPage G 291 R 612 FP_PageNext property FO_RefPage G 291 R 612 FP_PageNum property FO_BodyPage R 611 FP_PageNum property FO_Inset R 600 FP_PageNum property FO_MasterPage R 612 FP_PageNum property FO_RefPage R 612 FP_PageNumbering property FO_BookComponent R 511 FP_PageNumComputeMethod property FO_BookComponent R 511
89. F_ApiGetText fails FV_FO_TBL_BODY FV_FO_TBL_FOOTING FV_FO_MARKER FV_FO_TBL FV_FO_GRAPHIC FV_FO_EON FV_FO_TBL_ROW Example The following code retrieves and prints the text in the active document s main flow to the console It retrieves and prints only strings and line ends include futils h F_ObjHandleT docId flowId IntT i F_TextItemsT tis F_TextItemT ip Get IDs for active document and main flow docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc flowId F_ApiGetId FV_SessionId docId FP_MainFlowInDoc tis F_ApiGetText docId flowId FTI_String FTI_LineEnd Traverse text items and print strings and line ends for i 0 i lt tis len i ip amp tis val i if ip gt dataType FTI_String F_Printf NULL s ip gt u sdata else F_Printf NULL n F_ApiDeallocateTextItems amp tis FDK Programmer s Guide 113 o 6 Manipulating Text Getting and setting the insertion point or text selection The Frame API uses the document property FP_TextSelection to specify the insertion point or text selection in a document This property specifies a text range or F_TextRangeT structure which is defined as typedef struct F_TextLocT beg Beginning of the text range F_TextLocT end End of the text range F_TextRangeT The F_TextLocT structure which specifies a text location a partic
90. False F_ApiSilentPrintDoc docId The following code opens tmo my doc and modifies its default print settings so that the FrameMaker product will print two copies of the document to a printer named ps2 It does this by setting the document properties that specify the number of copies FP_PrintNumCopies and the printer FP_PrinterName to 2 and ps2 respectively F_ObjHandleT doclId Open the document docId F_ApiSimpleOpen tmp my doc False Change my doc s print properties F_ApiSetInt FV_SessionId docId FP_PrintNumCopies 2 F_ApiSetString FV_SessionId docId FP_PrinterName ps2 F_ApiSilentPrintDoc docId FDK Programmer s Guide Executing Commands with API Functions 4 If you save tmp my doc or attempt to print it within the same session the default printer will be ps2 and the default number of copies will be 2 unless your client or the user changes the values of FP_PrinterName and FP_PrintNumCopies Saving documents and books To save a document or book use one of the following functions e F_ApiSimpleSave is an easy to use function for saving a document or book e F_ApiSave allows you to script the process for saving a document or book Saving a document or book with F_ApiSimpleSave The syntax for F_ApiSimpleSave is F_ObjHandleT F_ApiSimpleSave F_ObjHandleT docId StringT saveAsName IntT interactive This argument Means dociId ID of the document or book
91. G 298 R 580 FP_LastUpdate property F_ApiUpdateTextInset G 236 R 341 FP_LastUpdate property FO_Text Inset R 663 FP_Leading property FO_FmtChangeList R 584 FP_Leading property FO_Pgf G 3 R 619 FP_Leading property FO_PgfFmt R 627 FP_LeadingChange property FO_FmtChangeList R 584 FP_LeftColNum property FO_Tbl G 87 R 656 FP_LeftIndent property FO_FmtChangeList R 584 FP_LeftIndent property FO_Pgf G 3 G 303 R 619 FP_LeftIndent property FO_PgfFmt G 274 R 626 FP_LeftIndentChange property FO_FmtChangeList R 584 FP_LeftMargin property FO_Doc R 559 FP_LeftMasterPage property FO_Doc R 540 FP_LetterSpace property FO_FmtChangeList R 583 FP_LetterSpace property FO_Pgf R 621 FP_LetterSpace property FO_PgfFmt R 629 FP_LineAscent property text location R 670 FDK Programmer s Reference amp Guide Index Reserved Names a FP_LineBaseLine property text location R 670 FP_LineBreakAfter property FO_Doc R 576 FP_LineCap property FO_GraphicObject R 593 FP_LineDescent property text location R 670 FP_LineSpacing property FO_Pgf R 619 FP_LineSpacing property FO_PgfFmt R 627 FP_LineSpacingFixed property FO_FmtChangeList R 584 FP_Locked property FO_Pgf R 547 R 617 FP_Locked property FO_Tbl R 653 FP_Locked property FO_Var R 672 FP_Locked property FO_XRef R 530 FP_Locked property text location R 670 FP_LocX property F_ApiSetMetric G 100 FP_LocX property FO_Doc G 97 FP_LocX prope
92. G 368 streat C library function G 370 stremp C library function G 370 strepy C library function G 370 StringListT structure G 382 R 678 StringT data type G 3 G 90 G 271 G 368 G 381 R 11 R 16 R 158 R 675 strlen C library function G 370 strtod C library function R 492 strtol C library function R 493 Text properties FO_Cell R 651 Text properties FO_Flow R 580 Text properties FO_SubCol R 521 Text properties FO_TextFrame R 606 Text properties FO_TextLine R 607 TXT_10 f code G 39 TXT_FAMILY_AND_ VARIATION f code G 39 UByteT data type G 368 R 675 UCharT data type G 368 R 675 UILanguage G 25 UIntT data type G 368 R 675 UShortT data type G 368 R 675 U V W X Y Z valType constants tables of G 273 R 690 VoidT data type G 368 R 675 XML files importing G 230 FDK Programmer s Reference amp Guide index 75 oe Index Reserved Names index 76 FDK Programmer s Reference amp Guide
93. G 72 R 324 FF_UFF_FONT flag F_ApiSimpleImportFormats G 72 R 324 FF_UFF_MATH flag F_ApiSimpleImportFormats G 72 R 324 FF_UFF_PAGE flag F_ApiSimpleImportFormats G 72 R 324 FDK Programmer s Reference amp Guide FF_UFF_PGF flag F_ApiSimpleImportFormats G 72 R 324 FF_UFF_REFPAGE flag F_ApiSimpleImportFormats G 72 R 324 FF_UFF_REMOVE_EXCEPTIONS flag F_ApiSimpleImportFormats G 73 R 324 FF_UFF_REMOVE_PAGE_BREAKS flag F_ApiSimpleImportFormats G 73 R 324 FF_UFF_TABLE flag F_ApiSimpleImportFormats G 72 R 324 FF_UFF_VAR flag F_ApiSimpleImportFormats G 73 R 324 FF_UFF_XREF flag F_ApiSimpleImportFormats G 73 R 324 FF_VISIBLE_ONLY flag F_ApiClipboardFunction G 128 R 57 R 68 R 73 R 246 FF_XRUI_CLOSED_DOCS flag F_ApiUpdateXRefs R 343 FF_XRUI EVERYTHING flag F_ApiUpdateXRefs R 343 FF_XRUI_FORCE_UPDATE flag F_ApiUpdateXRefs R 343 FF_XRUI INTERNAL flag F_ApiUpdateXRefs R 343 FF_XRUI_OPEN_DOCS flag F_ApiUpdateXRefs R 343 FilePathT structure G 375 R 382 R 677 FMacPath path type G 376 FO_ FO_AFrame objects G 280 G 295 R 596 properties of R 596 FO_Arc objects G 280 R 598 properties of R 598 FO_BodyPage objects G 11 G 280 G 289 G 290 G 291 R 610 properties of R 610 FO_Book objects G 351 R 84 R 495 properties of G 353 R 495 FO_BookComponent objects G 351 R 507 properties of R 507 FO_Cell objects G 281 G 303 G 332 G 333 G 336 G 337
94. Guide Creating Custom Dialog Boxes for Your Client The size and position values do not affect the initial position of modal dialog boxes Modal dialog boxes always appear in the center of the screen Setting the properties of a dialog item Like standard Frame graphic objects dialog items have properties These properties define the size and position of the item and relationships with other items You can set the following properties for a dialog item e Basic properties e Properties specific to different types of dialog items e Keyboard shortcuts e Relationships with other dialog items The rest of this section describes the different types of dialog items and explains how to set the properties for these items Setting basic dialog item properties To set or modify an item s basic properties follow these steps 1 Select the item 2 From the Graphics menu choose Object Properties 3 In the Dialog Item Properties dialog box specify the properties of the item Figure 10 16 shows an example of the Dialog Item Properties dialog box Dialog Item Properties 100 0 pt HypertextHelp clnthelp edit box FIGURE 10 16 Dialog ltem Properties dialog box for a text box FDK Programmer s Guide 197 a Creating Custom Dialog Boxes for Your Client 198 Working As is the case with standard Frame graphic objects different dialog items have different properties Each type of dialog item has a different Dialog Item
95. Guide 341 14 Frame Document Architecture For a reserved color all the properties are read only except FP_ColorOverPrint FP_ColorPrintCtl and FP_ColorViewCt1 If you try to change any of the read only properties the FDK returns an error of FE_ReservedColor except for properties that normally return FE_ReadOn1y for unreserved colors Structural element definitions A structured FrameMaker document has an Element Catalog which contains structural element definitions and named format change lists There are two ways to test whether a document is structured via the API To test whether a document contains structure elements get the FP_HighestLevelElement property for the main FO_F low object in the document To test whether the document contains an element catalog get the FP_FirstElementDefInDoc property for the FO_Doc object If you get legal values for these properties then the document contains structure elements or an element catalog What the user sees Each structural element definition has a name tag which usually corresponds to a type of document component or structural element such as Section List Quotation or BodyPara An element definition specifies an element s relationship to other elements in a structured document An element definition can also contain formatting information about the element The parts of an element definition that specify an element s format are known as the format rules T
96. In that list set the FS_ShowBookErrorLog flag to True For more information about the update book properties see Creating an updateParamsp script with F_ApiGetUpdateB ookDefaultParams on page 357 Writing messages to the error log The FrameMaker product includes an API client that writes messages to the error log To write a message to the error log you must use F_ApiCallClient The syntax for the client call is F_ApiCallClient BookErrorLog log b bookld d docla o objla text where e BookErrorLog is the name of the client to call e og identifies this as a log message e bis either the book ID or a document ID typically the active book e dis either a document ID or an object ID typically a document associated with a book component e ois an object in the document represented by the d argument If you pass both a document ID and an object ID the call adds a hypertext link from the error message to the object you specified e textis the text of the message to appear in the log To post a time stamp in the message pass the FM_PRINT_DATESTAMP token as the message string The call creates a unique log for each book or document ID you pass in the b argument if you pass 0 for a book ID you will create a log that is not associated with any book all calls with the 0 book ID will go to that log file When you pass a document ID for the d argument the call creates an entry with the d
97. Manipulating document windows The API provides several properties that allow you to manipulate document and book windows To change a document window s size and screen location set the document s FP_ScreenxX FP_ScreenY FP_ScreenWidth and FP_ScreenHeight properties To bring the window to the front set the document s FP_IsInFront property FDK Programmer s Guide 97 aes Getting and Setting Properties 98 Setting a document or book title bar The API allows you to set the title bars of both documents and books By default a document or book s title bar displays its name However you can make it display another string by setting the document or book s FP_Label property to the string For example the following code displays the string MyTitle in the title bar of the active document F_ObjHandleT docId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc F_ApiSetString FV_SessionId docId FP_Label MyTitle After you set a document s title bar it doesn t change until you reset it or the user closes the document Setting the title bar of a document or book doesn t change the name of the document or book file itself If you set the document or book title bar and the user closes and reopens the document or book the document or book name appears in the title bar again Setting a document or book status bar The API allows you to set the status bars of both documents and books If your client conducts extensive pro
98. Paragraph Tag Paragraph Tag 1ofi 100 z zlAe FiGURE 10 21 Completed layout of the dialog items 9 If you intend to create the dialog box for more than one platform change the platform view to check the layout on the other platforms FDK Programmer s Guide 207 a Creating Custom Dialog Boxes for Your Client You may need to make minor adjustments to the layout If you do you need to apply the changes to the other platform views Press Esc d r to reset the other platform views Set the properties of the dialog box To set the properties of the sample dialog box follow these steps 1 2 Select the dialog box in the new DRE file From the Graphics menu choose Object Properties The Item Order scroll box lists the three items remaining in this DRE file Using the Up and Down buttons change the order of items in the dialog box so that the Apply Paragraph Tag label is item 0 the button is item 1 the text box is item 2 and the Paragraph Tag label is item 3 These numbers are used to identify the dialog items in the code For details on the code used to run this example see A simple example on page 215 Note that the label for the text box follows the text box in consecutive order Since no keyboard shortcuts are defined in this example the label of the text box does not need to precede the text box The label and the text box can be in any order and do not need to be conse
99. Programmer s Reference amp Guide as organized in documents G 291 illustrated G 292 pagination of G 284 properties of G 290 to G 292 R 610 to R 612 illustrated G 290 G 292 reference G 289 G 391 properties of G 290 G 291 to G 292 R 612 text frame layouts of G 289 visible G 288 See also body pages frames PANTONE color model G 339 paragraph breaks specifying G 121 Paragraph Catalog G 300 Paragraph Catalog formats G 102 G 280 G 300 to G 302 API representation of G 280 G 300 to G 302 applying to paragraphs G 89 G 102 to G 103 G 302 changing G 91 G 302 changing individual paragraph formats and G 302 creating G 145 as organized in documents G 302 overriding G 302 properties of G 301 to G 302 R 621 to R 629 reapplying G 306 tags for G 300 G 302 paragraph default font properties FO_Pgf R 614 to R 616 paragraph default font properties FO_PgfFmt R 623 to R 625 Paragraph Designer illustrated G 301 specifying named frames with G 289 G 390 paragraph formats FO_PgfFmt R 621 to R 629 autonumbering properties of R 623 changing G 302 to G 305 creating G 145 default font properties of R 623 to R 625 hyphenation properties of R 625 indentation properties of R 626 language property of R 626 line spacing property of R 627 object pointer property of R 627 placement properties of R 627 to R 628 reference frame properties of R 628 spell checking language property of R 626 tab properties of R 16 R 629 table cell properties
100. Properties dialog box For most types of dialog items you can set the following properties in the Dialog Item Properties dialog box e Position relative to the dialog box In the Left text box type the offset of the item from the left side of the dialog box In the Top or Baseline text box type the offset of the item from the top of the dialog box e Width In the Width text box type the width of the item e Height In the Height text box type the height of the item Note that height is set to a fixed value for some items such as text boxes labels and buttons You cannot specify the height of any of these items For these items height is determined by the height of the text that appears in the item Similarly you cannot specify the width of certain items such as radio buttons check boxes and labels For these items width is determined by the length of the text that appears in the item For most types of items the Dialog Item Properties dialog box also contains the Other Properties text box and the Stuff Item text box The Stuff Item text box displays the number of a dialog item that is related to the current item For instructions on relating dialog items see Relating items in a dialog box on page 203 Some item types have additional properties Instructions on setting these properties are covered in the next section with specific types of items The following sections describe each type of item and item propert
101. R 526 FP_EgqnIntegralSizeLarge property FO_Doc R 550 FP_EgnIntegralSizeMed property FO_Doc R 550 FP_EgnIntegralSizeSmall property FO_Doc R 550 FP_EgqnLevel1SizeLarge property FO_Doc R 550 FP_EqnLevel1SizeMed property FO_Doc R 550 FP_EgqnLevel1SizeSmall property FO_Doc R 550 FP_EgqnLevel2SizeLarge property FO_Doc R 550 FP_EqnLevel2SizeMed property FO_Doc R 550 FP_EqnLevel2SizeSmall property FO_Doc R 550 FP_EgqnLevel3SizeLarge property FO_Doc R 550 FP_EqnLevel3SizeMed property FO_Doc R 551 FP_EqnLevel3SizeSmall property FO_Doc R 551 FP_EqnSigmaSizeLarge property FO_Doc R 551 index 50 FP_EqnSigmaSizeMed property FO_Doc R 551 FP_EgqnSigmaSizeSmall property FO_Doc R 551 FP_ErrorInBookComponent property FO_Element R 643 FP_Exclusions property FO_ElementDef R 646 FP_ExpandOMaticParent property FO_Command R 524 FP_ExportFilters property FO_Session R 633 FP_ExtractElementTags property FO_BookComponent R 514 FP_ExtractTags property FO_BookComponent R 510 FP_FamilyName property FO_Color R 519 FP_Fcode property FO_Command R 524 FP_Fcodes property FO_Command R 524 FP_FileExtensionOverride property FO_Doc R 504 FP_Fill property FO_GraphicObject G 11 R 593 FP_FirstAFrame property FO_SubCol R 521 FP_FirstAFrame property FO_TextFrame R 605 FP_FirstBodyPageInDoc property FO_Doc G 84 G 283 G 291 R 538 FP_FirstCell property FO_SubCol R 521 FP_FirstCell property FO_TextFrame R 605 F
102. R 544 FP_PDFDistillerAbsent property FO_Book R 500 FP_PDFDistillerAbsent property FO_Doc R 544 FP_PDFEndPage property FO_Book R 500 FP_PDFEndPage property FO_Doc R 544 FP_PDFJobOption property FO_Book R 501 FP_PDFJobOption property FO_Doc R 544 FP_PDFJobOptionsAbsent property FO_Book R 501 FP_PDFJobOptionsAbsent property FO_Doc R 544 FP_PDFLevel property FO_PgfFmt R 622 FP_PDFOpenPage property FO_Book R 501 FP_PDFOpenPage property FO_Doc R 544 FP_PDFPageHeight property FO_Book R 501 FDK Programmer s Reference amp Guide Index Reserved Names as FP_PDFPageHeight property FO_Doc R 544 FP_PDFPageWidth property FO_Book R 501 FP_PDFPageWidth property FO_Doc R 544 FP_PDFPrintPageRange property FO_Book R 501 FP_PDFPrintPageRange property FO_Doc R 545 FP_PDFRegistrationMarks property FO_Book R 501 FP_PDFRegistrationMarks property FO_Doc R 545 FP_PDFSeparateFiles property FO_Book R 501 FP_PDFSeparateFiles property FO_Doc R 545 FP_PDFStartPage property FO_Book R 501 FP_PDFStartPage property FO_Doc R 545 FP_PDFStructureLevell property FO_PgfFmt R 622 FP_PDFZoomFactor property FO_Book R 501 FP_PDFZoomFactor property FO_Doc R 545 FP_PDFZoomType property FO_Book R 501 FP_PDFZoomType property FO_Doc R 545 FP_Pen property FO_GraphicObject R 594 FP_Pen property FO_RulingFmt R 631 FP_PgfAlignment property FO_FmtChangeList R 585 FP_PgfAlignment property FO_Pgf R 619 FP_PgfAlignment prop
103. R 84 R 648 properties of G 337 R 648 FO_CharFmt objects G 124 G 269 G 280 G 306 G 308 R 515 properties of R 515 FDK Programmer s Reference amp Guide Index Reserved Names E FO_Color objects G 269 G 281 G 339 R 84 R 519 properties of R 519 FO_CombinedFontDefn objects G 269 G 282 properties of R 522 FO_Command objects G 161 G 269 R 75 R 81 properties of G 162 R 523 FO_CondFmt objects G 269 G 281 G 310 R 522 R 529 properties of R 529 FO_DialogResource objects G 211 G 214 G 221 R 531 properties of R 531 FO_DlgBox objects G 211 R 533 FO_DlgButton objects G 211 R 533 properties of R 533 FO_DlgCheckBox objects G 211 R 533 properties of R 533 FO_DlgEditBox objects G 211 R 534 properties of R 534 FO_DlgImage objects G 211 G 218 R 534 properties of R 534 FO_DlgLabel objects G 211 R 534 properties of R 534 FO_DlgPopUp objects G 211 G 218 R 535 properties of R 535 FO_DlgRadioButton objects G 211 R 535 properties of R 535 FO_DlgScrollBar objects R 536 properties of R 536 FO_DlgScrollBox objects G 211 G 218 R 536 R 537 properties of R 536 R 537 FO_DlgTriBox objects G 211 R 537 properties of R 537 FO_Doc objects G 3 G 275 G 280 G 282 G 304 R 84 R 537 properties of G 304 R 537 FO_Element objects G 281 R 638 properties of R 638 FO_ElementDef objects G 269 G 281 G 343 R 645 properties of R 645 FO_Ellipse objects G 280 R 598 properties of R 598 FO_Flow ob
104. Ron Avitzur PANTONE Computer Video simulations displayed may not match PANTONE identified solid color standards Use current PANTONE Color Reference Manuals for accurate color PANTONE Open Color Environment POCE Pantone Inc 1994 1996 Pantone Inc is the copyright owner of PANTONE Open Color Environment POCE and Software which are licensed to Adobe to distribute for use only in combination with the Adobe Software PANTONE Open Color Environment POCE and Software shall not be copied onto another diskette or into memory unless as part of the execution of the Adobe Software The Spelling and Thesaurus portions of this product are based on Proximity Linguistic Technology The Proximity Merriam Webster Linguibase 1983 1990 Merriam Webster Inc C A Stromberg AB Espasa Calpe Hachette IDE AS Kruger Lluis de Yzaguirre i Maura Merriam Webster Inc Munksgaard Int Publishers Ltd Nathan Text amp Satz Datentechnik Van Dale Lexicographie bv William Collins Sons amp Co Ltd Zanichelli All rights reserved Color Database Dainippon Ink amp Chemicals Inc licensed to Adobe Outside In Viewer Technology 1992 1996 Inso Corporation Image Stream Graphics and Presentation Filters 1992 1996 Inso Corporation All rights reserved TRUMATCH 4 Color Selector 1992 Trumatch Inc All rights reserved Portions copyrighted for the FrameViewer Retrieval Tools 1988 1995 Verity Inc All rights reserv
105. Specify sets of format rule clauses Types of objects that represent it FO_CondFmt FO_Marker FO_MarkerType FO_XRefFmt FO_XRef FO_VarFmt FO_Var FO_Fn FO_RulingFmt FO_Tb1Fmt FO TOL FO_Row FO_Cell FO_Color FO_TiApiClient FO_TiFlow FO_TiText FO_TiTextTable FO_ElementDef FO_Element FO_FmtRule FDK Programmer s Guide 281 14 Frame Document Architecture 282 Type of information Format rule clauses Format change list Rubi composites Combined font definitions Function Specify which formats to apply to elements in various contexts Specify format changes applied to an element in a specific context Describe the oyamoji base word and rubi phonetic spelling of certain words in Asian text Describe pairs of Asian and Western fonts that are treated as a single font family Types of objects that represent it FO_FmtRuleClause FO_FmtChangeList FO_Rubi FO_CombinedFontDefn The other sections of this chapter discuss the different types of information in a document How the API organizes the objects that constitute a document The API uses an FO_Doc object to organize the objects that constitute a document FO_Doc objects have a number of properties that specify the IDs of other objects in the document Many of these properties specify the ID of the first object in a linked list of objects For FP_FirstPgfFmtInDoc specifies the fir
106. Structured FrameMaker commands 5 Getting and Setting Properties What you can do with object properties Getting the IDs of the objects you want to change Manipulating properties Getting and setting session properties Getting and setting document properties Getting and setting graphic object properties Getting and setting paragraph properties Getting and setting book properties Getting and setting FrameMaker properties 6 Manipulating Text Getting text soc esaea eea a a a a o E a A A a Getting and setting the insertion point or text selection Adding and deleting text FDK Programmer s Guide Getting and setting text formatting oaoa a a a Executing Clipboard functions a 1 Chapter 7 Manipulating Asian Text 4131 Chapter Creating a rubigroup 2404 ac eg ee bbe Fae Ae RE eee ae ee AO Text encodings is aos se coe ie Se ee oe ea be Pee ee Awe oe ee A Using encoding data aoaaa a Inspecting and manipulating encoded text 2222000 Parsing an encoded string 1 2 Getting the encoding for a text item 2 a a Special issues with double byte encodings o oo aooo e eee ee ee 8 Creating and Deleting API Objects 143 Creating objects ooa ee Deleting objects a sa nen nea Babe Bab hale Ma Bk Pa a he ae ee a Implicit property changes 1 aaa a a a Chapter 9 Manipulating Commands and Menus withthe API 1
107. The ID of the object to get or set the property list for setVal The property list to apply to the object The F_PropValsT structure returned by F_ApiGetProps references memory that is allocated by the API Use F_ApiDeallocatePropVals to free this memory when you are done with it If F_ApiGetProps fails the API sets the len field of the returned structure to 0 FDK Programmer s Guide Getting and Setting Properties 5 The following code copies the properties from one selected graphic object to another Example F_PropValsT props F_ObjHandleT objlId ob j2Id docId Get ID of active document and the two selected objects docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc objlId F_ApiGetId FV_SessionId doclId FP_FirstSelectedGraphicInDoc obj2Id F_ApiGetId docId objlId FP_NextSelectedGraphicInDoc Make sure two objects are selected then copy properties if objlId amp amp obj2Id F_ApiAlert First select two objects FF_ALERT_CONTINUE_WARN else props F_ApiGetProps docId obj1Id if props len 0 return Get props failed F_ApiSetProps docId obj2Id amp props Because a graphic object s x and y coordinates are included in its property list this code moves the two graphic objects to the same location with one object overlaying the other After you have copied a property list to an object you can customize the list by changing individual proper
108. Value FP_FrameParent F_ObjHandleT ID of the frame containing the rectangle MetricT values are 32 bit integers that represent measurements in points The 16 most significant bits represent the digits before the decimal The 16 least significant bits represent the digits after the decimal A point is 65536 1 lt lt 16 in MetricT units For more information on Met ricT see MetricT values on page 675 of the FDK Programmer s Reference fo FO_Rectangle objects actually have many more properties than are shown in the table above For a complete list of Frame API objects and properties see Chapter 3 Object Reference in the FDK Programmer s Reference How clients can change FrameMaker documents books and sessions A client can change FrameMaker documents books and sessions by e Creating and destroying objects The API provides functions to create and destroy objects e Changing object properties The API provides functions to get and set object properties e Programmatically executing FrameMaker product commands such as Open Print Save and Clear All Change Bars How clients communicate with the user A client can communicate with the user by e Creating menus and menu items e Displaying dialog boxes The API allows a client to respond to user actions by e Notifying the client when the user initiates certain events such as Open Save or Quit e Passing a message to the client when the user clicks a
109. add text to table cells see Adding text to table cells on page 122 Adding table rows and columns To add table rows or columns to an existing table use these functions e F_ApiAddCols to add table columns e F_ApiAddRows to add table rows You can t add rows by changing the FO_Tb1 object s FP_Tb1lNumCols and FP_Tb1NumRows properties These properties are read only The syntax for F_ApiAddCols is IntT F_ApiAddCo ls F_ObjHandleT doclId F_ObjHandleT tableld IntT refColNum IntT direction IntT numNewCols This argument dociId tableld refColNum direction numNewCols Means The ID of the document containing the table The ID of the table to which to add columns The column at which to start adding columns The columns are numbered from left to right starting with column 0 The direction in which to add columns To add columns to the left of the reference column specify FV_Le FV_Right The number of columns to add ft To add columns to the right specify If successful F_ApiAddCols returns FE_Success Otherwise it returns an error code The syntax for F_ApiAddRows is 156 FDK Programmer s Guide Creating and Deleting API Objects Ba IntT F_ApiAddRows F_ObjHandleT docId F_ObjHandleT refRowId IntT direction IntT numNewRows This argument Means docId The ID of the document containing the table refRowId The ID of the row at whi
110. an FO_XRefFmt object The ID of the next FO_XRef object in the document The name of the file in which the cross reference source is located The element ID of the cross reference if it is in a structured flow in a FrameMaker document Suppose you insert the cross reference shown in Figure 14 26 using the See Heading amp Page cross reference format shown in Figure 14 25 qos This heading is the x ref source See This heading is the x ref source on page 1 offset 0 dataType FTI_MarkerAnchor idata FO_Marker ID offset 0 dataType FTI_XRefBegin idata FO_XRef ID offset 1 dataType FTI_String sdata See xd2This heading is the x ref source xd3 on page x11 1 offset 47 dataType FTI_XRefEnd idata FO_XRef ID FIGURE 14 26 A cross reference and the text items that represent it The following are some properties of the FO_XRef object that represents the cross reference Property FP_XRefFmt FP_NextXRefInDoc FP_XRefFile Type F_ObjHandleT F_ObjHandleT StringT Value ID of the FO_XRefFmt object representing the See Heading amp Page cross reference format ID of the next FO_XRef object in document An empty string Variable formats The user can insert variables that represent a variety of information such as the page number or the date into text The information a variable provides is specified by a variable f
111. and saveReturnParamspp property lists Steps 2 4 and 5 are discussed in the following sections Creating a saveParamsp script with F_ApiGetSaveDefaultParams The API provides a function named F_ApiGetSaveDefaultParams that creates a default saveParamsp property list If you are setting a number of properties it is easiest to use F_ApiGetSaveDefaultParams to get a default property list and then change individual properties as needed The syntax for F_ApiGetSaveDefaultParams is F_PropValsT F_ApiGetSaveDefaultParams The following table lists some of the properties in the property list returned by F_ApiGetSaveDefaultParams The first value listed for each property is the default value returned by F_ApiGetSaveDefaultParams You can change the list to use the other listed values FDK Programmer s Guide 61 a Executing Commands with API Functions Property FS_FileType Meaning and possible values Specifies the type of file to save to FV_SaveFmtBinary save in Frame binary format for this version of FrameMaker FV_SaveFmtBinary60 save in binary format for FrameMaker 6 0 FV_SaveFmt Interchange save as MIF FV_SaveFmt Stationery save in Stationery format Macintosh only FV_SaveFmtViewOnly save in View Only format FV_SaveFmtSgml save in SGML format FV_SaveFmtText save in Text Only format FV_SaveFmtXm1 save in XML format FV_SaveFm tPdf save as PostScript and th
112. are referenced by F_StringsT structures F_StringsT is defined as typedef struct UIntT len Number of strings StringT val Array of strings F_StringsT For example if Bold and Regular are the only font weights available in the current session the fields of the F_StringsT structure specified by the FO_Session property FP_FontWeightNames have the following values len 3 val lt None gt Regular Bold To set a character format s weight to Bold in this session you set its FP_FontWeight property to 2 For more information on session font properties see How the API indicates which fonts are available in a session on page 276 You can also use the following properties to specify a font 306 FDK Programmer s Guide Frame Document Architecture 14 e FP_FontPlatformName specifies a font name that uniquely identifies the font on a specific platform e FP_FontPostScriptName specifies the name given to a font when it is sent to a PostScript printer specifically the name that is passed to the PostScript FindFont operator before any font coordination operations The PostScript name is unique for all PostScript fonts but may not be available for fonts that have no PostScript version For the same Asian font the PostScript name can be different on different platforms This is because they might have slightly different extensions to the character mappings For example Ryumin Light on the Ma
113. books To compare two versions of a document or book using the FrameMaker product s built in comparison feature use F_ApiCompare The syntax for F_ApiCompare is F_CompareRetT F_ApiCompare F_ObjHandleT olderId F_ObjHandleT newerlId IntT flags StringT insertCondTag StringT deleteCondTag StringT replaceText IntT compareThreshold This argument Means olderId The ID of the older version of the document or book newerId The ID of the newer version of the document or book flags Bit flags that specify how to generate the summary and composite documents insertCondTag The condition tag to apply to insertions shown in the composite document For no insert condition tag specify NULL deleteCondTag The condition tag to apply to deletions shown in the composite document For no delete condition tag specify NULL replaceText Text to appear in place of the deleted text For no replacement text specify NULL compareThreshold If zero the compare function uses the default value of 75 If not zero the the function uses the setting in the FrameMaker configuratin files Threshold expresses the percentage of words that can change before paragraphs are considered not equal If two paragraphs are equal word differences between them are shown within a paragraph in the composite document The F_CompareRetT structure is defined as 68 FDK Programmer s Guide typedef struct F_CompareRetT F_Ob
114. button FO_DlgRadioButton Scroll list FO_DlgScrol11Box Text box or multiline text box FO_D1gEditBox Three state checkbox tribox FO_DlgTriBox The following table lists some dialog item properties FDK Programmer s Guide 211 Ea Handling Custom Dialog Box Events Property Type Meaning FP_Label StringT The label that appears adjacent to the item FP_Labels F_StringsT If the item is a scroll list pop up menu or image pop up menu the list of strings it contains FP_Sensitivity IntT Specifies whether the item is enabled If FP_Sensitivity is False the item is disabled and appears dimmed FP_State IntT The state of the item If the item is a pop up menu image pop up menu or scroll list FP_State specifies the index in the list specified by the FP_Labels property of the chosen string If no string is chosen FP_State is 1 f the item is a button a checkbox or a radio button FP_State specifies FV_DlgOptNotActive when the item is off and FV_DlgOptActive hen the item is on If the item is a tribox FP_State canalso specify FV_DlgOptDontCare when the item is set to As Is Not all types of dialog items have all of these properties For a complete list of properties for each type of dialog item see Dialog boxes on page 531 of the FDK Programmer s Reference Dialog resource and dialog item IDs When you open a dialog resource the API returns its ID The API also assigns a unique ID
115. cell properties of R 616 to R 617 tag properties of R 621 tagging G 302 traversing G 84 G 103 word spacing properties of R 621 index 23 oe Index Subjects See also Paragraph Catalog formats paragraph formats FO_PgfFmt paragraph properties paragraphs FO_PgfFmt Asian character spacing properties of R 622 parent frames of graphic objects defined G 295 G 390 parent s content rules of structural element definitions G 348 pasting text selections G 127 R 23 R 246 to R 247 path types G 376 See also filepaths pathnames pathnames conventions used in this manual G xiv R xx converting FDE filepaths to G 375 converting to FDE filepaths G 375 to G 377 See also filepaths path types pen patterns R 595 illustrated R 595 persistent identifiers See UIDs unique IDs platform names for fonts G 307 to G 308 Macintosh specification string for G 307 Windows specification string for G 307 to G 308 platform views of dialog boxes G 180 G 187 G 189 to G 190 G 207 platform independent code in the FDE illustrated G 365 platform specific code in the FDE illustrated G 365 platform specific views of dialog boxes G 180 to G 181 plus sign conditional text marker prefix G 318 pointers functions for allocating and deallocating memory R 32 freeing memory allocated to R 386 using in memory management G 378 to G 379 R 370 to R 372 R 373 master pointer G 378 points See coordinate pairs points F_PointsT properties funct
116. character string you choose to identify the format on all platforms The vendor ID is a four character string that identifies the filter vendor The FrameMaker product uses these IDs to identify your filter when it reimports a file imported by reference FDK Programmer s Guide Using Imported Files and Insets 12 File to file filter clients can contain more than one filter process in a single client You must register each filter individually and give each one a unique client name even though they are coded in the same file to file filter client For example you might have a DLL named my_filter dll Assume that DLL a process to convert myFormat to MIF and another process to convert FrameMaker documents to myFormat On Windows platforms you would provide two entries in the FrameMaker product s ini file on Unix platforms you would provide two entries in the apiclients file for the Macintosh you would specify the filters individually in the client s resource fork For more information on registering filter clients see the FDK Platform Guide for your platform Specifying format IDs and filetype hint strings When you register a filter the FrameMaker product uses the information you supply to associate that filter with a specific file format The product also uses that information to associate a filter with an imported graphic or a text inset Internally this information is stored in a filetype hint The filetype hint includes the f
117. client s different filters determines which filter to invoke for import and export Another advanage of these filters is they can filter from an external file to an external file For example you could filter from CGM to TIFF and the TIFF file can remain an external file that is imported into the document by reference FDK Programmer s Guide 5 re Introduction to the Frame API Take control clients A take control client is a client that takes control of a FrameMaker product session immediately after the FrameMaker product starts The UNIX implementation of the FDK allows users to specify a take control client in the FrameMaker product command line Take control clients are useful for conducting batch operations in which little or no user interaction is needed Portability The API s design makes it easy to create portable clients In most cases you only need to recompile your client to run it on a different platform To ensure that your client is completely portable use the FDE with the API You should replace platform specific I O string and memory functions in your client with the alternatives the FDE provides For more information on the FDE see Part III Frame Development Environment FDE The FDE and the API provide alternatives to the C language s fundamental data types For example the FDE and the API substitute IntT fora 32 bit int and UCharT for unsigned char The API uses other types for specific purposes For examp
118. client text insets Creating a client text inset To create a client text inset use F_ApiNewAnchoredOb ject To add text to it use F_ApiAddText After you create an inset you may also want to set the properties listed in the following table to provide information about the inset to the user and the FrameMaker product Property Type Meaning FP_TiClientName StringT The registered name of your client FP_TiClientSource StringT The name that appears as the source in the Text Inset Properties dialog box FP_TiClientType StringT The name that appears as the source type in the Text Inset Properties dialog box FP_Name StringT The inset name It is not automatically assigned by the FrameMaker product You can also use a client text inset s FP_TiClientData property to store data such as an SQL query string which your client can use to update the inset For example the following code creates a client text inset containing the text Inset text F_ObjHandleT docId insetId F_TextRangeT tr Add the inset at the current insertion point docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange 0 docId FP_TextSelection if tr beg objId 0 return insetId F_ApiNewAnchoredObject docId FO_TiApiClient amp tr beg FDK Programmer s Guide Using Imported Files and Insets 12 tr beg offset Increment textLoc so it s in the inset Unlock the inset add te
119. closing the dialog box call F_ApiReturnValue FR_ModalStayUp each time the user clicks the button The syntax for F_ApiReturnValue is VoidT F_ApiReturnValue IntT val This argument Means val Specifies a return value for the current callback To prevent a modeless dialog box from closing set it to FR_ModalStayUp For a list of the other values you can specify see F_ApiReturnValue on page 268 of the FDK Programmer s Reference 3 To close the dialog box for an event that is not a button call F_ApiClose For more information about F_ApiClose see Closing a dialog box on page 227 The following code opens and displays a modal dialog box containing a checkbox When the user clicks the checkbox the dialog box remains on the screen If the user clicks any other button the dialog box closes FDK Programmer s Guide define DLG_NUM 1 ECKBOX_NUM 14 F_ObjHandleT dlgId Global variable define CH Handling Custom Dialog Box Events uo Open resource and display dialog box Resource FO_DialogResource multiInteract dlgId F_ApiOpen F_ApiModalDialog DLG_NUM dlgId VoidT F_ApiDialog IntT dlgNum IntT itemNum IntT Event dlgNum modifiers itemNum modifiers Keeps dialog box on screen if checkbox is clicked if itemNum CH F_Printf NULL E CKBOX_NUM User toggled checkbox n F_ApiReturnValue FR_ModalStayUp
120. columns G 158 to G 159 R 22 R 84 FDK Programmer s Reference amp Guide tables R 22 R 83 text frames G 158 text insets R 24 text selections R 23 R 88 to R 89 undefined attributes R 91 dialog box items See dialog items Dialog Box Properties dialog box G 193 illustrated G 194 dialog boxes G 17 to G 24 G 177 to G 227 adding dialog items to G 192 alert G 17 to G 18 API representation of G 211 to G 213 basic items in G 196 Cancel button G 196 capturing screenshots of G 206 client defined functions for R 1 R 5 R 93 to R 94 closing G 227 function for G 227 R 5 compiling G 177 creating G 185 to G 188 custom creating G 177 to G 209 designing G 178 to G 181 G 189 to G 193 using G 211 to G 227 custom modal G 17 default button G 196 deleting dialog items from G 193 designing the layout of G 189 to G 193 G 207 displaying G 219 during initialization G 13 functions for G 7 G 219 R 5 to R 6 R 53 to R 56 editing G 209 editing dialog box information G 179 to G 181 G 209 file selection G 21 to G 22 first focus G 196 getting IDs of items in function for R 5 R 94 handling special events G 226 handling user actions in G 221 to G 227 initializing items in G 218 to G 219 input G 18 to G 21 integer prompt G 18 to G 20 invoking by name G 185 keyboard shortcuts Windows G 202 labels in G 201 FDK Programmer s Reference amp Guide Index Subjects a on Macintosh computers G 180 to G 181 G 189 to G 190 G 207 G 209 mani
121. command If a message or warning condition occurs the FrameMaker product prompts the user For example FDK Programmer s Guide 45 a Executing Commands with API Functions if you call F_ApiSimpleOpen in the interactive mode the FrameMaker product displays the Open dialog box and prompts the user to choose a file to open If the user chooses a text file the FrameMaker product displays a Reading Text File dialog box If you are sure that executing a command won t do something undesirable and you don t want the FrameMaker product to display error and warning messages call a simple function in noninteractive mode Be careful when you do this because you may inadvertently destroy data For example suppose you attempt to save a file by calling F_ApiSimpleSave in the noninteractive mode If the file already exists the FrameMaker product overwrites it without warning your client or the user Noninteractive mode is useful for clients that need to carry out tasks without a user present Using scriptable functions To specify a response for each possible message or warning that the FrameMaker product may issue while executing a command use a scriptable function to execute the command When you call a scriptable function you pass it a script or property list that contains properties corresponding to possible messages or warnings For most messages and warnings you either specify a Yes No or Cancel response or you can instruct the FrameM
122. contain different platform views you can edit the Windows Macintosh or UNIX view of a dialog box under the same version of FrameMaker For example in the UNIX version of FrameMaker you can edit the UNIX Windows and Macintosh views of a dialog box Figure 10 4 illustrates how the UNIX version of FrameMaker displays different views of the same dialog box Note that the first letter in the status bar indicates the current platform view of the dialog box 180 FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client 10 My New Dialog Box TagNane AutoLabd My New Dialog Box raram 8 a Preferences Yes No Teheel amp 4 7 w File Edit Format View Special Graphics My New Dialog Box Tag Name L Fj W 8 Dialog 1of1 100 z Z Al a Windows view of the dialog box FIGURE 10 4 Different views of the same dialog box in a UNIX version of FrameMaker Saving dialog box information When you save a Frame DRE file all the dialog box information is saved in text format in the special DRE syntax Some versions of FrameMaker also creates platform specific resource files for the current version you are using e If you are using the Windows version FrameMaker writes out a Windows dialog resource file dlg and an extra dialog information file xdi The files use the same base name as the DRE file for example if your DRE file is named mydialog dre FrameMaker writ
123. dataType FTI_VarBegin dataType FTI_String dataType FTI_VarEnd idata FO_Var ID sdata December 10 1992 idata FO_Var ID FIGURE 14 28 A variable instance and the text items that represent it FDK Programmer s Guide Frame Document Architecture 14 The following table lists some of the properties of the FO_Var object specified by FTI_VarBegin and FTI_VarEnd in Figure 14 28 Property Type Value FP_VarFmt F_ObjHandleT ID of the FO_VarFmt object that represents the Creation Date Long variable format FP_NextVarInDoc F_ObjHandleT ID of the next FO_Var object in the document Footnotes A footnote is a type of special text column that appears at the bottom of a page What the user sees A footnote reference or anchor appears in the main text as a number letter or special character A footnote is visually separated from the main text by a separator usually a horizontal line The Footnote Properties dialog box allows you to change characteristics that apply to all the footnotes in a document such as the type of numbering or special characters used to represent the anchor and the height of the footnote column How the API represents footnotes When the user chooses the Footnote command the FrameMaker product inserts a footnote anchor It also creates a text frame with invisible borders at the bottom of the text frame in which the footnote was inserted The user types the footnote text into the footnote text fra
124. each element s child elements For example the following function prints the IDs of all the direct children of a specified element VoidT traverseElement F_ObjHandleT docId F_ObjHandleT elementId StringT name if elementId elementId F_ApiGetId docId elementId FP_FirstChildElement while elementId F_Printf NULL StringT Element ID is 0x x n elementId traverseElement docId elementId elementId F_ApiGetId docId elementId FDK Programmer s Guide 105 aes Getting and Setting Properties 106 FP_NextSiblingElement Manipulating format change list properties Most object types in the FDK have a single list of properties that applies to all objects of that type For example if you call F_ApiGetProps forany FO_Pgf object in a document it will always return the same list of properties The values of the properties may be different for each paragraph but the list of properties will always be the same This is not the case with FO_FmtChangeList objects All FO_FmtChangeList objects have the following common properties e FP_Name e FP_NextFmtChangeListInDoc e FP_PgfCatalogReference However individual FO_FmtChangeList objects can have different sets of additional properties depending on what formatting characteristics they set An FO_FmtChangeList object can have all the properties listed under Format change lists on page 582 of the FDK Programmer s Referen
125. example Shift JIS an encoding for Japanese characters replaces the ASCII characters and with a solid vertical bar and overbar and the Yen symbol respectively Pathnames using the character in a Roman encoding would appear with the Yen symbol in Shift JIS However the pathname would still parse correctly because the character codes are the same For text that must be shared across platforms and encodings it is best to stay within the 7 bit ASCII range Filenames are a good example of text that should follow this rule Also keeping within 7 bit ASCII for tag names paragraph format tags character format tags etc is a good way to ensure a document will be usable on systems that support different languages Encoding schemes There are a number of encoding schemes that map the codes to individual characters Not only are there different encodings for each language but within a language there might be a number of encodings FrameMaker can save and import text in a number of encodings 132 FDK Programmer s Guide Manipulating Asian Text Language Encodings Roman FrameRoman ISOLatin 1 ASCII ANSI Windows Macintosh ASCII Japanese Shift JIS JIS EUC Traditional Chinese Big5 EUC CNS Simplified Chinese GB HZ Korean KSC8 amp Of these encodings FrameMaker uses the following to represent characters internally The following strings are the names Framemaker uses to identify these internal encodings
126. example a single client can contain processes for both import CGM as FrameVector and export Frame Vector as CGM Or a single text file to file filter client can include processes for filtering numerous versions of a given format However each process must be registered with a unique filter name For more information about registering filter clients see Registering filters on page 246 of this manual and the platform guide for the platform of interest Data passed to F_ApiNotify for file to file filters The FrameMaker product calls the client s F_ApiNotify callback with notification set to FA_Note_FilterFileToFile The value for docId is set to e for import filters the ID of the active document if there is one or 0 e for export filters the document to filter or the document containing the graphic to filter The value for sparm points to an F_FilterArgsT structure which you access by casting sparm as follows assuming argp is declared as a pointer to F_FilterArgsT argp F_FilterArgsT sparm F_FilterArgsT is defined as typedef struct F_FilterArgsT ConStringT infile ConStringT outfile ConStringT clname ConStringT informat ConStringT outformat ConStringT binname F_StringsT args reserved for future use currently NULL F_FilterArgsT se As previously stated a file to file filter client can include more than one process but you must register each process separately with
127. f_types h header file G 367 F_UBytesT facets getting G 265 function for G 265 R 9 R 183 to R 184 setting G 265 to R 316 function for G 265 R 9 R 316 to R 317 FA_Init naming convention G xiii R xix FA_Note naming convention G xiii R xix facets client specific G 258 deleting function for R 9 R 86 getting setting functions for G 263 identifying G 272 of imported graphics G 257 to G 259 querying R 183 functions for R 129 R 133 R 183 facilities of the FDE virtual environment G 366 fapi h header file G 8 G 370 R 27 fassert h header file G 378 fcharmap h header file G 382 f codes G 39 G 74 to G 75 G 389 R 101 for common user actions tables G 74 executing G 74 to G 75 function for R 7 R 101 and invisible documents G 98 fcodes h file G 39 FDE Frame Development Environment G x G 365 to G 387 R xvi components of G 365 illustrated G 365 T O channels G 366 initializing G 366 G 375 R 374 FDK Programmer s Reference amp Guide memory handling G 366 as related to API clients illustrated G 365 replacements for C language library functions G 366 G 381 to G 387 specifying filepaths G 375 to G 377 utility libraries G 366 G 381 to G 387 virtual environment G 366 functions G 375 to G 379 See also FDE clients FDE functions FDE clients function for displaying warning messages G 379 R 488 function for exiting G 378 R 374 function for reporting progress in G 379 including header files in G 367 FDE
128. flag FTI_CharPropsChange G 315 R 168 R 688 FTF_STRIKETHROUGH bit flag FTI_CharPropsChange G 315 R 168 R 688 index 69 os Index Reserved Names FTF_TSUME bit flag FTI_CharPropsChange G 315 R 168 R 689 FTF_UNDERLINING bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_VARIATION bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_WEIGHT bit flag FTI_CharPropsChange G 315 R 168 R 688 FTI_CharPropsChange text item type G 314 G 315 G 316 G 317 R 166 R 687 FTI_ElementBegin text item type G 314 R 166 R 687 FTI_ElementEnd text item type G 314 R 166 R 687 FTI_ElemPrefixBegin text item type R 166 FTI_ElemPrefixEnd text item type R 166 FTI_ElemSuffixBegin text item type R 166 FTI_ElemSuffixEnd text item type R 166 FTI_FlowBegin text item type G 313 R 166 R 686 FTI_FlowEnd text item type G 313 R 166 R 686 FTI_FnAnchor text item type G 313 G 327 R 166 R 687 FTI_FrameAnchor text item type G 313 R 166 R 687 FTI_LineBegin text item type G 313 R 166 R 686 FTI_LineEnd text item type G 313 R 166 R 686 FTI_MarkerAnchor text item type G 314 G 319 R 166 R 687 FTI_PageBegin text item type G 313 R 166 R 686 FTI_PageEnd text item type G 313 R 166 R 687 FTI_PgfBegin text item type G 313 R 166 R 686 FTI_PgfEnd text item type G 313 R 166 R 686 FTI_RubiCompositeBegin text item type G 314 R 172 R 687 FTI_RubiCompositeEnd text item type G 314 R 687 FTI_RubiTextBegin text item t
129. format to the set of characters When you apply a character format to a set of characters it overrides the default font setting of the paragraph format If you reapply a Paragraph Catalog format to the paragraph it does not affect the format of the characters that you previously tagged with the character format FrameMaker allows you to create character formats that override only some properties of the text to which they are applied To leave one of the current text properties intact you set the corresponding character format property to As Is The Character Designer indicates the As Is state with the words As Is or a grayed or stippled checkbox You can add character formats to the Character Catalog or modify or delete formats that are already in it How the API represents Character Catalog formats FrameMaker represents each Character Catalog format with an FO_CharFmt object whose properties provide the following information e The name of the character format e Character formatting information such as the font family angle and weight e Whether the character format s formatting overrides the default formatting of the text that the format is applied to e The ID of the next FO_CharFmt object in the document How the API represents fonts FO_Session objects have properties such as FP_FontFamilyNames that provide arrays of the names of the font families variations angles and weights available in the current session These lists
130. format with an FO_PgfFmt object The following table lists some of its properties Property Type Value FP_Name StringT Step FP_AutoNumString StringT lt n gt t FP_AutoNumChar StringT me FP_PgfIsAutoNum IntT True FP_NextPgfFmt InDoc F_ObjHandleT ID of the next Paragraph Catalog format in the document s list of Paragraph Catalog formats The FP_AutoNumChar property specifies the character format to be applied to the string specified by FP_AutoNumString When the default font is used FP_AutoNumChar is set to a null string FDK Programmer s Guide 301 14 Frame Document Architecture How the API organizes Paragraph Catalog formats The API organizes the FO_PgfFmt objects in a document in a linked list The FO_Doc property FP_FirstPgfFmtInDoc specifies the first FO_PgfFmt object in the list FO_PgfFmt objects havean FP_NextPgfFmtInDoc property which specifies the ID of the next FO_PgfFmt object in the list The order of the list does not correspond with the order in which the formats appear in the Paragraph Catalog Paragraphs A paragraph can be a body of text a title or an item in a list What the user sees You can type a paragraph in a text frame a footnote or a table cell Every paragraph has a paragraph format consisting of e A tag which is the name of a format stored in the Paragraph Catalog e Formatting information which is the same information that a Paragraph Catalog
131. generates structure for a document FDK Programmer s Guide Executing Commands with API Functions 4 F_ObjHandleT inputDocId ruleTb1DocId UCharT buf 64 F_Sprintf buf INPUTDOCID Sd inputDocId F_ApiCalliClient StructGen buf F_Sprintf buf RULEDOCID d ruleTblDocId F_ApiCalliClient StructGen buf F_ApiCallClient StructGen OUTPUTDOCNAME tmp mystruct doc F_ApiCallClient StructGen LOGNAME tmp logfile doc F_ApiCalliClient StructGen GenerateDoc Note that all of the documents you specify must be open before you call the structure generator If you are generating structure for a large number of documents you can greatly speed processing by opening the documents invisibly To open a document invisibly set the FS_MakeVisible property of the Open script to False For a complete list of the strings you can pass to the structure generator and other FrameMaker clients see Calling Clients Shipped With FrameMaker on page 699 of the FDK Programmer s Reference FDK Programmer s Guide 79 re Executing Commands with API Functions 80 FDK Programmer s Guide Getting and Setting Properties This chapter describes how to make changes in a FrameMaker product session book or document by getting and setting property values It discusses how to get and set individual properties and entire property lists It also provides
132. getting G 89 G 270 function for R 15 R 185 to R 186 See also IDs of API objects unanchored frames defined G 293 properties of G 295 R 608 uncompressing files G 42 undefined attributes G 348 Undo command Graphics menu G 192 unions for sets of property values R 690 unique identifiers See UIDs unique IDs unique object names G 269 UNIX pathnames conventions used in this manual G xiv R xx UNIX pathnames See filepaths pathnames FDK Programmer s Reference amp Guide UNIX platforms capturing screenshots of dialog boxes G 206 compiling and running FDE filters G 374 dialog boxes on G 180 to G 181 G 189 to G 190 G 207 disabling clients G 16 image pop up menus G 200 memory management on G 378 to G 379 registering clients with the FrameMaker product G 8 G 12 saving DRE files G 204 take control initialization G 15 See also filepaths unnamed objects G 270 unstraddling cells G 75 to G 79 G 337 to G 338 function for R 22 R 336 to R 337 illustrated G 338 Update status of books checking G 359 to G 360 updateParamsp property lists creating with F_ApiGetUpdateBookDefaultParams G 3 57 to G 358 from scratch G 359 updateReturnParamspp property lists G 359 updating cross references R 343 documents and books G 70 to G 74 functions for G 77 R 7 objects and properties automatically G 81 G 160 variables R 342 user actions common tables G 74 in dialog boxes handling G 221 to G 227 user input simulating G
133. hypertext marker that contains a message apiclient hypertext command How clients work with FrameMaker Clients use different mechanisms to work with FrameMaker on the different platforms the FDK supports On the Macintosh clients are dynamically loaded modules On Windows they are dynamic link libraries DLLs or they can be executable programs that use COM to communicate with a FrameMaker session On UNIX platforms they can be either dynamically 4 FDK Programmer s Guide Introduction to the Frame API aa linked code or separate processes that use the RPC mechanism to communicate with the FrameMaker product A client does not need to be aware of the low level details of integrating with FrameMaker because the API provides high level functions that are the same on all platforms When the user starts FrameMaker it sends an initialization call to each registered client Clients can take control immediately or they can request the FrameMaker product to notify them of specific events and wait for those events to occur Special types of clients In addition to conventional clients that take control of a FrameMaker product session in response to user actions the API allows you to create three special types of clients document reports filters and take control clients Document reports A document report is a client that provides detailed information about a document The user can start a document report by choosing Utilities gt Docum
134. if it is compressed check it out if it is under version control or perform other operations that may change its type 3 Checks the file s type If the file is a type that the FrameMaker product can t open the FrameMaker product displays a warning and cancels the Open operation If the file is from a previous version of a FrameMaker product it prompts the user to convert the file or cancel the Open operation 4 Issues an FA_Note_PostFileType notification to all clients that have requested it 5 Determines whether the file is a document or a book and whether its format is Frame binary or MIF 6 Issues an FA_Note_PreOpenDoc FA_Note_PreOpenBook FA_Note_PreOpenMIF or FA_Note_PreOpenBookMIF notification 7 Opens the document or book If the document or book is MIF the FrameMaker product converts it 8 Issues an FA_Note_PostOpenDoc FA_Note_PostOpenMIF FA_Note_PostOpenBook or FA_Note_PostOpenBookMIF notification Normally you don t request the FA_Note_PreFileType and FA_Note_PostFileType notifications because you don t want to do anything with a file before the FrameMaker product has checked its type However if you want to change a file s contents after the user has FDK Programmer s Guide 41 a Creating Your Client s User Interface 42 selected it but before the FrameMaker product has checked its type you should request notification for the FA_Note_PreFileType notification point For example su
135. image pop up menu The text box gets stuffed Body Ma The selected item from the with the value selected pop up menu is stuffed from the pop up menu into the text box FIGURE 10 18 Related dialog items A text box can also be related to a radio button If a radio button s stuff item is a text box turning on the radio button moves focus to the text box If the stuff item for a text box is a radio button typing in the text box automatically turns on the radio button To specify the stuff item for a dialog item follow these steps FDK Programmer s Guide 203 a Creating Custom Dialog Boxes for Your Client 204 1 In the DRE file select the item For example if you want a text box to be the stuff item for an image pop up menu select the image pop up menu first The order in which you select the items is important 2 Select the item which will be the stuff item of the first item 3 To identify the second item you selected as the stuff item for the first item you selected press Esc d f FrameMaker automatically deselects the second item The first item remains selected and the status bar displays information about this item The item number of the second item is displayed in parentheses indicating that the second item is the stuff item for the first item For example suppose you select an image pop up menu item 18 first then you select a text box item 17 Then you use the keyb
136. into FrameMaker and control the export of FrameMaker documents to markup XML or SGML Other FrameMaker features for developers MIF fmbatch FrameMaker provides other advanced features that are useful for developers You do not need the FDK to use these features Maker Interchange Format MIF is an easily parsed ASCII format that describes a document s text graphics formatting and layout FrameMaker can save a document or a book to a MIF file and convert a MIF file back to a document or book without losing any information You can write applications or scripts that convert a MIF file to the format of another desktop publishing package or convert other formats to MIF Here are some examples of things you can use MIF for e Sharing files with earlier releases of FrameMaker products e Converting database files into Frame documents e Filtering word processor documents into Frame documents You can find documentation for MIF in the online manuals folder for your FrameMaker installation The fmbatch utility is shipped with UNIX versions of FrameMaker It allows you to open print reformat and save FrameMaker product files without displaying them You can use fmbatch directly at a UNIX graphics workstation or in a remote shell from a nongraphics terminal The fmbatch utility provides interactive and batch modes When you use it in batch FDK Programmer s Guide Using Frame Developer Tools a mode you can execute op
137. its ID is to call F_ApiGetNamedOb ject For example the following code gets the IDs of the FrameMaker main menu bar and the File menu FDK Programmer s Guide 163 i Manipulating Commands and Menus with the API 164 F_ObjHandleT fileMenulId mainMenuBarId mainMenuBarlId F_ApiGetNamedObject FV_SessionId FO_Menu MakerMainMenu fileMenuId F_ApiGetNamedObject FV_SessionId FO_Menu FileMenu If a menu or command with the specified name doesn t exist F_ApiGetNamedOb ject returns 0 If you don t know a command s name there are several lists of objects you can traverse to get its ID e If you know the command is on a particular menu traverse the list of menu items on the menu e If you know the command is on a menu but you don t know which menu traverse the list of menu items in the session e Ifthe command isn t on any menu traverse the list of commands in the FrameMaker product session Because there are so many FrameMaker product commands traversing all of them can be slow If acommand is a menu item get its ID by traversing the list of menu items on a menu or in a session instead of traversing the list of commands in the session For example if you don t know a menu item s name but you know that its label is Database you can use the following code to get its ID F_ObjHandleT itemId StringT itemName itemId F_ApiGetId 0 FV_SessionId FP_FirstMenulItemInSession while item
138. list The order of the list does not correspond to the order in which the formats appear in the Character Catalog Condition Formats FrameMaker provides condition formats that allow the user to selectively show or hide text in a document FDK Programmer s Guide 309 14 Frame Document Architecture 310 What the user sees To selectively show and hide text you create a condition format or tag and apply it to selections of text For example you can create a condition tag named Comment and apply it to all the comments you add to a document You can then instruct the FrameMaker product to hide all the text with the Comment tag when you print a final draft of the document A document can have multiple condition tags FrameMaker allows you to specify a format override or a special style and color for a condition For example you can make all text tagged with the Comment condition underlined and red How the API represents condition formats The API represents each condition format with an FO_CondFmt object whose properties provide the following information e The condition name e Whether text tagged with the condition is currently visible e The format overrides e The ID of the next condition format in the document The API represents the condition setting of a location in text as a text property For more information on text properties see How the API represents text on page 312 If you choose to hide a condition
139. list by calling F_ApiGet ImportDefaultParams or you can create a list from scratch For a description of the default list returned by F_ApiGet ImportDefaultParams see F_ApiGetImportDefaultParams on page 120 of the FDK Programmer s Reference For information on creating a property list from scratch see Creating an openParamsp script from scratch on page 50 in this manual 3 Call F_ApilImport FDK Programmer s Guide 231 12 Using Imported Files and Insets 232 4 Check the Import status Use F_ApiCheckStatus to check the returned values in the importReturnParamspp list for information about how the FrameMaker product imported the file 5 Deallocate memory for the importParamsp and importReturnParamspp property lists Use F_ApiDeallocatePropVals to deallocate memory for the lists The following sections provide examples of how to import several specific types of files Importing the main flow of a Frame document file The following code imports the main flow of a Frame document file by reference It uses the formatting from the source document for the imported text If the imported file isn t a FrameMaker product document file it displays an alert F_PropValsT params returnParamsp NULL F_ObjHandleT doclId F_TextRangeT tr IntT i Get default import list Return if it can t be allocated params F_ApiGetImportDefaultParams if params len 0 return Ge
140. memory for the property list use the API convenience function F_ApiAllocatePropVals The syntax for F_ApiAllocatePropVals is F_PropValsT F_ApiAllocatePropVals IntT numProps This argument Means numProps The number of properties for which to allocate memory For example the following code creates an openParamsp property list that instructs F_ApiOpen to show the Open dialog box F_ObjHandleT docId F_PropValsT params returnParamsp NULL Allocate memory for the list params F_ApiAllocatePropVals 1 Set up the FS_ShowBrowser property and set it to True params val 0 propIdent num FS_ShowBrowser params val 0 propVal valType FT_Integer params val 0 propVal u ival True 50 FDK Programmer s Guide Executing Commands with API Functions 4 docId F_ApiOpen amp params amp returnParamsp F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp The API allocates memory for the property list created by F_ApiAllocatePropVals Use F_ApiDeallocatePropVals to free the property list when you are done with it Checking the Open status F_ApiOpen stores a pointer to a property list F_PropValsT structure in openReturnParamspp To get the name of the file that F_ApiOpen opened and other information about how F_ApiOpen opened the file check this property list It includes the properties shown in the following table P
141. menus You can t use the F_ApiDefineAndAddCommand function discussed in Defining commands and adding them to menus on page 26 to add a command to multiple menus Instead you must use F_ApiDefineCommand to create the command and F_ApiAddCommandToMenu to add it to the menus The syntax for F_ApiDefineCommand is F_ObjHandleT F_ApiDefineCommand IntT cmd StringT tag StringT label StringT shortcut This argument Means cmd The integer that the FrameMaker product passes to your client s F_ApiCommand function when the user chooses the menu item or types the keyboard shortcut for the command tag A unique name to identify the command label The title of the command as it appears on the menu shortcut The keyboard shortcut sequence The syntax for F_ApiAddCommandToMenu is IntT F_ApiAddCommandToMenu F_ObjHandleT toMenuld F_ObjHandleT cmdId This argument Means toMenuld The menu to which to add the command cmdId The ID of the command 166 FDK Programmer s Guide Manipulating Commands and Menus with the API 9 For example the following code creates a command named Grammar and adds it to the Edit and Utilities menus define GRAMMAR CMD 1 F_ObjHandleT editMenulId utilsMenulId grammarCmdId editMenuld F_ApiGetNamedObject FV_SessionId FO Menu EditMenu utilsMenulId F_ApiGetNamedObject FV_SessionId FO_Menu UtilitiesMenu g
142. number of header rows in the table To use the default number of header rows from the Table Catalog format specify 1 numFooterRows The number of footer rows in the table To use the default number of footer rows from the Table Catalog format specify 1 textLocp The location at which to insert the new table The location can t be within a footnote or a table If successful F_ApiNewTable returns the ID of the new FO_Tb1 object Otherwise it returns 0 and sets FA_errno to an error code Example The following code inserts the table shown in Figure 8 3 F_ObjHandleT docId pgfId tblid titlePgfId F_TextRangeT tr F_TextLocT textLoc Get the insertion point docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection if tr beg objId return Insert the table at the insertion point tblIid F_ApiNewTable docId NULL 3 3 0 0 amp tr beg Return if IP in FO_Tbl or FO_Fn and table wasn t created if tblId return FDK Programmer s Guide 155 az Creating and Deleting API Objects Get ID of paragraph in table s title titlePgfId F_ApiGetId docId tblid FP_FirstPgf Put some text in the table s title textLoc objiId textLoc offset 0 titlePgfId F_ApiAddText docId amp textLoc My Table Figure 8 3 Table created with F_ApiNewTable For an example of how to
143. objId specifies a flow text frame or table cell ID parentId should specify the ID of the document that contains it objid The ID of the object whose property you want to get or set To get or set the insertion point or text selection in a document specify the document s ID propNum The property to get or set To get or set the insertion point or text selection ina document set propNum to FP_TextSelection setVal The text range to which to set the property The beg objId and end objid fields of the F_TextRangeT structure returned by F_ApiGetTextRange always specify paragraph or text line IDs The beg objId and end objid fields of the F_TextRangeT structure that you pass to F_ApiSetTextRange can specify paragraph or text line IDs but they can also specify flow footnote subcolumn table cell or text frame IDs For example to set the insertion point at the beginning of the first paragraph on the page shown in Figure 6 1 you can use the following code F_ObjHandleT docId pgfId F_TextRangeT tr Get document and paragraph IDs here Create text range that specifies an insertion point tr beg objId tr end objId pgfId tr beg offset tr end offset 0 Set document s insertion point F_ApiSetTextRange FV_SessionId docId FP_TextSelection amp tr Instead of setting tr beg objId and tr end objid to the ID of the first paragraph you can set them to the ID of the A flow the text frame
144. objects object types text objects and individual types of objects offset value F_TextItemT structure G 312 OK buttons of dialog boxes G 196 displaying G 18 online help See context sensitive help Open dialog box R 326 displaying G 21 to G 22 R 53 to R 56 index 22 Open operation notification in G 41 to G 42 Open script property lists See openParamsp property lists Open status of files checking G 51 to G 52 printing the values of G 52 See also status flags opening channels G 377 R 353 documents and books G 46 to G 53 R 2 R 238 to R 244 R 326 files G 41 to G 42 openParamsp property lists allocating memory for G 50 to G 51 creating with F_ApiGetOpenDefaultParams G 49 to G 50 from scratch G 50 to G 51 deallocating memory for G 52 to G 53 P page backgrounds G 289 page frames G 147 G 290 API representation of G 290 defined G 290 G 390 deleting R 84 page properties See document properties page range printing R 148 pages G 280 G 288 to G 292 API representation of G 280 G 289 to G 290 API representation of the beginning of G 313 R 166 R 686 API representation of the end of G 313 R 166 R 687 applying page s layout to another page R 47 backgrounds of G 289 current G 291 displaying particular G 99 document lists of G 284 document properties for G 284 R 559 to R 561 hidden G 289 G 292 G 318 G 390 properties of G 290 R 611 master G 289 properties of G 290 G 291 to G 292 R 612 FDK
145. of a line specify whether the line end is a regular hyphenated or hard line end e An anchor for a table footnote marker cross reference variable or anchored frame The API represents tables footnotes markers cross references variables and anchored frames with separate objects It uses a text item to represent the anchor for each of these entities The text item specifies the ID of the object For example the API represents a table with an FO_Tb1 object It uses a table anchor FTI_Tb1lAnchor text item to indicate where the table occurs in the text e A text properties change This type of text item identifies the point in text at which the text properties change It specifies flags that indicate which text properties differ from the properties of the text immediately preceding the text item FDK Programmer s Guide Frame Document Architecture 14 The following table lists the values the F_TextItemT dataType field can have and the types of data the corresponding text item provides Text item type dataType FTI_TextObjId FTI_String FTI_LineBegin FTI_LineEnd FTI_PgfBegin FTI_PgfEnd FTI_FlowBegin FTI_FlowEnd FTI_PageBegin FTI_PageEnd FTI_TextFrameBegin FTI_TextFrameEnd FTI_SubColBegin FTI_SubColEnd FTI_FrameAnchor FTI_FnAnchor FTI_TblAnchor What the text item represents The object to which the offsets of all the text items are
146. of R 628 FDK Programmer s Reference amp Guide Index Subjects a tag properties of R 629 word spacing properties of R 629 See also Paragraph Catalog formats paragraph properties paragraphs FO_Pef paragraph numbering function for restarting R 7 R 267 paragraph properties G 102 G 302 to G 303 R 613 to R 621 applying to Paragraph Catalog formats G 102 to G 103 getting and setting G 102 to G 105 illustrated G 305 See also paragraph formats FO_PgfFmt paragraphs FO_Pgf paragraph reference frame properties FO_Pgf R 620 paragraphs FO_Pgf G 280 G 302 to G 305 adding text to function for R 23 adding to documents G 149 to G 150 function for R 220 to R 221 API representation of G 280 G 302 to G 305 API representation of the beginning of G 313 R 166 R 686 API representation of the end of G 313 R 166 R 686 Asian character spacing properties of R 613 autonumbering properties of R 613 to R 614 changing the formats of G 302 to G 305 general properties of R 617 getting in order G 86 hyphenation properties of R 617 to R 618 identifier properties of R 618 indentation properties of R 619 language properties of R 618 line spacing property of R 619 object pointer properties of R 620 as organized in documents G 304 to G 305 as organized in flows G 304 illustrated G 305 placement properties of R 619 to R 620 restarting numbering function for R 7 R 267 spell checking property of R 618 tab properties of R 16 R 621 table
147. of a menu set its FP_PrevMenuItemInMenu property to 0 To move it to the bottom of a menu set its FP_NextMenulItemInMenu property to 0 The following code moves the Copy menu item to the top of the Edit menu F_ObjHandleT copyCmdiId editMenuld editMenuld F_ApiGetNamedObject FV_SessionId FO Menu EditMenu copyCmdId F_ApiGetNamedObject FV_SessionId FO_Command Copy F_ApiSetId editMenuld copyCmdId FP_PrevMenuItemInMenu 0 If a menu is on a menu bar setting its FP_PrevMenuItemInMenu property to 0 moves it to the leftmost position on the menu bar setting its FP_NextMenuItemInMenu property to 0 moves it to the rightmost position You can t move a menu or menu item to another menu by setting its FP_NextMenuItemInMenu or FP_PrevMenuItemInMenu properties Instead you must delete it and then add it to the menu on which you want it to appear For example the following code moves the Font menu from the Format menu to the main menu bar F_ObjHandleT formatMenulId fontMenulId mainMenuBarId FDK Programmer s Guide Manipulating Commands and Menus with the API 9 Delete instance of Font menu on the Format menu F_ApiDelete formatMenuld fontMenulId F_ApiAddMenuToMenu mainMenuBarlId fontMenuld Changing the menu set The user can switch to a menu set by choosing the menu set from View gt Menus Your client can switch menu sets programmatically by setting the session s FP_Current
148. on multiple menus you will normally need only the predefined separators If you need additional separators you can create them with F_ApiNewNamedOb ject as follows F_ObjHandleT separatorId separatoriId F_ApiNewNamedOb ject FV_SessionId FO_MenulItemSeparator MySeparator Getting and setting menu item labels Most FrameMaker product menu items have only one label For example the label of the Cut command is always Cut However some menu items have different labels for different contexts For example the label of the TableConvert command is Convert to Table when paragraph text is selected but Convert to Paragraphs when the insertion point is ina table or table cells are selected The FP_Labels property specifies the labels a menu item can have in different contexts If a menu item has one label for all contexts its FP_Labels property specifies only that label Otherwise its FP_Labels property specifies pairs of strings with the following format FDK Programmer s Guide Manipulating Commands and Menus with the API 9 context label where context specifies a context and label specifies the menu item label that appears when that context is applicable The following table lists some of the values context can have Context value When the label is displayed Book When a book is active Document When a document is active Long When a menu item is on a pull down menu or the document pop up menu oTable When text
149. only file named my txt F_ApiSave mydocId tmp my txt amp params amp returnParamsp Deallocate property lists F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp The API allocates memory for the property list created by F_ApiGetSaveDefaultParams Use F_ApiDeallocatePropVals to free the property list when you are done with it Creating a saveParamsp script from scratch If you want to specify only a few properties when you call F_ApiSave it is most efficient to create a property list from scratch To create the property list you must allocate memory for it and then set up the individual properties Use the API convenience function F_ApiAllocatePropVals to allocate memory for the property list For example the following code createsa saveParamsp property list that instructs F_ApiSave to save a file as text only F_PropValsT params returnParamsp NULL F_ObjHandleT mydoclId Get the ID of the active document mydocId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Allocate memory for the list params F_ApiAllocatePropVals 1 Set up the FS_FileType property and set it to True params val 0 propIdent num FS_FileType params val 0 propVal valType FT_Integer params val 0 propVal u ival FV_SaveFmtText F_ApiSave mydocId tmp my txt amp params amp returnParamsp Checking Save status F_ApiSave sto
150. property FO_Doc R 547 R 578 FP_DocOpenType property FO_Doc R 547 FP_DocSaveType property FO_Doc R 547 FP_DontUpdateTextInsets property FO_Doc R 547 FP_DontUpdateXRefs property FO_Doc R 547 index 49 os Index Reserved Names FP_DoubleClick property FO_DialogResource G 221 R 531 FP_DoubleClick property FO_DIgScrollBox R 536 FP_DTheta property FO_Arc R 598 FP_ElementCatalog property FO_Book R 503 FP_ElementCatalog property FO_Doc R 566 FP_ElementCatalogDisplay property FO_Book R 504 FP_ElementCatalogDisplay property FO_Doc R 566 FP_ElementDef property FO_Element R 642 FP_ElementDef property FO_FmtRule G 345 R 590 FP_ElementDefType property FO_ElementDef R 646 FP_ElementInCatalog property FO_ElementDef G 344 R 646 FP_ElementIsCollapsed property FO_Element R 638 FP_ElementIsExcludedInContext property FO_Element R 644 FP_ElementIsInvalidInParent property FO_Element G 348 R 644 FP_ElementlIsInvalidInPosition property FO_Element R 644 FP_ElementIsUndefined property FO_Element R 643 FP_ElementPegf property FO_ElementDef R 646 FP_ElementPgfFormat property FO_ElementDef G 344 FP_ElementSelection property G 287 FP_ElementSelection property FO_Book R 504 FP_ElementSelection property FO_Doc R 565 FP_ElementType property FO_Element R 639 FP_ElemPrefixSuffix property FO_FmtRuleClause R 591 FP_EnabledWhen property FO_Command G 174 R 524 table of values
151. relative A string of characters with the same condition and character format The beginning of a line The end of a line and the line end type The beginning of a paragraph The end of a paragraph The beginning of a flow The end of a flow The beginning of a page The end of a page The beginning of a text frame The end of a text frame The beginning of a column The end of a column An anchored frame A footnote A table Text item data ID ofan FO_Pgf FO_Cell FO_TextLine FO_TiApiClient FO_TiFlow FO_TiText or FO_TiTextTable A character string Nothing If the line end is a normal line end 0 if it is a forced line end the FTI_HardLineEnd flag is set if it is a hyphen line end the FTI_HyphenLineEnd flag is set ID ofan FO_Pgf ID of an FO_Pgf ID of an FO Flow ID of an FO_Flow ID of an FO_BodyPage FO_HiddenPage FO_MasterPage FO_RefPage ID of an FO_BodyPage FO_HiddenPage FO_MasterPage FO_RefPage ID of an FO_TextFrame ID of an FO_TextFrame ID of an FO_SubCol ID of an FO_SubCol ID of an FO_AFrame ID ofan FO_Fn ID of an FO_Tb1l FDK Programmer s Guide 313 14 Frame Document Architecture Text item type dataType FI FI I_MarkerAnchor I_XRefBegin Hy FI I_XRefEnd I_VarBegin I_VarEnd FI I_TextInsetBegin FTI_TextInsetEnd I_ElementBegin T_ElementEnd I_ElemPrefixBegin T_ElemPr
152. s file the FrameMaker product will alert the user that no file exists to match the component name When you insert a new book component you should assign a document to it For more information on F_ApiNewSeriesOb ject see Creating series objects on page 149 The following code creates an untitled book with one component that represents a newly created custom document file After the code successfully saves the new document it creates a book component and assigns the document name to the new component FDK Programmer s Guide 355 me Frame Book Architecture define in MetricT 65536 72 VoidT F_ApiCommand command IntT command F_ObjHandleT bookId docId compId StringT s F_ApiBailOut bookId F_ApiNewNamedOb ject FV_SessionIid FO Book StringT First create an 8 5 x 11 custom document docId F_ApiCustomDoc F_MetricFractMul in 17 2 11 in 1 F_MetricFractMul in 1 4 in in in in FF_Custom SingleSided True Save the doc prompting for filename F_ApiSimpleSave docId StringT True If file has name make a component s F_ApiGetString FV_SessionId docId FP_Name if F_StrLen s compId F_ApiNewSeriesObject bookId FO_BookComponent 0 F_ApiSetString bookId compId FP_Name s F_ApiDeallocateString amp s Updating a book After making changes in the documents or components of a book your client must update the book to ensure all refe
153. second parameter to the name of the dialog box F_ApiOpenResource returns the dialog resource s ID Add code to initialize items in the dialog box A dialog resource does not provide default settings or values for many types of dialog items For example scroll lists pop up menus and image pop up menus are empty when you first open the dialog resource If you want any items to have default settings call F_ApiSetPropertyType functions to provide them after you call F_ApiOpenResource but before you display the dialog box Add code to display the dialog box To display a modal dialog box call F_ApiModalDialog To display a modeless dialog box call F_ApiModelessDialog Add code to update the dialog box If the dialog box is modeless you may want to update it when the user changes things in the FrameMaker product session For example if the dialog box displays a scroll list of all the open documents in a FrameMaker product session you may want to update the list whenever the user opens or closes a document To update a dialog box turn on notifications such as FA_Note_BackToUser and FA_Note_PostFunction Then add code to your client s F_ApiNotify callback to set item properties when it receives these notifications Add code to respond to user actions in the dialog box How you handle user actions in a dialog box depends on how you display the dialog box If you display it as a modeless dialog box you
154. should add a callback function named F_ApiDialogEvent to your client The FrameMaker product attempts to call this function whenever the user manipulates the dialog box Your client s F_ApiDialogEvent function can call API functions to get or set the properties of items in the dialog box It can also get and set the properties of other objects in the session and call functions to execute operations such as opening and closing documents If you display a dialog box as a modal dialog box you can instruct the API to call F_ApiDialogEvent for each dialog event just as it would for a modeless dialog box or you can wait until the dialog box is closed and then check the properties of the dialog s items to determine what the user changed FDK Programmer s Guide Handling Custom Dialog Box Events uo 6 Add code to respond to the user closing the dialog box The user can close a dialog box by clicking its close box on the Macintosh pressing Control w on Windows platforms or pressing Control c on UNIX platforms When the user closes the dialog box the FrameMaker product calls your client s F_ApiDialogEvent function Your client may need to conduct some special processing in response to this call For example it may need to turn off notifications that it uses for updating the dialog box The following sections discuss these steps in greater detail A simple example The following client implements a custom dialog
155. some of the object s properties and their values Property Data type Value FP_Name StringT Heading FP_KeepWithNext IntT True FP_LeftIndent MetricT 1 in The property list for the FO_PgfFmt object and the properties in the previous table are represented graphically in Figure 13 1 FO_PgfFmt objects have many other properties that are not shown in the illustration FDK Programmer s Guide 273 13 Frame Session Architecture 274 F_PropValsT len 3 val val 0 val 1 val 2 propldent propldent propldent num FP_Name num FP_KeepWithNext num FP_LeftIndent name NULL name NULL name NULL propVal propVal propVal valType FT_String valType FT_Integer valType FT_Metric u u u sval Heading ival True ival 1 in FIGURE 13 1 Some FO_PgfFmt properties FrameMaker product sessions The fundamental entity in Frame architecture is a session Each instance of a FrameMaker product that the user starts is a session FrameMaker allows the user to have many open documents and books in a session Of the open documents and books in a session only one document or book is active at a time An open document or book is active if it has the input focus How the API represents sessions The API represents each FrameMaker product session with an FO_Session object whose p
156. some tips for getting and setting the properties of specific types of objects What you can do with object properties In the FrameMaker product user interface the user can change an object in a variety of ways For example the user can change the size and fill pattern of a graphic object or the starting page number of a book component Each API object has a property list a set of properties describing its attributes Your API client can do anything a user can do to an object by getting and setting the properties in the object s property list For example your client can set properties to e Change a graphic object s size fill pattern or position in the back to front order e Make a document or book active e Change a book component s position in a book e Change a paragraph s format Your client can also change properties that the user doesn t have access to For example your client can set properties to e Make a document or book visible or invisible e Keep the FrameMaker product from reformatting a document every time a change is made The API ensures that your client doesn t corrupt a document by setting properties to illegal values When you change a property the API also automatically changes other properties as needed to preserve the integrity of the document or book There are a number of read only properties that you can get but not set For a complete list of object properties and their possible values see Ch
157. specify measurements such as tab offsets and font sizes MIF also uses itin lt MathFullForm gt statements MetricT values should not be confused with the metric system For more information on metric values see MetricT values on page 675 of the FDK Programmer s Reference The metric library provides a set of operations that allow you to manipulate metric values without converting them to other units of measurement For example F_MetricFloat converts areal number to a metric number F_MetricFractMul multiplies a metric number by a fraction and F_MetricToFloat converts a metric number to a real number All the functions in the metric library are prefixed with F_Met ric To use the FDE metric functions you must include fdetypes h and fmetrics h in your program MIF data structures and macros The FDE provides data structures that represent the statements described in the online manual MIF Reference It also provides convenience macros that help you get and set fields in these structures This saves you the effort of developing your own data structures and macros For the location of the files containing the MIF data structures and macros see the FDK Platform Guide for your platform MIF data structures adhere to the following naming conventions e Structure names contain the prefix Mif the statement name and the suffix Struct For example the FDE represents the lt TextFlow gt statement with the MifTextFlo
158. successful it returns the ID of the FO_Doc or FO_Book object that represents the document or book that it opened If a condition such as a nonexistent file makes it impossible to open a file F_ApiSimpleOpen aborts the operation and returns 0 If you set interactive to True the FrameMaker product displays the Open dialog box It uses the path specified by the session property FP_OpenDir as the default path The FrameMaker product also displays all the other messages and warnings it would normally display if the user chose the Open command For example if a document contains fonts that are not available in the current session the FrameMaker product displays a Fonts Unavailable Open Anyway dialog box If the user clicks Cancel F_ApiSimpleOpen aborts the operation and returns 0 If you set interactive to False the FrameMaker product does not display the Open dialog box or other messages and warnings If it is necessary to modify a file to continue opening it F_ApiSimpleOpen aborts the operation without notifying the user and returns 0 For example if a document contains fonts that are not available F_ApiSimpleOpen aborts the Open operation instead of converting the fonts Example The following code opens a document named tmp my doc and displays its ID include futils h F_ObjHandleT doclId UCharT msg 256 docId F_ApiSimpleOpen StringT tmp my doc False if docId F_ApiAlert StringT
159. such as a paragraph tag or a format change list e The formatting tag or name subformat rule or change list the rule clause uses to specify the element s formatting e The circumstances under which the rule clause applies if it is in a context rule the context if it is in a level rule the level e The context label For example the element definition shown in Figure 14 35 on page 343 includes a single format rule The following table lists some of the properties of that format rule Property Type Value FP_ElementDef F_ObjHandleT ID of the FO_ElementDef object that contains the format rule FP_FmtRuleClauses F_IntsT The IDs of the format rule clauses in the format rule For a list of the rule clause s properties see the table below FP_FmtRuleType IntT FV_CONTEXT_RULE FDK Programmer s Guide 345 14 Frame Document Architecture The F_IntsT structure specified by the FO_FmtRule object s FP_FmtRuleClauses property provides an array which includes the IDs of two format rule clauses The following table lists some of the properties of the first format rule clause Property Type Value FP_ContextLabel StringT BulletList FP_FmtChangeList F_ObjHandleT The ID of the format change list FO_FmtChangeList object that is applied to the element when the specified context is valid For a list of the change list s properties see How the API represents format change lists on page 346 F
160. table lists the properties you query to get the ID of an object s containing element Object Property that returns ID of containing element FO_Marker FP_Element FO_Fn FO_XRef FO_Var FO_AFrame FO_Row FO_Cell FO_Tb1 FP_TblElement FP_Tb1TitleElement FP_TblHeaderElement FP_Tb1BodyElement FP_Tb1FooterElement a If a table has a title or different types of rows it can comprise several elements To determine the ID of the object an element contains you query the element s FP_Object property FDK Programmer s Guide 109 aes Getting and Setting Properties Specifying client data for an element The FO_Element property FP_UserString allows your client to store its own data with individual structural elements The FP_UserString property is persistent between sessions after a client sets it it remains the same until a client resets it If an element is cut and pasted it retains its FP_UserString property If an element is copied and pasted both the original element and the pasted element retain the FP_UserString property Improving performance in FrameMaker clients If you are using the API to create FrameMaker documents you may need to add a large number of elements or element definitions at a time By default FrameMaker validates elements and applies format rules each time you add an element or element definition This can decrease performance considerably To k
161. text settings FF_UFF_DOCUMENT_PROPS Import document properties FF_UFF_FONT Import Character Catalog formats FF_UFF_MATH Import equation settings FF_UFF_PAGE Import page layouts FF_UFF_PGF Import Paragraph Catalog formats FF_UFF_REFPAGE Import reference pages FF_UFF_TABLE Import Table Catalog formats FDK Programmer s Guide Executing Commands with API Functions 4 This value Means FF_UFF_VAR Import variable formats FF_UFF_XREF Import cross reference formats FF_UFF_REMOVE_EXCEPTIONS Remove exception formats from target documents FF_UFF_REMOVE_PAGE_BREAKS Remove all forced page breaks from target documents Executing other updating and formatting commands The API provides several functions that allow you to execute FrameMaker product commands that update and reformat entire documents The syntax for the functions is IntT F_ApiClearAllChangebars F_ObjHandleT docId IntT F_ApiRehyphenate F_ObjHandleT doclId IntT F_ApiResetReferenceFrames F_ObjHandleT docId IntT F_ApiResetEgqnSettings F_ObjHandleT doclId IntT F_ApiRestartPgfNumbering F_ObjHandleT doclId IntT F_ApiUpdateVariables F_ObjHandleT docId IntT F_ApiUpdateXRefs F_ObjHandleT doclId IntT updateXRefFlags This argument Means docId ID of the document to update or reformat These functions behave like the corresponding commands in the user interface They are useful for clients t
162. that allow you to manipulate filepaths For example F_DeleteFile deletes a file or directory F_FilePathProperty checks file permissions and F_FilePathGetNext allows you to traverse all the files in a directory These functions are platform independent substitutes for functions such as remove _access and _fstat Making I O portable with channels To make your client s I O portable you use channels Channels are an abstraction of platform specific files or file systems The FDE provides functions to manipulate channels For example F_ChannelOpen opens a channel F_ChannelRead reads from a channel F_ChannelWrite writes to a channel and F_ChannelClose closes a channel These functions are substitutes for platform specific functions such as fopen fread fwrite and fclose All I O channels in the FDE are buffered internally To manipulate a file with FDE channel functions you must first convert the file s pathname to a filepath and then open the filepath with F_ChannelOpen For example the following code opens the file Macintosh HD myfile for reading FDK Programmer s Guide 377 Making I O and Memory Calls Portable ChannelT chan FilePathT path path F_PathNameToFilePath StringT Macintosh HD myfile NULL FMacPath if chan F_ChannelOpen path r NULL F_Printf NULL Couldn t open file n return Assertion handler functions Your client can reg
163. that is not a table or text line is selected oText When the insertion point is in a table cell or one or more table cells are selected Short When a menu item is on a pull right menu or one of the formatting bar menus For example the strings specified by the FP_Labels property of the TableConvert command are ToTable Convert to Table ToText Convert to Paragraphs Setting the labels of FrameMaker product menu items You can change the labels of FrameMaker product menu items If a FrameMaker product menu item has labels for different contexts you can change only the strings that specify the labels You can t change the strings that specify the contexts in which the labels appear For example the following code changes the labels for the TableConvert command include fstrings h F_ObjHandleT cmdId StringT labels 4 F_StringsT myLabels labels 0 StringT F_StrCopyString ToTable labels 1 StringT F_StrCopyString Make table out of this labels 2 StringT F_StrCopyString ToText labels 3 StringT F_StrCopyString Convert to paragraphs myLabels len 4 myLabels val StringT labels F_ApiSetStrings FV_SessionId cmdId FP_Labels amp myLabels FDK Programmer s Guide 171 i Manipulating Commands and Menus with the API Setting the labels of client defined menu items A client defined menu item can have only one labe
164. the Mif prefix the structure name the access type Get or Set and the structure field name For example to get the MType field of a lt Marker gt statement use the macro named MifMarkerGetMType mif_marker_ptr When you call MIF macros you must specify pointers to MIF data structures The names of MIF macros for list structures comprise the Mif prefix the substatement name the string List the access type Get or Set and the structure field name For example to get lt Polygon lt Point gt gt youuse MifPointListGetNext MifPointListGetPrev and MifPointListGetPoint Because most MIF data structures contain pointers to other structures you should dynamically allocate memory space for all data structures to minimize errors The MIF library The MIF library functions help write formatted MIF statements to a channel For information on functions that write individual MIF statements see Simple MIF library on page 387 FDK Programmer s Guide 385 18 FDE Utility Libraries 386 The MIF library maintains its own output channel and indent information Before you call any MIF library function you must 1 Call F_ChannelOpen to open a channel 2 Call F_MifSetOutputChannel to set the channel as the MIF output channel 3 Call F_MifSetIndent to set the channel s indent level After you finish writing to the channel be sure to call F_ChannelClose to close it For example
165. the file to filter the document into The client s F_ApiNotify callback should create the specified file if it does not already exist and filter the contents of the FrameMaker product document into it 242 FDK Programmer s Guide Using Imported Files and Insets Writing file to file filters A file to file filter takes a file of a specified format as input and writes a version of that file to disk in another format This is particularly useful for filtering graphic files that will be imported by reference Suppose you write a standard filter that converts a graphic file to FrameVector format When you import the graphic file by reference the Frame Vector file will actually be the referenced file Instead had you used a file to file filter for this conversion the original graphic file would be the referenced file and FrameMaker would filter it every time you opened the document Subsequent changes to the imported file in its native format would automatically show up in your document The FrameMaker product invokes a file to file filter either as a text import filter a graphic import filter a text export filter or a graphic export filter How the filter is invoked depends on the import or export actions made by a user or by some other client open actions invoke an import filter and save actions invoke an export filter It s important to note that the a file to file filter client can contain more than one filter process For
166. the left of the function name indicating that this function applies only to the content of a structured document If you register a client to work with the FrameMaker program interface you should be sure that your client doesn t use any functions identified as Structured otherwise your client may exhibit unpredictable behavior Pathnames Code examples in this manual use UNIX pathnames For example docId F_ApiSimpleOpen StringT tmp mydoc fm False If you are using the FDK on the Macintosh or on Windows change the code to use the filepath naming conventions for those platforms For example on Macintosh change the code above to code like the following docId F_ApiSimpleOpen StringT MyHardDrive tmp mydoc fm False On Windows change it to code like the following docId F_ApiSimpleOpen StringT c tmp mydoc fm False The FDK provides functions for converting platform specific filepaths For more information see Making I O portable with channels on page 377 of the FDK Programmer s Guide Typographic conventions This manual uses different fonts to represent different types of information e What you type is shown in text like this e Function names property names structure names returned values constants filter names program names pathnames and filenames are also shown in text like this e Placeholders such as those representing names of files and directories are shown in t
167. the property lists that it used to update the book include futils h IntT i UCharT msg 1024 F_PropValsT params returnParamsp NULL F_ObjHandleT bookId params F_ApiGetUpdateBookDefaultParams i F_ApiGetPropIndex amp params FS_ShowBookErrorLog params val i propVal u ival True i F_ApiGetPropIndex amp params FS_AllowInconsistentNumProps params val i propVal u ival FV_DoOK i F_ApiGetPropIndex amp params FS_UpdateBookNumbering params val i propVal u ival False err F_ApiUpdateBook bookId amp params amp returnp F_ApiPrintUpdateBookStatus returnp F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnp Using the book error log When updating a book the FrameMaker product posts errors to a book error log The error log is a FrameMaker document that lists error conditions and includes hypertext links to offending locations in the book s document files By default FDK clients post book errors to the console However your clients can post errors to the log and can include hypertext links in those messages FDK Programmer s Guide Frame Book Architecture 15 Displaying the error log for book updates By default the FrameMaker product displays update errors in the console You direct the FrameMaker product to display the error log via the property list you pass to F_ApiUpdateBook
168. the same as long as the object is in the same document The API provides a function named F_ApiGetUniqueOb ject which gets an object s ID from its UID IMPORTANT Jf you copy an object and then paste it the FrameMaker product considers the pasted object a new object and assigns a new UID to it This is also true for a paragraph that is conditionalized If the entire paragraph is of a given condition and that condition is hidden and then shown the paragraph will have a new UID Representing object characteristics with properties Each object has a property list or set of properties that represent its characteristics Each property has a value associated with it For example if a paragraph has two tabs the value of its FP_NumTabs property is 2 A property value can be more than an integer It can also be a string a pointer to a structure that contains a set of strings or a variety of other things The following table summarizes the different data types property values can be FDK Programmer s Guide Frame Session Architecture 13 Property data type What the property value represents IntT An integer enum boolean or ordinal value For many IntT properties the API provides defined constants such as True and False F_IntsT A set of integers or a set of IDs F_UIntsT A set of unsigned integers MetricT A measurement value F_MetricsT A set of metrics StringT A character string F_StringsT A set of character
169. the same as the FrameMaker product Text Inset Properties dialog box For example if your client updates client text insets by executing database queries its Text Inset Properties dialog box could provide a text field for the user to enter a new query After your client displays its Text Inset Properties it should call F_ApiReturnValue with retVal setto FR_DisplayedTiDialog This notifies the FrameMaker product that the dialog box has been displayed For more information on requesting and responding to notifications see Responding to user initiated events or FrameMaker product operations on page 34 For more information on using custom dialog boxes in your client see Chapter 11 Handling Custom Dialog Box Events Writing filter clients You can use the FDK to create filter clients that translate Frame files to or from other file formats The FrameMaker product calls an import filter client when the user or another client attempts to open or import a file with a specified format It calls an export filter client when the user chooses a particular format from the Format pop up menu of the Save As dialog box or the user or another client saves a file with a specified suffix IMPORTANT To write clients that import and export SGML documents use the Structure Import Export API For more information see the online manual Structure Import Esport API Programmer s Guide Filter clients that filter text file formats are
170. to R 173 in text ranges G 118 R 23 hiding G 309 to G 311 importing G 230 to G 235 function for R 192 to R 197 importing text files G 229 G 230 G 234 R 126 to R 127 FDK Programmer s Reference amp Guide manipulating G 111 to G 129 printing functions for R 5 R 253 to R 255 properties of R 669 to R 671 setting properties G 124 to G 126 R 669 setting type in properties G 126 See also conditions flows strings text boxes text columns text files text frames text insets text items text lines See also text locations text properties text ranges text selections variables text boxes in dialog boxes G 200 getting setting the state of function for R 5 properties of R 534 text columns API representation of the beginning of G 313 R 166 R 687 API representation of the end of G 313 R 167 R 687 creating G 150 function for R 14 R 216 to R 218 as organized in flows illustrated G 298 G 305 properties of R 520 to R 521 See also text frames text conditions See conditions text entry client response to G 38 to G 40 text files importing G 229 G 230 G 234 properties for table R 126 to R 127 text flows See flows text format G 311 See also Character Catalog formats text properties text frames API representation of G 294 API representation of the beginning of G 313 R 167 API representation of the end of G 313 R 167 cells as G 332 connecting G 297 to G 300 defined G 293 for footnotes G 327 as organiz
171. type These arguments are typed PathEnumT PathEnumT is defined as typedef enum FDefaultPath Platform the client is running on FUnixPath UNIX FMacPath Macintosh FDosPath Windows FDIPath Device independent PathEnumT The following table provides examples of the path types Path type Example FUnixPath MyDirectory MySubdirectory MyFile FMacPath HardDrive MyDirectory MySubdirectory MyFile FDosPath c mydirect mysubdir myfile FDIPath lt r gt lt c gt MyDirectory lt c gt MySubdirectory lt c gt MyFile FDK Programmer s Guide Making I O and Memory Calls Portable Device independent pathnames have the following format lt code gt name lt code gt name lt code gt name where code identifies the role of the component in the pathname and name is the name of a component in the pathname The following table lists codes and their meanings Code Meaning a Root of the file tree Component u Up one level in the file tree For example you can express the following UNIX pathname MyDirectory MySubdirectory MyFile as the following device independent absolute pathname lt r gt lt c gt MyDirectory lt c gt MySubdirectory lt c gt MyFile or as the following device independent relative pathname lt c gt MyFile For more information on how FrameMaker specifies device independent pathnames see the online MIF Reference Manipulating filepaths The FDE provides functions
172. unique number used to identify the dialog box It is passed to the F_ApiDialogEvent callback when the user does something in the dialog box If your client uses multiple modeless dialog boxes you can use the dialog number passed to F_ApiDialogEvent to determine which dialog box an event has occurred in Line 12 This line turns on the FA_Note_BackToUser notification The FrameMaker product sends this notification to the client each time it finishes processing some user input For example 216 FDK Programmer s Guide Handling Custom Dialog Box Events each time the user changes the insertion point or applies a paragraph format the FrameMaker product sends this notification to the client Lines 26 to 28 These lines handle the FA_Note_BackToUser notification When the client receives this notification it is possible the user has changed the insertion point or applied a new tag to the paragraph containing the insertion point To make sure the dialog box is displaying the correct tag the client gets the tag of the paragraph containing the insertion point each time it receives the notification Line 30 This line uses F_ApiSetString to stuff the paragraph tag into the text box When you get or set dialog item properties you must specify a dialog box ID and a dialog item ID The callto F_ApiDialogItemId gets the ID of the text box Lines 35 to 59 These lines define the F_ApiDialogEvent callback When a user changes a
173. use F_ApiNewNamedOb ject To add the format change list to a format rule clause set the format rule clause object s FP_FmtChangeListTag property to the name of the change list For example the following code creates the Code format change list shown in Figure 8 2 and adds it to the first format rule clause of the Para element definition s first text format rule F_ObjHandleT docId changeListId F_ObjHandleT edefId UIntT i F_StringsT fonts F_IntsT rules clauses FDK Programmer s Guide 153 az Creating and Deleting API Objects 154 docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc changeListId F_ApiNewNamedObject docId FO_FmtChangeList Code Get the index of the Courier font family in the list of fonts available in the current session fonts F_ApiGetStrings 0 FV_SessionId FP_FontFamilyNames for i 0 i lt fonts len amp amp F_StrEqual Courier fonts val i i if i fonts len return Courier font not found Add the FP_FontFamily property set it to Courier F_ApiSetInt docId changeListId FP_FontFamily i Add the FP_PairKern property F_ApiSetInt docId changeListId FP_Pairkern False Get ID of the first clause of the first text format rule edefId F_ApiGetNamedObject docId FO_ElementDef Para rules F_ApiGetInts docId edefId FP_TextFmtRules clauses F_ApiGetInts docId rules val 0 FP_FmtRuleClauses
174. 1 F_FilePathProperty function G 377 R 8 R 381 F_FilePathToPathName function G 375 R 7 R 382 F_FilePathUpdate function R 8 R 383 F_FilterArgsT structure R 681 F_FontEncIDQ function R 8 R 20 F_FontEnclIdQ function R 384 F_FontEncName function R 8 R 20 R 385 F_FontEncT structure R 682 F _FontsT structure R 11 R 99 R 682 F_FontT structure R 682 F_Free function G 19 G 21 G 94 G 369 G 373 G 379 G 381 R 12 R 18 R 53 R 59 R 60 R 386 F_FreeHandle function G 379 R 12 R 386 F_GetFilePath function R 8 R 387 F_GetHandleSize function R 12 R 389 F_GetMacFilePathInfo function R 8 R 388 F_HandleEqual function R 12 R 389 F_HashCreate function G 383 R 9 R 390 F_HashDestroy function R 9 R 392 F_HashEnumerate function R 9 R 393 F_HashGet function G 383 R 9 R 394 F_HashRemove function R 9 R 394 F_HashReportOnData function R 395 index 39 os Index Reserved Names F_HashSet function G 383 R 9 R 396 F_IntsT structure G 90 G 271 R 4 R 11 R 15 R 131 R 289 R 682 F_LanguageNumber function R 397 F_LanguageString function R 398 F_LockHandle function R 12 R 399 F_MakeDir function R 8 R 400 F_MetricApproxEqual function R 13 R 401 F_MetricConstrainAngle function R 13 R 401 F_MetricDiv function R 13 R 402 F_MetricFloat function G 384 R 13 R 403 F_MetricFractMul function G 372 G 384 R 13 R 403 F_MetricMake function R 13 R 404 F_MetricMul functio
175. 192 moving G 191 multiline text boxes G 200 properties of G 211 getting G 213 setting G 213 radio buttons G 199 resizing G 191 scroll bars G 201 scroll lists G 202 setting properties of G 197 to G 204 G 208 specifying order in dialog boxes G 194 to G 195 as stuff items G 203 to G 204 G 213 text boxes G 200 triboxes G 199 R 537 updating G 220 See also dialog boxes dialog resources dialog resources G 212 to G 213 opening G 217 to G 218 See also dialog boxes dialog items dictionaries document G 284 adding words to _R 303 to R 305 direct straight exit DSE function setting R 439 directories functions for allocating and returning handles for R 380 creating R 400 getting current G 96 R 24 R 59 to R 60 renaming R 434 returning filepath for R 421 to R 422 returning filepath of parent R 381 returning identification information R 388 returning information about R 381 returning the next file in R 379 to R 380 disabling the API G 16 document dictionaries See dictionaries document document properties Adobe Acrobat R 541 change bar G 284 R 549 condition G 284 R 550 equation G 284 R 550 to R 551 flow R 559 footnote G 284 G 327 R 557 to R 559 general R 546 to R 548 getting and setting G 97 to G 99 hypertext R 551 menu bar R 557 object pointer G 282 to G 284 R 538 to R 540 page G 284 R 559 to R 561 print G 284 R 561 to R 563 selection R 564 table footnote G 284 R 572 type in G 126 G 284 G 391 R 573 to R 575 typog
176. 2 FP_NumLines property FO_DlgScrollBox R 537 FP_NumNamespaces property FO_Element R 643 FP_NumPoints property FO_Line R 602 FP_NumPoints property FO_Polygon R 604 FP_NumPoints property FO_Polyline R 604 FP_NumTabs property FO_FmtChangeList R 585 FP_NumTabs property FO_Pgf R 621 FP_NumTabs property FO_PgfFmt R 629 FP_Object property G 109 FP_Object property FO_Element R 642 FP_ObjectAttributes property FO_GraphicObject R 594 FP_ObjectFmtRules property G 108 G 109 FP_ObjectFmtRules property FO_ElementDef G 343 R 647 FP_ObjectType property FO_ElementDef G 344 R 647 FP_OldTypeNum property FO_Marker R 609 R 609 FP_OpenDir property FO_Session G 94 R 635 FP_OperatingSystem property FO_Session R 635 FP_OptJLetSpace property FO_FmtChangeList R 583 FP_OptJLetSpace property FO_Pgf R 613 FP_OptJLetSpace property FO_PgfFmt R 622 FP_OptJRomSpace property FO_FmtChangeList R 583 FP_OptJRomSpace property FO_Pgf R 613 FP_OptJRomSpace property FO_PgfFmt R 622 FP_OptSpace property FO_FmtChangeList R 583 FP_OptSpace property FO_Pgf R 621 FP_OptSpace property FO_PgfFmt R 629 FP_OrphanRows property FO_Tbl R 653 FP_OrphanRows property FO_TblFmt R 658 index 58 FP_Outline property FO_CharFmt R 517 FP_Outline property FO_Doc R 575 FP_Outline property FO_FmtChangeList R 587 FP_Outline property FO_Pgf R 615 FP_Outline property FO_PgfFmt R 624 FP_Outline property text location R 671
177. 20 R 460 FDK Programmer s Reference amp Guide F_StrIEqualNQ function R 19 R 461 F_StrIEqualNEnc function R 20 R 462 F_StringsT structure G 23 G 90 G 271 G 306 R 4 R 11 R 16 R 160 R 275 R 684 F_StrIPrefix function R 19 F_StrIPrefixEnQ function R 20 F_StrIPrefixEnc function R 463 F_StrIlsEmpty function R 463 F_StrISuffixEnc function R 20 R 464 F_StrLen function G 370 R 20 R 465 F_StrLenEnc function R 20 R 465 F_StrListAppend function R 18 R 466 F_StrListCat function R 18 R 466 F_StrListCopy function R 18 R 467 F_StrListCopyListQ function R 18 R 468 F_StrListFirst function R 18 R 469 F_StrListFreeQ function R 18 R 469 F_StrListGet function R 18 R 470 F_StrListIIndex function R 18 R 471 F_StrListIndex function R 18 R 471 F_StrListInsert function G 382 R 18 R 472 F_StrListLast function R 18 R 473 F_StrListLenQ function R 18 R 474 F_StrListNew function G 382 R 18 R 474 F_StrListRemove function R 18 R 475 F_StrListSetString function R 18 R 476 F_StrListSortQ function G 382 R 18 R 477 F_StrNew function G 381 R 18 R 478 F_StrPrefix function R 19 R 478 F_StrPrefixN function R 19 R 479 F_StrRChr function R 19 R 480 F_StrRChrEnc function R 20 R 480 F_StrReverse function R 20 R 481 F_StrStripQ function R 20 R 482 F_StrStripLeadingSpaces function R 20 R 482 F_StrStripTrailingS paces function R 20 R 483 F_StrSubString function R 19 R 484 F_S
178. 214 G 219 G 223 R 5 R 206 F_ApiModelessDialog function G 214 G 216 G 219 R 5 R 208 F_ApiNewAnchoredFormattedObject function G 148 R 209 F_ApiNewAnchoredObject function G 148 G 236 R 14 R 24 R 210 F_ApiNewBookComponentInHierarchy function R 212 F_ApiNewElement function G 144 G 150 R 213 F_ApiNewElementInHierarchy function G 150 R 215 F_ApiNewGraphicObject function G 101 G 146 G 150 R 9 R 14 R 212 F_ApiNewNamedObject function G 145 G 170 G 355 R 14 R 218 F_ApiNewSeriesObject function G 11 G 143 G 149 R 14 R 220 F_ApiNewSubObject function G 152 R 221 F_ApiNewTable function G 143 G 148 G 154 R 15 R 22 R 224 F_ApiNotification function G 34 R 25 R 226 F_ApiNotifyQ function G 7 G 15 G 35 G 36 G 39 G 41 G 214 G 237 G 371 R 1 R 233 F_ApiObjectValidQ function R 24 R 237 F_ApiOpen function G 46 G 48 G 53 G 56 G 84 G 221 R 2 R 6 R 52 R 238 calling G 48 F_ApiOpenResource function G 214 G 216 G 217 R 6 R 245 index 37 os Index Reserved Names F_ApiPaste function G 127 R 3 R 23 R 246 F_ApiPopClipboard function G 129 R 3 R 248 F_ApiPrintFAErmo function R 4 R 248 F_ApiPrintImportStatus function R 4 R 250 F_ApiPrintOpenStatus function G 52 R 4 R 250 R 251 F_ApiPrintPropVal function R 5 R 251 F_ApiPrintPropVals function R 5 R 252 F_ApiPrintSaveStatus function G 65 R 4 R 253 F_ApiPrintTextItem function R 5 R
179. 253 F_ApiPrintTextItems function R 5 R 254 F_ApiPrintUpdateBookStatus function G 360 R 4 R 255 F_ApiPromoteElement function R 256 F_ApiPromptInt function G 18 G 223 R 5 R 256 F_ApiPromptMetric function G 18 G 223 R 5 R 258 F_ApiPromptString function G 7 G 18 G 223 R 5 R 260 F_ApiPushClipboard function G 129 R 3 R 261 F_ApiQuickSelect function G 42 R 3 R 262 F_ApiRedisplay function G 96 R 7 R 263 F_ApiReformat function G 97 R 7 R 25 R 264 F_ApiRehyphenate function G 73 R 7 R 265 F_ApiResetEqnSettings function G 73 R 7 R 266 F_ApiResetReferenceFrames function G 73 R 7 R 266 F_ApiRestartPgfNumbering function G 73 R 7 R 267 F_ApiReturnValue function G 37 R 1 R 5 R 268 F_ApiRun Q function R 270 F_ApiSave function G 59 G 60 R 2 R 6 R 52 R 272 F_ApiScrollBox function G 22 R 5 R 274 F_ApiScrollToText function R 276 F_ApiService function R 277 F_ApiSetAttributeDefs function R 278 F_ApiSetAttributes function R 280 F_ApiSetClientDir function R 25 R 282 F_ApiSetElementRange function R 282 F_ApiSetFdFunc function R 284 F_ApiSetIdQ function G 90 G 163 G 168 R 3 R 16 R 285 F_ApiSetInt function G 7 G 11 G 90 R 6 R 15 R 16 R 287 F_ApiSetIntByName function G 264 R 9 R 288 F_ApiSetInts function G 90 R 16 R 289 F_ApiSetMetric function G 90 G 99 R 16 R 291 index 38 F_ApiSetMetricByName function G 264 R 9
180. 316 structure for G 114 to G 115 G 271 R 689 text selections clearing G 127 function for R 3 R 56 to R 58 Clipboard functions and G 127 to G 129 R 3 copying G 127 function for R 3 R 68 to R 69 cutting G 127 function for R 3 R 72 to R 73 deleting function for R 3 R 88 to R 89 getting G 114 to G 117 function for R 181 to R 182 getting the text in function for R 173 to R 176 pasting G 127 function for R 3 R 23 R 246 to R 247 selection state of G 285 G 287 setting G 114 to G 117 functions for R 17 R 313 to R 314 See also text text items Text Symbols view option G 311 text tokens in strings R 485 index 32 title bars setting G 98 title label of dialog boxes G 196 TOC flows G 289 topical listing of API functions R 1 to R 24 transactions committing in getting and setting facets R 129 R 288 traversing lists of document objects G 84 lists of objects of one type G 85 ordered lists of objects G 85 to G 86 paragraphs G 84 G 103 starting G 83 tri state check boxes properties of R 537 See also triboxes triboxes in dialog boxes G 199 R 537 properties of G 199 R 537 type in properties G 126 G 284 R 573 to R 575 defined G 391 setting G 126 typedefs naming convention for G xiii R xix types See data types file types object types typographic conventions used in this manual G xiv R xx typographic properties R 576 U UByteT data structure for R 691 UIDs unique IDs G 89 G 270 G 391 defined G 391
181. 36 StringT F_ApiGetEncodingForFamily IntT family This argument Means family The font family for which you want to know the encoding Example The following code gets the index for the Minchu font family from the session list of font families It then gets the encoding for that font family include futils h include fstrings h include fencode h F_StringsT families StringT encoding UIntT i First get the list of font families for the session families F_ApiGetStrings 0 FV_SessionId FP_FontFamilyNames Now get the index of the Minchu family for i 0 i lt families len i if F_StrlEqual families val StringT minchu break if 1 families len return Minchu not found Now use the index to get th ncoding for Minchu encoding F_ApiGetEncodingForFamily i Free the strings F_ApiDeallocateStrings amp families F_ApiDeallocateString amp encoding Getting the encoding for a font variation If the font family returns an encoding of Multiple you should use F_ApiFamilyFonts to get a list of the variations for the family Then you can use F_ApiGetEncodingForFont to get the encoding for a specific variation The syntax for F_ApiGetEncodingForFont is StringT F_ApiGetEncodingForFont F_FontT font This argument Means font Pointer to a structure listing the font s name weight
182. 588 FP_KeepWithNext property FO_Pgf R 619 FP_KeepWithNext property FO_PgfFmt G 274 R 627 index 54 FP_KeepWithPrev property FO_FmtChangeList R 588 FP_KeepWithPrev property FO_Pgf R 619 FP_KeepWithPrev property FO_PgfFmt R 627 FP_KernX property FO_CharFmt R 516 FP_KernX property FO_Doc R 574 FP_KernX property FO_FmtChangeList R 587 FP_KernX property FO_Pgf R 615 FP_KernX property FO_PgfFmt R 624 FP_KernX property text location R 670 FP_KernY property FO_CharFmt R 517 FP_KernY property FO_Doc R 574 FP_KernY property FO_FmtChangeList R 587 FP_KernY property FO_Pgf R 615 FP_KernY property FO_PgfFmt R 624 FP_KernY property text location R 670 FP_KeyboardShortcutLabel property FO_Command R 525 FP_KeyboardShortcuts property FO_Command R 525 FP_Label property FO_Book G 98 R 496 FP_Label property FO_Command G 98 R 523 FP_Label property FO_DialogResource G 212 R 532 FP_Label property FO_DlgButton G 212 R 533 FP_Label property FO_DlgCheckBox G 212 R 533 FP_Label property FO_DlgLabel G 212 R 534 FP_Label property FO_DlgRadioButton G 212 R 535 FP_Label property FO_DlgTriBox G 212 R 537 FP_Label property FO_Doc G 98 R 577 FP_Label property FO_Menu R 523 FP_Label property FO_MenultemSeparator R 523 FP_Label property FO_Session R 634 FP_Labels property FO_Command G 170 R 525 FP_Labels property FO_DlgImage G 212 R 534 FP_Labels property FO_DlgPopUp
183. 59 functions for R 22 R 84 R 87 to R 88 getting the IDs of selected G 87 properties of G 333 G 336 R 651 to R 652 selecting G 118 See also cells rubi documents properties for formatting R 564 rubi composites properties of R 630 Rubi groups creating G 131 index 26 rubi text API representation of the beginning of R 171 R 172 API representation of the ending of R 171 Ruling Catalog G 328 ruling format properties G 329 R 630 ruling formats G 281 G 328 to G 330 API representation of G 281 G 329 to G 330 illustrated G 329 as organized in documents G 329 properties of G 329 R 630 rulings G 328 default G 334 override G 334 See also ruling formats S Save dialog box displaying G 21 to G 22 R 53 to R 56 Save operation repeating G 41 specifying aspects of G 60 Save operation property lists See saveParamsp property lists Save status of files checking G 64 to G 66 See also status flags saveParamsp property lists creating with F_ApiGetSaveDefaultParams G 61 to G 64 from scratch G 64 saveParamsp scripts See saveParamsp property lists saveReturnParamspp property lists G 64 saving contents of Clipboard G 129 dialog box information G 181 to G 185 documents and books G 59 to G 66 G 279 R 2 R 6 R 272 to R 274 R 327 to R 328 files G 35 Frame DRE files G 181 global document information G 284 G 285 screen display updating not updating G 97 screen flicker avoiding G 96 scriptable functions API G 45 G 46
184. 6 Introduction to FDE Replacing C library calls 370 The following table lists some commonly used C library functions and the FDE functions you can replace them with Function FDE substitute strcmp F_StrEqual or F_StrCmp strlen F_StrLen strcpy F_StrCpy strcat F_StrCat Some FDE functions have slightly different parameters or return values than the corresponding C library functions For example F_StrCpy returns VoidT while strcpy returns a pointer Before using an FDE library function look it up in Chapter 2 FDK Function Reference of the FDK Programmer s Reference A simple FDE filter The following client filters a text file into a Frame document Following the code is a line by line description of how it works 1 include fdetypes h 2 include fapi h 3 include fchannel h 4 include fmemory h 5 include fmetrics h 6 include futils h 7 include fioutils h 8 9 define BUFFERSIZE 1025 10 define in MetricT 72 65536 12 VoidT F_ApiNotify notification docId sparm iparm IntT notification F_ObjHandleT docId StringT sparm IntT iparm FilePathT path ChannelT chan F_TextLocT tl StringT buf IntT count F_FdeInit buf F_Alloc BUFFERSIZE NO_DSE FDK Programmer s Guide Introduction to FDE 16 26
185. 659 FP_TblTitleSelected property FO_Tbl R 656 R 658 FP_TbITopRuling property FO_Tbl G 336 R 656 FP_TblTopRuling property FO_TblFmt R 661 FP_TblWidth property FO_Tbl R 654 FP_Text property FO_DlgEditBox R 534 FP_TextFmtRules property G 108 G 109 FP_TextFmtRules property FO_ElementDef G 343 G 344 R 647 FP_TextIsInvalidInElement property FO_Element R 644 FP_TextLineType property FO_Math R 603 FP_TextLineType property FO_TextLine R 607 FP_TextLoc property FO_AFrame R 597 FP_TextLoc property FO_Fn R 581 FP_TextLoc property FO_Marker R 609 FP_TextRange property FO_Element R 640 FP_TextRange property FO_TextInset R 663 FP_TextRange property FO_Var R 672 FP_TextRange property FO_XRef R 530 FP_TextSelection property FO_Doc G 114 G 285 R 17 R 548 R 565 FP_Theta property FO_Arc R 598 FP_TiAutomaticUpdate property FO_Text Inset R 663 FP_TiByRows property FO_TiTextTable R 668 FP_TiClientData property FO_TiApiClient R 666 FP_TiClientName property FO_TiApiClient G 236 R 666 FP_TiClientSource property FO_TiApiClient G 236 R 666 FP_TiClientType property FO_TiApiClient G 236 R 666 FP_TiEOLisEOP property FO_TiText R 668 FP_TiFile property FO_TextInset R 663 FP_TiFlowName property FO_TiFlow R 667 FP_TiFlowPageSpace property FO_TiFlow R 667 FP_TiFormat property FO_TiFlow R 667 FP_TiHeadersEmpty property FO_TiTextTable R 668 FP_TilsUnresolved property FO_TiApiClient R
186. 666 FP_TiLocked property FO_Text Inset G 235 R 663 FP_TiMacEdition property FO_TextInset R 663 index 64 FP_TiMainFlow property FO_TiFlow R 667 FP_Tint property FO_GraphicObject R 595 FP_TintBaseColor property FO_Color R 520 FP_TiNumCols property FO_TiTextTable R 668 FP_TiNumHeaderRows property FO_TiTextTable R 668 FP_TiNumSeparators property FO_TiTextTable R 668 FP_TiRemoveOverrides property FO_TiFlow R 667 FP_TiRemovePageBreaks property FO_TiFlow R 667 FP_TiSeparator property FO_TiTextTable R 668 FP_TiTblTag property FO_TiTextTable R 668 FP_TiTextEncoding property FO_TiText R 668 FP_TiTextEncoding property FO_TiTextTable R 668 FP_TmpDir property FO_Session R 637 FP_TopMargin property FO_Doc R 561 FP_TopRowSelection property FO_Tbl G 87 R 656 FP_TopSeparator property FO_FmtChangeList R 583 FP_TopSeparator property FO_Pgf R 620 FP_TopSeparator property FO_PgfFmt R 628 FP_TopSepAtIndent property FO_FmtChangeList R 583 FP_Tracking property FO_CharFmt R 517 FP_Tracking property FO_Doc R 575 FP_Tracking property FO_FmtChangeList R 587 FP_Tracking property FO_Pgf R 615 FP_Tracking property FO_PgfFmt R 625 FP_Tracking property text location R 671 FP_TrackingChange property FO_FmtChangeList R 587 FP_Transient property FO_Marker R 610 FP_TrapwiseCompatibility property FO_Doc R 563 FP_TypeOfDisplayText property FO_Book G 353 R 497 FP_Underlining property FO_Ch
187. 7 R 372 executing R 107 importing text R 126 to R 127 renaming R 434 returning filepath for R 421 to R 422 returning identification information R 388 returning information about R 381 table of operations on R 6 generating for books G 71 header G 8 G 367 imported G 229 to G 235 importing text and graphics G 230 to G 235 MIF G x G xi R xvi R xvii opening G 41 to G 42 R 326 saving G 35 uncompressing G 42 filetype hint strings for importing and exporting text files G 254 printing out a list for installed filters G 255 syntax for G 249 fill patterns R 595 illustrated R 595 setting G 11 filters G 5 bailing out G 15 compiling and running G 373 to G 374 flags for alert boxes table G 18 for Frame Clipboard functions G 128 to G 129 table of G 128 for FS_ImportStatus table R 195 to R 196 naming convention for G xiii R xix for text item types G 111 tables of G 315 R 167 See also status flags and individual flags in the FDK Reserved Names Index flow properties See document properties flows G 280 G 297 to G 300 G 389 API representation of G 280 G 298 API representation of the beginning of G 313 R 166 R 686 API representation of the end of G 313 R 166 R 686 Autoconnect setting for G 297 creating G 145 G 150 deleting G 158 document properties for R 559 HIDDEN G 292 G 318 illustrated G 297 G 298 G 304 to G 305 main G 297 importing G 232 organization of paragraphs in G 304 as organized in docu
188. 75 R 22 R 331 F_ApiStringLenQ function R 332 F_ApiSubObject function R 221 F_ApiSystemShell function R 333 F_ApiTakeControl function R 25 R 334 F_ApiUnStraddleCells function G 75 R 22 R 336 F_ApiUnWrapElement function R 337 FDK Programmer s Reference amp Guide F_ApiUpdateBook function G 356 R 338 F_ApiUpdateTextInset function G 236 R 7 R 24 R 341 F_ApiUpdateVariables function G 73 R 7 R 342 F_ApiUpdateXRefs function G 73 G 221 R 7 R 343 F_ApiUserCancel function R 24 R 344 F_ApiUSleep function R 17 R 25 R 344 F_ApiWinConnectSession function R 345 F_ApiWinDefaultMessageFilter function R 346 F_ApiWrapElement function R 347 F_ApUpdateBook function calling G 70 F_Assert function R 347 F_AttributeDefsT structure R 678 F_Calloc function R 12 R 349 F_ChannelAppend function R 10 R 350 F_ChannelClose function G 369 G 373 G 377 G 386 R 10 R 351 F_ChannelCloseTmp function R 10 R 351 F_ChannelEof function R 10 R 352 F_ChannelFlush function R 10 R 352 F_ChannelMakeTmp function R 10 R 353 F_ChannelOpen function G 369 G 372 G 377 G 386 R 10 R 353 F_ChannelPeek function R 10 R 355 F_ChannelRead function G 377 R 10 R 356 F_ChannelSeek function R 10 R 357 F_ChannelSize function R 10 R 357 F_ChannelTellQ function R 10 R 358 F_ChannelWrite function G 369 G 377 R 10 R 359 F_CharIsAlphabetic function G 382 R 2 R 360 F_CharIsAlphaNumeric func
189. 78 ShowCharacterTags expandomatic item G 172 ShowDocumentWindows expandomatic item G 172 ShowFilesRecently Visited expandomatic item G 172 ShowFontChoices expandomatic item G 172 ShowImportFiles expandomatic item G 172 ShowParagraphTags expandomatic item G 172 Structure ViewMainMenu string constant R 78 ViewerPopup string constant R 78 ViewOnlyMainMenu string constant G 26 R 78 FMHOME directory getting G 96 A B AddrT data type G 367 AEClient AppleScript client R 30 R 31 alloc function G 369 BoolT data type G 367 R 675 ByteT datatype G 367 R 675 C D E ChannelT structure R 677 CHAR_APPLY_TAG f code G 39 CharT data type G 367 ConStringT data type G 367 R 675 DDQSort function R 27 DocFP_XmlEncoding property FO_Book R 505 DocFP_XmlFileEncoding property FO_Book R 505 R 570 DSE flag FDE functions G 379 R 439 ErrorT data type G 367 G 379 R 675 F G 356 G 357 FDK Programmer s Reference amp Guide Index Reserved Names F F_AEGetEventHandler function R 1 R 28 F_AEInstallEventHandler function R 1 R 29 F_AERemoveEventHandler function R 1 R 30 F_Alloc function G 369 G 372 G 379 R 12 R 32 F_AllocHandle function G 379 R 12 R 32 F_ApDeallocatePropVals function G 71 F_ApiAddCols function G 156 R 14 R 22 R 34 F_ApiAddCommand function R 35 F_ApiAddCommandToMenu function G 166 R 3 R 35 R 81 F_ApiAddMenu function R 37 F_ApiAddMenuToMenu function R 3 R 37 R
190. 82 F_ApiAddRows function G 156 R 14 R 22 R 39 F_ApiAddText function G 121 G 236 G 373 R 23 R 24 R 41 F_ApiAlert function G 7 G 17 R 5 R 43 F_ApiAlive function R 44 F_ApiAllocatePropVals function G 46 G 49 G 50 R 11 R 45 F_ApiAllocateTextItems function R 11 R 46 F_ApiApplyPageLayout function R 7 R 47 F_ApiBailOut function G 15 G 43 G 373 R 11 R 24 R 48 R 374 F_ApiCallClient function G 361 R 24 R 49 F_ApiCenterOnText function R 51 F_ApiCheckStatus function G 51 G 65 G 232 G 359 R 6 R 52 R 196 F_ApiChooseFile function G 21 R 5 R 53 F_ApiClear function G 127 R 3 R 23 R 56 F_ApiClearAllChangeBars function G 73 R 7 R 58 F_ApiClientDirQ function R 24 R 59 F_ApiClientName function R 24 R 60 F_ApiClose function G 7 G 66 G 227 R 2 R 5 R 6 R 17 R 61 compared with the Close Command G 67 F_ApiCombinedFamilyFonts function R 8 R 62 F_ApiCommand function G 7 G 10 G 24 G 29 R 1 R 3 R 64 F_ApiCompare function G 68 R 2 R 6 R 65 return value structure R 680 F_ApiConnectToSession function R 67 R 95 R 106 index 35 os Index Reserved Names F_ApiCopy function G 127 R 3 R 23 R 68 F_ApiCopyAttribute function R 69 F_ApiCopyAttributeDef function R 69 F_ApiCopyAttributeDefs function R 69 F_ApiCopyAttributes function R 69 F_ApiCopyElementCatalogEntries function R 69 F_ApiCopyFonts function R 69 F_ApiCopyInts function R 4 R 69 F_ApiCopyMetrics
191. 89 FP_CellLeftMarginFixed property FO_FmtChangeList R 589 FP_CellMarginsFixed property FO_Pgf R 616 FP_CellMarginsFixed property FO_PgfFmt R 628 FP_CellNumColsStraddled property FO_Cell G 337 R 648 FP_CellNumRowsStraddled property FO_Cell G 337 R 648 FP_CellOverrideBottomRuling property FO_Cell G 337 R 649 FP_CellOverrideFill property FO_Cell G 334 G 336 R 649 FP_CellOverrideLeftRuling property FO_Cell G 336 R 649 FP_CellOverrideRightRuling property FO_Cell R 649 FP_CellOverrideShading property FO_Cell G 334 R 649 R 650 FP_CellOverrideTopRuling property FO_Cell G 334 R 649 R 650 FP_CellRightMargin property FO_FmtChangeList R 589 FP_CellRightMargin property FO_Pgf R 616 FP_CellRightMargin property FO_PgfFmt R 628 FP_CellRightMarginChange property FO_FmtChangeList R 589 FP_CellRightMarginFixed property FO_FmtChangeList R 589 FP_CellRow property FO_Cell R 649 index 48 FP_CellTopMargin property FO_FmtChangeList R 589 FP_CellTopMargin property FO_Pgf R 616 FP_CellTopMargin property FO_PgfFmt R 628 FP_CellTopMarginChange property FO_FmtChangeList R 589 FP_CellTopMarginFixed property FO_FmtChangeList R 589 FP_CellUseOverrideBRuling property FO_Cell R 649 FP_CellUseOverrideFill property FO_Cell G 334 G 336 R 649 FP_CellUseOverrideLRuling property FO_Cell R 649 FP_CellUseOverrideRRuling property FO_Cell R 649 FP_CellUseOverrideShading property FO_Cell G
192. A 3 column page with a heading that spans columns FDK Programmer s Guide 299 14 Frame Document Architecture 300 The FO_TextFrame properties FP_FirstSubCol and FP_LastSubCol specify the first and last FO_SubCol objects in a specific text frame Each FO_SubCol object has an FP_PrevSubCol property anda FP_NextSubCol property which specify the previous and next FO_SubCol objects in the flow Each FO_SubCol object also has a FP_ParentTextFrame property which specifies the text frame it is in If a text frame has only one column its FP_FirstSubCol and FP_LastSubCol properties both specify the ID of the FO_SubCol object that represents it Figure 14 12 shows how the API organizes the objects that represent the two column text frame on the first page of the document in Figure 14 9 FP_FirstSubCol FO_SubCol FP_PrevSubCol Previous in flow me KO pae FO_TextFrame 8 8 3 3 2 g 3 B a al vena i t ame y FO_SubCol FP_NextSubCol FP_LastSubCol Next in flow FIGURE 14 12 Objects that represent a text frame with two columns In FrameMaker flows can be structured If a flow is structured the FO_Flow object that represents it hasa FP_HighestLevelElement property that specifies the ID of the root element For information on how the API organizes paragraphs and text in flows text frames and columns see How the API organizes paragraphs on page 304
193. ABLE_IS_CELLS constant FP_EnabledWhen R 527 FV_ENABLE_IS_GRAPHIC_INSET constant FP_EnabledWhen R 527 FV_ENABLE_IS_OBJ constant FP_EnabledWhen R 527 FV_ENABLE IS_OR_IN_FRAME constant FP_EnabledWhen R 527 FV_ENABLE_IS_TABLE constant FP_EnabledWhen R 527 FV_ENABLE_IS_TEXT_FRAME constant FP_EnabledWhen R 527 FV_ENABLE_IS_TEXT_INSET constant FP_EnabledWhen R 527 FV_ENABLE_IS_TEXT_SEL constant FP_EnabledWhen G 174 R 527 FV_ENABLE_IS_VIEW_ONLY constant FP_EnabledWhen R 527 FV_ENABLE_NEEDS_BOOKP_ONLY constant FP_EnabledWhen R 528 FV_ENABLE NEEDS_DOCP ONLY constant FP_EnabledWhen R 526 R 527 R 528 FV_ENABLE_OBJ_PROPS constant FP_EnabledWhen R 527 FV_EvCaps flag modifiers R 94 FV_EvCommand flag modifiers R 94 FV_EvControl flag modifiers R 94 FV_EvMeta flag modifiers R 94 FV_EvOption flag modifiers R 94 FV_EvShift flag modifiers R 94 FV_FO_AFRAME constant F_TextLocT R 214 R 215 FV_FO_EQN constant F_TextLocT R 214 R 215 index 72 FV_FO_MARKER constant F_TextLocT R 214 R 215 FV_FO_TBL constant F_TextLocT R 214 R 215 FV_FO_VAR constant F_TextLocT R 214 R 215 FV_FO_XREF constant F_TextLocT R 214 R 215 FV_HypertextBadMatrixSize constant FP_HypertextValidateErr R 554 FV_HypertextBadSyntaxPathSpec constant FP_HypertextParseErr R 553 FV_HypertextCantOpenDestFile constant FP_HypertextValidateErr R 554 FV_HypertextCommandIllegalWithinPopup constant FP_H
194. API Using hypertext commands in your client s user interface You can embed hypertext commands in markers within FrameMaker product documents The basic set of FrameMaker hypertext commands allows you to establish links within and between documents and to jump from link to link You can lock a FrameMaker document that contains hypertext commands so that it behaves like a command palette For information on locking documents see your FrameMaker product user documentation Documents have a set of properties that specify their characteristics when they are locked By setting these properties you can change how a locked document window appears For example you can hide the scroll bars and the window control buttons For a list of locked document properties see Document View Only properties on page 578 of the FDK Programmer s Reference FrameMaker provides a special hypertext command message apiclient that can send messages to your client With this command you can create an extremely flexible user interface Your client only needs to define responses for the hypertext messages that are sent to it Users and hypertext document designers can set up the interface that sends the messages The message apiclienthypertext command is especially useful for setting up command palettes for your client FDK Programmer s Guide 31 a Creating Your Client s User Interface 32 To use the message apiclient hypertext command in your clien
195. ApiAlert Select an object first 48 FF_ALERT_CONTINUE_WARN 49 else F_ApiSetInt docId objid FP_Fill FV_FILL_BLACK 50 break 51 52 case AddPage Add a new page 53 pgid F_ApiNewSeriesOb ject docId FO_BodyPage 0 54 break 55 56 Lines 1 5 These lines include header files and define the constants for the client s menu items All clients must include the fapi h header To ensure your client is portable include fapi h before any other header files Lines 6 25 These lines define the F_ApiInitialize callback function When the user starts the FrameMaker product it calls F_ApiInitialize The call to F_ApiGetNamedObject gets the ID of the FrameMaker product menu bar MakerMainMenu The call to F_ApiDefineAndAddMenu creates a menu named API on the menu bar The calls to F_ApiDefineAndAddCommand add menu items to the API menu and define keyboard shortcuts for the items Lines 26 56 These lines define the F_ApiCommand callback function When the user chooses a menu item the FrameMaker product calls this callback with command set to the menu item number in this example CloseDoc SetFill or AddPage Lines 31 34 These lines get the ID of the document to change To use most API functions you need to specify an ID This example gets the ID of the document that has input focus that is the active document In each FrameMaker product session there is only
196. Because FrameMaker gives precedence to the labels shortcuts and menu item locations specified by the menu configuration files users can configure your client s interface If users know the names of your client s commands they can assign labels and shortcuts to the FDK Programmer s Guide Creating Your Client s User Interface a commands and specify where the commands appear on the menus by editing their menu configuration files For example if your client defines a command with the following code F_ObjHandleT editMenulId editMenuld F_ApiGetNamedObject FV_SessionId FO Menu EditMenu F_ApiDefineAndAddCommand 1 editMenuld NumberLines Number Lines NL users can make the command appear on the Special menu instead of the Edit menu by adding the following line to their menu configuration files lt Command NumberLines gt lt Add NumberLines lt Menu SpecialMenu gt gt If users add this line to their menu configuration files and your client does not define the NumberLines command or is not running the NumberLines menu item appears dimmed IMPORTANT Adobe Systems recommends that you document the names of your client s menus and commands so that users can customize them For more information on using menu configuration files see the online manual Customizing FrameMaker For more information on changing commands menu items and menus see Chapter 9 Manipulating Commands and Menus with the
197. Boxes for Your Client 10 3 Set the properties of the dialog box 4 Save and test the DRE file Note that this example does not involve setting properties for specific dialog items since the example is relatively simple The steps for creating the sample dialog box are described in the following sections Designing the layout of the dialog box To design the layout of the sample dialog box follow these steps 1 Set the appropriate platform view of the dialog box By default the platform view is the same as the version of FrameMaker that you are using To change the platform view use the appropriate keyboard shortcut To work with the UNIX view of the dialog box press Esc d x To work with the Macintosh view of the dialog box press Esc d m To work with the Windows view of the dialog box press Esc d w Delete all extraneous items from the DRE file except two labels a text box and a button Drag the object handles of the dialog box rectangle to resize it Select the text in one of the label items and type Apply Paragraph Tag 2 3 4 5 Select the text in the other label item and type Paragraph Tag 6 Select the text in the button s label and type Apply 7 Drag the object handles of the text box and the button to resize them 8 Position the items within the dialog box Figure 10 21 shows the DRE file with the layout of the dialog box completed File Edit Format View Special Graphics Table ki Apply
198. ByteT UCharT UIntT UShortT VoidT Equivalent type int char unsigned long long Procedure pointer int char int char double int short char void unsigned int unsigned char unsigned int unsigned char unsigned int unsigned short float short char STRBUFFSIZE 1 unsigned char unsigned char unsigned char unsigned long unsigned short void Size Signed 4 bytes platform dependent Signed byte platform dependent Unsigned 4 bytes platform dependent Signed 4 bytes platform dependent Unsigned 4 bytes Signed 4 bytes Signed 4 bytes Signed 4 bytes Signed 4 bytes nsigned 4 bytes nsigned 4 bytes G nsigned 4 bytes nsigned 4 bytes Signed 4 bytes Signed 2 bytes 256 bytes Pointer Unsigned 1 byte Unsigned 1 byte Unsigned 4 bytes Unsigned 2 bytes None a PByteT PCharT PRealT PShortT PUByteT PUCharT and PUShortT are used to suppress compiler errors if a function is not declared in ANSI format They are used only for function arguments To ensure that your client does not use platform specific data types or functions the FDE redefines them If a client that includes the fdetypes h header file uses a platform specific 368 FDK Programmer s Guide Introduction to FDE 16 type or function the compiler issues an error message when you attempt to compile it For example if your client declares the following variable
199. CONTINUE_NOTE else Try to get ID of object in front of selected object sibId F_ApiGetId docId objid FP_NextGraphicInFrame If there is an object in front put it behind if sibId F_ApiSetId docId objid FP_PrevGraphicInFrame sibId Moving graphic objects to different frames or pages To move a graphic object to a different frame set its FP_FrameParent property to the ID of that frame The API automatically changes all the properties that need to be changed to maintain the lists of objects in the object s old and new parent frames To move a graphic object to a different page set its FP_FrameParent property to the ID of a frame on that page All pages have an invisible frame called a page frame To put a graphic object directly on a page set its FP_FrameParent property to the ID of the page s page frame For more information on page frames see How the API represents pages on page 289 For an example of how to move objects from a frame to a page frame see F_ApiSetId on page 285 of the FDK Programmer s Reference Grouping objects To group a set of objects you first use F_ApiNewGraphicOb ject to create a group FO_Group object Then you add the objects to the group object by setting their FP_GroupParent properties to the ID of the group object The objects must be in the same frame as the group object For information on how to use F_ApiNewGraphicOb ject see C
200. Cell R 651 FP_PrevComponentInBook property FO_BookComponent G 105 G 354 R 513 FP_PrevFn property FO_Fn G 328 R 581 FP_PrevGraphicInFrame property FO_GraphicObject G 85 G 100 G 295 R 217 R 595 FP_PrevGraphicInGroup property FO_GraphicObject G 296 R 595 FP_PrevMenultemInMenu property FO_Command G 163 R 523 FP_PrevMenultemInMenu property FO_Menu G 162 G 163 G 165 G 168 R 523 FP_PrevMenultemInMenu property FO_MenultemSeparator G 163 G 165 G 168 R 523 FP_PrevPgfInFlow property FO_Pgf G 304 G 328 R 620 FP_PrevRowInTbl property FO_Row G 336 R 651 FP_PrevSiblingElement property FO_Element R 642 FP_PrevSubCol property FO_SubCol G 299 R 521 FP_PrevTextFrameInFlow property F_ApiNewGraphicObject G 150 FP_PrevTextFrameInFlow property FO_TextFrame G 298 R 606 FP_PrintBlankPages property FO_Book R 502 FP_PrintBlankPages property FO_Doc R 561 FP_PrintCollated property FO_Book R 502 FP_PrintCollated property FO_Doc R 562 FP_PrintCols property FO_Doc R 562 FP_PrintDownloadAsianFonts property FO_Book R 502 FP_PrintDownloadTrueTypeAsTypel property FO_Book R 502 FP_PrintEmulsion property FO_Book R 502 FP_PrintEmulsion property FO_Doc R 562 FP_PrintEndPage property FO_Doc R 319 R 562 FP_PrintEndPageName property FO_Doc R 562 index 60 FP_PrintEndPoint property FO_Doc R 562 FP_PrinterName property FO_Book R 502 FP_PrinterName property FO_Doc R 319 R 562 FP_PrintEvenP
201. Chapter How the API represents commands and menus 222 805 Getting the IDs of commands and menus 2 ee Determining a session s menu configuration a a Arranging menus and menuitems 2 2 Getting and setting menu item labels 0 000 eee ee ee Manipulating expandomatic menu items 2 0002222 2a Using check marks en a E a E E E E S E E E o a G Using context sensitive commands and menu items aoao a Providing context sensitive Help for client menu items 10 Creating Custom Dialog Boxes for Your Client 177 OVEIVICW 6 28st wee ek a ea eaa a a ea a a we ee ee al a How to create adialogbox 0 000 0 ee ee Creating a DRE file 2 2 0 2 2 Designing the layout of the dialog box 2222200 Setting the properties of the dialog box a Setting the properties of adialogitem 0 00002 ee ee ee FDK Programmer s Guide vi Chapter Chapter Part Il Chapter Saving a DRE file 2 2 202008 Testing a dialog box aooaa 00000 b eee eee A simple example aoaaa a a General tips for dialog editing ooa oaa a Summary of keyboard shortcuts o oo 11 Handling Custom Dialog Box Events How the API represents dialog boxes Overview of using a custom dialog box in yourclient Opening dialog resources o oo 2 ee ee ee Initia
202. Client requires you to specify a client s registered name and a string which it passes to the client The following table lists FrameMaker functionality and the registered names of the clients you can call to invoke it programmatically Functionality Registered client name Element catalog manager Element Catalog Manager Structure generator Structure Generator Reading and writing SGML documents and FmDispatcher reading writing and updating DTD and EDD documents The following table lists the strings you pass to the structure generator client to programmatically generate structure in a document or book String Meaning INPUTDOCID objectiD The ID of the input document or book RULEDOCID objectID The ID of the rule table document OUTPUTDOCNAME filename The full pathname of the output document or book This string is optional If you do not specify a pathname the structure generator leaves the document unsaved and open LOGNAME filename The full pathname of a log file This string is optional If you do not specify a pathname the structure generator leaves the log file unsaved and open GenerateDoc Instructs the structure generator to generate structure using the strings listed above To programmatically generate structure for a document or a book you call F_ApiCallClient multiple times each time passing it one of the strings listed in the table above For example the following code
203. Command Copy j copyMenuld F_ApiMenulItemInMenu editMenuld copyCmdId True if copyMenulId editMenulId F_Printf NULL Copy is on the Edit menu else if copyMenuld F_Printf NULL Copy is on a submenu of the Edit Menu else F_Printf NULL Copy is not on the Edit menu If you want to enumerate the items at all hierarchical levels of a menu keep in mind that a menu item s FP_PrevMenuItemInMenu and FP_NextMenuItemInMenu properties specify menu items or menus only at the same hierarchical level To list all the menu items on a menu you must recursively traverse each of its submenus For example the following function prints the IDs of all the items on a specified menu and its submenus VoidT printMenultemIds menulId F_ObjHandleT menuld F_ObjHandleT itemId itemId F_ApiGetId FV_SessionId menuld FP_FirstMenulItemInMenu while itemId F_Printf NULL Item ID Ox x n itemId if F_ApiGetObjectType menuId itemId FO_Menu FDK Programmer s Guide 165 i Manipulating Commands and Menus with the API printMenultemIds itemId Recursive call itemId F_ApiGetId menulId itemId FP_NextMenulItemInMenu Arranging menus and menu items The API allows you to add a command to multiple menus and to reorder and delete menus and menu items The following sections describe this functionality in detail Adding a command to multiple
204. Custom Ruling and Shading dialog box FrameMaker provides default rulings such as Thick and Thin You can change these rulings or create your own How the API represents ruling formats The API represents a ruling format with an FO_RulingFmt object whose properties provide the following information e The name of the ruling format e Its line width e The gap between lines if the ruling specifies double lines e The ID of the next FO_RulingFmt object in the document Suppose you create the Medium ruling format shown in Figure 14 30 Edit Ruling Style x eam l E E cc g Dop ca e oe FIGURE 14 30 Medium ruling format The API represents this ruling format with an FO_RulingFmt object The following table lists some of its properties Property Type Value FP_Name StringT Medium FP_RulingPenWidth MetricT 2 pts FP_RulingGap MetricT 0 FP_RulingLines IntT 2 How the API organizes ruling formats The API organizes the FO_RulingFmt objects in a document in a linked list The FO_Doc property FP_FirstRulingFmtInDoc specifies the first FO_RulingFmt object in the list Each FO_RulingFmt object has an FP_NextRulingFmtInDoc property which specifies FDK Programmer s Guide 329 14 Frame Document Architecture the ID of the next FO_RulingFmt object in the list The order of the list does not correspond to the order in which the formats appear in the Custom Ruling and Shading dialog box Table Catalo
205. CustomDoc uses the FrameMaker product s default new document template and some parameters that you specify to create the new document e F_ApiOpen allows you to script the New operation For information on creating books see Creating a book on page 146 The following sections describe how to create a new document in greater detail Creating a document with F_ApiSimpleNewDoc To create a new document from a specific template use F_ApiSimpleNewDoc The syntax for F_ApiSimpleNewDoc is F_ObjHandleT F_ApiSimpleNewDoc StringT templateName IntT interactive FDK Programmer s Guide 53 a Executing Commands with API Functions This argument Means templateName The absolute pathname of the template to use For information on how filenames and paths on different platforms are expressed see the FDK Platform Guide for that platform interactive Specifies whether the FrameMaker product displays messages and warnings to the user If you set interactive to True the FrameMaker product creates a document from the specified template and displays messages and warnings to the user If you set interactive to False the FrameMaker product does not display messages and warnings if the FrameMaker product encounters a condition for which it normally displays a dialog box F_ApiSimpleNewDoc attempts to do what s necessary to continue creating the file If F_ApiSimpleNewDoc is successful it returns the ID of the documen
206. D of selected object in active document targetGraphicId F_ApiGetId targetDocId targetDocId FP_FirstSelectedGraphicInDoc if targetGraphicId return Get selected object s current fill pattern fillpatt F_ApiGetInt targetDocId targetGraphicId FP_Fill switch atoi message case UPARROW Only 16 patterns available so reset at 16 if fillpatt 16 fillpatt 0 break case DOWNARROW if fillpatt 0 fillpatt 15 break Set the fill pattern of the selected graphic F_ApiSetInt targetDocId targetGraphicId FP_Fill fillpatt For this example client to work you should have the View Only document and one normal document open Select a graphic in the normal document then click one of the hypertext markers in the View Only document Responding to user initiated events or FrameMaker product operations Your client can respond when the user initiates certain events or FrameMaker product operations For example you may want your client to archive an extra copy of a document each time the user saves it or to display a special dialog box when the user exits a document To make your client respond to events follow these general steps 1 Request notification for the events 2 Create a callback function named F_ApiNotify to respond to the events These steps are discussed in greater detail in the following sections Requesting notification for eve
207. Doc R 576 FP_SuperScriptSize property FO_Doc R 576 FP_SuperScriptStretch property FO_Doc R 576 FP_Symbols property FO_Doc R 551 FP_SymbolsList property FO_Doc R 551 FP_SystemVar property FO_VarFmt G 325 R 673 FP_TableTagging property FO_ElementDef R 647 FP_Tabs property FO_FmtChangeList R 585 FP_Tabs property FO_Pgf R 621 FDK Programmer s Reference amp Guide FP_Tabs property FO_PgfFmt R 629 FP_TailArrow property FO_GraphicObject R 595 FP_TblAlignment property FO_Tbl R 653 FP_TblAlignment property FO_TblFmt R 658 FP_TbIBodyFirstColor property FO_Tbl R 656 FP_TbIBodyFirstColor property FO_TblFmt R 661 FP_TbIBodyFirstFill property FO_Tbl G 336 R 656 FP_TblBodyFirstFill property FO_TblFmt R 661 FP_TblBodyFirstPeriod property FO_Tbl R 656 FP_TbIBodyFirstPeriod property FO_TblFmt R 661 FP_TblBodyNextColor property FO_Tbl R 656 FP_TbIBodyNextColor property FO_TblFmt R 661 FP_TbIBodyNextFill property FO_Tbl R 656 FP_TblBodyNextFill property FO_TbIFmt R 661 FP_TbIBodyNextPeriod property FO_Tbl R 657 FP_TbIBodyNextPeriod property FO_TblFmt R 661 FP_TbIBodyRowRuling property FO_Tbl G 336 R 655 FP_TbIBodyRowRuling property FO_TblFmt G 331 R 660 FP_TbIBodyRowRulingPeriod property FO_Tbl R 655 FP_TbIBodyRowRulingPeriod property FO_TblFmt R 660 FP_TblIBodyShadeBy property FO_Tbl R 657 FP_TblIBodyShadeBy property FO_TbIFmt R 661 FP_TblBottomRuling property FO_Tbl R 655 FP_TblBott
208. Document Architecture Table Designer x omas M Ee om ies Heaton Feoratueg OOOO Double AE Trin el thin Thin E Insert Table Format A FIGURE 14 31 Table Catalog format The following table lists some of the properties of the FO_Tb1Fmt object that represents Format A Property Type Value FP_Name StringT Format A FP_TblInitNumCols IntT 5 FP_TblInitNumHRows IntT al FP_Tb1ColRuling F_ObjHandleT ID of FO_RulingFmt object that represents the Thin line ruling FP_Tb1BodyRowRuling F_ObjHandleT ID of FO_RulingFmt object that represents the Thin line ruling FP_Tb1HFSeparatorRuling F_ObjHandleT ID of FO_RulingFmt object that represents the Double line ruling How the API organizes Table Catalog formats The API organizes the formats in the Table Catalog in a linked list The FO_Doc object property FP_FirstTblFmtInDoc specifies the ID of the first FO_Tb1Fmt object in the list Each FO_Tb1Fmt object has an FP_NextTblFmtInDoc property which specifies the ID of the next FO_Tb1Fmt object in the list The order of the list does not correspond to the order in which the formats appear in the Table Designer FDK Programmer s Guide 331 14 Frame Document Architecture 332 FrameMaker allows you to insert tables into text When you insert a table a table anchor symbol L appears on the screen at the point where you inserted it What the user sees Tables are useful for organizing information in cell
209. FE_BadOperation FDK Programmer s Guide 75 a Executing Commands with API Functions When you or the user straddle table cells the FrameMaker product does not delete any of the FO_Cel1l1 objects that represent the cells It links the paragraphs from the straddled cells into a single list The FP_FirstPgf and FP_LastPgf properties of each cell in the straddle specify the first and last paragraphs in this list Example The following code straddles the first two cells in the first column of a table F_ObjHandleT docId tableId firstrowId celllId Get IDs of document table first row and first cell docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tableId F_ApiGetId FV_SessionId docId FP_FirstTblInDoc firstrowIld F_ApiGetId docId tableId FP_FirstRowInTbl cellId F_ApiGetId docId firstrowId FP_FirstCellInRow If there are two cells in the row straddle them if F_ApiGetInt docId tableId FP_TblNumCols lt 2 F_ApiAlert Not enough columns FF_ALERT_CONTINUE_NOTE else F_ApiStraddleCells docId celllId 1 2 T lt Executing Structured FrameMaker commands The following sections describe how to programmatically execute FrameMaker commands Manipulating elements The API provides several functions that allow you to execute basic FrameMaker commands that manipulate elements The syntax for these functions is VoidT F_ApiDemoteElement F_ObjHandl
210. FO_ElementDef object with the following properties Property Type Value FP_Name StringT Item FP_ElementPgfFormat StringT item FP_NextElementDefInDoc F_ObjHandleT ID of the next FO_ElementDef object in the Element Catalog FP_Element InCatalog IntT True FP_GeneralRule StringT lt TEXT gt FP_ObjectType IntT FV_FO_CONTAINER FP_Comment StringT For normal body paragraphs FP_TextFmtRules F_IntsT The ID of the element definition s text format rule For a list of this format rule s properties see How the API represents format rules and format rule clauses on page 345 Format rules and format rule clauses An element definition can contain several format rules each of which can contain several format rule clauses What the user sees Format rules and format rule clauses allow the template builder to specify the formats an element has in specific circumstances A format rule can be either a context rule or a level rule A context rule contains clauses that specify an element s formatting based on its parent and sibling elements For example one clause of a format rule could specify that a Para element has the FirstBody paragraph format if it is the first child of a Heading element Another clause could specify that a Para element has the Body paragraph format in all other contexts A level rule contains clauses that specify an element s formatting based on the level to which i
211. FO_TblFmt R 660 FP_TblInitNumHRows property FO_TblFmt G 331 R 660 FP_TblInLockedTi property FO_Tbl R 653 FP_TblLastBodyRuling property FO_Tbl R 655 FP_TblLastBodyRuling property FO_TblFmt R 661 FP_TblLeftIndent property FO_Tbl R 653 R 659 FP_TbiLeftIndent property FO_TblFmt R 659 FP_TblLeftRuling property FO_Tbl R 655 FP_TblLeftRuling property FO_TblFmt R 661 FP_TblNumbering property FO_Tbl R 654 FP_TblNumbering property FO_TblFmt R 659 FP_TblINumCols property FO_Tbl G 156 R 654 FP_TblINumRows property FO_Tbl G 156 R 654 FP_TblOtherBodyRowRuling property FO_Tbl R 655 FP_TblOtherBodyRowRuling property FO_TbiFmt R 661 FP_TblOtherColRuling property FO_Tbl R 655 FP_TblOtherColRuling property FO_TblFmt R 661 FP_TbIPlacement property FO_Tbl R 653 FP_TblPlacement property FO_TblFmt R 659 FP_TblRightIndent property FO_Tbl R 654 FP_TblRightIndent property FO_TblFmt R 659 FP_TblRightRuling property FO_Tbl R 655 FP_TblRightRuling property FO_TblFmt R 661 FP_TblSpaceAbove property FO_Tbl R 654 FP_TblSpaceAbove property FO_TblFmt R 659 FP_TblSpaceBelow property FO_Tbl R 654 FP_TblSpaceBelow property FO_TblFmt R 659 FP_TblTag property FO_Tbl R 654 index 63 os Index Reserved Names FP_TblTag property FO_TblFmt R 659 FP_TblTitleGap property FO_Tbl R 658 FP_TblTitleGap property FO_TblFmt R 659 FP_TblTitlePosition property FO_Tbl R 658 FP_TbITitlePosition property FO_TblFmt R
212. FP_MinFontSize property FO_Doc R 568 FP_MinHang property FO_Flow R 580 FP_MinJLetSpace property FO_FmtChangeList R 583 FP_MinJLetSpace property FO_Pgf R 613 FP_MinJLetSpace property FO_PgfFmt R 622 FP_MinJRomSpace property FO_FmtChangeList R 583 FP_MinJRomSpace property FO_Pgf R 613 FP_MinJRomSpace property FO_PgfFmt R 622 FP_MinLeading property FO_Doc R 568 FP_MinLeftIndent property FO_Doc R 568 FP_MinLeftMargin property FO_Doc R 568 FP_MinRightIndent property FO_Doc R 568 FP_MinRightMargin property FO_Doc R 568 FP_MinSpace property FO_FmtChangeList R 583 FP_MinSpace property FO_Pgf R 621 FP_MinSpace property FO_PgfFmt R 629 FP_MinSpaceAbove property FO_Doc R 568 FP_MinSpaceBelow property FO_Doc R 568 FP_MinSpread property FO_Doc R 568 FP_MinStretch property FO_Doc R 568 FP_MinTabPosition property FO_Doc R 568 FP_MinTopMargin property FO_Doc R 568 FP_Mintracking property FO_Doc R 568 FP_MinVal property FO_DlgScrollBar R 536 FP_Mode property FO_Command R 526 FP_MoveTabs property FO_FmtChangeList R 585 FP_Name property FO_Book G 353 R 496 FP_Name property FO_BookComponent R 511 FP_Name property FO_CharFmt R 517 FP_Name property FO_Color R 519 FP_Name property FO_CombinedFontDefn R 522 FP_Name property FO_Command R 523 FP_Name property FO_CondFmt R 529 FP_Name property FO_Doc G 97 R 548 FP_Name property FO_ElementDef G 344 R 647 FP_Name property FO_Flow R 580 F
213. FV_HypertextUnrecognizedCommand constant FP_HypertextParseErr R 553 FV_HypertextUnrecognizedObjectType constant FP_HypertextValidateErr R 554 FV_HypertextUsesDefaultText constant FP_HypertextValidateErr R 554 FV_HypertextValid constant FP_HypertextValidateErr R 554 FV_ImportedByCopy status flag FS_ImportStatus R 195 FV_ImportedFilteredFile status flag FS_ImportStatus R 196 FV_ImportedGraphicFile status flag FS_ImportStatus R 196 FV_ImportedMakerDoc status flag FS_ImportStatus R 196 FV_ImportedMIF status flag FS_ImportStatus R 195 FV_ImportedSgmI1Doc status flag FS_ImportStatus R 196 FV_ImportedText status flag FS_ImportStatus R 195 FV_ImportedXmlDoc status flag FS_ImportStatus R 196 FV_ImportFileNotReadable status flag FS_ImportStatus R 195 FV_ImportTextTable status flag FS_ImportStatus R 195 FV_INCLUSION constant F_ElementCatalogEntryT R 113 FV_InsertionPointInFootnote status flag FS_ImportStatus R 196 FV_InsertionPointInTableCell status flag FS_ImportStatus R 196 FV_InsertionPointNotInText status flag FS_ImportStatus R 195 FV_InsufficientMemory status flag FS_ImportStatus R 195 FV_LANG_BRAZILIAN API language constant F_LanguageNumber R 397 FV_LANG_BRITISH API language constant F_LanguageNumber R 397 FV_LANG_CANADIAN_FRENCH API language constant F_LanguageNumber R 397 FV_LANG_CATALAN API language constant F_LanguageNumber R 397 FV_LANG_DANISH API language constan
214. F_ApiDeallocateTab function R 11 R 74 F_ApiDeallocateTabs function R 11 R 74 F_ApiDeallocateTextItem function R 74 F_ApiDeallocateTextItems function G 112 R 11 R 74 F_ApiDeallocateUBytes function R 11 R 74 F_ApiDeallocateUInts function R 11 R 74 F_ApiDeallocateVal function R 74 F_ApiDefineAndAddCommand function G 26 G 27 G 30 G 166 R 3 R 75 F_ApiDefineAndAddMenu function G 27 G 30 R 3 R 35 R 37 R 77 F_ApiDefineCommand function G 166 R 3 R 35 R 81 F_ApiDefineMenu function R 3 R 35 R 37 R 82 F_ApiDelete function G 158 G 167 R 3 R 15 R 22 R 24 R 83 F_ApiDeleteCols function G 158 R 22 R 84 R 85 F_ApiDeletePropByName function R 9 R 86 F_ApiDeleteRows function G 158 R 22 R 84 R 87 F_ApiDeleteText function G 121 R 23 R 88 F_ApiDeleteTextInsetContents function G 237 R 24 R 90 F_ApiDeleteUndefinedAttribute function R 91 F_ApiDemoteElement function R 92 F_ApiDialogEvent function G 7 G 214 G 216 G 217 G 220 G 221 G 224 G 225 R 1 R 6 R 92 F_ApiDialogItemId function G 212 G 217 R 5 R 94 F_ApiDoneCommand function R 25 R 96 F_ApiElementDefIsText function R 96 F_ApiErr function R 96 F_ApiFamilyFonts function R 8 R 99 R 117 F_ApiFcodes function G 74 R 7 R 101 disadvantage of G 75 F_ApiFind function R 23 R 102 F_ApiFindXSessionAddress function R 106 F_ApiForkAndExec function R 107 F_ApiGetAttributeDefs functio
215. F_ApiSetMetric to set these properties For example the following code increases a selected object s width by 10 points FDK Programmer s Guide 99 aes Getting and Setting Properties define pts MetricT 65536 Frame metric point F_ObjHandleT docId objId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Get ID of selected object objId F_ApiGetId FV_SessionId docId FP_FirstSelectedGraphicInDoc Get object s current width and add 10 points to it if objId F_ApiSetMetric docId objid FP_Width F_ApiGetMetric docId objId FP_Width 10 pts If you set the FP_Height and FP_Width properties of a polyline or polygon the API changes all the object s vertices proportionally If you want to change a polygon or polyline s vertices independently use F_ApiSetPoints tosetits FP_Points property For an example of how to set the FP_Points property see F_ApiSetPoints on page 295 of the FDK Programmer s Reference All graphic objects have an FP_Locx property which specifies the distance of the object s leftmost point from the left side of the parent frame and an FP_LocY property which specifies the distance of the object s uppermost point from the top of its parent frame To change an object s location within a frame use F_ApiSetMetric to set these properties Moving graphics forward or back in the draw order FrameMaker maintains the graphic objects in each frame i
216. F_ReadLongs function R 10 R 428 F_ReadShorts function R 10 R 430 F_Realloc function R 12 R 431 F_ReallocHandle function R 12 R 432 F_RenameFile function R 8 R 434 F_ResetByteOrder function G 382 R 10 R 435 F_ResetDirHandle function R 8 R 435 F_Scanf function R 10 R 436 F_SetAssert function G 378 R 437 F_SetByteOrder function G 382 R 10 R 438 F_SetDSExit function G 379 R 12 R 439 F_SprintfQ function G 369 R 10 R 440 F_Sscanf function R 10 R 441 F_StrAlphaToInt function G 381 R 20 R 441 F_StrAlphaToReal function R 20 R 442 F_StrBrkQ function R 19 R 443 F_StrCat function G 370 R 19 R 443 F_StrCatCharN function R 19 R 444 F_StrCatDblCharNEnc function R 20 R 445 F_StrCatIntNQ function R 19 R 446 F_StrCatNQ function R 19 R 446 F_StrCatNEnc function R 20 R 447 F_StrChrQ function R 19 R 448 F_StrChrEnQ function R 20 F_StrChrEnc function R 449 F_StrCmpQ function G 370 G 381 R 19 R 450 F_StrCmpN Q function R 19 R 451 F_StrCmpNEnc Q function R 20 R 451 F_StrCopyString function R 18 R 452 F_StrCpyQ function G 370 R 18 R 453 F_StrCpyNOQ function R 18 R 453 F_StrCpyNEnc function R 20 R 454 F_StrEqual function G 370 R 19 R 455 F_StrEqualNQ function R 19 R 456 F_StrICmpQ function R 19 R 457 F_StrICmpEnc function R 20 R 457 F_StrICmpN function R 19 R 458 F_StrICmpNEnc function R 20 R 459 F_StrIEqual function R 19 R 460 F_StrIEqualEnc function R
217. F_StrCpyNEnc Parsing an encoded string For the characters in a given string you might need to know whether a character is single byte whether a single byte is the first or last byte of a double byte character or whether two consecutive bytes comprise a valid double byte character The API has the following functions that map the given byte or bytes to the specified encoding BoolT F_CharIsDoubleByteFirst UCharT char FoneEncIdT feld BoolT F_CharIsDoubleByteSecond UCharT char FoneEncIdT feld BoolT F_CharIsDoubleByte UCharT firstChar UCharT secondChar FoneEncIdT feld Example The following code checks each character in a string to see whether it is one byte or two and increments by the correct amount StringT dbEncString UCharT currChar IntT i 0 FontEncIdT feld feId F_FontEncId ConStringT JISX0208 ShiftJIS Assume there is a Japanese string in dbEncString We do not need to also check if the second byte is null as all of the supported encodings do not have 0 in their FDK Programmer s Guide 139 Manipulating Asian Text valid range while dbEncString i 0 if F_CharIsDoubleByte dbEncString i dbEncString it 1l feld This is a double byte character i i 2 else This is either a true single byte char or the second byte was not a double byte seco
218. F_UBytes facet F_ApiSetUBytesByName The syntax for these functions is similar to other F_ApiGetPropertyType and F_ApiSetPropertyType functions except that you must identify the property with a character string instead of an integer For example the syntax for F_ApiGetUBytesByName is F_UBytes F_ApiGetUBytesByName F_ObjHandleT docId F_ObjHandleT objId StringT propName This argument Means docId The ID of the document containing the inset objid The ID of the inset whose facet you want to query propName The name of the facet to query For the exact syntax of the functions that get and set facets look up the functions in Chapter 2 FDK Function Reference in the FDK Programmer s Reference Getting and setting facets takes an additional step not needed with other properties committing the transaction After executing a series of gets or sets for a graphic inset s facets commit the transaction by getting or setting a facet named For example the following code gets two facets and commits the transaction IntT myInt err MetricT myMetric F_ObjHandleT docId insetId myInt F_ApiGetIntByName docId insetId myinteger facet myMetric F_ApiGetMetricByName docId insetId mymetric facet err F_ApiGetIntByName docId insetId If you are setting facets you commit the transaction by setting a facet named For example define in MetricT 72 65536 264 FD
219. FmtInDoc property FO_PgfFmt G 282 R 627 FP_NextPgfInDoc property FO_Pgf G 304 R 620 FP_NextPgfInFlow property FO_Pgf G 304 G 328 R 620 FP_NextRowInTbl property FO_Row G 336 R 651 FP_NextRubiInDoc property FO_Rubi R 630 FP_NextRulingFmtInDoc property FO_RulingFmt G 329 R 630 FP_NextSelectedComponentInBook property FO_BookComponent R 511 FP_NextSelectedGraphicInDoc property FO_GraphicObject G 296 R 594 FP_NextSiblingElement property G 105 FP_NextSiblingElement property FO_Element G 121 R 642 FP_NextSubCol property FO_SubCol G 299 R 521 FP_NextTag property FO_Pgf R 621 FP_NextTag property FO_PgfFmt R 629 FP_NextTblFmtInDoc property FO_TbIFmt G 331 R 659 FP_NextTblInDoc property FO_Tbl R 654 FP_NextTextFrameInFlow property F_ApiNewGraphicObject G 150 FP_NextTextFrameInFlow property FO_TextFrame G 298 R 605 index 57 os Index Reserved Names FP_NextTilnDoc property FO_TextInset R 663 FP_NextVarFmtInDoc property FO_VarFmt G 326 R 673 FP_NextVarInDoc property FO_Var G 327 R 672 FP_NextXRefFmtInDoc property FO_XRefFmt G 323 R 531 FP_NextXRefInDoc property FO_XRef G 324 R 530 FP_NumAtEnd property FO_FmtChangeList R 584 FP_NumAtEnd property FO_Pgf R 613 FP_NumAtEnd property FO_PgfFmt R 623 FP_Numbers property FO_Doc R 551 FP_Num Cols property FO_Doc R 559 FP_NumColumns property FO_TextFrame R 606 FP_Numltems property FO_DialogResource R 53
220. FrameMaker displays the Windows view with the updated layout For a summary of keyboard shortcuts see the section Summary of keyboard shortcuts on page 209 Manipulating the dialog box and its items When designing the layout of the dialog box you can manipulate the dialog box and its items in the same way that you manipulate standard Frame graphic objects 190 FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client Moving and resizing the dialog box and its items To move the dialog box select it and drag it to its new position To resize the dialog box select it and drag one of its object handles Do not manually resize the height of a multiline text box or a scroll list Multiline text boxes and scroll lists have special properties that define height in terms of the number of lines of text displayed To resize a multiline text box or scroll list set the height of the item in the Object Properties dialog box for the item For details see Setting basic dialog item properties on page 197 Also the length of a label check box or radio button is defined by the length of the text associated with the item To change the length of any of these items specify a shorter or longer string of text for the item Using commands to modify the dialog box and its items You can use the following commands from the Graphics menu when working with a dialog box and its items e Group e Ungroup only on items you
221. G 212 R 535 FP_Labels property FO_DlgScrollBox G 212 R 537 FP_Language property FO_CharFmt R 516 FP_Language property FO_FmtChangeList R 586 FP_Language property FO_Pgf R 618 FP_Language property FO_PgfFmt R 626 FP_Language property FO_Session R 635 FP_Language property FO_TextLine R 607 FP_LastAFrame property FO_SubCol R 521 FP_LastAFrame property FO_TextFrame R 605 FP_LastBodyPageInDoc property FO_Doc G 283 G 291 R 540 FDK Programmer s Reference amp Guide FP_LastCell property FO_SubCol R 521 FP_LastCell property FO_TextFrame R 605 FP_LastChildElement property FO_Element R 642 FP_LastFn property FO_SubCol R 521 FP_LastFn property FO_TextFrame R 605 FP_LastGraphicInFrame property FO_AFrame G 85 G 290 G 295 R 597 FP_LastGraphicInFrame property FO_UnanchoredFrame R 608 FP_LastGraphicInGroup property FO_Group G 296 R 599 FP_LastMasterPageInDoc property FO_Doc G 283 G 291 R 540 FP_LastPgf property FO_Cell G 76 G 337 R 650 FP_LastPgf property FO_Fn G 328 R 581 FP_LastPgf property FO_SubCol R 521 FP_LastPgf property FO_Tbl G 333 R 658 FP_LastPgf property FO_TextFrame G 304 R 605 FP_LastPgfRules property G 108 FP_LastPgfRules property FO_ElementDef G 343 R 647 FP_LastRefPageInDoc property FO_Doc G 283 G 291 R 540 FP_LastRowInTbl property FO_Tbl G 336 R 654 FP_LastSubCol property FO_TextFrame G 299 R 605 FP_LastTextFrameInFlow property FO_Flow
222. G 332 properties of G 330 to G 331 G 332 versus table properties G 332 tagging existing tables with G 330 See also table formats table cells See cells table columns adding to tables G 156 to G 157 function for R 14 R 22 R 34 to R 35 index 29 oe Index Subjects deleting from tables G 158 to G 159 function for R 22 R 84 as references to cells G 157 selecting G 118 Table Designer illustrated G 331 specifying ruling formats G 329 table footnote properties See document properties table formats G 330 to G 331 basic properties R 658 changing G 330 G 332 general properties R 659 new table properties R 660 overriding G 332 properties of R 658 to R 662 ruling properties R 660 to R 661 shading and color properties R 661 to R 662 See also Table Catalog formats Table menu name used to specify G 25 R 76 Table of Contents documents generating R 321 TOC flows on G 289 table ruling formats See ruling formats table selections getting and setting G 118 tables G 281 G 332 to G 338 adding rows to G 156 to G 157 function for R 14 R 22 R 39 to R 41 adding table columns to G 156 to G 157 function for R 14 R 22 R 34 to R 35 API representation of G 281 G 332 to G 338 basic properties R 653 creating G 148 to G 149 G 154 to G 156 functions for R 15 R 22 R 224 to R 226 deleting R 83 function for R 22 R 83 deleting rows from G 158 to G 159 functions for R 22 R 84 R 87 to R 88 deleting table columns from G 158 to G 159 function
223. ING you know the encoding has changed and you must get the encoding for the next string text item For more information see FTI_CharPropsChange on page 314 and FTF_ENCODING on page 315 Special issues with double byte encodings Following are some special issues to keep in mind when working with double byte text 140 FDK Programmer s Guide Manipulating Asian Text Decimal tabs The F_TabT data structure describes an individual tab stop It includes a field for a character such as a period or a comma for decimal aligned tab stops FrameMaker only supports single byte characters to align tab stops Offsets into strings Unless otherwise noted in the FDK Programmers Reference string functions that return an offset into the string express the offset in terms of characters and not bytes This should keep your existing code viable For example code to set text locations and text ranges should still work even for text that contains double byte text To get the count of characters in an encoded string use F_StrLenEnc This function returns the number of characters in the string even though some characters might be single byte and others might be double byte Remember that double byte encodings reserve single byte space for certain characters The syntax for F_StrLenEnc is IntT F_StrLenEnc ConStringT s FontEncIdT feid This argument Means s The string whose characters you want to count feId The ID o
224. Id itemName F_ApiGetString FV_SessionId itemId FP_Label if F_StrEqual itemName Database break itemId F_ApiGetId FV_SessionId itemId FP_NextMenuItemInSession F_Free itemName Determining a session s menu configuration The F_ApiGetNamedOb ject function indicates only whether a command or menu exists It does not indicate whether it appears on a menu To determine whether a command or menu appears on a specific menu call F_ApiMenuItemInMenu The syntax for F_ApiMenuItemInMenu is FDK Programmer s Guide Manipulating Commands and Menus with the API 9 F_ObjHandleT F_ApiMenuItemInMenu F_ObjHandleT menuld F_ObjHandleT menuitemId BoolT recursive This argument Means menuld The menu or menu bar to search menuitemId The ID of the menu item or menu to search for recursive Flag specifying whether to search the submenus on the menu specified by menuld Specify True to search them F_ApiMenuItemInMenu returns the ID of the menu on which it finds the specified menu or menu item If it finds the menu or menu item on a submenu of the menu specified by menutld it returns the ID of the submenu For example the following code determines whether the Copy menu item is on the Edit menu or any of its submenus F_ObjHandleT copyCmdId editMenulId copyMenuld editMenuld F_ApiGetNamedObject FV_SessionId FO Menu EditMenu copyCmdId F_ApiGetNamedOb ject FV_SessionId FO_
225. Id amp elemSelect beg FDK Programmer s Guide 151 az Creating and Deleting API Objects 152 The following code adds a highest level element named Appendix to the main flow of the active document F_ObjHandleT docId elemId chapEdefId F_TextLocT tl Get IDs of document main flow and element definition docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc chapEdefId F_ApiGetNamedObject docId FO_ElementDef Appendix Set up text location for beginning of main flow tl objId F_ApiGetId FV_SessionId docId FP_MainFlowInDoc tl offset 0 Insert the new element elemId F_ApiNewElement docId chapEdefId amp tl Creating format rules format rule clauses and format change lists To create format rules format rule clauses and unnamed format change lists in FrameMaker documents and books use F_ApiNewSubObject The syntax for F_ApiNewSubObject is F_ObjHandleT F_ApiNewSubObject F_ObjHandleT docOrBookId F_ObjHandleT parentId IntT property This argument Means docOrBookId The ID of the document in which to create the new object parentId The ID of the object s parent object property The property of the parent object to associate with the new object F_ApiNewSubObject allows you to associate the new object with a specified property of its parent object For example you can create an FO_FmtRule object as the suffix format
226. Id F_ApiGetId 0 FV_SessionId FP_ActiveDoc if docId F_Sprintf msg The active document s ID is 0x x docId F_ApiAlert msg FF_ALERT_CONTINUE_NOTE Get ID of the first document in list of open documents docId F_ApiGetId 0 FV_SessionId FP_FirstOpenDoc Traverse list of open documents and display their IDs while docId F_Sprintf msg The document s ID is 0x x docId F_ApiAlert msg FF_ALERT_CONTINUE_NOTE docId F_ApiGetId FV_SessionId docId FP_NextOpenDocInSession T FDK Programmer s Guide 83 aes Getting and Setting Properties 84 This code displays the ID of the active document twice because the active document is included in the list of open documents The linked list of open documents in a session isn t in any particular order The first document in the list is not necessarily the active document or the first document that was opened Another way to get a document ID is to use F_ApiSimpleOpen F_ApiOpen or F_ApiSimpleNewDoc to open or create the document These functions all return the IDs of the document they open or create Traversing lists of objects in a document Once you have the ID of a document you can query its properties to get to the lists of objects that it contains The document has a number of properties that point to these lists For example the document s FP_FirstGraphicInDoc property specifies the ID of the fi
227. IntT 256 bookId F_ApiGetId 0 FV_SessionId FP_ActiveBook if dateStamp F_Sprintf log_msg log b d d d o d os bookiId docId objid StringT FM_PRINT_DATESTAMP else F_Sprintf log_msg log b d d d o d os bookId docId objid errmsg F_ApiCallClient BookErrorLog log_msg F_ApiDeallocateString amp log_msg 362 FDK Programmer s Guide Frame Development Environment FDE FDK Programmer s Guide 363 364 FDK Programmer s Guide Introduction to FDE This chapter provides an overview of how the FDE works and how to use it to write portable FDK clients It also provides a simple example a portable filter that you can run right away The FDE helps make your clients portable by providing platform independent alternatives to platform specific input output I O string and memory schemes With the FDE you can run your client on all FrameMaker products with minimal effort The FDE also provides libraries of utility functions that are useful for filter development How the FDE works The FDE consists of the following e A virtual environment e Utility libraries Figure 16 1 shows the components of the FDE and their relationship to a client All of the platform specific code is contained within the virtual environment Client F g 2 gt gt 2 gt 5 5 l g E a 3 3 88 4 s5 2 8 en T
228. K Programmer s Guide Using Imported Files and Insets 12 F_ObjHandleT docId insetId F_ApiSetMetricByName docId insetId mymetric facet 2 in F_ApiSetIntByName docId insetId 0 Commit To get and set F_UBytesT facets follow the special procedures described in the following sections Getting an F_UBytesT facet Because an F_UBytesT facet can contain large amounts of data it is not feasible to return all the data in a single array Calling F_ApiGetUBytesByName returns only the next chunk of a facet s data To get all the data for an F_UBytesT facet you must call F_ApiGetUBytesByName repeatedly until F_UBytesT len is 0 For example the following code gets all the bytes in a facet named my facet F_ObjHandleT docId insetId F_UBytesT aUBytes do aUBytes F_ApiGetUBytesByName docId insetId my facet Code to do something with aUBytes goes here while aUBytes len F_ApiGet UBytesByName docId insetId Commit transaction Setting an F_UBytesT facet To setan F_UBytesT facet that contains a relatively small chunk of data you call F_ApiSetUBytesByName once To setan F_UBytesT facet that contains a large chunk of data you must call F_ApiSetUBytesByName multiple times passing a small chunk of data each time The size of the data chunk you pass depends on the platform you are using For example on UNIX platforms you should use about 10K In general if you use a larg
229. LL updateReturn A property list that returns information about how the FrameMaker Paramspp product updated the book IMPORTANT Always initialize the pointer to the property list that you specify for updateReturnParamspp to NULL before you call F_ApiUpdateBook To call F_ApiUpdateBook do the following 1 Initialize the pointer to the updateReturnParamspp property list to NULL 2 Create an updateParamsp property list You can get a default list by calling F_ApiGetUpdateBookDefaultParams or you can create a list from scratch 3 Call F_ApiUpdateBook 4 Check the Update status Check the returned values in the updateReturnParamspp list for information about how the FrameMaker product updated the book 5 Deallocate the updateParamsp and updateReturnParamspp property lists Steps 2 4 and 5 are discussed in the following sections Creating an updateParamsp script with F_ApiGetUpdateBookDefaultParams The API provides a function named F_ApiGetUpdateBookDefaultParams that creates a default updateParamsp property list If you are setting a number of properties it is easiest to use this function get the default property list and then change individual properties as needed The syntax for F_ApiGetUpdateBookDefaultParams is F_PropValsT F_ApiGetUpdateBookDefaultParams FDK Programmer s Guide 357 me Frame Book Architecture The following table lists some of the properties in the prop
230. Line parentFrameId The ID of the parent frame in which to create the object You can create a graphic object only in a frame To create a graphic object directly on a page not in an anchored or unanchored frame you create it in the page frame A page frame is an invisible frame that every page has For more information on page frames and how FrameMaker organizes graphics see How the API represents graphic objects on page 294 The API maintains a frame s child objects in a linked list The order of this list corresponds to the back to front draw order If the frame you specify for parentFramelId already has child objects F_ApiNewGraphicOb ject adds the new object to the end of the linked list that is it puts it in front of the other objects in the frame The API automatically updates the properties of the parent frame and the last object in the list to reflect the addition of the new object For instructions on moving objects forward or back in the draw order see Moving graphics forward or back in the draw order on page 100 F_ApiNewGraphicObject uses a set of arbitrary default values for the properties of the graphic objects that it creates Usually you will need to change most of these default properties Example To draw a circle with a one inch diameter directly on the current page of a document use the following code define in MetricT 65536 72 F_ObjHandleT docId pageId pFrameId circleld
231. Link constant FP_HypertextParsedCmdDestObjType R 557 FV_ObjectElement constant FP_HypertextParsedCmdDestObjType R 557 FV_ObjectGraphic constant FP_HypertextParsedCmdDestObjType R 557 FV_ObjectMarker constant FP_HypertextParsedCmdDestObjType R 557 FV_ObjectPgf constant FP_HypertextParsedCmdDestObjType R 557 FV_ObjectTextInset constant FP_HypertextParsedCmdDestObjType R 557 FV_ObjectUnknown constant FP_HypertextParsedCmdDestObjType R 557 index 73 os Index Reserved Names FV_ObjectXref constant FP_HypertextParsedCmdDestObjType R 557 FV_SaveFmtBinary for F_ApiGetSaveDefaultParams G 62 R 154 FV_SaveFmtBinary60 for F_ApiGetSaveDefaultParams G 62 R 154 FV_SaveFmtFilter for F_ApiGetSaveDefaultParams R 154 FV_SaveFmtInterchange for F_ApiGetSaveDefaultParams G 62 R 154 FV_SaveFmtPdf for F_ApiGetSaveDefaultParams G 62 R 154 FV_SaveFmtSgml for F_ApiGetSaveDefaultParams G 62 R 154 FV_SaveFmtStationery for F_ApiGetSaveDefaultParams G 62 R 154 FV_SaveFmtText for F_ApiGetSaveDefaultParams G 62 R 154 FV_SaveFmtViewOnly for F_ApiGetSaveDefaultParams G 62 R 154 FV_SaveFmtXml for F_ApiGetSaveDefaultParams G 62 R 154 FV_STRICTLY_VALID constant F_ElementCatalogEntryT R 113 R 683 FV_T_STRINGS constant F_AttributeDefT R 109 FV_UserCanceledImport status flag FS_ImportStatus R 196 FV_UserCanceledImportBrowser status flag FS_ImportStatus R
232. Macintosh Figure 10 19 shows a DRE file and the dialog box displayed when it is tested FDK Programmer s Guide 205 a Creating Custom Dialog Boxes for Your Client 206 File Edit Format View Special Graphics Table Apply Paragraph Tag Apply Paragraph Tag pecan tag Apply X 1of1 100 z FIGURE 10 19 Dialog box being tested In UNIX versions while you are testing the dialog box as modal you can use a keyboard shortcut to capture an image of the dialog box To set this up include the following line in your Xdefaults file Maker xwdCmd xwd id Swindowid frame gt HOME Screenl xwd To capture an image of the dialog box press Esc d t to display the dialog box as modal and then press Esc d c This invokes the xwd command to capture an image and save it to the file SHOME Screen1 xwd A simple example This section provides an example of how to create a simple dialog box named pgftag For instructions on writing the client code to implement this dialog box see A simple example on page 215 The dialog box is shown in Figure 10 20 Apply Paragraph Tag ems J Apply FiGURE 10 20 The pgftag dialog box To create the sample dialog box follow these general steps 1 Create a new DRE file For more information see Creating a DRE file on page 185 2 Design the layout of the dialog box FDK Programmer s Guide Creating Custom Dialog
233. MarkerInDoc property FO_Doc G 282 R 538 FP_FirstMarkerTypeInDoc property FO_Doc G 282 R 538 FP_FirstMasterPageInDoc property FO_Doc G 283 G 291 R 538 FP_FirstMenultemInMenu property FO_Menu G 162 R 528 FP_FirstMenultemInSession property FO_Session G 162 R 632 FP_FirstOpenBook property FO_Session G 275 R 632 FP_FirstOpenDoc property FO_Session G 275 R 632 FP_FirstPageNum property FO_BookComponent R 510 FP_FirstPageNum property FO_Doc R 559 FP_FirstPageVerso property FO_Doc R 559 FP_FirstPgf property FO_Cell G 76 G 337 R 650 FP_FirstPgf property FO_Fn G 328 R 581 FP_FirstPgf property FO_SubCol R 521 FP_FirstPgf property FO_Tbl G 333 R 657 FP_FirstPgf property FO_TextFrame G 304 R 605 FP_FirstPgfFmtInDoc property FO_Doc G 283 G 302 R 538 FP_FirstPgfInDoc property FO_Doc G 282 G 304 R 539 FP_FirstPgfRules property G 108 FP_FirstPgfRules property FO_ElementDef G 343 R 646 FP_FirstRefPageInDoc property FO_Doc G 283 G 291 R 539 FP_FirstRowInTbl property FO_Tbl G 336 R 654 FDK Programmer s Reference amp Guide Index Reserved Names a FP_FirstRubiInDoc property FO_Doc G 283 R 539 FP_FirstRulingFmtInDoc property FO_Doc G 283 G 329 R 539 FP_FirstSelectedComponentInBook property FO_Book G 353 R 495 FP_FirstSelectedGraphicInDoc property FO_Doc G 283 G 285 G 296 R 539 R 565 FP_FirstSelectedTiInDoc property FO_Doc R 539 R 565 FP_FirstSubCol propert
234. Master pages Master pages control the layout of body pages Each body page is associated with one master page and each master page can be associated with zero or more body pages A master page provides the following for the body page e The text frame layout which defines the number size and placement of the page s text frames and the column layout within each text frame e The page background which includes graphic objects and text frames such as headers and footers with unnamed flows By default single sided documents have at least one master page which is named Right Double sided documents have two master pages named Right and Left FrameMaker allows you to add your own custom master pages to both single sided and double sided documents When FrameMaker adds a body page it uses a left or right master page object as a background It also copies all the text frames with named flows from that master page to the body page Once the FrameMaker product copies these text frames to the body page they are independent of the text frames on the master page from which they were copied If you change the text frames it does not affect the master page A body page s background appears when you view a body page on the screen or print it However the background is part of the master page and not the body page The FrameMaker product superimposes the body page on the background for displaying and printing If you go to the master page and cha
235. MenuSet property For example the following code switches to quick menus F_ApiSetInt 0 FV_SessionId FP_CurrentMenuSet FV_MENU_QUICK You can t switch to custom menus unless you have already loaded a custom menu file To load a custom menu file call F_ApiLoadMenuCustomizationFile Manipulating menu item separators You can manipulate menu item separators FO_MenuItemSeparator objects the same way you manipulate menus and menu items with the following limitations e If there is more than one separator on a menu each separator must have a different name e A separator can t be the first or the last item on a menu e Separators can t appear next to each other FrameMaker provides six predefined separators Separator Separatorl1 Separator2 Separator3 Separator4 and Separator5 To get the ID of one of these separators use F_ApiGetNamedOb ject as follows F_ObjHandleT separatorId separatoriId F_ApiGetNamedOb ject FV_SessionId FO_MenulItemSeparator Separatorl1 You can use any predefined separator name when you add a separator to a menu For example you could use the predefined separator name Separator5 for the first separator you add to a menu However you should try to use the predefined separator name that corresponds to a separator s position among the separators on a menu For example the first separator on a menu should use the predefined separator name Separator1 and the second separat
236. NextSiblingElement property Adding and deleting text To add and delete text use F_ApiAddText and F_ApiDeleteText The syntax for these functions is F_TextLocT F_ApiAddText F_ObjHandleT docId F_TextLocT textLocp StringT text This argument Means docId The ID of the document to which you ll add text textLocp The point in text text location at which you ll add text text The text to add IntT F_ApiDeleteText F_ObjHandleT docId F_TextRangeT textRangep This argument Means docId The ID of the document to delete text from textRangep The text range to delete F_ApiAddText returns the text location at the end of the text that was added F_ApiDeleteText deletes any objects such as tables and markers anchored in the text it deletes To add text to or delete text from a text inset you must first unlock it by setting its FP_TiLocked property to False After you are done adding or deleting text relock the inset by setting its FP_TiLocked property to True To specify special characters line breaks or paragraph breaks when you add text use octal codes within the text string For example to specify an em dash use 321 For more information on special characters see How the API represents special characters on page 316 For a list of the characters in the FrameMaker product character set and the corresponding codes see Character Sets in your FrameMaker product user d
237. O_DlgScrollBar G 212 R 536 FP_State property FO_DlgScrollBox G 212 R 537 FP_State property FO_DlgTriBox G 212 R 537 FP_StatusLine property FO_Book G 353 R 496 FP_StatusLine property FO_Doc G 98 R 548 FP_StopCountingAt property FO_FmtRule R 590 FP_Stretch property FO_CharFmt R 517 FP_Stretch property FO_Doc R 575 FP_Stretch property FO_FmtChangeList R 587 FP_Stretch property FO_Pgf R 615 FP_Stretch property FO_PgfFmt R 625 FP_Stretch property Text location R 671 FP_StretchChange property FO_FmtChangeList R 587 FP_Strikethrough property FO_CharFmt R 517 FP_Strikethrough property FO_Doc R 575 FP_Strikethrough property FO_FmtChangeList R 587 FP_Strikethrough property FO_Pgf R 615 FP_Strikethrough property FO_PgfFmt R 625 FP_Strikethrough property text location R 671 FP_Strings property FO_Doc R 551 FP_StructuredApplication property FO_Book R 505 FP_StructuredApplication property FO_Doc R 569 FP_StyleOverride property FO_CondFmt R 529 FP_StyleOverrides property FO_Doc R 575 FP_StyleOverrides property FO_Row R 652 FP_StyleOverrides property text location R 671 FP_SubFmtRule property G 107 FP_SubFmtRule property FO_FmtRuleClause R 592 FP_SubScriptShift property FO_Doc R 576 FP_SubScriptSize property FO_Doc R 576 FP_SubScriptStretch property FO_Doc R 576 FP_SuffixRules property G 108 FP_SuffixRules property FO_ElementDef G 343 R 647 FP_SuperScriptShift property FO_
238. PI represents the table itself with the following objects e An FO_Tb1 object e One or more FO_Row objects e One or more FO_Cell objects FO_TblI and table formats FO_Tbl properties provide the following information e The table format tag name e Formatting such as alignment and rulings e The number of columns and rows e The ID of the paragraph in the table s title FDK Programmer s Guide Frame Document Architecture 14 e IDs of FO_Row objects that represent the first and last rows in the table e ID ofthe next FO_Tbl object in the document e The element IDs of the table table title table heading table body table footing elements if the table is a structured table in a FrameMaker document FO_Tb1 formatting properties are the same as FO_Tb1Fmt formatting properties except they do not include properties such as FP_Tb1lInitNumHRows that specify the initial numbers of rows or columns The table title If a table has a title the FO_Tb1 properties FP_FirstPgf and FP_LastPgf specify the IDs of the first and last FO_Pgf objects in the title Rows The API represents each row in a table with an FO_Row object FO_Row properties provide the following information about a table row e Its type heading body or footing e Whether it is kept with the previous row the next row or both when a page break occurs within the table e Its maximum and minimum allowable height e The IDs of the FO_Row objects that re
239. PI specification of G 276 to G 277 R 8 weights API specification of G 276 to G 277 G 316 R 8 footnote anchors API representation of G 312 G 313 R 166 R 687 defined G 389 illustrated G 328 Footnote command G 327 Footnote Properties dialog box G 327 footnote references See footnote anchors footnote separators G 327 footnote text frames G 327 footnotes G 281 G 327 to G 328 API representation of G 281 G 327 to G 328 document properties for G 284 G 327 R 572 footnote separators G 327 illustrated G 328 properties of G 327 to G 328 R 581 to R 582 text frames for G 327 See also footnote anchors forking a new process function for R 107 format change list properties R 582 to R 589 adding G 106 getting and setting G 106 removing G 107 format change lists G 346 adding properties G 106 advanced properties R 582 API representation of G 346 FDK Programmer s Reference amp Guide Index Subjects a Asian character spacing properties R 583 autonumber properties R 584 basic properties R 584 changing G 106 creating G 152 functions for R 221 to R 224 font properties R 585 general properties R 582 getting the IDs of named R 136 pagination properties R 588 properties of R 582 to R 589 removing properties G 107 table cell properties R 589 Format menu name used to specify G 25 R 76 format rule clause properties setting G 107 format rule clauses G 344 API representation of G 345 creating G 152 functions for R 221 to R 224 settin
240. P_Color property FO_FmtChangeList R 585 FP_Color property FO_GraphicObject R 593 FP_Color property FO_Pgf R 614 FP_Color property FO_PgfFmt R 623 FP_Color property text location R 669 FP_ColorOverprint property FO_Color R 519 FP_ColorPrintCtl property FO_Color R 519 FP_ColorTintPercent property FO_Color R 519 FP_ColorViewCtl property FO_Color R 519 FP_ColumnsAreBalanced property FO_TextFrame R 605 FP_CombinedFontFamily property FO_CharFmt R 515 FP_CombinedFontFamily property FO_Doc R 574 FP_CombinedFontFamily property FO_FmtChangeList R 586 FP_CombinedFontFamily property FO_Pgf R 614 FP_CombinedFontFamily property FO_PgfFmt R 623 FP_CombinedFontFamily property text location R 669 FP_CommandNum property FO_Command R 524 FP_Comment property FO_ElementDef G 344 R 645 FP_ComponentElement property FO_BookComponent G 355 R 514 FP_ComponentIsSelected property FO_BookComponent R 509 R 510 FP_CondFmtIsShown property FO_CondFmt R 529 FP_CondFmtIsShown property FO_Doc R 574 FP_CondFmtIsShown property FO_Row R 651 FP_ContentHeight property FO_Cell R 649 FP_ContentHeight property FO_Fn R 581 FP_ContentHeight property FO_SubCol R 520 FP_ContentHeight property FO_Tbl R 653 FP_ContentIsLooselyValid property FO_Element R 643 FP_ContentIsStrictly Valid property FO_Element R 643 FDK Programmer s Reference amp Guide Index Reserved Names as FP_ContentNeededAtBegin p
241. P_FirstCellInRow property FO_Row G 336 R 651 FP_FirstCharFmtInDoc property FO_Doc G 283 G 311 R 538 FP_FirstChildElement property FO_Element G 121 R 642 FP_FirstColorInDoc property FO_Doc G 282 R 538 FP_FirstCombinedFontDefnInDoc property FO_Doc G 283 R 538 FP_FirstCommandInSession property FO_Session G 162 R 632 FP_FirstComponentInBook property FO_Book G 353 G 354 R 495 FP_FirstCondFmtInDoc property FO_Doc G 283 G 311 R 538 FP_FirstElementDefInDoc property FO_Book R 504 FP_FirstElementDefInDoc property FO_Doc R 566 FP_FirstElementDefInDocInDoc property FO_Doc G 283 FP_FirstFlowInDoc property FO_Doc G 283 G 298 G 299 R 538 FP_FirstFmtChangeListInDoc property FO_Book R 504 FP_FirstFmtChangeListInDoc property FO_Doc R 566 FP_FirstFn property FO_SubCol R 521 FDK Programmer s Reference amp Guide FP_FirstFn property FO_TextFrame R 605 FP_FirstFnInDoc property FO_Doc G 283 R 538 FP_FirstGraphicInDoc property FO_Doc G 84 G 282 G 295 R 538 FP_FirstGraphicInFrame property FO_AFrame G 85 G 290 G 295 R 597 FP_FirstGraphicInFrame property FO_UnanchoredFrame R 608 FP_FirstGraphicInGroup property FO_Group G 296 R 599 FP_FirstIndent property FO_FmtChangeList R 584 FP_FirstIndent property FO_Pgf R 619 FP_FirstIndent property FO_PgfFmt R 626 FP_FirstIndentChange property FO_FmtChangeList R 584 FP_FirstIndentIsRelative property FO_FmtChangeList R 584 FP_First
242. P_FmtRule F_ObjHandleT ID of the FO_Rule object that contains the format rule clause FP_RuleClauseType IntT FV_RC_CHANGELIST Format change lists A format change list describes a set of changes to paragraph format properties What the user sees A format rule clause can use format change lists to specify how a paragraph format changes when the format rule clause applies A change list can specify a change to just a single paragraph property or it can specify changes to a long list of properties A change list can specify absolute values or relative values For example it can specify that the paragraph left indent is one inch or it can specify that it is one inch greater than the inherited left indent A change list can be named or unnamed A named change list appears in the Element Catalog Format rule clauses that use a named change list specify its name or tag Multiple rule clauses can specify the same named change list An unnamed change list appears in a rule clause It is used only by the rule clause in which it appears How the API represents format change lists The API uses an FO_FmtChangeList object to represent each change list in a document FO_FmtChangeList properties provide the following information about a change list 346 FDK Programmer s Guide Frame Document Architecture 14 e The ID of the next change list in the document s list of change lists e Its name if it is a named change list e A parag
243. P_Name property FO_FmtChangeList G 347 R 582 R 584 FP_Name property FO_HiddenPage R 611 FP_Name property FO_Marker R 609 FP_Name property FO_MasterPage R 612 FP_Name property FO_Menu R 523 FP_Name property FO_MenultemSeparator R 523 FP_Name property FO_Pgf G 217 G 303 R 621 FDK Programmer s Reference amp Guide FP_Name property FO_PgfFmt G 274 R 629 FP_Name property FO_RefPage R 612 FP_Name property FO_RulingFmt G 329 R 630 FP_Name property FO_Tbl G 336 FP_Name property FO_TblFmt G 331 R 659 FP_Name property FO_TextInset G 236 R 663 FP_Name property FO_UnanchoredFrame R 608 FP_Name property FO_VarFmt R 672 FP_Name property FO_XRefFmt G 323 R 531 FP_Namespace property FO_Element R 643 FP_NamespaceScope property FO_Element R 643 FP_NarrowRubiSpaceForKanji property FO_Doc R 564 FP_NarrowRubiSpaceForOther property FO_Doc R 564 FP_NewElemAttrDisplay property FO_Book R 504 FP_NewElemAttrDisplay property FO_Doc R 568 FP_NewElemAttrEditing property FO_Book R 504 FP_NewElemAttrEditing property FO_Doc R 569 FP_NextAFrame property FO_AFrame R 597 FP_NextCell property FO_Cell R 650 FP_NextCellInRow property FO_Cell R 650 FP_NextCellInTbl property FO_Cell R 650 FP_NextCharFmtInDoc property FO_CharFmt G 310 R 517 FP_NextColorInDoc property FO_Color R 519 FP_NextCombinedFontDefnInDoc property FO_CombinedFontDefn R 522 FP_NextCommandInSession property FO_C
244. P_Sensitivity property FO_DlgPopUp G 212 G 219 R 535 FP_Sensitivity property FO_DlgRadioButton G 212 G 219 R 535 FP_Sensitivity property FO_DlgScrollBar G 212 G 219 R 536 FP_Sensitivity property FO_DlgScrollBox G 212 G 219 R 537 FP_Sensitivity property FO_DlgTriBox G 212 G 219 R 537 FP_SeparateInclusions property FO_Book R 504 FP_SeparateInclusions property FO_Doc R 569 FP_SepOverride property FO_CondFmt R 529 FP_SepOverride property FO_Doc R 575 FP_SepOverride property FO_Row R 652 FP_SepOverride property text location R 671 FP_SgmlApplication property FO_Book R 505 FP_SgmlApplication property FO_Doc R 569 FP_Shadow property FO_CharFmt R 517 FP_Shadow property FO_Doc R 575 FP_Shadow property FO_FmtChangeList R 587 FP_Shadow property FO_Pgf R 615 FP_Shadow property FO_PgfFmt R 625 FP_Shadow property text location R 671 FP_ShiftOrUnshiftCommand property FO_Command G 174 R 526 index 61 os Index Reserved Names FP_ShowAll property FO_Doc R 550 FP_ShowCondIndicators property FO_Doc R 550 FP_SideHeadGap property FO_TextFrame R 606 FP_SideHeadPlacement property FO_TextFrame R 606 FP_SideHeadRoomInFlow property FO_Flow R 580 FP_SideHeadWidth property FO_TextFrame R 606 FP_SideOffset property FO_AFrame R 597 FP_Size property FO_DlgScrollBar R 536 FP_SkipBlankSeps property FO_Book R 503 FP_SkipBlankSeps property FO_Doc R 563 FP_SmallCapsSize property FO_D
245. Params R 188 FS_UpdateBookMasterPages property F_ApiGetUpdateBookDefaultParams R 188 FS_UpdateBookNumbering property F_ApiGetUpdateBookDefaultParams R 189 FS_UpdateBookOleLinks property F_ApiGetUpdateBookDefaultParams R 189 FS_UpdateBookStatus property F_ApiUpdateBook R 339 status flags of R 339 FS_UpdateBookTextReferences property F_ApiGetUpdateBookDefaultParams R 189 FS_UpdateBookXRefs property F_ApiGetUpdateBookDefaultParams R 189 FS_UpdateBrowserDirectory property F_ApiGetOpenDefaultParams R 144 FS_UpdateFRVList property F_ApiGetSaveDefaultParams R 157 FS_UpdateTextReferences property F_ApiGetOpenDefaultParams R 144 FS_UpdateXRefs property F_ApiGetOpenDefaultParams R 145 FS_UseAutoSaveFile property F_ApiGetOpenDefaultParams R 145 FS_UseDefaultUNIXpermissions property F_ApiGetSaveDefaultParams R 157 FS_UseMainFlow property F_ApiGetImportDefaultParams R 124 FS_UseRecoverFile property F_ApiGetOpenDefaultParams R 145 FT_ FT_ElementCatalog property value type G 273 R 690 FT_Id property value type G 273 R 690 FT_Integer property value type G 273 R 690 FT_Ints property value type G 273 R 690 FT_Metric property value type G 273 R 690 FT_Metrics property value type G 273 R 690 FT_Points property value type G 273 R 690 FT_String property value type G 273 R 690 FT_Strings property value type G 273 R 690 FT_Tabs property value type G 273 R 690 FT_TextLoc pro
246. PgfFmt objects have the same formatting properties To apply the properties from a paragraph to a Paragraph Catalog format or from a Paragraph Catalog format to a paragraph you can use F_ApiGetProps and F_ApiSetProps For example the following code applies the Paragraph Catalog format named Body to the paragraph containing the insertion point F_PropValsT props F_TextRangeT tr F_ObjHandleT docId pgfId bodyFmtId StringT pgfName docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Get ID of the Body Paragraph Catalog format then get selection bodyFmtId F_ApiGetNamedObject docId FO_PgfFmt Body if bodyFmtId return tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection if tr beg objId 0 return Get properties from the Body Paragraph Catalog format Then apply Body properties to paragraph containing insertion point or the beginning of the text selection FDK Programmer s Guide Getting and Setting Properties 5 ai props F_ApiGetProps docId bodyFmtId if props len 0 return F_ApiSetProps doclId tr beg objId amp props If you have changed the Body format you may want to reapply it to all paragraphs that are tagged Body To change these paragraphs you must traverse every paragraph in the document determine if it s tagged Body and set its properties if it is You can do this by adding the following code to the code shown above pgfId F_ApiGe
247. Programmer s Reference Filetype hint string syntax The FrameMaker product uses filetype hint strings for both graphic and document or text files The hint strings are stored with imported graphics and with text insets You also use hint strings to invoke specific filters from within your API clients For example to save a FrameMaker document as HTML use the following code to specify the HTML hint string InmtT 4 F_PropValsT params docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc params F_ApiGetSaveDefaultParams i F_ApiGetPropIndex amp params FS_FileType params val i propVal u ival FV_SaveFmtFilter i F_ApiGetPropIndex amp params FS_SaveFileTypeHint params val i propVal u sval F_StrCopyString StringT 0001ADBEHTML The syntax of a hint string is record_vers vendor format_id platform filter_vers filter_name Of these record_vers vendor format_id are the minimum required to specify a filter Each field must specify a four byte code except for filter_name which can be up to 31 characters long If necessary you must pad out each field so that it has exactly 4 Alphanumeric characters For example the hint for version 1 of the XML filter must be specified as follows 0001ADBEXML 00001 Note the space padding after the three character code for XML However the last field in a hint string does not need padding In the above example if you did not specify the version number of the XML fil
248. R 33 R 45 to R 46 R 431 allocating blocks of R 32 R 349 R 431 allocating for properties G 94 allocating for property lists G 50 API function for R 11 R 45 to R 46 allocating for text items API function for R 46 allocating with handles FDE functions for G 379 R 32 to R 33 allocating with pointers FDE functions for G 379 R 373 API functions applicable to R 11 R 32 to R 33 R 45 to R 46 R 74 comparing contents of blocks function for R 427 deallocating functions for R 74 deallocating from properties G 94 function for R 74 deallocating from property lists API function for R 11 R 74 deallocating from text items G 112 API function for R 11 FDE functions applicable to G 378 to G 379 R 349 R 370 freeing from clients API function for R 11 R 24 R 48 freeing from handles FDE function for G 379 R 370 R 386 freeing from pointers FDE function for G 379 R 370 R 386 making calls portable G 367 G 378 to G 379 preventing the relocation of FDE function for R 399 See also handles memory blocks associated with pointers memory management memory blocks associated with pointers FDE functions for G 379 R 370 R 373 allocating G 379 R 32 clearing G 379 R 370 comparing R 427 copying R 371 duplicating R 372 freeing G 379 R 386 reallocating R 431 memory calls making portable G 367 G 378 to G 379 replacing with FDE functions G 369 FDK Programmer s Reference amp Guide Index Subjects a memory manageme
249. SO CGM ADB ADB KHTML EXML ADBIRTF Text import and export hint strings The following table lists hint strings for importing and exporting text files To import or export this text Plain text Text ISO Latin 1 Text Roman 8 HEWLETT PACKARD UNIX Text ANSI Windows Text Macintosh Text ASCII Japanese JIS Japanese Shift JIS Japanese EUC Traditional Chinese BIG 5 Use this hint string 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 PG PG PG PG PG PG PG PG PG PG RE EXT XIS XRM MAC TASC JIS SIS BG5 FDK Programmer s Guide Using Imported Files and Insets 12 To import or export this text Use this hint string Traditional Chinese EUC CNS 0001PGRETEUH Simplified Chinese HZ 0001PGRETXHZ Simplified Chinese GB 0001PGRFTXGB Korean 0001PGRETKOR To generate a list of filters for a given session you print out the list of registered import filters and the list of registered export filters The following example gets those lists and prints their contents out to the console VoidT printFilterStrings VoidT F_StringsT importFilters exportFilters UInNeT a F_Printf NULL StringT n n IMPORT FILTERS n n importFilters F_ApiGetStrings 0 FV_SessionId FP_ImportFilters for i 0 i lt importFilters len i F_Printf NULL StringT s n importFilters val i
250. Subjects a responding to user choices of G 29 See also Frame commands Frame product commands committing the transaction in querying and setting facets R 129 common graphic object properties R 592 to R 595 Compare Documents running G 297 specifications for illustrated G 70 comparing documents and books G 68 to G 70 compiling API clients G 8 custom dialog boxes G 177 component documents See book components components of books See book components condition tags G 309 to G 311 conditional text appearance of illustrated G 318 formats G 281 G 284 G 309 to G 311 API representation of G 281 G 309 to G 311 as organized in documents G 311 properties of G 284 G 309 to G 311 R 522 R 528 markers illustrated G 318 prefixes for G 318 conditional text formats See conditional text conditional text markers See conditional text conditions applying to text G 311 properties for R 528 See also conditional text constants defining in MetricT values R 675 to R 677 See also initialization constants notification constants See also property value types and individual constants in the FDK Reserved Names Index container elements structural G 347 content rules of structural element definitions G 342 context rules G 344 context sensitive commands G 173 to G 175 context sensitive help for menu items G 175 to G 176 context sensitive menu items G 173 to G 175 Continue buttons displaying G 18 conventions as used in th
251. The FTI_CharPropsChange text item indicates that the text properties have changed the FTF_WEIGHT flag that it specifies indicates that the font weight has changed e The marker anchor is counted in the offset How the API represents special characters The API uses the FrameMaker product character set Some characters are either reserved by the C language or belong to the higher ASCII range To represent these characters in a string use octal or hexadecimal x sequences Hexadecimal Octal Character representation representation gt x3e 76 straight double quotation mark x22 42 left curved quotation mark xd2 322 right curved quotation mark xd3 323 For a complete list of the characters in the FrameMaker product character set and the corresponding hexadecimal codes see your Frame product user s manual If you are using 316 FDK Programmer s Guide Frame Document Architecture CE ANSI C you can use these hexadecimal codes or their octal equivalents If you are not using ANSI C you must use octal sequences Suppose you want to represent the following text in the API This is an em dash If you are not using ANSI C you must specify the string This is an em dash 321 If you are using ANSI C you can also specify the string This is an em dash xdl How the API represents text properties The FTI_CharPropsChange text item only indicates that particular text properties have changed It does
252. Using FrameMaker to design a dialog box To edit dialog box information through FrameMaker you open a special type of file called a Frame dialog resource DRE file As Figure 10 2 shows when you open a DRE file in FrameMaker it translates the dialog box information into a graphic representation of the dialog box This is similar to opening a Frame binary document in FrameMaker When you open a Frame binary document FrameMaker translates the document information into a graphic representation of the document 178 FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client 10 FrameMaker LON i Open i Save Frame binary document Frame binary document Representation pf the document Ff Open f Ee Save 1 i Representation o the dialog box DRE file DRE file FiGuRE 10 2 Comparison between opening a Frame binary file and a DRE file The rest of this section describes Frame DRE files and how FrameMaker interprets these files Frame DRE files A DRE file is a text file that uses special syntax to describe a dialog box and its items The following lines from a DRE file illustrate how the DRE file syntax describes the OK button in a dialog box lt Button lt MBaseLine 10 327 92 gt lt WBaseLine 59 231 53 gt lt XBaseLine 63 368 64 gt lt Label OK gt lt Active No gt lt HypertextHelp clnthelp button gt gt 29
253. _ApiGetTextProps F_ObjHandleT doclId F_TextLocT textLocp This argument Means docId The ID of the document containing the character textLocp The text location of the character that you want to get text properties for The returned properties are the properties that apply to the character to the right of the specified location propNum The text property suchas FP_FontFamily or FP_FontSize that you want to get The API allocates the returned properties Use F_ApiDeallocatePropVal or F_ApiDeallocatePropVals to free the properties when you re done with them FDK Programmer s Guide 123 o 6 Manipulating Text 124 You can get the text properties for only one character at a time because they can be different for each character For more information on how the API represents characters and text properties see How the API represents text on page 312 Example The following code gets the name of the character tag for the character to the right of the insertion point F_TextRangeT tr F_PropValT prop F_ObjHandleT doc Id Get the current insertion point docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection if tr beg objId return prop F_ApiGetTextPropVal docId amp tr end FP_CharTag F_Printf NULL The character tag is s n prop propVal u sval Setting text properties To set the text properties for a t
254. _BARS flag F_ApiCompare G 69 R 65 FF_CMP_COMPKIT flag F_ApiCompare G 69 R 66 FF_CMP_HYPERLINKS flag F_ApiCompare G 69 R 65 index 44 FF_CMP_SUMKIT flag F_ApiCompare G 69 R 66 FF_CMP_SUMMARY_ONLY flag F_ApiCompare G 69 R 65 FF_Custom_FirstPageLeft flag F_ApiCustomDoc G 56 R 71 FF_Custom_FirstPageRight flag F_ApiCustomDoc G 56 R 71 FF_Custom_SingleSided flag F_ApiCustomDoc G 56 R 71 FF_CUT_TBL_CELLS flag F_ApiClipboardFunction G 128 R 57 R 72 FF_DONT_APPLY_ALL_ROWS flag F_ApiPaste G 128 R 246 FF_DONT_DELETE_HIDDEN_TEXT flag F_ApiClipboardFunction G 128 R 57 R 73 R 246 FF_FilePathDirectory bit flag F_FilePathProperty R 382 FF_FilePathExist bit flag F_FilePathProperty R 382 FF_FilePathFile bit flag F_FilePathProperty R 382 FF_FilePathReadable bit flag F_FilePathProperty R 382 FF_FilePathWritable bit flag F_FilePathProperty R 382 FF_INSERT_BELOW_RIGHT flag F_ApiPaste G 128 R 246 FF_INTERACTIVE flag F_ApiClipboardFunction G 128 R 57 R 68 R 72 R 246 FF_REPLACE_CELLS flag F_ApiPasteQ G 128 R 246 FF_STRIP_HYPERTEXT flag F_ApiClipboardFunction R 68 FF_UFF_COLOR flag F_ApiSimpleImportFormats G 72 R 324 FF_UFF_COMBINED_FONTS flag F_ApiSimpleImportFormats G 72 FF_UFF_CombinedFont flag F_ApiSimpleImportFormats R 324 FF_UFF_COND flag F_ApiSimpleImportFormats G 72 R 324 FF_UFF_DOCUMENT_PROPS flag F_ApiSimpleImportFormats
255. _BookComponent FO_Pgf FO_BookComponent FO_Element FO_FmtRule FO_FmtRuleClause FO_FmtChangeList unnamed FO_Tbl FO_Tbl FO_Var FO_XRef FO_Cell FO_Row FO_Inset FO_TiFlow FO_TiText FO_TiTextTable Use F_ApiNewGraphicObject F_ApiNewAnchoredOb ject F_ApiNewSeriesOb ject F_ApiNewBookComponent InHierarchy F_ApiNewElement gt F_ApiNewElement InHierarchy F_ApiNewSubOb ject F_ApiNewTable F_ApiNewAnchoredFormattedOb ject F_ApiAddCols F_ApiAddRows F_ApiAddRows F_Apilmport FDK Programmer s Guide Creating and Deleting API Objects a To create objects of this type Use FO_Command F_ApiDefineCommand F_ApiDefineAndAddCommand FO_Menu F_ApiDefineMenu F_ApiDefineAndAddMenu FO_Doc F_ApiOpen F_ApiSimpleNewDoc F_ApiCustomDoc a To create a flow you must create a text frame See Creating flows on page 150 b You can also create new elements with F_ApiWrap and F_ApiSplitElement c For information on creating documents and books see Chapter 4 Executing Commands with API Functions If they succeed these functions return the ID of the object they create If they fail they return O and assign an error code to FA_errno Creating named objects A named object is an object such as a master page or a Paragraph Catalog format that is identified by a unique name To create named objects us
256. _Session R 636 FP_ProductName property FO_Session R 636 FP_Public property FO_Marker R 610 FP_Radius property FO_RoundRect R 604 FP_RectanglelsSmoothed property FO_Ellipse R 598 FP_RectangleIsSmoothed property FO_Rectangle G 3 R 604 FP_Reformatting property FO_Session G 97 R 264 R 636 FDK Programmer s Reference amp Guide FP_RememberMissingFontNames property FO_Session R 636 FP_Required property FO_Marker R 610 FP_ReservedColor property FO_Color R 520 FP_RightColNum property FO_Tbl G 87 R 656 FP_RightIndent property FO_FmtChangeList R 585 FP_RightIndent property FO_Pgf R 619 FP_RightIndent property FO_PgfFmt R 626 FP_RightIndentChange property FO_FmtChangeList R 585 FP_RightMargin property FO_Doc R 561 FP_RightMasterPage property FO_Doc R 540 FP_RowlsShown property FO_Row R 651 FP_RowKeepWithNext property FO_Row G 336 R 652 FP_RowKeepWithPrev property FO_Row R 652 FP_RowMaxHeight property FO_Row R 652 FP_RowMinHeight property FO_Row R 652 FP_RowStart property FO_Row R 652 FP_RowTbl property FO_Row R 652 FP_RowType property FO_Row G 336 R 652 FP_RpcProgramNumber property FO_Session R 636 FP_RpcPropertyName property FO_Session R 636 FP_RubiAlignAtBoundaries property FO_Doc R 564 FP_RubiElement property FO_Rubi R 630 FP_RubiFixedSize property FO_Doc R 564 FP_RubiOverhang property FO_Doc R 564 FP_RubiSize property FO_Doc R 564 FP_RubiTextRange property FO_Rub
257. _diris the directory in which you installed the FDK If you have already created your own DRE files you can select one of them IMPORTANT f your API client uses custom dialog boxes and your client will run on a Japanese system with the Japanese language set as the user interface language then you must use a special template for creating a dre file In the samples dre directory find jtemplat dre to use as a template for Japanese dialog boxes 3 Click Create FrameMaker displays the DRE file in a standard Frame document window The dialog box and its items appear on a single page The dialog box is displayed as a rectangle defining the boundaries of the dialog box Each item in the dialog box is displayed as a special Frame graphic object Although these objects appear to be composed of standard Frame graphic objects for example a checkbox is displayed as a rectangle and a text line you cannot ungroup a dialog item into separate objects A DRE file can describe a number of different types of dialog items including e Boxes e Buttons e Checkboxes e Radio buttons FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client 10 e Text boxes e Multiline text boxes e Pop up menus e Image pop up menus pop up menus that appear as bitmap images e Labels e Scroll bars e Scroll lists When you select an item the document window status bar displays information about the selected item in the
258. a new page and connects a text frame on the new page with the text frame on the previous page Main flows Each document has a main flow Normally the FrameMaker product treats the main flow like any named flow in the document However there are cases when the FrameMaker product treats the main flow specially e When you generate a table of contents or an index the FrameMaker product puts the generated text into the main flow of the generated document e When you run Compare Documents the FrameMaker product puts the Summary text into the main flow Usually the main flow is the default flow for the current language For example if the current language is English the main flow is A If there are several Autoconnect flows in the document with the default flow tag the main flow is the one in the backmost text frame on the frontmost body page FDK Programmer s Guide 297 14 Frame Document Architecture How the API represents flows The API represents a flow with an FO_Flow object whose properties provide the following information e The flow s format characteristics such as the feathering and whether Autoconnect is enabled e The IDs of the first and last FO_TextFrame objects in the flow e The ID of the next FO_Flow object in the document How the API organizes flows The API maintains a document s FO_Flow objects in a linked list The FO_Doc property FP_FirstFlowInDoc specifies the ID of the first FO_Flow object in t
259. able Element ranges in structured tables If FP_SelectedTbl returns NULL the following code determines whether the current element location is within a table as well as the type of the parent element F_ObjHandleT docId F_PropValT propVal F_ElementRangeT er Get the ID of the active document docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc if docId return er F_ApiGetElementRange FV_SessionId docId FP_ElementSelection First check to see if there is a selected table propVal F_ApiGetPropVal FV_SessionId docId FP_SelectedTbl if propVal propVal u ival Now determine whether the current element range is within a table propVal F_ApiGetPropVal docId er beg parentId FP_ElementType if propVal propVal u ival FV_FO_TBL F_Printf NULL StringT You are in a table n else if propVal propVal u ival FV_FO_TBL_ TITLE F_Printf NULL StringT You are in a table title n else if propVal propVal u ival FV_FO_TBL_HEADING F_Printf NULL StringT You are in a table heading n else if propVal propVal u ival FV_FO_TBL BODY F_Printf NULL StringT You are in a table body n else if propVal propVal u ival FV_FO_TBL_FOOTING F_Printf NULL StringT You are in a table footing n else if propVal propVal u ival FV_FO_TBL_ROW F_Prin
260. ages property FO_Book R 502 FP_PrintEvenPages property FO_Doc R 562 FP_PrintFileName property FO_Book R 503 FP_PrintFileName property FO_Doc R 562 FP_PrintImaging property FO_Book R 503 FP_PrintImaging property FO_Doc R 562 FP_PrintInclude property FO_BookComponent R 513 FP_PrintLastSheetFirst property FO_Book R 503 FP_PrintLastSheetFirst property FO_Doc R 562 FP_PrintLowRes property FO_Book R 503 FP_PrintLowRes property FO_Doc R 562 FP_PrintManualFeed property FO_Doc R 562 FP_PrintNumCopies property FO_Book R 503 FP_PrintNumCopies property FO_Doc R 562 FP_PrintOddPages property FO_Book R 503 FP_PrintOddPages property FO_Doc R 562 FP_PrintPaperHeight property FO_Book R 503 FP_PrintPaperHeight property FO_Doc R 562 FP_PrintPaperWidth property FO_Book R 503 FP_PrintPaperWidth property FO_Doc R 563 FP_PrintRegistrationMarks property FO_Book R 503 FP_PrintRegistrationMarks property FO_Doc R 563 FP_PrintRows property FO_Doc R 563 FP_PrintScale property FO_Book R 503 FP_PrintScale property FO_Doc R 563 FP_PrintScope property FO_Doc R 563 FP_PrintSeps property FO_Book R 503 FP_PrintSeps property FO_Doc R 563 FP_PrintStartPage property FO_Doc R 319 R 563 FP_PrintStartPageName property FO_Doc R 563 FP_PrintStartPoint property FO_Doc R 563 FP_PrintThumbnails property FO_Doc R 563 FP_PrintToFile property FO_Book R 503 FP_PrintToFile property FO_Doc R 563 FP_ProcessNumber property FO
261. ags for G 305 See also Character Designer text format text properties Character Designer As Is settings G 306 character formats applying to text G 124 character formats of tagged characters reapplying Paragraph Catalog formats and G 306 character library FDE G 381 G 382 character strings See strings characteristics of objects See properties characters FDE functions for G 381 G 382 R 360 to R 369 converting to lowercase G 382 R 368 converting to uppercase G 382 R 369 determining type of character G 382 R 360 to R 368 specifying special and higher ASCII G 121 G 316 to G 317 R 41 tagging G 306 characters FDE functions for R 369 check marks for menu items G 173 checkboxes in dialog boxes G 199 getting setting the state of function for R 5 properties of G 199 R 533 tri state G 199 R 537 child API objects automatic deletion of G 158 defined G 389 as organized in frames G 147 G 295 child elements structural G 347 traversing G 121 child graphic objects See child API objects clearing text selections G 127 R 3 R 23 R 56 to R 58 client data associating with structural elements G 110 client resources opening function for R 245 client text insets G 230 G 236 to G 238 creating G 236 to G 237 updating G 237 to G 238 See also text insets client defined callback functions R 1 client defined dialog boxes functions for R 1 R 5 R 93 to R 94 client_name defined G 8 clients See API clients FDK Programm
262. aker document and how the fields of the F_ElementRangeT structure specified by the FP_ElementSelection property are set to represent them Selection state No object is selected There is no text selection or insertion point One or more graphic objects are selected There is an insertion point or text selection within an element that has no subelements An entire element or range of elements excluding the highest level element is selected The highest level element is selected What the fields of the F_ElementRangeT structure specify beg parentId 0 childId 0 beg offset 0 beg end parentId 0 end childId 0 end offset 0 beg parent Id ID of the element containing the insertion point or selection beg childtId ID of the child element immediately following the insertion point or the beginning of the text selection beg offset offset of the beginning of the selection or insertion point from the beginning of the element containing it end parent Id ID of the element containing the insertion point or selection end childId ID of the child element immediately following the insertion point or the end of the text selection end offset offset of the end of the selection or insertion point from the beginning of the element containing it beg parent Id ID of the element containing the first selected element beg childtId ID of the first selected element beg offset 0 end
263. aker product to prompt the user for the response Scriptable functions return detailed information on how the FrameMaker product executes a command For example the scriptable Open function F_ApiOpen returns information such as whether the file was filtered and whether an Autosave file was used The API provides a function named F_ApiAllocatePropVals which allocates a property list that you can use with scriptable functions The API also provides functions that create default scripts for the different scriptable functions You can use these functions to get a default script and then customize the script by changing individual properties Opening documents and books The API provides two functions to open a document or book e F_ApiSimpleOpen is an easy to use function for opening a document or book e F_ApiOpen allows you to script the process of opening a document or book Opening a document or book with F_ApiSimpleOpen The syntax for F_ApiSimpleOpen is F_ObjHandleT F_ApiSimpleOpen StringT fileName BoolT interactive 46 FDK Programmer s Guide Executing Commands with API Functions 4 This argument Means fileName The absolute pathname of the file to open For information on how filenames and paths on different platforms are expressed see the FDK Platform Guide for your platform interactive Specifies whether the FrameMaker product displays messages and warnings to the user If F_ApiSimpleOpen is
264. alerts table of G 18 See also alert boxes Alt key keyboard shortcuts Windows G 202 anchor symbol G 294 G 311 G 332 G 389 anchored frames G 294 API representation of G 295 G 312 creating G 148 to G 149 R 217 functions for R 14 R 209 to R 212 defined G 293 G 389 FDK Programmer s Reference amp Guide Index Subjects locating G 294 properties of G 295 R 596 to R 597 See also unanchored frames anchored objects G 148 G 312 R 209 R 210 creating G 148 to G 149 functions for R 14 R 209 to R 212 default properties of G 148 See also anchored frames anchors G 311 G 312 See also anchor symbol anchored frames anchored objects ANSI C specifying special characters G 316 API Frame Application Program Interface G ix G 3 to G 12 R xv advantages and limitations of G xi R xvii closing connection with R 318 disabling G 16 error protection feature G 81 initializing connection with R 330 to R 331 manipulating commands and menus G 161 to G 176 servicing calls to R 277 to R 278 See also API clients API error codes API functions API clients G 3 bailing out of G 15 G 43 to G 44 G 375 G 389 function for R 11 R 24 R 48 calling another client function for R 24 R 49 to R 51 canceling operations function for R 24 changing objects with G 4 closing FDK client connection with the API R 318 communication with the FrameMaker product G 4 communication with the user G 4 compiling G 8 creating G 6 to G 12 example G 9
265. ally FDK Programmer s Guide 293 14 Frame Document Architecture Anchored frames You can draw graphic objects in anchored frames which are tied to text symbols named anchor symbols L An anchor symbol and its anchored frame moves with the text to which it is attached You can specify a variety of parameters that determine where a frame appears in relation to its anchor symbol For example it can be below the line containing the anchor symbol or at the bottom of the text frame containing the anchor symbol Unlike other graphic objects the anchored frame cannot be drawn directly on a page or into another frame it can only be created in text How the API represents graphic objects The API represents each type of graphic object with a different type of API object For example it represents polygons with FO_Polygon objects and text frames with FO_TextFrame objects All types of API graphic objects have properties that provide the following information e The graphic object s format that is characteristics such as its fill pattern and border width e The graphic object s location and angle e IDs of the graphic object s parent sibling and child objects Some format properties do not affect some graphic objects For example an FO_Rectangle object like all other objects has an FP_ArrowType property This property can have a value but that value will not affect the appearance of the rectangle that the object represents
266. alog boxes on Windows The syntax for F_ApiFcodes is IntT F_ApiFcodes IntT len IntT vec This argument Means len The length of the array of f codes in bytes vec The array of f codes to send to the FrameMaker product The following table lists some user actions and the f codes that emulate them User action Move insertion point to first flow on the current page Move insertion point to the start of the next word Move insertion point to the beginning of the next paragraph Center the current paragraph Left justify the current paragraph Make selected text bold F code CSR_TOP CSR_NEXT_BOW CSR_NEXT_BOP PGF_CENTER PGF_LEFT TXT_BOLD For a complete list of f codes see the fcodes h file shipped with the FDK 74 FDK Programmer s Guide Executing Commands with API Functions F_ApiFcodes uses the current focus in a dialog box or a visible document If you want to execute a set of f codes in a particular dialog box or document make sure that the dialog box or document is active To make a dialog box active use f codes such as FOCUS_INPUT_SEARCH and FOCUS_INPUT_PGFFMT To make a document active set the session property FP_ActiveDoc to the document s ID Many f codes perform tasks that API functions also perform Whenever possible try to use the other API functions instead of F_ApiFcodes to perform these tasks F_ApiFcodes does not provide error or status feedback for individual f codes
267. alog resource files G 179 capturing screenshots of G 206 contents of G 186 creating G 185 to G 188 deleting items from G 207 for different platforms G 181 to G 185 editing G 179 G 209 editing dialog box information G 179 to G 181 G 209 example of G 206 and Frame binary files G 178 keyboard shortcuts for G 209 opening G 179 and platform specific views of dialog boxes G 180 to G 181 saving G 180 G 181 G 204 to G 205 G 208 saving dialog box information G 181 to G 185 setting properties of G 193 G 208 testing G 205 G 208 See also dialog boxes dialog items DSE direct straight exit function setting R 439 E Edit Condition Tag dialog box illustrated G 310 Edit menu adding menus to G 28 getting the ID of G 26 name used to specify G 25 R 76 Element Catalog G 342 function for getting entries G 90 structure for entry sets G 271 R 682 structure for individual entries R 682 Element menu name used to specify G 25 index 9 E Index Subjects ellipse properties R 598 encoded text G 132 to G 142 encodings for fonts G 135 to G 137 encodings for the current session G 137 in text items G 140 initializing encoding data G 134 to G 135 inspecting and manipulating G 138 to G 139 parsing G 139 to G 140 Setting the U I encoding G 134 to G 135 special issues G 140 to G 142 decimal tabs G 141 ghost encodings G 141 internal strings G 141 offsets into strings G 141 using encoding data G 134 to G 137 EPSI Encapsulated PostScrip
268. ammer s Reference To determine if a particular FS_UpdateBookStatus bit is set use F_ApiCheckStatus For example the following code determines if an Update operation was canceled because the current book contains duplicate files components that refer to the same file F_PropValsT params returnParamsp NULL F_ObjHandleT bookId Get the active book update and check status bookId F_ApiGetId 0 FV_SessionId FP_ActiveBook params F_ApiGetUpdateBookDefaultParams F_ApiUpdate bookId amp params amp returnParamsp if F_ApiCheckStatus returnParamsp FV_DuplicateFileInBook F_ApiAlert Duplicate files in book FF_ALERT_CONTINUE_NOTE Deallocate property lists F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp FDK Programmer s Guide 359 rE Frame Book Architecture 360 The API provides a utility function named F_ApiPrintUpdateStatus which prints the save error values to the console platforms For more information see F_ApiPrintUpdateBookStatus on page 255 of the FDK Programmer s Reference The following code updates the currently active book The update operation will display the error log for any error conditions will allow inconsistent numbering properties and since the code allows inconsistent numbering will not update the numbering in the book It then prints out the update status Finally the code deallocates
269. ammer s Guide Using Imported Files and Insets This chapter provides instructions for using imported files and insets in your client It discusses the types of imported files and insets and describes how to import files It describes how to write a filter client a client that translates Frame files to or from other file formats It also discusses graphic inset editors clients that save graphics in a format that FrameMaker can import Types of imported files and insets FrameMaker and the Frame API allow you to import graphic and text files by copy and by reference The following sections briefly describe the types of imported files and insets Imported text files When the user imports a text file by copy the FrameMaker product copies the file s text into the FrameMaker product document The FrameMaker product no longer needs the original file to display the text When the user imports a text file by reference the FrameMaker product creates an object called a text inset A text inset contains a locked copy of the imported text It also references the imported text file and specifies how the text is displayed in the FrameMaker product document The FrameMaker product uses the information in a text inset to display the inset s text Each time it updates a text inset the FrameMaker product uses the text in the referenced file to replace the text in the inset There are several types of text insets which correspond to the types of
270. ammer s Guide 261 12 Using Imported Files and Insets 262 Responding to the user launching your inset editor When the user launches your graphic inset editor by choosing it from the Inset Editors scroll list the FrameMaker product calls the editor s F_ApiMessage callback with ob jId set to 0 You can include code in F_ApiMessage that allows the user to create a graphic inset and add it to the Frame document when your editor is launched To insert a graphic inset you add an FO_AFrame object and resize it to accommodate the inset Then you add an FO_Inset object to the frame and set its properties as needed The following code adds an external graphic inset described in the file myinset fi when the user chooses the editor myeditor from the Inset Editors scroll list VoidT F_ApiMessage message docId objId StringT message F_ObjHandleT docId F_ObjHandleT objid 0 if launched from scroll list F_ObjHandleT afrmId insetId F_TextRangeT tr if objId Code that allows user to create a graphic goes here Get the text selection and add frame at the beginning tr F_ApiGetTextRange FV_SessionId doclId FP_TextSelection afrmId F_ApiNewAnchoredObject docId FO_AFrame amp tr beg Code to resize and position frame goes here Add the inset to the frame and set its properties insetId F_ApiNewGraphicObject docId FO_Inset afrmId F_ApiSet String
271. ample if the user clicks in a text box the text box is the focus When the user presses the Tab key the focus moves from one item to the next in a specific order for example if the cursor is in a text box and the user presses the Tab key the focus might move to a button or pop up menu This order is called the focus order of a dialog box The focus order of a dialog box is specified by the order of items in the dialog box For example suppose item 4 is a text box and item 5 is a radio button If the text box has the focus pressing the Tab key moves the focus to the radio button The focus order defines the order in which items are selected when the user presses the Tab key You can change the focus order by changing the order of items in the dialog box To change the focus order follow these steps 1 Select an item in the scroll list 2 Click Up or Down to move the selected item up or down in the list To move the selected item up or down by 5 items at a time press the Shift key while clicking Up or Down When you select an item in the Item Order scroll list the corresponding graphic object in the DRE file also appears selected This helps you to identify the item in the DRE file FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client Dialog Box Properties the DRE file 2 TextBox 4 3 ImagePopUr 0 4 Label 5 PopUp 2 6 Box An item selected PEINT 23 r ih ce 8 Label in the scroll list is
272. ams FS_HowToImport params val i propVal u ival FV_DoByCopy Change properties to disallow nongraphic files i F_ApiGetPropIndex amp params FS_DisallowDoc params val i propVal u ival True i F_ApiGetPropIndex amp params FS_DisallowMIF params val i propVal u ival True i F_ApiGetPropIndex amp params FS_DisallowPlainText params val i propVal u ival True F_Apilmport docId amp tr beg tmp agraphic xwd amp params amp returnParamsp if F_ApiCheckStatus returnParamsp FV_BadImportFileType F_ApiAlert File isn t importable FF_ALERT_CONTINUE_NOTE T 7 wv Deallocate property lists F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp Importing a page of a PDF file The following code shows how to import the specified page of a PDF file Notice that insets for PDF pages have an FP_PageNum property no other insetscreated by FrameMaker use this property You determine the page to display in the inset by setting FP_PageNum where 0 is the first page in the PDF file FDK Programmer s Guide 233 12 Using Imported Files and Insets 234 As of this writing FrameMaker 7 0 the order of these calls is important You must coerce the page display by specifying the page number before setting the path for the inset otherwise FrameMaker will display the first page
273. angle and variation Example The following code loops through the session fonts then loops through the permutations of each and prints the encoding for each permutation to the console F_FontsT fam F_StringsT families weights variations angles FDK Programmer s Guide Manipulating Asian Text StringT encoding UIntT i J Get lists of families variations weights and angles families F_ApiGetStrings 0 FV_SessionId FP_FontFamilyNames weights F_ApiGetStrings 0 FV_SessionId FP_FontWeightNames variations F_ApiGetStrings 0 FV_SessionId FP_FontVariationNames angles F_ApiGetStrings 0 FV_SessionId FP_FontAngleNames Loop through each session font for i 0 i lt families len i Now print the encoding for each variation to the console fam F_ApiFamilyFonts i for j 0 j lt fam len j encoding F_ApiGetEncodingForFont fam val j F_Printf NULL The encoding for s s s s is s n families val fam val j family weights val fam val j weight variations val fam val j variation angles val fam val j angle encoding F_ApiDeallocateString amp encoding Be sure to fr the structures and strings Determining which encodings are currently supported The API has two functions to determine which encodings are supported for the current session F_ApilsEncodingSupported returns True if the passed encoding is currently support
274. aph and the FP_PrevPgfInFlow property of the next paragraph Figure 8 4 shows the paragraph objects in a flow before and afteran FO_Pgf object is deleted FP_NextPgfInF FP_NextPgfInF FO_Pgf FO_Pgf FO_Pgf Paragraph 1 je Paragraph 2 e Paragraph 3 FP_PrevPgfInF FP_PrevPgfInF Before FP_NextPgfInF FO_Pgf FO_Pof Paragraph 1 e Paragraph 3 FP_PrevPgfInF FiGuRE 8 4 FO_Pof objects in a flow before and after deleting an FO_Pgf object After 160 FDK Programmer s Guide Manipulating Commands and Menus with the API This chapter describes Frame API command and menu functionality in detail For an introduction to using commands and menus in your client s interface see Using commands menu items and menus in your client on page 24 How the API represents commands and menus The API uses an FO_Command object to represent each command an FO_Menu object to represent each menu and an FO_MenuItemSeparator object to represent each menu item separator in a FrameMaker product session Figure 9 1 shows a view only menu bar with the File menu open Below you can see a diagram of objects for that menu bar the menus in that menu bar and the items in the File menu FO_Menu FP_FirstMenultemInMenu FO_Menu FP_FirstMenultemInMenu FO_Command ViewOn
275. apter 3 Object Reference in the FDK Programmer s Reference To change a session document or book by setting object properties follow these general steps 1 Find out which objects represent the things you want to change To change something in a session book or document you need to know which objects the API uses to represent it For a description of how the API uses objects to represent things in FrameMaker see Part II Frame Product Architecture FDK Programmer s Guide 81 ee Getting and Setting Properties 82 2 Get the IDs of the objects you want to change To set an object s properties you must specify its ID The API provides functions for retrieving object IDs 3 Manipulate the objects properties The API provides functions for getting and setting individual properties and entire property lists For example the API represents a FrameMaker product session with an FO_Session object You don t need to get a session s ID because there is only one session and its ID is always FV_SessionId To find all the session characteristics you can change look up Session on page 631 in Chapter 3 Object Reference in the FDK Programmer s Reference You can for example change the session s automatic save time The API represents the automatic save time with an integer IntT property named FP_AutoSaveSeconds To set it to 60 seconds use the following code F_ApiSetInt 0 Sessions have n
276. apterRef Figure lt elemparanumonly gt E lt attribute attmame gt FIGURE 14 25 A cross reference format The following table lists some properties of the FO_XRefFmt object that represents this cross reference format Property Type Value FP_Name StringT See Heading amp Page FP_Fmt StringT See lt Sparatext gt on page lt Spagenum gt FP_NextXRefFmt InDoc F_ObjHandleT ID of the next FO_XRefFmt object in the document Cross references A cross reference refers to a specific location known as a source within the current document or another document The source can be either a cross reference marker a type 9 marker or a unique string of text What the user sees When you insert a cross reference you select a cross reference format which specifies the information provided by the cross reference For more information on cross reference formats see Cross reference formats on page 322 How the API represents cross reference instances The API represents each cross reference instance with the following e FTI_XRefBegin and FTI_XRefEnd text items that specify the ID of the FO_XRef object FDK Programmer s Guide 323 14 Frame Document Architecture e An FTI_String text item which provides the text that appears where the cross reference is inserted e EF e e e An FO_XRef object O_XRef properties provide the following information The ID of
277. arFmt R 517 FP_Underlining property FO_Doc R 575 FP_Underlining property FO_FmtChangeList R 588 FP_Underlining property FO_Pgf R 616 FP_Underlining property FO_PgfFmt R 625 FP_Underlining property text location R 671 FP_Unique property FO_BookComponent R 513 FP_Unique property FO_Cell R 651 FP_Unique property FO_Element R 640 FP_Unique property FO_Fn R 581 FP_Unique property FO_GraphicObject R 595 FP_Unique property FO_Marker R 609 FDK Programmer s Reference amp Guide FP_Unique property FO_Pgf R 618 FP_Unique property FO_Rubi R 630 FP_Unique property FO_SubCol R 521 FP_Unique property FO_Tbl R 654 FP_Unique property FO_Text Inset R 663 FP_Unique property FO_Var R 672 FP_Unique property FO_XRef R 530 FP_Untouchable property FO_Doc R 548 FP_UseCapitalization property FO_CharFmt R 517 FP_UseChangeBar property FO_CharFmt R 517 FP_UseCharacteristic properties FO_CharFmt G 308 FP_UseColor property FO_CharFmt R 517 FP_UseFontAngle property FO_CharFmt R 517 FP_UseFontFamily property FO_CharFmt R 518 FP_UseFontSize property FO_CharFmt R 518 FP_UseFontVariation property FO_CharFmt R 518 FP_UseFontWeight property FO_CharFmt R 518 FP_UselnitialStructure property FO_Book R 505 FP_UselnitialStructure property FO_Doc R 569 FP_UseKernX property FO_CharFmt R 518 FP_UseKernY property FO_CharFmt R 518 FP_UseNextTag property FO_Pgf R 621 FP_UseNextTag property FO_PgfFmt R 629
278. arT msg 256 mydocId F_ApiSimpleOpen tmp my doc False Save my doc as itself F_ApiSimpleSave mydocId tmp my doc False Save my doc as mynew doc mynewdocId F_ApiSimpleSave mydocId tmp mynew doc False If the Save As was successful display ID of mynew doc if mynewdocId F_ApiAlert Couldn t save as mynew doc FF_ALERT_CONTINUE_NOTE else F_Sprintf msg The ID of mynew doc is 0x x mynewdoclId F_ApiAlert msg FF_ALERT_CONTINUE_NOTE Saving a document or book with F_ApiSave To save a document or book and specify responses to warnings and messages that the FrameMaker product issues use the scriptable save function F_ApiSave With F_ApiSave you can specify aspects of the Save operation such as the file format for example MIF or Text Only and the UNIX file permissions You can specify all aspects or you can specify some and allow the user to decide others For example you can specify that the FrameMaker product should save a document as Text Only but allow the user to decide how to convert the document s tables to text The syntax for F_ApiSave is F_ObjHandleT F_ApiSave F_ObjHandleT doclId StringT saveAsName F_PropValsT saveParamsp F_PropValsT saveReturnParamspp This argument Means docid The ID of the document or book to save saveAsName The pathname to save the document or book to
279. arator property FO_Pgf R 620 FP_BottomSeparator property FO_PgfFmt R 628 FP_BottomSepAtIndent property FO_FmtChangeList R 583 FP_CanHaveCheckMark property FO_Command G 173 R 524 FP_Capitalization property FO_CharFmt R 515 FP_Capitalization property FO_Doc R 573 FP_Capitalization property FO_FmtChangeList R 585 FP_Capitalization property FO_Pgf R 614 FP_Capitalization property FO_PgfFmt R 623 FP_Capitalization property text location R 669 FP_CellAbovelInCol property FO_Cell R 648 FP_CellAngle property FO_Cell R 648 FP_CellBelowInCol property FO_Cell R 648 FP_CellBottomMargin property FO_FmtChangeList R 589 FP_CellBottomMargin property FO_Pgf R 616 index 47 os Index Reserved Names FP_CellBottomMargin property FO_PgfFmt R 628 FP_CellBottomMarginChange property FO_FmtChangeList R 589 FP_CellBottomMarginFixed property FO_FmtChangeList R 589 FP_CellColNum property FO_Cell R 648 FP_CellDefaultBottomRuling property FO_Cell G 337 R 648 FP_CellDefaultLeftRuling property FO_Cell G 336 R 648 FP_CellDefaultRightRuling property FO_Cell R 648 FP_CellDefaultTopRuling property FO_Cell G 334 R 648 FP_CelllsShown property FO_Cell R 648 FP_CelllsStraddled property FO_Cell G 337 R 648 FP_CellLeftMargin property FO_FmtChangeList R 589 FP_CellLeftMargin property FO_Pgf R 616 FP_CellLeftMargin property FO_PgfFmt R 628 FP_CellLeftMarginChange property FO_FmtChangeList R 5
280. are documentation as such terms are used in 48 C F R 12 212 or 48 C F R 227 7202 as applicable Consistent with 48 C F R 12 212 or 48 C F R 227 7202 1 through 227 7202 4 as applicable the commercial computer software and commercial computer software documentation are being licensed to U S government end users A only as commercial items and B with only those rights as are granted to all other end users pursuant to the terms and conditions set forth in the Adobe standard commercial agreement for this software Unpublished rights reserved under the copyright laws of the United States FDK Programmer s Guide Contents Using Frame Developer Tools 2 6822 ee ee ee ee IX The Frame Developer s Kit 2 aaou a a a a ix Other FrameMaker features for developers 0002 eee eee eee x Choosing the right Frame tools 0 a xi FDK documentation soe s ea aoas d a aa a a a a a a a a xi Naming COnventionS o s ss aa am aa aa aE a a e aa a a A A LA xii Style conventions sa s ses oe ee A eds we A Red ea we xiii Part I Frame Application Program Interface API Chapter 1 Introduction to the Frame API 4 3 How the API works 3 26 2 2 anG a Ye bag ela gaa yea Seabee eb ea De ees 3 Special types of clients o oo a a a 5 Portability cS GA a a ae Ee A eee a ee de PG wk ded Gh we a 6 Running clients with different FrameMaker product interfaces 6 Creating and runni
281. as UNIX support the concepts of user home SFMHOME and current directories The following code displays the names of these directories for the current session include futils h StringT homeDir fmhomeDir currentDir UCharT msg 512 Get directory names homeDir F_ApiGetString 0 FV_SessionId FP_UserHomeDir fmhomeDir F_ApiGetString 0 FV_SessionId FP_FM HomeDir currentDir F_ApiGetString 0 FV_SessionId FP_FM_ CurrentDir F_Sprintf msg Home dir s FMHOME s Current dir s homeDir fmhomeDir currentDir la Display the directory names in an alert box F_ApiAlert msg FF_ALERT_CONTINUE_NOTE Free the strings F_Free homeDir F_Free fmhomeDir F_Free currentDir Disabling redisplaying to avoid screen flicker If you change numerous properties at once it may cause screen flicker an effect that occurs when the FrameMaker product executes a long series of changes that aren t user initiated By default FrameMaker reformats the document after each change You can avoid screen flicker by batching changes To batch changes set the FO_Session property FP_Displaying to False As long as FP_Displaying is setto False the FrameMaker product does not refresh the documents in the current session when you or the user changes them To refresh the documents you must call F_ApiRedisplay for each changed document The syntax for F_ApiRedisplay is IntT F_ApiRedi
282. bT val Structures that describe the tabs F_TabsT The F_TabT structure is defined as typedef struct MetricT x Offset from paragraph s left margin UCharT type Constant for tab type e g FV_TAB_RIGHT StringT leader Characters before tab e g UCharT decimal Character for decimal tab e g F_TabT When you get the tabs for a paragraph or paragraph format the API returns them in left to right order in the val array However when you insert a tab you don t have to insert it in this order You just add it to the end of the val array When you call F_ApiSetTabs the API sorts the tabs for you For example the following code adds a 4 inch decimal tab to the Body paragraph format include fmemory h define in MetricT 65536 72 F_ObjHandleT docId pgfFmtId F_TabsT tabs Get the ID for the Body paragraph format docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc pgfFmtId F_ApiGetNamedObject docId FO_PgfFmt Body if pgfFmtId return Get the tabs and allocate space for new tab tabs F_ApiGetTabs docId pgfFmtId FP_Tabs if tabs len tabs val F_TabT F_Realloc tabs val tabs len sizeof F_TabT NO_DSE else tabs val F_TabT F_Alloc sizeof F_TabT NO_DS Gl lt Add the tab tabs val tabs len 1 type FV_TAB_ DECIMAL tabs val tabs len 1 x 4 in tabs val tabs len 1 decimal
283. bject s FP_FirstPgf property In some cases the first text frame in the flow may not contain any paragraphs You must traverse subsequent text frames and check them to see if they contain any paragraphs Each FO_Pgf objecthas FP_PrevPgfInFlow and FP_NextPgfInFlow properties which specify the IDs of the FO_Pgf objects before and after it in the flow To get the paragraphs in a flow in order you traverse these properties It is possible for a paragraph to begin in one text frame and end in another When this happens the ID of the FO_Pgf is specified by the FP_LastPgf property of the text frame in which it begins and the FP_FirstPgf property of the text frame in which it ends Suppose you create two text frames and connect them with a flow The first text frame has two paragraphs in it the second paragraph continues into the next text frame as shown in Figure 14 15 Tires Bi ia i teat Conan 2 which begins and endsin This is paragraph 3 which begins and text column 1 ends i in text column 2 This is paragraph 2 which begins intext columnl FIGURE 14 15 Flow with two text frames The API organizes the objects that represent the flow text frames and paragraphs as shown in Figure 14 16 FDK Programmer s Guide Frame Document Architecture 14
284. bject to the next If you only want the ID for a single named object it is usually easier to use F_ApiGetNamedOb ject The syntax for F_ApiGetNamedOb ject is F_ObjHandleT F_ApiGetNamedObject F_ObjHandleT docId IntT ob jType StringT name This argument Means docId The ID of the document or book containing the object objType The type of object for example FO_VarFmt name The name of the object for which to get the ID For example the following code gets the ID of the Paragraph Catalog format named Body in the active document 88 FDK Programmer s Guide Getting and Setting Properties s F_ObjHandleT docId pgfFmtId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc pgfFmtId F_ApiGetNamedObject docId FO_PgfFmt Body Getting IDs for objects that have persistent identifiers FrameMaker assigns a persistent unique identifier UID to each object in a document that isn t identified by a name The UID unlike the object s ID does not change from one session to another No matter how many times you open and exit a document an object s UID remains the same It is important to note that cut and paste functions will assign new UID s to the text For example conditionalizing text will change a paragraph s UID To get an object s UID you query its FP_Unique property with F_ApiGetInt If you already know an object s UID you can find its ID in the current session by calling F_ApiGetUniqueObj
285. bjiId amp amp tr beg offset tr end offset return tis F_ApiGetTextForRange docId amp tr FTI_String Getting and setting table selections If a table contains cells that are selected you can get the table s ID by querying the document property FP_SelectedTb1 For more information see Getting the IDs of selected tables and table rows on page 87 If a range of text that includes several tables is selected you can get the tables IDs by calling F_ApiGetText and retrieving the FTI_TblAnchor text items for the selection Each FTI_TblAnchor text item specifies the ID of a table To make the selection in a document include several tables set the text selection so that it includes the text that contains the tables anchors To make the selection include specific rows and columns within a single table call F_ApiMakeTb1Selection For more information see F_ApiMakeTblSelection on page 201 of the FDK Programmer s Reference FDK Programmer s Guide Manipulating Text 6 If the current element range is within a cell or if it indicates a selected table part you can get the table s ID by querying the document property FP_SelectedTbl However it s possible for a client to set the current element range to a point between table part elements In this case the document property FP_SelectedTbl is NULL For this reason you cannot always use FP_SelectedTbl to determine whether the current element range is in a t
286. bles the menu item FV_ENABLE_IS_TEXT_SEL Text is selected in a paragraph or a graphic text line FV_ENABLE_IN_TEXT_LINE The insertion point or selection is in a graphic text line For a complete list of the values FP_EnabledWhen can have see FO_Command on page 523 of the FDK Programmer s Reference When you create a command FP_EnabledWhen has the default value FV_ENABLE_ ALWAYS ENABLE To completely disable a command set its FP_EnabledWhen property to FV_ENABLE_ALWAYS DISABLE To reenable a command reset FP_EnabledWhen to FV_ENABLE_ALWAYS_ENABLE To enable a command only ina specific context set its FP_EnabledwWhen property to one of the other listed values For example the following code creates a command that is enabled only when text is selected F_ObjHandleT cmdId cmdId F_ApiDefineCommand 1 Transpose Transpose Words F_ApiSetInt FV_SessionId cmdId FP_EnabledWhen FV_ENABLE IS _TEXT_SEL If a command is a menu item it appears dimmed when it is disabled You can determine whether a menu item is disabled by getting its FP_MenuItemIsEnabled property This is easier than getting its FP_EnabledWhen property and determining whether the specified context currently applies You can t set the FP_MenuItemIsEnabled property Using shift menu items FrameMaker provides several shift menu items menu items that change wh
287. book is named C MyDocs book1 book and has three documents myDoc1 fm myDoc2 fm and myDoc3 fm D C MyDocs book1_book x w C MyDocs book1 book E myDocl fm myDoc2 fm B FIGURE 15 1 A book with three components 352 FDK Programmer s Guide Frame Book Architecture jo The API represents mybook book with one FO_Book object and three FO_BookComponent objects The following table lists some of the FO_Book object s properties Property Type Value FP_Name StringT C MyDocs book1 book FP_NextOpenBookInSession F_ObjHandleT 0 FP_FirstComponent InBook F_ObjHandleT ID of FO_BookComponent object for myDoc1 fm FP_FirstSelectedComponent F_ObjHandleT ID of FO_BookComponent InBook object for myDoc3 fm FP_StatusLine StringT Empty string the status line currently displays no text FP_TypeOfDisplayText IntT FV_BK_FILENAMF The following code shows how to get properties from the selected book component First it gets the active book and then the first selected component in the active book For the book in Figure 15 1 the component would be for myDoc3 fm For the selected component the code prints out the method the component uses to compute footnote numbering Then if the footnote numbering uses custom characters for footnotes daggers etc the code prints out the custom numbering string VoidT F_ApiCommand command IntT command F_ObjHandleT bookId compId StringT n
288. box is a separate dialog item Some items such as checkboxes already have labels Since text boxes do not have labels you need to add a separate label oe Tag o FiGURE 10 10 Dialog item with a separate label s Use Global Definitions s n s FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client 10 A label is considered to be a separate dialog item if it is not part of a button checkbox or radio button To add a label select a separate label then copy and paste it Deleting items from a dialog box To delete an item from a dialog box select the item and press the Delete key Note that by deleting an item you break the sequence of item numbers For example if you delete item 3 the sequence of item numbers skips from 2 to 4 You need to renumber the items so that the sequence is unbroken To renumber the items in a dialog box follow these steps 1 Select the dialog box 2 From the Graphics menu choose Object Properties FrameMaker automatically renumbers the items 3 Click OK to dismiss the Dialog Box Properties dialog box Setting the properties of the dialog box The graphic object that represents a dialog box has special properties that you must set when you create a new DRE file To set the properties for a DRE file follow these steps 1 In the DRE file select the rectangle representing the dialog box 2 From the Graphics menu choose Object Properties The Dialog Box P
289. box named pgftag as a modeless dialog box For instructions on creating this dialog box see A simple example on page 206 The pgftag dialog box contains a text box that displays the paragraph tag of the paragraph containing the insertion point The user can change the paragraph tag by typing a different tag in the text box and clicking the Apply button Following the code is a line by line description of how it works 1 include fapi h 2 define APPLY BUTTON 1 3 define TAG FIELD 2 4 define DLG_NUM 1 5 F_ObjHandleT dlgId 0 6 7 VoidT F_ApilInitialize init 8 Intr init 9 10 dlgId F_ApiOpenResource FO_DialogResource pgftag 11 F_ApiModelessDialog DLG_NUM dlgId 12 F_ApiNotification FA_Note_BackToUser True 13 14 15 VoidT F_ApiNotify notification docId filename iparm 16 IntT notification 17 F_ObjHandleT docId 18 StringT filename 19 IntT iparm 20 21 F_TextRangeT tr 22 StringT tag 23 24 Get tag of first paragraph in selection 25 docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc 26 tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection 27 if tr beg objId return No text selected in document 28 tag F_ApiGetString docId tr beg objId FP_Name 29 FDK Programmer s Guide 215 En Handling Custom Dialog Box Events 30 F_ApiSetString dlgId F_ApiDialogI
290. c R 577 FP_ViewDisplayUnits property FO_Doc R 577 FP_ViewFontSizeUnits property FO_Doc R 578 FP_ViewFormattingBar property FO_Session R 637 FP_ViewGrid property FO_Doc R 578 FP_ViewGridUnits property FO_Doc R 578 FP_ViewNoGraphics property FO_Doc R 578 FP_ViewOnlyDeadCodes property FO_Book R 507 FP_ViewOnlyDeadCodes property FO_Doc R 578 FP_ViewOnlyMenuBar property FO_Doc R 557 R 578 FP_ViewOnlySelect property FO_Doc R 579 FP_ViewOnlyWinBorders property FO_Book R 507 FP_ViewOnlyWinBorders property FO_Doc R 579 FP_ViewOnlyWinMenuBar property FO_Book R 507 FP_ViewOnlyWinMenuBar property FO_Doc R 579 FP_ViewOnlyWinPalette property FO_Doc R 548 R 579 FP_ViewOnlyWinPopup property FO_Book R 507 FP_ViewOnlyWinPopup property FO_Doc R 579 FP_ViewOnlyXRef property FO_Doc R 579 FP_ViewPageScrolling property FO_Doc R 578 FP_ViewQuickAccessBar property FO_Session R 637 FP_ViewRulers property FO_Doc R 578 FP_ViewRulerUnits property FO_Doc R 578 FP_ViewTextSymbols property FO_Doc R 578 FP_Visibility property FO_DialogBox R 533 FP_Visibility property FO_DlgButton R 533 FP_Visibility property FO_DlgCheckBox R 533 FP_Visibility property FO_DlgEditBox R 534 FP_Visibility property FO_DlgImage R 534 FP_Visibility property FO_DlgLabel R 534 FP_Visibility property FO_DlgPopup R 535 FP_Visibility property FO_DlgRadioButton R 535 index 65 os Index Reserved Names FP_Visibility prope
291. called text filter clients Filter clients that filter graphic file formats are called graphic filter clients The following sections describe how to write each type of filter client and how to register filter clients Writing text import filters The FrameMaker product invokes a text import filter in the following situations e The user attempts to open a file with a format that the client filters e The user attempts to import a file with a format that the client filters e Another client attempts to import or open a file with a format that the client filters e The FrameMaker product attempts to update a text inset that references a file with a format that the client filters The FrameMaker product invokes the client the same way in each of these situations It calls the client s F_ApiNotify callback with notification setto FA_Note_FilterIn docId set to the ID of the active document if there is one and sparm set to the pathname of the file to filter FDK Programmer s Guide 239 12 Using Imported Files and Insets The client s F_ApiNotify callback should do the following to respond to the FrameMaker product s call 240 1 Create a new invisible FrameMaker product document The client can create the document with F_ApiOpen or F_ApiCustomDoc For more information on using these functions see Creating documents on page 53 If the new document is not invisible it will cause an error Filte
292. can import Although FrameMaker on all platforms can display graphic insets only UNIX versions of FrameMaker support graphic inset editors A graphic inset maintained by a graphics inset editor doesn t have to be a graphic like the graphics you create with a paint program It can for example be a drawing created with a computer aided drafting application or a flow chart created with a project management application The UNIX version of FDK provides the source code for an example graphic inset editor named fmbitmap which is implemented using the FrameServer interface For more information on the location of the code see the FDK Platform Guide for UNIX A graphic inset editor can be either an API client that defines an F_ApiMessage callback or a FrameServer application that defines Launch and Edit callbacks This chapter discusses only API graphic inset editors To add a graphic inset using a graphic inset editor the user chooses Inset from the Special menu and selects an editor from the Inset Editors scroll list The FrameMaker product starts the editor and the user then creates the inset with the editor The editor uses API functions to create an anchored frame add an FO_Inset object to it and set the FO_Inset properties to describe the inset FrameMaker maintains a connection or live link between a graphic inset and the graphic inset editor that created it To edit a graphic inset the user can double click it The FrameMaker pr
293. ce or it may have just a small subset of these properties For example the format change list in Figure 5 1 has only the common properties listed above and the FP_FontFamily property If you call F_ApiGetProps for this format change list the function returns only four properties the three common properties listed above and the FP_FontFamily property Format change list Code Default font properties Family Courier FIGURE 5 1 Format change list If you attempt to use an F_ApiGetPropertyType function to get a property that a format change list doesn t have the function fails setting FA_errno to FE_PropNotSet Adding properties to a format change list To add a property to a format change list you just set the property on the FO_FmtChangeList object You can do this by calling an F_ApiSetPropertyType function or by creating a property list containing the property and calling F_ApiSetProps to set the list on the object For example the following code uses these two methods to add properties to the Code format change list define pts MetricT 65536 F_PropValsT props F_ObjHandleT docId changeListId FDK Programmer s Guide Getting and Setting Properties 5 docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Create the Code change list changeListId F_ApiNewNamedObject docId FO_FmtChangeList Code Add the FP_PairKern property to turn pair kerning off F_ApiSetInt docId
294. cessing it can display status messages in the status bar to inform users of its progress To set the status bar of a document or a book set its FP_StatusLine property The string you set FP_StatusLine to remains in the status bar only until a client or the FrameMaker product overwrites it FrameMaker overwrites the status bar frequently For example every time the user moves the insertion point to a different paragraph in a document the FrameMaker product redisplays the paragraph format in the status bar Enhancing performance by making documents invisible The API allows you to make a document invisible Your client can still make changes to an invisible document If your client needs to batch process multiple documents using invisible documents can increase its performance considerably To make a document invisible you can use the following code F_ObjHandleT docld F_ApiSetInt FV_SessionId docId FP_IsOnScreen False You can also open documents invisibly by setting the FP_MakeVisible property of the Open script to False IMPORTANT Because an invisible document can t get input focus it can t be the active document specified by the session property FP_ActiveDoc You can t send f codes to an invisible document FDK Programmer s Guide Getting and Setting Properties 5 Displaying a particular page Document objects FO_Doc have a property named FP_CurrentPage that specifies the ID of the current page The current pa
295. ch to start adding rows The added rows will be the same type as this row For example if refRowId specifies a heading row the added rows will also be heading rows direction The direction in which to add rows To add rows above the reference row specify FV_Above To add them below specify FV_Below For a list of the other constants you can specify for this parameter see F_ApiAddRows on page 39 of the FDK Programmer s Reference numNewRows The number of rows to add If successful F_ApiAddRows returns FE_Success F_ApiAddCols requires you to specify the number of the reference column whereas F_ApiAddRows requires you to specify the ID of the reference row This is because in Frame document architecture rows are objects Columns are just a way of referring to a set of cells When you create a row the API actually creates an FO_Row object to represent the row and an FO_Cell object to represent each cell in the row When you create a column the API just creates FO_Cell objects and adds them to existing FO_Row objects For more information on how tables and cells are organized see How the API represents tables on page 332 Example The following code adds a column to the right of the first column and two rows below the second row in a table F_ObjHandleT docId tblId rowlId row2Id Get the document and table IDs docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tbliId F_ApiGetId FV_Sessio
296. cintosh is Ryumin Light 8 3pv RKSJ H while it is Ryumin Light 90ms RKSJ H on a Windows system Since these are the same fonts FrameMaker will treat these as the same PostScript name To do so FrameMaker ignores the following keywords in PostScript names 83pv 90pv 90ms Ext Add NWP The FP_FontPlatformName property specifies a platform specific ASCII string that uniquely identifies a font for a particular platform The string consists of several fields separated by periods On the Macintosh platform it has the following syntax M FontName StyleFlags This field Represents M Platform designator FontName Macintosh Resource Manager font name for more information see your Macintosh documentation StyleFlags Macintosh font styles you can use zero or more of the following flags B Bold I Italic C Condense E Extend P Plain no flags set You cannot use the C and E flags for the same font The following strings are valid representations of the Macintosh font Helvetica Narrow Bold Oblique M Helvetica BIC M B Helvetica Bold IC M NI Helvetica Narrow Oblique B M NBI Helvetica Narrow BoldObl P On Windows platforms the string you specify for FP_FontPlatformName has the following syntax FDK Programmer s Guide 307 14 Frame Document Architecture 308 W FaceName ItalicFlag Weight Variation This field Represents W Platform designator FaceName Windows face name for more inf
297. ct document for the filterable file s contents To do this it calls F_ApiCustomDoc The parameters of F_ApiCustomDoc specify the dimensions and layout of the new document For example the first parameter specifies the page width the Met ricT equivalent of 8 5 inches To get the MetricT equivalent of fractions such as 8 5 inches you can t use simple multiplication and division You must use an FDE metric function such as F_MetricMul For example to get the MetricT equivalent of 8 5 inches you can t use the expression 17 2 in You must use F_MetricFractMul in 17 2 The last parameter of the F_ApiCustomDoc call specifies that the new document is not visible If another FDK client initiates the open operation it may keep the document invisible after the filter has added the filterable file s contents to it If the user initiates the open operation the FrameMaker product automatically makes the document visible when the filter returns FDK Programmer s Guide Introduction to FDE Note that you could alternately open an existing document to use as a template for the filtered data In that case you should still be sure to open it silintly using F_ApiOpen do not use F_ApiSimpleOpen Lines 44 to 50 These lines read text from the input channel and add it to the FrameMaker product document F_ReadBytes reads text from the input channel into the buffer until it reaches the end of the file F_ApiAddText adds th
298. cted the code has no effect Changing individual text properties If you need to apply only an individual property to a text range use F_ApiSetTextProp For example the following code changes the font family of the selected text to AvantGarde include fstrings h F_TextRangeT tr F_PropValT prop F_ObjHandleT docId UIntT i 0 F_StringsT strings docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_ TextSelection if tr beg objId return Get list of font families available in current session strings F_ApiGetStrings 0 FV_SessionId FP_FontFamilyNames Find index of AvantGarde in list of families in session for i 0 i lt strings len amp amp F_StrEqual AvantGarde strings val i i if i strings len return Font not found Free the returned strings F_ApiDeallocateStrings amp strings FDK Programmer s Guide 125 o 6 Manipulating Text 126 Set up property Set it to the index for AvantGarde prop propIdent num FP_FontFamily prop propVal valType FT_Integer prop propVal u ival i Apply the property to the text selection F_ApiSetTextPropVal docId amp tr amp prop Applying conditions to text The API uses the text property FP_InCond to specify the conditions applied to a text location FP_InCond specifies an array that includes the IDs of conditions that app
299. cuments To add a marker type to a document use F_ApiNewNamedOb ject Once you have the new marker type s ID you can set any properties that you want to be different from the default values F_ObjHandleT docId myMarkerTypeld Get ID of the active document docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Create the marker type myMarkerTypeId F_ApiNewNamedObject docId FO_MarkerType StringT MyMarkerType To delete a marker type from a document pass the document ID and the marker type ID to F_ApiDelete Mapping old marker types to named marker types In versions of FrameMaker earlier than 5 5 marker types were identified by number Type 1 through Type 10 were reserved for FrameMaker and given specific names Header Footer 1 Header Footer 2 etc Type 11 through Type 25 were for custom marker types FO_MarkerType and FO_Marker objects have an FP_OldTypeNum property that maps the named marker type to what was a numbered marker type in earlier documents In this way you can ensure that your client handles markers in legacy data the way you want For example assume your client adds a marker type named MyMarkerType to a document and you set the FP_OldTypeNum property of MyMarkerType to 11 The user might import or paste text from an older document into the document with MyMarkerType If the older text has markers of type 11 in it they will come into the new document as MyMarkerType The stan
300. cuments into G 72 function for R 2 R 323 to R 325 making active G 95 open API indication of G 275 opening G 46 to G 53 functions for R 2 R 238 to R 244 R 326 to R 327 organization of documents in G 351 as organized in sessions illustrated G 276 printing G 57 to G 59 function for R 2 print properties R 502 to R 503 FDK Programmer s Reference amp Guide Index Subjects a properties of G 351 to G 355 R 495 to R 503 getting and setting G 105 saving G 59 to G 66 functions for R 2 R 272 to R 274 R 327 to R 328 setting status bars G 98 setting title bars G 98 structured G 355 updating G 356 to G 360 updating files for function for R 321 to R 322 updating files of functions for R 2 View Only properties R 507 See also book components Bourne shell R 333 boxes in dialog boxes G 198 building blocks cross reference G 322 defined G 389 variable G 324 to G 325 buttons in dialog boxes G 199 getting setting the state of function for R 5 properties of G 199 R 533 bytes TO library functions for ordering G 382 R 435 R 438 reading R 427 to R 428 writing R 489 to R 490 See also longs 4 bytes shorts 2 bytes C C language library functions FDE replacements for G 370 G 381 to G 387 C language programs writing with the Frame API G ix R xv C library header files including in clients G 8 G 367 callback functions client defined R 1 defined G 389 Cancel buttons of dialog boxes G 196 displaying G 18 cells adding t
301. cutive in the Item Order scroll box In the Useful Items group box verify that the following items are specified First Focus is set to 2 Title Label is set to 0 Default Button is set to 1 OK Button is set to 1 Since the dialog box has only one button you do not need to specify the Cancel button Click OK to dismiss the Dialog Box Properties dialog box Saving and testing the DRE file When you finish designing the sample dialog box you need to test and save it 1 To save the file as a DRE file choose Save As from the File menu 2 Type the name 208 pgftag dre If you are in a UNIX or Windows version of FrameMaker additional files are created UNIX versions of FrameMaker create a file named pgftag x FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client Windows versions of FrameMaker create two files pgftag dlg and pgftag xdi You can use these files with the client code for this dialog box see A simple example on page 215 to build an FDK client For instructions on creating an FDK client that uses these files see the FDK Platform Guide for your platform 3 If you are in a UNIX or Windows version of FrameMaker press Esc d t to test the dialog box If you are using a Macintosh version of FrameMaker you can test the dialog box in MPW by using the makedbre tool You can only test the dialog box after saving it For details see the FDK Plat
302. d body pages are examples of series objects To create a series object use F_ApiNewSeriesObject The syntax for F_ApiNewSeriesObject is F_ObjHandleT F_ApiNewSeriesObject F_ObjHandleT docId IntT objType F_ObjHandleT prevId This argument Means docId The ID of the document or book to which to add the object objType The type of object to create for example FO_BodyPage or FO_Pgf previd The ID of the object that you want to add the new object after To add a paragraph at the beginning of a flow specify the flow s ID To add other objects at the beginning of a series specify 0 Example The following code inserts a paragraph after the paragraph containing the insertion point F_ObjHandleT docId pgfId F_TextRangeT tr F_TextLocT textLoc Get the insertion point docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection if tr beg objId return FDK Programmer s Guide 149 az Creating and Deleting API Objects Add the paragraph pgfId F_ApiNewSeriesObject docId FO_Pgf tr beg objId Put some text in the paragraph textLoc objiId pgfId textLoc offset 0 F_ApiAddText docId amp textLoc Here s some text Creating flows You can t create a flow directly with API functions However you can create one indirectly by creating a text frame with F_ApiNewGraphicOb ject Each time you create a te
303. dard graphic inset facets listed in the following table Platform on which facet format can be used Facet format All platforms DCS Black DCS Cyan DCS Magenta DCS Yellow CGM EPSI Encapsulated PostScript FrameImage Frame Vector GIF MacPaint PCX SVG TIFF XWD Macintosh only QuickDraw PICT QuickTime FDK Programmer s Guide 257 12 Using Imported Files and Insets 258 Platform on which facet format can be used Facet format Windows only DIB EMF OLE WME Windows Metafile FrameImage facets follow Sun raster image format FrameVector facets follow a TIFF format For a complete description of these formats see the online MIF Reference manual If an inset doesn t have one of the facet formats listed above FrameMaker can use a filter to convert another format into FrameImage or FrameVector formats For example if the inset has an HPGL facet the FrameMaker product can convert it into Frame Vector format FrameMaker uses an inset s facets to display and print it FrameMaker may use different facets to display and print a graphic For example the Macintosh version of FrameMaker may use the QuickDraw PICT facet for displaying a graphic and the EPSI facet for printing it When displaying an imported graphic FrameMaker uses one of the following facet formats in order of preference e Native platform format QuickDraw PICT WMF e FrameVector e FramelImage and other bitmap formats e TIFF e Othe
304. dard list of marker types Every document includes a set of required marker types Header Footer 1 Header Footer 2 Index Comment Subject Author Glossary Equation Hypertext Cross Ref and Conditional Text These are required markers and cannot be deleted You can add an existing public marker type to the standard list by setting the name string to the FP_AddMarkerTypeToStandardMarkers property of the current session object Once you add a marker type to this list it remains for the entire session you must quit the session to remove it F_ApiSetInt 0 FV_SessionId FP_OldTypeNum IntT 17 F_ApiSetString 0 FV_SessionId FP_AddMarkerTypeToStandardMarkers StringT MyMarkerType FDK Programmer s Guide 321 14 Frame Document Architecture This example first sets a session integer for FP_OldTypeNum to 17 This ensures that for the rest of the current session markers of type 17 from earlier documents will come into new documents as markers of type MyMarkerType If the the FP_OldTypeNum you specify is taken your new marker type will not be added to the list of standard marker types To confirm that your marker type was added to the standard list get the FP_MarkerNames property from the FV_SessionId object It s possible for the FP_OldTypeNum you specified to be taken another API client may have already used that value when assigning a marker type to the standard list For example HTML export in FrameMaker 5 5 is perf
305. data types See data types FDE filters example G 370 to G 374 FDE functions G 375 to G 379 G 381 to G 387 assertion handler G 378 R 348 channel G 377 R 350 character G 381 G 382 for replacing C library functions G 370 hash G 381 G 383 header file containing G 367 T O filepath G 375 to G 377 I O read write G 366 G 381 G 382 memory allocation and deallocation G 378 to G 379 metric G 366 G 384 R 675 to R 677 MIF G 366 G 381 G 385 to G 387 naming convention for G xii R xix for replacing I O and memory calls G 369 simple MIF G 381 G 387 string G 381 string list G 381 G 382 virtual environment functions G 375 to G 379 See also individual FDE functions in the FDK Reserved Names Index FDE header files including in FDE clients G 367 See also individual FDE header files FDE T O utility functions for handling filepaths G 375 to G 377 for reading and writing data G 366 G 381 G 382 for replacing common I O functions G 369 FDE utility libraries G 366 G 381 to G 387 functions provided in G 381 to G 387 FDE utility library functions G 366 G 381 to G 387 FDK Programmer s Reference amp Guide Index Subjects a FDE virtual environment G 366 fdetypes h header file G 367 G 370 G 378 G 379 G 381 G 382 G 384 G 387 R 27 FDK Frame Developer s Kit G ix R xv documentation G xi to G xii R xviii FDK clients writing with the Frame API G ix R xv FDK Platform Guide G xii R xviii FDK Programmer s Guide summary
306. ding ID assigned to an encoding name and to get the encoding name that is associated with a given encoding ID F_FontEncId returns the FontEncIadT for the encoding data associated with the specified encoding name If the encoding name is not supported for the current session this function returns the ID for the FrameRoman encoding The syntax for F_FontEncId is FontEncldT F_FontEncId ConStringT fontEncName This argument Means fontEncName The encoding of interest Possible values are FrameRoman JISX0208 ShiftJIS BIG5 GB2312 80 EUC KSC5601 1992 Multiple F_FontEncName returns the encoding name associated with the specified FontEncIdt If the specified FontEncIadT is not valid this function returns a NULL string The syntax for F_FontEncName is ConStringT F_FontEncName FontEncIdT fontEncId This argument Means fontEncId The encoding ID of interest FDK Programmer s Guide Manipulating Asian Text Functions for encoded strings The FDE includes the following functions for handling strings of a given encoding For more information see these functions in the FDK Programmers Reference F_StrChrEnc F_StrRChrEnc F_StrStrEnc F_StrIEqualEnc F_StrIEqualNEnc F_StrICmpEnc F_StrCmpNEnc F_StrICmpNEnc F_StrTruncEnc F_StrLenEnc F_StrCatDb1CharNEnc F_StriPrefixEnc F_StrISuffixEnc F_StrCatNEnc F_StrNCatNEnc
307. documentation Avoid using numeric link names that may conflict with page numbers 2 Use Esc F1k to lock the help document This allows users to click the document s hypertext markers and prevents them from altering the document 3 Copy the help document to the client directory On UNIX the client directory is the directory specified by the lt Directory gt statement in the apiclients file On Macintosh it s the folder containing the client On Windows it s the directory containing the client DLL When the user requests help for one of a client s menu items the FrameMaker product looks for the help document in the client s directory 4 Set the menu item s FP_HelpLink property to the filename of the help document When the user requests help for the menu item the FrameMaker product opens the help document specified by the FP_HelpLink property If the help information for the menu item is not on the first page of the help document you can set the FP_HelpLink property so that the FrameMaker product jumps to a specific page or hypertext link in the document Set the property to document_name linkname_or_page where document_name is the document name and linkname_or_page is the linkname of the hypertext link or the page number to jump to For example the following code sets the FP_HelpLink properties of several client defined menu items F_ObjHandleT menulId cmdlId cmd2Id Opens my hlp when help is requested
308. don t necessarily provide the full ink name as described in the color library s reference material Some ink names have prefixes or suffixes that are not used by the API The following table lists the formal name for each color library that FrameMaker supports along with an example of a legal string to specify an ink name via the FDK Color library name Ink name Crayon Apricot DIC COLOR GUIDE SPOT 2298p FOCOLTONE 1070 Greys 49 Grey prcs MUNSELL High Chrome Colors 2 5R 7 10 MUNSELL Book of Color 2 5R 9 1 PANTONE Coated Yellow 012 PANTONE ProSim Process Yellow PANTONE Uncoated Yellow 012 PANTONE ProSim EURO Process Yellow PANTONE Process CSG 1 1 PANTONE Process Euro E 1 1 TOYO COLOR FINDER 000 1pc TRUMATCH 4 Color Selector l a FDK Programmer s Guide Frame Document Architecture CE Tinted colors In FO_Color objects that are tints the following properties have no meaning FP_FamilyName FP_InkName FP_Cyan FP_Magenta FP_Yellow FP_Black Changing these properties in a tinted color will turn the FO_Color object into an untinted color If you want to change the hue of a tinted FO_Color object you must select a new base color or change the hue of the base color Also you cannot change FP_ColorPrintCt1 and FP_ColorViewCt1 in a tinted color if you try to change them the FDK returns an error of FE_TintedColor To change these properties you must change them in the tint s base color FP_TintPerce
309. e Writing the No dialog resource dialog box code to compilation UNIX operate the necessary FrameMaker product dialogbox r i A Open e Representation of l DRE file the dialog box i Save FEN IN BEE a BEE i dre Other pE FDK client source files for client Save e X resource file x i X resource file x FiGuRE 10 6 Creating a dialog box for a UNIX client Norte If your dialog box uses scroll lists you might want to include the single quote character in your scroll list strings For example you might want to use a single quote to represent length in feet By default FrameMaker converts the single quote character to an escaped double quote This is because single quotes are not valid in filenames To override this default add the following statement to the dialog box resource file along with the other statements for the given scroll list Maker dialog bb itemX isEnc noConv where itemx specifies the item number for example Maker dialog bb item7 isEnc specefies item 7 If you place this statement at the head of the resource statements for the dialog box item that scroll list will display single quotes correctly Dialog box information on the Macintosh In the Macintosh build process dialog box information is read directly from the Frame DRE file For this reason no other intermediary resource file is written out when you save a DRE file in FrameMaker Figure 10 7 shows the
310. e to get the paragraphs in a document s main flow in order you can use the following code include futils h F_ObjHandleT docId pgfiId flowId textFrameld UCharT msg 256 docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Get ID of main flow then the first text column in the flow then the first paragraph in that text column i flowId F_ApiGetId FV_SessionId docId FP_MainFlowInDoc textFrameId F_ApiGetId docId flowId FP_FirstTextFrameInF low pgfId F_ApiGetId docId textFrameId FP_FirstPgf Traverse ordered list of paragraphs in the flow while pgfId F_Sprintf msg The paragraph s ID is 0x x pgfId F_ApiAlert msg FF_ALERT_CONTINUE_NOTE pgfId F_ApiGetId docId pgfId FP_NextPgfInFlow For a diagram of the links between flows text frames and paragraphs see The list of paragraphs in a flow on page 304 Getting the IDs of selected objects Document objects have properties that allow you to get the IDs of the following types of selected objects e Graphic objects e Tables and table rows To get the IDs of selected structural elements in FrameMaker documents you must call a special function F_ApiGetElementRange FDK Programmer s Guide Getting and Setting Properties 5 For background information on selection in Frame documents see How the API represents the selection in a document on page 285 For information on gettin
311. e 279 The syntax for F_ApiCustomDoc is F_ObjHandleT F_ApiCustomDoc MetricT width letricT height IntT numCols letricT columnGap etricT letricT e etricT IntT sidedness BoolT makeVisible topMargin botMargin tricT leftinsideMargin rightoutsideMargin Thi s argument width hei ght numCols col top bot lef rig sid mak umnGap argin argin tinsideMargin htoutsideMargin edness eVisible Means Page width The Frame API expresses linear measurements with MetricT values For more information on MetricT values see Chapter 4 Data Types and Structures Reference in the FDK Programmer s Reference Page height Default number of columns Default column spacing Page top margin Page bottom margin Left margin for single sided documents or the inside margin for double sided documents Right margin for single sided documents or the outside margin for double sided documents Constant that specifies whether the document is single sided or double sided and on which side the document starts See the following table for the list of constants Specifies whether to make the document visible True makes it visible The sidedness argument can have any of the values shown in the following table FDK Programmer s Guide 55 ae Executing Commands with API Functions 56 sidedness constant New document page characteri
312. e API represents each object s property list witha F_PropValsT structure The F_PropValsT structure is defined as typedef struct UIntT len Number of properties in list F_PropValT val Property value pairs F_PropValsT The F_PropValT structure which provides an individual property value pair is defined as typedef struct F_PropidentT propiIdent The property identifier F_TypedValT propVal The property value F_PropValT The F_PropIdenttT structure which identifies a property by either its property number constant one of the constants beginning with FP_ ora property name is defined as typedef struct IntT num The property number constant StringT name The property name F_PropiIdenttT Most properties are identified by property number constants Only inset facets a special type of properties are identified by names For information on insets see Chapter 12 Using Imported Files and Insets If a property is identified by a name F_PropIdentT num is 0 The F_TypedValT structure is defined as typedef struct IntT valType The type of value See table below union StringT sval String value F_StringsT ssval Set of strings F_MetricsT msval Set of metrics F_PointsT psval Set of points F_TabsT tsval Set of tabs _TextLocT tlval Text location TextRangeT trval Text range lementCatalogEntriesT csval Ele
313. e F_ApiNewNamedOb ject The syntax for F_ApiNewNamedOb ject is F_ObjHandleT F_ApiNewNamedObject F_ObjHandleT doclId IntT ob jType StringT name This argument Means docId The ID of the document to which to add the object To create a book specify FV_SessionId objType The type of object to create for example FO_MasterPage FO_PgfFmt or FO_Book name The name to give to the object If the object is an FO_Book object specify the pathname of the book file to create F_ApiNewNamedObject uses a set of default properties when it creates a new named object Because the property lists for most named objects are quite long it is often easier to copy the properties from a similar object and then change individual properties Creating a paragraph format The following code creates a paragraph format named MyHead which looks like Heading1 except that it s indented two inches FDK Programmer s Guide 145 az Creating and Deleting API Objects define in MetricT 65536 72 F_PropValsT proplist F_ObjHandleT docId HeadinglId myHeadId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Create MyHead paragraph format myHeadId F_ApiNewNamedObject docId FO_PgfFmt MyHead Get ID for Headingl HeadinglId F_ApiGetNamedObject docId FO_PgfFmt Headingl if HeadinglId return Get properties for Headingl and copy them to MyHead proplist F_ApiGetProps docId Headin
314. e appears on it If the user holds down the Shift key and displays the Edit menu the label Check in All Open Files appears on it define CHECKIN_CMD 1 define CHECKIN_ALL CMD 2 F_ObjHandleT editMenulId checkinCmdId checkinAl1lCmdId editMenuld F_ApiGetNamedObject FV_SessionId FO Menu EditMenu checkinCmdId F_ApiDefineAndAddCommand CHECKIN_CMD editMenuId Checkin Check in File checkinAllCmdId F_ApiDefineCommand CHECKIN_ALL_CMD CheckinAl1 Check in All Open Files F_ApiSetInt editMenuld checkinCmdId FP_HasShiftOrUnshiftCommand FV_ITEM_HAS SHIFT_COMMAND F_ApiSetId editMenulId checkinCmdId FP_ShiftOrUnshiftCommand checkinAl1CmdId Providing context sensitive Help for client menu items When a user chooses context sensitive Help in a FrameMaker product the cursor changes to a question mark The API allows you to provide context sensitive Help for your client s menu items The API displays the help information that you provide in a FrameMaker hypertext document To provide context sensitive Help for a client defined menu item follow these steps 1 Create a document containing help text for the menu item FDK Programmer s Guide 175 i Manipulating Commands and Menus with the API To allow users to navigate within the document add hypertext markers to it For more information on using hypertext markers see your FrameMaker product user
315. e lists Steps 2 4 and 5 are discussed in the following sections Creating an openParamsp script with F_ApiGetOpenDefaultParams If you need to specify a number of properties in the openParamsp property list it is easiest to get a default list with F_ApiGetOpenDefaultParams and then modify individual properties in the list The syntax for F_ApiGetOpenDefaultParams is F_PropValsT F_ApiGetOpenDefaultParams The following table lists some of the properties in the property list returned by F_ApiGetOpenDefaultParams The first value listed for each property is the default value used in the list You can change the list to use the other listed values For the complete list of properties in the property list see F_ApiGetOpenDefaultParams on page 138 of the FDK Programmer s Reference Property Instruction or situation and possible values FS_ShowBrowser Display Open dialog box False don t display it True display it FS_OpenDocViewOnly Open document as View Only False don t open as View Only True open as View Only FS_NameSt ripe String specifying the name that appears on the document title bar Setting this property on Macintosh platforms has no effect NULL FS_NewDoc Create a new document False open an existing document True create a new document For example to get a default openParamsp property list and modify it so that it instructs F_ApiOpen to show the Open dia
316. e number For example if the user types 10 cookies the returned value is 10 F_ApiPromptMetric dialog boxes behave like metric dialog boxes in the user interface If the user types a number followed by a string that represents a unit the API converts the value into the equivalent number of metric units For example if the user types 5in or 5 the API returns 5 4718592 If the user doesn t specify a unit the API uses the unit specified by defaultunit IMPORTANT F_ApiPromptString allocates memory for the string referenced by stringp Use the FDK function F_ApiDeallocateString to free the string when you are done with it For more information on F_ApiDeallocateString see F_ApiDeallocateStructureType on page 74 of the FDK Programmer s Reference Examples The following code displays the dialog box shown in Figure 3 2 FDK Programmer s Guide 19 Ss Creating Your Client s User Interface include fmemory h IntT err StringT sres err F_ApiPromptString amp sres StringT String StringT Default text if err return Some code to use the string goes here F_ApiDeallocateString amp sres Enter Value String Default text OK Cancel FIGURE 3 2 String prompt dialog box The following code displays the dialog box shown in Figure 3 3 include futils h Provides declaration for F_Sprintf IntT err ires UCharT msg 256 err F_ApiPromptiInt amp ire
317. e of the file the user is attempting to open or import For more information on F_ApiNotify and other Frame API functions see the FDK Programmer s Reference FDK Programmer s Guide 371 16 Introduction to FDE 372 F_FdelInit initializes the FDE You must initialize the FDE before calling any FDE functions Lines 25 to 32 The FDE memory allocation function F_Alloc allocates a buffer for reading text from the file The NO_DSE flag instructs the function to return NULL if it is unable to allocate memory for the buffer The F_ApiReturnValue 0 call notifies the FrameMaker product that the filter was unable to filter the specified file After the filter returns the FrameMaker product displays an alert informing the user that the filter could not filter the file Lines 33 to 34 F_PathNameToFilePath converts the platform specific pathname specified by filename toa platform independent filepath The FDefaultPath flag instructs F_PathNameToFilePath to use the filenaming conventions of the current platform to interpret the platform specific pathname Because the pathname specified by filename is absolute F_PathNameToFilePath ignores the second parameter the anchor Lines 35 to 36 F_ChannelOpen opens the file specified by the platform independent filepath The r instructs F_ChannelOpen to open the file for reading only Lines 37 to 40 The filter needs to create a new FrameMaker produ
318. e of the radio button on or off In the Initial State text box type O if the radio button is initially off or 1 if it is initially on e Number of the group to which the radio button belongs In the Group text box type the number that identifies the radio button s group When you assign group numbers start with 1 FDK Programmer s Guide 199 a Creating Custom Dialog Boxes for Your Client 200 The radio button item includes a label To change the text in the label select the text next to the radio button and type over it If the text is longer than one line add another label for each additional line of text You can set the label of the radio button in your client code For details see Labels on page 201 Text boxes A text box allows the user to enter text The text box item does not include a label For instructions on adding a label for a text box see the section Adding dialog items on page 192 For information on setting the basic properties for this dialog item see the section Setting basic dialog item properties on page 197 Multiline text boxes A multiline text box is a text box that displays more than one line of text The multiline text box item does not include a label For instructions on adding a label for a multiline text box see the section Adding dialog items on page 192 For information on setting the basic properties for this dialog item see the section Setting basic dial
319. e text in the buffer to the Frame document starting at the current insertion point Line 51 This line sets the filter s return value to the ID of the document the filter created This notifies the FrameMaker product that the filter opened the file successfully Lines 52 to 56 These lines clean up and free resources used by the filter The calls to F_FilePathFree and F_Free free resources used by the filepath and the text buffer F_ChannelClose closes the input channel and F_ApiBailOut exits the filter Compiling and running the example FDE filter The source code for the example filter and a makefile or project file are provided online with the FDK To compile the sample filter use your platform s make or build utility For the location of example files and instructions on compiling and linking them see the FDK Platform Guide for your platform To run the e 7 Register xample filter follow these general steps it as required by your platform s implementation of the FDK e If you are working on a Macintosh computer copy or move the compiled example filter to the FrameMaker product Filters folder The sample resource file that you compile with the filter instructs the FrameMaker product to call the filter any time the user attempts to open or import a file with the type KURT e If you are working on a Windows platform and you have compiled your client into a DLL named 1 filter dll and copied or moved i
320. eT docI Id VoidT F_ApiMergeIntoFirst F_ObjHandleT docId VoidT F_ApiMergeIntoLast F_ObjHandleT docId VoidT F_ApiPromoteElement F_ObjHandleT docId VoidT F_ApiSplitElement F_ObjHandleT docId VoidT F_ApiUnWrapElement F_ObjHandleT doclId VoidT F_ApiWrapElement F_ObjHandleT docId F_ObjHandleT edefId 76 FDK Programmer s Guide Executing Commands with API Functions 4 This argument Means docId ID of the document containing selected text and or structure elements edefld ID of element definition for the new element These functions behave like the corresponding commands in the user interface They all use the current text or element selection in the specified document to determine which text and elements to manipulate You can allow the user to set the text or element selection or you can do it programmatically For information on setting the text selection programmatically see Getting and setting the insertion point or text selection on page 114 For more information on setting the element selection programmatically see Getting and setting the structural element selection on page 120 Importing element definitions into FrameMaker documents and books To import element definitions from a FrameMaker document or book to a FrameMaker document or book use F_ApiSimpleImportElementDefs The syntax for F_ApiSimpleImportElementDefs is IntT F_ApiSimpleImportElem
321. ear gt FP_SystemVar IntT FV_VAR_CREATION_DATE_LONG FDK Programmer s Guide 325 14 Frame Document Architecture 326 Property Type Value FP_NextVarFmt InDoc F_ObjHandleT ID of next FO_VarFmt object in the document Variables The user can insert variables in text There are some restrictions on inserting some variable formats For example you can insert current page number running header and running footer variables only in an untagged flow on a master page What the user sees The information an instance of a variable provides depends on its variable format For example if a variable s format is Page Count and the current document has 27 pages each time the variable occurs in text it appears as 27 How the API represents instances of variables The API represents each variable instance with the following e An FTI_VarBegin textitem and an FTI_VarEnd text item that specify the ID of an FO_Var object e An FTI_String text item that provides the text that appears where the variable is inserted e An FO_Var object FO_Var properties provide the following information e TheID ofan FO_VarFmt object e ID ofthe next FO_Var object in the document e The element ID of the variable if it is a structured variable in a FrameMaker document Figure 14 28 shows an instance of the Creation Date Long variable and the text items that represent it December 10 19924 offset 0 offset 1 Offset 8
322. ect The syntax for F_ApiGetUniqueOb ject is F_ObjHandleT F_ApiGetUniqueObject F_ObjHandleT doclId IntT ob jType IntT unique This argument Means docId The ID of the document containing the object objType The object type for example FO_Pgf unique The object s UID For an example of how you can use UIDs see F_ApiGetUniqueObject on page 185 of the FDK Programmer s Reference Manipulating properties The API allows you to get and set either an individual property or a property list for an object It is generally easier to get and set properties individually However some tasks such as applying a Paragraph Catalog format to a paragraph are easier to perform by getting and setting property lists Getting and setting individual properties To get or set an individual property use the F_ApiGetPropertyType or F_ApiSetPropertyType function that corresponds to the property s data type For FDK Programmer s Guide 89 rs Getting and Setting Properties 90 example to get an integer enum or boolean IntT data type property use F_ApiGet Int To set a property that represents a set of strings F_StringsT data type use F_ApiSet Strings The data types of API properties are listed in Chapter 3 Object Reference of the FDK Programmer s Reference The following table lists the functions you use to set different types of properties The API also provides special functions
323. ecutes Copy and Paste operations and then restores the original Clipboard contents F_ObjHandleT docId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc F_ApiPushClipboard F_ApiCopy docId 0 F_ApiPaste doclId 0 F_ApiPopClipboard FDK Programmer s Guide 129 o 6 Manipulating Text 130 FDK Programmer s Guide Manipulating Asian Text This chapter describes how to use the API to manipulate Asian text in Frame documents Specifically it discusses e Creating a rubi group e The text encodings supported by FrameMaker e How to use encoding data in an API client e Inspecting and manipulating encoded text e Parsing encoded strings e Getting the encoding for a text item e Special issues such as decimal tabs character offsets and internal strings To better understand the material in this chapter you may want to learn more about how the API represents text For information on this subject see Text on page 311 Creating a rubi group Users create rubi groups by selecting the oyamoji text and choosing Rubi from the Special menu Internally a rubi group is stored as an anchored object To create a rubi group via the API use F_ApiNewAnchoredOb ject Note that F_ApiNewAnchoredObject accepts a text location but not a selection as an argument This changes the process for creating a group slightly e Identify the location for the rubi group e Get the oyamoji location e Insert the oyamoji te
324. ed APPLE COMPUTER INC APPLE MAKES NO WARRANTIES EXPRESS OR IMPLIED INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE REGARDING THE APPLE SOFTWARE APPLE DOES NOT WARRANT GUARANTEE OR MAKE ANY REPRESENTA TIONS REGARDING THE USE OR THE RESULTS OF THE USE OF THE APPLE SOFTWARE IN TERMS OF ITS CORRECTNESS ACCURACY RELIABILITY CURRENTNESS OR OTHERWISE THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE APPLE SOFTWARE IS ASSUMED BY YOU THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES THE ABOVE EXCLUSION MAY NOT APPLY TO YOU IN NO EVENT WILL APPLE ITS DIRECTORS OFFICERS EMPLOYEES OR AGENTS BE LIABLE TO YOU FOR ANY CONSEQUENTIAL INCIDENTAL OR INDIRECT DAMAGES INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS BUSINESS INTERRUPTION LOSS OF BUSINESS INFORMATION AND THE LIKE ARISING OUT OF THE USE OR INABILITY TO USE THE APPLE SOFTWARE EVEN IF APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU Adobe Systems Incorporated 345 Park Avenue San Jose California 95110 USA Notice to U S government end users The software and documentation are commercial items as that term is defined at 48 C F R 2 101 consisting of commercial computer software and commercial computer softw
325. ed F_ApiGet SupportedEncodings returns a F_StringsT list of all the encodings supported for the current session The syntax for F_ApilsEncodingSupported is BoolT F_ApiGetEncodingForFamily ConStringT encodingName This argument Means encodingName The encoding of interest Possible values are FrameRoman JISX0208 ShiftJIS BIG5 GB2312 80 EUC KSC5601 1992 The syntax for F_ApiGet SupportedEncodings is F_StringsT F_ApiGetSupportedEncodings FDK Programmer s Guide 137 Manipulating Asian Text Inspecting and manipulating encoded text For text of a given encoding you can perform actions such as string comparison search for the occurance of a character in a string character count truncation concatenation and others The functions to perform these actions are much like the corresponding string functions for Roman text However they must be passed an encoding ID so they can check a character code against the encoding For example a single byte code might be a single byte character in one encoding while in another encoding it might be the first or last byte of a double byte character The API provides functions to determine exactly that Getting encoding IDs When you initialize the encoding data the FDE assigns an ID to each encoding data structure String functions that use this encoding data generally require the ID to identify the encoding The FDE includes functions to get the enco
326. ed that is the number you specified when you displayed the dialog box with F_ApiModelessDialog or F_ApiModalDialog itemNum If the user manipulated a specific dialog item itemNum is a nonnegative number specifying the dialog item If the user didn t manipulate a specific dialog item itemNum is a negative number constant specifying what the user did For example if the user closed the dialog box itemNum is set to FV_DlgClose For a list of the constants see Handling special events in a modeless dialog box on page 226 modifiers Bit flags specifying which modifier keys the user was holding down when the event occurred For a list of possible flags see F_ApiDialogEvent on page 93 of the FDK Programmer s Reference Normally you will want to include code in the F_ApiDialogEvent function to check the properties of the item specified by itemNum If the dialog box includes any items that the user can double click you may also want to check the FO_DialogResource property FP_DoubleClick to determine whether the user double clicked in the dialog box Your F_ApiDialogEvent function can include calls to any API function It can get and set properties of objects in the dialog box and in the FrameMaker product session It can also call functions such as F_ApiOpen or F_ApiUpdateXrefs to execute FrameMaker product operations For example the following code handles events for a dialog box that contains
327. ed by F_ApiOpen statusBit The status bit you want to test FDK Programmer s Guide 51 ae Executing Commands with API Functions 52 If the specified bit is set F_ApiCheckStatus returns True For example the following code determines if an Open operation was canceled because a document used unavailable fonts F_ObjHandleT docId F_PropValsT params returnParamsp NULL Get default property list params F_ApiGetOpenDefaultParams docId F_ApiOpen tmp my doc amp params amp returnParamsp if F_ApiCheckStatus returnParamsp FV_CancelFontsMapped F_ApiAlert Canceled because my doc has unavailable fonts FF_ALERT_CONTINUE_NOTE Deallocate property lists F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp The API also provides a convenience function named F_ApiPrintOpenStatus which prints the Open status values to the console on UNIX platforms the error log window on the Macintosh and the Frame console on Windows F_ApiPrintOpenStatus is useful for debugging clients that use F_ApiOpen For more information see F_ApiPrintOpenStatus on page 250 of the FDK Programmer s Reference Deallocating Open script property lists After you are done with the Open script property lists call the API convenience function F_ApiDeallocatePropVals to free the memory they use The syntax for F_ApiDeallocatePropVal
328. ed column FP_RightColNum specifies the number of the rightmost selected column If a range of text that includes several tables is selected and you want to get the tables IDs you must get the text selection and traverse all the table anchor text items in it For more information on getting the text selection see Getting and setting the insertion point or text selection on page 114 Getting the IDs of selected structural elements For information on getting the IDs of selected structural elements see Getting and setting the structural element selection on page 120 FDK Programmer s Guide 87 aes Getting and Setting Properties Getting the IDs of formats and other named objects The following are some of the types of objects that are named identified by a unique name FO_CharFmt e FO Color e FO _CombinedFontDefn e FO Command FO_CondFmt e FO ElementDef e FO Flow e FO FmtChangeList e FO_MarkerType e FO MasterPage e FO Menu e FO PgfFmt e FO TblFmt e FO_UnanchoredFrame named frames on reference pages e FO VarFmt e FO_XRefFmt The API maintains all the named objects of a particular type in a linked list To get the objects you can query FO_Doc properties and traverse the list For example to get all the variable formats in a document query the FO_Doc object s FP_FirstVarFmtInDoc property and then traverse the FP_NextVarFmtInDoc properties from one FO_VarFmt o
329. ed in flows G 298 properties of R 605 to R 606 text frame layouts G 289 See also footnotes text insets G 229 to G 230 G 281 adding text to function for R 24 API functions applicable to R 24 API representation of G 281 FDK Programmer s Reference amp Guide Index Subjects a API representation of the beginning of G 314 R 167 API representation of the end of G 314 R 167 client text insets G 230 G 236 to G 238 common properties R 662 to R 666 creating functions for R 15 R 24 deleting text from function for R 24 R 90 deleting function for R 24 getting default property list for use with function for R 24 getting text from function for R 24 manipulating G 236 properties for text imported by an FDK client R 666 properties for text imported from a Frame product R 667 properties for text imported from a MIF file R 667 properties for text imported from a text file R 667 to R 668 properties of R 662 to R 668 updating stale function for R 24 updating function for R 7 text item structures G 112 G 312 to G 316 R 686 to R 689 allocating memory for API function for R 46 deallocating memory from G 112 R 165 R 170 functions for R 11 R 46 R 165 R 170 text item types getting G 111 to G 113 tables of G 313 to G 314 R 686 to R 689 text items G 112 G 312 to G 316 R 164 R 170 API representation of G 112 G 312 to G 316 arrays of allocating memory for R 46 for paragraphs illustrated G 316 printing text in f
330. editMenuld F_ApiGetNamedObject FV_SessionId FO Menu EditMenu Define the menu and add it to the Edit menu menuld F_ApiDefineAndAddMenu editMenulId GrammarMenu Grammar Define some commands and add them to the menu cmdlId F_ApiDefineAndAddCommand CHECK menuld CheckGrammar Check Grammar CG cmd2Id F_ApiDefineAndAddCommand PRINT menuld PrintErrors Print Errors PE Spelling Checker L Thesaurus lt gt eT Grammar d Check Grammar Print Errors FIGURE 3 7 Edit menu with a client defined pull right menu FDK Programmer s Guide Creating Your Client s User Interface a Responding to the user choosing a command Whenever the user chooses a menu item or types a keyboard shortcut for a command created by your client the FrameMaker product attempts to call your client s F_ApiCommand function Your client should define this function as follows VoidT F_ApiCommand command IntT command Code to respond to command choices goes here This argument Means command The value of the cmd parameter in the F_ApiDefineAndAddCommand call that created the command that the user chose Example The following client defines some commands and adds them to the Special menu It provides an F_ApiCommand function to respond to the user choosing the commands include fapi h define LOAD 1 define QUERY 2
331. eep FrameMaker from validating elements and applying format rules set the FO_Session properties FP_Validating and FP_ApplyFmtRules to False 110 FDK Programmer s Guide Manipulating Text This chapter describes how to use the API to manipulate text in Frame documents Specifically it discusses how to e Retrieve text from a document e Get and set the location of the insertion point or current text selection e Add and delete text e Get and set text formatting e Programmatically execute Clipboard operations To better understand the material in this chapter you may want to learn more about how the API represents text For information on this subject see Text on page 311 Getting text Text in Frame documents is contained in objects such as FO_Cell FO_Element FO_Fn FO_Pgf FO_TextLine FO_Var FO_SubCol FO_TextFrame and FO_Flow objects To get text you must get the ID of the object that contains it For information on getting object IDs see Getting the IDs of the objects you want to change on page 82 Once you have the ID of an object that contains text you use F_ApiGetText to retrieve the text The syntax for F_ApiGetText is F_TextItemsT F_ApiGetText F_ObjHandleT docId F_ObjHandleT objId IntT flags This argument Means docId The ID of the document containing the object for which you want to get text objId The ID of the object FO_Flow FO_Element FO_Fn FO_Paf FO_Cell FO_SubCol
332. efixEnd I_ElemSuffixBegin I_ElemSuffixEnd FI FI I_CharPropsChange I_RubiComposite Begin I_RubiComposite End E I_RubiTextBegin T_RubiTextEnd What the text item represents A marker The beginning of a cross reference instance The end of a cross reference instance The beginning of a variable instance The end of a variable instance The beginning of a text inset The end of a text inset The beginning of a container element The end of a container element The beginning of an element s prefix The end of an element s prefix The beginning of an element s suffix The end of an element s suffix A change in the text properties The beginning of a rubi composite and the beginning of oyamoji text The end of a rubi composite The beginning of rubi text and the end of oyamoji text The end of rubi text Text item data ID of an FO_Marker ID of an FO_XRef ID of an FO_XRef ID of an FO_Var ID of an FO_Var ID of an FO_TiApiClient FO_TiFlow FO_TiText or FO_TiTextTable ID of an FO_TiApiClient FO_TiFlow FO_TiText or FO_TiTextTable ID of an FO_Element ID of an FO_Element ID of an FO_Element ID of an FO_Element ID of an FO_Element ID of an FO_Element Flags indicating which properties have changed see the table below ID of an FO_Rubi ID of an FO_Rubi ID of an FO_R
333. em while editing the DRE file you should not allow dialog items to overlap The following commands from the Graphics menu have no effect on a dialog box and its items e Reshape e Smooth e Unsmooth e Flip Up Down e Flip Left Right e Rotate e Set Number of Sides IMPORTANT The Undo command discards only changes in size and position The Undo command does not discard any other changes Redisplaying the dialog box Measurements in DRE files must use whole number values If you group items align items or work in a zoomed DRE file FrameMaker might not use whole numbers for measurements As a result the display of the dialog box might differ from the actual measurements of the dialog box by up to 0 5 pixels To see the correct view of the dialog box use the shortcut Esc d x Esc d w or Esc d m This redisplays the DRE file with the correct measurements Adding dialog items Because dialog items are special Frame graphic objects you cannot create them by using the Tools palette To create a dialog item you need to select an existing item in a DRE file and copy and paste the item When you add an item to a dialog box FrameMaker assigns the next highest item number to the item Some dialog items such as buttons checkboxes and radio buttons already contain labels You can add a label to dialog items that don t have labels such as text boxes pop up menus and scroll lists Figure 10 10 shows that the label for a text
334. en invoke Acrobat Distiller to create a PDF version of the document This is the same as choosing PDF from the Format popup menu in the Save As dialog box FS_AlertUserAboutFailure Specifies whether to notify the user if something unusual occurs while the file is being saved False don t notify user True notify user FS_SaveMode Specifies whether to use Save or Save As mode FV_ModeSaveAs use Save As mode FV_ModeSave use Save mode a Note This will only work if the Acrobat Distiller software is installed on the system For the complete property list returned by F_ApiGetSaveDefaultParams see F_ApiGetSaveDefaultParams on page 152 of the FDK Programmer s Reference For example to get a default saveParamsp property list and modify it so that it instructs F_ApiSave to save the active document as Text Only use the following code F_PropValsT params returnParamsp NULL F_ObjHandleT mydoclId Intl i Get the ID of the active document 62 xy FDK Programmer s Guide Executing Commands with API Functions 4 mydocId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Get default property list params F_ApiGetSaveDefaultParams FDK Programmer s Guide 63 a Executing Commands with API Functions 64 Get index of FS_FileType property and set it to Text Only i F_ApiGetPropIndex amp params FS_FileType params val i propVal u ival FV_SaveFmtText Save to text
335. en the user holds down the Shift key For example when the user holds down the Shift key and displays the File menu the label of the Close menu is Close All Open Files instead of Close If the user chooses the menu item the FrameMaker product closes all open files Shift menu items actually represent two separate commands which are linked by their FP_HasShiftOrUnshiftCommand and FP_ShiftOrUnshiftCommand properties For example the Close menu item represents the commands Close and CloseAll The following FDK Programmer s Guide Manipulating Commands and Menus with the API 9 table shows the values of their FP_HasShiftOrUnshiftCommand and FP_ShiftOrUnshiftCommand properties Command Property Value Close FP_HasShiftOrUnshiftCommand FV_ITEM_HAS_SHIFT_COMMAND FP_ShiftOrUnshiftCommand ID of CloseAll command CloseAll FP_HasShiftOrUnshiftCommand FV_ITEM_HAS UNSHIFT_COMMAND FP_ShiftOrUnshiftCommand ID of Close command The API allows clients to create and use shift menu items To combine two commands into a shift menu item you have to set the FP_HasShiftOrUnshiftCommand and FP_ShiftOrUnshiftCommand properties for only one of the commands The API automatically sets the properties of the other command for you For example the following code creates a shift menu item representing the client defined commands Checkin and CheckinAll If the user displays the Edit menu normally the label Check in Fil
336. ent FA_Note_PreSaveDoc Frame binary format 7 After saving the document FA_Note_PostSaveDoc Document saved as Before saving the document FA_Note_FilterOut filterable type Document exited Before exiting the document FA_Note_PreQuitDoc After exiting the document FA_Note_PostQuitDoc For a complete list of events and notification points see F_ApiNotification on page 226 of the FDK Programmer s Reference You can request notification in your client s F_ApiInitialize callback or anywhere you want in your client Example Suppose you want the FrameMaker product to notify your client whenever the user exits a document To request this notification when your client is first started write the F_Apilnitialize callback as follows FDK Programmer s Guide 35 E Creating Your Client s User Interface 36 VoidT F_Apilnitialize initialization IntT initialization Request notification for exit if initialization FA_Init_First F_ApiNotification FA_Note_PreQuitDoc True Requesting notification for API filters API client filters do not need to request notification To receive filter notifications filters only need to be registered with the FrameMaker product If they are correctly registered filters receive the following notifications This type of filter Receives this notification Import FA_Note_FilteriIn Export FA_Note_FilterOut File to file FA_Note_FilterFileToFil For more info
337. ent Reports from the File menu and then choosing the report from the Document Reports dialog box The FDK includes a sample document report named wordcnt which counts the number of words in a document For more information on sample programs provided with the FDK see the FDK Platform Guide for the platform you re using Filters A filter is a client that converts FrameMaker product files to or from other file formats An import filter is a filter that the FrameMaker product calls when the user attempts to open a non Frame file and chooses a filter in the Unknown File Type dialog box The import filter reads the file and converts it to a FrameMaker product document or book The FDK includes a sample import filter named mmlimport that converts MML files to FrameMaker product documents An export filter is a filter that the FrameMaker product calls when the user attempts to save a FrameMaker product document or book in a particular format by choosing the format in the Save dialog box or by specifying a filename with a particular extension The export filter writes information in the document or book to a file with a different format A file to file filter is a filter that the FrameMaker product can call to both import or export files of different formats A single file to file filter client can actually consist of more than one filter For example the same client could filter CGM to FrameVector and FrameVector to CGM The way you register the
338. ent attempts to import or open a graphic file with a format that the client filters The FrameMaker product invokes the client the same way in each of these situations It calls the client s F_ApiNotify callback with notit docId set to the ID of the active document if there is one and sparm set to the pathname of the file to filter The client s F_ApiNotify callback should do the following to respond to the FrameMaker product s call FDK Programmer s Guide fication setto FA_Note_FilterIn 241 12 Using Imported Files and Insets 1 Determine whether to open or import the graphic file If the user or another client is attempting to open the graphic file the FrameMaker product sets the docId parameter to 0 when it calls the client s F_ApiNotify callback If the user or client is attempting to import the graphic file into an existing document the FrameMaker product sets the docId parameter to a document ID 2 To open the graphic file create a new FrameMaker product document The client can create the document with F_ApiOpen or F_ApiCustomDoc The client can filter the imported graphic directly onto a page of the document or it can create an anchored frame for the graphic 3 To import the graphic file into an existing document determine where to import the graphic The client should check the document specified by the docId parameter of the F_ApiNotify call If the document has an insertio
339. entDefs F_ObjHandleT docOrBookId F_ObjHandleT fromDocOrBookId IntT importFlags This argument Means docOrBookId The ID of the document or book to import element definitions to fromDocOrBookId The ID of the document or book from which to import element definitions importFlags See the following table for the flags that you can OR into this parameter The following table lists flags that you can OR into the importFlags parameter Flag Meaning FF_IED_REMOVE_OVERRIDES Clear format overrides FF_IED_REMOVE_BOOK_INFO If docOrBookId specifies a document clear formatting inherited from the parent book FF_IED_DO_NOT_IMPORT_EDD If the document specified by fromDocOrBookId is an EDD don t treat it as an EDD just import its element catalog FDK Programmer s Guide 77 a Executing Commands with API Functions Flag Meaning FF_IED_NO_NOTIFY Do not issue the FA_Note_PreImportElemDefs or FA_Note_PostImportElemDefs notifications If you import element definitions to a book F_ApiSimpleImportElementDefs imports element definitions to each book component for which the FP_ImportFmtInclude property is setto True Calling FrameMaker clients programmatically Much of the structured document functionality FrameMaker provides is implemented in FDK clients To call this functionality programmatically you must use F_ApiCallClient F_ApiCall
340. er chooses it the FrameMaker product never executes the Print operation Instead it calls your client s F_ApiCommand callback with command set to PRINT_CMD The F_ApiCommand callback can execute your own version of the Print operation For example it can set the default number of copies to 1 and then call F_ApiSilentPrintDoc to print the document This prevents the user from printing more than one copy of a document at a time Allowing users to configure your client s interface When you call F_ApiDefineAndAddCommand and specify the name of a command that is already defined in the user s menu configuration files the FrameMaker product gives precedence to the definition in the configuration files If the configuration files assign a label or a shortcut to the command the FrameMaker product uses it instead of the one you specify If the command is already a menu item the FrameMaker product ignores the menu that you specify and leaves the menu item where it is For example if the Print command is already defined and appears on the File menu the following code has the same effect as the sample code in the previous section define PRINT_C 223 F_ObjHandleT printCmdId bogusMenulId 12345 printCmdiId F_ApiDefineAndAddCommand PRINT_CMD bogusMenulId Print This is ignored This too If you use this code the Print command appears on the File menu exactly as it normally does
341. er s Guide Using Imported Files and Insets 12o To use this import filter Use this hint string Ami Professional 1 0001AW4W0330 Lotus 1 2 3 5 0 0001AW4W0204 Lotus 1 2 3 4 0 0001AW4W0203 Microsoft Excel 5 0 OOOLAW4W0214 Microsoft Word97 98 2000 0001AW4W3490 ICHITAROS OOOLIVY JAW ICHITARO6 OOOLIVY JBW RTF Japanese OOO1LIVY RIF CGM Import IsoDraw 00011ISO CGM SVG 00010RBLSVG SGML 0001FRAMSGML XML 0001FRAMXML RTF Ver1 6 OOO1ADBIRTF WORD97 98 2000 000LADBIWORD Excel97 98 2000 OOO0LADBIXLS Hint strings for export filters To use this import filter Use this hint string Frame Vector 0001FRAMFRMV FrameImage 0001FRAMFRMI IGES 0001IMAGIGES QuickDraw PICT OOO1LIMAGPICT EPS 0001IMAGEPS TIFF 0001IMAGTIFF DIB 0001IMAGDIB GIF 0001IMAGGIF CCITTG4 0001IMACG4IM JPEG 0001IMAGJPEG FDK Programmer s Guide 253 12 Using Imported Files and Insets 254 To use this import filter Portable Network Graphics Windows Metafile PDF Microsoft RTF Microsoft Word Win 6 0 7 0 Microsoft Word Mac 6 0 Microsoft Word Mac 5 x Microsoft Word Mac 4 x WordPerfect DOS Win 5 1 WordPerfect Mac 3 5 RTF Japanese CGM Export IsoDraw HTML XML RTF1 6 Use this hint string 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 IMAGPNG IMAGWMF FRAMPDF AW4W0192 AW4Ww0490 AW4W04 9m AW4W0542 AW4wW0541 AW4W0071 AW4W0602 IVY RIFJ I
342. er s Reference amp Guide clipboard functions See Frame Clipboard functions Close Command compared with F_ApiClose G 67 closing channels G 377 R 351 dialog boxes G 227 R 5 documents and books G 66 to G 67 R 2 R 6 R 61 to R 62 file handles R 377 CMYK color model G 339 color models G 339 color views G 339 bit positions representing illustrated R 520 colors G 281 G 338 API representation of G 281 G 339 color models G 339 as organized in documents G 339 properties of G 339 R 519 to R 520 columns See table columns text columns text frames combined font definitions properties for R 522 combined fonts angles API specification of R 8 command shortcuts See keyboard shortcuts commands aborting G 37 adding to menu bars function for R 75 to R 77 adding to menus G 26 to G 28 functions for R 3 R 35 to R 37 R 75 to R 77 R 81 adding to multiple menus G 166 to G 167 API functions for R 3 API representation of G 161 to G 163 arranging on menus function for R 35 in the client user interface G 24 to G 31 client defined responding to R 3 context sensitive G 173 to G 175 creating G 158 function for R 3 defining G 26 to G 28 functions for R 75 to R 77 R 81 to R 82 determining existence of function for R 3 getting IDs of G 163 to G 164 function for R 3 linked lists of G 162 manipulating with the API _G 161 to G 176 properties of R 523 to R 528 removing function for R 3 FDK Programmer s Reference amp Guide Index
343. er size chunk you can set the facet more quickly However if you use too large a size you risk exceeding the interapplication communication mechanism s capacity For example to set the EPSI facet of a graphic inset to the contents of a file named mydata use the following code FDK Programmer s Guide 265 12 Using Imported Files and Insets 266 FDK Programmer s Guide Frame Product Architecture FDK Programmer s Guide 267 268 FDK Programmer s Guide Frame Session Architecture This chapter discusses the general organization of FrameMaker product sessions from a programmer s perspective It provides useful background information for programmers who want to use the Frame API Identifying objects The API assigns a unique ID to each object Most API functions that manipulate objects require you to specify this ID An object s ID is valid only as long as the object is available in the current FrameMaker product session For example suppose you have a document with a rectangle drawn in it When you open the document the API assigns an ID to the FO_Rectangle object that represents the rectangle As long as the document is open the ID of the FO_Rectangle object remains the same However if you exit the document and then reopen it the API may assign a new ID to the rectangle In addition to IDs there are two types of identifiers that are persistent between sessions e Unique object names e Unique persistent ide
344. erations on multiple files automatically For example you can use fmbatch for e Printing books or documents from a remote location e Printing multiple books or documents automatically e Updating multiple books or documents automatically e Converting multiple books or documents to MIF For more information on the fmbatch utility see the FrameMaker product user documentation for UNIX platforms Choosing the right Frame tools There are often several tools or combinations of tools that you can use to solve a given problem In particular you can use the API to perform many of the tasks that MIF and fmbatch perform The tool or combination of tools you should use depends on your needs Generally MIF and fmbatch are more useful for one time solutions to small problems whereas the API is more useful for full scale applications or applications where interaction with the user is required The following table summarizes the advantages and limitations of each Frame tool Frame tool or feature Advantages Limitations Frame API Fast interactive and portable easy to provide a user Must be compiled interface for your applications MIF Can be used by text processing utilities or UNIX shell Files must be saved as script It can also be used to provide backwards MIF not interactive compatibility allowing files to be opened in earlier releases of the product Third party MIF creators do not need to write complete MIF FrameMaker wil
345. erence MIF writing functions for directing output to a MIF output channel setting indent levels for the channel and writing a variety of simple MIF statements e I O functions for writing and reading from input channels when byte swapping is necessary How to make your client portable To use the FDE to make your client portable follow these general steps 1 Add a call to F_FdeInit to initialize the FDE environment To initialize the FDE environment call F_FdeInit as follows F_FdeInit Replace C primitive data types with FDE types Replace any C primitive data types such as char or int with FDE types such as UCharT or InttT FDK Programmer s Guide Introduction to FDE 16 3 Replace I O and memory calls in your client with calls to the FDE s virtual environment Use the FDE virtual environment s channel I O and memory functions to make your I O and memory calls platform independent For a description of the virtual environment and its I O and memory facilities see Chapter 17 Making I O and Memory Calls Portable 4 Replace string character and other platform specific C library function calls with corresponding calls to FDE utility library functions For information on the utility library functions see Chapter 2 FDK Function Reference of the FDK Programmer s Reference 5 Include the appropriate FDE header files All FDE clients must include the fdetypes h header file If you are u
346. erties on page 197 Checkboxes A checkbox allows the user to choose from two or three options A checkbox can have two states on or off or three states on as is or off For example checkboxes in the FrameMaker Find Change dialog box have two states the checkboxes in the Character Designer have three states Three state checkboxes are also called triboxes Triboxes and two state checkboxes are handled as different objects internally by FrameMaker For more information see How the API represents dialog boxes on page 211 In addition to the basic properties of the dialog item see Setting basic dialog item properties on page 197 checkboxes have the following properties e Initial state of the checkbox In the Initial State text box type 0O if the checkbox is initially off or 1 if it is initially on e Number of states for the checkbox In the States text box type 2 if the checkbox has two states or 3 if the checkbox has three states The checkbox item includes a label To change the text in the label select the text next to the checkbox and type over it Radio buttons A radio button allows the user to select one choice out of several choices Each radio button belongs to a set Only one radio button in a set can be selected at a time In addition to the basic properties of the dialog item see Setting basic dialog item properties on page 197 radio buttons have the following properties e Initial stat
347. erty FO_PgfFmt R 627 FP_PgfCatalogReference property FO_FmtChangeList G 347 R 582 FP_PgfIsAutoNum property FO_FmtChangeList R 584 FP_PgfIsAutoNum property FO_Pgf G 303 R 613 FP_PgfIsAutoNum property FO_PgfFmt R 623 FP_PgfNumber property FO_Pgf G 303 R 614 FP_PgfNumbering property FO_BookComponent R 512 FP_PgfNumComputeMethod property FO_BookComponent R 512 FP_PgfNumComputeMethod property FO_Doc R 548 R 558 FP_PgfSpellChecked property FO_Pgf R 618 FP_Placement property FO_FmtChangeList R 588 FP_Placement property FO_Pgf R 620 FP_Placement property FO_PgfFmt R 627 FP_Platform property FO_Session R 635 FP_PointPageNum property FO_BodyPage R 611 FP_PointPageNumStyle property FO_Doc R 561 FP_Points property F_ApiSetPoints G 100 FP_Points property FO_Line R 602 FP_Points property FO_Polygon R 604 FP_Points property FO_Polyline R 604 FP_PolyIsBezier property FO_Polygon R 604 FP_PolyIsBezier property FO_Polyline R 604 index 59 os Index Reserved Names FP_Position property FO_CharFmt R 517 FP_Position property FO_Doc R 575 FP_Position property FO_FmtChangeList R 587 FP_Position property FO_Pgf R 615 FP_Position property FO_PgfFmt R 624 FP_Position property text location R 671 FP_PrefixRules property G 108 FP_PrefixRules property FO_ElementDef G 343 R 647 FP_PrevAFrame property FO_AFrame R 597 FP_PrevCell property FO_Cell R 651 FP_PrevCellInRow property FO_
348. erty list returned by F_ApiGetUpdateBookDefaultParams The first value listed for each property is the default value for the property You can change any property in the list to use its other legal values Property Meaning and possible values FS_AlertUserAboutFailure Specifies whether to notify the user if something unusual occurs during the update operation False don t notify user True notify user FS_MakeVisible Make newly generated files lists and indexes visible True make visible False don t make visible FS_ShowBookErrorLog Specifies whether to use the book error log to display warnings False don t display book error log display warnings in the console True display the book error log For the complete list returned by F_ApiGetUpdateBookDefaultParams see F_ApiGetUpdateBookDefaultParams on page 187 of the FDK Programmer s Reference For example to get a default updateParamsp property list and modify it so that it instructs F_ApiUpdate to show the book error log use the following code F_PropValsT params ErrorT err Get the default parameter list params F_ApiGetUpdateBookDefaultParams Get the index for the error log property then set the property to True i F_ApiGetPropIndex amp params FS_ShowBookErrorLog params val i propVal u ival True The API allocates memory for the property list created by F_ApiGetUpdateBookDe
349. es a handle F_ClearHandle initializes a handle s block of data and F_FreeHandle frees memory allocated to a handle Handle memory functions that are typed ErrorT return FdeSuccess if they are successful Other handle memory functions return NULL if they are unable to comply with a request To use the FDE memory functions you must include fdetypes h and fmemory h in your program Allocating memory with pointers The FDE provides functions that allow you to allocate and deallocate memory with pointers For example F_Alloc allocates memory F_ClearPtr initializes a pointer s block of data and F_Free frees memory allocated to a pointer Pointer memory functions that are not typed ErrorT return NULL if they are unable to comply with a request Functions that are typed ErrorT return FdeSuccess if they are successful If you are a UNIX programmer you should avoid static memory allocation because it consumes valuable data and heap space on the Windows and Macintosh platforms To use the FDE memory functions you must include fdetypes h and fmemory h in your program Error and progress reporting The virtual environment provides functions that allow you to report error and progress status For example F_Warning prints a warning message to the console window on UNIX platforms or to the error log window on the Macintosh or the Frame console on Windows To use the FDE progress reporting functions you must
350. es by name in the FDK Reserved Names Index property data types tables of G 270 G 273 property identifier structure G 272 R 684 property lists G 3 G 81 G 270 G 272 to G 274 allocating memory for function for R 11 R 45 to R 46 API representation of G 272 deallocating memory from function for R 11 R 74 getting G 92 to G 94 function for R 16 R 150 to R 151 getting default functions for R 24 R 120 to R 128 R 138 to R 146 R 152 to R 158 R 187 to R 190 getting particular properties in G 93 illustrated G 274 manipulating directly G 93 to G 94 Open script G 49 to G 50 FDK Programmer s Reference amp Guide Index Subjects a order of properties in G 93 printing values in specified function for R 252 for scriptable functions G 46 setting G 92 to G 94 function for R 16 R 297 setting function for R 16 structure for G 272 R 684 property names identifying properties by G 272 property number constants identifying properties by G 272 property value constants naming convention for G xiii R xix property value data types See property data types property value type constants See property value types property value types tables of G 273 R 690 property values G 3 to G 4 G 270 to G 271 G 390 data types for tables G 270 G 273 structure for individual R 689 types of tables G 273 R 690 union for sets R 690 property value pairs function for getting indexes of R 24 R 149 functions for printing R 5 R 252 struc
351. es out the additional files mydialog dlg and mydialog xdi These files are resource description files recognized by Windows and are used to compile the dialog box resources with your FDK client e If you are using the UNIX version FrameMaker writes out an X resource file x The files use the same base name as the DRE file For example if your DRE file is named mydialog dre FrameMaker writes out the additional file mydialog x This resource description file is recognized by X Windows and is used to display the dialog box for your FDK client Be sure you do not use the name of a standard FrameMaker dialog box for as the name of your dialog box you can see the filenames for the X resource files for the standard FrameMaker dialog boxes in SFMHOME fminit UILanguage xresources Check these names to be sure you don t make a dialog box resource with a duplicate name FDK Programmer s Guide 181 a Creating Custom Dialog Boxes for Your Client 182 e The Macintosh version of FrameMaker does not write out any platform specific resource files During the build process on the Macintosh the DRE file is converted to Macintosh resources which are placed in the resource fork of the FDK client The rest of this section briefly describes how dialog boxes are included in your FDK client For further details see the FDK Platform Guide for your platform Dialog box information in Windows In the Windows build process dialog box informati
352. ese objects as shown in Figure 14 7 FDK Programmer s Guide 295 14 Frame Document Architecture 296 FO_BodyPage gt FP_PageFrame FP_FirstGraphicInFrame FP_FirstGraphiclnFrame m Draw Order p FO_Ellipse FO_UnanchoredFrame Page frame FP_LastGraphiclnFrame FO_UnanchoredFrame Ik E E g Ww We 2 2 Q Q 0 0 5 2 o a ols Ww We y FO_TextLine FP_LastGraphiclnFrame al phiclnFrame phiclnFrame FP_PrevGra FP_NextGraphi a FO_Rectangle A phicInFrame phicInFrame FP_NextGra FP_PrevGra lt a FO_Polygon FiGURE 14 7 API objects that represent a page and the graphic objects on it How the API represents groups The API represents a grouped set of graphic objects with an FO_Group object It maintains the objects that constitute a group in a linked list The FO_Group properties FP_FirstGraphicInGroup and FP_LastGraphicInGroup specify the first and last objects in the list Each graphic object has FP_PrevGraphicInGroup and FP_NextGraphicInGroup properties which specify the objects before and after it in the list Grouping graphic objects does not affect their position in the linked list of API graphic objects in a frame That is it does not affect their position in the draw order Group objects themselves have an arbitrary posit
353. essing the property directly use the following code IntT i F_PropValsT props props F_ApiGetProps 0 FV_SessionId i F_ApiGetPropIndex amp props FP_ProductName F_ApiAlert props val i propVal u sval FF_ALERT_CONTINUE_NOTE Allocating and deallocating memory for properties The F_ApiGetPropertyType functions that return pointers to arrays make copies of the arrays allocating memory for them For example F_ApiGetString does not return a pointer to the actual string used by the FrameMaker product Instead it creates a copy of the string and returns a pointer to the copy The API does not deallocate memory used by the copy of the string When you are done with it you must deallocate it Similarly when you calla F_ApiSet PropertyType function such as F_ApiSetString the function does not set a pointer to the string you pass to it Instead it copies the string The API does not deallocate the string you pass When you are done with it you must deallocate it For example the following code queries and displays the FP_OpenDir property It uses the FDE function F_Free to free the returned string 94 FDK Programmer s Guide Getting and Setting Properties 5 include fstrings h include fmemory h StringT openDir openDir F_ApiGetString 0 FV_SessionId FP_OpenDir F_ApiAlert openDir FF_ALERT_CONTINUE_NOTE F_Free openDir For more informa
354. et its first parameter to the dialog resource ID and its second parameter to the ID of the item for which you want to get or set a property For more information on using F_ApiGetPropertyType and F_ApiSetPropertyType functions see Chapter 5 Getting and Setting Properties For example if you create a dialog resource named mydlg which contains a checkbox with the item number 3 the following code opens the resource and turns the checkbox on define CHECKBOX_ITEM_NUM 3 F_ObjHandleT dlgId dlgId F_ApiOpenResource FO_DialogResource mydlg F_ApiSetInt dlgId F_ApiDialogItemId dlgId CHECKBOX_ITEM_NUM FP_State FV_DlgOptActive Manipulating related items When you change a dialog box programmatically the dialog box behaves as if you are changing it interactively For example if you programmatically turn on one radio button in a set the radio button in the set that was previously turned on automatically turns off If a text box is the stuff item for a pop up menu when you choose a setting in the pop up menu the item is automatically stuffed in the text box FDK Programmer s Guide 213 E Handling Custom Dialog Box Events Overview of using a custom dialog box in your client 214 To use a custom dialog box in your client follow these general steps 1 Call F_ApiOpenResource to open the dialog resource Set the first parameter of F_ApiOpenResource to FO_DialogResource and the
355. etFile property specifies an external file which contains the data the FrameMaker product uses to display the graphic For a more detailed description of graphic insets and how to manipulate them see Writing graphic inset editors on page 256 Imported PDF pages FrameMaker provides special functionality for selecting and importing a page of a PDF file The page displays within an anchored frame and is treated as an imported graphic For an example of how to do this via the FDK see Importing a page of a PDF file on page 233 Imported markup files FrameMaker provides special functionality for importing and exporting XML and SGML documents It provides default import and export which can handle most markup documents If you have complex markup you can customize the default import and export with read write rules or use the Structure Import Export API to customize SGML or XML import export clients For more information on importing and exporting markup files see the online manual Structure Import Export API Programmer s Guide Importing text and graphics To import text or graphics into a FrameMaker product document use F_ApiImport With F_Apilmport you can specify aspects of the Import operation such as whether to import a file by reference or by copy 230 FDK Programmer s Guide Using Imported Files and Insets 12 F_ObjHandleT F_ApilImport F_ObjHandleT enclosingDocId F_TextLocT textLocP StringT filename
356. eted FDK Programmer s Guide 319 14 Frame Document Architecture The FO_Doc property FP_MarkerTypeNames specifies an F_StringsT structure which provides the list of marker types available in the current document The document object also has an FP_FirstMarkerTypelInDoc property as an entry into the document s list of marker types Given a marker type name you can use F_ApiGetNamedOb ject to get the ID of the associated FO_MarkerType The following code returns the ID of the index marker type F_ObjHandleT docId markerId Get ID of the active document docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc markerId F_ApiGetNamedObject docId FO_MarkerType StringT Index Figure 14 24 shows an index marker anchor and the text item that represents it Marker Type Index Marker Text presidents past New Marker This MOREEN E A E ipii g offset 40 dataType FTI_MarkerAnchor idata FO_Marker ID FIGURE 14 24 A marker anchor and the text item that represents it The following table lists some of the properties of the FO_Marker object specified by FTI_MarkerAnchor in Figure 14 24 Property Type Value FP_MarkerTypeId F_ObjHandleT ID of the FO_MarkerType for Index FP_MarkerText StringT presidents past FP_NextMarkerInDoc F_ObjHandleT ID of the next FO_Marker object in the document 320 FDK Programmer s Guide Frame Document Architecture 14 Adding marker types to do
357. eted notification constant R 231 FA_Note_ClientCall notification constant R 230 R 269 FA_Note_DirtyBook notification constant R 229 FA_Note_DirtyDoc notification constant R 229 FA_Note_DisplayClientTiDialog notification constant R 230 R 269 FA_Note_FilterFileToFile notification constant R 235 R 236 FA_Note_FilterIn notification constant G 35 G 41 R 227 R 235 R 236 R 269 FA_Note_FilterOut notification constant G 35 R 229 R 235 R 236 FA_Note_Num notification constant R 232 FA_Note_PostAutoSaveDoc notification constant R 229 FA_Note_PostBookComponentOpen notification constant R 228 FA_Note_PostChangeElement notification constant R 231 FA_Note_PostDistill notification constant R 229 index 41 os Index Reserved Names FA_Note_PostDragElement notification constant R 232 FA_Note_PostFileType notification constant G 35 G 41 R 227 R 228 FA_Note_PostFunction notification constant G 38 G 214 G 220 R 230 R 235 R 236 R 237 FA_Note_PostGenerate notification constant R 228 R 235 FA_Note_PostGoToXrefSrc notification constant R 231 FA_Note_PostHypertext notification constant R 231 R 235 FA_Note_PostImport notification constant R 230 R 235 FA_Note_PostImportElementDefs notification constant R 232 FA_Note_PostInlineTypeIn notification constant R 232 FA_Note_PostInsertElement notification constant R 231 R 235 FA_Note_PostMouseCommand notification constant R 230 R 236 FA_Note_PostOpe
358. etricT properties metrics F_MetricsT properties MIF Maker Interchange Format G x G 390 R xvi advantages and limitations of G xi R xvii importing MIF files as text G 229 See also MIF functions MIF statements MIF write output channel FDK Programmer s Reference amp Guide MIF lt MathFullForm gt statement R 603 MIF data structures G 384 to G 385 setting fields in G 385 MIF files G x G x1 R xvi R xvii MIF functions G 366 G 381 G 385 to G 387 R 408 to R 418 simple G 381 G 387 R 418 MIF library FDE G 385 to G 387 R 418 See also MIF functions MIF write output channel MIF macros G 384 to G 385 MIF statements functions for G 385 ending R 410 starting new R 408 substatements in G 385 See also MIF write output channel MIF write output channel functions for G 386 indenting R 411 to R 413 returning the current indent level R 411 setting G 386 R 415 setting the indent level G 386 R 414 writing a blank space to R 416 writing a comment string to R 408 writing a decimal to R 409 writing a new line to R 414 writing a tab space to R 416 writing a text string to R 417 writing an integer to R 413 MifUnitT values G 386 R 409 minus sign conditional text marker prefix G 318 mmlimport filter G 5 modal dialog boxes G 17 G 177 G 197 G 205 to G 206 G 211 R 206 to R 207 displaying function for G 219 displaying dialog resources as function for R 206 handling user actions in G 223 to G 225 multiple interactio
359. ets importing element definitions G 77 formats from documents G 72 function for R 192 to R 197 main flow of a Frame document file G 232 properties for import operations tables R 120 to R 127 FDK Programmer s Reference amp Guide text and graphics G 230 to G 235 text files G 229 G 230 G 234 R 126 to R 127 See also graphic insets insets text insets importing element definitions G 77 inclusions in content rules lists of G 342 indentation See paragraph formats FO_PgfFmt indentation properties of paragraphs FO_Pgf indentation properties of indexes generating G 297 initialization callback function G 7 G 10 R 198 to R 199 creating G 13 G 35 definition of G 13 initialization calls G 5 responding to G 13 function for R 1 R 198 to R 199 initialization constants naming convention for G xiii R xix tables of G 14 R 198 initialization flags See initialization constants initialization types G 14 to G 16 R 198 initializing after bail out G 15 of document reports G 15 FDE Frame Development Environment G 366 G 375 R 374 FDE font encoding data R 375 of filters G 15 first G 14 preventing G 16 take control G 14 types of G 14 to G 16 R 198 See also initialization callback function initialization calls initialization constants input prompting users for G 7 G 17 to G 24 input dialog boxes displaying G 18 to G 21 See also dialog boxes input output calls See I O calls Insert Table dialo
360. etting its FP_TiLocked property to False When you are finished modifying its contents you should set its FP_TiLocked property back to True To update a client text inset you may want to delete its current contents The API provides a function F_ApiDeleteTextInsetContents which makes this easier The syntax for F_ApiDeleteTextInsetContents is IntT F_ApiDeleteTextInsetContents F_ObjHandleT doclId F_ObjHandleT insetId This argument Means docId The ID of the document containing the text inset insetId The text inset containing the text to be deleted FDK Programmer s Guide 237 12 Using Imported Files and Insets 238 If your client is unable to update one of its client text insets it should set the inset s FP_TilsUnresolved property to True For example the following code handles the FA_Note_UpdateClientTi notification Request notification F_ApiNotification FA_Note_UpdateClientTi True F_ApiNotify function to handle notifications VoidT F_ApiNotify notification docId sparm iparm IntT notification F_ObjHandleT docId StringT sparm IntT iparm F_TextRangeT tr if notification FA_Note_UpdateClientTi FA_errno FE_Success Initialize and check later tr F_ApiGetTextRange docId iparm FP_TextRange Unlock inset so it can be modified F_ApiSetInt docId iparm FP_TiLocked False Delete existing contents and add some new stu
361. ewOnlyMainMenu Defining commands and adding them to menus To define a command and add it to a menu use F_ApiDefineAndAddCommand The syntax for F_ApiDefineAndAddCommand is F_ObjHandleT F_ApiDefineAndAddCommand IntT cmd F_ObjHandleT toMenuld StringT name StringT label StringT shortcut This argument Means cmd The integer that the FrameMaker product passes to your client s toMenuld name label shortcut F_ApiCommand function when the user chooses the menu item or types the keyboard shortcut for the command The ID of the menu to which to add the command A unique name to identify the command The title of the command as it appears on the menu The keyboard shortcut sequence Many FrameMaker product commands use shortcuts beginning with Esc To specify Esc when you create a command use in the string you pass to shortcut F_ApiDefineAndAddCommand returns the ID of the command it creates IMPORTANT To ensure that your client is portable to the different platforms that FrameMaker supports specify only shortcuts that begin with Esc On UNIX the Esc shortcut appears on the menu next to the menu item label On the Macintosh or Windows the shortcut does not appear However the user can still execute it For example if you specify xy for the keyboard shortcut the user can execute the command from the keyboard by pressing Esc x y For FDK Programmer s Guide Creati
362. ext like this For example this represents the name of your working directory Myair e Omitted code in source code examples is indicated with ellipses For example the ellipsis in the following code indicates that some of the code necessary to create a complete program is omitted F_ApiAlert StringT Hello world FF_ALERT_CONTINUE_NOTE FDK Programmer s Guide Frame Application Program Interface AP FDK Programmer s Guide 1 FDK Programmer s Guide Introduction to the Frame API This chapter provides an overview of how the API works and how to create an FDK client It also provides a simple example a client that you can create and run right away The API enables you to create a client that takes control of a FrameMaker product session With the API a client can do almost anything an interactive user can do It can create save and print documents add and delete text and graphics and perform many other formatting and document management tasks It can also interact with the user by responding to user actions displaying dialog boxes and creating menus How the API works The API represents everything in a FrameMaker product session as an object Each object has a type a constant that indicates the type of thing it represents For example an object s type can be FO_Doc if it represents a document FO_Rectangle if it represents a graphic rectangle or FO_Pgf if it represents a paragraph
363. ext range use F_ApiSetTextPropVal or F_ApiSetTextProps The syntax for these functions is VoidT F_ApiSetTextPropVal F_ObjHandleT doclId F_TextRangeT textRangep F_PropValT setVal VoidT F_ApiSetTextProps F_ObjHandleT doclId F_TextRangeT textRangep F_PropValsT setVal This argument Means docId The ID of the document containing the text textRangep The text range setVal The property or property list to apply to the text range Applying a character format to text To apply a character format to a text range copy the property list of the FO_CharFmt object that represents the character format to the text range For example to apply the character format named Emphasis to the current text selection use the following code FDK Programmer s Guide Manipulating Text 6 F_TextRangeT tr F_PropValsT props F_ObjHandleT docId charFmtId IntT i docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc if docId return Get current text selection Return if there isn t one tr F_ApiGetTextRange FV_SessionId docId FP_ TextSelection if tr beg objId return Get Emphasis properties charFmtId F_ApiGetNamedObject docId FO_CharFmt Emphasis props F_ApiGetProps docId charFmtId Apply properties to selection F_ApiSetTextProps docId amp tr amp props This code has the same effect as choosing Emphasis in the Character Catalog If no text is sele
364. ext to G 122 API representation of G 333 to G 334 G 336 custom shading and filling G 333 to G 334 index 3 index 4 Index Subjects properties of G 333 G 336 R 616 to R 617 R 628 R 648 to R 651 selecting function for R 17 R 22 R 201 to R 202 selection state of G 286 straddling G 75 to G 79 G 337 to G 338 function for R 22 R 331 to R 332 illustrated G 338 as text frames G 332 unstraddling G 75 to G 79 G 337 to G 338 function for R 22 R 336 to R 337 illustrated G 338 See also rows change bar properties See document properties change bars for documents document properties for G 284 function for clearing R 7 R 58 change lists document properties for R 566 channels G 377 G 389 functions for G 377 R 350 appending the contents of one to another R 350 closing G 377 R 351 determining offsets on R 358 flushing buffered output into R 352 indicating the ends of R 352 making temporary R 353 opening G 377 R 353 printing formatted output to R 424 reading G 377 R 356 reading bytes from R 427 reading formatted input R 436 returning the next byte of R 355 returning the size of R 357 setting offsets on R 357 writing to G 377 R 359 T O channels FDE G 366 Character Catalog G 305 Character Catalog formats G 280 G 305 to G 309 API representation of G 280 G 306 applying G 306 to text G 124 creating G 306 G 308 as organized in documents G 309 overriding G 311 properties of G 306 G 308 to G 309 R 515 to R 518 t
365. extComponentInBook properties that specify the IDs of the previous and next FO_BookComponent objects in the list The order of the list is the same as the order of the components in the book Suppose you create the book shown in Figure 15 1 on page page 352 The API represents this book with the objects shown in Figure 15 2 on page page 355 354 FDK Programmer s Guide Frame Book Architecture io FP_FirstComponent InBook O_Book myDoc1 fm FO_Book gt Component y FP_NextComponent InBook FO_Book Component myDoc2 fm FP_PrevComponent InBook FO_Book Component myDoc3 fm FIGURE 15 2 Objects that represent a book and its components How the API represents structured books If a book is a FrameMaker structured book it has an FP_HighestLevelElement property which specifies the ID of the FO_Element object that represents the root element Each component in the book also has an FP_ComponentElement property which specifies the FO_ Element object ID for that component s structure element Creating new books and components To create a new book use F_ApiNewNamedOb ject If you pass an empty string for the object name the FrameMaker product creates an untitled book To insert a new book component in a book use F_ApiNewSeriesOb ject This creates a new book component but the component has no document file assigned to it If the user tries to to open such a component
366. f information Condition formats Markers Marker types Cross reference formats Cross reference instances Variable formats Variable instances Footnotes Table ruling formats Table Catalog formats Tables Colors Text insets Structural element definitions Structural element instances Format rules Function Specify tags that the user can apply to text to indicate that it belongs to a particular variation of the document Describe placeholders that contain hidden text Specifies a named catagory of markers Specify the wording and typographic style of cross references Describe instances of cross references in the document Specify units of text and system supplied information that the user can use multiple times in a document Describe instances of variables in the document Describe footnotes Specify rulings and shadings that the user can apply to individual table cells Specify table formats that the user can apply to a table and that provide default numbers of columns and rows for new tables Describe instances of tables in the document and specify formatting information such as alignment ruling and shading Specify colors that the user can apply to graphic objects and text Describe text that is imported by reference Specify tags that specify the organization of parts of a FrameMaker structured document Describe instances of structural elements in a structured document
367. f is specified no unit symbol is generated All the MIF library functions are prefixed with F_Mif To use the FDE MIF functions you must include fdetypes h and fmi fstmt h in your program Simple MIF library The simple MIF library functions are useful for writing individual MIF statements Each function s name corresponds to the MIF statement that it writes If a MIF statement uses an enumerated value string such as Left Right or Center you construct a constant from that string by prefixing it with MIF For example the enumerated value strings for the lt DParity gt MIF statement are FirstLeft and FirstRight When you call the corresponding MIF library function F_MifDParity you can specify either MIFFirstLet ft or MIFFirstRight forthe DParity argument If you aren t sure if a certain constant exists you can check for it inthe fmiftype h header file For the syntax and description of MIF statements see the online MIF Reference All simple MIF library functions have the prefix F_Mif To use them you must include FDK Programmer s Guide fdetypes h and fmifstmt h in your program 387 Glossary This glossary contains words used in the FDK Programmer s Guide For other references providing more information about a term see the index anchored frame bail out body page building blocks callback channel child graphic objec
368. f the encoding for s Internal strings in FrameMaker Internal strings such as encoding names marker text or FrameMaker product client names all use text in the 7 bit ASCII range Tags paragraph format tags for example can use double byte text However for FrameMaker documents the tag names of elements cannot use double byte text Text in an unsupported encoding A document can include text in an encoding that is not supported by the current system configuration In this case FrameMaker retains the encoding identification with the text even though it can t display the text correctly This is referred to as a ghost encoding For example suppose a document contains Japanese text but the system can only display Western text The Japanese text appears as a series of arbitrary characters each character corresponding to a single byte of what might be a double byte or single byte Japanese character If you get the encoding for that text the FDE will return JISX0208 ShiftJIS Note that ghost encoded text is displayed as though it is FrameRoman text This is important because it is likely that line breaks will split up double byte characters Furthermore functions like F_CharIsDoubleByteFirst and F_CharIsDoubleByteSecond return FDK Programmer s Guide 141 Manipulating Asian Text unreliable results For this reason you have no way to ensure ghost encoded text items are valid and we suggest you specifically do not proces
369. faultParams Use F_ApiDeallocatePropVals to free the property list when you are done with it 358 FDK Programmer s Guide Frame Book Architecture jo Creating an updateParamsp script from scratch If you want to specify only a few properties when you call F_ApiUpdat eBook it is most efficient to create a property list from scratch To create the property list you must allocate memory for it and then set up the individual properties Use the API convenience function F_ApiAllocatePropVals to allocate memory for the property list For example the following code creates an updateParamsp property list that will instruct F_ApiUpdateBook to display the error log DEFINE ERR_LOG 0 F_PropValsT params returnParamsp NULL Allocate memory for the list params F_ApiAllocatePropVals 1 Set up FS_ShowBookErrorLog property and set it to True params val ERR_LOG propIdent num FS_ShowBookErrorLog params val ERR_LOG propVal valType FT_Integer params val ERR_LOG propVal u ival True When you re finished free the F_PropValsT F_ApiDeallocatePropVals amp params Checking update status F_ApiUpdateBook stores a pointer to a property list in updateReturnParamspp the list contains one property which contains flags to indicate the status For a list of the possible flags see F_ApiUpdateBook on page 338 of the FDK Progr
370. ff F_ApiDeleteTextInsetContents docId iparm F_ApiAddText docId amp tr beg New text If there were errors the inset is unresolved if FA_errno FE_Success F_ApiSetInt docId iparm FP_TilsUnresolved True Relock inset F_ApiSetInt docId iparm FP_TiLocked True Displaying a Text Inset Properties dialog box When a user double clicks a text inset that isn t a client text inset the FrameMaker product displays the Text Inset Properties dialog box This dialog box provides information about the text inset such as the last modification date of the inset s source file and the date the inset was last updated It also provides buttons for the user to execute some operations such as convert the inset to text When a user double clicks one of your client s text insets the Frame product does not display a Text Inset Properties dialog box To display a Text Inset Properties dialog box your client must request the FA_Note_DisplayClientTiDialog notification If your client has requested this notification when the user double clicks one of its insets the FrameMaker FDK Programmer s Guide Using Imported Files and Insets La product calls the client s F_ApiNotify callback with notification set to FA_Note_DisplayClientTiDialog and iparm set to the inset ID When your client receives the notification it can display its own Text Inset Properties dialog box This dialog box does not need to appear
371. filters G 373 dialog boxes on G 180 to G 181 G 189 disabling clients G 16 image pop up menus G 200 memory management on G 378 to G 379 registering clients with the FrameMaker product G 8 G 12 saving global document information G 285 take control initialization G 15 main flows G 297 makefiles G 8 Maker Interchange Format See MIF Maker Interchange Format manipulating asian text G 131 to G 142 document windows G 97 expandomatic menu items G 172 to G 173 menu item separators G 169 to G 170 properties G 89 to G 95 property lists G 93 to G 94 selected graphic objects G 87 text G 111 to G 129 marker anchors API representation of G 312 G 314 R 166 R 687 illustrated G 320 marker types API representation of G 281 properties of R 609 Marker window G 319 markers G 281 G 319 to G 320 Adding marker types to documents G 321 API representation of G 281 G 319 to G 320 conditional text illustrated G 318 creating G 148 to G 149 functions for R 14 R 210 to R 212 Mapping old marker types to named marker types G 321 properties of G 319 to G 320 R 608 The standard list of marker types G 321 See also hypertext markers master pages G 289 G 292 API representation of G 289 G 292 creating See named objects creating default G 292 properties of G 290 G 291 to G 292 R 612 FDK Programmer s Reference amp Guide master pointer G 378 See also pointers math equations See equations memory allocating functions for R 32 to
372. fined as typedef struct UIntT len Number of strings StringT val Font names F_StringsT For example if Courier Helvetica and Times are the only font families available in the current session the fields of the F_StringsT structure specified by FP_FontFamilyNames have the following values len 4 val lt Reserved gt Courier Helvetica Times Properties that specify font families angles weights and variations use the index of the val array For example the FO_CharFmt property FP_FontFamily specifies the font family for a character format Given the F_StringsT values shown above if the font family for a character format is Helvetica the value of the format s FP_FontFamily property is 2 Although a specific angle weight or variation may be in one of the lists described above it may not be available for all combinations of font families angles weights and variations For example the Bold weight may be available for Times and Helvetica but not for Zapf Chancery The FDK provides a convenience function named F_ApiFamilyFonts which returns all the permutations of font families angles weights and variations in a FrameMaker product session For more information see F_ApiFamilyFonts on page 99 of the FDK Programmer s Reference FDK Programmer s Guide 277 mie Frame Session Architecture 278 FDK Programmer s Guide Frame Document Architecture This chapter describes F
373. fined as typedef struct UIntT len The number of unsigned bytes UByteT val The facet data F_UBytesT Internal and external graphic insets There are two types of graphic insets internal and external You choose which type your client supports Both types require a display and print facet and can have one or more client specific facets Internal graphic insets Internal graphic insets are wholly contained within a FrameMaker product document If a graphic inset is internal the FO_Inset object s FP_InsetFile property is set to a null string Internal graphic insets are generally more portable than external graphic insets To update an internal graphic inset the user starts the FrameMaker product and initiates an event that the graphic inset editor monitors For example if the user double clicks the inset the graphic inset editor updates the inset by setting its facets The following EPSI facet data describes the rectangle in Figure 12 1 FIGURE 12 1 A graphic inset FDK Programmer s Guide 259 12 Using Imported Files and Insets UbyteT epsFacet PS Adobe 2 0 EPSF 2 0 n Pages 0 n S BoundingBox 0 0 18 18 n S Creator kurt n CreationDate Fri Oct 16 10 40 20 1992 n EndComments n SsBeginPreview 18 18 1 18 n ole oe 000040 n 40 n 40 n 40 n 40 n 40 n 40 n 000040 n 40 n 40 n 40 n 40 n 40 n 40 n 40 n 000040 n SFFFFCO
374. fined as 0 Examples The following code closes the active document If the document has unsaved changes the client prompts the user F_ObjHandleT docId IntT resp 0 Get the ID of active document Return if there isn t one docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc if docId return See if document has been modified if F_ApiGetInt FV_SessionId docId FP_DocIsModified resp F_ApiAlert Document was changed close it anyway FF_ALERT_OK_ DEFAULT if resp F_ApiClose docId FF_CLOSE_MODIFIED The following code closes the active document unless it has unsaved changes F_ObjHandleT docId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc if docId return if F_ApiClose docId 0 F_ApiAlert Unsaved changes Can t close FF_ALERT_CONTINUE_WARN Quitting a Frame session To quit a Frame session call F_ApiClose with Id setto FV_SessiontId For the syntax of F_ApiClose see Closing documents and books on page 66 For example to close all the open documents and books in the current Frame session and quit the session use the following code FDK Programmer s Guide 67 a Executing Commands with API Functions F_ApiClose FV_SessionId FF_CLOSE_MODIFIED Because of the flag set to FF_CLOSE_MODIFIED if any books or documents have been changed the FrameMaker product abandons the changes Comparing documents and
375. finition is defined in the Element Catalog and whether it can be used as the highest level element for a flow e The ID of the next FO_ElementDef object in the document e Initial structure rules for automatic insertion of child elements e Initial pattern rules for table components The API uses an FO_FmtRule object to represent each of an element definition s format rules The FO_ElementDef object has the following properties that specify an element definition s format rules e FP_FirstPgfRules e FP_LastPgfRules FP_ObjectFmtRules e FP_PrefixRules Hy P_SuffixRules Hj e FP_TextFmtRules Each of these properties specifies an F_IntsT structure which provides a list of FO_FmtRule IDs For example suppose you create the element definition shown in Figure 14 35 Element type and name Element Container Item Content rule General rule lt TEXT gt Text format rules Element paragraph format item 1 If context is BulletList Numbering properties Autonumber format b t Else if context is NumberList Numbering properties Autonumber format lt n gt t Optional comment Comment For normal body paragraphs Text format rules FIGURE 14 35 Element definition for Item element FDK Programmer s Guide 343 14 Frame Document Architecture 344 The API represents the element definition in Figure 14 35 as an
376. fmtRuleld Determining the formatting that applies to an element To determine the formatting that applies to an element you first get the following properties e FP_MatchingTextClauses e FP_MatchingObjectClauses e FP _MatchingPrefixClauses e FP_MatchingSuffixClauses FDK Programmer s Guide Getting and Setting Properties 5 e FP_MatchingFirstPgfClauses e FP _MatchingLastPgfClauses Each of these properties specifies a list of format rule clauses that applies to the element Getting these properties only for the element itself is not sufficient to determine the element s formatting These properties specify only the format rule clauses that are in the element definition s format rules that is the format rules specified by the element definition s FP_TextFmtRules FP_ObjectFmtRules FP_PrefixRules FP_SuffixRules FP_FirstPgfRules and FP_LastPgfRules properties In order to fully determine the element s formatting you must find any applicable format rule clauses that the element inherits from its ancestor elements To determine whether an element inherits format rule clauses from ancestor elements you must traverse up the structure tree and check the FP_MatchingClauses properties for each ancestor element Determining which element contains an object Frequently it is useful to determine which element contains an object such as a cross reference a marker or a table The following
377. following format view item_number item_type related_item_number where e viewis a letter specifying the current platform view of the dialog box X for X Windows on UNIX M for Macintosh or W for Windows For details on setting platform views see Setting the platform view of the dialog box on page 189 e item_numberis the number of the selected item In DRE files the items in a dialog box are identified by unique numbers Item numbers start from 0 and increase sequentially You use these numbers in your client code to identify items in the dialog box e item_type is the item s type e related_item_number specifies the number of a related item Some types of items such as text boxes image pop up menus and radio buttons can be related to other items If there is no related item the status bar displays an empty pair of parentheses If the item type does not support related items such as buttons or labels the status bar does not display parentheses For information about related items see Relating items in a dialog box on page 203 If you select more than one item the status bar displays information on the item with the lowest number Figure 10 9 shows the status bar when an item is selected FDK Programmer s Guide 187 a Creating Custom Dialog Boxes for Your Client File Edit Format View Special Graphics Table Help Paragraph Tag ft Information about the selected item Fj X 2 Tex
378. for R 22 R 84 R 85 to R 86 document footnote properties for G 284 general properties R 654 getting the IDs of selected G 87 objects representing illustrated G 334 organization of illustrated G 335 properties of G 332 to G 338 R 638 to R 658 versus Table Catalog format properties G 332 retagging G 332 index 30 ruling properties R 655 to R 656 selecting G 118 selecting elements in structured G 119 selection properties R 656 shading and color properties R 656 to R 657 sorting data qsort R 27 to R 28 tagging G 332 title properties R 657 titles of G 333 See also cells hash tables rows ruling formats table columns tabs adding G 103 to G 105 function for getting R 16 R 162 to R 164 function for setting R 16 R 305 to R 307 structure for G 104 G 271 R 685 See also paragraph formats FO_PgfFmt tab properties of paragraphs FO_Pgf tab properties of Tag area choosing commands in G 42 R 3 tagging characters G 306 paragraphs G 302 tables G 332 take control initialization G 14 templates creating documents from G 53 to G 54 G 279 function for R 325 to R 326 text G 111 G 311 to G 318 adding G 123 function for R 23 R 41 to R 42 to table cells G 122 API functions applicable to R 23 API representation of G 312 to G 318 applying character formats G 124 applying conditions to G 126 conditional G 318 illustrated G 318 deleting functions for R 88 to R 90 getting G 111 to G 113 functions for R 23 R 24 R 164
379. form Guide for the Macintosh General tips for dialog editing When editing dialog boxes keep the following in mind e A DRE file can contain only one dialog box If the DRE file already contains a dialog box do not paste another dialog box into the DRE file e Inthe Dialog Item Properties dialog box FrameMaker displays size and position information in units of points You cannot switch the units used for display even by specifying a change in the View Options dialog box You can however use any units to enter data e Help buttons should not be added to modeless dialog boxes Help buttons are mainly used with modal dialog boxes To get context sensitive help for modeless dialog boxes the user can choose Context Sensitive Help from the Help menu or use the appropriate keyboard shortcut for the platform Summary of keyboard shortcuts The following table lists the keyboard shortcuts for editing dialog boxes To do this Use this shortcut Capture an image of the dialog box while testing as modal Esc dc UNIX only Relate the selected items to each other Esc d f Select the first item in the draw order usually this is the dialog box in the Esc o F DRE file Select the next item in the draw order Escon Display the properties of the selected dialog box or item Esc g o Test the dialog box as modal UNIX and Windows only Esc dt FDK Programmer s Guide 209 a Creating Custom Dialog Boxes for Your Client 210
380. format provides such as indents and leading Every paragraph starts with a tag and formatting information that matches a Paragraph Catalog format There are several ways you can change a paragraph s format e Apply a different Paragraph Catalog format to the paragraph When you do this the FrameMaker product changes the paragraph s formatting information to match that of the Paragraph Catalog format This process is known as tagging e Change the paragraph s formatting information This does not affect the Paragraph Catalog format that you tagged the paragraph with For example if you tag a paragraph with a tag named indentbody that specifies a 1 inch indent and subsequently change the paragraph s indent to 2 inches the indentbody format and other paragraphs tagged as indentbody still have a 1 inch indent This change is a format override and it applies only to that paragraph instance e Change the Paragraph Catalog format s formatting information FrameMaker allows you to update all the paragraphs that are tagged with the format you changed You can choose whether you want to retain format overrides when FrameMaker updates all paragraphs in the document with the same tag How the API represents paragraphs FrameMaker represents each paragraph with an FO_Pgf object whose properties provide the following information 302 FDK Programmer s Guide Frame Document Architecture 14 e The ID of the text frame and text colum
381. frames anchored G 293 G 294 G 389 API representation of G 295 lists of graphic objects in G 295 nesting G 293 organization of graphic objects in G 295 to G 296 illustrated G 295 properties of G 295 unanchored G 293 R 608 See also anchored frames text frames FrameVector facets G 257 FS_UpdateBookStatus property F_ApiUpdateBook status flags of R 339 fstrings h header file G 381 fstrlist h header file G 382 functions See API functions FDE functions G general rules in content rules G 342 G 347 general structural element properties R 638 geometric shapes defined G 293 Gets R 164 getting API object types G 84 attribute definitions R 108 to R 110 attributes R 110 to R 112 FDK Programmer s Reference amp Guide IDs G 82 to G 89 G 163 to G 164 G 270 the insertion point G 114 to G 117 pathnames G 97 properties G 7 G 37 G 89 to G 92 G 95 to G 105 G 162 G 389 property lists G 92 to G 94 text G 111 to G 113 in text ranges G 118 text properties G 123 to G 124 G 317 text selections G 114 to G 117 UIDs G 89 G 270 valid elements R 112 global document information G 280 G 284 to G 288 API representation of G 280 G 285 to G 288 defined G 390 saving G 284 G 285 global variables effect of bailing out on G 44 for error conditions G 45 R 693 graphic inset editors G 256 to responding to user launching of G 262 See also graphic insets graphic insets G 230 G 256 to client specific facets G 258 creating G 261 fu
382. frequently such as FA_Note_BackToUser or FA_Note_PostFunction avoid conducting extensive processing each time they are issued If you don t you may decrease FrameMaker product performance For example suppose you request the FA_Note_PostFunction notification so that you can update a dialog box when the insertion point changes The API issues the FA_Note_PostFunction notification for nearly every event in a FrameMaker product session If you update the entire dialog box every time you receive the notification it slows the FrameMaker product It is more efficient to first determine whether the insertion point changed and then to update the dialog box only if it changed FDK Programmer s Guide Handling Custom Dialog Box Events no Handling user actions in dialog boxes How you handle user actions in a dialog box depends on whether the dialog is modal or modeless The following sections discuss how to handle user actions in each type of dialog box Handling user actions in a modeless dialog box After you display a modeless dialog box the API attempts to call a function named F_ApiDialogEvent from your client whenever the user does something such as click the mouse or press a key in the dialog box Your client should define F_ApiDialogEvent as follows VoidT F_ApiDialogEvent IntT dlgNum IntT itemNum IntT modifiers This argument Means dlgNum The number of the dialog box in which the user action occurr
383. function for R 2 R 238 to R 244 opening with F_ApiSimpleOpen G 46 to G 47 function for R 2 R 326 to R 327 organization of API objects in G 82 G 84 G 282 to G 284 organization of graphic objects in G 295 to G 296 organization of pages in G 291 illustrated G 292 organization of paragraphs in G 304 as organized in books G 351 as organized in sessions illustrated G 276 portrait G 57 printing G 57 to G 59 R 319 document properties for G 284 R 561 to R 563 function for R 6 R 319 to R 320 properties of R 537 to R 579 redisplaying function for R 7 R 263 to R 264 reformatting G 70 to G 74 G 96 functions for G 77 R 7 R 25 refreshing G 96 rehyphenating words in function for R 7 R 265 saving G 59 to G 66 G 279 functions for R 6 R 272 to R 274 R 327 to R 328 selection state properties for G 285 to G 286 setting status bars G 98 setting title bars G 98 structured G 342 Table of Contents G 289 updating G 70 to G 74 functions for G 77 R 7 See also document properties DOS platforms memory management on G 378 to G 379 FDK Programmer s Reference amp Guide Index Subjects a double byte strings FDE functions for determining if a prefix of another string R 463 determining if a suffix of another string R 464 double precision numbers converting strings to R 492 double sided documents master pages for G 289 G 292 draw order G 100 G 293 G 389 grouping and G 296 moving graphic objects in G 100 DRE Frame di
384. g box illustrated G 331 insertion point getting G 114 to G 117 function for R 181 to R 182 selection state of G 285 G 287 setting G 114 to G 117 function for R 17 R 313 to R 314 text containing G 317 inset facets See facets FDK Programmer s Reference amp Guide Index Subjects a insets G 229 to G 293 defined G 293 G 390 properties of G 247 to G 250 R 599 to R 602 responding to users clicking function for R 206 See also facets graphic insets text insets integer IntT properties function for getting R 16 R 128 to R 129 function for setting R 16 R 287 to R 288 integer array F_IntsT properties function for getting R 15 R 131 to R 132 function for setting R 16 R 289 to R 290 integer arrays structure for G 271 R 682 See also integer array F_IntsT properties integer facets function for getting R 9 R 129 to R 130 function for setting R 9 R 288 to R 289 integer prompt dialog boxes displaying G 18 to G 20 R 257 function for R 5 R 257 to R 258 illustrated G 20 R 258 integers data type for G 3 G 271 G 367 R 675 FDE function for converting and appending to strings R 446 R 493 prompting users for G 18 to G 20 R 257 function for R 5 R 257 to R 258 See also integer IntT properties integer arrays interactive mode in simple functions G 45 G 47 interfaces setting up for API clients G 7 G 17 to G 44 internal graphic insets G 230 G 259 to G 260 See also graphic insets IntT facets See
385. g formats Each document has a Table Catalog containing table formats What the user sees When you create a new table you specify a format from the Table Catalog The format provides the following information e The Table Catalog format name e Format characteristics such as the table position alignment and rulings e The number of columns and rows If you tag an existing table with a Table Catalog format the Table Catalog format provides only the format name and the format characteristics for the table it does not affect the number of columns or rows After you have created a new table or tagged an existing table you can change the number of columns or rows or the format without affecting the Table Catalog tag You can also instruct the FrameMaker product to apply the changes to the Table Catalog tag and other tables tagged with the format You can modify or delete formats that are already in the Table Catalog or you can add new formats How the API represents Table Catalog formats FrameMaker represents each Table Catalog format with an FO_Tb1Fmt object whose properties provide the following information e The name of the table format e Format characteristics e The default number of initial columns and rows e The ID of the next FO_Tb1Fmt object in the document Suppose you create the Table Catalog format described in the Table Designer and the Insert Table dialog box in Figure 14 31 330 FDK Programmer s Guide Frame
386. g properties G 107 format rules G 344 API representation of G 345 creating G 152 functions for R 221 to R 224 format rules of structural element definitions G 342 specifying G 342 formats copying G 102 R 297 importing from documents G 72 function for R 7 R 323 See also Character Catalog formats conditional text formats cross reference formats Paragraph Catalog formats properties ruling formats Table Catalog formats variable formats formatted anchored objects creating G 148 to G 149 function for R 209 to R 210 formatting documents G 70 to G 74 G 96 functions for G 77 R 7 R 25 FP_ImportHint property FO_Inset syntax of FP_ImportHint strings G 249 to G 255 FP_TintPercent G 341 fprogs h header file G 379 Frame Above setting Paragraph Designer G 289 G 390 frame anchors API representation of G 312 G 313 R 166 R 687 index 13 oe Index Subjects Frame API See API Frame Application Program Interface Frame Application Program Interface See API Frame Application Program Interface Frame Below setting Paragraph Designer G 289 G 390 Frame binary documents importing as text G 229 Frame Clipboard functions G 127 to G 129 API functions for G 127 to G 129 R 3 R 23 R 248 R 261 to R 262 flags for G 128 to G 129 table of G 128 manipulating the Clipboard stack G 129 R 248 R 261 to R 262 saving contents of Clipboard G 129 Frame commands replacing with your own commands G 30 See also c
387. g selected text see Getting and setting the insertion point or text selection on page 114 Getting the IDs of selected graphic objects The API maintains an unordered list of all the selected graphic objects in a document To manipulate graphic objects the user has selected you traverse this list For example the following code sets the fill pattern of all the selected graphic objects in the active document to black F_ObjHandleT docId objId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc objid F_ApiGetId FV_SessionId docId FP_FirstSelectedGraphicInDoc while objId F_ApiSetInt docId objId FP_Fill FV_FILL_BLACK objId F_ApiGetId docId objId FP_NextSelectedGraphicInDoc Getting the IDs of selected tables and table rows If a table is selected you can get its ID by querying the document property FP_SelectedTbl A table is considered selected if any of its cells are selected or the insertion point is in any of its cells To get the IDs of the rows selected within a table query the FO_Tb1 object s FP_TopRowSelection and FP_BottomRowSelection properties FP_TopRowSelection specifies the ID of the row at the top of the selection FP_BottomRowSelection specifies the ID of the row at the bottom of the selection To determine which cells in a row are selected query a table s FP_LeftColNum and FP_RightColNum properties FP_LeftColNum specifies the number starting from 0 of the leftmost select
388. g the footnote FDK Programmer s Guide 303 14 Frame Document Architecture 304 How to apply formats to paragraphs To apply a format from the paragraph format catalog to a specific paragraph object first get the ID of the FO_Pgf object in question Then loop through the document looking for the FO_PgfFmt object with a name that matches the tag you want to apply to the paragraph Then use F_ApiGetProps to get the list of properties from the FO_PgfFmt object and use F_ApiSetProps to set the property list to the FO_Pgf in question How the API organizes paragraphs The API maintains FO_Pgf objects in two linked lists e The list of all FO_Pgf objects in a document e The list of FO_Pgf objects in a flow The list of paragraphs in a document The FO_Doc property FP_FirstPgfInDoc specifies the first FO_Pgf object in the list of FO_Pgf objects ina document Each FO_Pgf object has an FP_NextPgfInDoc property which specifies the next FO_Pgf object in the list The order of the list of FO_Pgf objects in a document does not necessarily correspond to the actual order of the paragraphs in the document The list of paragraphs in a flow FO_F low objects do not have a property that specifies the first FO_Pgf object in a flow To find the first FO_Pgf object in the flow you must find the first FO_TextFrame object in the flow Then you must get the FO_Pgf object specified by the FO_TextFrame o
389. ge is the page that appears on the screen If more than one page appears on the screen it is the page that appears with a dark border around it You can make a page current by making the document that contains it the active document and then setting the document s FP_CurrentPage property to the page s ID For example the following code displays the second body page and then the first reference page of the active document F_ObjHandleT docId bPglId bPg2Id rPglId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Get second body page ID bPglid F_ApiGetId FV_SessionId docId FP_FirstBodyPageInDoc bPg2Id F_ApiGetId docId bPglId FP_PageNext if bPg2Id F_ApiSetId FV_SessionId docId FP_CurrentPage bPg2Id j F_ApiAlert Now at 2nd body page FF_ALERT_CONTINUE_NOTE Go to first reference page rPglid F_ApiGetId FV_SessionId docId FP_FirstRefPageInDoc if rPglId F_ApiSetId FV_SessionId docId FP_CurrentPage rPglId j Getting and setting graphic object properties The following sections describe useful tasks you can perform by getting and setting graphic object properties Changing an object s size and location within a frame Each graphic object has FP_Height and FP_Width properties which specify its height the distance between its highest and lowest points and its width the distance between its leftmost and rightmost points To change an object s size use
390. glId F_ApiSetProps docId myHeadId amp proplist F_ApiSetMetric docId myHeadId FP_LeftIndent 2 in F_ApiDeallocatePropVals amp proplist Creating a book The following code creates a book named mybook inthe tmp directory It uses F_ApiNewSeriesObject to add book components For more information on F_ApiNewSeriesOb ject see Creating series objects on page 149 For more information on creating books and book components see Creating new books and components on page 355 F_ObjHandleT bkId componentId bkId F_ApiNewNamedObject FV_SessionId FO_Book tmp mybook Create component and then change its name componentId F_ApiNewSeriesObject bkId FO_BookComponent 0 F_ApiSetString bkId componentId FP_Name docl Add another component after the first one componentId F_ApiNewSeriesObject bkId FO_BookComponent componentId F_ApiSetString bkId componentId FP_Name doc2 Creating graphic objects To create any graphic object except an anchored frame use F_ApiNewGraphicOb ject 146 FDK Programmer s Guide Creating and Deleting API Objects Ba The syntax for F_ApiNewGraphicObject is F_ObjHandleT F_ApiNewGraphicObject F_ObjHandleT doclId IntT objType F_ObjHandleT parentFramelId This argument Means docId The ID of the document in which to create the new object objType The type of graphic object to create for example FO_Rectangle or FO_
391. grammer s Guide Creating Custom Dialog Boxes for Your Client 10 Invoking the dialog box by name When you write the code to invoke the dialog box use the name of the resource as an argument for opening the dialog resource e In Windows and on the Macintosh the dialog resource is named after the DRE file For example if your DRE file is named mydialog dre the build process creates a dialog resource named mydialog e On UNIX the dialog resource is the X resource file For more details on displaying dialog boxes see Opening dialog resources on page 217 How to create a dialog box The process of creating a dialog box involves the following general steps Each step is described in more detail in subsequent sections of this chapter 1 Using FrameMaker create a new DRE file from an existing DRE file For details see the next section 2 Design the layout of the dialog box For more information see the section Designing the layout of the dialog box on page 189 3 Specify the properties of the dialog box For more information see the section Setting the properties of the dialog box on page 193 4 Specify the properties of the dialog items For details see the section Setting the properties of a dialog item on page 197 5 Save the new DRE file On some platforms this creates platform specific resource files For details see the section Saving a DRE file on page 204 6 Test the dia
392. gs function R 8 R 20 R 161 F_ApiGetTabs function G 90 G 103 R 16 R 162 F_ApiGetText function G 111 G 118 R 23 R 24 R 164 F_ApiGetText2 function R 170 F_ApiGetTextForRange function G 118 R 23 R 173 F_ApiGetTextForRange2 function R 174 F_ApiGetTextLoc function G 90 R 16 R 176 F_ApiGetTextProps function G 123 G 317 R 16 R 23 R 178 R 669 F_ApiGetTextPropVal function G 123 R 23 R 179 F_ApiGetTextRange function G 90 G 115 R 16 R 17 R 23 R 181 F_ApiGetTextVal function R 23 R 182 F_ApiGetUBytesByName function G 264 G 265 R 9 R 183 F_ApiGetUniqueObject function G 89 G 270 R 15 R 185 F_ApiGetUpdateBookDefaultParams function G 71 G 357 R 187 FDK Programmer s Reference amp Guide Index Reserved Names properties returned by R 187 F_ApiGetVal function R 190 R 190 F_ApiHypertextCommand function R 9 R 192 F_Apilmport function G 230 G 256 R 6 R 9 R 15 R 24 R 52 R 120 R 192 R 250 F_ApilnitializeQ function G 7 G 10 R 1 R 48 R 198 creating G 13 G 35 F_ApilsEncodingSupported function R 8 R 20 R 199 F_ApiLoadMenuCustomizationFile function G 169 R 3 R 200 F_ApiMakeTblSelection function G 118 R 17 R 22 R 201 F_ApiMenuExists function R 203 F_ApiMenultemInMenu function G 164 R 3 R 203 F_ApiMergelntoFirst function R 204 F_ApiMergelntoLast function R 205 F_ApiMessage function G 7 G 262 R 1 R 9 R 204 F_ApiModalDialog function G
393. h as Open Print or Close To execute these commands programmatically use API functions such as F_ApiSimpleOpen F_ApiSilentPrintDoc or F_ApiClose For more information on using API functions to execute FrameMaker product commands see Chapter 4 Executing Commands with API Functions 4 Add code to get and set object properties To get or set an object property use the F_ApiGetPropertyType or F_ApiSetPropertyType function that corresponds to the type of property you want to get or set For example to get or set an IntT property use F_ApiGetInt or F_ApiSetInt To get or seta StringT property use F_ApiGetString or F_ApiSetString For more information on changing object properties see Chapter 5 Getting and Setting Properties 5 Add code to create objects FDK Programmer s Guide 7 E Introduction to the Frame API To create objects use the F_ApiNewObjectType function that corresponds to the kind of object that you want to create For example to create a new anchored frame use F_ApiNewAnchoredOb ject For more information on creating objects see Chapter 8 Creating and Deleting API Objects 6 Compile your client The API function declarations are contained in the fapi h header Be sure to include this header in your client code Include C library header files before the fapi h header The FDK comes with sample makefiles or project files for each supported platform To
394. h as the footnote numbering and the default paragraph format Change bar properties which specify the appearance and position of change bars in the document The current text selection or insertion point There is also global document information that affects how the FrameMaker product behaves when the document is active This type of global information includes The document dictionary which lists words that you want the FrameMaker product Spelling Checker to ignore Type in properties which specify whether Smart Spaces or Smart Quotes is enabled Equation properties which specify default symbol sizes and fonts the FrameMaker product uses when you add equations to the document Printing properties which specify the defaults that appear in the Print dialog box such as the printer name and the range of pages to print View properties which specify how the FrameMaker product displays and scrolls the document in the window Structure properties which specify whether element boundaries appear and how the Element Catalog appears for a structured document in a FrameMaker session FDK Programmer s Guide Frame Document Architecture 14 FrameMaker saves most of the global document information with each document For example if you set the zoom for a document to 140 percent and save and exit a document the next time you open the document the zoom will be set to 140 percent How the API represents global document information The Frame
395. h the Windows view of the dialog box press Esc d w FrameMaker retains the layout and geometry information for each platform view that you use How FrameMaker gets view information When you change to a platform view for the first time FrameMaker calculates the geometry information for that view FrameMaker caches this geometry information in local memory during the session If you change back to that platform view later FrameMaker does not recalculate the geometry information instead the product reads the cached geometry information from local memory FrameMaker calculates geometry information for a view only if the geometry information is not already cached Updating views and cached information When you switch views you may notice that layout changes are not reflected in other views This occurs because FrameMaker is reading cached geometry information for that view which has not been updated with changes made to other views FDK Programmer s Guide 189 a Creating Custom Dialog Boxes for Your Client To update a view with geometry information from another view you must make FrameMaker recalculate the geometry information Since FrameMaker calculates geometry information only if the information is not already cached you must clear the cached information from local memory To clear the cached geometry information for the current view you reset the current platform view Resetting the current platform view To reset the c
396. hanges the FP_FirstPgf and FP_LastPgf properties of the first cell topmost and leftmost so that it specifies the first and last paragraphs of the new linked list of paragraphs All the other cells specify paragraph IDs of zero It changes the properties of the first FO_Ce11 object in the straddle as listed in the following table Property New value FP_CellIsStraddled False FP_Cel1NumRowsStraddled The number of rows in the straddle FP_CellNumColsStraddled The number of columns in the straddle It also changes the properties of cells other than the first cell in the straddle as listed in the following table Property New value FP_CellIsStraddled True FP_CellNumRowsStraddled 1 FP_CellNumColsStraddled 1 The straddle uses the custom rulings and shadings of the first cell When the user unstraddles the cells the FrameMaker product leaves all the paragraphs that were in the straddle in the first cell It gives each other cell a new empty paragraph It leaves the original custom rulings and shadings of each cell intact Suppose you straddle both cells in a table row that has two cells Each cell contains a single paragraph before you straddle them Figure 14 34 shows how the FO_Cell objects appear before and after they are straddled and unstraddled The FrameMaker product automatically inserts a new paragraph in the second cell after you unstraddle the cells FDK Programmer s Guide 337 14 Frame Document Architecture
397. has changed The Character Catalog format has changed The capitalization has changed The character position has changed The condition tag has changed Font stretch value has changed Character language has changed Tsume setting has changed An internal flag having to do with asian text input If there is a non zero value for this flag a front end processor is controlling that text you should not modify the associated text item The text encoding has changed FDK Programmer s Guide 315 14 Frame Document Architecture Flag Meaning FTF_ALL OR of all the flags listed above Figure 14 19 shows a paragraph and the text items the API uses to represent the paragraph s text This is a marker offset 0 offset 0 offset 0 offset 5 offset 5 offset 17 offset 18 offset 18 dataType dataType dataType dataType dataType dataType dataType dataType FTI_PegfBegin FTI_LineBegin FTI_String FTI_CharProps _ FTI_String FTI_Marker FTI_LineEnd FTI_PgfEnd idata ID of sdata This Change sdata is a Anchor idata 0 idata ID of FO_Pgf idata marker idata ID of FO_Pgf FTF_WEIGHT FO_Marker FiGURE 14 19 Paragraph text and the text items that represent it There are several important things to note about the text items shown in Figure 14 19 e Because the string This andthe string is a marker have different font weights there are separate text items for them e
398. hat it should not relocate it You can then safely use any absolute pointer into the block without fear of the memory being relocated After you are done with the pointer you unlock the memory allowing the operating system to relocate it The Macintosh also provides nonrelocatable memory that you can access directly To develop portable clients that use large memory blocks you should use handle based memory management There are some trade offs between using pointers and handles Handles may slow down the access to memory Pointers may fragment the heap space especially if you 378 FDK Programmer s Guide Making I O and Memory Calls Portable use them on the Macintosh with memory blocks larger than 512K In general you should use pointers for small memory allocations and handles for large allocations Many FDE memory allocation functions such as F_Alloc providea flags argument that specifies what to do if memory can t be allocated If you set this argument to DSE and memory can t be allocated the FDE calls a function that you register by calling F_SetDSExit If you set flags to NO_DSE and memory allocation is unsuccessful the memory allocation function returns NULL For more information see F_SetDSExitQ on page 439 of the FDK Programmer s Reference Allocating memory with handles The FDE provides functions that allow you to allocate and deallocate memory with handles For example F_AllocHandle allocat
399. hat need to update and reformat multiple files For more information on a particular function look it up in FDK Programmer s Reference Example The following code opens a book and resets the change bars in each of its component documents include fmemory h F_ObjHandleT bookId compId docId StringT compName bookId F_ApiSimpleOpen tmp my book False compId F_ApiGetId FV_SessionId bookId FP_FirstComponent InBook Traverse book s components opening each on and clearing its change bars FDK Programmer s Guide 73 a Executing Commands with API Functions while compId compName F_ApiGetString bookId compId FP_Name docId F_ApiSimpleOpen compName False F_Free compName F_ApiClearAllChangebars docId compId F_ApiGetId bookId compId FP_NextComponentInBook Simulating user input To simulate user input call the API function F_ApiFcodes F_ApiFcodes sends an array of function codes f codes to the FrameMaker product F codes are hexadecimal codes that specify individual user actions such as cursor movement and text entry They are especially useful for manipulating windows For example the f code KBD_EXPOSEWIN brings the active document or book window to the front When you use F_ApiFcodes to send an array of f codes to FrameMaker it executes each f code as if the user performed the action IMPORTANT F_ApiFcodes does not work with di
400. he footing row row 3 The following are some of the properties of the FO_Row object that represents the table s heading row Property Type FP_PrevRowInTbl F_ObjHandleT FP_NextRowInTbl F_ObjHandleT FP_RowType IntT FP_RowKeepWithNext IntT j P_FirstCellInRow F_ObjHandleT Value NULL ID of FO_Row that represents row 2 FV_ROW_HEADING True ID of FO_Cel11 that represents the R1 C1 cell The following are some properties of the FO_Ce11 object that represents the R2 C2 cell For the cell s override fill and rulings to override the fill and ruling provided by the table s format the FP_CellUseOverrideCharacteristic properties must be set to True Property FP_CellOverrideFill FP_CellUseOverrideFill FA_CellDefaultLeftRuling FP_CellOverrideLeftRuling Type IntT IntT F_ObjHandleT F_ObjHandleT Value 5 True ID of FO_RulingFmt that represents the Medium line ruling ID of FO_RulingFmt that represents the Thick line ruling FDK Programmer s Guide Frame Document Architecture CE Property Type Value FP_CellDefaultBottomRuling F_ObjHandleT ID of FO_RulingFmt that represents the Medium line ruling FP_CellOverrideBottomRuling F_ObjHandleT ID of FO_RulingFmt that represents the Thick line ruling How the API represents straddle table cells When the user straddles a set of table cells the FrameMaker product links all of the paragraphs in the cells It c
401. he Paragraph Designer use arrowdown If you place the image pop up menu next to a text box for example such as the Paragraph Tag text box in the Paragraph Designer use tallarrowdn FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client You can t specify the list of settings for an image pop up menu in the DRE file Instead you must include code in your client to provide it For more information see Initializing items in a dialog box on page 218 The image pop up menu item does not include a label For instructions on adding a label for an image pop up menu see the section Adding dialog items on page 192 For information on setting the basic properties for this dialog item see the section Setting basic dialog item properties on page 197 Labels A label is a single line of text that you can use to identify other items in a dialog box Some types of dialog items such as radio buttons checkboxes and buttons already include labels For these items the label is part of the dialog item Other items such as text boxes and pop up menus do not include labels For these items the label is a separate dialog item To change the text in a label select the label s text in the DRE file and type over it You can also include code in your client to change a label dynamically To do this set the label property on the API object representing the label For details on the properties of the API object see
402. he list FO_Flow objects have a property named FP_NextFlowInDoc which specifies the next FO_Flow object in the list The order of the list is random it does not correspond to the order in which the flows appear in the document The API also maintains the objects that represent a flow s text frames in a linked list The FO_Flow properties FP_FirstTextFrameInFlow and FP_LastTextFrameInF low specify the first and last FO_TextFrame objects in the list Each FO_TextFrame object has an FP_PrevTextFrameInFlow property anda FP_NextTextFrameInFlow property which specify the previous and next FO_TextFrame objects in the list For more information on how flows text frames and paragraphs are organized see How the API organizes paragraphs on page 304 Suppose you create the document shown in Figure 14 9 The document has two flows a main flow named A and a second flow that is unnamed The A flow connects a two column text frame on the first page and a two column text frame on the second page The unnamed flow appears only on the first page and has only one text frame INUIT IKU Flow A efil lI gt lI lI gt lI u lI lI gt lI Unnamed flow 1 2 FIGURE 14 9 Document with a named and an unnamed flow Figure 14 10 shows how the API organizes the objects that represent the flows and text frames shown in Figure 14 9 298 FDK Programmer s Guide
403. he part of an element definition that specifies a container element s contents is known as a content rule The content rule includes the following e A general rule which specifies what elements are inside the container and in what order e A list of inclusions which specifies other elements that can appear anywhere in a container or the elements it includes its descendants e A list of exclusions which specifies elements that cannot appear in a container or in its descendants Element definitions also specify attribute definitions which describe attributes or separate units of information that the user can store with an element An attribute definition can specify that an attribute is required for all elements with the element definition It can also provide a list of the values an attribute can have as well as a default value 3 Structured documents are only available the Structured FrameMaker product interface 342 FDK Programmer s Guide Frame Document Architecture CE How the API represents structural element definitions FrameMaker represents each element definition with an FO_ElementDef object FO_ElementDef properties provide the following information about an element definition e Its name e Its format rules e Comments which describe its use e Its attribute definitions e Its content rule e The type of element it defines for example a container or a system variable e Flags indicating whether the element de
404. hen clicking Change on the element catalog To change an element via the API you must change the FP_ElementDef property of the FO_Element object You can traverse the list of element definitions in the document by starting with the FP_FirstElementDefInDoc property of the FO_Doc object and then using the FP_NextElementDefInDoc property of the resulting FO_ElementDef object You can identify the element definition by using its FP_Name property FDK Programmer s Guide Frame Document Architecture CE FDK Programmer s Guide 349 14 Frame Document Architecture 350 FDK Programmer s Guide Frame Book Architecture This chapter describes books and discusses how the Frame API represents them What the user sees A book maintains a collection of documents that are known as components The book helps you organize and format these component documents It also enables you to create generated files such as tables of contents and indexes A book does not contain the component document files It contains references to the component document files in an ordered list such a reference is called a book component Each component contains its own setup data such as pagination and numbering For example each component contains properties to determine whether its page and paragraph numbering continues from the previous document or restarts at 1 and whether the document starts on a left or right page The component properties sho
405. herwise it returns FE_Success If you set dlgNum to a nonzero value when the user manipulates the dialog box the API calls your client s F_ApiDialogEvent callback just as it does for a modeless dialog box Updating items in a dialog box If you display a modeless dialog box you may need to request and monitor notifications to update it when the user changes things in the FrameMaker product session For example if the dialog box displays information that is dependent on the insertion point you should request and monitor the FA_Note_BackToUser or FA_Note_PostFunction notifications so that you can update the dialog box whenever the user changes the insertion point Avoid requesting more notifications than you need to update a dialog box Also be sure to turn off notifications after the dialog box is closed If your client requests notifications that are issued very frequently it can decrease FrameMaker product performance For example if your dialog box includes a scroll list that displays a list of open documents in the session you could update the list by requesting and monitoring the FA_ Note BackToUser notification However this would be inefficient because the FrameMaker product would issue notifications for many events that don t affect the dialog box It is much more efficient to request and monitor only the FA_Note_PostOpenDoc and FA_Note_QuitDoc notifications If you need to monitor notifications that are issued very
406. hic object in the list If you traverse this list you will cover every graphic object in a document The order of the list is completely random e The list of API graphic objects in the graphic object s parent frame Each API graphic object except an anchored frame and a page frame has exactly one parent frame object The parent frame is the frame that contains the graphic object The API maintains a linked list of the child objects in each frame FO_UnanchoredFrame and FO_AFrame objects have FP_FirstGraphicInFrame and FP_LastGraphicInFrame properties which specify the first and last objects in the list of their child objects All API graphic objects have FP_PrevGraphicInFrame and FP_NextGraphicInFrame properties which specify the objects before and after them in the list The order of the objects in the linked list is the same as the draw order of the graphic objects in a frame Like the frames they represent API frame objects can be nested that is an FO_UnanchoredFrame or FO_AFrame object can be the parent of another FO_UnanchoredFrame object Every API graphic object except an object that represents a page frame or an anchored frame is a descendant of exactly one API page frame object Suppose you create a page that contains e Anunanchored frame that contains an oval a rectangle and a text frame with some text in it e A text line that overlaps the unanchored frame but is drawn directly on the page FrameMaker organizes th
407. his argument Means docId The ID of the document containing the Tag area in which to display the prompt prompt The prompt that appears in the Tag area stringlist The list of strings from which the user can choose FDK Programmer s Guide Creating Your Client s User Interface a F_ApiQuickSelect returns the index of the string the user chose or 1 if the user canceled the command For example the following code implements the quick key interface shown in Figure 3 9 F_StringsT fruits StringT strings 3 IntT choice F_ObjHandleT docId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc strings 0 StringT Kumquat strings 1 StringT Durian strings 2 StringT Rambutan fruits len 3 fruits val strings choice F_ApiQuickSelect docId StringT Fruit amp fruits if choice 1 F_Printf NULL StringT The user chose s n strings choice Fruit Rambutan FIGURE 3 9 Tag area with client defined quick key Freeing system resources by bailing out Instead of leaving your client idle when it s not executing you may want to free the system resources it uses The API provides a function named F_ApiBailOut which allows you to do this When you call F_ApiBailOut the FrameMaker product waits until your client returns from the current callback then exits your client freeing the system resources it uses If your client is a dynamically linked client on a UNIX pla
408. i R 630 FP_RuleClauseType property FO_FmtRuleClause G 346 R 591 FP_RulingGap property FO_RulingFmt G 329 R 631 FP_RulingLines property FO_RulingFmt G 329 R 631 FP_RulingPenWidth property FO_RulingFmt G 329 R 631 FP_RulingSep property FO_RulingFmt R 631 FP_Runaround property FO_GraphicObject R 595 FP_RunaroundGap property FO_GraphicObject R 595 FP_RunInSeparator property FO_FmtChangeList R 588 FP_RunInSeparator property FO_Pgf R 620 FP_RunInSeparator property FO_PgfFmt R 627 FP_ScreenHeight property FO_Book R 496 FP_ScreenHeight property FO_DialogResource R 532 FDK Programmer s Reference amp Guide Index Reserved Names as FP_ScreenHeight property FO_Doc R 577 FP_ScreenHeight property FO_Session R 636 FP_ScreenWidth property FO_Book R 496 FP_ScreenWidth property FO_DialogResource R 532 FP_ScreenWidth property FO_Doc R 577 FP_ScreenWidth property FO_Session R 636 FP_ScreenX property FO_Book R 496 FP_ScreenX property FO_DialogResource R 532 FP_ScreenX property FO_Doc R 577 FP_ScreenX property FO_Session R 636 R 637 FP_SelectedTbl property FO_Doc G 283 G 285 R 540 R 565 FP_Sensitivity property FO_DlgButton G 212 G 219 R 533 FP_Sensitivity property FO_DlgCheckBox G 212 G 219 R 533 FP_Sensitivity property FO_DlgEditBox G 212 G 219 R 534 FP_Sensitivity property FO_DlgImage G 212 G 219 R 534 FP_Sensitivity property FO_DlgLabel G 212 G 219 R 534 F
409. iGetImportDefaultParams R 126 FS_NumColumns property F_ApiGetImportDefaultParams R 126 FS_OpenDocView Only property F_ApiGetOpenDefaultParams G 49 R 143 FS_OpenedFileName property F_ApiOpen G 51 R 239 FS_OpenFileNotWritable property F_ApiGetOpenDefaultParams R 143 FS_Openld property F_ApiGetOpenDefaultParams R 143 FS_OpenInNewWindow property F_ApiGetOpenDefaultParams R 144 FS_OpenNativeError property F_ApiOpen G 51 R 239 values of and associated status flags R 240 FS_OpenStatus property F_ApiOpen G 51 R 240 R 243 status flags of R 240 FS_RasterDpi property F_ApiGetImportDefaultParams R 125 FS_RasterImage Width property F_ApiGetImportDefaultParams R 125 FS_RefFileNotFound property F_ApiGetOpenDefaultParams R 144 FS_RemoveManualPageBreaks property F_ApiGetImportDefaultParams R 124 FS_RemoveOverrides property F_ApiGetImportDefaultParams R 124 FS_RetainNameStripe property F_ApiGetSaveDefaultParams R 155 index 68 FS_SaveAsModeName property F_ApiGetSaveDefaultParams R 156 FS_SavedFileName property F_ApiSave G 65 R 272 FS_SaveFileNotWritable property F_ApiGetSaveDefaultParams R 155 FS_SaveFileTypeHint property F_ApiGetSaveDefaultParams R 155 FS_SaveLockCantBeReset property F_ApiGetSaveDefaultParams R 154 FS_SaveModDateChanged property F_ApiGetSaveDefaultParams R 155 FS_SaveMode property F_ApiGetSaveDefaultParams G 62 R 156 FS_Sa
410. ialog box after the FrameMaker product is started To do this you could use the following F_ApiInitialize function VoidT F_Apilnitialize initialization IntT initialization F_ApiAlert Client has started FF_ALERT_CONTINUE_NOTE 1 For information on registering your client with the FrameMaker product see the FDK Platform Guide for your platform FDK Programmer s Guide 13 ee API Client Initialization Initialization types 14 The following table summarizes the different types of initializations and the initialization constants FrameMaker can pass to your client s F_ApiInitialize callback TABLE 2 2 Type of When F_Apilnitialize Clients that receive initialization is called Initialization constant initialization FrameMaker starts with no special options FrameMaker starts with take control client Document report chosen from Document Reports dialog box Notification menu choice or hypertext command for a client that has bailed out After starting After starting After all clients have finished processing the FA_Init_First initialization After report is chosen When the menu item is chosen the hypertext command is clicked or the notification should be issued FA_Init_First FA_Init_First FA_Init_TakeControl FA_Init_DocReport FA_Init_Subsequent All except document reports and filters All except document reports and filters All clients set up as take
411. iation property FO_PgfFmt R 624 FP_FontVariation property text location R 669 FP_FontVariationNames property FO_Session G 276 R 633 FP_FontWeight property FO_CharFmt R 516 FP_FontWeight property FO_Doc R 574 FP_FontWeight property FO_FmtChangeList R 587 FP_FontWeight property FO_Pgf R 615 FP_FontWeight property FO_PgfFmt R 624 FP_FontWeight property text location G 317 R 670 FP_FontWeightNames property FO_Session G 277 R 634 FP_FormatName property G 107 FP_FormatOverride property FO_Element R 639 FP_FormatTag property FO_FmtRuleClause R 591 FP_FrameParent property FO_GraphicObject G 101 R 593 FDK Programmer s Reference amp Guide FP_FrameParent property FO_Rectangle G 4 FP_FrameParent property FO_SubCol R 521 FP_Functions property FO_Doc R 551 FP_GeneralRule property FO_ElementDef G 344 R 647 FP_GeneralRuleErrorOffsets property FO_ElementDef R 647 FP_GenerateAcrobatInfo property FO_Book R 499 FP_GenerateAcrobatInfo property FO_Doc R 543 FP_GenerateInclude property FO_BookComponent R 511 FP_GraphicCantBeSelected property FO_GraphicObject R 593 FP_GraphicIsButton property FO_TextFrame R 605 FP_GraphicIsSelected property FO_GraphicObject R 593 FP_Gravity property FO_Session R 634 FP_GreekSize property FO_Session R 634 FP_GroupParent property FO_GraphicObject G 101 R 593 FP_HasShiftOrUnshiftCommand property G 174 FP_HasShiftOrUnshiftCommand property
412. iddenPage The selected table object The first FO_TiApiClient FO_TiFlow FO_TiText or FO_TiTextTable in the list of text insets The first FO_Rubi in the list of rubi composites The first FO_CombinedFontDefn in the list of combined font definitions FDK Programmer s Guide 283 14 Frame Document Architecture FP_FirstBodyPagelInDoc FP_FirstMasterPagelInDoc and FP_FirstRefPageInDoc point to the lists of pages in a document These lists are ordered to reflect the order of the pages All other lists including the list of FO_Pgf objects are not ordered The terms first and last indicate only the position of the objects in an arbitrarily ordered list There is no guarantee that a more recently added object will come later in a list nor is there a guarantee that the order of a list will remain the same as the document is modified 284 Global document information FrameMaker allows you to set global document information characteristics that apply generally to an entire document What the user sees Global document information includes the following formatting characteristics Document page properties which specify the document s page numbering and pagination style Document condition properties which specify whether conditional text appears and whether formatting associated with condition tags overrides other formatting Document and table footnote properties which specify the appearance of the footnotes suc
413. ies not covered in the previous section You set these properties in one of the following ways e Enter values in the Dialog Item Properties dialog box for example to specify the initial state of a checkbox e Select and edit the item in the DRE file for example to specify the text in a label select the text and type over it e Write client code for example to specify the menu choices in a pop up menu Boxes A box appears as a rectangle drawn with a single black line You can use a box to organize the items in a dialog box The items contained within a box must have numbers that follow the item number of the box For details see Specifying the focus order on page 194 You can also use a box as a line separator by setting its width or height to 0 FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client 10 IMPORTANT Do not put a box within another box except in cases where the inside box is a separator a box with a height or width of 0 For information on setting the basic properties for this dialog item see the section Setting basic dialog item properties on page 197 Buttons A button allows the user to execute a command or invoke an action from a dialog box The button item includes a label To change the text in the label select the text on the button face and type over it For information on setting the basic properties for this dialog item see the section Setting basic dialog item prop
414. ification F_ObjHandleT doclId StringT sparm IntT iparm if notification FA_Note_PreFunction amp amp iparm KBD_INPUT F_Printf NULL The user typed s n sparm Prevent text from being added to document F_ApiReturnValue FR_CancelOperation Responding to events initiated by API clients FrameMaker notifies your client of any event that it has requested notification for The event can be initiated directly by the user or by another client The Frame API provides a set of functions that allow API clients to programmatically execute Open Save and several other FrameMaker product operations For more information on these functions see Chapter 4 Executing Commands with API Functions When a client executes an operation with one of these functions the FrameMaker product notifies all the other API clients that have requested notification for that event It does not however notify the client that executed the operation For example to have your client automatically make an additional copy of a document when the user saves it use the following code Turn on notification F_ApiNotification FA_Note_PostSaveDoc True VoidT F_ApiNotify notification docId sparm iparm IntT notification F_ObjHandleT docId StringT sparm IntT iparm 1 An API client can explicitly instruct the FrameMaker product to suppress notifications to other API clients when it opens or saves a file by setti
415. ify notification docId sparm iparm IntT notification F_ObjHandleT docId StringT sparm IntT iparm If user is trying to close document cancel command if notification FA_Note_PreQuitDoc F_ApiReturnValue FR_CancelOperation Responding to text entry and actions that have no specific notifications The API doesn t provide specific notifications for most user actions Instead it provides the following general notifications which it issues for nearly every user action Event or operation Notification points Notification constants Any user action that the After the FrameMaker product finishes FA_Note_BackToUser FrameMaker product processing the action processes FrameMaker product Before the FrameMaker product executes FA_Note_PreFunction command invoked or the command or adds text to the document text entered in a document After the FrameMaker product executes FA_Note_PostFunction the command or adds text to the document The API issues the FA_NoteBackToUser notification after any user action the FrameMaker product processes including insertion point changes selection changes and text entry This notification is useful if you need to update a modeless dialog box containing settings that are dependent on the insertion point When the API issues the FA_NoteBackToUser notification it indicates only that an action occurred it does not specify which action If you want to respond to specific actions
416. ight color libraries Crayon DIC FOCOLTONE Greys MUNSELL PANTONE TOYO and TRUMATCH How the API represents colors The API represents each default color and each user defined color with an FO_Color object Tints are special FO_Color objects because each tint includes a reference to a base color which is itself an FO_Color object For a tint the FP_TintBaseColor property returns the object ID of the base FO_Color object Paragraph formats graphic objects and other objects to which you can apply a color have properties that specify the ID of an FO_Color object For example all graphic objects have an FP_Color property that specifies the ID of an FO_Color object The properties of FO_Color objects provide the following information e The name of the color e The color library and associated pigment used for the color e The CMYK values of the color e Tint base color and percentage e Whether the color overprints or knocks out when printing Library colors FP_FamilyName and FP_InkName When you specify a color from a library the FP_Cyan FP_Magenta FP_Yellow and FP_Black properties are set to represent the library color If you later set FP_FamilyName and FP_InkName to NULL the CMYK settings remain the same but the FO_Color object no longer defines a library color Both FP_FamilyName and FP_InkName are required to uniquely define a library color The order in which you set the values of these properties is important You mus
417. il another function fails and sets it or until your code explicitly sets it To determine whether a set of API function calls has failed initialize FA_errno to FE_Success once before all the calls and check it once after all the calls To find the error codes a function can generate look up the function in the FDK Programmer s Reference For a list of all API error codes and their meanings see the fapidefs h header file included with FDK or Chapter 5 Error Codes in the FDK Programmer s Reference In the interest of brevity the examples in this chapter do not include error handling code However you should check FA_errno after calling functions that set it Handling messages and warnings In the user interface some commands such as Open and Save sometimes need to prompt the user with warnings or messages The API provides two types of functions to execute these commands e Simple functions allow you to either suppress the messages and warnings entirely or to prompt the user with them e Scriptable functions allow you to specify a response for each possible message or warning Using simple functions Simple functions enable you to execute commands such as Save and Open without specifying numerous parameters They execute these commands in either an interactive or a noninteractive mode If you call a simple function and specify the interactive mode the FrameMaker product behaves exactly as it would if the user had initiated the
418. ilter version the vendor and the file format this filter handles Assume you create a filter client that translates Himyaritic documents to English and you assign it the format ID HIM When you import a Himyaritic file by reference into a FrameMaker product document the FrameMaker product creates a text inset and saves the format ID in the inset s import hint FP_ImportHint property The next time you open the document the FrameMaker product uses the import hint to update the text inset It looks for a client with the format ID HIM If it finds a client with this ID it uses that client to update the inset Note that this mechanism works across platforms If you move the document and text file to another platform the hint string will still indicate the correct filter assuming the filter is installed on the new platform Specifying format IDs You can make up format IDs for specific file formats However FrameMaker reserves the following format IDs for the specified file formats Value Description CDR Corel Draw CGM Computer Graphics Metafile CVBN Corel Ventura compound document Windows DCA DCA to MIF UNIX DIB Device independent bitmap Windows DRW Micrografx CAD FDK Programmer s Guide 247 12 Using Imported Files and Insets 248 Value DXF EMF EPSB EPSD EPSF EPSI FRMV G4IM
419. include fdetypes h and fprogs h in your program FDK Programmer s Guide 379 Making I O and Memory Calls Portable 380 FDK Programmer s Guide FDE Utility Libraries This chapter describes FDE utility libraries e The string library provides platform independent equivalents for many of the functions in lt string h gt e The string list library provides routines for creating a list of strings and manipulating the strings e The character library provides platform independent equivalents for some of the functions in lt ctype h gt that can be used on Frame characters e The I O library provides functions to read data from or write data to channels and performs byte swapping when it is necessary e The hash library provides functions to create a hash table and manipulate the cells in it e The metric library provides functions for manipulating and converting MetricT values values using Frame s internal representation of measurements e The MIF data structures and macros provide data structures and macros to represent and manipulate the statements described in the online MIF Reference e The MIF library provides functions that help you write nicely formatted MIF to a channel e The simple MIF library provides functions to write individual MIF statements to a channel For lists of FDE utility library functions see Chapter 1 Function Summary in the FDK Programmer s Reference For the complete description of a fu
420. ing them from the FrameMaker product Modules folder For more information on disabling individual clients see the FDK Platform Guide for your platform IMPORTANT Many FrameMaker features are implemented via API clients If you disable the API then you also disable these features Such features include XML and SGML import and export Save As HTML and Word Count 16 FDK Programmer s Guide Creating Your Client s User Interface This chapter describes how to use the Frame API to create a user interface for your FDK client Your client can interact with the user in the following ways e By displaying its own dialog boxes By implementing its own menus menu items and keyboard shortcuts By responding to the message apiclient hypertext command By responding to user initiated events or FrameMaker product operations By implementing quick key commands The following sections discuss these ways of interacting with the user in greater detail Using API dialog boxes to prompt the user for input The Frame API provides a variety of premade dialog boxes All of these dialog boxes are modal the user must dismiss them before continuing The following sections discuss how to use these dialog boxes The API also allows you to create and use custom modal and modeless dialog boxes For more information see Chapter 10 Creating Custom Dialog Boxes for Your Client and Chapter 11 Handling Custom Dialog Box Events Using ale
421. integer facets invisible documents G 98 K keyboard shortcuts G 26 adding to menus G 26 in dialog boxes Windows G 202 for dialog editing G 209 prefix for coding G 26 index 17 E Index Subjects L labels adding to dialog box items G 193 of checkboxes G 199 of client defined menu items G 172 in dialog boxes G 201 of Frame product menu items G 171 of menu items G 170 to G 172 properties of R 534 of radio buttons G 200 landscape documents creating G 57 language strings functions for R 397 table of R 397 languages See Frame products languages available in language strings paragraph formats FO_PgfFmt language property of languages See paragraphs FO_Pgf language properties of Left master page G 292 level rules G 344 libfde a library file G 367 libraries See FDE utility libraries line breaks specifying G 121 line properties R 602 line spacing See paragraph formats FO_PgfFmt line spacing property of paragraphs FO_Pgf line spacing property of lines dashed R 595 properties of R 602 See also text lines linked lists of commands G 162 in Frame product architecture G 82 of menu items G 162 of menus G 162 order of objects in G 84 lists See linked lists little endian byte order G 382 R 435 R 438 lock count for handles R 399 longs 4 bytes FDE function for reading and swapping R 428 to R 429 FDE function for writing and swapping R 490 index 18 Macintosh computers compiling and running FDE
422. ion for getting R 16 R 146 to R 148 function for setting R 16 R 295 to R 297 polygon properties R 16 R 603 polyline properties R 16 R 604 pop up menus adding menus or menu items to G 27 R 79 in dialog boxes G 200 getting setting the state of function for R 5 properties of G 200 R 535 See also image pop up menus index 24 portability creating and ensuring G 6 G 366 to G 370 G 375 to G 379 portrait documents creating G 57 PostScript names for fonts G 307 to G 308 primitive data types C language API substitutes for G 6 R 675 FDE substitutes for G 6 G 367 to G 369 R 675 Print command replacing G 30 print properties See document properties print settings changing G 58 printer state function for getting R 148 printer state function for setting R 297 printing books function for G 57 to G 59 R 2 current API error status function for R 4 R 98 R 248 documents G 57 to G 59 function for R 6 R 319 to R 320 properties for specifying R 561 to R 563 formatted output functions for R 424 R 440 imported graphics facets for G 258 properties G 284 property value pairs functions for R 5 status flags functions for R 4 R 250 text in text items functions for R 5 R 253 to R 254 values in specified property lists function for R 252 values of specified properties function for R 251 to R 252 progress function for showing R 426 project files G 8 properties G 3 to G 4 allocating memory for G 94 API function
423. ion in the draw order How the API represents selections of graphic objects The FO_Doc property FP_FirstSelectedGraphicInDoc specifies the ID of the object that represents the first selected graphic object in a document If more than one graphic object is selected the API forms a linked list of the API graphic objects that represent the selected graphic objects API graphic objects have an FP_NextSelectedGraphicInDoc property that specifies the ID of the next selected graphic object The order of the list is not necessarily the same as the order in which the graphic objects were selected FDK Programmer s Guide Frame Document Architecture CE Although FP_FirstSelectedGraphicInDoc is a document property you can only select graphic objects that are within the same frame Flows FrameMaker uses flows to connect text frames in a document What the user sees A flow tells the FrameMaker product where to put additional text when a text frame is full In a simple document there may be only one flow associated with the body pages In complex documents such as newsletters you may create multiple flows that have connected text frames on different pages S lay z n nT qk mi FIGURE 14 8 Multiflow document Flows have an Autoconnect setting that controls whether the FrameMaker product generates a new page when you fill the last text frame of a flow If Autoconnect is on the FrameMaker product creates
424. ion on custom documents on a specific platform see your user documentation On UNIX platforms when the user attempts to create a new document from an ASCII text file or a MIF file that doesn t provide the necessary objects the FrameMaker product looks for a template named xxxTemplate where xxx is the suffix of the file being opened First it looks in the directory from which it was started then it looks in the user s home directory If the FrameMaker product can t find xxxTemplate in either of these locations it looks for a template named ASCIITemplate in the same locations If it can t find ASCIITemplate it uses NewTemplate On the Macintosh the FrameMaker product looks for an ASCII template If it can t find one it uses the template that is included in its data fork On Windows the FrameMaker product uses the ASCII template specified in the maker ini file When you instruct FrameMaker to save a document it lists the document s objects and their properties in a file By default the FrameMaker product writes the information to a Frame binary format file You can also choose to save a document as a MIF file FDK Programmer s Guide 279 14 Frame Document Architecture 280 How the API represents documents A document actually consists of much more than text and graphic objects It includes information specifying a variety of other things such as formatting user preferences and the FrameMaker product s default behavio
425. ir ae ete e a e e a T Va a a a Oe Qe Ae ee a Ww Gedo aD a at 311 Markers ic ce a ai a a E le ee ah ee ee 319 Cross reference formats o oo a a 322 Cross referenceS 4 o oo RA ER eee ee b eta ee eS we 323 Variable formats a s sa 44 64 4 hee ee ee eR a Ee aa 324 Variables nw a agave ark Be Re BOR Go ao Wek A A RGR Rae Rw de 326 FOOINGLESS 2 arn ea eo wt ev Ge ae ta ee ee ee ee es a ee ae ea 327 Ruling Formats 2 08 2 Swen and werd ala gule Fare Pb eka dy eek ee es 328 Table Catalog formats o oo oaa a 330 Tables a a Gh dee Sea Gee eee a hs Ge a a es a E a a 332 COlOMS lt lt ana hb oh he e ee a ee GR ec ea ee d a a 338 Structural element definitions 0 0 a 342 Format rules and format rule clauses oaoa aa ee 344 Format change lists 2 1 ee 346 Siructural elements cos wr arn o kae 4 aoa eat A eee we a ek A ae 347 Chapter 15 Frame Book Architecture 351 What the user sees 2 2 0 00 2 ee ee 351 How the API represents books aaoo a 351 Creating new books andcomponents 0000 eee ee eee 355 Updatingabook 2 2 A ea aa a a aa a a a a a a a e aA 356 Using the book error log aooaa aa a 360 FDK Programmer s Guide vii viii Part Ill Chapter Chapter Chapter Frame Development Environment FDE 16 Introduction to FDE How the FDE works 0 00 eee ee How to make your client portable 0 Asimple FDE filter 2
426. is manual G xii to G xiv R xix to R xxi index 5 index 6 Index Subjects coordinate pairs structure for individual R 683 structure for sets G 271 R 684 See also points F_PointsT properties coordinates measuring R 683 copying API structures R 4 R 69 the contents of handles R 372 memory blocks R 373 properties G 102 R 297 text selections G 127 R 3 R 23 R 68 to R 69 creating API clients G 6 to G 12 API objects G 7 G 143 to G 145 documents G 53 to G 57 G 279 functions for G 53 G 56 R 6 R 70 to R 72 R 238 to R 244 R 325 to R 326 the F_ApilInitializeQ function G 13 G 35 cross reference building blocks G 322 cross reference formats G 281 G 322 to G 323 R 531 API representation of G 281 G 322 to G 323 illustrated G 323 properties of G 322 to G 323 R 531 cross reference instances G 323 to G 324 R 530 properties of G 323 to G 324 R 530 cross references API representation of G 281 G 323 to G 324 API representation of the beginning of G 314 R 167 R 687 API representation of the end of G 314 R 167 R 687 creating G 148 to G 149 function for R 209 to R 210 illustrated G 324 properties of G 323 to G 324 R 529 to R 531 updating function for R 7 R 343 See also cross reference formats cross reference instances current directory getting G 96 current page defined G 291 custom dialog boxes G 177 to G 227 creating G 177 to G 209 using G 211 to G 227 See also dialog boxes custom doc
427. ister an assertion handler and perform its own error handling with the FDE function F_SetAssert When the client s assertion handler returns the FDE s assertion handler is called to clean up the system and exit the client properly To use the FDE assertion handler functions you must include fdetypes hand fassert h in your client Making memory allocation portable The FDE provides a set of functions you can substitute for your client s platform specific memory allocation and deallocation function calls These functions accommodate the different memory models on UNIX Macintosh and Windows platforms The Macintosh does not use a hardware memory management unit Instead the operating system periodically compacts memory to free up more space To accommodate this model the Macintosh uses relocatable memory It allows you to work with handles which are pointers to pointers to relocatable memory Each handle points to a master pointer which in turn points to the memory block If the operating system decides to move the memory it moves the block and then updates the master pointer to point to the new location The old memory location can then be overwritten The handle however remains the same So your client is not affected by the change in the absolute location of the memory Sometimes you may need to use a pointer directly into absolute memory To create this pointer you must first lock the memory to tell the operating system t
428. istiller Exchange Frame FrameMaker Frame Viewer InstantView and PostScript are trademarks of Adobe Systems Incorporated Apple PowerBook QuickTime Macintosh and Power Macintosh are trademarks of Apple Computer Inc registered in the United States and other countries Focoltone is a registered trademark of Gordon Phillips Limited ImageStream Graphics Filters and ImageStream are registered trademarks of Inso Corporation Microsoft MS DOS Windows and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and or other countries Quadralay and WebWorks are registered trademarks of Quadralay Corporation PANTONE PANTONE MATCHING SYSTEM PANTONE Process Color System and POCE are trademarks of Pantone Inc Proximity and Linguibase are registered trademarks of Proximity Technology Inc A Merriam Webster is a registered trademark of Merriam Webster Inc Sun is a trademark or registered trademark of Sun Microsystems Inc in the United States and other countries TRUMATCH is a registered trademark of Trumatch Inc Unix is a registered trademark and X Window System is a trademark of The Open Group Verity and TOPIC are registered trademarks of Verity Inc All other trademarks are property of their respective owners The following are copyrights of their respective companies or organizations Portions reproduced with the permission of Apple Computer Inc 1996 Apple Computer Inc Milo 1988
429. itemId FP_Text F_Printf NULL Text box contains text s n text break case FV_DlgClose F_Printf NULL The user closed the dialog box n break default break Handling user actions in a modal dialog box The API allows you to implement two different types of modal dialog boxes e Single interaction dialog boxes which close as soon as the user clicks an item e Multiple interaction dialog boxes which allow the user to manipulate one or more items without closing For example alert boxes are single interaction modal dialog boxes The API dialog boxes displayed by F_ApiPromptInt F_ApiPromptMetric and F_ApiPromptString are multiple interaction modal dialog boxes The following sections describe how to handle user actions in each type of modal dialog box Handling user actions in single interaction dialog boxes To implement a dialog box as a single interaction modal dialog box follow these steps 1 Display the dialog box by calling F_ApiModalDialog with dlgNum setto 0 F_ApiModalDialog does not return until the user clicks a dialog item or uses another command such as Esc or Control c to close the dialog box 2 After F_ApiModalDialog returns determine what the user did by getting the properties of items in the dialog box For example the following code handles user actions in a modal dialog box that contains Cancel Apply and Help buttons define APPLY BUTTON 1 defi
430. itional text in the document the FrameMaker product adds a hidden page to the document to store the hidden text A document can have only one hidden page FrameMaker represents the hidden page with an FO_HiddenPage object The FO_Doc property FP_HiddenPage specifies its ID The hidden page has only one text flow named HIDDEN For more information on how the API represents hidden conditional text see How the API represents hidden conditional text on page 318 How the API represents master pages Both single sided and double sided documents have default master pages named Right and Left In single sided documents the Left master page is not visible to the user However you can get and set its properties with the API 292 FDK Programmer s Guide Frame Document Architecture 14 Graphic objects A graphic object is anything the user can draw with the Tools palette or an imported graphic What the user sees A graphic object can be e An anchored frame which is a container for graphic objects that is tied to a specific location in text e Anunanchored frame which is a container for graphic objects that is not tied to a specific location in text e A simple geometric shape which is a line an arc a rectangle a rounded rectangle an ellipse a polyline or a polygon e A group which is an invisible graphic object that holds together a set of other graphic objects e A text line which is a single line of text that isn
431. its appearance and its item focus order You can test it as a modal dialog box or as a modeless dialog box e A modal dialog box prevents the user from performing any other action in FrameMaker while the dialog box is visible For example the Print dialog box is a modal dialog box Until the user clicks Print or Cancel to close the dialog box the user can t perform any other action e A modeless dialog box allows the user to perform other actions in FrameMaker while the dialog box is displayed For example the Marker dialog box is a modeless dialog box While the Marker dialog box is displayed the user can do other work in a Frame document A DRE file does not specify whether a dialog box is modal or modeless Your client code determines the dialog box type when it displays it For more information see Displaying a dialog box on page 219 To test a dialog box use one of the following keyboard shortcuts e To test the dialog box as modal press Esc d t In this mode clicking any button dismisses the dialog box e To test the dialog box as modeless press Esc d T In this mode clicking any button does not dismiss the dialog box To close the dialog box use the native window manager functionality IMPORTANT These keyboard shortcuts only work in UNIX and Windows versions of FrameMaker If you are using a Macintosh version you can test the dialog box by using the MPW tool makedbre For details see the FDK Platform Guide for the
432. ivity property to False For example the following code disables a dialog item F_ObjHandleT dlgId itemId F_ApiSetInt dlgId itemId FP_Sensitivity False Displaying a dialog box After you have opened a dialog resource you can display it as a modal or a modeless dialog box To display it as a modal dialog box call F_ApiModalDialog To display it as a modeless dialog box call F_ApiModelessDialog The syntax for F_ApiModalDialog and F_ApiModelessDialog is IntT F_ApiModalDialog IntT dlgNum F_ObjHandleT dlgId IntT F_ApiModelessDialog IntT digNum F_ObjHandleT dlgId This argument Means dlgNum A unique number to identify the dialog box The API passes this number to your client s F_ApiDialogEvent callback when there is a user action in the dialog box If you don t want the API to call your client s F_ApiDialogEvent callback when there is a user action set dlgNum to 0 FDK Programmer s Guide 219 E Handling Custom Dialog Box Events 220 This argument Means dlg d The ID of the dialog resource to display F_ApiModelessDialog returns immediately Ifit can t display the dialog box it returns an error code Otherwise it returns FE_Success If you call F_ApiModalDialog with dlgNum setto 0 it does not return until the user closes the dialog box If the user clicks Help in the dialog box F_ApiModalDialog returns a nonzero value ot
433. jHandleT F_ObjHandleT Executing Commands with API Functions 4 sumId ID of the summary document compiId ID of the composite document The following values can be ORed into the flags argument This value Means FF_CMP_SUMMARY_ONLY Generate summary document but not composite document FF_CMP_CHANGE_BARS FF_CMP_HYPER FF_CMP_SUMKI1 LINKS FF_CMP_COMPKIT Turn on change bars in the composite document Put hypertext links in the summary document Open the summary document Open the composite document If you specify the FF_CMP_SUMKIT or FF_CMP_COMPKIT flags F_ApiCompare opens the summary and comparison documents and returns their IDs in the F_CompareRetT structure It does not make these documents visible to the user If you want them to be visible you must set each of the document s FP_DocIsOnScreen properties to True Example The following code opens two documents and compares them as specified in the dialog boxes shown in Figure 4 2 It makes the summary document visible F_ObjHandleT oldId newId IntT flags F_CompareRetT cmp ol ne fl did wid ags cmp If FA _ errno F_ApiSimpleOpen tmp 1Chapter False F_ApiSimpleOpen tmp 1Chapter new False T FF_CMP_CHANGE_BARS FF_CMP_COMPKIT FF_CMP_SUMKIT F_ApiCompare oldId newId flags Comment we r Repl F aced Text 75 E Success
434. jects G 111 G 280 G 298 G 299 G 304 R 579 properties of R 579 FO_FmtChangeList objects G 106 G 282 G 346 R 582 FO_FmtRule objects G 281 G 343 G 345 index 45 os Index Reserved Names FO_FmtRuleClause objects G 282 FO_Fn objects G 281 G 303 G 327 R 581 properties of R 581 FO_Group objects G 280 G 296 R 599 properties of R 599 FO_HiddenPage objects G 280 G 289 G 292 R 84 R 611 properties of R 611 FO_Inset objects G 230 G 256 G 259 G 280 R 599 facets of G 257 properties of R 599 FO_Line objects G 280 G 295 R 602 properties of R 602 FO_Marker objects G 281 G 319 R 608 properties of R 608 FO_MarkerType objects G 269 G 281 R 609 properties of R 609 FO_MasterPage objects G 269 G 280 G 289 G 291 R 84 R 612 properties of R 612 FO_Math objects G 280 R 603 properties of R 603 FO_Menu objects G 161 G 270 R 77 R 82 properties of R 523 R 528 FO_MenultemSeparator objects G 161 G 169 G 270 properties of R 523 R 528 FO_Pef objects G 3 G 102 G 111 G 280 G 284 G 302 R 613 properties of R 613 FO_PgfFmt objects G 102 G 270 G 273 G 280 G 282 G 301 R 613 R 621 example property list for illustrated G 273 properties of R 621 FO_Polygon objects G 280 R 603 properties of R 603 FO_Polyline objects G 280 R 604 properties of R 604 FO_Rectangle objects G 3 G 280 R 604 properties of R 604 FO_RefPage objects G 270 G 280 G 289 G 291 R 612 properties of R 612 FO_RoundRect objects G 280
435. ker product reinitializes the client and when it issues the FA_Note_PreQuitDoc notification VoidT F_Apilnitialize initialization IntT initialization switch initialization case FA_Init_First Request notification F_ApiNotification FA_Note_PreQuitDoc True Bail out and wait for the event F_ApiBailOut break case FA_Init_Subsequent F_ApiAlert StringT Client is reinitializing FF_ALERT_CONTINUE_NOTE break VoidT F_ApiNotify notification docId filename IntT notification F_ObjHandleT docId StringT filename if notification FA_Note_PreQuitDoc F_ApiAlert StringT Client has reinitialized FF_ALERT_CONTINUE_NOTE 44 FDK Programmer s Guide Executing Commands with API Functions This chapter discusses how to use Frame API functions to execute FrameMaker commands programmatically The API doesn t provide a function to directly execute each of the commands available in the FrameMaker product user interface This is because you can achieve the effect of some commands by setting object properties For example to set a graphic s fill pattern you set the object s FP_Fill property For more information on setting object properties see Chapter 5 Getting and Setting Properties Handling errors When an API function fails it stores an error code in the global variable FA_errno FA_errno retains the error code unt
436. king KURT 2 Start the FrameMaker product 3 Open the file you created The FrameMaker product calls the filter the file to it on a Macintosh computer change the file s type to which creates a new document and adds the text from FDK Programmer s Guide 1 r Making I O and Memory Calls Portable This chapter discusses the FDE virtual environment functions you can use to replace the platform specific I O assertion handler and memory calls in your client For lists of the FDE virtual environment functions see Chapter 1 Function Summary of the FDK Programmer s Reference For the complete description of a function look it up in Chapter 2 FDK Function Reference in the FDK Programmer s Reference Initializing the FDE Before you call any FDE functions you should initialize the FDE To initialize the FDE call F_FdeInit as follows F_FdeInit IMPORTANT Each time your client bails out and reinitializes it should reinitialize the FDE by calling F_FdeInit Using platform independent representations of pathnames The FDE allows you to specify pathnames with a platform independent representation called a filepath The FDE uses the datatype FilePathT to specify a filepath Converting pathnames to filepaths The FDE provides functions that allow you to convert platform specific pathname strings to filepaths and filepaths back to platform specific pathname strings For example the follo
437. ks e FP_CanHaveCheckMark which specifies whether an item can have a check mark e FP_CheckMarkIsOn which specifies whether a check mark appears next to an item To use a check mark with a menu item set FP_CanHaveCheckMark to True Then make the check mark visible by setting FP_CheckMarkIsOn to True or invisible by setting it to False IMPORTANT Once you set FP_CanHaveCheckMark to True resetting itto False has no effect Setting FP_CheckMarkIsOn has an effect only when FP_CanHaveCheckMark is setto True Using context sensitive commands and menu items Many FrameMaker product commands and menu items change depending on the context For example the Group command is disabled when there are no objects selected The API provides properties that allow you to make your client s commands and menu items context sensitive like FrameMaker product commands The following sections describe how to use these properties FDK Programmer s Guide 173 E Manipulating Commands and Menus with the API 174 Enabling commands for specific contexts The FP_EnabledWhen property specifies the contexts in which a command is enabled The following table lists some of the values FP_EnabledWhen can have FP_EnabledWhen value Context in which a menu item is active FV_ENABLE_ALWAYS_ENABLE All contexts This is the default value FV_ENABLE_ALWAYS_DISABLE No context Setting FP_EnabledWhen to this value completely disa
438. l 0 F_StrCopyString red colors val 1 F_StrCopyString green colors val 2 F_StrCopyString blue wu err F_ApiScrollBox amp choice Choose a color amp colors 0 if err F_Sprintf msg The choice is s colors val choice else F_Sprintf msg Cancel was pressed F_ApiAlert msg FF_ALERT_CONTINUE_NOTE F_ApiDeallocateStrings amp colors FDK Programmer s Guide 23 E Creating Your Client s User Interface FrameMaker SGML fed green blue FIGURE 3 6 Scroll list dialog box Using commands menu items and menus in your client The API allows you to use commands menu items and menus in your client s user interface A command is a part of FrameMaker product or FDK client functionality that a user can invoke by typing a shortcut A menu item is an instance of a command that appears on a menu There can be several menu items for each command A menu is a list of menu items or other menus A menu bar is a list of menus that appears at the top of the screen on a Macintosh at the top of a document or book window on UNIX platforms and at the top of the FrameMaker product window on Windows platforms To use commands and menus in your client s user interface follow these general steps 1 Get the IDs of the FrameMaker product menu bars and menus that you want to add your client s menus and commands to 2 Define your client s commands and add them to
439. l always write out complete MIF fmbatch Doesn t require C programming can be used remotely from Only provides simple a nongraphics terminal functions only available on UNIX platforms FDK documentation FDK documentation assumes that you have a thorough knowledge of FrameMaker For background information on FrameMaker see your user documentation FDK documentation includes the following manuals FDK Programmer s Guide xi SS Using Frame Developer Tools FDK Platform Guide The FDK Platform Guide is printed in several versions each describing how to install the FDK on a specific platform It provides the pathnames of sample programs and describes platform specific differences in using the FDK FDK Programmer s Guide The FDK Programmer s Guide describes how to use the FDK to create clients for FrameMaker To get the most from this manual you should be familiar with the C programming language and event driven programming The FDK Programmer s Guide is divided into three parts e Part I Frame Application Program Interface API provides instructions for creating API clients e Part I Frame Product Architecture provides a conceptual overview of how the API represents sessions books and documents e Part II Frame Development Environment FDE provides instructions for making filters and API clients platform independent FDK Programmer s Reference The FDK Programmer s Guide which you are reading now
440. l bar so that the height of the scroll bar is greater than the width The scroll bar appears distorted until you use the keyboard shortcut for viewing the dialog box on the current platform You can use a similar process to change the orientation from vertical to horizontal For information on setting the basic properties for this dialog item see the section Setting basic dialog item properties on page 197 Scroll lists A scroll list is a list of items from which the user can select an item You can t specify the list of items in the DRE file Instead you must include code in your client to provide it For more information see Initializing items in a dialog box on page 218 The scroll list item does not include a label For instructions on adding a label for a scroll list see the section Adding dialog items on page 192 For information on setting the basic properties for this dialog item see the section Setting basic dialog item properties on page 197 Specifying keyboard shortcuts for Windows versions In Windows the user can activate or select certain dialog items by pressing a keyboard shortcut The shortcut is identified by the first underlined letter in the item s label When the user presses the Alt key and this letter the dialog item is activated Figure 10 17 illustrates how a shortcut is identified in the label of a text box 202 FDK Programmer s Guide Creating Custom Dialog Boxes for Your Clien
441. l for all contexts Its FP_Labels property should specify only one string For example the following code sets the label of a client defined menu item to My Item F_StringsT myLabels F_ObjHandleT cmdId StringT labels 1 labels 0 StringT My Item myLabels len 1 myLabels val StringT labels F_ApiSetStrings FV_SessionId cmdId FP_Labels amp myLabels Manipulating expandomatic menu items An expandomatic menu item is a dynamically determined set of menu items that FrameMaker treats as a single menu item For example the list of paragraph formats that appears on the lower part of the Format gt Paragraphs menu is an expandomatic menu item named ShowParagraphTags FrameMaker currently uses the following expandomatic menu items Expandomatic menu item name Description ShowCharacterTags The list of character formats available in the current document ShowDocumentWindows The list of document windows in the current session ShowFilesRecentlyVisited The list of the last five files opened ShowFontChoices The list of font families available in the session ShowImportFiles The list of open files that a user can import into the current document ShowParagraphTags The list of paragraph formats available in the current document A FrameMaker product can change the contents of an expandomatic menu item during a session For example when the user sets the insertion point in a document the FrameMake
442. l property FO_DlgScrollBar R 536 FP_InitStructurePattern property FO_ElementDef R 646 FP_InsertLinks property FO_BookComponent R 511 FP_InsetDpi property FO_Inset G 256 R 599 FP_InsetEditor property FO_Inset G 256 G 262 R 599 FP_InsetFile property FO_Inset G 230 G 257 G 259 G 263 R 599 FP_InsetIsFixedSize property FO_Inset G 257 R 599 FP_InsetIsFlippedSideways property FO_Inset G 257 R 599 FP_InsetUpdater property FO_Inset R 600 FP_InTextFrame property FO_AFrame R 597 FP_InTextFrame property FO_Cell R 650 FP_InTextFrame property FO_Fn R 581 FP_InTextFrame property FO_Pgf G 303 R 620 FP_InTextFrame property text location R 670 FP_InTextObj property FO_AFrame R 597 FP_InTextObj property FO_Cell R 650 FP_InTextObj property FO_Fn G 328 R 581 FP_InTextObj property FO_Pgf G 303 R 620 FP_InTextObj property text location R 670 FP_InvalidHighestLevel property FO_Element R 644 FP_InvariantName property FO_Marker R 609 FP_IsIconified property FO_Book R 495 FP_IsIconified property FO_Doc R 577 FP_IsIconified property FO_Session R 634 FP_IsInFront property FO_Book G 97 R 496 FP_IsInFront property FO_Doc R 577 FP_IsInFront property FO_Session R 634 FP_IsOnScreen property FO_Book R 496 FP_IsOnScreen property FO_Doc G 98 R 548 R 577 FP_IsOnScreen property FO_Session R 634 FP_IsTextRange property FO_FmtRuleClause R 591 FP_KeepWithNext property FO_FmtChangeList R
443. le it uses F_ObjHandleT for object IDs For a list of API data types see Chapter 4 Data Types and Structures Reference in the FDK Programmer s Reference Due to platform limitations Asynchronous clients clients that run outside of the FrameMaker process space are not portable on all platforms For specific information on Asynchronous clients see the FDK Platform guide for the platform in question Running clients with different FrameMaker product interfaces FrameMaker ships with two product interfaces Structured FrameMaker and FrameMaker A client can only use functionality that is available in the product interface that is active for the currently running FrameMaker process For example if a client is running on the unstructured FrameMaker product interface it can t create or manipulate structural elements FO_Element objects On the other hand all functions in the FDK are available to a client running on the Structured FrameMaker product interface To determine if a function is available in a particular product interface see Chapter 2 FDK Function Reference in the FDK Programmer s Reference For an example of how to programmatically determine which product interface is running see F_ApiGetString on page 158 of the FDK Programmer s Reference Creating and running a client To create and run a client follow these general steps 6 FDK Programmer s Guide Introduction to the Frame API aa
444. le IDs docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tbliIid F_ApiGetId FV_SessionId docId FP_SelectedTbl Get the ID of the first row and cell rowld F_ApiGetId docId tbliId FP_FirstRowInTbl cellId F_ApiGetId docId rowId FP_FirstCellInRow FDK Programmer s Guide Manipulating Text 6 Set up text location at beginning of cell ip objId cellld ip offset 0 F_ApiAddText docId amp ip This text appears in the cell For an example of how to create a table and add text to its title see Creating tables on page 154 Getting and setting text formatting Although the API doesn t represent text as objects the characters in text have properties Each character has a property list describing its font color condition tags and other character formatting attributes The API provides special functions to get and set the properties in this list You can also get and set text formatting by getting and setting paragraph paragraph format and character format properties For more information see Getting and setting paragraph properties on page 102 Getting text properties To get an individual property for a character use F_ApiGetTextPropVal To get the entire list of text properties for a character use F_ApiGetTextProps The syntax for these functions is F_PropValT F_ApiGetTextPropVal F_ObjHandleT doclId F_TextLocT textLocp IntT propNum F_PropValsT F
445. leT cutCmdId cutCmdId F_ApiGetNamedOb ject FV_SessionId FO_Command Cut F_ApiSetString FV_SessionId cutCmdId FP_Label Excise the API changes the label of all instances of the Cut command to Excise The following properties apply only to individual instances of an FO_Menu FO_Command or FO_MenuItemSeparator object e FP_PrevMenultemInMenu e FP_NextMenuItemInMenu When you get or set these properties you must indicate which instance of the object you want to get or set them for To do this set the first parameter of the F_ApiGetId or F_ApiSetId function to the ID of the menu containing the instance For example the following code gets the ID of the menu item above Cut on the Edit menu Then it gets the ID of the menu item above Cut on the document window pop up menu F_ObjHandleT editMenulId cutCmdId docPopupMenuld previtemOnEditMenuld prevItemOnDocMenuld editMenuld F_ApiGetNamedObject FV_SessionId FO Menu EditMenu docPopupMenuld F_ApiGetNamedOb ject FV_SessionId FO_Menu MakerPopup cutCmdId F_ApiGetNamedOb ject FV_SessionId FO_Command Cut previtemOnEditMenuld F_ApiGetId editMenuld cutCmdId FP_PrevMenulItemInMenu previtemOnDocMenuld F_ApiGetId docPopupMenuld cutCmdId FP_PrevMenulItemInMenu Getting the IDs of commands and menus To manipulate a command or menu you need its ID If you know its name the simplest way to get
446. lean up memory for any cells pass 0 e stringifyMe specifies a procedure that turns non string keys into strings This is most useful for debugging FDK Programmer s Guide 383 18 FDE Utility Libraries 384 Structures and pointers in keys The routines F_HashSet F_HashGet and F_HashRemove each receive a key as an argument These routines work best with flat keys such as integers or strings It is safest to use flat keys instead of structures for keys if necessary you can always use F_Sprintf to put structure fields into a string The internal hash routine used by these functions examines the bytes in the key If the key is a structure containing pointers it only checks the pointers not the pointed to data Further it examines every byte in the key If you use structures for keys you should be sure to to clear the memory first then assign values to the structure members then set the item in your hash table For example use F_ClearPtr amp myStructKey sizeof myStructKey when myStructKey will be a key for a teble cell When you pass a key to F_HashSet the function actually creates a copy of the key However it only copies the string or the number of bytes specified in F_HashCreate as the key length If your key is a structure that contains pointers F_HashSet will create copies of the pointers but not copies of the pointed to data Metric library The Frame API uses the MetricT type to
447. lementLocT beg Beginning of the element range F_ElementLocT end End of the element range F_ElementRangeT The F_ElementLocT structure specifies a location within an element It is defined as typedef struct F_ObjHandleT parentId Parent element ID F_ObjHandleT childId Child element ID IntT offset Offset within child parent element F_ElementLocT For information on how FrameMaker sets the fields of the F_ElementRangeT structure specified by FP_ElementSelection to represent different types of selection see How the API represents the element selection in a structured FrameMaker document on page 286 For examples of how to get and set element selections see F_ApiGetElementRange on page 113 and F_ApiSetElementRange on page 282 of the FDK Programmer s Reference FDK Programmer s Guide Manipulating Text 6 To traverse the selection returned by F_ApiGetElementRange traverse the child elements of the element specified by beg childId Then traverse its sibling elements and all of their child elements until you reach the element specified by end childId To traverse an element s child elements you query its FP_FirstChildElement property and then query each child element s FP_NextSiblingElement property To traverse an element s siblings you query its FP_NextSiblingElement property and then query each sibling element s FP_
448. lizing items in a dialog box Displaying a dialog box oaoa a a Updating items in a dialog box Handling user actions in dialog boxes oaao aaa aa Closing a dialog box a aooaa a a 12 Using Imported Files and Insets Types of imported files andinsets Importing text and graphics aooaa a Updating text insets ooo 0000 Client text insets ooa Writing filter ciems soes an e aea a a a a a a a Specifying format IDs and filetype hint strings Associating a file format with signature bytes Writing graphic inset editors 2 Frame Product Architecture 13 Frame Session Architecture Identifying objects 2 22 2 0022 0005 Representing object characteristics with properties FrameMaker product sessions FDK Programmer s Guide Chapter 14 Frame Document Architecture 279 DOCUMENTS 6 kee hea ee See eS ERE RAS ER owe ew ee 279 Global document information 2 2 a 284 Pages 2k sek p ai Bae ee Bee Rae OR a Pe eA ee te eB 288 Graphic ODjeCts cc ae we Me a Re ew a Oe ee a ee G 293 FIOWS 2 2 face a eck ae ae et ae Mee ee ee ee A ee ee ee 297 Paragraph Catalog formats 2 2 2 a 300 ParagrapnS 4 24 428s be ee hee wee ee hed eee RR BE eS 302 Character Catalog formats 2 aa ee 305 Condition Formats ss s as s aa sa aa a a a aa a 309 TEXT e G
449. ll displays an alert that tells the user to select an object The constant FF_ALERT_CONTINUE_WARN specifies the type of alert an alert with a Continue button To set the object s fill pattern the client must set its FP_Fill property FP_Fill isan IntT property so the client must use F_ApiSetInt to set it The syntax for F_ApiSetInt is VoidT F_ApiSetInt parentId Object s parent objId Object whose property you want to set property Constant specifying property to set value Value to which to set the property FP_Fill can have any value between 0 and 15 The API defined constant FV_FILL_ BLACK specifies 0 black Lines 52 54 These lines add a body page to the document when the user chooses Add a Page from the API menu A body page object is a series object To create a series object you use F_ApiNewSeriesOb ject The syntax for F_ApiNewSeriesOb ject is F_ObjHandleT F_ApiNewSeriesObject parentId Object s Parent objectType Constant specifying new object type prevObjectId Object for new object to follow The parentId parameter specifies the ID of the object that is to contain the new object The new page should appear in the active document so parentId is setto docId The API uses FO_BodyPage objects to represent body pages so objectType is setto FO_BodyPage Specifying 0 for prevObjectId puts the new page at the beginning of the document For more information o
450. log box For more information see the section Testing a dialog box on page 205 Creating a DRE file The first step in creating a dialog box is to create a DRE file This file stores all the information about a dialog box and its items FDK Programmer s Guide 185 a Creating Custom Dialog Boxes for Your Client 186 Since dialog boxes and dialog items are different objects than standard Frame graphic objects you cannot create a new file such as a blank portrait document for example and draw the dialog box and its items You must start from an existing DRE file that already contains these objects Also although you may find that you are able to copy and paste dialog items from a DRE file into a regular Frame document you should not use a Frame document to create a dialog box A saved Frame document cannot be converted to the dialog resources necessary to create a dialog box To create a new DRE file start FrameMaker and use the DRE file as a template as follows 1 Choose New from the FrameMaker File menu Using the New command ensures that you don t overwrite the template 2 Select an existing DRE file You can use the DRE template file provided with the FDK You can find the template file in the following locations fdk_install_dir samples dre template dre in UNIX fdk_install_dir samples dre template dre on the Macintosh fdk_install_dir samples dre template dre in Windows where fok_install
451. log box use the following code F_ObjHandleT docId F_PropValsT params returnParamsp NULL IntT i Get a default property list params F_ApiGetOpenDefaultParams FDK Programmer s Guide 49 a Executing Commands with API Functions If F_ApiGetOpenDefaultParams fails len will be 0 if params len 0 return Get index of FS_ShowBrowser property then set it to True i F_ApiGetPropIndex amp params FS_ShowBrowser params val i propVal u ival True Change default to tmp when Open dialog box appears F_ApiSetString 0 FV_SessionId FP_OpenDir tmp docId F_ApiOpen amp params amp returnParamsp F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp The API allocates memory for the property list created by ia F_ApiGetOpenDefaultParams Use F_ApiDeallocatePropVals to free the property list when you are done with it For another example of how to call F_ApiOpen using a default property list created by F_ApiGetOpenDefaultParams see F_ApiGetOpenDefaultParams on page 138 of the FDK Programmer s Reference Creating an openParamsp script from scratch If you only need to specify a few properties when you call F_ApiOpen it is most efficient to create a property list from scratch To create the property list you must allocate memory for it and then set up the individual properties To allocate
452. lso variable formats View menu name used to specify G 25 R 76 view only menu bar to G 162 view only properties See document properties virtual environment defined G 391 virtual environment See FDE virtual environment W warnings displaying G 17 to G 18 G 45 G 379 R 488 See also API error codes Windows platforms compiling and running FDE filters G 373 index 33 os Index Subjects dialog boxes on G 180 to G 181 G 189 X disabling clients G 16 image pop up menus G 200 keyboard shortcuts in dialog boxes G 202 memory management on G 378 to G 379 registering clients with the FrameMaker product G 8 G 12 take control initialization G 15 Y Z word spacing See paragraph formats FO_PgfFmt j word spacing properties of paragraphs FO_Pgf Yes buttons displaying G 18 word spacing properties of wrdcnt document report G 5 Writing export filters G 242 Writing file to file filters G 243 Writing graphic import filters G 241 Writing text import filters G 239 X resource files UNIX G 181 G 182 G 185 XML attributes G 348 XMP Metadata R 497 R 540 xxxTemplate G 279 index 34 FDK Programmer s Reference amp Guide Symbols BookMainMenu string constant G 25 R 78 CustomMakerMainMenu string constant R 78 MakerMainMenu string constant G 25 G 27 R 78 MakerPopup string constant R 78 QuickBookMainMenu string constant G 25 R 78 QuickMakerMainMenu string constant G 25 G 27 R 78 QuickMakerPopup string constant R
453. ly to the text location To apply conditions to a text range set the FP_InCond property for the text range For example the following code applies the Comment condition to the selected text F_TextRangeT tr F_PropValT prop F_ObjHandleT docId commentId F_IntsT condIds docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_ TextSelection if tr beg objId return Get the ID of the Comment condition commentId F_ApiGetNamedObject docId FO_CondFmt Comment Set up array of conditions just one in this case condids val IntT amp commentId condiIds len 1 Set up property prop propident num FP_InCond prop propVal valType FT_Ints prop propVal u isval condIds Apply the property to the text selection F_ApiSetTextPropVal docId amp tr amp prop Setting type in properties A Frame document has a set of properties called type in properties which specify the text characteristics of the insertion point in the document Type in properties do not apply to text that is already in a document they apply only to text as the user types it in the document Whenever the user changes the insertion point in a document the FrameMaker product sets the document s type in properties to match the text properties of the character to the left of the FDK Programmer s Guide Manipulating Text 6 insertion point However a document
454. lyMainMenu gt ViewOnlyFileMenu New senate sae line FP_NextMenultemInMenu FP_NextMenultemInMenu FO_Menu FO_Command ViewOnlyEditMenu Open ne s emnnalentnun FP_NextMenultemInMenu FP_NextMenultemInMenu FO_Menu FO_Command ViewOnlyNavMenu Quit FIGURE 9 1 FrameMaker view only menu bar and the objects that represent it FDK Programmer s Guide 161 E Manipulating Commands and Menus with the API IMPORTANT FP_FirstMenuItemInMenu FP_PrevMenuItemInMenu and FP_NextMenuItemInMenu properties can specify menu menu item or menu item separator IDs The following table lists some of the properties of the FO_Command object that represent the Open menu item in Figure 9 1 Property Type Value FP_CanHaveCheckMark IntT False FP_Fcodes F_IntsT 0x310 FP_KeyboardShortcuts F_StringsT fo FP_KeyboardShortcut Label StringT Wt FP_Labels F_StringsT Open FP_MenultemIsEnabled IntT True FP_Name StringT Open You can get and set FO_Command FO_Menu and FO_MenulItemSeparator properties the same way you get and set the properties of other API objects For more information on getting and setting object properties see Chapter 5 Getting and Setting Properties Lists of menus menu items and commands in a session The API maintains a linked list of all the menus and menu items in a session The FO_Session property FP_FirstMenuItemInSession specifies the ID of the first object i
455. me Characteristics such as the footnote anchor s numbering type are represented as document properties because they apply to all the footnotes in a document and not just individual footnote instances For more information on the document properties that govern footnote characteristics see How the API represents documents on page 280 The API represents each footnote anchor with an FTI_FnAnchor text item which specifies the ID of the FO_Fn object that represents the footnote FO_Fn properties provide the following information e The footnote number e The ID of the text frame in which the footnote text appears e The ID of the next footnote in the list of footnotes in the document e The IDs of the first and last paragraphs containing the footnote s text e The element ID of the footnote if it is a structured footnote in a FrameMaker document FDK Programmer s Guide 327 14 Frame Document Architecture Figure 14 29 shows a footnote and the text item that represents it The footnote text is actually in its own text col umn 1 Which appears down here offset 17 dataType FTI_FnAnchor idata FO_Fn ID FIGURE 14 29 A footnote and the text item that represents it The following table lists the properties of the FO_Fn object specified by the FTI_FnAnchor text item in Figure 14 29 Property Type Value FP_InTextOb j F_ObjHandleT The ID of the subcolumn FO_SubCo1 in which the footnote a
456. ment Catalog AttributeDefsT adsval Attribute definitions AttributesT asval Attribute values _ElementRangel 7 4 A T erng Element range _IntsT isval Set of integers UIntsT uisval Set of unsigned integers IntT ival Integer u F_TypedValT a ee ee 272 FDK Programmer s Guide Frame Session Architecture 13 The constants used in the valType field are described in the following table valType constant Property data type u field FT_Integer IntT ival FT_Ints F_IntsT isval FT_Metric Met ricT ival FT_Metrics F_MetricsT msval FT_String StringT sval FT_Strings F_StringsT ssval FT_Id F_ObjHandleT ival FT_Points F_PointsT psval FT_Tabs F_Tabs tsval FT_TextLoc F_TextLocT tlival FTI_TextRange F_TextRangeT trval FT_UInts F_UIntsT uisval FT_UBytes F_UBytesT No field FT_ElementCatalog F_ElementCatalogEntriesT csval FT_AttributeDefs F_AttributeDefsT adsval FT_Attributes F_AttributesT asval FT_ElementRange F_ElementRangeT erng IMPORTANT Integer IntT metric MetricT and ID F_ObjHandleT values are all putin the ival field of the u union Example Suppose the user creates a paragraph format named Heading which has a 1 inch left indent and has Keep With Next Paragraph turned on The API represents this paragraph format with an FO_PgfFmt object The following are
457. ments G 298 to G 300 illustrated G 298 properties of G 298 G 299 R 579 to R 580 special G 289 structure properties of R 581 structured G 300 See also text frames fmbatch utility G x R xvi advantages and limitations of G xi R xvii fmemory h header file G 379 fmetrics h header file G 384 fmifstmt h header file G 387 FO_ naming convention G xiii R xix focus order of a dialog box G 194 to G 195 font encoding functions for getting the encoding for a given ID R 385 getting the ID of a named encoding R 384 getting function for R 117 to R 118 example FDE G 370 to G 374 for graphic insets G 241 to G 250 R 600 to R 602 initializing G 15 making portable example G 370 to G 374 registering G 15 requesting notification for G 36 find and replace API function for R 23 fioutils h header file G 382 first focus of dialog boxes G 196 first initialization G 14 index 12 FDK Programmer s Reference amp Guide font encoding data initializing R 375 font encoding for dialog boxes R 375 font family encoding getting function for R 115 fonts angles API specification of G 276 to G 277 R 8 API representation of G 306 to G 308 API specification of G 276 to G 277 R 8 conventions used in this manual G xiv R xx families API specification of G 276 to G 277 R 8 names determination of G 306 to G 308 platform G 307 to G 308 PostScript G 307 to G 308 specifying G 306 to G 309 text encoding API specification of R 8 variations A
458. menus 3 Define your client s menus and add them to FrameMaker product menus or menu bars 4 Write an F_ApiCommand callback to respond to the user invoking your client s commands These steps are discussed in greater detail in the following sections Getting the IDs of FrameMaker product menus and menu bars To get the IDs of commands menus or menu bars use F_ApiGetNamedObject The syntax for F_ApiGetNamedObject is F_ObjHandleT F_ApiGetNamedObject F_ObjHandleT parentId IntT ob jType StringT ob jName This argument Means parentId The ID of the document book or session containing the object for which you want to get an ID For commands and menus it is always FV_SessionId 24 FDK Programmer s Guide Creating Your Client s User Interface a This argument ob jType ob7jName Means The object type To get the ID of a command specify FO_Command To get the ID of a menu or menu bar specify FO_Menu The name of the command menu or menu bar This name may not be the same as the label or title that appears on a menu The menu and command names you can specify for objName depend on the FrameMaker product and how the user has customized the menus On UNIX platforms the default command names are listed in SFMHOME fminit UILanguage configui Commands and the default menu names are listed in SFMHOME fminit UILanguage con figui Product InterfaceMenus where
459. milar to these dialog boxes it should include code to handle these events For example to make your client support the FV_DlgNoChange event add code to do the following to a dialog box e Set the state of every tribox to FV_DlgOptDontCare e Set the text of every text box to an empty string e Set the state of any pop up menus that contain an As Is item to the index of that item Closing a dialog box To close a dialog box call F_ApiClose The syntax for F_ApiClose is F_ObjHandleT F_ApiClose F_ObjHandleT objlId IntT flags This argument Means objid The ID of the dialog box to close flags Currently an unused parameter Set it to 0 You can close a dialog box anywhere in your client code including the F_ApiDialogEvent callback For example you can call F_ApiClose to close the dialog box after a dialog event for clicking a radio button However you can call F_ApiReturnValue to set FR_ModalStayUp in the callback for a given dialog box event In that case the FR_ModalStayUp overrides any call to F_ApiClose for the same event IMPORTANT Check the ID you pass to F_ApiClose to make sure it is not 0 If you call F_ApiClose with objId set to O it quits the Frame session abandoning any unsaved changes For example the following code closes a dialog box F_ObjHandleT dlgId if dlgId 0 F_ApiClose dlgId 0 FDK Programmer s Guide 227 E Handling Custom Dialog Box Events 228 FDK Progr
460. mmer s Guide 107 rs Getting and Setting Properties 108 You can also set FP_FmtChangeList and FP_SubFmtRule only indirectly by calling F_ApiSubObject to add a change list or subformat rule to the format rule clause or by calling F_ApiDelete to delete a change list or subformat rule For an example of how to use F_ApiSubOb ject see Creating format rules format rule clauses and format change lists on page 152 Setting element definition properties Element definitions have the following properties that are only indirectly settable e FP_TextFmtRules FP_ObjectFmtRules e FP _ PrefixRules e FP_SuffixRules e FP_FirstPgfRules e FP_LastPgfRules Each of these properties specifies a list of format rules You can t directly add a format rule to one of these lists Instead you must call F_ApiSubObject F_ApiSubOb ject creates an FO_FmtRule object and adds it to the end of the specified list You also can t directly remove a format rule from a list Instead you must call F_ApiDelete to delete the format rule For example the following code adds and deletes a text format rule F_ObjHandleT docId paraEdefId fmtRulelId paraEdefId F_ApiGetNamedObject docId FO_ElementDef Para Add a text format rule to the element definition fmtRuleId F_ApiSubObject docId paraEdefId FP_TextFmtRules Delete the text format rule F_ApiDelete docId
461. n EndPreview n EndProlog n Page one 1 0 0 moveto 18 0 rlineto 0 18 rlineto 18 0 rlineto closepath 0 setgray 1 setlinewidth stroke sTrailer n We T o External graphic insets External graphic insets are stored in an external file The FP_InsetFile property of an external graphic inset is set to a platform specific filename that specifies the file For information on converting platform specific pathnames to platform independent device independent pathnames see Chapter 17 Making I O and Memory Calls Portable Users can update external graphic insets the same way they edit internal graphic insets Because external graphic inset data is not contained within the FrameMaker product document users can also edit the inset with other applications besides a graphic inset editor To edit an external graphic inset from FrameMaker the user opens the document and double clicks the inset The FrameMaker product launches the graphic inset editor which updates the inset by editing the inset file 260 FDK Programmer s Guide Using Imported Files and Insets 12 Example Suppose the user creates a bitmap inset with a graphic inset editor named myeditor The resulting FO_Inset object s property list and some of its properties are shown in 261 F_PropValsT len 12 val val 0 val 1 val 2 propiIdent propiIdent propiIde
462. n G 223 G 224 to G 225 single interaction G 223 testing G 205 modeless dialog boxes G 17 G 205 to G 206 displaying function for G 219 displaying dialog resources as function for R 208 to R 209 handling user actions in G 221 to G 223 G 225 to G 226 multiple G 225 to G 226 testing G 205 FDK Programmer s Reference amp Guide Index Subjects a multiline text boxes in dialog boxes G 200 multiple modeless dialog boxes handling user actions in G 225 to G 226 multiple interaction dialog boxes G 223 handling user actions in G 224 to G 225 N named graphic frames G 289 G 390 named objects G 87 to G 89 G 269 to G 270 R 136 to R 137 creating G 145 function for R 14 R 218 to R 220 defined G 390 getting the IDs of G 87 to G 89 G 269 to G 270 function for R 15 R 136 to R 137 naming conventions as used in this manual G xii R xix NewTemplate template G 279 No buttons displaying G 18 noapi start up option G 16 NoName elements R 347 noninteractive mode in simple functions G 46 G 47 notices See alert boxes alerts notification of events nonspecific G 38 to G 40 in Open operations G 41 to G 42 requesting G 13 G 34 to G 36 function for R 25 R 226 to R 233 requesting for filters G 36 responding to G 15 G 34 to G 42 function for R 1 R 233 to R 237 when updating dialog items G 220 notification constants G 35 G 38 R 227 to R 232 naming convention for G xiii R xix notification points G 34 to G 36 G 38 R
463. n R 108 F_ApiGetAttributes function R 110 F_ApiGetElementCatalog function R 112 F_ApiGetElementRange function G 120 R 113 F_ApiGetEncodingForFamily function R 8 R 20 R 115 F_ApiGetEncodingForFont function R 8 R 20 R 117 F_ApiGetIdQ function G 11 G 82 G 90 G 163 R 15 R 17 R 119 FDK Programmer s Reference amp Guide F_ApiGetImportDefaultParams function R 6 R 24 R 120 F_ApiGetInt function G 7 G 90 R 5 R 16 R 128 R 151 F_ApiGetIntByName function G 263 R 9 R 129 F_ApiGetInts function G 90 R 15 R 131 F_ApiGetMetric function G 90 R 16 R 132 F_ApiGetMetricByName function G 263 R 9 R 133 F_ApiGetMetrics function G 90 R 16 R 135 F_ApiGetNamedObject function G 24 G 88 G 163 G 164 G 270 R 3 R 15 R 35 R 37 R 75 R 136 F_ApiGetObjectType function G 84 R 24 R 138 F_ApiGetOpenDefaultParams function G 48 G 49 R 6 R 24 R 138 properties returned by G 49 R 138 F_ApiGetPoints function G 90 R 16 R 146 F_ApiGetPrinterState function R 148 F_ApiGetPropertyType functions G 7 G 89 G 94 G 213 G 263 R 151 F_ApiGetPropIndex function G 93 R 24 R 149 F_ApiGetProps function G 92 G 102 R 16 R 150 F_ApiGetPropVal function R 15 R 151 F_ApiGetSaveDefaultParams function G 61 R 6 R 24 R 152 F_ApiGetString function G 7 G 90 G 94 R 5 R 16 R 151 R 158 F_ApiGetStrings function G 90 R 16 R 99 R 115 R 160 F_ApiGetSupportedEncodin
464. n R 13 R 405 F_MetricNormalizeAngle function R 13 R 405 F_MetricSqrt function R 13 R 406 F_MetricSquare function R 13 R 406 F_MetricsT structure G 90 G 271 R 4 R 11 R 135 R 294 R 683 F_MetricToFloat function G 384 R 13 R 407 F_MifBegin function R 13 R 408 F_MifComment function R 13 R 408 F_MifDecimal function R 13 R 409 F_MifEndQ function R 13 R 410 F_MifGetIndent function R 13 R 411 F_MifIndent function R 13 R 411 F_MifIndentDec function R 13 R 412 F_MifIndentInc function R 14 R 412 F_MifInteger function R 14 R 413 F_MifNewLine Q function R 14 R 414 F_MifSetIndent function G 386 R 14 R 414 F_MifSetOutputChannel function G 386 R 14 R 415 F_MifSpace function R 14 R 416 F_MifTab Q function R 14 R 416 F_MifText function R 14 R 417 F_MifTextString function R 14 R 417 F_NewMacFilePath function R 8 R 421 F_ObjHandleT data type G 3 G 4 G 90 G 271 R 15 R 675 F_PathNameToFilePath function G 372 G 375 R 8 R 422 F_PathNameType function R 8 R 424 F_PointsT structure G 90 G 271 R 4 R 11 R 16 R 147 R 295 R 684 F_PointT structure R 295 R 683 F_Printf function G 369 R 10 R 424 index 40 F_Progress function R 426 F_PropIdentT structure G 272 R 684 F_PropValsT structure G 92 G 272 R 4 R 11 R 16 R 684 F_PropValT structure G 272 R 4 R 11 R 74 R 684 F_PtrEqual function R 12 R 427 F_ReadBytes function G 373 R 10 R 427
465. n a linked list Each graphic object has FP_PrevGraphicInFrame and FP_NextGraphicInFrame properties that specify the graphic objects before and after it in the list The order of this list corresponds to the back to front draw order The first object in the list is the first object the FrameMaker product draws and therefore appears in back of objects later in the list To move a graphic object forward or back in the draw order you change its FP_PrevGraphicInFrame or FP_NextGraphicInFrame property so that it specifies a different object You need to change only one of these properties The FrameMaker product automatically changes the other one for you It also automatically changes the FP_PrevGraphicInFrame or FP_NextGraphicInFrame properties of the object s siblings To move an object all the way to the back of the objects in a frame set its FP_PrevGraphicInFrame property to 0 To move an object all the way to the front set its FP_NextGraphicInFrame property to 0 For example the following code moves a selected graphic object forward one level 100 FDK Programmer s Guide Getting and Setting Properties 5 F_ObjHandleT docId objid sibId docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Get ID of one and only one selected object objId F_ApiGetId FV_SessionId docId FP_FirstSelectedGraphicInDoc if objId F_ApiGetId docId objId FP_NextSelectedGraphicInDoc F_ApiAlert Select a single object FF_ALERT_
466. n containing the paragraph e The paragraph s formatting information the same set of properties that a Paragraph Catalog format provides e The paragraph s tag e The IDs of sibling FO_Pgf objects e A flag indicating whether the paragraph has been successfully spell checked since the last change was made to it Each paragraph object also contains an F_TextItemsT structure which represents the text in the paragraph For more information about text and the F_TextItemsT structure see How the API represents text on page 312 Suppose you create the paragraph shown in Figure 14 14 Ue ee A Ba il 1 1 This paragraph is tagged with the Step tag FiGURE 14 14 A paragraph The API represents the paragraph with an FO_Pgf object The following table lists some of its properties Property Type Value FP_Name StringT Step FP_AutoNumString StringT lt n gt t FP_PgfIsAutoNum IntT True FP_PgfNumber StringT ds FA_LeftIndent MetricT 0 FP_InTextFrame F_ObjHandleT ID of the text frame the paragraph starts in FP_InTextObj F_ObjHandleT ID of the subcolumn FO_SubCol object the paragraph starts in A paragraph s FP_InTextObj property does not always specify the ID of a subcolumn If the paragraph appears in a table cell it specifies the ID of the FO_Cel1 object representing the cell If the paragraph appears in a footnote FP_InTextObj specifies the ID of the FO_Fn object representin
467. n creating different types of objects see Creating objects on page 143 FDK Programmer s Guide 11 re Introduction to the Frame API Compiling and running the example client The source code for the example client and a makefile or project file are provided in the samples myapi directory of your FDK installation For the location of the files see the FDK Platform Guide for your platform To compile the client use your platform s make or build utility To run the example client you must first register it as required by your platform s implementation of the API e Ifyou are working on a UNIX platform with US English as the user interface language and the pathname of your compiled client is usr fdk samples ch1 fa myapi you can register it by creating a text only file named fminit usenglish APIArea apiclients with the following lines in it lt APIclient lt Name myapi gt lt Directory usr fdk samples ch1 gt lt CommandLine FAPIDIR fa myapi gt gt When you start the FrameMaker product it reads this file and starts the fa myapi client e If you are working on a Macintosh computer copy or move the example client to the FrameMaker product s Modules folder e If you are working on a Windows platform and you have compiled your client into a DLL named myapi dll and copied or moved it to the FrameMaker fminit directory add the following line to the maker ini file myapi Standard Ch 1 Sample fminit mya
468. n documents is not in any particular order The FO_Doc object specified by FP_FirstOpenDoc does not necessarily represent the first document the user opened The API represents a book with an FO_Book object The API also maintains the FO_Book objects that represent the session s open books in a linked list The FO_Session property FP_FirstOpenBook specifies the ID of the first FO_Book object in the list The FO_Book property FP_NextOpenBookInSession specifies the next FO_Book object in the list As with the list of FO_Doc objects the linked list of FO_Book objects is not in any particular order How the API indicates which document or book is active FO_Session has two properties FP_ActiveDoc and FP_ActiveBook that specify the IDs of the objects that represent the active document and the active book Only one document or one book can be active at a time If there is no active document or book these properties are set to 0 Invisible documents and books can t be active Example Suppose you start FrameMaker and open the books and documents shown in Figure 13 2 The Frame API represents the session with the objects shown in Figure 13 3 FDK Programmer s Guide 275 Frame Session Architecture ij Adobe FrameMaker SGML 276 w C Sales Training Manual book 1Chapter fm 2Chapter fm a C Sales Training M anual2 book M E3 gt C Sales Training Manual2 book E D 1 Chapter fm 2Chapter fm FIGURE 13
469. n item in a client defined dialog box the FrameMaker product calls this function with dlgNum set to the dialog box s number itemNum set to the number of the item and modifiers set to bit flags specifying the modifier keys the user was holding down Lines 44 to 45 These lines check itemNum to determine whether the user closed the dialog box When the user closes the dialog box the FrameMaker product sets itemNum to FV_DlgClose If the dialog box was closed the client no longer needs the FA_Note_BackToUser notification and can turn it off Line 47 This line checks itemNum to determine whether the user clicked Apply If the user did anything but click Apply the client ignores it and returns Lines 49 to 58 These lines get the string in the text box and change the tag FP_Name property of the current paragraph to it Note that programmatically changing a paragraph tag does not change other properties of the paragraph Opening dialog resources To open a dialog resource call F_ApiOpenResource The syntax for F_ApiOpenResource is FDK Programmer s Guide 217 E Handling Custom Dialog Box Events 218 F_ObjHandleT F_ApiOpenResource IntT resourceType StringT resourceName This argument Means resourceType The type of resource to open To open a dialog resource specify FO_DialogResource resourceName The name of the resource to open On UNIX specify the name of the dialog resource file On the Maci
470. n point the client should create an anchored frame at the insertion point to filter the graphic into If there is a selected frame in the document the client should filter the graphic into the frame 4 Filter the graphic file into the FrameMaker product document The client can translate the graphic file into FrameMaker product graphic objects such as ellipses lines and rectangles FO_Ellipse FO_Line and FO_Rectangle objects For more information on creating FrameMaker product graphic objects see Creating graphic objects on page 146 If the graphic file contains a complex graphic the client can create a graphic inset Graphic insets provide graphic data in standard formats such as TIFF or FrameVector which the FrameMaker product can use to display and print a graphic For more information on creating graphic insets see Writing graphic inset editors on page 256 Note that a client does not need to be a graphic inset editor to create a graphic inset A filter client can also create a graphic inset Writing export filters The FrameMaker product invokes an export filter when the user chooses a particular format from the Format pop up menu of the Save As dialog box or when the user or another client saves a file with a specified suffix The FrameMaker product calls the client s F_ApiNotify callback with notification setto FA_Note_FilterOut docId set to the ID of the document to filter and sparm set to the pathname of
471. n the FrameMaker product ini file To setup a client to receive FA_Init_TakeControl initializations on the Macintosh set the flags field of the client s fdat resource to include ApiClientFlagCanTakeControl For more information on setting up clients to receive take control initializations see the FDK Platform Guide for your platform Document report initialization When the FrameMaker product is started it does not attempt to initialize API clients that are registered as document reports It initializes a document report only when the user chooses the document report from the Document Reports dialog box When this occurs the FrameMaker product calls the document report s F_ApiInitialize callback with initialization setto FA_Init_DocReport To appear in the Document Reports dialog box a document report must be registered with the FrameMaker product as a document report For information on registering document reports see the FDK Platform Guide for your platform Filter initialization If your client is registered as a filter you should not define an F_ApilInitialize function for it When the user opens or saves a file and selects your filter the FrameMaker product notifies your client by calling your client s F_ApiNotify callback For more information on F_ApiNotify and notification see Responding to user initiated events or FrameMaker product operations on page 34 To receive notification your filte
472. n the list The menu or menu item property FP_NextMenuItemInSession specifies the next object in the list The list is not in any particular order The API also maintains a linked list of all the commands in a session The FO_Session property FP_FirstCommandInSession specifies the ID of the first command in the list The FO_Command property FP_NextCommandiInSession specifies the next command in the list Like the list of menus and menu items this list is not in any particular order For a complete listing of all the available menus in the FrameMaker product see Getting the IDs of FrameMaker product menus and menu bars on page 24 Getting and setting menu and menu item properties A single menu or command can have multiple instances in a FrameMaker product session each FrameMaker product menu can contain an instance For example on UNIX platforms the Cut command appears as a menu item on both the Edit menu and the document window pop up menu The API uses only one object to represent all instances of a menu command or menu item separator For example it uses only one FO_Command object to represent both instances of the Cut command on UNIX platforms 162 FDK Programmer s Guide Manipulating Commands and Menus with the API 9 Most properties of an FO_Menu FO_Command or FO_MenultemSeparator object apply to all instances of the object For example if you use the following call to set the label of the Cut command F_ObjHand
473. nBook notification constant R 228 FA_Note_PostOpenBookMIF notification constant R 228 FA_Note_PostOpenBookt notification constant R 235 FA_Note_PostOpenDoc notification constant G 35 R 227 FA_Note_PostOpenMIF notification constant R 227 FA_Note_PostOpenSGML notification constant R 227 FA_Note_PostOpenXML notification constant R 227 FA_Note_PostPrint notification constant R 231 FA_Note_PostQuitBook notification constant R 229 FA_Note_PostQuitDoc notification constant G 35 R 229 FA_Note_PostQuitSession notification constant R 230 FA_Note_PostRevertBook notification constant R 230 FA_Note_PostRevertDoc notification constant R 229 FA_Note_PostSaveAsPDFDialog notification constant R 229 FA_Note_PostSaveAsPdfDialog notification constant R 269 FA_Note_PostSaveBook notification constant R 229 FA_Note_PostSaveBookMIF notification constant R 229 FA_Note_PostSaveDoc notification constant G 35 R 228 FA_Note_PostSaveMIF notification constant R 228 FA_Note_PostSaveSGML notification constant R 228 FA_Note_PostSaveXML notification constant R 228 index 42 FA_Note_PostSetAttrValue notification constant R 232 R 235 FA_Note_PostWrapElement notification constant R 232 R 235 FA_Note_PreAutoSaveDoc notification constant R 229 FA_Note_PreBookComponentOpen notification constant R 228 FA_Note_PreChangeElement notification constant R 231 FA_Note_PreDistill notification constant R 229 R 235 FA_Note_PreDragElement notificati
474. nId docId FP_SelectedTbl Add the column F_ApiAddCols docId tblId 0 FV_Right 1 Get the ID for row 1 then traverse to the ID for row 2 rowlld F_ApiGetId docId tblId FP_FirstRowInTbl row2Id F_ApiGetId docId rowlId FP_NextRowInTbl Add the rows if row2Id F_ApiAddRows docId row2Id FV_Below 2 FDK Programmer s Guide 157 az Creating and Deleting API Objects Creating commands menus and menu item separators For information on creating and deleting commands menus and menu item separators see Chapter 9 Manipulating Commands and Menus with the API Deleting objects To delete objects use F_ApiDelete The syntax for F_ApiDelete is IntT F_ApiDelete F_ObjHandleT doclId F_ObjHandleT objId This argument Means docId The ID of the document from which to delete the object objid The ID of the object to delete If F_ApiDelete is successful it returns FE_Success Otherwise it returns an error code There are a number of objects that you can t delete For example you can t delete an FO_Doc object oran FO_VarFmt object that represents a system variable format For the list of these objects see F_ApiDelete on page 83 of the FDK Programmer s Reference When you delete an object the API automatically deletes all of that object s child objects For example if you delete a frame the API deletes all the objects in the frame If yo
475. nce amp Guide Index Reserved Names FE_BadObjld error code R 694 FE_BadOperation error code R 694 FE_BadPageDelete error code R 694 FE_BadParameter error code R 694 FE_BadPropNum error code R 694 FE_BadPropType error code R 694 FE_BadRange error code R 694 FE_BadSaveFileName error code R 694 FE_BadSelectionForOperation error code R 694 FE_BadShortcut error code R 694 FE_BookUnStructured error code R 694 FE_Busy error code R 694 FE_Canceled error code R 694 FE_CanceledByClient error code R 695 FE_CantSmooth error code R 695 FE_CantUpdateMacEdition error code R 695 FE_CircularReference error code R 695 FE_CompareTypes error code R 695 FE_DocModified error code R 695 FE_DupName error code R 695 FE_EmptyTextObject error code R 695 FE_FailedState error code R 695 FE_FileClosedByClient error code R 695 FE_FilterFailed error code R 695 FE_GenRuleAmbiguous error code R 695 FE_GenRuleConnectorExpected error code R 695 FE_GenRuleItemExpected error code R 695 FE_GenRuleLeftBracketExpected error code R 695 FE_GenRuleMixedConnectors error code R 695 FE_GenRuleRightBracketExpected error code R 695 FE_GenRuleSyntaxError error code R 695 FE_GroupSelect error code R 695 FE_HiddenPage error code R 695 FE_InvalidString error code R 695 FE_InvAttribute error code R 696 FE_InvAttributeDef error code R 696 FE_MissingFile error code R 696 FE_NameNotFound error code R 696 FE_NoColorFamily error code R 696 FE_NoSuchFlow error code R 696 FE_NotApiComma
476. ncoding data sets up structures to represent each internal encoding supported by the current release of the FrameMaker product This is true even if the current session doesn t support the languages those encodings represent For example you could process a string of Korean text with the FDE even if the current session of FrameMaker would not be able to display it correctly The typical way to use this function is to initialize the FDE and then get the encoding name used for the current FrameMaker session Then you pass that encoding name to F_FdeInitFontEncs so your client will use the same encoding for its dialog boxes The syntax for F_FdeInitFontEncs is FontEncldT F_FdeInitFontEncs ConStringT fontEncName This argument Means fontEncName The name of the font encoding to use for your client s dialog boxes Possible values for font EncName are Value Means FrameRoman Roman text JISX0208 ShiftJIs Japanese text BIG5 Traditional Chinese text GB2312 80 EUC Simplified Chinese text KSC5601 1992 Korean text The returned FontEnc1IdtT is the ID of the font encoding you specified for your dialog boxes 134 FDK Programmer s Guide Manipulating Asian Text The following code initializes the FDE and ensures the dialog box encoding is one the client can support If the dialog box encoding for the current session is Japanese or Simplified Chinese it passes that encoding the F_FdeInitFontEncs Othe
477. nction look it up in Chapter 2 FDK Function Reference in the FDK Programmer s Reference String library The string library provides functions for allocating and manipulating strings For example F_StrNew allocates a string F_StrCmp compares two strings and F_StrAlphaToInt converts an alphanumeric string to an integer The FDE uses the StringT type for strings StringT is an array of UCharT When you specify a string size in an FDE string function you must include the terminating 0 in the size The string library provides functions for allocating manipulating and freeing strings IMPORTANT Use F_Free or F_ApiDeallocateString tofree StringT strings See F_Free on page 386 of the FDK Programmer s Reference and F_ApiDeallocateStructureType on page 74 of the FDK Programmer s Reference Most FDE string functions have the prefix F_Str To use FDE string functions you must include fdetypes h and fstrings h in your program and call F_FdeInit FDK Programmer s Guide 381 18 FDE Utility Libraries 382 The string list library The string list library provides routines for creating a string list and manipulating the strings in it For example F_StrListNew allocates a string list F_StrListInsert inserts a string into a list and F_StrListSort sorts a string list String lists are typed StringListT All the functions in the string list library are prefixed with F_StrList To use
478. nction for G 256 R 15 external G 230 G 260 to G 261 facets of G 257 to G 259 filters for G 241 to G 250 R 600 to R 602 functions applicable to R 9 internal G 230 G 259 to G 260 live links to graphic inset editors G 256 modifying G 261 properties of G 247 to G 250 G 256 R 599 to R 602 getting setting G 263 to responding to user clicking of function for R 9 responding to user double clicking of G 262 to G 263 See also graphics graphic objects G 280 G 293 to G 297 R 592 to R 608 API representation of G 280 G 294 to G 297 API representation of selections of G 296 changing size location within a frame G 99 creating G 146 to G 148 function for R 14 R 216 to R 218 default properties of G 147 FDK Programmer s Reference amp Guide Index Subjects a defined G 294 G 390 drawing G 293 to G 294 in frames G 293 getting the IDs of selected G 87 function for R 17 R 119 to R 120 grouping G 293 G 296 manipulating G 87 moving in the draw order G 99 to G 102 moving to different frames or pages G 101 as organized in documents G 84 G 295 to G 296 as organized in frames G 295 to G 296 illustrated G 295 on pages G 293 properties of G 102 G 294 to G 295 R 592 to R 608 common R 592 to R 595 copying between graphic objects G 102 getting and setting G 99 to G 102 selecting G 296 traversing lists of G 84 See also graphic insets groups of graphic objects objects graphics G 293 displaying imported G 258 importing G 230 to G
479. nd so treat as a single char for proper scanning y i Getting the encoding for a text item The function F_ApiGetText returns a F_TextItemsT structure which is a list of text items that makes up a range of document text Note that among other things a single text item can represent a string of characters with common text properties For a change in character encoding to occur there must be a corresponding change in some text property such as a new font family or font variation This means that any text item that is a string must be a string of a given encoding For more information about text items see Text on page 311 For a given text item you can use the offset to determine a text location corresponding to that text item You can then use F_ApiGetTextPropVal to get the font at that location Given the font you can use F_ApiGetEncodingForFont to determine the encoding at that location You now know the encoding for a given text item As you scan the items in a F_Text ItemsT structure you can flag changes to the text encoding Until you see a change in text encoding you can assume any string text items are of the current encoding Keep in mind that a change of text encoding necessarily occurs at a change in character properties This is indicated in the F_Text ItemT as a data type of FTI_CharPropsChange The data for an FTI_CharPropsChange is a flag to indicate the type of change If the flag indicates FTF_ENCOD
480. nd error code R 696 FE_NotBodyPage error code R 696 FE_NotBookComponent error code R 696 FE_NotCommand error code R 696 FE_NotFound error code R 696 FE_NotFrame error code R 696 FE_NotGraphic error code R 696 index 43 os Index Reserved Names FE_NotGroup error code R 696 FE_NotInMenu error code R 696 FE_NotMenu error code R 696 FE_NotPef error code R 696 FE_NotPgfOrFlow error code R 696 FE_NotTextFrame error code R 696 FE_NotTextObject error code R 696 FE_OffsetNotFound error code R 697 FE_OutOfRange error code R 697 FE_PageFrame error code R 697 FE_PropNotSet error code R 697 FE_ReadOnly error code R 697 FE_ReservedColor error code R 697 FE_SomeUnresolved error code R 697 FE_Success error code R 697 FE_SystemError error code R 697 FE_TableInLockedTi error code R 697 FE_TintedColor error code R 697 FE_Transport error code R 697 FE_TypeUnNamed error code R 697 FE_ViewOnly error code R 697 FE_WantsCustom error code R 697 FE_WantsLandscape error code R 697 FE_WantsPortrait error code R 697 FE_WithinFrame error code R 697 FE_WrongProduct error code R 697 FF_ FF_ALERT_CANCEL_DEFAULT flag F_ApiAlert G 18 R 43 FF_ALERT_CONTINUE_NOTE flag F_ApiAlert G 18 R 43 FF_ALERT_CONTINUE_WARN flag F_ApiAlert Q G 11 G 18 R 43 FF_ALERT_NO_DEFAULT flag F_ApiAlert G 18 R 43 FF_ALERT_OK_DEFAULT flag F_ApiAlert G 18 R 43 FF_ALERT_YES_DEFAULT flag F_ApiAlert G 18 R 43 FF_CLOSE_MODIFIED flag G 67 FF_CMP_CHANGE
481. ndling G 45 index 20 metric MetricT properties function for getting R 16 R 132 to R 133 function for setting R 16 R 291 to R 292 metric facets function for querying R 9 R 133 to R 134 function for setting R 9 R 292 to R 293 metric functions G 366 G 381 G 384 R 13 R 401 to R 407 R 675 to R 677 comparing metric numbers R 401 computing square roots R 406 computing squares R 406 constraining angles R 401 constructing metric numbers from fractions R 404 converting metric numbers to real numbers R 407 converting real numbers to metric numbers R 403 dividing metric numbers R 402 multiplying metric numbers R 403 R 405 normalizing angles R 405 metric library FDE See metric functions metric prompt dialog boxes displaying G 18 to G 21 R 258 function for R 5 R 258 to R 260 illustrated G 21 R 260 metric values See MetricT values metrics F_MetricsT properties function for getting R 16 R 135 to R 136 function for setting R 16 R 293 to R 295 MetricT facets See metric facets MetricT functions See metric functions MetricT values G 271 G 384 R 675 defining constants in R 675 to R 677 functions for G 366 G 384 R 675 to R 677 converting real numbers to G 384 converting to real numbers G 384 for linear measurements table R 676 for percentages and angles R 676 prompting users for G 18 to G 21 R 258 to R 260 function for R 5 R 258 to R 260 specifying in code R 675 to R 677 structure for G 271 R 683 See also metric M
482. ne CANCEL BUTTON 2 F_ObjHandleT dlgId Open the resource and display the dialog box dlgId F_ApiOpenResource FO_DialogResource singleInteract FDK Programmer s Guide 223 E Handling Custom Dialog Box Events 224 Determine what the user action was and respond to it if F_ApiModalDialog 0 dlgId if F_ApiGetInt dlgId F_ApiDialogItemId dlgId APPLY_BUTTON FP_State True F_Printf NULL Apply was clicked n else if F_ApiGetInt dlgId F_ApiDialogItemId dlgId CANCEL BUTTON FP_State True F_Printf NULL Cancel was clicked n else F_Printf NULL Dialog closed nothing clicked n else User requested help code to provide help goes here Handling user actions in multiple interaction dialog boxes To implement a dialog box as a multiple interaction modal dialog box follow these steps 1 Display the dialog box by calling F_ApiModalDialog with dlgNum set toa nonzero value When there is a user action in the dialog box the API calls your client s F_ApiDialogEvent function passing it the number you specified for dlgNum Your client s F_ApiDialogEvent function can handle user actions in the modal dialog box the same way it handles user actions in a modeless dialog box 2 Call F_ApiReturnValue FR_ModalStayUp in your client s F_ApiDialogEvent callback If you want to allow the user to click a button without
483. ng Your Client s User Interface a more information on specifying keyboard shortcuts see the sections of your user documentation that discuss the FrameMaker product s configurable user interface Example The following code defines a command with the shortcut Esc N Land adds it to the Utilities menu define NUMBER_LINES 1 F_ObjHandleT utilsMenuld cmdId utilsMenuld F_ApiGetNamedObject FV_SessionId FO_Menu UtilitiesMenu cmdId F_ApiDefineAndAddCommand NUMBER_LINES utilsMenuld NumberLines Number lines NL Defining and adding menus To define a menu and add it to a menu bar or another menu use F_ApiDefineAndAddMenu The syntax for F_ApiDefineAndAddMenu is F_ObjHandleT F_ApiDefineAndAddMenu F_ObjHandleT toMenuld StringT name StringT label This argument Means toMenuld The ID of the menu or menu bar to which to add the new menu name A unique name that identifies the new menu label The title of the new menu as it appears on the menu or menu bar F_ApiDefineAndAddMenu returns the ID of the menu it creates If you specify a menu bar ID for toMenuId the FrameMaker product implements the new menu as a pull down menu If you specify a pull down or a pop up menu ID for toMenuld the FrameMaker product implements the new menu as a pull right menu IMPORTANT Your menu appears only on the menu bar you specify For example if you add a menu only
484. ng a client 2 2 a 6 A simple example 2 aa a 9 Chapter 2 API Client Initialization 2 2 18 Responding to the FrameMaker product s initialization call oa aooaa a 13 Initialization types ooa oaa a 14 Disabling the APL s rocna deno eo he GH a A e A ee A eS 16 Chapter 3 Creating Your Client s User Interface 17 Using API dialog boxes to prompt the user forinput 17 Using commands menu items and menus in your client o a aa aa 24 Replacing FrameMaker product menus and commands aooaa a 30 Allowing users to configure your client s interface o oo ooa 00000 30 Using hypertext commands in your client s user interface 08 31 FDK Programmer s Guide Chapter 4 Chapter Chapter Responding to user initiated events or FrameMaker product operations Implementing quick keys aoaaa ee Freeing system resources by bailingout Executing Commands with API Functions Handling errors ss ss m e so aana a a ae aa E E A Handling messages and warnings Opening documents and books Creating documents Printing documents and books a aoaaa a a a Saving documents and books Closing documents and books ooo Quitting a Frame session ooo ee Comparing documents and books Updating and generating documents and books Simulating user input 2 ea e ee Straddling table cells Executing
485. ng the FS_DontNotifyAPIClients property of the Open or Save script to True For more information on properties in the Open and Save scripts see F_ApiGetOpenDefaultParams on page 138 and F_ApiGetSaveDefaultParams on page 152 of the FDK Programmer s Reference FDK Programmer s Guide Creating Your Client s User Interface a After the document has been saved save another copy if notification FA_Note_PostSaveDoc F_ApiSimpleSave docId mybackup doc False In the example above F_ApiNotify which responds to a Save notification uses F_ApiSimpleSave to execute a Save operation itself This does not result in infinite recursion because the FrameMaker product does not notify the client of the Save operation that it executes itself Handling notification for Open operations The Open operation is more complex than most other operations FrameMaker product does the following when it opens a file 1 Determines whether the file is filterable If the file is filterable the FrameMaker product issues the FA_Note_FilterIn notification to the appropriate filter and abandons the Open operation It is up to the filter to finish opening the file No other client receives any notification If the file is not filterable the FrameMaker product continues with the Open operation 2 Issues an FA_Note_PreFileType notification to all clients that have requested it This allows clients to uncompress a file
486. nge the graphic objects that constitute the background the changes appear when you view or print the body pages associated with the master page Reference pages Reference pages can contain named graphic frames Named graphic frames provide decoration such as a thick line ruling for paragraphs in the body pages The Paragraph Designer provides two settings Frame Above and Frame Below that allow you to specify the named graphic frames you want to appear above or below a paragraph Reference pages can also contain special flows that control the appearance of generated documents For example a Table of Contents document normally has a flow named TOC on one of its reference pages How the API represents pages FrameMaker represents body pages master pages and reference pages with FO_BodyPage FO_MasterPage and FO_RefPage objects respectively In addition to these pages a document can also have a hidden page which stores hidden conditional text The user cannot see or directly modify hidden pages FrameMaker represents each hidden page with an FO_HiddenPage object FDK Programmer s Guide 289 14 Frame Document Architecture 290 Page objects have a number of common properties These properties specify the following characteristics of a page e The dimensions of the page e Its type body master reference or hidden e Its numbering e IDs of the objects that represent its page frame and its sibling pages A page objec
487. nitialization Code for initialization type 9 F_ObjHandleT menuBarId menuld GOANOaARWND gt 11 Get ID of the FrameMaker product menu bar 12 menuBariId F_ApiGetNamedObject FV_SessionId FO Menu 13 MakerMainMenu 14 Add menu named API to the FrameMaker product menu bar 15 menuId F_ApiDefineAndAddMenu menuBarId APIMenu API 17 Add items to API menu 18 F_ApiDefineAndAddCommand CloseDoc menuld CloseDocCmd 19 Close ICD 20 F_ApiDefineAndAddCommand SetFill menulId SetFillCmd 21 Set Fill ESE 22 F_ApiDefineAndAddCommand AddPage menulId AddPageCmd 23 Add Page AP 24 25 26 VoidT F_ApiCommand command 27 IntT command 28 29 F_ObjHandleT pgId objid docId 31 Get the ID of the active document 32 docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc 33 if docId return Return if there is no active document FDK Programmer s Guide 9 re Introduction to the Frame API 35 switch command 36 37 case CloseDoc Close document even if it s changed 38 F_ApiClose docId FF_CLOSE_MODIFIED 39 break 40 41 case SetFill Set fill pattern to black 42 Get ID of selected object 43 objId F_ApiGetId FV_SessionId docId 44 FP_FirstSelectedGraphicInDoc 45 46 If an object is selected set its fill 47 if objId F_
488. not indicate what they have changed to The API provides a function named F_ApiGetTextProps which allows you to retrieve the text properties for individual characters in text You cannot retrieve the text properties for a range or selection of text because they may be different for individual characters within the selection You can however set the text properties for a range of text For examples of how to get and set text properties see Getting and setting text formatting on page 123 Suppose you retrieve the text properties at the insertion point shown in Figure 14 20 5 A Tale of Thro Cities Fow A Body f booktitle ES _ _ FIGURE 14 20 Text containing insertion point The following are some of the properties of the text at the insertion point Property Type Value FP_CharTag StringT booktitle FP_FontFamily IntT Index of Times font for more information on font name indexes see How the API indicates which fonts are available in a session on page 276 FP_FontWeight IntT Index of Bold font weight FP_FontAngle IntT Index of Regular font angle FP_InCond F_IntsT NULL If the conditions Comment and MyComment are applied to the text location the FP_InCond property specifies an F_IntsT structure with the following values len 2 val Comment_ID MyComment_ID where Comment_ID and MyComment_IDare the IDs of the FO_CondFmt objects that represent the Comment and MyComment condition formats
489. nsets see Writing graphic inset editors on page 256 IMPORTANT The outfile must be in a format that FrameMaker can read natively For a document filter the file to MIF or a FrameMaker document file For a graphic filter the file to MIF FrameVector TIFF or any other graphic format FrameMaker can read natively You must specify the outfile format when you register the filter and your filter must create valid data for that format 3 Set the return value to 0 zero Call F_ApiReturnValue 0 to indicate success Specifying any non zero value indicates failure IMPORTANT File to file filters differ from other filters in the return value that indicates success If you copy standardfilter code to create a file to file filter be sure to change the return values so they indicate success or failure for a file to file filter Note that file to file filters can use F_Progress to report their progress to the FrameMaker product On Windows and Macintosh platforms this function displays a progress indicator a thermometer and the user can cancel the filter by clicking the indicator s Cancel button On Unix this function doesn t display anything but calling this function provides points in the filter process at which the user can press Control C to cancel If the user cancels F_Progress returns a non zero value FDK Programmer s Guide Using Imported Files and Insets 12 o The following code shows how to get values out
490. nt You can set FP_TintPercent to a metric value from 0 00 to 100 0 representing 0 to 100 or to FV_COLOR_NOT_TINTED If you set it to FV_COLOR_NOT_TINTED then FP_TintBaseColor automatically changes to FV_NO_BASE_COLOR When you set a percentage value for FP_TintPercent if FP_TintBaseColor was set to FV_NO_BASE_COLOR then it automatically changes to the object ID for the color Black FP_TintBaseColor Every tint has a base color Note that you cannot use a tint as a base color for some other tint If you set the base color to FV_NO_BASE_COLOR then the FP_TintPercent for the current FO_Color object is set to FV_COLOR_NOT_TINTED When you set a valid color for FP_TintBaseColor if FP_TintPercent was initially set to FV_COLOR_NOT_TINTED then it will auatomatically be set to the metric value of 100 0 for 100 Be sure to change the tint percent if you want less than 100 Reserved colors FrameMaker has eight reserved colors FO_Color objects have a read only property named FP_ReservedColor to specify whether the object represents a reserved color or not Unless the color is one of the eight reserved colors FP_ReservedColor will always be FV_COLOR_NOT_RESERVED FP_ReservedColor can have one of the following values FV_COLOR_NOT_RESERVED FV_COLOR_CYAN FV_COLOR_MAGENTA FV_COLOR_YELLOW FV_COLOR_BLAC FV_COLOR_WHIT FV_COLOR_RED FV_COLOR_GREEN FV_COLOR_BLUE ALN FDK Programmer s
491. nt on DOS platforms G 378 to G 379 on Macintosh computers G 378 to G 379 on UNIX platforms G 378 to G 379 using handles and pointers G 378 to G 379 R 370 R 372 menu bars adding commands to function for R 75 to R 77 adding menus to G 13 G 27 R 79 function for R 3 R 37 to R 39 R 82 arranging menus on G 166 to G 170 R 3 determining if a menu is on function for R 203 to R 204 getting IDs of G 24 to G 26 G 27 strings specifying tables G 25 view only to G 162 menu customization file loading function for R 3 R 200 menu item separators adding moving and deleting G 170 creating G 158 creating separator objects G 170 manipulating G 169 to G 170 properties of R 523 R 528 menu items adding to menus G 26 to G 28 R 35 function for R 35 arranging G 166 to G 170 R 3 check marks G 173 in the client user interface G 24 to G 31 context sensitive G 173 to G 175 context sensitive help for G 175 to G 176 creating menu item separators G 158 determining if on menu function for R 203 to R 204 expandomatic G 172 to G 173 getting labels G 170 to G 172 getting properties of G 162 linked lists of G 162 manipulating menu item separators G 169 to G 170 properties of R 523 to R 528 removing G 167 function for R 3 reordering G 168 to G 169 responding to user choices of G 29 function for R 1 R 64 setting properties of G 162 shift G 174 to G 175 index 19 oe Index Subjects menu propertie
492. nt s pages To get objects in order you must traverse the ordered lists that the API maintains There are ordered lists of the graphic objects in a frame the text columns within a flow and many other objects These lists can be deeply nested for example when a frame contains a frame that contains some graphic objects There are a variety of object properties you can query to get to ordered lists For example to get to the list of graphic objects in a frame you can query the frame s FP_FirstGraphicInFrame or FP_LastGraphicInFrame properties If you already FDK Programmer s Guide 85 es Getting and Setting Properties 86 have one of the graphic object s IDs you can query its FP_PrevGraphicInFrame and FP_NextGraphicInFrame properties to get to the objects behind it and in front of it in the list The order of the list corresponds to the back to front order of the graphics in the frame For information on the linked lists that a particular object is included in see the section that discusses that object in Chapter 14 Frame Document Architecture Although there are ordered lists of the paragraphs within each of a document s flows there is no ordered list of flows You can get the paragraphs only in the order in which they occur within an individual flow To get the paragraphs within an individual flow in order you navigate from the flow to the first text frame in the flow to the first paragraph in that text frame For exampl
493. nt num FP_InsetEditor num FP_FrameParent num 0 name NULL name NULL name FrameImage propVal propVal propVal valType FT_String valType FT_Id valType FT_UBytes u u u sval myeditor ival ID of frame NULL containing the inset FIGURE 12 2 The property list for a bitmap FO_Inset object The u union for the FrameImage facet is NULL The F_PropValT structure for F_UBytesT facets does not provide the facet data It only serves as a placeholder indicating that a facet exists To get and set the data for F_UBytesT facets you must follow special procedures which are described in Getting and setting facets on page 263 Setting up your client to create and modify graphic insets To set up your client to create and modify graphic insets do the following 1 Register your client as an API client You must register your client and all the facets it uses For information on registering API clients see the FDK Platform Guide for your platform 2 Addan F_ApiMessage callback to your client When the user clicks your client in the Inset Editors scroll list or double clicks a graphic inset the FrameMaker product calls F_ApiMessage from your client Define F_ApiMessage as follows VoidT F_ApiMessage StringT message Not used for insets F_ObjHandleT docId ID of document containing the inset F_ObjHandleT objId The ID of the inset or 0 FDK Progr
494. nt Means docId The ID of the document book or session containing the object If the object is a session specify 0 objid The ID of the object whose property you want to query propNum The property to query for example FP_FnNum The syntax for F_ApiSetString is VoidT F_ApiSetString F_ObjHandleT doclId F_ObjHandleT objid IntT propNum StringT setVal This argument Means docId The ID of the document book or session containing the object objid The ID of the object whose property you want to set propNum The property to set for example FP_PrintFileName setVal The string to which to set the property You can look up the exact syntax of an F_ApiGetPropertyType or F_ApiSetPropertyType function in Chapter 2 FDK Function Reference in the FDK Programmer s Reference Suppose you want your client to change some characteristics of the Heading paragraph format To find out how the API represents paragraph formats look up paragraph formats in Part II Frame Product Architecture For a complete list of paragraph format properties see Object Reference on page 495 of the FDK Programmer s Reference The following code demonstrates how to change different types of paragraph format properties define in MetricT 72 65536 A Frame metric inch F_ObjHandleT docId pgfFmtId Get the ID of Headingl format in active document docId F_ApiGetId 0 FV_SessionId FP_ActiveD
495. nt page The current page is the page that appears on the screen If more than one page appears on the screen it is the page that appears with a dark border around it Suppose you create a double sided document that has three body pages two master pages Left and Right and a single reference page as shown in Figure 14 4 The current page is the Right master page 1 Right 1 Body Master Reference Page FIGURE 14 4 Document with body master and reference pages FrameMaker organizes the objects as shown in Figure 14 5 FDK Programmer s Guide 291 14 Frame Document Architecture FP_FirstBodyPagelnDoc FO_BodyPage Body page 1 ts Z a o o D D iy oO a jae a a We WL FO_BodyPage Body page 2 a zZz o oO o D D iv a a u WL FP_LastBodyPagelnDoc FO_BodyPage Body page 3 FO_Doc FP_FirstRefPagelnDoc FO_RefPage Reference page Y FP_LastRefPagelnDoc FP_CurrentPage gt FO_MasterPage Right master page FP_FirstMasterPagelnDoc geNext gePrev FP_Pa FP_Pa y FO_MasterPage Left master page FP_LastMasterPagelnDoc FIGURE 14 5 Example document and page objects How the API represents hidden pages If the user chooses to hide cond
496. nt the filter client created into the existing document Closes the document the filter client created Creates a text inset in the existing document and then copies the specified flow of the document the filter client created into the text inset Closes the document the filter client created Sets the FP_TiFile property of the inset to the pathname of the filterable file Returns the ID of the inset created by the filter client to the other client s F_ApilImport call Sets the FP_ImportHint property of the text inset to a string specifying the filter client This string is based on the format ID you specified when you registered your client For more information on format IDs see Specifying format IDs and filetype hint strings on page 247 For the complete syntax of import hint strings see Syntax of FP_ImportHint strings on page 600 of the FDK Programmer s Reference Replaces the contents of the inset with the specified flow of the document the filter client created Closes the document the filter client created For a simple example of a text import filter see A simple FDE filter on page 370 Writing graphic import filters The FrameMaker product invokes a graphic import filter in the following situations e When the user attempts to open a graphic file with a format that the client filters e When the user attempts to import a graphic file with a format that the client filters e When another cli
497. ntifiers UIDs Each object generally has either an FP_Name property specifying a unique object name or an FP_Unique property specifying a UID Unique object names There are many types of objects that you can assign unique names to in the user interface These objects which are called named objects include FO_Book e FO_CharFmt e FO Color e FO _CombinedFontDefn FO_Command FO_CondFmt FO_ElementDef FO_FmtChangeList FO_MarkerType FO_MasterPage FDK Programmer s Guide 269 13 Frame Session Architecture 270 e FO Menu FO MenuItemSeparator e FO PgfFmt e FO_RefPage e FO RulingFmt e FO_TiFlow e FO TiText e FO_Tbh1Fmt e FO_UnanchoredFrame named frames on reference pages only e FO VarFmt e FO XRefFmt The API provides a function named F_ApiGetNamedObject which gets the ID of a named object with a specified name IMPORTANT A document can contain several flows with the same name For example a document can contain several A flows To get the ID of a specific flow first get the ID of a text frame in that flow for example the text frame for the current text location and then query the text frame s FP_Flow property Unique persistent identifiers UIDs The API and MIF identify unnamed objects with UIDs An unnamed object is an object that doesn t have a unique name For example FO_Pgf objects are unnamed UIDs are unique within documents An object s UID remains
498. ntosh and on Windows platforms specify the resource name F_ApiOpenResource looks for the specified dialog resource first in your client s resources On UNIX platforms it looks in the directory specified by the client s lt Directory gt statement inthe apiclients file On the Macintosh it looks in the client s resource fork On Windows platforms it looks in the client DLL IMPORTANT Your client s dialog resources must be correctly set up for the API to open them For information on setting up dialog resources see the FDK Platform Guide for your platform If F_ApiOpenResource doesn t find the dialog resource in your client s resources it looks in the FrameMaker product s resources If it can t find the dialog resource in either the client or the FrameMaker product resources it returns 0 If it finds and successfully opens the dialog resource it returns the dialog resource s ID IMPORTANT To manipulate a dialog box outside of the function in which you opened it you must save its ID to a global variable For example the following code opens a dialog box named mydlg F_ObjHandleT dlgId Global declaration dlgId F_ApiOpenResource FO_DialogResource mydlg Initializing items in a dialog box Before you display a dialog box you can initialize the state or value of the items it contains The dialog resource provides defaults for most items However it does not provide defaults for FO_DlgP
499. nts To receive notification for a particular event your client must request it by calling F_ApiNotification The syntax for F_ApiNotification is 34 FDK Programmer s Guide Creating Your Client s User Interface a IntT F_ApiNotification IntT notification IntT state This argument Means notification A constant that specifies the notification point See the table below for a list of the constants state Specifies whether to turn notification for the notification point on or off Specify True to request notification or False to turn notification off For most events there are several notification points or stages in the event when the FrameMaker product can notify your client For example when the FrameMaker product saves a file there are two notification points one immediately before and one immediately after it saves the file The following table lists the notification points and constants the FrameMaker product passes to F_ApiNotify for some events Event or operation Notification points Notification constants Frame binary Before checking the type of the FA_Note_PreFileType document opened file to be opened After checking the type of the FA_Note_PostFileType file to be opened Before opening the file FA_Note_PreOpenDoc After opening the file FA_Note_PostOpenDoc Filterable document Before checking the type of the FA_Note_FilterIn opened file to be opened Document saved in Before saving the docum
500. o get an object s ID you start traversing at the object that represents the session the FO_Session object because it is the only object whose ID FV_SessionId you know from the start From the FO_Session object you can get the IDs of the active and open documents and books in the session FO_Session objects have properties named FP_ActiveDoc and FP_ActiveBook that specify the IDs of the active document or book A document or a book is active if it has input focus FO_Session objects also have properties named FP_FirstOpenDoc and FP_FirstOpenBook that specify the first document and the first book in the linked lists of open documents and books in a session FO_Doc objects have a property named FP_NextOpenDocInSession that specifies the ID of the next FO_Doc object in the list of open documents FO_Book objects have a property named FP_NextOpenBookInSession that specifies the ID of the next FO_Book object in the list of open books If an FO_Doc or an FO_Book object is the last object in the list its FP_NextOpenDocInSession or FP_NextOpenBookInSession property is set to 0 Fora diagram of how the API represents the documents and books in a session see Figure 13 2 on page 276 Suppose you want to display the IDs of the active document and all the open documents in a session You can use the following code to do this include futils h F_ObjHandleT docId UCharT msg 256 Get the ID of the active document and display it doc
501. o parent FV_SessionId The session s ID FP_AutoSaveSeconds The property to set 60 The value to set it to The following sections describe steps 2 and 3 in greater detail Getting the IDs of the objects you want to change Every object in a session has an ID To get or set the properties of a particular object you must specify its ID In Frame book and document architecture objects are organized in linked lists an object has properties that specify the IDs of other objects which have properties that specify the IDs of other objects and so on To get the IDs of specific objects you traverse the linked lists by querying these properties For diagrams and descriptions of the linked lists in Frame architecture see Part II Frame Product Architecture To query a property that specifies an object ID use F_ApiGetId which is defined as F_ObjHandleT F_ApiGetId F_ObjHandleT docId F_ObjHandleT objId IntT propNum This argument Means docId The ID of the document book or session containing the object whose property you want to query objid The ID of the object whose property you want to query propNum The property to query Specify one of the API defined constants such as FP_ActiveDoc FDK Programmer s Guide Getting and Setting Properties 5 F_ApiGetId returns the ID specified by the property If the property doesn t specify an ID or an error occurs F_ApiGetId returns 0 T
502. oard shortcut Esc d f The text box becomes the stuff item of the image pop up menu FrameMaker deselects the text box The image pop up menu remains selected and the status bar displays the following information X 18 ImagePopup 17 The number in parentheses indicates that item 17 is the stuff item of item 18 You can also specify the stuff item by choosing Object Properties from the Graphics menu and typing the number of the related item in the Stuff Item text box Saving a DRE file To save the DRE file choose the Save command from the File menu To save it under a different name choose the Save As command from the File menu IMPORTANT When naming a DRE file that you will use with UNIX versions of FrameMaker do not use asterisks question marks and extra periods other than the period used in the filename extension in the filename These symbols may cause problems in the X resource files generated by FrameMaker The Save As dialog box appears with the option to save the files as a Frame dialog resource This option is only available when you open a DRE file in FrameMaker If you open a Frame binary file this option does not appear In UNIX and Windows versions of FrameMaker saving a DRE file creates additional files e UNIX versions of FrameMaker creates X resource files x files Your FDK client uses these files to display the dialog boxes e Windows versions of FrameMaker creates Windows dialog resource file
503. oc pgfFmtId F_ApiGetNamedObject docId FO_PgfFmt Heading1 FDK Programmer s Guide 91 aes Getting and Setting Properties 92 Set Next Pgf Tag to Heading2 F_ApiSetString docId pgfFmtId FP_NextTag Heading2 Turn on Keep With Next F_ApiSetInt docId pgfFmtId FP_KeepWithNext True Set the left indent to 1 inch F_ApiSetMetric docId pgfFmtId FP_LeftIndent in This code changes only the Heading Paragraph Catalog format It does not change the formats of paragraphs that have already been tagged with Heading1 Getting and setting property lists Because most objects have relatively long property lists it is often easier to get and set individual properties However to perform the following types of tasks you may need to get and set entire property lists e Getting and setting text properties e Applying table paragraph and character formats e Copying graphic object properties To get and set property lists you need to understand how the API represents them For more information see Property lists on page 272 F_ApiGetProps and F_ApiSetProps make it easy to get and set property lists The syntax for these functions is F_PropValsT F_ApiGetProps F_ObjHandleT docId F_ObjHandleT objId VoidT F_ApiSetProps F_ObjHandleT docId F_ObjHandleT objid F_PropValsT setVal This argument Means docId The ID of the session book or document containing the object objid
504. oc R 576 FP_SmallCapStretch property FO_Doc R 576 FP_SmartQuotes property FO_Doc R 561 FP_SmartSpaces property FO_Doc R 561 FP_Snap property FO_Session R 637 FP_SnapAngle property FO_Doc R 577 FP_SnapGridUnits property FO_Doc R 577 FP_SpaceAbove property FO_FmtChangeList R 585 FP_SpaceAbove property FO_Pgf R 620 FP_SpaceAbove property FO_PgfFmt R 628 FP_SpaceAboveChange property FO_FmtChangeList R 585 FP_SpaceBelow property FO_FmtChangeList R 585 FP_SpaceBelow property FO_Pgf R 620 FP_SpaceBelow property FO_PgfFmt R 628 FP_SpaceBelowChange property FO_FmtChangeList R 585 FP_Spacing property FO_Flow R 580 FP_Specification property FO_FmtRuleClause R 591 FP_SpecificationForCSS property FO_Element R 592 FP_SpotColorView property FO_Doc R 577 FP_Spread property FO_CharFmt R 517 FP_Spread property FO_Doc R 575 FP_Spread property FO_FmtChangeList R 587 FP_Spread property FO_Pgf R 615 FP_Spread property FO_PgfFmt R 625 FP_Spread property text location R 671 FP_SpreadChange property FO_FmtChangeList R 587 FP_Start property FO_FmtChangeList R 588 FP_Start property FO_Pgf R 620 FP_Start property FO_PgfFmt R 628 FP_State property FO_DlgButton G 212 R 533 FP_State property FO_DlgCheckBox G 212 R 533 FP_State property FO_DlgImage G 212 R 534 FP_State property FO_DlgPopUp G 212 R 535 index 62 FP_State property FO_DlgRadioButton G 212 R 535 FP_State property F
505. ocument s pathname It then indents all contiguous entries with the same document ID under that document s pathname This continues until you pass a different document ID If you pass 0 for the d argument the call will not indent the errors If you don t have the document ID you can specify log entry indenting under a filename via the text you pass for the log message To do this you precede the log message with a filename followed by a carriage return This method creates an indented section each time you pass a filename and carraige return even if you pass the same filename in a series of log entries For example if you passed the following to the BookErrorLog client in two consecutive calls filename fm 012Here is my first Log Message filename fm 012Here is my second Log Message The BookErrorLog client would create the following messages FDK Programmer s Guide 361 me Frame Book Architecture filename fm Here is my first Log Message filename fm Here is my second Log Message Example The following code shows a function that posts messages to a log with or without a time stamp if you pass valid ID s for all the ID arguments the log message will include a hypertext link to the specified object in the specified document VoidT ReportError F_ObjHandleT docId F_ObjHandleT objid ConStringT errmsg BoolT dateStamp F_ObjHandleT bookId StringT log_msg F_StrNew U
506. ocumentation FDK Programmer s Guide 121 o 6 Manipulating Text 122 Example The following code adds some text at the insertion point or the beginning of the current text selection and then deletes it The text has a dagger at the end of it F_TextLocT trm F_TextRangeT tr F_ObjHandleT docId Get current text selection docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId doclId FP_TextSelection Return if there is no selection or IP if tr beg objId return Insert text at insertion point or beginning of selection Use the octal code 240 to display the dagger trm F_ApiAddText docId amp tr beg Here s some text 240 F_ApiAlert Now we 11 delete it FF_ALERT_CONTINUE_NOTE Set tr to end at end of the added text Then delete it tr end offset trm offset F_ApiDeleteText docId amp tr Adding text to table cells To add text to a table cell you must first get the ID of the cell To do this you traverse from the table to the row containing the cell and then to the cell Once you have the ID of the cell that you want to add text to you add text to it by calling F_ApiAddText The following code adds some text to the first cell in the first row of the selected table in the active document F_TextLocT ip F_ObjHandleT docId tbliId rowId celllId Get the document and selected tab
507. oduct starts the appropriate editor and instructs it to edit the inset file An API graphic inset editor can update and create insets in response to other events such as the user opening a document or choosing a menu item It can request and respond to notifications like any other API client inset properties The API represents each graphic inset with an FO_Inset object An FO_Inset object has the properties common to all graphic objects It also has some properties that are specific to graphic insets The following table lists some of these properties Property Type Meaning FP_InsetDpi IntT Dots per inch DPI Indicates scale factor It only applies to autosizing raster images FP_InsetEditor StringT Name of client to call to edit the inset on UNIX platforms only FDK Programmer s Guide Using Imported Files and Insets 12 Property Type Meaning FP_InsetFile StringT Platform specific pathname if the inset is an external inset or a null string if it is internal The pathname can be document relative FP_InsetIsFixedSize IntT True if FP_Width and FP_Height are used for the graphic s size False if autosize is used FP_InsetIsFlippedSideways IntT True if inset is flipped sideways In addition to the properties listed in the table above each FO_Inset object has special properties called facets which contain data describing the imported graphic Each FO_Inset object must have at least one of the stan
508. of contents G xii R xviii FDK Programmer s Reference G xii R xvili fhash h header file G 383 File menu name used to specify G 25 R 76 view only menu bar G 161 file operations functions for table R 6 file selection dialog boxes displaying G 21 to G 22 function for R 5 illustrated G 22 file types checking during Open operations G 41 filenames specifying in opening R 326 See also filepaths filepaths converting pathnames to G 375 to G 377 converting to pathnames G 375 functions for G 375 to G 377 R 376 to R 384 R 387 to R 388 basenames for R 376 converting DOS specific to FDE G 375 converting FDE filepaths to UNIX pathnames G 375 converting Macintosh specific to FDE G 375 to G 377 converting MIF platform independent to FDE G 375 to G 377 converting platform specific to platform independent G 375 R 422 to R 423 converting UNIX specific to FDE G 375 to G 377 creating from pathnames G 375 to G 377 R 422 to R 423 filepath information R 383 to R 384 freeing resources associated with G 375 R 378 guessing path type R 424 platform dependent R 382 to R 383 platform independent G 375 to G 377 R 387 R 422 to R 423 index 11 oe Index Subjects returning a copy of a specified filepath R 378 returning file or directory identification information R 388 manipulating G 377 files checking the Open status of G 51 to G 52 checking the Save status of G 64 to G 66 DRE G 179 functions for deleting G 37
509. of the F_FilterArgsT structure Then it opens infile and writes a MIF version to out file Example tinclude fdetypes h include fapi h tinclude fchannel h fFinclude futils h Finclude fioutils h Finclude fmifstmt h 4 i 4 4 4 4 T define BUFSIZE 256 VoidT F_ApiNotify notification docId sparm iparm IntT notification F_ObjHandleT docId StringT sparm IntT iparm FilePathT inPath NULL FilePathT outPath NULL ChannelT inChan NULL ChannelT outChan NULL UCharT buf BUFSIZE F_FilterArgsT argp IntT count Gl F_ApiBailOut F_FdeInit Here is where the code gets access to the filter data argp F_FilterArgsT sparm Next the code declares the necessary file I 0 if inPath F_PathNameToFilePath argp gt infile NULL FDefaultPath NULL return These next 3 returns should free the preceeding paths and channels if inChan F_ChannelOpen inPath r NULL return if outPath F_PathNameToFilePath argp gt out file NULL FDefaultPath NULL return if outChan F_ChannelOpen outPath a NULL return Now the code sets and initializes the MIF output file FDK Programmer s Guide 245 12 Using Imported Files and Insets 246 F_MifSetOutputChannel outChan F_MifSetIndent 0 F_MifMIFFile 7 0
510. of the inset If you want to change the page it displays you must similarly coerce FrameMaker to redisplay the inset You can do this by setting the inset path to a dummy string setting the new page then setting the path to the PDF file if F_ApiChooseFile amp path Select a file to import FV_ChooseSelect return if F_StrIsEmpty path return Now the code has a path prompt for a page num If the user doesn t cancel create an anchored frame and place an inset within it Then set the inset properties To be useful this code would need to set properties for the anchored frame position and size as well if F_ApiPromptiInt amp pgNum PDF PageNum 1 tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection frameId F_ApiNewAnchoredObject docId FO_AFrame amp tr beg insetId F_ApiNewGraphicObject docId FO_Inset frameld F_ApiSetInt docId insetId FP_PageNum pgNum 1 F_ApiSetString docId insetId FP_InsetFile path F_ApiReformat docId Deallocate the string F_ApiDeallocateString amp path Importing a text file The following code imports a text file by reference into a table It parses each paragraph in the text file into a row of cells interpreting each tab in the paragraph as a cell separator Notice how the code uses the FS_FileTypeHint parameter to specify the encoding for the text file F_PropValsT params
511. offset 0 IMPORTANT A valid text range can span multiple paragraphs subcolumns or text frames It can t span multiple flows footnotes table cells or text lines It is possible for a document to have no text selection or insertion point at all This can occur in the following circumstances e One or more graphic objects in the document are selected e One or more entire table cells in the document are selected e There is no selection of any type in the document If a document has no text selection or insertion point at all the fields of the F_TextRangeT structure have the following values Field Value beg objId 0 beg offset 0 end objId 0 end offset 0 For more information on the different types of selection and the properties that represent it see How the API represents the selection in a document on page 285 To get and set a document s insertion point or text selection use F_ApiGetTextRange and F_ApiSetTextRange to get and set its FP_TextSelection property FDK Programmer s Guide 115 o 6 Manipulating Text 116 The syntax for these functions is F_TextRangeT F_ApiGetTextRange F_ObjHandleT parentId F_ObjHandleT objid IntT propNum VoidT F_ApiSetTextRange F_ObjHandleT parentId F_ObjHandleT objId IntT propNum F_TextRangeT setVal This argument Means parentId The ID of the object containing objId If objId specifies a document ID parentId should specify FV_SessionId If
512. og item properties on page 197 Pop up menus A pop up menu allows the user to select a setting from a list of settings You can t specify the list of settings in the DRE file Instead you must include code in your client to provide it For more information see Initializing items in a dialog box on page 218 The pop up menu dialog item does not include a label For instructions on adding a label for a pop up menu see the section Adding dialog items on page 192 For information on setting the basic properties for this dialog item see the section Setting basic dialog item properties on page 197 Image pop up menus An image pop up menu is a pop up menu that appears as a bitmap image of an arrow pointing downward For an example of this bitmap image look at the left side of the Paragraph Designer window In the Dialog Item Properties dialog box for this item the name of the bitmap used is specified in the File Name text box The name can be either arrowdown or tallarrowdn e In UNIX and Windows versions of FrameMaker these two bitmaps are identical Do not change these names e In Macintosh versions of FrameMaker arrowdown is the same height as a label tallarrowdn is the same height as a text box which has a greater height than a label You can change these names to specify the bitmap with the appropriate height If you place the image pop up menu next to a label for example such as the Commands label in t
513. olumn specified by refColNum and numDelCols 1 columns to the right of it If F_ApiDeleteCols is successful it returns FE_Success Otherwise it returns an error code When you delete a table column the API automatically deletes all the FO_Ce11 objects in the column The syntax for F_ApiDeleteRows is IntT F_ApiDeleteRows F_ObjHandleT docId F_ObjHandleT tblid IntT refRowld IntT numDelRows This argument Means docId The ID of the document containing the table tblid The ID of the table containing the rows refRowId The ID of the first row to delete numDelRows The number of rows to delete F_ApiDeleteRows deletes the row specified by refRowId and numDelRows 1 rows below it If F_ApiDeleteRows is successful it returns FE_Success Otherwise it returns an error code F_ApiDeleteRows deletes only one type of row at a time If you attempt to delete a range of rows that includes body rows and header or footer rows F_ApiDeleteRows returns an error When you delete a table row the API automatically deletes the FO_Row object and all the FO_Ce11 objects in the row FDK Programmer s Guide 159 az Creating and Deleting API Objects Implicit property changes When you create or delete an object the API automatically updates other objects and properties that are affected For example if you delete a paragraph FO_Pgf the API automatically updates the FP_NextPgfInFlow property of the previous paragr
514. omRuling property FO_TblFmt R 660 FP_TblCatalogEntry property FO_Tbl R 654 FP_TblCatalogEntry property FO_TblFmt R 659 FP_TblColRuling property FO_Tbl R 655 FP_TblIColRuling property FO_TblFmt G 331 R 660 FP_TbIColRulingPeriod property FO_Tbl R 655 FP_TbIColRulingPeriod property FO_TblFmt R 660 FP_TbIColWidths property FO_Tbl R 654 FP_TbIFnCellPosition property FO_Doc R 572 FP_TblFnCellPrefix property FO_Doc R 572 FP_TblFnCellSuffix property FO_Doc R 572 FP_TblFnCustNumString property FO_Doc R 572 FP_TbIFnFirstNum property FO_BookComponent R 513 FP_TblFnFmt property FO_Doc R 572 FP_TbIFnNumComputeMethod property FO_BookComponent R 513 FP_TbIFnNumStyle property FO_BookComponent R 513 FP_TbIFnNumStyle property FO_Doc R 573 FDK Programmer s Reference amp Guide Index Reserved Names a FP_TblFnPosition property FO_Doc R 573 FP_TbIFnPrefix property FO_Doc R 573 FP_TblFnSuffix property FO_Doc R 573 FP_TbIHFColor property FO_Tbl R 657 FP_TbIHFColor property FO_TblFmt R 662 FP_TbIHFFill property FO_Tbl R 657 FP_TbIHFFill property FO_TblFmt R 662 FP_TbIHFRowRuling property FO_Tbl R 655 FP_TbIHFRowRuling property FO_TblFmt R 660 FP_TblHFSeparatorRuling property FO_Tbl G 336 R 655 FP_TblHFSeparatorRuling property FO_TblFmt G 331 R 661 FP_TblInitNumBodyRows property FO_TbiFmt R 660 FP_TblInitNumCols property FO_TblFmt G 331 R 660 FP_TblInitNumFRows property
515. ommand G 162 R 526 FP_NextComponentInBook property FO_BookComponent G 105 G 354 R 511 FP_NextCondFmtInDoc property FO_CondFmt G 311 R 529 FP_NextElementDefInDoc property FO_ElementDef G 344 R 647 FP_NextFlowInDoc property FO_Flow G 298 R 580 FP_NextFmtChangeListInDoc property FO_FmtChangeList G 347 R 582 FP_NextFn property FO_Fn G 328 R 581 FP_NextFnInDoc property FO_Fn G 328 R 581 FP_NextGraphicInDoc property FO_GraphicObject G 295 R 594 FP_NextGraphicInFrame property FO_GraphicObject G 85 G 100 G 295 R 217 R 594 FP_NextGraphicInGroup property FO_GraphicObject G 296 R 594 FP_NextInvalidElement property FO_Element R 644 FDK Programmer s Reference amp Guide Index Reserved Names a FP_NextMarkerInDoc property FO_Marker G 320 R 609 FP_NextMarkerTypeInDoc property FO_Marker R 609 FP_NextMenultemInMenu property FO_Command G 163 R 35 R 523 FP_NextMenulItemInMenu property FO_Menu G 162 G 163 G 165 G 168 R 35 R 523 FP_NextMenulItemInMenu property FO_MenultemSeparator G 163 G 165 G 168 R 523 FP_NextMenultemInSession property FO_Command R 523 FP_NextMenultemInSession property FO_Menu R 523 FP_NextMenultemInSession property FO_MenultemSeparator R 523 FP_NextMenultemInSession property FO_Session G 162 FP_NextOpenBookInSession property FO_Book G 83 G 275 G 353 R 496 FP_NextOpenDocInSession property FO_Doc G 83 G 275 R 540 FP_NextPgf
516. ommands Frame Development Environment See FDE Frame Development Environment Frame dialog resource DRE files See DRE Frame dialog resource files Frame product commands functions for executing G 7 G 40 G 45 to G 79 See also commands Frame product operations Frame product documents properties for importing table R 124 Frame product menu bars See menu bars Frame product menus getting IDs of G 24 to G 26 replacing with your own menus G 30 setting menu item labels G 171 table G 25 See also menus Frame product operations initiating G 40 notification in G 34 to G 36 Open G 41 to G 42 responding to G 34 to G 42 Save G 41 G 60 suspending functions for R 17 R 328 R 344 to R 345 See also Frame product commands Frame product sessions See sessions Frame products defined G xiii R x1x index 14 Frame tools advantages and limitations of table G xi R xvii choosing G xi R xvii FrameBuilder documents importing element definitions from G 77 manipulating elements in G 76 to G 77 FramelImage facets G 257 G 259 R 183 R 316 FrameMaker G 258 FrameMaker product client initialization by G 5 events monitoring by G 43 getting the name of current product interface G 94 languages available in R 635 list of products R 636 regaining control from function for R 25 R 334 registering API clients with G 8 to G 9 G 12 returning control to function for R 96 servicing calls to the API function for R 277 to R 278
517. on constant R 232 FA_Note_PreFileType notification constant G 35 G 41 R 227 R 228 FA_Note_PreFunction notification constant G 38 R 230 R 235 FA_Note_PreGenerate notification constant R 228 FA_Note_PreGenerate notification constant R 235 FA_Note_PreGoToXrefSrc notification constant R 231 FA_Note_PreHypertext notification constant R 231 R 235 FA_Note_PreImport notification constant R 230 R 235 FA_Note_PreImportElementDefs notification constant R 232 FA_Note_PreInlineTypeIn notification constant R 232 FA_Note_PreInsertElement notification constant R 231 R 235 FA_Note_PreMouseCommand notification constant R 230 R 236 FA_Note_PreOpenBook notification constant R 228 R 235 FA_Note_PreOpenBookMIF notification constant R 228 FA_Note_PreOpenDoc notification constant G 35 R 227 FA_Note_PreOpenMIF notification constant R 227 FA_Note_PreOpenSGM L notification constant R 227 FA_Note_PreOpenXML notification constant R 227 FA_Note_PrePrint notification constant R 231 FA_Note_PreQuitBook notification constant R 229 FA_Note_PreQuitDoc notification constant G 35 G 44 R 229 FA_Note_PreQuitSession notification constant R 230 FA_Note_PreRevertBook notification constant R 230 FA_Note_PreRevertDoc notification constant R 229 FA_Note_PreSaveAsPDFDialog notification constant R 229 R 237 FA_Note_PreSaveAsPdfDialog notification constant R 269 FDK Programmer s Reference amp Guide FA_Note_PreSaveBook notification constant R
518. on needs to be provided in a Windows dialog resource file a dlg file Additional information specific to Frame dialog boxes needs to be provided in a separate file an xdi file For this reason when you save a DRE file in FrameMaker the product also writes out the same dialog box information ina dlg file andan xdi file Figure 10 5 shows the process of creating a dialog box for a Windows client Designing the Writing the Compiling the dialog box code to dialog resources Windows operate the with your FDK ker dialog box client Open 0 jij i i View of the DRE file dialog box Save JE N Other source FDK client files for client Save resource file dlg Save 1 1 Extra dialog information file xdi FiguRE 10 5 Creating a dialog box for a Windows client Dialog box information in UNIX In UNIX dialog box information is read dynamically from X resource files when you invoke FrameMaker For this reason when you save a DRE file in FrameMaker the product also writes out the same dialog box information in an X resource file x file FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client 10 Figure 10 6 shows the process of creating a dialog box for a UNIX client Designing th
519. one active document at a time The session object FO_Session has a property named FP_ActiveDoc that specifies its ID To retrieve 10 FDK Programmer s Guide Introduction to the Frame API aa the active document s ID from the FO_Session object you use F_ApiGetId to query the FO_Session object s FP_ActiveDoc property The syntax for F_ApiGetId is F_ObjHandleT F_ApiGetId parentId Object s parent objId Object whose property you want to query property Constant specifying property to query The parentId parameter specifies the ID of the object s parent the session book or document that contains the object No other object contains the FO_Session object so parentId is setto 0 The ID of the FO_Session object there can only be one is always FV_SessionId so objId is setto FV_SessionlId Lines 37 40 These lines close the active document when the user chooses Close Doc from the API menu The FF_CLOSE_MODIFIED flag instructs the API to close the document without warning the user even if the document has unsaved changes Lines 41 51 These lines set the fill pattern of a selected object to black when the user chooses Set Fill from the API menu To set the selected object s fill pattern the client needs the object s ID To get the ID the client uses F_ApiGetId to query the document property FP_FirstSelectedGraphicInDoc If no object is selected F_ApiGetId returns 0 The F_ApiAlert ca
520. one of each type of dialog item FDK Programmer s Guide 221 E Handling Custom Dialog Box Events F_ObjHandleT dlgId define BUTTON_1 1 define CHECKBOX_1 2 define TRIBOX_1 3 define POPUP_1 4 define SCROLLBOX_1 5 define IMAGE_1 6 define EDITBOX_1 7 define RADIOBUTTON_1 8 VoidT F_ApiDialogEvent dlgNum itemNum modifiers IntT dlgNum IntT itemNum IntT modifiers IntT state F_ObjHandleT itemId StringT text E labels F StringsT if F_ApiGetInt 0 dlgId FP_DoubleClick True F_Printf NULL The user double clicked n itemId F_ApiDialogItemId dlgId itemNum switch itemNum case BUTTON_1 case CHECKBOX_1 case TRIBOX_1 case RADIOBUTTON_1 state F_ApiGetInt dlgId itemId FP_State switch state case FV_DlgOptActive m F_Printf NULL d set to on n itemNum break case FV_DlgOptNotActive F_Printf NULL d set to off n itemNum break case FV_DlgOptDontCare F_Printf NULL d set to As Is n itemNum break break case IMAGE_1 case POPUP_1 case SCROLLBOX_1 state F_ApiGetInt dlgId itemId FP_State labels F_ApiGetStrings dlgId itemId FP_Labels 222 FDK Programmer s Guide Handling Custom Dialog Box Events uo F_Printf NULL s was chosen from item d n labels val state itemNum break case EDITBOX_1 text F_ApiGetString dlgId
521. open If you are using F_ApiOpen to create a document specify the template name openParamsp A property list script that tells the FrameMaker product how to open the file and how to respond to errors and other conditions that arise Use F_ApiGetOpenDefaultParams or F_ApiAllocatePropVals to create and allocate memory for this property list To use the default list specify NULL openReturnParamspp A property list that returns the pathname and provides information on how the FrameMaker product opened the file IMPORTANT Always initialize the pointer to the property list that you specify for openReturnParamspp to NULL before you call F_ApiOpen If F_ApiOpen is successful it returns the ID of the opened document or book Otherwise it returns 0 To call F_ApiOpen do the following 1 Initialize the pointer to the openReturnParamspp property list to NULL 2 Create an openParamsp property list You can get a default list by calling F_ApiGetOpenDefaultParams or you can create a list from scratch 3 Call F_ApiOpen 4 Check the Open status Check the returned values in the openReturnParamspp list for the name of the opened file and other information about how the FrameMaker product opened the file FDK Programmer s Guide Executing Commands with API Functions 4 5 Deallocate memory for the openParamsp and openReturnParamspp property lists Use F_ApiDeallocatePropVals to deallocate memory for th
522. operty FO_ElementDef G 345 index 51 os Index Reserved Names FP_FmtRuleClause property FO_FmtRule R 590 FP_FmtRuleClauses property FO_FmtRule G 345 R 590 FP_FmtRuleType property FO_FmtRule G 345 R 590 FP_FnCustNumString property FO_Doc R 557 FP_FnFirstNum property FO_BookComponent R 510 FP_FnFirstNum property FO_Doc R 557 FP_FnFmt property FO_Doc R 557 FP_FnHeightPerCol property FO_Doc R 557 FP_FnInstancePosition property FO_Doc R 558 FP_FnInstancePrefix property FO_Doc R 558 FP_FnInstanceSuffix property FO_Doc R 558 FP_FnNum property FO_Fn G 328 R 581 FP_FnNumberingPerPage property FO_Doc R 558 FP_FnNumComputeMethod property FO_BookComponent R 510 FP_FnNumStyle property FO_BookComponent R 510 FP_FnNumStyle property FO_Doc G 328 R 558 FP_FnRefPosition property FO_Doc R 559 FP_FnRefPrefix property FO_Doc R 559 FP_FnRefSuffix property FO_Doc R 559 FP_FontAngle property FO_CharFmt R 515 FP_FontAngle property FO_Doc R 574 FP_FontAngle property FO_FmtChangeList R 586 FP_FontAngle property FO_Pgf R 614 FP_FontAngle property FO_PgfFmt R 623 FP_FontAngle property text location G 317 R 669 FP_FontAngleNames property FO_Session G 277 R 633 FP_FontEncodingName property FO_CharFmt R 515 FP_FontEncodingName property FO_CombinedFontDefn R 522 FP_FontEncodingName property FO_Doc R 574 FP_FontEncodingName property FO_Pgf R 614 FP_FontEncodingName property
523. opup FO_DlgScroll1Box and FO_DlgImage items Be sure to include code to initialize these items When you set the FP_Labels property of an FO_DlgPopup item set the first string in the F_StringsT structure to the title of the pop up menu The title appears at the top of the menu when the user clicks on it Although the title appears only on UNIX platforms you must specify it on all platforms FDK Programmer s Guide Handling Custom Dialog Box Events uo When you first open a dialog box containing an FO_DlgPopup item the default state of the item is 0 so the title appears as the current choice Because the title is not a valid choice you should initialize the FP_State property of FO_DlgPopup items to another number For example the following code initializes a pop up menu F_ObjHandleT dlgId popupMenuld F_StringsT strings strings val StringT F_Alloc 3 sizeof StringT NO_DSE strings len 3 strings val 0 F_StrCopyString Popup title strings val 1 F_StrCopyString PopupItem1 strings val 2 F_StrCopyString PopuplItem2 F_ApiSetStrings dlgId popupMenulId FP_Labels amp strings Make the first item the default F_ApiSetInt dlgId popupMenulId FP_State 1 When you initialize a dialog box you may also want to disable some of its items making them unavailable to the user A disabled item appears dimmed and can t receive input focus To disable an item set its FP_Sensit
524. or should use the predefined separator name Separator2 This makes it easier for other clients and users who modify menu configuration files to manipulate the separators You can use the same separator on different menus For example if you create two menus that contain two separators you can use Separatorl and Separator2 on each menu FDK Programmer s Guide 169 i Manipulating Commands and Menus with the API 170 Adding moving and deleting separators You can add move and delete separators the same way you add move and delete commands and menu items For example the following code removes the separator that appears after the Conditional Text menu item on the Special menu It then adds a separator and moves it above the Conditional Text menu item F_ObjHandleT specialMenuld separatorId conditionCmdId specialMenuld F_ApiGetNamedObject FV_SessionId FO_Menu SpecialMenu separatorlId F_ApiGetNamedOb ject FV_SessionId FO_MenulItemSeparator Separatorl1 conditionCmdId F_ApiGetNamedOb ject FV_SessionId FO_Command ConditionalText Delete the separator F_ApiDelete specialMenuld separatorId Add it back and move it below the Conditional Text item F_ApiAddCommandToMenu specialMenuld separatorId F_ApiSetId specialMenuld separatorId FP_NextMenuItemInMenu conditionCmdId Creating separator objects Because separators appear the same and you can use the same separator
525. or menu item is on several menus you must make a separate F_ApiDelete call to remove it from each menu For example the following code removes the Copy command from the Edit menu FDK Programmer s Guide 167 i Manipulating Commands and Menus with the API 168 F_ObjHandleT copyCmdId editMenulId editMenuld F_ApiGetNamedObject FV_SessionId FO Menu EditMenu copyCmdId F_ApiGetNamedObject FV_SessionId FO_Command Copy F_ApiDelete editMenuld copyCmdId Reordering menus and menu items To change a menu or menu item s position on a menu set its FP_NextMenuItemInMenu or FP_PrevMenuItemInMenu properties to specify the IDs of other menus or menu items on the menu You need to set only one of these properties FrameMaker automatically sets the other one for you For example if the Cut and Copy commands are on the Edit menu you can use the following code to make Copy appear above Cut F_ObjHandleT cutCmdiId copyCmdId editMenuld editMenuld F_ApiGetNamedObject FV_SessionId FO Menu EditMenu cutCmdId F_ApiGetNamedOb ject FV_SessionId FO_Command Cut copyCmdId F_ApiGetNamedObject FV_SessionId FO Command Copy F_ApiSetId editMenuld copyCmdId FP_NextMenuItemInMenu cutCmdId The following F_ApiSetId call has the same effect as the call in the code above F_ApiSetId editMenuld cutCmdId FP_PrevMenuItemInMenu copyCmdId To move a menu or menu item to the top
526. ormat What the user sees Each variable format can specify a combination of text and building blocks Building blocks are FrameMaker product defined variables that you can string together 324 FDK Programmer s Guide Frame Document Architecture 14 There are six principal classes of variable formats e Page number e Date e Filename e Table e Running header or footer e User Each of these classes has a unique set of building blocks You cannot use a building block from one class in another class For example you cannot use a date building block in a page number variable format How the API represents variable formats FrameMaker represents each variable format with an FO_VarFmt object whose properties provide the following information e The name of the variable format e The list of building blocks and text strings e The type of variable it is for example page count or user variable e ID ofthe next FO_VarFmt object in the document Suppose you edit the Creation Date Long variable format so that its definition is as shown in Figure 14 27 Edit System Variable K second gt Kk second00 gt K minute gt K minuteOO gt kK hour gt FIGURE 14 27 Creation Date Long variable definition The following are some properties of the FO_VarFmt object that represents the Creation Date Long variable format Property Type Value FP_Fmt StringT lt Smonthname gt lt Sdaynum gt lt Sy
527. ormation see your Windows documentation ItalicFlag Whether font is italic you can use one of the following flags I Italic R Regular Weight Weight classification for example 400 Regular or 700 Bold The following strings are valid representations of the Windows font Helvetica Narrow Bold Oblique W Helvetica Narrow I 700 W Helvetica I 700 Narrow When reading in a document FrameMaker determines a font name by checking font properties in the following order e FP _FontPlatformName e Combination of FP_FontFamily FP_FontVariation FP_FontWeight and FP_FontAngle e FP_FontPostScriptName Your clients do not need to use all three methods to change fonts You should always specify the PostScript name if it is available Use the platform name only if your client is for a specific platform How the API represents As Is settings FO_CharFmt objects use two properties to represent a font characteristic one to represent the characteristic s As Is state and one to represent the characteristic itself For example FP_UseFontWeight specifies whether the character format s font weight overrides the default font weight of the text that the format is applied to FP_FontWeight specifies the character format s font weight If FP_UseFontWeight is True the font weight specified by FP_FontWeight overrides the default font weight for the text If FP_UseFontWeight is False AsIs FP_FontWeight does not affect the text s fon
528. ormed by a client that adds the HTML Macro marker type to the standard list The value of that marker s FP_OldTypeNunm is 11 After that client is initialized no other clients can use the same value for FP_OldTypeNum when assigning a marker to the standard list Cross reference formats When you insert a cross reference in a document you choose a cross reference format that specifies the information provided by the cross reference What the user sees A cross reference format consists of a combination of text and cross reference building blocks Cross reference building blocks are variables that provide information such as the current page number or filename Each document has a catalog of cross reference formats You can add or delete formats from this catalog How the API represents cross reference formats FrameMaker represents each cross reference format with an FO_XRefFmt object whose properties provide the following information e The name of the cross reference format e A string containing the cross reference s text and cross reference building blocks e The ID of the next FO_XRefFmt object in the document Suppose you create a cross reference format named See Heading amp Page as shown in Figure 14 25 322 FDK Programmer s Guide Frame Document Architecture Edit Cross Reference Format x Heading amp Page lt paratext gt on page lt pagenum gt Chapter Kk elempagenum gt A ChapterGuide Ch
529. oth specify the ID of the FO_TextFrame object since it is the only object that appears directly on the page FO_BodyPage FP_PageFrame FO_UnanchoredFrame gt page frame FO_TextFrame FP_FirstGraphiclnFrame FP_LastGraphiclnFrame FIGURE 14 3 Objects for a body page with a single text frame FrameMaker automatically creates and destroys the page frame when it creates and destroys the page The page frame is not accessible to the user However as a developer you need to use it to get the objects on a page FDK Programmer s Guide Frame Document Architecture CE The API maintains the different types of visible pages in a document body pages master pages and reference pages in separate linked lists FO_Doc objects have the following properties that specify the first and last page object in each list How the API organizes pages e FP_FirstBodyPageInDoc and FP_LastBodyPageInDoc e FP_FirstMasterPageInDoc and FP_LastMasterPageInDoc e FP_FirstRefPageInDoc and FP_LastRefPageInDoc Each page object has two properties FP_PagePrev and FP_PageNext that specify the IDs of the page objects before and after it in the list When you delete a page the API removes the object that represents it and updates the FP_PagePrev and FP_PageNext properties for all the FO_Page objects before and after it FO_Doc objects also have a property named FP_CurrentPage that specifies the ID of the curre
530. ou can do it programmatically The syntax for the functions is IntT F_ApiCut F_ObjHandleT docId IntT flags IntT F_ApiCopy F_ObjHandleT docId IntT flags IntT F_ApiPaste F_ObjHandleT docId IntT flags IntT F_ApiClear F_ObjHandleT docId IntT flags FDK Programmer s Guide 127 o 6 Manipulating Text This argument doc Id flags Means The ID of the document in which you want to cut copy paste or clear the selection Bit flags that specify how to cut copy paste or clear the selection See the table below Specify O for the default behavior Specifying 0 for flags instructs these functions to behave in the following ways e F_ApiCut and F_ApiClear leave selected table cells empty and delete hidden text e F_ApiPaste inserts table columns to the left of the current columns and rows above the current row e All functions suppress any Frame dialog boxes or alert boxes that arise To specify the behavior of the functions you can OR the following values into the flags argument This value Means Applies to FF_INTERACTIVE Prompt user with dialog boxes All Clipboard functions or alert boxes that arise FF_CUT_TBL_CELLS Remove cut or cleared table F_ApiClear and cells F_ApiCut FF_DONT_DELETE_HIDDEN_TEXT Don t delete hidden text F_ApiClear F_ApiCut and F_ApiPaste
531. p Help menu name used to specify G 25 R 76 hidden conditional text API representation of G 318 hidden pages G 289 G 292 G 318 API representation of G 289 defined G 390 properties of G 289 R 611 HIDDEN text flows G 292 G 318 hiding text G 309 to G 311 HLS color model G 339 hypertext commands G 31 setting up G 32 simulating user invoked R 192 index 16 hypertext markers illustrated G 33 responding to user clicking G 32 G 32 to G 34 R 192 function for R 1 R 206 hyphenation See paragraph formats FO_PgfFmt hyphenation properties of paragraphs FO_Pgf hyphenation properties of I J T O calls making portable G 367 G 375 to G 379 replacing with FDE functions G 369 TO channels See channels ID ObjHandleT properties function for getting R 15 R 119 to R 120 function for setting R 16 R 285 identifiers See IDs of API objects UIDs unique IDs identifying objects G 269 to G 270 IDs of API objects G 3 for active documents or books G 275 data type for G 3 G 6 G 271 G 390 defined G 390 for dialog boxes R 5 R 94 for dialog items G 212 to G 213 of Frame product menus G 24 to G 26 getting G 82 to G 89 G 269 to G 270 for graphics G 285 of menu bars G 24 to G 26 for tables G 285 See also ID ObjHandleT properties UIDs unique IDs illegal values protection against G 81 image pop up menus in dialog boxes G 200 properties of G 200 R 534 import filters See filters imported graphics See graphic ins
532. parent Id ID of the element containing the first selected element end childId ID of the sibling element following the last selected element or O if there is no sibling element following the last selected element end offset 0 beg beg beg end parentId 0 childtid ID of the highest level element offset 0 parentId 0 childId 0 end offset 0 end Example Suppose you create the document shown in Figure 14 1 FDK Programmer s Guide 287 14 Frame Document Architecture S C Sales Training 1 Chapter fm FIGURE 14 1 A document The API represents the document with an FO_Doc object The following table lists some of its properties Property Type Value FP_Name StringT C Sales Training 1lChapter FP_ViewBorders IntT True FP_ViewRulers IntT True FP_ViewPageScrolling IntT FV_SCROLL_ VERTICAL FP_Zoom MetricT 1 lt lt 16 FP_IsIconified IntT False FP_ViewText Symbols IntT True FP_IsOnScreen IntT True Pages Frame documents have three kinds of visible pages body pages master pages and reference pages What the user sees With FrameMaker the user can change any of the visible pages 288 FDK Programmer s Guide Frame Document Architecture Body pages Body pages are what a user normally thinks of as the document s pages They organize the text and graphic objects that appear in the body of a document
533. penDefaultParams R 142 FS_FormatImportedText property F_ApiGetImportDefaultParams R 124 FS_GraphicDpi property F_ApiGetImportDefaultParams R 125 FS_HowToImport property F_ApiGetImportDefaultParams R 122 FS_ImportAsType property F_ApiGetImportDefaultParams R 123 FS_ImportAsType property F_Apilmport R 121 FS_ImportedFileName property F_Apilmport R 194 FS_ImportedTbITag property F_ApiGetImportDefaultParams R 126 FS_ImportFlowPageSpace property F_ApiGetImportDefaultParams R 124 FS_ImportFlowTag property F_ApiGetImportDefaultParams R 124 FS_ImportNativeError property F_Apilmport R 194 FS_ImportStatus property F_Apilmport R 194 possible status flags table R 195 FS_LanguageNotAvailable property F_ApiGetOpenDefaultParams R 142 FS_LeaveHeadingRowsEmpty property F_ApiGetImportDefaultParams R 126 index 67 os Index Reserved Names FS_LockCantBeReset property F_ApiGetOpenDefaultParams R 142 FS_Makelconic property F_ApiGetOpenDefaultParams R 142 FS_MakePageCount property F_ApiGetSaveDefaultParams R 155 FS_MakeVisible property F_ApiGetOpenDefaultParams R 142 FS_MakeVisible property F_ApiGetUpdateBookDefaultParams G 358 R 188 FS_ManualUpdate property F_ApiGetImportDefaultParams R 123 FS_NameStripe property F_ApiGetOpenDefaultParams G 49 R 142 FS_NewDoc property F_ApiGetOpenDefaultParams G 49 R 143 R 239 FS_NumCellSeparators property F_Ap
534. perty value type G 273 R 690 FDK Programmer s Reference amp Guide Index Reserved Names as FT_TextRange property value type G 273 R 690 FT_UBytes property value type G 273 R 690 FT_UInts property value type G 273 R 690 FTF_ FTF_ALL bit flag FTI_CharPropsChange G 316 R 689 FTF_ANGLE bit flag FTI_CharPropsChange G 315 R 167 R 688 FTF_CAPITALIZATION bit flag FTI_CharPropsChange G 315 R 167 R 688 FTF_CHANGEBAR bit flag FTI_CharPropsChange G 315 R 167 R 688 FTF_CHARTAG bit flag FTI_CharPropsChange G 315 R 167 R 688 FTF_COLOR bit flag FTI_CharPropsChange G 315 R 167 R 688 FTF_CONDITIONTAG bit flag FTI_CharPropsChange G 315 R 167 R 688 FTF_ENCODING bit flag FTI_CharPropsChange G 315 R 167 R 168 R 689 FTF_FAMILY bit flag FTI_CharPropsChange G 315 R 167 R 688 FTF_KERNX bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_KERNY bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_LANGUAGE bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_OUTLINE bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_OVERLINE bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_PAIRKERN bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_POSITION bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_SHADOW bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_SIZE bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_SPREAD bit flag FTI_CharPropsChange G 315 R 168 R 688 FTF_STRETCH bit
535. phic in the document s list of selected graphics FP_SelectedTbl is 0 T There is an insertion pointor FP_TextSelection specifies the location of the text selection or text selection that isn tina insertion point table cell but may include FP_FirstSelectedGraphicInDoc is 0 table anchors FP_SelectedTbl is 0 1 Some platforms do not save some of the global document information such as the printing properties FDK Programmer s Guide 285 14 Frame Document Architecture Selection state How selection properties are set There is an insertion pointor FP_TextSelection specifies the location of the text selection or text selection within a single insertion point within the cell for example the ID of the paragraph table cell containing the insertion point and the offset within that paragraph FP_FirstSelectedGraphicInDoc is 0 FP_SelectedTb1 specifies the ID of the table containing the cell If the current selection is in a paragraph the paragraph s FP_InTextObjJ property specifies the ID of the cell that contains the selection The cell s FP_Ce11Co1Num property specifies the column number and the cell s FP_Ce11Row property specifies the ID of its row An entire cell or set of cells FP_TextSelection specifiesan F_TextRangeT structure is selected for which the objId and offset fields of F_TextRangeT beg and F_TextRangeT end are setto 0 FP_FirstSelectedGraphicInDoc is 0 FP_SelectedTb1 specifies
536. pi dll all For more information on how to register clients see the FDK Platform Guide After you have registered the example client start the FrameMaker product and open a document The API menu should appear to the right of the FrameMaker product menus 12 FDK Programmer s Guide API Client Initialization This chapter describes how to start interaction between your client and FrameMaker Responding to the FrameMaker product s initialization call When the FrameMaker product starts it attempts to start all the clients registered with it except document reports and filters The FrameMaker product attempts to start each client by calling its F_ApiInitialize callback function Your client should define F_ApiInitialize as follows VoidT F_Apilnitialize initialization IntT initialization Your client code goes here TABLE 2 1 This argument Means initialization A flag that indicates the type of initialization see Initialization types on page 14 Usually you want your client to do something immediately after the user starts the FrameMaker product For example you may want to add menus to the menu bar or request notification for certain events To do this you call API functions from the F_ApiInitialize function For information on creating menus and requesting notification see Chapter 3 Creating Your Client s User Interface Suppose you want your client to display a d
537. ppears FP_FnNum IntT Oz FP_PrevFn F_ObjHandleT ID of the previous footnote in the text frame in this case NULL FP_NextFn F_ObjHandleT ID of the next footnote in the text frame in this case NULL FP_NextFnInDoc F_ObjHandleT ID of the next footnote in the document FP_FirstPgf F_ObjHandleT ID of the first paragraph FO_Pgf in the footnote FP_LastPgf F_ObjHandleT ID of the last paragraph FO_Pgf in the footnote in this example it is the same as the one specified by FP_FirstPgf Although FP_FnNum specifies an integer the number that appears in the document can be one of several ordinal or special characters For example if you set the document s FP_FnNumStyle property to FV_FN_NUM_ALPHA_UC an A would appear instead of the in the body text and at the beginning of the footnote To get all the paragraphs in a footnote you traverse the FP_NextPgfInFlow and FP_PrevPgfInFlow properties just as you would to get the paragraphs in any other flow Ruling Formats Each document has a Ruling Catalog containing several ruling formats 328 FDK Programmer s Guide Frame Document Architecture What the user sees Rulings are the lines that border a table cell or an entire table A ruling format specifies a line type such as Thin or Thick and the gap between the line and the cell contents You can specify rulings for an entire table in the Table Designer or for individual table cells in the
538. ppose you want to uncompress a compressed document file when the user opens it Normally when a user attempts to open a compressed file the FrameMaker product displays an Unrecognized type alert and cancels the Open operation when it checks the file s type You must uncompress the file after the user has chosen it but before the FrameMaker product checks its type To do this you could use the following code F_ApiNotification FA_Note_PreFileType True VoidT F_ApiNotify notification docId sparm iparm IntT notification F_ObjHandleT docId StringT sparm IntT iparm if notification FA_Note_PreFileType Code to test if file is compressed goes here F_ApiAlert Uncompressing file FF_ALERT_CONTINUE_NOTE Code to uncompress file goes here Implementing quick keys FrameMaker provides a quick key interface which allows the user to choose commands in the document Tag area In FrameMaker for example the user can apply a character format by pressing Esc q c FrameMaker displays an f prompt in the Tag area The user can then choose a character format by typing the first few letters of the format s name and pressing Return when the format appears in the Tag area Your client can implement its own quick key interface by calling F_ApiQuickSelect The syntax for F_ApiQuickSelect is IntT F_ApiQuickSelect F_ObjHandleT doclId StringT prompt F_StringsT stringlist T
539. present the rows before and after it in the table e The ID of the FO_Cell1 object that represents the first leftmost cell in the row e The conditions that apply to the row e The element ID of the row if it is a structured row in a FrameMaker document If a row has conditions applied to it its FP_InCond property specifies an F_IntsT structure that includes the IDs of the FO_CondFmt objects that represent the conditions Cells The API represents each cell in a table with an FO_Ce11 object whose properties provide the following information e The ruling and shading that the cell inherits from the table format e Custom ruling and shading e Flags that indicate whether the cell s custom shading and fill override the table s shading and fill e IDs of sibling FO_Cell objects e IDs of the first and last paragraphs in the cell e The element ID of the cell if it is a structured cell in a FrameMaker document The FO_Cel1 object properties FP_FirstPgf and FP_LastPof specify the IDs of the first and last paragraphs in the cell If there is more than one paragraph in the cell each paragraph s FP_PrevPgfInFlow and FP_NextPgfInFlow properties specify the IDs of the paragraphs before and after it FDK Programmer s Guide 333 14 Frame Document Architecture FO_Cell objects have two properties for each ruling For example the properties for the top ruling are FP_CellDefaultTopRuling and FP_CellOverrideTopRuling The defa
540. process of creating a dialog box for a Macintosh client FDK Programmer s Guide 183 a Creating Custom Dialog Boxes for Your Client Designing the dialog box DRE file Macintosh FrameMaker product J Representation of the dialog box Save Writing the Compiling the dialog code to resources with your operate the FDK client dialog box ULL Other is m D dre FDK client FiguRE 10 7 Creating a dialog box for a Macintosh client Dialog box information across platforms If you are writing a client for multiple platforms you can use the same DRE file to describe a dialog box on different platforms Figure 10 8 shows an example of the process for using a single DRE file to design the same dialog box on different platforms UNIX _ FrameMaker Gaile re XN SS gt Ope E FDK client i a X resource DRE file View of the Save dialog box r gt Macintosh build process DRE file Windows FrameMaker Save DRE fil ini ile DRE file View of the dialog box Save gt EN Windows build process Windows lt Save Extra dialog information file xdi FIGURE 10 8 Using the same DRE file across different platforms 184 FDK Pro
541. pulating G 190 to G 192 metric prompt G 18 to G 21 modal G 17 G 177 G 197 G 205 to G 206 G 211 G 219 R 206 to R 207 modeless G 17 G 205 to G 206 G 219 R 208 to R 209 modifying G 191 to G 192 moving G 191 multiple modeless G 225 to G 226 for multiple platforms G 184 multiple interaction G 223 G 224 to G 225 OK button G 196 platform view G 180 G 187 G 189 to G 190 G 207 platform specific views of G 180 to G 181 predefined R 5 properties of G 208 R 531 to R 537 setting G 193 to G 197 G 208 resizing G 191 saving dialog box information G 181 to G 185 scroll bars in G 201 scroll list G 22 to G 24 R 5 scroll lists in G 202 single interaction G 223 specifying item order in G 194 to G 195 specifying position G 196 specifying size G 196 specifying the focus order G 194 to G 195 string prompt G 18 to G 20 testing G 205 to G 206 G 209 title label G 196 on UNIX platforms G 180 to G 181 G 189 to G 190 G 207 updating items in G 220 on Windows platforms G 180 to G 181 G 189 to G 190 G 207 See also dialog items dialog resources DRE Frame dialog resource files Dialog Item Properties dialog box G 197 G 209 dialog items G 196 adding to dialog boxes G 192 boxes G 198 buttons G 199 checkboxes G 199 deleting G 193 disabling G 219 IDs of G 212 to G 213 index 7 index 8 Index Subjects initializing G 218 to G 219 labels G 201 manipulating G 190 to G 192 modifying G 191 to G
542. r The API represents the information in a document with a set of objects The following table summarizes the information a document can contain and the objects the API uses to represent it Type of information Global document information Pages Graphic objects Text columns Text frames Text flows Paragraph Catalog formats Paragraphs Character Catalog formats Function Specifies the document s general characteristics some aspects of the FrameMaker product s behavior when the document has input focus and IDs of other objects that constitute the document Organize text and graphic objects in the document Describe graphic objects in the document Contain text Contain text Specify how text frames in the document are linked Specify tags that the user can apply to a paragraph to change its formatting Contain the document s text and provide formatting information for individual paragraphs Specify tags that the user can apply to a selection of characters to change its formatting Types of objects that represent it FO_Doc FO_BodyPage FO_MasterPage FO_RefPage FO_HiddenPage FO_UnanchoredFrame FO_AFrame FO_Group FO_Arc FO_Rectangle FO_Ellipse FO_RoundRect FO_Polyline FO_Polygon FO_Line FO_TextLine FO_TextFrame FO_Inset FO_Math FO_SubCol FO_TextFrame FO_Flow FO_PgfFmt FO_Pgf FO_CharFmt FDK Programmer s Guide Frame Document Architecture 14 Type o
543. r product changes the ShowParagraphTags menu item to list the paragraph formats available in the document If the user adds or deletes a paragraph format the FrameMaker product updates the list to reflect the change You can manipulate an expandomatic menu item just as you manipulate any other menu item However you can t manipulate the individual items that constitute the expandomatic item For 172 FDK Programmer s Guide Manipulating Commands and Menus with the API 9 example you can move or remove the entire ShowParagraphTags item but you can t move or remove an individual item such as Body that appears on it You can get the ID of an expandomatic item with the code similar to the following F_ObjHandleT itemId itemId F_ApiGetNamedOb ject FV_SessionId FO_Command ShowParagraphtTags Individual items in an expandomatic item don t have IDs You can determine which items an expandomatic menu item contains by getting object properties For example you can determine which items ShowFontChoices contains by getting the session property FP_FontFamilyNames Using check marks FrameMaker displays check marks next to some menu items to indicate the state of a setting or option For example when borders are visible in a document a FrameMaker product displays a check mark next to the Borders menu item Your client can also display check marks next to its menu items Menu items have two properties that control check mar
544. r bitmap formats When printing an imported graphic FrameMaker uses one of the following facet formats in order of preference e EPSI Encapsulated PostScript e Native platform format QuickDraw PICT WMF e FrameVector e TIFF e FramelImage and other bitmap formats Unlike other properties which are identified by numbers facets are identified by names Instead of using propIdent num to identify a facet the API sets propIdent num to 0 and sets propIdent name to the facet name For more information on how the API represents property and property lists see Representing object characteristics with properties on page 270 In addition to the facets listed above each FO_Inset object can have several client specific facets Client specific facets contain information that your client uses A client specific facet can contain a complete set of data or just a pathname to an external data file or database You must register the names of client specific facets with the FrameMaker product For FDK Programmer s Guide Using Imported Files and Insets 12 information on registering FDK clients and facets for inset editors see the FDK Platform Guide for UNIX A graphic inset can have as many client specific facets as you want Facets can specify integer Int T metric Met ricT or unsigned bytes F_UBytesT data Facets such as EPSI and FrameImage that specify multiple characters or binary data are F_UBytesT facets F_UBytesT is de
545. r client to manipulate the dialog box After you create a custom dialog box for your client you need to add code to your client to manipulate it For more information see Chapter 11 Handling Custom Dialog Box Events 3 Compile the dialog box with your client in the build process After you write the code for your client you can compile the code with the files containing dialog box information Each platform Windows Macintosh UNIX uses a different build process For more information see the FDK Platform Guide for the appropriate platform FDK Programmer s Guide 177 a Creating Custom Dialog Boxes for Your Client This overview section describes the fundamentals behind the first step of this process creating dialog boxes for clients The later sections of this chapter describe the specific procedures in this step of the process The end of this chapter lists some helpful tips to keep in mind when editing dialog boxes Designing a dialog box in FrameMaker You can use FrameMaker as a dialog editing application FrameMaker can represent dialog box information as special Frame graphic objects You can then modify the dialog box and its items just as you would modify standard Frame graphic objects Figure 10 1 shows a dialog box edited within FrameMaker File Edit Format View Special Graphics Table My New Dialog Box TagName o Preferences yes lt No X 2 PopUp 1ofi 100 z zl gt FIGURE 10 1
546. r must be registered as a filter For information on registering filters see the FDK Platform Guide for your platform Initialization after a client has bailed out If your API client is waiting for an event and not performing any other processing it can call F_ApiBailOut This exits your client s process and frees all the system resources that it uses If an event that your client is waiting for occurs the FrameMaker product restarts your client by calling its F_ApiInitialize function with initialization set to FA_Init_Subsequent A document report should always bail out after it completes processing because the API initializes it each time the user chooses it from the Document Reports dialog box A filter should always bail out after it filters a file because the API initializes it each time a filterable file is opened imported or saved FDK Programmer s Guide 15 ae API Client Initialization For more information on F_ApiBailOut see F_ApiBailOut on page 48 of the FDK Programmer s Reference Disabling the API The user can disable all API clients before starting the FrameMaker product On UNIX platforms the user can disable all clients by specifying noapi ina resource file or when starting the FrameMaker product from the command line On Windows platforms the user can disable all clients by changing the API On setting inthe maker ini file to API Off On the Macintosh the user can disable clients by dragg
547. r set the text size to 10 points KBD_OPEN The user chose Open KBD_INPUT The user typed some text KBD_ALIGN The user chose Align For a complete list of f codes see the fcodes h file shipped with the FDK If a user action is associated with a text string the API passes the string to the sparm parameter of your client s F_ApiNotify function For example when the user types text the API sets sparm to the text the user typed The following table lists some f codes and the strings that are associated with them F code Associated string that the API passes to sparm PGF_APPLY_TAG The name of the paragraph format the user applied CHAR_APPLY_TAG The name of the character format the user applied KBD_INPUT The text the user typed It can be one or more characters depending on how fast the user types TXT_FAMILY_AND_VARIATION The name of the font family the user chose Your client can cancel any action for which it receives the FA_Note_PreFunction notification by calling F_ApiReturnValue with retVal set to FR_CancelOperation Your client can even cancel text entry For example the following code intercepts any text the user attempts to type in a document and prints it to the console FDK Programmer s Guide 39 a Creating Your Client s User Interface 40 include fcodes h Turn on notification F_ApiNotification FA_Note_PreFunction True VoidT F_ApiNotify notification docId sparm iparm IntT not
548. r the contents of the specified file into the new document The client can use Frame API calls such as F_ApiAddText and F_ApiNewTable to add content to the document For more information on adding text and objects to a document see Chapter 6 Manipulating Text and Chapter 8 Creating and Deleting API Objects The FrameMaker product allows users and clients that call F_ApiImport to specify into which flow of a document to import The user or client can specify any flow in the document A filter client should generally filter a file into the main flow of the document it creates However it can filter the file into any flow in the document For more information on main flows see Main flows on page 297 Call F_ApiReturnValue to indicate whether the file was successfully filtered If the client successfully filters the file it should call F_ApiReturnValue docId where docidis the ID of the Frame document the filter created If the client fails it should call F_ApiReturnValue 0 When the client s F_ApiNotify callback returns the FrameMaker product checks the value set by the F_ApiReturnValue call If the value set by the F_ApiReturnValue callis 0 the FrameMaker product displays an alert notifying the user that the file could not be opened or imported If the value set by the F_ApiReturnValue call is the ID of the new document the client created what the FrameMaker product does depends on how the fil
549. rame documents and their components and shows how the Frame API represents them Documents A document is a set of pages with graphic objects and text that the user creates with FrameMaker and stores in a file What the user sees When you create a new document you can use a template to create it or you can create a custom document Any document can be a template Because the FrameMaker product copies everything from a template to a new document most users prefer to use templates containing only layout and formatting information FrameMaker provides ready made templates for a variety of document types You can t create a document completely from scratch the document must have a certain set of default objects for the FrameMaker product to work correctly To ensure that all documents have this set of objects the FrameMaker product always uses a template to create a new document Even if you choose the Custom document option the FrameMaker product creates the new document from a default template On UNIX platforms this template is named NewTemplate and is located in S FMHOME fminit UILanguage CustomDocs where UlLanguage is the language in use On the Macintosh the template is part of the data fork of the FrameMaker product application If there is a template located in the appropriate folder the FrameMaker product uses it instead On Windows platforms the custom document template is specified in the maker ini file For more informat
550. rammarCmdId F_ApiDefineCommand GRAMMAR_CMD Grammar Grammar GG F_ApiAddCommandToMenu editMenuld grammarCmdIqd F_ApiAddCommandToMenu utilsMenulId grammarCmdId You can also use F_ApiAddCommandToMenu to add FrameMaker defined commands to multiple menus For example the following code adds the Compare Documents command to the Edit and Utilities menus F_ObjHandleT editMenulId compareCmdId UtilsMenuld compareCmdId F_ApiGetNamedObject FV_SessionId FO_Command DocCompare editMenuld F_ApiGetNamedObject FV_SessionId FO Menu EditMenu UtilsMenulId F_ApiGetNamedObject FV_SessionId FO_Menu UtilitiesMenu F_ApiAddCommandToMenu editMenuld compareCmdIqd F_ApiAddCommandToMenu UtilsMenulId compareCmdId A user s menu configuration file can also add a FrameMaker or a client command to several menus For example the following lines of a menu configuration file add a client defined command named Grammar to the Edit and Utilities menus lt Command Grammar gt lt Add Grammar lt Menu EditMenu gt gt lt Add Grammar lt Menu UtilitiesMenu gt gt Removing menus and menu items To remove a menu or menu item call F_ApiDelete with the first parameter set to the ID of the menu that contains the menu or menu item and the second parameter set to the ID of the menu or menu item F_ApiDelete deletes a menu or menu item from only the menu you specify If a menu
551. raph FIGURE 14 21 Body page with conditional and unconditional text If you hide the text the body page appears as shown in Figure 14 22 Marker text 95675 Marker text 93024 FIGURE 14 22 Body page with the conditional text hidden If you could see the hidden page and the text in the HIDDEN flow it would appear as shown in Figure 14 23 The numbers in the markers that represent the hidden conditional text on the body page correspond to the numbers in the markers on the hidden page Marker text 84974 This whole paragraph is conditional 4 Marker text 84974 Marker text 95675 fonditional Marker text 95675 Marker text 93024 f his paragraph is also conditional Marker text 93024 FIGURE 14 23 Hidden conditional text on the hidden page FDK Programmer s Guide Frame Document Architecture 14 Markers Markers are anchored objects that store data and associate that data with specific locations in the text Various features in FrameMaker may refer to a marker or you can use markers to store data for your FDK clients What the user sees You can use markers to mark entries for a table of contents or an index A marker s position in text is indicated by a marker symbol A marker contains text which appears in the Marker window when you select the marker and choose Marker from the Special menu Any number of marker types can be defined for a document 11 of them are predefined by
552. raph format tag if the change list specifies one A change list has one property for each paragraph format property it changes For example if it changes only the first indent it has the properties described above and just an FP_FirstIndent property If it changes the space below and the leading it has the properties described above and the FP_SpaceBelow and FP_Leading properties If a change list changes a paragraph property to an absolute value the property it uses has the same name as the corresponding paragraph format property for example FP_FirstIndent If the change list changes a property with a relative value the property it uses has the name of the corresponding paragraph format property with the word Change appended to it for example FP_First IndentChange For example the format rule clause in the element definition in Figure 14 35 on page 343 includes an unnamed change list The following table lists the change list s properties Property Type Value FP_Name StringT NULL FP_NextFmtChangeListInDoc F_ObjHandleT ID of the next FO_FmtChangeList object in the document FP_PgfCatalogReference StringT NULL FP_AutoNumString StringT b t Structural elements Structured FrameMaker documents contain structural elements which are instances of structural element definitions What the user sees Each structural element is a component of a document A structural element can consist of one or more paragraphs a te
553. raphic R 576 view G 284 G 288 R 576 to R 578 view only R 578 to R 579 See also documents document reports G 5 bailing out G 15 initializing G 15 document structure properties G 284 R 566 document window scrolling to a specified text range R 276 to R 277 document windows manipulating G 97 documents G 279 to G 348 active G 10 G 83 G 274 G 275 adding body pages to G 11 G 289 API representation of G 275 G 288 clearing change bars in function for R 7 closing G 66 to G 67 function for R 6 R 61 to R 62 comparing G 68 to G 70 function for R 6 R 65 to R 66 component of books G 351 creating G 53 to G 57 G 279 functions for G 53 G 56 R 6 R 70 to R 72 R 238 to R 244 R 325 to R 326 custom G 55 to G 56 G 57 delaying reformatting of G 97 destroying items in G 143 displaying particular pages of G 99 formatting G 70 to G 74 G 96 functions for G 77 R 7 R 25 functions applicable to R 6 to R 7 getting the pathname of G 97 importing formats from G 72 function for R 7 R 192 to R 197 R 323 to R 325 importing Frame product documents main flow of G 232 properties for table R 124 information included in table G 280 to G 281 FDK Programmer s Reference amp Guide landscape G 57 making active G 95 making invisible G 98 master pages for G 289 G 292 next API indication of G 83 open API indication of G 83 G 275 getting the IDs of G 83 to G 84 illustrated G 275 to G 276 opening with F_ApiOpen G 48 to G 53
554. rated R 520 spot colors G 338 square roots function for returning R 491 static memory allocation in UNIX G 379 status bars setting G 98 index 27 oe Index Subjects status bits function for checking R 6 R 52 to R 53 status flags for FS_ImportStatus table R 195 to R 196 when books F_ApiSave function for printing R 4 when importing documents or books F_Apilmport function for printing R 4 R 250 when opening documents or books F_ApiOpen R 240 to R 243 function for printing R 4 R 250 to R 251 when saving documents or books F_ApiSave R 273 to R 274 function for printing R 4 R 253 when updating books F_ApiUpdateBook R 339 function for printing R 255 to R 256 straddling cells G 75 to G 79 G 337 to G 338 API representation of G 337 to G 338 function for R 22 R 331 to R 332 illustrated G 338 string functions G 381 R 18 to R 20 R 440 to R 465 allocating space for G 381 specifying string size in G 381 See also string lists strings string library FDE See string functions string list library FDE G 381 G 382 string lists data type for G 382 FDE functions for G 381 allocating new G 382 R 474 appending strings to G 382 R 466 concatenating R 466 copying R 468 copying strings from R 467 freeing strings in R 469 inserting strings into G 382 R 472 positioning strings in R 476 removing strings from R 475 returning first strings in R 469 R 471 returning last strings in R 473 returning specified
555. reating graphic objects on page 146 To remove an object from a group set the object s FP_GroupParent property to 0 FDK Programmer s Guide 101 ee Getting and Setting Properties 102 Copying properties from one graphic object to another Each type of graphic object has a number of properties such as FP_Fill and FP_BorderWidth which are common to all graphic objects Some of these properties don t manifest themselves for all graphic objects For example rectangles have an FP_ArrowType property although they don t have arrowheads For a list of properties common to all graphic objects see Common graphics properties on page 592 of the FDK Programmer s Reference You canuse F_ApiGetProps and F_ApiSetProps to copy common properties from one graphic object to another as shown in the example in Getting and setting property lists on page 92 When you copy properties from one graphic object to another the objects do not have to be the same type For example you can copy the properties from a line to a rectangle The API copies only the common properties leaving properties that are specific to the rectangle such as FP_RectangleIsSmoothed intact Getting and setting paragraph properties The following sections describe useful tasks you can perform by getting and setting paragraph properties Applying paragraph and Paragraph Catalog formats Paragraph FO_Pgf objects and Paragraph Catalog format FO_
556. rences are valid For example if you change the page numbering properties you must update the book to ensure cross references indicate the correct numbering You can update a book via the F_ApiUpdateBook command or the F_ApiSimpleGenerate command With F_ApiUpdateBook you can specify aspects of the Update operation such as whether to update books with view only documents You can specify all aspects of the operation or you can specify some aspects and allow the user to decide others For example you can instruct the FrameMaker product to post an alert if the book contains a MIF file To use F_ApiUpdateBook you should first understand property lists and how to manipulate them directly For more information on this subject see Representing object characteristics with properties on page 270 and Manipulating property lists directly on page 93 The syntax for F_ApiUpdateBook is 356 FDK Programmer s Guide Frame Book Architecture io ErrorT F_ApiUpdateBook F_ObjHandleT bookId F_PropValsT updateParamsp F_PropValsT updateReturnParamspp This argument Means docId The ID of the document or book to save updateParamsp A property list that tells the FrameMaker product how to update the book and how to respond to errors and other conditions Use F_ApiGetUpdateBookDefaultParams or F_ApiAllocatePropVals to create and allocate memory for this property list To use the default list specify NU
557. res a pointer to a property list in returnParamspp This property list provides information on how the FrameMaker product saved the file It includes the properties shown in the following table FDK Programmer s Guide Executing Commands with API Functions 4 Property Meaning and Possible Values FS_SavedFileName A string that specifies the saved file s pathname FS_SaveNativeError The error condition If the file is saved successfully it is set to FE_Success For a complete list of the other values it can be set to see F_ApiSave on page 272 of the FDK Programmer s Reference FS_SaveStatus A bit field indicating what happened when the file was saved For a complete list of the possible status flags see F_ApiSave on page 272 of the FDK Programmer s Reference The FS_SaveNativeError property andthe FA_errno value indicate the result of the callto F_ApiSave The FS_SaveStatus flags indicate how or why this result occurred To determine if a particular FS_SaveStatus bit is set use F_ApiCheckStatus For example the following code determines if a Save operation was canceled because the current FrameMaker document was already open F_PropValsT params returnParamsp NULL F_ObjHandleT mydoclId Get the ID of the active document mydocId F_ApiGetId 0 FV_SessionId FP_ActiveDoc params F_ApiGetSaveDefaultParams F_ApiSave mydocId tmp my doc amp params amp returnParamsp
558. rmation on writing client filters see Writing filter clients on page 239 For more information on registering filters see the FDK Platform Guide for your platform Adding the F_ApiNotify callback The FrameMaker product notifies your client of events for which it has requested notification by calling its F_ApiNotify function Your client should define F_ApiNotify as follows VoidT F_ApiNotify notification docId sparm iparm IntT notification F_ObjHandleT docId StringT sparm IntT iparm Code that responds to notifications goes here This argument Means notification A constant that indicates the event and the notification point see the table on page 35 for a list of some constants docId The ID of the active document when the event occurs For filters the document into which the filter should import its data if this is zero the filter must create a new document FDK Programmer s Guide Creating Your Client s User Interface a This argument Means sparm The string if any associated with the notification For example if the notification is for an Open or Save sparm specifies the pathname of the affected file If the notification is for text entry sparm specifies the text the user typed Depending on how fast the user is typing sparm may specify one or several characters at a time iparm The integer associated with the notification For example if notification is FA_NotePreF
559. roperties of paragraph formats FO_PgfFmt R 623 of paragraphs FO_Pgf R 613 to R 614 B bailing out of API clients G 15 G 43 to G 44 R 48 defined G 389 function for R 11 R 24 R 48 basename of a specified filepath R 376 to R 377 batching changes G 96 big endian byte order G 382 R 438 binary files and Frame DRE files G 178 importing as text G 229 bit flags See flags FDK Programmer s Reference amp Guide body pages G 288 adding to documents G 11 G 149 to G 150 G 289 function for R 220 to R 221 API representation of G 289 defined G 389 organization of objects on G 290 illustrated G 290 properties of G 291 to G 292 R 610 See also pages book components G 351 creating G 355 to G 356 R 212 to R 213 function for adding to documents R 220 to R 221 as organized in books G 354 to G 355 properties of G 351 to G 355 R 503 to R 514 structure properties of R 514 book structure properties R 503 books G 275 G 351 to G 362 active G 274 G 275 Adobe Acrobat properties R 498 API representation of G 351 to G 355 illustrated G 355 checking the Update status of G 359 to G 360 closing G 66 to G 67 function for R 2 R 61 to R 62 comparing G 68 to G 70 function for R 2 R 65 to R 66 components of G 351 creating G 146 G 355 to G 356 documents as set up in G 351 error log G 360 to G 362 functions applicable to R 2 general properties R 495 to R 496 generating files for G 71 function for R 2 R 321 to R 322 importing formats from do
560. roperties dialog box appears displaying the properties of the dialog box You can specify the following properties for a dialog box e The order of the items in the dialog box e The title of the dialog box e The item initially highlighted or selected by the cursor called the first focus of the dialog box e The button activated by pressing the Return key called the default button e The items that act as the OK Cancel and Help buttons e The size and position of the dialog box note that modal dialog boxes are always positioned in the center of the screen The Item Order list in the Dialog Box Properties dialog box displays a list of all the dialog items in the DRE file Each dialog item is associated with an item number Note the item number of each dialog item You use these item numbers to identify dialog items in your client code FDK Programmer s Guide 193 Creating Custom Dialog Boxes for Your Client 194 2 TextBox 0 3 ImagePopUr 4 Label 2 5 PopUp 6 Box 29 8 Label 9 ScrollBox 23 10 Label 11 MultiLine 30 2 13 Label 31 15 RadioButto 16 TextBox 17 RadioButtor 314 0 pt 44 0 pt 18 ImagePopU 19 Label 239 0 pt 44 0 pt 20 Label 21 TextBox 22 Scrollbar 23 Scrollbar 24 CheckBox 25 CheckBox 26 ImagePopU FiguRE 10 11 Properties of a dialog box Specifying the focus order When the user selects an item in a dialog box except a label or a box the item becomes the focus of the dialog box For ex
561. roperties provide the following categories of information about the session System information such as the operating system the current FrameMaker product version and the current directory The automatic save settings Names of fonts available on the system IDs of the objects that represent open and active documents and books Whether the FrameMaker product reformats and redisplays documents after changes have been made FDK Programmer s Guide Frame Session Architecture 13 e Whether element reformatting and validation is turned on for FrameMaker structured documents Suppose you start FrameMaker on an X Window System platform and open a document named mydoc The API represents this session with an FO_Session object The following are some of its properties Property Type Value FP_ProductName FT_String FrameMaker FP_VersionMajor FT_Integer 5 FP_WindowSystem FT_String X Windows FP_AutoSaveSeconds FT_Integer 300 FP_ActiveDoc FT_Id ID of the object that represents mydoc How the API indicates which documents and books are open The API represents a document with an FO_Doc object The API maintains a linked list of the FO_Doc objects that represent a session s open documents The FO_Session property FP_FirstOpenDoc specifies the ID of the first FO_Doc object in the list The FO_Doc property FP_NextOpenDocInSession specifies the ID of the next FO_Doc object in the list The list of FO_Doc objects that represent ope
562. roperty FO_Element R 643 FP_ContentNeededAtEnd property FO_Element R 644 FP_ContextLabel property FO_Element R 638 FP_ContextLabel property FO_FmtRuleClause G 346 R 590 FP_CountElements property FO_FmtRule R 590 FP_CurrentMenuSet property FO_Menu G 169 FP_CurrentMenuSet property FO_Session R 632 FP_CurrentPage property FO_Doc G 99 G 291 R 538 R 576 FP_CustomElementList property FO_Book R 503 FP_CustomElementList property FO_Doc R 566 R 567 FP_Cyan property FO_Color R 519 FP_Dash property FO_GraphicObject R 593 R 595 FP_DefaultExclusions property FO_Doc R 566 FP_DefaultInclusions property FO_Doc R 566 FP_Dictionary property FO_Doc R 546 FP_Displaying property FO_Session G 96 G 97 R 263 R 632 FP_DisplayName property FO_Session R 632 FP_DocAcrobatColumnArticleThreads property FO_Book R 499 FP_DocAcrobatColumnArticleThreads property FO_Doc R 542 FP_DocAcrobatDefaultsChanged property FO_Book R 499 FP_DocAcrobatDefaultsChanged property FO_Doc R 542 FP_DocAcrobatElementList property FO_Book R 499 FP_DocAcrobatElementList property FO_Doc R 542 FP_DocAcrobatElements property FO_Book R 499 FP_DocAcrobatElements property FO_Doc R 542 FP_DocAcrobatNoArticleThreads property FO_Book R 499 R 542 FP_DocFluidFlow property FO_Doc R 578 FP_DoclIsDoubleSided property FO_Doc R 559 FP_DoclsHelp property FO_Doc R 546 FP_DoclIsModified property FO_Doc R 547 FP_DoclIsViewOnly
563. roperty FO_Doc R 567 FP_MaxInterlinePadding property FO_Flow R 559 R 580 FP_MaxInterPgfPadding property FO_Flow R 559 R 580 FP_MaxJLetSpace property FO_FmtChangeList R 583 FP_MaxJLetSpace property FO_Pgf R 613 FP_MaxJLetSpace property FO_PgfFmt R 622 FP_MaxJRomSpace property FO_FmtChangeList R 583 FP_MaxJRomSpace property FO_Pgf R 613 FP_MaxJRomSpace property FO_PgfFmt R 622 FP_MaxLeading property FO_Doc R 567 FP_MaxLeftIndent property FO_Doc R 567 FP_MaxLeftMargin property FO_Doc R 567 FP_MaxRightIndent property FO_Doc R 567 FP_MaxRightMargin property FO_Doc R 567 FP_MaxSpace property FO_FmtChangeList R 583 FP_MaxSpace property FO_Pgf R 621 FP_MaxSpace property FO_PgfFmt R 629 FP_MaxSpaceAbove property FO_Doc R 567 FP_MaxSpaceBelow property FO_Doc R 567 FP_MaxSpread property FO_Doc R 567 FP_MaxStretch property FO_Doc R 567 FP_MaxTabPosition property FO_Doc R 567 FP_MaxTopMargin property FO_Doc R 567 FP_MaxTracking property FO_Doc R 567 FP_MaxVal property FO_DlgScrollBar R 536 FP_MenuBar property FO_Doc R 557 FP_MenultemIsEnabled property FO_Command G 174 R 523 FP_MenultemIsEnabled property FO_Menu G 174 R 523 FP_MenultemIsEnabled property FO_MenultemSeparator G 174 R 523 FP_MenultemType property FO_Command R 526 FP_MenuType property FO_Menu R 528 FP_MinBottomMargin property FO_Doc R 567 index 56 FP_MinFirstIndent property FO_Doc R 567
564. roperty Meaning and possible values FS_OpenedFileName A string that specifies the opened file s pathname If you scripted FS_ShowBrowser or the file was filtered or you didn t specify the pathname this pathname can be different from the one you specified in the Open script FS_OpenNativeError The error condition If the file is opened successfully it is set to FE_Success For a complete list of the other values it can be set to see F_ApiOpen on page 238 of the FDK Programmer s Reference FS_OpenStatus A bit field indicating what happened when the file was opened For a complete list of the possible status flags see F_ApiOpen on page 238 of the FDK Programmer s Reference The FS_OpenNativeError property andthe FA_errno global variable indicate the result of acallto F_ApiOpen The FS_OpenStatus flags indicate how or why this result occurred For example if you attempt to open a file with F_ApiOpen and the Open operation is canceled FS_OpenNativeError and FA_errno are setto FE_Canceled If the operation was canceled because the user canceled it the FV_UserCanceled bit of the FS_OpenStatus property list is set The API provides a function named F_ApiCheckStatus which allows you to determine if a particular FS_OpenStatus bit is set The syntax for F_ApiCheckStatus is IntT F_ApiCheckStatus F_PropValsT p IntT statusBit This argument Means p The openReturnParamspp property list return
565. rst graphic object in the list of its graphic objects and its FP_FirstBodyPagelInDoc property specifies the first body page in the list of its body pages Except for the lists of pages the lists are completely unordered For example the first graphic object in the list of graphic objects is not necessarily the first graphic that appears in the document Suppose you want to traverse the list of all the paragraphs in the active document To do this you can use the following code include futils h F_ObjHandleT docId pgfId UCharT msg 256 Get the ID of the active document docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc Get ID of the first paragraph in the list of paragraphs pgfId F_ApiGetId FV_SessionId docId FP_FirstPgfInDoc Traverse the list of paragraphs and display their IDs Even empty documents have several paragraphs because text columns on master pages contain paragraphs y while pgfId F_Sprintf msg The paragraph s ID is 0x x pgfId F_ApiAlert msg FF_ALERT_CONTINUE_NOTE pgfId F_ApiGetId docId pgfId FP_NextPgfInDoc The paragraphs in the list are not ordered Traversing lists of graphic objects The API does not maintain separate lists of the different types of graphic objects in a document For example a document s text columns FO_TextFrame objects rectangles FDK Programmer s Guide Getting and Setting Properties 5
566. rst opens the dialog box e Default button The default button is a button the user can activate by pressing the Return key e OK button The OK button is the button that performs an action and dismisses the dialog box e Cancel button If you are creating a modal dialog box identify a Cancel button If the user closes the dialog box by clicking its close box on the Macintosh pressing Control w on Windows or pressing Control c on UNIX platforms the dialog box activates the Cancel button Useful Items Title Label 0 First Focus 2 Default Button 31 OK Button 31 Cancel Button j2 FIGURE 10 14 Specifying the basic items in a dialog box To specify any of these items type the item number in the appropriate text box For example to specify the Cancel button as item 4 type 4 in the Cancel Button text box If a dialog box doesn t use one of these items type 1 in the text box for the item For example to create a dialog box with no Help button type 1 in the Help Button text box Specifying the size and position of a dialog box You can change the properties of a dialog box that specify its initial size and position You can also adjust the size of the dialog box manually by selecting its rectangle and dragging the handles Size Offset From Frame Width 404 0 pt Top 10 0 pt Height 227 0 pt Left 10 0 pt FiguRE 10 15 Specifying the size and position of a dialog box 196 FDK Programmer s
567. rt boxes To display a dialog box with a short message use F_ApiAlert The syntax for F_ApiAlert is IntT F_ApiAlert StringT message IntT type This argument Means message The message that appears in the alert box type The type of alert box FDK Programmer s Guide 17 se Creating Your Client s User Interface Specify one of the following values for the type argument 18 type constant FF_ALERT_OK_ DEFAULT Type of dialog box displayed Displays OK and Cancel buttons OK is the default FE ALERT_CANCEL_DEFAU FF ALERT_CONTINUE_NOTF FF ALERT _CONTINUE_WARN FE ALERT _YES_ DEFAULT EF ALERT _NO_DEFAULT iT Displays OK and Cancel buttons Cancel is the default Displays Continue button Displays Continue button with a warning indication Displays Yes and No buttons Yes is the default Displays Yes and No buttons No is the default F_ApiAlert returns 0 if the user clicks OK Continue or Yes otherwise it returns a nonzero value Example The following code displays the alert box shown in Figure 3 1 IntT err BLE F_ApiAlert StringT This alert is an OK_DEFAULT FIGURE 3 1 FF_ALERT_OK_DEFAULT FF_ALERT_OK_DEFAULT alert box Using string integer and metric input dialog boxes To prompt the user for a single string integer or metric value use F_ApiPromptString
568. rty FO_DlgTriBox R 537 FP_Visibility property FO_ScrollBar R 536 FP_Visibility property FO_ScrollBox R 537 FP_VolrNumComputeMethod property FO_BookComponent R 513 FP_VolrNumComputeMethod property FO_Doc R 548 FP_VolumeNumber property FO_BookComponent R 513 FP_VolumeNumber property FO_Doc R 548 FP_VolumeNumStyle property FO_BookComponent R 514 FP_VolumeNumStyle property FO_Doc R 549 FP_VolumeNumtText property FO_BookComponent R 514 FP_VolumeNumText property FO_Doc R 549 FP_WesternFamily property FO_CombinedFontDefn R 522 FP_WesternFontPlatformName property FO_CharFmt R 516 FP_WesternFontPostScriptName property FO_CharFmt R 516 FP_WesternShift property FO_CombinedFontDefn R 522 FP_WesternSize property FO_CombinedFontDefn R 522 FP_WideRubiSpaceForKanji property FO_Doc R 564 FP_WideRubiSpaceForOther property FO_Doc R 564 FP_Width property F_ApiSetMetric G 99 FP_Width property FO_Doc G 97 FP_Width property FO_GraphicObject G 3 G 263 R 595 FP_Width property FO_Rectangle G 3 FP_Width property FO_Row R 652 FP_Width property FO_SubCol R 521 FP_Width property text location R 671 FP_WindowSystem property FO_Session R 637 FP_XmIDocType property FO_Book R 505 R 569 FP_XmlEncoding property FO_Doc R 569 FP_XmlPublicId property FO_Book R 505 R 570 FP_XmlStandalone property FO_Book R 506 FP_XmlStandalone property FO_Doc R 570 FP_XmlStyleSheet property FO_Book
569. rty FO_GraphicObject R 594 FP_LocX property FO_Row R 651 FP_LocX property FO_SubCol R 521 FP_LocX property text location R 670 FP_LocY property F_ApiSetMetric G 100 FP_LocY property FO_Doc G 97 FP_LocY property FO_GraphicObject R 594 FP_LocY property FO_Row R 651 FP_LocY property FO_SubCol R 521 FP_LocY property text location R 670 FP_Magenta property FO_Color R 519 FP_MainFlowInDoc property FO_Doc G 283 R 540 FP_MakeVisible property F_ApiOpen G 98 FP_MarkerNames property FO_Session R 635 FP_MarkerText property FO_Marker G 320 R 608 FP_MarkerType property FO_Marker G 320 R 609 FP_MarkerTypeld property FO_Marker R 609 FP_MarkerTypeNames property FO_Doc G 320 R 540 FP_MasterPage property FO_BodyPage R 610 FP_MatchingContextInUserString property FO_Element R 641 FP_MatchingFirstPgfClauses property FO_Element R 639 FP_MatchingLastPgfClauses property FO_Element R 639 FP_MatchingObjectClauses property G 108 FP_MatchingObjectClauses property FO_Element R 639 FP_MatchingPrefixClauses property FO_Element R 640 index 55 os Index Reserved Names FP_MatchingSuffixClauses property FO_Element R 640 FP_MatchingTextClauses property G 108 FP_MatchingTextClauses property FO_Element R 640 FP_MathFullForm property FO_Math R 603 FP_MathSize property FO_Math R 603 FP_MaxBottomMargin property FO_Doc R 567 FP_MaxFirstIndent property FO_Doc R 567 FP_MaxFontSize p
570. rty FO_Session G 83 G 275 R 631 FP_ActiveDoc property FO_Session G 10 G 83 G 95 G 275 R 631 FDK Programmer s Reference amp Guide FP_AddMarkerTypeToStandardMarkers property FO_Session R 632 FP_AdjHyphens property FO_FmtChangeList R 582 FP_AdjHyphens property FO_Pgf R 617 FP_AdjHyphens property FO_PgfFmt R 625 FP_AFramelsCropped property FO_AFrame R 596 FP_AFramelsFloating property FO_AFrame R 596 FP_Alignment property FO_AFrame R 596 FP_AllowAsSpecialCase property FO_Element R 643 FP_AlsolInsert property FO_ElementDef R 645 FP_AnchorType property FO_AFrame R 596 FP_Angle property FO_GraphicObject R 592 FP_ApplyFmtRules property G 110 FP_ApplyFormatRules property FO_Session G 110 R 631 FP_ArrowBaseAngle property FO_GraphicObject R 592 FP_ArrowLength property FO_GraphicObject R 592 FP_ArrowScaleFactor property FO_GraphicObject R 592 FP_ArrowScaleHead property FO_GraphicObject R 593 FP_ArrowTipAngle property FO_GraphicObject R 593 FP_ArrowType property FO_GraphicObject R 593 FP_AttrDisplay property FO_Element R 638 FP_AttributeDefs property FO_ElementDef R 645 FP_Attributes property FO_Element R 638 FP_Attribute ValueInvalid property FO_Element R 643 FP_AutoBackup property FO_Session R 632 FP_AutoChangeBars property FO_Doc R 549 FP_AutoNumChar property FO_FmtChangeList R 584 FP_AutoNumChar property FO_Pgf R 613 FP_AutoNumChar property FO_PgfFmt R 623
571. rule of an element definition or as a subformat rule of a format rule clause For a complete list of the properties with which you can associate new format rule objects see F_ApiNewSubObject on page 221 of the FDK Programmer s Reference The following code creates a prefix rule and adds it to the Quotation element definition so that the element definition appears as shown in Figure 8 1 FDK Programmer s Guide Creating and Deleting API Objects F_ObjHandleT docId quoteEdefId prefixRulelId clauseld Get ID of Para element definition docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc quoteEdefId F_ApiGetNamedObject docId FO_ElementDef Quotation Add the prefix format rule prefixRuleId F_ApiNewSubOb ject docId quoteEdefId FP_PrefixRules Set the rule type F_ApiSetInt docId prefixRuleId FP_FmtRuleType FV_CONTEXT_RULE Add rule clause to suffix rule 322 is left quote clauselId F_ApiNewSubObject docId prefixRuleld FP_FmtRuleClauses F_ApiSetInt docId clauseId FP_IsTextRange True F_ApiSetString docId clauseId FP_ElemPrefixSuffix 322 Element Container Quotation General rule lt Text gt Text format rules 1 In all contexts Text range No additional formatting Prefix rules 1 Inall contexts Prefix Text range FIGURE 8 1 Quotation element definition To create a named format change list
572. rwise it passes Roman to F_FdelInitFontEncs Example FontEncIdT feld StringT encName F_FdeInit encName F_ApiGetString 0 FV_SessionId FP_DialogEncodingName if F_StriEqual encName JISX0208 ShiftJIS F_StrIEqual encName GB2312 80 EUC F_FdeInitFontEncs ConStringT encName feld else feId F_FdeInitFontEncs ConStringT FrameRoman Getting the encoding for fonts Font families and individual fonts have associated encodings The possible encodings are Value Means FrameRoman Roman text JISX0208 ShiftJIs Japanese text BIG5 Traditional Chinese text GB2312 80 EUC Simplified Chinese text KSC5601 1992 Korean text Multiple More than one encoding for the font family If the returned encoding is Multiple the font family has different encodings for its different variations In that case you must get the encoding for each variation Non text fonts may return FrameRoman or they may return the family name of the font For example on some platforms the encoding for the Symbol font family is indicated by the string Symbol Getting the encoding for a font family To get the encoding for a font family first get a list of font families then loop through that list to get the index of the family you want Then you pass the index to F_ApiGetEncodingForFamily The syntax for F_ApiGetEncodingForFamily is FDK Programmer s Guide 135 Manipulating Asian Text 1
573. s StringT Integer 1234 if err F_Sprintf msg StringT Cancelled ires has no value else F_Sprintf msg StringT The value of ires is d ires F_ApiAlert msg FF_ALERT_CONTINUE_NOTE Enter Value E er OK Cancel FIGURE 3 3 Integer prompt dialog box The following code displays the dialog box shown in Figure 3 4 define IN MetricT 65536 72 Default unit inches IntT err MetricT mres err F_ApiPromptMetric amp mres StringT Metric 12 34in IN 20 FDK Programmer s Guide Creating Your Client s User Interface a FIGURE 3 4 Metric prompt dialog box Using file selection dialog boxes To display dialog boxes similar to the FrameMaker product s Open and Save dialog boxes use F_ApiChooseFile F_ApiChooseFile displays files and directories in a scrolling list and allows the user to choose a file or directory The syntax for F_ApiChooseFile is IntT F_ApiChooseFile StringT choice StringT title StringT directory StringT stuffVal IntT mode StringT helpLink This argument Means choice The selected pathname when the user clicks OK title The message that appears in the dialog box directory The default directory when the dialog box is first displayed If you specify an empty string the last directory used by your client is used If your client hasn t used any directories the directory specified by the ses
574. s d1g and extra dialog information files xdi files You compile these files with FDK client When FrameMaker creates these additional files it names these files after the DRE file For example in Windows versions saving the file named mydlg dre creates additional files named mydlg dlg and mydlg xdi In UNIX versions saving the file mydlg dre creates the X resource file named mydlg x FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client Macintosh versions of FrameMaker do not create any additional files During the build process you convert the DRE files into Macintosh resources which are placed in the resource fork of your FDK client In Windows and Macintosh clients the dialog resource is named after the base name of the DRE file the filename without the dre extension In UNIX clients the dialog resources are the generated X resource files When you open the dialog resource using the F_ApiOpenResource function use the name for the resource as an argument to the function The name of the resource is usually the base name of the DRE file For details on the process of including dialog boxes in your FDK client see the FDK Platform Guide for your platform For details on opening dialog resources and displaying dialog boxes see Opening dialog resources on page 217 Testing a dialog box In UNIX and Windows versions of FrameMaker you can test a dialog box while you are modifying it to verify
575. s is VoidT F_ApiDeallocatePropVals F_PropValsT pvp This argument Means pvp The property list Example The following code opens a document named tmp my doc It creates a property list that instructs F_ApiOpen to open the document as View Only and to display the title Doc in the title bar include fstrings h F_PropValsT params returnParamsp NULL F_ObjHandleT docId Allocate memory for Open scrip FDK Programmer s Guide Executing Commands with API Functions 4 with two properties params F_ApiAllocatePropVals 2 if params len 0 return Force title displayed on title bar to be Doc params val 0 propIdent num FS_NameStripe params val 0 propVal valType FT_String params val 0 propVal u sval StringT F_StrCopyString Doc Open the file as View Only params val 1 propIdent num FS_OpenDocViewOnly params val 1 propVal valType FT_Integer params val 1 propVal u ival True Open tmp my doc docId F_ApiOpen tmp my doc amp params amp returnParamsp Free memory used by the Open scripts F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp Creating documents To create a new document you can use the following functions e F_ApiSimpleNewDoc is an easy to use function that allows you to specify a template and interactive or noninteractive modes e F_Api
576. s R 195 FV_BadImportFileName status flag FS_ImportStatus R 195 FV_BadImportFileType status flag FS_ImportStatus R 195 FV_BadImportScriptValue status flag FS_ImportStatus R 195 FV_CancelFileDoc status flag FS_ImportStatus R 196 FV_CancelFileFilterable status flag FS_ImportStatus R 196 FV_CancelFileGraphic status flag FS_ImportStatus R 196 FV_CancelFileMacEdition status flag FS_ImportStatus R 196 FV_CancelFileMIF status flag FS_ImportStatus R 196 FV_CancelFileText status flag FS_ImportStatus R 196 FV_ChooseOpen mode constant R 54 FV_ChooseOpenDir mode constant R 54 FDK Programmer s Reference amp Guide FV_ChooseSave mode constant R 54 FV_ChooseSelect mode constant R 54 FV_CmdaAlert constant FP_HypertextParsedCmdCode R 555 FV_CmdaAlertTitle constant FP_HypertextParsedCmdCode R 555 FV_CmdError constant FP_HypertextParsedCmdCode R 555 FV_CmdExit constant FP_HypertextParsedCmdCode R 555 FV_CmdGoToLink constant FP_HypertextParsedCmdCode R 555 FV_CmdGoToLinkFitWin constant FP_HypertextParsedCmdCode R 555 FV_CmdGoToNew constant FP_HypertextParsedCmdCode R 555 FV_CmdGoToObjectId constant FP_HypertextParsedCmdCode R 555 FV_CmdGoToObjectIdFitWin constant FP_HypertextParsedCmdCode R 555 FV_CmdGoToPage constant FP_HypertextParsedCmdCode R 555 FV_CmdMatrix constant FP_HypertextParsedCmdCode R 555 FV_CmdMessage constant FP_HypertextParsedCmdCode R
577. s See document properties menus adding commands to G 26 G 27 to G 28 R 3 functions for R 35 to R 37 R 75 to R 77 R 81 adding keyboard shortcuts to G 26 adding menu items to G 26 G 27 to G 28 R 35 function for R 35 adding pull right menus to G 27 adding to menu bars G 13 G 27 R 37 functions for R 3 R 37 to R 39 R 77 to R 80 R 82 adding to other menus G 27 functions for R 3 R 37 to R 39 R 77 to R 80 R 82 adding to pop up menus G 27 API functions applicable to R 3 API representation of G 161 to G 163 arranging G 166 to G 170 R 3 arranging commands in function for R 35 arranging menu items in G 166 to G 170 R 3 changing the menu set G 169 checking for the existence of function for R 3 R 203 in the client user interface G 24 to G 31 creating G 158 functions for R 3 defining G 27 determining configuration of G 164 to G 166 determining existence of function for R 3 determining if a menu item is on function for R 203 to R 204 determining if on menu bar function for R 203 to R 204 getting IDs of G 24 to G 26 G 27 G 163 to G 164 function for R 3 getting properties of G 162 linked lists of G 162 loading custom menu files G 169 manipulating with the API _G 161 to G 176 multiple adding commands to G 166 to G 167 properties of R 523 R 528 pull down G 27 removing G 167 function for R 3 reordering G 168 to G 169 setting properties of G 162 See also Frame product menus messages ha
578. s any text that uses ghost encodings 142 FDK Programmer s Guide Creating and Deleting API Objects To create or destroy anything in a FrameMaker document you must create or destroy the object the API uses to represent it This chapter discusses how to create and destroy objects Before you use API functions to create and delete objects you need an understanding of how the Frame API organizes objects For background information on this subject see Part II Frame Product Architecture Creating objects The API provides different functions for creating different types of objects For example you use F_ApiNewTable to create tables and F_ApiNewSeriesObject to create objects that occur in ordered series The following table lists the API object types and the functions you use to create them To create objects of this type Use FO_Book F_ApiNewNamedOb ject FO_CharFmt FO_Color FO_CondFmt FO_ElementDef FO_FmtChangeList named FO_MasterPage FO_MenultemSeparator FO_PgfFmt FO_RefPage FO_RulingFmt FO_Tb1Fmt FO_VarFmt FO_XRefFmt FDK Programmer s Guide 143 az Creating and Deleting API Objects 144 To create objects of this type FO_Arc FO_Ellipse FO_Flow FO_Group FO_Inset FO_Line FO_Math FO_Polyline FO_Polygon FO_Rectangle FO_RoundRect FO_TextFrame FO_TextLine FO_UnanchoredFrame FO_AFrame FO_Fn FO_Marker FO_Rubi FO_Tbl FO_TiApiClient FO_BodyPage FO
579. s applicable to R 15 to R 17 of API objects R 495 to R 673 automatic updating of G 81 G 160 batching changes in G 96 copying G 102 R 297 data types for tables G 270 G 273 deallocating memory from G 94 R 11 function for R 11 defined G 3 G 390 getting G 7 G 37 G 89 to G 92 G 95 to G 105 G 389 API functions for table G 90 R 15 for menus and menu items G 162 getting values of function for R 190 to R 191 FDK Programmer s Reference amp Guide identifying G 272 structure for G 272 R 684 implicit changes in G 160 for import operations tables R 120 to R 127 manipulating G 89 to G 95 naming convention for G xiii R xix object changes possible with G 81 order of in property lists G 93 page G 289 to G 292 R 610 to R 612 printing values of specified function for R 251 to R 252 querying G 84 to G 89 function for R 15 R 190 to R 191 read only G 81 R 495 representing object characteristics with G 270 to G 274 setting G 7 G 37 G 45 G 89 to G 92 G 95 to G 105 API error protection feature G 81 API functions for G 89 R 15 to R 17 R 300 to R 301 of dialog boxes G 193 to G 195 G 208 of dialog items G 197 to G 204 G 208 individually G 89 to G 92 for menus and menu items G 162 steps for G 81 type in G 126 G 284 G 391 R 573 to R 575 See also document properties property lists property values individual types of properties generally under individual object types in this index See also individual properti
580. s arranged in rows and columns Tables can have titles and heading body and footing rows FrameMaker automatically repeats table titles and heading and footing rows on each page of a table Each cell in a table is actually a type of text frame It can contain text and nearly anything you insert in text such as an anchored frame or a marker You cannot insert another table directly into a table cell Like a paragraph each table has a tag and a format The tag is the name of a Table Catalog format A table format specifies the layout characteristics of a table such as its position in a text frame its alignment and the rulings and shadings of its columns and rows The table format can specify different rulings for the different types of rows for example the body heading and footing rows You can override a Table Catalog format by changing an individual table s format You can also override an individual table s format by specifying a custom ruling shading or color for an individual cell or set of cells in the table If you retag a table with a Table Catalog format after you have specified custom ruling for some of its cells it does not affect the custom ruling for those cells How the API represents tables The API represents a table anchor with an FTI_TblAnchor text item For more information on text items see How the API represents text on page 312 Each FTI_TblAnchor text item specifies the ID of an FO_Tb1 object The A
581. s long that describes the filter Hint strings for the standard installation of filters The following tables list the minimal hint strings for all the import and export filters that ship with FrameMaker on Windows and for importing and exporting text files The import and export filters lists were generated against the standard installation of filters for the US English version of FrameMaker 7 0 Your installation may not include all of these filters and you may 250 FDK Programmer s Guide the tables Windows hint strings Using Imported Files and Insets 12 have other filters installed For this reason a code example that generates these lists follows The following tables list hint strings for Windows filters Hint strings for import filters To use this import filter Corel Draw DIB Micrografx Drawing AutoCAD DWG AutoCAD DXF Windows Enhanced Metafile EPS EPSF PDF Frame Image Frame Vector CCITTG4 GEM GIF HPGL IGES JPEG PCX QuickDraw PICT Portable Network Graphics MacPaint Sun Raster File TIFF Windows Metafile Windows Metafile to Frame Vector Use this hint string 0001 IMAGCDR 0001FRAMDIB OOO1IMAGDRW 0001 IMAGDWG 0001IMAGDXF 0001FRAMEMF 0001FRAMEPSF 0001FRAMPDF 0001FRAMFRMI 0001FRAMFRMV OOO1IMAGG4IM O0001IMAGGEM OQ01FRAMGIF OOO1IMAGHPGL OOO1IMAGIGES OOO1IMAGJPEG 0001FRAMPCX 0001IMAGPICT
582. saveParamsp A property list that tells the FrameMaker product how to save the file and how to respond to errors and other conditions Use F_ApiGetSaveDefaultParams or F_ApiAllocatePropVals to create and allocate memory for this property list To use the default list specify NULL FDK Programmer s Guide Executing Commands with API Functions 4 This argument Means saveReturnParamspp A property list that returns information about how the FrameMaker product saved the file IMPORTANT Always initialize the pointer to the property list that you specify for saveReturnParamspp to NULL before you call F_ApiSave If F_ApiSave is successful it returns the ID of the document or book it saved If F_ApiSave performs a Save operation it returns the ID that you specified in the docId parameter If F_ApiSave performs a Save As operation it returns the ID of the new document or book If F_ApiSave can t save a file it returns O To call F_ApiSave do the following 1 Initialize the pointer to the saveReturnParamspp property list to NULL 2 Createa saveParamsp property list You can get a default list by calling F_ApiGetSaveDefaultParams or you can create a list from scratch 3 Call F_ApiSave 4 Check the Save status Check the returned values in the saveReturnParamspp list for the name of the saved file and other information about how the FrameMaker product saved the file 5 Deallocate the saveParamsp
583. sing functions from the FDE utility libraries you must also include the header files for these functions after fdetypes h For example you must include fstrlist h if you use any of the string list functions If you need to include other C library header files they must precede all FDE header files 6 Compile your client and link the FDK library with it The following sections describe Steps 2 3 and 4 in greater detail Replacing C primitive data types with FDE types To ensure portability across different platforms and compilers the FDE uses substitutes for C language primitive data types These types are defined in the _types h header file The following table lists the FDE data types and their equivalents FDE data type Equivalent type Size AddrT char void Unsigned 4 bytes BoolT long Signed 4 bytes ByteT char Signed byte CharT char Signed byte ConStringT const unsigned char Pointer ErrorT long Signed 4 bytes FunctionT Function pointer Unsigned 4 bytes returns IntT GenericT char void Signed 4 bytes IntT long Signed 4 bytes MetricT long Signed 4 bytes Nat iveDoubleT double Signed 4 bytes platform dependent FDK Programmer s Guide 367 16 Introduction to FDE FDE data type NativeIntT NativeCharT NativeULongT NativeLongT ProcedureT PByteT PCharT PRealT PShortT U UByteT U UCharT PUShortT RealT ShortT StrBuffT StringT U
584. sion property FP_OpenDir is used stuffval The default value that appears in the input field when the dialog box first appears If the dialog box type specified by mode doesn t have an input field this string is ignored mode A constant specifying the type of dialog box For a list of dialog box types see F_ApiChooseFile on page 53 of the FDK Programmer s Reference helpLink Obsolete in versions 6 0 and later pass an empty string The name of a document containing help information for the dialog box and an optional hypertext link IMPORTANT F_ApiChooseFile allocates memory for the string referenced by choice Use F_ApiDeallocateString to free the string when you are done with it Example To create the dialog box shown in Figure 3 5 add the following code to your client FDK Programmer s Guide 21 se Creating Your Client s User Interface 22 include futils h include fmemory h IntT err StringT sres UCharT msg 256 err F_ApiChooseFile amp sres StringT Choose a file StringT tmp StringT FV_ChooseSelect StringT if err F_Sprintf msg StringT Cancelled sres is not defined else F_Sprintf msg StringT The value of sres is s sres F_ApiAlert msg FF_ALERT_CONTINUE_NOTE if err F_ApiDeallocateString amp sres Choose a file cil fe 1Chapter f z 2Chapter fm Manual backup book Manual book e Manual2 book
585. spaces from R 482 removing trailing spaces from R 483 returning strings in string lists R 470 returning text tokens in R 485 FDK Programmer s Reference amp Guide returning the length of R 465 returning the length of double byte R 465 reversing characters in R 481 truncating R 486 truncating double byte strings R 487 prompting users for G 18 to G 20 R 260 function for R 5 R 260 to R 261 properties F_StringsT of function for getting R 16 R 160 to R 161 function for setting R 16 R 303 to R 305 properties StringT of function for getting R 16 R 158 to R 159 function for setting R 16 R 301 to R 303 structure for sets G 23 G 271 G 306 R 684 See also string lists structural element CSS properties R 641 structural element definition properties getting and setting G 108 structural element definitions G 269 G 281 G 342 G 348 API representation of G 281 G 343 to G 347 getting and setting properties G 108 importing G 77 function for R 322 and NoName elements R 347 properties of G 342 R 645 to R 647 structural element ID properties R 642 structural element Namespace properties R 643 structural element properties G 348 R 638 to R 644 general R 638 structural element range properties function for getting R 113 to R 115 function for setting R 282 to R 284 structural element validation properties R 643 to R 644 structural elements G 281 G 342 G 347 API representation of G 281 API representation of the beginning of G 314 R
586. splay F_ObjHandleT doclId For example to change a number of properties at once use code similar to the following 96 FDK Programmer s Guide Getting and Setting Properties 5 F_ObjHandleT docId F_ApiSetInt 0 FV_SessionId FP_Displaying False Change multiple properties here F_ApiSetInt 0 FV_SessionId FP_Displaying True F_ApiRedisplay docId Must be called for each document While FP_Displaying is set to False the FrameMaker product doesn t update the display at all In some cases you may want the FrameMaker product to update the display but to delay reformatting documents while you change them To do this set the FO_Session property FP_Reformatting to False After you have reset FP_Reformatting to True refresh the documents that you have changed by calling F_ApiReformat for each document Getting and setting document properties The following sections describe useful tasks you can perform by getting and setting document properties Getting a document s pathname A document s absolute pathname is specified by its FP_Name property The following code displays the active document s absolute pathname F_ObjHandleT docId StringT docName Get the document ID and name docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc docName F_ApiGetString FV_SessionId docId FP_Name F_ApiAlert docName FF_ALERT_CONTINUE_NOTE F_Free docName
587. ssage goes here This argument Means message The string from the hypertext command message docId The ID of the document containing the hypertext marker objid The ID of the hypertext marker the user clicked FDK Programmer s Guide Creating Your Client s User Interface Example Suppose you want to create a command palette with two arrows in it When the user clicks an arrow it changes the fill pattern of a selected graphic object in the active document To make this command palette create a document with the graphics shown in Figure 3 8 Next fill pattern FIGURE 3 8 Example hypertext markers Assuming your client is registered with the FrameMaker product as myapi insert the following hypertext markers into the document e Inthe text column around the up arrow message myapi 1 e Inthe text column around the down arrow message myapi 2 Save the document in View Only format To respond to the user clicking one of the arrows add the following code to your client define UPARROW 1 define DOWNARROW 2 VoidT F_ApiMessage message docId objId StringT message F_ObjHandleT docId F_ObjHandleT objId F_ObjHandleT targetDocId targetGraphiclId IntT fillpatt Get ID of active document Note that View Only documents are not considered active targetDocId F_ApiGetId 0 FV_SessionId FP_ActiveDoc FDK Programmer s Guide 33 a Creating Your Client s User Interface Get I
588. ssary By default the FDE assumes the channel and the platform are consistent If you do not specify whether the input or output channel order is little endian the functions do not swap bytes When you use the FDE I O functions you should take care of alignment issues yourself FDE T O functions return 0 if they reach the end of a file or an error occurs To use the FDE channel utility functions you must include fdetypes h and fioutils h in your program FDK Programmer s Guide FDE Utility Libraries 18 The hash library The hash library provides functions to create a hash table and manipulate the cells in it For example F_HashCreate creates a hash table F_HashSet adds an entry to a hash table and F_HashGet fetches an entry from a hash table All the functions in the library are prefixed by F_Hash To use any FDE hash functions you must include fdetypes h and fhash h in your program The hash table is stored in a data structure of type HashTableT This data structure is opaque to you you must use the F_Hash routines to manipulate a hash table Creating hash tables You create a hash table via F_HashCreate which is defined as follows HashT F_HashCreate StringT name Name of the table IntT minSize Minimum size of the table PShortT keyLen Size of keys GenericT notFound Returned if searched key not found Determine if cell can be reused BoolT deadQuery GenericT
589. st FO_PgfFmt object Paragraph example Catalog format in the lis tof FO_Pg fFmt objects in the document Each FO_PgfFmt object has a FP_NextPgfFmtInDoc property that specifies the next FO_PgfFmt object in the list If you want to get all the specified by FP_FirstPa FO_PgfFmt objects ina document you get the FO_PgfFmt object fFmtInDoc and traverse the links to the other objects Document object property FP_FirstGraphicInDoc FP_Firs FP_Firs FP_Firs FP_Firs FP_Firs FP_Firs FP_Firs FP_Firs tColorInDoc tPgfInDoc tMarkerInDoc tMarkerTypeInDoc tVarInDoc tVarFmt InDoc tXRefInDoc tXRefFmt InDoc Object that the property specifies The first graphic object for example FO_UnanchoredFrame or FO_Line in the list of graphic objects The first FO_Col objects The first FO_Pgf The first FO_Mar objects or inthe list of FO_Color in the list of FO_Pgf objects ker inthe listof FO_Marker The first FO_MarkerType in the list of marker types The first FO_Var The first FO_Var objects The first FO_XRe The first FO_XRe 1 objects in the list of FO_Var objects Fmt inthe list of FO_VarFmt f inthe listof FO_XRef objects fFmt inthe listof FO_XRefFmt FDK Programmer s Guide Frame Document Architecture 14 Document object property FP_FirstFnInDoc FP_FirstTblInDoc FP_FirstFlowInDoc FP_FirstPgfFmtInDoc FP_Fir
590. stCharFmt InDoc FP_FirstCondFmt InDoc FP_FirstTb1lFmtInDoc FP_FirstRulingFmt InDoc FP_FirstSelectedGraphicInDoc FP_MainFlowInDoc FP_FirstElementDefInDoc FP_FirstFmtChangeListInDoc FP_FirstBodyPageInDoc or FP_LastBodyPageInDoc FP_FirstMasterPageInDoc or FP_LastMasterPageInDoc FP_FirstRefPagelInDoc or FP_LastRefPageInDoc FP_HiddenPage FP_SelectedTbl FP_FirstTilInDoc FP_FirstRubilInDoc FP_FirstCombinedFontDefnInDoc Object that the property specifies The first FO_Fn inthe list of FO_Fn objects The first FO_Tb1 in the list of FO_Tb1 objects The first FO_Flow inthe listof FO_Flow objects The first FO_PgfFmt inthe list of FO_PgfFmt objects The first FO_CharFmt inthe listof FO_CharFmt objects The first FO_CondFmt in the list of FO_CondFmt objects The first FO_Tb1Fmt inthe list of FO_TbolFmt objects The first FO_RulingFmt in the list of FO_RulingFmt objects The first graphic object in the list of selected graphic objects FO_F low that represents the main flow First structural element definition in the list of element definitions in a FrameMaker document First format change list in the list of format change lists in a FrameMaker document The first or last FO_BodyPage in the list of FO_BodyPage objects The first or last FO_MasterPage in the list of FO_MasterPage objects The first or last FO_RefPage in the list of FO_RefPage objects The hidden page FO_H
591. stObjectId constant FP_HypertextParsedCmdDest R 556 FV_DestPageNum constant FP_HypertextParsedCmdDest R 556 FV_DestXRef constant FP_HypertextParsedCmdDest R 556 FV_DisallowedImportType status flag FS_ImportStatus R 195 FV_DlgClose constant itemNum G 217 G 226 R 93 FV_DlgEnter constant itemNum G 226 R 93 FV_DlgNoChange constant itemNum G 226 R 93 FV_DlgOptDontCare constant itemNum G 227 FV_DlgReset constant itemNum G 226 R 93 FV_DlgUndo constant itemNum G 226 R 94 FV_Element flag modifiers R 91 FV_ElementsOfType flag modifiers R 91 FV_ENABLE_ALWAYS_DISABLE constant FP_EnabledWhen G 174 R 526 FV_ENABLE_ALWAYS_ENABLE constant FP_EnabledWhen G 174 R 526 FV_ENABLE_CAN_PASTE constant FP_EnabledWhen R 527 FV_ENABLE_ COPY constant FP_EnabledWhen R 527 FV_ENABLE_COPY_FONT constant FP_EnabledWhen R 527 FV_ENABLE_IN_CELL_TEXT constant FP_EnabledWhen R 527 FV_ENABLE_IN_FLOW constant FP_EnabledWhen R 527 index 71 os Index Reserved Names FV_ENABLE IN MATH constant FP_EnabledWhen R 527 FV_ENABLE_IN_PARA_ TEXT constant FP_EnabledWhen R 527 FV_ENABLE IN_ TABLE constant FP_EnabledWhen R 527 FV_ENABLE_IN_TABLE TITLE constant FP_EnabledWhen R 527 FV_ENABLE_IN_TEXT constant FP_EnabledWhen R 527 FV_ENABLE_IN_TEXT_LINE constant FP_EnabledWhen G 174 R 527 FV_ENABLE_IS_AFRAME constant FP_EnabledWhen R 527 FV_ENABLE_IS_CELL constant FP_EnabledWhen R 527 FV_EN
592. stics FF_Custom_SingleSided Single sided FF_Custom_FirstPageRight Double sided starting with a right page FF_Custom_FirstPageLeft Double sided starting with a left page If successful F_ApiCustomDoc returns the ID of the document it created Otherwise it returns 0 Example The following code creates a custom document with the characteristics specified in the dialog box in Figure 4 1 include fmetrics h define in MetricT 65536 72 A Frame metric inch F_ObjHandleT docId docId F_ApiCustomDoc F_MetricFractMul in 17 2 11 in 1 F_MetricFractMul in 1 4 in in in in FF_Custom_SingleSided True Right 1st Page 1 0 Inch FiGuRE 4 1 Specifications for custom document Creating a document with F_ApiOpen To create a document with F_ApiOpen set the FS_NewDoc property in the openParamsp script to True For the syntax of F_ApiOpen see Opening a document or book with F_ApiOpen on page 48 When you use F_ApiOpen to create a document set fileName to the name of the template that you want to use You don t provide the name for the new document until you save it FDK Programmer s Guide Executing Commands with API Functions 4 For example the following code creates a document from a template named tmp template and saves itas tmp mynew doc F_ObjHandleT docId F_PropValsT params returnParamsp NULL params F_ApiAllocatePropVals 1 if params len 0 ret
593. strings F_ObjHandleT The ID of another object F_PointsT A set of x y coordinate pairs F_TabsT A set of tab descriptions F_TextLocT A point location in text F_TextRangeT A range or selection of text F_ElementCatalogEntriesT The list of elements in the Element Catalog F_AttributeDefsT An set of attribute definitions F_AttributesT An set of attributes F_ElementRangeT An element selection The API uses MetricT data to express measurement values This manual uses constants to represent conventional measurement system units as MetricT data For example the constant in represents an inch and the constant pts represents a pointin MetricT units For example five inches 5 4718592 are represented as 5 in For more information on the MetricT type and other data types and data structures listed in the table above see Chapter 4 Data Types and Structures Reference in the FDK Programmer s Reference Many property values are pointers to data structures For example FO_Doc objects have a property named FP_Dictionary that specifies words that the Spelling Checker will permit inadocument FP_Dictionary isan FT_Strings property Its value is a pointer to an F_StringsT structure which is defined as typedef struct UIntT len Number of permitted words StringT val Vector of permitted words F_StringsT FDK Programmer s Guide 271 13 Frame Session Architecture Property lists At the highest level th
594. strings in R 470 returning the number of strings in R 474 sorting R 477 See also strings index 28 string prompt dialog boxes displaying G 18 to G 20 R 260 function for R 5 R 260 to R 261 illustrated G 20 R 261 strings API representation of G 312 G 313 R 166 R 686 copying functions for R 4 R 69 data type for G 3 G 271 G 381 R 675 FDE functions for G 381 R 440 allocating new G 381 R 478 appending characters to R 444 appending double byte characters to R 445 appending integers to R 446 appending to string lists R 466 comparing G 381 R 455 comparing characters in R 450 concatenating R 443 R 446 concatenating double byte strings R 447 converting alphanumeric to integers G 381 R 441 converting alphanumeric to real numbers R 442 converting integers to R 446 converting to double precision numbers R 492 converting to long integers R 493 copying R 452 copying double byte strings R 454 copying from string lists R 467 copying one to another R 453 determining if a prefix of another string R 478 determining if a suffix of another string R 484 finding double byte characters in R 449 R 480 finding one in another R 484 finding single characters in R 443 R 448 R 480 freeing strings in string lists R 469 freeing the memory used by G 381 inserting into string lists R 472 printing formatted output to R 440 reading formatted input from R 441 removing characters from R 482 removing from string lists R 475 removing leading
595. t draw order f codes flow footnote reference getting properties FDK Programmer s Guide A container that is tied to a specific location in the text An anchored frame moves with the text as the anchor symbol 1 moves See also unanchored frame The process by which an API application can exit and free system resources A printable page in a document See also master page Text strings that define a cross reference format variable definition index entry or other item For example in a running header Running H F variable the building block lt Scurpagenum gt isa building block that specifies the current page number An application defined function that responds to a call such as an initialization call from FrameMaker A platform independent abstraction of an input or output stream A graphic object that belongs to a particular group or frame The order in which FrameMaker draws graphic objects that is the back to front order By default the draw order is the same as the order in which you draw the graphic objects When graphic objects overlap the ones in the front at the end of the draw order obscure those in back Hexadecimal function codes that specify individual user actions such as cursor movement or text entry An abstract notion of where text in a document can flow Flows connect text frames If text in an autoconnected frame reaches the end of a text frame FrameMaker automatically creates a ne
596. t F_LanguageNumber R 397 FV_LANG_DUTCH API language constant F_LanguageNumber R 397 FDK Programmer s Reference amp Guide Index Reserved Names as FV_LANG_ENGLISH API language constant F_LanguageNumber R 397 FV_LANG_FINNISH API language constant F_LanguageNumber R 398 FV_LANG_FRENCH API language constant F_LanguageNumber R 397 FV_LANG_GERMAN API language constant F_LanguageNumber R 397 FV_LANG_ITALIAN API language constant F_LanguageNumber R 397 FV_LANG_JAPANESE API language constant F_LanguageNumber R 398 FV_LANG_KOREAN API language constant F_LanguageNumber R 398 FV_LANG_NORWEGIAN API language constant F_LanguageNumber R 398 FV_LANG_NYNORSK API language constant F_LanguageNumber R 398 FV_LANG_PORTUGUESE API language constant F_LanguageNumber R 397 FV_LANG_SIMPLIFIED_CHINESE API language constant F_LanguageNumber R 398 FV_LANG_SPANISH API language constant F_LanguageNumber R 397 FV_LANG_SWEDISH API language constant F_LanguageNumber R 398 FV_LANG_SWISS_GERMAN API language constant F_LanguageNumber R 397 FV_LANG_TRADITIONAL_CHINESE API language constant F_LanguageNumber R 398 FV_LOOSELY_VALID constant F_ElementCatalogEntryT R 113 R 683 FV_MissingScript status flag FS_ImportStatus R 195 FV_NoFlowWithSpecifiedName status flag FS_ImportStatus R 195 FV_NoMainFlow status flag FS_ImportStatus R 195 FV_OBJ_END_OFFSET constant G 117 R 689 FV_ObjectData
597. t s interface follow the general steps below 1 Set up the hypertext commands 2 Create a function named F_ApiMessage in your client to respond to the user clicking a hypertext marker that contains a message apiclient command These steps are discussed in greater detail in the following sections Setting up hypertext commands The syntax for message apiclient is message apiclient yourmessage This argument Means apiclient The name under which the client is registered with the FrameMaker product On UNIX platforms it is the name specified in the lt Name gt statement in the apiclients file On the Macintosh it is the name of the client file in the Modules folder On Windows it is the ClientName specified in the APIClients section of the maker ini file For more information on registering FDK clients see the FDK Platform Guide for your platform yourmessage The string that the FrameMaker product passes to the API client When the user clicks a hypertext command the FrameMaker product calls the F_ApiMessage function of the client specified by apiclientand passes the string specified by yourmessage to the client Responding to message apiclient commands To respond to the message apiclient hypertext command your client must define F_ApiMessage as follows VoidT F_ApiMessage message docId objId StringT message F_ObjHandleT docId F_ObjHandleT objId Code to respond to hypertext me
598. t facets G 257 G 258 G 259 G 265 R 183 R 316 equal sign conditional text marker prefix G 318 equation properties See document properties equations G 293 document properties for G 284 R 550 to R 551 properties of R 603 resetting settings in function for R 7 R 266 error codes See API error codes errors handling G 45 See also API error codes status flags Esc shortcuts G 26 Escape symbol G 26 events initiated by API clients responding to G 40 monitoring by the FrameMaker product of G 43 notification points in G 34 to G 36 R 227 to R 232 requesting notification of G 13 G 34 to G 36 function for R 25 R 226 to R 233 responding to notification of G 15 G 34 G 36 to G 42 function for R 1 R 233 to R 237 exclusions in content rules lists of G 342 executable_name defined G 8 exiting clients G 378 FDE function for R 374 See also bailing out of API clients expandomatic menu items manipulating G 172 to G 173 export filters See filters expressions testing if true function for R 348 index 10 external graphic insets G 230 G 260 G 260 to G 261 See also graphic insets F F_ naming convention G xii R xix F_Api naming convention G xii R xix F_ApiSetElementRange function G 120 F_Char naming convention G 382 F_Hash naming convention G 383 F_Metric naming convention G 384 F_Mif naming convention G 387 f_stdio h header file R 27 R 45 F_Str naming convention G 381 F_StrList naming convention G 382
599. t is nested within specific types of ancestor elements For example one clause of a level rule could specify that a Para element appears in 12 point type if has only one Section element among its ancestors Another clause could specify that a Para element appears in 10 point type if there are two Section elements among its ancestors A format rule clause can use any of the following to specify an element s formatting in specific contexts FDK Programmer s Guide Frame Document Architecture 14 e A formatting tag or name such as a paragraph tag a character tag or a marker name e A subformat rule e A format change list A named format change list How the API represents format rules and format rule clauses The API uses an FO_FmtRule object to represent each format rule in an element definition and an FO_FmtRuleClause object to represent each format rule clause in a format rule Each FO_FmtRule object has an FP_FmtRuleClauses property which specifies its format rule clause FO_FmtRule properties provide the following information about a format rule e A list of its format rule clauses e An indication of whether it is a context rule or a level rule e Ifthe format rule is a level rule the element tags to count among the element s ancestors and the tag at which to stop counting FO_FmtRuleClause properties provide the following information about a format rule clause e A flag indicating how the rule clause specifies formatting
600. t weight Ifan FP_UseCharacteristic property is False the character format s property list includes only the FP_UseCharacteristic property It doesn t include the FP_Characteristic property for the characteristic since this property is not used Suppose you create the character format specified in the Character Designer in Figure 14 17 FDK Programmer s Guide Frame Document Architecture Character Designer E ra mee 2 se i FiguRE 14 17 Character Designer The API represents the character format with an FO_CharFmt object The following table lists some of its properties Property Type Value FP_CharTag StringT booktitle FP_FontAngle IntT Index of Italic font angle FP_UseFontAngle IntT True FP_UseFontFamily IntT False FP_UseFontVariation IntT False FP_UseFontWeight IntT False FP_UseUnderline IntT False FP_FontSize MetricT 36 pts FP_UseFontSize IntT True This character format overrides the default font angle setting and the size of the text to which it is applied It does not override any of the text s other default characteristics How the API organizes Character Catalog formats The API organizes the formats in a document s Character Catalog in a linked list FO_Doc objects have an FP_FirstCharFmtInDoc property that specifies the first FO_CharFmt object in the list FO_CharFmt objects have an FP_NextCharFmtInDoc property which specifies the ID of the next FO_CharFmt object in the
601. t 10 fusridoc dty dresinew dre File Edit Format View Special Graphics Table Help Paragraph Tag Apply Underlined character used to identify the keyboard shortcut for the text box label 1ofi 100 z Z ei SE FIGURE 10 17 Keyboard shortcut for an item in Windows To specify a keyboard shortcut for the Windows version of a dialog box follow these steps 1 In the DRE file select the letter of the label to be used for the keyboard shortcut 2 From the Format menu choose Style gt Underline If the item has a separate label item make sure that its item number follows the label s item number For example if the item is a text box make sure its item number follows the item number of its label For more information see Specifying the focus order on page 194 Relating items in a dialog box You can relate certain types of dialog items to other items If two items are related manipulating one changes the other For example in the FrameMaker Paragraph Designer the Paragraph Tag pop up menu consists of two dialog items a text box and an image pop up menu The image pop up menu is the bitmap image of an arrow pointing downward If the user chooses a setting from the image pop up menu the setting is displayed or stuffed in the text box The image pop up menu s stuff item is the text box Figure 10 18 shows a text box and an image pop up menu The text box is the stuff item of the
602. t current selection Return if there isn t one docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection if tr beg objId 0 return Change property to use formatting from source document i F_ApiGetPropIndex amp params FS_FormatImportedText params val i propVal u ival FV_SourceDoc F_Apilmport docId amp tr beg tmp frame doc amp params amp returnParamsp if F_ApiCheckStatus returnParamsp FV_ImportedMakerDoc F_ApiAlert File wasn t a Frame document FF_ALERT_CONTINUE_NOTE Deallocate property lists F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp FDK Programmer s Guide Using Imported Files and Insets 12 Importing a graphic The following code imports a graphic file by copy It prevents the API from importing the file if it is not a graphic F_PropValsT params returnParamsp NULL F_ObjHandleT docId F_TextRangeT tr IntT i Get default import list Return if it can t be allocated params F_ApiGetImportDefaultParams if params len 0 return Get current insertion point Return if there isn t one docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection if tr beg objId 0 return Change property to import by copy i F_ApiGetPropIndex amp par
603. t does not actually contain the text and graphic objects that appear on a page Instead it has a property named FP_PageF rame which specifies the ID of a page frame A page frame is an invisible unanchored frame whose dimensions match those of the page For more information on unanchored frames see Graphic objects on page 293 The API represents a page frame with an FO_UnanchoredFrame object This FO_UnanchoredFrame object has properties that specify the IDs of the first and last objects in the linked list of API graphic objects that appear directly on the page Suppose you create a body page with a single text frame as shown in Figure 14 2 Sgee ear Evang eng piyeasvesioseanevane van tg sieves etee veg E T T ELL T T ons gip vee ated by the dashed line The dashed line does not appear when the Text Symbols option of the View menu is set off This text column is drawn directly on the page frame Unlike text columns and other frames the page frame does not have a border and is completely invisible to the user FIGURE 14 2 Single text frame on a body page The API represents the body page in Figure 14 2 with the objects shown in Figure 14 3 The FO_BodyPage object does not have a property that specifies the ID of the FO_TextFrame object Instead it has a property named FP_PageFrame that specifies the ID of its page frame an FO_UnanchoredFrame object The page frame properties FP_FirstGraphicInFrame and FP_LastGraphicInFrame b
604. t it created otherwise it returns 0 You don t provide the name for the new document until you save it IMPORTANT Ifyou call F_ApiSimpleNewDoc with interactive setto True and the user clicks Portrait Custom or Landscape in the New dialog box F_ApiSimpleNewDoc does not create a document It returns O and sets FA_errno to FE_WantsPortrait FE_WantsCustom or FE_WantsLandscape It is up to your client to create a portrait custom or landscape document by calling F_ApiCustomDoc For more information on creating custom documents see Creating a custom document on page 55 Example The following code creates a document from the templates Reports Report1 template and saves itas tmp mynew doc It then uses F_ApiSimpleSave to save the the document For more information on F_ApiSimpleSave see Saving documents and books on page 59 F_ObjHandleT docId docId F_ApiSimpleNewDoc templates Reports Reportl False if docId F_ApiAlert Can t create document FF_ALERT_CONTINUE_NOTE T 7 wv else F_ApiSimpleSave docId tmp mynew doc False 54 FDK Programmer s Guide Creating a custom document Executing Commands with API Functions 4 To create a custom new document use F_ApiCustomDoc This function uses the FrameMaker product s default new document template to create the custom document For more information on the default new document template see Documents on pag
605. t set a valid value for FP_FamilyName before you set FP_InkName If you try to set the ink name when the family name is set to NULL F_ApiSetString returns an error of FE_NoColorFamily When you set a value for FP_FamilyName two things can happen e Ifthe current value for FP_InkName specifies a valid ink for the newly set FP_FamilyName then FP_InkName does not change e Ifthe current value for FP_InkName does not specify a valid ink for the newly set FP_FamilyName then the value for FP_InkName automatically changes to the first ink name for the new color family If you set FP_FamilyName to a color family that is not installed on your system F_ApiSetString returns an error of FE_BadFamilyName If you set FP_InkName to a FDK Programmer s Guide 339 14 Frame Document Architecture name that is not included in the current family F_ApiSet String returns an error of FE_BadInkName If you set one of either FP_FamilyName or FP_InkName to NULL then the other property value automatically changes to NULL Formal color library names and ink names Note that you must specify the family name as the as the formal color library name including the registered trademark symbol For example the following sets the color library for a color to MUNSELL Book of Color note the code xa8 for the character F_ApiSetString docId baselId FP_FamilyName MUNSELL xa8 Book of Color When specifying an ink name you
606. t to the FrameMaker product filters directory add the following line to the APIClients section of your product ini file KurtWrite TextImport kurt KURT Kurt all filters filter dll krt This instructs the FrameMaker product to call the filter when the user attempts to open or import a FDK Programmer s Guide file witha krt extension 373 16 Introduction to FDE e Ifyou are working on a UNIX platform with US English as the user interface language and the pathname of your compiled clientis usr fdk samples filter filter you can 374 register it by creating a text file name with the following lines in it lt APIclient d fminit usenglish APIArea apiclients lt Name KurtWrite Files Import gt lt Type TextImport gt lt Suffix krt gt lt Facet kurt gt lt FormatId KURT gt lt VendorId FAPI gt lt Directory usr fdk samp lt CommandLine FAPIDIR fil gt les filter gt lter gt This instructs the FrameMaker product to call the filter when the user attempts to open or import a file witha krt extension The FDK sets the environment variable SFAPIDIR to the directory specified by the lt Directory gt statement For more information on how to register filters see the FDK Platform Guide for your platform 1 Create a sample Text Only file If you are working on a UNIX or a Windows platform give the file a filename with an krt extension If you are wor
607. tBox 1ofi 100 izaan FiGURE 10 9 Item information in the status bar 188 FDK Programmer s Guide Creating Custom Dialog Boxes for Your Client 10 Designing the layout of the dialog box FrameMaker displays the dialog box information graphically in a standard Frame document window Within FrameMaker you can e Set the platform view of the dialog box e Manipulate the dialog box and its items as graphic objects e Add new items e Delete existing items The rest of this section describes the specific steps for each of these tasks Setting the platform view of the dialog box Before you start editing the dialog box make sure that you are working with the platform view of the dialog box that you want FrameMaker can display views of the dialog box as it appears on different platforms The status bar displays a letter identifying the current platform view of the dialog box By default the current platform view matches the version of FrameMaker you are using for example if you are using a UNIX version of FrameMaker an opened DRE file displays the X Windows view of the dialog box If the current platform view is not the view you want to work with change it to the appropriate platform view You can change the current platform view of a dialog box by using a keyboard shortcut e To work with the UNIX view of the dialog box press Esc d x e To work with the Macintosh view of the dialog box press Esc d m e To work wit
608. tId FV_SessionId docId FP_FirstPgfInDoc while pgfId Get each paragraph s tag and see if it s Body pgfName F_ApiGetString docId pgfId FP_Name if F_StrEqual StringT Body pgfName F_ApiSetProps docId pgfId amp props F_Free pgfName pgfId F_ApiGetId docId pgfId FP_NextPgfInDoc Adding tabs To get and set the tabs for a paragraph or Paragraph Catalog format use F_ApiGetTabs and F_ApiSetTabs The syntax for F_ApiGetTabs and F_ApiSetTabs is F_TabsT F_ApiGetTabs F_ObjHandleT doclId F_ObjHandleT objid IntT propNum VoidT F_ApiSetTabs F_ObjHandleT doclId F_ObjHandleT objid IntT propNum F_TabsT setVal This argument Means docId The ID of the document containing the paragraph or paragraph format whose tabs you want to query or set objid The ID of the paragraph or paragraph format whose tabs you want to query or set 1 Some examples in this chapter use FDE functions suchas F_StrEqual F_Alloc and F_Realloc For more information on using the FDE and these functions see Part III Frame Development Environment FDE FDK Programmer s Guide 103 aes Getting and Setting Properties 104 This argument Means propNum The property to query Specify FP_Tabs setVal The F_TabsT structure to which to set the property The F_TabsT structure is defined as typedef struct UIntT len The number of tabs in val F_Ta
609. tParams R 122 FS_DontNotifyAPIClients property F_ApiGetOpenDefaultParams R 140 FS_DontNotifyAPIClients property F_ApiGetSaveDefaultParams R 153 FS_FileIsGraphic property F_ApiGetImportDefaultParams R 125 FS_FileIsInUse property F_ApiGetOpenDefaultParams R 140 FS_FileIsInUse property F_ApiGetSaveDefaultParams R 154 FS_FileIlsMakerDoc property F_ApiGetImportDefaultParams R 124 FS_FileIsOldVersion property F_ApiGetOpenDefaultParams R 140 FS_FileIsSgmlDoc property F_ApiGetImportDefaultParams R 122 FDK Programmer s Reference amp Guide Index Reserved Names as FS_FileIsStructured property F_ApiGetOpenDefaultParams R 141 FS_FileIsText property F_ApiGetImportDefaultParams R 126 FS_FileIsText property F_ApiGetOpenDefaultParams R 141 FS_FileIsXm1Doc property F_ApiGetImportDefaultParams R 122 FS_FileType property F_ApiGetSaveDefaultParams G 62 R 154 FS_FileTypeHint property F_ApiGetImportDefaultParams R 122 FS_FileTypeHint property F_ApiGetOpenDefaultParams R 141 FS_FitGraphicInSelectedRect property F_ApiGetImportDefaultParams R 125 FS_FontChangedMetric property F_ApiGetOpenDefaultParams R 141 FS_FontNotFoundInCatalog property F_ApiGetOpenDefaultParams R 141 FS_FontNotFoundInDoc property F_ApiGetOpenDefaultParams R 142 FS_ForceImportAsText property F_ApiGetImportDefaultParams R 122 FS_ForceOpenAsText property F_ApiGetO
610. tag the FrameMaker product moves text with that tag to a hidden page and replaces it with markers For more information on hidden conditional text see How the API represents hidden conditional text on page 318 Suppose you create the condition tag specified in the Edit Condition Tag dialog box shown in Figure 14 18 Edit Condition Tag Comment Urderine El ColorfRea El se Delete Lance FiGuRE 14 18 Edit Condition Tag dialog box The API represents the condition with an FO_CondFmt object The following table lists some of its properties Property Type Value FP_Name StringT Comment FP_NextCondFmt InDoc F_ObjHandleT ID of next condition in list of document s conditions FDK Programmer s Guide Frame Document Architecture 14 Property Type Value FP_CondFmt IsShown IntT True FP_SepOverride F_ObjHandleT ID of the FO_Color object that represents red color j P_StyleOverride IntT FV_CN_SINGLE_UNDERLINE ny P_UseSepOverride IntT True How the API organizes condition formats The API organizes a document s FO_CondEmt objects in a linked list The FO_Doc property FP_FirstCondFmtInDoc specifies the first FO_CondFmt object in the list FO_CondFmt objects have a property named FP_NextCondFmtInDoc which specifies the ID of the next FO_CondFmt object in the list The order of the list does not correspond to the order in which the formats appear in the Conditional Text window Text
611. temId dlgId TAG FIELD 31 FP_Text tag Stuff tag in text box 32 F_Free tag 33 34 35 VoidT F_ApiDialogEvent dlgNum itemNum modifiers 36 IntT dlgNum 37 IntT itemNum 38 IntT modifiers 39 40 F_TextRangeT tr 41 F_ObjHandleT docId 42 StringT tag 43 44 if itemNum FV_DlgClose User closed dialog box 45 F_ApiNotification FA_Note_BackToUser False 46 47 if itemNum APPLY_BUTTON return Apply not pressed 48 49 tag F_ApiGetString dlgId F_ApiDialogItemId dlgId 50 TAG FIELD FP_Text 51 if tag F_StrLen tag lt 1 return Text box empty 52 53 Get current selection and apply tag to first pgf in it 54 docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc 55 tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection 56 if tr beg objId return 57 F_ApiSetString docId tr beg objId FP_Name tag 58 F_Free tag 59 Line 5 This line declares the ID of the dialog resource It is declared as a global variable because the FrameMaker product does not pass dialog IDs to the F_ApiDialogEvent callback You need the ID to get and set properties of the items in the dialog box Lines 10 to 11 These lines open and display the dialog box when the FrameMaker product starts The call to F_ApiOpenResource opens the dialog resource The call to F_ApiModelessDialog displays the dialog box as a modeless dialog box DLG_NUM is a
612. ter XML would have been the last field and it would not have required padding record_vers specifies the version of the record currently 0001 FDK Programmer s Guide 249 12 Using Imported Files and Insets vendor is a code specifying the filter s vendor The code is a string of four characters The following table lists the possible codes Code PGRF FAPI FFLT IMAG XTND Meaning Built in Frame filters External Frame FDK client filter External Frame filters External ImageMark filters External XTND filters This is not a comprehensive list of codes Codes may be added to this list by Frame or by developers at your site format_idis a code specifying the format that the filter translates The code is a string of four characters See Specifying format IDs on page 247 for information about format codes and a table that lists some of the possible codes platformis a code specifying the platform on which the filter was run The code is a string of four characters The following table lists the possible codes Code MAC6 MACP WINT WIN3 WIN4 OS 2 UNIX Meaning Macintosh 68000 series Power Macintosh Windows NT Windows 3 1 Windows 95 IBM OS 2 Generic X 11 Sun HP filter_versis a string of four characters identifying the version of the filter on that platform For example version 1 0 of a filter is represented by the string 1 0 filter_name is a text string up to 31 character
613. ter call was initiated The following table summarizes the situations in which a filter call can be initiated and what the FrameMaker product does in each situation How the filter call was initiated What the FrameMaker product does The user attempted to open the Makes the document created by the filter client visible filterable file Another client attempted to open the Returns the ID of the document created by the filter client to filterable file with the other clients F_ApiOpen call If the filter fails to F_ApiOpen open the filterable file the FrameMaker product returns 0 to the other client s F_ApiOpen call Ifthe F_ApiOpen call specified a property list with FS _MakeVisible setto True the FrameMaker product makes the document visible FDK Programmer s Guide Using Imported Files and Insets 12 How the filter call was initiated The user attempted to import the filterable file by copy into an existing document Another client attempted to import the filterable file by copy with F_Apilmport into an existing document The user attempted to import the filterable file by reference into an existing document Another client attempted to import the filterable file by reference with F_Apilmport into an existing document The FrameMaker product attempted to update a text inset that references the filterable file What the FrameMaker product does Copies the specified flow of the docume
614. text files you can import The following table lists the text inset file types and the corresponding API text inset objects File type API inset object that represents it Text FO_TiText FO_TiTextTable Frame binary document FO_TiFlow MIF FO_TiFlow FDK Programmer s Guide 229 12 Using Imported Files and Insets Client text insets The API allows you to create a special type of text inset called a client text inset The text for a client text inset is not directly provided by an external file Instead it is provided and maintained by an FDK client The API represents each client text inset in a document with an FO_TiApiClient object For more information on client text insets see Client text insets on page 236 Imported graphics files When the user imports a graphics file the FrameMaker product creates an object called a graphic inset The API uses an FO_Inset object to represent each graphic inset in a document An FO_Inset object has properties that specify aspects of how an imported graphic appears such as its size and scaling If the user imports a graphics file by copy the resulting graphic inset is called an internal graphic inset An internal graphic inset contains all of an imported graphic s data If the user imports a graphics file by reference the resulting inset is called an external graphic inset An external graphic inset does not contain all the data for an imported graphic Instead its FP_Ins
615. tf NULL StringT You are in a table row n else F_Printf NULL StringT You are not in a table at all n Be sure to deallocate memory for the property value F_ApiDeallocatePropVal amp propVal FDK Programmer s Guide 119 o 6 Manipulating Text 120 Getting and setting the structural element selection Although you can get and set selected structural elements in a FrameMaker document by getting and setting the text selection it is usually easier to use the following functions e F_ApiGetElementRange gets the structural element selection in a document or book e F_ApiSetElementRange sets the structural element selection in a document or book The syntax for these functions is F_ElementRangeT F_ApiGetElementRange F_ObjHandleT docId F_ObjHandleT objld IntT propNum VoidT F_ApiSetElementRange F_ObjHandleT doclId F_ObjHandleT objld IntT propNum F_ElementRangeT setVal This argument Means docId The object containing ob jId To get or set the element selection in a document specify FV_SessionIid objid The ID of the document or book in which you want to get or set the element selection propNum The property to get or set To get or set the element selection specify FP_ElementSelection setVal The element range to set the property to The F_ElementRangeT structure is defined as typedef struct F_E
616. tform bailing out has no effect IMPORTANT Never call exit F_Exit or abort from an API client If you call one of these functions the function exits the FrameMaker product and unpredictable results including data loss may occur After it exits your client the FrameMaker product continues processing events that affect it Your client s menus remain on the menu bar and are still valid If your client has requested notification for particular events the FrameMaker product continues to monitor those events The FrameMaker product also monitors message apiclient hypertext commands that specify your client If the user chooses one of your client s menu items or hypertext commands or initiates an event for which your client requested notification the FrameMaker product restarts your client calling its F_ApiInitialize function with initialization setto FA_Init_Subsequent After F_ApiInitialize has returned control the FDK Programmer s Guide 43 a Creating Your Client s User Interface FrameMaker product also calls the appropriate callback function for the menu choice hypertext command or event IMPORTANT Jf your client bails out it loses all its global variable settings The following code requests notification for the FA_Note_PreQuitDoc notification point and then bails out after the user starts the FrameMaker product If the user subsequently closes a document it displays dialog boxes indicating when the FrameMa
617. the FrameMaker product as a standard list of marker types and the others are defined by the user The list of defined marker types is saved with the document How the API represents markers The API represents each marker with the following e An FTI_MarkerAnchor text item that specifies the ID of an FO_Marker object e An FO Marker object FO_Marker properties provide the following information e The marker type the Id of an FO_MarkerType object e The text the marker contains e The ID of the next FO_Marker object in the document e The location of the marker in text e The element ID of the marker if it is a structured marker in a FrameMaker document e If included the number of a marker type in versions earlier than 5 5 when opening the document in FrameMaker 5 5 this maps the old numbered marker type to the new named marker type FO_MarkerType properties provide the following information e The ID of the next FO_MarkerType object in the document e The name of the marker type as it appears in the user interface e The internal name of the marker type usually the same as the name that appears in the user interface e If included the number of a marker type in versions earlier than 5 5 when opening the document in FrameMaker 5 5 this maps the old numbered marker type to the new named marker type e Whether the marker type appears in the user interface whether it is saved with the document and whether the marker type can be del
618. the FDE string list functions you must include fdetypes h and fstrlist h in your program Character library The character library provides routines that convert and manipulate Frame characters For example F_CharIsAlphabetic determines whether a character is alphabetic F_CharToLower converts a character to lowercase and F_CharToUpper converts a character to uppercase The FDE implements all character library functions as macros The character library functions are all prefixed with F_Char To use the FDE character functions you must include fdetypes h and fcharmap h in your client IMPORTANT Before you use the character library functions you must call F_FdeInit to initialize the character library The I O library The I O library provides functions that allow your client to read data from and write data to channels These functions can swap bytes when reading or writing on a channel For example it may be necessary to swap bytes in either of the following cases e The platform your client is running on is little endian and the channel you are reading from or writing to isn t e The channel is little endian but the platform isn t When you use the I O library functions you can specify whether an input or output channel s byte ordering is little endian or big endian by calling F_SetByteOrder or F_ResetByteOrder The I O functions use this information to determine whether byte swapping is nece
619. the ID of the table containing the cell The table properties FP_TopRowSelection and FP_BottomRowSelection specify the IDs of the first and last rows containing selected cells The FP_LeftColNum and FP_RightColNum properties of the table specify the index numbers of the outermost columns in the selection a If an entire cell is selected there is no text selection How the API represents the element selection in a structured FrameMaker document In a structured FrameMaker document the selection properties described in the previous section behave as they would in an unstructured document However structured FrameMaker documents have an additional selection property FP_ElementSelection which specifies the selection in terms of the selected element range or F_ElementRangeT structure The F_ElementRangeT structure is defined as typedef struct F_ElementLocT beg Beginning of the element range F_ElementLocT end End of the element range F_ElementRangeT The F_ElementLocT structure specifies a location within an element It is defined as typedef struct F_ObjHandleT parentId Parent element ID F_ObjHandleT childId Child element ID IntT offset Offset within child parent element F_ElementLocT 286 FDK Programmer s Guide Frame Document Architecture CE The following table summarizes the different types of selection in a structured FrameM
620. the body pages or a graphic that appears at the top of the page The Paragraph Designer provides two settings Frame Above and Frame Below to specify the named frames that appear above or below a paragraph API objects identified by a unique name for example FO_PgfFmt and FO_CharFmt objects The API representation of basic entities in FrameMaker For example an FO_Pgf object represents a paragraph and an FO_Rectangle object represents a rectangle An invisible unanchored frame whose dimensions match those of a page The API represents a page frame with an FO_UnanchoredFrame object The frame containing a graphic object See also page frame The characteristics of API objects Different types of objects have different properties For example FO_Rectangle objects have properties to represent a rectangle s height and width These properties are named FP_Height and FP_Width respectively Each property has a value associated with it For example if a paragraph has two tabs the value ofits FP_NumTabs property is 2 FDK Programmer s Guide reference page A nonprinting page containing named frames that can be used above and below paragraphs or above footnote text A reference page can also contain special flows that control the appearance of generated files such as indexes and lists See also master page body page and named frames series object Objects that the API keeps in ordered series Series objects include FO_Pgf
621. the scroll bar For details on the properties of the API object see Dialog boxes on page 531 of the FDK Programmer s Reference For instructions on getting and setting properties see Chapter 5 Getting and Setting Properties To display the currently selected value of a scroll bar in the dialog box add a text box or a label The dialog box does not automatically stuff the scroll bar value into the text box or label To do this you must add code to your client that gets the scroll bar value and programmatically stuffs it into the text box or label If you resize a scroll bar by dragging on its object handles it may appear distorted To eliminate the distortion use the keyboard shortcut for viewing the dialog box on the current FDK Programmer s Guide 201 a Creating Custom Dialog Boxes for Your Client platform For instructions on using this shortcut see Setting the platform view of the dialog box on page 189 To change the length of a scroll bar type over the value in the Width or the Height text box e Ifthe scroll bar is horizontal type the length of the scroll bar in the Width text box e Ifthe scroll bar is vertical type the length of the scroll bar in the Height text box Note that you cannot change the width of a vertical scroll bar Similarly you cannot change the height of a horizontal scroll bar To change the orientation of a scroll bar from horizontal to vertical drag the object handles of the scrol
622. ties Manipulating property lists directly If you are setting individual text properties or using scriptable functions such as F_ApiOpen you need to manipulate property lists directly The order of the properties in property lists is not guaranteed to remain the same in different versions of FrameMaker products and the Frame API So to get a particular property in a list you must traverse the entire property list and check each property s identifier until you find it The API provides a convenience routine named F_ApiGetPropIndex that does this for you The syntax for F_ApiGetPropIndex is IntT F_ApiGetPropIndex F_PropValsT pvp IntT propNum This argument Means pvp The property list propNum The property whose index you want to get FDK Programmer s Guide 93 aes Getting and Setting Properties F_ApiGetPropIndex returns the index of the F_PropValT structure that represents the property s property value pair If you specify an invalid property for propNum F_ApiGetPropIndex returns FE_BadPropNum Suppose you want to display the session property that provides the name of the current FrameMaker product interface The easy way to do this would be to use the following code StringT productName productName F_ApiGetString 0 FV_SessionId FP_ProductName F_ApiAlert productName FF_ALERT_CONTINUE_NOTE To do the same thing by getting the property list for the session and acc
623. ting the anchor type for example FTI_TblAnchor and F_TextItemT u idata contains the ID of the anchored object for example an FO_Tb1 object For more information on the F_TextItemsT structure see How the API represents text on page 312 After you are finished with an F_TextItemsT structure free the memory that it uses with F_ApiDeallocateTextItems The syntax for F_ApiDeallocateTextItems is VoidT F_ApiDeallocateTextItems F_TextItemsT itemsp where itemsp isthe F_TextItemsT structure that you want to free If you call F_ApiGetText fora structural element FO_Element object the returned information depends on the type of element as shown in the following table Element s FP_ElementType value Information returned by F_ApiGetText FV_FO_CONTAINER All the text items from the beginning to the end of the element FV_FO_SYS_VAR All the text items from the beginning to the end of the variable F V_FO_XREF All the text items from the beginning to the end of the cross reference FV_FO_FOOTNOTE All the text items from the beginning to the end of the footnote FDK Programmer s Guide Manipulating Text 6 Element s FP_ElementType value Information returned by F_ApiGetText FV_FO_TBL_TITLE All the text items from the beginning to the end of the table title FV_FO_TBL_CELL All the text items from the beginning to the end of the cell FV_FO_TBL_HEADING Nothing
624. tinguish between you the developer and the user the person for whom you write clients FDK manuals may use the term FrameMaker product to refer to the FrameMaker software as opposed to the software you write to work with the FrameMaker product Structured program interface FrameMaker 7 0 and later ships with two program interfaces Structured FrameMaker and FrameMaker The structured program interface presents menus icons and commands for working with structured documents The FDK includes some functions that only work on structured documents For example setting an element range makes no sense in a document that doesn t contain any structure elements Further you can specify that an FDK client requires the Structured FrameMaker program interface For example assume you specify Structured FrameMaker when you register your client If a user has your client installed but is running the FrameMaker program interface not structured then his installation of FrameMaker will not initialize your client when it starts up In earlier versions you could specify which FrameMaker products would initialize your client FrameMaker FrameMaker SGML or Frame Viewer The FDK Programmer s Reference indicates those FDK functions that apply only to structured FrameMaker documents as follows FDK Programmer s Guide xiii aS Using Frame Developer Tools Xiv Structured F_ApiGetAttributeDefs In this example the word Structured appears to
625. tion R 2 R 361 F_CharIsControl function R 2 R 361 F_CharIsDoubleByteFirst function R 362 R 363 F_CharIsDoubleByteSecond function R 364 F_CharIsEol function R 365 F_CharIsHexadecimal function R 2 R 366 F_CharIsLower function R 2 R 366 F_CharIsNumeric function R 2 R 367 F_CharlsUpper function R 2 R 368 F_CharToLower function G 382 R 2 R 368 F_CharToUpper function G 382 R 2 R 369 F_ClearHandle function G 379 R 12 R 370 F_ClearPointer function G 379 F_ClearPtr function R 12 R 370 F_CombinedFontsT structure R 62 R 679 FDK Programmer s Reference amp Guide Index Reserved Names F_CombinedFontT structure R 680 F_CompareRetT structure G 68 R 680 F_CopyPtrQ function R 12 R 371 F_DeleteFile function G 377 R 8 R 372 F_DuplicateHandle function R 12 R 372 F_DuplicatePtr function R 12 R 373 F_ElementCatalogEntriesT structure G 90 G 271 R 683 F_ElementCatalogEntryT structure R 682 F_ElementFmtsT structure G 90 F_ElementLocT structure G 286 F_ElementRangeT structure G 286 F_Exit Q function R 374 F_FdelInit function G 366 G 372 G 375 G 382 R 374 F_FdeInitFontEncs function R 20 R 375 F_FilePathBaseName function R 8 R 376 F_FilePathCloseDir function R 8 R 377 F_FilePathCopy function R 7 R 378 F_FilePathFree function G 373 G 375 R 8 R 378 F_FilePathGetNext function G 377 R 8 R 379 F_FilePathOpenDir function R 8 R 380 F_FilePathParent function R 8 R 38
626. tion on FDE functions see Part III Frame Development Environment FDE Some API functions return structures containing pointers to arrays The API allocates memory for these arrays When you are done with this memory you must deallocate it The API provides convenience functions such as F_ApiDeallocatePropVals F_ApiDeallocateStrings and F_ApiDeallocateMetrics which you can use for this For example to get the property list for an object and then deallocate it use code similar to the following F_PropValsT props F_ObjHandleT ob jId doclId props F_ApiGetProps docId objId F_ApiDeallocatePropVals amp props Getting and setting session properties The following sections describe useful tasks you can perform by getting and setting session properties Making a document or book active In addition to finding out which document is active by getting the session s FP_ActiveDoc property you can make a document active by setting this property For example the following code makes the document specified by docId active F_ObjHandleT docId F_ApiSetId 0 FV_SessionId FP_ActiveDoc docId When you make a visible document active its window gets input focus On some platforms the windowing system highlights a window s title bar or brings it to the front FDK Programmer s Guide 95 aes Getting and Setting Properties Getting the user home FMHOME and current directories Some platforms such
627. to each item in a dialog box To get a dialog item s ID call F_ApiDialogItemId The syntax for F_ApiDialogItemId is F_ObjHandleT F_ApiDialogItemId F_ObjHandleT dialogId IntT itemNum This argument Means dialogid The ID of the dialog box containing the item itemNum The item number of the item F_ApiDialogItemId returns the dialog item s ID or 0 if the item doesn t exist A dialog item s item number appears in the Dialog Object Properties window for the item when you create the dialog box It also appears in the Frame dialog resource file following the 212 FDK Programmer s Guide Handling Custom Dialog Box Events no description of the item For example the following portion of a Frame dialog resource file describes a text box item with the item number 2 A EditBox lt BaseLine 23 74 80 gt lt Label ImATextBox gt lt StuffObject 1 gt lt HypertextHelp dbre hlp edit box gt gt 2 If the name of the dialog resource containing this text box is mydlg x you can use the following code to get its ID define EDITBOX_ITEM_NUM 2 F_ObjHandleT dlgId editboxId dlgId F_ApiOpenResource FO_DialogResource mydlg editboxId F_ApiDialogItemId dlgId EDITBOX_ITEM_NUM Getting and setting dialog item properties You can get and set the dialog item properties with F_ApiGet PropertyType and F_ApiSetPropertyType functions When you call one of these functions s
628. to G 12 creating custom dialog boxes for G 177 to G 209 current getting directory containing R 24 R 59 to R 60 getting registered name of R 24 R 60 disabling G 16 executing commands in G 7 G 45 to G 79 for filters G 5 G 15 G 36 index 1 index 2 Index Subjects freeing memory from R 11 R 24 R 48 including header files in G 8 initializing G 7 G 13 to G 16 G 375 initializing FDK client connection with the API R 330 to R 331 modes of interaction G 17 portability of G 6 G 366 to G 370 G 375 to G 379 property manipulation capabilities of G 81 registering with the FrameMaker product G 8 to G 9 G 12 responding to events initiated by G 40 running G 12 running with different FrameMaker product interfaces G 6 setting up user interfaces for G 7 G 17 to G 44 special types of G 5 to G 6 suspending operation of functions for R 17 R 328 R 344 to R 345 user configuration of the user interface G 30 to G 31 API error codes naming convention for G xii R xix printing current error status R 98 R 248 table of R 693 to R 697 API filters See filters API functions alphabetical listing of R 27 to R 493 for creating objects tables G 143 to G 145 R 14 declarations of G 8 determining the availability of G 6 disadvantage of F_ApiFcodes G 75 executing commands with G 7 G 40 G 45 to G 79 for getting and setting properties table G 90 header file containing G 8 naming convention for G xii R xix scriptable G xii G
629. to get and set properties that are identified by names These functions are used for getting and setting inset properties only They are discussed in Chapter 12 Using Imported Files and Insets Property s data type Functions to get and set property F_AttributesT F_ApiGetAttributes F_ApiSetAttributes F_AttributeDefsT F_ApiGetAttributeDefs F_ApiSetAttributeDefs F_ElementCatalogEntriesT F_ApiGetElementCatalog F_ElementFmtsT F_ApiGetElementFormats F_ApiSetElementFormats F_ElementRangeT F_ApiGetElement Range F_ApiSetElement Range F_ObjHandleT F_ApiGetId F_ApiSetId IntT including boolean enum and ordinal F_ApiGet Int F_ApiSetInt F_IntsT F_ApiGetInts F_ApiSetInts MetricT F_ApiGetMet ric F_ApiSetMetric F_MetricsT F_ApiGetMetrics F_ApiSetMetrics F_PointsT F_ApiGetPoints F_ApiSetPoints StringT F_ApiGet String F_ApiSetString F_StringsT F_ApiGet Strings F_ApiSetStrings F_TabsT F_ApiGetTabs F_ApiSetTabs F_TextLocT F_ApiGetTextLoc F_ApiSetTextLoc F_TextRangeT F_ApiGet TextRange F_ApiSetTextRange FDK Programmer s Guide Getting and Setting Properties can The syntax for most F_ApiGetPropertyType and F_ApiSetPropertyType functions is similar For example the syntax for F_ApiGetInt is IntT F_ApiGetInt F_ObjHandleT doclId F_ObjHandleT objid IntT propNum This argume
630. to save saveAsName Name of the pathname to save the document or book to For information on how filenames and paths on different platforms are represented see the FDK Platform Guide for that platform interactive Specifies whether the FrameMaker product displays messages and warnings to the user True to display messages and warnings If you set interactive to False and you specify the document or book s current name the FrameMaker product saves the document or book under its current name If you specify another filename for saveAsName the FrameMaker product saves the document or book to that filename If you set interactive to True the FrameMaker product displays the Save dialog box and allows the user to choose a filename The document or book s current name appears as the default name If F_ApiSimpleSave is successful it returns the ID of the document it saved If you save the document under its current name the returned ID is the same ID you specified in the docId parameter If you specify another filename for saveAsName the returned ID is the ID of the new document If F_ApiSimpleSave can t save the file it returns 0 Example The following code opens and then saves a document named tmp my doc After it has saved the document as tmp my doc it saves a copy of it as mynew doc FDK Programmer s Guide 59 a Executing Commands with API Functions 60 include futils h F_ObjHandleT mydocId mynewdocld UCh
631. to the MakerMainMenu menu bar the menu will not appear if the user switches to quick menus For your menu to appear after the user has switched to quick menus you must also add it to the QuickMakerMainMenu menu bar Adding commands to a menu that you have created To add a command to a menu that you have created call F_ApiDefineAndAddCommand with toMenuld set to the ID returned by the F_ApiDefineAndAddMenu call that FDK Programmer s Guide 27 Creating Your Client s User Interface created the menu For example the following code defines a menu and adds it to the FrameMaker document menu bar Then it adds some commands to the menu define CHECK J define PRINT 2 F_ObjHandleT menubarId menuId cmdlId cmd2Id Get the ID of the FrameMaker main menu bar menubarId F_ApiGetNamedObject FV_SessionId FO Menu MakerMainMenu Define and add the menu to the main menu menuld F_ApiDefineAndAddMenu menubarId GrammarMenu Grammar Define some commands and add them to the menu cmdlId F_ApiDefineAndAddCommand CHECK menuld CheckGrammar Check Grammar CG cmd2Id F_ApiDefineAndAddCommand PRINT menuld PrintErrors Print Errors PE Example The following code defines a menu and adds it to the Edit menu define CHECK i define PRINT 2 F_ObjHandleT editMenulId menuId cmdilId cmd2Id Get the ID of the edit menu
632. trSuffix function R 19 R 484 F_StrTokQ function R 19 R 485 F_StrTrunc function R 20 R 486 F_StrTruncEnc function R 20 R 487 F_TabsT structure G 90 G 104 G 271 R 4 R 11 R 16 R 162 R 305 R 685 F_TabT structure G 104 R 4 R 11 R 162 R 305 R 685 F_TextItemsT structure G 112 G 312 R 4 R 11 R 46 R 165 R 171 R 173 R 175 R 689 FDK Programmer s Reference amp Guide Index Reserved Names a F_TextItemT structure G 112 G 312 R 4 R 165 R 171 R 686 F_TextLocT structure G 90 G 114 G 271 R 16 R 176 R 181 R 209 R 211 R 308 R 689 F_TextRangeT structure G 90 G 114 G 271 R 16 R 181 R 313 R 689 F_TypedValT structure G 272 R 689 F_TypedValT u union G 272 F_UBytesT structure R 4 R 11 R 183 R 317 R 691 F_UlIntsT structure G 271 R 4 R 11 R 691 F_UnlockHandle function R 12 R 488 F_ValT structure R 4 F_Warning function G 379 R 488 F_WriteBytes function R 10 R 489 F_WriteLongs function R 10 R 490 F_WriteShorts function R 10 R 491 FA_errno global variable G 45 FA_Init_DocReport initialization flag G 14 G 15 R 198 FA_Init_First initialization flag G 14 R 198 FA_Init_Subsequent initialization flag G 14 G 15 R 48 R 198 FA_Init_TakeControl initialization flag G 14 R 198 FA_Note_Alert notification constant R 235 FA_Note_BackToUser notification constant G 38 G 214 G 216 G 217 G 220 R 230 FA_Note_BodyPageAdded notification constant R 231 FA_Note_BodyPageDel
633. ts that can take control of a FrameMaker product session and communicate interactively with the user With the API a client can do nearly everything an interactive user can do and more The API gives a client direct access to the text and graphic objects in documents The API includes a set of header files libraries and makefiles for each supported platform Here are some examples of the types of clients you can create with the API e Grammar checkers e Bibliography utilities Voice control utilities Document reporting utilities Version control systems for documents Table utilities such as sorting and totaling Database publishing packages Interfaces to document management systems Filters to exchange files between other desktop publishing applications and FrameMaker FDK Programmer s Guide ix SS Using Frame Developer Tools FDE The Frame Development Environment FDE helps you make your client portable to all platforms supported by FrameMaker It provides platform independent alternatives to platform specific I O string and memory allocation schemes It also provides a variety of utility functions such as Maker Interchange Format MIF writing functions Frame encourages you to use the FDE to develop all your clients The FDE includes header files and libraries for each supported platform Structure Import Export API The Structure Import Export API allows you to write clients that control the import of markup documents
634. ture for individual G 272 R 684 structure for sets G 272 R 684 pull down menus adding pull right menus to R 79 adding to menu bars R 79 creating G 27 pull right menus adding to other menus R 79 creating G 27 Q querying facets R 183 to R 184 properties G 84 to G 89 quick keys implementing G 42 to G 43 R 262 quick key interface G 42 to G 43 function for implementing R 262 quitting Frame sessions G 67 function for R 17 index 25 os Index Subjects R radio buttons in dialog boxes G 199 getting setting the state of function for R 5 properties of G 199 R 535 read only properties G 81 symbol indicating R 495 rectangle properties R 604 reference frames function for resetting R 7 R 266 properties of R 620 R 628 reference page properties R 612 reference pages G 289 G 391 API representation of G 289 creating See named objects creating properties of G 290 G 291 to G 292 R 612 reformatting documents G 70 to G 74 G 96 functions for G 77 R 7 R 25 registered names of current client R 24 R 60 registering API clients with the FrameMaker product G 8 to G 9 G 12 filters G 15 rehyphenating words function for R 7 return values of functions See individual functions in the FDK Reserved Names Index RGB color model G 339 Right master page G 292 rounded rectangle properties R 604 TOWS adding to tables G 156 to G 157 function for R 14 R 22 R 39 to R 41 API representation of G 333 deleting from tables G 158 to G 1
635. ty F_ApiGetUpdateBookDefaultParams R 188 FS_AutoBackupOnSave property F_ApiGetSaveDefaultParams R 153 FS_BeefyDoc property F_ApiGetOpenDefaultParams R 139 FS_BookIsInUse property F_ApiGetOpenDefaultParams R 139 FS_CellSeparator property F_ApiGetImportDefaultParams R 126 FDK Programmer s Reference amp Guide FS_DisallowBookDoc property F_ApiGetOpenDefaultParams R 139 FS_DisallowBookMIF property F_ApiGetOpenDefaultParams R 139 FS_DisallowDoc property F_ApiGetImportDefaultParams R 121 FS_DisallowDoc property F_ApiGetOpenDefaultParams R 139 FS_DisallowFilterTypes property F_ApiGetImportDefaultParams R 121 FS_DisallowFilterTypes property F_ApiGetOpenDefaultParams R 139 FS_DisallowGraphicTypes property F_ApiGetImportDefaultParams R 121 FS_DisallowMacEditions property F_ApiGetImportDefaultParams R 121 FS_DisallowMIF property F_ApiGetImportDefaultParams R 121 FS_DisallowMIF property F_ApiGetOpenDefaultParams R 140 FS_DisallowPlainText property F_ApiGetImportDefaultParams R 121 FS_DisallowPlainText property F_ApiGetOpenDefaultParams R 140 FS_DisallowSgml property F_ApiGetImportDefaultParams R 121 FS_DisallowSgml property F_ApiGetOpenDefaultParams R 140 FS_DisallowXml property F_ApiGetImportDefaultParams R 122 FS_DisallowXml property F_ApiGetOpenDefaultParams R 140 FS_DontNotifyAPIClients property F_ApiGetImportDefaul
636. u delete an FO_Tb1 object the API deletes all the FO_Row objects and FO_Ce11 objects in the table Similarly if you delete an element in a FrameMaker document the API deletes all the descendants of that element Deleting flows and text frames When you delete a flow the API also deletes all the text frames in it and all the paragraphs in the text frames If you don t want to delete a text frame when you delete a flow you must disconnect the text frame from the flow before you delete it To disconnect a text frame from a flow set the text frame s FP_PrevTextFrameInFlow and FP_NextTextFrameInFlow properties to 0 If you delete a text frame that is not connected to another text frame the API deletes the flow that contains it Deleting table columns and rows To delete table columns and rows use these functions e F_ApiDeleteCols to delete table columns e F_ApiDeleteRows to delete table rows 158 FDK Programmer s Guide Creating and Deleting API Objects Ba The syntax for F_ApiDeleteCols is IntT F_ApiDeleteCols F_ObjHandleT docId F_ObjHandleT tblid IntT refColNum IntT numDelCols This argument Means docId The ID of the document containing the table tblid The ID of the table containing the columns refColNum The first column to delete Columns are numbered from left to right starting with column 0 numDelCols The number of columns to delete F_ApiDeleteCols deletes the c
637. ubi ID ofan FO_Rubi 314 FDK Programmer s Guide Frame Document Architecture The following table lists the bit flags that a client can bitwise AND with the idata field of an FTI_CharPropsChange text item and the types of text property changes each flag indicates For example to determine if the font family changed bitwise AND the FTF_FAMILY flag with the idata field Flag FTF_FAMILY Hj F_VARIATION FTF_WEIGH FTF_ANGLE FTF_UNDERLINING FTF_STRIKETHROUGH FTF_OVERLINE Hy F_CHANGEBAR Hy F_OUTLINE FTF_SHADOW Hy F_PAIRKERN Hy F_SIZE FTF_KERNX FTF_KERNY FTF_SPREAD nj TF_COLOR Hy F_CHARTAG Hy F_CAPITALIZATION Hy F_POSITION ny TF_CONDITIONTAG Hy F_STRETCH FTF_LANGUAGE FTF_TSUME ETF TIF FTF_ENCODING Meaning The font family has changed The font variation has changed The font weight has changed The font angle has changed The underlining has changed The strikethrough characteristic has changed The overline characteristic has changed The change bars have changed The outline characteristic has changed The shadow characteristic has changed The pair kerning has changed The font size has changed The kern x characteristic has changed The kern y characteristic has changed The font spread has changed The color
638. uide 57 ae Executing Commands with API Functions 58 When you call F_ApiSilentPrintDoc the FrameMaker product doesn t notify the user about error or warning conditions that occur when it attempts to print To determine whether an error occurred check FA_errno Changing the print settings for a document When you print a document in the user interface you can change the print settings in the Print dialog box FrameMaker saves most print settings with a document For example if you set the scale to 90 percent and print the document in the same session or save the document the default setting for the scale will be 90 percent Similarly if an API client calls F_ApiSilentPrintDoc to print the document the scale will be 90 percent if the client doesn t change it The API represents a document s print settings with a set of document properties For example adocument s FP_PrintNumCopies property specifies the number of copies of the document to print To change a print setting programmatically you change the property that represents it For more information on changing properties see Chapter 5 Getting and Setting Properties For a list of document print properties see Document print properties on page 561 of the FDK Programmer s Reference Examples The following code opens a document named tmp my doc and prints it using the default print settings F_ObjHandleT docId docId F_ApiSimpleOpen tmp my doc
639. ular point in text is defined as typedef struct F_ObjHandleT objId Object that contains the text IntT offset Characters from beginning F_TextLocT If a range of text is selected FP_TextSelection specifies a selection F_TextRangeT beg and F_TextRangeT end specify the beginning and end of the selection If there is an insertion point FP_TextSelection specifies an insertion point F_TextRangeT beg and F_TextRangeT end are the same both specify the location of the insertion point If there is no text selection or insertion point the objId and offset fields of both F_TextRangeT beg and F_TextRangeT end are setto 0 For example suppose the first five characters of the first paragraph on the page shown in Figure 6 1 are selected Subcolum Text frame FIGURE 6 1 Page with text frame containing two subcolumns The fields of the F_TextRangeT structure specified by the document s FP_TextSelection property have the following values 114 FDK Programmer s Guide Manipulating Text 6 Field Value beg objId ID of the first paragraph beg offset 0 end objId ID of the first paragraph end offset 5 If no text is selected and the insertion point is at the very beginning of the paragraph the fields of the F_TextRangeT structure have the following values Field Value beg objiId ID of the first paragraph beg offset 0 end objId ID of the first paragraph end
640. uld not differ from the corresponding properties in the document file However by setting the values in one but not both a client could set up a component with different numbering properties than the corresponding document file Subsequent book updates will make the numbering properties match For example the paragraph numbering for a set of document in files might be set to restart at 1 When the user adds the documents to the book then each component will have the same numbering properties Your client could loop through a book and set the numbering for each component to continue from the previous file In this case when your client or the user updates the book the FrameMaker product will change the numbering for the document files so they match the component numbering For more information about how component and document numbering properties interact see your Frame product user s manual IMPORTANT A book component can be a document saved in any file format The FDK can only modify document objects in documents that were saved in FrameMaker binary FASL files but you can use channels to open MIF or text files and modify them How the API represents books The API represents each book with an FO_Book object which can contain one or more FO_BookComponent objects FO_Book objects have properties that provide the following information FDK Programmer s Guide 351 er Frame Book Architecture e Whether the book has been modified
641. ult ruling is the ruling that the cell inherits from the FO_Tb1 object that contains it For example the FP_Cel1DefaultTopRuling property for a cell in a body row inherits the value of the FP_Tb1BodyRowRuling property in the FO_Tb1 object that contains it An override ruling is a ruling that the user specifies in the Custom Ruling and Shading dialog box for an individual cell If a value is specified for an override ruling it overrides the default ruling The FO_Cell properties FP_CellOverrideShading and FP_CellOverrideFill specify the cell s custom shading and fill If the cell s custom shading and fill override the table s default shading and fill FP_CellUseOverrideFill and FP_CellUseOverrideShading are True How the API organizes the objects that represent tables Figure 14 32 shows a table anchor a table and the text item that represents the anchor offset 0 dataType FTI_TblAnchor sdata NULL idata FO_Tbl ID FIGURE 14 32 A table and the text item that represents its anchor The API represents the table with the objects shown in Figure 14 33 334 FDK Programmer s Guide FP_FirstRowInTbl m FO_Tbl L N a FP_LastRowInTbl FIGURE 14 33 Objects that represent a table FDK Programmer s Guide FO_Row Heading Row FP_FirstCellInRow Frame Document Architecture FP_NextRowInTbl y r FP_PrevRowInTbl FO_Row Body Row
642. umString bookId compId F_ApiGetId 0 FV_SessionId FP_ActiveBook F_ApiGetId FV_SessionId bookId FP_FirstSelectedComponent InBook F_Printf NULL n CompName is s F_ApiGetString bookId compId FP_Name switch F_ApiGetInt bookId compId FP_FnNumComputeMethod case FV_NUM_RESTART F_Printf NULL nFn Compute FV_NUM_RESTART break case FV_NUM_CONTINUE F_Printf NULL nFn Compute FV_NUM_CONTINUE T lt e FDK Programmer s Guide 353 me Frame Book Architecture break case FV_NUM_PERPAGE F_Printf NULL nFn Compute FV_NUM_PERPAGE break case FV_NUM_READ_FROM_FILE F_Printf NULL nFN Compute FV_NUM_READ_FROM_FILE break default F_Printf NULL nFn Num Compute Method UNKNOWN break if F_ApiGetInt bookId compId FP_FnNumStyle FV_FN_NUM_CUSTOM F_Printf NULL nFn Num Style FV_FN_NUM_CUSTOM numString F_ApiGetString bookId compId FP_FnCustNumString F_Printf NULL n Cust Str s numString F_ApiDeallocateString amp numString How the API organizes book components The API organizes the FO_BookComponent objects that represent a book s components in a linked list The FO_Book object s FP_FirstComponentInBook property specifies the first FO_BookComponent object in the list Each FO_BookComponent object has FP_PrevComponentInBook and FP_N
643. uments creating G 55 to G 56 G 57 Custom Ruling and Shading dialog box G 329 Customizing FrameMaker G 31 cutting text selections G 127 R 3 R 72 to R 73 D dagger symbol t indicating read only properties R 495 dash patterns R 595 setting R 294 R 595 data structures R 677 to R 691 copying functions for R 4 R 69 functions applicable to R 4 MIF G 384 to G 385 See also individual structures in the FDK Reserved Names Index data types G 3 to G 4 R 675 to R 677 for object IDs G 3 G 6 G 271 G 390 primitive C language G 6 G 367 to G 369 R 675 FDE substitutes for G 6 G 367 to G 369 R 675 for property values tables G 273 See also data structures filepaths IDs of API objects integers MetricT values See also primitive data types C language string lists strings and individual data types in the FDK Reserved Names Index default button of dialog boxes G 196 default font properties of paragraph formats FO_PgfFmt R 623 to R 625 of paragraphs FO_Pgf R 614 to R 616 default objects G 279 default print settings R 319 default rulings for cells in tables G 334 default scripts creating and customizing G 46 defined attributes G 348 deleting API objects G 158 to G 159 R 14 R 83 to R 90 dialog box items G 193 facets R 9 R 86 files G 377 R 372 flows G 158 hash tables R 392 menu item separators G 170 page frames R 84 rows G 158 to G 159 R 22 R 84 R 87 to R 88 structural elements R 337 to R 338 table
644. unction or FA_NotePostFunction iparm specifies the f code for the command F_ApiNotify can call API functions to get or set object properties or to initiate FrameMaker product operations The FrameMaker product calls F_ApiNotify only at the notification points for which your client has requested notification For example the following code prints the name of each document the user opens to the console VoidT F_Apilnitialize initialization IntT initialization if initialization FA_InitFirst F_ApiNotification FA_Note_PostOpenDoc True VoidT F_ApiNotify notification docId sparm iparm IntT notification F_ObjHandleT docId StringT sparm IntT iparm if notification FA_Note_PostOpenDoc F_Printf NULL The user opened s n sparm Canceling commands Your client can cancel any command or action for which it receives a FA_Note_PreNotificationPoint notification For example if it receives the FA_Note_PreQuitDoc notification it can cancel the Close command and prevent the user from closing a document To abort a command call F_ApiReturnValue with the parameter set to FR_CancelOperation when your client receives notification for the command For example the following code cancels the Exit command preventing the user from closing any documents FDK Programmer s Guide 37 a Creating Your Client s User Interface F_ApiNotification FA_Note_PreQuitDoc True VoidT F_ApiNot
645. unctions for R 5 R 253 to R 254 See also text text item structures text item types text line end type API representation of G 313 R 166 R 686 text lines API representation of the beginning of _G 313 R 166 R 686 API representation of the end of G 313 R 166 R 686 defined G 293 properties of R 606 to R 607 text locations F_TextLocT G 114 properties of functions for getting R 16 R 23 R 178 to R 179 functions for setting R 16 R 23 R 308 to R 309 structure for G 114 G 271 R 689 index 31 E Index Subjects text nodes R 96 text objects API representation of G 313 R 167 text properties G 311 G 317 R 669 to R 671 API representation of G 312 G 317 API representation of changes in G 312 G 314 G 317 R 166 changing individual G 125 getting G 123 to G 124 G 317 functions for R 16 R 23 R 179 to R 180 R 669 getting the value of function for R 182 to R 183 at the insertion point G 317 keeping intact G 306 setting G 93 G 124 to G 126 G 317 functions for R 17 R 23 R 309 to R 311 R 314 to R 316 R 669 type in G 126 G 284 G 391 R 573 to R 575 See also text locations F_TextLocT text ranges F_TextRangeT text ranges F_TextRangeT G 114 to G 117 R 689 centering function for R 51 to R 52 getting properties of G 114 to G 117 function for R 16 R 23 R 181 to R 182 getting textin G 118 R 181 to R 182 function for R 23 setting properties of G 114 to G 117 functions for R 17 R 23 R 311 to R
646. unique filter names clname contains the unique client name and binname contains the client s filename FDK Programmer s Guide 243 12 Using Imported Files and Insets 244 The values for informat and out format come from the registration data for a particular filter process For both import and export filters infile is the path of the file to filter and out file is the path for the resulting file The FrameMaker product supplies these values It s possible that the FrameMaker product has already created a file at the location specified by outfile however your client will need to create this file if it doesn t already exist The example on page 245 shows how to get the values stored in a F_FilterArgsT structure and how to call F_ChannelOpen to ensure you can write to out file How F_ApiNotify should respond The client s F_ApiNotify callback should do the following to respond to FrameMaker calling a file to file filter 1 Open the input file for reading and open the output file for writing The paths for these files are stored in the FilterArgsT data structure 2 Filter the infile into the outfile If you re filtering a graphic file that contains a complex graphic the client can create a graphic inset Graphic insets provide graphic data in standard formats such as TIFF or FrameVector which the FrameMaker product can use to display and print a graphic For more information on creating graphic i
647. ur client to the FrameMaker product s Modules folder e On Windows platforms add the following lines to the APIClients section of the maker ini file ClientName ClientType description path mode ClientName is the name that the FrameMaker product and other clients use to reference your client ClientType specifies your client type for example Standard DocReport or Text Import description is a string describing your client pathis the pathname of your 8 FDK Programmer s Guide Introduction to the Frame API aa client s DLL mode determines what product interfaces your client supports can be one of all maker or structured You can also register a Windows client by setting values in the DLL s VERSIONINFO resource then copying or moving the DLL in the PrameMaker product s Plugins folder For information on registering your client on a specific platform see the FDK Platform Guide for that platform A simple example The following client adds a menu with three items to the FrameMaker product menu bar when the FrameMaker product starts The first menu item closes the active document the second item sets the fill pattern of a selected graphic object the third item adds a body page to the active document Following the code is a line by line description of how it works include fapi h define CloseDoc 1 define SetFill 2 define AddPage 3 VoidT F_Apilnitialize initialization IntT i
648. urn Set up the FS_NewDoc property and set it to True params val 0 propIdent num FS_NewDoc propVal valType FT_Integer propVal u ival True params val O O O params val docId F_ApiOpen tmp template amp params amp returnParamsp See Saving documents and books on page 59 for syntax F_ApiSimpleSave docId tmp mynew doc False Deallocate property lists F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp IMPORTANT Jf you are creating a document with F_ApiOpen and you display the New dialog box by setting FS_ShowBrowser to True the user may click Portrait Custom or Landscape If this occurs F_ApiOpen does not create a new document It returns O and sets FA_errno to FE_WantsPortrait FE_WantsCustom or FE_WantsLandscape It is up to your client to create a portrait custom or landscape document by calling F_ApiCustomDoc Printing documents and books To print a document or book use F_ApiSilentPrintDoc F_ApiSilentPrintDoc uses the default print settings for a document The default print settings are the settings that appear in the Print dialog box when the user attempts to print the document in the user interface The syntax for F_ApiSilentPrintDoc is IntT F_ApiSilentPrintDoc F_ObjHandleT doclId This argument Means docId The ID of the document or book to print FDK Programmer s G
649. urrent platform view use the keyboard shortcut Esc d r FrameMaker clears the cached geometry information for the current view and notifies you that the geometry information is no longer cached When you switch to another view FrameMaker prompts you to save the current view since the geometry information is no longer cached If you do not want to cache the geometry information for the current view choose No in the alert box The next time you change to that view FrameMaker recalculates the geometry information For example suppose you make layout changes in the UNIX view and then change to the Windows view If the layout displayed in the Windows view does not match the layout in the UNIX view you need to reset the Windows view To update Windows view follow these steps 1 Press Esc dr to reset the Windows view which is the current platform view FrameMaker notifies you that the cached geometry information is cleared from local memory 2 Press Esc d x to change back to the UNIX view Since no geometry information is cached for the Windows view FrameMaker prompts you to save the current geometry information 3 In the alert box choose No FrameMaker does not cache any Windows geometry information and displays the UNIX view 4 Press Esc d w to change back to the Windows view Since no geometry information is cached for the Windows view FrameMaker recalculates the geometry information based on information from the UNIX view
650. use the FA_Note_ PreFunction or the FA Note _PostFunction notification instead of FA_NoteBackToUser IMPORTANT When the FrameMaker product performs a book wide command a command that process all documents in a book it posts an FA_NotePreFunction and FA_NotePostFinction notification for the book file and another for each document in the book When trapping book wide frunctions you should check the value of docId to determine whether it indicates a document or the active book For example if you search a book with two documents in it the FrameMaker product posts the following funtion notifications FA_Note_PreFunction start searching book 38 FDK Programmer s Guide Creating Your Client s User Interface a FA_Note_PreFunction start searching first document FA_Note_PostFunction stop searching first document FA_Note_PreFunction start searching second document FA_Note_PostFunction stop searching second document FA_Note_PostFunction stop searching book When the API issues an FA_Note_PreFunction or FA_Note _PostFunction notification it specifies the user action by setting iparm to a function code f code An f code is a hexadecimal code that specifies a command or other user action The following table shows some common f codes and the commands or user actions they specify F code Command or user action PGF_APPLY_TAG The user applied a paragraph format CHAR_APPLY_TAG The user applied a character format TXT_10 The use
651. veNativeError property F_ApiSave G 65 R 272 values of and associated status flags R 273 FS_SaveStatus property F_ApiSave G 65 R 273 status flags of R 273 FS_SaveTextExtraBlankLineAtEOP property F_ApiGetSaveDefaultParams R 156 FS_SaveTextTblSetting property F_ApiGetSaveDefaultParams R 156 FS_SgmlImportApplication property F_ApiGetImportDefaultParams R 123 FS_SgmlOpenApplication property F_ApiGetOpenDefaultParams R 144 FS_SgmlSaveApplication property F_ApiGetOpenDefaultParams R 156 FS_ShowBookErrorLog property F_ApiGetUpdateBookDefaultParams G 358 R 188 FS_ShowBrowser property F_ApiGetImportDefaultParams R 123 FS_ShowBrowser property F_ApiGetOpenDefaultParams G 49 R 144 FS_ShowRasterDpiDialog property F_ApiGetImportDefaultParams R 125 FS_ShowSaveTextDialog property F_ApiGetSaveDefaultParams R 157 FS_StructuredImportApplication property F_ApiGetImportDefaultParams R 123 FS_StructuredOpenA pplication property F_ApiGetOpenDefaultParams R 144 FS_StructuredSaveApplication property F_ApiGetOpenDefaultParams R 157 FS_TblNumHeadingRows property F_ApiGetImportDefaultParams R 126 FS_TextInsetName property F_ApiGetImportDefaultParams R 123 FDK Programmer s Reference amp Guide FS_TreatParaAsRow property F_ApiGetImportDefaultParams R 127 FS_UNIXpermissions property F_ApiGetSaveDefaultParams R 157 FS_UpdateBookGeneratedFiles property F_ApiGetUpdateBookDefault
652. w text frame and connects it In structured documents a structured flow contains structural elements An anchor that appears in the main text as a number letter or special character Using API functions to determine and get one or more characteristics of an object 389 390 global document information graphic object hidden page ID inset MIF named graphic frames named objects object page frame parent frame properties property value Characteristics that apply to an entire document Anything that the user can create with the Tools palette Specifically a graphic object can be an anchored frame an unanchored frame a geometric shape a line arc rectangle rounded rectangle oval polyline or polygon a group of other graphic objects in a frame together a text line a text frame an imported graphic an equation or an inset The page where FrameMaker stores hidden conditional text A document can have only one hidden page The API represents each hidden page with an FO_HiddenPage object Identifier for an API object IDs are typed as F_ObjHandleT 32 bit integers An imported image created with an inset editor a specially modified external application that can be launched from FrameMaker Maker Interchange Format a set of ASCII statements that describes a FrameMaker document or book Frames on reference pages that contain a graphic decoration such as a line ruling for paragraphs in
653. wStruct structure FDK Programmer s Guide FDE Utility Libraries 18 Structure type names use the suffix StructT For example the structure type name for MifTextFlowStruct is MifTextFlowStructT Each of the substatements in a MIF statement is represented as a field whose name corresponds to the name of the substatement For example the FDE represents the statement lt Marker lt MType N gt lt MText string gt gt with the structure typedef struct MifMarkerStruct IntT MType StringT MText MifMarkerStructT If a substatement is a structure a pointer in the structure points to the structure that represents the substatement For example the FDE represents the statement lt Para lt Pgf gt gt with typedef struct MifParaStruct MifPgfStructT Pgf MifParaStructT If a substatement is a list of structures it is represented as a link structure The link structure s name contains a Mif prefix the substatement name anda StructL suffix The link structure type includes the suffix StructLT A pointer in the structure points to the link structure of the substatement For example the FDE represents the statement lt AFrames lt Frame gt gt with typedef struct MifAFrameStruct struct MifFrameStructL Frame MifAFrameStructT where the field Frame contains a list of all the frames associated with AFrame To get or set a field in a MIF data structure use MIF macros MIF macro names contain
654. wing code converts the UNIX pathname tmp myfile toa filepath FilePathT path path F_PathNameToFilePath tmp myfile NULL FUnixPath F_FilePathFree path1 IMPORTANT Jf you call a function typed FilePathT you must use F_FilePathFree to free the returned pointer when you are done with it The following code converts the filepath created above back to a UNIX pathname FDK Programmer s Guide 375 Making I O and Memory Calls Portable 376 FilePathT path StringT pathname pathname F_FilePathToPathName path FUnixPath You don t have to convert a filepath back to the platform specific pathname it was originally created from you can convert it to a pathname for any platform the FDE supports For example the following code converts the filepath created above to a Windows pathname FilePathT path StringT pathname pathname F_FilePathToPathName path FDosPath To makea F_FilePathToPathName and F_PathNameToFilePath call platform independent set the second parameter to FDefaultPath This instructs the function to use the pathname conventions of the platform the client is currently running on For example the following code converts a filepath to a pathname for the current platform FilePathT path StringT pathname pathname F_FilePathToPathName path FDefaultPath FDE filepath functions such as F_PathNameToFilePath and F_FilePathToPathName have arguments that specify a path
655. x events that don t apply to specific dialog items If one of these events occurs the API sets the itemNum parameter of the F_ApiDialogEvent function to one of the following negative integer constants Constant Event FV_DlgClose The dialog box closed A dialog box closes when the user makes a dialog close gesture such as pressing Control c when the user exits the FrameMaker product It also closes the dialog box when your client specifies the dialog box ID in a call to F_ApiClose and your code does not call F_ApiReturnValue to set a return value of FR_ModalStayUp The API does not specify how a dialog box is closed it sets itemNum to FV_DlgClose regardless of how the dialog box was closed FV_DlgEnter The user moved input focus to the dialog box This event does not occur on UNIX platforms F V_D1gNoChange The user pressed Shift F8 to set all the items in a dialog box to their As Is states FV_DlgReset The user pressed Shift F9 to reset the items in the dialog box to the values they had the last time the user clicked Apply FV_DlgUndo The user chose Undo Command z on the Macintosh or Control z on Windows platforms This event does not occur on UNIX platforms 226 FDK Programmer s Guide Handling Custom Dialog Box Events Some FrameMaker product dialog boxes such as the Paragraph Designer and the Character Designer support the FV_DlgNoChange and FV_DlgReset events If your client uses dialog boxes si
656. x of property specifying filename and display it i F_ApiGetPropIndex returnParamsp FS_SavedFileName F_Sprintf msg Saved s returnParamsp gt val i propVal u sval F_ApiAlert msg FF_ALERT_CONTINUE_NOTE Deallocate Save scripts F_ApiDeallocatePropVals amp params F_ApiDeallocatePropVals returnParamsp Closing documents and books To close a document or book use F_ApiClose The syntax for F_ApiClose is IntT F_ApiClose F_ObjHandleT Id IntT flags This argument Means Id The ID of the document book or session to close To close the session specify FV_SessionlId flags Specifies whether to abort or to close open documents or books if they have unsaved changes Set the FF_CLOSE_MODIFIED flag to close open documents and books regardless of their state 66 FDK Programmer s Guide Executing Commands with API Functions 4 F_ApiClose behaves somewhat differently than the Close command in the user interface If there are unsaved changes in a file and you set FF_CLOSE_MODIFIED forthe flags argument F_ApiClose abandons the changes and closes the file anyway If you set flags to 0 F_ApiClose aborts the Close operation and returns FE_DocModi fied IMPORTANT Jf you are closing an individual document make sure Id specifies a valid document ID and not 0 If Id is setto 0 F_ApiClose quits the Frame session because FV_SessionId is de
657. xt e Get the rubi location e Insert the rubi text Once you have a rubi group you can get the text range for the oyamoji and rubi text In this way you can edit the rubigroup contents The following example shows how to create a new rubi group F_TextRangeT tr oyamojiTr rubiTr F_ObjHandle docId rubiGrpId StringT sl s2 Assuming known contents in sl and Hiragana chars in s2 FDK Programmer s Guide 131 Manipulating Asian Text docId F_ApiGetID 0 FV_SessionId FP_ActiveDoc tr F_ApiGetTextRange FV_SessionId docId FP_TextSelection if tr beg objId 0 return Insert the Rubi Group rubiGrpId F_ApiNewAnchoredObject docId FO Rubi amp tr beg Get the location of the oyamoji and add the text oyamojiTr F_ApiGetTextRange docId rubiGrpId FP_OyamojiTextRange F_ApiAddText docId amp oyamogiTr beg s1 Get the location of the rubi and add the text rubiTr F_ApiGetTextRange docId rubiGrpId FP_RubiTextRange F_ApiAddText docId amp rubiTr beg s2 Text encodings Asian character sets include thousands of characters and so the single byte range used for Roman character sets is insufficient Asian character sets use single and double byte codes to identify each character They also reserve the same single byte encodings for nearly every character in the 7 bit ASCII range Any differences among characters in the ASCII range are relatively insignificant For
658. xt frame the API automatically creates a flow to contain it For example to create a flow on the first body page of the active document you can use the following code F_ObjHandleT docId tFramelId flowId pageId pFrameld Get ID of first body page s page frame docId F_ApiGetId 0 FV_SessionId FP_ActiveDoc pageId F_ApiGetId FV_SessionId docId FP_FirstBodyPageInDoc tFramelId F_ApiGetId docId pageId FP_PageFrame Create the text frame and get the flow s ID from it tFramelId F_ApiNewGraphicObject docId FO_TextFrame pFramelId flowId F_ApiGetId docId tFramelId FP_Flow To connect a text frame in a flow set its FP_NextTextFrameInF low or FP_PrevTextFrameInFlow property to the ID of a text frame that is already in the flow To disconnect a text frame from a flow set its FP_NextTextFrameInFlow or FP_PrevTextFrameInFlow property to 0 Creating structural elements The API provides the following functions for creating structural elements in FrameMaker documents and books e F_ApiNewElement inserts a new element at a specified text location in a document e F_ApiNewElementInHierarchy inserts a new element at a specified position in the element hierarchy of a document or book The syntax for F_ApiNewElement is 150 FDK Programmer s Guide Creating and Deleting API Objects Ba F_ObjHandleT F_ApiNewElement F_ObjHandleT docId F_ObjHandleT elemDefId F_TextLocT textLocp
659. xt range one or more child elements or anything you can insert in text such as variables or tables Each structural element has an element definition specifying what its format and contents should be Elements in a document can have the same element definition For example a document may have several elements with a Para element definition For more information on element definitions see Structural element definitions on page 342 The elements in a container element are called its child elements Child elements can also be containers container elements can be nested The element definition s general rule specifies a container s allowable child elements or text and the order in which they should occur FDK Programmer s Guide 347 14 Frame Document Architecture 348 A container element can violate its content rule by omitting required child elements by including excluded child elements or by having the elements in the wrong order If a container element obeys its content rule it is said to be valid Elements can also have attributes which correspond to SGML or XML attributes An attribute can be a defined attribute which is defined in the element s element definition or an undefined attribute which is not defined in the element s element definition How the API represents structural elements FrameMaker represents a structural element with an FO_Element object whose properties provide the following information
660. xt to it and then relock it F_ApiSetInt docId insetId FP_TiLocked False F_ApiAddText docId amp tr beg Inset text F_ApiSetInt docId insetId FP_TiLocked True Set some other inset info F_ApiSetString docId insetId FP_TiClientData Select Where F_ApiSetString docId insetId FP_TiClientSource Larry s SQL Client F_ApiSetString docId insetId FP_TiClientType SOL Query Updating a client text inset The API issues the following notifications when client text insets need to be updated e FA_Note_UpdateAl11ClientTi when the user or an FDK client has instructed the FrameMaker product to update all the insets in the document e FA_Note_UpdateClientTi when the user or an FDK client has instructed the FrameMaker product to update one of your client s insets When it issues these notifications the API sets the docId parameter of your client s F_ApiNotify callback to the ID of the enclosing document For the FA_Note_UpdateClientTi notification it also sets the iparm parameter of your client s F_ApiNotify callback to the ID of the inset Your client can use the FP_LastUpdate property of an inset to determine whether it is stale To keep your client s text insets updated you should request these notifications and include code in your client s F_ApiNotify callback to handle them To modify a client text inset s contents you must first unlock it by s
661. y FO_TextFrame G 299 R 605 FP_FirstTblFmtInDoc property FO_Doc G 283 G 331 R 539 FP_FirstTblInDoc property FO_Doc G 283 R 539 FP_FirstTextFrameInFlow property FO_Flow G 298 R 580 FP_FirstTiInDoc property FO_Doc G 283 R 539 FP_FirstVarFmtInDoc property FO_Doc G 282 R 539 FP_FirstVarInDoc property FO_Doc G 282 R 539 FP_FirstVis property FO_DlgScrollBox R 536 FP_FirstXRefFmtInDoc property FO_Doc G 282 R 539 FP_FirstXRefInDoc property FO_Doc G 282 R 540 FP_Flow property FO_TextFrame G 270 R 605 FP_FlowIsAutoConnect property FO_Flow R 580 FP_FlowlIsFeathered property FO_Flow R 580 FP_FlowlIsPostScript property FO_Flow R 580 FP_FlowIsSynchronized property FO_Flow R 580 FP_FlowTreeRoot property FO_Flow G 300 FP_FM_BinDir property FO_Session R 632 FP_FM_CurrentDir property FO_Session R 632 FP_FM_HelpDir property FO_Session R 633 FP_FM_HomeDir property FO_Session R 633 FP_FM_InitDir property FO_Session R 633 FP_FM_SgmIDir property FO_Session R 637 FP_FM_StructureDir property FO_Session R 637 FP_FM_XmIDir property FO_Session R 638 FP_Fmt property FO_VarFmt G 325 R 672 FP_Fmt property FO_XRefFmt G 323 R 531 FP_FmtChangeList property G 107 FP_FmtChangeList property FO_FmtRuleClause G 346 R 591 FP_FmtChangeListName property FO_FmtRuleClause R 591 FP_FmtChangeListTag property G 107 G 153 FP_FmtRule property FO_FmtRuleClause G 346 R 591 FP_FmtRuleClause pr
662. ype G 314 R 171 R 688 FTI_RubiTextEnd text item type G 314 R 171 R 688 FTI_String text item type G 313 G 324 G 326 R 166 R 686 FTI_SubColBegin text item type G 313 R 166 R 687 FTI_SubColEnd text item type G 313 R 167 R 687 FTI_TblAnchor text item type G 312 G 313 G 332 R 167 R 687 FTI_TextFrameBegin text item type G 313 R 167 R 687 FTI_TextFrameEnd text item type G 313 R 167 R 687 FTI_TextInsetBegin text item type G 314 R 167 FTI_TextInsetEnd text item type G 314 R 167 FTI_TextObjld text item type G 313 R 167 R 686 index 70 FTI_VarBegin text item type G 314 G 326 G 327 R 167 R 687 FTI_VarEnd text item type G 314 G 326 G 327 R 167 R 687 FTI_XRefBegin text item type G 314 G 323 R 167 R 687 FTI_XRefEnd text item type G 314 G 323 R 167 R 687 FunctionT data type G 367 FUnixPath path type G 376 FV_ FV_AllElements flag modifiers R 91 FV_ALTERNATIVE constant F_ElementCatalogEntryT R 113 R 683 FV_AT_CHOICES constant F_AttributeDefT R 109 FV_AT_INTEGER constant F_AttributeDefT R 109 FV_AT_INTEGERS constant F_AttributeDefT R 109 FV_AT_REAL constant F_AttributeDefT R 109 FV_AT_REALS constant F_AttributeDefT R 109 FV_AT_STRING constant F_AttributeDefT R 109 FV_AT_UNIQUE_ID constant F_AttributeDefT R 109 FV_AT_UNIQUE_IDREF constant F_AttributeDefT R 109 FV_AT_UNIQUE_IDREFS constant F_AttributeDefT R 109 FV_BadEnclosingDocld status flag FS_ImportStatu
663. ypertextValidateErr R 555 FV_HypertextDestinationLinkNotFound constant FP_HypertextValidateErr R 554 FV_HypertextEmptyCommand constant FP_HypertextParseErr R 553 FV_HypertextEmptyLineInMiffleOfPopup constant FP_HypertextValidateErr R 555 FV_HypertextExpectedNumberParam constant FP_HypertextParseErr R 554 FV_HypertextExtraArguments constant FP_HypertextParseErr R 553 FV_HypertextFcodeInvalid constant FP_HypertextValidateErr R 555 FV_HypertextFileNotMakerDoc constant FP_HypertextValidateErr R 554 FV_HypertextFileNotRegular constant FP_HypertextValidateErr R 554 FV_HypertextFlowMissingLines constant FP_HypertextValidateErr R 554 FV_HypertextHelpDirNotFound constant FP_HypertextParseErr R 554 FV_HypertextMatrixCommandInvalid constant FP_HypertextValidateErr R 554 FV_HypertextMissingArguments constant FP_HypertextParseErr R 553 FV_HypertextMissingPopupLabelltem constant FP_HypertextValidateErr R 555 FV_HypertextMissingPopupMarker constant FP_HypertextValidateErr R 555 FV_HypertextNoNamedFlow constant FP_HypertextValidateErr R 554 FV_HypertextObjectIdNotFound constant FP_HypertextValidateErr R 554 FV_HypertextPageNameNotFound constant FP_HypertextValidateErr R 554 FV_HypertextRecursiveFlow constant FP_HypertextValidateErr R 555 FV_HypertextSyntaxOK constant FP_HypertextParseErr R 553 FDK Programmer s Reference amp Guide FV_HypertextUnanchoredPartialPath constant FP_HypertextParseErr R 554

14 - Docu + Design Daube

Contents

Download Pdf Manuals

Related Search

Related Contents