Adobe FDK Programmer’s Reference Frame Maker 11.0 Framemaker11 Fdkref

User Manual: adobe FrameMaker - 11.0 - FDK Programmer’s Reference Free User Guide for Adobe FrameMaker Software, Manual

Open the PDF directly: View PDF PDF.
Page Count: 1049

DownloadAdobe FDK Programmer’s Reference Frame Maker - 11.0 Framemaker11 Fdkref
Open PDF In BrowserView PDF
FDK Programmer’s Reference
VERSION 11

Frame Developer’s Kit,
November 2012

Adobe Systems Incorporated

Corporate Headquarters
345 Park Avenue
San Jose, CA 95110-2704
(408) 536-6000

© 2012 Adobe Systems Incorporated and its licensors. All rights reserved.
Adobe® FrameMaker® 11 for Windows® Frame Developer’s Kit for Windows
This manual is protected under copyright law, 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 the informational content contained in this manual.
This manual is licensed for use under the terms of the Creative Commons Attribution Non-Commercial 3.0 License. This License allows users to copy,
distribute, and transmit the manual for noncommercial purposes only so long as (1) proper attribution to Adobe is given as the owner of the manual; and (2)
any reuse or distribution of the manual contains a notice that use of the manual is governed by these terms. The best way to provide notice is to include the
following link. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/3.0/us/
Adobe, the Adobe logo, Adobe AIR, Adobe Captivate, Adobe Type Manager, Acrobat, AIR, Creative Suite, Distiller, Flash, FrameMaker, Illustrator,
PageMaker, Photoshop, PostScript, Reader, RoboHelp, and RoboScreenCapture are trademarks of Adobe Systems Incorporated in the United States and/or
other countries.
Microsoft, Windows, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other
countries. Solaris is a trademark or registered trademark of Oracle and/or its affiliate. SVG is a trademark of the World Wide Web Consortium; marks
of the W3C are registered and held by its host institutions MIT, INRIA, and Keio.
Updated Information/Additional Third Party Code Information available at http://www.adobe.com/go/thirdparty.
Portions include software under the following terms:
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
This Program was written with MacApp®: ©1985-1988 Apple Computer, Inc. APPLE COMPUTER, INC. MAKES NO WARRANTIES WHATSOEVER,
EITHER EXPRESS OR IMPLIED, REGARDING THIS PRODUCT, INCLUDING WARRANTIES WITH RESPECT TO ITS MERCHANTABILITY OR ITS
FITNESS FOR ANY PARTICULAR PURPOSE. The MacApp software is proprietary to Apple Computer, Inc. and is licensed to Adobe for distribution only
fors use in combination with Adobe FrameMaker.
Portions copyright 1984-1998 Faircom Corporation. "FairCom" and "c-tree Plus" are trademarks of Faircom Corporation and are registered in the United States
and other countries. All Rights Reserved.
MPEG Layer-3 audio compression technology licensed by Fraunhofer IIS and THOMSON multimedia (http://www.iis.fhg.de/amm).
ImageStream Graphics Filters and ImageStream are registered trademarks of Inso Corporation.
Portions utilize code licensed from Nellymoser (www.nellymoser.com)
Adobe Flash Player 10 video compression and decompression is powered by On2 TrueMotion video technology. © 1992-2005 On2 Technologies, Inc. All Rights
Reserved. http://www.on2.com.
Certain trademarks are owned by The Proximity Division of Franklin Electronic Publishers, Inc., and are used by permission. Merriam-Webster is a
trademark of Merriam-Webster, Inc.
This product contains either BSAFE and/or TIPEM software by RSA Data Security, Inc.

Sorenson Spark™ video compression and decompression technology licensed from Sorenson Media, Inc.
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 Software 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 herein. Unpublished-rights reserved under the copyright laws of the United
States. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of
Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the
Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and
regulations contained in the preceding sentence shall be incorporated by reference.

.....
The latest version of this document is available online at
http://www.adobe.com/devnet/framemaker.html

I M P O R TA N T N O T I C E

Contents

.....

..................................

1

What’s New in FDK 11 ............................................................................................... 17
Key catalogs for key-based (indirect) referencing ........................................................ 17
New APIs for key catalog functionality...................................................................... 18
New FDK APIs to update DITA references ................................................................. 18
Support for object styles ............................................................................................... 19
Support for multiple views ........................................................................................... 19
Support for hotspots in objects ..................................................................................... 19
Interactive multimedia links for 3D objects ................................................................. 20
Support for referring to content using line numbers ..................................................... 21
Support for guided structured authoring with banner text ............................................ 21
New APIs, notifications, error codes, objects, and properties ...................................... 21
New APIs .................................................................................................................... 21
New notifications ........................................................................................................ 22
New error codes .......................................................................................................... 22
New objects................................................................................................................. 23
New properties ............................................................................................................ 23
CMS Connector Framework ......................................................................................... 26

2

Function Summary ..................................................................................................... 27
Client-defined callback functions ............................................................................... 28
Books .......................................................................................................................... 28
Characters.................................................................................................................... 30
Clipboard..................................................................................................................... 31
Commands and menus ................................................................................................ 31
Data structures: copying.............................................................................................. 33
Debugging................................................................................................................... 33
DITA references: updating.......................................................................................... 35
Dialog boxes: predefined ............................................................................................ 35
Dialog boxes: client-defined ....................................................................................... 35
Documents: comparing ............................................................................................... 37
Documents: file operations ......................................................................................... 37
Documents: formatting ............................................................................................... 38
Documents: updating .................................................................................................. 38
F-codes ........................................................................................................................ 39
Files, directories, and filepaths ................................................................................... 39
Fonts............................................................................................................................ 41
Graphic insets.............................................................................................................. 41
Hash tables .................................................................................................................. 42
Hypertext..................................................................................................................... 42
FDK Programmer’s Reference

1

Contents

I/O ............................................................................................................................... 42
Insets ........................................................................................................................... 43
Key Catalogs ............................................................................................................... 44
Memory: allocating and deallocating structures ......................................................... 44
Memory: manipulating with handles .......................................................................... 46
Memory: manipulating with pointers.......................................................................... 46
Menus.......................................................................................................................... 47
Metrics ........................................................................................................................ 48
Maker Interchange Format (MIF) ............................................................................... 48
Objects: creating and deleting..................................................................................... 50
Objects: getting IDs .................................................................................................... 52
Printing........................................................................................................................ 52
Properties .................................................................................................................... 52
Selection...................................................................................................................... 54
Sessions....................................................................................................................... 54
Sleep............................................................................................................................ 54
String lists.................................................................................................................... 54
Strings: allocating, copying, and deallocating ............................................................ 56
Strings: comparing and parsing................................................................................... 56
Strings: concatenating ................................................................................................. 58
Strings: miscellaneous................................................................................................. 58
Strings: encoded ......................................................................................................... 59
Structure: manipulating elements................................................................................ 59
Structure: manipulating element definitions and format rules.................................... 61
Tables .......................................................................................................................... 61
Text.............................................................................................................................. 63
Text: find and replace.................................................................................................. 63
Text insets ................................................................................................................... 64
Unicode ...................................................................................................................... 64
Undo/Redo .................................................................................................................. 64
Utility .......................................................................................................................... 66
3

2

FDK Programmer’s Reference

FDK Function Reference ............................................................................................ 67
F_Alloc()......................................................................................................................... 68
F_AllocHandle() ............................................................................................................. 69
F_ApiAddCols() ............................................................................................................. 70
F_ApiAddCommandToMenu() ...................................................................................... 72
F_ApiAddMenuToMenu().............................................................................................. 74
F_ApiAddRows()............................................................................................................ 78
F_ApiAddText() ............................................................................................................. 80
F_ApiAlert() ................................................................................................................... 82
F_ApiAlive()................................................................................................................... 85
F_ApiAllocatePropVals() ............................................................................................... 85
F_ApiAllocateTextItems().............................................................................................. 86
F_ApiApplyAttributeExpression() ................................................................................. 88
F_ApiApplyAttributeExpressionAsCondition()............................................................. 89
F_ApiApplyPageLayout() .............................................................................................. 90
F_ApiBailOut()............................................................................................................... 92

...

Contents

F_ApiCallClient() ........................................................................................................... 93
F_ApiCenterOnText()..................................................................................................... 94
F_ApiCheckStatus()........................................................................................................ 96
F_ApiChooseFile() ......................................................................................................... 97
F_ApiClear()................................................................................................................. 100
F_ApiClearAllChangebars()......................................................................................... 102
F_ApiClientDir() .......................................................................................................... 103
F_ApiClientName() ...................................................................................................... 104
F_ApiClientPath()......................................................................................................... 106
F_ApiClose() ................................................................................................................ 107
F_ApiCombinedFamilyFonts()..................................................................................... 109
F_ApiCommand()......................................................................................................... 111
F_ApiCompare()........................................................................................................... 112
F_ApiConnectToSession()............................................................................................ 115
F_ApiCopy()................................................................................................................. 115
F_ApiCopyStructureType() .......................................................................................... 118
F_ApiCustomDoc() ...................................................................................................... 119
F_ApiCut().................................................................................................................... 123
F_ApiDeallocateStructureType().................................................................................. 125
F_ApiDefineAndAddCommand() ................................................................................ 126
F_ApiDefineAndAddCommandEx()............................................................................ 129
F_ApiDefineAndAddMenu()........................................................................................ 134
F_ApiDefineCommand() .............................................................................................. 137
F_ApiDefineCommandEx().......................................................................................... 139
F_ApiDefineMenu() ..................................................................................................... 141
F_ApiDelete() ............................................................................................................... 143
F_ApiDeleteAllKeyDefinitions() ................................................................................. 144
F_ApiDeleteCols()........................................................................................................ 145
F_ApiDeletePropByName() ......................................................................................... 147
F_ApiDeleteRows() ...................................................................................................... 148
F_ApiDeleteText()........................................................................................................ 151
F_ApiDeleteTextInsetContents().................................................................................. 152
F_ApiDialogEvent() ..................................................................................................... 155
F_ApiDialogItemId() .................................................................................................... 158
F_ApiDisconnectFromSession()................................................................................... 159
F_ApiEnableUnicode()................................................................................................. 162
F_ApiErr() .................................................................................................................... 164
F_ApiFamilyFonts() ..................................................................................................... 165
F_ApiFcodes() .............................................................................................................. 167
F_ApiFind() .................................................................................................................. 168
F_ApiGetAllKeyDefinitions() ...................................................................................... 175
F_ApiGetAllKeys() ...................................................................................................... 185
F_ApiGetEncodingForFamily().................................................................................... 187
F_ApiGetEncodingForFont()........................................................................................ 189
F_ApiGetId() ................................................................................................................ 191
F_ApiGetImportDefaultParams() ................................................................................. 193
F_ApiGetInt() ............................................................................................................... 201
F_ApiGetIntByName() ................................................................................................. 203

FDK Programmer’s Reference

3

Contents

F_ApiGetInts().............................................................................................................. 204
F_ApiGetKeyCatalog()................................................................................................. 206
F_ApiGetKeyDefinition()............................................................................................. 207
F_ApiGetMetric() ......................................................................................................... 209
F_ApiGetMetricByName()........................................................................................... 210
F_ApiGetMetrics()........................................................................................................ 212
F_ApiGetNamedObject().............................................................................................. 214
F_ApiGetNewXMLDefaultParams()............................................................................ 215
F_ApiGetObjectType()................................................................................................. 218
F_ApiGetOpenDefaultParams() ................................................................................... 219
F_ApiGetPoints().......................................................................................................... 228
F_ApiGetPropIndex() ................................................................................................... 230
F_ApiGetProps()........................................................................................................... 231
F_ApiGetPropVal() ...................................................................................................... 232
F_ApiGetSaveDefaultParams() .................................................................................... 234
F_ApiGetString() .......................................................................................................... 241
F_ApiGetStrings() ........................................................................................................ 242
F_ApiGetSupportedEncodings() .................................................................................. 244
F_ApiGetTabs() ............................................................................................................ 245
F_ApiGetText() ............................................................................................................ 249
F_ApiGetText2() .......................................................................................................... 256
F_ApiGetTextForRange()............................................................................................. 260
F_ApiGetTextForRange2()........................................................................................... 261
F_ApiGetTextLoc() ...................................................................................................... 264
F_ApiGetTextProps() ................................................................................................... 265
F_ApiGetTextPropVal() ............................................................................................... 267
F_ApiGetTextRange() .................................................................................................. 269
F_ApiGetTextVal()....................................................................................................... 271
F_ApiGetUBytesByName().......................................................................................... 273
F_ApiGetUniqueObject() ............................................................................................. 275
F_ApiGetUpdateBookDefaultParams()........................................................................ 278
F_ApiGetVal() .............................................................................................................. 282
F_ApiHypertextCommand()......................................................................................... 285
F_ApiImport()............................................................................................................... 286
F_ApiInitialize() ........................................................................................................... 293
F_ApiIsEncodingSupported()....................................................................................... 295
F_ApiLoadMenuCustomizationFile() .......................................................................... 296
F_ApiMakeTblSelection() ............................................................................................ 297
F_ApiMenuItemInMenu() ............................................................................................ 298
F_ApiMessage()............................................................................................................ 303
F_ApiModalDialog() .................................................................................................... 303
F_ApiModelessDialog() ............................................................................................... 305
F_ApiMoveComponent().............................................................................................. 306
F_ApiNetLibSetAuthFunction()................................................................................... 307
F_ApiNewAnchoredFormattedObject() ....................................................................... 310
F_ApiNewAnchoredObject()........................................................................................ 312
F_ApiNewBookComponentOfTypeInHierarchy()....................................................... 316
F_ApiNewGraphicObject() .......................................................................................... 322

4

FDK Programmer’s Reference

...

Contents

F_ApiNewKeyCatalog()............................................................................................... 324
F_ApiNewKeyDefinition()........................................................................................... 325
F_ApiNewNamedObject()............................................................................................ 327
F_ApiNewSeriesObject().............................................................................................. 329
F_ApiNewTable()......................................................................................................... 336
F_ApiNewXML() ......................................................................................................... 338
F_ApiNotification() ...................................................................................................... 339
F_ApiNotify() ............................................................................................................... 349
F_ApiObjectValid() ...................................................................................................... 354
F_ApiOpen()................................................................................................................. 355
F_ApiOpenResource() .................................................................................................. 363
F_ApiPaste() ................................................................................................................. 364
F_ApiPopClipboard() ................................................................................................... 366
F_ApiPrintFAErrno().................................................................................................... 367
F_ApiPrintImportStatus() ............................................................................................. 369
F_ApiPrintOpenStatus() ............................................................................................... 370
F_ApiPrintPropVal() .................................................................................................... 370
F_ApiPrintPropVals()................................................................................................... 371
F_ApiPrintSaveStatus() ................................................................................................ 372
F_ApiPrintTextItem() ................................................................................................... 373
F_ApiPrintTextItems().................................................................................................. 374
F_ApiPrintUpdateBookStatus().................................................................................... 375
F_ApiProgressBarEx().................................................................................................. 376
F_ApiPromptInt() ......................................................................................................... 379
F_ApiPromptMetric() ................................................................................................... 381
F_ApiPromptString() .................................................................................................... 382
F_ApiPushClipboard().................................................................................................. 384
F_ApiQuickSelect() ...................................................................................................... 385
F_ApiRedisplay().......................................................................................................... 386
F_ApiReformat() .......................................................................................................... 388
F_ApiRehyphenate()..................................................................................................... 389
F_ApiResetEqnSettings() ............................................................................................. 390
F_ApiResetReferenceFrames()..................................................................................... 391
F_ApiRestartPgfNumbering() ...................................................................................... 392
F_ApiReturnValue() ..................................................................................................... 393
F_ApiSave().................................................................................................................. 399
F_ApiScrollBox() ......................................................................................................... 402
F_ApiScrollToText() .................................................................................................... 404
F_ApiService().............................................................................................................. 405
F_ApiSetAttributeSimple()........................................................................................... 411
F_ApiSetClientDir() ..................................................................................................... 412
F_ApiSetId() ................................................................................................................. 414
F_ApiSetInt() ................................................................................................................ 417
F_ApiSetIntByName().................................................................................................. 419
F_ApiSetInts() .............................................................................................................. 421
F_ApiSetMetric().......................................................................................................... 423
F_ApiSetMetricByName()............................................................................................ 425
F_ApiSetMetrics() ........................................................................................................ 426

FDK Programmer’s Reference

5

Contents

F_ApiSetPoints() .......................................................................................................... 429
F_ApiSetProps() ........................................................................................................... 432
F_ApiSetPropVal() ....................................................................................................... 434
F_ApiSetString()........................................................................................................... 436
F_ApiSetStrings() ......................................................................................................... 438
F_ApiSetTabs()............................................................................................................. 441
F_ApiSetTextLoc()....................................................................................................... 444
F_ApiSetTextProps() .................................................................................................... 445
F_ApiSetTextPropVal()................................................................................................ 447
F_ApiSetTextRange()................................................................................................... 450
F_ApiSetTextVal() ....................................................................................................... 452
F_ApiSetUBytesByName() .......................................................................................... 454
F_ApiShutDown() ........................................................................................................ 455
F_ApiSilentPrintDoc().................................................................................................. 456
F_ApiSimpleGenerate()................................................................................................ 459
F_ApiSimpleImportFormats() ...................................................................................... 462
F_ApiSimpleNewDoc() ................................................................................................ 464
F_ApiSimpleOpen()...................................................................................................... 465
F_ApiSimpleSave() ...................................................................................................... 466
F_ApiSleep()................................................................................................................. 468
F_ApiStraddleCells() .................................................................................................... 470
F_ApiStringLen().......................................................................................................... 471
F_ApiUndoCancel()...................................................................................................... 474
F_ApiUndoEndCheckPoint()........................................................................................ 475
F_ApiUndoStartCheckPoint() ...................................................................................... 476
.F_ApiUnStraddleCells() .............................................................................................. 477
F_ApiUpdateBook() ..................................................................................................... 480
F_ApiUpdateDITAReference() .................................................................................... 483
F_ApiUpdateDITAReferences()................................................................................... 485
F_ApiUpdateKeyDefinition()....................................................................................... 487
F_ApiUpdateTextInset()............................................................................................... 488
F_ApiUpdateVariables()............................................................................................... 489
F_ApiUpdateXRef() ..................................................................................................... 490
F_ApiUpdateXRefs().................................................................................................... 492
F_ApiUserCancel()....................................................................................................... 494
F_ApiUSleep().............................................................................................................. 494
F_ApiWinConnectSession() ......................................................................................... 495
F_ApiWinInstallDefaultMessageFilter() ...................................................................... 496
F_Assert() ..................................................................................................................... 498
F_Calloc() ..................................................................................................................... 499
F_ChannelAppend()...................................................................................................... 500
F_ChannelClose() ......................................................................................................... 501
F_ChannelCloseTmp().................................................................................................. 502
F_ChannelEof() ............................................................................................................ 502
F_ChannelFlush() ......................................................................................................... 503
F_ChannelMakeTmp().................................................................................................. 503
F_ChannelOpen().......................................................................................................... 504
F_ChannelPeek() .......................................................................................................... 506

6

FDK Programmer’s Reference

...

Contents

F_ChannelRead() .......................................................................................................... 506
F_ChannelSeek() .......................................................................................................... 508
F_ChannelSize() ........................................................................................................... 509
F_ChannelTell()............................................................................................................ 510
F_ChannelWrite() ......................................................................................................... 511
F_CharIsAlphabetic() ................................................................................................... 512
F_CharIsAlphaUTF8().................................................................................................. 513
F_CharIsAlphaNumeric() ............................................................................................. 514
F_CharIsAlphaNumericUTF8().................................................................................... 515
F_CharIsControl()......................................................................................................... 515
F_CharIsControlUTF8() ............................................................................................... 516
F_CharIsDoubleByte().................................................................................................. 517
F_CharIsDoubleByteFirst() .......................................................................................... 518
F_CharIsDoubleByteSecond()...................................................................................... 520
F_CharIsEol() ............................................................................................................... 521
F_CharIsEolUTF8()...................................................................................................... 522
F_CharIsHexadecimal()................................................................................................ 523
F_CharIsHexadecimalUTF8() ...................................................................................... 524
F_CharIsLower() .......................................................................................................... 525
F_CharIsLowerUTF8()................................................................................................. 525
F_CharIsNumeric()....................................................................................................... 526
F_CharIsNumericUTF8() ............................................................................................. 527
F_CharIsUpper()........................................................................................................... 528
F_CharIsUpperUTF8() ................................................................................................. 528
F_CharToLower()......................................................................................................... 529
F_CharToLowerUTF8() ............................................................................................... 530
F_CharToUpper() ......................................................................................................... 531
F_CharToUpperUTF8()................................................................................................ 532
F_CharUTF16ToUTF8() .............................................................................................. 533
F_CharUTF32ToUTF8() .............................................................................................. 534
F_CharUTF8ToUTF16() .............................................................................................. 535
F_CharUTF8ToUTF32() .............................................................................................. 536
F_ClearHandle() ........................................................................................................... 537
F_ClearPtr() .................................................................................................................. 537
F_CopyPtr() .................................................................................................................. 538
F_DeleteFile()............................................................................................................... 539
F_DigitValue().............................................................................................................. 540
F_DuplicateHandle() .................................................................................................... 541
F_DuplicatePtr() ........................................................................................................... 542
F_Exit()......................................................................................................................... 543
F_FdeEncodingsInitialized() ........................................................................................ 544
F_FdeInit() .................................................................................................................... 544
F_FdeInitFontEncs()..................................................................................................... 545
F_FilePathBaseName()................................................................................................. 547
F_FilePathCloseDir().................................................................................................... 548
F_FilePathCopy().......................................................................................................... 548
F_FilePathFree() ........................................................................................................... 549
F_FilePathGetNext()..................................................................................................... 550

FDK Programmer’s Reference

7

Contents

F_FilePathOpenDir() .................................................................................................... 551
F_FilePathParent() ........................................................................................................ 552
F_FilePathProperty() .................................................................................................... 553
F_FilePathToPathName() ............................................................................................. 554
F_FontEncId()............................................................................................................... 556
F_FontEncName() ........................................................................................................ 557
F_FontEncToTextEnc() ................................................................................................ 558
F_Free() ........................................................................................................................ 559
F_FreeHandle()............................................................................................................. 560
F_GetFilePath() ............................................................................................................ 561
F_GetICUDataDir() ...................................................................................................... 561
F_GetHandleSize() ....................................................................................................... 562
F_HandleEqual()........................................................................................................... 563
F_HashCreate()............................................................................................................. 564
F_HashDestroy()........................................................................................................... 568
F_HashEnumerate() ...................................................................................................... 568
F_HashGet().................................................................................................................. 570
F_HashRemove() .......................................................................................................... 570
F_HashReportOnData() ................................................................................................ 571
F_HashSet() .................................................................................................................. 573
F_IsValidUTF8() .......................................................................................................... 573
F_LanguageNumber()................................................................................................... 574
F_LanguageString() ...................................................................................................... 576
F_LockHandle()............................................................................................................ 577
F_MakeDir() ................................................................................................................. 579
F_MetricApproxEqual() ............................................................................................... 579
F_MetricConstrainAngle()............................................................................................ 580
F_MetricDiv()............................................................................................................... 582
F_MetricFloat()............................................................................................................. 582
F_MetricFractMul() ...................................................................................................... 583
F_MetricMake()............................................................................................................ 584
F_MetricMul() .............................................................................................................. 585
F_MetricNormalizeAngle() .......................................................................................... 585
F_MetricSqrt() .............................................................................................................. 587
F_MetricSquare().......................................................................................................... 587
F_MetricToFloat() ........................................................................................................ 588
F_MifBegin() ................................................................................................................ 589
F_MifComment().......................................................................................................... 589
F_MifDecimal() ............................................................................................................ 590
F_MifEnd() ................................................................................................................... 591
F_MifGetIndent().......................................................................................................... 593
F_MifIndent() ............................................................................................................... 593
F_MifIndentDec()......................................................................................................... 594
F_MifIndentInc() .......................................................................................................... 595
F_MifInteger() .............................................................................................................. 595
F_MifNewLine()........................................................................................................... 596
F_MifSetIndent() .......................................................................................................... 597
F_MifSetOutputChannel() ............................................................................................ 598

8

FDK Programmer’s Reference

...

Contents

F_MifSpace() ................................................................................................................ 599
F_MifTab() ................................................................................................................... 599
F_MifText() .................................................................................................................. 600
F_MifTextString() ........................................................................................................ 601
Simple MIF library ....................................................................................................... 601
F_PathNameToFilePath() ............................................................................................. 606
F_PathNameType()....................................................................................................... 608
F_Printf() ...................................................................................................................... 608
F_Progress().................................................................................................................. 610
F_PtrEqual().................................................................................................................. 611
F_ReadBytes() .............................................................................................................. 613
F_ReadLongs() ............................................................................................................. 614
F_ReadShorts() ............................................................................................................. 615
F_Realloc() ................................................................................................................... 616
F_ReallocHandle()........................................................................................................ 618
F_RenameFile() ............................................................................................................ 620
F_ResetByteOrder()...................................................................................................... 620
F_ResetDirHandle()...................................................................................................... 622
F_Scanf() ...................................................................................................................... 623
F_SetAssert() ................................................................................................................ 624
F_SetByteOrder().......................................................................................................... 625
F_SetDSExit()............................................................................................................... 625
F_SetICUDataDir()....................................................................................................... 626
F_Sprintf() .................................................................................................................... 628
F_Sscanf()..................................................................................................................... 630
F_StrAlphaToInt() ........................................................................................................ 631
F_StrAlphaToIntUnicode()........................................................................................... 631
F_StrAlphaToReal() ..................................................................................................... 633
F_StrAlphaToRealUnicode()........................................................................................ 633
F_StrBrk()..................................................................................................................... 635
F_StrBrkUTF8 () .......................................................................................................... 635
F_StrCat() ..................................................................................................................... 637
F_StrCatCharN()........................................................................................................... 638
F_StrCatDblCharNEnc() .............................................................................................. 639
F_StrCatIntN() .............................................................................................................. 640
F_StrCatN() .................................................................................................................. 642
F_StrCatNEnc() ............................................................................................................ 643
F_StrCatUTF8CharNByte ()......................................................................................... 644
F_StrChr()..................................................................................................................... 645
F_StrChrEnc()............................................................................................................... 646
F_StrChrUTF8() ........................................................................................................... 648
F_StrCmp() ................................................................................................................... 649
F_StrCmpN() ................................................................................................................ 650
F_StrCmpNEnc() .......................................................................................................... 650
F_StrICmpNUTF8Char ................................................................................................ 651
F_StrCmpUTF8().......................................................................................................... 652
F_StrCmpUTF8Locale()............................................................................................... 654
F_StrICmpUTF8Locale() ............................................................................................. 655

FDK Programmer’s Reference

9

Contents

F_StrConvertEnc(), F_StrConvertEnc_IgnoreControlChars(), F_StrConvertEnc_ConvertControlChars() .............................................................................................................. 655
F_StrCopyString() ........................................................................................................ 658
F_StrCpy() .................................................................................................................... 659
F_StrCpyN() ................................................................................................................. 660
F_StrCpyNEnc() ........................................................................................................... 661
F_StrCpyNUTF8Char () ............................................................................................... 662
F_StrEqual().................................................................................................................. 663
F_StrEqualN()............................................................................................................... 664
F_StrICmp().................................................................................................................. 664
F_StrICmpEnc()............................................................................................................ 665
F_StrICmpN()............................................................................................................... 666
F_StrICmpNEnc()......................................................................................................... 667
F_StrIEqual() ................................................................................................................ 668
F_StrIEqualEnc() .......................................................................................................... 669
F_StrIEqualN() ............................................................................................................. 670
F_StrIEqualNEnc() ....................................................................................................... 671
F_StrIEqualNUTF8Char () ........................................................................................... 672
F_StrIPrefixEnc().......................................................................................................... 673
F_StrIsEmpty() ............................................................................................................. 674
F_StrISuffixEnc() ......................................................................................................... 675
F_StrLen()..................................................................................................................... 676
F_StrLenEnc() .............................................................................................................. 676
F_StrLenUTF16() ......................................................................................................... 677
F_StrListAppend() ........................................................................................................ 678
F_StrListCat() ............................................................................................................... 679
F_StrListCopy() ............................................................................................................ 679
F_StrListCopyList()...................................................................................................... 681
F_StrListFirst() ............................................................................................................. 682
F_StrListFree().............................................................................................................. 683
F_StrListGet()............................................................................................................... 684
F_StrListIIndex() .......................................................................................................... 684
F_StrListIndex()............................................................................................................ 686
F_StrListInsert()............................................................................................................ 687
F_StrListLast().............................................................................................................. 687
F_StrListLen() .............................................................................................................. 688
F_StrListNew() ............................................................................................................. 689
F_StrListRemove() ....................................................................................................... 690
F_StrListSetString()...................................................................................................... 690
F_StrListSort() .............................................................................................................. 691
F_StrNew() ................................................................................................................... 693
F_StrPrefix() ................................................................................................................. 694
F_StrPrefixN() .............................................................................................................. 695
F_StrRChr() .................................................................................................................. 695
F_StrRChrEnc() ............................................................................................................ 696
F_StrReverse() .............................................................................................................. 698
F_StrReverseUTF8Char ()............................................................................................ 698
F_StrStrip() ................................................................................................................... 701

10

FDK Programmer’s Reference

...

Contents

F_StrStripLeadingSpaces()........................................................................................... 701
F_StrStripTrailingSpaces() ........................................................................................... 702
F_StrStripUTF8Chars () ............................................................................................... 703
F_StrStripUTF8String ()............................................................................................... 704
F_StrStripUTF8Strings () ............................................................................................. 705
F_StrSubString()........................................................................................................... 706
F_StrSuffix()................................................................................................................. 707
F_StrTok() .................................................................................................................... 708
F_StrTokUTF8 ().......................................................................................................... 709
F_StrTrunc() ................................................................................................................. 710
F_StrTruncEnc() ........................................................................................................... 711
F_TextEncToFontEnc() ................................................................................................ 712
F_UnlockHandle() ........................................................................................................ 714
F_UTF16CharSize() ..................................................................................................... 714
F_UTF16NextChar() .................................................................................................... 715
F_UTF8CharSize() ....................................................................................................... 716
F_UTF8NextChar() ...................................................................................................... 717
F_Warning().................................................................................................................. 719
F_WriteBytes() ............................................................................................................. 719
F_WriteLongs() ............................................................................................................ 720
F_WriteShorts() ............................................................................................................ 721
4

Object Reference ....................................................................................................... 723
Books .......................................................................................................................... 723
FO_Book................................................................................................................... 723
FO_BookComponent ................................................................................................ 739
Character formats ........................................................................................................ 750
FO_CharFmt ............................................................................................................. 750
Colors .......................................................................................................................... 755
FO_Color .................................................................................................................. 755
Columns ...................................................................................................................... 757
Combined font definitions .......................................................................................... 758
FO_CombinedFontDefn............................................................................................ 759
Commands, menus, menu items, and menu item separators ...................................... 760
Common command, menu, and menu item separator properties.............................. 760
FO_Command........................................................................................................... 761
FO_MenuItemSeparator............................................................................................ 766
FO_Menu .................................................................................................................. 766
Conditions ................................................................................................................... 767
FO_AttrCondExpr..................................................................................................... 767
FO_CondFmt ............................................................................................................ 767
Cross-references .......................................................................................................... 769
FO_XRef................................................................................................................... 769
FO_XRefFmt ............................................................................................................ 770
Dialog boxes ............................................................................................................... 770
FO_DialogResource.................................................................................................. 771
FO_DlgBox............................................................................................................... 774
FO_DlgButton........................................................................................................... 775
FDK Programmer’s Reference 11

Contents

FO_DlgCheckBox..................................................................................................... 775
FO_DlgEditBox ........................................................................................................ 776
FO_DlgImage............................................................................................................ 776
FO_DlgLabel ............................................................................................................ 776
FO_DlgPopUp .......................................................................................................... 777
FO_DlgRadioButton ................................................................................................. 777
FO_DlgScrollBar ...................................................................................................... 778
FO_DlgScrollBox ..................................................................................................... 779
FO_DlgTriBox .......................................................................................................... 780
Documents .................................................................................................................. 780
FO_Doc..................................................................................................................... 780
Elements ...................................................................................................................... 829
Flows ........................................................................................................................... 829
FO_Flow ................................................................................................................... 829
Footnotes ..................................................................................................................... 830
FO_Fn ....................................................................................................................... 830
Format change lists ..................................................................................................... 831
FO_FmtChangeList................................................................................................... 831
Format rules ................................................................................................................ 841
FO_FmtRule.............................................................................................................. 841
FO_FmtRuleClause................................................................................................... 842
Frames ......................................................................................................................... 844
Graphics ...................................................................................................................... 844
FO_AFrame .............................................................................................................. 849
FO_Arc...................................................................................................................... 851
FO_Ellipse ................................................................................................................ 852
FO_Group ................................................................................................................. 852
FO_Inset.................................................................................................................... 852
FO_Iterator................................................................................................................ 858
FO_KeyCatalog ........................................................................................................ 859
FO_Line .................................................................................................................... 860
FO_Math ................................................................................................................... 860
FO_Polygon .............................................................................................................. 861
FO_Polyline .............................................................................................................. 861
FO_Rectangle............................................................................................................ 862
FO_RoundRect.......................................................................................................... 862
FO_TextFrame .......................................................................................................... 863
FO_TextLine ............................................................................................................. 865
FO_UnanchoredFrame.............................................................................................. 867
FO_Graphicsfmt........................................................................................................ 868
Insets ........................................................................................................................... 872
Markers ....................................................................................................................... 872
FO_Marker................................................................................................................ 872
Marker types ............................................................................................................... 873
FO_MarkerType........................................................................................................ 873
Menus .......................................................................................................................... 873
Menu items ................................................................................................................. 874
Pages ........................................................................................................................... 874

12

FDK Programmer’s Reference

...

Contents

FO_BodyPage ........................................................................................................... 874
FO_HiddenPage ........................................................................................................ 875
FO_MasterPage......................................................................................................... 875
FO_RefPage .............................................................................................................. 876
Paragraphs ................................................................................................................... 877
FO_Pgf ...................................................................................................................... 877
FO_PgfFmt................................................................................................................ 887
Rubi composites .......................................................................................................... 898
FO_Rubi.................................................................................................................... 898
Table ruling formats .................................................................................................... 899
FO_RulingFmt .......................................................................................................... 899
Separators .................................................................................................................... 899
Session ........................................................................................................................ 899
FO_Session ............................................................................................................... 900
Structural elements ..................................................................................................... 909
FO_Element .............................................................................................................. 909
FO_ElementDef ........................................................................................................ 917
Tables .......................................................................................................................... 920
FO_Cell..................................................................................................................... 921
FO_Row .................................................................................................................... 924
FO_Tbl ...................................................................................................................... 926
Table formats .............................................................................................................. 933
FO_TblFmt................................................................................................................ 933
Text columns ............................................................................................................... 937
Text frames ................................................................................................................. 937
Text insets ................................................................................................................... 937
Common text inset properties ................................................................................... 938
FO_TiApiClient properties ....................................................................................... 942
FO_TiFlow properties ............................................................................................... 942
FO_TiText properties ................................................................................................ 943
FO_TiTextTable properties ....................................................................................... 944
Text properties ............................................................................................................ 944
Variables ...................................................................................................................... 949
FO_Var ...................................................................................................................... 949
FO_VarFmt................................................................................................................ 949
5

Data Types and Structures Reference ..................................................................... 953
Data types ................................................................................................................... 953
MetricT values .......................................................................................................... 954
Data structures ............................................................................................................ 955
ChannelT................................................................................................................... 955
DirHandleT ............................................................................................................... 956
FilePathT................................................................................................................... 956
HandleT..................................................................................................................... 956
HashT ........................................................................................................................ 956
StringListT ................................................................................................................ 956
F_AttributeDefsT ...................................................................................................... 956
F_AttributeDefT........................................................................................................ 957

FDK Programmer’s Reference

13

Contents

F_AttributesT ............................................................................................................ 958
F_AttributeT.............................................................................................................. 958
F_CombinedFontsT .................................................................................................. 958
F_CombinedFontT .................................................................................................... 959
F_CompareRetT........................................................................................................ 959
F_ElementLocT ........................................................................................................ 959
F_ElementRangeT .................................................................................................... 960
F_FontEncT .............................................................................................................. 960
F_FontsT ................................................................................................................... 960
F_FontT..................................................................................................................... 961
F_ElementCatalogEntryT ......................................................................................... 961
F_ElementCatalogEntriesT....................................................................................... 962
F_IntsT ...................................................................................................................... 962
F_MetricsT................................................................................................................ 962
F_PointT.................................................................................................................... 962
F_PointsT .................................................................................................................. 962
F_PropIdentT ............................................................................................................ 963
F_PropValT ............................................................................................................... 963
F_PropValsT.............................................................................................................. 963
F_StringsT................................................................................................................. 963
F_TabT ...................................................................................................................... 964
F_TabsT .................................................................................................................... 964
F_TextItemT.............................................................................................................. 964
F_TextItemsT ............................................................................................................ 968
F_TextLocT............................................................................................................... 968
F_TextRangeT........................................................................................................... 968
F_TypedValT............................................................................................................. 969
F_UBytesT ................................................................................................................ 970
F_UIntsT ................................................................................................................... 970

14

6

Error Codes .............................................................................................................. 971

7

Calling Clients Shipped with FrameMaker ............................................................ 977
Calls to work with structured documents ................................................................... 977
Calls to Sort Tables ..................................................................................................... 984
Calls for WebDAV workgroup management .............................................................. 986
Call to work with book error logs ............................................................................... 990

8

CMS Connector FrameWork .................................................................................. 993
CMS API Data Structures and Enum Constants ......................................................... 993
F_CMSResultT ......................................................................................................... 993
F_CMSOpResultT .................................................................................................... 993
F_CMSPropertyT...................................................................................................... 994
F_CMSItemPropertyT .............................................................................................. 994
F_CMSItemTypeValueT ........................................................................................... 995
F_CMSItemFileTypeValueT ..................................................................................... 996
F_CMSPropertiesT ................................................................................................... 996

FDK Programmer’s Reference

...

Contents

F_CMSMenuItemT................................................................................................... 997
F_CMSMenuTypeT .................................................................................................. 997
F_CMSVersioningStrategyT ..................................................................................... 998
F_CMSDeleteParamT............................................................................................... 998
F_CMSInfoT............................................................................................................. 999
F_CMSInfosT ........................................................................................................... 999
Error Codes ............................................................................................................... 1000
CMS API Functions .................................................................................................. 1001
F_ApiAllocateCMSInfos ............................................................................................ 1001
F_ ApiDeallocateCMSInfos ....................................................................................... 1002
F_ ApiAllocateCMSProperties ................................................................................... 1002
F_ApiDeallocateCMSProperties ................................................................................ 1003
F_ApiCMSCommand ................................................................................................. 1004
F_CMSCommandsT ............................................................................................... 1005
F_CMSCommandArgsIdT...................................................................................... 1007
F_ApiCMSRegister .................................................................................................... 1010
F_ApiCMSCreateObject............................................................................................. 1011
F_ApiCMSEnableCommand ...................................................................................... 1012
F_ApiCMSDisableCommand..................................................................................... 1013
F_ApiCMSAddMenuEntry......................................................................................... 1014
F_ApiCMSGetProperties............................................................................................ 1015
F_ApiCMSGetProperty .............................................................................................. 1016
F_ApiCMSSetProperties ............................................................................................ 1017
F_ApiCMSSetProperty............................................................................................... 1019
F_ApiCMSConfigLoginUI......................................................................................... 1021
F_ApiCMSShowCheckoutUI ..................................................................................... 1022
F_CMSCustomizeCheckoutUI ............................................................................... 1022
F_ApiCMSShowCheckinUI ....................................................................................... 1023
F_ApiCMSShowCancelCheckoutUI .......................................................................... 1024
F_ApiCMSShowDeleteUI .......................................................................................... 1025
F_ApiCMSShowCommonListUI ............................................................................... 1026
F_ApiCMSShowPropertyUI....................................................................................... 1028
F_ApiCMSShowBrowseRepositoryUI....................................................................... 1029
F_ApiCMSGetCmsIdFromName ............................................................................... 1030
F_ApiCMSGetCMSInfo............................................................................................. 1031
F_ApiCMSGetCmsIdFromSession ............................................................................ 1032
F_ApiCMSGetCmsInfoList........................................................................................ 1032
9

APIs to automate the CMS connectors functionality .......................................... 1035
F_ApiCMSLogin ........................................................................................................ 1035
F_ApiCMSLogout ...................................................................................................... 1036
F_ApiCMSCheckout .................................................................................................. 1037
F_ApiCMSCheckin .................................................................................................... 1038
F_ApiCMSCancelCheckout ....................................................................................... 1039
F_ApiCMSDelete ....................................................................................................... 1040
F_ApiCMSOpenFile................................................................................................... 1041
F_ApiCMSUploadObject ........................................................................................... 1042
F_ApiCMSDownloadObject ...................................................................................... 1043

FDK Programmer’s Reference

15

Contents

F_ApiGetCMSObjectFromPath.................................................................................. 1044

16

FDK Programmer’s Reference

1

What’s New in FDK 11

..................................
.....

1

This chapter provides an overview of the new features in FDK 11.

Key catalogs for key-based (indirect) referencing
FDK 11 supports key catalogs for indirect referencing. You can define a key for a file
or resource in your project; updating the key will update the references to the file or
resource everywhere.
A key catalog is a collection of all the keys in your project—you can manage all the
keys from the key catalog. A key catalog is represented by the FO_KeyCatalog object.
The key mapping consists of:


Key name



Referenced file



Type of the source file containing the key definition



Source file containing the key definition



Information for using the key as a text variable

The key catalog consists of:


A unique key catalog tag



A hash-based list of key mappings



Count of key mappings (including duplicate ones)



Type of the source file containing the key catalog (KEYDEFSRC_NONE,
KEYDEFSRC_DITAMAP)



Source of key catalog. (DITA Map or other document holding the key catalog)



Name of the client owning the key catalog.



Appropriate Flags

FDK Programmer’s Reference

17

1

W h a t ’ s N e w i n F D K 11

New FDK APIs to update DITA references

New APIs for key catalog functionality
The following new APIs support the key catalog functionality


F_ApiNewKeyCatalog()
Creates a new key catalog with the specified tag.



F_ApiGetKeyCatalog()
Finds a key catalog with the specified tag.



F_ApiNewKeyDefinition()
Adds a new key definition to the specified key catalog.



F_ApiUpdateKeyDefinition()
Updates the specified key definition field for the specified key in the specified key
catalog.



F_ApiGetKeyDefinition()
Gets the specified key definition field for the specified key from the specified key
catalog.



F_ApiGetAllKeyDefinitions()
Gets all the key definitions from the specified key catalog.



F_ApiDeleteAllKeyDefinitions()
Deletes all the key definitions in the specified key catalog.



F_ApiGetAllKeys()
Gets all the key tags from the specified key catalog.

New FDK APIs to update DITA references
The following new APIs have been provided to update DITA references:


F_ApiUpdateDITAReference()
Updates the DITA object represented by the specified element.



F_ApiUpdateDITAReferences()
Updates all DITA references of the specified type. For example, you can use this API
to update all conrefs, all xrefs, or all conrefs as well as xrefs.

18

FDK Programmer’s Reference

Support for object styles

...

W h a t ’ s N e w i n F D K 11

Support for object styles
Object styles work similar to Paragraph and Character formats but work on objects.
Users can save frequently used object properties as a style and can apply these object
styles to various objects, such as images, anchored frames, and text frames for
consistent size and appearance.
Object styles are controlled through the new FO_GraphicsFmt object.

Support for multiple views
To support the FrameMaker 11 feature of multiple views, FDK 11 provides a new
session property FP_ActiveView, which can be set to one of the following:


WYSIWYG View



Author View



XML View

Support for hotspots in objects
FDK 11 supports hotspots through the following properties:


FP_ViewHotspotIndicators
A document-level property that turns on hotspot indicators. A hotspot indicator is a
square box at the centre of an object to indicate that the object is a hotspot.



FP_IsHotspot
An object-level property that specifies whether an object is a hotspot. If this property
is turned off, the object is no longer considered a hotspot.



FP_HotspotCmdStr
The command string for the hotspot, similar to the hypertext command string. This
is an object-level property.



FP_HotspotTitle
The tooltip for the hotspot. Applicable for the output formats that support it (for
example HTML). This is an object-level property and is optional.

FDK Programmer’s Reference

19

1

W h a t ’ s N e w i n F D K 11

Interactive multimedia links for 3D objects

Interactive multimedia links for 3D objects
FDK 11 provides the following properties to manage links to embedded U3D
(Universal 3D), FLV files, and SWF files in the PDF output.


FP_InsetGfxPlayWindowInPdf
If this property is set, on publishing a document to PDF, inset objects that have facets
of type FLV, U3D, or SWF will be activated in a new Window in a PDF.



FP_InsetGfxActiveInPdf
If this property is set, on publishing a document to PDF, inset objects that have facets
of type FLV, U3D, or SWF will be activated as soon as the page containing the
graphic object is visible.



FP_InsetGfxName
This property assigns a name to inset objects that have facets of type FLV, U3D, or
SWF.



FP_InsetJavaScriptAttached
Indicates whether Javascript is attached with the graphic object that has a U3D facet.



FP_InsetJavaScriptFile
Use this property to attach a Javascript file to a graphic object that has a U3D facet.
If the value of the file path sepecified is null, the Javascript file attached to the inset
is removed.



FP_InsetSaveFacetToFile
Saves the given facet of an inset to a given file.



FP_InsetU3dViewList
Returns the list of views defined in the U3D facet of an inset object.



FP_InsetU3dAnimationList
Returns the list of animations defined in the U3D facet of an inset object.



FP_InsetU3dPartList
Returns the list of parts defined in the U3D facet of an inset object.



FP_InsetMonikerFilePath
Returns the file path of the moniker of an inset object that has an OLE2 facet.

20

FDK Programmer’s Reference

Support for referring to content using line numbers

...

W h a t ’ s N e w i n F D K 11

Support for referring to content using line numbers
FDK 11 supports the setting of line numbers. The line numbers are set at a document
level and appear before the line. The following properties are provided for managing
line numbers:


FP_LineNumRestart
If set, restarts line number display on each page.



FP_LineNumShow
If set, enables the line number display.



FP_LineNumDistance
Sets the line number display width, that is the space in which the line numbers are
displayed.

Support for guided structured authoring with banner text
Banner text in a FrameMaker file instructs you about what to enter in an element. You
can control the instructional text you want to display for each of the elements.The
following properties are used to handle banner text:


FP_BannerText
Property of element definition object, FO_ElementDef. Users can set, change, or
query the banner text associated with an element definition object.



FP_BannerTextDisplay
Boolean property of document specifying whether banner text should be displayed in
a document.

New APIs, notifications, error codes, objects, and properties
The following new API, notifications, error codes, objects, and properties are added in
this release:

New APIs


F_ApiClientPath()



F_ApiDefineAndAddCommandEx()



F_ApiDefineCommandEx()

FDK Programmer’s Reference

21

1

W h a t ’ s N e w i n F D K 11

New APIs, notifications, error codes, objects, and properties



F_ApiDeleteAllKeyDefinitions()



F_ApiDeleteCondTag()



F_ApiGetAllKeyDefinitions()



F_ApiGetAllKeys()



F_ApiGetKeyCatalog()



F_ApiGetKeyDefinition()



F_ApiGetNewXMLDefaultParams()



F_ApiNewKeyCatalog()



F_ApiNewKeyDefinition()



F_ApiNewXML()



F_ApiProgressBarEx()



F_ApiSetAttributeSimple()



F_ApiUpdateDITAReference()



F_ApiUpdateDITAReferences()



F_ApiUpdateKeyDefinition()

New notifications


FA_Note_IsCommandEnabled



FA_Note_LoadKeyCatalog



FA_Note_PostSwitchView



FA_Note_PreSwitchView



FA_Note_ReLoadKeyCatalog



FA_Note_UpdateDITAReference



FA_Note_UpdateDITAReferences

New error codes

22



FE_BadKey



FE_BadKeyField



FE_KeyCatalogIsStale



FE_KeyCatalogNotLoaded

FDK Programmer’s Reference

New APIs, notifications, error codes, objects, and properties



FE_KeyDefinitionDoesNotExist



FE_NonDITADocument



FE_UpdateDITAReferenceFailed



FE_UpdateDITAReferenceFailedCannotConvertToFMObject



FE_UpdateDITAReferenceFailedCannotFindReferencedFile



FE_UpdateDITAReferenceFailedCannotOpenReferencedFile



FE_UpdateDITAReferenceFailedCannotResolveReference



FE_UpdateDITAReferenceFailedInvalidElementType

...

W h a t ’ s N e w i n F D K 11

New objects


FO_GraphicsFmt



FO_KeyCatalog

New properties


FP_ActiveView



FP_DefaultKeyCatalog



FP_FirstDITAConrefElementInDoc



FP_FirstDITALinkElementInDoc



FP_FirstDITATopicrefElementInDoc



FP_FirstDITATopicsetrefElementInDoc



FP_FirstDITAXrefElementInDoc



FP_FirstGraphicsFmtInDoc



FP_FirstKeyCatalogInSession



FP_FMConsoleString



FP_Focus



FP_GroupDialog



FP_HotspotCmdStr



FP_HotspotTitle



FP_InsetMonikerFilePath



FP_InsetMonikerPath

FDK Programmer’s Reference

23

1

24

W h a t ’ s N e w i n F D K 11

New APIs, notifications, error codes, objects, and properties



FP_InsetU3dAnimationList



FP_InsetU3dPartList



FP_InsetU3dViewList



FP_IsHotspot



FP_IsTempOpenSave



FP_KeyCatalog



FP_KeyCatalogType



FP_KeyCatalogWorkflow



FP_LineNumDistance



FP_LineNumRestart



FP_LineNumShow



FP_MaxSize



FP_MinSize



FP_NextDITAConrefElementInDoc



FP_NextDITALinkElementInDoc



FP_NextDITATopicrefElementInDoc



FP_NextDITATopicsetrefElementInDoc



FP_NextDITAXrefElementInDoc



FP_NextGraphicsFmtInDoc



FP_SpecifiedKeyCatalog



FP_UseAFrameIsCropped



FP_UseAFrameIsFloating



FP_UseAlignment



FP_UseAnchorType



FP_UseAngle



FP_UseBaselineOffset



FP_UseBorderWidth



FP_UseColGapWidth



FP_UseColumnsAreBalanced



FP_UseDTheta

FDK Programmer’s Reference

New APIs, notifications, error codes, objects, and properties



FP_UseFill



FP_UseFlowIsAutoConnect



FP_UseFlowIsPostScript



FP_UseHeight



FP_UseInsetDpi



FP_UseLocX



FP_UseLocY



FP_UseMathSize



FP_UseNumColumns



FP_UseOverprint



FP_UsePen



FP_UseRadius



FP_UseRunaround



FP_UseRunaroundGap



FP_UseSideHeadGap



FP_UseSideHeadPlacement



FP_UseSideHeadWidth



FP_UseSideOffset



FP_UseTextLineType



FP_UseTheta



FP_UseTintPercent



FP_UseWidth



FP_ViewHotspotIndicators



FP_XSLTTransformationScenarioFile

FDK Programmer’s Reference

...

W h a t ’ s N e w i n F D K 11

25

1

W h a t ’ s N e w i n F D K 11

CMS Connector Framework

CMS Connector Framework
FrameMaker extends the support to any standard content management system (CMS)
by providing a set of full-featured APIs.
With CMS APIs, you can implement additional authoring and content management
capabilities beyond the ones provided by the CMS.
In addition, you can create your own user interface or extend the existing user interface
features.
New CMS API, structures, enums, error codes, enums, and properties added in this
release:

26



“CMS API Data Structures and Enum Constants” on page 993



“Error Codes” on page 1000



“CMS API Functions” on page 1001



“APIs to automate the CMS connectors functionality” on
page 1035

FDK Programmer’s Reference

2

Function Summary

..................................
.....

1

This chapter lists the FDK functions by topic. If you know what you want to do, but
don’t know which function to use, look it up in this chapter. If you know the name of a
function and want a complete description of it, look it up in Chapter 2, “FDK Function
Reference.”
The functions are listed under all the topics to which they apply, so some functions
appear more than once.

FDK Programmer’s Reference

27

1

Function Summary

Client-defined callback functions
To

Use this function

Respond to the user choosing a menu item
created by your client

F_ApiCommand()

Respond to the FrameMaker product’s
initialization message

F_ApiInitialize()

Respond to the user clicking a hypertext
marker or inset

F_ApiMessage()

Respond to the user or another client executing
operations such as Open or Save

F_ApiNotify()

Turn a notification on or off

F_ApiNotification()

Respond to the user interacting with a clientdefined dialog box

F_ApiDialogEvent()

Set a callback function that is called for setting
the username/password information before
performing the NetLib related authentication.

F_ApiNetLibSetAuthFunction()

Set a return value for a client-defined callback
function

F_ApiReturnValue()

Books

28

To

Use this function

Close a book

F_ApiClose()

Compare two books

F_ApiCompare()

Create a book

F_ApiNewNamedObject()

Generate/update files for a book

F_ApiSimpleGenerate()
F_ApiUpdateBook()

Import element definitions to a book

F_ApiSimpleImportElementDefs()

Import formats from a document to a book

F_ApiSimpleImportFormats()

Insert a book component of a specified
type at a specified position in a structured
FrameMaker book.

F_ApiNewBookComponentOfTypeInHierarchy()

Move a book component within the book.

F_ApiMoveComponent()

Open a book (the easy way)

F_ApiSimpleOpen()

FDK Programmer’s Reference

To

Use this function

Open a book (with a script)

F_ApiOpen()

Print a book

F_ApiSilentPrintDoc()

Save a book (the easy way)

F_ApiSimpleSave()

Save a book (with a script)

F_ApiSave()

Write entries to the book error log

F_ApiCallClient()

FDK Programmer’s Reference

...

Function Summary

29

1

Function Summary

Characters

30

To

Use this function

Convert a character to lowercase

F_CharToLower()

Convert a character to uppercase

F_CharToUpper()

Convert a UTF-8 character to lowercase

F_CharToLowerUTF8()

Determine whether a character is alphabetic

F_CharIsAlphabetic()

Determine whether a character is
alphanumeric

F_CharIsAlphaNumeric()

Determine whether a character is a
FrameMaker product control character

F_CharIsControl()

Determine whether a character is alphabetic

F_CharIsEol()

Determine whether a character is hexadecimal

F_CharIsHexadecimal()

Determine whether a character is lowercase

F_CharIsLower()

Determine whether a character is numeric

F_CharIsNumeric()

Determine whether a character is uppercase

F_CharIsUpper()

Determine whether a specified UTF-8
character is an alphanumeric character

F_CharIsAlphaNumericUTF8()

Determine whether a specified character is a
FrameMaker control character.

F_CharIsControlUTF8()

Determine whether a specified character is a
FrameMaker end-of-line (EOL) character.

F_CharIsEolUTF8()

Determine whether a specified UTF-8
character is a hexadecimal digit

F_CharIsHexadecimalUTF8()

Determine whether a specified UTF-8
character is a lowercase character

F_CharIsLowerUTF8()

Determine whether a specified UTF-8
character is a numeric character in a decimal
system.

F_CharIsNumericUTF8()

Determine whether a specified UTF-8
character is an uppercase character

F_CharIsUpperUTF8()

FDK Programmer’s Reference

...

Function Summary

Clipboard
To

Use this function

Copy selection to the Clipboard

F_ApiCopy()

Clear selection

F_ApiClear()

Cut selection to the Clipboard

F_ApiCut()

Paste contents of the Clipboard

F_ApiPaste()

Pop the entry at the top of the Clipboard stack to
the Clipboard

F_ApiPopClipboard()

Push the Clipboard contents onto the Clipboard
stack

F_ApiPushClipboard()

Commands and menus
To

Use this function

Add a command to a menu

F_ApiAddCommandToMenu()

Add a menu to a menu or menu bar

F_ApiAddMenuToMenu()

Add a menu item separator to a menu

F_ApiAddCommandToMenu()

Allow user to choose a command by typing in
the document window Tag area

F_ApiQuickSelect()

Arrange the menu items on a menu

F_ApiSetId()

Arrange the menus on a menu or menu bar

F_ApiSetId()

Create a command

F_ApiDefineCommand()

Create a command and specify the views in
which this command is valid

F_ApiDefineCommandEx()

Create a command and add it to a menu

F_ApiDefineAndAddCommand()

Create a menu

F_ApiDefineMenu()

Create a menu and add it to a menu or menu bar

F_ApiDefineAndAddMenu()

Determine if a menu or command exists

F_ApiGetNamedObject()

Determine if a menu or menu item is on a menu
or menu bar

F_ApiMenuItemInMenu()

Get the ID of a menu, command or menu item
separator with a specified name

F_ApiGetNamedObject()

FDK Programmer’s Reference

31

1

32

Function Summary

To

Use this function

Respond to the user executing a command
created by your client

F_ApiCommand()

Load a menu customization file

F_ApiLoadMenuCustomizationFil
e()

Remove amenu item, menu item separator,
menu, or command

F_ApiDelete()

FDK Programmer’s Reference

...

Function Summary

Data structures: copying
To

Use this function

Copy an F_AttributesT structure

F_ApiCopyAttributes()

Copy an F_AttributeDefsT structure

F_ApiCopyAttributeDefs()

Copy an F_ElementCatalogEntriesT structure

F_ApiCopyElementCatalog
Entries()

Copy an F_AttributesT structure

F_ApiCopyAttributes()

Copy an F_IntsT structure

F_ApiCopyInts()

Copy an F_MetricsT structure

F_ApiCopyMetrics()

Copy an F_PointsT structure

F_ApiCopyPoints()

Copy an F_PropValT structure

F_ApiCopyPropVal()

Copy an F_PropValsT structure

F_ApiCopyPropVals()

Copy a StringT variable

F_ApiCopyString()

Copy an F_StringsT structure

F_ApiCopyStrings()

Copy an F_TabT structure

F_ApiCopyTab()

Copy an F_TabsT structure

F_ApiCopyTabs()

Copy an F_TextItemT structure

F_ApiCopyTextItem()

Copy an F_TextItemsT structure

F_ApiCopyTextItems()

Copy an F_UBytesT structure

F_ApiCopyUBytes()

Copy an F_UIntsT structure

F_ApiCopyUInts()

Copy an F_ValT structure

F_ApiCopyVal()

Debugging
To

Use this function

Print the current API error status

F_ApiPrintFAErrno()

Print status flags returned by a call to
F_ApiImport()

F_ApiPrintImportStatus()

Print status flags returned by a call to F_ApiOpen()

F_ApiPrintOpenStatus()

FDK Programmer’s Reference

33

1

34

Function Summary

To

Use this function

Print the status flags returned by a call to
F_ApiSave()

F_ApiPrintSaveStatus()

Print the status flags returned by a call to
F_ApiUpdateBook()

F_ApiPrintUpdateBookStatu
s()

Print a property-value pair

F_ApiPrintPropVal()

Print the property-value pairs in a property list

F_ApiPrintPropVals()

Print the text in a single text item

F_ApiPrintTextItem()

Print the text in a set of text items (F_TextItemsT
structure)

F_ApiPrintTextItems()

FDK Programmer’s Reference

...

Function Summary

DITA references: updating
To

Use this function

Update the DITA object represented by the
specified element.

F_ApiUpdateDITAReference()

Update all DITA references of the specified
type. For example, you can use this API to
update all conrefs, all xrefs, or all
conrefs as well as xrefs.

F_ApiUpdateDITAReferences()

Dialog boxes: predefined
To

Use this function

Display an OK/Cancel or Continue dialog box
with a specified message

F_ApiAlert()

Display a dialog box that allows the user to
select a file or directory

F_ApiChooseFile()

Display a dialog box that prompts the user for
an integer value

F_ApiPromptInt()

Display a dialog box that prompts the user for a
metric value

F_ApiPromptMetric()

Display a dialog box that prompts the user for a
string

F_ApiPromptString()

Display dialog boxes similar to FrameMaker’s
Open and Save dialog boxes

F_ApiChooseFileExEx ()

Display a scroll list that allows the user to
choose from a list of items you provide

F_ApiScrollBox()

Dialog boxes: client-defined
To

Use this function

Close a dialog box

F_ApiClose()

Display a dialog resource as a modal dialog box

F_ApiModalDialog()

Display a dialog resource as a modeless dialog
box

F_ApiModelessDialog()

FDK Programmer’s Reference

35

1

36

Function Summary

To

Use this function

Get the ID of an item in a dialog box from its
item number

F_ApiDialogItemId()

Get the string entered in a text field

F_ApiGetString()

Get the state of a button, checkbox,
radio button, text box, pop-up menu,
or scroll list

F_ApiGetInt()

Keep a client-defined modal dialog box on the
screen after the user has clicked an item in it

F_ApiReturnValue()

Open a dialog resource

F_ApiOpenResource()

Respond to the user interacting with a clientdefined dialog box

F_ApiDialogEvent()

Set the string entered in a text field

F_ApiSetString()

Set the list of strings that appears in a scroll list
or pop-up menu

F_ApiSetStrings()

Set the state of a button, checkbox,
radio button, text box, pop-up menu, or scroll
list

F_ApiSetInt()

FDK Programmer’s Reference

...

Function Summary

Documents: comparing
To

Use this function

Compare two documents

F_ApiCompare()

Documents: file operations
To

Use this function

Check status bit in status scripts returned by
F_ApiOpen() or F_ApiSave()

F_ApiCheckStatus()

Close (quit) a document

F_ApiClose()

Create a new custom document

F_ApiCustomDoc()

Create a new document from a template

F_ApiSimpleNewDoc()

Create a new document using a script

F_ApiOpen()

Get a default property list for use with
F_ApiOpen()

F_ApiGetOpenDefaultParams()

Get a default property list for use with
F_ApiSave()

F_ApiGetSaveDefaultParams()

Get a default property list for use with
F_ApiImport()

F_ApiGetImportDefaultParams()

Import a text or graphics file

F_ApiImport()

Open a document (the easy way)

F_ApiSimpleOpen()

Open a document (with a script)

F_ApiOpen()

Print a document

F_ApiSilentPrintDoc()

Save a document (the easy way)

F_ApiSimpleSave()

Save a document (with a script)

F_ApiSave()

Apply an attribute expression to a document
to perform attribute-based-filtering.

F_ApiApplyAttributeExpression()

Apply an attribute-based expression to the
document and the filtered text is displayed in
the specified color.

F_ApiPreviewAttributeExpression
()

Apply an attribute-based expression to the
document where the filtered text is converted
to conditional text.

F_ApiApplyAttributeExpressionAs
Condition()

FDK Programmer’s Reference

37

1

Function Summary

Documents: formatting
To

Use this function

Accept all the tracked changes in the specified
document

F_ApiTrackChangesAcceptAll
()

Apply a page’s layout to another page

F_ApiApplyPageLayout()

Clear the change bars for a document

F_ApiClearAllChangeBars()

Redisplay a document after FP_Displaying
has been turned off

F_ApiRedisplay()

Reformat a document after FP_Reformatting
has been turned off

F_ApiReformat()

Rehyphenate words in a document

F_ApiRehyphenate()

Reject all the tracked changes in the specified
document

F_ApiTrackChangesRejectAll
()

Reset equation settings for a document

F_ApiResetEqnSettings()

Reset reference frames

F_ApiResetReferenceFrames()

Restart paragraph numbering for a document

F_ApiRestartPgfNumbering()

Documents: updating

38

To

Use this function

Import formats from another document

F_ApiSimpleImportFormats()

Import element definitions to a document

F_ApiSimpleImportElementDefs()

Updates a specified cross-reference in the
document.

F_ApiUpdateXRef()

Update the cross-references in a document

F_ApiUpdateXRefs()

Update a text inset

F_ApiUpdateTextInset()

Update the variables in a document

F_ApiUpdateVariables()

FDK Programmer’s Reference

...

Function Summary

F-codes
To

Use this function

Execute a set of f-codes

F_ApiFcodes()

Files, directories, and filepaths
To

Use this function

Copy a filepath (platform-independent representation
of a pathname)

F_FilePathCopy()

Convert a filepath to a platform-specific or platformindependent pathname

F_FilePathToPathName()

Convert a platform-specific or platform-independent
pathname to a filepath

F_PathNameToFilePath()

Close a directory handle opened with
F_FilePathOpenDir()

F_FilePathCloseDir()

Create a directory

F_MakeDir()

Delete a file specified by a filepath

F_DeleteFile()

Determine which platform naming conventions a
pathname uses

F_PathNameType()

Free the memory used by a filepath

F_FilePathFree()

Get the basename (base directory name or filename)
specified by a filepath

F_FilePathBaseName()

Get the filepath associated with a specified channel

F_GetFilePath()

Get the next file in a directory specified by a handle
opened with F_FilePathOpenDir()

F_FilePathGetNext()

Get the parent directory of a specified file or directory

F_FilePathParent()

Get the permissions and other information for a
specified file or directory

F_FilePathProperty()

Open and return a handle that can be used to obtain the
file and subdirectory entries in a specified directory

F_FilePathOpenDir()

Rename a file

F_RenameFile()

F_NewMacFilePath()

F_GetMacFilePathInfo()

FDK Programmer’s Reference

39

1

40

Function Summary

To

Use this function

Reset a directory’s handle so that the next call to
F_FilePathGetNext() returns the first file or
directory entry in the directory

F_ResetDirHandle()

FDK Programmer’s Reference

...

Function Summary

Fonts
To

Use this function

Get the angles, variations, and weights
available for a specified font or combined font

F_ApiFamilyFonts()

Get the character encoding for a specified font
or font family

F_ApiGetEncodingForFamily()

Get and set character encoding data for a
session

F_ApiGetSupportedEncodings()

F_ApiCombinedFamilyFonts()

F_ApiGetEncodingForFont()

F_ApiIsEncodingSupported()
F_FontEncId()
F_FontEncName()

Graphic insets
To

Use this function

Create a graphic inset

F_ApiImport()
F_ApiNewGraphicObject()

Delete a facet

F_ApiDeletePropByName()

Query an integer (IntT) facet

F_ApiGetIntByName()

Query a metric (MetricT) facet

F_ApiGetMetricByName()

Query an unsigned bytes
(F_UBytesT) facet

F_ApiGetUBytesByName()

Respond to the user clicking an inset

F_ApiMessage()

Set an integer (IntT) facet

F_ApiSetIntByName()

Set a metric (MetricT) facet

F_ApiSetMetricByName()

Set an unsigned bytes (F_UBytesT) facet

F_ApiSetUBytesByName()

FDK Programmer’s Reference

41

1

Function Summary

Hash tables
To

Use this function

Add an entry to a hash table

F_HashSet()

Call a specified function with the key and
datum of each entry in a hash table

F_HashEnumerate()

Create a hash table

F_HashCreate()

Delete a hash table and all its entries

F_HashDestroy()

Get an entry from a hash table

F_HashGet()

Remove an entry from a hash table

F_HashRemove()

Create a hash table

F_HashReportOnData()

Hypertext
To

Use this function

Execute a hypertext command

F_ApiHypertextCommand()

I/O

42

To

Use this function

Append the contents of one channel to another

F_ChannelAppend()

Close a channel

F_ChannelClose()

Close a temporary channel

F_ChannelCloseTmp()

Create a temporary channel

F_ChannelMakeTmp()

Determine whether the end of a channel has been read

F_ChannelEof()

Flush buffered output to a channel

F_ChannelFlush()

Get the size of a channel

F_ChannelSize()

Get the byte after the current position in a channel

F_ChannelPeek()

Get the offset of the current byte relative to the
beginning of an input channel

F_ChannelTell()

Open a channel

F_ChannelOpen()

FDK Programmer’s Reference

To

Use this function

Read from a channel

F_ChannelRead()

...

Function Summary

F_ReadBytes()
F_ReadLongs()
F_ReadShorts()
Read formatted input

F_Scanf()
F_Sscanf()

Set the position for the next input operation in a
channel

F_ChannelSeek()

Set the byte order of a channel so that subsequent I/O
calls will swap bytes if the platform is big endian

F_SetByteOrder()

Set the byte order of a channel so that subsequent I/O
calls will swap bytes if the platform is little endian

F_ResetByteOrder()

Write to a channel

F_ChannelWrite()
F_WriteBytes()
F_WriteLongs()
F_WriteShorts()

Write formatted output

F_Printf()
F_Sprintf()

Insets
See “Graphic insets” on page 41 and “Text insets” on page 64.

FDK Programmer’s Reference

43

1

Function Summary

Key Catalogs
To

Use this function

Create a new key catalog

F_ApiNewKeyCatalog()

Find a key catalog with the specified
tag.

F_ApiGetKeyCatalog()

Add a new key definition to the specified
key catalog.

F_ApiNewKeyDefinition()

Update the specified key definition field
for the specified key in the specified key
catalog.

F_ApiUpdateKeyDefinition()

Get the specified key definition field for
the specified key from the specified key
catalog.

F_ApiGetKeyDefinition()

Get all the key definitions from the
specified key catalog.

F_ApiGetAllKeyDefinitions()

Delete all the key definitions in the
specified key catalog.

F_ApiDeleteAllKeyDefinitions()

Get all the key tags from the specified
key catalog.

F_ApiGetAllKeys()

Memory: allocating and deallocating structures

44

To

Use this function

Allocate memory for a property list

F_ApiAllocatePropVals()

Allocate memory for text items (an
F_TextItemsT structure)

F_ApiAllocateTextItems()

Exit and free all resources used by client

F_ApiBailOut()

Deallocate memory for a property (an
F_PropValT structure)

F_ApiDeallocateProp()

Deallocate memory for a property list (an
F_PropValsT structure)

F_ApiDeallocatePropVals()

Deallocate memory for text items (an
F_TextItemsT structure)

F_ApiDeallocateTextItems()

Deallocate memory for an F_FontsT
strcture

F_ApiDeallocateFonts()

FDK Programmer’s Reference

To

Use this function

Deallocate memory for an F_IntsT
structure

F_ApiDeallocateInts()

Deallocate memory for an F_MetricsT
structure

F_ApiDeallocateMetrics()

Deallocate memory for an F_PointsT
structure

F_ApiDeallocatePoints()

Deallocate memory for a StringT
variable

F_ApiDeallocateString()

Deallocate memory for an F_StringsT
structure

F_ApiDeallocateStrings()

Deallocate memory for an F_TabT
structure

F_ApiDeallocateTab()

Deallocate memory for an F_TabsT
structure

F_ApiDeallocateTabs()

Deallocate memory for an F_UbytesT
structure

F_ApiDeallocateUBytes()

Deallocate memory for an F_UIntsT
structure

F_ApiDeallocateUInts()

FDK Programmer’s Reference

...

Function Summary

45

1

Function Summary

Memory: manipulating with handles
To

Use this function

Allocate a block of memory to a handle

F_AllocHandle()

Allocate a new block of memory to a handle
and copy the contents of a specified block of
memory to it

F_DuplicateHandle()

Compare two blocks of memory specified by
handles

F_HandleEqual()

Free a block of memory specified by a handle

F_FreeHandle()

Get the size of a handle’s block of data

F_GetHandleSize()

Initialize a block of memory specified by a
handle to 0

F_ClearHandle()

Lock a handle and return the address of the
data block of the handle

F_LockHandle()

Reallocate a block of memory

F_ReallocHandle()

Specify a direct straight exit function for the
FDE to call when memory allocation fails

F_SetDSExit()

Unlock a handle

F_UnlockHandle()

Memory: manipulating with pointers
To

Use this function

Allocate a block of memory to a pointer

F_Alloc()
F_Calloc()

46

Allocate a new block of memory to a pointer
and copy the contents of a specified block of
memory to it

F_DuplicatePtr()

Compare two blocks of memory specified by
pointers

F_PtrEqual()

Copy the contents of a block of memory to
another block of memory

F_CopyPtr()

Free a block of memory specified by a pointer

F_Free()

Initialize a block of memory specified by a
pointer to 0

F_ClearPtr()

FDK Programmer’s Reference

To

Use this function

Reallocate a block of memory to a pointer

F_Realloc()

Specify a direct straight exit function for the
FDE to call when memory allocation fails

F_SetDSExit()

...

Function Summary

Menus
See “Commands and menus” on page 31.

FDK Programmer’s Reference

47

1

Function Summary

Metrics
To

Use this function

Compare two metric numbers

F_MetricApproxEqual()

Compute the square root of a metric number

F_MetricSqrt()

Compute the square of a metric number

F_MetricSquare()

Constrain a specified angle to a specified range of
degrees

F_MetricConstrainAngle()

Construct a metric number from a fraction

F_MetricMake()

Convert a metric number to a real number

F_MetricToFloat()

Convert a real number to a metric number

F_MetricFloat()

Divide two metric numbers

F_MetricDiv()

Multiply a metric value by a fraction

F_MetricFractMul()

Multiply two metric numbers

F_MetricMul()

Normalize a specified angle between 0 and 360
degrees

F_MetricNormalizeAngle()

Maker Interchange Format (MIF)

48

To

Use this function

Indent and start a new MIF statement and
automatically increase the indent level

F_MifBegin()

Write a comment string to the MIF write channel

F_MifComment()

Write a real number with n digits after the decimal
point

F_MifDecimal()

Indent and finish a MIF statement

F_MifEnd()

Return the current indent level of the MIF write
channel

F_MifGetIndent()

Indent the output channel according to the indent
level

F_MifIndent()

Decrease the indent level

F_MifIndentDec()

Increase the indent level

F_MifIndentInc()

Write an integer to the MIF write channel

F_MifInteger()

FDK Programmer’s Reference

To

Use this function

Write a new line to the MIF write channel

F_MifNewLine()

Set the indent level of the MIF write channel

F_MifSetIndent()

Set a channel to receive MIF output

F_MifSetOutputChannel()

Write a blank space to the MIF output channel

F_MifSpace()

Write a tab to the MIF channel

F_MifTab()

Write a simple text string to the MIF output channel

F_MifText()

Write a text string enclosed in single quotes (`') to
the MIF channel

F_MifTextString()

FDK Programmer’s Reference

...

Function Summary

49

1

Function Summary

Objects: creating and deleting

50

To

Use this function

Add a Boolean conditional expression to
the document

F_ApiAddNewBuildExpr()
F_ApiDeleteBuildExpr()

Apply the Boolean conditional
expression to the document.

F_ApiSetActiveBuildExpr()

Pre-register a given server with the
provided username and password, so that
instead of prompting the user for
authentication, the server uses the login
information when required.

F_ApiNetLibAuthenticateServer()

Return the name of the active expression
in the document

F_ApiGetActiveBuildExpr()

Return the Boolean conditional
expression in the document with the
given name

F_ApiGetBuildExpr()

Return an array of all Boolean
conditional expression names in the
document

F_ApiGetBuildExprCatalog()

Upload a folder and subfolders to the
server.

F_ApiNetLibUploadFolder()

Create an anchored object, such as a
marker or an anchored frame

F_ApiNewAnchoredObject()

Create a book component in a structured
book

F_ApiNewBookComponentInHierarchy()

Create a column in a table

F_ApiAddCols()

Create a client text inset

F_ApiNewAnchoredObject()

Create a format rule, format rule clause,
or format change list

F_ApiNewSubObject()

Create a formatted anchored object, such
as a table, variable, or cross-reference

F_ApiNewAnchoredFormattedObject()

Create a graphic object, such as a text
column or an oval

F_ApiNewGraphicObject()

Create a named object, such as a
reference page

F_ApiNewNamedObject()

Create a row in a table

F_ApiAddRows()

FDK Programmer’s Reference

To

Use this function

Create a series object, such as a
paragraph, body page, or book
component

F_ApiNewSeriesObject()

Create a structural element in a
Structured document

F_ApiNewElement()

Create a table with a specified number of
rows and columns

F_ApiNewTable()

Create a structural element in a
Structured document
or book

F_ApiNewElementInHierarchy()

Create a text or graphic inset

F_ApiImport()

Delete unused formats (character,
paragraph, or table) from the document

F_ApiDeleteUnusedFmts()

Delete an object

F_ApiDelete()

FDK Programmer’s Reference

...

Function Summary

51

1

Function Summary

Objects: getting IDs
To

Use this function

Get the ID of an object with a specified
persistent identifier

F_ApiGetUniqueObject()

Get the ID of an object that has a specified
name

F_ApiGetNamedObject()

Query an ID (F_ObjHandleT) property

F_ApiGetId()

Printing
To

Use this function

Print a document

F_ApiSilentPrintDoc()

Specify the number of copies of a document to
print and other integer print properties

F_ApiSetInt()

Specify the printer to which to print a document
and other string print properties

F_ApiSetString()

Properties

52

To

Use this function

Get an element definition’s attribute definitions

F_ApiGetAttributeDefs()

Get an element’s attributes

F_ApiGetAttributes()

Get a document’s element catalog

F_ApiGetElementCatalog()

Query a property of any type

F_ApiGetPropVal()

Query an array of integers (F_IntsT) property

F_ApiGetInts()

Query an ID (F_ObjHandleT) property

F_ApiGetId()

Query an integer (IntT) property

F_ApiGetInt()

Query a metric (MetricT) property

F_ApiGetMetric()

Query a metrics (F_MetricsT) property

F_ApiGetMetrics()

Query an array of points (F_PointsT) property for
a polygon or polyline

F_ApiGetPoints()

FDK Programmer’s Reference

To

Use this function

Query a string (StringT) property

F_ApiGetString()

Query a strings (F_StringsT) property

F_ApiGetStrings()

Query a text location (F_TextLocT) property

F_ApiGetTextLoc()

Query a text range (F_TextRangeT) property

F_ApiGetTextRange()

Query the text properties (for example, character
tag, font family, font weight) for a text range

F_ApiGetTextProps()

...

Function Summary

F_ApiGetTextPropVal()
F_ApiGetTextVal()

Retrieve the array of tabs (F_TabsT) for a
paragraph or paragraph format

F_ApiGetTabs()

Retrieve the entire property list (F_PropValsT) for
an object

F_ApiGetProps()

Set an element definition’s attribute definitions

F_ApiSetAttributeDefs()

Set an element’s attributes

F_ApiSetAttributes()

Set a property of any type

F_ApiSetPropVal()

Set an array of integers (F_IntsT) property

F_ApiSetInts()

Set an ID (F_ObjHandleT) property

F_ApiSetId()

Set an integer (IntT) property

F_ApiSetInt()

Set a metric (MetricT) property

F_ApiSetMetric()

Set a metrics (F_MetricsT) property

F_ApiSetMetrics()

Set a text location (F_TextLocT) property

F_ApiSetTextLoc()

Set the entire property list (F_PropValsT) for an
object

F_ApiSetProps()

Set an array of points (F_PointsT) property

F_ApiSetPoints()

Set a string (StringT) property

F_ApiSetString()

Set a strings (F_StringsT) property

F_ApiSetStrings()

Set a tabs (F_TabsT) property

F_ApiSetTabs()

Set the text properties (for example, character tag,
font family, font weight) for a text range

F_ApiSetTextProps()
F_ApiSetTextPropVal()
F_ApiSetTextVal()

Set a text range (F_TextRangeT) property

F_ApiSetTextRange()

FDK Programmer’s Reference

53

Selection
To

Use this function

Determine where the insertion point or selected text
is

F_ApiGetTextRange()

Get the element selection in a Structured document

F_ApiGetElementRange()

Set the text selection or insertion point by setting the
property that specifies the text selection
(FP_TextSelection)

F_ApiSetTextRange()

Select cells in a table

F_ApiMakeTblSelection()

Get the IDs of selected graphic objects

F_ApiGetId()

Set the element selection in a Structured document

F_ApiSetElementRange()

Scroll the document to display the currenttrext
range

F_ApiScrollToText()

Sessions
To

Use this function

Quit a session

F_ApiClose()

Sleep
To

Use this function

Suspend FrameMaker product and client operation
for specified number of seconds

F_ApiSleep()

Suspend FrameMaker product and client operation
for specified number of microseconds

F_ApiUSleep()

String lists
To

Use this function

Append a string to a string list

F_StrListAppend()

Concatenate two string lists

F_StrListCat()

To

Use this function

Copy a string from a string list to a string of a
specified size

F_StrListCopy()

Copy an entire string list

F_StrListCopyList()

Create a string list

F_StrListNew()

Free a string list

F_StrListFree()

Get the th string in a string list

F_StrListGet()

Get the first string in a string list

F_StrListFirst()

Get the last string in a string list

F_StrListLast()

Get the position of a specified string in a string list

F_StrListIndex()

Get the position of a specified string in a string list,
ignoring case

F_StrListIIndex()

Get the length of a string list

F_StrListLen()

Insert a string in a string list

F_StrListInsert()

Remove a specified string from a string list

F_StrListRemove()

Copy a string to a specified position in a string list

F_StrListSetString()

Sort a string list using a specified comparison
function

F_StrListSort()

FDK Programmer’s Reference

...

Function Summary

55

1

Function Summary

Strings: allocating, copying, and deallocating
To

Use this function

Allocate a new string

F_StrNew()

Copy a string, allocating memory for the new string

F_StrCopyString()

Copy a string to memory that is already allocated

F_StrCpy()

Copy a specified number of characters of
a string

F_StrCpyN()

Deallocate a string

F_Free()

Strings: comparing and parsing
To

Use this function

Compare two strings

F_StrCmp()
F_StrEqual()

Compare two strings, ignoring case

F_StrICmp()
F_StrIEqual()

56

Compare two strings up to a specified number of
characters

F_StrEqualN()

Compare two strings up to a specified number of
characters, ignoring case

F_StrICmpN()

Determine whether a string is a prefix of another string

F_StrPrefix()

Determine whether a string is a prefix of another string,
up to a specified number of characters

F_StrPrefixN()

Determine whether a string is a prefix of another string,
ignoring case

F_StrIPrefix()

Determine whether a string is a substring of another
string

F_StrSubString()

Determine whether a string is a suffix of another string

F_StrSuffix()

Parse a string into tokens

F_StrTok()

Return a pointer to the first occurrence in a string of any
of a specified set of characters

F_StrBrk()

FDK Programmer’s Reference

F_StrCmpN()

F_StrIEqualN()

To

Use this function

Return a pointer to the first occurrence of a character in
a string

F_StrChr()

Return a pointer to the first occurrence of a character in
a string, starting from the end of the string

F_StrRChr()

FDK Programmer’s Reference

...

Function Summary

57

1

Function Summary

Strings: concatenating
To

Use this function

Concatenate two strings

F_StrCat()

Concatenate two strings, limiting the result to a specified
number of characters

F_StrCatN()

Concatenate a string and an integer, limiting the result to a
specified number of characters

F_StrCatIntN()

Concatenate a string and a character, limiting the result to a
specified number of characters

F_StrCatCharN()

Strings: miscellaneous

58

To

Use this function

Convert a string to an integer

F_StrAlphaToInt()

Convert a string to a real number

F_StrAlphaToReal()

Get the length of a string

F_StrLen()

Reverse a string

F_StrReverse()

Strip a specified set of characters from
a string

F_StrStrip()

Strip leading spaces from a string

F_StrStripLeadingSpaces()

Strip trailing spaces from a string

F_StrStripTrailingSpaces()

Truncate a string at a specified position

F_StrTrunc()

FDK Programmer’s Reference

...

Function Summary

Strings: encoded
To

Use this function

Perform string operations on double-byte text that
similar to the operations you can perform on
single-byte text

F_StrCatDblCharNEnc()
F_StrCatNEnc()
F_StrChrEnc()
F_StrCmpNEnc()
F_StrConvertEnc()
F_StrCpyNEnc()
F_StrICmpEnc()
F_StrICmpNEnc()
F_StrIEqualEnc()
F_StrIEqualNEnc()
F_StrIPrefixEnc()
F_StrISuffixEnc()
F_StrLenEnc()
F_StrRChrEnc()
F_StrTruncEnc()

Get encoding information for a font or font family

F_ApiGetEncodingForFamily()
F_ApiGetEncodingForFont()

Get and set encoding data for a session

F_ApiGetSupportedEncodings()
F_ApiIsEncodingSupported()
F_FontEncId()
F_FontEncName()

Initialize encoding data for a session

F_FdeInitFontEncs()

Structure: manipulating elements
To

Use this function

Add an element to a location in the
structural hierarchy of a Structured
document or book

F_ApiNewElementInHierarchy()

Copy attributes

F_ApiCopyAttribute()
F_ApiCopyAttributes()

FDK Programmer’s Reference

59

1

Function Summary

To

Use this function

Copy newly added structures—perform a
deep copy and copy any arrays or strings
referenced by the structure.

F_ApiCopyStructureTypes

Create a book component in a structured
book

F_ApiNewBookComponentIn
Hierarchy()

Create an element in a document

F_ApiNewElement()

Deallocate attributes

F_ApiDeallocateAttributes()

Deallocate memory referenced by the
newly added structures—perform a deep
deallocation and deallocates any arrays or
strings referenced by the structure.

F_ApiDeallocateStructureType()

Delete an element, but leave its contents in
the document

F_ApiUnWrapElement()

Demote an element

F_ApiDemoteElement()

Get an element’s attributes

F_ApiGetAttributes()

Get current valid elements for the insertion
point

F_ApiGetElementCatalog()

Get the element selection

F_ApiGetElementRange()

Insert an element around the selected text
and elements

F_ApiWrapElement()

Insert a book component of a specified type
at a specified position in a structured

F_ApiNewBookComponentOfTypeInHierarchy()

Merge selected elements into the first
element

F_ApiMergeIntoFirst()

Merge selected elements into the last
element

F_ApiMergeIntoLast()

Promote an element

F_ApiPromoteElement()

Set the element selection in a Structured
document or book

F_ApiSetElementRange()

Set an element’s attributes

F_ApiSetAttributes()

Split one element into two

F_ApiSplitElement()

FrameMaker book.

60

FDK Programmer’s Reference

...

Function Summary

Structure: manipulating element definitions and format rules
To

Use this function

Check the value of an element definition to
determine that the element is text and not a
real element

F_ApiElementDefIsText()

Copy attribute definitions

F_ApiCopyAttributeDef()
F_ApiCopyAttributeDefs()

Create a format change list
(FO_FmtChangeList object)

F_ApiNewNamedObject()

Create a format rule (FO_FmtRule object)

F_ApiNewSubObject()

Create a format rule clause
(FO_FmtRuleClause object)

F_ApiNewSubObject()

Deallocate attribute definitions

F_ApiDeallocateAttributeDefs()

Delete a format change list from the format
change list catalog

F_ApiDelete()

Delete a format rule or format rule clause

F_ApiDelete()

Get an element definition’s attribute
definitions

F_ApiGetAttributeDefs()

Get the ID of a format change list

F_ApiGetNamedObject()

Import element definitions to a document

F_ApiSimpleImportElementDefs()

Set an element definition’s attribute
definitions

F_ApiSetAttributeDefs()

F_ApiNewSubObject()

Tables
To

Use this function

Add columns to a table

F_ApiAddCols()

Add rows to a table

F_ApiAddRows()

Create a new table

F_ApiNewTable()

Delete columns from a table

F_ApiDeleteCols()

Delete rows from a table

F_ApiDeleteRows()
F_ApiDelete()

Delete a table

F_ApiDelete()

FDK Programmer’s Reference

61

1

62

Function Summary

To

Use this function

Select cells in a table

F_ApiMakeTblSelection()

Straddle cells in a table

F_ApiStraddleCells()

Unstraddle cells in a table

F_ApiUnStraddleCells()

FDK Programmer’s Reference

...

Function Summary

Text
To

Use this function

Clear text selection from a document

F_ApiClear()

Copy text selection from a document to the
Clipboard

F_ApiCopy()

Cut text selection from a document to the
Clipboard

F_ApiCut()

Delete text from a paragraph or graphic text line

F_ApiDeleteText()

Get the text (array of text items) that an object
contains

F_ApiGetText()

Get the text (array of text items) that an text range
contains

F_ApiGetTextForRange()

Get a text property (for example, character tag,
font family, font weight) for a text location

F_ApiGetTextPropVal()
F_ApiGetTextVal()

Get all the text properties for a text location

F_ApiGetTextProps()

Insert text in a paragraph, graphic text line, or
client text inset

F_ApiAddText()

Paste Clipboard contents at insertion point in a
document

F_ApiPaste()

Query a text range property

F_ApiGetTextRange()

Set a text property for a text range

F_ApiSetTextPropVal()
F_ApiSetTextVal()

Set all the text properties for a text range

F_ApiSetTextProps()

Set a text range property

F_ApiSetTextRange()

Text: find and replace
To

Use this function

Execute the find and replace command from an
API client

F_ApiFind()

FDK Programmer’s Reference

63

1

Function Summary

Text insets
To

Use this function

Add text to a client text inset
(FO_TiApiClient object)

F_ApiAddText()

Convert a locked text inset range to text

F_ApiConvertToText()

Create a Frame product text inset
(FO_TiFlow, FO_TiText, or
FO_TiTextTable object)

F_ApiImport()

Create a client text inset

F_ApiNewAnchoredObject()

Delete a text inset

F_ApiDelete()

Delete text from a client text inset
(FO_TiApiClient object)

F_ApiDeleteTextInsetContents()

Get a default property list for use with
F_ApiImport()

F_ApiGetImportDefaultParams()

Get text from a text inset

F_ApiGetText()

Update stale text insets

F_ApiUpdateTextInset()

Unicode
To

Use this function

Enable Unicode Mode or Compatibility Mode

F_ApiEnableUnicode()

Undo/Redo

64

To

Use this function

Clear both the undo and redo stacks in the
document specified by docId.

F_ApiUndoCancel()

Mark the starting point of a series of API calls
that are to be treated as a single undoable
operation in the document specified by docId.

F_ApiUndoStartCheckPoint()

FDK Programmer’s Reference

To

Use this function

Mark the ending point of a series of API calls
that are to be treated as a single undoable
operation for the docid specified in the call to
F_ApiUndoStartCheckpoint

F_ApiUndoEndCheckPoint()

FDK Programmer’s Reference

...

Function Summary

65

1

Function Summary

Utility

66

To

Use this function

Allow the user to cancel a client operation

F_ApiUserCancel()

Call another FDK client

F_ApiCallClient()

Determine if an ID represents a valid object in a
specified document

F_ApiObjectValid()

Exit and free memory

F_ApiBailOut()

Get a default property list for use with
F_ApiImport()

F_ApiGetImportDefaultParams()

Get a default property list for use with
F_ApiOpen()

F_ApiGetOpenDefaultParams()

Get a default property list for use with
F_ApiSave()

F_ApiGetSaveDefaultParams()

Get an object’s type

F_ApiGetObjectType()

Get the index for a property-value pair
(PropValT) in a property list

F_ApiGetPropIndex()

Get the directory containing the current client

F_ApiClientDir()

Get the registered name of the current client

F_ApiClientName()

Reformat a document

F_ApiReformat()

Request notification for specific events from the
Frame product

F_ApiNotification()

Suspend Frame product and client operation for
specified number of seconds

F_ApiSleep()

Set the default directory for the client

F_ApiSetClientDir()

Suspend Frame product and client operation for
specified number of microseconds

F_ApiUSleep()

FDK Programmer’s Reference

3

FDK Function Reference

..................................
.....

2

This chapter lists the FDK functions alphabetically. If you know the name of a function
and want a complete description of it, look it up in this chapter. If you know what you
want to do, but don’t know which function to use, see Chapter 1, “Function Summary.”
Some examples in this chapter use FDE functions, such as F_Alloc() and
F_Sprintf(). For more information on using FDE and FDE functions, see Part III,
“Frame Development Environment (FDE),” in the FDK Programmer’s Guide.
..............................................................................

IMPORTANT: The examples in this chapter assume that your client includes the
fapi.h and fdetypes.h header files in addition to the header files listed in the
function synopsis.
..............................................................................

FDK Programmer’s Reference

67

3

FDK Function Reference

F_Alloc()

F_ A l l o c ( )
F_Alloc() allocates a block of memory.
Synopsis
#include "fdetypes.h"
#include "fmemory.h"
. . .
PtrT F_Alloc(UIntT n,
PUCharT flags);

Arguments
n

The number of bytes of memory to allocate

flags

Specifies whether to bail out (DSE) or return NULL (NO_DSE) if the
requested memory isn’t available

Returns
A pointer to the allocated block of memory, or NULL if the requested memory isn’t
available.
Example
The following code allocates memory to a pointer, clears it, and then frees it:
. . .
UCharT *ptr = NULL;
ptr = F_Alloc(65535, NO_DSE);
if(ptr == NULL)
{
F_Printf(NULL, "Couldn't Allocate memory.\n");
return;
}
else
F_ClearPtr(ptr, 65535);
. . .
F_Free(ptr);
. . .

See also
“F_AllocHandle()” on page 69.

68

FDK Programmer’s Reference

F_AllocHandle()

...

FDK Function Reference

F_AllocHandle()
F_AllocHandle() allocates a new handle to a block of memory. Use
F_FreeHandle() to free the memory when you are done with it.
After you have allocated a handle, call F_LockHandle() to get the address of the
handle’s block of memory.
Synopsis
#include "fdetypes.h"
#include "fmemory.h"
. . .
HandleT F_AllocHandle(UIntT n,
PUCharT flags);

Arguments
n

The number of bytes of memory to allocate

flags

Specifies whether to bail out (DSE) or return NULL (NO_DSE) if the
requested memory isn’t available

Returns
A handle to the allocated block of memory, or NULL if the requested memory isn’t
available.

FDK Programmer’s Reference

69

3

FDK Function Reference

F_ApiAddCols()

Example
The following code allocates a block of memory to a handle, clears the memory, and
then stores some data to it. After storing data to the memory, it unlocks and frees the
handle.
. . .
HandleT hndl = NULL;
UCharT *ptr;
UIntT i;
hndl = F_AllocHandle(66000, NO_DSE);
if(hndl == NULL)
{
F_Printf(NULL, "Couldn't allocate handle.\n");
return;
}
F_ClearHandle(hndl);
ptr = F_LockHandle(hndl);
/* Stuff the block of memory with a bunch of 9s. */
for(i= 0; i < 66000; i++)
ptr[i] = '9';
F_FreeHandle(hndl);
. . .

See also
“F_Alloc()” on page 68, “F_LockHandle()” on page 577, and “F_UnlockHandle()” on
page 714.

F_ApiAdd Cols()
F_ApiAddCols() adds columns to a table.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiAddCols(F_ObjHandleT docId,
F_ObjHandleT tableId,
IntT refColNum,
IntT direction,
IntT numNewCols);

70

FDK Programmer’s Reference

F_ApiAddCols()

...

FDK Function Reference

Arguments
docId

The ID of the document containing the table.

tableId

The ID of the table.

refColNum

The column at which to start adding columns. The columns are numbered
from left to right starting with column 0.

direction

The direction from the reference column in which to add columns. To add
columns to the left of the reference column, specify FV_Left. To add them
to the right, specify FV_Right.

numNewCols

The number of columns to add.

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiAddCols() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadParameter

The function call specified an invalid parameter

FE_BadObjId

Invalid object ID

FE_BadOperation

The function call specified an illegal operation

Example
The following code adds a column to the right of the first column in the selected table:
. . .
F_ObjHandleT docId, tblId;
/* Get the document and table IDs. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tblId = F_ApiGetId(FV_SessionId, docId, FP_SelectedTbl);
/* Add the column. */
F_ApiAddCols(docId, tblId, 0, FV_Right, 1);
. . .

See also
“F_ApiAddRows()” on page 78.

FDK Programmer’s Reference

71

3

FDK Function Reference

F_ApiAddCommandToMenu()

F_ApiAddCommandToMenu()
F_ApiAddCommandToMenu() adds a FrameMaker product command or a clientdefined command to a menu.
F_ApiAddCommandToMenu() adds the command at the bottom of the specified
menu. To change a command’s position on a menu, set its
FP_PrevMenuItemInMenu and FP_NextMenuItemInMenu properties. For more
information on arranging menus and menu items, see “Arranging menus and menu
items” on page 388 of the FDK Programmer’s Guide.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiAddCommandToMenu(F_ObjHandleT toMenuId,
F_ObjHandleT commandId);

Arguments
toMenuId

The ID of the menu to which to add the command

commandId

The ID of the command

To add a command that you have created, set commandId to the ID returned by the
F_ApiDefineCommand() or F_ApiDefineCommandEx() call that created the
command.
To add a FrameMaker product command, you must get its ID. To get its ID, call
F_ApiGetNamedObject() with the objectName parameter set to its name. For
example, to get the ID of the Copy command, use the following code:
. . .
F_ObjHandleT copyCmdId;
copyCmdId = F_ApiGetNamedObject(FV_SessionId, FO_Command,
"Copy");
. . .

To add a command to a menu that you have created, set toMenuId to the ID returned
by F_ApiDefineMenu() or F_ApiDefineAndAddMenu() when you created the
menu.
To add a menu item to a FrameMaker product menu, you must get the menu’s ID by
calling F_ApiGetNamedObject() with the objectName parameter set to the
menu’s name.

72

FDK Programmer’s Reference

F_ApiAddCommandToMenu()

...

FDK Function Reference

The [Files] section of the maker.ini file specifies the location of the menu and
command configuration files that list FrameMaker’s menus and commands.
Users can create custom menu files that override the default menus and commands. For
more information, see your FrameMaker product installation documentation.
Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiAddCommandToMenu() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this
operation or fmbatch is running

FE_BadOperation

Parameters specify an invalid operation

FE_NotCommand

commandId doesn’t specify a command

FE_NotMenu

toMenuId doesn’t specify a menu

FE_BadParameter

Parameter has an invalid value

FE_SystemError

System error

Example
The following code creates a command named MyCommand and adds it to the File
menu. It also adds the FrameMaker product command UpperCaseText to the File
menu. It then rearranges the commands on the menu so that the two newly added
commands appear first:

FDK Programmer’s Reference

73

3

FDK Function Reference

F_ApiAddMenuToMenu()

. . .
#define MY_CMD 1
F_ObjHandleT cmdId, ucCmdId, menuId;
/* Create the command. */
cmdId = F_ApiDefineCommand(MY_CMD, "MyCommand",
"My Command", "\\!MC");
/* Get the ID of the file menu and the UpperCaseText command. */
menuId = F_ApiGetNamedObject(FV_SessionId, FO_Menu, "FileMenu");
ucCmdId = F_ApiGetNamedObject(FV_SessionId,
FO_Command, "UpperCaseText");
/* Add the two commands to the File menu. */
F_ApiAddCommandToMenu(menuId, cmdId);
F_ApiAddCommandToMenu(menuId, ucCmdId);
/* Set command object properties to rearrange menu items. */
F_ApiSetId(FV_SessionId, menuId, FP_FirstMenuItemInMenu, cmdId);
F_ApiSetId(menuId, ucCmdId, FP_PrevMenuItemInMenu, cmdId);
. . .

See also
“F_ApiDefineCommand()” on page 137, “F_ApiDefineAndAddCommand()” on
page 126, and “F_ApiGetNamedObject()” on page 214.

F_ApiAddMenuToMenu()
F_ApiAddMenuToMenu() adds a FrameMaker product menu or a menu that you have
created to another menu or menu bar.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiAddMenuToMenu(F_ObjHandleT toMenuId,
F_ObjHandleT menuId);

74

FDK Programmer’s Reference

F_ApiAddMenuToMenu()

...

FDK Function Reference

Arguments
toMenuId

The ID of the menu to which the new menu is to be added

menuId

The ID of the new menu

To add a menu to a menu or menu bar that you have created, set
toMenuId to the ID returned by the F_ApiDefineMenu() or
F_ApiDefineAndAddMenu() call that created the menu or menu bar.
To add a menu to one of the FrameMaker product’s menus or menu bars, you must get
the menu or menu bar’s ID. To get its ID, call F_ApiGetNamedObject() with the
objectName parameter set to its name. For example, to get the ID of the Book main
menu bar, use the following code:
. . .
F_ObjHandleT mainMenuId;
mainMenuId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"!BookMainMenu");
. . .

The [Files] section of the maker.ini file specifies the location of the menu and command
configuration files that list FrameMaker’s menus and commands.
..............................................................................

IMPORTANT: Your menu appears only on the menu bar you specify. For example, if you
only add a menu 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 !QuickMakerMainMenu.
..............................................................................

The following table lists the types of menus you can add a menu to and how the
FrameMaker product implements the added menu.
Type of menu or menu
bar you are adding a
menu to

How the FrameMaker product
implements the added menu

Where the FrameMaker
product adds the menu

Menu bar

Pull-down menu

At the right of the menu
bar

Pull-down menu

Pull-right menu

At the bottom of the pulldown menu

FDK Programmer’s Reference

75

3

FDK Function Reference

F_ApiAddMenuToMenu()

Type of menu or menu
bar you are adding a
menu to

How the FrameMaker product
implements the added menu

Where the FrameMaker
product adds the menu

Pop-up menu

Pull-right menu

At the bottom of the popup menu

Pull-right menu

Pull-right menu

At the bottom of the pullright menu

To change a menu’s position on a menu or menu bar after you add it, set its
FP_PrevMenuItemInMenu and FP_NextMenuItemInMenu properties. For more
information on arranging menus and menu items, see “Arranging menus and menu
items” on page 388 of the FDK Programmer’s Guide.

76

FDK Programmer’s Reference

F_ApiAddMenuToMenu()

...

FDK Function Reference

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiAddMenuToMenu() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this
operation or fmbatch is running

FE_NotMenu

toMenuId and menuId don’t specify menus

FE_BadOperation

Parameters specify an invalid operation

FE_BadParameter

Parameter has an invalid value

FE_SystemError

System error

Example
The following code creates a menu with one command and adds it to the FrameMaker
main menu bar (for both complete and quick menus):
. . .
#define MY_CMD 1
F_ObjHandleT quickMenuBarId, menubarId, menuId, cmdId;
/* Create the menu, then create a command and add it. */
menuId = F_ApiDefineMenu("APIMenu", "API Menu");
cmdId = F_ApiDefineAndAddCommand(MY_CMD, menuId, "MyCmd",
"My Cmd", "");
/* Get ID of FrameMaker main menu (complete menus). */
menubarId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"!MakerMainMenu");
/* Get ID of FrameMaker main menu (quick menus). */
quickMenuBarId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"!QuickMakerMainMenu");
/* Add the menu to the menu bars. */
F_ApiAddMenuToMenu(menubarId, menuId);
F_ApiAddMenuToMenu(quickMenuBarId, menuId);
. . .

FDK Programmer’s Reference

77

3

FDK Function Reference

F_ApiAddRows()

See also
“F_ApiDefineMenu()” on page 141, “F_ApiDefineAndAddMenu()” on page 134, and
“F_ApiGetNamedObject()” on page 214.

F_ApiAdd Rows()
F_ApiAddRows() adds one or more rows to a table.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiAddRows(F_ObjHandleT docId,
F_ObjHandleT refRowId,
IntT direction,
IntT numNewRows);

Arguments
docId

The ID of the document containing the table.

refRowId

The ID of the row at which to starting adding rows.

direction

The direction from the reference row in which to add rows. For a list of the
constants you can specify, see the table below.

numNewRows

The number of rows to add.

The following table lists the constants you can specify for direction.
Direction constant

78

Meaning

FV_Above

Add rows above the row specified by refRowId. The added rows
are the same type as the row specified by refRowId.

FV_Below

Add rows below the row specified by refRowId. The added rows
are the same type as the row specified by refRowId.

FV_Body

Add body rows at the bottom of the existing body rows (refRowId
is used to determine which table to add rows to).

FV_Footing

Add footing rows at the bottom of the existing footing rows
(refRowId is ignored).

FV_Heading

Add heading rows at the bottom of the existing heading rows
(refRowId is ignored).

FDK Programmer’s Reference

F_ApiAddRows()

...

FDK Function Reference

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiAddRows() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this operation

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid row ID

FE_BadOperation

Parameters specify an invalid operation

FE_BadParameter

Parameter has an invalid value

Example
The following code adds two rows after the first row of the selected table:
. . .
F_ObjHandleT docId, tblId, row1Id;
/* Get the document and table IDs. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tblId = F_ApiGetId(FV_SessionId, docId, FP_SelectedTbl);
/* Get the ID for row 1. */
row1Id = F_ApiGetId(docId, tblId, FP_FirstRowInTbl);
/* Add the rows. */
F_ApiAddRows(docId, row1Id, FV_Below, 2);
. . .

See also
“F_ApiAddCols()” on page 70.

FDK Programmer’s Reference

79

3

FDK Function Reference

F_ApiAddText()

F_ApiAddTe xt()
F_ApiAddText() inserts text into a paragraph or a text line.
Synopsis
#include "fapi.h"
. . .
F_TextLocT F_ApiAddText(F_ObjHandleT docId,
F_TextLocT *textLocp,
StringT text);

Arguments
docId

The ID of the document

textLocp

The text location at which to add the text

text

The text to add

The text you specify for text must use the FrameMaker product character set. To add
special characters, you must specify octal (\) or hexadecimal (\x) sequences. The
following table lists some of these sequences.

80

Special character

Hexadecimal
representation

Octal
representation

>

\x3e

\76

" (straight double quotation mark)

\x22

\42

“ (left double quotation mark)

\xd2

\322

” (right double quotation mark)

\xd3

\323

FDK Programmer’s Reference

F_ApiAddText()

...

FDK Function Reference

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 not
using ANSI C, you must specify octal (\) sequences instead of hexadecimal codes. If
you are using ANSI C, you can specify either octal or hexadecimal sequences.
Returns
The text location of the end of the text that was added. If it fails, the returned text
location is invalid.
If F_ApiAddText() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID.

FE_BadObjId

Invalid object ID.

FE_NotTextObject

The object that textLocp specifies is not a
paragraph (FO_Pgf) or a text line
(FO_TextLine).

FE_OffsetNotFound

The offset specified for the text location couldn’t be
found in the specified text object.

FE_ReadOnly

The specified document is read-only.

FE_BadSelectionForOperation

The location that textLocp specifies is invalid.
For example, it is inside a variable or outside the
highest level element in a structured document.

FDK Programmer’s Reference

81

3

FDK Function Reference

F_ApiAlert()

Example
To add the following text at the insertion point (or the end of the current text selection),
The new CoffeeTool
is now on sale.

use the following code:
. . .
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,docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
/* Add text. Use octal 011 for Return (end of paragraph). */
trm = F_ApiAddText(docId, &tr.end, "The new CoffeeTool\011");
/* Add more text to the end of the text that was just added. */
F_ApiAddText(docId, &trm, "is now on sale.");
. . .

See also
“F_ApiGetText()” on page 249 and “F_ApiDeleteText()” on page 151.

F_ApiAlert ()
F_ApiAlert() displays an alert box with a message. Depending on the constant you
specify for type, it displays either OK and Cancel buttons, Yes and No buttons, or a
Continue button.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiAlert(StringT message, IntT type);

82

FDK Programmer’s Reference

F_ApiAlert()

...

FDK Function Reference

Arguments
message

The message that appears in the dialog box. If the message is longer than 255
characters, it is truncated.

type

The dialog box type. See below for dialog types.

Specify one of the following constants for the type argument:
type constant

Type of dialog box displayed

FF_ALERT_OK_DEFAULT

Displays OK and Cancel buttons; OK is the default

FF_ALERT_CANCEL_DEFAULT

Displays OK and Cancel buttons; Cancel is the default

FF_ALERT_CONTINUE_NOTE

Displays Ok button

FF_ALERT_CONTINUE_WARN

Displays Ok button with a warning indication

FF_ALERT_YES_DEFAULT

Displays Yes and No buttons; Yes is the default

FF_ALERT_NO_DEFAULT

Displays Yes and No buttons; No is the default

Returns
0 if the user clicked OK, Continue, or Yes; -1 if the user clicked
Cancel or No.
Example
Use the code shown in Figure 2-1 and Figure 2-2 to produce the following alert boxes.

F_ApiAlert("This alert is an OK_DEFAULT.", FF_ALERT_OK_DEFAULT);

FDK Programmer’s Reference

83

3

FDK Function Reference

F_ApiAlert()

F_ApiAlert("This alert is a CANCEL_DEFAULT.", FF_ALERT_CANCEL_DEFAULT);

F_ApiAlert("This alert is a CONTINUE_NOTE.", FF_ALERT_CONTINUE_NOTE);

F_ApiAlert("This alert is a CONTINUE_WARN.", FF_ALERT_CONTINUE_WARN);
Figure 2-1 Sample code for alert boxes

F_ApiAlert("This alert is a YES_DEFAULT.", FF_ALERT_YES_DEFAULT);

84

FDK Programmer’s Reference

F_ApiAlive()

...

FDK Function Reference

F_ApiAlert("This alert is a NO_DEFAULT.", FF_ALERT_NO_DEFAULT);
Figure 2-2 Sample code for alert boxes

F_ A p i A l i v e ( )
Checks whether the current asynchronous client has a connection with a FrameMaker
process. Use it after registering the asynchronous client via
F_ApiWinConnectSession().
Synopsis
#include "f_stdio.h"
. . .
IntT F_ApiAlive (VoidT);

Returns
If there is a current connection to a FrameMaker process, this function returns a positive
integer. Otherwise it returns 0.
See also
F_ApiWinConnectSession()

F_ApiAllocatePropVals()
F_ApiAllocatePropVals() allocates memory for a property list.
Synopsis
#include "fapi.h"
. . .
F_PropValsT F_ApiAllocatePropVals(IntT numProps);

FDK Programmer’s Reference

85

3

FDK Function Reference

F_ApiAllocateTextItems()

Arguments
numProps

The number of properties in the property list

Returns
A property list (an F_PropValsT data structure).
The returned F_PropValsT structure references memory that is allocated by the API.
Use F_ApiDeallocatePropVals() to free this memory when you are done with it.
If F_ApiAllocatePropVals() fails, the API sets the len field of the returned
structure to 0.
Example
The following code allocates memory for an Open script (property list):
. . .
F_PropValsT openParams;
openParams = F_ApiAllocatePropVals(FS_NumOpenParams);
if(openParams.len == 0) return;
/* Use property list here. */
/* We’re done with the property list, so we deallocate it. */
F_ApiDeallocatePropVals(&openParams);
. . .

See also
“F_ApiDeallocateStructureType()” on page 125.

F _ A p i A l l o c a t eTe x t It e ms ()
F_ApiAllocateTextItems() allocates memory for an F_TextItemsT structure
and the array of text items that it references.
Synopsis
#include "fapi.h"
. . .
F_TextItemsT F_ApiAllocateTextItems(IntT numTextItems);

86

FDK Programmer’s Reference

F_ApiAllocateTextItems()

...

FDK Function Reference

Arguments
numTextItems

The number of text items to allocate

FDK Programmer’s Reference

87

3

FDK Function Reference

F_ApiApplyAttributeExpression()

Returns
An F_TextItemsT structure.
The returned F_TextItemsT structure references memory that is allocated by the
API. Use F_ApiDeallocateTextItems() to free this memory when you are done
with it.
If F_ApiAllocateTextItems() fails, the API sets the len field of the returned
structure to 0.
Example
The following code allocates ten text items:
. . .
F_TextItemsT tis;
tis = F_ApiAllocateTextItems(10);
. . .

See also
“F_ApiGetText()” on page 249.

F_ApiApplyAttributeExpre ssion()
Applies an attribute expression to a document to perform attribute-based-filtering.
Synopsis
#include "fapi.h"
...
IntT F_ApiApplyAttributeExpression(F_ObjHandleT docId,
F_ObjHandleT attrExprId);

Arguments

88

docId

The ID of the document to which the attribute
expression is to be applied.

attrExprId

The ID of the attribute expression to be applied to
the document.

FDK Programmer’s Reference

F_ApiApplyAttributeExpressionAsCondition()

...

FDK Function Reference

Returns
FE_Success if it succeeds, or an error code if an error occurs. If
F_ApiApplyAttributeExpression() fails, the API assigns one of the following
values to FA_errno.
FA_errno Value

Meaning

FE_BadDocId
FE_BadObjId
FE_InvalidAttrExpr

Invalid document ID.

FE_WrongProduct

The current FrameMaker product doesn't support
the operation.

FE_SystemError .

Couldn't allocate memory

Invalid expression ID.
The attribute expression being invalid cannot be
applied to the document

Example
The following code applies the expression named 'WebOutput' to the document.
. . .
F_ObjHandleT attrExprId = F_ApiGetNamedObject(docId,
FO_AttrCondExpr,"WebOutput");
F_ApiApplyAttributeExpression(docId, attrExprId);
...

F_ApiApplyAttributeExpre ssionAsCondition()
Applies an attribute-based expression to the document where the filtered text is
converted to conditional text.
Synopsis
#include "fapi.h"
...
StatusT F_ApiApplyAttributeExpressionAsCondition(
F_ObjHandleT docId,
F_ObjHandleT attrExpId,
F_ObjHandleT condId,
BoolT removePreviouslyApplied);

FDK Programmer’s Reference

89

3

FDK Function Reference

F_ApiApplyPageLayout()

Arguments
docId

The ID of the document on which attrExpId is to be
applied

attrExpId

The ID of the attribute expression to be applied on the
document

condId

The ID of the conditional text format that will be
applied on the filtered text

removePreviouslyApplied

If true, then remove the conditional text settings at all
locations in the document, whereever condId is

applied.
Returns
If succeeds: FE_Success
If an error occurs: An error code

If API fails, the API assigns one of the following values to FA_errno:
FA_errno value

Meaning

FE_Success

Operation is successful

FE_BadDocId

Invalid document ID

FE_InvalidAttrExpr

The expression string set in the attrExpId's object is
invalid

FE_WrongProduct

Current product interface isn’t Structured FrameMaker

FE_BadObjId

Invalid object ID

F_ApiApplyPageLayout()
F_ApiApplyPageLayout() applies a page’s layout to another page.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiApplyPageLayout(F_ObjHandleT docId,
F_ObjHandleT destPage,
F_ObjHandleT srcPage);

90

FDK Programmer’s Reference

F_ApiApplyPageLayout()

...

FDK Function Reference

Arguments
docId

The document containing the pages

destPage

The page with the layout to apply

srcPage

The page to which to apply the layout

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiApplyPageLayout() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this
operation or fmbatch is running

FE_BadOperation

Parameters specify an invalid operation

FE_BadParameter

Parameter has an invalid value

FE_SystemError

System error

Example
The following code applies the layout of the Right master page to the
current page:
. . .
F_ObjHandleT docId, curPageId, rtPageId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
curPageId = F_ApiGetId(FV_SessionId, docId, FP_CurrentPage);
rtPageId = F_ApiGetId(FV_SessionId, docId, FP_RightMasterPage);
F_ApiApplyPageLayout(docId, curPageId, rtPageId);
. . .

See also
“F_ApiSimpleImportFormats()” on page 462.

FDK Programmer’s Reference

91

3

FDK Function Reference

F_ApiBailOut()

F_ApiBailOut()
F_ApiBailOut() allows your client to bail out. When your client calls
F_ApiBailOut(), the FrameMaker product waits until it returns control from the
current callback, and then exits it, saving system resources.
After your client has bailed out, the FrameMaker product still processes events that
affect it. Menus your client created are still valid. If your client has requested
notification for particular events, the FrameMaker product continues to monitor those
events. It also monitors apiclient hypertext commands that specify your client’s
name. If these events occur, the FrameMaker product restarts your client by calling its
F_ApiInitialize() function with initialization set to
FA_Init_Subsequent.
..............................................................................

IMPORTANT: If your client bails out, it loses all its global variable settings.

..............................................................................

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiBailOut();

Arguments
None.
Returns
VoidT.
If F_ApiBailOut() fails, the API assigns the following value to FA_errno.

92

FA_errno value

Meaning

FE_Transport

A transport error occurred

FDK Programmer’s Reference

F_ApiCallClient()

...

FDK Function Reference

Example
The following code bails out if the FrameMaker product currently running is not
FrameMaker:
. . .
StringT product;
product = F_ApiGetString(0, FV_SessionId, FP_ProductName);
if (!F_StrEqual(product, "FrameMaker"))
{
F_ApiAlert ("FDK client requires FrameMaker to run.",
FF_ALERT_CONTINUE_WARN);
F_ApiBailOut();
/* Bail out is not effective until return. */
return;
}
. . .

F_ApiCallC lient()
F_ApiCallClient() allows a client to call another client. It is useful for calling
Structured FrameMaker clients, such as the structure generator and the element catalog
manager.
F_ApiCallClient() calls the F_ApiNotify() function of the target client, with
notification set to FA_Note_ClientCall, docId set to 0, and sparm set
to the string specified by arg. To receive the notification sent by
F_ApiCallClient(), the target client must be registered and must have requested
the FA_Note_ClientCall notification, as shown in the
following code:
. . .
F_ApiNotification(FA_Note_ClientCall, True);
. . .

FDK Programmer’s Reference

93

3

FDK Function Reference

F_ApiCenterOnText()

Synopsis
#include "fapi.h"
. . .
IntT F_ApiCallClient(StringT clname,
StringT arg);

Arguments
clname

The registered name of the target client. For the names of FrameMakwe
clients, see the table below.

arg

A string that is passed to the target client.

Returns
FE_Success if it succeeds, or the value specified by the target client’s last call to
F_ApiReturnValue(). Note that calls to the structure generator always return
FE_Success no matter what string is passed to it as an argument.
If F_ApiCallClient() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_NameNotFound

There is no client with the specified name in the current
FrameMaker product session

FE_BadParameter

For the TableSort client only:
One of the arguments is invalid. For example, you gave a value for
the sort key that is greater than the number of columns or rows in
the current table selection, or you have no table cells selected.

F_ApiCenterOnText()
F_ApiCenterOnText() centers a range of text so the middle of the text appears in
the middle of the document window.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiCenterOnText(F_ObjHandleT docId,
F_TextRangeT *textRangep);

94

FDK Programmer’s Reference

F_ApiCenterOnText()

...

FDK Function Reference

Arguments
docId

The ID of the document containing the text range

textRangep

The range of text to center

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiCenterOnText() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadRange

The specified text range is invalid

FE_NotTextObject

One of the objects specified for textRangep isn’t a paragraph
(FO_Pgf) or a text line (FO_TextLine)

FE_OffsetNotFound

The offset specified for the text location couldn’t be found in the
specified paragraph or text line

Example
The following code centers the text selection or insertion point:
. . .
F_ObjHandleT docId;
F_TextRangeT tr;
/* Get current text selection */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
F_ApiCenterOnText(docId, &tr);
. . .

See also
“F_ApiScrollToText()” on page 404.

FDK Programmer’s Reference

95

3

FDK Function Reference

F_ApiCheckStatus()

F_ApiCheckStatus()
F_ApiCheckStatus() checks the scripts returned by F_ApiOpen(),
F_ApiImport(), F_ApiSave(), and F_ApiUpdateBook() to determine if a
specified status bit is set.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiCheckStatus(F_PropValsT *p,
IntT statusBit);

Arguments
p

The property list returned by F_ApiOpen(), F_ApiSave(),
F_ApiImport(), or F_ApiUpdateBook()

statusBit

The status bit to test

Returns
True if the bit is set; otherwise, False.
Example
The following code determines whether fonts were mapped after a document is opened
successfully:
. . .
F_PropValsT returnParams;
returnParams = F_ApiAllocatePropVals(FS_NumOpenReturnParams);
. . .
/* Call to F_ApiOpen() goes here. */
if (F_ApiCheckStatus(&returnParams, FV_FontsWereMapped))
F_ApiAlert("Unavailable fonts were mapped.",
FF_ALERT_CONTINUE_NOTE);
. . .

See also
“F_ApiAddRows()” on page 78, “F_ApiOpen()” on page 355, “F_ApiSave()” on
page 399, and “F_ApiUpdateBook()” on page 480.

96

FDK Programmer’s Reference

F_ApiChooseFile()

...

FDK Function Reference

F_ApiChooseFile()
F_ApiChooseFile() displays dialog boxes similar to a Frame product’s Open and
Save dialog boxes. It displays directories and files in a scroll list and allows the user to
choose a file or directory.
Depending on the platform you are running your client on and the constant you specify
for mode, the dialog box can provide Select, Open, Save, Use, or Cancel buttons. If the
user clicks Select, Open, Save, or Use, F_ApiChooseFile() stores the selected file
or directory’s pathname to *choice. If the user clicks Cancel,
F_ApiChooseFile() does not assign a value to *choice.
..............................................................................

IMPORTANT: F_ApiChooseFile() allocates memory for the string referenced by
*choice. Use F_Free() to free the string when you are done with it.
..............................................................................

Synopsis
#include "fapi.h"
. . .
IntT F_ApiChooseFile(StringT *choice,
StringT title,
StringT directory,
StringT stuffVal,
IntT mode,
StringT helpLink);

FDK Programmer’s Reference

97

3

FDK Function Reference

F_ApiChooseFile()

Arguments
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 an FDK client is used. If no FDK
client has used a directory, the directory specified by the session 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. See the table below for possible
values.

helpLink

Obsolete for versions 6.0 and later; pass an empty string.
The name of a document containing help information for the dialog box or an
empty string ("") if there is no help document.

You can specify the following values for mode.
mode constant

Dialog box type

FV_ChooseSelect

Dialog box that allows the user to choose a file by
clicking Select. It provides an input field that the user
can type a filename in.

FV_ChooseOpen

Dialog box that allows the user to choose a file by
clicking Open. It provides an input field that the user
can type a filename in.

FV_ChooseSave

Dialog box that allows the user to select a file. It
provides Save and Cancel buttons and an input field.

FV_ChooseOpenDir

Dialog box that allows the user to choose a directory.

Returns
0 if the user clicked Open, Select, Use, or Save; a nonzero value if the user clicked
Cancel or an error occurred.
If F_ApiChooseFile() fails, the API assigns the following value to FA_errno.

98

FA_errno value

Meaning

FE_Transport

A transport error occurred

FDK Programmer’s Reference

F_ApiChooseFile()

...

FDK Function Reference

Example
The following code displays the dialog boxes shown in Figure 2-3, Figure 2-4, and
Figure 2-5
. . .
IntT err;
StringT sres;
err = F_ApiChooseFile(&sres, "Choose a file to open.",
"", "", FV_ChooseOpen, "");
if (!err) F_ApiDeallocateString(&sres);
err = F_ApiChooseFile(&sres, "Select a file.",
"", "", FV_ChooseSelect, "");
if (!err) F_ApiDeallocateString(&sres);
err = F_ApiChooseFile(&sres, "Choose a file to save.", "",
"myfile.doc", FV_ChooseSave, "");
if (!err) F_ApiDeallocateString(&sres);
. . .

Figure 2-3 FV_ChooseFile dialog box

FDK Programmer’s Reference

99

3

FDK Function Reference

F_ApiClear()

Figure 2-4 FV_ChooseSelect dialog box

Figure 2-5 FV_ChooseSave dialog box

See also
“F_ApiScrollBox()” on page 402.

F _ A p i C l e a r( )
F_ApiClear() deletes the current selection from a document.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiClear(F_ObjHandleT docId
IntT flags);

100

FDK Programmer’s Reference

F_ApiClear()

...

FDK Function Reference

Arguments
docId

The ID of the document from which to clear the selection.

flags

Bit field that specifies how to clear the text and how to handle interactive alerts. For
default settings, specify 0.

If you specify 0 for flags, F_ApiClear() suppresses any interactive alerts or
warnings that arise, leaves the selected table cells empty, and deletes hidden text. You
can also OR the following values into flags.
flags constant

Meaning

FF_INTERACTIVE

Prompt user with dialog or alert boxes that arise

FF_CUT_TBL_CELLS

Remove cleared table cells

FF_VISIBLE_ONLY

Clear only the visible portion of the selection

FF_DONT_DELETE_HIDDEN_TEXT

Don’t delete hidden text

The FF_INTERACTIVE flag takes precedence over other flags. So, if you specify
FF_INTERACTIVE | FF_DONT_DELETE_HIDDEN_TEXT and the selection contains
hidden text, the Frame product allows the user to choose whether to delete the hidden
text.
Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiClear() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadSelectionForOperation

Current selection is invalid for this operation

FE_Canceled

User or parameters canceled the operation

FE_WrongProduct

Current Frame product doesn’t support requested
operation

FDK Programmer’s Reference 101

3

FDK Function Reference

F_ApiClearAllChangebars()

Example
The following code extends the text selection to the end of the paragraph, and then
deletes it:
. . .
F_TextRangeT tr;
F_ObjHandleT docId, pgfId, nextpgfId;
/* Get current text selection. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
/* Get ID of next paragraph and extend selection to it. */
nextpgfId = F_ApiGetId(docId, tr.end.objId, FP_NextPgfInFlow);
if (nextpgfId)
{
tr.end.objId = nextpgfId;
tr.end.offset = 0;
F_ApiSetTextRange(FV_SessionId, docId, FP_TextSelection,&tr);
}
F_ApiClear(docId, 0);
. . .

See also
“F_ApiCopy()” on page 115, “F_ApiCut()” on page 123, and “F_ApiPaste()” on
page 364.

F_ A p i C l e a rA llC h an gebars()
F_ApiClearAllChangebars() clears change bars from a specified document. It
executes the same command as clicking the Clear All Change Bars box in the Change
Bars dialog box.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiClearAllChangebars(F_ObjHandleT docId);

102

FDK Programmer’s Reference

F_ApiClientDir()

...

FDK Function Reference

Arguments
docId

The ID of the document for which to clear the change bars

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiClearAllChangebars() fails, the API assigns one of the following values
to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Bad document ID

FE_WrongProduct

Current Frame product doesn’t support this operation

FE_SystemError

System error

Example
The following code removes the change bars from the current document:
. . .
F_ObjHandleT docId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
F_ApiClearAllChangebars(docId);
. . .

F _ A p i C l i e n t D i r( )
F_ApiClientDir() returns the name of the current FDK client’s directory, which is
the directory that contains the client’s DLL.
Synopsis
#include "fapi.h"
. . .
StringT F_ApiClientDir(VoidT);

Arguments
None.

FDK Programmer’s Reference 103

3

FDK Function Reference

F_ApiClientName()

Returns
The name of the current FDK client’s directory if it succeeds, or NULL if an error
occurs. If you get a NULL string, you should check FA_errno; if it is set to
FE_Success, then there is no  statement in the apiclients file. To
provide a client directory, use F_ApiSetClientDir(). For more information, see
“F_ApiSetClientDir()” on page 412.
If F_ApiClientDir() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

..............................................................................

IMPORTANT: Use F_Free() to free the string returned by F_ApiClientDir()
when you are done with it.
..............................................................................

Example
The following code displays the name of the directory containing the current FDK client
in an alert box:
. . .
#include "fmemory.h"
StringT clientDir;
clientDir = F_ApiClientDir();
F_ApiAlert(clientDir, FF_ALERT_CONTINUE_NOTE);
F_Free(clientDir);
. . .

See also
“F_ApiSetClientDir()” on page 412 and “F_ApiClientName()” on page 104.

F_ApiClientName( )
F_ApiClientName() returns the registered name of the current client (the client that
calls F_ApiClientName()). For more information on registering FDK clients, see
the FDK Platform Guide for your platform.

104

FDK Programmer’s Reference

F_ApiClientName()

...

FDK Function Reference

Synopsis
#include "fapi.h"
. . .
StringT F_ApiClientName(VoidT);

Arguments
None.
Returns
The registered name of the current client if it succeeds, or NULL if an error occurs.
If F_ApiClientName() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

..............................................................................

IMPORTANT: Use F_Free() to free the string returned by F_ApiClientName()
when you are done with it.
..............................................................................

Example
The following code displays the registered name of the current FDK client in an alert
box:
. . .
#include "fmemory.h"
StringT clientName;
clientName = F_ApiClientName();
F_ApiAlert(clientName, FF_ALERT_CONTINUE_NOTE);
F_Free(clientName);
. . .

See also
“F_ApiClientDir()” on page 103.

FDK Programmer’s Reference 105

3

FDK Function Reference

F_ApiClientPath()

F _ A p i C l i e n t P a th ()
F_ApiClientPath() returns the name of the current FDK client’s path, which is the
path that contains the client’s DLL.
Synopsis
#include "fapi.h"
. . .
StringT F_ApiClientPath(ConStringT clientName);

Arguments
None.
Returns
The name of the current FDK client’s path if it succeeds, or NULL if an error occurs..
If F_ApiClientPath() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

..............................................................................

IMPORTANT: Use F_Free() to free the string returned by F_ApiClientPath()
when you are done with it.
..............................................................................

Example
The following code displays the name of the path containing the current FDK client in
an alert box:
. . .
#include "fmemory.h"
StringT clientPath;
clientDir = F_ApiClientPath();
F_ApiAlert(clientDir, FF_ALERT_CONTINUE_NOTE);
F_Free(clientPath);
. . .

See also
“F_ApiClientDir()” on page 103 and “F_ApiClientName()” on page 104.

106

FDK Programmer’s Reference

F_ApiClose()

...

FDK Function Reference

F _ A p i C l o s e( )
F_ApiClose() closes a document, book, dialog box, or Frame session.
If there are unsaved changes in a file and you set FF_CLOSE_MODIFIED for the
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_DocModified.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiClose(F_ObjHandleT Id,
IntT flags);

Arguments
Id

The ID of the document, book, dialog box, or session to close.

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.

To quit a Frame session, set Id to FV_SessionId.
..............................................................................

IMPORTANT: If you are closing an individual document or a dialog box, make sure Id
specifies an object ID and not 0. If Id is set to 0, F_ApiClose() quits the Frame
session, because the value of the FV_SessionId constant is 0. If you call
F_ApiClose() in the F_ApiDialogEvent() callback, call it only to close custom
modeless dialog boxes. Calling it for any other reason, such as ending the Frame
product session or closing a modal dialog box, will cause unexpected results.
..............................................................................

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiClose() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_DocModified

The document was modified and flags was set to 0

FDK Programmer’s Reference 107

3

FDK Function Reference

F_ApiClose()

Example
The following code closes the active document:
. . .
F_ObjHandleT docId;
IntT resp;
/* Get ID of active document. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
/* See whether document has been modified. */
if (F_ApiGetInt(FV_SessionId, docId, FP_DocIsModified))
resp = F_ApiAlert("Document changed. Close it anyway?",
FF_ALERT_OK_DEFAULT);
if (!resp) F_ApiClose (docId, FF_CLOSE_MODIFIED);
. . .

See also
“F_ApiSave()” on page 399.

108

FDK Programmer’s Reference

F_ApiCombinedFamilyFonts()

...

FDK Function Reference

F_ApiCombinedFamilyFonts()
F_ApiCombinedFamilyFonts() returns the permutations of angles, variations, and
weights available for a specified combined font definition.
..............................................................................

IMPORTANT: To return the permutations of a combined font family, you must use
F_ApiFamilyFonts(). For more information, see “F_ApiFamilyFonts()” on
page 165.
..............................................................................

Synopsis
#include "fapi.h"
. . .
F_CombinedFontsT F_ApiCombinedFamilyFonts
(F_ObjHandleT combinedFont);

Arguments
combinedFont

The object ID of a combined font definition

To get a list of combined font definitions, use FP_FirstCombinedFontDefnInDoc to
get the first combined font definition in the document. From that you can build a list of
combined font definitions using FP_NextCombinedFontDefnInDoc.
Returns
An F_CombinedFontsT structure provides a list of the permutations of angles,
variations, and weights available for the specified combined font definition.
F_CombinedFontsT is defined as:
typedef struct {
UIntT len;
F_CombinedFontT *val;
} F_CombinedFontsT;

F_CombinedFontT is defined as:
typedef struct {
F_ObjHandelT combinedFont; /* Combined font ID */
UIntT variation; /* Index of the font variation. */
UIntT weight; /* Index of the font weight. */
UIntT angle; /* Index of the font angle. */
} F_CombinedFontT;

FDK Programmer’s Reference 109

3

FDK Function Reference

F_ApiCombinedFamilyFonts()

Example
The following code loops through the combined fonts in a document and prints the
combined font name, the base and Western font family names, and the permutations for
the combined font:
. . .
#include "fapi.h"
#include "futils.h"
#include "fstrings.h"
. . .
UIntT i, base, west;
F_StringsT families, weights, variations, angles;
StringT cFontName;
F_CombinedFontsT perms;
F_ObjHandleT docId, cFontId;
. . .
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
/*Get lists of families, vars, weights, and angles for session*/
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 combined font definitions for the doc */
cFontId = F_ApiGetId(FV_SessionId, docId,
FP_FirstCombinedFontDefnInDoc);
while (cFontId) {
/* Print combined font name, and base and Western family names
*/
cFontName = F_ApiGetString(docId, cFontId, FP_Name);
base = F_ApiGetInt(docId, cFontId, FP_BaseFamily);
west = F_ApiGetInt(docId, cFontId, FP_WesternFamily);
F_Printf(NULL, (StringT)
"\n%s is composed of the %s and %s font families.\n",
cFontName, families.val[base], families.val[west]);

110

FDK Programmer’s Reference

F_ApiCommand()

...

FDK Function Reference

/* Print the permutations of the combined font */
perms = F_ApiCombinedFamilyFonts(cFontId);
for (i = 0; i < perms.len; i++) {
F_Printf(NULL, (StringT)
"Variation: %s, Weight: %s, Angle: %s\n",
variations.val[perms.val[i].variation],
weights.val[perms.val[i].weight],
angles.val[perms.val[i].angle]);
}
/* Free the array of F_CombinedFontT structures and */
/* get the next combined font definition in the document. */
F_Free(perms.val);
cFontId = F_ApiGetId(docId, cFontId,
FP_NextCombinedFontDefnInDoc);
}
. . .
/* Free the string list structures. */
F_ApiDeallocateStrings(&families);
F_ApiDeallocateStrings(&weights);
F_ApiDeallocateStrings(&variations);
F_ApiDeallocateStrings(&angles);

F_ApiCommand()
F_ApiCommand() is a callback that you must define to respond to the user choosing
a menu item added by your client.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiCommand(command)
IntT command;
{
/* Code to respond to menu item choices goes here. */
}

FDK Programmer’s Reference

111

3

FDK Function Reference

F_ApiCompare()

Arguments
command

The cmd parameter from the
F_ApiDefineCommand(),F_ApiDefineCommandEx()or
F_ApiDefineAndAddCommand() call that created the menu item that the user
chose

Returns
VoidT.
Example
See “Responding to the user choosing a command” on page 209 of the FDK
Programmer’s Guide.

F_ApiCompare ()
F_ApiCompare() compares two documents or two books.
Synopsis
#include "fapi.h"
. . .
F_CompareRetT F_ApiCompare(F_ObjHandleT olderId,
F_ObjHandleT newerId,
IntT flags,
StringT insertCondTag,
StringT deleteCondTag,
StringT replaceText,
IntT compareThreshold);

112

FDK Programmer’s Reference

F_ApiCompare()

...

FDK Function Reference

Arguments
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. Specify 0 for the default flags.

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

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. If a paragraph is not equal to another, it is marked
inserted or deleted. To specify an 85% threshold, set
compareThreshold to 85. The default value is 75.

You can OR the values shown in the following table into the flags argument.
flags constant

Meaning

FF_CMP_SUMMARY_ONLY

Generate a summary document, but not a composite document

FF_CMP_CHANGE_BARS

Turn on change bars in the composite document

FF_CMP_HYPERLINKS

Put hypertext links in the summary document

FF_CMP_SUMKIT

Open the summary document

FF_CMP_COMPKIT

Open the composite document

FDK Programmer’s Reference

113

3

FDK Function Reference

F_ApiCompare()

Returns
An F_CompareRetT data structure. F_CompareRetT is defined as:
typedef struct {
F_ObjHandleT sumId; /* The ID of the summary document */
F_ObjHandleT compId; /* The ID of the composite document */
} F_CompareRetT;

If you use F_ApiCompare() to compare two books, it sets compId to 0.
If F_ApiCompare() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID.

FE_BadCompare

olderId and newerId don’t specify the same types of files.

FE_CompareTypes

One of the files isn’t a FrameMaker product document or book or one
file is a book and the other is a document.

FE_WrongProduct

Current FrameMaker product doesn’t support the operation.

Example
The following code opens two documents and compares them:
. . .
F_ObjHandleT oldId, newId;
IntT flags;
F_CompareRetT cmp;
oldId = F_ApiSimpleOpen("/tmp/old.doc", False);
newId = F_ApiSimpleOpen("/tmp/new.doc", False);
flags = FF_CMP_CHANGE_BARS | FF_CMP_COMPKIT;
cmp = F_ApiCompare(oldId, newId, flags, "Comment",
"", "REPLACED TEXT", 75);
if (!cmp.compId)
F_ApiAlert("Couldn’t compare", FF_ALERT_CONTINUE_NOTE);
. . .

114

FDK Programmer’s Reference

F_ApiConnectToSession()

...

FDK Function Reference

F_ApiConnectToSession()
F_ApiConnectToSession() connects the calling process to an existing
FrameMaker product session process.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiConnectToSession(ConStringT clientName,
ConStringT hostname,
IntT prognum);

Arguments
clientName

The registered name of the client

hostname

The host running the FrameMaker product session

prognum

The RPC number of the FrameMaker product session

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiConnectToSession() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_DupName

The client attempted to connect to the same session

FE_ReadOnly

The client attempted to connect to a session started with the
-noapi option

FE_OutOfRange

The client attempted to connect to a session of a
FrameMaker product version that doesn’t support this
function

FE_NameNotFound

There is no FrameMaker product session

See also
“F_ApiDisconnectFromSession()” on page 159

F_ApiCopy()
F_ApiCopy() copies the current selection to the FrameMaker product Clipboard.

FDK Programmer’s Reference

115

3

FDK Function Reference

F_ApiCopy()

Synopsis
#include "fapi.h"
. . .
IntT F_ApiCopy(F_ObjHandleT docId,
IntT flags);

Arguments
docId

The ID of the document from which to copy the selection.

flags

Bit field that specifies how to copy the text and how to handle interactive alerts. For
default settings, specify 0.

If you specify 0 for flags, F_ApiCopy() suppresses any interactive alerts or
warnings that arise. You can also OR the following values into flags.
flags constant

Meaning

FF_INTERACTIVE

Prompt user with dialog or alert boxes that arise

FF_STRIP_HYPERTEXT

Do not copy any hypertext markers in the selection

FF_VISIBLE_ONLY

Copy only the visible portion of the selection

The FF_INTERACTIVE flag takes precedence over other flags. So, if you specify
FF_INTERACTIVE | FF_VISIBLE_ONLY and the selection is not visible, the
FrameMaker product allows the user to choose whether to copy the selection.

116

FDK Programmer’s Reference

F_ApiCopy()

...

FDK Function Reference

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiCopy() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_WrongProduct

Current FrameMaker product doesn’t support
operation

FE_BadSelectionForOperation

Selection doesn’t support operation

FE_Canceled

User or parameters canceled the operation

FE_BadOperation

Parameters specified an invalid operation

Example
The following code selects the first 10 characters of the paragraph containing the
insertion point and copies them to the FrameMaker product Clipboard:
. . .
F_TextRangeT tr;
F_ObjHandleT docId, pgfId, nextpgfId;
/* Get current text selection. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId,docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
/* Set text selection. */
tr.beg.offset = 0;
tr.end.offset = 10;
F_ApiSetTextRange(FV_SessionId,docId, FP_TextSelection, &tr);
F_ApiCopy(docId, 0);
. . .

See also
“F_ApiClear()” on page 100, “F_ApiCut()” on page 123, and “F_ApiPaste()” on
page 364.

FDK Programmer’s Reference

117

3

FDK Function Reference

F_ApiCopyStructureType()

F_ApiCopy Str u c t u re Ty p e( )
The following functions copy frequently used API structures. These functions perform
a complete copy, copying any arrays or strings referenced by the structures.
Synopsis
#include "fapi.h"
. . .
F_AttributeT F_ApiCopyAttribute(F_AttributeT *fromattribute);
F_AttributeDefT F_ApiCopyAttributeDef(
F_AttributeDefT *fromattributedef);
F_AttributeDefsT F_ApiCopyAttributeDefs(
F_AttributeDefsT *fromattributedefs);
F_AttributesT F_ApiCopyAttributes(
F_AttributesT *fromattributes);
F_ElementCatalogEntriesT F_ApiCopyElementCatalogEntries(
F_ElementCatalogEntriesT *fromelementcatents);
F_FontsT F_ApiCopyFonts(F_FontsT *fonts);
F_IntsT F_ApiCopyInts(F_IntsT *fromints);
F_MetricsT F_ApiCopyMetrics(F_MetricsT *frommetrics);
F_PointsT F_ApiCopyPoints(F_PointsT *frompoints);
F_PropValT F_ApiCopyProp(F_PropValT *frompropp);
F_PropValsT F_ApiCopyPropVals(F_PropValsT *frompvp);
StringT F_ApiCopyString(ConStringT s);
F_StringsT F_ApiCopyStrings(F_StringsT *fromstrings);
F_TabT F_ApiCopyTab(F_TabT *fromtab);
F_TabsT F_ApiCopyTabs(F_TabsT *fromtabs);
F_TextItemT F_ApiCopyTextItem(F_TextItemT *fromtip);
F_TextItemsT F_ApiCopyTextItems(F_TextItemsT *fromip);
F_UBytesT F_ApiCopyUBytes(F_UBytesT *fromubytes);
F_UIntsT F_ApiCopyUInts(F_UIntsT *fromuints);
F_TypedValT F_ApiCopyVal(F_TypedValT *fromvalp);

Arguments
fromStructureType

The structure to copy

Returns
A copy of the specified structure.

118

FDK Programmer’s Reference

F_ApiCustomDoc()

...

FDK Function Reference

Example
The following code copies the list of font family names available in the current session:
. . .
F_StringsT familyNames, strs;

familyNames = F_ApiGetStrings(0, FV_SessionId,
FP_FontFamilyNames);
strs = F_ApiCopyStrings(&familyNames);

F_ApiDeallocateStrings(&familyNames);
. . .

F_ApiCustomDoc()
F_ApiCustomDoc() creates a new custom document using the FrameMaker
product’s default new document template. For more information on default new
document templates, see “Documents” on page 73 of the FDK Programmer’s Guide.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiCustomDoc(MetricT width,
MetricT height,
IntT numCols,
MetricT columnGap,
MetricT topMargin,
MetricT botMargin,
MetricT leftinsideMargin,
MetricT rightoutsideMargin,
IntT sidedness,
BoolT makeVisible);

Arguments
width

The document page width.

height

The document page height.

numCols

The default number of columns.

columnGap

The default column spacing.

FDK Programmer’s Reference

119

3

120

FDK Function Reference

F_ApiCustomDoc()

topMargin

The document page top margin.

botMargin

The document page bottom margin.

leftinsideMargin

The left margin for single-sided documents, or the inside margin
for double-sided documents.

rightoutsideMargin

The right margin for single-sided documents, or the outside
margin for double-sided documents.

sidedness

A 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.

makeVisible

Specifies whether the document is visible after it is created. Set
to True to make the document visible.

FDK Programmer’s Reference

F_ApiCustomDoc()

...

FDK Function Reference

The sidedness argument can have the values shown in the following table.
sidedness constant

New document page characteristics

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

Returns
The ID of the new document if it is successful, or 0 if it fails.
If F_ApiCustomDoc() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this operation

FE_BadParameter

Parameter has an invalid value

Example
The following code creates a custom document with the properties specified in the
dialog box in Figure 2-6:
. . .
#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);
. . .

FDK Programmer’s Reference 121

3

FDK Function Reference

F_ApiCustomDoc()

Figure 2-6 Custom document dialog box

See also
“F_ApiSimpleNewDoc()” on page 464 and “F_ApiOpen()” on page 355.

122

FDK Programmer’s Reference

F_ApiCut()

...

FDK Function Reference

F_ApiCut()
F_ApiCut() cuts the current selection to the FrameMaker product Clipboard.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiCut(F_ObjHandleT docId,
IntT flags);

Arguments
docId

The ID of the document from which to cut the current selection.

flags

Bit field that specifies how to cut the text and how to handle interactive alerts. For
default settings, specify 0.

If you specify 0 for flags, F_ApiCut() suppresses any interactive alerts or warnings
that arise, leaves selected table cells empty, and deletes hidden text. You can also OR
the following values into flags.
flags constant

Meaning

FF_INTERACTIVE

Prompt user with dialog or alert boxes that arise

FF_CUT_TBL_CELLS

Remove cut table cells

FF_VISIBLE_ONLY

Cut only the visible portion of the selection

FF_DONT_DELETE_HIDDEN_TEXT

Don’t cut hidden text

The FF_INTERACTIVE flag takes precedence over other flags. So, if you specify
FF_INTERACTIVE | FF_DONT_DELETE_HIDDEN_TEXT and the selection contains
hidden text, the FrameMaker product allows the user to choose whether to delete the
hidden text.

FDK Programmer’s Reference 123

3

FDK Function Reference

F_ApiCut()

Returns
FE_Success if it succeeds, or an error code if an error occurs
If F_ApiCut() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_WrongProduct

Current FrameMaker product doesn’t support
requested operation

FE_BadSelectionForOperation

Selection doesn’t support operation

FE_Canceled

User or parameters canceled the operation

FE_BadOperation

Parameters specified an invalid operation

Example
The following code cuts the selected text from a document:
. . .
F_ApiCut(docId, 0);
. . .

See also
“F_ApiClear()” on page 100, “F_ApiCopy()” on page 115, “F_ApiPaste()” on
page 364, “F_ApiPopClipboard()” on page 366, and “F_ApiPushClipboard()” on
page 384.

124

FDK Programmer’s Reference

F_ApiDeallocateStructureType()

...

FDK Function Reference

F_ApiDeallocate St ructureType( )
The following functions deallocate memory referenced by frequently used API
structures. These functions perform a deep deallocation, deallocating any arrays or
strings referenced by the structures.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiDeallocateAttribute(F_AttributeT *attribute);
VoidT F_ApiDeallocateAttributeDef(
F_AttributeDefT *attributedef);
VoidT F_ApiDeallocateAttributeDefs(
F_AttributeDefsT *attributedefs);
VoidT F_ApiDeallocateAttributes(F_AttributesT *attributes);
VoidT F_ApiDeallocateElementCatalogEntries(
F_ElementCatalogEntriesT *elementcatents);
VoidT F_ApiDeallocateFonts(F_FontsT *fonts);
VoidT F_ApiDeallocateInts(F_IntsT *ints);
VoidT F_ApiDeallocateMetrics(F_MetricsT *metrics);
VoidT F_ApiDeallocatePoints(F_PointsT *points);
VoidT F_ApiDeallocatePropVal(F_PropValT *prop);
VoidT F_ApiDeallocatePropVals(F_PropValsT *pvp);
VoidT F_ApiDeallocateString(StringT s);
VoidT F_ApiDeallocateStrings(F_StringsT *strings);
VoidT F_ApiDeallocateTab(F_TabT *tab);
VoidT F_ApiDeallocateTabs(F_TabsT *tabs);
VoidT F_ApiDeallocateTextItem(F_TextItemT *tip);
VoidT F_ApiDeallocateTextItems(F_TextItemsT *ip);
VoidT F_ApiDeallocateUBytes(F_UBytesT *ubytes);
VoidT F_ApiDeallocateUInts(F_UIntsT *uints);
VoidT F_ApiDeallocateVal(F_TypedValT *valp);

Arguments
StructureType

The structure referencing memory that needs to be deallocated

Returns
VoidT.

FDK Programmer’s Reference 125

3

FDK Function Reference

F_ApiDefineAndAddCommand()

Example
The following code deallocates a property list:
. . .
F_PropValsT props;
. . .
F_ApiDeallocatePropVals(&props);
. . .

F_ApiDefineAndAddCommand()
F_ApiDefineAndAddCommand() defines a command (FO_Command object) and
adds it to a menu or menu bar.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiDefineAndAddCommand(IntT cmd,
F_ObjHandleT toMenuId,
StringT name,
StringT label,
StringT shortcut);

Arguments
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. It must be unique for each command in
your client, but it need not be unique for different clients.

toMenuId

The ID of the menu to which to add the command.

name

A unique name for the command. If the user or a client has already defined a
command or menu with this name, the new command replaces it.

label

The title of the command as it appears on the menu.

shortcut

The keyboard shortcut sequence. Many FrameMaker product commands use
shortcuts beginning with Escape (\!). To specify Escape when you create a
command, use \\! in the string you pass to shortcut.

To add the new command to a menu that you have created, set toMenuId to the ID
returned by the F_ApiDefineMenu() or F_ApiDefineAndAddMenu() call that
created the menu.

126

FDK Programmer’s Reference

F_ApiDefineAndAddCommand()

...

FDK Function Reference

To add a command to a FrameMaker product menu, you must first get the menu’s ID.
To get its ID, call F_ApiGetNamedObject() with the objectName parameter set
to its name. For example, to get the ID of the Edit menu, use the following code:
. . .
F_ObjHandleT editMenuId;
editMenuId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"EditMenu");
. . .

The [Files] section of the maker.ini file specifies the location of the menu and command
configuration files that list FrameMaker’s menus and commands.
The following table lists some FrameMaker product menus and the names you use to
specify them:
Menu title

Menu name

Edit

EditMenu

File

FileMenu

Format

FormatMenu

Graphics

GraphicsMenu

Special

SpecialMenu

Table

TableMenu

View

ViewMenu

Help

!HelpMenu

If 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.
If the user has already put the menu item specified by name on the menus,
F_ApiDefineAndAddCommand() ignores the toMenuId parameter and connects
the command to the existing menu item. If the menu item is not already on a menu,
F_ApiDefineAndAddCommand() adds it to the bottom of the menu specified by
toMenuId.

FDK Programmer’s Reference 127

3

FDK Function Reference

F_ApiDefineAndAddCommand()

..............................................................................

IMPORTANT: If you want to add a command to more than one menu, do not call
F_ApiDefineAndAddCommand() repeatedly to add the command to the menus. This
does not work, because if a command already exists,
F_ApiDefineAndAddCommand() ignores the toMenuId argument and just
replaces the existing command with the new command. To add a command to multiple
menus, define the command first by calling F_ApiDefineCommand() or
F_ApiDefineCommandEx()—or call F_ApiDefineAndAddCommand(), if you
want to define and add the command to a menu at the same time—and then call
F_ApiAddCommandToMenu() to add the command to other menus.
..............................................................................

128

FDK Programmer’s Reference

F_ApiDefineAndAddCommandEx()

...

FDK Function Reference

Returns
The ID of the new command (FO_Command object), or 0 if an error occurs.
If F_ApiDefineAndAddCommand() fails, the API assigns one of the following
values to FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this
operation or fmbatch is running

FE_BadOperation

Parameters specify an invalid operation

FE_NotMenu

The menu specified by toMenuId
doesn’t exist

FE_BadParameter

Parameter has an invalid value

FE_SystemError

System error

Example
The following code creates a command named MyCmd and adds it to the Utilities
menu:
. . .
#define MY_CMD 1
F_ObjHandleT menuId, cmdId;
menuId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"UtilitiesMenu");
cmdId = F_ApiDefineAndAddCommand(MY_CMD, menuId, "MyCmd",
"My Cmd", "\\!MC");
. . .

See also
“F_ApiAddCommandToMenu()” on page 72, “F_ApiDefineCommand()” on page 137,
and “F_ApiGetNamedObject()” on page 214.

F_ApiDefineAndAddCommandEx()
F_ApiDefineAndAddCommandEx() is similar to
F_ApiDefineAndAddCommand() with an extra parameter to specify the views in
which this command is valid.

FDK Programmer’s Reference 129

3

FDK Function Reference

F_ApiDefineAndAddCommandEx()

Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiDefineAndAddCommandEx (IntT cmd,
F_ObjHandleT toMenuId,
ConStringT tag,
ConStringT label,
ConStringT shortcut,
const F_StringsT *validViewsList);

Arguments
cmd

The integer that the FrameMaker product passes to the client’s
F_ApiCommand() function when the user chooses the menu item
or types the keyboard shortcut for the command. It must be unique
for each command in your client, but it need not be unique for
different clients.

toMenuId

The ID of the menu to which to add the command.

tag

A unique name for the command. If the user or a client has already
defined a command or menu with this name, the new command
replaces it.

label

The title of the command as it appears on the menu.

shortcut

The keyboard shortcut sequence. Many FrameMaker commands
use shortcuts beginning with Escape (\!). To specify Escape when
you create a command, use \\! in the string you pass to
shortcut.

validViewsList

The view(s) for which this command is valid. The view(s) can be:
WYSIWYG View
XML View
Author View
corresponding to the views supported by FrameMaker.

To add the new command to a menu that you have created, set toMenuId to the ID
returned by the F_ApiDefineMenu() or F_ApiDefineAndAddMenu() call that
created the menu.

130

FDK Programmer’s Reference

F_ApiDefineAndAddCommandEx()

...

FDK Function Reference

To add a command to a FrameMaker product menu, you must first get the menu’s ID.
To get its ID, call F_ApiGetNamedObject() with the objectName parameter set
to its name. For example, to get the ID of the Edit menu, use the following code:
. . .
F_ObjHandleT editMenuId;
editMenuId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"EditMenu");
. . .

The [Files] section of the maker.ini file specifies the location of the menu and command
configuration files that list FrameMaker’s menus and commands.
The following table lists some FrameMaker product menus and the names you use to
specify them:
Menu title

Menu name

Edit

EditMenu

File

FileMenu

Format

FormatMenu

Graphics

GraphicsMenu

Special

SpecialMenu

Table

TableMenu

View

ViewMenu

Help

!HelpMenu

If you call F_ApiDefineAndAddCommandEx() 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.
If the user has already put the menu item specified by name on the menus,
F_ApiDefineAndAddCommandEx() ignores the toMenuId parameter and
connects the command to the existing menu item. If the menu item is not already on a
menu, F_ApiDefineAndAddCommandEx() adds it to the bottom of the menu
specified by toMenuId.

FDK Programmer’s Reference 131

3

FDK Function Reference

F_ApiDefineAndAddCommandEx()

..............................................................................

IMPORTANT: If you want to add a command to more than one menu, do not call
F_ApiDefineAndAddCommandEx() repeatedly to add the command to the menus.
This does not work, because if a command already exists,
F_ApiDefineAndAddCommandEx() ignores the toMenuId argument and just
replaces the existing command with the new command. To add a command to multiple
menus, define the command first by calling F_ApiDefineCommand() or
F_ApiDefineCommandEx()—or call F_ApiDefineAndAddCommandEx(), if
you want to define and add the command to a menu at the same time—and then call
F_ApiAddCommandToMenu() to add the command to other menus.
..............................................................................

132

FDK Programmer’s Reference

F_ApiDefineAndAddCommandEx()

...

FDK Function Reference

Returns
The ID of the new command (FO_Command object), or 0 if an error occurs.
If F_ApiDefineAndAddCommandEx() fails, the API assigns one of the following
values to FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this
operation or fmbatch is running

FE_BadOperation

Parameters specify an invalid operation

FE_NotMenu

The menu specified by toMenuId
doesn’t exist

FE_BadParameter

Parameter has an invalid value

FE_SystemError

System error

Example
The following code makes the command valid in WYSIWYG View and Author View:
StringT validViews[2] = {(StringT)"WYSIWYG
View",(StringT)"Author View"};
F_StringsT validViewsList = {2, validViews};
F_ObjHandleT cmdId = F_ApiDefineAndAddCommandEx (CMD_NUM,
menuId, "api_command", "API Command", !ac", &validViewsList);

The following code makes the command valid in all views:
StringT validViews = {(StringT)"All"};
F_StringsT validViewsList = {1, &validViews};
F_ObjHandleT cmdId = F_ApiDefineAndAddCommandEx (CMD_NUM,
menuId, "api_command", "API Command", !ac", &validViewsList)

FDK Programmer’s Reference 133

3

FDK Function Reference

F_ApiDefineAndAddMenu()

F_ApiDefineAndAddMenu()
F_ApiDefineAndAddMenu() defines a menu (FO_Menu object) and adds it to
another menu.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiDefineAndAddMenu(F_ObjHandleT toMenuId,
StringT name,
StringT label);

Arguments
toMenuId

The name of the menu or menu bar to which to add the new menu.

name

A unique name for the new menu. If the user or an FDK client has already
defined a command or menu with this name, the new menu replaces it.

label

The title of the menu as it appears on the menu bar or menu.

To add a menu to a menu or menu bar created by your client, set toMenuId to the ID
returned by the F_ApiDefineMenu() or F_ApiDefineAndAddMenu() call that
created the menu or menu bar.
To add a menu to one of a FrameMaker product’s menus or menu bars, you must get the
menu or menu bar’s ID. To get its ID, call F_ApiGetNamedObject() with the
objectName parameter set to its name. For example, to get the ID of the FrameMaker
main menu bar, use the following code:
. . .
F_ObjHandleT mainMenuId;
mainMenuId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"!MakerMainMenu");
. . .

134

FDK Programmer’s Reference

F_ApiDefineAndAddMenu()

...

FDK Function Reference

The following table lists some of the menu bars that you can add menus to and the
strings that specify them. Menu bar names preceded by an exclamation mark (!) can’t
be removed by the user.
FrameMaker product menu bar

toMenuBar string

Menu bar for documents (complete menus)

!MakerMainMenu

Menu bar for documents (quick menus)

!QuickMakerMainMenu

Menu bar for documents (custom menus)

!CustomMakerMainMenu

Menu bar for books (complete menus)

!BookMainMenu

Menu bar for books (quick menus)

!QuickBookMainMenu

Structure menu bar (structured product interface only)

!StructureViewMainMenu

View-only menu bar

!ViewOnlyMainMenu

The [Files] section of the maker.ini file specifies the location of the menu and command
configuration files that list FrameMaker’s menus and commands.
..............................................................................

IMPORTANT: The menu you add appears only on the menu bar you specify. For
example, if you add a menu only to the !MakerMainMenu menu bar, the menu does
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 !QuickMakerMainMenu.
..............................................................................

If you call F_ApiDefineAndAddMenu() and specify the name of a menu 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 to the menu, the FrameMaker product uses it instead of the one you specify. If the
menu is already on a menu or menu bar, the FrameMaker product ignores the menu that
you specify and leaves the menu where it is.
If the menu specified by name is not already on a menu or menu bar,
F_ApiDefineAndAddMenu() adds it. How the FrameMaker product adds it depends

FDK Programmer’s Reference 135

3

FDK Function Reference

F_ApiDefineAndAddMenu()

on the type of menu you are adding it to. The following table lists the types of menus
you can add another menu to and how the FrameMaker product adds the menu.
Type of menu or menu bar
you are adding a menu to

How the FrameMaker product
implements the added menu

Where the FrameMaker
product adds the menu

Menu bar

Pull-down menu

At the right of the menu
bar

Pull-down menu

Pull-right menu

At the bottom of the pulldown menu

Pop-up menu

Pull-right menu

At the bottom of the popup menu

Pull-right menu

Pull-right menu

At the bottom of the pullright menu

Returns
The ID of the new menu (FO_Menu object), or 0 if an error occurs.
If F_ApiDefineAndAddMenu() fails, the API assigns one of the following values to
FA_errno.

136

FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this
operation or fmbatch is running

FE_BadOperation

Parameters specify an invalid operation

FE_NotMenu

The menu specified by toMenuId doesn’t exist or
isn’t a menu; tag specifies an existing command

FE_BadParameter

Parameter has an invalid value

FE_SystemError

System error

FDK Programmer’s Reference

F_ApiDefineCommand()

...

FDK Function Reference

Example
The following code defines and adds a menu named APIMenu to the FrameMaker main
menu:
. . .
#define MY_CMD 1
F_ObjHandleT menubarId, menuId, cmdId;
/* Get ID of FrameMaker main menu. */
menubarId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"!MakerMainMenu");
/* Define and add a menu to the main menu. */
menuId = F_ApiDefineAndAddMenu(menubarId, "APIMenu",
"API Menu");
/* Add a command to the menu. */
cmdId = F_ApiDefineAndAddCommand(MY_CMD, menuId, "MyCmd",
"My Cmd", "");
. . .

See also
“F_ApiAddMenuToMenu()” on page 74, “F_ApiDefineMenu()” on page 141, and
“F_ApiGetNamedObject()” on page 214.

F_ApiDefineCommand()
F_ApiDefineCommand() defines a command (FO_Command object). After you
define a command, you can add it to a menu with F_ApiAddCommandToMenu().
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiDefineCommand(IntT cmd,
StringT name,
StringT label,
StringT shortcut);

FDK Programmer’s Reference 137

3

FDK Function Reference

F_ApiDefineCommand()

Arguments
cmd

The integer that the FrameMaker product passes to your client’s
F_ApiCommand() function when the user executes the command. It must be
unique for each menu item in your client, but it need not be unique for different
clients.

name

A unique name for the command. If the user or a client has already defined a
command or menu with this name, the new command replaces it.

label

The title of the menu item as it appears on the menu.

shortcut

The keyboard shortcut sequence. Many FrameMaker product commands use
shortcuts beginning with Escape (\!). To specify Escape when you create a
command, use \\! in the string you pass to shortcut.

If you call F_ApiDefineCommand() 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.
Returns
The ID of the new command (FO_Command object), or 0 if an error occurs.
If F_ApiDefineCommand() fails, the API assigns one of the following values to
FA_errno.

138

FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this
operation or fmbatch is running

FE_BadOperation

Parameters specify an invalid operation

FE_BadParameter

Parameter has an invalid value

FE_NotCommand

tag specifies a menu; can’t redefine a menu as a
command

FE_SystemError

System error

FDK Programmer’s Reference

F_ApiDefineCommandEx()

...

FDK Function Reference

Example
The following code defines a command named CheckGrammar that has a keyboard
shortcut of Esc C G:
. . .
#define CHECK_GRAMMAR 1
F_ObjHandleT cmdId;
cmdId = F_ApiDefineCommand(CHECK_GRAMMAR, "CheckGrammar",
"Check Grammar", "\\!CG");
. . .

See also
“F_ApiDefineCommandEx()” on page 139, “F_ApiAddCommandToMenu()” on
page 72, “F_ApiDefineAndAddCommand()” on page 126, and
“F_ApiGetNamedObject()” on page 214.

F_ApiDefineCommandEx()
F_ApiDefineCommandEx() is similar to F_ApiDefineCommand() with an extra
parameter to specify views in which this command is valid. After you define a
command, you can add it to a menu with F_ApiAddCommandToMenu().
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiDefineCommandEx(IntT cmd,
ConStringT name,
ConStringT label,
ConStringT shortcut,
const F_StringsT *validViewsList);

FDK Programmer’s Reference 139

3

FDK Function Reference

F_ApiDefineCommandEx()

Arguments
cmd

The integer that the FrameMaker product passes to your client’s
F_ApiCommand() function when the user executes the command. It
must be unique for each menu item in your client, but it need not be
unique for different clients.

name

A unique name for the command. If the user or a client has already
defined a command or menu with this name, the new command
replaces it.

label

The title of the menu item as it appears on the menu.

shortcut

The keyboard shortcut sequence. Many FrameMaker product
commands use shortcuts beginning with Escape (\!). To specify
Escape when you create a command, use \\! in the string you pass
to shortcut.

validViewsList

The views for which this command is valid. The view(s) can be:
WYSIWYG View
Code View
Author View
corresponding to the views supported by FrameMaker.

If you call F_ApiDefineCommandEx() 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.
Returns
The ID of the new command (FO_Command object), or 0 if an error occurs.
If F_ApiDefineCommandEx() fails, the API assigns one of the following values to
FA_errno.

140

FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this
operation or fmbatch is running

FE_BadOperation

Parameters specify an invalid operation

FE_BadParameter

Parameter has an invalid value

FE_NotCommand

tag specifies a menu; can’t redefine a menu as a
command

FE_SystemError

System error

FDK Programmer’s Reference

F_ApiDefineMenu()

...

FDK Function Reference

Example
The following code makes the comman valid in WYSIWYG view and Author view:
. . .
StringT validViews[2] = {(StringT)"WYSIWYG iew",(StringT)"Author
View"};
F_StringsT validViewsList = {2, validViews};
F_ObjHandleT cmdId = F_ApiDefineCommandEx (CMD_NUM,
"api_command", "API Command", "!ac", &validViewsList);
. . .

See also
“F_ApiAddCommandToMenu()” on page 72, “F_ApiDefineAndAddCommand()” on
page 126, and “F_ApiGetNamedObject()” on page 214.

F_ApiDefineMenu()
F_ApiDefineMenu() defines a menu (FO_Menu object). After you define a menu,
you can add it to a menu or a menu bar with F_ApiAddMenuToMenu().
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiDefineMenu(StringT name,
StringT label);

Arguments
name

A unique name for the menu. If the user or an FDK client has
already defined a command or menu with this name, the new menu replaces it.

label

The title of the menu as it appears on the menu bar or menu.

If you call F_ApiDefineMenu() and specify the name of a menu 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 to the menu, the FrameMaker product uses it instead of the one you specify.
If the user has already defined a menu with the name specified by name,
F_ApiDefineMenu() ignores the label parameter and uses the label specified by
the user.

FDK Programmer’s Reference 141

3

FDK Function Reference

F_ApiDefineMenu()

Returns
The ID of the new menu (FO_Menu object), or 0 if an error occurs.
If F_ApiDefineMenu() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this
operation or fmbatch is running

FE_BadOperation

Parameters specify an invalid operation

FE_NotMenu

tag specifies a command; can’t redefine a
command as a menu

FE_BadParameter

Parameter has an invalid value

FE_SystemError

System error

Example
The following code adds a menu named Search to the menu bar for books. It also adds
a command labeled Find and Replace to the Search menu.
. . .
#define FIND_REPLACE 1
F_ObjHandleT menubarId, menuId;
/* Define menu and add a command to it. */
menuId = F_ApiDefineMenu("SearchMenu", "Search");
F_ApiDefineAndAddCommand(FIND_REPLACE, menuId, "FindReplace",
"Find and Replace", "\\!fR");
/* Put the menu on the menu bar for books. */
menubarId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"!BookMainMenu");
F_ApiAddMenuToMenu(menubarId, menuId);
. . .

See also
“F_ApiAddMenuToMenu()” on page 74, “F_ApiDefineAndAddMenu()” on page 134,
and “F_ApiGetNamedObject()” on page 214.

142

FDK Programmer’s Reference

F_ApiDelete()

...

FDK Function Reference

F_ApiDelete()
F_ApiDelete() deletes an object from a document. Be careful about possible side
effects when you use F_ApiDelete(). When you delete some objects, the API
deletes any objects they contain. For example, when you delete a table, the API deletes
all the FO_Row and FO_Cell objects that it contains. When you delete a frame, the
API deletes all the objects in it.
The following types of objects can’t be deleted with F_ApiDelete():


FO_Book



FO_Doc



FO_HiddenPage



FO_Cell



FO_MasterPage (Left and Right master pages only)



FO_UnanchoredFrame (page frames only)



FO_Color (predefined colors only)



FO_Session



FO_VarFmt (system variables only)

To delete table rows and columns, use F_ApiDeleteCols() and
F_ApiDeleteRows() instead of F_ApiDelete(). To delete a page frame, delete
the page that contains it. To delete text, see “F_ApiDeleteText()” on page 151.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiDelete(F_ObjHandleT docId,
F_ObjHandleT objId);

Arguments
docId

The ID of the document, book, or menu containing the object

objId

The ID of the object to remove

Returns
FE_Success if it succeeds, or an error code if an error occurs.

FDK Programmer’s Reference 143

3

FDK Function Reference

F_ApiDeleteAllKeyDefinitions()

If F_ApiDelete() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid object ID

FE_BadDelete

Specified object couldn’t be deleted

FE_BadOperation

Function call specified an illegal operation

FE_BadParameter

Function call specified an invalid parameter

FE_NotMenu

objId is a menu item (FO_Menu, FO_Command, or
FO_MenuItemSeparator), but docId is not the ID of the menu
containig it

Example
The following code deletes all the markers in the current document:
. . .
F_ObjHandleT docId, mrkrId, prvmrkrId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
/* Get first marker, then traverse markers and delete them. */
mrkrId = F_ApiGetId(FV_SessionId, docId, FP_FirstMarkerInDoc);
while (mrkrId)
{
/* As each marker is deleted, its FP_NextMarkerInDoc property
** becomes invalid, so it is necessary to get the next marker
** before deleting the current one.
*/
prvmrkrId = mrkrId;
mrkrId = F_ApiGetId(docId, prvmrkrId, FP_NextMarkerInDoc);
F_ApiDelete(docId, prvmrkrId);
}
. . .

F _ A p i D e l et e A l l K ey D ef i n i t i o n s ( )
Deletes all the key definitions in the specified key catalog.

144

FDK Programmer’s Reference

F_ApiDeleteCols()

...

FDK Function Reference

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiDeleteAllKeyDefinitions(F_ObjHandleT keyCatalogId)

Arguments
keyCatalogId

The ID of the key catalog from which to delete all key definitions.

Returns
If F_ApiDeleteAllKeyDefinitions() fails, the API assigns the following value
to FA_errno.
FA_errno value

Meaning

FE_BadObjId

The ID provided does not specify a key catalog.

F_ApiDeleteCols()
F_ApiDeleteCols() deletes columns from a table. To delete an entire table, use
F_ApiDelete().
Synopsis
#include "fapi.h"
. . .
IntT F_ApiDeleteCols(F_ObjHandleT docId,
F_ObjHandleT tableId,
IntT delColNum,
IntT numDelCols);

Arguments
docId

The ID of the document containing the table.

tableId

The ID of the table containing the columns.

delColNum

The first column to delete. Columns are numbered from left to right, starting
with 0.

numDelCols

The number of columns to delete.

F_ApiDeleteCols() deletes the column specified by delColNum and
(numDelCols-1) columns to the right of it.

FDK Programmer’s Reference 145

3

FDK Function Reference

F_ApiDeleteCols()

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiDeleteCols() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support requested operation

FE_BadOperation

Parameter specifies an invalid operation

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid table ID

Example
The following code deletes the first two columns in the selected table in the active
document:
. . .
F_ObjHandleT docId, tblId;
/* Get the document and table IDs. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tblId = F_ApiGetId(FV_SessionId, docId, FP_SelectedTbl);
F_ApiDeleteCols(docId, tblId, 0, 2);
. . .

See also
“F_ApiDelete()” on page 143 and “F_ApiDeleteRows()” on page 148.
St ru cture d

F_ApiDeleteCondTag()
F_ApiDeleteCondTag() deletes a conditional tag from a document.
Synopsis
#include "fapi.h"
StatusT F_ApiDeleteCondTag(F_ObjHandleT docId, F_ObjHandleT
condTagId, IntT action);

146

FDK Programmer’s Reference

F_ApiDeletePropByName()

...

FDK Function Reference

Arguments
docId

The ID of the document containing the conditional tag to be deleted

condTagId

The ID of the conditional tag object (type: FO_CondFmt) in the doc

action

One of the following:
FF_UNTAGGED_ASK: Prompt the user
FF_UNTAGGED_UNCOND: Make text unconditional
FF_UNTAGGED_DELETE: Delete text

Returns
Returns one of the following
FE_BadDocId

Document id is invalid

FE_BadObjId

Conditional tag object id is invalid.

FE_ReadOnly

Document is read only.

FE_BadValue

Action is not one of the specified values

FE_Success

Deletion was successful

F_ApiDeletePropByName()
F_ApiDeletePropByName() deletes an inset facet.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiDeletePropByName(F_ObjHandleT docId,
F_ObjHandleT objId,
StringT propName);

Arguments
docId

The ID of the document containing the inset whose facet you want to delete

objId

The ID of the inset

propName

The name of the facet you want to delete

Returns
VoidT.

FDK Programmer’s Reference 147

3

FDK Function Reference

F_ApiDeleteRows()

If F_ApiDeletePropByName() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadPropNum

Specified property number is invalid

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid object ID

FE_BadPropType

Incorrect property type for this function

Example
The following code deletes a facet called wks.facet:
. . .
F_ObjHandleT docId, insetId;
F_ApiDeletePropByName(docId, insetId, "wks.facet");
. . .

F_ApiDeleteRows()
F_ApiDeleteRows() deletes rows from a table. Like the Delete command in the
FrameMaker product user interface, F_ApiDeleteRows() does not allow you to
delete more than one type of row at time. The range of rows you specify must be all
body rows, all header rows, or all footer rows.
To delete an entire table, use F_ApiDelete().
Synopsis
#include "fapi.h"
. . .
IntT F_ApiDeleteRows(F_ObjHandleT docId,
F_ObjHandleT tableId,
F_ObjHandleT refRowId,
IntT numDelRows);

148

FDK Programmer’s Reference

F_ApiDeleteRows()

...

FDK Function Reference

Arguments
docId

The ID of the document containing the table

tableId

The ID of the table containing the rows

refRowId

The ID of the first row to delete

numDelRows

The number of rows to delete, including refRowId

F_ApiDeleteRows() deletes refRowId and (numDelRows - 1) rows below it.
Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiDeleteRows() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support the requested operation.

FE_BadOperation

Parameter specifies an invalid operation.

FE_BadDocId

Invalid document ID.

FE_BadObjId

Invalid table or row ID.

FE_OutOfRange

The refRowId parameter does not specify a row in the table, or the
specified range includes more than one type of row (for example,
header rows and body rows).

Example
The following code deletes the first row of the selected table:
. . .
F_ObjHandleT docId, tblId, rowId;
/* Get the document and selected table IDs. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tblId = F_ApiGetId(FV_SessionId, docId, FP_SelectedTbl);
/* Get the ID for the first row, then delete it. */
rowId = F_ApiGetId(docId, tblId, FP_FirstRowInTbl);
F_ApiDeleteRows(docId, tblId, rowId, 1);
. . .

FDK Programmer’s Reference 149

3

FDK Function Reference

F_ApiDeleteRows()

See also
“F_ApiDelete()” on page 143 and “F_ApiDeleteCols()” on page 145.

150

FDK Programmer’s Reference

F_ApiDeleteText()

...

FDK Function Reference

F_ApiDeleteText()
F_ApiDeleteText() deletes a specified text range from a document.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiDeleteText(F_ObjHandleT docId,
F_TextRangeT *textRangep);

Arguments
docId

The ID of the document from which to delete the text

textRangep

The text range to delete

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiDeleteText() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadDelete

Specified text couldn’t be deleted

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid object ID

FE_BadRange

Specified text range is invalid

FE_NotTextObject

Object specified for the text range isn’t an object that
contains text, for example, a text frame (FO_TextFrame),
a paragraph (FO_Pgf) or a text line (FO_TextLine)

FE_OffsetNotFound

Offset specified for the text range couldn’t be found in the
specified paragraph or text line

FE_BadSelectionForOpe
ration

Selection is within a locked text range.

FDK Programmer’s Reference 151

3

FDK Function Reference

F_ApiDeleteTextInsetContents()

Example
The following code gets the text selection from the active document and deletes it:
. . .
F_TextRangeT tr;
F_ObjHandleT docId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId,docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
F_ApiDeleteText(docId, &tr);
. . .

See also
“F_ApiClear()” on page 100 and “F_ApiAddText()” on page 80.

F_ A p i D e l e t e TextInsetC onten ts()
F_ApiDeleteTextInsetContents() deletes the text in a text inset. You must
unlock a text inset before you call F_ApiDeleteTextInsetContents() to delete
its contents. After you are done, you must relock the text inset.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiDeleteTextInsetContents(F_ObjHandleT docId,
F_ObjHandleT insetId);

Arguments
docId

The ID of the document containing the inset

insetId

The text inset containing the text to be deleted

Returns
FE_Success if it succeeds, or an error code if an error occurs.

152

FDK Programmer’s Reference

F_ApiDeleteTextInsetContents()

...

FDK Function Reference

If F_ApiDeleteTextInsetContents() fails, the API assigns one of the
following values to FA_errno.
FA_errno value

Meaning

FE_BadDelete

Specified text couldn’t be deleted

FE_BadDocId

Invalid document ID

FE_BadObjId

The ID does not specify a text inset

FE_BadSelectionForOperation

The specified text inset is locked

Example
See “Updating a client text inset” on page 469 of the FDK Programmer’s Guide.
See also
“F_ApiDelete()” on page 143.
St ru cture d

F_ApiDeleteUndefinedAttribute()
F_ApiDeleteUndefinedAttribute() deletes from structural elements, an
attribute for which no value is assigned. You can delete undefined attributes for a given
element, all elements of a specific type, or all elements in the document.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiDeleteUndefinedAttribute(F_ObjHandleT docId,
StringT attrName, IntT scope, F_ObjHandleT objId);

Arguments
docId

The ID of the document containing the element or elements whose attributes
you want to delete

attrName

The name of the attribute you want to delete

scope

One of FV_Element, FV_ElementsOfType, or FV_AllElements

objId

The element or element definition from which to delete the undefined attributes

The value for objId indicates a different type of object, depending on the value of
scope, as indicated by the following table:

FDK Programmer’s Reference 153

3

FDK Function Reference

F_ApiDeleteTextInsetContents()

If scope is:

objId must be:

FV_Element

The ID of the element from which you want to delete the
undefined attribute

FV_ElementsOfType

The element definition for the type of element from which you
want to delete the undefined attributes

FV_AllElements

0

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiDeleteUndefinedAttribute() fails, the API assigns one of the
following values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid object ID

FE_AttributeNot
Undefined

Specified attribute in specified element contains a value

Example
The following code deletes all undefined instances of the attribute named “author” in
the document:
. . .
F_ObjHandleT docId;
ErrorT err;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);

err = F_ApiDeleteUndefinedAttribute(docId, (StringT)"author",
FV_AllElements, 0);
. . .

St ru cture d

F_ApiDemoteElement()
F_ApiDemoteElement() demotes the selected structural element or elements. The
element becomes a child of the sibling element before it.

154

FDK Programmer’s Reference

F_ApiDialogEvent()

...

FDK Function Reference

..............................................................................

IMPORTANT: At least one structural element must be selected when
F_ApiDemoteElement() is called.

..............................................................................

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiDemoteElement(F_ObjHandleT docId);

Arguments
docId

The document that contains the element selection

Returns
VoidT.
If F_ApiDemoteElement() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product isn’t Structured
FrameMaker

FE_BadDocId

Invalid document ID

FE_BadSelectionForOperation

Current text selection is invalid for this operation

Example
The following code demotes the selected elements in the active document:
. . .
F_ApiDemoteElement(F_ApiGetId(0, FV_SessionId, FP_ActiveDoc));
. . .

See also
“F_ApiPromoteElement()” on page 377.

F _ A p i D i a l o g E ve n t ( )
F_ApiDialogEvent() is a callback that you can define in your client. The
FrameMaker product calls F_ApiDialogEvent() when an event occurs in a dialog
box opened by your client.
FDK Programmer’s Reference 155

3

FDK Function Reference

F_ApiDialogEvent()

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiDialogEvent(IntT dlgNum,
IntT itemNum,
IntT modifiers);

Arguments
dlgNum

The number of the dialog in which the event occurred (the number you
specified when you called F_ApiModalDialog() or
F_ApiModelessDialog() to display the dialog)

itemNum

If an event occurred in a specific dialog item, the number (a nonnegative
integer) of the dialog item.
If the event doesn’t apply to a specific dialog item, a negative integer
constant specifying the event. See the table below for a list of constants.

modifiers

Bit flags specifying which modifier keys the user was holding down when
the event occurred. See the table below for a list of possible flags.

The API can set the itemNum parameter function to the ID of a dialog item or to one
of the following negative constants:

156

Constant

Meaning

FV_DlgClose

The user closed the dialog box.

FV_DlgEnter

The user moved input focus to the dialog box.

FV_DlgNoChange

The user pressed Shift-F8 to set the dialog box to As Is settings.

FDK Programmer’s Reference

F_ApiDialogEvent()

Constant

Meaning

FV_DlgReset

The user pressed Shift-F9 to reset the dialog box.

FV_DlgResize

A modeless dialog was resized. Here is a usage example:

...

FDK Function Reference

VoidT F_ApiDialogEvent(IntT dlgNum, IntT itemNum,
IntT modifiers)
{
switch(dlgNum)
{
case DLG_NUM1:
{
If
(itemNum == FV_DlgResize)
{
/* 'dlgNum' dialog has been resized - do something
if needed */
}
}
break;
}
}

The modifiers parameter can have the following bit flags set:
Flag

Meaning

FV_EvCaps

The Caps Lock key is on

FV_EvControl

The user was holding down the Control key

FV_EvMeta

The user was holding down the the Alt key (on Windows)

FV_EvShift

The user was holding down the Shift key

Returns
VoidT.

FDK Programmer’s Reference 157

3

FDK Function Reference

F_ApiDialogItemId()

Example
See “Handling user actions in dialog boxes” on page 448 of the FDK Programmer’s
Guide.

See also
“F_ApiDialogItemId()” on page 158.

F_ A p i D i a l o g ItemId()
F_ApiDialogItemId() returns the ID of a dialog item with a specified item number.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiDialogItemId(F_ObjHandleT dialogId,
IntT itemNum);

Arguments
dialogId

The ID of the dialog box containing the item

itemNum

The item number of the item

Returns
The ID of the item with the specified number or 0 if there is no item with the specified
number.
Example
The following code gets the ID of the dialog with the number APPLY_BUTTON.
. . .
#define APPLY_BUTTON 1
F_ObjHandleT dlgId, dlgItemId;
. . .
dlgItemId = F_ApiDialogItemId(dlgId, APPLY_BUTTON);
. . .

See also
“F_ApiDialogEvent()” on page 155.

158

FDK Programmer’s Reference

F_ApiDisconnectFromSession()

...

FDK Function Reference

F_Api Di s conn ect FromS ession( )
F_ApiDisconnectFromSession() ends communication with a FrameMaker
product process.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiDisconnectFromSession();

Arguments
None.
Returns
FE_Success if it succeeds, or a system error code if an error occurs.
See also
“” on page 173, “F_ApiConnectToSession()” on page 115
St ru cture d

F _ A p i E l e me n tD e fI s Tex t ()
Some structural elements in FrameMaker documents are placeholders for text. For
example, when a Para element contains text with a cross-reference element embedded
in it, the ranges of text that surround the cross-reference element are treated as elements
themselves. These elements are called text nodes.
When you are traversing the elements in a container, it is often useful to know if a given
element is a text node. F_ApiElementDefIsText() checks the value of an element
definition to determine whether the element it is applied to is a text node.
F_ApiElementDefIsText() is implemented as a macro.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiElementDefIsText(F_ObjHandleT docId,
F_ObjHandleT objId);

FDK Programmer’s Reference 159

3

FDK Function Reference

F_ApiDisconnectFromSession()

Arguments
docId

The ID of the document containing the element definition

objId

The ID of the element definition (FO_ElementDef)

Returns
True if the element definition corresponds to that of a text node, or False if it
doesn’t.
Example
The following code displays an alert if an element is a text node:
. . .
F_ObjHandleT edefId, objId;
. . .
if (F_ApiElementDefIsText(docId, edefId))
F_ApiAlert("Element is text node.", FF_ALERT_CONTINUE_NOTE);
. . .

St ru cture d

F _ A p i E l e me n tL o c To Te x t L o c ()
F_ApiElementLocToTextLoc() returns the text location structure that corresponds
with the current element location.
Synopsis
#include "fapi.h"
. . .
F_TextLocT F_ApiElementLocToTextLoc (F_ObjHandleT docId,
const F_ElementLocT *elocp);

160

FDK Programmer’s Reference

F_ApiDisconnectFromSession()

...

FDK Function Reference

Arguments
docId

The ID of the document containing the element

elocp

The element location structure to convert

Returns
An F_TextLocT structure specifying a text location. The F_TextLocT structure is
defined as:
typedef struct{
F_ObjHandleT objId; /* Object containing text */
IntT offset; /* Characters from start of object */
} F_TextLocT;

If F_ApiElementLocToTextLoc() fails, the API assigns one of the following
values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadParameter

elocp was empty or a parameter was improperly specified

FE_WrongProduct

Current FrameMaker product doesn’t support the operation

FDK Programmer’s Reference 161

3

FDK Function Reference

F_ApiEnableUnicode()

Example
The following code converts an element location to a text location and gets the name of
the paragraph format for the text location:
. . .
F_ObjHandleT docId;
F_ElementRangeT eRange;
F_ElementLocT eloc;
F_TextLocT textLoc;
StringT paraTag;
. . .
eRange = F_ApiGetElementRange(FV_SessionId, docId,
FP_ElementSelection);
eloc = eRange.beg;
textLoc = F_ApiElementLocToTextLoc (docId, &eloc);
if (F_ApiGetObjectType(docId, textLoc.objId) == FO_Pgf)
paraTag = F_ApiGetString(docId, textLoc.objId, FP_Name);
. . .

See also
“F_ApiTextLocToElementLoc()” on page 473.

F_ApiEnableUnicode()
Used to enable Unicode Mode or Compatibility Mode.
Synopsis
#include "fapi.h"
...
VoidT F_ApiEnableUnicode(BoolT enable);

Arguments
enable

True enables Unicode Mode, False enables Compatibility Mode.
Default: False

Returns
VoidT
162

FDK Programmer’s Reference

F_ApiEnableUnicode()

...

FDK Function Reference

Example
The following example creates two alerts.
The first one shows the string "This will be treated as FrameRoman on
English locale: Ч ÎƧ ÿ¥" on an English locale.
The second one shows the string "This will be treated as Unicode on
every locale: ä 뮤 ‫ ش‬." on any locale.
#include "fencode.h"
. . .
F_ApiAlert("This will be treated as FrameRoman on English
locale:
\xC3\xA4 \xEB\xAE\xA4 \xD8\xB4",
FF_ALERT_CONTINUE_NOTE);

F_ApiEnableUnicode(True);
F_ApiAlert("This will be treated as Unicode on every locale:
\xC3\xA4
\xEB\xAE\xA4 \xD8\xB4",
FF_ALERT_CONTINUE_NOTE);
. . .

FDK Programmer’s Reference 163

3

FDK Function Reference

F_ApiErr()

F_ApiErr()
F_ApiErr() prints your client’s name and a message to the console.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiErr(StringT message);

Arguments
message

The message to print

Returns
VoidT.
Example
The following code prints the message Frame API client "myclient":
There’s been a problem with this client. when a problem occurs with
the client:
. . .
F_ApiErr("There’s been a problem with this client.\n");
. . .

164

FDK Programmer’s Reference

F_ApiFamilyFonts()

...

FDK Function Reference

F_ApiFamilyFonts()
F_ApiFamilyFonts() returns the permutations of angles, variations, and weights
available for a specified font family.
..............................................................................

IMPORTANT: To return the permutations of a combined font, you must use
F_ApiCombinedFamilyFonts(). For more information, see
“F_ApiCombinedFamilyFonts()” on page 109.

..............................................................................

Synopsis
#include "fapi.h"
. . .
F_FontsT F_ApiFamilyFonts(IntT family);

Arguments
family

The index of the font family (in the list of fonts in the session)

To get the list of font families, angles, variations, or weights in the current FrameMaker
product session, use F_ApiGetStrings(). For more information, see
“F_ApiGetStrings()” on page 242.
Returns
An F_FontsT structure providing a list of the permutations of angles, variations, and
weights available for the specified font family.
F_FontsT is defined as:
typedef struct {
UIntT len; /* The number of structures referenced by val.*/
F_FontT *val; /* Structures listing the permutations. */
} F_FontsT;

F_FontT is defined as:
typedef struct {
UIntT family; /* The index of the font family name. */
UIntT variation; /* The index of the variation name. */
UIntT weight; /* The index of the weight name. */
UIntT angle; /* The index of the angle name. */
} F_FontT;

FDK Programmer’s Reference 165

3

FDK Function Reference

F_ApiFamilyFonts()

Example
The following code prints the variations, weights, and angles available for Helvetica in
the current session:
. . .
#include "futils.h"
#include "fstrings.h"
. . .
UIntT i, j;
F_StringsT families, weights, variations, angles;
F_FontsT perms;
/* 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);
/* Get the index for Helvetica. */
for (i=0; i < families.len; i++)
if(F_StrIEqual(families.val[i], "helvetica")) break;
if (i == families.len) return; /* Helvetica not found. */
/* Get the permutations and print them to the console. */
perms = F_ApiFamilyFonts(i);
for (j=0; j < perms.len; j++)
{
F_Printf(NULL, "Variation: %s, Weight: %s, Angle: %s\n",
weights.val[perms.val[j].variation],
variations.val[perms.val[j].weight],
angles.val[perms.val[j].angle]);
}
/* Free the structures and strings. */
F_ApiDeallocateFonts(&perms);
F_ApiDeallocateStrings(&families);
F_ApiDeallocateStrings(&weights);
F_ApiDeallocateStrings(&variations);
F_ApiDeallocateStrings(&angles);
. . .

166

FDK Programmer’s Reference

F_ApiFcodes()

...

FDK Function Reference

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. When you use F_ApiFcodes() to send an array of
f-codes to the FrameMaker product, it executes each f-code as if the user performed the
action.
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 (or has focus).
Synopsis
#include "fapi.h"
. . .
IntT F_ApiFcodes(IntT len,
IntT* vec);

Arguments
len

The length of the array of f-codes

vec

The array of f-codes to send to the FrameMaker product

For a complete list of f-codes, see the fcodes.h file shipped with the FDK. To use
FDK-defined f-code constants, such as KBD_RETURN, include this file in your client.

FDK Programmer’s Reference 167

3

FDK Function Reference

F_ApiFind()

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiFcodes() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

Example
The following code executes f-codes to move the cursor down one line and move the
current document window to the back:
. . .
#include "fm_commands.h"
. . .
static IntT fcodes[] = {CSR_DOWN, KBD_HIDEWIN};
F_ApiFcodes(sizeof(fcodes)/sizeof(IntT), fcodes);
. . .

F_ApiFind()
F_ApiFind() performs the same actions as using the Find dialog box to search a
document for text or other types of content.
Synopsis
#include "fapi.h"
. . .
F_TextRangeT F_ApiFind(F_ObjHandleT docId,
const F_TextLocT *textLocp,
const F_PropValsT *findParamsp);

Arguments
docId

The ID of the document to search.

textLocp

The text location to begin searching from.

findParamsp

A property list that specifies what to search for.

The findParamsp parameter points to a property list that contains:

168

FDK Programmer’s Reference

F_ApiFind()

...

FDK Function Reference



FS_FindCustomizationFlags, an optional property you can use to customize
the search.



One of a list of a list of properties that specify what type of content to search for; text,
elements, character formats, etc. You must specify one of these properties.

The properties you can assign to findParamsp are:
Property

Meaning and possible values

FS_FindCustomizationFlags

An optional parameter of type FT_Integer that may
be any of the following bit flags OR’ed together:

FF_FIND_CONSIDER_CASE,
FF_FIND_WHOLE_WORD,
FF_FIND_USE_WILDCARDS,
FF_FIND_BACKWARDS
If no customization flags are specified the default is to
search forward, to not use wildcards, to not consider
case, and to not use whole words.
FS_FindWrap

A BoolT flag that determines whether the find
operation will wrap when it reaches the location
where the search began. Default is True; the find
operations wraps.
If False, after reaching the location where the search
began, the find operation returns an empty
F_TextRangeT and FA_errno is set to
FE_NotFound.

FS_FindText

FT_String search text

FS_FindElementTag

FT_Strings as follows:
propVal.u.ssval.len =
FV_NumFindElementItems;
propVal.u.ssval.val[FV_FindElemTag
] = [an_element_tag];
propVal.u.ssval.val[FV_FindAttrNam
e]= [an_attribute_name];
propVal.u.ssval.val[FV_FindAttrVal
ue] = [an_attribute_value];
All of the strings must be present, but any or all may
be empty

FDK Programmer’s Reference 169

3

FDK Function Reference

F_ApiFind()

Property

FS_FindCharFmt

Meaning and possible values

No associated propertya. One or more of the
following additional properties should be specified to
tailor the search

FP_FontFamily
FP_CombinedFont
FP_FontSize
FP_FontAngle
FP_FontWeight
FP_FontVariation
FP_Color
FP_Spread
FP_Stretch
FP_Language
FP_Underline
FP_Overline
FP_Strikethrough
FP_ChangeBar
FP_Capitalization
FP_Position
FP_Tsumeb

170

FS_FindPgfTag

FT_String paragraph tag

FS_FindCharTag

FT_String character tag

FS_FindTableTag

FT_String table tag

FS_FindObject

FV_FindAnyMarker
FV_FindAnyXRef
FV_FindUnresolvedXRef
FV_FindAnyTextInset
FV_FindUnresolvedTextInset
FV_FindAnyPub
FV_FindAnyVariable
FV_FindAnchoredFrame
FV_FindFootnote
FV_FindAnyTable
FV_FindAutomaticHyphen
FV_FindAnyRubi

FS_FindMarkerOfType

FT_String marker type

FS_FindMarkerText

FT_String marker text

FS_FindXRefWithFormat

FT_String format

FS_FindNamedVariable

FT_String variable name

FDK Programmer’s Reference

F_ApiFind()

Property

Meaning and possible values

FS_FindCondTextInCondTags

FT_Strings condition tags

FS_FindCondTextNotInCond
Tags

FT_Strings condition tag

...

FDK Function Reference

a. Actually including a FS_FindCharFmt property is not required; when
FrameMaker sees one of the text properties it assumes the client is
searching for a character format.
b. See the FDK Programmer’s Reference for a description of these properties
and their values.
Whenever this function finds something that corresponds to a text range (a word, object
anchor, marker, etc.), it returns an F_TextRangeT structure for that range. However,
when searching for structure elements, you can find elements that have no
corresponding text range.
Structure elements for the following table parts have no corresponding text range:


Table title



Table head



Table foot



Table body



Table row



Table cell

When you find a structure element for one of these objects, F_ApiFind() returns an
empty F_TextRangeT structure and FA_errno is set to FE_Success. In this case,
you can get the document’s FP_ElementSelection property to return a
corresponding F_ElementRangeT structure for the table part structure element.
Returns
When it finds anything other than structure elements for table parts, an F_TextRangeT
structure. When it finds structure elements for table parts, an empty F_TextRangeT
structure, and FA_errno is set to FE_Success.

FDK Programmer’s Reference 171

3

FDK Function Reference

F_ApiFind()

If F_ApiFind() fails, an empty text range is returned and FA_errno is set to one of
the following values.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadParameter

findParamsp was empty or a parameter was
improperly specified

172

FE_BadInsertPos

The textLocp was not valid

FE_NotTextObject

The textLocp was not a text location

FDK Programmer’s Reference

F_ApiFind()

...

FDK Function Reference

Example
The following code searches the specified document from the beginning of the current
selection for the first occurrence of a text string:
. . .
F_ObjHandleT docId;
F_PropValsT findParams;
F_TextRangeT trSel, trFound;
StringT searchString = (StringT)"findme";

/* Assuming a document has been attached to a window... */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
if (docId == 0)
return;

/* Set ‘trSel’ to the text range of the selection */
trSel = F_ApiGetTextRange(FV_SessionId, docId,
FP_TextSelection);
if (trSel.beg.objId == 0 && trSel.end.objId == 0)
return;

/* Allocate and initialize ‘findParams’ */
findParams = F_ApiAllocatePropVals(1);
findParams.val[0].propIdent.num = FS_FindText;
findParams.val[0].propVal.valType = FT_String;
findParams.val[0].propVal.u.sval =
F_StrCopyString(searchString);

/* Perform the text string search */
trFound = F_ApiFind(docId, &trSel.beg, &findParams);

/* Free the F_PropValsT structures */
F_ApiDeallocatePropVals(&findParams);
. . .

FDK Programmer’s Reference 173

3

174

FDK Function Reference

F_ApiFind()

FDK Programmer’s Reference

F_ApiGetAllKeyDefinitions()

2

...

FDK Function Reference

FDK Function Reference

F_ApiGetAllKeyDefinition s()
F_ApiGetAllKeyDefinitions() gets all the key definitions from the specified key
catalog.
Synopsis
#include "fapi.h"
. . .
F_TypedValsT F_ApiGetAllKeyDefinitions(F_ObjHandleT
keyCatalogId, IntT filterType)

Arguments
keyCatalogId

The ID of the key catalog from which to get the key definitons.

filterType

Specifies the type of key fields to get for each key definition.
flterType can have the following values:


FV_KeyDefFieldsTypePrimary:
Gets only the primary key fields (Tag, Target, SrcFile, and
Duplicate)



FV_KeyDefFieldsTypeAll:
Gets all key fields.

Returns
Returns the information in an F_TypedValsT structure as follows: FieldTag is of
type FT_Integer. FieldValue is of type as specified in the table below. .
FieldTag value

FieldValue type

FV_KeydefKeyAttrs

FT_AttributesEx

FV_KeydefKeyDefaultText

FT_String

FV_KeydefKeyDuplicate

FT_Integer

FV_KeydefKeyFoundInRefFile

FT_Integer

FV_KeydefKeyInValid

FT_Integer

FV_KeydefKeySrcFile

FT_String

FV_KeydefKeySrcType

FT_Integer

FV_KeydefKeyTag

FT_String

FV_KeydefKeyTarget

FT_String

FV_KeydefKeyVarList

FT_Vals
FDK Programmer’s Reference 175

4

FDK Function Reference

F_ApiGetAllKeyDefinitions()

If F_ApiGetAllKeyDefinitions() fails, the API assigns one of the following
values to FA_errno.

St ru cture d

FA_errno value

Meaning

FE_BadObjId

The ID provided does not specify a key catalog.

FE_KeyCatalogNotLoaded

The key catalog provided is currently not loaded.

FE_KeyCatalogIsStale

The key catalog provided is currently marked as stale
and needs to be re-loaded before using.

FE_BadFilterType

The filter type provided is not valid.

F_ApiGetAttributeDefs( )
F_ApiGetAttributeDefs() gets an element definition’s attribute definitions.
Synopsis
#include "fapi.h"
. . .
F_AttributeDefsT F_ApiGetAttributeDefs(
F_ObjHandleT docId,
F_ObjHandleT elemDefId);

Arguments
docId

The ID of the document or book containing the element definition

elemDefId

The ID of the element definition for which to get attribute definitions

Returns
An F_AttributeDefsT structure specifying the attribute definitions. The
F_AttributeDefsT structure is defined as:
typedef struct {
UIntT len;
F_AttributeDefT *val;
} F_AttributeDefsT;

176

FDK Programmer’s Reference

F_ApiGetAllKeyDefinitions()

...

FDK Function Reference

The F_AttributeDefT structure describes an attribute definition. It is defined as:
typedef struct {
StringT name; /* The attribute name. */
BoolT required; /* True if the attribute is required. */
BoolT readOnly; /* True if the attribute is read only. */
IntT attrType; /* The attribute type. See following table. */
F_StringsT choices;/* Choices if attrType is FV_AT_CHOICES.*/
F_StringsT defValues;/* The default if the attribute is not
** required. If attrType is
** FV_AT_REALS, FV_AT_STRINGS, etc,
** the default can have multiple strings.
*/
StringT rangeMin; /* The minimum allowed value (if any). */
StringT rangeMax; /* The maximum allowed value (if any). */
} F_AttributeDefT;

The F_AttributeDefT.attrType field identifies the attribute value’s type. It can
specify one of the following constants.
attrType constant

Attribute value type

FV_AT_STRING

Any arbitrary text string

FV_AT_STRINGS

One or more arbitrary text strings

FV_AT_CHOICES

A value from a list of choices

FV_AT_INTEGER

A signed whole number (optionally restricted to a range of
values)

FV_AT_INTEGERS

One or more integers (optionally restricted to a range of
values)

FV_AT_REAL

A real number (optionally restricted to a range of values)

FV_AT_REALS

One or more real numbers (optionally restricted to a range of
values)

FV_AT_UNIQUE_ID

A string that uniquely identifies the element

FV_AT_UNIQUE_IDREF

A reference to a UniqueID attribute

FV_AT_UNIQUE_IDREFS

One or more references to UniqueID attributes

FDK Programmer’s Reference 177

4

FDK Function Reference

F_ApiGetAllKeyDefinitions()

If F_ApiGetAttributeDefs() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_WrongProduct

The current FrameMaker product doesn’t support the
requested operation.

FE_BadObjId

Invalid object ID

Example
The following code gets the attribute definitions from the Chapter element definition
and prints the names of the required attributes:
. . .
F_ObjHandleT docId, edefId;
F_AttributeDefsT attributeDefs;
UIntT i;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
edefId = F_ApiGetNamedObject(docId, FO_ElementDef, "Chapter");
attributeDefs = F_ApiGetAttributeDefs(docId, edefId);
for(i=0; i0)
{
/* Code to do something with aUBytes goes here. */
}
} while (n > 0);
F_ApiGetIntByName(docId, insetId, ""); /* Commit transaction. */
F_ApiDeallocateUBytes(&aUBytes);
. . .

See also
F_ApiSetUBytesByName().

F_ApiGetUniqueObject()
F_ApiGetUniqueObject() gets the ID of an object from its persistent unique
identifier (UID). FrameMaker products assign a UID to each object in a document or
book that isn’t identified by a name. The UID, unlike the object’s ID, does not change
from one session to another.
..............................................................................

IMPORTANT: When you copy an object to the clipboard and paste it, the FrameMaker
product changes the UID. This also happens when you hide and show conditional text.
..............................................................................

Synopsis
F_ObjHandleT F_ApiGetUniqueObject(F_ObjHandleT docId,
IntT objType,
IntT unique);

FDK Programmer’s Reference 275

4

FDK Function Reference

F_ApiGetUniqueObject()

Arguments
docId

The ID of the document containing the object

objType

The type of object (for example, FO_Pgf)

unique

The object’s UID

Returns
The ID of the object, or 0 if an error occurs.
If F_ApiGetUniqueObject() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_TypeUnNamed

Objects of the specified type aren’t identified by UIDs

FE_NameNotFound

Object with specified UID couldn’t be found

Example
The following code will build a client gets and saves the location of the current insertion
point (or the beginning of the current text selection) when the user chooses a menu item
named Save Position. If the user subsequently chooses the Return to Previous Position
menu item, the client scrolls to the saved insertion point, even if the document has been
exited and reopened in the meantime.

276

FDK Programmer’s Reference

F_ApiGetUniqueObject()

...

FDK Function Reference

#include "fapi.h"
#define SAVE 1
#define LAST 2
IntT pgfUID;
F_TextRangeT tr;
VoidT F_ApiInitialize(initialization)
IntT initialization;
{
F_ObjHandleT menuBarId, menuId;
menuBarId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"!MakerMainMenu");
menuId = F_ApiDefineAndAddMenu(menuBarId, "APIMenu", "API");
F_ApiDefineAndAddCommand(SAVE, menuId,"SaveLastPosCmd",
"Save position","");
F_ApiDefineAndAddCommand(LAST, menuId,"ReturnToLastPosCmd",
"Return to previous position","");
}
VoidT F_ApiCommand(command)
IntT command;
{
F_ObjHandleT docId, pgfId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
switch(command)
{
case SAVE: /* Get and save the insertion point. */
tr = F_ApiGetTextRange(FV_SessionId, docId,
FP_TextSelection);
if (!tr.beg.objId) return;
/* Get UID of paragraph containing insertion point.*/
pgfUID = F_ApiGetInt(docId, tr.beg.objId, FP_Unique);
break;

FDK Programmer’s Reference 277

4

FDK Function Reference

F_ApiGetUpdateBookDefaultParams()

case LAST: /* Scroll to saved insertion point. */
if (!pgfUID) break; /* Break if no insertion point. */
/* Get paragraph ID from its UID. Then scroll to it. */
pgfId = F_ApiGetUniqueObject(docId, FO_Pgf, pgfUID);
tr.beg.objId = tr.end.objId = pgfId;
F_ApiScrollToText(docId, &tr);
}
}

See also
F_ApiGetNamedObject().

F_ApiGetUpdateBookDefaultParams()
F_ApiGetUpdateBookDefaultParams() gets a default property list that you can
use to call F_ApiUpdateBook().
Synopsis
#include "fapi.h"
. . .
F_PropValsT F_ApiGetUpdateBookDefaultParams();

Arguments
None.
Returns
A property list (an F_PropValsT data structure) with the properties shown in the
following table. The first value listed by each property is the value that
F_ApiGetUpdateBookDefaultParams() assigns to the property. The other
values are values you can set the property to.
F_ApiGetUpdateBookDefault
Params() property

Instruction or situation and possible values

FS_AlertUserAboutFailure

Alert user with warnings and messages if necessary.
False: don’t notify user when unexpected conditions
occur.
True: notify user when unexpected conditions occur.

278

FDK Programmer’s Reference

F_ApiGetUpdateBookDefaultParams()

F_ApiGetUpdateBookDefault
Params() property

FS_AllowInconsistentNum
Props

...

FDK Function Reference

Instruction or situation and possible values

Allow the FrameMaker product to update numbering,
text insets, etc. of all the FrameMaker documents in
the book, even if there are documents in the book with
numbering properties that don’t match the properties
specified in the book.
FV_DoOK: update numbering even if there are
inconsistent properties in the book
FV_DoCancel: cancel the update operation when it
encounters a document with inconsistent numbering
properties
FV_DoShowDialog: show dialog box and let user
decide

FS_AllowNonFMFiles

Allow the FrameMaker product to update numbering,
text insets, etc. of all the FrameMaker documents in
the book, even if there are documents in the book that
were not created by a FrameMaker product.
FV_DoOK: update the book even if the book contains
files not created by a FrameMaker product
FV_DoCancel: cancel the update operation when it
encounters a document not created by a FrameMaker
product
FV_DoShowDialog: show dialog box and let user
decide

FS_AllowViewOnlyFiles

Allow the FrameMaker product to update view-only
documents in the book.
FV_DoOK: update the view-only documents
FV_DoCancel: cancel the entire update operation
when it encounters a view-only document
FV_DoShowDialog: show dialog box and let user
decide

FS_MakeVisible

Make newly generated files (lists and indexes) visible.
True: make visible
False: don’t make visible

FS_NumExportParams

The available number of properties in the export script
that user can set.

FS_NumExportReturnParams

The number of parameters returned by the export
script.

FDK Programmer’s Reference 279

4

FDK Function Reference

F_ApiGetUpdateBookDefaultParams()

F_ApiGetUpdateBookDefault
Params() property

Instruction or situation and possible values

FS_ShowBookErrorLog

Display the book error log for this update operation.
False: don’t display the error log; all warnings and
errors go to the console
True: display the error log

FS_UpdateBookGenerated
Files

Update generated files such as TOC, lists, and indexes.
Only update those generated files that have
FP_GenerateInclude set to True in their
associated FO_BookComponent objects.
True: update generated files
False: don’t update generated files

FS_UpdateBookNumbering

Update numbering in all the book’s documents.
True: update numbering
False: don’t update numbering

FS_UpdateBookOleLinks

Update OLE links in all the book’s documents.
True: update OLE links
False: don’t update OLE links

FS_UpdateBookText
References

Update text insets in all the book’s documents.
True: update text insets
False: don’t update text insets

FS_UpdateBookXRefs

Update cross-references in all the book’s documents.
True: update cross-references
False: don’t update cross-references

..............................................................................

IMPORTANT: The returned F_PropValsT structure references memory that is
allocated by the API. Use F_ApiDeallocatePropVals() to free this memory when
you are done with it.
..............................................................................

If F_ApiGetOpenDefaultParams() fails, the API sets the len field of the
returned structure to 0.

280

FDK Programmer’s Reference

F_ApiGetUpdateBookDefaultParams()

...

FDK Function Reference

Example
The following code gets a default Update Book script with
F_ApiGetUpdateBookDefaultParams(). It modifies the script to instruct the
FrameMaker product to prompt the user if the book contains non-FrameMaker files. It
then uses the script to call F_ApiUpdateBook().

. . .
IntT i;
F_PropValsT script, *returnp = NULL;
F_ObjHandleT bookId;
bookId = F_ApiGetId(0, FV_SessionId, FP_ActiveBook);
if(!bookId)
return;
/* Get default property list. */
script = F_ApiGetUpdateBookDefaultParams();
/* Get indexes of properties and change them. */
i = F_ApiGetPropIndex(&script, FS_AlertUserAboutFailure);
script.val[i].propVal.u.ival = True;
i = F_ApiGetPropIndex(&script, FS_AllowNonFMFiles);
script.val[i].propVal.u.ival = FV_DoShowDialog;
/* Update the book */
F_ApiUpdateBook(bookId, &script, &returnp);
/* Free memory used by Update Book scripts. */
F_ApiDeallocatePropVals(&script);
F_ApiDeallocatePropVals(returnp);
. . .

See also
F_ApiUpdateBook().

FDK Programmer’s Reference 281

4

FDK Function Reference

F_ApiGetVal()

F_ApiGetVal()
F_ApiGetVal() queries a property of any type. If you know a property’s type, it is
normally easier to get its value by calling an F_ApiGet
() function,
such as F_ApiGetInt().
Synopsis
F_TypedValT F_ApiGetVal(F_ObjHandleT docId,
F_ObjHandleT objId,
IntT propNum);

Arguments
docId

The ID of the document, book, or session containing the object whose property
you want to query. 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. Specify an API-defined constant, such as FP_FnNum.

Returns
The F_TypedValT structure for the specified property.
If F_ApiGetVal() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid object ID

FE_BadPropNum

Specified property number is invalid

FE_BadPropType

Incorrect property type for this function

FE_WrongProduct

Current FrameMaker product doesn’t support the operation

Example
The following code prints the name of the current FrameMaker product:
. . .
F_TypedValT val;
val = F_ApiGetVal(FV_SessionId, FV_SessionId, FP_ProductName);
F_Printf(NULL,"The product name is %s.\n", val.u.sval);
. . .

282

FDK Programmer’s Reference

F_ApiGetVal()

...

FDK Function Reference

See also
F_ApiDeallocateStructureType() and F_ApiGetProps().

FDK Programmer’s Reference 283

4

284

FDK Function Reference

F_ApiGetVal()

FDK Programmer’s Reference

F_ApiHypertextCommand()

2

...

FDK Function Reference

FDK Function Reference

F_ApiHypertextCommand()
F_ApiHypertextCommand() simulates a user-invoked hypertext command. Calling
F_ApiHypertextCommand() has the same effect as a user clicking on a hypertext
marker containing the specified text.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiHypertextCommand(F_ObjHandleT docId,
StringT hypertext);

Arguments
docId

The ID of the document that you want to act as the source of the hypertext
command.

hypertext

A hypertext command to execute, such as gotolink or previouslink.
You can specify any command that would be valid in a hypertext marker in
the document specified by docId.

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiHypertextCommand() fails, the API assigns the following value to
FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

Example
The following code executes a hypertext command to return to the previous hypertext
link:
. . .
F_ObjHandleT docId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
F_ApiHypertextCommand(docId, "previouslink");
. . .
FDK Programmer’s Reference 285

2

FDK Function Reference

F_ApiImport()

F_ApiImport()
F_ApiImport() imports text or graphics into a document.
F_ApiImport() allows you to specify a script (property list) telling the FrameMaker
product how to import text or graphics and how to deal with error and warning
conditions. For example, you can specify whether to import a file by reference or by
copy.
If you import a file by reference, F_ApiImport() creates an inset. The following
table summarizes the types of files you can import with F_ApiImport() and the
types of inset objects it creates when you import them by reference.
File type

Type of inset object F_ApiImport() creates

Graphics

FO_Inset

Text

FO_TiText
FO_TiTextTable

Frame binary document

FO_TiFlow

MIF

FO_TiFlow

When importing a graphic, you can specify that it be imported at its default resolution
by setting the FS_GraphicDpi property to 0 and setting the
FS_FitGraphicInSelectedRect property to False. If the graphic has no default
resolution, it is imported at 72 dpi.
For graphic objects, FrameMaker automatically determines whether the object-path is a
local path or an HTTP path and acts accordingly.For example, if the path is an HTTP
path, the object is downloaded before importing it in the file.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiImport(F_ObjHandleT enclosingDocId,
F_TextLocT *textLocP,
StringT filename,
F_PropValsT *importParamsp,
F_PropValsT **importReturnParamspp);

286

FDK Programmer’s Reference

F_ApiImport()

...

FDK Function Reference

Arguments
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().

..............................................................................

IMPORTANT: Always initialize the pointer to the property list that you specify for
importReturnParamspp to NULL before you call F_ApiImport().
..............................................................................

To get a property list to specify for the importParamsp parameter, use
F_ApiGetImportDefaultParams() or create the list from scratch. For a list of all
the properties an Import script property list can include, see
“F_ApiGetImportDefaultParams()” on page 193.
Returns
The ID of the inset that F_ApiImport() creates. Or 0 if F_ApiImport() imports
by copy or creates a graphic inset.
If F_ApiImport() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_SystemError

System error, such as an unreadable file or
insufficient memory

FE_BadParameter

The property list contained an invalid parameter

FE_BadFileType

The specified file exists, but it does not have the
correct file type

FE_MissingFile

The specified file does not exist

FE_NoSuchFlow

The script specifies an import flow that does not
exist

FE_FailedState

Internal error

FDK Programmer’s Reference 287

2

FDK Function Reference

F_ApiImport()

FA_errno value

Meaning

FE_CircularReference

Importing the specified file causes a circular
reference

FE_FileClosedByClients

The file was closed by a client before it could be
imported

The property list returned to importReturnParamspp has the properties shown in
the following table.
Property

Meaning and Possible Values

FS_ImportedFileName

A string specifying the source file’s pathname. If you scripted
FS_ShowBrowser, this pathname can be different from the
one you specified in the Import script.

FS_ImportNativeError

The error condition; normally the same value as FA_errno.
If the file is imported successfully, it is set to FE_Success.
See the table below for a list of possible values.

FS_ImportStatus

A bit field indicating what happened when the file was
imported. See the table below for a list of possible flags.

Both the FS_ImportNativeError property and the FA_errno global variable
indicate the result of a call to F_ApiImport(). The following table lists the possible

288

FDK Programmer’s Reference

F_ApiImport()

...

FDK Function Reference

status flags and the FA_errno and FS_ImportNativeError values associated
with them.
FS_ImportNativeError and
FA_errno values

FE_BadParameter,
FE_BadFileType,
FE_MissingFile,
FE_FailedState, or
FE_CanceledByClient
(file was not imported)

Possible FS_ImportStatus flags

FV_BadImportFileName: the specified source filename is
invalid
FV_BadImportFileType: the Import script specified a file
type different from the source file’s actual type
FV_BadImportScriptValue: the Import script contained an
invalid property value
FV_BadTextFileTypeHint: The file was a text file, and the string
in FS_FileTypeHint was not a valid import hint string. For
information on the syntax of this string, see “Syntax of
FP_ImportHint strings” on page 939.
FV_MissingScript: F_ApiImport() was called without a
script.
FV_DisallowedImportType: source file’s type disallowed
by script.
FV_NoMainFlow: script specified to import the main flow, but
the source file does not have a main flow.
FV_NoFlowWithSpecifiedName: script specified a flow
name that does not exist
FV_InsertionPointNotInText: the insertion point in the
enclosing document is not in text
FV_InsufficientMemory: there is insufficient memory to
import the source file
FV_BadEnclosingDocId: there is no open document with the
specified ID
FV_ImportFileNotReadable: the specified source file is
unreadable

FDK Programmer’s Reference 289

2

FDK Function Reference

F_ApiImport()

FS_ImportNativeError and
FA_errno values

FE_Success

Possible FS_ImportStatus flags

FV_ImportedByCopy: the source file was imported
by copy
FV_ImportedText: the source file is a text file
FV_ImportTextTable: the source file is a text file, which
was imported into a table.
FV_ImportedMIF: the source file is a MIF file
FV_ImportedMakerDoc: the source file is a FASL file.
FV_ImportedFilteredFile: the source file was filtered
FV_ImportedGraphicFile: the source file is a
graphics file
FV_ImportedSgmlDoc: the source file is an SGML document

FV_ImportedXmlDoc: the source file is an XML
document

290

FDK Programmer’s Reference

F_ApiImport()

FS_ImportNativeError and
FA_errno values

FE_Cancel

...

FDK Function Reference

Possible FS_ImportStatus flags

FV_CancelFileText: the file is text, so the user or the Import
script canceled the Import operation
FV_CancelFileGraphic: the source file is a graphic, so the
user or the Import script canceled the Import operation
FV_CancelFileMacEdition: the source file is a Macintosh
Edition, so the Import script canceled the Import operation
FV_CancelFileDoc: the file is a FASL file, so the user or the
script canceled the Import operation
FV_CancelFileSgml: the file is an SGML document, so the
user or the script canceled the Import operation
FV_CancelFileXML: the file is an XML document, so the user
or the script canceled the Import operation
FV_CancelFileMIF: the source file is a MIF file, so the user or
the script canceled the Import operation
FV_CancelFileFilterable: the source file is a filterable
file, so the user or the script canceled the Import operation
FV_InsertionPointInFootnote: the insertion point was
in a footnote and the import script specified to import the file as
a table, so the file could not be imported
FV_InsertionPointInTableCell: the insertion point was
in a table cell and the import script specified to import the file as
a table, so the file could not be imported
FV_UserCanceledImport: the user canceled the Import
operation
FV_UserCanceledImportBrowser: the user canceled the
Import browser

To determine whether a particular FS_ImportStatus bit is set, use
F_ApiCheckStatus(). For more information, see “F_ApiCheckStatus()” on
page 96.
After you are done with the property lists you use to call F_ApiImport(), use
F_ApiDeallocatePropVals() to deallocate the memory they use. Calling
F_ApiImport() again also deallocates the memory.

FDK Programmer’s Reference 291

2

FDK Function Reference

F_ApiImport()

Example
The following code imports a graphic file, named agraphic.xwd, by reference.
. . .
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(0, docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
/* Change properties to disallow nongraphic files. */
i = F_ApiGetPropIndex(¶ms, FS_DisallowDoc);
params.val[i].propVal.u.ival = True;
i = F_ApiGetPropIndex(¶ms, FS_DisallowMIF);
params.val[i].propVal.u.ival = True;
i = F_ApiGetPropIndex(¶ms, FS_DisallowPlainText);
params.val[i].propVal.u.ival = True;

/* Set properties to import graphic at default resolution*/
i = F_ApiGetPropIndex(¶ms, FS_GraphicDpi);
params.val[i].propVal.u.ival = 0;
i = F_ApiGetPropIndex(¶ms, FS_FitGraphicInSelectedRect);
params.val[i].propVal.u.ival = False;
F_ApiImport(docId, &tr.beg, "/tmp/agraphic.xwd",
¶ms, &returnParamsp);
if (F_ApiCheckStatus(returnParamsp, FV_BadImportFileType))
F_ApiAlert("File isn’t a graphic.", FF_ALERT_CONTINUE_NOTE);
/* Deallocate property lists. */
F_ApiDeallocatePropVals(¶ms);
F_ApiDeallocatePropVals(returnParamsp);
. . .

292

FDK Programmer’s Reference

F_ApiInitialize()

...

FDK Function Reference

See also
“F_ApiCheckStatus()” on page 96, “F_ApiGetOpenDefaultParams()” on page 219,
“F_ApiPrintOpenStatus()” on page 370, and “F_ApiSimpleOpen()” on page 465.

F _ A p i I n i t i al i ze ( )
F_ApiInitialize() is a callback that you define in your client to respond to a
FrameMaker product attempting to initialize your client.
F_ApiInitialize should be called for all APIs clients, including filters and
document reports. This enables filters and document reports to make the
F_ApiEnableUnicode(True) call necessary for enabling Unicode Mode. If
Unicode Mode isn’t enabled, sparm received in F_ApiNotify isn’t in Unicode
because the API runs in Compatibility Mode. For more information on Unicode Mode
and Compatibility Mode, see Chapter 1, “Working with Unicode.” in the FDK
Programmer’s Reference.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiInitialize(initialization)
IntT initialization;

Arguments
initialization

A constant that indicates the type of initialization

The following table summarizes the different types of initializations and the
initialization constants FrameMaker products can use to call call
F_ApiInitialize().

FDK Programmer’s Reference 293

2

FDK Function Reference

F_ApiInitialize()

When F_ApiInitialize() is
called

Initialization flag

FrameMaker product
starts with no special
options

After starting

FA_Init_First

All except document
reports and filters

FrameMaker product
starts with take-control
client

After starting

FA_Init_First

All except document
reports and filters

After all API clients
have finished processing
the FA_Init_First
initialization

FA_Init_TakeControl

Client that takes
control of the session

Document report chosen
from Document Reports
dialog box

After report is chosen

FA_Init_DocReport

The chosen document
report

Notification, menu
choice, or hypertext
command for a client
that has bailed out

When the menu item is
chosen, the hypertext
command is clicked, or
the notification should
be issued

FA_Init_Subsequent

Clients that have
bailed out and are
waiting for an event, a
menu choice, or a
hypertext command to
occur

Type of initialization

Clients that receive
initialization

Returns
VoidT.
Example
The following code displays a dialog box after the FrameMaker product is started:
. . .
VoidT F_ApiInitialize(initialization)
IntT initialization;
{
if (initialization == FA_Init_First)
F_ApiAlert("API client has started.", FF_ALERT_CONTINUE_NOTE);
}
. . .

See also
“F_ApiNotification()” on page 339.

294

FDK Programmer’s Reference

F_ApiIsEncodingSupported()

...

FDK Function Reference

F_ApiIsEncodingSupported()
F_ApiIsEncodingSupported() checks whether the specified encoding is
supported for the current session. For example, unless FrameMaker is running on a
system that supports Japanese text, Japanese encoding is not supported.
Synopsis
#include "fapi.h"
. . .
BoolT F_ApiIsEncodingSupported(ConStringT encodingName);

Arguments
encodingName

The encoding you want to test.

Allowed values for encodingName are:
Value

Means

FrameRoman

Roman text

JISX0208.ShiftJIS

Japanese text

BIG5

Traditional Chinese text

GB2312-80.EUC

Simplified Chinese text

KSC5601-1992

Korean text

Returns
True if the specified encoding is supported for the current session; otherwise returns
False.
Example
The following code checks to see whether Japanese text is supported for the current
session:
. . .
BoolT isSupported;

isSupported = F_ApiIsEncodingSupported(
(ConString) "JISX0208.ShiftJIS");
. . .

FDK Programmer’s Reference 295

2

FDK Function Reference

F_ApiLoadMenuCustomizationFile()

F_Api LoadMenuCustomi zati onFil e ()
F_ApiLoadMenuCustomizationFile() loads a menu customization file. A menu
customization file is a text file containing statements that change the menus and
commands the user sees in the FrameMaker product. For example, a menu
customization file can change the name of a command or move a command from one
menu to another.
For information on writing menu customization files, see the online manual
Customizing FrameMaker products.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiLoadMenuCustomizationFile(StringT pathname,
BoolT silent);

Arguments
pathname

The pathname of the menu customization file to load. If you specify only a
filename, the function looks in the client directory. If silent is set to False,
the pathname specified by pathname is used as the default in the Menu
Customization File dialog box.

silent

Specifies whether to display the Menu Customization File dialog box and allow
the user to choose the file. To display the dialog box and allow the user to choose
the file, specify False. To use the file specified by pathname without asking
the user, specify True.

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiLoadMenuCustomizationFile() fails, the API assigns one of the
following values to FA_errno.

296

FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this operation or
fmbatch is running

FE_BadOperation

Parameters specify an invalid operation

FE_BadParameter

Parameter has an invalid value

FE_SystemError

System error

FDK Programmer’s Reference

F_ApiMakeTblSelection()

...

FDK Function Reference

Example
The following code loads a menu customization file named mymenus.cfg, without
notifying the user:
. . .
F_ApiLoadMenuCustomizationFile("c:\\maker\\fmint\\mymenus.cfg",
True);
. . .

F _ A p i M a k eT b l S el e ct i o n ()
F_ApiMakeTblSelection() selects a range of cells in a table.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiMakeTblSelection(F_ObjHandleT docId,
F_ObjHandleT tableId,
IntT topRow,
IntT bottomRow,
IntT leftCol,
IntT rightCol);

Arguments
docId

The ID of the document containing the table.

tableId

The ID of the table containing the rows to select.

topRow

The number of the first row in the selection. The rows are numbered from top
to bottom, starting with 0 (including heading rows). To select the entire table,
specify FF_SELECT_WHOLE_TABLE.

bottomRow

The number of the last row in the selection.

leftCol

The number of the leftmost column in the selection. The columns are
numbered from left to right, starting with 0.

rightCol

The number of the rightmost column in the selection.

To select an entire table, including the table title, set topRow to
FF_SELECT_WHOLE_TABLE. F_ApiMakeTblSelection() ignores the values for
the other parameters.

FDK Programmer’s Reference 297

2

FDK Function Reference

F_ApiMenuItemInMenu()

..............................................................................

IMPORTANT: F_ApiMakeTblSelection() can’t select different types of rows at
the same time, unless you set topRow to FF_SELECT_WHOLE_TABLE or you set
topRow and bottomRow to select one or more entire columns.
..............................................................................

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiMakeTblSelection() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid table ID

FE_BadOperation

Parameters specify an action that is invalid

FE_OutOfRange

Row or column specification not in table

FE_BadParameter

Parameter has an invalid value

Example
The following code selects the cells R1-C1 to R2-C2 in a table:
. . .
F_ObjHandleT docId, tblId;
/* Get the document and table IDs. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tblId = F_ApiGetId(FV_SessionId, docId, FP_FirstTblInDoc);
/* Select the cells. If row 0 is a heading row and
** row 1 is a body row, this call won’t work.
*/
F_ApiMakeTblSelection(docId, tblId, 0, 1, 0, 1);
. . .

F_ApiMenuItemInMenu()
F_ApiMenuItemInMenu() determines if a menu item or menu is on a menu or menu
bar.

298

FDK Programmer’s Reference

F_ApiMenuItemInMenu()

...

FDK Function Reference

Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiMenuItemInMenu (F_ObjHandleT menuId,
F_ObjHandleT menuitemId,
BoolT recursive);

Arguments
menuId

The menu or menu bar to search.

menuitemId

The ID of the menu item or menu to search for.

recursive

Specifies whether to search the submenus of the menu or menu bar
specified by menuId. Specify True to search them.

Returns
The ID of the menu on which F_ApiMenuItemInMenu() found the object specified
by menuitemId, or 0 if it did not find the object.
If F_ApiMenuItemInMenu() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this operation or
fmbatch is running

FE_BadOperation

Parameters specify an invalid operation

FE_BadParameter

Parameter has an invalid value

FDK Programmer’s Reference 299

2

FDK Function Reference

F_ApiMenuItemInMenu()

Example
The following code searches the Edit menu and its submenus for the Copy menu item:
. . .
F_ObjHandleT copyCmdId, menuId, returnId;
menuId = F_ApiGetNamedObject(FV_SessionId, FO_Menu,
"EditMenu");
copyCmdId = F_ApiGetNamedObject(FV_SessionId, FO_Command,
"Copy");
returnId = F_ApiMenuItemInMenu(menuId, copyCmdId, True);
if(returnId == menuId)
F_ApiAlert("Copy is on the Edit menu." ,
FF_ALERT_CONTINUE_NOTE);
else if (!returnId)
F_ApiAlert("Copy is not on the Edit menu." ,
FF_ALERT_CONTINUE_NOTE);
else
F_ApiAlert("Copy is on a pull-right of the Edit menu.",
FF_ALERT_CONTINUE_NOTE);
. . .

See also
“F_ApiGetNamedObject()” on page 214.
St ru cture d

F_ApiMergeIntoFirst()
F_ApiMergeIntoFirst() merges the selected structural elements into the first
element in the selection.
..............................................................................

IMPORTANT: At least two structural elements must be selected when
F_ApiMergeIntoFirst() is called.

..............................................................................

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiMergeIntoFirst(F_ObjHandleT docId);

300

FDK Programmer’s Reference

F_ApiMenuItemInMenu()

...

FDK Function Reference

Arguments
docId

The ID of the document containing the selected elements

Returns
VoidT.
If F_ApiMergeIntoFirst() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product isn’t supported

FE_BadDocId

Invalid document ID

FE_BadSelectionForOperation

Current text selection is invalid for this operation

Example
The following code merges the selected structural elements in the active document:
. . .
F_ObjHandleT docId;
/* Get the document ID. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
/* Merge the elements. */
F_ApiMergeIntoFirst(docId);
. . .

See also
“F_ApiMergeIntoLast()”.
St ru cture d

F_ApiMergeIntoLast()
F_ApiMergeIntoLast() merges the selected structural elements into the last
element in the selection.
..............................................................................

IMPORTANT: At least two structural elements must be selected when
F_ApiMergeIntoLast() is called.

..............................................................................

FDK Programmer’s Reference 301

2

FDK Function Reference

F_ApiMenuItemInMenu()

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiMergeIntoLast(F_ObjHandleT docId);

Arguments
docId

The ID of the document containing the selected elements

Returns
VoidT.
If F_ApiMergeIntoLast() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product isn’t supported

FE_BadDocId

Invalid document ID

FE_BadSelectionForOperation

Current text selection is invalid for this operation

Example
The following code merges the selected structural elements in the active document:
. . .
F_ObjHandleT docId;
/* Get the document ID. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
/* Merge the elements. */
F_ApiMergeIntoLast(docId);
. . .

See also
“F_ApiMergeIntoFirst()” on page 300.

302

FDK Programmer’s Reference

F_ApiMessage()

...

FDK Function Reference

F_ApiMessage()
F_ApiMessage() is a callback that you can define in your client. The FrameMaker
product calls F_ApiMessage() when the user clicks a hypertext marker containing
the text message apiclient, where apiclient is the name under which your
client is registered with the FrameMaker product. For information on creating hypertext
markers that message FDK clients, see “Using hypertext commands in your client’s user
interface” on page 213 of the FDK Programmer’s Guide.

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiMessage(StringT message,
F_ObjHandleT docId,
F_ObjHandleT objId);

Arguments
message

The string specified by the hypertext command. It is NULL if the user clicked an
inset.

docId

The ID of the document containing the hypertext marker or the inset.

objId

The ID of the hypertext marker or the inset. If the user chooses your client from
the Inset Editors scroll list, it is 0.

Returns
VoidT.
Example
See “Responding to message apiclient commands” on page 214 and “Responding to the
user launching your inset editor” on page 494 of the FDK Programmer’s Guide.

See also
“F_ApiHypertextCommand()” on page 285 and “F_ApiNotify()” on page 349.

F_ApiModalDialog()
F_ApiModalDialog() displays a dialog resource as a modal dialog box. This is the
most common type of dialog box. The user must close the dialog box before continuing,
usually by clicking OK or Cancel.

FDK Programmer’s Reference 303

2

FDK Function Reference

F_ApiModalDialog()

..............................................................................

IMPORTANT: When you are through with it, you should always close a dialog resource
via F_ApiClose(). Also, in some circumstances you might want a custom dialog box
to be modal, and in others you might want it to be modeless. To do this, you should
create two separate dialog resources. Then you should always call one with
F_ApiModalDialog(), and call the other with F_ApiModelessDialog().
..............................................................................

Synopsis
#include "fapi.h"
. . .
IntT F_ApiModalDialog(IntT dlgNum,
F_ObjHandleT dlgId);

Arguments
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.

dlgId

The ID of the dialog resource to display.

After calling F_ApiModalDialog(), you must call F_ApiClose() to free memory.
Returns
FE_Success or a nonzero value if the user requested help.
Example
The following code displays a dialog named mydlg as a modal dialog box:
. . .
#define MY_DLG 1
F_ObjHandleT dlgId;
/* Open the resource and display the dialog box. */
dlgId =
Resource(FO_DialogResource, "mydlg");
F_ApiModalDialog(MY_DLG, dlgId);
. . .
F_ApiClose (dlgId, FF_CLOSE_MODIFIED);
. . .

304

FDK Programmer’s Reference

F_ApiModelessDialog()

...

FDK Function Reference

See also
“F_ApiModelessDialog()” on page 305, “F_ApiDialogEvent()” on page 155, and
“F_ApiOpenResource()” on page 363.

F_ApiModelessDialog()
F_ApiModelessDialog() displays a dialog resource as a modeless
dialog box. Modeless dialog boxes allow the user to switch between the dialog box and
the window that created it. Modeless dialog boxes are preferred when it would be
convenient to keep the dialog box displayed for a while.
..............................................................................

IMPORTANT: When you are through with it, you should always close a dialog resource
via F_ApiClose(). Also, in some circumstances you might want a custom dialog box
to be modal, and in others you might want it to be modeless. To do this, you should
create two separate dialog resources. Then you should always call one with
F_ApiModalDialog(), and call the other with F_ApiModelessDialog().
..............................................................................

Synopsis
#include "fapi.h"
. . .
IntT F_ApiModelessDialog(IntT dlgNum,
F_ObjHandleT dlgId);

Arguments
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.

dlgId

The ID of the dialog resource to display.

After calling F_ApiModelessDialog(), you must call F_ApiClose() to free
memory.
Returns
FE_Success or an error code if the dialog resource couldn’t be displayed.

FDK Programmer’s Reference 305

2

FDK Function Reference

F_ApiMoveComponent()

Example
The following code displays a dialog named mydlg as a modeless dialog box:
. . .
#define MY_DLG 1
F_ObjHandleT dlgId;
/* Open the resource and display the dialog box. */
dlgId = F_ApiOpenResource(FO_DialogResource, "mydlg");
F_ApiModelessDialog(MY_DLG, dlgId);
. . .
F_ApiClose (dlgId, FF_CLOSE_MODIFIED);
. . .

See also
“F_ApiModalDialog()” on page 303, “F_ApiDialogEvent()” on page 155, and
“F_ApiOpenResource()” on page 363.

F_ApiMoveComponent()
Moves a book component within the book.
Synopsis
#include "fapi.h"
...
VoidT F_ApiMoveComponent(F_ObjHandleT bookId,
F_ObjHandleT compId,
IntT moveAction);

Arguments

bookId .
compId

The ID of the book that contains the component

moveAction .

Specifies the action to move the component

The ID of the book component that is to be
moved.

You can specify the following values for moveAction.

306

FDK Programmer’s Reference

F_ApiNetLibSetAuthFunction()

...

FDK Function Reference

moveAction

Meaning

FA_COMPONENT_MOVEUP

Move the component up at the same hierarchical
level.

FA_COMPONENT_MOVEDOWN Move the component down at the same
hierarchical level.

FA_COMPONENT_PROMOTE

Move the component to a higher/outer level in
hierarchy.

FA_COMPONENT_DEMOTE

Move the component to a lower/inner level in
hierarchy.

Returns
VoidT

Example
The following code moves up a book component.
. . .
F_ObjHandleT bookId;
F_ObjHandleT comp1Id, comp2Id;

/* Get ID of active book and its second component. */
bookId = F_ApiGetId(0, FV_SessionId, FP_ActiveBook);
comp1Id = F_ApiGetId(FV_SessionId, bookId,
FP_FirstComponentInBook);
comp2Id = F_ApiGetId(bookId, comp1Id,
FP_NextComponentInBook);
/* Move the component. */
F_ApiMoveComponent(bookId, comp2Id,
FA_COMPONENT_MOVEUP);
...

F_ApiNetLib SetAu thFu nction ()
Sets a callback function that is called for setting the username/password information
before performing the NetLib related authentication.

FDK Programmer’s Reference 307

2

FDK Function Reference

F_ApiNetLibSetAuthFunction()

Synopsis
#include "fapi.h"
...
VoidT F_ApiNetLibSetAuthFunction(VoidT (*p_auth_func)(ConStringT
url,
StringT username, StringT password,
IntT *cancelp) );

Arguments

p_auth_func

Callback function that sets the username and
password information for the NetLib related
authentication.

:

NOTE: After registering the callback function, whenever NetLib needs authentication,

it calls this function with the server’s URL as ‘url’ parameter. This function checks the
URL string and accordingly fills-in the username and password fields and sets *cancelp
to 0. If you want to cancel the authentication request from NetLib, set *cancelp to 1. In
this case, set the username and password to empty strings.
To unregister the callback function, call F_ApiNetLibSetAuthFunction() with
NULL as the parameter. Then, FrameMaker’s standard NetLib authentication dialog is
displayed for the purpose.
The server authentication fails if the strings are set with an invalid username or
password through this callback function. NetLib calls the function again and this time
too, the function sets the wrong authentication information. This process will go on and
FrameMaker will hang. Therefore, use some mechanism (like counters) in the callback
function to avoid such a condition. For example, if the authentication requests for a
particular server reaches a certain number of times (say 3), cancel the later requests for
that server.
Returns

VoidT

Example
The following code sets the authentication callback function as ‘SplAuthFunction()’.
The callback function matches the URL provided and fills in the username & password

308

FDK Programmer’s Reference

F_ApiNetLibSetAuthFunction()

...

FDK Function Reference

accordingly.
. . .
F_ApiNetLibSetAuthFunction(SplAuthFunction);
. . .
. . .
VoidT SplAuthFunction(ConStringT url, StringT username,
StringT password, IntT *cancelp)
{
static int attempts_srv1 = 0;
static int attempts_srv2 = 0;
// send authentication information for first three
attempts only
if (attempts_srv1 < 3 &&
F_StrCmp(url, (ConStringT)"hostname:8080") == 0)
{

F_StrCpy(username, (ConStringT)"user123");
F_StrCpy(password, (ConStringT)"pass234");
*cancelp = 0;
attempts_srv1++;
}
else if (attempts_srv2 < 3 &&
F_StrCmp(url, (ConStringT)"cmsserver") == 0)
{
F_StrCpy(username, (ConStringT)"Admin");
F_StrCpy(password, (ConStringT)"Password");
*cancelp = 0;
attempts_srv2++;
}
else
{
F_StrCpy(username, (ConStringT)"");
F_StrCpy(password, (ConStringT)"");
*cancelp = 1;
attempts_srv1 = 0;

FDK Programmer’s Reference 309

2

FDK Function Reference

F_ApiNewAnchoredFormattedObject()

attempts_srv2 = 0;
}
}
. . .

F_ApiNewAnchoredFormattedObject()
F_ApiNewAnchoredFormattedObject() can create the following types of
anchored objects:


FO_Var



FO_XRef



FO_Tbl

F_ApiNewAnchoredFormattedObject() inserts the object at the specified
location in text. It uses arbitrary default properties for the new object. After you have
created the object, you can use the F_ApiSet
() functions to change
its properties.
If you call F_ApiNewAnchoredFormattedObject() to create a table, it uses the
default numbers of rows and columns from the specified Table Catalog format. To use
the default Table Catalog format for a new table, set format to NULL. To specify the
number of rows and columns when you create a table, use F_ApiNewTable().
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewAnchoredFormattedObject(F_ObjHandleT docId,
IntT objType,
StringT format,
F_TextLocT *textLocp);

310

FDK Programmer’s Reference

F_ApiNewAnchoredFormattedObject()

...

FDK Function Reference

Arguments
docId

The ID of the document to which to add the object

objType

The type of object to create (for example, FO_XRef)

format

The string that specifies the object’s format (for example, Heading & Page
for a cross-reference, Format A for a table, or Current Date (Long)
for a variable)

textLocp

The text location at which to insert the anchored object

The F_TextLocT structure is defined as:
typedef struct {
F_ObjHandleT objId; /* ID of the paragraph or text line */
IntT offset; /* From beginning of paragraph or text line */
} F_TextLocT;

Returns
The ID of the new anchored object, or 0 if an error occurs.
If F_ApiNewAnchoredFormattedObject() fails, the API assigns one of the
following values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid object ID

FE_NotTextObject

Object specified for text location is not a paragraph (FO_Pgf)

FE_OffsetNotFound

Offset specified for the text location couldn’t be found in the
specified paragraph or text line

FE_BadNew

Object can’t be created; the format specified by format may not
exist

FDK Programmer’s Reference

311

2

FDK Function Reference

F_ApiNewAnchoredObject()

Example
The following code adds a Current Date (Short) variable at the insertion point
(or the beginning of the text selection) of the active document:
. . .
F_TextRangeT tr;
F_ObjHandleT docId, variableId;
/* Get the insertion point. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if (tr.beg.objId == 0) return;
/* Insert the variable. */
variableId = F_ApiNewAnchoredFormattedObject(docId, FO_Var,
"Current Date (Short)", &tr.beg);
. . .

See also
“F_ApiNewAnchoredObject()”.

F_ApiNewAnchoredObject()
F_ApiNewAnchoredObject() can create any of the following anchored objects:


FO_AFrame



FO_Fn



FO_Marker



FO_TiApiClient



FO_Tbl

F_ApiNewAnchoredObject() inserts the object at the specified location in text. It
uses arbitrary default properties for the new object. After you have created the object,
you can use the F_ApiSet
() functions to change its properties.
Tables created by F_ApiNewAnchoredObject() have a single column and a single
body row. It is usually easier to use F_ApiNewTable() to create tables.

312

FDK Programmer’s Reference

F_ApiNewAnchoredObject()

...

FDK Function Reference

Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewAnchoredObject(F_ObjHandleT docId,
IntT objType,
F_TextLocT *textlocp);

Arguments
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_Fn)

textlocp

The text location at which to insert the anchored object

The F_TextLocT structure is defined as:
typedef struct {
F_ObjHandleT objId; /* ID of the paragraph or text line */
IntT offset; /* From beginning of paragraph or text line */
} F_TextLocT;

Returns
The ID of the new anchored object, or 0 if an error occurs.
If F_ApiNewAnchoredObject() fails, the API assigns one of the following values
to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadNew

Anchored object can’t be created

FE_BadObjId

Invalid object ID

FE_BadOperation

Function call specified an illegal operation

FE_NotTextObject

Object specified for the text location is not a paragraph (FO_Pgf)

FE_OffsetNotFound

Offset specified for the text location couldn’t be found in the
specified paragraph or text line

FDK Programmer’s Reference 313

2

FDK Function Reference

F_ApiNewAnchoredObject()

Example
The following code inserts a new anchored frame at the beginning of a paragraph:
. . .
F_TextRangeT tr;
F_ObjHandleT docId, afrmId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
/* Insert the frame. */
afrmId = F_ApiNewAnchoredObject(docId, FO_AFrame, &tr.beg);
. . .

See also
“F_ApiNewAnchoredFormattedObject()” on page 310.
St ru cture d

F_Api NewB o ok Comp onen tInH ierarch y ()
F_ApiNewBookComponentInHierarchy() inserts a book component at a
specified position in a structured book.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewBookComponentInHierarchy(
F_ObjHandleT bookId;
StringT compName,
F_ElementLocT *elemLocp);

Arguments
bookId

The ID of the book to add the component to

compName

The name of the component

elemLocp

The position at which to add the new element

..............................................................................

IMPORTANT: The book you specify for bookId must already be structured.
..............................................................................

314

FDK Programmer’s Reference

F_ApiNewAnchoredObject()

...

FDK Function Reference

Returns
The ID of the new element that corresponds to the book component, or 0 if an error
occurs.
If F_ApiNewBookComponentInHierarchy() fails, the API assigns one of the
following values to FA_errno.
FA_errno value

Meaning

FE_BadBookId

Invalid book ID

FE_BadCompPath

Component name specified for compName is invalid

FE_BadNew

The object can’t be created

FE_BookUnStructured

Specified book is unstructured

Example
The following code adds a component to a book:
. . .
F_ObjHandleT bookId, elemId;
F_ElementLocT elemLoc;
/* Get ID of active book and its highest level element. */
bookId = F_ApiGetId(0, FV_SessionId, FP_ActiveBook);
elemLoc.childId = F_ApiGetId(FV_SessionId, bookId,
FP_HighestLevelElement);
elemLoc.parentId = 0;
elemLoc.offset = 0;
/* Insert the new element. */
elemId = F_ApiNewBookComponentInHierarchy(bookId, "Chapter1",
&elemLoc);
. . .

FDK Programmer’s Reference 315

2

FDK Function Reference

F_ApiNewBookComponentOfTypeInHierarchy()

See also
“F_ApiNewElementInHierarchy()” on page 320 and “F_ApiNewSeriesObject()” on
page 329.

F_ApiNewBookComponentOfTypeInHierarc hy()
Inserts a book component of a specified type at a specified position in a structured
FrameMaker book.
Synopsis
#include "fapi.h"
...
F_ObjHandleT F_ApiNewBookComponentOfTypeInHierarchy(F_ObjHandleT
bookId,
ConStringT compName,
IntT compType,
const F_ElementLocT *elemLocp);

Arguments
You can specify the following values for compType.
compType

Meaning

FV_BK_FOLDER

Folder type book component.

FV_BK_GROUP

Group type book component.

Returns
The ID of the new element that corresponds to the book component, or 0 if an error
occurs.
If F_ApiNewBookComponentOfTypeInHierarchy() fails, the API assigns one of
the following values to FA_errno

316

FA_errno Value

Meaning

FE_BadBookId
FE_BadParameter
FE_BadNew
FE_BookUnStructured

Invalid book ID.

FDK Programmer’s Reference

Invalid compType.
The object can’t be created.
Specified book is unstructured.

F_ApiNewBookComponentOfTypeInHierarchy()

...

FDK Function Reference

Example
The following code adds a component of type folder to a book.
. . .
F_ObjHandleT bookId, elemId;
F_ElementLocT elemLoc;

/* Get ID of active book and its highest level element. */
bookId = F_ApiGetId(0, FV_SessionId, FP_ActiveBook);
elemLoc.childId = F_ApiGetId(FV_SessionId, bookId,
FP_HighestLevelElement);

elemLoc.parentId = 0;
elemLoc.offset = 0;

/* Insert the new element. */
elemId = F_ApiNewBookComponentOfTypeInHierarchy(bookId,
"TechDoc Folder", FV_BK_FOLDER,
&elemLoc);
. . .

St ru cture d

F_ApiNewElement()
F_ApiNewElement() creates a structural element (FO_Element) in a structured
document.
F_ApiNewElement() inserts the new element at the specified location in text, using
the specified element definition.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewElement(F_ObjHandleT docId,
F_ObjHandleT elemDefId,
F_TextLocT *textLocp);

FDK Programmer’s Reference 317

2

FDK Function Reference

F_ApiNewBookComponentOfTypeInHierarchy()

Arguments
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 F_TextLocT structure is defined as:
typedef struct {
F_ObjHandleT objId; /* ID of the paragraph or text line */
IntT offset; /* From beginning of paragraph or text line */
} F_TextLocT;

For object (noncontainer) elements, F_ApiNewElement() inserts the appropriate
type of object for the element. If there is a matching format rule,
F_ApiNewElement() uses it to format the object. Otherwise, it uses one of the
following default formats:

Object type

Object inserted

Format used if no matching
format rule exists

FV_FO_XREF

Cross-reference

Undefined XRef

FV_FO_EQN

Equation

medium

FV_FO_MARKER

Marker

Type 11

FV_FO_TBL

Table with the format
and number of rows and
columns specified by the
table format

Format A if it exists;
otherwise, a table with a
heading row, 8 body rows, a
footing row, and 5 columns

FV_FO_SYS_VAR

Variable

Filename (Long)

FV_FO_GRAPHIC

A centered 1.0-inch by
1.0-inch anchored frame
below the current
position; cropped is off,
and floating is on

Returns
The ID of the new element, or 0 if an error occurs.

318

FDK Programmer’s Reference

F_ApiNewBookComponentOfTypeInHierarchy()

...

FDK Function Reference

If F_ApiNewElement() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadNew

Object can’t be created

FE_BadObjId

Invalid object ID

FE_NotTextObject

Object specified for the text location isn’t a paragraph (FO_Pgf) or
a text line (FO_TextLine)

FE_OffsetNotFound

Offset specified for the text location couldn’t be found in the
specified paragraph or text line

Example
See “Creating objects” on page 357 of the FDK Programmer’s Guide.

FDK Programmer’s Reference 319

2

FDK Function Reference

F_ApiNewBookComponentOfTypeInHierarchy()

See also
“F_ApiUnWrapElement()” on page 479.
St ru cture d

F_ApiNewElementInHierarc hy()
F_ApiNewElementInHierarchy() creates a structural element (FO_Element
object) at a specified location in the element hierarchy of a structured document or
book.
To create the root element for a book, you must use
F_ApiNewElementInHierarchy(); you can’t use F_ApiNewElement().
However, 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().
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewElementInHierarchy(F_ObjHandleT docId,
F_ObjHandleT elemDefId,
F_ElementLocT *elemLocp);

Arguments
docId

The ID of the document or book to add the element to

elemDefId

The ID of the element definition for the new element

elemLocp

The location at which the element is inserted

For object (noncontainer) elements, F_ApiNewElementInHierarchy() inserts the
appropriate type of object for the element. If there is a matching format rule,
F_ApiNewElementInHierarchy() uses it to format the object. Otherwise, it uses
one of the following default formats:

320

Object type

Object inserted

Format used if no matching
format rule exists

FV_FO_XREF

Cross-reference

Undefined XRef

FV_FO_EQN

Equation

medium

FV_FO_MARKER

Marker

Type 11

FDK Programmer’s Reference

F_ApiNewBookComponentOfTypeInHierarchy()

...

FDK Function Reference

Object type

Object inserted

Format used if no matching
format rule exists

FV_FO_TBL

Table with the format
and number of rows and
columns specified by the
table format

Format A if it exists;
otherwise, a table with a
heading row, 8 body rows, a
footing row, and 5 columns

FV_FO_SYS_VAR

Variable

Filename (Long)

FV_FO_GRAPHIC

A centered 1.0-inch by
1.0-inch anchored frame
below the current
position

Returns
The ID of the new element, or 0 if an error occurs.
If F_ApiNewElementInHierarchy() fails, the API assigns one of the following
values to FA_errno.
FA_errno value

Meaning

FE_BadBookId

Invalid book (FO_Book object) ID

FE_BadObjId

Invalid element definition (FO_ElementDef object) ID

FE_BadInsertPos

elemLocP specifies an invalid place to insert the element; for
example, it specifies a position before the highest element in the
flow

FDK Programmer’s Reference 321

2

FDK Function Reference

F_ApiNewGraphicObject()

Example
The following code adds a Para element at the insertion point, or the beginning of the
current element selection:
. . .
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 element selection in active document. */
elemSelect = F_ApiGetElementRange(FV_SessionId, docId,
FP_ElementSelection);
if(elemSelect.beg.parentId == 0 || paraEdefId == 0)return;
/* Insert the new element. */
elemId = F_ApiNewElementInHierarchy(docId, paraEdefId,
&elemSelect.beg);
. . .

F_ApiNewGraphicObject()
F_ApiNewGraphicObject() creates the following types of graphic objects:


FO_Arc



FO_Ellipse



FO_Flow 1



FO_Group



FO_Inset



FO_Line



FO_Math



FO_Polyline



FO_Polygon

.................................
1. To create a flow, you must create a text frame. See “Creating flows” on page 366 of the FDK Programmer’s
Guide.

322

FDK Programmer’s Reference

F_ApiNewGraphicObject()



FO_Rectangle



FO_RoundRect



FO_TextFrame



FO_TextLine



FO_UnanchoredFrame

...

FDK Function Reference

To create an anchored frame, use F_ApiNewAnchoredObject().
If there is more than one object within the parent frame,
F_ApiNewGraphicObject() adds the new API graphic object to the end of the
linked list of child objects. That is, it puts it in the front of the back-to-front draw order.
It automatically takes care of updating the object’s FP_PrevGraphicInFrame and
FP_NextGraphicInFrame properties. F_ApiNewGraphicObject() gives the
new API graphic object a set of arbitrary default properties. For example, FP_LocX
and FP_LocY are both 0. After you have created the object, you can use the
F_ApiSet
() functions to change its properties.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewGraphicObject(F_ObjHandleT docId,
IntT objType,
F_ObjHandleT parentId);

Arguments
docId

The ID of the document in which to create the new object

objType

The type of API graphic object to create (for example, FO_Rectangle or
FO_Line)

parentId

The ID of the parent frame in which to create the object

Returns
The ID of the new graphic object, or 0 if an error occurs.
If F_ApiNewGraphicObject() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid object ID

FDK Programmer’s Reference 323

2

FDK Function Reference

F_ApiNewKeyCatalog()

FA_errno value

Meaning

FE_NotFrame

Specified parent object is not a frame

FE_BadNew

Object can’t be created

Example
The following code creates an ellipse and a text frame within the selected frame:
. . .
F_ObjHandleT docId, parentId, ellpsId, tFramId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
parentId = F_ApiGetId(FV_SessionId,
docId, FP_FirstSelectedGraphicInDoc);
if ((F_ApiGetObjectType(docId, parentId) != FO_AFrame) &&
(F_ApiGetObjectType(docId, parentId) != FO_UnanchoredFrame))
{
F_ApiAlert("Select a frame first.", FF_ALERT_CONTINUE_WARN);
return;
}
ellpsId = F_ApiNewGraphicObject(docId, FO_Ellipse, parentId);
tFramId = F_ApiNewGraphicObject(docId, FO_TextFrame, parentId);
. . .

For an example of how to create a polygon, see “F_ApiSetPoints()” on page 429.

See also
“F_ApiNewAnchoredObject()” on page 312, “F_ApiNewNamedObject()”, and
“F_ApiNewSeriesObject()” on page 329.

F_ApiNewKeyCatalog()
Creates a new key catalog with the specified tag.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewKeyCatalog(StringT tag)

324

FDK Programmer’s Reference

F_ApiNewKeyDefinition()

...

FDK Function Reference

Arguments
tag

The tag of the new key catalog.

Returns
Returns the handle of the new key catalog.
If F_ApiNewKeyCatalog() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadName

The tag provided is not valid.

FE_DupName

A key catalog for the tag provided already exists.

F_ApiNewKeyDefinition()
Adds a new key definition to the specified key catalog.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiNewKeyDefinition(F_ObjHandleT keyCatalogId, StringT
key, StringT href, IntT srcType, StringT srcFile, IntT flags)

FDK Programmer’s Reference 325

2

FDK Function Reference

F_ApiNewKeyDefinition()

Arguments
keyCatalogId

The ID of the key catalog to which the key definiton is being added.

key

The tag of the key for which the key definition is being added.

href

The complete path of the file that the key refers to.

srcType

The type of the file that contains the key definition. See the following
table for a list of values.

srcFile

The complete path of the file that contains the key definition.

flags

Bit flags specifying information about the key definition. See the
following table for a list of flags.

srcType can have one of the following values:
srcType

Meaning

FV_KeySrcTypeNone

Source file type not specified.

FV_KeySrcTypeDitamap

Source file is a DITA Map.

You can OR the following bit-flags into flags:

326

Bit mask

Meaning

FF_DUPLICATE_KEY_DEFINITION

The specified key definiton is duplicate
(that is, it already exists in the key catalog)
and will not be used as active definition for
resolving keys.

FF_FOUND_IN_REFERENCED_FILE

The specified key definiton is contained in a
file referenced directly or indirectly from
the file that contains the key definition
(srcFile).

FF_INVALID_KEY

The specified key definiton is invalid due to
some reason but will still be retained in the
key catalog.

FDK Programmer’s Reference

F_ApiNewNamedObject()

...

FDK Function Reference

Returns
If F_ApiNewKeyDefinition() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadObjId

The ID provided does not specify a key catalog.

FE_BadKey

The key provided is not valid.

FE_KeyDefinitionAlreadyE
xists

The definition for the specified key is already available
in the key catalog and the key definition provided is not
duplicate.

F_ApiNewNamedObject()
F_ApiNewNamedObject() can create the following named objects:


FO_Book



FO_CharFmt



FO_CombinedFontDefn



FO_Color



FO_Command



FO_CondFmt



FO_ElementDef



FO_FmtChangeList



FO_MasterPage



FO_Menu



FO_MenuItemSeparator



FO_PgfFmt



FO_RefPage



FO_RulingFmt



FO_TblFmt



FO_VarFmt



FO_XRefFmt

FDK Programmer’s Reference 327

2

FDK Function Reference

F_ApiNewNamedObject()

F_ApiNewNamedObject() uses arbitrary default properties for the objects it creates.
After you have created the object, you can use the F_ApiSet
()
functions to change its properties.
..............................................................................

IMPORTANT: When you create a new element definition, it does not appear in the
Element Catalog unless you set FP_ElementInCatalog to True.
..............................................................................
..............................................................................

IMPORTANT: When you create a new book and specify a pathname, you must specify an
absolute pathname for the name argument. To create an untitled book, pass an empty
string for the name argument.
..............................................................................

Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewNamedObject(F_ObjHandleT docId,
IntT objType,
StringT name);

Arguments
docId

The ID of the document to which to add the object

objType

The type of object to create (for example, FO_MasterPage or FO_PgfFmt)

name

The name to give to the new object

Returns
The ID of the new named object, or 0 if an error occurs.
If F_ApiNewNamedObject() fails, the API assigns one of the following values to
FA_errno.

328

FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadName

Specified name for the new object is invalid

FE_BadNew

Object can’t be created

FE_DupName

Specified name for the new object belongs to an existing object

FDK Programmer’s Reference

F_ApiNewSeriesObject()

...

FDK Function Reference

Example
The following code creates a new paragraph format named MyPgfFormat and a new
master page named MyPg:
. . .
F_ObjHandleT docId, pgfFmtId, mstrpgId;
/* Get ID of active document. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
/* Create the paragraph format and master page. */
pgfFmtId = F_ApiNewNamedObject(docId, FO_PgfFmt, "MyPgfFormat");
mstrpgId = F_ApiNewNamedObject(docId, FO_MasterPage, "MyPg");
. . .

See also
“F_ApiNewAnchoredObject()” on page 312, “F_ApiNewGraphicObject()” on
page 322, and “F_ApiNewSeriesObject()”.

F_ApiNewSeriesObject()
F_ApiNewSeriesObject() creates a series object. Series objects include the
following object types:


FO_BodyPage



FO_BookComponent



FO_Pgf

F_ApiNewSeriesObject() allows you to specify the position in the series at which
to add the new object.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewSeriesObject(F_ObjHandleT docId,
IntT objType,
F_ObjHandleT prevId);

Arguments
docId

The ID of the document to which to add the object.

FDK Programmer’s Reference 329

2

330

FDK Function Reference

F_ApiNewSeriesObject()

objType

The type of object to create (for example, FO_BodyPage or FO_Pgf).

prevId

The ID of the object in the series after which to add the new object. To add a
paragraph at the start of a flow, specify the ID of the flow. To add an object at the
beginning of any other series, specify 0.

FDK Programmer’s Reference

F_ApiNewSeriesObject()

...

FDK Function Reference

Returns
The ID of the new series object, or 0 if an error occurs.
If F_ApiNewSeriesObject() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadNew

Object can’t be created

FE_BadObjId

Invalid object ID

FE_NotBodyPage

prevId must specify the ID of a body page

FE_NotPgf

prevId must specify the ID of a paragraph

FE_NotBookComponent

prevId must specify the ID of a book component

Example
The following code inserts a paragraph after the paragraph containing the insertion
point:
. . .
F_ObjHandleT docId, pgfId;
F_TextRangeT tr;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if (tr.beg.objId == 0) return;
pgfId = F_ApiNewSeriesObject(docId, FO_Pgf, tr.beg.objId);
. . .

See also
“F_ApiNewAnchoredObject()” on page 312 and “F_ApiNewNamedObject()” on
page 327.
St ru cture d

F_ApiNewSubObject()
F_ApiNewSubObject() creates the following types of format rule objects:


FO_FmtRule



FO_FmtRuleClause

FDK Programmer’s Reference 331

2

FDK Function Reference

F_ApiNewSeriesObject()



FO_FmtChangeList

To create a named format change list (FO_FmtChangeList object) in the format
change list catalog, use F_ApiNewNamedObject().
F_ApiNewSubObject() allows you to associate the new object with a specified
property of the parent object. For example, you can create an FO_FmtRule as the text
format rule of an element definition or as a subformat rule of a format rule clause.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewSubObject(F_ObjHandleT docOrBookId,
F_ObjHandleT parentId
IntT property);

Arguments
docOrBookId

The ID of the document or book 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 the new object with

The following table shows the parent objects for which you can create format rule
objects. It also lists the properties with which you can associate the new object, the type
of object you can create, and how many objects of that type of object you can associate
with each property.

Parent object type

Property

Type of new object

Number that
can be
created

FO_ElementDef

FP_TextFmtRules

FO_FmtRule

Multiple

FP_ObjectFmtRules

FO_FmtRule

One

FP_PrefixRules

FO_FmtRule

Multiple

FP_SuffixRules

FO_FmtRule

Multiple

FP_FirstPgfRules

FO_FmtRule

Multiple

FP_LastPgfRules

FO_FmtRule

Multiple

FP_FmtRuleClauses

FO_FmtRule
Clause

Multiple

FO_FmtRule

332

FDK Programmer’s Reference

F_ApiNewSeriesObject()

...

FDK Function Reference

Parent object type

Property

Type of new object

Number that
can be
created

FO_FmtRuleClause

FP_SubFmtRule

FO_FmtRule

One

FO_FmtRuleClause

FP_FmtChangeList

FO_FmtChange
List

One

If you associate a new format rule object with a property that can specify multiple
objects, F_ApiNewSubObject() adds the new object after any existing objects for
that property.
If you attempt to associate a new format rule object with a property that can specify only
one object and that property already has an object associated with it,
F_ApiNewSubObject() fails, returning 0.

FDK Programmer’s Reference 333

2

FDK Function Reference

F_ApiNewSeriesObject()

Returns
The ID of the new format rule object, or 0 if an error occurs.
If F_ApiNewSubObject() fails, the API assigns one of the following values to
FA_errno.

334

FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid object ID

FE_BadNew

Object can’t be created

FE_BadPropNum

The property number specified for property is invalid

FE_WrongProduct

Current FrameMaker product isn’t supported

FDK Programmer’s Reference

F_ApiNewSeriesObject()

...

FDK Function Reference

Example
The following code adds a format rule to the Section element definition so that the
element definition appears as shown in Figure 2-1:
. . .
#define in (MetricT) 65536*72
F_ObjHandleT docId, sectEdefId, fmtRuleId, clauseId;
F_ObjHandleT changeListId;
/* Get ID of Section element definition. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
sectEdefId = F_ApiGetNamedObject(docId, FO_ElementDef,
"Section");
/* Add the format rule. */
fmtRuleId = F_ApiNewSubObject(docId, sectEdefId,
FP_TextFmtRules);
/* Set rule type and other characteristics. */
F_ApiSetInt(docId, fmtRuleId, FP_FmtRuleType,
FV_CONTEXT_RULE);
/* Add rule clause to format rule. */
clauseId = F_ApiNewSubObject(docId, fmtRuleId,
FP_FmtRuleClauses);
F_ApiSetString(docId, clauseId, FP_ContextLabel,"SubSection");
F_ApiSetString(docId, clauseId, FP_Specification,"Section");
/* Create format change list and add it to rule clause. */
changeListId = F_ApiNewSubObject(docId, clauseId,
FP_FmtChangeList);
F_ApiSetMetric(docId, changeListId, FP_LeftIndentChange, in);
. . .

Element (Container): Section
General rule: Head, (Para | List)+, Section*
Text format rules
1. If context is:
Context label: SubSection
Basic properties
Indents
Move left indent by: 1.0"

FDK Programmer’s Reference 335

2

FDK Function Reference

F_ApiNewTable()

Figure 2-1 Section element definition

See also
“F_ApiNewSeriesObject()” on page 329.

F_ApiNewTable()
F_ApiNewTable() inserts a table (FO_Tbl object).
When you create a table in the user interface, you can specify a Table Catalog format for
the table. The FrameMaker product uses the following properties of the Table Catalog
format as the defaults for the new table:


Number of body rows (FP_TblInitNumBodyRows)



Number of columns (FP_TblInitNumCols)



Number of footer rows (FP_TblInitNumFRows)



Number of header rows (FP_TblInitNumHRows)



Paragraph formats for header, body, and footer cells

For example, if the Table Catalog format’s FP_TblInitNumCols property is set to
8, the FP_NumCols property of the new table is set to 8.
With F_ApiNewTable(), you can use the Table Catalog format properties as defaults
for the number of rows and columns in a new table, or you can provide your own
defaults.
After you have created a table, you can add or remove rows with F_ApiAddRows()
and F_ApiDeleteRows(). You can add or remove columns with
F_ApiAddCols() and F_ApiDeleteCols(). You can also use
F_ApiSet
() functions to change the table’s other properties.
If you use F_ApiNewTable() to create a table in a structured document,
FrameMaker applies default element tags, such as Table, Row, and Cell, to the table
element and its child elements. To make these elements valid, you must add code to
change their tags. In most cases it is easier to add tables to structured documents by
calling F_ApiNewElementInHierarchy() or F_ApiNewElement() to add a
table element.

336

FDK Programmer’s Reference

F_ApiNewTable()

...

FDK Function Reference

Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewTable(F_ObjHandleT docId,
StringT format,
IntT numCols,
IntT numBodyRows,
IntT numHeaderRows,
IntT numFooterRows,
F_TextLocT *textLocp);

Arguments
docId

The ID of the document to which to add the table.

format

The table format tag (for example, FormatA or Wide Table). To use
the default format, specify NULL.

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 number of heading rows in the table. To use the default number of
header rows from the Table Catalog format, specify -1.

numFooterRows

The number of footing 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.

Returns
The ID of the new table, or 0 if an error occurs.
If F_ApiNewTable() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID.

FE_BadObjId

Invalid object ID.

FE_NotTextObject

Object specified for the text location isn’t a paragraph (FO_Pgf).

FE_OffsetNotFound

Offset specified for the text location couldn’t be found in the
specified paragraph or text line.

FDK Programmer’s Reference 337

2

FDK Function Reference

F_ApiNewXML()

FA_errno value

Meaning

FE_BadOperation

Function call specified an illegal operation.

FE_BadNew

Table can’t be created; the format specified by format may not
exist or the text location specified by textLocp is in a table or a
footnote.

Example
The following code inserts a new table at the insertion point. The new table uses all the
defaults from the Format A Table Catalog format, except the number of heading rows,
which is 0.
. . .
F_ObjHandleT docId, tblId;
F_TextRangeT tr;
/* Get the insertion point. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
/* Insert the table at the insertion point. */
tblId = F_ApiNewTable(docId, "Format A", -1, -1,0, -1, &tr.beg);
. . .

See also
“F_ApiAddCols()” on page 70, “F_ApiAddRows()” on page 78, and
“F_ApiNewAnchoredObject()” on page 312.

F_ApiNewXML()
F_ApiNewXML() creates a new, untitled XML.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiNewXML(const F_PropValsT *newXMLParams,
F_PropValsT **newXMLReturnParamspp);
. . .

338

FDK Programmer’s Reference

F_ApiNotification()

...

FDK Function Reference

Arguments
newXMLParams

A property list that instructs FrameMaker how to open the file
and how to respond to errors and other conditions. To use the
default list, specify NULL.

newXMLReturnParamspp

A property list that returns the filename and provides
information about how the FrameMaker product opened the
file. It must be initialized before you call F_ApiNewXML().

To get a property list to specify for the newXMLParams parameter, use
F_ApiGetNewXMLDefaultParams().
Returns
ID of the new XML document.
Example
The following code demonstrates how to create a new XML file with a specified
structured application.
F_PropValsT params = F_ApiGetNewXMLDefaultParams ();
F_PropValsT *retParams = NULL;
for (UIntT i = 0; i < params.len; i++)
{
switch (params.val[i].propIdent.num)
{
case FS_StructuredApplication:
params.val[i].propVal.u.sval = F_StrCopyString
("My_Strcutured_App");
break;
}
}
F_ApiNewXML (¶ms, &retParams);
F_ApiDeallocatePropVals (¶ms);
F_ApiDeallocatePropVals (retParams);

F_ApiNotification()
F_ApiNotification() requests that the FrameMaker product notify your client
whenever a specified event, or stage of an event, occurs.

FDK Programmer’s Reference 339

2

FDK Function Reference

F_ApiNotification()

..............................................................................

IMPORTANT: If the FrameMaker product encounters an internal error and exits, it
does not send any notification to your client about operations performed after the error
occured. For example, after an error the product allows the user to save changes in
open documents, but it does not notify any clients of the save operations.
..............................................................................

Synopsis
#include "fapi.h"
. . .
IntT F_ApiNotification(IntT notification,
IntT state);

Arguments
notification

Constant that specifies the notification point. See the following table for a
list of available constants.

state

Specifies whether to turn notification on or off. True turns it on, and
False turns it off.

Many events have several notification points or stages that you can request notification
for. The following table lists the notification points and the constants that specify them:
Event or operation

Notification points

Notification constants

Frame binary
document opened

Before checking the
type of the file to be
opened

FA_Note_PreFileType

After checking the type
of the file to be opened

FA_Note_PostFileType

Before opening the file

FA_Note_PreOpenDoc

After opening the file

FA_Note_PostOpenDoc

Before checking the
type of the file to be
opened

FA_Note_PreFileType

After checking the type
of the file to be opened

FA_Note_PostFileType

Before opening the file

FA_Note_PreOpenMIF

After opening the file

FA_Note_PostOpenMIF

MIF document opened

340

FDK Programmer’s Reference

F_ApiNotification()

Event or operation

Notification points

Notification constants

SGML document
opened

Before checking the
type of the file to be
opened

FA_Note_PreFileType

After checking the type
of the file to be opened

FA_Note_PostFileType

Before opening the file

FA_Note_PreOpenSGML

After opening the file

FA_Note_PostOpenSGML

Before checking the
type of the file to be
opened

FA_Note_PreFileType

After checking the type
of the file to be opened

FA_Note_PostFileType

Before opening the file

FA_Note_PreOpenXML

After opening the file

FA_Note_PostOpenXML

Filterable document
opened

Before checking the
type of the file to be
opened

FA_Note_FilterIn

Frame binary book
opened

Before checking the
type of the file to be
opened

FA_Note_PreFileType

After checking the type
of the file to be opened

FA_Note_PostFileType

Before opening the file

FA_Note_PreOpenBook

After opening the file

FA_Note_PostOpenBook

Before checking the
type of the file to be
opened

FA_Note_PreFileType

After checking the type
of the file to be opened

FA_Note_PostFileType

Before opening the file

FA_Note_PreOpenBookMIF

After opening the file

FA_Note_PostOpenBookMIF

Before opening the file

FA_Note_PreBook
ComponentOpen

After opening the file

FA_Note_PostBook
ComponentOpen

XML document
opened

MIF book opened

User double-clicked to
open a document in a
book window

...

FDK Function Reference

FDK Programmer’s Reference 341

2

FDK Function Reference

F_ApiNotification()

Event or operation

Notification points

Notification constants

Generating a list or
TOC for a document or
a book

Before generating the
file

FA_Note_PreGenerate

After generating the file

FA_Note_PostGenerate

Before saving the
document

FA_Note_PreSaveDoc

After saving the
document

FA_Note_PostSaveDoc

Before saving the
MIF file

FA_Note_PreSaveMIF

After saving the
MIF file

FA_Note_PostSaveMIF

Before specifying
Acrobat settings and
generating PostScript

FA_Note_PreSaveAs
PDFDialog

After specifying
Acrobat settings and
generating PostScript

FA_Note_PostSaveAs
PDFDialog

Before distilling the
PostScript

FA_Note_PreDistill

After distilling the
PostScript

FA_Note_PostDistill

Document saved as
filterable type

Before the document is
saved

FA_Note_FilterOut

Document exited

Before exiting the
document

FA_Note_PreQuitDoc

After exiting the
document

FA_Note_PostQuitDoc

Before exiting the book

FA_Note_PreQuitBook

After exiting the book

FA_Note_PostQuitBook

First change made to a
document since it was
opened or saved

After the document is
changed

FA_Note_DirtyDoc

First change made to a
book since it was
opened or saved

After the book is
changed

FA_Note_DirtyBook

Document saved in
Frame binary format

Document saved in
MIF format

Document saved as
PDF

Book exited

342

FDK Programmer’s Reference

F_ApiNotification()

Event or operation

Notification points

Notification constants

Book saved in Frame
binary format

Before saving the book

FA_Note_PreSaveBook

After saving the book

FA_Note_PostSaveBook

Before saving the
MIF file

FA_Note_PreSaveBookMIF

After saving the
MIF file

FA_Note_PostSaveBookMIF

Before saving the
document

FA_Note_PreAutoSaveDoc

After saving the
document

FA_Note_PostAutoSaveDoc

Before reverting the
document

FA_Note_PreRevertDoc

After reverting the
document

FA_Note_PostRevertDoc

Before reverting
the book

FA_Note_PreRevertBook

After reverting
the book

FA_Note_PostRevertBook

Before the OK to Exit
dialog box appears

FA_Note_PreQuitSession

Immediately before
exiting the session

FA_Note_PostQuitSession

Another client calls
F_ApiCallClient(
)
with clname set to the
current client’s name

After
F_ApiCallClient(
) is called

FA_Note_ClientCall

Any user action, such
as a command choice
or text entry

After the FrameMaker
product finishes
processing the user
action

FA_Note_BackToUser

Text inset owned by
current client clicked

After the user clicked
the inset

FA_Note_DisplayClientTi
Dialog

FrameMaker product
updating all text insets

When the client needs
to update insets that
belong to it

FA_Note_UpdateAllClientTi

Book saved in MIF
format

Document saved with
Autosave

Document reverted

Book reverted

FrameMaker product
exited

...

FDK Function Reference

FDK Programmer’s Reference 343

2

FDK Function Reference

F_ApiNotification()

Event or operation

Notification points

Notification constants

FrameMaker product
updating a specific text
inset

When the client needs
to update a specified
inset

FA_Note_UpdateClientTi

Text or graphic
imported

Before importing the
text or graphic

FA_Note_PreImport

After importing the text
or graphic

FA_Note_PostImport

Before the
FrameMaker product
executes command or
adds text to the
document

FA_Note_PreFunction

After the FrameMaker
product executes
command or adds text
to the document

FA_Note_PostFunction

Before the
FrameMaker product
responds to the mouse
click

FA_Note_PreMouseCommand

After the FrameMaker
product responds to the
mouse click

FA_Note_PostMouseCommand

Before the
FrameMaker product
executes the hypertext
command

FA_Note_PreHypertext

After the FrameMaker
product executes the
hypertext command

FA_Note_PostHypertext

Before the
FrameMaker product
goes to the crossreference source

FA_Note_PreGoToXrefSrc

After the FrameMaker
product goes to the
cross-reference source

FA_Note_PostGoToXrefSrc

FrameMaker product
command invoked or
text entered in a
document

Mouse button clicked

Hypertext command
invoked

The user clicked Go To
Source in the crossreference dialog box

344

FDK Programmer’s Reference

F_ApiNotification()

Event or operation

Notification points

Notification constants

Document or book
printed

After the user clicks
OK in the Print dialog
box, but before the
FrameMaker product
prints the document or
book

FA_Note_PrePrint

After the FrameMaker
product prints the
document or book

FA_Note_PostPrint

Body page added to
document

After the FrameMaker
product adds the
body page

FA_Note_BodyPageAdded

Body page deleted
from document

After the FrameMaker
product deletes the
body page

FA_Note_BodyPageDeleted

Structural element
inserteda

Before the element is
inserted

FA_Note_PreInsertElement

After the element is
inserted

FA_Note_PostInsertElement

Before the element is
copied.

FA_Note_PreCopyElement

After the element is
copied.

FA_Note_PostCopyElement

Before the element is
changed

FA_Note_PreChangeElement

After the element is
changed

FA_Note_PostChangeElement

Before the element is
wrapped

FA_Note_PreWrapElement

After the element is
wrapped

FA_Note_PostWrapElement

Before the element is
dragged

FA_Note_PreDragElement

After the element is
dragged

FA_Note_PostDragElement

Before the attribute
value is set

FA_Note_PreSetAttrValue

After the attribute value
is set

FA_Note_PostSetAttrValue

Structural element
copied

Structural element
changed

Structural element
wrapped

Structural element
dragged

An attribute value
is set

...

FDK Function Reference

FDK Programmer’s Reference 345

2

FDK Function Reference

F_ApiNotification()

Event or operation

Notification points

Notification constants

Element definitions are
imported

Before the element
definitions are
imported

FA_Note_PreImportElementDefs

After the element
definitions are
imported

FA_Note_PostImportElementDef
s

Before the text entry

FA_Note_PreInlineTypeIn

After the text entry

FA_Note_PostInlineTypeIn

When the inset is
selected

FA_Note_U3DCommand: if the selected
inset is a u3d object

Inline input of doublebyte text
An inset is selected

FA_Note_Not_U3DCommand: if the
selected inset is not a u3d object
A Robohelp screen
capture is inserted

When the screen
capture is inserted

FA_Note_RSC_Supported_File:
When the file supports Robohelp screen
capture.
FA_Note_Not_RSC_Supported_File
: When the file does not support Robohelp
screen capture.

When the graphic is
clicked

FA_Note_AI_Supported_File

A graphic not
supported by Adobe
Illustrator is clicked.

When the graphic is
clicked

FA_Note_Not_AI_Supported_File

The workspace
launches a particular
client’s modeless
dialog

Before the modeless
dialog is launched

FA_Note_Dialog_Create

A graphic supported by
Adobe Illustrator (AI)
is clicked. Following
format are supported
by AI:
"FrameImage",
"FrameVector", "PDF",
"EPSI", "TIFF",
"SVG", "DIB", "EMF",
"JPEG", "QuickDraw
PICT", "PNG", "PSD",
"WMF", "DXF

346

FDK Programmer’s Reference

F_ApiNotification()

...

FDK Function Reference

Event or operation

Notification points

Notification constants

When a client’s
modeless dialog is
closed because of
workspace-related
events such as
switching workspaces

Before the modeless
dialog is closed

FA_Note_QuitModelessDialog

When a client displays
or updates (in case the
dialog is already
displayed) a crossreference dialog

Before the dialog is
displayed or updated.

FA_Note_DisplayClientXRefDia
log

A particular DITA
reference is updated as
specified using the
element ID and the
reference type string

After the reference is
updated

FA_Note_UpdateDITAReference

All DITA references of
the specified type are
updated.

After the references are
updated

FA_Note_UpdateDITAReferences

A DITA map is
published

Before publishing starts

FA_Note_PrePublishDitamap

A DITA map is
published

After the book or
document has been
generated

FA_Note_PostPublishDitamap

When FrameMaker
wants to determine
whether a command is
enabled or disabled

FA_Note_IsCommandEnabled

When a view is
switched

Before theview is
switched

FA_Note_PreSwitchView

When a view is
switched

After the view is
switched

FA_Note_PostSwitchView

Key catalog
information is not
loaded and hence
cannot be used.

FA_Note_LoadKeyCatalog

Key catalog
information is not upto-date. Hence, the Key
catalog needs to be reloaded before being
used.

FA_Note_ReLoadKeyCatalog

FDK Programmer’s Reference 347

2

FDK Function Reference

F_ApiNotification()

Event or operation

Export

Notification points

Notification constants

FA_Note_PreExport
FA_Note_PostExport
FA_Note_FilterFileToFile
FA_Note_Dialog
FA_Note_Alert
FA_Note_Palette
FA_Note_ToolBar
FA_Note_ConsoleMessage
FA_Note_Help
FA_Note_URL
FA_Note_CursorChange
FA_Note_FontSubstitution
FA_Note_UndoCheckpoint
FA_Note_FileOpen

a. FrameMaker issues the FA_Note_PreInsertElement and FA_Note_PostInsertElement
notifications when the user inserts an element using the element catalog or a menu command or dialog box
which inserts a marker, footnote, cross-reference, equation, anchored frame, or table. FrameMaker does not
issue the FA_Note_PreInsertElement and FA_Note_PostInsertElement notifications when it
automatically inserts elements because the user or a client added rows, columns, or table titles; when the
user or a client imports a graphic; or when a client adds an element programmatically.

The notification constants are numbered sequentially, starting with 0. The API provides
a constant, FA_Note_Num, that specifies the total number of notifications. This makes
it easy to request notification for all notification points, as shown in the following
example code.
Returns
FE_Success if it succeeds, or an error code if it fails.

348

FDK Programmer’s Reference

F_ApiNotify()

...

FDK Function Reference

If F_ApiNotification() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

FE_BadNotificationNum

The specified notification number was invalid

Example
The following code instructs the FrameMaker product to notify your client for all
notification points:
. . .
IntT i;
for (i=0; i < FA_Note_Num; i++)
F_ApiNotification(i, True);
. . .
VoidT F_ApiNotify(notification, docId, sparm, iparm)
IntT notification;
F_ObjHandleT docId;
StringT sparm;
IntT iparm;
{
F_Printf(NULL, "Notification: %d:\n", notification);
}
. . .

See also
“F_ApiNotify()” on page 349.

F_ApiNotify()
F_ApiNotify() is a callback that you can define in your client. The FrameMaker
product calls F_ApiNotify() when the user or another API client initiates an
operation, such as Open or Save, for which your client has requested notification. To
request notification, you must call F_ApiNotification() for each notification
point.
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(),
FDK Programmer’s Reference 349

2

FDK Function Reference

F_ApiNotify()

with the parameter set to FR_CancelOperation, when your client receives
notification for the command. For more information, see “Canceling commands” on
page 221 of the FDK Programmer’s Guide.
..............................................................................

IMPORTANT: If the FrameMaker product encounters an internal error and exits, it
does not send any notification to your client about operations performed after the error
occured. For example, after an error the product allows the user to save changes in
open documents, but it does not notify any clients of the save operations.
..............................................................................

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiNotify(IntT notification,
F_ObjHandleT docId,
StringT sparm,
IntT iparm);

Arguments
notification

A constant that indicates the event and the notification point. See the table
in “F_ApiNotification()” on page 339 for a list of the 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.

sparm

The string, if any, associated with the notification. For example, if the
notification is for an Open or Save operation, sparm specifies the
pathname of the affected file. If the notification is for text entry, sparm
specifies the text the user typed.

iparm

If notification is FA_NotePreFunction or
FA_NotePostFunction, iparm is the f-code for the command. If
notification is FA_NotePreMouseCommand or
FA_NotePostMouseCommand, iparm specifies bit flags specifying
the number of mouse clicks and the modifier keys the user was holding
down. See the table below for a list of the flags.

..............................................................................

IMPORTANT: For book-wide commands, the FrameMaker product posts an
FA_NotePreFunction and FA_NotePostFunction notification for the book file, and for
each document in the book. When trapping book-wide functions, 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 function notifications:

350

FDK Programmer’s Reference

F_ApiNotify()

...

FDK Function Reference

FA_Note_PreFunction (start searching book)
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)

..............................................................................

The following table shows the values sparm has for specific notifications.
Notifications

sparm value

All Open, Save, Print, and Close
notifications for documents
and books

The complete pathname of the document
or book.

FA_Note_PreDistill
FA_Note_PostDistill

When this notification occurs as a result of saving
a document or book as PDF, sparm contains the
complete pathname of thePostScript file that was
generated from the document or book

FA_Note_PreFunction
FA_Note_PostFunction

If the user typed text, the text. If the user applied a
paragraph or character format or a font family, the
name of the format or font family.

FA_Note_PreChangeElement
FA_Note_PostChangeElement

The element tag of the changed structural element.

FA_Note_PreGenerate
FA_Note_PostGenerate

The book’s filename. If the book is untitled, NULL.

FA_Note_PreHypertext

The string of the hypertext command.

FA_Note_PostHypertext

Null

FA_Note_PreImport
FA_Note_PostImport

The name of the imported file.

FA_Note_PreInsertElement

The element tag of the inserted structural element.

FA_Note_PostInsertElement

The element tag of the inserted structural element.

FA_Note_PreOpenBook
FA_Note_PostOpenBook

The complete pathname of the book file. If the
book is untitled, NULL.

FA_Note_PreSetAttrValue
FA_Note_PostSetAttrValue

The attribute name.

FA_Note_PreWrapElement

The element tag of the wrapped structural element.

FA_Note_PostWrapElement

The element tag of the wrapped structural element.

FDK Programmer’s Reference 351

2

FDK Function Reference

F_ApiNotify()

Notifications

sparm value

FA_Note_UpdateDITAReference

DITA Reference type string:


DITA_AUTO



DITA_CONREF



DITA_XREF



DITA_LINK



DITA_TOPICREF



DITA_TOPICSETREF

FA_Note_UpdateDITAReference
s

NULL

FA_Note_PreSwitchView

The name of the new view.

FA_Note_PostSwitchView

The name of the old view.

All other notifications

NULL.

The following table shows the values iparm has for specific notifications.
Notifications

iparm value

FA_Note_PreFunction
FA_Note_PostFunction

The f-code for the command the user invoked. For a
list of f-code constants, see the fcodes.h header
file provided with the FDK.

FA_Note_UpdateAllClientTi

One of the following flags to indicate which text
insets are to be updated:
FV_UpdateAllAutomaticClientTi indicates all
insets with the FP_TiAutomaticUpdate property
set to True.
FV_UpdateAllManualClientTi indicates all
insets with the FP_TiAutomaticUpdate property
set to False.
FV_UpdateAllClientTi indicates all insets
regardless of the setting for the
FP_TiAutomaticUpdate property.

352

FA_Note_UpdateClientTi

The ID of the text inset.

FA_Note_PreHypertext
FA_Note_PostHypertext

The ID of the hypertext object that was activated. If
the hypertext message is for an FDK client, iparm
is the same as the ID passed to the objId parameter
of the client’s F_ApiMessage() callback.

FA_Note_PreGoToXrefSrc
FA_Note_PostGoToXrefSrc

The ID of the associated cross-reference

FDK Programmer’s Reference

F_ApiNotify()

...

FDK Function Reference

Notifications

iparm value

FA_Note_PreMouseCommand
FA_Note_PostMouseCommand

The 8 high bits specify the number of mouse clicks
minus one.
The next 8 bits indicate the modifier key
used:FF_SHIFT_KEY, FF_CONTROL_KEY,
FF_ALT_KEY, or FF_CMD_KEY
The 16 low bits specify the mouse action: for
example, FF_TEXT_SEL if the user is selecting text;
FF_TEXT_EXT if the user is extending an existing
selection; or OBJ_SEL if the user is selecting an
object. For a complete list of the constants for mouse
actions, see /* Mouse actions */ in the
fapidefs.h header file provided with the FDK.

FA_Note_PreInsertElement
FA_Note_PostInsertElement

The ID of the inserted structural element.

FA_Note_PreWrapElement
FA_Note_PostWrapElement

The ID of the newly created structural element.

FA_Note_PreDragElement

The ID of the structural element that is cut if the
operation is completed.

FA_Note_PostDragElement

The ID of the structural element that is pasted if the
operation is completed.

FA_Note_PreSetAttrValue
FA_Note_PostSetAttrValue

The ID of the element for which the attribute is set.

FA_Note_PreImportElemDefs

The ID of the document from which element
definitions are imported.

FA_Note_PreSaveAsPDFDialo
g
FA_Note_PostSaveAsPDFDial
og

When this notification occurs as a result of the user
choosing to save as PDF in the Save As dialog box,
the value is non-zero. When this notification is the
result of the API saving as PDF, the value is zero.

FA_Note_UpdateDITAReferen
ce

The ID of the element to be updated

FDK Programmer’s Reference 353

2

FDK Function Reference

F_ApiObjectValid()

Notifications

iparm value

FA_Note_UpdateDITAReferen
ces

The refType for which DITA references will be
updated. The refType value can be one of:

All other notifications



FV_DITAObjTypeConref: Update all references
of type DITA Conref.



FV_DITAObjTypeXref: Update all references of
type DITA Xref.



FV_DITAObjTypeLink: Update all references of
type DITA Link.



FV_DITAObjTypeTopicref: Update all
references of type DITA Topicref.



FV_DITAObjTypeTopicsetref: Update all
references of type DITA Topicsetref.

0.

Returns
VoidT.
Example
See “Adding the F_ApiNotify() callback” on page 220 of the FDK Programmer’s
Guide.
See also
“F_ApiNotification()” on page 339.

F _ A p i O b je c tVa l i d ( )
F_ApiObjectValid() determines if an object ID identifies an object in the specified
document. An object ID is invalid if the object has been deleted. In general, an object ID
is valid for only one document in a session, so F_ApiObjectValid() is useful for
debugging your clients.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiObjectValid(F_ObjHandleT docId,
F_ObjHandleT objId);

354

FDK Programmer’s Reference

F_ApiOpen()

...

FDK Function Reference

Arguments
docId

The ID of the document containing the object

objId

The ID whose validity you want to determine

Returns
True if the ID identifies an object in the current document, or False if it doesn’t.
If F_ApiObjectValid() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid object ID

Example
The following code determines if an ID is a valid ID for an object in the current
document, and then removes the object:
. . .
F_ObjHandleT docId, objId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
objId = F_ApiGetNamedObject(docId, FO_PgfFmt, "Body");
/* Code that might remove object or invalidate ID here. */
if (F_ApiObjectValid(docId, objId))
F_ApiDelete(docId, objId);
. . .

F_ApiOpen()
F_ApiOpen() opens a document or book. It can also create a new document.
F_ApiOpen() allows you to specify a script (property list) telling the FrameMaker
product how to open or create the file and how to deal with error and warning
conditions. For example, you can specify whether to abort or to continue opening a
document if it contains fonts that are not available. If the file is already open and
invisible, it will make the file visible. If you are using FileNames that have characters
above ASCII 128 see the FrameMaker FAQ on the Developer Web Page.

FDK Programmer’s Reference 355

2

FDK Function Reference

F_ApiOpen()

Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiOpen(StringT fileName,
F_PropValsT *openParamsp,
F_PropValsT **openReturnParamspp);

Arguments
fileName

The full pathname of the file to open. If you are using
F_ApiOpen() to create a document, specify the name 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.

openParamsp

A property list telling the FrameMaker product how to open the
file and how to respond to errors and other conditions. To use the
default list, specify NULL.

openReturnParamspp

A property list that returns the filename and provides information
about how the FrameMaker product opened the file. It must be
initialized before you call F_ApiOpen().

..............................................................................

IMPORTANT: Always initialize the pointer to the property list that you specify for
openReturnParamspp to NULL before you call F_ApiOpen().
..............................................................................

To get a property list to specify for the openParamsp parameter, use
F_ApiGetOpenDefaultParams() or create the list from scratch. For a list of all the
properties an Open script property list can include, see
“F_ApiGetOpenDefaultParams()” on page 219. For an example of how to create a
property list from scratch, see “Example” on page 243 of the FDK Programmer’s
Guide.
To create a new document with F_ApiOpen(), set the FS_NewDoc property in the
openParamsp property list to True.
..............................................................................

IMPORTANT: When creating a new document (FS_NewDoc is True), and you display
the New dialog box (FS_ShowBrowser is True), the user may click Portrait,
Custom, or Landscape. If this occurs, F_ApiOpen() returns 0 and sets FA_errno
to FE_WantsPortrait, FE_WantsCustom, or FE_WantsLandscape. To create
a portrait, custom, or landscape document, use F_ApiCustomDoc() (see
“F_ApiCustomDoc()” on page 119.)
..............................................................................

356

FDK Programmer’s Reference

F_ApiOpen()

...

FDK Function Reference

Returns
The ID of the document or book if it opens it successfully, or 0 if an error occurs.
The property list that openReturnParamspp is set to has the properties shown in the
following table.
Property

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; normally the same value as
FA_errno. If the file is opened successfully, it is set
to FE_Success. See the table below for a list of
possible values.

FS_OpenStatus

A bit field indicating what happened when the file
was opened. See the table below for a list of possible
flags.

Both the FS_OpenNativeError property and the FA_errno global variable
indicate the result of a call to F_ApiOpen(). The following table lists the possible

FDK Programmer’s Reference 357

2

FDK Function Reference

F_ApiOpen()

status flags and the FA_errno and FS_OpenNativeError values associated with
them.
FS_OpenNativeError and
FA_errno values

Possible FS_OpenStatus flags

FE_BadParameter
(file wasn’t opened)

FV_FileHadStructure: file had structured features, but current
FrameMaker product interface is not structured.
FV_FileAlreadyOpenThisSession: file is already open and
script disallowed opening another copy
FV_BadFileType: file was an executable file or other unreadable
type
FV_BadFileName: specified filename was invalid
FV_CantNewBooks: script specified a book that didn’t exist (the
Open operation can’t create a new book)
FV_BadScriptValue: Open script contained an invalid property
value
FV_MissingScript: F_ApiOpen() called without a script
FV_CantForceOpenAsText: Open script attempted to open the
file as text, but file was wrong type
FV_DisallowedType: file was a Frame binary document and the
Open script disallowed it
FV_DocDamagedByTextFilter: file was a text document and
was damaged when it was filtered
FV_DocHeadersDamaged: the document headers were damaged
(probably because of a file system problem)
FV_DocWrongSize: file is the wrong size (probably because of a
file system problem)
FV_ChecksumDamage: bad checksum

FE_SystemError
(file wasn’t opened)

FV_TooManyWindows: too many windows were open
FV_BadTemplate: a bad template was specified
FV_FileNotReadable: don’t have read permission for
the file

358

FDK Programmer’s Reference

F_ApiOpen()

...

FDK Function Reference

FS_OpenNativeError and
FA_errno values

Possible FS_OpenStatus flags

FE_Success
(file was opened)

FV_FileHasNewName: filename was changed from the name
specified in the F_ApiOpen() call
FV_RecoverFileUsed: recover file was present, and it was used
FV_AutoSaveFileUsed: Autosave file was present, and the user
or the Open script chose to use it
FV_FileWasFiltered: file was filterable and it was filtered
FV_FontsWereMapped: the document contained unavailable
fonts, which were mapped to substitute fonts
FV_FontMetricsChanged: the file contained fonts with
changed metrics, but it was opened anyway
FV_FontsMappedInCatalog: the Paragraph or Character
Catalog used unavailable fonts, which were mapped to substitute
fonts
FV_LanguagesWerentFound: the document used some
unavailable languages, but it was opened anyway

FV_FileIsOldVersion: the file was from an old FrameMaker
product version, but the user or the Open script chose to open it
anyway
FV_FileStructureStripped: the file had structured features,
which the user or the Open script chose to strip
FV_FileIsText: the file was a Text Only file, but the user or the
Open script chose to open it anyway
FV_OpenedViewOnly: the user or the Open script chose to open
the file as a View Only file
FV_EditableCopyOpened: the file was in use and the user or
the Open script opened an editable copy
FV_BadFileRefsWereMapped: file reference contained illegal
characters; the illegal characters were converted to something safe
for the current platform
FV_ReferencedFilesWerentFound: imported graphics files
couldn’t be found, but the file was opened anyway

FDK Programmer’s Reference 359

2

FDK Function Reference

F_ApiOpen()

FS_OpenNativeError and
FA_errno values

FE_Success
(file was opened)

Possible FS_OpenStatus flags

FV_UnresolvedXRefs: there were unresolved cross-references,
but the file was opened anyway
FV_UnresolvedTextInsets: there were unresolved text
insets, but the file was opened anyway

FE_Success,
FE_Canceled,
FE_FailedState, or
FE_CanceledByClient

FV_LockWasReset: file lock was reset
FV_LockNotReset: file had lock that wasn’t reset
FV_LockCouldntBeReset: file had lock that couldn’t
be reset
FV_FileWasInUse: file was in use
FV_FileIsViewOnly: file is a View Only file
FV_LockWasInvalid: file had invalid lock
FV_FileIsNotWritable: The file was not writable, and the
user canceled the open via the alert.
FV_FileModDateChanged: The file has changed since the last
time it was opened or saved in the current session.

FE_Canceled
(file wasn’t opened)

FV_CancelUseRecoverFile: a recover file was present, so the
user or the Open script canceled the Open operation
FV_CancelUseAutoSaveFile: an Autosave file was present,
so the user or the Open script canceled the Open operation
FV_CancelFileIsText: the file was text, so the user or the
Open script canceled the Open operation
FV_CancelFileIsInUse: the file was in use, so the user or the
Open script canceled the Open operation
FV_CancelFileHasStructure: the file had structure, so the
user or the script canceled the Open operation
FV_CancelReferencedFilesNotFound: the file contained
referenced files that were not available, so the user or the Open
script canceled the Open operation
FV_CancelLanguagesNotFound: the file contained languages
that weren’t available, so the user or the Open script canceled the
Open operation

360

FDK Programmer’s Reference

F_ApiOpen()

FS_OpenNativeError and
FA_errno values

...

FDK Function Reference

Possible FS_OpenStatus flags

FV_CancelFontsMapped: the document contained fonts that
needed to be mapped to other fonts, so the user or the Open script
canceled the Open operation
FV_CancelFontMetricsChanged: the file contained fonts
with changed metrics, so the user or the Open script canceled the
Open operation
FV_CancelFontsMappedInCatalog: the document’s
Character Catalog or Paragraph Catalog contained fonts that
needed to be mapped to other fonts, so the user or the Open script
canceled the Open operation
FV_CancelFileIsDoc: the file was a document and the Open
script disallowed it
FV_CancelFileIsMIF: the file was a MIF file and the Open
script disallowed it
FV_CancelBook: the file was a book and the Open script
disallowed it
FV_CancelBookMIF: the file was a MIF file and the Open script
disallowed it
FV_CancelFileIsFilterable: the file was a filterable file
and the Open script disallowed it
FV_CancelFileIsOldVersion: the file was from an old
version of a FrameMaker product, so the user or the Open script
canceled the Open operation
FV_CancelFileIsSgml: the file was an SGML document and
the Open script disallowed it
FV_CancelFileIsXML: the file was an XML document and the
Open script disallowed it
FV_CancelFileBrowser: the user canceled the Open operation
from the file browser

FV_CancelTempDiskFull: there was insufficient room on the
disk to cache data while opening the file.

To determine if a particular FS_OpenStatus bit is set, use F_ApiCheckStatus().
For more information, see “F_ApiCheckStatus()” on page 96.
After you are done with the property lists you use to call F_ApiOpen(), use
F_ApiDeallocatePropVals() to deallocate the memory they use.

FDK Programmer’s Reference 361

2

FDK Function Reference

F_ApiOpen()

Example
The following code opens a document named /tmp/my.doc. It creates a property list
that instructs the FrameMaker product to open my.doc in Text Only format,
regardless of its type. If the FrameMaker product opens the file successfully, the client
displays its filename.
. . .
#include "futils.h"
F_PropValsT params, *returnp = NULL;
F_ObjHandleT docId;
IntT i;
UCharT msg[256];
/* Allocate memory for the Open script. */
params = F_ApiAllocatePropVals(1);
if(params.len == 0) return;
/* Open file as Text Only regardless of its type. */
params.val[0].propIdent.num = FS_ForceOpenAsText;
params.val[0].propVal.valType = FT_Integer;
params.val[0].propVal.u.ival = True;
/* Open /tmp/my.doc. */
docId = F_ApiOpen("/tmp/my.doc", ¶ms, &returnp);
/* Get filename of document from return property list. */
if (docId)
{
/* Get index of return property that specifies filename. */
i = F_ApiGetPropIndex(returnp, FS_OpenedFileName);
F_Sprintf(msg, "Opened %s",
returnp->val[i].propVal.u.sval);
F_ApiAlert(msg, FF_ALERT_CONTINUE_NOTE);
}
/* Free memory used by Open scripts. */
F_ApiDeallocatePropVals(¶ms);
F_ApiDeallocatePropVals(returnp);
. . .

362

FDK Programmer’s Reference

F_ApiOpenResource()

...

FDK Function Reference

See also
“F_ApiCheckStatus()” on page 96, “F_ApiGetOpenDefaultParams()” on page 219,
“F_ApiPrintOpenStatus()” on page 370, and “F_ApiSimpleOpen()” on page 465.

F _ A p i O p e n R e so u rce ( )
F_ApiOpenResource() opens a client resource. With this function, you also have
access to FrameMaker cursors.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiOpenResource(IntT resourceType,
StringT resourceName);

Arguments
resourceType

The type of resource to open. To open a dialog resource, specify
FO_DialogResource.

resourceName

The name of the resource to open.

Returns
The ID of the opened resource, or 0 if it can’t open the resource.
If F_ApiOpenResource() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_BadOperation

Function call specified an illegal operation

Example
For two examples, see “F_ApiModalDialog()” on page 303 and
“F_ApiModelessDialog()” on page 305.

See also
“F_ApiModalDialog()” on page 303, “F_ApiModelessDialog()” on page 305, and
“F_ApiSetClientDir()” on page 412.

FDK Programmer’s Reference 363

2

FDK Function Reference

F_ApiPaste()

F_ A p i P a st e ( )
F_ApiPaste() pastes the contents of the FrameMaker product Clipboard into a
specified document at the insertion point. Cutting and Pasting objects will cause
FrameMaker to create a new UID for the pasted object.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiPaste(F_ObjHandleT docId,
IntT flags);

Arguments
docId

The ID of the document to which to paste the selected text.

flags

Bit field that specifies how to paste the text and how to handle interactive alerts. For
default settings, specify 0.

If you specify 0 for flags, F_ApiPaste() suppresses any interactive alerts or
warnings that arise. It also inserts columns to the left of the current columns and rows
above the current row.
You can also OR the following values into flags.
flags constant

Meaning

FF_INTERACTIVE

Prompt user with dialog or alert boxes
that arise.

FF_VISIBLE_ONLY

Cut only the visible portion of the selection.

FF_DONT_DELETE_HIDDEN_TEXT

Don’t replace hidden text.

FF_DONT_APPLY_ALL_ROWS

Don’t apply condition setting on the Clipboard to all
rows. If whole table is selected and the Clipboard
contains condition setting, cancel the paste.

FF_REPLACE_CELLS

Replace selected cells with cells on the Clipboard.

FF_INSERT_BELOW_RIGHT

Add columns to the right of the current column or
below the current row.

When you use F_ApiPaste() to paste table cells into a table, it does not work
exactly like the interactive Paste command. The interactive Paste command
automatically overwrites cells if the Clipboard contains less than an entire row or
column. For example, if the insertion point is in a three-column table and the Clipboard
contains a single cell, the interactive Paste command overwrites the cell containing the
364

FDK Programmer’s Reference

F_ApiPaste()

...

FDK Function Reference

insertion point with the cell on the Clipboard. If two cells in the table are selected, the
Paste command overwrites both of them with the cell on the Clipboard.
By default, F_ApiPaste() does not overwrite any cells. If the Clipboard contains
less than an entire row or column when you call F_ApiPaste(), or of the current
selection is less than an entire row, F_ApiPaste does nothing and returns
FE_BadSelectionForOperation. This ensures that your do not inadvertently
overwrite any cells. To make F_ApiPaste() replace cells with the Clipboard
contents, you must call it with the FF_REPLACE_CELLS flag set.
The FF_INTERACTIVE flag takes precedence over other flags. So, if you specify
FF_INTERACTIVE | FF_DONT_DELETE_HIDDEN_TEXT and the selection contains
hidden text, the FrameMaker product prompts the user and allows the user to choose
whether to delete the hidden text. It is illegal to specify FF_REPLACE_CELLS |
FF_INSERT_BELOW_RIGHT.
Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiPaste() fails, the API assigns one of the following values to FA_errno.
FA_errno value

Meaning

FE_BadOperation

Function call specified an illegal operation

FE_BadDocId

Invalid document ID

FE_BadSelectionForOperation

Current text selection is invalid for this operation

FE_Canceled

User canceled the operation

FDK Programmer’s Reference 365

2

FDK Function Reference

F_ApiPopClipboard()

Example
The following code makes sure the insertion point is an insertion point (not a selection),
and then pastes the text on the Clipboard to it.
. . .
F_TextRangeT tr;
F_ObjHandleT docId;
/* Get text selection. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
/* Make sure selection is an insertion point. */
tr.beg.objId = tr.end.objId;
tr.beg.offset = tr.end.offset;
F_ApiSetTextRange(FV_SessionId, docId, FP_TextSelection, &tr);
/* Paste Clipboard contents. */
F_ApiPaste(docId, 0);
. . .

See also
“F_ApiClear()” on page 100, “F_ApiCopy()” on page 115, and “F_ApiCut()” on
page 123.

F_ApiPopClipboard()
F_ApiPopClipboard() pops the Clipboard stack, moving the entry on the top of the
stack to the Clipboard.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiPopClipboard(VoidT);

Arguments
None.

366

FDK Programmer’s Reference

F_ApiPrintFAErrno()

...

FDK Function Reference

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiPopClipboard() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

FE_BadOperation

Clipboard stack is empty

Example
The following code executes 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(docId, 0);
F_ApiPopClipboard();
. . .

See also
“F_ApiCopy()” on page 115, “F_ApiCut()” on page 123, “F_ApiPaste()” on page 364,
and “F_ApiPushClipboard()” on page 384.

F_ApiPrintFA Errno()
F_ApiPrintFAErrno() prints the current API error status, represented by the global
variable, FA_errno. It is useful for debugging clients.
When an API function fails, it stores an error code in the global variable, FA_errno.
FA_errno retains the error code until 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.
For example, if you call F_ApiNotification() and specify an invalid notification
constant, the API sets FA_errno to FE_BadNotificationNum. If you
FDK Programmer’s Reference 367

2

FDK Function Reference

F_ApiPrintFAErrno()

subsequently call F_ApiPrintFAErrno(), it prints the string
FE_BadNotificationNum.
For a list of error codes and their meanings, see Chapter 5, “Error Codes.”
F_ApiPrintFAErrno() prints to the Frame console..
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPrintFAErrno(VoidT);

Arguments
None.
Returns
VoidT.
If F_ApiPrintFAErrno() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

Example
The following code enables automatic change bars for the current document and uses
F_ApiPrintFAErrno() to check for errors.
. . .
F_ObjHandleT docId;
IntT changeBarsOn;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
FA_errno = FE_Success;
changeBarsOn = F_ApiGetInt(FV_SessionId, docId,
FP_AutoChangeBars);
/* If previous call succeeds, this call prints FE_Success. */
F_ApiPrintFAErrno();
. . .

368

FDK Programmer’s Reference

F_ApiPrintImportStatus()

...

FDK Function Reference

F _ A p i P r i n t I m p o r t St a t u s( )
F_ApiPrintImportStatus() prints status flags returned by F_ApiImport(). It
is useful for debugging your clients.
F_ApiPrintImportStatus() prints to Frame console.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPrintImportStatus(F_PropValsT *p);

Arguments
p

The property list that F_ApiImport() returns in importReturnParamspp

Returns
VoidT.
Example
The following code prints the import status after calling F_ApiImport():
. . .
F_PropValsT params, *returnParamsp = NULL;
F_ObjHandleT docId;
F_TextRangeT tr;
params = F_ApiGetImportDefaultParams();
if(params.len == 0) return;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
F_ApiImport(docId, &tr.beg, "/tmp/frame.doc",
¶ms, &returnParamsp);
F_ApiPrintImportStatus(returnParamsp);
. . .

See also
“F_ApiImport()” on page 286.

FDK Programmer’s Reference 369

2

FDK Function Reference

F_ApiPrintOpenStatus()

F _ A p i P r i n tO p en St a tu s ( )
F_ApiPrintOpenStatus() prints status flags returned by F_ApiOpen(). It is
useful for debugging your clients.
F_ApiPrintOpenStatus() prints to the Frame console..
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPrintOpenStatus(F_PropValsT *p);

Arguments
p

The property list that F_ApiOpen() returns in openReturnParamspp

Returns
VoidT.
Example
The following code prints the open status after calling F_ApiOpen() to open a
document named /tmp/my.doc:
. . .
F_PropValsT params, *returnParamsp = NULL;
F_ObjHandleT docId = 0;
params = F_ApiGetOpenDefaultParams();
docId = F_ApiOpen("/tmp/my.doc", ¶ms, &returnParamsp);
if (!docId) return;
F_ApiPrintOpenStatus(returnParamsp);
. . .

See also
“F_ApiOpen()” on page 355.

F_ApiPrintPropVal()
F_ApiPrintPropVal() prints the value of a specified property. It is useful for
debugging your clients.
F_ApiPrintPropVal() prints to the Frame console.

370

FDK Programmer’s Reference

F_ApiPrintPropVals()

...

FDK Function Reference

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPrintPropVal(F_PropValT *p);

Arguments
p

The property to print

Returns
VoidT.
Example
The following code prints the name of the active document:
. . .
F_PropValT prop;
F_ObjHandleT docId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
prop = F_ApiGetPropVal(FV_SessionId, docId, FP_Name);
F_ApiPrintPropVal(&prop);
. . .

See also
“F_ApiGetPropVal()” on page 232.

F_ApiPrintPropVals()
F_ApiPrintPropVals() prints the values in a specified property list. It is useful for
debugging your clients.
F_ApiPrintPropVals() prints to the Frame console.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPrintPropVals(F_PropValsT *p);

FDK Programmer’s Reference 371

2

FDK Function Reference

F_ApiPrintSaveStatus()

Arguments
p

The property list

Returns
VoidT.
Example
The following code gets the properties for the paragraph containing the insertion point
and prints them to the console:
. . .
F_PropValsT props;
F_TextRangeT tr;
F_ObjHandleT docId, pgfId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
props = F_ApiGetProps(docId, tr.end.objId);
F_ApiPrintPropVals(&props);
. . .

F_ApiPrintSaveSt atus()
F_ApiPrintSaveStatus() prints errors returned by F_ApiSave(). It is useful
for debugging your clients.
F_ApiPrintSaveStatus() prints to the Frame console.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPrintSaveStatus(F_PropValsT *p);

Arguments
p

The property list that F_ApiSave() returns in saveReturnParamspp

Returns
VoidT.

372

FDK Programmer’s Reference

F_ApiPrintTextItem()

...

FDK Function Reference

Example
The following code prints the save status after calling F_ApiSave() to save the
active document as /tmp/my.doc:
. . .
F_PropValsT params, *returnParamsp = NULL;
F_ObjHandleT mydocId;
/* Allocate Save scripts. */
params = F_ApiGetSaveDefaultParams();
if(params.len == 0) return;
/* Save document. */
mydocId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
F_ApiSave(mydocId, "/tmp/my.doc", ¶ms, &returnParamsp);
/* Print save status. */
F_ApiPrintSaveStatus(returnParamsp);
. . .

See also
“F_ApiSave()” on page 399.

F_ApiPrintTe xtItem()
F_ApiPrintTextItem() prints the text in a specified text item. It is useful for
debugging clients.
F_ApiPrintTextItem() prints to the Frame console.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPrintTextItem(F_TextItemT *textItem);

Arguments
textItem

The text item to print

Returns
VoidT.

FDK Programmer’s Reference 373

2

FDK Function Reference

F_ApiPrintTextItems()

Example
The following code prints the first string text item in the paragraph containing the
insertion point:
. . .
F_TextItemsT tis;
F_ObjHandleT docId;
F_TextRangeT tr;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if(tr.beg.objId == 0) return;
tis = F_ApiGetText(docId, tr.beg.objId, FTI_String);
if(tis.len == 0) return;
F_ApiPrintTextItem(&tis.val[0]);
F_ApiDeallocateTextItems(&tis);
. . .

See also
“F_ApiGetText()” on page 249 and “F_ApiPrintTextItems()” on page 374.

F_ApiPrintTe xtItems()
F_ApiPrintTextItems() prints the text in a specified set of text items
(F_TextItemsT structure). It is useful for debugging clients.
F_ApiPrintTextItems() prints to the Frame console.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPrintTextItems(F_TextItemsT *textItems);

Arguments
textItems

Returns
VoidT.

374

FDK Programmer’s Reference

The set of text items to print

F_ApiPrintUpdateBookStatus()

...

FDK Function Reference

Example
The following code prints the string text items in the main flow in the active document:
. . .
F_TextItemsT tis;
F_ObjHandleT docId, flowId;
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
flowId = F_ApiGetId(FV_SessionId, docId, FP_MainFlowInDoc);
tis = F_ApiGetText(docId, flowId, FTI_String);
if(tis.len == 0) return;
F_ApiPrintTextItems(&tis);
F_ApiDeallocateTextItems(&tis);
. . .

See also
“F_ApiGetText()” on page 249 and “F_ApiPrintTextItem()” on page 373.

F_ApiPrintUpdateBookStatus()
F_ApiPrintUpdateBookStatus() prints errors returned by
F_ApiUpdateBook(). It is useful for debugging your clients.
F_ApiPrintUpdateBookStatus() prints to the Frame console.
Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPrintUpdateBookStatus(F_PropValsT *p);

Arguments
p

The property list that F_ApiUpdateBook() returns in updateReturnParamspp

Returns
VoidT.

FDK Programmer’s Reference 375

2

FDK Function Reference

F_ApiProgressBarEx()

Example
The following code prints the update status after calling F_ApiUpdateBook() to
update the active book:
. . .
F_PropValsT params, *returnParamsp = NULL;
F_ObjHandleT bookId;
/* Allocate update scripts. */
params = F_ApiGetUpdateBookDefaultParams();
if(params.len == 0) return;
/* Update book. */
bookId = F_ApiGetId(0, FV_SessionId, FP_ActiveBook;
F_ApiUpdateBook(bookId, ¶ms, &returnParamsp);
/* Print update status. */
F_ApiPrintUpdateBookStatus(returnParamsp);
. . .

See also
“F_ApiSave()” on page 399.

F_ApiProgressBarEx()
F_ApiProgressBarEx() runs a progress bar in a separate thread while the user can
continue working in the background.
Synopsis
#include "fapi.h"
...
StatusT
F_ApiProgressBarEx(BoolT bShow, const F_PropValsT *vals);

376

FDK Programmer’s Reference

F_ApiProgressBarEx()

...

FDK Function Reference

Arguments
One of the following:

bShow

True (Start the progress bar)
False (End the progress bar)
Structure that includes an array of property-value pairs.

vals

Property

FP_DbTitleLabel

Type

Meaning

StringT

Sets the title of the progress bar dialog.

Returns
FE_Success.

St ru cture d

F_ApiPromoteElement()
F_ApiPromoteElement() promotes the selected structural element. The selected
element becomes a sibling of its former parent. It appears immediately after its former
parent. The siblings that follow it become its children.
..............................................................................

IMPORTANT: One structural element must be selected when
F_ApiPromoteElement() is called. The element cannot be the root element or a
child of the root element.
..............................................................................

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPromoteElement(F_ObjHandleT docId);

Arguments
docId

The ID of the document containing the selected structure element

Returns
VoidT.

FDK Programmer’s Reference 377

2

FDK Function Reference

F_ApiProgressBarEx()

If F_ApiPromoteElement() fails, the API assigns one of the following values to
FA_errno.

378

FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product isn’t supported

FE_BadDocId

Invalid document ID

FE_BadSelectionForOperation

Current selection is invalid for this operation

FDK Programmer’s Reference

F_ApiPromptInt()

...

FDK Function Reference

Example
The following code promotes the selected structural element in the active document:
. . .
F_ApiPromoteElement(F_ApiGetId(0, FV_SessionId, FP_ActiveDoc));
. . .

See also
“F_ApiDemoteElement()” on page 154.

F_Api Pro mptInt()
F_ApiPromptInt() displays a dialog box that prompts the user for a single integer
value. It allows you to provide a default value, which appears in the entry field when the
dialog box appears. The dialog box has OK and Cancel buttons. F_ApiPromptInt()
does not assign a value to *intp if the user clicks Cancel. If the user types alphabetic
text after a number, the API ignores the text and just returns the value of the number.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiPromptInt(IntT* intp,
StringT message,
StringT stuffVal);

Arguments
intp

The value in the input field when the user clicks OK.

message

The message that appears in the dialog box. It must be 255 characters or less.

stuffVal

The default value that appears in the input field when the dialog box is first
displayed.

FDK Programmer’s Reference 379

2

FDK Function Reference

F_ApiPromptInt()

Returns
0 if the user clicked OK, or a nonzero value if the user clicked Cancel or an error
occurred.
If F_ApiPromptInt() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

Example
The following code displays the dialog box shown in Figure 2-2:
. . .
#include "futils.h"
IntT err;
IntT ires;
UCharT mesg[256];
err = F_ApiPromptInt(&ires, "Integer?", "1234");
if (err)
F_Sprintf(mesg, "Cancel was pressed, ires is undefined");
else F_Sprintf(mesg, "The value of ires is %d.", ires);
F_ApiAlert(mesg, FF_ALERT_CONTINUE_NOTE);
. . .

Figure 2-2 Integer prompt dialog box

See also
“F_ApiPromptMetric()”, and “F_ApiPromptString()” on page 382.

380

FDK Programmer’s Reference

F_ApiPromptMetric()

...

FDK Function Reference

F_ApiPromptMetric()
F_ApiPromptMetric() displays a dialog box that prompts the user for a single
metric value. It allows you to provide a default value, which appears in the entry field
when the dialog box appears. The dialog box has OK and Cancel buttons.
F_ApiPromptMetric() does not assign a value to *metricp if the user clicks
Cancel.
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 (for
example 10pts or 5"), the API converts the number into the equivalent number of
metric units. If the user doesn’t specify a unit, the API uses points (metric 65536).
Synopsis
#include "fapi.h"
. . .
IntT F_ApiPromptMetric(MetricT *metricp,
StringT message,
StringT stuffVal,
MetricT defaultunit);

Arguments
metricp

The value in the input field when the user clicks OK.

message

The message that appears in the dialog box. It must be 255 characters or
less.

stuffVal

The default value that appears in the input field when the dialog box is first
displayed.

defaultunit

The metric unit to use if the user doesn’t specify one.

Returns
0 if the user clicked OK, or a nonzero value if the user clicked Cancel or an error
occurred.
If F_ApiPromptMetric() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

FDK Programmer’s Reference 381

2

FDK Function Reference

F_ApiPromptString()

Example
The following code displays the dialog box shown in Figure 2-3:
. . .
#include "futils.h"
#define in (MetricT)(65536*72)
IntT err;
MetricT mres;
UCharT mesg[256];
err = F_ApiPromptMetric(&mres, "Metric?", "12.34 in", in);
if (err)
F_Sprintf(mesg, "Cancel was pressed, mres is undefined");
else
F_Sprintf(mesg, "The value of mres is %f inches.", mres/in);
F_ApiAlert(mesg, FF_ALERT_CONTINUE_NOTE);
. . .

Figure 2-3 Metric prompt dialog box

See also
“F_ApiPromptInt()” on page 379 and “F_ApiPromptString()”.

F_Api PromptStri ng()
F_ApiPromptString() displays a dialog box that prompts the user for a single
string value. It allows you to provide a default string, which appears in the entry field
when the dialog box appears. The dialog box has OK and Cancel buttons.
F_ApiPromptString() does not assign a value to *stringp if the user clicks
Cancel.
..............................................................................

IMPORTANT: If you are running your client on Windows, do not call
F_ApiPromptString() to prompt the user for a pathname. If the user enters a
pathname as a string, the backslash character (\) is interpreted as a special escape
character. For example, the characters \s represent a space. If the user enters the

382

FDK Programmer’s Reference

F_ApiPromptString()

...

FDK Function Reference

pathname c:\sample, this string is interpreted as c: ample. To prompt the user for
a pathname, use F_ApiChooseFile() to display a file selection dialog box.
..............................................................................

Synopsis
#include "fapi.h"
. . .
IntT F_ApiPromptString(StringT *stringp,
StringT message,
StringT stuffVal);

Arguments
stringp

The string in the input field when the user clicks OK.

message

The message that appears in the dialog box. It must be 255 characters or less.
Newline and linefeed characters are ignored.

stuffVal

The default value that appears in the input field when the dialog box is first
displayed.

..............................................................................

IMPORTANT: F_ApiPromptString() allocates memory for the string it returns.
Use F_Free() to free the string when you are done with it.
..............................................................................

FDK Programmer’s Reference 383

2

FDK Function Reference

F_ApiPushClipboard()

Returns
0 if the user clicked OK, or a nonzero value if the user clicked Cancel or an error
occurred.
If F_ApiPromptString() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

Example
The following code displays the dialog box shown in Figure 2-4:
. . .
IntT err;
StringT sres;
err = F_ApiPromptString(&sres, "String?", "Default text");
if (err) return;
F_ApiAlert(sres, FF_ALERT_CONTINUE_NOTE);
F_Free(sres);
. . .

Figure 2-4 String prompt dialog box

See also
“F_ApiPromptInt()” on page 379 and “F_ApiPromptMetric()” on page 381.

F_ApiPushClipboard()
F_ApiPushClipboard() pushes the current Clipboard contents onto the Clipboard
stack. It is useful if you want to use FDK Clipboard functions, such as F_ApiCopy()
or F_ApiCut(), without losing the Clipboard’s original contents.

384

FDK Programmer’s Reference

F_ApiQuickSelect()

...

FDK Function Reference

Synopsis
#include "fapi.h"
. . .
VoidT F_ApiPushClipboard(VoidT);

Arguments
None.
Returns
VoidT.
If F_ApiPushClipboard() fails, the API assigns the following value to
FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

Example
See “F_ApiPopClipboard()” on page 366.
See also
“F_ApiCopy()” on page 115, “F_ApiCut()” on page 123, “F_ApiPopClipboard()” on
page 366, and “F_ApiPaste()” on page 364.

F _ A p i Q u i c k S e l ec t ()
F_ApiQuickSelect() implements a quick-key interface that allows the user to
choose a string from a list of strings in the document Tag area.
F_ApiQuickSelect() highlights the document Tag area and displays a prompt and
the first string in a specified list of strings. The user can display a string in the Tag area
by typing the first few letters of the string. The user can also scroll through the strings
by pressing the up and down arrow keys. To choose a string, the user presses Return
when the string appears in the Tag area. To cancel the choice, the user clicks in the
document without pressing Return.

FDK Programmer’s Reference 385

2

FDK Function Reference

F_ApiRedisplay()

Synopsis
#include "fapi.h"
. . .
IntT F_ApiQuickSelect(F_ObjHandleT docId,
StringT prompt,
F_StringsT *stringlist);

Arguments
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

Returns
An index into the array of strings specified by stringlist or -1 if the user cancels
the quick selection.
If F_ApiQuickSelect() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

FE_BadDocId

The specified document ID is invalid

Example
See “Implementing quick keys” on page 228 of the FDK Programmer’s Guide.

F _ A p i R e d i sp l a y ( )
F_ApiRedisplay() updates the display for a specified document to reflect any
changes that occurred while FP_Displaying was set to False. If you have set
FP_Displaying to False and subsequently reset it to True, you should call
F_ApiRedisplay() to redisplay each document you modified.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiRedisplay(F_ObjHandleT docId);

386

FDK Programmer’s Reference

F_ApiRedisplay()

...

FDK Function Reference

Arguments
docId

The ID of the document to be redisplayed

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiRedisplay() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Invalid document ID

Example
The following code disables redisplaying, and then reenables it and redisplays all the
documents in the session:
. . .
F_ObjHandleT docId;
F_ApiSetInt(0, FV_SessionId, FP_Displaying, False);
/* Code to change documents without reformatting goes here.

*/

F_ApiSetInt(0, FV_SessionId, FP_Displaying, True);
/* Redisplay all the documents in the session. */
docId = F_ApiGetId(0, FV_SessionId, FP_FirstOpenDoc);
while (docId)
{
F_ApiRedisplay(docId);
docId = F_ApiGetId(FV_SessionId, docId,
FP_NextOpenDocInSession);
}
. . .

See also
“F_ApiReformat()”.

FDK Programmer’s Reference 387

2

FDK Function Reference

F_ApiReformat()

F_ApiReformat()
F_ApiReformat() reformats the specified document. If you have disabled and
subsequently reenabled reformatting by setting the session property,
FP_Reformatting, you should then call F_ApiReformat() to reformat each
changed document in the session.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiReformat(F_ObjHandleT docId);

Arguments
docId

The ID of the document to reformat

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiReformat() fails, the API assigns the following value to FA_errno.

388

FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FDK Programmer’s Reference

F_ApiRehyphenate()

...

FDK Function Reference

Example
The following code disables reformatting, and then reenables it and reformats all the
documents in the session:
. . .
F_ObjHandleT docId;
F_ApiSetInt(0, FV_SessionId, FP_Reformatting, False);
/* Code to change documents without reformatting goes here.

*/

F_ApiSetInt(0, FV_SessionId, FP_Reformatting, True);
/* Reformat all the documents in the session. */
docId = F_ApiGetId(0, FV_SessionId, FP_FirstOpenDoc);
while (docId)
{
F_ApiReformat(docId);
docId = F_ApiGetId(FV_SessionId, docId,
FP_NextOpenDocInSession);
}
. . .

F_ApiRehyphenate()
F_ApiRehyphenate() rehyphenates a specified document based on changes the user
has made to words’ hyphenation points.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiRehyphenate(F_ObjHandleT docId);

Arguments
docId

The ID of the document to rehyphenate

Returns
FE_Success if it succeeds, or an error code if an error occurs.

FDK Programmer’s Reference 389

2

FDK Function Reference

F_ApiResetEqnSettings()

If F_ApiRehyphenate() fails, the API assigns one of the following values to
FA_errno.
FA_errno value

Meaning

FE_BadDocId

Bad document or book ID

FE_WrongProduct

Current FrameMaker product doesn’t support this operation

FE_SystemError

Couldn’t allocate memory

Example
The following code rehyphenates the active document:
. . .
F_ApiRehyphenate(F_ApiGetId(0, FV_SessionId, FP_ActiveDoc));
. . .

F_ApiResetEqnSettings()
F_ApiResetEqnSettings() resets the document equation settings to the default
settings.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiResetEqnSettings(F_ObjHandleT docId);

Arguments
docId

The ID of the document for which to reset equation settings

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiResetEqnSettings() fails, the API assigns one of the following values to
FA_errno.

390

FA_errno value

Meaning

FE_BadDocId

Bad document or book ID

FDK Programmer’s Reference

F_ApiResetReferenceFrames()

FA_errno value

Meaning

FE_WrongProduct

Current FrameMaker product doesn’t support this operation

FE_SystemError

Couldn’t allocate memory

...

FDK Function Reference

Example
The following code resets the equation settings for the active document:
. . .
F_ApiResetEqnSettings(F_ApiGetId(0,FV_SessionId, FP_ActiveDoc));
. . .

F_ApiResetReferenceFrames()
F_ApiResetReferenceFrames() resets the reference frames in the specified
document. It is useful for updating a document after you have programmatically
changed a reference frame that is referenced by paragraphs in the document.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiResetReferenceFrames(F_ObjHandleT docId);

Arguments
docId

The ID of the document for which to reset reference frames

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiResetReferenceFrames() fails, the API assigns one of the following
values to FA_errno.
FA_errno value

Meaning

FE_BadDocId

Bad document or book ID

FE_WrongProduct

Current FrameMaker product doesn’t support this operation

FE_SystemError

Couldn’t allocate memory

FDK Programmer’s Reference 391

2

FDK Function Reference

F_ApiRestartPgfNumbering()

Example
The following code resets reference frames for the active document:
. . .
F_ApiResetReferenceFrames(F_ApiGetId(0, FV_SessionId,
FP_ActiveDoc));
. . .

F_ApiRestartPgfNumbering()
F_ApiRestartPgfNumbering() restarts the paragraph numbering for a specified
document. For more information on paragraph numbering, see your FrameMaker
product user documentation.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiRestartPgfNumbering(F_ObjHandleT docId);

Arguments
docId

The ID of the document for which to restart paragraph numbering

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiRestartPgfNumbering() fails, the API assigns one of the following
values to FA_errno.

392

FA_errno value

Meaning

FE_BadDocId

Bad document or book ID

FE_WrongProduct

Current FrameMaker product doesn’t support books

FE_SystemError

Couldn’t allocate memory

FDK Programmer’s Reference

F_ApiReturnValue()

...

FDK Function Reference

Example
The following code restarts paragraph numbering for the active document:
. . .
F_ApiRestartPgfNumbering(F_ApiGetId(0, FV_SessionId,
FP_ActiveDoc));
. . .

F _ A p i R e t u r n Va l u e ( )
F_ApiReturnValue() sets a return value for a client-defined callback. It allows a
client to provide status information to the FrameMaker product or client that called the
callback. You can call it in the following callbacks:


F_ApiDialogEvent()



F_ApiNotify()

F_ApiReturnValue() is useful for canceling FrameMaker product operations.
When your client receives a FA_Pre
notification for an
operation, it can cancel the operation by calling F_ApiReturnValue() with
retval set to FR_CancelOperation. For example, if your client’s
F_ApiNotify() callback responds to all FA_Note_PrePrint notifications by
calling F_ApiReturnValue() with retval set to FR_CancelOperation, the
FrameMaker product cancels all print operations.
Your client can also call F_ApiReturnValue() to respond to a
FA_Note_ClientCall notification. The API returns the value specified by retval
to the client that called F_ApiCallClient().
Your client can also call F_ApiReturnValue() in a F_ApiDialogEvent()
callback to prevent the FrameMaker product from closing a modal dialog box.
Your client can call F_ApiReturnValue() several times in a callback function. The
last call it makes before the callback returns overrides any previous calls.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiReturnValue(IntT retval);

FDK Programmer’s Reference 393

2

FDK Function Reference

F_ApiReturnValue()

Arguments
retval

The value to return

You can set retval to any integer. If you client sets retval in response to one of
the following notifications, it can use the listed constants.

Notification

Values client can pass to
F_ApiReturnValue()

FA_Note_DisplayClient
TiDialog

FR_Displayed
TiDialog

The client has displayed
its version of the Text
Inset Properties dialog
box

FR_DisplayedXRe
fDialog

If the client displays or
updates its crossreference dialog, it sets
the return value as
FR_DisplayedXRefD
ialog.If this return
value is not set,
FrameMaker assumes
that the client did not
display any dialog and
the standard crossreference dialog is
displayed.

FA_PreNotificationPoint

FR_Cancel
Operation

Cancel the operation for
which the notification
was issued

FA_Note_PreSaveAsPDF
Dialog

FR_Cancel
Operation

Cancel the Save as PDF
operation

FR_SkipStep

Do not display the
Acrobat Settings dialog
box

FA_Note_PostSaveAsPDF
Dialog

FR_Cancel
Operation

Cancel the Save as PDF
operationa

FA_Note_PreDistill

FR_Cancel
Operation

Cancel the Save as PDF
operation

FA_Note_ClientCall

Any value recognized
by the client that called
F_ApiCallClient(
)

Client-defined

FA_Note_DisplayClientXRef
Dialog

394

FDK Programmer’s Reference

Meaning

F_ApiReturnValue()

Notification

Values client can pass to
F_ApiReturnValue()

...

FDK Function Reference

Meaning

The ID of the
document into which
the file was filtered

The document was
filtered successfully

0

The document was not
filtered successfully

FA_Note_IsCommandEnabled

FR_CommandEnabl
ed

Return value to be used
in response to
notification
FA_Note_IsCommand
Enabled if command
should be enabled.

FA_Note_IsCommandEnabled

FR_CommandDisab
led

Return value to be used
in response to
notification
FA_Note_IsCommand
Enabled if command
should be disabled

FA_Note_FilterIn

a. Note that this event occurs before the distilling operation begins. You can now cancel the operation after the
user closes Save As PDF dialog box.

If your client calls F_ApiReturnValue() for notifications other than those listed
above, it has no effect.
A client can also call F_ApiReturnValue() in a F_ApiDialogEvent() callback
that responds to actions in a client-defined modal dialog box. Normally, when the user
clicks a button in a client-defined modal dialog box, the FrameMaker product calls the
client’s F_ApiDialogEvent() callback and then closes the dialog box. However, if
the client’s F_ApiDialogEvent() callback calls F_ApiReturnValue() with
retVal set to FR_DialogStayUp, the FrameMaker product does not close the
dialog box. The following table lists the values a client can pass to
F_ApiReturnValue() in an F_ApiDialogEvent() callback.
Values client can pass to F_ApiReturnValue()

Meaning

FR_DialogStayUp

Do not close the modal dialog box in which
the event occurred

Any other value

Close the modal dialog box

Returns
The value of the retval parameter the previous time F_ApiReturnValue() was
called in the current callback function.

FDK Programmer’s Reference 395

2

FDK Function Reference

F_ApiReturnValue()

If F_ApiReturnValue() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_Transport

A transport error occurred

Example
See “F_ApiCallClient()” on page 93 and “Handling user actions in multiple modeless
dialog boxes” on page 454 of the FDK Programmer’s Guide.
See also
“F_ApiDialogEvent()” on page 155, “F_ApiNotify()” on page 349, and
“F_ApiCallClient()” on page 93.
St ru cture d

F_ApiRun()
F_ApiRun() provides the minimum functionality required in an FDK client’s
main() function.
..............................................................................

IMPORTANT: F_ApiRun() is available only to Windows RPC clients.

..............................................................................

Synopsis
#include "fapi.h"
. . .
IntT F_ApiRun(VoidT);

Arguments
None.
Returns
FE_Success if it succeeds, or a nonzero value if an error occurs.

396

FDK Programmer’s Reference

F_ApiReturnValue()

...

FDK Function Reference

C++ clients that need to include their own main() functions can call F_ApiRun().
F_ApiRun() is defined as:
IntT F_ApiRun()
{
StringT s;
if (s = F_ApiStartUp(NULL))
F_ApiErr(s);
else
while (!FA_bailout)
F_ApiService(0);
F_ApiShutDown();
return(s!=NULL);
}

Example
The following code can be used as the main function for an FDK client written in C++:
int main() {return (F_ApiRun());}

FDK Programmer’s Reference 397

2

FDK Function Reference

F_ApiReturnValue()

See also
“F_ApiShutDown()” on page 455, “F_ApiService()” on page 405, and “F_ApiErr()” on
page 164.

398

FDK Programmer’s Reference

F_ApiSave()

2

...

FDK Reference

FrameMaker+SGMLFDK Fnction Reference

F_ApiSave()
F_ApiSave() saves a document or book. It allows you to script the way the
FrameMaker product saves the file and to specify responses to warnings and messages
that arise while the file is being saved. You can save a file under its current name or save
it as a new file.
Synopsis
#include "fapi.h"
. . .
F_ObjHandleT F_ApiSave(F_ObjHandleT Id,
StringT saveAsName,
F_PropValsT *saveParamsp,
F_PropValsT **saveReturnParamspp);

Arguments
Id

The ID of the document or book to save.

saveAsName

The pathname for saving the document or book.

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.

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().
..............................................................................

To get a property list for saveParamsp, you can use
F_ApiGetSaveDefaultParams() and modify individual properties in the list it
returns, or you can create a list from scratch. For information on
F_ApiGetSaveDefaultParams(), see “F_ApiGetSaveDefaultParams()” on
page 234. For information on creating a property list from scratch, see “Creating a
saveParamsp script from scratch” on page 255 of the FDK Programmer’s Guide.

FDK Programmer’s Reference 399

6

FDK Function Reference

F_ApiSave()

The property list returned in saveReturnParamspp has the properties shown in the
following table.
Property

Meaning and possible values

FS_SavedFileName

A string that specifies the saved file’s full pathname.

FS_SaveNativeError

The error condition. If the file is saved successfully, it is
set to FE_Success. See the table below for the
possible values.

FS_SaveStatus

A bit field indicating what happened when the file was
saved. See the table below for the possible values.

Both the FS_SaveNativeError property and the FA_errno global variable
indicate the result of a call to F_ApiSave(). The FS_SaveStatus flags indicate
how or why this result occurred. The following table lists the possible status flags and
the FA_errno and FS_SaveNativeError values associated with them.
FS_SaveNativeError and
FA_errno values

Possible FS_SaveStatus flags

FE_Success

None.

FE_Canceled or
FE_CanceledByClient
(file wasn’t saved)

FV_FileNotWritable: file was not writable.
FV_BadSaveFileName: specified file name is not allowed by
the operating system.
FV_BadFileId: the file’s operating system ID was bad.
FV_BadSaveScriptValue: script specified by
saveParamsp had an invalid value.
FV_CancelSaveFileIsInUse: The file is in use and the user
did not or could not reset the lock. Or the file is in use, and the
FS_FileIsInUse script is set to FV_DoCancel, or it is set to
FV_ResetLockAndContinue but the FrameMaker product
could not reset the lock.
FV_CancelSaveModDateChanged: The file has changed since
the last time it was opened or saved in the current session.
FV_FileWasInUse: file was in use.
FV_LockCouldntBeReset: file lock couldn’t be reset.
FV_LockWasReset: file lock was reset.
FV_LockNotReset: file lock was not reset.

400

FDK Programmer’s Reference

F_ApiSave()

FS_SaveNativeError and
FA_errno values

...

FDK Reference

Possible FS_SaveStatus flags

FE_Canceled or
FE_CanceledByClient
(file wasn’t saved)

FV_FileIsViewOnly: file was View Only.

FE_WrongProduct

None. Current FrameMaker product doesn’t support this
operation

FE_FailedState or
FE_BadParameter

None. The filename was invalid.

FE_FilterFailed

FV_InvalidSaveFilter: The filter specified by
FS_SaveFileTypeHint is not installed, or the syntax for
FS_SaveFileTypeHint is invalid.

After you are done with the property lists you use to call F_ApiSave(), use
F_ApiDeallocatePropVals() to deallocate the memory they use.
Returns
The ID of the document it saved, or 0 if it fails.
Example
See “Example” on page 257 of the FDK Programmer’s Guide and
“F_ApiGetSaveDefaultParams()” on page 234.

See also
“F_ApiDeallocateStructureType()” on page 125, “F_ApiGetSaveDefaultParams()” on
page 234, “F_ApiPrintSaveStatus()” on page 372, and “F_ApiSimpleSave()” on
page 466.

FDK Programmer’s Reference 401

6

FDK Function Reference

F_ApiScrollBox()

F_ApiScrollBox()
F_ApiScrollBox() displays an array of items and allows the user to
choose one.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiScrollBox(IntT *selected_item,
StringT title,
F_StringsT *stringslist
IntT default);

Arguments
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.

stringslist

The list of items to appear in the scroll list.

default

The index of the item that is selected when the dialog box first appears.
For no default, specify -1.

..............................................................................

IMPORTANT: If you set default to -1, always check to make sure the value
returned in selected_item is 0 or greater before you use it as an array index. If
you set default to -1 and the user clicks OK without choosing an item, the value
returned in selected_item will be -1.
..............................................................................

F_StringsT is defined as:
typedef struct {
UIntT len; /* Number of strings */
StringT *val; /* Array of strings */
} F_StringsT;

Returns
0 if the user clicked OK, or a nonzero value if the user clicked Cancel or an error
occurred.

402

FDK Programmer’s Reference

F_ApiScrollBox()

...

FDK Reference

If F_ApiScrollBox() fails, the API assigns the following value to FA_errno.
FA_errno value

Meaning

FE_Transport

The user clicked Cancel, or a transport error occurred

Example
The following code displays a scroll list dialog box, with a default item labeled “Kurt”:
. . .
#include "futils.h"
IntT choice, err;
UCharT msg[256];
F_StringsT names;
StringT nameList[4];
nameList[0]
nameList[1]
nameList[2]
nameList[3]

=
=
=
=

(StringT)"Kelly";
(StringT)"Jens";
(StringT)"Kurt";
(StringT)"Heycke";

names.len = 4;
names.val = nameList;
err = F_ApiScrollBox(&choice, "Choose a name.", &names, 2);
if (!err)
F_Sprintf(msg, "The name is %s.", nameList[choice]);
else
F_Sprintf(msg, "Cancel was pressed");
F_ApiAlert(msg, FF_ALERT_CONTINUE_NOTE);
. . .

See also
“F_ApiChooseFile()” on page 97.

FDK Programmer’s Reference 403

6

FDK Function Reference

F_ApiScrollToText()

F _ A p i S c ro l l To Te x t( )
F_ApiScrollToText() scrolls the document window to a specified text range. It
scrolls to the end of the range that is closest to the current display position.
Synopsis
#include "fapi.h"
. . .
IntT F_ApiScrollToText(F_ObjHandleT docId,
F_TextRangeT *textRangep);

Arguments
docId

The ID of the document containing the text range

textRangep

The text range to which to scroll

Returns
FE_Success if it succeeds, or an error code if an error occurs.
If F_ApiScrollToText() fails, the API assigns one of the following values to
FA_errno.

404

FA_errno value

Meaning

FE_BadDocId

Invalid document ID

FE_BadObjId

Invalid object ID

FE_NotTextObject

One or both of the IDs specified by textRangep is not the ID of
an object that contains text, such as a paragraph (FO_Pgf) or a
flow (FO_Flow)

FE_OffsetNotFound

Offset specified for the text range couldn’t be found in the
specified paragraph or text line

FE_BadRange

Specified text range is invalid

FDK Programmer’s Reference

F_ApiService()

...

FDK Reference

Example
The following code scrolls the document window to the insertion point or the end of the
text selection:
. . .
F_ObjHandleT docId;
F_TextRangeT tr;
/* Get the insertion point or text selection. */
docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);
tr = F_ApiGetTextRange(FV_SessionId, docId, FP_TextSelection);
if (tr.beg.objId == 0) return;
/* Scroll to it. */
F_ApiScrollToText(docId, &tr);
. . .

See also
“F_ApiCenterOnText()” on page 94.

F_ApiService()
F_ApiService() services calls from the FrameMaker product to the API.
F_ApiService() is useful only if you are providing a replacement for
F_ApiRun()—for example, if your client needs to select on its own file descriptors.
On Windows, F_ApiService parameters are ignored. F_ApiService() waits for and
dispatches a single Windows message. If your application contains its own message
processing loop you need not call this routine. It is not generally feasible for console
applications to receive FDK notifications since there is no way for them to both wait for
user imput and call F_ApiService(). Consequently, console applications should not
register for notifications.
..............................................................................

IMPORTANT: F_ApiService() is only available to Windows RPC clients.
..............................................................................

Synopsis
#include "fapi.h"
. . .
IntT F_ApiService(IntT *imaskp);

FDK Programmer’s Reference 405

6

FDK Function Reference

F_ApiService()

Arguments
imaskp

The address of an integer select() mask.

Returns
The number of bits the call to select() selected, if any.
If you want other file descriptors to be active at the same time as the API “listen” port,
set imaskp to the address of an integer select() mask that you want to OR into
the F_ApiService() function’s call to select(). If the call to select() selects
on any of the parameter’s file descriptors, F_ApiService() returns the number of the
bits, and puts the bits into *imaskp.
Example
The following code sets as the input file descriptor the shell window from which you
start the FrameMaker product and processes requests from that file descriptor:
. . .
/* Set the shell window as the input fd. */
in_fd = open("/dev/tty",O_RDONLY);
/* Start API. If it fails to start, exit and print error.*/
if (s = F_ApiStartUp(NULL))
F_ApiErr(s);
else
while (!FA_bailout)
{
myfds = 1<
Source Exif Data: 
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.6
Linearized                      : Yes
Author                          : Adobe Systems Incorporated
Create Date                     : 2012:11:07 12:37:33Z
Keywords                        : FDK, Programmer’s Reference, Documentation, API, C, Plugins, Clients
Modify Date                     : 2013:02:15 09:03:18+01:00
Subject                         : FDK Documentation
Has XFA                         : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Creator Tool                    : FrameMaker 11.0
Metadata Date                   : 2013:02:15 09:03:18+01:00
Format                          : application/pdf
Description                     : FDK Documentation
Title                           : FDK Programmer’s Reference
Creator                         : Adobe Systems Incorporated
Producer                        : Acrobat Distiller 10.1.4 (Windows)
Document ID                     : uuid:359a4458-48b4-4bf3-986a-996a10537d5d
Instance ID                     : uuid:503860f2-d4fd-5c4d-a32e-373fbe73fa5e
Page Mode                       : UseOutlines
Page Count                      : 1049
EXIF Metadata provided by EXIF.tools

Navigation menu