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

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

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

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

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

ABLE 1.1

Property Data Type Value

FP_FrameParent F_ObjHandleT

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

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

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

● 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

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

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

FDK Programmer’ s Guide 9

Introduction to the Frame API

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.

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

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

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

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

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 all clients have finished processing the

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

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

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

Creating Your Client’s User

Interface

This chapter describes how to use the Frame API to create a user interface for your FDK client.

Your client can interact with the user in the following ways:

● By displaying its own dialog boxes

● By implementing its own menus, menu items, and keyboard shortcuts

● By responding to the message apiclient hypertext command

● By responding to user-initiated events or FrameMaker product operations

● By implementing quick-key commands

The following sections discuss these ways of interacting with the user in greater detail.

Using API dialog boxes to prompt the user for input

The Frame API provides a variety of premade dialog boxes. All of these dialog boxes are modal—the user must dismiss them before continuing. The following sections discuss how to use these dialog boxes.

The API also allows you to create and use custom modal and model ess d ialog box es. For more information, see Chapter 10, “Creating Custom Dialog Boxes for Your Client” and

Chapter 11, “Handling Custom Dialog Box Events”

Using alert boxes

To display a dialog box with a short message, use F_ApiAlert(). The syntax for F_ApiAlert() is:

IntT F_ApiAlert(StringT mess age,

IntT type);

This argument Means

message

type

The message that appears in the alert box The type of alert box

FDK Programmer’ s Guide 17

Creating Your Client’s User Interface

Specify one of the following values for the type argument.

type constant Type of dialog box displayed

FF_ALERT_OK_DEFAULT

FF_ALERT_CANCEL_DEFAULT

FF_ALERT_CONTINUE_NOTE

FF_ALERT_CONTINUE_WARN

FF_ALERT_YES_DEFAULT

FF_ALERT_NO_DEFAULT

Displays OK and Cancel buttons; OK is the default Displays OK and Cancel buttons; Cancel is the default Displays Continue button Displays Continue button with a warning indication Displays Yes and No buttons; Yes is the default Displays Yes and No buttons; No is the default

F_ApiAler t() returns 0 if the user clicks OK, Continue, or Yes; otherwise, it returns a nonzero value.

Example

The following code displays the alert box shown in Figure 3.1:

. . . IntT err;

err = F_ApiAlert((StringT)"T his alert is an OK_DE FAULT.",

FF_ALERT_OK_DEFAULT);

. . .

IGURE 3.1 FF_ALERT_OK_DEFAULT alert box

Using string, integer, and metric input dialog boxes

To prompt the user for a single string, integer, or metric value, use F_ApiPromptString(), F_ApiProm ptInt( ), or F_ApiPromptMetric(). These functions all allow you t o provi de

a default value for the entry field. Their syntax is:

IntT F_ApiPromptString(Strin gT *stringp,

StringT message,

StringT stuffVal); IntT F_ApiPromptInt(IntT *in tp,

StringT message,

StringT stuffVal);

18 FDK Programmer’s Guide

Creating Your Client’s User Interface

IntT F_ApiPromptMetric(Metri cT *metricp,

StringT message,

StringT stuffVal,

MetricT defaultunit);

This argument Means

stringp, intp,

metricp

message

stuffVal

defaultunit

A pointer to the user variable that gets the return value from the input field when the user clicks OK.

The message that appears in the dialog box. The default value that appears in the input field when the dialog box is first

displayed. It must be a string for integer and metric prompts, as well as string prompts.

The metric unit to use if the user doesn’t specify one. For example, to use inches as the default unit, specify 4718592. For more information on metric values, see ‘‘MetricT values’’ on page 675 of the FDK Programmer’s

Reference

These functions all return 0 if the user clicks OK. Otherwise, they return a nonzero error value. If the user clicks Cancel, the API does not assign a value to *stringp, *intp, or *metricp.

If the user types alphabetic text after a number in an F_ApiPromptInt() dialog box, the API ignores the te xt and just r eturns the number. For example, if the us er type s 10 cookies, the returned value is 10.

F_ApiPromptMetric() dialog boxes behave like metric dialog boxes in the user interface. If the user types a number followed by a string that represents a unit, the API converts the value into the equivalent number of metric units. For example, if the user types 5in or 5", the API retur ns 5*(47185 92). If the user doesn’t specify a unit, the API uses the unit specified by defaultunit.

IMPORTANT: F_ApiPromptString() allocates memory for the string referenced by

*stringp. Use the FDK function F_ApiDeallocateString() to free the string when you are done with it. For more information on F_ApiDeallocateString(), see ‘‘F_ApiDeallocateStructureType()’’ on

page 74 of the FDK Programmer’s Reference.

Examples

The following code displays the dialog box shown in Figure 3.2:

FDK Programmer’ s Guide 19

Creating Your Client’s User Interface

. . . #include "fmemory.h" IntT err; StringT sres; err = F_ApiPromptString(&sre s, (StringT)"String?" ,

if (err) return; /* Some code to use the stri ng goes here. */ F_ApiDeallocateString(&sres); . . .

IGURE 3.2 String prompt dialog box

The following code displays the dialog box shown in Figure 3.3:

(StringT)"Default text");

. . . #include "futils.h" /* Provi des declaration for F _Sprintf(). */ IntT err, ires; UCharT msg[256];

err = F_ApiPromptInt(&ires, (StringT)"Integer?", "1234"); if (err) F_Sprintf(msg,(Stri ngT)"Cancelled, ires has no value");

else F_Sprintf(msg,(StringT) "The value of ires is %d.",ires); F_ApiAlert(msg, FF_ALERT_CON TINUE_NOTE); . . .

IGURE 3.3 Integer prompt dialog box

The following code displays the dialog box shown in Figure 3.4:

. . . #define IN (MetricT) 65536*7 2 /* Default unit (in ches) */ IntT err; MetricT mres; err = F_ApiPromptMetric(&mre s, (StringT)"Metric?" ,

"12.34in", IN);

. . .

20 FDK Programmer’s Guide

FIGURE 3.4 Metric prompt dialog box

Using file selection dialog boxes

T o displ ay dialog box es similar to t he FrameMaker prod uct’ s Op en and Sav e dialog bo xes, use F_ApiChooseFile(). F_ApiChooseFile() displays files and directories in a scrolling

list and allows the user to choose a file or directory. The syntax for F_ApiChooseFile() is:

IntT F_ApiChooseFile(StringT *choice,

StringT title,

StringT directory,

StringT stuffVal,

IntT mode,

StringT helpLink);

Creating Your Client’s User Interface

This argument Means

choice

title

Using scroll list dialog boxes

T o di splay a s croll li st dial og box, use F_ApiScrollBox(). F_ApiScrollBox() displays an array of items that you provide and allows the user to choose one.

The syntax for F_ApiScrollBox() is:

IntT F_ApiScrollBox(IntT *se lected_item,

StringT title,

F_StringsT *stringslist,

IntT default);

This argument Means

selected_item

title

The index of the selected item when the user clicks OK (or double-clicks an item). The index of the first item is

The title that appears on the dialog box.

22 FDK Programmer’s Guide

This argument Means

Creating Your Client’s User Interface

stringslist

default

The list of items that appears in the scroll list. The index of the item that is selected when th e dialog bo x f irst app ears. F or

no default, specify

-1.

F_Strings T is defined as:

typedef struct {

UIntT len; /* Number of stri ngs */

StringT *val; /* Array of st rings */ } F_StringsT;

The F_ApiScrollBox() function returns a nonzero value if the user clicks Cancel or an error occurs, or 0 if the user clicks OK.

Example

To create the dialog box shown in Figure 3 .6, add the following code to your client:

. . . #include "futils.h" IntT err, choice, listLen = 3; UCharT msg[256]; F_StringsT colors;

colors.val = (StringT *) F_A lloc(listLen*sizeof(S tringT), NO_DSE); if (colors.val) {

colors.len = (UIntT)listLen;

colors.val[0] = F_StrCopyStr ing("red");

colors.val[1] = F_StrCopyStr ing("green");

colors.val[2] = F_StrCopyStr ing("blue");

err = F_ApiScrollBox(&choice , "Choose a color.", &colors, 0);

if (!err)

F_Sprintf(msg, "The choice i s %s.", colors.val[ch oice]);

else

F_Sprintf(msg, "Cancel was p ressed"); F_ApiAlert(msg, FF_ALERT_CON TINUE_NOTE); F_ApiDeallocateStrings(&colo rs);

} . . .

FDK Programmer’ s Guide 23

Creating Your Client’s User Interface

FIGURE 3.6 Scroll list dialog box

Using commands, menu items, and menus in your client

The API allows you to use commands, menu items, and menus in your client’s user interface. A command is a part of FrameMaker product or FDK client functionality that a user can invoke by typing a shortcut. A menu item is an instance of a command that appe ars on a menu. There can be several menu items for each command.

A menu is a list of menu items or other menus. A menu bar is a list of menus that appears at the top of the screen on a Macintosh, at the top of a document or book window on UNIX platforms, and at the top of the FrameMaker product window on Windows platforms.

To use commands and menus in your client’s user interface, follow these general steps:

1. Get the IDs of the FrameMaker product menu bars and menus that you want to add your

client’s menus and commands to.

2. Define your client’s commands and add them to menus.

3. Define your client’s menus and add them to FrameMaker product menus or menu bars.

4. Write an F_ApiCommand() callback to respond to the user invoking your client’s

commands.

These steps are discussed in greater detail in the following sections.

Getting the IDs of FrameMaker product menus and menu bars

To get the IDs of commands, menus, or menu bars, use F_ApiGetNamedObject(). The syntax for F_ApiGetNamedObject() is:

F_ObjHandleT F_ApiGetNamedOb ject(F_ObjHandleT par entId,

IntT objType, StringT objName);

This argument Means

parentId

The ID of the document, book, or session containing the object for whi ch you want to get an ID. For commands and menus, it is always

FV_SessionId.

24 FDK Programmer’s Guide

This argument Means

Creating Your Client’s User Interface

objType

objName

The object type. To get the ID of a command, specify FO_Command. To get the ID of a menu or menu bar, specify

The name of the command, menu, or menu bar. This name may not be the same as the label or title that appears on a menu.

FO_Menu.

The menu and command names you can specify for objName depend on t he FrameMaker product and how the user has customized the menus. On UNIX platforms, the default command names are listed in $FMHOME/fminit/UILanguage/configui/Commands and the default menu names ar e listed in $FMHOME/f minit/ UILanguage/configui/ProductInterfaceMenus, where

UILanguage ProductInterface

represents the user-interface language (such as usenglish for US English) and

is the name of the product interface (either maker or structured). For information on where the menus ar e listed on ot her plat forms, see t he FDK Platfor m Guide fo r your platform.

The following table lists some FrameMaker product menus and the names you use to specify them:

Menu title Name

Edit Element

EditMenu

ElementMenu

File Format Graphics Special Table View Help

FileMenu

FormatMenu

GraphicsMenu

SpecialMenu

TableMenu

ViewMenu

!HelpMenu

The followin g table lists the names of some Frame Maker product menu bars. Menu bar names starting with an exclamation point (!) can’t be removed by the user.

FrameMaker product menu bar Name

Menu bar for documents (complete menus) Menu bar for documents (quick menus) Menu bar for books (complete menus) Menu bar for books (quick menus)

!MakerMainMenu

!QuickMakerMainMenu

!BookMainMenu

!QuickBookMainMenu

FDK Programmer’ s Guide 25

Creating Your Client’s User Interface

FrameMaker product menu bar Name

View-only menu bar

Example

The following code gets the ID of the Edit menu and the view-only menu bar:

. . . F_ObjHandleT editMenuId, vie wOnlyMenuBarId; editMenuId = F_ApiGetNamedOb ject(FV_SessionId, FO _Menu,

"EditMenu");

viewOnlyMenuBarId = F_ApiGetNamedObject (FV_SessionId, FO_Menu,

"!ViewOnlyMainMenu");

. . .

Defining commands and adding them to menus

To define a command and add it to a menu, use F_ApiDefineAndAddCommand(). The syntax for F_ApiDefineAndAddCommand() is:

F_ObjHandleT F_ApiDefineAndA ddCommand(IntT cmd,

F_ObjHandleT toMenuId, StringT name, StringT label, StringT shortcut);

!ViewOnlyMainMenu

This argument Means

cmd

toMenuId

name

label

shortcut

The integer that the FrameMaker product passes to your client’s

F_ApiCommand()

the keyboard shortcut for the command. The ID of the menu to which to add the command. A unique name to identify the command. The title of the command as it appears on the menu. The keyboard shortcut sequence. Many FrameMaker product commands use

shortcuts beginning with Esc (\! ). To specify Esc when you create a command, use

\\! in the string you pass to shortcut.

function when the user chooses t he m e nu it em or ty pes

F_ApiDefineAndAddCommand() returns the ID of the command it creates.

IMPORTANT: To ensure that your client is portable to the different platforms that

FrameMaker supports, specify only shortcuts that begin with Esc. On UNIX, the Esc shortcut appears on the menu next to the menu item label. On the Macintosh or Windows, the shortcut does not appear. However, the user can still execute it. For example, if you specify \\!xy for the keyboard shortcut, the user can execute the command from the keyboard by pressing Esc x y. For

26 FDK Programmer’s Guide

more information on specifying keyboard shortcuts, see the sections of your user documentation that discuss the FrameMaker product’s configurable user interface.

Example

The following code defines a command with the shortcut EscNL and adds it to the Utilities menu:

. . . #define NUMBER_LINES 1 F_ObjHandleT utilsMenuId, cm dId;

utilsMenuId = F_ApiGetNamedO bject(FV_SessionId, F O_Menu, "UtilitiesMen u"); cmdId = F_ApiDefineAndAddCom mand(NUMBER_LINES, ut ilsMenuId,

. . .

Defining and adding menus

To define a menu and add it to a menu bar or another menu, use F_ApiDefineAndAddMenu(). The syntax for F_ApiDefineAndAddMenu() is:

Creating Your Client’s User Interface

"NumberLines","Number lines" , "\\!NL");

F_ObjHandleT F_ApiDefineAndA ddMenu(F_ObjHandleT t oMenuId,

StringT name, StringT label);

This argument Means

toMenuId

name

label

The ID of the menu or menu bar to which to add the new menu A unique name that identifies the new menu The title of the new menu as it appears on the menu or menu bar

F_ApiDefineAndAddMenu() returns the ID of the menu it creates. If you specify a menu bar ID for toMenuId, the FrameMaker product implements the new

menu as a pull-down menu. If you specify a pull-down or a pop-up menu ID for toMenuId, the FrameMaker product implements the new menu as a pull-right menu.

