Macromedia FrameMaker - 2017 Programmer’s Guide

FDK PROGRAMMER’S GUIDE

ADOBE® FRAMEMAKER® (2017 release)

Developing Structured Applications with FrameMaker FrameMaker Online Manual

If this guide is distributed with software that includes an end-user agreement, this guide, 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. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end-user license agreement.

The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide.

Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner.

Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization.

Adobe, the Adobe logo, Acrobat, Distiller, Flash, FrameMaker, Illustrator, PageMaker, Photoshop, PostScript, Reader, Garamond, Kozuka Mincho, Kozuka Gothic, MinionPro, and MyriadPro are trademarks of Adobe Systems Incorporated.

Microsoft, Windows, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Solaris is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. UNIX is a trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. SVG is a trademark of the World Wide Web Consortium; marks of the W3C are registered and held by its host institutions MIT, INRIA, and Keio. All other trademarks are the property of their respective owners.

This product contains either BISAFE and/or TIPEM software by RSA Data Security, Inc.

This product contains color data and/or the Licensed Trademark of The Focoltone Colour System.

PANTONE® Colors displayed in the software application or in the user documentation may not match PANTONEidentified standards. Consult current PANTONE Color Publications for accurate color. PANTONE® and other Pantone, Inc. trademarks are property of Pantone, Inc. © Pantone, Inc. 2003. Pantone, Inc. is the copyright owner of color data and/or software which are licensed to Adobe Systems Incorporated to distribute for use only in combination with Adobe Illustrator. PANTONE Color Data and/or Software shall not be copied onto another disk or into memory unless as part of the execution of Adobe Illustrator software.

Software is produced under Dainippon Ink and Chemicals Inc.'s copyrights of color-data-base derived from Sample Books.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Certain Spelling portions of this product is based on Proximity Linguistic Technology. ©Copyright 1990 MerriamWebster Inc. ©Copyright 1990 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 2003 Franklin Electronic Publishers Inc.©Copyright 2003 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. Legal Supplement ©Copyright 1990/1994 Merriam-Webster Inc./Franklin Electronic Publishers Inc. ©Copyright 1994 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990/ 1994 Merriam- Webster Inc./Franklin Electronic Publishers Inc. ©Copyright 1997All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA ©Copyright 1990 MerriamWebster Inc. ©Copyright 1993 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 2004 Franklin Electronic Publishers Inc. ©Copyright 2004 All rights reserved.

Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1991 Dr. Lluis de Yzaguirre I Maura ©Copyright 1991 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990 Munksgaard International Publishers Ltd. ©Copyright 1990 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990 Van Dale Lexicografie bv ©Copyright 1990 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1995 Van Dale Lexicografie bv ©Copyright 1996 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990 IDE a.s. ©Copyright 1990 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1992 Hachette/Franklin Electronic Publishers Inc. ©Copyright 2004 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1991 Text & Satz Datentechnik ©Copyright 1991 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 2004 Bertelsmann Lexikon Verlag ©Copyright 2004 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 2004 MorphoLogic Inc. ©Copyright 2004 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990 William Collins Sons & Co. Ltd. ©Copyright 1990 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1993-95 Russicon Company Ltd. ©Copyright 1995 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 2004 IDE a.s. ©Copyright 2004 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. The Hyphenation portion of this product is based on Proximity Linguistic Technology. ©Copyright 2003 Franklin Electronic Publishers Inc.©Copyright 2003 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1984 William Collins Sons & Co. Ltd. ©Copyright 1988 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990 Munksgaard International Publishers Ltd. ©Copyright 1990 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1997 Van Dale Lexicografie bv ©Copyright 1997 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1984 Editions Fernand Nathan ©Copyright 1989 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1983 S Fischer Verlag ©Copyright 1997 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1989 Zanichelli ©Copyright 1989 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1989 IDE a.s. ©Copyright 1989 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1990 Espasa-Calpe ©Copyright 1990 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA. ©Copyright 1989 C.A. Stromberg AB. ©Copyright 1989 All rights reserved. Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA.

Portions of Adobe Acrobat include technology used under license from Autonomy, and are copyrighted.

Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.

Notice to U.S. government end users. The software and documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60- 741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.

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

PART I: Getting Started

Using Frame Developer Tools .........................................13

The Frame Developer’s Kit .......................................................................................... 13

Choosing the right Frame tools ..................................................................................... 15

FDK documentation ...................................................................................................... 16

Naming conventions ..................................................................................................... 16

Style conventions .......................................................................................................... 17

Getting Started with FDK ..............................................19

Downloading and installing the FDK ........................................................................... 20

System requirements ..................................................................................................... 20

Reviewing the sample programs in the samples/hello folder ....................................... 21

Getting familiar with how the FDK works on Windows .............................................. 22

Writing FDK clients for Windows ................................................................................ 23

Compiling, Registering, and Running FDK Clients ..................................................... 30

Writing an Asynchronous FDK Client .......................................................................... 41

Example: adding menus and commands ....................................................................... 57

Next Steps ..................................................................................................................... 59

. . . . .

PART II: Frame Product Architecture

1 Frame Session Architecture ........................................ ............................................... 63

Identifying objects ........................................................................................................ 63

Representing object characteristics with properties ...................................................... 65

FrameMaker product sessions ...................................................................................... 69

2 Frame Document Architecture .................................................................................. 75

Documents .................................................................................................................... 75

Global document information ....................................................................................... 81

Pages ............................................................................................................................. 87

Graphic objects ............................................................................................................. 92

Flows ............................................................................................................................. 97

Paragraph Catalog formats .......................................................................................... 102

Paragraphs ................................................................................................................... 103

Character Catalog formats .......................................................................................... 108

Condition Formats ...................................................................................................... 112

FDK Programmer’s Guide 5

Contents

Text ............................................................................................................................. 114

Markers ....................................................................................................................... 124

Cross-reference formats .............................................................................................. 127

Cross-references .......................................................................................................... 129

Variable formats .......................................................................................................... 131

Variables ...................................................................................................................... 133

Footnotes ..................................................................................................................... 134

Ruling Formats ........................................................................................................... 136

Table Catalog formats ................................................................................................. 138

Tables .......................................................................................................................... 140

Colors .......................................................................................................................... 149

Structural element definitions ..................................................................................... 152

Format rules and format rule clauses .......................................................................... 155

Format change lists ..................................................................................................... 157

Structural elements ..................................................................................................... 159

3 Frame Book Architecture ......................................................................................... 161

What the user sees ....................................................................................................... 161

How the API represents books .................................................................................... 162

Creating new books and components ......................................................................... 166

Updating a book .......................................................................................................... 167

Using the book error log ............................................................................................. 172

PART III: Frame Application Program Interface

1 Introduction to the Frame API ................................................................................ 177

How the API works ..................................................................................................... 177

Special types of clients ............................................................................................... 179

Running clients with different FrameMaker product interfaces ................................. 181

Creating and running a client ...................................................................................... 181

A simple example ........................................................................................................ 183

Using old clients with FDK 12 ................................................................................... 187

2 API Client Initialization ........................................................................................... 189

Responding to the FrameMaker product’s initialization call ...................................... 189

Initialization types ....................................................................................................... 190

Disabling the API ........................................................................................................ 192

FrameMaker Product Activation by Asynchronous Clients ....................................... 192

3 Creating Your Client’s

User Interface 195

Using API dialog boxes to prompt the user for input ................................................. 195

Using commands, menu items, and menus in your client .......................................... 205

Replacing FrameMaker product menus and commands ............................................. 213

Allowing users to configure your client’s interface .................................................... 213

6 FDK Programmer’s Guide

Contents

Using hypertext commands in your client’s user interface ......................................... 215

Responding to user-initiated events or FrameMaker product operations ................... 219

Implementing quick keys ............................................................................................ 230

Freeing system resources by bailing out ..................................................................... 232

4 Executing Commands with API Functions .............. ............................................... 235

Handling errors ........................................................................................................... 235

Handling messages and warnings ............................................................................... 235

Opening documents and books ................................................................................... 237

Creating documents .................................................................................................... 246

Printing documents and books .................................................................................... 251

Saving documents and books ...................................................................................... 253

Closing documents and books .................................................................................... 260

Quitting a Frame session ............................................................................................. 262

Comparing documents and books ............................................................................... 262

Updating and generating documents and books ......................................................... 265

Simulating user input .................................................................................................. 272

Straddling table cells ................................................................................................... 273

Executing FrameMaker commands ............................................................................ 274

5 Getting and Setting Properties ................................. ............................................... 279

What you can do with object properties ..................................................................... 279

Getting the IDs of the objects you want to change ..................................................... 280

Manipulating properties .............................................................................................. 290

Getting and setting session properties ........................................................................ 297

Getting and setting document properties .................................................................... 300

Getting and setting graphic object properties ............................................................. 303

Getting and setting paragraph properties .................................................................... 306

Getting and setting book properties ............................................................................ 310

Getting and setting FrameMaker properties ............................................................... 311

. . .

6 Manipulating T ext .....................................................................................................319

Getting text ................................................................................................................. 319

Getting and setting the insertion point or text selection ............................................. 323

Adding and deleting text ............................................................................................. 333

Getting and setting text formatting ............................................................................. 336

Executing Clipboard functions ................................................................................... 343

7 Manipulating Asian Text .......................................................................................... 347

Creating a rubi group .................................................................................................. 347

Text encodings ............................................................................................................ 348

Using encoding data .................................................................................................... 350

Inspecting and manipulating encoded text .................................................................. 355

Parsing an encoded string ........................................................................................... 357

Getting the encoding for a text item ........................................................................... 359

Special issues with double byte encodings ................................................................. 359

FDK Programmer’s Guide 7

Contents

8 Creating and Deleting API Objects ......................................................................... 361

Creating objects .......................................................................................................... 361

Deleting objects .......................................................................................................... 381

Implicit property changes ........................................................................................... 383

9 Manipulating Commands and Menus with the API ..............................................385

How the API represents commands and menus .......................................................... 385

Getting the IDs of commands and menus ................................................................... 389

Determining a session’s menu configuration .............................................................. 391

Arranging menus and menu items .............................................................................. 392

Getting and setting menu item labels .......................................................................... 399

Manipulating expandomatic menu items .................................................................... 401

Using check marks ...................................................................................................... 402

Using context-sensitive commands and menu items .................................................. 402

10 Creating Custom Dialog Boxes for Your Client .....................................................407

Overview ..................................................................................................................... 407

How to create a dialog box ......................................................................................... 412

Creating a DRE file ..................................................................................................... 412

Designing the layout of the dialog box ....................................................................... 415

Setting the properties of the dialog box ...................................................................... 419

Setting the properties of a dialog item ........................................................................ 423

Saving a DRE file ....................................................................................................... 431

Modeless Dialog Boxes .............................................................................................. 432

Testing a dialog box .................................................................................................... 433

A simple example ........................................................................................................ 435

General tips for dialog editing .................................................................................... 439

Summary of keyboard shortcuts ................................................................................. 439

8 FDK Programmer’s Guide

11 Handling Custom Dialog Box Events ........ .......................................................... ....441

How the API represents dialog boxes ......................................................................... 441

Overview of using a custom dialog box in your client ............................................... 444

Opening dialog resources ............................................................................................ 448

Initializing items in a dialog box ................................................................................ 449

Displaying a dialog box .............................................................................................. 450

Updating items in a dialog box ................................................................................... 451

Handling user actions in dialog boxes ........................................................................ 452

Closing a dialog box ................................................................................................... 461

12 Using Imported Files and Insets .............................................................................. 463

Types of imported files and insets .............................................................................. 463

Importing text and graphics ........................................................................................ 464

Updating text insets .................................................................................................... 471

Client text insets .......................................................................................................... 471

Writing filter clients .................................................................................................... 476

Specifying format IDs and filetype hint strings .......................................................... 480

Associating a file format with signature bytes ............................................................ 492

13 Working with Unicode ..............................................................................................505

Introduction to Unicode Support ................................................................................ 505

Unicode Mode ............................................................................................................. 505

Compatibility mode .................................................................................................... 515

International Components for Unicode (ICU) ............................................................ 523

Mixed Mode operations .............................................................................................. 524

Handling for special characters ................................................................................... 524

PART IV: Frame Development Environment (FDE)

14 Introduction to FDE .................................................................................................531

How the FDE works ................................................................................................... 531

How to make your client portable ............................................................................... 533

A simple FDE filter ..................................................................................................... 538

15 Making I/O and Memory Calls Portable ........ ............................. ........................... 543

Initializing the FDE .................................................................................................... 543

Using platform-independent representations of pathnames ........................................ 543

Making I/O portable with channels ............................................................................ 547

Assertion-handler functions ........................................................................................ 547

Making memory allocation portable ........................................................................... 548

Error and progress reporting ....................................................................................... 549

Contents

. . .

16 FDE Utility Libraries ................................................................................................551

String library ............................................................................................................... 551

The string list library ................................................................................................... 552

Character library ......................................................................................................... 552

The I/O library ............................................................................................................ 553

The hash library .......................................................................................................... 553

Metric library .............................................................................................................. 555

MIF data structures and macros .................................................................................. 555

The MIF library .......................................................................................................... 557

Simple MIF library ..................................................................................................... 558

Glossary .................................................................... 559

FDK Programmer’s Guide 9

Contents

10 FDK Programmer’s Guide

PART I

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

Getting Started

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

The Frame Developer’s Kit

The Frame Developer’s Kit™ (FDK) provides tools for developers to enhance the functionality of FrameMaker.

This chapter provides an overview of the FDK and other aspects of FrameMaker that are useful for developers. It also discusses the FDK documentation.

The principal parts of the FDK are:

 Frame Application Program Interface™ (API)

 Frame Development Environment™ (FDE)

 Frame Structure Import/Export Application Program Interface (Structure

Import/Export API)

The following sections describe these parts and discuss how you can use them.

1Using Frame Developer Tools

. . . . .

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 nearly anything an interactive user can do and more. The API gives a client direct access to the text and graphic objects in documents. The API includes a set of header files, libraries, and makefiles for each supported platform. Here are some examples of the types of clients you can create with the API:

 Grammar checkers

 Bibliography utilities

FDK Programmer’s Guide 13

Using Frame Developer Tools

The Frame Developer’s Kit

 Voice control utilities

 Document reporting utilities

 Version control systems for documents

 Table utilities, such as sorting and totaling

 Database publishing packages

 Interfaces to document management systems

 Filters to exchange files between other desktop publishing applications and

FrameMaker products

FDE

The Frame Development Environment (FDE) 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.

Structure Import/Export API

The Structure Import/Export API allows you to write clients that control the import of markup documents into FrameMaker, and control the export of FrameMaker documents to markup.

Other FrameMaker product features for developers

FrameMaker provides other advanced features that are useful for developers. You do not need the FDK to use these features.

MIF

Maker Interchange Format (MIF) is an easily parsed ASCII format that describes a document’s text, graphics, formatting, and layout. FrameMaker can save a document or a book to a MIF file, and convert a MIF file back to a document or book, without losing any information.

You can write applications or scripts that convert a MIF file to the format of another desktop publishing package, or convert other formats to MIF.

Here are some examples of things you can use MIF for:

 Sharing files with earlier releases of FrameMaker products

 Converting database files into Frame documents

14 FDK Programmer’s Guide

 Filtering word processor documents into Frame documents

You can find documentation for MIF in the online manuals folder for your FrameMaker installation.

Choosing the right Frame tools

There are often several tools or combinations of tools that you can use to solve a given problem. In particular, you can use the API to perform many of the tasks that MIF and fmbatch perform. The tool or combination of tools you should use depends on your needs. Generally, MIF and fmbatch are more useful for one-time solutions to small problems, whereas the API is more useful for full-scale applications or applications where interaction with the user is required.

The following table summarizes the advantages and limitations of each Frame tool.

Frame tool or feature Advantages Limitations

Using Frame Developer Tools

Choosing the right Frame tools

. . .

Frame API Fast, interactive, and portable; easy to

provide a user interface for your applications

MIF Can be used by text-processing

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

Must be compiled

