Adobe FrameMaker 11.0 User guide

VERSION 11

Frame Developer’s Kit,

October 2012

Adobe Systems Incorporated

Corporate Headquarters

345 Park Avenue

San Jose, CA 95110-2704

(408) 536-6000

FDK Programmer’s Guide

Adobe® FrameMaker® 11 for Windows® Frame D

eveloper’s Kit for Windows

This manual is protected under copyright law, furnished for informational use only, is subject to change without notice, and should not be construed as a

commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may

appear in the informational content contained in this manual.

This manual is licensed for use under the terms of the Creative Commons Attribution Non-Commercial 3.0 License. This License allows users to copy,

distribute, and transmit the manual for noncommercial purposes only so long as (1) proper attribution to Adobe is given as the owner of the manual; and (2)

any reuse or distribution of the manual contains a notice that use of the manual is governed by these terms. The best way to provide notice is to include the

following link. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/3.0/us/

Adobe, the Adobe logo, Adobe AIR, Adobe Captivate, Adobe Type Manager, Acrobat, AIR, Creative Suite, Distiller, Flash, FrameMaker, Illustrator,

PageMaker, Photoshop, PostScript, Reader, RoboHelp, and RoboScreenCapture are trademarks of Adobe Systems Incorporated in the United States and/or

other countries.

Microsoft, Windows, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other

countries. Solaris is a trademark or registered trademark of Oracle and/or its affiliate. SVG is a trademark of the World Wide Web Consortium; marks

of the W3C are registered and held by its host institutions MIT, INRIA, and Keio.

Updated Information/Additional Third Party Code Information available at http://www.adobe.com/go/thirdparty

.

Portions include software under the following terms:

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

).

EITHER EXPRESS OR IMPLIED, REGARDING THIS PRODUCT, INCLUDING WARRANTIES WITH RESPECT TO ITS MERCHANTABILITY OR ITS

FITNESS FOR ANY PARTICULAR PURPOSE. The MacApp software is proprietary to Apple Computer, Inc. and is licensed to Adobe for distribution only

fors use in combination with Adobe FrameMaker.

MPEG Layer-3 audio compression technology licensed by Fraunhofer IIS and THOMSON multimedia (http://www.iis.fhg.de/amm

).

ImageStream Graphics Filters and ImageStream are registered trademarks of Inso Corporation.

Portions utilize code licensed from Nellymoser (www.nellymoser.com

)

Reserved. http://www.on2.com

.

Certain trademarks are owned by The Proximity Division of Franklin Electronic Publishers, Inc., and are used by permission. Merriam-Webster is a

trademark of Merriam-Webster, Inc.

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

Sorenson Spark™ video compression and decompression technology licensed from Sorenson Media, Inc.

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

Notice to U.S. government end users. The software and documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of

“Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R.

§227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software

and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial items and (b) with only those

rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United

States. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of

Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the

Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and

regulations contained in the preceding sentence shall be incorporated by reference.

. . . . .

The latest version of this document is available online at

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

FDK Programmer’s Guide 3

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

. . . . .

Contents

PART I: Getting Started

Using Frame Developer Tools .........................................11

The Frame Developer’s Kit .......................................................................................... 11

Choosing the right Frame tools ..................................................................................... 13

FDK documentation ...................................................................................................... 14

Naming conventions ..................................................................................................... 14

Style conventions .......................................................................................................... 15

Getting Started with FDK 11 ..........................................17

Downloading and installing the FDK ........................................................................... 18

System requirements ..................................................................................................... 18

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

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

Writing FDK clients for Windows ................................................................................ 21

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

Writing an Asynchronous FDK Client ......................................................................... 39

Example: adding menus and commands ....................................................................... 55

Next Steps .....................................................................................................................57

PART II: Frame Product Architecture

1 Frame Session Architecture .......................................................................................61

Identifying objects ........................................................................................................ 61

Representing object characteristics with properties ...................................................... 63

FrameMaker product sessions ...................................................................................... 67

2 Frame Document Architecture ..................................................................................73

Documents .................................................................................................................... 73

Global document information ....................................................................................... 79

Pages ............................................................................................................................. 85

Graphic objects ............................................................................................................. 90

Flows ............................................................................................................................. 95

Paragraph Catalog formats .......................................................................................... 100

Paragraphs ................................................................................................................... 101

Character Catalog formats .......................................................................................... 106

Condition Formats ...................................................................................................... 110

Contents

4 FDK Programmer’s Guide

Text ............................................................................................................................. 112