IMPORTANT: Your menu appears only on the menu bar you specify. For example, if you add

a menu only to the !MakerMainMenu menu bar, the menu will not appear if the user switches to quick menus. For your menu to appear after the user has switched to quick menus, you must also add it to the !QuickMakerMainMenu menu bar.

Adding commands to a menu that you have created

To add a command to a menu that you have created, call F_ApiDefineAndAddCommand() with toMenuId set to the ID returned by the F_ApiDefineAndAddMenu() call that

FDK Programmer’ s Guide 27

Creating Your Client’s User Interface

created the menu. For example, the following code defines a menu and adds it to the FrameMaker document menu bar. Then it adds some commands to the menu.

. . . #define CHECK 1 #define PRINT 2 F_ObjHandleT menubarId, menu Id, cmd1Id, cmd2Id;

/* Get the ID of the FrameMa ker main menu bar. */ menubarId = F_ApiGetNamedObj ect(FV_SessionId, FO_ Menu,

/* Define and add the menu t o the main menu. */ menuId = F_ApiDefineAndAddMe nu(menubarId, "Gramma rMenu",

/* Define some commands and add them to the menu. */ cmd1Id = F_ApiDefineAndAddCo mmand(CHECK, menuId,

cmd2Id = F_ApiDefineAndAddCo mmand(PRINT, menuId,

. . .

"!MakerMainMenu");

"Grammar");

"CheckGrammar","Check Gramma r", "\\!CG");

"PrintErrors","Print Errors" , "\\!PE");

Example

The following code defines a menu and adds it to the Edit menu:

. . . #define CHECK 1 #define PRINT 2 F_ObjHandleT editMenuId, men uId, cmd1Id, cmd2Id;

/* Get the ID of the edit me nu. */ editMenuId = F_ApiGetNamedOb ject(FV_SessionId, FO _Menu,

"EditMenu");

/* Define the menu and add i t to the Edit menu. * / menuId = F_ApiDefineAndAddMe nu(editMenuId, "Gramm arMenu",

"Grammar");

/* Define some commands and add them to the menu. */ cmd1Id = F_ApiDefineAndAddCo mmand(CHECK, menuId,

"CheckGrammar","Check Gramma r", "\\!CG");

cmd2Id = F_ApiDefineAndAddCo mmand(PRINT, menuId,

"PrintErrors","Print Errors" , "\\!PE");

. . .

IGURE 3.7 Edit menu with a client-defined pull-right menu

28 FDK Programmer’s Guide

Creating Your Client’s User Interface

Responding to the user choosing a command

Whenever the user chooses a menu item or types a keyboard shortcut for a command created by your client, the FrameMaker product attempts to call your client’s F_ApiCommand() function. Your client should define this function as follows:

VoidT F_ApiCommand(command)

IntT command;

{

/* Code to respond to comman d choices goes here. */

}

This argument Means

command

Example

The value of the cmd parameter in the

F_ApiDefineAndAddCommand()

user chose

call that created the command that the

The following client defines some commands and adds them to the Special menu. It provides an F_ApiCommand() function to respond to the user choosing the commands.

#include "fapi.h" #define LOAD 1 #define QUERY 2

VoidT F_ApiInitialize(initia lization)

IntT initialization;

{

F_ObjHandleT specialMenuId;

/* Get the ID of the special menu. */ specialMenuId = F_ApiGetName dObject(FV_SessionId, FO_Menu,

"SpecialMenu"); /* Define the commands and a dd them to the Specia l menu. */ F_ApiDefineAndAddCommand(LOA D, specialMenuId,

"LoadDatabase", "Load Databa se","");

F_ApiDefineAndAddCommand(QUE RY, specialMenuId,

"QueryDatabase", "Query Data base", "");

}

VoidT F_ApiCommand(command)

IntT command;

{

switch(command) {

case LOAD: /* Code to load database goe s here. */

break;

case QUERY: /* Code to query database go es here. */

break;

}

FDK Programmer’ s Guide 29

Creating Your Client’s User Interface

Replacing FrameMaker product menus and commands

You can replace FrameMaker product menus and commands with your own menus and commands by calling F_ApiDefineAndAddCommand() and F_ApiDefineAndAddMenu() with the name parameter set to the name of a FrameMaker product menu or command.

For example, the following code replaces the FrameMaker product Print command:

. . . #define PRINT_CMD 223 F_ObjHandleT fileMenuId, pri ntCmdId; fileMenuId = F_ApiGetNamedOb ject(FV_SessionId, FO _Menu,

"FileMenu");

printCmdId = F_ApiDefineAndA ddCommand(PRINT_CMD, fileMenuId,

"Print", "Print...", "\\!fp" );

. . .

If you use this code, the Print command appears on the File menu exactly as it normally would. However, when the user chooses it, the FrameMaker product never executes the Print operation. Instead, it calls your client’s F_ApiCommand() callback with command set to PRINT_CMD . The F_ApiCommand() callback can execute your own version of the Print operation. For example, it can set the default number of copies to 1 and then call F_ApiSilentPrintDoc() t o print t he document. Th is pre v ents the u ser from pr inting mor e than one copy of a document at a time.

Allowing users to configure your client’s interface

When you call F_ApiDefineAndAddCommand() and specify the name of a command that is already defined in the user’s menu configuration files, the FrameMaker product gives precedence to the definition in the configuration files. If the configuration files assign a label or a shortcut to the command, the FrameMaker product uses it instead of the one you specify. If the command is already a menu item, the FrameMaker product ignores the menu that you specify and leaves the menu item where it is.

For example, if the Print command is already defined and appears on the File menu, the following code has the same effect as the sample code in the previous section:

. . . #define PRINT_CMD 223 F_ObjHandleT printCmdId, bog usMenuId = 12345; printCmdId = F_ApiDefineAndA ddCommand(PRINT_CMD, bogusMenuId,

"Print", "This is ignored", "This too");

. . .

If you use this code, the Print command appears on the File menu exactly as it normally does. Because FrameMaker gives precedence to the labels, shortcuts, and menu item locations

specified by the menu configuration files, users can configure your client’s interface. If users know the names of your client’s commands, they can assign labels and shortcuts to the

30 FDK Programmer’s Guide

Creating Your Client’s User Interface

commands and specify where the commands appear on the menus by editing their menu configuration files.

For example, if your client defines a command with the following code:

. . . F_ObjHandleT editMenuId; editMenuId = F_ApiGetNamedOb ject(FV_SessionId, FO _Menu,

"EditMenu");

F_ApiDefineAndAddCommand(1, editM enuId,

"NumberLines","Number Lines" , "\\!NL");

. . .

users can make the command appear on the Special menu instead of the Edit menu by adding the following line to their menu configuration files:

If users add this line to their menu configuration files and your client does not define the NumberLines command or is not running, the NumberLines menu item appears dimmed.

IMPORTANT: Adobe Systems recommends that you document the names of your client’s

menus and commands so that users can customize them.

For more information on using menu configuration files, see the online manual, Customizing FrameMaker. For more information on changing commands, menu items, and menus, see

Chapter 9, “Manipulating Commands and Menus with the API”

Using hypertext commands in your client’s user int erface

You can embed hypertext commands in markers within FrameMaker product documents. The basic set of FrameMaker hypertext commands allows you to establish links within and between documents and to jump from link to link.

You can lock a FrameMaker document that contains hypertext commands so that it behaves like a command palette. F or informati on on locking doc uments, see your FrameMaker pr oduct user documentatio n. Document s ha ve a set of properties that spe cify their char acter isti cs when they are locked. By setting these properties, you can change how a locked document window appears. For e xample, y ou can hide the scrol l bars an d the windo w c ontrol b utto ns. For a list of locked document properties, see ‘‘Document View Only properties’’ on page 578 of the FDK

Programmer’s Reference.

FrameMaker provides a special hypertext command, message apiclient, that can send messages to your client. With this command, you can create an extremely flexible user interface. Your client only needs to define re sponses for the hypert ext mes sages t hat are sent to it. Users and hypertext document designers can set up the interface that sends the messages. The message palettes for your client.

apiclient hypertext command is especially useful for setting up command

FDK Programmer’ s Guide 31

Creating Your Client’s User Interface

To use the message apiclient hypertext command in your client’s interface, follow the general steps below:

1. Set up the hypertext commands.

2. Create a function named F_ApiMessage() in your client to respo nd t o the user clicking

a hypertext marker that contains a message apiclient command.

These steps are discussed in greater detail in the following sections.

Setting up hypertext commands

The syntax for message apiclient is:

message apiclient y ourmessage

This argument Means

apiclient

yourmessage

The name under which the client is registered with the FrameMaker product. On UNIX platforms, it is the name specified in the

apiclients Modules [APIClients]

on registering FDK clients, see the FDK Platform Guide for your platform. The string that the FrameMaker product passes to the API client.

file. On the Macintosh, it is the name of the client file in the

folder. On Windows, it is the ClientName specified in the

section of the maker.ini file. For more information

When the user clicks a hypertext command, the FrameMaker product calls the F_ApiMess age() function of the client specified by by

yourmessage to the clien t.

Responding to message apiclient commands

To respond to the message apiclient hypertext command, your clie nt must define F_ApiMessage() as follows:

VoidT F_ApiMessage(message, docId, objId)

StringT message; F_ObjHandleT docId; F_ObjHandleT objId;

{ /* Code to respond to hypert ext message goes here . */ }

<Name> statement in the

apiclient and passes the string specified

This argument Means

message

docId

objId

The string from the hypertext command message The ID of the document containing the hypertext marker The ID of the hypertext marker the user clicked

32 FDK Programmer’s Guide

Example

Creating Your Client’s User Interface

Suppose you want to create a command palette with two arrows in it. When the user clicks an arrow, it changes the fill pattern of a selected graphic object in the active document. To make this command palette, create a document with the graphics shown in Figure 3.8.

FIGURE 3.8 Example hypertext markers

Assuming your client is registered with the FrameMaker product as myapi, insert the following hypertext markers into the document:

● In the text column around the up arrow: message myapi 1

● In the text column around the down arrow: message myapi 2

Save the document in View Only format. To respond to the user clicking one of the arrows, add the following code to your client:

. . . #define UPARROW 1 #define DOWNARROW 2

VoidT F_ApiMessage(message, docId, objId)

StringT message; F_ObjHandleT docId; F_ObjHandleT objId;

{ F_ObjHandleT targetDocId, ta rgetGraphicId; IntT fillpatt;

/* Get ID of active document . Note that View Only documents * are not considered active. */ targetDocId = F_ApiGetId(0, FV_SessionId, FP_Acti veDoc);

FDK Programmer’ s Guide 33

Creating Your Client’s User Interface

/* Get ID of selected object in active document. */ targetGraphicId = F_ApiGetId (targetDocId, targetD ocId,

FP_FirstSelectedGraphicInDoc) ;

if(!targetGraphicId) return;

/* Get selected object’s cur rent fill pattern. */ fillpatt = F_ApiGetInt(targe tDocId, targetGraphic Id, FP_Fill);

switch(atoi(message))

{ case UPARROW:

/* Only 16 patterns availabl e, so reset at 16. */ if (++fillpatt == 16) fillpa tt = 0; break;

case DOWNARROW:

if (--fillpatt == 0) fillpat t = 15; break;

}

/* Set the fill pattern of t he selected graphic. */ F_ApiSetInt(targetDocId, tar getGraphicId, FP_Fill , fillpatt); } . . .

For this example client to work, you should have the View Only document and one normal document open. Select a graphic in the normal document, then click one of the hypertext markers in the View Only docume nt.

Responding to user-initiated events or FrameMaker product

operations

Your client can respond when the user initiates certain events or FrameMaker product operations. For example, you may want your client to archive an extra copy of a document each time the user saves it, or to display a special dial og box when the user exits a document.

To make your client respond to events, follow these general steps:

1. Request notification for the events.

2. Create a callback function named F_ApiNotify() to respond to the events.

These steps are discussed in greater detail in the following sections.

Requesting notification for events

To receive notification for a particular event, your client must request it by calling F_ApiNotification().

The syntax for F_ApiNotification() is:

34 FDK Programmer’s Guide

Creating Your Client’s User Interface

IntT F_ApiNotification(IntT notification,

IntT state);

This argument Means

notification

state

A constant that specifies the notification point. See the table below for a list of the constants.

Specifies whether to turn notification for the notification point on or off. Specify

True to request notification or False to turn notification off.

For most events, there are se veral notification points, or stages in the event w hen the FrameMaker product can notify your client. For example, when the FrameMaker product saves a file, there are two notification points: one immediately before and one immediately after it saves the file. The following table lists the notification points and constants the FrameMaker product passes to F_ApiNotify() for some events.

Event or operation Notification points Notification constants

Frame binary document opened

Filterable document opened

Before checking the type of the file to be opened

After checking the type of the file to be opened

Before opening the file After opening the file Before checking the type of the

file to be opened

FA_Note_PreFileType

FA_Note_PostFileType

FA_Note_PreOpenDoc

FA_Note_PostOpenDoc

FA_Note_FilterIn

Document saved in Frame binary format

Document saved as filterable type

Document exited Before exiting the document

Before saving the documen t After saving the document Before saving the documen t

After exiting the document

FA_Note_PreSaveDoc

FA_Note_PostSaveDoc

FA_Note_FilterOut

FA_Note_PreQuitDoc

FA_Note_PostQuitDoc

For a complete list of e vents and notif icatio n points, see ‘‘F_ApiNotificat ion()’’ on page 226 of

the FDK Programmer’s Reference.

You can request notification in your client’s F_ApiInitialize() callback or anywhere you want in your client.

Example

Suppose you want the FrameMaker product to notify your client whenever the user exits a document. To request this notification when your client is first started, write the F_ApiInitialize() callback as follows:

FDK Programmer’ s Guide 35

Creating Your Client’s User Interface

. . . VoidT F_ApiInitialize(initia lization)

IntT initialization;

{

/* Request notification for exit. */ if (initialization == FA_Ini t_First)

F_ApiNotification(FA_Note_Pr eQuitDoc, True); } . . .

Requesting notification for API filters

API client filters do not need to request notification. To receive filter notifications, filters only need to be registered with the FrameMaker product. If they are correctly registered, filters receive the following notifications:

This type of filter Receives this notification

Import Export File-to-file

For more information on writing client filters, see “Writing filter clients” on page 239. For more information on registering filters, see the FDK Platform Guide for your platform.

Adding the F_ApiNotify() callback

The FrameMaker product notifies your client of events for which it has requested notification by calling its F_A piNotify () function. Your client should define F_ApiNotify() as follows:

VoidT F_ApiNotify(notificati on, docId, sparm, ipa rm)

IntT notification; F_ObjHandleT docId; StringT sparm; IntT iparm;