Files must be saved as MIF; not interactive

FDK Programmer’s Guide 15

Using Frame Developer Tools

FDK documentation

FDK documentation assumes that you have a thorough knowledge of FrameMaker . For background information on FrameMaker, see your user documentation.

FDK documentation includes the following manuals, which are available in the doc folder of your FDK installation.

FDK Programmer’s Reference

The FDK Programmer’s Reference provides FDK reference information, such as error codes and data structure, function, and property descriptions.

FDK Programmer’s Guide

The FDK Pr ogrammer’s Guide is the guide you are reading now. It describes how to use the FDK to create clients for FrameMaker. To get the most from this guide, you should be familiar with the C programming language and event-driven programming.

The FDK Programmer’s Guide is divided into four parts:

 Part I, "Getting Started," provides step-by-step guidance for getting familiar with the

FDK.

 Part II, “Frame Product Architecture,” provides a conceptual overview of how the

API represents sessions, books, and documents.

 Part III, "Frame Application Program Interface (API),” provides instructions for

creating API clients.

 Part IV, "Frame Development Environment," provides instructions for making filters

and API clients platform-independent.

Naming conventions

To help you identify the structures, constants, and functions defined by the FDK, this manual and the FDK adhere to the following naming conventions:

Type Naming convention Example

API error codes Begin with FE _ FE_NotPgf API functions Begin with F_Api F_ApiGetInt()

16 FDK Programmer’s Guide

Using Frame Developer Tools

Style conventions

Type Naming convention Example

. . .

Style conventions

API scriptable function property names

FDE functions Begin with F_ F_StrNew() Flags used by API functions Begin with FF_ and all

Initialization constants Begin with FA_Init FA_Init_First Notification constants Begin with FA_Note FA_Note_PreFileType Object property names Begin with FP_ FP_Fill Object types Begin with FO _ FO_Doc Property value constants Begin with FV_ FV_Doc_Type_MIF Typedefs End with T MetricT

Begin with FS_ FS_NewDoc

FF_UFF_VAR

letters are uppercase

This manual uses the term API graphic object to refer to objects (such as FO_Polygon and FO_TextFrame objects) that the API uses to represent the graphic objects (such as polygons and text frames) that appear on a page.

FDK manuals distinguish between you, the developer, and the user, the person for whom you write clients.

FDK manuals may use the term FrameMaker product to refer to the FrameMaker software, as opposed to the software you write to work with the FrameMaker product.

Structured program interface

FrameMaker 7.0 and later ships with two program interfaces—Structured FrameMaker and FrameMaker. The structured program interface presents menus, icons, and commands for working with structured documents. The FDK includes some functions that only work on structured documents. For example, setting an element range makes no sense in a document that doesn’t contain any structure elements. Further, you can specify that an FDK client requires the Structured FrameMaker program interface. For example, assume you specify Structured FrameMaker when you register your client. If a user has your client installed, but is running the FrameMaker program interface (not structured), then his installation of FrameMaker will not initialize your client when it starts up.

FDK Programmer’s Guide 17

Using Frame Developer Tools

Style conventions

The FDK Programmer’s Reference indicates those FDK functions that apply only to structured FrameMaker documents, as follows:

Structured F_ApiGetAttributeDefs()

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.

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 ellipsis in the following code indicates that some of the code necessary to create a complete program is omitted:

. . . F_ApiAlert((StringT)"Hello world.", FF_ALERT_CONTINUE_NOTE); . . .

18 FDK Programmer’s Guide

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

This Getting Started section is intended to help you get familiar with the basics of FDK. It includes information on creating, compiling, running, and debugging FDK clients. Sample code snippets are provided as pointers that you can build upon and create your own FDK clients.

In this section:

 "Downloading and installing the FDK"

 "System requirements"

 "Reviewing the sample programs in the samples/hello folder"

 "Getting familiar with how the FDK works on Windows"

 "Writing FDK clients for Windows"

 "Compiling, Registering, and Running FDK Clients"

 "Writing an Asynchronous FDK Client"

 "Example: adding menus and commands"

2Getting Started with FDK

. . . . .

 "Next Steps"

FDK Programmer’s Guide 19

Getting Started with FDK

Downloading and installing the FDK

DownloadingandinstallingtheFDK

Download the FrameMaker FDK from the FrameMaker Developer Center

http://www.adobe.com/devnet/framemaker.html

System requirements

Ensure that your system meets the following requirements:

 Intel Pentium IV

 Microsoft Windows XP, or Windows Vista or Windows 7

 1GB of RAM

 53MB of available hard-disk space

In addition, you should have Microsoft Visual Studio 2010 installed on the system.

20 FDK Programmer’s Guide

Getting Started with FDK

Reviewing the sample programs in the samples/hello folder

The samples folder contains several programs that will help you get started. As an example, here is a code extract from the samples/hello/hello.c file:

/* * Program Name: * hello * * General Description: * Greets the user at product startup time. * * Invocation: * Once the client is installed, launch FrameMaker. * * Install Info (Windows): * Add the following entry (all on one line) to the

[APIClients] * section of your maker.ini file: * * hello=Standard, Greets user at startup, * fdk_install_dir\samples\hello\debug\hello.dll, all * * Replace fdk_install_dir with the path of the directory * in which you installed your copy of the FDK files. * Restart maker. * * Exceptions: * None. *

**************************************************************** *******/

. . .

#include "fapi.h" /* required for all FDK client programs */ #include "fencode.h"

/* Call back invoked at product startup time */

FDK Programmer’s Guide 21

Getting Started with FDK

Getting familiar with how the FDK works on Windows

VoidT F_ApiInitialize(init) IntT init; {

/* Making it unicode enabled. */ F_FdeInit(); F_ApiEnableUnicode(True); F_FdeInitFontEncs("UTF-8");

Getting familiar with how the FDK works on Windows

FDK clients on Windows are not implemented as true Windows clients. They are dynamic link libraries (DLLs) that provide entry points or callback functions, which FrameMaker can invoke.

There are several types of FDK clients:

 A standard FDK client is an FDK client that initializes when FrameMaker starts and

thenwaits to respond to specific user actions, such as menu choices.

 A take-control client is an FDK client that responds to a special initialization and

takes complete control of a FrameMaker session. Many of the effectsyou can get with this type of client can also be realized by an asynchronous client.

 A filter is an FDK client that converts FrameMaker files to or from other file formats.

FrameMaker calls a filter when the user attempts to open, import, or save a file with a particular format.

 A document r eport is an FDK client that provides information about a document. The

user can start a document report by choosing Utilities>Document Reports from the File menu and selecting the report from the Document Reports dialog box.

When FrameMaker starts, it reads the maker.ini file in the FrameMaker installation directory, and if applicable, the maker.ini file stored in the user’s Documents and Settings directory. The [APIClients] section of the maker.ini file contains entries describing the FDK clients to be loaded. FrameMaker then scans the

fminit/Plugins directory and subdirectories and loads the FDK clients that have a .dll file extension and valid VERSIONINFO resource information. FrameMaker

ignores all other files in the fminit/Plugins directory that do not have a .dll file extension and valid VERSIONINFO resource information.

22 FDK Programmer’s Guide

WritingFDKclientsforWindows

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

How to write an FDK client for Windows

When you write an FDK client, you should do the following for it to compile and run correctly on Windows:

 Include the correct FDK header files in the correct order

 Replace platform-specific functions and data types with FDE equivalents

 Include calls to initialize the FDE if your client calls FDE functions

The following sections discuss these tasks in greater detail.

Including FDK header files

The following table lists the header files you must include in your client in the order in which you must include them.

Getting Started with FDK

Writing FDK clients for Windows

. . .

If you are using Include

Any FDK function or constant fapi.h Any FDE type fdetypes.h

A specific FDE function Header file for the function’s group (for example,

fhash.h for a hash function). For more information, see the function’s description in the FDK Programmer’s Reference guide.

Any Structure Import/Export API functions

Constants for Frame f-codes fcodes.h

fm_struct.h

IMPORTANT: You must include the fapi.h header file before any other FDK header

files. For example, if your client uses API functions and FDE metric utility functions, it must include header files as follows:

#include "fapi.h" #include "fdetypes.h" #include "fmetrics.h"

If you need to include any C library header files or your own header files, include them before the FDK header files.

FDK Programmer’s Guide 23

Getting Started with FDK

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

Writing FDK clients for Windows

Adding calls to initialize the FDE

If your client calls FDE functions, it must call F_FdeInit() once before it calls the functions. The syntax for F_FdeInit() is:

ErrorT F_FdeInit(VoidT);

To call F_FdeInit(), your client must include the fdetypes.h header file.

Howtowritefilterclients

You can use filter clients to translate documents from one format to another. FrameMaker invokes an import filter client when it recognizes a file of a particular format or when the file has a registered suffix. It invokes an export filter when you choose a particular format from the Format pop-up menu of the Save As dialog box or save a file using a registered suffix. For example, if you register a suffix for a text import filter and then open a file with that suffix, the Unknown File Type dialog box appears with the appropriate filter preselected.

You must register your filter client before use. For information on registering clients, see "Compiling, Registering, and Running FDK Clients"

You can also use your filter to import text or graphic files into a document. If you import a file by reference, FrameMaker stores in the document the registered format and vendor ID of the filter used in the import operation. If you import the file by copy, FrameMaker stores the facet name in the document. The information in both these cases ensures that FrameMaker invokes the correct filter for updating the next time you open the document.

IMPORTANT: If you are writing a filter client, FrameMaker will not fully recognize it

unless you include function calls that actually cause the API library to link with your client. To make sure the client links properly , you can include the following as minimal code in your F_ApiNotification() function:

. . . F_ObjHandleT docId; docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);

Identifying your filter

To identify your filter to FrameMaker, you need to supply information in the line that registers the filter. This information identifies the filter on all platforms and identifies the original import filter when reimporting the file. FrameMaker uses several pieces of information that you specify for this purpose:

 The vendor ID is a four-character string describing the provider of the filter.

24 FDK Programmer’s Guide

Getting Started with FDK

Writing FDK clients for Windows

 The format ID is a four-character string describing the file format of files on which

the filter operates.

 The facet name is an arbitrary-length string describing the filter.

For example, assume you create a filter for Windows machines that translates Himyaritic documents to English. You give it the format ID "HIMF" and the vendor ID "FAPI". If you create a document and create a text inset using that filter, FrameMaker stores this information with the inset. The next time you open that document, FrameMaker knows to update the inset with your Himyaritic filter.

FrameMaker reserves the following vendor IDs:

 "FRAM"

 "FFLT"

 "IMAG"

 "XTND"

 "AW4W"

 "ADBE"

. . .

 "ADBI"

Your client cannot use these vendor IDs. FrameMaker recognizes FAPI as a valid ID for anyFDK filter client. However, you do not have to use this ID. You can use any other four-characterstring as your vendor ID.

FrameMaker reserves format IDs for the indicated file formats. For a complete list of format Ids, see "Specifying format IDs and filetype hint strings"

. FrameMaker does not supply filters for all of these formats. However, to aid in portabilityof your clients, you should not use one of these format IDs unless it is for the specified file format.

Automatic recognition of a file format

Some graphic file formats have signature bytes. Signature bytes are a set of bytes that have a unique value and location in a particular file format. FrameMaker can use signature bytes to identify a graphic file’s format.

The documentation for the file format that your graphics filter converts may contain information on the signature bytes for that format. If it does, you can register the signature bytes in the [FormatList] section of the maker.ini file. Each graphic file format description must be on a separate line and must have the following format:

n=facet_name start_offset signature_size signature

where n is any number, facet_name is the file format’s description (also used in the client registration), start_offset is how many bytes from the start of the file the signature begins, signature_size is the size in bytes of the signature, and signature is the hexadecimal value of the signature. You can enclose any of the

FDK Programmer’s Guide 25

Getting Started with FDK

Writing FDK clients for Windows

arguments in double quotation marks. For example, you can register the file format for MIF with the following:

[FormatList] 100="MIF" 0 8 0x3c4d494646696c65

where 0x3c4d494646696c65 is the hexadecimal encoding of the characters MIFFile.

Using Windows pathnames

The FDK delimits pathnames with backslashes (\). When you specify a pathname in an FDK function call, follow these rules:

 Follow the drive letter with a colon.

 Don’t terminate a pathname that specifies a file with a backslash.

The following table lists examples of files and directories and the pathname strings that specify them.

File or Directory Absolute Pathname Relative Pathname

File named myfile.doc on the c: drive

Directory named mydir on the c: drive

c:\myfile.doc myfile.doc

c:\mydir mydir

Because the backslash is a special character, you must precede it with another backslash when you specify it in a string. For example, to open a file named c:\myfile.doc with F_ApiSimpleOpen(), use the following code:

F_ApiSimpleOpen("c:\\myfile.doc", False);

Using pathnames returned by FDK functions

Pathnames returned by FDK functions don’t end with a backslash, unless they specify rootdirectories, such as c:\.

Using F_PathNameToFilePath()

To specify an absolute pathname when you call F_PathNameToFilePath(), you must specify a pathname that includes the drive and begins with the root directory of the drive. If the pathname does not include the drive and begin with the root directory of the drive, F_PathNameToFilePath() assumes the pathname is relative.

If you call F_PathNameToFilePath() with anchor set to NULL and you do not specify an absolute pathname, F_PathNameToFilePath() adds the currently open

26 FDK Programmer’s Guide

Getting Started with FDK

Writing FDK clients for Windows

directory or the currently open directory of the specified drive to the pathname. For example, if you specify c:myfile.c for pathname, F_PathNameToFilePath() generates: c:\cwd\myfile.c, where cwd is the currently open directory on drive c:. If you specify \\myfile.c for pathname, F_PathNameToFilePath() generates: current_drive:\myfile.c, where current_drive is the current drive.

If you do not set anchor to NULL, F_PathNameToFilePath() constructs the filepath relative to the path specified by anchor. If the pathname you specify for pathname and the filepath you specify for anchor are inconsistent, F_PathNameToFilePath() ignores anchor and constructs the filepath with the currently open directory

Using F_FilePathGetNext()

The function F_FilePathGetNext() returns the next file in a specified directory. To do so, this function uses DOS system calls. As a result, since DOS is case-insensitive, the returned FilePathT structure uses only uppercase letters. This may not match a FilePathT structure you have created.

. . .

FDK Programmer’s Guide 27

Getting Started with FDK

Writing FDK clients for Windows

For example, assume you want to create a filepath and then at some later time process all files in the same directory other than the one you created. You might be tempted to use this code:

/* Bad code! */ . . . /* Create the new filepath */ newpath = F_PathNameToFilePath ("vpg.doc", NULL, FDosPath); . . . DirHandleT handle; FilePathT *path, *file; IntT statusp; pathname = StringT; handle = F_FilePathOpenDir(newpath, &statusp); if (handle) { pathname = F_FilePathToPathName (newpath); while ((file = F_FilePathGetNext (handle, &Statusp)) != NULL) { /* WRONG! This attempts to compare current file to the one you

created. */ if ! (F_StrEqual (pathname, F_FilePathToPathName (file))) ProcessFile (file); F_FilePathFree (file); } } /* Bad code! */

. . ..

28 FDK Programmer’s Guide

The string returned by F_FilePathToPathName(newpath) contains the lowercase letters as specified in the earlier call to the function F_PathNameToFilePath(). On the other hand, the string returned by each call to F_FilePathToPathName() always contains only uppercase letters. Therefore, the call to F_StrEqual() never succeeds. Instead of calling F_StrEqual(), you should call F_StrIEqual().

Using menus and commands

The following sections describe how to use menus and commands in your FDK client.

Getting Started with FDK

Writing FDK clients for Windows

FindingFrameMakermenuandcommandnames

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

MathCharacterFile = fminit\mathchar.cfg ConfigCommandsFile = fminit\cmds.cfg MSWinConfigCommandsFile = fminit\wincmds.cfg ConfigMathFile = fminit\mathcmds.cfg ConfigMenuFile = fminit\maker\menus.cfg ConfigCustomUIFile = fminit\customui.cfg

