Macromedia FrameMaker - 7.0 User Guide
FDK 7.0
Programmer’s
Guide
© 2002 Adobe Systems Incorporated. All rights reser ved.
Adobe FrameM aker 7.0 User Guide for Windows, Macintos h, and UNIX
This manual, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such
license. The content of this ma nual is furnished for information al us e onl y, is subject to change without noti c e, and should not be construed as a
commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that
may appear in this book.
Except as permitted by such license, no part of this publication ma y be reproduced, stored in a retrieval system, or transmitted, in any form or by
any means, electronic, mechanical, recording, or othe rw ise , without the prior written permission of A dobe Systems Incorporated.
Please remember that existing artwork or images that you ma y w a nt t o inc lu de in your project may be protected un der copyright law. The
unauthorized incorpora ti on of suc h m at er ia l in to your ne w w ork could be a violation of the right s of the cop yright owner. Please be sure to obtain
any permission required from the copyright owner.
Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization.
Adobe, the Adobe logo, Ac robat, Acrobat Reader, Adobe Typ e Ma na ge r, ATM, D ispl a y PostSc ri pt, Dist il ler, Exchange, Frame, FrameM aker,
FrameViewer, InstantView, and PostScript are trademarks of Adobe Systems Incorporated.
Apple, Power Book, QuickT ime, Mac int osh a nd Power Maci ntos h are tradem arks of A pple Com puter , Inc. , re giste red in the Un ited Stat es and othe r
countries. Fo coltone is a re gistered trademark of Gordon Phil lips Limite d. ImageStr eam Graphic s Filters and ImageStream are registered trademarks
of Inso Corporation. Microsoft, MS-DOS, Windows, and Windows NT are either reg is tered trademarks or trademarks of Micro s of t Corporation in
the United States and/or other countries. Quadralay and WebWorks are registered trademarks of Quadralay Corporation. PANTONE, PANTONE
MATCHING SYSTEM, PANTONE Process Color System, and POCE are trademar ks of Pantone, Inc. Proximity and Linguibase are
registered trad emar ks of P ro ximit y Techn olo gy I nc. A Me rri am-We bs ter is a re gi ste red trad emar k of Mer ria m- Webst er Inc . Su n is a trad emar k or
registered trademark of Sun Microsystems, Inc. in the United States and other countries. TRUMATCH is a registered trademark of Trumatch Inc.
Unix is a registered trademark and X Window System is a trademark of The Open Group. Verity and TOPIC are registered trademarks of Verity,
Inc. All other trademarks are property of their respective owners.
The following are co pyrights of their respective com panies or organizations: Portions reproduced with the pe rm issi on of Apple Computer, Inc .
© 1996 Apple Computer, Inc. Milo © 1988 Ron Avitzur PANTONE
solid color standards. Use current PANTONE Color Reference Manuals for accurat e color. “PANTONE Open Color Environ me nt
© Pantone, Inc., 1994, 199 6. Pant one, Inc. is the copyright own er of “PANTONE Open Colo r E nvi ronment
licensed to Adobe to distribute for use only in combination with the A dobe Software. “PANTONE Op en Color Environment
®
Computer Video simulations displayed may not match PANTONE-identified
™
(POCE™)” and Software which are
™
(POCE™)”
™
(POCE™)” and
Software shall not be copied onto another diskette or into memory unless as part of the execution of the Adobe Software. The Spelling and Thesaurus
portions of this product are based on Prox imi ty L in gui sti c T echnology. The Proximity/Merri am -W ebster Linguibase © 1983, 1990 MerriamWebster, Inc. C.A. Stromberg AB; Espasa -Calpe; Hach ette; IDE /AS; Kruger; Llui s de Yzaguirre i Maura; Merri am-Webster Inc.; Munksgaard Int.
Publishers Ltd.; Nathan; Text & Satz Datentechnik; Van Dale Lexicographie bv; William Collins Sons & Co. Ltd.; Zanichelli. All rights reserved.
Color Database © Dainippon Ink & Chemicals, Inc., licen s ed t o A dobe. Outside In
®
Graphics and Presentation Filters, 1992-1996 Inso Corporation. All rights reserved. TRUMATCH 4-Color Selector © 1992 Trumatch, Inc.
Stream
®
Viewer Technology, 1 992-1996 Inso Corporation; Ima ge
All rights reserved. Portions co pyrighted for the FrameViewer Retrieval Tools © 1988-1995 Verity, Inc . All right s reserved.
APPLE COMPUTER, INC. (“APPLE”) MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THE APPLE
SOFTWARE. APPLE DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTA-TIONS REGARDING THE USE OR THE
RESULTS OF THE USE OF THE APPLE S OFTWARE IN TERM S OF ITS COR RECTNESS, ACC URACY, RELI ABILITY, CU RRENTNESS,
OR OTHERWISE. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE APPLE SOFTWARE IS ASSUMED BY YOU.
THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY
TO YOU.
IN NO EVENT WILL APPLE, ITS DIRECTORS, OFFICERS, EMPLOYEES, OR AGENTS BE LIABLE TO YOU FOR ANY
CONSEQUENTIAL, INCIDENTAL, OR INDIRECT DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS
INTERRUPTION, LOSS OF BUSINESS INFORMATION, AND THE LIKE) ARISING OUT OF THE USE OR INABILITY TO USE THE
APPLE SOFTWARE EVEN IF APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES DO
NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE
LIMITATIONS MAY NOT APPLY TO YOU.
Adobe Systems Incorporated, 345 Park Ave nue, San Jose, California 95110, USA
Notice to U.S. gov ernment end users. Th e s o ft w are and documentat ion are “commerci al items,” as that te rm 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 applicabl e. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.72 02-4, as applicable, the
commercial computer softwa re and commercial computer soft w ar e do cumentation are being licensed to U.S. government end users (A) only as
commercial items and (B) with onl y th ose rights as are granted to all other end users pursuant to the terms and conditions set forth in the Adobe
standard commercial agreement for this software. Unpublishe d rights reserved under the copyrig ht laws of t he United States.
ii FDK Programmer’s Guide
Contents
Using Frame Developer Tools . . . . . . . . . . . . . . . . . . . . . . . ix
The Frame Developer’s Kit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix
Other FrameMaker features for developers . . . . . . . . . . . . . . . . . . . . . . . . . . x
Choosing the right Frame tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi
FDK documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi
Naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Style conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Part I: Frame Application Program Interface (API)
Chapter 1 Introduction to the Frame API . . . . . . . . . . . . . . . . 3
How the API works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Special types of clients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Portability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Running clients with different FrameMaker product interfaces. . . . . . . . . . . . . . . . . 6
Creating and running a client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
A simple example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Chapter 2 API Client Initialization . . . . . . . . . . . . . . . . . . . 13
Responding to the FrameMaker product’s initialization call . . . . . . . . . . . . . . . . . 13
Initialization types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Disabling the API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chapter 3 Creating Your Client’s User Interface . . . . . . . . . . . . 17
Using API dialog boxes to prompt the user for input . . . . . . . . . . . . . . . . . . . . . 17
Using commands, menu items, and menus in your client . . . . . . . . . . . . . . . . . . 24
Replacing FrameMaker product menus and commands. . . . . . . . . . . . . . . . . . . 30
Allowing users to configure your client’s interface . . . . . . . . . . . . . . . . . . . . . . 30
Using hypertext commands in your client’s user interface . . . . . . . . . . . . . . . . . . 31
FDK Programmer’ s Guide iii
Responding to user-initiated events or FrameMaker product operations . . . . . . . . . . 34
Implementing quick keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Freeing system resources by bailing out. . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Chapter 4 Executing Commands with API Functions . . . . . . . . . 45
Handling errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Handling messages and warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Opening documents and books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Creating documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Printing documents and books. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Saving documents and books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Closing documents and books. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Quitting a Frame session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Comparing documents and books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Updating and generating documents and books. . . . . . . . . . . . . . . . . . . . . . . 70
Simulating user input. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Straddling table cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Executing Structured FrameMaker commands . . . . . . . . . . . . . . . . . . . . . . . 76
Chapter 5 Getting and Setting Proper ties . . . . . . . . . . . . . . . 81
What you can do with object properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Getting the IDs of the objects you want to change. . . . . . . . . . . . . . . . . . . . . . 82
Manipulating properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Getting and setting session properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Getting and setting document properties . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Getting and setting graphic object properties . . . . . . . . . . . . . . . . . . . . . . . . 99
Getting and setting paragraph properties . . . . . . . . . . . . . . . . . . . . . . . . . .102
Getting and setting book properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Getting and setting FrameMaker properties . . . . . . . . . . . . . . . . . . . . . . . . .105
Chapter 6 Manipulating Text . . . . . . . . . . . . . . . . . . . . . 111
Getting text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
Getting and setting the insertion point or text selection . . . . . . . . . . . . . . . . . . .114
Adding and deleting text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
iv FD K Programmer’s Guide
Getting and setting text formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Executing Clipboard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Chapter 7 Manipulating Asian Text . . . . . . . . . . . . . . . . . . 131
Creating a rubi group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Text encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Using encoding data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Inspecting and manipulating encoded text. . . . . . . . . . . . . . . . . . . . . . . . . .138
Parsing an encoded string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Getting the encoding for a text item . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Special issues with double byte encodings . . . . . . . . . . . . . . . . . . . . . . . . .140
Chapter 8 Creating and Deleting API Objects . . . . . . . . . . . . 143
Creating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Deleting objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Implicit property changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Chapter 9 Manipulating Commands and Menus with the API . . . . 161
How the API represents commands and menus. . . . . . . . . . . . . . . . . . . . . . .161
Getting the IDs of commands and menus . . . . . . . . . . . . . . . . . . . . . . . . . .163
Determining a session’s menu configuration. . . . . . . . . . . . . . . . . . . . . . . . .164
Arranging menus and menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Getting and setting menu item labels . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Manipulating expandomatic menu items. . . . . . . . . . . . . . . . . . . . . . . . . . .172
Using check marks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Using context-sensitive commands and menu items . . . . . . . . . . . . . . . . . . . .173
Providing context-sensitive Help for client menu items . . . . . . . . . . . . . . . . . . .175
Chapter 10 Creating Custom Dialog Boxes for Your Client . . . . . . 177
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
How to create a dialog box. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
Creating a DRE file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
Designing the layout of the dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
Setting the properties of the dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . .193
Setting the properties of a dialog item . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
FDK Programmer’ s Guide v
Saving a DRE file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
Testing a dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
A simple example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
General tips for dialog editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Summary of keyboard shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Chapter 11 Handling Custom Dialog Box Events . . . . . . . . . . . 211
How the API represents dialog boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . .211
Overview of using a custom dialog box in your client . . . . . . . . . . . . . . . . . . . .214
Opening dialog resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
Initializing items in a dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .218
Displaying a dialog box. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Updating items in a dialog box. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
Handling user actions in dialog boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
Closing a dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227
Chapter 12 Using Imported Files and Insets . . . . . . . . . . . . . 229
Types of imported files and insets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
Importing text and graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Updating text insets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
Client text insets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
Writing filter clients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
Specifying format IDs and filetype hint strings . . . . . . . . . . . . . . . . . . . . . . . .247
Associating a file format with signature bytes . . . . . . . . . . . . . . . . . . . . . . . .255
Writing graphic inset editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
Part II: Frame Product Architecture
Chapter 13 Frame Session Architecture. . . . . . . . . . . . . . . . 269
Identifying objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269
Representing object characteristics with properties . . . . . . . . . . . . . . . . . . . . .270
FrameMaker product sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
vi FDK Programmer’s Guide
Chapter 14 Frame Document Architecture . . . . . . . . . . . . . . . 279
Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279
Global document information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
Graphic objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293
Flows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
Paragraph Catalog formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300
Paragraphs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
Character Catalog formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305
Condition Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311
Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319
Cross-reference formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322
Cross-references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323
Variable formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .324
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .326
Footnotes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .327
Ruling Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .328
Table Catalog formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .332
Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
Structural element definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
Format rules and format rule clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . .344
Format change lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .346
Structural elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347
Chapter 15 Frame Book Architecture . . . . . . . . . . . . . . . . . 351
What the user sees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
How the API represents books. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
Creating new books and components . . . . . . . . . . . . . . . . . . . . . . . . . . . .355
Updating a book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356
Using the book error log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .360
FDK Programmer’ s Guide vii
Part III: Frame Developm ent Environment (FDE)
Chapter 16 Introduction to FDE . . . . . . . . . . . . . . . . . . . . 365
How the FDE works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .365
How to make your client portable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .366
A simple FDE filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
Chapter 17 Making I/O and Memory Calls Portable . . . . . . . . . . 375
Initializing the FDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
Using platform-independent representations of pathnames . . . . . . . . . . . . . . . . .375
Making I/O portable with channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
Assertion-handler functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .378
Making memory allocation portable . . . . . . . . . . . . . . . . . . . . . . . . . . . . .378
Error and progress reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .379
Chapter 18 FDE Utility Libraries. . . . . . . . . . . . . . . . . . . . 381
String library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
The string list library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
Character library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
The I/O library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
The hash library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
Metric library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
MIF data structures and macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
The MIF library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
Simple MIF library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387
viii FDK Programmer’s Guide
Using Frame Developer Tools
The Frame Developer’s Kit
The Frame Developer’s Kit (FDK) provides tools for developers to enhance the
functionality of FrameMaker
aspects of FrameMaker that are useful for developers. It also discusses the FDK
documentation.
The principal parts of the FDK are:
● Frame Application Program Interface
● Frame Development Environment
● Frame Structure Import/Export Application Program Interface (Structure Import/Export
The following sections describe these parts and discuss how you can use them.
Frame API
The Frame API allows you to write C language programs, called FDK clients, that can take
control of a FrameMaker product session and communicate interactively with the user. With
the API, a client can do nea rly ev er ything an in teracti v e user ca n do and more. The API gi v es a
client direct access to the text and graphic objects in documents. The API includes a set of
header files, libraries, and makefiles for each supported platform. Here are some examples of
the types of clients you can create with the API:
● Grammar checkers
API)
. This chapter provides an overview of the FDK and other
(API)
(FDE)
● Bibliography utilities
● Voice control utilities
● Document reporting utilities
● Version control systems for documents
● Table utilities, such as sorting and totali ng
● Database publishing packages
● Interfaces to document management systems
● Filters to exchange files between other desktop publishing applications and FrameMaker
FDK Programmer’ s Guide ix
Using Frame Deve loper Tools
FDE
The Frame Development Environment (FDE) helps you make your client portable to all
platforms supported by FrameMaker. It provides platform-independent alternatives to
platform-specific I/O, string, and memory allocation schemes. It also provides a variety of
utility functions, such as Maker Interchange Format (MIF) writing functions. Frame
encourages you to use the FDE to develop all your clients. The FDE includes header files and
libraries for each supported platform.
Structure Import/Export API
The Structure Import/Expo rt API al lows you to write client s that co ntrol the import of markup
documents into FrameMaker, and control the export of FrameMaker documents to markup
(XML or SGML).
Other FrameMaker features for developers
MIF
fmbatch
FrameMaker provides other advanced features that are useful for developers. You do not need
the FDK to use these features.
Maker Interch ange Form at (MIF) is an easi ly parsed ASCII format that de scribes a docum ent’ s
text, graphics, formatting, and layout. FrameMaker can save a document or a book to a MIF
file, and convert a MIF file back to a document or book, without losing any information.
You can write applications or sc ripts that convert a MIF file to the format of another desktop
publishing package, or convert other formats to MIF.
Here are some examples of things you can use MIF for:
● Sharing files with earlier releases of Fr ameMaker products
● Converting database files into Frame documents
● Filtering word processor documents into Frame documents
You can find documentation for MIF in the online manuals folder for your FrameMaker
installation.
The fmbatch utility is shipped with UNIX versions of FrameMaker. It allows you to open,
print, reformat, and save FrameMaker product files without displaying them. You can use
fmbatch directly at a UNIX graphics workstation or in a remote shell from a nongraphics
terminal. The fmbatch utili ty pro vides interac tiv e a nd batch mode s. When you use it in ba tch
x FDK Programmer’s Guide
mode, you can execute operations on multiple files automatically. For example, you can use
fmbatch for:
● Printing books or documents from a remote location
● Printing multiple books or docume nts automati cally
● Updating multiple books or documents automatically
● Converting multiple books or documents to MIF
For more information on the fmbatch utility, see the FrameMaker product user
documentation for UNIX platforms.
Choosing the right Frame tools
There are often several tools or combinations of tools that you can use to solve a given
problem. In particular, you can use the API to perform many of the tasks that MIF and
fmbatch perform. The tool or combination of tools you should use depends on your needs.
Generally, MIF and fmbatch are more useful for one-time solutions to small problems,
whereas the API is more useful for full-scale applications or applications where interaction
with the user is required.
Using Frame Developer Tools
The following table summarizes the advantages and limitations of each Frame tool.
Frame tool
or feature Advantages Limitations
Frame API Fast, interactive, and portable; easy to provide a user
interface for your applications
MIF Can be used by text-processing utilities or UNIX shell
script. It can also be used to provide “backwards”
compatibility allowing files to be opened in earlier releases
of the product.
Third party MIF creators do not need to write complete
MIF. FrameMaker will always write out complete MIF.
fmbatch
Doesn’t require C pr ogramming ; can be used remotely fr om
a nongraphics terminal
FDK documentation
FDK documentation assumes that you have a thorough knowledge of FrameMaker. For
background information on FrameMaker, see your user documentation.
Must be compiled
Files must be saved as
MIF; not interactive
Only provides simple
functions; only
available on UNIX
platforms
FDK documentation includes the following manuals.
FDK Programmer’ s Guide xi
Using Frame Deve loper Tools
FDK Platform Guide
The FDK Platform Guide is printed in several versions, each describing how to install the
FDK on a specific platform. It provides the pathnames of sample programs and describes
platform-specific differences in using the FDK.
FDK Programmer’s Guide
The FDK Programmer’s Guide describes how to use the FDK to create clients for
FrameMaker. To get the most from this manual, you should be familiar with the C
programming language and event-driven programming.
The FDK Programmer’s Guide is divided into thre e parts:
● Part I, Frame Application Program Interface (API), provides instruct ions for creating API
clients.
● Part II, Frame Product Architecture, provides a conceptual overview of how the API
represents sessions, books, and documents.
● Part III, Frame Development Environment (FDE), provides instructions for making filters
and API clients platform-independent.
FDK Programmer’s Reference
The FDK Programmer’s Guide, which you are reading now, provides FDK reference
information, such as error codes and data structure, function, and property descriptions.
Structure Import/Export API Programmer’s Guide
The Structure Import/Export API Programmer’s Guide provides instructions and reference
information for using the Structure Import/Export API.
Naming conventions
To help you identify the structures, constants, and functions defined by the FDK, this manual
and the FDK adhere to the following naming conventions:
Type Naming convention Example
API error codes Begin with FE_
API functions Begin with F_Api
API scriptable function
property names
Begin with FS_
FE_NotPgf
F_ApiGetInt()
FS_NewDoc
FDE functions Begin with F_
F_StrNew()
xii FDK Programmer’s Guide
Using Frame Developer Tools
Type Naming convention Example
Flags used by API functions Begin with FF_ and all let t e r s
Initialization constants Begin with FA_Init
Notification constants Begin with FA_Note
Object property names Begin with FP_
Object types Begin with FO_
Property value constants Begin with FV_
Typedefs End with T
This manual uses the term API graphic object to refer to objects (such as FO_Polygon and
FO_TextFr ame objects ) th at t he API uses to represent the gr aphi c obj ec ts (such as polygons
and text frames) that appear on a page.
Style conventions
FDK manuals distinguish between you, the developer, and the user, the person for whom you
write clients.
FF_UFF_VAR
are uppercase
FA_Init_First
FA_Note_PreFileType
FP_Fill
FO_Doc
FV_Doc_Type_MIF
MetricT
FDK manuals may use the term FrameMaker product t o re fe r to the FrameMaker software, as
opposed to the software you write to work with the FrameMaker product.
Structured program interface
FrameMaker 7.0 and later ships with two program interfaces—Structured FrameMaker and
FrameMaker. The structured program interface presents menus, icons, and commands for
working with structured documents. The FDK includes some functions that only work on
structured documents. For example, setting an element range makes no sense in a document
that doesn’t contain any structure elements. Further, you can specify that an FDK client
requires the Structured FrameMaker program interface. For example, assume you specify
Structured FrameMak er when you re gi ster your cl ient. I f a use r has you r cli ent ins tall ed, b ut i s
running the FrameMaker program interface (not structured), then his installation of
FrameMaker will not initialize your client when it starts up. (In earlier versions you could
specify which FrameMaker products would initialize your client; FrameMaker,
FrameMaker+SGML, or FrameViewer.)
The FDK Programmer’s Refer e nce indicates tho se FDK functions th at apply only to structured
FrameMaker documents, as follows:
FDK Programmer’ s Guide xiii
Using Frame Deve loper Tools
Structured
In this example the word Structured appears to the left of the function name, indicating that
this function applies only to the content of a structured document. If you register a client to
work with the FrameMaker program interface, you should be sure that your client doesn’t use
any functions identified as Structured, otherwise your client may exhibit unpredictable
behavior.
Pathnames
Code examples in this manual use UNIX pathnames. For example:
docId = F_ApiSimpleOpen((Str ingT)"/tmp/mydoc.fm", False);
If you are using the FDK on the Macintosh or on Windows, change the code to use the
filepath naming conventions for those platforms. F or e x ampl e, on Macintosh, change t he cod e
above to code like the following:
docId = F_ApiSimpleOpen((Str ingT)"MyHardDrive:tmp :mydoc.fm", False);
On Windows, change it to code like the following:
docId = F_ApiSimpleOpen((Str ingT)"c:\\tmp\\mydoc. fm", False);
The FDK provides functions for converting platform-specific filepaths. For more information,
see “Making I/O portable with channels” on page 377 of the FDK Programmer’s Guide.
F_ApiGetAttributeDefs()
Typographic conventions
This manual uses different fonts to represent different types of information.
● What you type is shown in
text like this.
● Function names, property names, structure names, returned values, constants, filter names,
program names, pathnames, and filenames are also shown in
text like this.
● Placeholders (such as those representing names of files and directories) are shown in
text like this.
For example, this represents the name of your working directory:
/Mydir
● Omitted code in source code examples is indicated with ellipses.
For example, the el lipsi s in the foll o wi ng code indic ates th at some of th e code necess ary to
create a complete program is omitted:
. . .
F_ApiAlert((StringT)"Hello w orld.", FF_ALERT_CONT INUE_NOTE);
xiv FDK Progra mmer’s Guide
Part I
Frame Application Program Interface
(API)
FDK Programmer’ s Guide 1
2 FDK Programmer’s Guide
Introduction to the Frame API
1
This chapter provides an overview of how the API works and how to create an FDK client. It
also provides a simple example—a client that you can create and run right away.
The API enables you to create a client that takes control of a FrameMaker product session.
With the API, a client can do almost anything an interactive user can do. It can create, save,
and print documents; add and del ete te xt and gra phics; an d perform man y other formatti ng and
document-management tasks. It can also interact with the user by responding to user actions,
displaying dialog boxes, and creating menus.
How the API works
The API represents e v eryth ing in a Fr ameMaker pr oduct ses sion as an object.1 Each object has
a type, a constant that indicates the type of thing it represents. For example, an object’s type
can be FO_Doc (if it represents a document), FO_Rectangle (if it represents a graphic
rectangle), or FO_Pgf (if it represents a paragraph).
FrameMaker products assign an identifier (ID) to each object in a session. You use this ID to
identify an object when you call API functions.
An object’s characteristics are called properties. Each type of object has a particular set of
properties or a property list. For example, an FO_Rectangle object’s property list includes
properties named FP _Width and FP_Height, which represent its height and width. An
FO_Pgf object’s property list includes properties named FP_LeftIndent and
FP_Leadin g, which represent its left indent and its leading. Each property has a
predetermined data typ e, such as IntT (int e ger, Boolean, or ordinal), StringT (string), or
F_ObjHand leT (object ID).
Each of an indi vid ual obj ect’s properties has a value. This value descri bes th e prope rty f or that
particular object. For example, suppose a document contains a smoothed rectangle that is 20
points wide and 10 points high. The Frame API represents the rectangle as an
FO_Rectan gle object with the following properties and values.
TABLE 1.1
Property Data Type Value
FP_Width MetricT 20 * 65536
FP_Height MetricT 10 * 65536
FP_RectangleIsSmoothed IntT True
a
1. Frame API objects should not be confused with the graphic object s that you create with the Tools palette, object elements in
structured documents, or the objects of object-oriented programming langua ges.
FDK Programmer’ s Guide 3
Introduction to the Frame API
1
ABLE 1.1
T
Property Data Type Value
FP_FrameParent F_ObjHandleT
a.
MetricT values are 32-bit integers that represent measurements in points. The 16
most significant bits represent the digits before the decimal. The 16 least significant
bits represent the digits after the decimal. A point is 65536 (1 << 16) in
units. For more information on MetricT, see ‘ ‘Metr icT values’’ on page 675 of the
FDK Programmer’s Reference.
ID of the frame containing the
rectangle
MetricT
FO_Rectan gle objects actually have many more properties than are shown in the table
above. For a complete list of Frame API objects and properties, see Chapter 3, “Object
Reference” in the FDK Programmer’s Reference.
How clients can change FrameMaker documents, books, and sessions
A client can change FrameMaker documents, books, and sessions by:
● Creating and destroying objects
The API provides functions to create and destroy objects.
● Changing object properties
The API provides functions to get and set object properties.
● Programmatically executing FrameMaker product commands, such as Open, Print, Save,
and Clear All Change Bars
How clients communica te with the user
A client can communicate with the user by:
● Creating menus and menu items
● Displaying dialog boxes
The API allows a client to respond to user actions by:
● Notifying the client when the user initiates certain events, such as Open, Save, or Quit
● Passing a message to the client when the user clicks a hypertext marker that contains a
message apiclient hypertext command
How clients work with FrameMaker
Clients us e different mechanisms to work with FrameMaker on the different platforms the
FDK supports. On the Macintosh, clients are dynamic ally loa ded modules. On Windows, they
are dynamic link libraries (DLLs), or they can be executable programs that use COM to
communicate with a FrameMak er session. On UNIX platf orms, they c an be either dynamic ally
4 FDK Programmer’s Guide
linked code or separate processes that use the RPC mechanism to communicate with the
FrameMaker product. A client does not need to be aware of the low-level details of integrating
with FrameMaker, because the API provides high-level functions that are the same on all
platforms.
When the user starts FrameMaker it sends an initi alization call to each registered client.
Clients can take control immediately, or they can request the FrameMaker product to notify
them of specific events and wait for t hose events to occu r.
Special types of clients
In addition to conventional clients that take control of a FrameMaker product session in
response to user actions, the API allows you to create th ree special ty pes of clients: document
reports, filters, and take-control clients.
Document reports
Introduction to the Frame API
1
Filters
A document report is a client that provides detailed information about a document. The user
can start a document report by choosing Utilities>Document Reports from the File menu, and
then choosing the report from the Document Reports dialog box. The FDK includes a sample
document report, named wordcnt, which counts the number of words in a document. For
more inform ation on sample programs provided with the FDK, see the FDK Platform Guide
for the platform you’re using.
A filter is a client that converts FrameMaker product files to or from other file formats.
An import filter is a filter that the FrameMaker product calls when the user attempts to open a
non-Frame file and chooses a filter in the Unknown File Type dialog box. The import filter
reads the file and c onverts it to a FrameMaker product documen t or book . The FDK include s a
sample import filter, named mmlimport, that converts MML files to FrameMaker product
documents.
An export fi lter is a filter that the FrameMaker product calls when the user attempts to save a
FrameMaker product document or book in a particular format by choosing the format in the
Save dialog box or by specifying a filename with a particular extension. The export filter
writes information in the document or book to a file with a different format.
A file-to-file filter is a fil ter that the FrameMaker pr oduct can ca ll to both impo rt or e xport f iles
of different formats. A single file-to-file filter client can actually consist of more than one
filter. For example, the same client could filter CGM to FrameVector and FrameVector to
CGM. The way you register the client’s different filters determines which filter to invoke for
import and export. Another advanage of these filters is they can filter from an external file to
an external file. For e xample, y ou could f ilt er from CGM to TIFF, and the TIFF file can r emain
an external file th at is imported into the document by reference.
FDK Programmer’ s Guide 5
Introduction to the Frame API
1
Take-control clients
A take-control client is a client that takes control of a FrameMaker product session
immediately after the FrameMaker product starts. The UNIX implementation of the FDK
allows users to specify a take-control client in the FrameMaker product command line. Takecontrol clients are useful for conducting batch operations in which little or no user interaction
is needed.
Portability
The API’s design makes it easy to create portable clients. In most cases, you only need to
recompile your cli ent to run it on a diff er ent platform. To ensure that your client is completely
portable, use the FDE with the API. You should replace platform-specific I/O, str i ng, and
memory functions in your client with the al terna ti v es th e FDE pro vide s. For more infor mat ion
on the FDE, see Part III, Frame Development Environment (FDE).
The FDE and the API provide alternatives to the C language’s fundamental data types. For
example, the F DE and the AP I substitute IntT for a 32-bit int and UCharT for
unsigned char. The API uses other types for specific purposes. For example, it uses
F_ObjHand leT for object IDs. For a list of API data typ es, see Chapter 4 , “Data Types and
Structures Reference,” in the FDK Programmer’s Reference.
Due to platform limitations Asynchronous clients (clients that run outside of the FrameMaker
process space) are not portable on all platforms. For specific information on Asynchronous
clients se e the FDK Platform guide for the platform in question.
Running clients with different FrameMaker product interfaces
FrameMaker ships with t wo product interfaces, Structured FrameMaker and FrameMaker. A
client can only use functionality that is available in the product interface that is active for the
currently running FrameMaker process . For example, if a client is running on the unstructured
FrameMaker product interface , it can’t create or mani pulate struct ural elements ( FO_Element
objects). On the other hand, all functions in the FDK are available to a client running on the
Structured FrameMaker product interface.
To determine if a function is available in a particular product interface, see Chapter 2, “FDK
Function Reference,” in the FDK Programmer’s Reference. For an example of how to
programmatically determine which product interface is running, see ‘‘F_ApiGetString()’’ on
page 158 of the FDK Programmer’s Reference.
Creating and running a client
To create and run a client, follow these general steps:
6 FDK Programmer’s Guide
Introduction to the Frame API
1. Write an init ialization fu nction.
Most clients need to define an F_ApiInitialize() callback function. When the
FrameMaker product starts, it calls your client’s F_ApiInitialize() function. Normally,
you will want to include code in F_ApiInitialize() to set up your client’s menus and
request notification for particular events.
For more information on creating an F_ApiInitialize() callback, see Chapter 2, “API
Client Initialization”.
2. Set up the client’s user interface.
Your client probably needs to inte ract wi th the use r. To res pond to use r acti ons, you can def ine
the following ca llback functions in your client:
● F_ApiNotify() to respond to the user initiating FrameMaker product operations, such
as Open an d Save
● F_ApiCommand() to respond to the user choosing menu items created by your client
● F_ApiMessage() to respond to the user clicking hypertext markers that contain the
message apiclient command
1
● F_ApiDialogEvent() to respond to the user manip ulati ng items in a dialo g box creat ed
by your client
You can also display notices and prompt the user for inpu t by usi ng API dial og box funct i ons,
such as F_ApiAlert() and F_ApiPromptString().
For more information on setting up your client’s user interface, see Chapter 3, “Creating Your
Client’s User Interface”.
3. Add code to programmatically execute FrameMaker product commands.
Your client probably needs to execute some FrameMaker product commands, such as Open,
Print, or Close. To execute these commands programmatically, use API functions, such as
F_ApiSimpleOpen(), F_ApiSilentPrintDoc(), or F_ApiClose().
For more informati on on u si ng API fu nct io ns to execute FrameMak e r pr oduc t commands, see
Chapter 4, “Executing Commands with API Functions”.
4. Add code to get and set object properties.
To get or set an object property, use the F_ApiGetPropertyType() or
F_ApiSetPropertyType() function that corresponds to the type of property you want to
get or set. For example, to get or set an IntT property, use F_ApiGetInt() or
F_ApiSetI nt(). To get or set a StringT property, use F_ApiGetString() or
F_ApiSetS tring( ).
For more information on changing object properties, see Chapter 5, “Getting and Setting
Properties”.
5. Add code to create objects.
FDK Programmer’ s Guide 7
Introduction to the Frame API
1
T o creat e objects, use the F_ApiNewObjectType() function t hat correspond s to the kind of
object that you want to create. For example, to create a new anchored frame, use
F_ApiNewAnchoredObject().
For more information on creating objects, see Chapter 8, “Creating and Deleting API
Objects”.
6. Compile your client.
The API function declarations are cont ained in the fapi.h header. Be sure to include this
header in your client code. Include C library header files before the fapi.h header.
The FDK comes with sample makefiles or project files for each supported platform. To
compile your client, use your platform’s make or build utility. For more information on using
FDK makefiles or project files on a specific platform, see the FDK Platform Guide for that
platform.
7. Register your client with the FrameMaker product.
The FrameMaker product needs to know about your client to initialize it. To let the
FrameMaker product know about your client, you must make some changes to the
environment under which the client runs.
● On UNIX platforms, when you start FrameMaker it looks for a text-only file named
fminit/UILanguage/APIArea/apiclients, where
UILanguage is the user interface
language (such as usenglish for US English). It looks in the directory from which it
was started, in your home directory, and in $FMHOME. To register your client, create an
fminit/UILanguage/APIArea/apiclients file in your home directory or the
directory from which you intend to start the FrameMaker product. Add the following lines
to the file:
<APIclient
<Name
<Directory
<CommandLine $FAPIDIR
>
client_name>
clientdir>
/executab le_name>
The path clientdir specifies the full path of the directory containing your client’s executable
file and other resources,
reference your client, and
FDK sets the environment variable $FAPIDIR to
● On Macintosh computers, copy or mov e your client t o the FrameMaker p roduct’ s Modules
client_name is the name that FrameMaker and other clients use to
executab le_name is the name of your clien t’s executable f il e. The
clientdir.
folder.
● On Windows platforms, add the followin g lines to the [APIClients] section of the
maker.ini file:
ClientName=ClientType, description, path, mode
ClientName
client.
TextImport.
is the name that the FrameMak er product and other client s use to r eference your
ClientType specifies your client type: for example, Standard, DocReport, or
description is a string describing your client. path is the pathname of your
8 FDK Programmer’s Guide
client’s DLL.mode determine s wha t p rodu ct interfaces your cl ie nt supports—can be one of
all, maker, or structured.
You can also register a Windows client by setting values in the DLL’s VERSIONINFO
resource, then copying or moving the DLL in the PrameMaker product’s Plugins folder.
For information on registering your client o n a specific platform, see the FDK Plat form Guide
for that platform.
A simple example
The followin g client adds a menu wit h three items to t he FrameMak er pro duct menu bar when
the FrameMaker product starts. The first menu item closes the active document; the second
item sets the fill pattern of a selected graphic object; the third item adds a body page to the
active document. Following the code is a line-by-line description of how it works.
1. #include "fapi.h"
2. #define CloseDoc 1
3. #define SetFill 2
4. #define AddPage 3
5.
6.
VoidT F_ApiInitialize(initia lization)
7. IntT initialization; /* Code for initializ ation type */
8. {
9. F_ObjHandleT menuBarId, menu Id;
10.
11.
/* Get ID of the FrameMaker product menu bar. */
12. menuBarId = F_ApiGetNamedObject(FV_SessionId, FO_ Menu,
13. "!MakerMainMenu");
14. /* Add menu named "API" to the FrameMaker product menu bar. */
15. menuId = F_ApiDefineAndAddMenu(menuBarId, "APIMen u", "API");
16.
17.
/* Add items to API menu. */
18. F_ApiDefineAndAddCommand(CloseDoc, menuId,"CloseD ocCmd",
19. "Close","\\!CD");
20. F_ApiDefineAndAddCommand(SetFill, menuId,"SetFill Cmd",
21. "Set Fill","\\!SF");
22. F_ApiDefineAndAddCommand(AddPage, menuId,"AddPage Cmd",
23. "Add Page","\\!AP");
24. }
25.
26.
VoidT F_ApiCommand(command)
27. IntT command;
28. {
29. F_ObjHandleT pgId, objId, docId;
30.
31.
/* Get the ID of the active document. */
32. docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc) ;
33. if(!docId) return; /* Return if there is no activ e document. */
34.
Introduction to the Frame API
1
FDK Programmer’ s Guide 9
Introduction to the Frame API
1
35. switch (command)
36. {
37. case CloseDoc: /* Close d ocument even if it’s changed. */
38. F_ApiClose(docId, FF_CLOSE_MODIFI ED);
39. break;
40.
41.
42. /* Get ID of selected object . */
43. objId = F_ApiGetId(FV_Sessio nId, docId,
44. FP_FirstSelectedGraphicInDoc );
45.
46.
47. if (!objId) F_ApiAlert("Sele ct an object first.",
48. FF_ALERT_CONTINUE_WARN);
49. else F_ApiSetInt(docId, objI d, FP_Fill, FV_FILL_B LACK);
50. break;
51.
52.
53. pgId = F_ApiNewSeriesObject( docId, FO_BodyPage, 0 );
54. break;
55. }
56. }
case SetFill: /* Set fill pattern to black. */
case AddPage: /* Add a ne w page. */
/* If an object is selected, set its fill. */
Lines 1.–5.
These lines includ e heade r f iles a nd def ine t he consta nts for the cli ent’s menu items. All clients
must include the fapi.h header. To e nsure your cl ient is portable, include fapi.h before
any other header files.
Lines 6.–25.
These line s define the F_ApiInitialize() callback function. When the user starts the
FrameMaker product, it calls F_ApiInitialize().
The call to F_ApiGetNamedObject() gets the ID of the FrameMaker product menu bar
(!MakerMainMenu). The call to F_ApiDefineAndAddMenu() creates a menu named API
on the menu bar. The calls to F_ApiDefineAndAddCommand() add menu items to the API
menu and define keyboard shortcuts for the items.
Lines 26.–56.
These line s define the F_ApiCommand() callback function. When the user chooses a menu
item, the FrameMaker product calls this callback with command set to the menu item number
(in this example, CloseDoc, SetFill , or AddPage).
Lines 31.–34.
These lines get the ID of the document to change. To use most API functions, you need to
specify an ID. This e xample get s the ID of th e document tha t has input focus, that is, the active
document.
In each FrameMaker product session there is only one active document at a time. The session
object (FO_Session) has a property named FP_ActiveDoc that specifies its ID. To retrieve
10 FDK Programmer’s Guide
Introduction to the Frame API
the active document’s ID from the FO_Session object, you use F_ApiGetId() to query
the FO_Session object’s FP_ActiveDoc property. The syntax for F_ApiGetId() is:
F_ObjHandleT F_ApiGetId(pare ntId, /* Object’s par ent */
objId, /* Object whose prop erty you want to quer y */
property );/* Constant speci fying property to que ry */
The parentId parameter specifies the ID of the object’s parent—the session, book, or
document that contains the object. No other object contains the FO_Session object, so
parentId is set to 0. The ID of the FO_Session object (there can only be one) is always
FV_Sessio nId, so objId is set to FV_SessionId.
Lines 37.–40.
These lines close the active document when the user chooses Close Doc from the API menu.
The FF_CLOSE _MODIFIED flag instruct s the API t o clos e the do cument without war ning the
user, even if the document has unsaved changes.
Lines 41.–51.
These lines set the f i ll patt ern of a se lect ed object to blac k when the user choo ses Set Fi ll fro m
the API menu. To set the selected object’s fill pattern, the client needs the object’s ID. To get
the ID, the cl ient uses F_ApiGetId() to query the document property,
FP_FirstSelectedGraphicInDoc. If no object is selected, F_ApiGetId() returns 0.
1
The F_ApiAlert() call displays an alert that tells the user to select an object. The constant,
FF_ALERT_CONTINUE_WARN, specifies the type of al ert—an ale rt with a Continue button.
To set the object’s fill pattern, the client mu st set its FP_Fill property. FP_Fill is an
IntT property, so the client must use F_ApiSetInt() to s et it. The syntax for
F_ApiSetI nt() is:
VoidT F_ApiSetInt(parentId,/ * Object’s parent */
objId, /* Object whose prope rty you want to set * /
property, /* Constant specif ying property to set */
value);/* Value to which to set the property */
FP_Fill can have any value between 0 and 15. The API-defi ned constant,
FV_FILL_B LACK, specifies 0 (black).
Lines 52.–54.
These lines add a body page t o the docu me nt whe n th e user chooses Add a Page fr om the API
menu. A body page object is a series object. To create a series object, you use
F_ApiNewSeriesObject(). The sy ntax for F_ApiNewSeriesObject() is:
F_ObjHandleT F_ApiNewSeriesO bject(parentId,/* Obj ect’s Parent */
objectType, /* Constant spec ifying new object typ e */
prevObjectId); /* Object for new object to follow */
The parentId parameter specif ies t he ID of the ob ject t hat is to cont ain the new object. The
new page shoul d appear in the acti v e document, so parentId is set to docId. The API uses
FO_BodyPa ge objects to represent body pages, so objectType is set to FO_BodyPage.
Specifying 0 for prevObjectId puts the new page at the beginning of the document. For
more information on creating different types of objects, see “Creating objects” on page 143.
FDK Programmer’ s Guide 11
Introduction to the Frame API
1
Compiling and running the example client
The source code for the example client and a makefile or project file are provided in the
samples/m yapi dire ctory of your FDK inst allati on. F or th e locati on of the fi les, see the FDK
Platform Guide for your platform. To compile the client, use your platform’s make or build
utility.
To run the example client, you must first register it as required by your platform’s
implementation of the API:
● If you are wor king on a UNIX platfo rm with US English as the us er inte rface language, and
the pathname of your compiled client is /usr/fdk/samples/ch1/fa.myapi, you can
register it by creating a text-only file named
~/fminit/usenglish/APIArea/apiclients with the following lines in it:
<APIclient
<Name myapi>
<Directory /usr/fdk/samples/ch1>
<CommandLine $FAPIDIR/fa.myapi>
>
When you start the FrameMaker product, it reads this file and starts the fa.myapi client.
● If you are working on a Macintosh computer, copy or move the example client to the
FrameMaker product’s Modules folder.
● If you are working on a Windows platform and you have compiled your client into a DLL
named myapi.dll and copied or moved it to the FrameMaker fminit directory, add
the following line to the maker.ini file:
myapi = Standard,Ch. 1 Sample,fminit\myapi.dll,all
For more information on how to register clients, see the FDK Platform Guide.
After you have registered the example client, start the FrameMaker product and open a
document. The API menu should appear to the right of the FrameMaker product menus.
12 FDK Programmer’s Guide
API Client Initialization
2
This chapter describes how to start interaction between your client and FrameMaker.
Responding to the FrameMaker product’s initialization call
When the FrameMaker product starts, it attempts to start all the clients registered with it,1
except document reports and filters. The FrameMaker product attempts to start each client by
calling its F_ApiInitialize() callback function.
Your client should define F_ApiInitialize() as follows:
VoidT F_ApiInitialize(initia lization)
IntT initialization;
{
/* Your client code goes her e */
}
TABLE 2.1
This argument Means
initialization
Usually, you want your client to do something immediately after the user starts the
FrameMaker product. For example, you may want to add menus to the menu bar or request
notification for certain events. To do this, you call API functions from the
F_ApiInitialize() function. For information on creating menus and requesting
notification, see Chapter 3 , “Creating Your Client’s User Interface.”
Suppose you want your cl ien t t o di splay a dialog box after th e FrameMaker product is st ar ted.
To do this, you could use the following F_ApiInitialize() function:
. . .
VoidT F_ApiInitialize(initia lization)
IntT initialization;
{
F_ApiAlert("Client has start ed.", FF_ALERT_CONTIN UE_NOTE);
}
. . .
A flag that indicates the type of initialization (see “Initialization
types” on page 14)
1. For information on registerin g yo ur cl ie nt with the Fra meMaker product, see the FDK Platform Guide for your platform.
FDK Programmer’ s Guide 13
API Client Initialization
2
Initialization types
The following table summarizes the different types of initializations and the
initializ ation constants FrameMaker can pass to your client’s F_ApiInitialize()
callback.
TABLE 2.2
Type of
initialization
FrameMaker starts
with no special options
FrameMaker starts
with take-control
client
Document report
chosen from
Document Reports
dialog box
Notification, menu
choice, or hypertext
command for a client
that has bailed out
When F_ApiInitialize
is called Initialization constant
After starting
After starting
After all clients have finished
processing the
FA_Init_First
FA_Init_First
FA_Init_TakeControl
FA_Init_First
initialization
After report is chosen
When the menu item is chosen,
the hypertext command is
clicked, or the notification
should be issued
FA_Init_DocReport
FA_Init_Subsequent
Clients that receive
initialization
All except document
reports and filters
All except document
reports and filters
All clients set up as takecontrol clients
The chosen document
report
Clients that hav e bai l ed
out and are waiting for an
event, menu choice, or
hypertext command to
occur
First initializa tion
When the user starts the FrameMaker product, the product calls the F_ApiInitialize()
function of each registered client (unless it’s a document report or filter) with
initializ ation set to FA_Init_First.
Take-control initialization
The FDK allows you to set up clients to receive a special initialization called a take-control or
FA_Init_TakeControl initialization. The FrameMaker product issues the
FA_Init_TakeControl in itiali zatio n after it has issued th e FA_Init_First initialization
and all clients have returned control. This initialization is useful if you want your client to
conduct some batch processing after other clients have initialized, but before the interactive
user has control.
14 FDK Programmer’s Guide
On UNIX platforms, the FrameMaker pr oduct issues the FA_Init_TakeControl
initialization to only one client. The user speci fies this client by starting the FrameMaker
product with the -apiclient client_name option (where client_name is the
registered name of the client).
On Windows and Macintosh platforms, the FrameMaker product can issue the
FA_Init_TakeControl initialization to several clients. To set up a client to receive
FA_Init_TakeControl initializations on Windows, set the client’s type to TakeControl
in the FrameMak er product .ini file. To set up a client to receive FA_Init_TakeControl
initializations on the Macinto sh, set the flags fie ld of the clien t’ s fdat resource to in clude
ApiClientFlagCanTakeControl. For more information on setting up clients to receive
take-control initializations, see the FDK Platform Guide for your platform.
Document report initialization
When the FrameMaker product is started, it does not attempt to initialize API clients that are
registered as do cument re ports . It ini tial izes a document report only when the user ch ooses t he
document report from the Document Reports dialog box. When this occurs, the FrameMaker
product calls the document report’s F_ApiInitialize() callback with
initializ ation set to FA_Init_DocReport.
API Client Initialization
2
To appear in the Document Reports dialog box, a docu me nt r epo rt mu st b e registered with the
FrameMaker product as a document report. For information on registering document reports,
see the FDK Platform Guide for your platform.
Filter initialization
If your client is registered as a filter, you should not define an F_ApiInitialize()
function for it. When the user opens or saves a file and selects your filter, the FrameMaker
product notifies your client by calling your client’s F_ApiNotify() callback. For more
information on F_ApiNotify() and notification, see “Responding to user-initiated events
or FrameMaker product operations” on page 34.
To receive notific ati on, your filter must be r e gistered as a fi lt er. For information on registering
filters, see the FDK Platform Guide for your platform.
Initialization after a client has bailed out
If your API client is waiting for an event and not performing any other processing, it can call
F_ApiBail Out(). This exits your client’s process and frees all the system resources that it
uses. If an event that your client is waiting for occurs, the FrameMaker product restarts your
client by calling its F_ApiInitialize() function with initialization set to
FA_Init_Subsequent.
A document report should always bail out after it completes processing, because the API
initializes it each time the user chooses it from the Document Reports dia log box. A filter
should always bail out after it filters a file, because the API initializes it each time a filterable
file is opened, imported, or saved.
FDK Programmer’ s Guide 15
API Client Initialization
2
For more information on F_Ap iBailO ut(), see ‘‘F_ApiBailOut()’’ on page 48 of the FDK
Programmer’s Reference.
Disabling the API
The user can disable all API clients before starting the FrameMaker product. On UNIX
platforms, the user can disable all clients by specifying -noapi in a resou rce file or when
starting the FrameMak er produc t from the command li ne. On W i ndo ws platfor ms, the user can
disable all clients by changing the API=On setting in the maker.ini file to API=Off. On
the Macintosh, the user can disable clients by dragging them from the FrameMaker product
Modules folder. For more information on disabling individual clients, see the FDK Platform
Guide for your platform.
IMPORTANT: Many FrameMaker features are implemented via API clients. If you disable
the API then you also disable these features. Such features include XML and
SGML import and export, Save As HTML, and Word Count.
16 FDK Programmer’s Guide
Loading...