Markers ....................................................................................................................... 122

Cross-reference formats .............................................................................................. 125

Cross-references .......................................................................................................... 127

Variable formats .......................................................................................................... 129

Variables ......................................................................................................................131

Footnotes ..................................................................................................................... 132

Ruling Formats ........................................................................................................... 134

Table Catalog formats ................................................................................................. 136

Tables .......................................................................................................................... 138

Colors .......................................................................................................................... 147

Structural element definitions ..................................................................................... 150

Format rules and format rule clauses .......................................................................... 153

Format change lists ..................................................................................................... 155

Structural elements ..................................................................................................... 157

3 Frame Book Architecture .........................................................................................159

What the user sees ....................................................................................................... 159

How the API represents books .................................................................................... 160

Creating new books and components ......................................................................... 164

Updating a book .......................................................................................................... 165

Using the book error log ............................................................................................. 170

PART III: Frame Application Program Interface

4 Introduction to the Frame API ................................................................................175

How the API works ..................................................................................................... 175

Special types of clients ............................................................................................... 177

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

Creating and running a client ...................................................................................... 179

A simple example ....................................................................................................... 181

Using old clients with FDK 11 ................................................................................... 185

5 API Client Initialization ...........................................................................................187

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

Initialization types ....................................................................................................... 188

Disabling the API ........................................................................................................ 190

FrameMaker Product Activation by Asynchronous Clients ....................................... 190

6 Creating Your Client’s User Interface ....................................................................193

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

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

Replacing FrameMaker product menus and commands ............................................. 211

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

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

Contents

FDK Programmer’s Guide 5

. . .

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

Implementing quick keys ............................................................................................ 228

Freeing system resources by bailing out ..................................................................... 230

7 Executing Commands with API Functions ............................................................233

Handling errors ........................................................................................................... 233

Handling messages and warnings ............................................................................... 233

Opening documents and books ................................................................................... 235

Creating documents .................................................................................................... 244

Printing documents and books .................................................................................... 249

Saving documents and books ...................................................................................... 251

Closing documents and books .................................................................................... 258

Quitting a Frame session ............................................................................................. 260

Comparing documents and books ............................................................................... 260

Updating and generating documents and books ......................................................... 263

Simulating user input .................................................................................................. 270

Straddling table cells ................................................................................................... 271

Executing FrameMaker commands ............................................................................ 272

8 Getting and Setting Properties ................................................................................277

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

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

Manipulating properties .............................................................................................. 288

Getting and setting session properties ........................................................................ 295

Getting and setting document properties .................................................................... 298

Getting and setting graphic object properties ............................................................. 301

Getting and setting paragraph properties .................................................................... 304

Getting and setting book properties ............................................................................ 308

Getting and setting FrameMaker properties ............................................................... 309

9 Manipulating Text .....................................................................................................317

Getting text ................................................................................................................. 317

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

Adding and deleting text ............................................................................................. 331

Getting and setting text formatting ............................................................................. 334

Executing Clipboard functions ................................................................................... 339

10 Manipulating Asian Text ..........................................................................................343

Creating a rubi group .................................................................................................. 343

Text encodings ............................................................................................................ 344

Using encoding data .................................................................................................... 346

Inspecting and manipulating encoded text .................................................................. 351

Parsing an encoded string ........................................................................................... 353

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

Special issues with double byte encodings ................................................................. 355

Contents

6 FDK Programmer’s Guide

11 Creating and Deleting API Objects .........................................................................357

Creating objects .......................................................................................................... 357

Deleting objects .......................................................................................................... 377

Implicit property changes ........................................................................................... 379

12 Manipulating Commands and Menus with the API ..............................................381

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

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

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

Arranging menus and menu items .............................................................................. 388

Getting and setting menu item labels .......................................................................... 395

Manipulating expandomatic menu items .................................................................... 397

Using check marks ...................................................................................................... 398

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

13 Creating Custom Dialog Boxes for Your Client .....................................................403

Overview ..................................................................................................................... 403

How to create a dialog box ......................................................................................... 408

Creating a DRE file ..................................................................................................... 408

Designing the layout of the dialog box ....................................................................... 411

Setting the properties of the dialog box ...................................................................... 415

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

Saving a DRE file .......................................................................................................427

Modeless Dialog Boxes .............................................................................................. 428

Testing a dialog box .................................................................................................... 429

A simple example ....................................................................................................... 431

General tips for dialog editing .................................................................................... 435

Summary of keyboard shortcuts ................................................................................. 435