The following table lists the menus and commands each file contains.

Menu or Command File Contents

MathCharacterFile Special math characters ConfigCommandsFile Basic commands

. . .

MSWinConfigCommandsFile Windows-specific commands ConfigMathFile Math commands ConfigMenuFile Standard menus ConfigCustomUIFile Custom menus

Using FDK functions that write to FrameMaker console

The following functions write output to the FrameMaker console on Windows:

 F_ApiPrintFAErrno()  F_ApiPrintOpenStatus()  F_ApiPrintPropVals()  F_ApiPrintSaveStatus()  F_Printf() with Channel set to NULL  F_Warning()

For descriptions of these functions, see the FDK Programmer’s Reference guide. As with printf(), the F_Printf() function does not automatically print a line feed ("\n") after the output. If you don’t end the output with "\n", the next call to one of the functions listed above begins printing on the last line printed by the F_Printf() call.

FDK Programmer’s Guide 29

Getting Started with FDK

Compiling, Registering, and Running FDK Clients

Using platform-dependent session properties

Session (FO_Session) objects have the following platform-dependent properties:

Property Value

FP_FM_BinDir Pathname of the bin directory in the FrameMaker installation

Compiling FDK Clients

The following sections describe how to compile FDK sample clients and your own clients.

Supported compilers

To compile FDK clients for Windows, you must use Microsoft Visual Studio 2010.

30 FDK Programmer’s Guide

Getting Started with FDK

Compiling, Registering, and Running FDK Clients

Compiling and registering sample clients in Microsoft Visual Studio 2010

To compile and register a sample FDK client in Microsoft Visual Studio 2010, follow these steps:

1. Start Microsoft Visual Studio 2010

2. Open the Project and then choose the solution file for one of the sample clients.For

example, to compile the aframes sample client, choose

fdk_install_dir\samples\aframes\aframes.sln, where fdk_install_dir is the pathname of the directory in which the FDK is installed.

NOTE: The project settings for the sample clients have relative paths to the FDK lib and

include files already specified. If you open a sample project from its location in the FDK installation, these paths will be valid. If you move the sample client to a different location, you may need to specify new paths for the include and lib files. For more information, see "Compiling and registering your own FDK clients"

3. Use the build utility to build the client. Choose Rebuild Solution from the Build

menu. Microsoft Visual Studio 2010 compiles your code into a DLL file named project.dll in the debug subdirectory of your client directory, where project is the name of the sample project. For example, the aframes sample client compiles into debug\aframes.dll.

4. Register the sample client.

. . .

Each of the following sample clients includes a VERSIONINFO resource, and you register each by placing the DLL file in the Plugins folder:

 pickfmts  elemutils  dialog

Because the remaining sample clients do not include a VERSIONINFO resource, you must register them in the maker.ini file. For more information see "Registering clients

in the FrameMaker maker.ini file".

Running the sample FDK clients

It is best to store client DLL files in the FrameMaker Plugins folder (install_dir\FrameMaker<version>\fminit\Plugins), or in a folder below it. If you register your clients via the VersionInfo resource, you must store them in this way. When you register a client in the .ini file, you can specify any location for the DLL file.

After you have compiled and registered a sample FDK client, start FrameMaker to test the client. Some of the sample clients add menus and commands to the FrameMaker menus. For example, if you have compiled and registered the sample client described in

FDK Programmer’s Guide 31

Getting Started with FDK

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

Compiling, Registering, and Running FDK Clients

"Introduction to the Frame API", a menu named API appears on the FrameMaker menu

after you start FrameMaker. To test the commands on this menu, open or create a document, and choose each of the commands.

Compiling and registering your own FDK clients

To compile and register one of your own FDK clients, follow the instructions in this section.

Compiling and registering the client

To compile and register the FDK client, follow these general steps:

1. Create a project directory for your FDK client project.

2. Start Microsoft Visual Studio 2010 and create a new Win32 Dynamic- Link Library

project.

Choose New and then project from the File menu. The New dialog box appears. Select Visual C++ Projects and then Win32 from Project Types. Select Win32 Project, type your client's name in the Name field and then click OK. Win32 application wizard appears.

Click on Application Settings, select DLL from Application Type and Empty project from Additional Options.

3. Create or place your source files in the project directory, then add those files to your

project.

4. (Optional) Create a resource for any custom dialog boxes. If your client contains

custom dialog boxes, you need to create a resource for them. For instructions, see

"Handling Custom Dialog Box Events"

5. (Optional) Create a VERSIONINFO resource. Including a VERSIONINFO resource

is one method for registering a client. For more information on registering clients, see "Registering FDK Clients"

6. Choose Properties from the Project menu to display the Properties Pages dialog box.

In the Properties Pages dialog box, choose General . Set Use of MFC field to Use Standard Windows Libraries.

IMPORTANT: If you don’t set the Use of MFC field to "Use Standard Windows

Libraries", your client will not link correctly.

7. Set your project’s C/C++ Language options.

In the Property Pages dialog box, choose C/C++.

32 FDK Programmer’s Guide

Getting Started with FDK

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

Compiling, Registering, and Running FDK Clients

Choose Code Generation and choose 8 Byte or default from the Struct Member Alignment pull down menu. 8 bytes is also the default value for this field.

IMPORTANT: If you don’t set the Struct Member Alignment to 8 Bytes, your client may

cause unexpected runtime errors.

With Code Generation still selected, choose Single-Threaded from the Runtime Library popup list. The FDK ships in a single-threaded version. By default, the project sets this option to Multi-threaded. Compiling the FDK with a multi-threaded runtime library produces the following warning:

defaultlib "LIBC" conflicts with use of other libs;

IMPORTANT: For Version 7.0 and later of the FDK, it is important that you make this

setting. Earlier versions of the FDK did not use symbols that conflicted with the multithreaded runtime library. However, for version 7.0 and later the FDK and the Structure Import/Export API use conflicting symbols.

. . .

In the General page under C/C++ language options, add path to the FDK include files in Additional Include Directories field. You can specify an absolute path or a relative path. For example, the Property Pages for the sample clients all use the following relative path:

..\..\include

8. Set your project’s Linker options:

In the Property Pages dialog box, choose the Linker page.

Choose General and then Input. Add the FDK libraries fdk.lib, api.lib, and fmdbms32.lib to the additional

dependencies field.

If you are compiling a structure import/export client, be sure to also link the Structure Import/Export API library. For more information, see "Linking the Structure

Import/Export API library".

IMPORTANT: If your client inclu des cust om dialog boxes, you must add

/section:.rsrc,w to the Project Options. For more information, see “"Compiling clients

with custom dialog boxes"”.

In the Category field, choose Input, then add the path to the FDK lib files in the Additional library path field.

FDK Programmer’s Guide 33

Getting Started with FDK

Compiling, Registering, and Running FDK Clients

You can specify an absolute path or a relative path. For example, the project settings for the sample clients all use the following relative path:

..\..\lib

As an alternative, you can specify access to the FDK include and lib directories for the Development Environment 2003. To do this, choose Tools > Options to display the Options dialog box. Select Project and then VC++ Directories, and enter the paths to the FDK include and lib directories for Include files and Library files.

9. Use Microsoft Visual Studio 2010 build utility to build your client.

Choose Rebuild All from the Build menu. Visual Studio compiles your code into a dynamic link library file with the name you typed in the New dialog box. It puts this library file into the debug subdirectory of your client directory.

10. Register the client.

You can register the client by using either of these two methods:

 As mentioned in step 5, create and include in your client’s project a VERSIONINFO

resource that contains information about the client, and copy or move the compiled client into the fminit/Plugins directory.

 Add an entry for your client in the [APIClients] section of the maker.ini file

inthe FrameMaker directory.

For more information on registering clients, see "Registering FDK Clients"

Usingcustomdialogboxes

The FDK samples include a template document for designing custom dialog boxes. You open this document in FrameMaker and edit it with the FrameMaker graphic tools and commands.

When you save a custom dialog box in a Windows version of FrameMaker, it generates two Windows resource definition files, a .dlg file and a .xdi file.

 The .dlg file is a text file containing resource statements. These statements are

standard Windows descriptions of the dialog box and its controls.

 The .xdi file is a text file containing a user-defined resource statement. This

statement contains data used by FrameMaker to manipulate the dialog boxes.

When creating the .dlg and .xdi files, FrameMaker uses the name of the .dre file (without the extension) to name the files and the actual dialog resource. For example, when saving the file named mydlg.dre, FrameMaker creates the resource description files mydlg.dlgand mydlg.xdi. Both files describe the dialog resource named mydlg.

To compile the .dlgand .xdifiles in your dll you must create a resource for the project, and provide directives to include these files in the resource. In the process of

34 FDK Programmer’s Guide

Getting Started with FDK

Compiling, Registering, and Running FDK Clients

compiling the client, these resource definition files are compiled into a single resource file (.rc). This resource file is linked to your client. To set up the resource definition files to be compiled, follow these general steps:

1. Start Microsoft Visual Studio 2010.

2. If one doesn’t already exist for the project, create a resource script. Choose Add New

Item from the File menu. The Add New Item dialog box appears. Choose Resource File.

3. Include the resource description files generated by FrameMaker.

Choose Resource Includes from the Edit menu. The Resource Includes dialog box appears. In the Compile-Time Directives field, type #include statements to include the resource description files. For example, suppose you create two custom dialog boxes named pgftag.dre and chartag.dre. When FrameMaker saves these files it also creates the files pgftag.dlg, pgftag.xdi, chartag.dlg, and chartag.xdi.

To include these files in the resource script, type the following in the Compile-Time Directives field:

#include "pgftag.dlg" #include "pgftag.xdi" #include "chartag.dlg" #include "chartag.xdi"

. . .

Compiling clients with custom dialog boxes

If your FDK client uses custom dialog boxes, you need to specify a special link option before compiling it:

1. In Micrsoft Visual Studio, choose Project->Properties. This displays the Project Properties dialog box.

2. Choose Linker and then Command Line.

3. Add the following option to the Additional Options field:

/section:.rsrc,w

This link option makes the dialog resources writable. If you do not specify it before compiling, your DK client may exit unexpectedly when it attempts to display a custom dialog box.

4. Repeat steps 3 for each target in your project.

Making adjustments to custom dialog boxes

Since the .dlg files produced by FrameMaker are text files containing resource statements, you can open these files as resources. You can use the built-in tools for

FDK Programmer’s Guide 35

Getting Started with FDK

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

Compiling, Registering, and Running FDK Clients

dialog editing to view, adjust, and test the dialog box. Because you are modifying the .dlg file but not the .xdi file, you should not make major changes to the dialog box (for example, do not add new items to the dialog box). If you do, the description in the .dlg file will not match the description in the .xdi file.

LinkingtheStructureImport/ExportAPIlibrary

To link the Structure Import/Export API library on Windows follow these steps:

1. In Microsoft Visual Studio 2010, open your client’s project.

2. Choose Properties from the Project menu to display the Properties Pages dialog box.

3. In the Property Pages dialog box, click on Linker and then Input.

4. Add the Structure Import/Export API library struct.lib and the resource

fmstruct.res to the Additional Dependencies field. Add struct.lib before fdk.lib, and add fmstruct.res to the end of the Object/Library Modules field.

5. Add the following link option to the 'Additional Options' field in 'Command Line'

property page:

/section:.rsrc,w

IMPORTANT: This link option is required for some of the dialog boxes that ar e internal

to the structure import/export functionality in FrameMaker. Without this link option, your client may crash when it interacts with these dialog boxes.

Registering FDK Clients

For FrameMaker to recognize your client, you must register it on the system on which you intend to run it. When registering your client, you can name it anything you like, although the name cannot contain spaces. Also, you should not use a name that is already used by one of the clients that ships with FrameMaker.

To register your client, you add an entry for your client in the [APIClients] section of the maker.ini file in the FrameMaker directory. The [APIClients] section of the maker.ini file lists the FDK clients to load when FrameMaker starts. For more information on registering your client using the maker.ini file, see "Registering clients

in the FrameMaker maker.ini file".

Registering clients in the FrameMaker maker.ini file

You can register a client is by adding an entry for the client in the FrameMaker maker.ini file. The [APIClients] section of the maker.ini file lists the FDK clients

36 FDK Programmer’s Guide

Getting Started with FDK

Compiling, Registering, and Running FDK Clients

to load when FrameMaker starts. Each client description must be on a separate line and cannot contain line breaks. Clients that are not filters use the following format:

client = type, description, DLL_file, mode

where

For this statement Specify

client the client’s name type the type of client—valid types for clients other than filters

are Standard,TakeControl, and DocReport

. . .

DLL_file the pathname of the client’s DLL file—can specify a full

mode whether the client can run with FrameMaker in unstructured

pathname or a relative pathname based on the FrameMaker installation directory.

or structured mode. This fields can be one of maker, structured, or all. The mode field is required.

The fields in this line are separated by a comma and zero or more spaces. For example, if you have compiled the aframes sample client into c:\fdk\samples\aframes\debug\aframes.dll, and you want to register it with FrameMaker, add the following to the maker.ini file in the FrameMaker installation directory (without any line breaks):

AFrames=DocReport,Anchored Frames Report,c:\fdk\samples\aframes\ debug\aframes.dll, all

If the client is a filter, register it with the following line:

client = type, facet_name, format_id, vendor_id, display_name, description, DLL_file, mode, suffix

where the variables are:

FDK Programmer’s Guide 37

Getting Started with FDK

Compiling, Registering, and Running FDK Clients

For this statement Specify

type One of:

facet_name the name of the file format supported by the client. format_id a four-character string that identifies the file format vendor_id a four-character string that identifies the client’s provider display_name the filter name to display in in dialog boxes when opening

● TextImport

● GFXImport

● Export

● FileToFileTextImport

● FileToFileTextExport

● FileToFileGFXImport

● FileToFileGFXExport

or saving a file of the given format. This name must match the client name.

description a description of the client that appears when you choose

DLL_file the pathname of the client’s DLL file mode whether the client can run with FrameMaker in

suffix the filename extension of the file type that the client filters

About

unstructured or structured mode. This fields can be one of maker, structured, or all. The mode field is required.

For information on format and vendor IDs, see "How to write filter clients". For example, assume you have a graphics import filter for the CGM format that uses ACGM as its facet name, has its executable stored in acgmflt.dll, and should be invoked on files with the suffix cgm. You can register this filter with this line:

ACGMFILTER=GFXImport,ACGM,CGM,FAPI,ACGMFILTER,acgmflt.dll,all, cgm

Specifying no description for a client

When you register your client by using the FrameMaker maker.ini file, and you don’t want to specify a description, enter a space in the description field. For example:

client= Standard, ,c:\clients\myclient\debug\myclient.dll, all

38 FDK Programmer’s Guide

Getting Started with FDK

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

Compiling, Registering, and Running FDK Clients

The description field must contain at least one character. If no characters appear between the commas delimiting the description field, your client will not be registered.

Running FDK Clients

When FrameMaker starst, it reads the maker.ini file. The [APIClients] section of the maker.ini file contains entries describing the FDK clients to be loaded. FrameMaker then scans the fminit/Plugins directory and subdirectories and loads the FDK clients that have a .dll file extension and valid VERSIONINFO resource information.

FrameMaker ignores any files in the fminit/Plugins directory and subdirectories that do not have a name with the .dll extension, or do not contain valid VERSIONINFO resource information.

For information on how FrameMaker starts a client, see "API Client Initialization” in the FDK Programmer’s Guide.

Compatibility between FDK and FrameMaker product releases

To ensure your existing Windows clients are compatible with release 11 of FrameMaker, you should recompile them. It is possible to run a a client compiled in an earlier version of the FDK with FrameMaker 11, as long as the client does not use any functions or properties that have changed. However, it is recommended that you recompile your clients with the newer version of the FDK as soon as possible.

. . .

Disabling FDK clients

To disable all FDK clients, edit the following line in the maker.ini file in the FrameMaker installation directory, or in the version of the .ini file that is stored in the user’s Documents and Settings directory:

API=On

Replace On with Off. The next time you start FrameMaker, no FDK clients will be started.