{

/* Code that responds to not ifications goes here. */

}

FA_Note_FilterIn

FA_Note_FilterOut

FA_Note_FilterFileToFile

This argument Means

notification

docId

A constant that indicates the event and the notification point (see the table on

page 35 for a list of some constants).

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.

36 FDK Programmer’s Guide

This argument Means

Creating Your Client’s User Interface

sparm

iparm

The string, if any, associated with the notification. For example, if the notification is for an Open or Save, affected file.

If the notification is for text entry, Depending on how fast the user is typing, several characters at a time.

The integer associated with the notification. For example, if

sparm specifies the pathname of the

sparm specifies the text the user typed.

sparm may specify one or

notification is FA_NotePreFunction or FA_NotePostFunction, iparm specifies the f-code for the

command.

F_ApiNoti fy() can call API functions to get or set object properties or to initiate FrameMaker product operations. The FrameMaker product calls F_ApiNotify() only at the notification points for which your client has requested notification.

For example, the following code prints the name of each document the user opens to the console:

. . . VoidT F_ApiInitialize(initia lization)

IntT initialization;

{

if (initialization == FA_Ini tFirst)

F_ApiNotification(FA_Note_Po stOpenDoc, True);

}

VoidT F_ApiNotify(notificati on, docId, sparm, ipa rm)

IntT notification; F_ObjHandleT docId; StringT sparm; IntT iparm;

{

if (notification == FA_Note_ PostOpenDoc)

F_Printf(NULL, "The user ope ned: %s\n", sparm); } . . .

Canceling commands

Your client can cancel any command or action for which it receives a FA_Note_P reNotificationPoint notification. For exampl e, if it receives the FA_Note_PreQuitDoc notification, it can cancel the Close command and prevent the user

from closing a document. To abort a command, call F_ApiReturnValue(), with the parameter set to

FR_CancelOperation, when your client receives notification for the command. For example, the following code cancels the Exit command, preventing the user from closing any documents:

FDK Programmer’ s Guide 37

Creating Your Client’s User Interface

. . . F_ApiNotification(FA_Note_Pr eQuitDoc, True); . . . VoidT F_ApiNotify(notificati on, docId, sparm, ipa rm)

IntT notification; F_ObjHandleT docId; StringT sparm; IntT iparm;

{

/* If user is trying to clos e document, cancel co mmand. */ if (notification == FA_Note_ PreQuitDoc)

F_ApiReturnValue(FR_CancelOp eration); } . . .

Responding to text entry and actions that have no specific noti fications

The API doesn’t provide specific notifications for most user actions. Instead, it provides the following general notifications, which it issues for nearly every user action.

Event or operation Notification points Notification constants

Any user action that the FrameMaker product processes

FrameMaker product command invoked or text entered in a document

After the FrameMaker product finishes processing the action

Before the FrameMaker product executes the command or adds text to the document

After the FrameMaker product executes the command or adds text to the document

FA_Note_BackToUser

FA_Note_PreFunction

FA_Note_PostFunction

The API issues the FA_NoteBackToUser notification aft er a ny user acti on the FrameMa ker product processes, including insertion point changes, selection changes, and text entry. This notification is useful if you need to update a modeless dialog box containing settings that are dependent on the insertion point.

When the API issues the FA_NoteBackToUser notification, it indicates only that an action occurred; it does not specify which action. If you want to respond to specific actions, use the

FA_Note_PreFunction or the FA_Note_PostFunction notification instead of FA_NoteBackToUser.

IMPORTANT: When the FrameMaker product performs a book-wide command (a command

that process all documents in a book), it posts an FA_NotePreFunction and FA_NotePostFinction notification for the book file, and another for each document in the book. When trapping book-wide fruncti ons , you sh oul d c heck the value of docId to determin e whether it indicate s a document or the a ct ive book.

For example, if you search a book with two documents in it, the FrameMaker product posts the following funtion notifications: FA_Note_PreFunction (start searching book)

38 FDK Programmer’s Guide

Creating Your Client’s User Interface

FA_Note_PreFunction (start searching first document) FA_Note_PostFunction (stop searching first document) FA_Note_PreFunction (start searching second document) FA_Note_PostFunction (stop searching second document) FA_Note_PostFunction (stop searching book)

When the API issues an FA_Note_PreFunction or FA_Note_PostFunction notification, it specifies the u ser action by setting iparm to a function code (f-code). An f-code is a hexadecimal code that specifies a command or other user action. The following table shows some common f-codes and the commands or user actions they specify.

F-code Command or user action

PGF_APPLY_TAG

CHAR_APPLY_TAG

TXT_10

KBD_OPEN

KBD_INPUT

KBD_ALIGN

The user applied a paragraph format The user applied a character format The user set the text size to 10 points The user chose Open The user typed some text The user chose Align

For a complete list of f-codes, see the fcodes.h file shipped with the FDK. If a user action is associated with a text string, the AP I passes the st ring to the sparm

parameter of yo ur cl ient’s F_ApiNotify() function. For example, when th e user types te xt, the API sets sparm to the text the user typed.

The following table lists some f-codes an d the strings that are associated with them.

F-code Associated string that the API passes to sparm

PGF_APPLY_TAG

CHAR_APPLY_TAG

KBD_INPUT

The name of the paragraph format the user applied. The name of the character format the user applied. The text the user typed. It can be one or more characters

depending on how fast the user types.

TXT_FAMILY_AND_VARIATION

The name of the font family the user chose.

Your client can cancel any action for which it receives the FA_Note_PreFunction notification b y calling F_ApiReturnValue() with retVal set to FR_CancelOperation. Your client can even cancel text entry.

For example, the following code intercepts any text the user attempts to type in a document and prints it to the console:

FDK Programmer’ s Guide 39

Creating Your Client’s User Interface

. . . #include "fcodes.h" /* Turn on notification. */ F_ApiNotification(FA_Note_Pr eFunction, True); . . . VoidT F_ApiNotify(notificati on, docId, sparm, ipa rm)

IntT notification; F_ObjHandleT docId; StringT sparm; IntT iparm;

{

if (notification == FA_Note_ PreFunction

&& iparm == KBD_INPUT)

{

F_Printf(NULL,"The user type d: %s\n", sparm); /* Prevent text from being a dded to document. */ F_ApiReturnValue(FR_CancelOp eration);

} } . . .

Responding to events initiated by API clients

FrameMaker notifies your client of any event that it has requested notification for. The event can be initiated directly by the user or by another client.

The Frame API provid es a s et of f unctions that allow API clients to pro gra mma ti cal l y execute Open, Save, a nd se v er al othe r FrameMak er pr oduct operat ions. F or mor e info rmatio n on thes e functions, see Chapter 4, “Executing Commands with API Functions” When a client executes an operation with one of these functions, the FrameMaker product notifies all the other API clients that have requested notification for that event

. It does not, however, notify the client that exe cuted the ope rati on. F or e xampl e, to have your client automatically mak e an ad diti onal copy of a document when the user saves it, use the following code:

. . . /* Turn on notification. */ F_ApiNotification(FA_Note_Po stSaveDoc, True); . . . VoidT F_ApiNotify(notificati on, docId, sparm, ipa rm)

IntT notification; F_ObjHandleT docId; StringT sparm; IntT iparm;

{

1. An API client can expl icitly instruct the Fr ameMaker produc t to suppress notif ications to othe r API clients when it ope ns or saves a file by setting th e on properties in the Open and Save scripts, see “F_ApiGetOpenDefaultParams() ” on page 138 and

‘‘F_ApiGetSaveDefaultParams()’’ on page 152 of t he FDK Programmer’s Reference.

FS_DontNotifyAPIClients property of the Open or Save script to True. For more information

40 FDK Programmer’s Guide

Creating Your Client’s User Interface

/* After the document has be en saved, save anothe r copy. */ if (notification == FA_Note_ PostSaveDoc)

F_ApiSimpleSave(docId, "mybackup. doc", False); } . . .

In the example above, F_ApiNotify(), which responds to a Save notification, uses F_ApiSimpleSave() to execute a Save operation itself. This does not result in infinite

recursion becau se the FrameMak er pr oduct do es not n otify t he clie nt of the Sa v e opera tion th at it executes itself.

Handling notification for Open operations

The Open operation is more complex than most other operations. FrameMaker product does the following when it opens a fil e:

1. Determines whether the file is filterable. If the file is f i lt erable, the FrameMaker produc t is sue s the FA_Note_FilterIn notification

to the appropriate filter and abandons the Open operation. It is up to the f i lter to f in ish ope ning the file. No other client receives any notification.

If the file is not filterable, the FrameMaker product continues with the Open operation.

2. Issues an FA_Note_PreFileType notification to all clients that have requested it. This allows clients to uncompress a file if it is compressed, check it out if it is under version

control, or perform other operations that may change its type.

3. Checks the file’s type. If the file i s a type that the FrameMak e r pr oduct can’t open, t he FrameMaker produc t displays

a warning and cancels the Open operation. If the file is from a previous version of a FrameMaker product, it prompts the user to convert the file or cancel the Open operation.

4. Issues an FA_Note_PostFileType notification to all clients that have requested it.

5. Determines whether the file is a document or a book, and whether its format is Frame

binary or MIF.

6. Issues an FA_Note_PreOpenDoc, FA_Note_PreOpenBook, FA_Note_PreOpenMIF,

or FA_Note_PreOpenBookMIF notification.

7. Opens the document or book. If the document or book is MIF, the FrameMaker product converts it.

8. Issues an FA_Note_PostOpenDoc, FA_Note_PostOpenMIF,

FA_Note_PostOpenBook, or FA_Note_PostOpenBookMIF notification.

Normally, you don’t request the FA_Note_PreFileType and FA_Note_PostFileType notifications, because you don’t want to do anything with a file before the FrameMaker product has checked its ty pe. Howe ve r , if you want to change a f ile’s contents after the user has

FDK Programmer’ s Guide 41

Creating Your Client’s User Interface

selected it but before the FrameMaker product has checked its type, you should request notification for the FA_Note_PreFileType notification point.

For example, suppose you want to uncompress a compressed document file when the user opens it. Normally, when a user attempts to open a compressed file, the FrameMaker product displays an “Unreco gnized typ e” alert and cancel s the Open op eration whe n it check s the f ile’s type. You must uncompress the file after the user has chosen it, but before the FrameMaker product checks its type. To do this, you could use the following code:

. . . F_ApiNotification(FA_Note_Pr eFileType, True); . . . VoidT F_ApiNotify(notificati on, docId, sparm, ipa rm)

IntT notification; F_ObjHandleT docId; StringT sparm; IntT iparm

{

if (notification == FA_Note_ PreFileType) { /* Code to test if file is c ompressed goes here. */ F_ApiAlert("Uncompressing fi le.", FF_ALERT_CONTIN UE_NOTE); /* Code to uncompress file g oes here. */

} } . . .

Implementing quick keys

FrameMaker provid es a quick-key interface , whi ch allows the us er to choose commands in the document Tag area. In FrameMaker, for example, the user can apply a character format by pressing Esc q c. FrameMaker displays an f: prompt in the Tag area. The user can then choose a character format by typing the first few letters of the format’s name and pressing Return when the format appears in the Tag area.

Your client can implement its own quick-key interface by calling F_ApiQuickSelect(). The syntax for F_ApiQuickSelect() is:

IntT F_ApiQuickSelect(F_ObjH andleT docId,

StringT prompt,

F_StringsT *stringlist);

This argument Means

docId

prompt

stringlist

The ID of the document containing the Tag area in which to display the prompt

The prompt that appears in the Tag area The list of strings from which the user can choose

42 FDK Programmer’s Guide

Creating Your Client’s User Interface

F_ApiQuickSelect() returns the index of the string the user chose or -1 if the user canceled th e command.

For example, the following code implements the quick-key interface shown in Figure 3.9:

. . . F_StringsT fruits; StringT strings[3]; IntT choice; F_ObjHandleT docId;

docId = F_ApiGetId(0, FV_Ses sionId, FP_ActiveDoc) ; strings[0] = (StringT)"Kumqu at"; strings[1] = (StringT)"Duria n"; strings[2] = (StringT)"Rambu tan"; fruits.len = 3; fruits.val = strings; choice = F_ApiQuickSelect(docId, (StringT)"F ruit:", &fruits);

if (choice != -1)

F_Printf(NULL, (StringT)"The user chose: %s.\n",

strings[choice]);

. . .

IGURE 3.9 Tag area with client-defined quick key

Freeing system resources by bailing out

Instead of leaving your client idle when it’s not executing, you may want to free the system resources it uses. The API provides a function named F_ApiBailOut(), which allows you to do this. When you call F_ApiBailOut(), the FrameMaker product w aits until your clien t returns from the curre nt ca ll back, t hen exits your client, freeing the s ystem reso urces it uses. If your client is a dynamically linked client on a UNIX platform, bailing out has no effect.

IMPORTANT: Never call exit(), F_Exit(), or abort() from an API client . If you c all

one of these functions, the function exits the FrameMaker product and unpredictable results, including data loss, may occur.

After it exits your client, the FrameMaker product continues processing events that affect it. Your client’s menus remain on the menu bar and are still valid. If your client has requested notification for particular events, the FrameMaker product continues to monitor those events. The FrameMaker product also monitors message apiclient hypertext commands that specify your client.

If the user chooses one of your client’s menu items or hypertext commands, or initiates an event for which your client requested notification, the FrameMaker product restarts your client, calling its F_ApiInitialize() function with initialization set to FA_Init_Subsequent. After F_ApiInitialize() has returned control, the

FDK Programmer’ s Guide 43

Creating Your Client’s User Interface

FrameMaker product also calls the appropriate callback function for the menu choice, hypertext command, or event.

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

The following code requests notification for the FA_Note_PreQuitDoc notification point and then bails o ut aft er t he use r s tarts t he FrameMa ker produ ct. If t he use r subs equentl y closes a document, it di spla ys dia log b ox es indica ting when the FrameMa ker produ ct r einit iali zes t he client and when it issues the FA_Note_PreQuitDoc notification.

. . . VoidT F_ApiInitialize(initia lization) IntT initialization; { switch (initialization){ case FA_Init_First:

/* Request notification. */

F_ApiNotification(FA_Note_Pr eQuitDoc, True);

/* Bail out and wait for the event. */

F_ApiBailOut(); break;

case FA_Init_Subsequent:

F_ApiAlert((StringT)"Client is reinitia lizing",

FF_ALERT_CONTINUE_NOTE); break; }

}

VoidT F_ApiNotify(notificati on, docId, filename) IntT notification; F_ObjHandleT docId; StringT filename; {

if (notification == FA_Note_ PreQuitDoc)

F_ApiAlert((StringT)"Client has reiniti alized.",

FF_ALERT_CONTINUE_NOTE);

}

