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

+ 532 hidden pages

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