IMPORTANT: Some FrameMaker features, such as the Word Count document report,

Save As HTML, or import and export of XML are implemented as FDK clients. If you disable all FDK clients, these features will not be available.

FDK Programmer’s Guide 39

Getting Started with FDK

Compiling, Registering, and Running FDK Clients

Debugging FDK Clients

You debug your client as part of the FrameMaker executable. The FrameMaker executable is not compiled with debugging information, so you don’t have access to any symbols within FrameMaker.

To use Microsoft Visual Studio to debug your client as part of the FrameMaker executable, follow these general steps:

1. Start Microsoft Visual Studio 2010.

2. Open your client’s project and add breakpoints.

3. Select Project->Properties and then Debugging page. Go to Command Field and add

the path to FrameMaker executable.pen the FrameMaker executable. For example, if FrameMaker is installed in

c:\Program Files\Adobe\FrameMaker10,

then to open its executable, open

c:\Program Files\Adobe\FrameMaker10\FrameMaker.exe.

4. From the Build menu select Configuration Manager. Highlight the Debug Project

Configuration.

5. From the Debug menu, choose Start. Alternately, if you have already started the

debugger for your program, from the Debug menu choose Restart. If FrameMaker isn’t able to load your client, it displays the following error message in an alert box:

File Error: Cannot find client_name.dll

40 FDK Programmer’s Guide

FrameMaker may not be able to load your client for the following reasons:

 The client is not located in the fminit/Plugins directory or subdirectories, or does not

have a name with the .dll extension.

 The client’s VERSIONINFO resource information is missing or invalid.  The maker.ini file doesn’t specify the correct full pathname for your client’s DLL.

 The FrameMaker release is incompatible with the FDK release that you used to

compile the client.

To check that your FDK client has control, you can have it display a string in the status bar of the document or book window. For more information, see the descriptions of FO_Book and FO_Doc in the FDK Programmer’s Reference guide.

Writing an Asynchronous FDK Client

This section describes how to create asynchronous clients on Windows, and provides instructions for compiling and running a sample asynchronous client. Before writing an asynchronous API client you should be familiar with both the FrameMaker FDK andWindows API programming.

The purpose of many FDK clients is to modify FrameMaker in some way, such as by changing or adding functionality. In these applications the main goal of the resultant application is still for the end user to use FrameMaker.

A different kind of application is one that uses FrameMaker to support some aspect of the application’s functionality, but in which use of FrameMaker is not the goal. For example, you might create a data base and want to use FrameMaker to print catalogs from it. In this case, your application runs primarily independently of FrameMaker, but calls FrameMaker (possibly as a child process) during some part of its operation.

The FDK allow you to create asynchronous applications that control a FrameMaker process. Even though the main purpose of the application may not be to run FrameMaker, this chapter refers to such an application as an FDK client, since it calls FDK functions.

Getting Started with FDK

Writing an Asynchronous FDK Client

. . .

An asynchronous client does not run as part of the FrameMaker process nor as a child process. Instead, it is its own application in a separate process, communicating with a FrameMaker process via Microsoft RPC (Remote Procedure Calls). You should be aware of some consequences of this difference:

 An asynchronous client can be started independently of any FrameMaker product. It

can be an EXE, or a DLL of some EXE other than FrameMaker.

 It must have its own main() function.

 You can use MFC or any other application framework to develop an asynchronous

client.

 An asynchronous client can run on a machine other than that running the associated

FrameMaker process.

End user installations

To run asynchronous clients, the executable applications or the DLL files must be installed correctly. An EXE can be installed wherever the user wants. A DLL that is a plugin for another application must be installed correctly for that application. A DLL that is a plugin for FrameMaker must be installed in the appropriate Plugins directory, or its path must be specified in the maker.ini file.

The user also must have the following files installed in his or her FrameMaker installation directory, at the same level as the FrameMaker application:

FDK Programmer’s Guide 41

Getting Started with FDK

Writing an Asynchronous FDK Client

 afmfdk.dll  fmrnclnt.exe

In addition, the user must have the following entries in the maker.ini file:

[Files] MarshallingDLL = afmfdk.dll RunWrappedPlugin = fmrnclnt.exe . . . [Preferences] ExecutablePlugins = EXE WrappedPlugins = DLX PluginExtensions = DLL, DLX, EXE

The [Preferences] entries tell FrameMaker which filename extensions are valid for different types of clients.

 PluginExtensions must list extensions for all the files you want to be loaded as

clients of any type.

 ExecutablePlugins lists extensions for clients that are built as executables

which run outside of the FrameMaker process.

 WrappedPlugins lists extensions for clients that are built as DLLs, but will run in

an address space that is external to the FrameMaker process. Such a client uses fmrnclnt.exe to wrap its DLL and runs in the fmrnclnt.exe address space.

Note that you can substitute other extensions for the ones shown in the example above. For more information, see "Types of asynchronous clients"

Registering asychronous clients

You can register asynchronous clients just as you register other clients; you can store the registration data in the client’s VersionInfo resource, or you can make an entry in the maker.ini file for FrameMaker. Additionally, your client can pass an F_PropValsT structure to F_ApiWinConnectSession() that is a list of registration data.

F_ApiWinConnectSession() is defined as:

F_ApiWinConnectSession(const F_PropValsT *connectProps, ConStringT hostname, const struct _GUID *service);

You can include the following properties in connectProps:

42 FDK Programmer’s Guide

Writing an Asynchronous FDK Client

corresponds to this statement in a client’s

This property

FI_PLUGIN_NAME the name of the client. FI_PLUGIN_TYPE the type of client

VERSIONINFO res ource

Getting Started with FDK

. . .

FI_PLUGIN_PRODUCTS

s specifies structured or unstructured FrameMaker, using the

names of FrameMaker products this client upports—use a space-delimited string with one or both of Maker and

MakerSGML

FI_PLUGIN_FACET the name of the file format supported by the client (filters,

only)

FI_PLUGIN_FORMATID a four-character string that identifies a file format (filters,

FI_PLUGIN_VENDOR a four-character string that identifies the client’s provider. FI_PLUGIN_SUFFIX the filename extension of the file type that the client filters

FI_PLUGIN_INFORMAT the file format for the file to filter (filters, only) FI_PLUGIN_OUTFORMAT the file format for the resulting file (filters, only) FI_PLUGIN_DESCRIPTION a description of the client that appears when you choose

FI_PLUGIN_PRODUCTNAME the name by which customers know your client.

If connectProps is NULL, the FrameMaker process uses the client’s VersionInfo resource or the entries in the maker.ini file. If the client has no

registration information in any of these sources, the FrameMaker process registers it as a standard client.

only).

(filters, only).

About

Types of asynchronous clients

Asynchronous clients can be executable applications (EXE), dynamically linked libraries (DLLs) that are a part of another application, or DLLs that are plugins for FrameMaker (wrapped plugins).

FDK Programmer’s Guide 43

Getting Started with FDK

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

Writing an Asynchronous FDK Client

Asynchronous EXE applications

An EXE can be either a console application or a Windows application. After connecting with the FrameMaker process, the EXE application passes calls to FrameMaker through afmfdk.dll.

IMPORTANT: Because they don’t have a Windows mes sage processing loop, co nso l e

applications cannot handle notifications from the FDK. For example, this means a console application cannot process commands from menus it adds to FrameMaker. Nor can it process notifications such as FA_Note_PreOpenDoc or FA_Note_PreSaveDoc.

Asynchronous DLLs

A DLL that is part of another application can call F_ApiStartUp() to make a connection with a FrameMaker process. For example, you could write a plugin for Acrobat Exchange that writes the data from Acrobat Forms to a FrameMaker document. In that case, the DLL communicates with the FrameMaker process, as a part of its parent EXE, via afmfdk.dll.

A DLL that runs as a wrapped plugin for FrameMaker runs in its own memory space. After connecting with the FrameMaker process, the DLL invokes fmrnclnt.exe to run as a wrapper for the DLL. The wrapped DLL then communicates with FrameMaker via afmfdk.dll, as though it is an EXE.

44 FDK Programmer’s Guide

Registering multiple FrameMaker processes as servers

When you first run FrameMaker, it registers istelf in the system registry as the default instance of the FrameMaker instance on that machine. By default, asynchronous clients connect to this instance.

You can register multiple instances of the FrameMaker process, each with a unique entry in the system registry. Then you can use these processes as a bank of servers, and your client can choose among them when making a connection.

You identify a FrameMaker process as a server by its entry in the system registry. The entry can specify:

 A name to identify the GUID for that specific process.

 Whether the process starts up when called by a client, or whether it must already be

running before the client can connect to it.

To register a process, you start FrameMaker with specific commandline options. This creates an entry in the system registry for the machine on which you start FrameMaker.

To start FrameMaker with commandline options:

1. Choose Run from the Start menu.

Getting Started with FDK

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

Writing an Asynchronous FDK Client

The Run Application dialog box appears.

2. In the text box, type the full pathname of the FrameMaker.exe file, followed by the

commandline options. Alternately, you can start FrameMaker from a DOS Command Prompt window. For example, type FrameMaker_path\FrameMaker10 /option, where FrameMaker_path is the install path for the version of FrameMaker you want to run, and /option is one or more of:

 progid:process_name

where process_name is a name you provide. This option registers a name for the FrameMaker process.

 auto

This option allows the FrameMaker process to automatically start up if it isn’t running when another process calls it.

 noauto

This option disallows automatic start-up.

. . .

This creates an entry in the system registry for the machine on which you started FrameMaker.

Registering a name for a FrameMaker process

To specify a name for the process, use the /progid option. For example, type

FrameMaker_path\FrameMaker10 /progid:MyProcess.Api1, where FrameMaker_path is the install path for the version of FrameMaker you want to run.

This establishes a name, MyProcess.Api1, for the process. When you start FrameMaker with no /progid option, you create system registry entry

with the default name of FrameMaker.API.1.

Asynchronous clients running locally on the host can refer to processes by their names. In this way, your client can choose which process to run for a given task.

IMPORTANT: Client s connecting to a remote host cannot use the process name to

connect to a FrameMaker process. Instead, they must use the GUID for that process, as it is specified in the system registry.

Registering automatic start-up for a process

If the FrameMaker process is not running, an asynchronous client can still call it. If the process is so registered, it will start up when the client calls it. Alternatively, you can register the process in a way that does not allow automatic start-up.

FDK Programmer’s Guide 45

Getting Started with FDK

Writing an Asynchronous FDK Client

To register the process for automatic start-up, use the /auto option. To disallow automatic start-up, use the /noauto option. For example, type FrameMaker_path\FrameMaker7.2 /progid:MyProcess.Api1 /auto, where FrameMaker_path is the install path for the version of FrameMaker you want to run. This establishes a process named MyProcess.Api1, which will start automatically when an asynchronous client calls it.

Running asynchronous clients on remote hosts

With systems that support DCOM, you can run a client on one machine (the client machine), connected to a FrameMaker process on another machine (the host machine). To accomplish this, you make use of the DCOM services provided with your operating system. Also, both machines must be in the same domain, and the same user must have the accounts on both machines.

For an asynchronous client to connect to a FrameMaker process on a remote host:

1. Register the FrameMaker process as a server process on the host machine.

This establishes entries on the host machine’s system registry for the FrameMaker processes you want to run as servers. For more information see “"Registering multiple

FrameMaker processes as servers".

2. Run dcomcnfg on the host machine to configure DCOM accessibility for each

process you want to run as a server.

46 FDK Programmer’s Guide

This enables DCOM connections to the FrameMaker server processes that are registered on the host machine.

3. Run dcomcnfg on the client machine to configure its DCOM accessibility.

This enables the client machine to connect to the host machine via DCOM.

Enabling DCOM for the server processes on the host

To enable DCOM for a FrameMaker process on the host machine:

1. Choose Run from the Start menu.

The Run dialog box appears.

2. In the Run dialog box, type dcomcnfg

The DCOM Configuration Properties service application appears.

3. Select the Default Properties tab and click Enable Distributed COM on this

Computer.

4. In the Applications list box, double-click the FrameMaker process you want to

enable, then set the appropriate security options.

Getting Started with FDK

Writing an Asynchronous FDK Client

5. Click the Security tab and make sure Use default configuration permissions is turned

on.

6. Apply any other settings to the FrameMaker process or your computer that are

appropriate for your network configuration. You should check with the system administrator to ensure the options you set are compatible with his administration procedures.

7. Click OK.

Enabling DCOM for client machine

To enable DCOM on the client machine:

1. Choose Run from the Start menu.

The Run dialog box appears.

2. In the Run dialog box, type dcomcnfg

3. The DCOM services application appears.

4. Select the Default Properties tab and click Enable Distributed COM on this

Computer.

. . .

5. Apply any other settings to your computer that are appropriate for your network

configuration.You should check with the system administrator to ensure the options you set are compatible with the administration procedures.

6. Click OK.

To find more information on DCOM see the Windows Online Help.

Connecting with a FrameMaker process

Asynchronous clients connect with a FrameMaker process by calling F_ApiStartUp() or F_ApiWinConnectSession(). When connecting to a process on a local host, FrameMaker does not have to be registered as a server. For a process on remote host, your client must know the GUID for that process.

A machine may have more than one FrameMaker process running at a time. In that case, the processes must be registered as servers, and they should be registered with a name for each process. For information about registering FrameMaker processes as servers, see "Registering multiple FrameMaker processes as servers"

Asynchronous clients use COM to communicate with FrameMaker processes. If any FDK call returns FE_Busy, then you probably need to register a message filter. When using COM, an application should always register a message filter. If your code calls F_ApiStartUp() or F_ApiWinConnectSession() before initializing COM, these routines automatically initialize COM and register a message filter. However, if you initialized COM before calling these routines, they assume your application already

FDK Programmer’s Guide 47

Getting Started with FDK

Writing an Asynchronous FDK Client

registered a message filter. If your application initializes COM but does not register a message filter, be sure to call F_ApiWinInstallDefaultMessageFilter().

Connecting to the default process on a local host

You use F_ApiStartUp() when the desired FrameMaker process is running on the local machine. For example, a DLL that is a FrameMaker plugin calls F_ApiStartUp(). In that case, the FrameMaker process that invokes the DLL identifies itself by passing a globally unique identifier (GUID) via the FMGUID environment variable. Likewise, if you want an EXE to connect locally to the currently active FrameMaker process, use F_ApiStartUp().

The following call makes this connection:

F_ApiStartUp(NULL);

For more information, see F_ApiStartUp() in the FDK Programmer’s Reference guide.

Connecting to a named process on a local host

To connect to a named process on a local machine, you need to convert the process name to a GUID. Then you can pass that GUID to F_ApiWinConnectSession() to initiate communication between your client and the FrameMaker process.

48 FDK Programmer’s Guide

Note that F_ApiStartUp() makes a reliable connection only when the desired FrameMaker process is the only FrameMaker process running on the local host. If no FrameMaker process is running, F_ApiStartUp() will not work. Also, if more than one process is running,

F_ApiStartUp() cannot determine which process will finally connect with your client. To choose one of many FrameMaker processes on a local host, you should have all of the processes registered as servers on that host.

If you have registered the process as a named server, and your client is connecting to it on a local host, you can use the Win32 API to get the GUID associated with that name. Then you pass the GUID to F_ApiWinConnectSession().

The following example uses the Win32 API function CLSIDFromProgID() to get the GUID for a process named MyProcess.Api1. It then calls F_ApiWinConnectSession() to connect to the process. Note that you need a

Getting Started with FDK

Writing an Asynchronous FDK Client

Unicode string for the process name. The example uses the Win32 API call,

MultiByteToWideChar() to convert a string to Unicode.

#define WBUFLEN 512 OLECHAR progStr; CLSID serviceId; StringT myProcess = F_StrCopyString("MyProcess.API.1"); . . . progStr = (OLECHAR*)malloc( WBUFLEN*sizeof(wchar_t) ); MultiByteToWideChar(CP_ACP, 0, (char *)opt_progid, -1, progStr,

WBUFLEN ); if(CLSIDFromProgID(progStr, &serviceId))