44 FDK Programmer’s Guide

Executing Commands with API

Functions

This chapter discusses how to use Frame API functions to execute FrameMaker commands programmatically.

The API doesn’t provide a function to directly execute each of the commands available in the FrameMaker product user interface. This is because you can achieve the effect of some commands by setting object properties. For example, to set a graphic’s fill pattern, you set the object’s FP_Fill property . For more informati on on settin g object prop erties, se e Chapter 5,

“Getting a nd Setting Properties”

Handling errors

When an API f unction fails, it stores an err or 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 fun ction calls has failed, ini tialize FA_errno to FE_Succ ess once before all the calls and check it once after all the calls .

T o f ind t he error codes a func tion can g enerate, l ook up the f unction i n the FDK Programmer’s Reference. For a list of all API error codes and their meanings, see the fapidefs.h header

file included with FDK or Chapter 5, “Error Codes” in the FDK Programmer’s Reference. In the interest of brevity, the examples in this chapter do not include error-handling code. However, you should check FA_errno after calling functions that set it.

Handling messages and warnings

In the user interface, some commands such as Open and Save sometimes need to prompt the user with warnings or messages. The API provides two types of functions to execute these commands:

● Simple functions allow you to either supp ress the messages and warnings entirely or to

prompt the user with them.

● Scriptable functions allow you to specify a response for each possible message or warning.

Using simple functions

Simple functions enable you to execute commands such as Save and Open without specifying numerous parameters. They execute these commands in either an interactive or a noninteractive mode. If you call a simple function and specify the interactive mode, the FrameMaker product behaves exactly as it would if the user had initiated the command. If a message or warning condi tion occurs, the FrameMaker product prompt s the user . F or examp le,

FDK Programmer’ s Guide 45

Executing Commands with API Functions

if you call F_ApiSimpleOpen() in the interact ive mode, the FrameMaker prod uct di spl ays the Open dialog box and prompts the user to choose a file to open. If the user chooses a text file, the FrameMaker product displays a Reading Text File dialog box.

If you are sure that ex ecuting a command won’ t do something unde sirable , and you don’ t want the FrameMaker product to display error and warning messages, call a simple function in noninteractive mode. Be careful when you do this, because you may inadvertently destroy data. For exampl e, suppose you attempt to sav e a file by call ing F_ApiSimpleSave() in the noninteractive mode. If the file already exists, the FrameMaker product overwrites it without warning your clie nt or th e user. Noninteractive mode is useful for cl ients that ne ed to car ry ou t tasks without a user present.

Using scriptable functions

To specify a response for each possi ble mes sage o r wa rning t hat t he Fra meMak er pr oduct may issue while executing a command, use a scriptable function to execute the command. When you call a scriptable function, you pass it a script or property list that contains properties corresponding to possib le mes sag es or warnings. For most mes sag es and warnings, you eith er specify a Yes, No, or Cancel response, or you can instruct the FrameMaker product to prompt the user for the response. Scriptable functions return detailed information on how the FrameMaker product executes a command. For example, the scriptable Open function F_ApiOpen () returns information, such as whether the file was filtered and whether an Autosave file was used.

The API provides a function named F_ApiAllocatePropVals(), which allocates a property list that you can use with scriptable functions. The API also provides functions that create defaul t scri pts fo r the di f fer ent scr ipta ble functi ons. You can use these functions to get a default script and then customize the script by changing individual properties.

Opening documents and books

The API provides two functions to open a document or book:

● F_ApiSimpleOpen() is an easy-to-use function for opening a document or book.

● F_ApiOpen() allows you to script the process of opening a document or book.

Opening a document or book with F_ApiSimpleOpen()

The syntax for F_ApiSimpleOpen() is:

F_ObjHandleT F_ApiSimpleOpen (StringT fileName,

BoolT interactive);

46 FDK Programmer’s Guide

This argument Means

Executing Commands with API Fu nctions

fileName

interactive

The absolute pathname of the file to open. For information on how filenames and paths on different platforms are expressed, see the FDK Platform Guide for your platform.

Specifies whether the FrameMaker product displays messages and warnings to the user.

If F_ApiSimpleOpen() is successful, i t retur ns the I D of th e FO_Doc or FO_Book object that represents the document or book that it opened. If a condition (such as a nonexistent file) makes it impossible to open a file, F_ApiSimpleOpen() aborts the operation and returns 0.

If you set interactive to True, the FrameMaker product displays the Open dialo g box. It uses the path specified by the session property FP_OpenDir as the default path. The FrameMaker product also displays all the other messages and warnings it would normally display if the user chose the Open command. For example, if a document contains fonts that are not available in the current session, the FrameMaker product displays a “Fonts Unavailable. Open Anyway?” dialog box. If the user clicks Cancel, F_ApiSimpleOpen() aborts the operation and returns 0 .

If you set interactive to False, the FrameMaker product does not display the Open dialog box or other messages and warnings. If it is necessary to modify a file to continue opening it, F_ApiSimpleOpen() aborts the operation without notifying the user, and returns 0. For example, if a document contains fonts that are not available, F_ApiSimpleOpen() aborts the Open operation instead of converting the fonts.

Example

The following code opens a document named /tmp/my.doc1 and displays its ID:

. . . #include "futils.h" F_ObjHandleT docId; UCharT msg[256];

docId = F_ApiSimpleOpen((Str ingT)"/tmp/my.doc", F alse);

if (!docId)

F_ApiAlert((StringT)"Couldn’ t open.",FF_ALERT_CON TINUE_NOTE);

else

{

F_Sprintf(msg, (StringT)"my. doc’s ID is 0x%x.", d ocId); F_ApiAlert(msg, FF_ALERT_CON TINUE_NOTE);

}

. . .

1. Examples in this manual use UNIX pathnames. For information on specifying pathnames on other platforms, see the FDK Platform Guide for that platform.

FDK Programmer’ s Guide 47

Executing Commands with API Functions

Opening a document or book with F_ApiOpen()

To open a document or book and programmatically specify responses to warnings and messages that the Fra meMaker pr oduct issue s, use F_ApiOpen(). With F_ApiOpen(), you can specify aspects of the Open operation, such as whether to make a document visible and whether to use an Autosave file. You can specify all aspects of the operation, or you can specify some aspects and allow the user to decide others. For example, you can instruct the FrameMaker product to only open a MIF file but allow the user to choose the file.

To use F_ApiOpen(), you should first underst and pro perty l ists and how to manipulate them directly. For more info rmation on th is subject, s ee “Representing object characteristics with

properties” on page 270 and “Manipulating property lists directly” on page 93.

The syntax for F_ApiOpen() is:

F_ObjHandleT F_ApiOpen(Strin gT fileName,

F_PropValsT *openParamsp, F_PropValsT **openReturnPara mspp);

This argument Means

fileName

openParamsp

openReturnParamspp

IMPORTANT: Always initialize the pointer to the property list that you specify for

The absolute pathname of the file to open. If you are using

F_ApiOpen()

A property list (script) that tells the FrameMaker product how to open the file and how to respond to errors and other conditions that arise. Use

F_ApiGetOpenDefaultParams() or

F_ApiAllocatePropVals()

for this property list. To use the default list, specify A property list that returns the pathname and provides information

on how the FrameMaker product opened the file.

to create a document, specify the template name.

to create and allocate memory

NULL.

openReturnParamspp to NULL before you call F_ApiOpen().

If F_ApiOpen() is successful, it returns the ID of the opene d doc ument or b ook. Other wise, it returns 0.

To call F_ApiOpen(), do the following:

1. Initialize the pointer to the op enRet urnPar amspp property list to NULL.

2. Create an openParamsp property list.

You can get a default list by calling F_ApiGetOpenDefaultParams(), or you can create a list from scratch.

3. Call F_ApiOpen ().

4. Check the Open status.

Check the returned values in th e openReturnParamspp list for the name of the opened file and other information about how the FrameMaker product opened the file.

48 FDK Programmer’s Guide

Executing Commands with API Fu nctions

5. Deallocate memory for the openParamsp and openReturnParamspp prope rty lists. Use F_ApiDeallocatePropVals() to deallocate memory fo r the lists.

Steps 2, 4, and 5 are discussed in the following sections.

Creating an ope nParamsp script with F_Ap iGetOpenD efaultParams()

If you need to specify a number of properties in the openParamsp property list, it is easiest to get a default list with F_ApiGetOpenDefaultParams() and then modify individual properties in the list.

The syntax for F_ApiGetOpenDefaultParams() is:

F_PropValsT F_ApiGetOpenDefaultPa rams();

The following table lists some of the properties in the property list returned by F_ApiGetOpenDefaultParams(). The first value listed for each property is the default

value used in the list. You can chang e the list to use the other listed values. For the complete list of properties in the proper ty list , see ‘‘F_ApiGetOpenDefaultPa rams()’’ on page 138 of the

FDK Programmer’s Reference.

Property Instruction or situation and possible values

FS_ShowBrowser

Display Open dialog box.

False: don’t display it. True: display it.

FS_OpenDocViewOnly

Open document as View Only.

False: don’t open as View Only. True: open as View Only.

FS_NameStripe

FS_NewDoc

String specifying the name that appears on the document title bar. Setting this property on Macintosh platforms has no effect.

NULL.

Create a new document.

False: open an existing document. True: create a new document.

For example, to g et a default openParamsp property list and modify it so that it instructs F_ApiOpen () to show the Open dialog box, use the following code:

. . . F_ObjHandleT docId; F_PropValsT params, *returnP aramsp = NULL; IntT i;

/* Get a default property li st. */ params = F_ApiGetOpenDefaultParams();

FDK Programmer’ s Guide 49

Executing Commands with API Functions

/* If F_ApiGetOpenDefaultPar ams() fails, len will be 0. */ if(params.len == 0) return;

/* Get index of FS_ShowBrows er property, then set it to True. */ i = F_ApiGetPropIndex(¶m s, FS_ShowBrowser); params.val[i].propVal.u.ival = True;

/* Change default to /tmp wh en Open dialog box ap pears. */ F_ApiSetString(0, FV_SessionId, FP_Open Dir, "/tmp");

docId = F_ApiOpen("", ¶m s, &returnParamsp); F_ApiDeallocatePropVals(&par ams); F_ApiDeallocatePropVals(retu rnParamsp); . . .

The API allocates memo ry for the prop erty list created by F_ApiGetOpenDefaultParams(). Use F_ApiDeallocatePropVals() to free the

property list when you are done with it. For another example of how to call F_ApiO pen() using a default

property list created by F_ApiGetOpenDefaultParams(), see

‘‘F_ApiGetOpenDefaultParams()’’ on page 138 of the FDK Programmer’s Reference.

Creating an openParamsp script from scratch

If you only need to specif y a few properties when you call F_ApiOpen(), it is most efficient to create a propert y list from s cratc h. To create the proper ty li st, you mus t all ocate memory for it and then set up the individual properties.

To allocate memory for the property list, use the API convenience function,

F_ApiAllocatePropVals(). The syntax for F_ApiAllocatePropVals() is:

F_PropValsT F_ApiAllocatePropVals (IntT numProps);

This argument Means

numProps

The number of properties for which to allocate memory

For example, the following code creates an openParamsp property list that instructs

F_ApiOpen () to show the Open dialog box:

. . . F_ObjHandleT docId; F_PropValsT params, *returnP aramsp = NULL;

/* Allocate memory for the l ist. */ params = F_ApiAllocatePropVals(1);

/* Set up the FS_ShowBrowser property and set it to True. */ params.val[0].propIdent.num = FS_ShowBr owser; params.val[0].propVal.valTyp e = FT_Integer; params.val[0].propVal.u.ival = True;

50 FDK Programmer’s Guide

Executing Commands with API Fu nctions

docId = F_ApiOpen("", ¶m s, &returnParamsp); F_ApiDeallocatePropVals(&par ams); F_ApiDeallocatePropVals(retu rnParamsp); . . .

The API allocates memo ry for the prop erty list created by F_ApiAllocatePropVals(). Use F_ApiDeallocatePropVals() to free the property list when you are done with it.

Checking the Open status

F_ApiOpen () stores a pointer to a property list (F_PropValsT structure) in openReturnParamspp. To get the name of the file that F_ApiOpen() opened and other

information about ho w F_ApiOpen() opened the f ile, c heck this propert y list. It incl udes the properties shown in the following table.

Property Meaning and possible values

FS_OpenedFileName

FS_OpenNativeError

FS_OpenStatus

A string that specifies the opened file’s pathname. If you scripted

FS_ShowBrowser

the pathname, this pathname can be different from the one you specified in the Open script.

The error condition. If the file is opened successfully, it is set to

FE_Success

to, see ‘‘F_ApiOpen()’’ on page 238 of the FDK Programmer’s

Reference.

A bit field indicating what happened when the file was opened. F or a complete list of the possible status flags, see ‘‘F_ApiOpen()’’ on

page 238 of the FDK Programmer’s Reference.

, or the file was filtered, or you didn’t specify

. For a complete list of the other values it can be set

The FS_OpenNativeError property and the FA_errno global v ar iable indicate the resul t of a call to F_ApiOpen(). The FS_OpenStatus flags indicate how or why this result occurred. For example, if you attempt to open a file with F_ApiOpen() and the Open operation is canceled , FS_OpenNativeError and FA_errno are set to FE_Canceled. If the operation was canceled because the user canceled it, the FV_UserCanceled bit of the FS_OpenSt atus property list is set.

The API provides a function named F_ApiCheckStatus(), which allows you to determi ne if a particular FS_OpenStatus bit is set. Th e syntax for F_ApiCheckStatus() is:

IntT F_ApiCheckStatus(F_Prop ValsT *p,

IntT statusBit);

This argument Means

statusBit

FDK Programmer’ s Guide 51

The openReturnParamspp property list returned by F_ApiOpen() The status bit you want to test

Executing Commands with API Functions

If the specified bit is set, F_ApiCheckStatus() returns True. For example, the following code determines if an Open operation was canceled because a document used unavailable fonts:

. . . F_ObjHandleT docId;

F_PropValsT params, *returnP aramsp = NULL;

/* Get default property list . */ params = F_ApiGetOpenDefaultParams();

docId = F_ApiOpen("/tmp/my.d oc", ¶ms, &return Paramsp); if (F_ApiCheckStatus(returnP aramsp, FV_CancelFont sMapped))

F_ApiAlert("Canceled because my.doc has unavailab le fonts.",

FF_ALERT_CONTINUE_NOTE);

/* Deallocate property lists . */ F_ApiDeallocatePropVals(&par ams); F_ApiDeallocatePropVals(retu rnParamsp); . . .

