Page is loading ...
VERSION 12
Frame Developer’s Kit,
January 2014
Adobe Systems Incorporated
Corporate Headquarters
345 Park Avenue
San Jose, CA 95110-2704
(408) 536-6000
FDK Programmer’s Guide
© Copyright 1986 - 2014 Adobe Systems Incorporated and its licensors. All rights reserved.
Adobe, the Adobe logo & FrameMaker are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other
countries.
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.
Portion include technology under Inso Corporation.
Portions include technology under copyright Right Hemisphere, Inc.
Portions utilize Microsoft Windows Media Technologies. Copyright (c) 2006 Microsoft Corporation. All Rights Reserved.
Notices, terms and conditions pertaining to third party software are located at http://www.adobe.com/go/thirdparty and
incorporated by reference herein.
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 12 .........................................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
1 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 12 ................................................................................... 185
2 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
3 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
Contents
FDK Programmer’s Guide 5
. . .
Using hypertext commands in your client’s user interface ......................................... 213
Responding to user-initiated events or FrameMaker product operations ................... 217
Implementing quick keys ............................................................................................ 228
Freeing system resources by bailing out ..................................................................... 230
4 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
5 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
6 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
7 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
8 Creating and Deleting API Objects .........................................................................357
Creating objects .......................................................................................................... 357
Deleting objects .......................................................................................................... 377
Implicit property changes ........................................................................................... 379
9 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
10 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
11 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
12 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
13 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)
14 Introduction to FDE .................................................................................................527
How the FDE works ................................................................................................... 527
How to make your client portable ............................................................................... 529
A simple FDE filter ..................................................................................................... 534
15 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
16 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
Im
port/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
Frame
Maker 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 rep
resents 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 F
O_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
nam
es, 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 12
This Getting Started section is intended to help you get familiar with the basics of FDK
12. 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 12
Downloading and installing the FDK
18 FDK Programmer’s Guide
5
DownloadingandinstallingtheFDK
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 12
Reviewing the sample programs in the samples/hello folder
FDK Programmer’s Guide 19
. . .
Reviewing the sample programs in the samples/hello folder
Thesamplesfoldercontainsseveralprogramsthatwillhelpyougetstarted.Asan
example,hereisacodeextractfromthesamples/hello/hello.cfile:
/*
* 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 */
Getting Started with FDK 12
Getting familiar with how the FDK works on Windows
20 FDK Programmer’s Guide
5
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 ef
fectsyou can get
wit
h 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 wi
th
a particular format.
Adocument report is an FDK client that provides information about a document. The
user can start
a document report by choosing Utilities>Document Reports from th
e
Fi
le 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.
/