F_ApiConnectWinSession(0, 0, &serviceId);

. . .

Note that F_ApiWinConnectSession() takes three parameters. In the first parameter you can pass a list of properties that correspond to the entries you provide when registering a FrameMaker client.

. . .

The second parameter is for the address of a remote host, when making a connection to a remote host. If this parameter is NULL or 0, F_ApiWinConnectSession() connects to the local host.

The third parameter specifies the desired FrameMaker process on the host machine. If this parameter is NULL or 0, F_ApiWinConnectSession() uses the value of the FMGUID environment variable on the specified host.

For more information, see F_ApiWinConnectSession() in the FDK Programmer’s Reference guide.

Connecting to a remote host

To connect to a remote machine, you need the address of that machine. Once you have the address, you can call F_ApiWinConnectSession() to initiate communication between your client process and the FrameMaker process on the host machine. The following call makes this connection to the currently running FrameMaker process on the remote host:

F_ApiWinConnectSession(0, remote, 0);

where remote is the address of the remote host.

The above call only works when the desired FrameMaker process is the only FrameMaker process running on the remote host. If no FrameMaker process is running, this will not work. Also, if more than one process is running, you cannot predict which process will finally connect with your client.

FDK Programmer’s Guide 49

Getting Started with FDK

Writing an Asynchronous FDK Client

To choose one of many FrameMaker processes on a remote host, you should have all of the processes registered as servers on that host.

To choose a registered process, you must know the GUID for that process ahead of time; you pass that GUID to F_ApiWinConnectSession(). Assuming you have specified a GUID in serviceId, the following call connects to a specific process on the remote host:

stringT remote;‘ CLSID serviceId; . . . F_ApiWinConnectSession(0, remote, &serviceId);

where remote is the address string of the machine that is running the FrameMaker process.

How to write an asynchronous FDK client

To write an asynchronous client that communicates with FrameMaker, you proceed as you would for any C application, providing a main() function and adding whatever functionality you need.

A Windows client can get control of a FrameMaker process by invoking F_ApiCallClient() to call itself. For the duration of the notification, that is while the client is processing the resulting callback, the client has exclusive control of FrameMaker. At some point in its processing, your client needs to communicate with a FrameMaker process. To do so, it follows these general steps:

1. Connect to the FrameMaker process. To connect to a local host, use F_ApiStartUp() or F_ApiWinConnectSession().

To connect to a remote host, use F_ApiWinConnectSession(). For information about connecting to FrameMaker processes, see "Connecting with a FrameMaker

process". For information about the functions to connect to FrameMaker processes, see

F_ApiWinConnectSession() and F_ApiStartUp() in the FDK Programmer’s Reference guide.

2. Depending on your client, wait for requests from FrameMaker or perform some

operations using FrameMaker.

Once connected to a running FrameMaker process, your client can use the FDK to control the FrameMaker process, or receive notifications from it. However, bear in mind that console programs cannot handle notifications from the FDK. (This is because console programs do not have a Windows message processing loop; applications running in console programs must not request notifications.)

50 FDK Programmer’s Guide

Getting Started with FDK

Writing an Asynchronous FDK Client

Note that a client can take exclusive control of the FrameMaker process by requesting notification for FA_Note_ClientCall and then calling itself via F_ApiCallClient().

While handling the notification, no other clients can take control of the FrameMaker process.

3. When done, disconnect from the FrameMaker process.

How your client disconnects depends on the situation. With a client that is a plugin for FrameMaker, you can call F_ApiBailOut() to terminate the client. After calling F_ApiBailOut(), the client’s notification points are still registered with the FrameMaker process. If a notification event occurs, the FrameMaker process restarts the client by calling F_ApiInitialize() with initialization set to FA_Init_Subsequent. When it starts up subsequently, the client’s global variable settings are lost.

If the FrameMaker process still exists when your client is completely done communicating with it, your client should call the function F_ApiDisconnectFromSession() to break the RPC connection.

Alternatively, the FrameMaker process may have shut down when your client wants to break the connection (for example, due to a user request or due to a command from your client). If so, your client should call the function F_ApiShutDown() to close its side of the RPC connection.

. . .

FDK Programmer’s Guide 51

Getting Started with FDK

Writing an Asynchronous FDK Client

Writing a Main routine in Windows.

Windows does not provide a default main routine for remote plugins. You must provide your own main routine. Simply include the following lines in your client:

#define DONT_REDEFINE /* We need to use native types. */ #include ‘fapi.h’ #include <windows.h> int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,

LPSTR lpCmdLine, int nCmdShow) { return F_ApiRun(); } The routine F_ApiRun() is documented in the FDK manuals and is

implemented as follows: IntT F_ApiRun(VoidT) {

ConStringT s = F_ApiStartUp(NULL); if (s)

F_ApiErr(s);

else

while (!FA_bailout)

F_ApiService(NULL); F_ApiShutDown();

return s !=NULL;

}

52 FDK Programmer’s Guide

F_ApiStartup() and F_ApiService() ignore their parameters and should be passed NULL.

It is not necessary to call F_ApiRun(). You may choose to implement your main routine using these primitives directly. If your program has a windows message loop you need only call F_ApiStartup(NULL).

However if your remote plugin does not call F_ApiRun(), it must either periodically check the FA_bailout flag or arrange to terminate based on the FA_NotePostQuitSession notification. You must make these checks, otherwise FrameMaker can terminate leaving your client running.

Getting Started with FDK

Writing an Asynchronous FDK Client

Compiling and running a sample client

The following code sample is a console application that connects to the default FrameMaker session and gets the name of the active FrameMaker document. Following the code is a lineby-line description of how it works.

1. #define DONT_REDEFINE // Console app needs native types

2. #define WBUFLEN 512

4. #include "fdetypes.h"

5. #include "futils.h"

6. #include "fapi.h"

7. #include "fstrings.h"

8. #include <windows.h>

9. #include <ddeml.h> //not required

10. #include <stdarg.h> //not required

11.

12. int main(int argc, char **argv)

13. {

14. StringT opt_progid;

15. CLSID pclsid;

16. LPOLESTR progStr;

17. HRESULT res;

18. F_ObjHandleT docId;

19.

20. // Get the process name.

21. if(argc == 2)

22. opt_progid = F_StrCopyString((StringT)argv[1]);

23. else {

24. fprintf(stderr, "You must provide a process name.");

25. return(1);

26. }

27.

28. // Convert the process name into a GUID

29. progStr = (OLECHAR*)malloc( WBUFLEN*sizeof(wchar_t) );

30. if(0 == MultiByteToWideChar(CP_ACP, 0,

(char *)opt_progid, -1, 31. progStr, WBUFLEN )) {

32. fprintf(stderr, "failed to allocate\n");

. . .

FDK Programmer’s Guide 53

Getting Started with FDK

Writing an Asynchronous FDK Client

33. return(1);

34. }

35. if (progStr[0] == '{') // hex-codes within brackets

36. res = CLSIDFromString(progStr, &pclsid);

37. else

38. res = CLSIDFromProgID(progStr, &pclsid);

39.

40. if(res == S_OK)

41. F_ApiWinConnectSession(NULL, NULL, &pclsid);

42. if (!F_ApiAlive()) {

43. fprintf(stderr, "No connection: %s\n", opt_progid);

44. return 1;

45. }

46. // Print the name of the current document.

47. docId = F_ApiGetId(0, FV_SessionId, FP_ActiveDoc);

48. if (docId) {

49. StringT docname = F_ApiGetString(FO_Session, docId,

FP_Name);

50. fprintf(stderr, "Current document: %s\n", docname);

51. F_ApiDeallocateString(&docname);

52. } else

53. fprintf(stderr, "No active document\n");

54.

55. return 0;

56. }

54 FDK Programmer’s Guide

Line 1

To compile this client as a console application, you need to use types that are native to the C language. This statement keeps the FDE from redefining those types.

Lines 20–26

These lines parse the commandline options you pass to the client when you invoke it. You invoke the exe with the name of a FrameMaker process as an argument. To run the default process, use the name FrameMaker.API.1. For example, assuming the exe is named fmRemote.exe, type the following to invoke it with the default FrameMaker process: fmRemote.exe FrameMaker.API.1

For more information, see "Registering a name for a FrameMaker process"

Getting Started with FDK

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

Writing an Asynchronous FDK Client

Lines 28–38

These lines convert the process name into a valid GUID. Note that you need a Unicode string for the process name. The code uses the Win32 API call, ultiByteToWideChar() to convert the process name to Unicode. It then uses the Win32 API functions CLSIDFromProgID() or CLSIDFromString() to get the GUID for the specified process.

Lines 40–45

If you successfully retrieve a GUID for the process, these lines make the connection to a FrameMaker session.

Lines 46–56

Now that the client has connected with a session, it can use the FDK to interact with that session. These lines are standard FDK code to get the name of the active document for the current session. You can add code to perform other actions such as adding menus to the application window, manipulating the active document, or anything else you can do via the FDK.

. . .

IMPORTANT: Because they don’t have a Windows mes sage processing loop, co nso l e

applications cannot handle notifications from the FDK, such as menu commands or notifications such as FA_Note_PreSaveDoc.

Compiling and registering the sample client

To compile the sample client in Microsoft Visual Studio 2010, follow these steps:

1. Create a project for a console application.

Use the Project Wizard to create a new project for a console application.

2. Set up the project options and settings as described in "Compiling, Registering, and

Running FDK Clients".

IMPORTANT: Your link settings must include fdk.lib and api.lib. but neither

fmdbms32.lib nor fmdebug.lib. In previous versions of the FDK, fmdbms32.lib and fmdebug.lib were requir ed to compile. These libraries ar e now obsolete, but we include them so you don’t have to change the link settings to compile existing FDK projects. If a remote client fails to start up and you see these libraries mentioned in the error text, then you must remove them from your link settings and recompile.

Compile the client.

FDK Programmer’s Guide 55

Getting Started with FDK

Writing an Asynchronous FDK Client

4. Register the client

There are three ways to register an asynchronous client. See "Registering asychronous

clients".

You must also be sure the end user has a correct installation to run asynchronous clients. See "End user installations"

5. Connect the client with a named FrameMaker process.

To connect with a named FrameMaker process:

– On your machine, register the FrameMaker process as a server. See "Registering

multiple FrameMaker processes as servers". Be sure to register it with a name. See "Registering a name for a FrameMaker process"

– In a command window, type the filename for the client, followed with the name of the FrameMaker process the argument.

– To connect to the default FrameMaker process, use the process name, FrameMaker.API.1.

For example, type remote.exe process_name, where process_name is the name you assigned to a FrameMaker process. Note that unlss you registered the process to start up automatically, that process must be running when you invoke the sample client.

56 FDK Programmer’s Guide

Summary of supporting functionality

To support communication with a FrameMaker process, the FDK provides the following functions:

Function Purpose

F_ApiWinConnectSession() Initiates communication between the calling

process and an identified FrameMaker process

F_ApiDisconnectFromSession() Severs communication with a FrameMaker

F_ApiSetClientDir() Identifies a directory the FrameMaker process

F_ApiShutDown() Closes a client’s connection with the API F_ApiWinInstallDefaultMessag

eFilter() F_ApiService() useful if you are providing a replacement for

F_ApiStartup() See the description after the table

process

associates with an unregistered client

Registers the default FDK message filter for a COM session.

F_ApiRun().

Function Purpose

F_ApiAlive() F_ApiErr(message) Prints client name and message to console. F_ApiRun provides the minimum functionality required in

Using F_ApiStartup(F_FdFuncT) the F_FdFuncT argument is ignored because Windows RPC is not based on sockets. F_ApiStartup queries the application’s ersion information for client configuration data, if present, and connects to FrameMaker.

For information on these functions and properties, see the FDK Programmer’s Reference guide.

Example: adding menus and commands

The following code adds a menu named “Database” to the Special menu. The menu has two commands “Load Database” and “Query Database”.

Getting Started with FDK

Example: adding menus and commands

an FDK client’s

main() function

. . .

FDK Programmer’s Guide 57

Getting Started with FDK

Example: adding menus and commands

When the user selects either of the commands, a prompt is displayed.

#include "fapi.h"

#define LOAD 1 #define QUERY 2 VoidT F_ApiInitialize(initialization) IntT initialization; { F_ObjHandleT specialMenuId, databaseMenuId; /* Get the ID of the special menu. */ specialMenuId = F_ApiGetNamedObject(FV_SessionId, FO_Menu, "SpecialMenu"); /* Define the menu and add it to the Edit menu. */ databaseMenuId = F_ApiDefineAndAddMenu(specialMenuId,

"DatabaseMenu", "Database"); /* Define the commands and add them to the Special menu. */ F_ApiDefineAndAddCommand(LOAD, databaseMenuId, "LoadDatabase", "Load Database","\\!LD"); F_ApiDefineAndAddCommand(QUERY, databaseMenuId, "QueryDatabase", "Query Database", "\\!QD"); } VoidT F_ApiCommand(command) IntT command; { switch(command) { case LOAD: /* Code to load database goes here. */

F_ApiAlert((ConStringT)"Load Command Executed!!\n" ,

58 FDK Programmer’s Guide

Next Steps

Getting Started with FDK

Next Steps

. . .

FF_ALERT_CONTINUE_NOTE); break; case QUERY: /* Code to query database goes here. */

F_ApiAlert((ConStringT)"Query Command Executed!!\n" ,

FF_ALERT_CONTINUE_NOTE); break; } }

By now, you would have become familiar with the basic operations of the FDK. Here are the suggested next steps that will help you use the FDK more effectively:

 Study the Programmer’s Guide to understand the detailed flow and usage model  Review the samples provided (available in the samples folder of the FDK

installation) and write your own program modeled on them.

 Refer to the FDK Programmer’s Reference for details of syntax and examples

FDK Programmer’s Guide 59

Getting Started with FDK

Next Steps

60 FDK Programmer’s Guide

PART II

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

Frame Product Architecture

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

This chapter discusses the general organization of FrameMaker product sessions from a programmer’s perspective. It provides useful background information for programmers who want to use the Frame API.

Identifying objects

The API assigns a unique ID to each object. Most API functions that manipulate objects require you to specify this ID. An object’s ID is valid only as long as the object is available in the current FrameMaker product session. For example, suppose you have a document with a rectangle drawn in it. When you open the document, the API assigns an ID to the FO_Rectangle object that represents the rectangle. As long as the document is open, the ID of the FO_Rectangle object remains the same. However, if you exit the document and then reopen it, the API may assign a new ID to the rectangle.

In addition to IDs, there are two types of identifiers that are persistent between sessions:

11 Frame Session Architecture

. . . . .

 Unique object names

 Unique persistent identifiers (UIDs)

Each object generally has either an FP_Name property specifying a unique object name or an FP_Unique property specifying a UID.

Unique object names

There are many types of objects that you can assign unique names to in the user interface. These objects, which are called named objects, include:

 FO_Book  FO_CharFmt  FO_Color  FO_CombinedFontDfn  FO_Command  FO_CondFmt

FDK Programmer’s Guide 63

Frame Session Architecture

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

Identifying objects

 FO_ElementDef  FO_FmtChangeList  FO_MarkerType  FO_MasterPage  FO_Menu  FO_MenuItemSeparator  FO_PgfFmt  FO_RefPage  FO_RulingFmt  FO_TiFlow  FO_TiText  FO_TblFmt  FO_UnanchoredFrame (named frames on reference pages only)  FO_VarFmt  FO_XRefFmt

The API provides a function named F_ApiGetNamedObject(), which gets the ID of a named object with a specified name.

IMPORTANT: A document can contain several flows with the same name. For example,

a document can contain several A flows. To get the ID of a specific flow, fir st get the ID of a text frame in that flow, for example, the text frame for the current text location, and then query the text frame’s FP_Flow property.

Unique persistent identifiers (UIDs)

The API and MIF identify unnamed objects with UIDs. An unnamed object is an object that doesn’t have a unique name. For example, FO_Pgf objects are unnamed.

UIDs are unique within documents. An object’s UID remains the same as long as the object is in the same document. The API provides a function named