The API also provides a convenience function named F_ApiPrintOpenStatus(), which prints the Open status values to the console on UNIX platforms, the error log window on the Macintosh, and the Frame console on Windows. F_ApiPrintOpenStatus() is useful for debugging clients that use F_ApiOpen(). For more information, see

‘‘F_ApiPrintOpenStatus()’’ on page 250 of the FDK Programmer’s Reference.

Deallocating Open script property lists

After you are done with the Open script property lists, call the API convenience function, F_ApiDeallocatePropVals(), to free the memory they use.

The syntax for F_ApiDeallocatePropVals() is:

VoidT F_ApiDeallocatePropVal s(F_PropValsT *pvp);

This argument Means

pvp

Example

The property list

The following code opens a document named /tmp/my.doc. It creates a property list that instructs F_ApiOpen() to ope n the document as View Only and to display the title, Doc, in the title bar.

. . . #include "fstrings.h"

F_PropValsT params, *returnP aramsp = NULL; F_ObjHandleT docId;

/* Allocate memory for Open scrip

52 FDK Programmer’s Guide

Executing Commands with API Fu nctions

with two properties. */ params = F_ApiAllocatePropVals(2); if(params.len == 0) return;

/* Force title displayed on title bar to be "Doc" . */ params.val[0].propIdent.num = FS_NameSt ripe; params.val[0].propVal.valTyp e = FT_String; params.val[0].propVal.u.sval = (StringT)F_StrCopy String("Doc");

/* Open the file as View Onl y. */ params.val[1].propIdent.num = FS_OpenDo cViewOnly; params.val[1].propVal.valTyp e = FT_Integer; params.val[1].propVal.u.ival = True;

/* Open /tmp/my.doc. */ docId = F_ApiOpen("/tmp/my.d oc", ¶ms, &return Paramsp);

/* Free memory used by the O pen scripts. */ F_ApiDeallocatePropVals(&par ams); F_ApiDeallocatePropVals(retu rnParamsp); . . .

Creating documents

To create a new document, you can use the following functions:

● F_ApiSimpleNewDoc() is an easy-to-use function that allows you to specify a template

and interactive or noninteractive modes.

● F_ApiCustomDoc() uses the FrameMaker produ ct’s default new d ocument temp late and

some parameters that you specify to create the new do cument.

● F_ApiOpen() allows you to script the New operation.

For informat ion on cr eatin g books , see “Cre ating a book” on page 146. The following sec tions describe how to create a new document in greater detail.

Creating a document with F_ApiSimpleNewDoc()

To create a new document from a specific template, use F_ApiSimpleNewDoc(). The syntax for F_ApiSimpleNewDoc() is:

F_ObjHandleT F_ApiSimpleNewD oc(StringT templateNa me,

IntT interactive);

FDK Programmer’ s Guide 53

Executing Commands with API Functions

This argument Means

templateName

interactive

The absolute pathname of the template to use. For information on how filenames and paths on different platforms are expressed, see the FDK Platform Guide for that platform.

Specifies whether the FrameMaker product d isplays mess ages and warnings to the user.

If you set interactive to True, the FrameMaker product creates a document from the specified t empla te and displays messa ges and warnings t o t he user. If you set interactive to False, the FrameMaker product does not display messages and warnings; if the FrameMaker product encounters a condition for which it normally displays a dialog box, F_ApiSimpleNewDoc() attempts to do what’s necessary to continue creating the file.

If F_ApiSimpleNewDoc() is successful, it returns the ID of the document it created; otherwise, it returns 0. You don’t provide the name for the new document until you save it.

IMPORTANT: If you call F_ApiSimpleNewDoc() with interactive set to True and

the user clicks Portrait, Custom, or Landscape in the New dialog box, F_ApiSimpleNewDoc() does not create a document. It retu rns 0 and sets FA_errno to FE_WantsPortrait, FE_WantsCustom, or FE_WantsLandscape. It is up to your client to create a portrait, custom, or

landscape document by calling F_ApiCustomDoc(). For more information on creating custom documents, see “Creating a custom document” on

page 55.

Example

The following code creates a document from the /templates/Reports/Report1 template and saves it as /tmp/mynew.doc. It then uses F_ApiSimpleSave() to save the the document. For more information on F_ApiSimpleSave(), see “Saving documents and

books” on page 59

. . . F_ObjHandleT docId;

docId = F_ApiSimpleNewDoc("/ templates/Reports/Rep ort1", False);

if (!docId)

F_ApiAlert("Can’t create doc ument.", FF_ALERT_CON TINUE_NOTE);

else

F_ApiSimpleSave(docId, "/tmp/myne w.doc", False);

. . .

54 FDK Programmer’s Guide

Creating a custom document

To create a custom new document, use F_ApiCustomDoc(). This function uses th e FrameMaker product’s default new-document template to create the custom document. For more information on the default new-document template, see “Documents” on page 279.

The syntax for F_ApiCustomDoc() is:

Executing Commands with API Fu nctions

F_ObjHandleT F_ApiCustomDoc(MetricT

MetricT height, IntT numCols, MetricT columnGap, MetricT topMargin, MetricT botMargin, MetricT leftinsideMargin, MetricT rightoutsideMargin, IntT sidedness, BoolT makeVisible);

This argument Means

width

height

numCols

columnGap

topMargin

Page width. The Frame API expresses linear measurements with

MetricT

Chapter 4, “Data Types and Structures Reference,” in the FDK Programmer’s Reference.

Page height. Default number of columns. Default column spacing. Page top margin.

values. For more information on MetricT values, see

width,

botMargin

leftinsideMargin

rightoutsideMargin

sidedness

makeVisible

Page bottom margin. Left margin (for single-sided documents) or the inside margin (for

double-sided documents). Right margin (for single-sided documents) or the outside margin (for

double-sided documents). Constant that specifies whether the document is single-sided or

double-sided and on which side the document starts. See the following table for the list of constants.

Specifies whether to make the document visible. True makes it visible.

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

FDK Programmer’ s Guide 55

Executing Commands with API Functions

sidedness constant New document page characteristics

FF_Custom_SingleSided

FF_Custom_FirstPageRight

FF_Custom_FirstPageLeft

Single-sided Double-sided, starting with a right page Double-sided, starting with a left page

If successful, F_ApiCustomDoc() returns the ID of the document it created. Otherwise, it returns 0.

Example

The following code creates a custom document with the characteristics specified in the dialog box in Figure 4.1:

. . . #include "fmetrics.h" #define in (MetricT)(65536*7 2) /* A Frame metric inch */

F_ObjHandleT docId;

docId = F_ApiCustomDoc(F_Met ricFractMul(in,17,2), 11*in, 1,

F_MetricFractMul(in,1,4), in , in, in, in,

FF_Custom_SingleSided, True);

. . .

IGURE 4.1 Specifications for custom document

Creating a document with F_Api Open()

To create a document with F_ApiOpen(), set the FS_NewDoc property in the openParam sp script to True. For the syntax of F_ApiOpen(), see “Opening a document

or book with F_ApiOpen()” on page 48.

When you use F_ApiOpen() to create a document, set fileName to the name of the template that you want to use. You don’t provide the name for the new document until you save it.

56 FDK Programmer’s Guide

Executing Commands with API Fu nctions

For example, the fol lowing code cr eates a document from a template named /tmp/template and saves it as /tmp/mynew.doc.

. . . F_ObjHandleT docId; F_PropValsT params, *returnP aramsp = NULL;

params = F_ApiAllocatePropVals(1); if(params.len == 0) return;

/* Set up the FS_NewDoc prop erty and set it to Tr ue. */ params.val[0].propIdent.num = FS_NewDoc ; params.val[0].propVal.valTyp e = FT_Integer; params.val[0].propVal.u.ival = True;

docId = F_ApiOpen("/tmp/temp late", ¶ms, &retu rnParamsp);

/* See “Saving documents and book s” on page 59 for syntax. */ F_ApiSimpleSave(docId, "/tmp/myne w.doc", False);

/* Deallocate property lists . */ F_ApiDeallocatePropVals(&par ams); F_ApiDeallocatePropVals(retu rnParamsp); . . .

IMPORTANT: If you are cr ea ting a document with F_ApiOpen() and you display t he New

dialog box (by setting FS_ShowBrowser to True), the user may click Portrait, Custom, or Landscape. If this occurs, F_ApiOpen() does not create a new document. It returns 0 and sets FA_errno to FE_WantsPortrait, FE_WantsCustom, or FE_WantsLandscape. It is up to your client to create a portrait, custom, or landscape document by calling F_ApiCustomDoc().

Printing documents and books

T o print a document or boo k, use F_ApiSilentPrintDoc(). F_ApiSilentPrintDoc() uses the default print setti ngs for a document. The default print setti ngs are the se ttings that appear in the Print dialog box when the user attempts to print the document in the user interface.

The syntax for F_ApiSilentPrintDoc() is:

IntT F_ApiSilentPrintDoc(F_O bjHandleT docId);

This argument Means

docId

The ID of the document or book to print

FDK Programmer’ s Guide 57

Executing Commands with API Functions

When you call F_ApiSilentPrintDoc(), the FrameMaker product doesn’t not if y t he user about error or warning conditions that occur when it attempts to print. To determine whether an error occurred, check FA_errno .

Changing the print settings for a document

When you print a document in the user interfa ce, you can cha nge the print settings in the Print dialog box. FrameMaker sa ves most print settings with a document . For exampl e, if you set the scale to 90 percent and print the document in the same session or save the document, the default setti ng for the scale will be 90 percent. Similarly, if an API client calls F_ApiSilentPrintDoc() to print the document, the scale will be 90 percent, if the client doesn’t change it.

The API represents a document’s print settings with a set of document properties. For example, a doc ument’s FP_PrintNumCopies property specifies t he number o f copies of the document to print. To change a print setting programmatically, you change the property that represents it. For more information on changing properties, see Chapter 5, “Getting and

Setting Properties” For a list of document print properties, see ‘‘Document print p roperties’’ on page 561 of the FDK Programmer’s Reference.

Examples

The following code opens a document named /tmp/my.doc and p rints it using the default print settings:

. . . F_ObjHandleT docId; docId = F_ApiSimpleOpen("/tmp/my. doc", False); F_ApiSilentPrintDoc(docId); . . .

The following code opens /tmp/my.doc and modifies its default print settings so that the FrameMaker product will prin t t wo copi es of t he docu ment t o a pri nter n amed ps2. I t does t his by setting the document pro perti es that specif y the numbe r of copi es (FP_PrintNumCopies) and the printer (FP_PrinterName) to 2 and ps2, respectively:

. . . F_ObjHandleT docId;

/* Open the document. */ docId = F_ApiSimpleOpen("/tmp/my. doc", False);

/* Change my.doc’s print pro perties. */ F_ApiSetInt(FV_SessionId, do cId, FP_PrintNumCopies , 2); F_ApiSetString(FV_SessionId, docId, FP_PrinterNam e, "ps2");

F_ApiSilentPrintDoc(docId); . . .

58 FDK Programmer’s Guide

Executing Commands with API Fu nctions

If you save /tmp/my.doc or attempt to print it within th e same session, the default printer will be ps2 and the defa ult number of copies will be 2 unless your client or the user changes the values of FP_PrinterName and FP_PrintNumCopies.

Saving documents and books

To save a document or book, use one of the following functions:

● F_ApiSimpleSave() is an easy-to-use function for saving a document or book.

● F_ApiSave() allows you to script the process for saving a document or book.

Saving a document or book with F_ApiSimpleSave()

The syntax for F_ApiSimpleSave() is:

F_ObjHandleT F_ApiSimpleSave (F_ObjHandleT docId,

StringT saveAsName, IntT interactive);

This argument Means

docId

saveAsName

interactive

ID of the document or book to save. Name of the pathname to save the document or book to. For information on

how filenames and paths on different platforms are represented, see the FDK Platform Guide for that platform.

Specifies whether the FrameMaker product displays messages and warnings to the user (

True to display messages and warnings).

If you set interactive to False and you specify the document or book’s current name, the FrameMaker product saves the document or book under its current name. If you specify another filename for saveAsN ame, the FrameMaker product saves the document or book to that filename.

If you set interactive to True, the FrameMaker product displays the Save dialog box and allows th e user t o choose a f ilena me. The documen t or book ’s current name appears as the default name.

If F_ApiSimpleSave() is successful, it returns the ID of the document it saved. If you save the documen t under its current name, the returned ID is the same ID you specified in the docId parameter . If you sp ecify ano ther f ilen ame for saveAsName, the re turned ID is th e ID of the new document. If F_ApiSimpleSave() can’t save the file, it returns 0.

Example

The following code opens and then saves a document named /tmp/my.doc. After it has saved the document as /tmp/my.doc, it saves a copy of it as mynew.doc:

FDK Programmer’ s Guide 59

Executing Commands with API Functions

. . . #include "futils.h" F_ObjHandleT mydocId, mynewd ocId; UCharT msg[256];

mydocId = F_ApiSimpleOpen("/ tmp/my.doc", False);

/* Save my.doc as itself. */ F_ApiSimpleSave(mydocId, "/t mp/my.doc", False);

/* Save my.doc as mynew.doc. */ mynewdocId = F_ApiSimpleSave (mydocId, "/tmp/mynew .doc", False);

/* If the Save As was succes sful, display ID of m ynew.doc. */ if (!mynewdocId)

F_ApiAlert("Couldn’t save as mynew.doc.",

FF_ALERT_CONTINUE_NOTE);

else {

F_Sprintf(msg, "The ID of my new.doc is 0x%x.", my newdocId); F_ApiAlert(msg, FF_ALERT_CON TINUE_NOTE); }

. . .

Saving a document or book with F_ApiSave()

To save a document or book and specify responses to warnings and messages that the FrameMaker product issues, use the scriptable save function, F_ApiSave(). With F_ApiSave (), you can specify aspects of the Save operation, such as the file format (for example, MIF or Text Only) and the UNIX file permissions. You can specify all aspects, or you can specify some and allow the user to decide others. For example, you can specify that the FrameMaker product should save a document as Text Only, but allow the user to decide how to convert the document’s tables to text.

The syntax for F_ApiSave() is:

F_ObjHandleT F_ApiSave(F_Obj HandleT docId,

StringT saveAsName, F_PropValsT *saveParamsp, F_PropValsT **saveReturnPara mspp);

This argument Means

docId

saveAsName

saveParamsp

The ID of the document or book to save. The pathname to save the document or book to. 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() F_ApiAllocatePropVals()

for this property list. To use the default list, specify

to create and allocate memory

NULL.

60 FDK Programmer’s Guide

This argument Means

Executing Commands with API Fu nctions

saveReturnParamspp