14 Handling Custom Dialog Box Events ......................................................................437

How the API represents dialog boxes ......................................................................... 437

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

Opening dialog resources ............................................................................................ 444

Initializing items in a dialog box ................................................................................ 445

Displaying a dialog box .............................................................................................. 446

Updating items in a dialog box ................................................................................... 447

Handling user actions in dialog boxes ........................................................................ 448

Closing a dialog box ................................................................................................... 457

15 Using Imported Files and Insets ..............................................................................459

Types of imported files and insets .............................................................................. 459

Importing text and graphics ........................................................................................ 460

Updating text insets .................................................................................................... 467

Client text insets .......................................................................................................... 467

Writing filter clients .................................................................................................... 472

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

Contents

FDK Programmer’s Guide 7

. . .

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

16 Working with Unicode ..............................................................................................501

Introduction to Unicode Support ................................................................................ 501

Unicode Mode ............................................................................................................. 501

Compatibility mode .................................................................................................... 511

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

Mixed Mode operations .............................................................................................. 521

Handling for special characters ...................................................................................522

PART IV: Frame Development Environment (FDE)

17 Introduction to FDE .................................................................................................527

How the FDE works ................................................................................................... 527

How to make your client portable ............................................................................... 529

A simple FDE filter ..................................................................................................... 534

18 Making I/O and Memory Calls Portable ................................................................539

Initializing the FDE .................................................................................................... 539

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

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

Assertion-handler functions ........................................................................................ 543

Making memory allocation portable ........................................................................... 544

Error and progress reporting ....................................................................................... 545

19 FDE Utility Libraries ................................................................................................547

String library ............................................................................................................... 547

The string list library ................................................................................................... 548

Character library ......................................................................................................... 548

The I/O library ............................................................................................................ 549

The hash library .......................................................................................................... 549

Metric library .............................................................................................................. 551

MIF data structures and macros .................................................................................. 551

The MIF library .......................................................................................................... 553

Simple MIF library ..................................................................................................... 554

Glossary .................................................................... 555

Contents

8 FDK Programmer’s Guide

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

PART I

Getting Started

FDK Programmer’s Guide 11

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

. . . . .

Using Frame Developer Tools

The Frame Developer’s Kit

The Frame



Developer’s Kit™ (FDK) provides tools for developers to enhance the

functionality of FrameMaker



.

This chapter provides an overview of the FDK and other aspects of FrameMaker that are

useful for developers. It also discusses the FDK documentation.

The principal parts of the FDK are:

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

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

Using Frame Developer Tools

The Frame Developer’s Kit

12 FDK Programmer’s Guide

 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

Using Frame Developer Tools

Choosing the right Frame tools

FDK Programmer’s Guide 13

. . .

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

fmbatch perform. The tool or combination of tools you should use depends on your

needs. Generally, MIF and fmbatch are more useful for one-time solutions to small

problems, whereas the API is more useful for full-scale applications or applications

where interaction with the user is required.

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

Frame tool

or feature Advantages Limitations

Frame API Fast, interactive, and portable; easy to

provide a user interface for your

applications

Must be compiled

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.

Files must be saved as MIF; not

interactive

Using Frame Developer Tools

FDK documentation

14 FDK Programmer’s Guide

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 Programmer’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()

Using Frame Developer Tools

Style conventions

FDK Programmer’s Guide 15

. . .

This manual uses the term API graphic object to refer to objects (such as FO_Polygon

and FO_TextFrame objects) that the API uses to represent the graphic objects (such

as polygons and text frames) that appear on a page.

Style conventions

FDK manuals 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.

API scriptable function

property names

Begin with FS_ FS_NewDoc

FDE functions Begin with F_ F_StrNew()

Flags used by API functions Begin with FF_ and all

letters are uppercase

FF_UFF_VAR

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

Type Naming convention Example

Using Frame Developer Tools

Style conventions

16 FDK Programmer’s Guide

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

. . .

FDK Programmer’s Guide 17

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

. . . . .

Getting Started with FDK 11

This Getting Started section is intended to help you get familiar with the basics of FDK

11. 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"

 "Next Steps"

Getting Started with FDK 11

Downloading and installing the FDK

18 FDK Programmer’s Guide

5

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.

Getting Started with FDK 11

Reviewing the sample programs in the samples/hello folder

FDK Programmer’s Guide 19

. . .

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

Page is loading ...

Adobe FrameMaker 11.0 User guide

Adobe FrameMaker 11.0 User guide

Related papers

Other documents