F_ApiGetUniqueObject

IMPORTANT: If you copy an object an d then pa ste it, the Fram eMaker product

considers the pasted object a new object and assigns a new UID to it. This is also true true for a paragraph that is conditionalized. If the entire paragraph is of a given

(), which gets an object’s ID from its UID.

64 FDK Programmer’s Guide

Representing object characteristics with properties

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

condition, and that condition is hidden and then shown, the paragraph will have a new UID.

Representing object characteristics with properties

Each object has a property list, or set of properties that represent its characteristics. Each property has a value associated with it. For example, if a paragraph has two tabs, the value of its FP_NumTabs property is 2. A property value can be more than an integer. It can also be a string, a pointer to a structure that contains a set of strings, or a variety of other things. The following table summarizes the different data types property values can be.

Property data type What the property value represents

Frame Session Architecture

. . .

IntT An integer, enum, boolean, or ordinal value. For many

F_IntsT A set of integers or a set of IDs. F_UIntsT A set of unsigned integers. MetricT A measurement value. F_MetricsT A set of metrics. StringT A character string. F_StringsT A set of character strings. F_ObjHandleT The ID of another object. F_PointsT A set of x-y coordinate pairs. F_TabsT A set of tab descriptions. F_TextLocT A point (location) in text. F_TextRangeT A range or selection of text. F_ElementCatalogEntriesT The list of elements in the Element Catalog. F_AttributeDefsT An set of attribute definitions. F_AttributesT An set of attributes. F_ElementRangeT An element selection.

IntT properties, the API provides defined constants, such as True and False.

FDK Programmer’s Guide 65

Frame Session Architecture

Representing object characteristics with properties

The API uses MetricT data to express measurement values. This manual uses constants to represent conventional measurement system units as MetricT data. For example, the constant in represents an inch and the constant pts represents a point in MetricT units, for example 5 inches (5* 4718592) are represented as 5*in.

For more information on the MetricT type and other data types and data structures listed in the table above, see chapter, “Data Types and Structures Reference,” of the FDK Programmer’s Reference.

Many property values are pointers to data structures. For example, FO_Doc

objects

have a property named FP_Dictionary that specifies words that the Spelling Checker will permit in a document. FP_Dictionary is an FT_Strings property. Its value is a pointer to an F_StringsT structure, which is defined as:

typedef struct {

UIntT len; /* Number of permitted words */ StringT *val; /* Vector of permitted words */

} F_StringsT;

Property lists

At the highest level, the API represents each object’s property list with a F_PropValsT structure. The F_PropValsT structure is defined as:

typedef struct {

UIntT len; /* Number of properties in list */ F_PropValT *val; /* Property-value pairs */

} F_PropValsT;

The F_PropValT structure, which provides an individual property-value pair, is defined as:

typedef struct {

F_PropIdentT propIdent; /* The property identifier */ F_TypedValT propVal; /* The property value */

} F_PropValT;

66 FDK Programmer’s Guide

The F_PropIdentT structure, which identifies a property by either its property number constant (one of the constants beginning with FP_) or a property name, is defined as:

typedef struct {

IntT num; /* The property number constant */ StringT name; /* The property name */

} F_PropIdentT;

Most properties are identified by property number constants. Only inset facets, a special type of properties, are identified by names. For information on insets, see Chapter 12,

Frame Session Architecture

Representing object characteristics with properties

“Using Imported Files and Insets.” If a property is identified by a name, F_PropIdentT.num is

The F_TypedValT structure is defined as:

typedef struct {

IntT valType; /* The type of value. See table below */ union {

StringT sval; /* String value */ F_StringsT ssval; /* Set of strings */ F_MetricsT msval; /* Set of metrics */ F_PointsT psval; /* Set of points */ F_TabsT tsval; /* Set of tabs */ F_TextLocT tlval; /* Text location */ F_TextRangeT trval; /* Text range */ F_ElementCatalogEntriesT csval; /* Element Catalog */ F_AttributeDefsT adsval; /* Attribute definitions */ F_AttributesT asval; /* Attribute values */ F_ElementRangeT *erng; /* Element range */ F_IntsT isval; /* Set of integers */ F_UIntsT uisval; /* Set of unsigned integers */ IntT ival; /* Integer */

} u;

} F_TypedValT;

. . .

The constants used in the valType field are described in the following table.

valType constant Property data type u field

FT_Integer IntT ival FT_Ints F_IntsT isval FT_Metric MetricT ival FT_Metrics F_MetricsT msval FT_String StringT sval FT_Strings F_StringsT ssval FT_Id F_ObjHandleT ival FT_Points F_PointsT psval FT_Tabs F_TabsT tsval FT_TextLoc F_TextLocT tlval FT_TextRange F_TextRangeT trval

FDK Programmer’s Guide 67

Frame Session Architecture

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

Representing object characteristics with properties

valType constant Property data type u field

FT_UInts F_UIntsT uisval FT_UBytes F_UBytesT No field FT_ElementCatalog F_ElementCatalogEntriesT csval FT_AttributeDefs F_AttributeDefsT adsval FT_Attributes F_AttributesT asval FT_ElementRange F_ElementRangeT erng

IMPORTANT: Integer (IntT), metric (MetricT), and ID (F_ObjHandleT) values are

all put in the ival field of the u union.

Example

Suppose the user creates a paragraph format named Heading, which has a 1-inch left indent and has Keep With Next Paragraph turned on. The API represents this paragraph format with an FO_PgfFmt object. The following are some of the object’s properties and their values.

68 FDK Programmer’s Guide

Property Data type Value

FP_Name StringT Heading FP_KeepWithNext IntT True FP_LeftIndent MetricT 1*in

Frame Session Architecture

len: 3 val:

F_PropValsT

val[0]

propIdent

propVal

num: FP_Name name: NULL

valType: FT_String

sval: Heading

val[1]

propIdent

propVal

num: FP_KeepWithNext name: NULL

valType: FT_Integer

ival: True

val[2]

propIdent

propVal

num: FP_LeftIndent name: NULL

valType: FT_Metric

ival: 1*in

FrameMaker product sessions

The property list for the FO_PgfFmt object and the properties in the previous table are represented graphically in Figure 1-1. FO_PgfFmt objects have many other properties that are not shown in the illustration.

. . .

Figure 1-1 Some FO_PgfFmt properties

FrameMaker product sessions

The fundamental entity in Frame architecture is a session. Each instance of a FrameMaker product that the user starts is a session. FrameMaker allows the user to have many open documents and books in a session.

Of the open documents and books in a session, only one document or book is active at a time. An open document or book is active if it has the input focus.

FDK Programmer’s Guide 69

Frame Session Architecture

FrameMaker product sessions

How the API represents sessions

The API represents each FrameMaker product session with an FO_Session object, whose properties provide the following categories of information about the session:

 System information, such as the operating system, the current FrameMaker product

version, and the current directory

 The automatic save settings

 Names of fonts available on the system  IDs of the objects that represent open and active documents and books

 Whether the FrameMaker product reformats and redisplays documents after changes

have been made

 Whether element reformatting and validation is turned on (for FrameMaker

structured documents)

Suppose you start FrameMaker on a Window System platform and open a document named mydoc. The API represents this session with an FO_Session object. The following are some of its properties.

Property Type Value

FP_ProductName FT_String FrameMaker FP_VersionMajor FT_Integer 5 FP_WindowSystem FT_String Windows FP_AutoSaveSeconds FT_Integer 300 FP_ActiveDoc FT_Id ID of the object that represents mydoc

How the API indicates which documents and books are open

The API represents a document with an FO_Doc object. The API maintains a linked list of the FO_Doc objects that represent a session’s open documents. The FO_Session property, FP_FirstOpenDoc, specifies the ID of the first FO_Doc object in the list. The FO_Doc property, FP_NextOpenDocInSession, specifies the ID of the next FO_Doc object in the list. The list of FO_Doc objects that represent open documents is not in any particular order. The FO_Doc object specified by FP_FirstOpenDoc does not necessarily represent the first document the user opened.

70 FDK Programmer’s Guide

Frame Session Architecture

FrameMaker product sessions

The API represents a book with an FO_Book object. The API also maintains the FO_Book objects that represent the session’s open books in a linked list. The FO_Session property, FP_FirstOpenBook, specifies the ID of the first FO_Book object in the list. The FO_Book property,

FP_NextOpenBookInSession

with the list of FO_Doc objects, the linked list of FO_Book objects is not in any particular order.

How the API indicates which document or book is active

FO_Session has two properties, FP_ActiveDoc and FP_ActiveBook, that specify the IDs of the objects that represent the active document and the active book. Only one document or one book can be active at a time. If there is no active document or book, these properties are set to 0. Invisible documents and books can’t be active.

Example

Suppose you start FrameMaker and open the books and documents shown in Figure 1-2. The Frame API represents the session with the objects shown in Figure 1-3.

, specifies the next FO_Book object in the list. As

. . .

Figure 1-2 A FrameMaker\session with open documents and books

FDK Programmer’s Guide 71

Frame Session Architecture

FO_Session

FO_Book

(Manual.book)

FO_Book

(Manual2.book)

FP_FirstOpenBook

FO_Doc

(2Chapter)

FO_Doc

(1Chapter)

FP_FirstOpenDoc

FP_ActiveDoc

FP_NextOpenDocInSession

FP_NextOpenBookInSession

FrameMaker product sessions

Figure 1-3 API representation of a session with open documents and books

Although Manual.book is iconified, the API still considers it open. Although FP_FirstOpenDoc specifies

2Chapter, it is not necessarily the first document that

was opened.

How the API indicates which fonts are available in a session

The following FO_Session properties specify which fonts are available in the current session:

 FP_FontFamilyNames specifies the available families, for example, Helvetica

and Times.

 FP_FontVariationNames specifies the available variations, for example,

Narrow and Oblique.

 FP_FontWeightNames specifies the available weights, for example, Bold and

Regular.

 FP_FontAngleNames specifies the available angles, for example, Italic and

Regular.

72 FDK Programmer’s Guide

Frame Session Architecture

FrameMaker product sessions

The FP_FontFamilyNames, FP_FontVariationNames, FP_FontWeightNames, and FP_FontAngleNames properties determine which

choices appear in the Family, Weight, Angle, and Variation fields of the Character Designer and Paragraph Designer, and the pull-right menu items in the Format menu. Each of the properties specifies an F_StringsT structure, which is defined as:

typedef struct {

UIntT len; /* Number of strings */ StringT *val; /* Font names */

} F_StringsT;

For example, if Courier, Helvetica, and Times are the only font families available in the current session, the fields of the F_StringsT structure specified by

FP_FontFamilyNames have the following values:

len: 4 val: {"<Reserved>","Courier","Helvetica","Times"}

Properties that specify font families, angles, weights, and variations use the index of the val array. For example, the FO_CharFmt property, FP_FontFamily, specifies the

font family for a character format. Given the F_StringsT values shown above, if the font family for a character format is Helvetica, the value of the format’s FP_FontFamily property is 2.

. . .

Although a specific angle, weight, or variation may be in one of the lists described above, it may not be available for all combinations of font families, angles, weights, and variations. For example, the Bold weight may be available for Times and Helvetica, but not for Zapf Chancery. The FDK provides a convenience function named F_ApiFamilyFonts(), which returns all the permutations of font families, angles, weights, and variations in a FrameMaker product session. For more information, see “F_ApiFamilyFonts()” in the FDK Programmer’s Reference guide.

FDK Programmer’s Guide 73

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

This chapter describes Frame documents and their components and shows how the Frame API represents them.

Documents

A document is a set of pages with graphic objects and text that the user creates with a FrameMaker product and stores in a file.

What the user sees

When you create a new document, you can use a template to create it, or you can create a custom document. Any document can be a template. Because the FrameMaker product copies everything from a template to a new document, most users prefer to use templates containing only layout and formatting information. FrameMaker provides ready-made templates for a variety of document types.

22 Frame Document Architecture

. . . . .

You can’t create a document completely from scratch—the document must have a certain set of default objects for the FrameMaker product to work correctly. To ensure that all documents have this set of objects, the FrameMaker product always uses a template to create a new document. Even if you choose the Custom document option, the FrameMaker product creates the new document from a default template. This custom document template is specified in the maker.ini file.

FDK Programmer’s Guide 75

Frame Document Architecture

Documents

When the user attempts to create a new document from an ASCII text file or a MIF file that doesn’t provide the necessary objects, FrameMaker uses the ASCII template specified in the maker.ini file.

When you instruct FrameMaker to save a document, it lists the document’s objects and their properties in a file. By default, FrameMaker writes the information to a Frame binary format file. You can also choose to save a document as a MIF file.

How the API represents documents

A document actually consists of much more than text and graphic objects. It includes information specifying a variety of other things, such as formatting, user preferences, and the FrameMaker product’s default behavior. The API represents the information in a document with a set of objects. The following table summarizes the information a document can contain and the objects the API uses to represent it.

Type of information Function

Global document information

Pages Organize text and graphic objects in

Graphic objects Describe graphic objects in the

Specifies the document’s general characteristics, some aspects of the FrameMaker product’s behavior when the document has input focus, and IDs of other objects that constitute the document

the document

document

Types of objects that represent it

FO_Doc

FO_BodyPage FO_MasterPage FO_RefPage FO_HiddenPage

FO_UnanchoredFrame FO_AFrame FO_Group FO_Arc FO_Rectangle FO_Ellipse FO_RoundRect FO_Polyline FO_Polygon FO_Line FO_TextLine FO_TextFrame FO_Inset FO_Math

76 FDK Programmer’s Guide

Text columns Contain text FO_SubCol

Text frames Contain text FO_TextFrame

Type of information Function

Frame Document Architecture

Documents

. . .

Types of objects that represent it

Text flows Specify how text frames in the

document are linked

Paragraph Catalog formats

Paragraphs Contain the document’s text and

Character Catalog formats

Condition formats Specify tags that the user can apply to

Markers Describe placeholders that contain

Marker types Specifies a named catagory of markers FO_MarkerType

Cross-reference formats

Cross-reference instances

Variable formats Specify units of text and system-

Specify tags that the user can apply to a paragraph to change its formatting

provide formatting information for individual paragraphs

Specify tags that the user can apply to a selection of characters to change its formatting

text to indicate that it belongs to a particular variation of the document

hidden text

Specify the wording and typographic style of cross-references

Describe instances of cross-references in the document

supplied information that the user can use multiple times in a document

FO_Flow

FO_PgfFmt

FO_Pgf

FO_CharFmt

FO_CondFmt

FO_Marker

FO_XRefFmt

FO_XRef

FO_VarFmt

Variable instances Describe instances of variables in the

Footnotes Describe footnotes FO_Fn

Table ruling formats Specify rulings and shadings that the

Table Catalog formats

Tables Describe instances of tables in the

Colors Specify colors that the user can apply

document

user can apply to individual table cells

Specify table formats that the user can apply to a table and that provide default numbers of columns and rows for new tables

document and specify formatting information, such as alignment, ruling, and shading

to graphic objects and text

FO_Var

FO_RulingFmt

FO_TblFmt

FO_Tbl FO_Row FO_Cell

FO_Color

FDK Programmer’s Guide 77

Frame Document Architecture

Documents

Type of information Function

Types of objects that represent it

Text insets Describe text that is imported by

reference

FO_TiApiClient FO_TiFlow FO_TiText FO_TiTextTable

Structural element definitions

Specify tags that specify the organization of parts of a structured

FO_ElementDef

document

Structural element instances

Describe instances of structural elements in a structured document

FO_Element

Format rules Specify sets of format rule clauses FO_FmtRule

Format rule clauses Specify which formats to apply to

FO_FmtRuleClause

elements in various contexts

Format change list Specify format changes applied to an

FO_FmtChangeList

element in a specific context

Rubi composites Describe the oyamoji (base word) and

FO_Rubi

rubi (phonetic spelling) of certain words in Asian text

Combined font definitions

Describe pairs of Asian and Western fonts that are treated as a single font

FO_CombinedFontDfn

family

The other sections of this chapter discuss the different types of information in a document.

78 FDK Programmer’s Guide