IMPORTANT: Always initialize the pointer to the property list that you specify for

A property list that returns information about how the FrameMaker product saved the file.

saveReturnParamspp to NULL before you call F_ApiSave().

If F_ApiSave() is successful, it returns the ID of the document or book it saved. If F_ApiSave () performs a Save operation, it returns the ID that you specified in the docId

parameter. If F_ApiSave() perform s a Save As operation, it returns the ID of the new document or book. If F_ApiSave() can’t save a file, it returns 0.

To call F_ApiSave(), do the following:

1. Initialize the pointer to the sa veRet urnPar amspp property list to NULL.

2. Create a saveParamsp property list.

You can get a default list by calling F_ApiGetSaveDefaultParams(), or you can create a list from scratch.

3. Call F_ApiSave ().

4. Check the Save status.

Check the returned values in th e saveReturnParamspp list for the name of the s aved file and other in formation about how the FrameMaker pro duct saved the file.

5. Deallocate the saveParamsp and saveReturnParamspp property lists. Steps 2, 4, and 5 are discussed in the following sections.

Creating a saveParamsp script with F_ApiGetSaveDefaultParams()

The API provides a function named F_ApiGetSaveDefaultParams() that creates a default save Paramsp property list. If you are setting a number of properties, it is easiest to use F_ApiGetSaveDefaultParams() to get a default property list and then change individual properties as needed.

The syntax for F_ApiGetSaveDefaultParams() is:

F_PropValsT F_ApiGetSaveDefaultPa rams();

The following table lists some of the properties in the property list returned by F_ApiGetSaveDefaultParams(). The first value listed for each property is the default

value returned by F_ApiGetSaveDefaultParams(). You can change the list to use the other listed values.

FDK Programmer’ s Guide 61

Executing Commands with API Functions

Property Meaning and possible values

FS_FileType

FS_AlertUserAboutFailure

Specifies the type of file to save to FV_SaveFmtBinary: save in Frame binary format for this

version of FrameMaker. FV_SaveFmtBinary60: save in binary format for

FrameMaker 6.0

FV_SaveFmtInterchange: save as MIF. FV_SaveFmtStationery: save in Stationery format

(Macintosh only).

FV_SaveFmtViewOnly: save in View Only format FV_SaveFmtSgml: save in SGML format. FV_SaveFmtText: save in Tex t On ly format. FV_SaveFmtXml: save in XML format. FV_SaveFmtPdf: save as PostScript, and then invoke

Acrobat Distiller This is the same as choosing PDF from the Format popup menu in the Save As dialog box.

Specifies whether to notify the user if something unusual occurs while the file is being saved

to create a PDF version of the document.

False: don’t notify user True: notify user

FS_SaveMode

Specifies whether to use Save or Save As mode

FV_ModeSaveAs: use Save As mode FV_ModeSave: us e Save mode

a. Note: This will only work if the Acrobat Distiller software is installed on the system.

For the comple te property list returned by F_ApiGetSaveDefaultParams(), see

‘‘F_ApiGetSaveDefaultParams()’’ on page 152 of the FDK Programmer’s Reference.

For example, to g et a default saveParamsp property list and modify it so that it instructs

F_ApiSave () to save the active document as Text Only, use the following code:

. . . F_PropValsT params, *returnP aramsp = NULL; F_ObjHandleT mydocId; IntT i;

/* Get the ID of the active document. */

62 FDK Programmer’s Guide

Executing Commands with API Fu nctions

mydocId = F_ApiGetId(0, FV_S essionId, FP_ActiveDo c);

/* Get default property list . */ params = F_ApiGetSaveDefaultParams();

FDK Programmer’ s Guide 63

Executing Commands with API Functions

/* Get index of FS_FileType property and set it t o Text Only. */ i = F_ApiGetPropIndex(¶m s, FS_FileType); params.val[i].propVal.u.ival =

/* Save to text only file na med my.txt. */ F_ApiSave(mydocId, "/tmp/my. txt", ¶ms, &retur nParamsp);

/* Deallocate property lists . */ F_ApiDeallocatePropVals(&par ams); F_ApiDeallocatePropVals(retu rnParamsp); . . .

The API allocates memo ry for the prop erty list created by F_ApiGetSaveDefaultParams(). Use F_ApiDeallocatePropVals() to free the

property list when you are done with it.

Creating a saveParamsp script from scratch

If you want to sp eci fy onl y a f ew properties when you call F_ApiSave(), it is most effi ci ent to create a propert y list from s cratc h. To create the proper ty li st, you mus t all ocate memory for it, and then set up the individual properties.

FV_SaveFmtText;

Use the API convenience function, F_ApiAllocatePropVals(), to allocate m emory for the property list. For example, the following code creates a saveParamsp property list that instructs F_ApiSave() to save a file as text only:

. . . F_PropValsT params, *returnP aramsp = NULL; F_ObjHandleT mydocId;

/* Get the ID of the active document. */ mydocId = F_ApiGetId(0, FV_S essionId, FP_ActiveDo c);

/* Allocate memory for the l ist. */ params = F_ApiAllocatePropVals(1);

/* Set up the FS_FileType pr operty and set it to True. */ params.val[0].propIdent.num = FS_FileTy pe; params.val[0].propVal.valTyp e = FT_Integer; params.val[0].propVal.u.ival = FV_SaveFmtText;

F_ApiSave(mydocId, "/tmp/my. txt", ¶ms, &retur nParamsp); . . .

Checking Save status

F_ApiSave () stores a pointer to a property list in returnParamspp. This property list provides inf ormatio n on ho w t he FrameMak er pr oduct s a v ed t he f il e. It incl udes t he prope rtie s shown in the following table.

64 FDK Programmer’s Guide

Executing Commands with API Fu nctions

Property Meaning and Possible Values

FS_SavedFileName

FS_SaveNativeError

FS_SaveStatus

A string that specifies the saved file’s pathname. The error condition. If the file is saved successfully, it is set to

FE_Success

to, see ‘‘F_ApiSave()’’ on page 272 of th e FDK Programmer’s

Reference.

A bit field indicating what happened when the file was saved. For a complete list of the possible status flags, see ‘‘F_ApiSave()’’ on

page 272 of the FDK Programmer’s Reference.

. For a complete list of the other values it can be set

The FS_SaveNativeError property and the FA_errno value indicate the result of the call to F_ApiSave(). The FS_SaveStatus flags indicate how or why t his result occurre d.

To determine if a particular FS_SaveStatus bit is set, use F_ApiCheckStatus(). For example, the following code determines if a Save operation was canceled because the current FrameMaker document was already open:

. . . F_PropValsT params, *returnP aramsp = NULL; F_ObjHandleT mydocId;

/* Get the ID of the active document. */ mydocId = F_ApiGetId(0, FV_S essionId, FP_ActiveDo c);

params = F_ApiGetSaveDefaultParams();

F_ApiSave(mydocId, "/tmp/my. doc", ¶ms, &retur nParamsp);

if (F_ApiCheckStatus(returnP aramsp,

F_ApiAlert("Save cancelled - file is in use",FF_ALERT_ CONTINUE_NOTE);

/* Deallocate property lists . */ F_ApiDeallocatePropVals(&par ams); F_ApiDeallocatePropVals(retu rnParamsp); . . .

FV_FileWasInUse))

The API provides a utility function named F_ApiPrintSaveStatus(), which prints the save error values to the console on UNIX platforms, the FrameMaker console on Windows, and the error log window on the Macintosh. For more information, see

‘‘F_ApiPrintSaveStatus()’’ on page 253 of the FDK Programmer’s Reference.

Example

The following code opens /tmp/my.doc and saves it as a View Only document name d /tmp/viewonly.doc. It gets the name of the saved file fro m the returned property li st and

displays it.

FDK Programmer’ s Guide 65

Executing Commands with API Functions

. . . #include "futils.h"

IntT i; UCharT msg[1024]; F_PropValsT params, *returnP aramsp = NULL; F_ObjHandleT mydocId, viewon lydocId;

params = F_ApiAllocatePropVals(1);

mydocId = F_ApiSimpleOpen("/ tmp/my.doc", False); if(!mydocId) return;

/* Set file type to View Onl y. */ params.val[0].propIdent.num = FS_FileTy pe; params.val[0].propVal.valTyp e = FT_Integer; params.val[0].propVal.u.ival = FV_SaveFmtViewOnly ;

/* Save document as viewonly .doc. */ viewonlydocId = F_ApiSave(my docId, "/tmp/viewonly .doc",

¶ms, &returnParamsp);

/* Get index of property spe cifying filename and display it. */ i = F_ApiGetPropIndex(return Paramsp, FS_SavedFile Name); F_Sprintf(msg, "Saved: %s", returnParamsp->val[i].prop Val.u.sval); F_ApiAlert(msg, FF_ALERT_CON TINUE_NOTE);

/* Deallocate Save scripts. */ F_ApiDeallocatePropVals(&par ams); F_ApiDeallocatePropVals(retu rnParamsp); . . .

Closing documents and books

To close a do cument or book, use F_ApiClose(). The syntax for F_ApiClose() is:

IntT F_ApiClose(F_ObjHandleT Id,

IntT flags);

This argument Means

The ID of the document, book, or session to close. To close the session, specify

FV_SessionId.

flags

Specifies whether to abort or to close open documents or books if they have unsaved changes. Set the documents and books regardless of their state.

FF_CLOSE_MODIFIED flag to close open

66 FDK Programmer’s Guide

Examples

Executing Commands with API Fu nctions

F_ApiClos e() behaves somewhat differently than the Close command in the user interface. If there are unsaved changes in a file and you set FF_CLOSE_MODIFIED 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.

IMPORTANT: If you are closing an individual document, make sure Id specifies a valid

document ID and not 0. If Id is set to 0, F_ApiClose() quits the Frame session (because FV_SessionId is defined as 0).

The following code closes the active document. If the document has unsaved changes, the client prompts the user.

. . . F_ObjHandleT docId; IntT resp = 0;

/* Get the ID of active docu ment. Return if there isn’t one. */ docId = F_ApiGetId(0, FV_Ses sionId, FP_ActiveDoc) ; if(!docId) return;

/* See if document has been modified. */ if (F_ApiGetInt(FV_SessionId , docId, FP_DocIsModi fied)) resp = F_ApiAlert("Docume nt was changed, close it anyway?",

FF_ALERT_OK_DEFAULT);

if (!resp) F_ApiClose(docId, FF_CLOSE_MODIFIED); . . .

The following code closes the active document unless it has unsaved changes:

. . . F_ObjHandleT docId;

docId = F_ApiGetId(0, FV_Ses sionId, FP_ActiveDoc) ; if(!docId) return; if (F_ApiClose(docId, 0))

F_ApiAlert("Unsaved changes. Can’t close.",

FF_ALERT_CONTINUE_WARN);

. . .

Quitting a Frame session

To quit a Frame session, call F_ApiClose(), with Id set to FV_SessionId. For the syntax of F_ApiC lose(), see “Closing documents and books” on page 66.

For exampl e, to close all the ope n documents and books i n the current Frame session, and quit the session , use the following code:

FDK Programmer’ s Guide 67

Executing Commands with API Functions

. . . F_ApiClose(FV_SessionId, FF_ CLOSE_MODIFIED); . . .

Because of the flag set to FF_CLOSE_MODIFIED, if any books or documents have been changed, the FrameMaker product abandons the changes.

Comparing documents and books

To compare two versions of a document or book using the FrameMaker product’s built-in comparison feature, use F_ApiCompare().

The syntax for F_ApiCompare() is:

F_CompareRetT F_ApiCompare(F _ObjHandleT olderId,

F_ObjHandleT newerId, IntT flags, StringT insertCondTag, StringT deleteCondTag, StringT replaceText, IntT compareThreshold);

This argument Means

olderId

newerId

flags

insertCondTag

deleteCondTag

replaceText

compareThreshold

The ID of the older version of the document or book. The ID of the newer version of the document or book. Bit flags that specify how to generate the summary and composite

documents. The condition tag to apply to insertions shown in the composite

document. For no insert conditio n tag, specify The condition tag to apply to deletions shown in the composite

document. For no delete condition tag, specify Text to appear in place of the deleted text. For no replacement text,

specify If zero, the compare function uses the default value of 75 .

If not zero, the the function uses the setting in the FrameMaker configuratin files.

Threshold expresses the percentage of words that can change before paragraphs are considered not equal. If two paragraphs are equal, word differences between them are shown within a paragraph in the composite document.

NULL.

The F_CompareRetT structure is defined as:

68 FDK Programmer’s Guide

Executing Commands with API Fu nctions

typedef struct {

F_ObjHandleT sumId; /* ID of the summary document */ F_ObjHandleT compId; /* ID o f the composite docum ent */

} F_CompareRetT;

The following values can be ORed into the flags argument.

This value Means

Example

FF_CMP_SUMMARY_ONLY

FF_CMP_CHANGE_BARS

FF_CMP_HYPERLINKS

FF_CMP_SUMKIT

FF_CMP_COMPKIT

Generate summary document, but not composite document Turn on change bars in the composite document Put hypertext links in the summary document Open the summary document Open the composite document

If you specify the FF_CMP_SUMKIT or FF_CMP_COMPKIT flags, F_ApiCompare() opens the summary and comparison documents and returns their IDs in the F_CompareRetT structure. It does not mak e th ese documents visible to the use r. If you want them to be visible, you must set each of the document’s FP_DocIsOnScreen properties to True.

The following code opens two documents and compares them as specified in the dialog boxes shown in Figure 4.2. It makes the summary document visible.

. . . F_ObjHandleT oldId, newId; IntT flags; F_CompareRetT cmp;

oldId = F_ApiSimpleOpen("/tm p/1Chapter", False); newId = F_ApiSimpleOpen("/tm p/1Chapter.new", Fals e);

flags = FF_CMP_CHANGE_BARS | FF_CMP_COMPKIT | FF_ CMP_SUMKIT;

cmp = F_ApiCompare(oldId, ne wId, flags, "Comment" ,

"", "Replaced Text", 75);

if (FA_errno != FE_Success)

F_ApiAlert("Couldn’t compare ", FF_ALERT_CONTINUE_ NOTE);

. . .

FDK Programmer’ s Guide 69

Executing Commands with API Functions

FIGURE 4.2 Specifications for Compare Documents

Updating and generating documents and books

The API provides a variety of functions that allow you to generate, update, and reformat documents and books. The following sections discuss these functions.

Updating the files in a book

To update the numbering, text insets, cross-references, etc. in all the files in a book, and to programmatically specify responses to warnings and messages that the FrameMaker product issues, use F_ApiUpdateBook(). You can specify all aspects of the operation, or you can specify some aspects and allow the user to decide others. For example, you can instruct the FrameMaker product to update view-only files, or to abort the update when it encounters a view-only file.