Frame Document Architecture

Documents

How the API organizes the objects that constitute a document

The API uses an FO_Doc object to organize the objects that constitute a document. FO_Doc objects have a number of properties that specify the IDs of other objects in the document. Many of these properties specify the ID of the first object in a linked list of objects. For example, FP_FirstPgfFmtInDoc specifies the first FO_PgfFmt object (Paragraph Catalog format) in the list of FO_PgfFmt objects in the document. Each FO_PgfFmt object has a FP_NextPgfFmtInDoc property that specifies the next FO_PgfFmt object in the list. If you want to get all the FO_PgfFmt objects in a document, you get the FO_PgfFmt object specified by FP_FirstPgfFmtInDoc and traverse the links to the other objects.

Document object property Object that the property specifies

FP_FirstGraphicInDoc The first graphic object (for example,

FO_UnanchoredFrame

list of graphic objects

or FO_Line) in the

. . .

FP_FirstColorInDoc The first

objects

FP_FirstPgfInDoc The first FO_Pgf in the list of FO_Pgf objects

FP_FirstMarkerInDoc The first FO_Marker in the list of

FO_Marker

FP_FirstMarkerTypeInDoc The first FO_MarkerType, in the list of marker

types

FP_FirstVarInDoc The first

FP_FirstVarFmtInDoc The first FO_VarFmt in the list of

FO_VarFmt

FP_FirstXRefInDoc The first FO_XRef in the list of FO_XRef

objects

FP_FirstXRefFmtInDoc The first FO_XRefFmt in the list of

FO_XRefFmt

FP_FirstFnInDoc The first FO_Fn in the list of FO_Fn objects

FP_FirstTblInDoc The first FO_Tbl in the list of FO_Tbl objects

FP_FirstFlowInDoc The first FO_Flow in the list of FO_Flow

objects

FP_FirstPgfFmtInDoc The first FO_PgfFmt in the list of

FO_PgfFmt

FO_Color in the list of FO_Color

objects

FO_Var in the list of FO_Var objects

objects

FP_FirstCharFmtInDoc The first FO_CharFmt in the list of

FO_CharFmt

objects

FDK Programmer’s Guide 79

Frame Document Architecture

Documents

Document object property Object that the property specifies

FP_FirstCondFmtInDoc The first FO_CondFmt in the list of

FO_CondFmt

FP_FirstTblFmtInDoc The first FO_TblFmt in the list of

FO_TblFmt

objects

FP_FirstRulingFmtInDoc The first FO_RulingFmt in the list of

FO_RulingFmt objects

FP_FirstSelectedGraphicInDoc The first graphic object in the list of selected

graphic objects

FP_MainFlowInDoc

FP_FirstElementDefInDoc First structural element definition in the list of

FP_FirstFmtChangeListInDoc First format change list in the list of format change

FP_FirstBodyPageInDoc or FP_LastBodyPageInDoc

FP_FirstMasterPageInDoc or

FP_LastMasterPageInDoc

FP_FirstRefPageInDoc or FP_LastRefPageInDoc

FP_HiddenPage The hidden page (FO_HiddenPage)

FP_SelectedTbl The selected table object

FP_FirstTiInDoc The first FO_TiApiClient, FO_TiFlow,

FP_FirstRubiInDoc The first

FO_Flow that represents the main flow

element definitions in a FrameMaker document

lists in a document

The first or last FO_BodyPage in the list of

FO_BodyPage

The first or last FO_MasterPage in the list of

FO_MasterPage

The first or last FO_RefPage in the list of

objects

FO_RefPage objects

FO_TiText

of text insets

, or FO_TiTextTable in the list

FO_Rubi in the list of rubi composites

80 FDK Programmer’s Guide

FP_FirstCombinedFontDfnInDoc The first FO_CombinedFontDfn in the list of

combined font definitions

FP_FirstBodyPageInDoc, FP_FirstMasterPageInDoc, and FP_FirstRefPageInDoc point to the lists of pages in a document. These lists are

ordered to reflect the order of the pages. All other lists (including the list of FO_Pgf objects) are not ordered. The terms first and last indicate only the position of the objects in an arbitrarily ordered list. There is no guarantee that a more recently added object will come later in a list, nor is there a guarantee that the order of a list will remain the same as the document is modified.

Global document information

FrameMaker products allow you to set global document information, characteristics that apply generally to an entire document.

What the user sees

Global document information includes the following formatting characteristics:

 Document page properties, which specify the document’s page numbering and

pagination style

 Document condition properties, which specify whether conditional text appears and

whether formatting associated with condition tags overrides other formatting

 Document and table footnote properties, which specify the appearance of the

footnotes, such as the footnote numbering and the default paragraph format

 Change bar properties, which specify the appearance and position of change bars in

the document

 The current text selection or insertion point

Frame Document Architecture

Global document information

. . .

There is also global document information that affects how the FrameMaker product behaves when the document is active. This type of global information includes:

 The document dictionary, which lists words that you want the FrameMaker product

Spelling Checker to ignore

 Type-in properties, which specify whether Smart Spaces or Smart Quotes is enabled

 Equation properties, which specify default symbol sizes and fonts the FrameMaker

product uses when you add equations to the document

 Printing properties, which specify the defaults that appear in the Print dialog box,

such as the printer name and the range of pages to print

 View properties, which specify how FrameMaker displays and scrolls the document

in the window

 Structure properties, which specify whether element boundaries appear and how the

Element Catalog appears for a structured document in a session.

FrameMaker saves most of the global document information with each document. For example, if you set the zoom for a document to 140 percent and save and exit a document, the next time you open the document, the zoom will be set to 140 percent.

FDK Programmer’s Guide 81

Frame Document Architecture

Global document information

How the API represents global document information

The Frame API represents global document information with FO_Doc object properties.

How the API represents the selection in a document

The API uses several properties to specify what is selected in a document:

 FP_TextSelection specifies a structure that provides the location of the insertion

point or the beginning and end of a text selection.

 FP_FirstSelectedGraphicInDoc specifies the ID of the first graphic in the list

of selected graphics in a document.

 FP_SelectedTbl specifies the ID of a table that contains the insertion point or

some selected cells.

 FP_ElementSelection specifies the range of elements selected if the document

is a structured document in a session.

The following table summarizes the different types of selection in an unstructured document and how these properties are set to represent them.

Selection state How selection properties are set

No object is selected. There is no text selection or insertion point.

FP_TextSelection specifies an F_TextRangeT

structure for which the objId and offset fields of

F_TextRangeT.beg

and F_TextRangeT.end are set to

0. FP_FirstSelectedGraphicInDoc is 0. FP_SelectedTbl is 0.

One or more graphic objects are selected.

FP_TextSelection specifies an F_TextRangeT

structure for which the objId and offset fields of

F_TextRangeT.beg and F_TextRangeT.end are set to 0

FP_FirstSelectedGraphicInDoc specifies the ID of

the first selected graphic in the document’s list of selected graphics.

FP_SelectedTbl is 0.

There is an insertion point or text selection (that isn’t in a table cell, but may include table anchors).

FP_TextSelection specifies the location of the text

selection or insertion point

FP_FirstSelectedGraphicInDoc is 0. FP_SelectedTbl is 0.

82 FDK Programmer’s Guide

Frame Document Architecture

Selection state How selection properties are set

Global document information

. . .

There is an insertion point or text selection within a single table cell.

FP_TextSelection specifies the location of the text

selection or insertion point within the cell; for example, the ID of the paragraph containing the insertion point, and the offset within that paragraph.

FP_FirstSelectedGraphicInDoc is 0. FP_SelectedTbl

cell. If the current selection is in a paragraph, the paragraph´s

FP_InTextObj property specifies the ID of the cell that

contains the selection. The cell’s specifies the column number, and the cell’s property specifies the ID of its row.

An entire cell or set of cells is selected.

FP_TextSelection specifies an F_TextRangeT

structure for which the objId and offset fields of

F_TextRangeT.beg 0

FP_FirstSelectedGraphicInDoc is 0. FP_SelectedTbl specifies the ID of the table containing the

cell. The table properties

FP_BottomRowSelection

last rows containing selected cells. The

FP_RightColNum

numbers of the outermost columns in the selection.

a. If an entire cell is selected, there is no text selection.

specifies the ID of the table containing the

FP_CellColNum property

FP_CellRow

and F_TextRangeT.end are set to

FP_TopRowSelection and

specify the IDs of the first and

FP_LeftColNum and

properties of the table specify the index

How the API represents the element selection in a structured FrameMaker document

In a structured FrameMaker document, the selection properties described in the previous section behave as they would in an unstructured document. However, structured FrameMaker documents have an additional selection property, FP_ElementSelection, which specifies the selection in terms of the selected element range or F_ElementRangeT structure.

The F_ElementRangeT structure is defined as:

typedef struct {

F_ElementLocT beg; /* Beginning of the element range. */ F_ElementLocT end; /* End of the element range. */

} F_ElementRangeT;

FDK Programmer’s Guide 83

Frame Document Architecture

Global document information

The F_ElementLocT structure specifies a location within an element. It is defined as:

typedef struct {

F_ObjHandleT parentId; /* Parent element ID. */ F_ObjHandleT childId; /* Child element ID. */ IntT offset; /* Offset within child/parent element. */

} F_ElementLocT;

The following table summarizes the different types of selection in a structured FrameMaker document and how the fields of the F_ElementRangeT structure specified by the FP_ElementSelection property are set to represent them.

Selection state What the fields of the F_ElementRangeT structure specify

No object is selected. There is no text selection or insertion point.

One or more graphic objects are selected.

There is an insertion point or text selection within an element that has no subelements.

beg.parentId: 0 beg.childId beg.offset end.parentId end.childId end.offset

: 0

beg.parentId: ID of the element containing the insertion

point or selection

beg.childId: ID of the child element immediately following

the insertion point or the beginning of the text selection

beg.offset: offset of the beginning of the selection or

insertion point from the beginning of the element containing it

end.parentId: ID of the element containing the insertion

point or selection

end.childId: ID of the child element immediately following

the insertion point or the end of the text selection

end.offset: offset of the end of the selection or insertion point

from the beginning of the element containing it

84 FDK Programmer’s Guide

Frame Document Architecture

Global document information

Selection state What the fields of the F_ElementRangeT structure specify

. . .

An entire element or range of elements (excluding the highest level element) is selected.

beg.parentId: ID of the element containing the first selected

element

beg.childId: ID of the first selected element beg.offset: 0 end.parentId

element

: ID of the element containing the first selected

end.childId: ID of the sibling element following the last

selected element, or last selected element

0 if there is no sibling element following the

end.offset: 0

The highest level element is selected.

beg.parentId: 0 beg.childId

: ID of the highest-level element

beg.offset: 0 end.parentId end.childId end.offset

:: 0

: 0

Example

Suppose you create the document shown in Figure 2-1.

Figure 2-1 A document

FDK Programmer’s Guide 85

Frame Document Architecture

Global document information

The API represents the document with an FO_Doc object. The following table lists some of its properties.

Property Type Value

FP_Name StringT C:\Sales\Training\1Chapter

FP_ViewBorders IntT True

FP_ViewRulers IntT True

FP_ViewPageScrolling IntT FV_SCROLL_VERTICAL

FP_Zoom MetricT 1 << 16

FP_IsIconified IntT False

FP_ViewTextSymbols IntT True

FP_IsOnScreen IntT True

86 FDK Programmer’s Guide

Pages

Frame Document Architecture

Pages

. . .

Frame documents have three kinds of visible pages: body pages, master pages, and reference pages.

What the user sees

With FrameMaker, the user can change any of the visible pages.

Body pages

Body pages are what a user normally thinks of as the document’s pages. They organize the text and graphic objects that appear in the body of a document.

Master pages

Master pages control the layout of body pages. Each body page is associated with one master page, and each master page can be associated with zero or more body pages. A master page provides the following for the body page:

 The text frame layout, which defines the number, size, and placement of the page’s

text frames and the column layout within each text frame

 The page background, which includes graphic objects and text frames (such as

headers and footers) with unnamed flows

By default, single-sided documents have at least one master page, which is named Right. Double-sided documents have two master pages, named Right and Left. FrameMaker products allow you to add your own custom master pages to both singlesided and double-sided documents.

When a FrameMaker product adds a body page, it uses a left or right master page object as a background. It also copies all the text frames with named flows from that master page to the body page. Once the FrameMaker product copies these text frames to the body page, they are independent of the text frames on the master page from which they were copied. If you change the text frames, it does not affect the master page.

A body page’s background appears when you view a body page on the screen or print it. However, the background is part of the master page and not the body page. The FrameMaker product superimposes the body page on the background for displaying and printing. If you go to the master page and change the graphic objects that constitute the background, the changes appear when you view or print the body pages associated with the master page.

FDK Programmer’s Guide 87

Frame Document Architecture

Pages

Reference pages

Reference pages can contain named graphic frames. Named graphic frames provide decoration, such as a thick line ruling, for paragraphs in the body pages. The Paragraph Designer provides two settings, Frame Above and Frame Below, that allow you to specify the named graphic frames you want to appear above or below a paragraph.

Reference pages can also contain special flows that control the appearance of generated documents. For example, a Table of Contents document normally has a flow named TOC on one of its reference pages.

How the API represents pages

FrameMaker represents body pages, master pages, and reference pages with FO_BodyPage, FO_MasterPage, and FO_RefPage objects, respectively.

In addition to these pages, a document can also have a hidden page, which stores hidden conditional text. The user cannot see or directly modify hidden pages. FrameMaker represents each hidden page with an FO_HiddenPage object.

Page objects have a number of common properties. These properties specify the following characteristics of a page:

 The dimensions of the page

 Its type (body, master, reference, or hidden)

 Its numbering

 IDs of the objects that represent its page frame and its sibling pages

A page object does not actually contain the text and graphic objects that appear on a page. Instead, it has a property named FP_PageFrame, which specifies the ID of a page frame. A page frame is an invisible unanchored frame whose dimensions match those of the page. (For more information on unanchored frames, see “Graphic objects” on page 92.) The API represents a page frame with an FO_UnanchoredFrame object. This FO_UnanchoredFrame object has properties that specify the IDs of the first and last objects in the linked list of API graphic objects that appear directly on the page.

88 FDK Programmer’s Guide

Frame Document Architecture

FO_UnanchoredFrame

(page frame)

FO_BodyPage

FP_PageFrame

FO_TextFrame

FP_FirstGraphicInFrame

FP_LastGraphicInFrame

Pages

Suppose you create a body page with a single text frame as shown in Figure 2-2.

Figure 2-2 Single text frame on a body page

The API represents the body page in Figure 2-2 with the objects shown in Figure 2-3. The FO_BodyPage object does not have a property that specifies the ID of the FO_TextFrame object. Instead, it has a property, named FP_PageFrame, that specifies the ID of its page frame (an FO_UnanchoredFrame object). The page frame properties, FP_FirstGraphicInFrame and FP_LastGraphicInFrame, both specify the ID of the FO_TextFrame object, since it is the only object that appears directly on the page.

. . .

Figure 2-3 Objects for a body page with a single text frame

A FrameMaker product automatically creates and destroys the page frame when it creates and destroys the page. The page frame is not accessible to the user. However, as a developer, you need to use it to get the objects on a page.

FDK Programmer’s Guide 89

Frame Document Architecture

1 Right 1

Reference PageMaster PagesBody Pages

Pages

How the API organizes pages

The API maintains the different types of visible pages in a document (body pages, master pages, and reference pages) in separate linked lists. FO_Doc objects have the following properties that specify the first and last page object in each list:

 FP_FirstBodyPageInDoc and FP_LastBodyPageInDoc

 FP_FirstMasterPageInDoc and FP_LastMasterPageInDoc

 FP_FirstRefPageInDoc and FP_LastRefPageInDoc

Each page object has two properties, FP_PagePrev and FP_PageNext, that specify the IDs of the page objects before and after it in the list. When you delete a page, the API removes the object that represents it and updates the FP_PagePrev and

FP_PageNext properties for all the FO_Page objects before and after it.

FO_Doc objects also have a property named FP_CurrentPage that specifies the ID

of the current page. The current page is the page that appears on the screen. If more than one page appears on the screen, it is the page that appears with a dark border around it.

Suppose you create a double-sided document that has three body pages, two master pages (Left and Right), and a single reference page, as shown in Figure 2-4. The current page is the Right master page.

Figure 2-4 Document with body, master, and reference pages

90 FDK Programmer’s Guide

Frame Document Architecture

FP_PagePrev

FP_LastRefPageInDoc

FO_Doc

FO_MasterPage

(Left master page)

FO_MasterPage

(Right master page)

FO_RefPage

(Reference page)

FO_BodyPage

(Body page 3)

FO_BodyPage

(Body page 2)

FO_BodyPage

(Body page 1)

FP_PageNext

FP_FirstBodyPageInDoc

FP_LastBodyPageInDoc

FP_FirstRefPageInDoc

FP_FirstMasterPageInDoc

FP_CurrentPage

FP_LastMasterPageInDoc

FP_PagePrev

FP_PageNext

FP_PagePrev

FP_PageNext

FrameMaker products organize the objects as shown in Figure 2-5.

Pages

. . .

Figure 2-5 Example document and page objects

FDK Programmer’s Guide 91

Graphic objects

Frame Document Architecture

Graphic objects

How the API represents hidden pages

If the user chooses to hide conditional text in the document, the FrameMaker product adds a hidden page to the document to store the hidden text. A document can have only one hidden page. FrameMaker products represent the hidden page with an FO_HiddenPage object. The FO_Doc property FP_HiddenPage specifies its ID. The hidden page has only one text flow, named HIDDEN. For more information on how the API represents hidden conditional text, see page 122.

How the API represents master pages

Both single-sided and double-sided documents have default master pages, named Right and Left. In single-sided documents, the Left master page is not visible to the user. However, you can get and set its properties with the API.

A graphic object is anything the user can draw with the Tools palette, or an imported graphic.

What the user sees

A graphic object can be:

 An anchored frame, which is a container for graphic objects that is tied to a specific

location in text.

 An unanchored frame, which is a container for graphic objects that is not tied to a

specific location in text.

 A simple geometric shape, which is a line, an arc, a rectangle, a rounded rectangle,

an ellipse, a polyline, or a polygon.

 A group, which is an invisible graphic object that holds together a set of other

graphic objects.

 A text line, which is a single line of text that isn’t in a paragraph or flow (for more

information on text lines, see “Text” on page 114).

 A text frame, which is a container for text in a flow (for more information on text

frames, see “Text” on page 114).

 An imported graphic such as a bitmap or a PostScript file created with another

application.

 An inset or imported graphic.

 A math equation, which describes a formatted equation.

92 FDK Programmer’s Guide

Frame Document Architecture

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

Graphic objects

You can draw a graphic object directly on a page in a document. A graphic object drawn directly on a page doesn’t move as you edit the text around it. You can also draw a graphic object inside an anchored or unanchored frame. When you move a frame, all the graphic objects inside it move with it. You can nest frames; that is, you can draw a frame within a frame within a frame.

Draw order

The graphic objects in a frame have a back-to-front order or draw order that specifies the order in which the FrameMaker product draws them. By default, the draw order is the same as the order in which you created the objects. When graphic objects overlap, the ones in front (at the end of the draw order) obscure those in back. You can change the draw order by selecting a graphic object and choosing Front or Back from the Tools palette.

Groups

You can create a group from one or more graphic objects. This allows you to manipulate them as a single object. When you resize the group, the FrameMaker product automatically resizes the group’s component objects proportionally.

. . .

Anchored frames

You can draw graphic objects in anchored frames, which are tied to text symbols named anchor symbols (^). An anchor symbol (and its anchored frame) moves with the text to which it is attached. You can specify a variety of parameters that determine where a frame appears in relation to its anchor symbol. For example, it can be below the line containing the anchor symbol or at the bottom of the text frame containing the anchor symbol. Unlike other graphic objects, the anchored frame cannot be drawn directly on a page or into another frame; it can only be created in text.

How the API represents graphic objects

The API represents each type of graphic object with a different type of API object. For example, it represents polygons with FO_Polygon objects and text frames with FO_TextFrame objects.

All types of API graphic objects information:

 The graphic object’s format—that is, characteristics such as its fill pattern and border

width

 The graphic object’s location and angle

1. This manual uses the term API graphic object to refer to objects (such as FO_Polygon and

FO_TextFrame

frames) that appear on a page.

objects) that the API uses to represent the graphic objects (such as polygons and text

have properties that provide the following

FDK Programmer’s Guide 93

Frame Document Architecture

Graphic objects

 IDs of the graphic object’s parent, sibling, and child objects

Some format properties do not affect some graphic objects. For example, an FO_Rectangle object, like all other objects, has an FP_ArrowType property. This

property can have a value, but that value will not affect the appearance of the rectangle that the object represents.

All types of API graphic objects also have several properties that are specific to them. For example, FO_Arc objects have a property named FP_Theta that specifies an arc’s theta value.

Suppose you create the arrow shown in Figure 2-6.

Figure 2-6 Arrow in an unanchored frame

The API represents the arrow with an FO_Line object, whose properties include those shown in the following table.

Property Type Value

FP_FrameParent F_ObjHandleT ID of the frame containing the arrow

FP_Pen IntT FV_FILL_BLACK

FP_LocX MetricT .25*in

FP_LocY MetricT 1.125*in

FP_HeadArrow IntT True

FP_ArrowType IntT FV_ARROW_HOLLOW

How the API organizes graphic objects

The API maintains each API graphic object in at least two linked lists:

 The list of all the API graphic objects in the document

For convenience, the API maintains a linked list of all the API graphic objects in a document. The FO_Doc property FP_FirstGraphicInDoc specifies the ID of the first object in the list. API graphic objects have a property named FP_NextGraphicInDoc, which specifies the ID of the next API graphic object in

94 FDK Programmer’s Guide

Frame Document Architecture

Graphic objects

the list. If you traverse this list, you will cover every graphic object in a document. The order of the list is completely random.

 The list of API graphic objects in the graphic object’s parent frame

Each API graphic object (except an anchored frame and a page frame) has exactly one parent frame object. The parent frame is the frame that contains the graphic object. The API maintains a linked list of the child objects in each frame.

FO_UnanchoredFrame and FO_AFrame objects have FP_FirstGraphicInFrame and FP_LastGraphicInFrame properties,

which specify the first and last objects in the list of their child objects. All API graphic objects have FP_PrevGraphicInFrame and FP_NextGraphicInFrame properties, which specify the objects before and after them in the list. The order of the objects in the linked list is the same as the draw order of the graphic objects in a frame.

Like the frames they represent, API frame objects can be nested: that is, an

FO_UnanchoredFrame or FO_AFrame object can be the parent of another FO_UnanchoredFrame object. Every API graphic object (except an object that

represents a page frame or an anchored frame) is a descendant of exactly one API page frame object.

. . .

Suppose you create a page that contains:

 An unanchored frame that contains an oval, a rectangle, and a text frame with some

text in it

 A text line that overlaps the unanchored frame, but is drawn directly on the page

FrameMaker products organize the objects as shown in Figure 2-7.

FDK Programmer’s Guide 95

Frame Document Architecture

FP_PageFrame

FO_BodyPage

FP_LastGraphicInFrame

FO_Ellipse

FO_Rectangle

FO_TextFrame

FP_NextGraphicInFrame

FP_PrevGraphicInFrame

FP_NextGraphicInFrame

FP_PrevGraphicInFrame

FP_FirstGraphicInFrame

FO_UnanchoredFrame

FO_TextLine

FP_NextGraphicInFrame

FP_PrevGraphicInFrame

FP_LastGraphicInFrame

FP_FirstGraphicInFrame

FO_UnanchoredFrame

(Page frame)

Draw Order

Graphic objects

Figure 2-7 API objects that represent a page and the graphic objects on it

How the API represents groups

The API represents a grouped set of graphic objects with an FO_Group object. It maintains the objects that constitute a group in a linked list. The FO_Group properties, FP_FirstGraphicInGroup and FP_LastGraphicInGroup, specify the first and last objects in the list. Each graphic object has FP_PrevGraphicInGroup and FP_NextGraphicInGroup properties, which specify the objects before and after it in the list.

Grouping graphic objects does not affect their position in the linked list of API graphic objects in a frame. That is, it does not affect their position in the draw order. Group objects themselves have an arbitrary position in the draw order.

96 FDK Programmer’s Guide

Flows

VIEWS

123

Frame Document Architecture

Flows

. . .

How the API represents selections of graphic objects

The FO_Doc property, FP_FirstSelectedGraphicInDoc, specifies the ID of the object that represents the first selected graphic object in a document. If more than one graphic object is selected, the API forms a linked list of the API graphic objects that represent the selected graphic objects. API graphic objects have an FP_NextSelectedGraphicInDoc property that specifies the ID of the next selected graphic object. The order of the list is not necessarily the same as the order in which the graphic objects were selected.

Although FP_FirstSelectedGraphicInDoc is a document property, you can only select graphic objects that are within the same frame.

FrameMaker products use flows to connect text frames in a document.

What the user sees

A flow tells the FrameMaker product where to put additional text when a text frame is full. In a simple document, there may be only one flow associated with the body pages. In complex documents such as newsletters, you may create multiple flows that have connected text frames on different pages.

Figure 2-8 Multiflow document

Flows have an Autoconnect setting that controls whether the FrameMaker product generates a new page when you fill the last text frame of a flow. If Autoconnect is on, the FrameMaker product creates a new page and connects a text frame on the new page with the text frame on the previous page.

FDK Programmer’s Guide 97

Frame Document Architecture

Flows

Main flows

Each document has a main flow. Normally, the FrameMaker product treats the main flow like any named flow in the document. However, there are cases when the FrameMaker product treats the main flow specially:

 When you generate a table of contents or an index, the FrameMaker product puts the

generated text into the main flow of the generated document.

 When you run Compare Documents, the FrameMaker product puts the Summary text

into the main flow.

Usually the main flow is the default flow for the current language. For example, if the current language is English, the main flow is A.

If there are several Autoconnect flows in the document with the default flow tag, the main flow is the one in the backmost text frame on the frontmost body page.

How the API represents flows

The API represents a flow with an FO_Flow object, whose properties provide the following information:

 The flow’s format characteristics, such as the feathering and whether Autoconnect is

enabled

 The IDs of the first and last FO_TextFrame objects in the flow

 The ID of the next FO_Flow object in the document

How the API organizes flows

The API maintains a document’s FO_Flow objects in a linked list. The FO_Doc property, FP_FirstFlowInDoc, specifies the ID of the first FO_Flow object in the list. FO_Flow objects have a property named FP_NextFlowInDoc, which specifies the next FO_Flow object in the list. The order of the list is random; it does not correspond to the order in which the flows appear in the document.

The API also maintains the objects that represent a flow’s text frames in a linked list. The FO_Flow properties, FP_FirstTextFrameInFlow and FP_LastTextFrameInFlow, specify the first and last FO_TextFrame objects in the list. Each FO_TextFrame object has an FP_PrevTextFrameInFlow property and a FP_NextTextFrameInFlow property, which specify the previous and next FO_TextFrame objects in the list. For more information on how flows, text frames, and paragraphs are organized, see “How the API organizes paragraphs” on page 106.

98 FDK Programmer’s Guide

Frame Document Architecture

AAA

Flow A

Unnamed flow

FP_LastTextFrameInFlow

FO_Flow

(Unnamed flow)

FP_LastTextFrameInFlow

FO_TextFrame

FP_FirstTextFrameInFlow

FO_Flow

(Flow A)

FP_MainFlowInDoc

FP_FirstFlowInDoc

FO_TextFrame

FP_NextTextFrameInFlow

FP_PrevTextFrameInFlow

FO_TextFrame

FP_NextFlowInDoc

FP_FirstTextFrameInFlow

FO_Doc

Flows

Suppose you create the document shown in Figure 2-9. The document has two flows: a main flow, named A, and a second flow that is unnamed. The A flow connects a twocolumn text frame on the first page and a two-column text frame on the second page. The unnamed flow appears only on the first page and has only one text frame.

Figure 2-9 Document with a named and an unnamed flow

Figure 2-10 shows how the API organizes the objects that represent the flows and text frames shown in Figure 2-9.

. . .

Figure 2-10 Objects that represent a document with two flows

FDK Programmer’s Guide 99

Frame Document Architecture

FO_TextFrame

FP_LastSubCol

FO_SubCol

FP_NextSubCol

FP_PrevSubCol

FO_SubCol

FP_FirstSubCol

Flows

Although the FP_FirstFlowInDoc property specifies the FO_Flow object for the unnamed flow in Figure 2-10, it could also specify the FO_Flow object that represents Flow A. The determination of which flow is first in the list is completely random.

The API uses FO_SubCol objects to represent the column formatting of text as follows:

 Contiguous paragraphs in each column of a text frame are within a single

FO_SubCol object.

 Contiguous paragraphs within sidehead area are within a single FO_SubCol.

 Each contiguous series of paragraphs that spans columns and/or sideheads is

represented by a single FO_SubCol object.

 Following paragraphs that do not span columns and sideheads begin a new group of

FO_SubCol objects. For example, Figure 14.11 shows a page that has seven FO_SubCol objects.two groups of three, plus one for the heading that spans all columns..

The FO_TextFrame properties, FP_FirstSubCol and FP_LastSubCol, specify the first and last FO_SubCol objects in a specific text frame. Each FO_SubCol object has an FP_PrevSubCol property and a FP_NextSubCol property, which specify the previous and next FO_SubCol objects in the flow. Each FO_SubCol object also has a FP_ParentTextFrame property, which specifies the text frame it is in. If a text frame has only one column, its FP_FirstSubCol and FP_LastSubCol properties both specify the ID of the FO_SubCol object that represents it.

100 FDK Programmer’s Guide

Figure 2-11 shows how the API organizes the objects that represent the two-column text frame on the first page of the document in Figure 2-9.

Figure 2-11 Objects that represent a text frame with two columns

Macromedia FrameMaker - 2017 Programmer’s Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

The Frame Developer’s Kit

1Using Frame Developer Tools

Frame API

Structure Import/Export API

Other FrameMaker product features for developers

Choosing the right Frame tools

FDK documentation

FDK Programmer’s Reference

FDK Programmer’s Guide

Naming conventions

Style conventions

Structured program interface

Typographic conventions

2Getting Started with FDK

Downloading and installing the FDK

System requirements

Reviewing the sample programs in the samples/hello folder

Getting familiar with how the FDK works on Windows

How to write an FDK client for Windows

Including FDK header files

Writing FDK clients for Windows

Adding calls to initialize the FDE

Using Windows pathnames

Using menus and commands

Using FDK functions that write to FrameMaker console

Compiling, Registering, and Running FDK Clients

Using platform-dependent session properties

Compiling FDK Clients

Compiling and registering your own FDK clients

Registering FDK Clients

Running FDK Clients

Compatibility between FDK and FrameMaker product releases

Disabling FDK clients

Debugging FDK Clients

Writing an Asynchronous FDK Client

End user installations

Registering asychronous clients

Types of asynchronous clients

Registering multiple FrameMaker processes as servers

Registering a name for a FrameMaker process

Running asynchronous clients on remote hosts

Connecting to the default process on a local host

Connecting to a named process on a local host

Connecting to a remote host

How to write an asynchronous FDK client

Writing a Main routine in Windows.

Compiling and registering the sample client

Summary of supporting functionality

Example: adding menus and commands

Next Steps

Identifying objects

11 Frame Session Architecture

Unique object names

Unique persistent identifiers (UIDs)

Representing object characteristics with properties

Property lists

FrameMaker product sessions

How the API represents sessions

Documents

What the user sees

22 Frame Document Architecture

How the API represents documents

Global document information

What the user sees

How the API represents global document information

Pages

What the user sees

How the API represents pages

Graphic objects

What the user sees

How the API represents graphic objects

Flows

What the user sees

How the API represents flows