To use F_ApiUpdateBook(), you should first understand property lists and how to manipulate them direc tly. For more information on this subject, see “Representing object

characteristics with properties” on page 270 and “Manipulating property lists directly” on page 93.

The syntax for F_ApiUpdateBook() is:

ErrorT F_ApiOpen(F_ObjHandleT bookId,

F_PropValsT *updateParamsp, F_PropValsT **updateReturnPa ramspp);

70 FDK Programmer’s Guide

This argument Means

Executing Commands with API Fu nctions

bookId

updateParamsp

updateReturnParamspp

IMPORTANT: Always initialize the pointer to the property list that you specify for

The ID of the book you will update. A property list (script) that tells the FrameMaker product how to

update the book and how to respond to errors and other conditions that arise. Use or F_ApiAllocatePropVals() to create and allocate memory for this property list. To use the default list, specify

NULL

A property list that provides information on ho w th e FrameMaker product updated the book.

F_ApiGetUpdateBookDefaultParams()

openReturnParamspp to NULL before you call F_ApiUpdateBook().

If F_ApiUpdateBook() is successful, it returns FE_Success. Otherwise, it returns an error which has the same value as FA_errno.

To call F_ApiUpdateBook(), do the following:

1. Initialize the pointer to the updateReturnParamspp property list to NULL.

2. Create an updateParamsp property list.

You can get a default list by calling F_ApiGetUpdateBookDefaultParams(), or you can create a list from sc ratch.

3. Call F_ApiUpda teBo ok().

4. Check the Up date status.

Check the returned values in th e updateReturnParamspp list for the name of the opened file and other information about how the FrameMaker product opened the file.

5. Deallocate memory for the updateParamsp and updateReturnParamspp property

lists.

Use F_ApiDeallocatePropVals() to deallocate memory fo r the lists.

Generating files for a book

To generate and update files for a book, use F_ApiSimpleGenerate(). The book and its generated files must be set up before you call F_ApiSimpleGenerate().

The syntax for F_ApiSimpleGenerate() is:

IntT F_ApiSimpleGenerate(F_O bjHandleT bookId,

IntT interactive, IntT makeVisible);

FDK Programmer’ s Guide 71

Executing Commands with API Functions

This argument Means

bookId

interactive

makeVisible

Importing formats

To import formats from a document to all the documents in a book or from one document to another document, use F_ApiSimpleImportFormats().

The syntax for F_ApiSimpleImportFormats() is:

IntT F_ApiSimpleImportFormat s(F_ObjHandleT bookId ,

F_ObjHandleT fromDocId, IntT formatFlags);

This argument Means

bookId

fromDocId

formatFlags

The ID of the book for which to generate files Specifies whether to display warnings and messages to the user (True

displays messages and warnings) Specifies whether to display generated fi les (True displays the files)

The ID of the book or document to which to import formats The ID of the document from which to import formats Bit field that specifies the formats to import

You can OR the values in the following table into the formatFlags parameter to specify which formats to import.

This value Means

FF_UFF_COLOR

FF_UFF_COMBINED_FONTS

FF_UFF_COND

FF_UFF_DOCUMENT_PROPS

FF_UFF_FONT

FF_UFF_MATH

FF_UFF_PAGE

FF_UFF_PGF

FF_UFF_REFPAGE

FF_UFF_TABLE

Import colors Import combined font definitions Import conditional text settings Import document properties Import Character Catalog formats Import equation settings Import page layouts Import Paragraph Catalog formats Import reference pages Import Table Catalog formats

72 FDK Programmer’s Guide

Executing Commands with API Fu nctions

This value Means

FF_UFF_VAR

FF_UFF_XREF

FF_UFF_REMOVE_EXCEPTIONS

FF_UFF_REMOVE_PAGE_BREAKS

Import variable formats Import cross-reference formats Remove exception formats from target documents Remove all forced page breaks from target documents

Executing other updating and formatting commands

The API provi des s everal functions that allow you to execute FrameMa k er pr oduct commands that update and reformat entire documents.

The syntax for the functions is:

IntT F_ApiClearAllChangebars (F_ObjHandleT docId); IntT F_ApiRehyphenate(F_ObjH andleT docId); IntT F_ApiResetReferenceFram es(F_ObjHandleT docId ); IntT F_ApiResetEqnSettings(F _ObjHandleT docId); IntT F_ApiRestartPgfNumberin g(F_ObjHandleT docId) ; IntT F_ApiUpdateVariables(F_ ObjHandleT docId); IntT F_ApiUpdateXRefs(F_ObjH andleT docId,

IntT updateXRefFlags);

This argument Means

docId

ID of the document to update or reformat

These functions behave like the corresponding commands in the user interface. They are useful for clients that need to update and reformat multiple files. For more information on a particular function, look it up in FDK Programmer’s Reference

Example

The following code opens a book and resets the change bars in each of its component documents:

. . . #include "fmemory.h"

F_ObjHandleT bookId, compId, docId; StringT compName;

bookId = F_ApiSimpleOpen("/t mp/my.book", False); compId = F_ApiGetId(FV_Sessi onId, bookId,

FP_FirstComponentInBook);

/* Traverse book’s component s, opening each one * and clearing its change ba rs. */

FDK Programmer’ s Guide 73

Executing Commands with API Functions

while(compId) {

compName = F_ApiGetString(bo okId, compId, FP_Name ); docId = F_ApiSimpleOpen(comp Name, False); F_Free(compName); F_ApiClearAllChangebars(docI d); compId = F_ApiGetId(bookId, compId, FP_NextCompon entInBook);

} . . .

Simulating user input

To simulate user input, call the API function F_ApiFcodes(). F_ApiFcod es() sends an array of function codes (f-codes) to the FrameMaker product.

F-codes are hexadecimal codes that specify individual user actions, such as cursor movement and text entry. They are especially useful for manipul ati ng windows. For example, the f-code

KBD_EXPOS EWIN brings the active document or book window to the front. When you use F_ApiFcod es() to send an array of f-codes to FrameMak er, it executes each f-code as if the

user performed the action.

IMPORTANT: F_ApiFcodes() does not work with dialog boxes on Windows.

The syntax for F_ApiFcodes() is:

IntT F_ApiFcodes(IntT len,

IntT *vec);

This argument Means

len

vec

The length of the array of f-codes in bytes The array of f-codes to send to the FrameMaker product

The following table lists some user actions and the f-codes that emulate them.

User action F-code

Move insertion point to first flow on the current page CSR_TOP Move insertion point to the start of the next word CSR_NEXT_BOW Move insertion point to the beginning of the next paragraph CSR_NEXT_BOP Center the current paragraph PGF_CENTER Left justify the current paragraph PGF_LEFT Make selected text bold TXT_BOLD

For a complete list of f-codes, see the fcodes.h file shipped with the FDK.

74 FDK Programmer’s Guide

Executing Commands with API Fu nctions

F_ApiFcod es() uses th e cu rrent focus in a dial og box or a visible documen t. I f you want to execute a set of f-codes in a particular dialog box or document, make sure that the dialog box or document is active. To make a dialog box active, use f-codes such as FOCUS_INPUT_SEARCH and FOCUS_INPUT_PGFFMT . To make a document active, set the session property FP_ActiveDoc to the document’s ID.

Many f-codes perf orm tasks t hat API fu nctions a lso perf orm. Whene ver possibl e, try to use the other API functions instead of F_ApiFcodes() to perform these tasks. F_ApiFcodes() does not provide error or status feedback for individual f-codes, whereas each API function stores an error code to FA_errno when it fails. It is also difficult to debug lengthy f-code sequences.

The following code uses f-cod es t o enter the string HI!, select the text, and then make it bold:

. . . static IntT fcodes[] = {CSR_TOP,'H','I','!',HIGH_ WORD_PREV,

TXT_BOLD}; F_ApiFcodes(sizeof(fcodes)/s izeof(IntT), fcodes); . . .

Straddling table cells

To straddle and unstraddle table cells, use F_ApiStraddleCells() and F_ApiUnStraddleCells().

The syntax for these functions is:

IntT F_ApiStraddleCells(F_Ob jHandleT docId,

F_ObjHandleT cellId, IntT heightInRows, IntT widthInCols);

IntT F_ApiUnStraddleCells(F_ ObjHandleT docId,

F_ObjHandleT cellId, IntT heightInRows, IntT widthInCols);

This argument Means

docId

cellId

heightInRows

widthInCols

The ID of the document containing the table The ID of the first (leftmost and uppermost) cell to straddle or unstraddle The number of cells to straddle or unstraddle vertically The number of cells to straddle or unstraddle horizontally

Both heightInRows and widthInCol s must be greater than 0. At least one of them must be greater than 1. The cells you straddle must all be from the same type of row. You can’t, for example, straddle a set of cells that are in both heading and body rows. You also can’t straddle cells that are already straddled. If the cells you specify include cells that are already straddled, F _ApiSt radd leCells () returns FE_BadOperation.

FDK Programmer’ s Guide 75

Executing Commands with API Functions

When you or the user straddle table cells, the FrameMaker product does not delete any of the FO_Cell objects that represent the cells. It links the para graphs from the straddle d cells into

a single list. The FP_FirstPgf and FP_LastPgf properties of each cell in the straddle specify the first and last paragraphs in this list.

Example

The following code straddles the first two cells in the first column of a table:

. . . F_ObjHandleT docId, tableId, firstrowId, cellId;

/* Get IDs of document, tabl e, first row, and fir st cell. */ docId = F_ApiGetId(0, FV_Ses sionId, FP_ActiveDoc) ; tableId = F_ApiGetId(FV_Sess ionId, docId, FP_Firs tTblInDoc); firstrowId = F_ApiGetId(docI d, tableId, FP_FirstR owInTbl); cellId = F_ApiGetId(docId, f irstrowId, FP_FirstCe llInRow);

/* If there are two cells in the row, straddle th em. */ if (F_ApiGetInt(docId, table Id, FP_TblNumCols) < 2)

F_ApiAlert("Not enough colum ns!", FF_ALERT_CONTIN UE_NOTE); else F_ApiStraddleCells(docI d, cellId, 1, 2); . . .

Executing Structured FrameMaker commands

The following sections describe how to programmatically execute FrameMaker commands.

Manipulating elements

The API provides several functions that allow you to execute basic FrameMaker commands that manipulate elements.

The syntax for these functions is:

VoidT F_ApiDemoteElement(F_O bjHandleT docId); VoidT F_ApiMergeIntoFirst(F_ ObjHandleT docId); VoidT F_ApiMergeIntoLast(F_O bjHandleT docId); VoidT F_ApiPromoteElement(F_ ObjHandleT docId); VoidT F_ApiSplitElement(F_Ob jHandleT docId); VoidT F_ApiUnWrapElement(F_O bjHandleT docId); VoidT F_ApiWrapElement(F_Obj HandleT docId,

F_ObjHandleT edefId);

76 FDK Programmer’s Guide

This argument Means

Executing Commands with API Fu nctions

docId

edefId

ID of the document containing selected text and/or structure elements ID of element definition for the new element

These functions behave like the corresponding commands in the user interface. They all use the current text or element selection in th e specified document to determine which text and elements to manipulate. You can allow the user to set the text or element selecti on, or you can do it programmatically. For information on setting the text selection programmatically, see

“Getting and setting the insertion point or text selection” on page 114. For more information

on setting the element selection programmatically, see “Getting and setting the structural

element selection” on page 120

Importing element definitions into FrameMaker documents and books

To import element definitions from a FrameMaker document or book to a FrameMaker document or book, use F_ApiSimpleImportElementDefs().

The syntax for F_ApiSimpleImportElementDefs() is:

IntT F_ApiSimpleImportElemen tDefs(

F_ObjHandleT docOrBookId,

F_ObjHandleT fromDocOrBookId,

IntT importFlags);

This argument Means

docOrBookId

fromDocOrBookId

importFlags

The ID of the document or book to import element definitions to. The ID of the document or book from which to import element

definitions. See the following table for the flags that you can OR into this parameter.

The following ta ble lists flags that you can OR into the importFlags parameter:

Flag Meaning

FF_IED_REMOVE_OVERRIDES

FF_IED_REMOVE_BOOK_INFO

FF_IED_DO_NOT_IMPORT_EDD

Clear format overrides. If docOrBookId specifies a document, clear

formatting inherited from the parent book. If the document specified by fromDocOrBookId is

an EDD, don’t treat it as an EDD; just import its element catalog.

FDK Programmer’ s Guide 77

Executing Commands with API Functions

Flag Meaning

FF_IED_NO_NOTIFY

Do not issue the FA_Note_PreImportElemDefs

or FA_Note_PostImportElemDefs

If you import element definitions to a book, F_ApiSimpleImportElementDefs() imports element definitions to each book component for which the set to

True.

Calling FrameMaker clients programmatically

Much of the structured document functionality FrameMaker provides is implemented in FDK clients. To call this functionality programmatically, you must use F_ApiCallClient().

F_ApiCallClient() requires you to specify a client’s registered name and a string, which it passes to the client. The follow ing table lists FrameMaker functionality and the registered names of the clients you can call to invoke it programmatically.

Functionality Registered client name

Element catalog manager Structure generator Reading and writing SGML documents and

reading, writing, and updating DTD and EDD documents

Element Catalog Manager

Structure Generator

FmDispatcher

notifications.

FP_ImportFmtInclude property is

The following ta ble lists the st rings you pass to the structure generator client to programmatically generate structure in a document or book.

String Meaning

INPUTDOCID objectID RULEDOCID objectID

OUTPUTDOCNAME filename

LOGNAME filename

GenerateDoc

The ID of the input document or book. The ID of the rule table document. The full pathname of the output document or book. This string

is optional. If you do not specify a pathname, the structure generator leaves the document unsaved and open.

The full pathname of a log file. This string is optional. If you do not specify a pathname, the structure generator leaves the log file unsaved and open.

Instructs the structure generator t o generate structure, using t he strings listed above.

To programmatically generate structure for a document or a book, you call F_ApiCallClient() multiple times, each time passing it one of the strings listed in the table above. For example, the following code generates structure for a document:

78 FDK Programmer’s Guide

Executing Commands with API Fu nctions

. . . F_ObjHandleT inputDocId, rul eTblDocId; UCharT buf[64]; . . . F_Sprintf(buf, "INPUTDOCID % d", inputDocId); F_ApiCallClient("StructGen", buf);

F_Sprintf(buf, "RULEDOCID %d ", ruleTblDocId); F_ApiCallClient("StructGen", buf);

F_ApiCallClient("StructGen", "OUTPUTDOCNAME /tmp/ mystruct.doc"); F_ApiCallClient("StructGen", "LOGNAME /tmp/logfil e.doc"); F_ApiCallClient("StructGen", "GenerateDoc"); . . .

Note that all of the documents you specify must be open before you call the structure generator. If you are generating structure for a large number of documents, you can greatly speed processing by opening the documents invisibly. To open a document invisibly, set the FS_MakeVi sible property of the Op en script to False.

For a complete l ist of the st rings you c an pass to t he struc ture gener ator and ot her FrameMak er clients, see ‘‘Calling Clients Shipped With FrameMaker’’ on page 699 of the FDK

Programmer’s Reference.

FDK Programmer’ s Guide 79

Executing Commands with API Functions

80 FDK Programmer’s Guide

Getting and Setting Properties

This chapter describes how to make changes in a FrameMaker product session, book, or document by getting and setting property values. It discusses how to get and set individual properties and entire property lists. It also provides some tips for getting and setting the properties of specific types of objects.

What you can do with object properties

In the FrameMaker product user interface, the user can change an object in a variety of ways. For example, the user can change the size and fill pattern of a graphic object or the starting page number of a book component.

Each API object has a property list, a set of properties descr ibing it s attrib utes . Your API client can do anything a user can do to an object by getting and setting the properties in the object’s property list. For example, your client can set properties to:

● Change a graphic object’s size, fill pattern, or position in the back-to-front order

● Make a document or book active

● Change a book component’s position in a book

● Change a paragraph’s format

Your client can also change properties that the user doesn’t have access to. For example, your client can set properties to:

● Make a document or book visible or invisible

● Keep the FrameMaker product from reformatting a document every time a change is made

The API ensures that your client doesn’t corrupt a document by setting properties to illegal values. When you change a property, the API also automatically changes other properties as needed to preserve the integrity of the document or book.

There are a number of read-only properties that you can get but not set. For a complete list of object properties and their possible values, see Chapter 3, “Object Reference,” in the FDK

Programmer’s Reference.

To change a session, document, or book by setting object properties, follow these general steps:

1. Find out which objects represent the things you want to change.

To change something in a session, book, or docu me nt, you need to know whi ch o bje cts the API uses to represen t it. F or a descri ption of h o w the API uses objects t o represe nt things i n FrameMaker, see Part II, Frame Product Architecture.

FDK Programmer’ s Guide 81

Getting and Setting Properties

2. Get the IDs of the objects you want to change.

To set an object’s properties, you must specify its ID. The API provides functions for retrieving object IDs.

3. Manipulate the objects’ properties. The API provides functions for getting and setting individual properties and entire property

lists. For example, the API represents a FrameMaker product session with an FO_Session object.

You don’t need to get a session’s ID, because there is only one session and its ID is always FV_Sessio nId. To find all the session characteristics you can change, look up “Session” on

page 631 in C hapter 3, “Object Reference,” in the FDK Programmer’s Reference.

You can, for example, change the session’s automatic save time. The API represents the automatic save time with an integer (IntT) property named FP_AutoSaveSeconds. To set it to 60 seconds, use the following code:

F_ApiSetInt(0, /* Sessions h ave no parent */

FV_SessionId, /* The session’s ID */

FP_AutoSaveSeconds, /* The property to set */

60); /* The value to set it to */

The following sections describe steps 2 and 3 in greater detail.

Getting the IDs of th e objects yo u want to change

Every object in a sessi on has an ID. To get or set the p roper ties of a parti cular objec t, you must specify its ID. In Frame book and document architecture, obj ects are organize d in li nked lists: an object has properties that specify the IDs of other objects, which have properties that specify the IDs of other objects, and so on. To get the IDs of specific objects, you traverse the linked lists by querying these properties. For diagrams and descriptions of the linked lists in Frame architecture, see Part II, “Frame Product Architecture.”

To query a property that specifies an object ID, use F_ApiGetId(), which is defined as:

F_ObjHandleT F_ApiGetId(F_Ob jHandleT docId,

F_ObjHandleT objId, IntT propNum);

This argument Means

docId

objId

The ID of th e document, book, or session containing the object whose property yo u want to query.

The ID of the object whose property you want to query.

propNum

The property to query. Specify one of the API-defined constants, such as

FP_ActiveDoc

82 FDK Programmer’s Guide

Getting and Setting Properties

F_ApiGetI d() returns the ID specified by the property. If the property doesn’t specify an ID or an error occurs, F_ApiGetId() returns 0.

To get an object’s ID, you start traversing at the object that represents the session (the FO_Sessio n object), because it is the only object whose ID (FV_SessionId) you know from the start.

From the FO_Session object, you can get the IDs of the active and open documents and books in the session. FO_Sessio n objects have properties, named FP_ActiveDoc and FP_Active Book, that s pec if y the IDs of the acti ve document or book. A document or a book is active if it has input focus.

FO_Sessio n objects also have properties, named FP_FirstOpenDoc and FP_FirstO penBoo k, that specify the first document and the first book in the linked lists of open documents and books in a session. FO_Doc objects have a property named FP_NextOpenDocInSession that specif ie s t h e I D of the next FO_Doc object in the list of

open documents. FO_Book objects hav e a property na med FP_NextOpenBookInSession that specifies the ID of the next FO_Book object in the list of open books. If an FO_Doc or an FO_Book obje ct is the last object in the l ist, its FP_NextOpenDocInSession or FP_NextOpenBookInSession prope rty is set to 0. For a diagram of how the API represents the documents and books in a session, see Figure 13.2 on page 276.

Suppose you want to display the IDs of the active document and all the open documents in a session. You can use the following code to do this:

. . . #include "futils.h" F_ObjHandleT docId; UCharT msg[256];

/* Get the ID of the active document and display it. */ docId = F_ApiGetId(0, FV_Ses sionId, FP_ActiveDoc) ; if (docId)

{

F_Sprintf(msg, "The active d ocument’s ID is 0x%x. ", docId);

F_ApiAlert(msg, FF_ALERT_CON TINUE_NOTE);

}

/* Get ID of the first docum ent in list of open d ocuments. */ docId = F_ApiGetId(0, FV_Ses sionId, FP_FirstOpenD oc);

/* Traverse list of open doc uments and display th eir IDs. */ while (docId)

{

F_Sprintf(msg, "The document ’s ID is 0x%x.", docI d);

F_ApiAlert(msg, FF_ALERT_CON TINUE_NOTE);

docId = F_ApiGetId(FV_Sessio nId, docId,

FP_NextOpenDocInSession);

} . . .

FDK Programmer’ s Guide 83

Getting and Setting Properties

This code displays the ID of the active document twice, because the active document is included in the list of open documents.

The linked list of open document s in a sessi on isn’t in any particular order . The f irs t docume nt in the list is not necessarily the active document or the first document that was opened.

Another way to get a document ID is to use F_ApiSimpleOpen(), F_ApiOpen(), or F_ApiSimpleNewDoc() to open or create the document. These functions all return the IDs of the document they open or create.

Traversing lists of objects in a document

Once you have the ID of a document, you can query its properties to get to the lists of objects that it contains . The documen t has a number of proper ties t hat point to the se list s. For exa mple, the document’s FP_FirstGraphicInDoc property specifies the ID of the first graphic object in the list of its graphic objects and its FP_FirstBodyPageInDoc property specifies the first body page in the list of its body pages. Except for the lists of pages, the lists are completely unord er ed. For example, the first gr aph ic o bject in the list of graphic objects is not necessarily the first graphic that appears in the document.

Suppose you want to traverse the list of all the paragraphs in the active document. To do this, you can use the following code:

. . . #include "futils.h" F_ObjHandleT docId, pgfId; UCharT msg[256];

/* Get the ID of the active document. */ docId = F_ApiGetId(0, FV_Ses sionId, FP_ActiveDoc) ;

/* Get ID of the first parag raph in the list of p aragraphs. */ pgfId = F_ApiGetId(FV_Sessio nId, docId, FP_FirstP gfInDoc);

/* Traverse the list of para graphs and display th eir IDs. ** Even empty documents have several paragraphs, because text ** columns on master pages c ontain paragraphs. */ while (

. . .

pgfId)

{

F_Sprintf(msg, "The paragrap h’s ID is 0x%x.",

F_ApiAlert(msg, FF_ALERT_CON TINUE_NOTE);

pgfId = F_ApiGetId(docId, pg fId, FP_NextPgfInDoc) ;

}

pgfId);

The paragraphs in the list are not ordered.

Traversing lists of graphic objects

The API does not maintain separate lists of the different types of graphic objects in a document. For example, a document’s text columns (FO_TextFrame objects), rectangles

84 FDK Programmer’s Guide

Getting and Setting Properties

(FO_Rectangle objects), and anchored frames (FO_AFrame objects ) are all in the same list. To determine objects’ types as you traverse them, use F_ApiGetObjectType().

The syntax for F_ApiGetObjectType() is:

UIntT F_ApiGetObjectType(F_ObjHandleT docId,

F_ObjHandleT objId);

This argument Means

docId

objId

The ID of the document, book, or session containing the object The ID of the object whose type you want to get

For example, the following code counts the number of anchored frames in the active document:

. . . #include "futils.h" IntT numFrames = 0; F_ObjHandleT docId, objId; UCharT msg[256];

docId = F_ApiGetId(0, FV_Ses sionId, FP_ActiveDoc) ;

/* Get ID of first graphic i n the list of graphic s. */ objId = F_ApiGetId(FV_Sessio nId, docId, FP_FirstG raphicInDoc);

/* Traverse list of graphics , counting anchored f rames. */ while (objId)

{

if (

F_ApiGetObjectType(docId,objId) == FO_AFrame) numFrame s++;

objId = F_ApiGetId(docId, ob jId, FP_NextGraphicIn Doc);

}

F_Sprintf(msg, "The document has %d anchored fram es.",

numFrames); F_ApiAlert(msg, FF_ALERT_CON TINUE_NOTE); . . .

Traversing ordered lists of objects

Tra versing the list of all the objects of a certain type in a document is useful if you want to get every object of that type and the order doesn’t matter to you. However, it isn’t very useful if you want the objects in some kind of order, such as the order in which they appear on a document’s pages. To get objects in order, you must traverse the ordered lists that the API maintains. There are ordered lists of the graphic objects in a frame, the text columns within a flow, and many other objects. These lists can be deeply nested, for example, when a frame contains a frame that contains some graphic objects.

There are a variety of object properties you can query to get to ordered lists. For example, to get to the list of graphic objects in a frame, you can query the frame’s FP_FirstGraphicInFrame or FP_LastGraphicInFrame properties. If you already

FDK Programmer’ s Guide 85

Getting and Setting Properties

have one of the graphic object’s IDs, you can query its FP_PrevGraphicInFrame and FP_NextGraphicInFrame properties to get to the objects behind it and in front of it in the

list. The order of the list corresponds to the back-to-front order of the graphics in the frame. For information on the linked lists that a particular object is included in, see the section that discusses that object in Chapter 14, “Frame Document Architecture”

Although there are ordered lists of the paragraphs within each of a document’s flows, there is no ordered list of flows. You can get the paragraphs only in the order in which they occur within an individual flow.

T o get the paragr aphs withi n an indi vidua l flo w in or der , y ou nav igate f rom the flo w to th e fi rst text frame in the flow, to the first paragraph in that text frame. For example, to get the paragraphs in a document’s main flow in order, you can use the following code:

. . . #include "futils.h" F_ObjHandleT docId, pgfId, f lowId, textFrameId; UCharT msg[256];

docId = F_ApiGetId(0, FV_Ses sionId, FP_ActiveDoc) ;

/* Get ID of main flow, then the first text colum n in the * flow, then the first para graph in that text co lumn. */ flowId = F_ApiGetId(FV_Sessi onId, docId, FP_MainF lowInDoc); textFrameId = F_ApiGetId(doc Id, flowId,

FP_FirstTextFrameInFlow);

pgfId = F_ApiGetId(docId, te xtFrameId, FP_FirstPg f);

/* Traverse ordered list of paragraphs in the flo w. */ while (pgfId)

{

F_Sprintf(msg, "The paragrap h’s ID is 0x%x.", pgf Id); F_ApiAlert(msg, FF_ALERT_CON TINUE_NOTE); pgfId = F_ApiGetId(docId, pg fId, FP_NextPgfInFlow );

}

. . .

For a diagram of the links between flows, text frames, and paragraphs, see “The list of

paragraphs in a flow” on page 304.

Getting the IDs of selected object s

Document objects have properties that allow you to get the IDs of the following types of selected objects:

● Graphic objects

● Tables and table rows

To get the IDs of selected structural elements in FrameMaker documents, you must call a special function, F_ApiGetElementRange().

86 FDK Programmer’s Guide

Macromedia FrameMaker - 7.0 User Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Using Frame Developer Tools

The Frame Developer’s Kit

Frame API

Structure Import/Export API

Other FrameMaker features for developers

fmbatch

Choosing the right Frame tools

FDK documentation

FDK Platform Guide

FDK Programmer’s Guide

FDK Programmer’s Reference

Structure Import/Export API Programmer’s Guide

Naming conventions

Style conventions

Structured program interface

Pathnames

Typographic conventions

Introduction to the Frame API

How the API works

How clients can change FrameMaker documents, books, and sessions

How clients communica te with the user

How clients work with FrameMaker

Special types of clients

Document reports

Filters

Take-control clients

Portability

Running clients with different FrameMaker product interfaces

Creating and running a client

A simple example

Compiling and running the example client

API Client Initialization

Responding to the FrameMaker product’s initialization call

Initialization types

First initializa tion

Take-control initialization

Document report initialization

Filter initialization

Initialization after a client has bailed out

Disabling the API

Using API dialog boxes to prompt the user for input

Using alert boxes

Using string, integer, and metric input dialog boxes

Using file selection dialog boxes

Using scroll list dialog boxes

Using commands, menu items, and menus in your client

Getting the IDs of FrameMaker product menus and menu bars

Defining commands and adding them to menus

Defining and adding menus

Responding to the user choosing a command

Replacing FrameMaker product menus and commands

Allowing users to configure your client’s interface

Using hypertext commands in your client’s user int erface

Setting up hypertext commands

Responding to message apiclient commands

Example

Requesting notification for events

Adding the F_ApiNotify() callback

Implementing quick keys

Freeing system resources by bailing out

Handling errors

Handling messages and warnings

Using simple functions

Using scriptable functions

Opening documents and books

Opening a document or book with F_ApiSimpleOpen()

Opening a document or book with F_ApiOpen()

Creating documents

Creating a document with F_ApiSimpleNewDoc()

Creating a custom document

Creating a document with F_Api Open()

Printing documents and books

Changing the print settings for a document

Examples

Saving documents and books