bc

Acrobat Forms API
Reference
Technical Note #5181
Version : Acrobat 6.0

ADOBE SYSTEMS INCORPORATED

Corporate Headquarters
345 Park Avenue
San Jose, CA 95110-2704(408) 536-6000
http://partners.adobe.com

May 2003

Copyright 2003 Adobe Systems Incorporated. All rights reserved.
NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in hardcopy orelectronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, orotherwise, without the prior written consent of the Adobe Systems Incorporated.
PostScript is a registered trademark of Adobe Systems Incorporated. All instances of the name PostScript in the text are references to the
PostScript language as defined by Adobe Systems Incorporated unless otherwise stated. The name PostScript also is used as a producttrademark for Adobe Systems’ implementation of the PostScript language interpreter.
Except as otherwise stated, any reference to a "PostScript printing device,” "PostScript display device,” or similar item refers to a printing
device, display device or item (respectively) that contains PostScript technology created or licensed by Adobe Systems Incorporated and not
to devices or items that purport to be merely compatible with the PostScript language.
Adobe, the Adobe logo, Acrobat, the Acrobat logo, Acrobat Capture, Distiller, PostScript, the PostScript logo and Reader are either registeredtrademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.
Apple, Macintosh, and Power Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries. PowerPCis a registered trademark of IBM Corporation in the United States. ActiveX, Microsoft, Windows, and Windows NT are either registeredtrademarks or trademarks of Microsoft Corporation in the United States and/or other countries. UNIX is a registered trademark of The OpenGroup. All other trademarks are the property of their respective owners.
This publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as acommitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies,
makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and all warranties
of merchantability, fitness for particular purposes, and noninfringement of third party rights.

Acrobat SDK Documentation Roadmap
Getting Started
Getting Started Using the Acrobat Software Development Kit
PDF Specification
Acrobat SDK Release Notes
Acrobat Development Overview

Acrobat Developer FAQ
Acrobat Plug-in Tutorial

Reader Enabling
Acrobat SDK Samples Guide

PDF Reference
ManualUpgrading Plug-ins from Acrobat 5.0 to Acrobat 6.0

Acrobat Core API

Extended API for Plug-in

PDF Creation APIs
and Specifications

Acrobat CoreAPI Overview

AcroColor API Reference

Acrobat Distiller
Parameters

ADM Programmer’s
Guide and Reference

Acrobat Distiller
API Reference

Catalog API Reference

pdfmark
Reference

Acrobat Core
API Reference

JavaScript
Acrobat JavaScript
Scripting
Reference

Acrobat Interapplication
Communication (IAC)
Acrobat IAC Overview
Acrobat IAC Reference

Digital Signature API
Reference

Forms API Reference

PDF Consultant
Accessibility Checker

Search API Reference

Spelling API Reference

Using the Save as
XML Plug-in

Weblink API Reference

Acrobat
JavaScript
Scripting Guide
Programming
Acrobat JavaScript
Using Visual Basic

Contents

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
What Is In This Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Other Useful Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Conventions Used in This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

AcroForm API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

AcroForm Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
AcroForm Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
PDField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Core Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
ASAtom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
ASBool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
ASFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
ASPathName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
AVDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
CosDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
CosObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
PDAnnot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
PDDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
PDPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

AcroForm Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
AFExecuteThisScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
AFImportAppearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
AFLayoutBorder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
AFLayoutCreateStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
AFLayoutDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
AFLayoutNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
AFLayoutText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
AFPDDocEnumPDFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
AFPDDocGetPDFieldFromName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Acrobat Forms API Reference5

Contents

AFPDDocLoadPDFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
AFPDFieldFromCosObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
AFPDFieldGetCosObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
AFPDFieldGetDefaultTextAppearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
AFPDFieldGetFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
AFPDFieldGetName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
AFPDFieldGetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
AFPDFieldIsAnnot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
AFPDFieldIsTerminal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
AFPDFieldIsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
AFPDFieldReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
AFPDFieldSetDefaultTextAppearance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
AFPDFieldSetFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
AFPDFieldSetOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
AFPDFieldSetValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
AFPDFormFromPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
AFPDWidgetGetAreaColors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
AFPDWidgetGetBorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
AFPDWidgetGetRotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
AFPDWidgetSetAreaColors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
AFPDWidgetSetBorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
AssembleFormAndImportFDF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
ExportAsFDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
ExportAsFDFEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
ExportAsFDFWithParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
ExportAsHtml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
ExportAsHtmlEx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
ImportAnFDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
IsPDDocAcroForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
ResetForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

AcroForm Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
AFPDFieldEnumProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

AcroForm Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
AcroForm Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
AF_Flags_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
AFPDFieldBorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
AFPDFieldFlags_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
AFPDWidgetBorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
AFPDWidgetBorderRec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
AFPDWidgetBorderStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
ExportAsFDFParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
ExportAsFDFParamsRec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

6

Acrobat Forms API ReferenceContents

RetCode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
TextAppearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
TextAppearanceP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Core Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
PDColorSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
PDColorValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
PDColorValueRec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
PDRotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

AcroForm Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Init_TextAppearanceP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
SetDefaultTextAppearanceP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
TextApperanceIsValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Text-to-Speech API (Windows only) . . . . . . . . . . . . . . . . . . . . . . . . . 87
AFTTSGetNumberOfVoices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
AFTTSGetPitch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
AFTTSGetSpeaker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
AFTTSGetSpeechRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
AFTTSGetVoiceName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
AFTTSGetVolume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
AFTTSIsAvailable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
AFTTSPause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
AFTTSQSilence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
AFTTSQSound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
AFTTSQueueTextData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
AFTTSReset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
AFTTSResume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
AFTTSSetPitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
AFTTSSetSpeaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
AFTTSSetSpeechRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
AFTTSSetVolume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
AFTTSStop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
AFTTSTalk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

AcroForm OLE Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

Acrobat Forms API Reference

7

Contents

OLE Automation Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
AFormApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109

OLE Automation Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
PopulateListOrComboBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
SetBackgroundColor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
SetBorderColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
SetButtonCaption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
SetButtonIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
SetExportValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
SetForegroundColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
SetJavaScriptAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
SetResetFormAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
SetSubmitFormAction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Add. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
AddDocJavascript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
ExecuteThisJavascript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
ExportAsFDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
ExportAsHtml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
ImportAnFDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

OLE Automation Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
BorderStyle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
BorderWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
ButtonLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
CalcOrderIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
CharLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
DefaultValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Editable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Highlight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
IsHidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
IsMultiline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
IsPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
IsReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
IsRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
IsTerminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

8

Acrobat Forms API ReferenceContents

Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
NoViewFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
PrintFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
TextFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
TextSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
_NewEnum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156

Acrobat Forms API Reference

9

Contents

10

Acrobat Forms API ReferencePreface

The Adobe® Acrobat® Forms plug-in allows a Portable Document Format (PDF) document to
act as a form; that is, the Acrobat equivalent of a paper form with fields. It is now faster andeasier to exchange information either in familiar paper or electronic forms converted to
PDF files with Acrobat, or as dynamic interactive database templates.
NOTE:

Forms as used here do not refer to XObject forms as defined in the PDF Reference.

The Forms plug-in for Acrobat (versions 4.0 and above) allows users to author form fields.
For Acrobat Reader, the Forms plug-in does not allow form authoring, but allows users to fillin data and print Acrobat forms. The Reader Forms plug-in also does not allow users to savedata to the local hard disk. Both Acrobat and Reader allow Web designers to send data fromthe form back to a Web server.

What Is In This Document
This document is a reference for developers who want to take advantage of the Forms API.
It is divided into two sections:●

AcroForm API Reference describes the Forms API and explains how to use it. It
includes the new Text-to-Speech APIs for Windows.

●

AcroForm OLE Automation describes the OLE Automation methods exported by the
Adobe Acrobat AcroForm plug-in.

If you received this technical note without obtaining the entire Acrobat Software
Development Kit (SDK), you can get the complete SDK by visiting:
http://partners.adobe.com/asn/developer/acrosdk/main.html.Other UsefulDocumentation

Other Useful Documentation
You should be familiar with the Acrobat core API. The following technical notes provide thisinformation.
Acrobat Core API Overview, technical note 5190,gives an overview of the objects andmethods provided by the Acrobat core API.
Acrobat Core API Reference, technical note 5191,describes in detail the objects and methods
provided by the Acrobat core API.
Acrobat Development Overview, technical note 5167, describes how to develop Acrobat
plug-ins on the various platforms available.

Acrobat Forms API Reference

11Preface
Conventions Used in This Book

PDF Reference, Fourth Edition, version 1.5. Provides a description of the PDF file format, as
well as suggestions for producing efficient PDF files.

Conventions Used in This Book
The Acrobat documentation uses text styles according to the following conventions.
Font

Used for

Examplesmonospaced

Paths and filenames

C:\templates\mytmpl.fm

Code examples set off
from plain text

These are variable declarations:

Code items within plaintext

The GetExtensionID method ...

Parameter names andliteral values inreference documents

The enumeration terminates if proc
returns false.

Pseudocode

ACCB1 void ACCB2 ExeProc(void){ do something }Placeholders in code
examplesAFSimple_Calculate(cFunction,
cFields)

Live links to Web pages

The Acrobat Solutions Network URL is:
http://partners/adobe.com/asn/

Live links to sections
within this document

See Using the SDK.

monospaced boldmonospaced italic

blue

AVMenu commandMenu,helpMenu;

Live links to other
See the Acrobat Core API Overview.
Acrobat SDK documents

bold

12

Live links to code items
within this document

Test whether an ASAtom exists.

PostScript language and
PDF operators,
keywords, dictionary
key names

The setpagedevice operator

User interface names

The File menu

Acrobat Forms API ReferencePreface
Conventions Used in This Book

Font

Used for

ExamplesitalicDocument titles that are
not live links

Acrobat Core API Overview

New terms

User space specifies coordinates for...

PostScript variables

filename deletefile

Acrobat Forms API Reference

13Preface
Conventions Used in This Book

14

Acrobat Forms API ReferenceAcroForm API Reference

Introduction
The Acrobat Forms plug-in exports its own Host Function Table (HFT), whose methods canbe used by other plug-ins. To use the Acrobat Forms plug-in’s HFT, a plug-in must:●

include the header file FormsHFT.h (which includes AF_ExpT.h and AF_Sel.h).

●import the HFT using ASExtensionMgrGetHFT. A convenient way to do this is to use
the Init_AcroFormHFT macro defined in FORMSHFT.H.
#define Init_AcroFormHFT
ASExtensionMgrGetHFT(ASAtomFromString(AcroFormHFT_NAME),
AcroFormHFT_LATEST_VERSION)●

assign the HFT returned by this call to a plug-in-defined global variable named
gAcroFormHFT.

Data may be imported and exported into Acrobat Forms in Forms Data Format (FDF). FDF isused to submit form data to a server, as well as to receive the response and incorporate it
into a form. FDF is based on PDF and uses the same syntax and set of basic object types as
PDF. It also has the same file structure, except that the cross-reference table is optional. See
the PDF Reference (Version 1.5, Fourth Edition), Section 8.6.6, for more information.

Contents
This reference contains the following:●

AcroForm Objects introduces AcroForm-specific API objects and briefly describes Core
objects that are extensively used in the AcroForm API.

●

AcroForm Methods describes in detail all AcroForm methods, including theirparameters, return value, and related methods.

●

AcroForm Callbacks describes in detail the callback functions.

●

AcroForm Declarations describes in detail the data structures used by the Acrobat
Forms plug-in.

●

AcroForm Macros describes in detail the macros available for use by developers.

●

Text-to-Speech API (Windows only) describes in detail all methods in the Text-to-Speech
API.

Acrobat Forms API Reference15

AcroForm API Reference
Exceptions

Exceptions
All AcroForm methods may return an exception. Possible exceptions are:16

Exception Name

Description

gAFpdErrExportFdf

Error during export of FDF document.

gAFpdErrBadFdf

Invalid FDF document.

gAFfileErrSubmitFdf

Error opening URL to submit this form.

gAFpdErrReqdFld

Required field found empty during export of FDF
document.

Acrobat Forms API ReferenceAcroForm Objects

AcroForm Objects
The PDField object is introduced in the Forms API.

PDField
A PDField is an opaque object representing a field in an Acrobat form.
A PDF document that contains forms has an AcroForm entry in the document catalog
dictionary, which contains an array of references to each of the root fields in the document.
The three most important properties of a field are its type, name, and value. Other
properties specify the appearance of a field. Fields can be organized into a hierarchy, andother field properties associate it with its parent and children.
There is a field dictionary for every PDField. Acrobat uses annotations to represent a
field’s appearance and to manage user interactions. A PDField dictionary may also be anannotation, in which case its subtype is Widget. There is no ambiguity, because the keysof annotations and PDFields do not overlap.

PDFields are not created until needed. This saves memory and enhances performance.
Suppose, for example, a PDF file represents a 100-page catalog, where a purchase order ison the last page. PDFields are not created for all the elements in the purchase orderwhen the document is opened. When the user displays the purchase order, the annotation
handler draws the field announcements and creates the PDFields for form fields.
When the annotation handler creates a PDField, it typically displays a page that contains
the field.

Acrobat Forms API Reference17AcroForm Objects
Core Objects

Co re O b je c t s
These objects are defined in the Acrobat Core API and used by the Forms API. For further
information about these objects, see the Acrobat Core API Reference.

ASAtom
A hashed token used in place of strings to optimize performance (it is much faster tocompare ASAtoms than strings).

ASBoolA boolean value.

ASFileAn opaque representation of an open file.

ASPathName
A file system-specific named location for a particular type of device. Uses the ASFileSys
structure pointers for callback. An ASPathName is specific to a given ASFileSys.

AVDoc
A view of a PDF document in a window. There is one AVDoc per displayed document.
Unlike a PDDoc, an AVDoc has a window associated with it.

CosDocA Cos-level representation of an entire PDF file.

CosObjA general object in a PDF file, which may be of any Cos object type.

18

Acrobat Forms API ReferenceAcroForm Objects
Core Objects

PDAnnot
A structure that defines objects and methods used to manipulate annotations, as per the
logical model defined in the PDF specification.

PDDoc
The underlying PDF representation of a document. There is a correspondence between a
PDDoc and an ASFile; the PDDoc object is the hidden object behind every AVDoc. An
ASFile may have zero or more underlying files, so a PDF file does not always correspondto a single disk file. For example, an ASFile may provide access to PDF data in a database.
Through PDDocs, your application can perform most of the Edit -> Pages menu items fromAcrobat (delete, replace, and so on). You can create and delete thumbnails through thisobject. You can also set and retrieve document information fields through this object aswell. The first page in a PDDoc is page 0.

PDPageA single page in the PDF representation of a document. Just as PDF files are partiallycomposed of their pages, PDDocs are composed of PDPages. A page contains a series ofobjects representing the objects drawn on the page (PDGraphic), a list of resources usedin drawing the page, annotations (PDAnnot), an optional thumbnail image of the page,
and the beads used in any articles that occur on the page. The first page in a PDDoc is page0.

Acrobat Forms API Reference19AcroForm Objects
Core Objects

20

Acrobat Forms API ReferenceAcroForm Methods

AFExecuteThisScript
ASBool AFExecuteThisScript (PDDoc pdd, const char* cScript,
char** pRetValue);
Description
Executes a JavaScript script.
Parameters

pdd

The PDDoc in which the script is to be executed.

cScript

A string containing the text of the script to be executed. If Unicode, thestring must begin with 0xFEFF and end with 2 null bytes. If this is not thecase, it is assumed to be in the application's language encoding, as
returned by AVAppGetLanguageEncoding.

pRetValue

To get a return value from the execution of the script, pass a non- NULL
value for this parameter. If on return *pRetVal is non-NULL, the caller
should dispose of the string by calling ASFree. If present, the value will
be in host encoding.
N O T E : The script sets this value by assigning it to event.value. See

the Acrobat JavaScript Object Specification for more information.
Return Value
The JavaScript value of event.rc. This function pre-initializes it to true; a script may set
it to false if desired.
Header File
AF_Sel.h
ExampleAVDoc avDoc = AVAppGetActiveDoc();
PDDoc pdDoc = AVDocGetPDDoc (avDoc);char * buf = "console.println(\"myName\");";
AFExecuteThisScript(pdDoc, buf, NULL);

Acrobat Forms API Reference21

AcroForm Methods

AFImportAppearance
ASBool AFImportAppearance(CosDoc cd, CosObj *coIcon,
AVDoc avd, char *cTitle);
Description
Opens the dialog box that allows the user to select a PDF to use as the icon for a button.
Parameters

cd

The CosDoc that contains the appearance you are trying to import.

coIconIf AFImportAppearance is successful, coIcon is a pointer to a CosObj
that will contain the Cos representation of the appearance.

avd

The AVDoc that you want the window to be the child of. You can pass NULL
if you do not have an AVDoc.

cTitleThe window title of the dialog box when it appears. You can pass NULL if
you want the title of the dialog to be the same as it is when brought up
through the field properties dialog.

Return Value

true if appearance was imported properly, false otherwise.
Header File
AF_Sel.hRelated Methods
None
ExampleAVDoc avDoc = AVAppGetActiveDoc();
PDDoc pdDoc = AVDocGetPDDoc (avDoc);char ReturnValue[128] = "";char* pReturnValue = ReturnValue;
char* buf = "var rc = app.response({cQuestion: 'What is the company ?',cDefault: 'Adobe'} ); if(rc!=null) event.value=rc;";
ASBool bRc = AFExecuteThisScript (pdDoc, buf, &pReturnValue);if(pReturnValue) {AVAlertNote(pReturnValue)
ASfree(pReturnValue);}

22

Acrobat Forms API ReferenceAcroForm Methods

AFLayoutBordervoid AFLayoutBorder (void* vlayout,
AFPDWidgetBorderRec border, PDColorValue pdcvBrdr,
PDColorValue pdcvBg, ASBool bDown);
Description
Draws a border into the layout context.
Parameters

vlayout

The layout of the annotation. Use AFLayoutNew to create a new layout
before calling this method.

border

A pointer to a structure containing information about the appearance aborder.

pdcvBrdr

A PDColorValue structure representing the color of the annotations
border.

pdcvBg

A PDColorValue structure representing the color of the annotations
background.

bDown

A boolean specifying whether the background should be drawn as it isdrawn in forms while being "pressed” (clicked by the mouse) or not. If
true, draws as if it is a field that is being pressed.

Return Value
None
Header File
AF_Sel.hRelated Methods

AFLayoutNew
ExampleAFLayoutBorder (layout, &border, &pdcvBorder, &pdcvBackground, false);

Acrobat Forms API Reference23

AcroForm Methods

AFLayoutCreateStream
CosObj AFLayoutCreateStream (void* vlayout);
Description
Creates a layout stream that can be used as an annotation appearance.
Parameters

vlayout

The layout of the annotation. Use AFLayoutNew to create a new layout
before calling this method.

Return Value
A stream CosObj.
Header File
AF_Sel.hRelated Methods
AFLayoutNew
AFLayoutDelete
Example// Write the whole thing to a CosStream.
CosObj coStream = AFLayoutCreateStream(layout);
AFLayoutDelete(layout);

24

Acrobat Forms API ReferenceAcroForm Methods

AFLayoutDelete
void AFLayoutDelete (void* vlayout);
Description
Frees the layout context.
Parameters

vlayout

The layout of the annotation to remove.

Return Value
None
Header File
AF_Sel.hRelated Methods

AFLayoutNew
AFLayoutCreateStream
ExampleCosObj coStream = AFLayoutCreateStream(layout);
AFLayoutDelete(layout);

Acrobat Forms API Reference25

AcroForm Methods

AFLayoutNew
void* AFLayoutNew (ASFixedRectP frBbox,
PDRotate annotRotation, CosDoc cd);
Description
Create a new layout context for annotations. Use PDAnnotGetRect to get the
annotation’s bounding box, then use this method to define new layout context.
Parameters

frBboxThe bounding box of the area for text and border data to flow
into.

annotRotation

The rotation of the annotation.

cd

The CosDoc.

Return ValueA new layout.
Header File
AF_Sel.hRelated Methods

AFLayoutBorder
AFLayoutText
AFLayoutCreateStream
ExamplePDAnnotGetRect (theAnnot, &frBBox);void *layout = AFLayoutNew (&frBBox, PDPageGetRotate (pdPage),
theCosDoc);26

Acrobat Forms API ReferenceAcroForm Methods

AFLayoutText
void AFLayoutText (void* vlayout, ASBool bMultline,
ASBool bWrap, AFPDWidgetBorderRec border, TextAppearanceP ta,char* cBytes);
Description
Sets the text layout for the annotation.
NOTE:

Before calling this method, you should call AFLayoutNew to create a new layout,
as well as AFLayoutBorder.

Parameters

vlayout

The layout of the annotation.

bMultline

If true, the text can use multiple lines in a text field. Otherwise, text
is single line.

bWrap

If true, the text will wrap.

border

The border appearance that defines the width and line style of aborder.
The border of the annotation should be the same as in your call to
AFLayoutBorder.

ta

A pointer to structure containing font, point size, and color
information. You should initialize the structure with the
SetDefaultTextAppearanceP macro which defaults to
Helvetica.

cBytes

The text string for the layout.

Return Value
None
Exceptions
Raises an exception if the field is a radio box or button.
Header File
AF_Sel.hRelated Methods

AFLayoutNew
AFLayoutBorder

Acrobat Forms API Reference27

AcroForm Methods

ExamplePDAnnotGetBBox(theAnnot, &frBBox);void *layout = AFLayoutNew(&frBBox, PDPageGetRotate(pdPage), theCosDoc);
AFLayoutBorder(layout, &border, &pdcvBorder, &pdcvBackground, false);
AFLayoutText(layout, true, true, &border, &textAppearance, "Welcome to
AcroForm");

28

Acrobat Forms API ReferenceAcroForm Methods

AFPDDocEnumPDFields
void AFPDDocEnumPDFields (PDDoc doc, ASBool terminals,
ASBool no_repeat, AFPDFieldEnumProc proc, void *clientData);
Description
Enumerates all PDFields that exist in a PDDoc.
Parameters

doc

The PDDoc whose PDFields are enumerated.

terminals

If true, only PDFields without children are enumerated.

no_repeat

If true, then only one instance of a PDField for each name isenumerated.

proc

A user-supplied callback that is called for each PDField. The
enumeration terminates if proc returns false.

clientData

Pointer to user-specified data that is passed to proc each time it iscalled.

Return Value
None
Header File
AF_Sel.h
ExampleAVDoc currentAVDoc;
PDDoc currentPDDoc;
AFPDFieldEnumProc enumProc;
currentAVDoc = AVAppGetActiveDoc ();currentPDDoc = AVDocGetPDDoc (currentAVDoc);/* Set up enumeration */enumProc = ASCallbackCreateProto (AFPDFieldEnumProc, &FieldEnumProc);
AFPDDocEnumPDFields (currentPDDoc, false, false, enumProc, NULL);

Acrobat Forms API Reference29

AcroForm Methods

AFPDDocGetPDFieldFromName
PDField AFPDDocGetPDFieldFromName (PDDoc doc, char* name);
Description
Retrieves a PDField with a given name from a PDDoc. (If multiple fields have the same
name, a change to any of them affects all of them.)
Parameters

doc

The PDDoc containing the field.

name

Name of the field to retrieve.

Return Value
The PDField specified by name. Returns NULL if there is no PDField with the given
name in the PDDoc.
Header File
AF_Sel.hRelated Methods

AFPDFieldGetName

30

Acrobat Forms API ReferenceAcroForm Methods

AFPDDocLoadPDFields
void AFPDDocLoadPDFields (PDDoc doc);
Description
Makes sure every PDField in the given PDDoc exists.
NOTE:

It is no longer necessary to call this method. It still exists for backwards
compatibility, but its purpose is now automatically taken care of internally.

Parameters

doc

The PDDoc for the form whose PDFields are loaded.

Return Value
None
Header File
AF_Sel.h

Acrobat Forms API Reference

31AcroForm Methods

AFPDFieldFromCosObj
PDField AFPDFieldFromCosObj (CosObj dict);
Description
Retrieves the PDField object for which a Cos object is the dictionary.
Parameters

dict

The Cos object for which to retrieve the corresponding PDField object.

Return Value
The PDField corresponding to dict. Returns NULL if the Cos object is not a PDField.
Header File
AF_Sel.hRelated Methods

AFPDFieldGetCosObj
ExamplePDAnnot anAnnotation;
CosObj annotCosObj;
PDField annotField;/* Get PDField for Cos object */annotCosObj = PDAnnotGetCosObj (anAnnotation);annotField = AFPDFieldFromCosObj (annotCosObj);

32

Acrobat Forms API ReferenceAcroForm Methods

AFPDFieldGetCosObj
CosObj AFPDFieldGetCosObj (PDField fldP);
Description
Retrieves the Cos object which is the field object of a PDField object.
Parameters

fldP

The PDField object for which to retrieve the corresponding Cos object.

Return Value
Cos object corresponding to the PDField object fldP.
Header File
AF_Sel.hRelated Methods

AFPDFieldGetCosObj
AFPDFieldGetDefaultTextAppearance
AFPDFieldGetName
AFPDFieldGetValue
ExamplePDField fldP;
CosObj fieldCosObject;
if (AFPDFieldIsValid (fldP)) {/* Get Cos Object for field */fieldCosObject = AFPDFieldGetCosObj (fldP);

Acrobat Forms API Reference33

AcroForm Methods

AFPDFieldGetDefaultTextAppearance
void AFPDFieldGetDefaultTextAppearance (PDField fldP,
TextAppearanceP aP);
Description
Gets the default text appearance of a field. Use this method to get the font, size, color, andso forth—values that were set through the field properties dialog box.
Parameters

fldP

The PDField object for which to retrieve the text appearance.

aP

A pointer to a structure describing the text appearance. Returns text matrix,
quadding, text color, and so forth.

Return Value
None
Header File
AF_Sel.hRelated Methods

AFPDWidgetSetAreaColors

34

Acrobat Forms API ReferenceAcroForm Methods

AFPDFieldGetFlags
ASUns32 AFPDFieldGetFlags (PDField fldP, AF_Flags_t flagType);
Description
Retrieves the flags of a PDField for a given flag type.
Parameters

fldP

The PDField whose flags are obtained.

flagType

Type of flags to obtain.

Return Value
The value of flags of flagType.
Header File
AF_Sel.hRelated Methods

AFPDFieldGetName
AFPDFieldGetValue
AFPDFieldSetFlags

Acrobat Forms API Reference35

AcroForm Methods

AFPDFieldGetName
char* AFPDFieldGetName (PDField fldP);
Description
Gets the name of a PDField object.
Parameters
The PDField whose name is retrieved.

fldP
Return ValueA C program NULL-terminated string.
NOTE:

Do not modify or free this string. To use this string indefinitely, copy it to a private
buffer.

Header File
AF_Sel.hRelated Methods

AFPDFieldGetDefaultTextAppearance
AFPDFieldGetValue
ExamplePDField fldP;
char *fieldName;
fieldName = AFPDFieldGetName (fldP);

36

Acrobat Forms API ReferenceAcroForm Methods

AFPDFieldGetValue
CosObj AFPDFieldGetValue (PDField fldP);
Description
Retrieves the value from a PDField. The value is stored in the field entry with the V key.
Values can be inherited. If a PDField Cos object does not have a V key, its value isinherited from a parent’s V key (the parent must have the same name as the PDField). For
example, radio buttons inherit values this way.
NOTE:

Retrieving the value of a radio button or combo box requires Cos-level
programming. See the PDF Reference for details.

Parameters

fldP

The PDField whose value is retrieved.

Return Value
The value of the field as a CosObj. If the field has no value, a NULL CosObj is returned.
Header File
AF_Sel.hRelated Methods

AFPDFieldGetCosObj
AFPDFieldGetDefaultTextAppearance
AFPDFieldGetName
AFPDFieldSetValue
ExampleThis example shows how to obtain the string value of an encoded string from the CosObj.
PDField fldP;
CosObj fieldCosValue = AFPDFieldGetValue(fldP);
char *fieldValue = CosCopyStringValue(fieldCosValue, NULL);
ASText asText = ASTextFromPDText(fieldValue);char *realField = ASTextGetEncodedCopy(asText,(ASHostEncoding)PDGetHostEncoding());

Acrobat Forms API Reference37AcroForm Methods

AFPDFieldIsAnnot
ASBool AFPDFieldIsAnnot (PDField fldP);
Description
Determines whether or not a PDField is an annotation (PDAnnot), that is, whether thefield dictionary is also an annotation. If this is the case, the value of Subtype is Widget.
Parameters

fldP

The field in question.

Return Value

true if the PDField is an Acrobat annotation, false otherwise.
Header File
CosField.hRelated Methods

AFPDFieldIsTerminal
AFPDFieldIsValid
ExamplePDField fldP;
if (AFPDFieldIsAnnot (fldP)) {/* Process annotation */38

Acrobat Forms API ReferenceAcroForm Methods

AFPDFieldIsTerminal
ASBool AFPDFieldIsTerminal (PDField fldP);
Description
Determines whether a field is terminal: the field has no children or it has the same name asits children.
Parameters

fldP

The PDField to test.

Return Value
If true, fldP is valid and all its children (if any) have the same name as fldP. Otherwise
all have unique names.
Header File
AF_Sel.hRelated Methods

AFPDFieldIsAnnot
AFPDFieldIsValid
ExamplePDField fldP;
if (AFPDFieldIsTerminal (fldP)) {/* Process field */Acrobat Forms API Reference

39

AcroForm Methods

AFPDFieldIsValid
ASBool AFPDFieldIsValid (PDField fldP);
Description
Determines whether a field is valid or not.
NOTE:This method is intended only to ensure that the field has not been deleted, not toensure that all necessary information is present and the field has valid values.

Parameters

fldP

The field to test.

Return Value

true if fldP is a valid PDField; false otherwise.
Header File
AF_Sel.hRelated Methods

AFPDFieldIsAnnot
AFPDFieldIsTerminal
ExamplePDField fldP;
if (AFPDFieldIsValid (fldP)) {/* Process field */}40

Acrobat Forms API ReferenceAcroForm Methods

AFPDFieldResetvoid AFPDFieldReset (PDField fldP);
Description
Sets a PDField’s value to its default state. This is the value associated with the DV key forthe field. If there is no DV key for the field, set the field’s value to the NULL Cos object; or, if
the field has options, the default DV is the first element of the Opt array.
A DV entry’s value can be inherited from a parent (just like V).
The PDField’s value is set only if it is terminal; see AFPDFieldIsTerminal.
Parameters

fldP

The PDField to reset.

Return Value
None
Header File
AF_Sel.hRelated Methods

ResetForm
ExampleAVDoc currentAVDoc;
PDField annotField;/* Remove current field selection, so selected field is operated on */currentAVDoc = AVAppGetActiveDoc ();AFPDFieldReset (annotField);

Acrobat Forms API Reference41

AcroForm Methods

AFPDFieldSetDefaultTextAppearance
void AFPDFieldSetDefaultTextAppearance(PDField fldP,
TextAppearanceP aP);
Description
Sets the default text appearance of a field. Use this method to set the font, size, color, andso forth.
Parameters

fldP

The PDField object for which to set the text appearance.

aP

A pointer to a structure describing the text appearance to set.

Return Value
None
Header File
AF_Sel.hRelated Methods

AFPDWidgetSetAreaColors

42

Acrobat Forms API ReferenceAcroForm Methods

AFPDFieldSetFlags
void AFPDFieldSetFlags (PDField fldP, AF_Flags_t flagType,AFPDFieldFlags_t flags);
Description
Sets the flags of type flagType for a PDField.
The flags of a field’s children (if any) are also set.
Parameters

fldP

The PDField for which to set flags and children’s flags.

flagType

The type of the flags to set. If flagType is Flags_Annot and the
PDField is not an annotation, no flags are changed.

flags

The value of the flags.

Return Value
None
Header File
AF_Sel.hRelated Methods

AFPDFieldGetDefaultTextAppearance
AFPDFieldSetOptions
AFPDFieldSetValue

Acrobat Forms API Reference43AcroForm Methods

AFPDFieldSetOptions
RetCode AFPDFieldSetOptions (PDField fldP, CosObj array);Description
Sets the options entry for a field. The options entry has the key Opt and represents a list of
options for a choice field.
If the field is not valid, remove the options entry.
Parameters

fldP

The PDField whose options are set.

array

The value to set in the options entry.

Return Value

Good if the operation succeeded, Bad otherwise.
Header File
AF_Sel.hRelated Methods

AFPDFieldSetFlags
AFPDFieldSetValue
Exampleconst char cOption1[] = "Blue";
const char cOption2[] = "Red";
CosObj coOpts = CosNewArray(cd, false, 2);
CosObj coOpt = CosNewString(cd, false, cOption1, strlen(cOption1));
CosArrayPut(coOpts, 0, coOpt);
coOpt = CosNewString(cd, false, cOption2, strlen(cOption2));
CosArrayPut(coOpts, 1, coOpt);
AFPDFieldSetOptions(coOpts);

44

Acrobat Forms API ReferenceAcroForm Methods

AFPDFieldSetValue
void AFPDFieldSetValue (PDField fldP, CosObj val);
Description
Sets the value for a PDField. The value is stored in the field entry with the V key. Updates
the display of the field and its namesakes; that is, fields with the same fully qualified names,
if any. Changing the field dictionary’s value for the V entry directly does not change theappearance of the field, which is represented by the AP key.
NOTE:

Setting the value of a radio button or combo box requires Cos-level programming.
See the PDF Reference for details.

Parameters

fldP

The field whose value is set.

val

The field’s new value. If it is different than the previous value, all previous
instances of value keys (V) in the field’s dictionary and those of its namesakes(fields with the same fully qualified name) are removed.

Return Value
None
Header File
AF_Sel.hRelated Methods

AFPDFieldGetValue
AFPDFieldSetFlags
AFPDFieldSetOptions
ExamplePDField fldP;
CosDoc currentCosDoc;
CosObj cosObject, newString;char *fieldName;
ASInt32 fieldNameLength;cosObject = AFPDFieldGetCosObj (fldP);
currentCosDoc = CosObjGetDoc (cosObject);fieldName = AFPDFieldGetName (fldP);
fieldNameLength = strlen (fieldName);
newString = CosNewString (currentCosDoc, false, fieldName,
fieldNameLength);
AFPDFieldSetValue (fldP, newString);

Acrobat Forms API Reference45

AcroForm Methods

AFPDFormFromPage
CosObj AFPDFormFromPage (CosDoc cd, PDPage pdp);
Description
Creates an XObject form from a PDF page. A form XObject is a content stream that can betreated as a single graphics object. Use this method for importing PDF graphics into
documents.
Parameters

cd

The CosDoc that the XObject will be created in.

pdp

The PDPage that you want to create the XObject from.

Return ValueA Cos object pointing to the XObject on the PDF page.
Header File
AF_Sel.hRelated Methods
None

46

Acrobat Forms API ReferenceAcroForm Methods

AFPDWidgetGetAreaColors
void AFPDWidgetGetAreaColors(PDAnnot pdan,
PDColorValue borderP, PDColorValue bkgndP);
Description
Gets the border and background colors of an annotation.
Parameterspdan

The annotation.

borderP(Filled by the method) A pointer to a structure representing the border colorof the annotation.

bkgndP(Filled by the method) A pointer to a structure representing the backgroundcolor of the annotation.

Return Value
None
Header File
AF_Sel.hRelated Methods

AFPDWidgetSetAreaColors

Acrobat Forms API Reference47

AcroForm Methods

AFPDWidgetGetBorder
ASBool AFPDWidgetGetBorder(PDAnnot pdan,
AFPDWidgetBorderRec pdwb);
Description
Gets the border of an annotation.
Parameterspdan

The annotation.

pdwb(Filled by the method) A pointer to a structure describing the form fieldappearance definitions for the outside border of an annotation.

Return Value

true if successful getting border, false otherwise.
Header File
AF_Sel.hRelated Methods

AFPDWidgetSetAreaColors

48

Acrobat Forms API ReferenceAcroForm Methods

AFPDWidgetGetRotation
ASAtom AFPDWidgetGetRotation (PDAnnot pdan);Description
Gets the rotation of the annotation.
Parameterspdan

The annotation widget.

Return Value
Returns a ASAtom object representing the annotation’s rotation with respect to the page.
Header File
AF_Sel.hRelated Methods
None

Acrobat Forms API Reference49

AcroForm Methods

AFPDWidgetSetAreaColors
void AFPDWidgetSetAreaColors(PDAnnot pdan,
PDColorValue borderP, PDColorValue bkgndP);
Description
Sets the border and background color of the annotation.
Parameterspdan

The annotation.

borderP

A pointer to a structure representing the border color of the annotation.

bkgndP

A pointer to a structure representing the background color of theannotation.

Return Value
None
Header File
AF_Sel.hRelated Methods

AFPDWidgetGetAreaColors

50

Acrobat Forms API ReferenceAcroForm Methods

AFPDWidgetSetBordervoid AFPDWidgetSetBorder(PDAnnot pdan,
AFPDWidgetBorderRec pdwb);
Description
Sets the border of an annotation.
Parameterspdan

The annotation whose change border appearance will be set.

pdwb

A pointer to a structure describing the form field appearance
definitions for the outside border of an annotation. Possible bordertypes are solid, dashed, beveled, inset, underline.

Return Value
None
Header File
AF_Sel.hRelated Methods

AFPDWidgetSetAreaColors

Acrobat Forms API Reference51

AcroForm Methods

AssembleFormAndImportFDF
PDDoc AssembleFormAndImportFDF (PDDoc pdCurrForm,
CosDoc cdFDF, ASBool bAddToCurr);
Description
Constructs an Acrobat form from templates and imports an FDF file.
Parameters

pdCurrform

The current form being viewed, if any, at the time cdFDF is being
imported. This parameter can be NULL; if not NULL, then cdFDF
can refer to templates in the current form, by omitting the F key in
the TRef dictionary. Even if the F key is not NULL, it can be a relative
path (as opposed to an absolute path), as long as pdCurrForm is
not NULL.

cdFDF

The FDF file being imported.

bAddToCurr

If true (and pdCurrForm is not NULL), then instead of creating a
new form, the templates spawn pages that are appended at the endof pdCurrForm (and the function returns pdCurrForm).

Return Value
The PDDoc for the newly-created form (or pdCurrForm, if bAddToCurr is true).
Header File
AF_Sel.hRelated Methods

ExportAsFDF
ExportAsFDFEx
ExportAsFDFWithParams
ImportAnFDF
ExampleCosObj dictFDF = CosDictGet(CosDocGetRoot(cdFDF), FDF_K);
if (CosObjGetType(CosDictGet(dictFDF, Pages_K)) == CosArray)
AssembleFormAndImportFDF(0/*no current doc is open*/, cdFDF, false);

52

Acrobat Forms API ReferenceAcroForm Methods

ExportAsFDF
CosDoc ExportAsFDF (PDDoc pdForm, CosObj rgIncExcFlds,
ASBool bIncl, ASBool bEmpty, ASBool bMenu, ASBool bLoadFields,
ASPathName fdfPath);
Description
Exports form data to a CosDoc, which can be written to an FDF file. See the PDF Reference
for a description of this format.
To create an FDF file from this CosDoc, call the Core API method CosDocSaveToFile.
NOTE:

ExportAsFDFWithParams provides the same functionality with additional
options.

Parameters

pdFormThe PDDoc for the form for which we want to export the data.

rgIncExcFlds

If rgIncExcFlds is CosNewNull, then all fields are exported,and bIncl is ignored. If rgIncExcFlds is a CosArray, then thearray elements may be:a) names of fields (the names may be of non-terminal fields, which isa fast and easy way to cause all their children to be included in the
FDF file).
b) arrays, whose first element is a field name, and the rest of theelements are field dictionary key names whose values should beexported in the FDF file.
For example: [ (My listbox) /AP /Opt ].
This variety of rgIncExcFlds array element can only be used if
bIncl is true (see below).
c) If rgIncExcFlds contains a single element, which is itself anarray as described in b) above, and its first element, whichcorresponds to the field name, is NULL, then the FDF file will include
the requested field properties of all fields. For example:[ null /F /Ff ].

bIncl

If true, rgIncExcFlds is an array of the fields to export.
Otherwise, rgIncExcFlds is an array of the fields to exclude fromexporting.

bEmptyIf true, all fields selected per the above criteria are exported. If
false, exclude fields that have no value.

bMenu

If true, suppresses saving text fields that have the "password” flagset, and does not force filling-in required fields when creating an
FDF file.

Acrobat Forms API Reference53

AcroForm Methods

bLoadFields

Not used.

fdfPathThe path where the FDF file will be saved (by the client ofExportAsFDF) after it is produced. You need this in order to create
an FDF file with an F key that gives the relative path to the form,
from the location where the FDF file will be saved. Pass NULL if anabsolute pathname is desired.

Return Value
The FDF CosDoc containing the exported data.
Exceptions
Raises gAFpdErrExportFdf if it cannot export field data. The viewer may raise otherexceptions.
Header File
AF_Sel.hRelated Methods

ExportAsFDFEx
ExportAsFDFWithParams
ImportAnFDF
AssembleFormAndImportFDF
Example/* Export all fields to CosDoc */cosDoc = ExportAsFDF (currentPDDoc, rgFld, true, true, false, false,
NULL);

54

Acrobat Forms API ReferenceAcroForm Methods

ExportAsFDFEx
CosDoc ExportAsFDFEx (PDDoc pdForm, CosObj rgIncExcFlds,
ASBool bIncl, ASBool bEmpty, ASBool bMenu, ASBool bLoadFields,
ASPathName fdfPath, const char* submitBtnName);
Description
Exports form data to a CosDoc, which can be written to an FDF file. See the PDF Reference
for a description of this format.
To create an FDF file from this CosDoc, call the Acrobat viewer plug-in API method
CosDocSaveToFile.
NOTE:

This method is the same as ExportAsFDF, with the exception of the additionalparameter submitBtnName. ExportAsFDFWithParams provides the samefunctionality with additional options.

Parameters

pdFormA PDDoc for the form whose data is exported.

rgIncExcFlds

If rgIncExcFlds is CosNewNull, then all fields areexported, and bIncl is ignored. If rgIncExcFlds is a
CosArray, then the array elements may be:a) names of fields (the names may be of non-terminal fields,
which is a fast and easy way to cause all their children to be
included in the FDF file).
b) arrays, whose first element is a field name, and the rest of theelements are field dictionary key names whose values should beexported in the FDF file.
For example: [ (My listbox) /AP /Opt ].
This variety of rgIncExcFlds array element can only be used
if bIncl is true (see below).
c) If rgIncExcFlds contains a single element, which is itself
an array as described in b) above, and its first element, whichcorresponds to the field name, is NULL, then the FDF file will
include the requested field properties of all fields. For example:[ null /F /Ff ].

bIncl

If true, rgIncExcFlds is an array of the fields to export.
Otherwise, rgIncExcFlds is an array of the fields to exclude
from exporting.

bEmptyIf true, all fields selected per the above criteria are exported. If
false, exclude fields that have no value.

Acrobat Forms API Reference55

AcroForm MethodsbMenu

If true, suppresses saving text fields that have the "password”
flag set, and doesn’t force filling-in required fields when creating
an FDF file.

bLoadFields

Not used.

fdfPathThe path where the FDF file will be saved after it is produced.
You need this in order to create an FDF file with an F key thatgives the relative path to the form, from the location where the
FDF file will be saved. Pass NULL if an absolute pathname isdesired.

submitBtnName

A NULL-terminated string containing the name of the button
used to submit. If the value passed is not NULL, then the FDF
file will include a field dictionary corresponding to the submit
button, which will only contain one key, namely T.
N O T E : This dictionary is no different than the one you get whenan AcroForm has an empty text field (that is, no value),and parameter bEmpty is true.
Return Value
The FDF CosDoc containing the exported data.
Exceptions
Raises gAFpdErrExportFdf if it cannot export field data. The viewer may raise otherexceptions.
Header File
AF_Sel.hRelated Methods

ExportAsFDF
ExportAsFDFWithParams
ImportAnFDF
AssembleFormAndImportFDF
Example/* Export all fields to CosDoc */cosDoc = ExportAsFDFEx (currentPDDoc, rgFld, true, true, false, false,
NULL, NULL);

56

Acrobat Forms API ReferenceAcroForm Methods

ExportAsFDFWithParams
CosDoc ExportAsFDFWithParams (ExportAsFDFParamsRec params);
Description
Exports form data to a CosDoc, which can be written to an FDF file. See the PDF Reference
for a description of this format.
ParametersparamsAn ExportAsFDFParamsRec structure.

Return Value
The FDF CosDoc containing the exported data.
NOTE:

Call CosDocSaveToFile to create an FDF file from this CosDoc.

Exceptions
Raises gAFpdErrExportFdf if cannot export field data. The viewer may raise otherexceptions.
Header File
AF_Sel.hRelated Methods

ExportAsFDF
ExportAsFDFEx
ImportAnFDF
AssembleFormAndImportFDF

Acrobat Forms API Reference57

AcroForm Methods

ExportAsHtml
void ExportAsHtml (PDDoc formPD, CosObj rgIncExcFlds,
ASBool bIncl, ASBool bEmpty, ASFile Hfile);
Description
Exports data from a form to a file in HTML format.
Parameters

formPD

The PDDoc for the form whose data is exported.

rgIncExcFlds

If rgIncExcFlds is CosNewNull, then all fields are exported, andbIncl is ignored. If it is a CosArray, then the array elements must
be indirect references to field dictionaries.

bIncl

If true, rgIncExcFlds is an array of the fields to export.
Otherwise, rgIncExcFlds is an array of the fields to exclude fromexporting.

bEmptyIf true, all fields selected per the above criteria are exported. If
false, exclude fields that have no value.

Hfile

File to which the HTML data is written.

Return Value
None
Header File
AF_Sel.hRelated Methods

ExportAsHtmlEx

58

Acrobat Forms API ReferenceAcroForm Methods

ExportAsHtmlEx
void ExportAsHtmlEx (PDDoc pdForm, CosObj rgIncExcFlds,
ASBool bIncl, ASBool bEmpty, ASFile Hfile,const char* submitBtnName);
Description
Exports data from a form to a file in HTML format.
NOTE:

This method is the same as ExportAsHtml, with the exception of the additionalparameter submitBtnName.

Parameters

pdFormThe PDDoc for the form whose data is exported.

rgIncExcFlds

If rgIncExcFlds is CosNewNull, then all fields areexported, and bIncl is ignored. If it is a CosArray, then thearray elements must be names of fields. The names may be of
non-terminal fields, which is a fast and easy way to cause all
their children to be exported.

bIncl

If true, rgIncExcFlds is an array of the fields to export.
Otherwise, rgIncExcFlds is an array of the fields to exclude
from exporting.

bEmptyIf true, all fields selected per the above criteria are exported. If
false, exclude fields that have no value.

Hfile

File to which the HTML data is written.

submitBtnName

A NULL-terminated string containing the name of the button
used to submit. If the value passed is not NULL, then include"...&submitBtnName=&..." as part of the generated xwww-form-urlencoded output.
N O T E : This type of output is the same one you get when an

AcroForm has an empty text field (that is, no Value), andparameter bEmpty is true.
Return Value
None
Header File
AF_Sel.h

Acrobat Forms API Reference59AcroForm Methods

Related Methods

ExportAsHtml
ImportAnFDF

60

Acrobat Forms API ReferenceAcroForm Methods

ImportAnFDF
ASBool ImportAnFDF (PDDoc pdForm, CosDoc cdFDF);
Description
Imports data from an FDF file into a PDDoc’s form. See the PDF Reference for a descriptionof this format.
Parameters

pdFormThe PDDoc for the form into which we want to import the data.

cdFDF

The CosDoc for the FDF file containing the data.

Return Value

true if the fields in the FDF file only contained values or flags (that is, V, F, Ff, ClrF, ClrFf,
SetF, SetFf ), false if any field contained other attributes, such as appearances (that is,AP), actions (that is, A), and so forth.
Exceptions
Raises gAFpdErrBadFdf if the FDF file is invalid.
Raises an exception if memory cannot be allocated for FDF file data.
Header File
AF_Sel.hRelated Methods

AssembleFormAndImportFDF
ExportAsFDF
ExportAsFDFEx
ExportAsFDFWithParams

Acrobat Forms API Reference61

AcroForm Methods

IsPDDocAcroForm
ASBool IsPDDocAcroForm (PDDoc doc);
Description
Indicates whether a PDDoc contains an Acrobat form.
Parameters

doc

The PDDoc to test.

Return Value

true if doc contains a form, false otherwise.
Header File
AcroForm.h
Related Methods

AFPDFieldIsValid
Example/* Return true if active doc has form */if ((avDoc = AVAppGetActiveDoc ()) != NULL)
return IsPDDocAcroForm (AVDocGetPDDoc (avDoc));

62

Acrobat Forms API ReferenceAcroForm Methods

ResetFormvoid ResetForm (PDDoc formPD, CosObj rgIncExcFlds,
ASBool bIncl);
Description
Resets the indicated fields of a PDDoc’s form to their default values.
A PDField’s value is reset only if it is terminal; see AFPDFieldIsTerminal.
Parameters

formPD

The PDDoc for the form whose fields are reset.

rgIncExcFlds

If rgIncExcFlds is CosNewNull, then all fields are reset, andbIncl is ignored. If it is a CosArray, then the array elements must
be names of fields. The names may be of non-terminal fields, which
is a fast and easy way to cause all their children to be reset.

bIncl

If true, rgIncExcFlds is an array of the fields to reset. Otherwise,
rgIncExcFlds is an array of the fields to exclude from resetting.

Return Value
None
Header File
AF_Sel.hRelated Methods

AFPDFieldSetDefaultTextAppearance
ExampleAVDoc currentAVDoc;
PDDoc currentPDDoc;
CosObj rgFld = CosNewNull ();ResetForm (currentPDDoc, rgFld, (ASBool)true);

Acrobat Forms API Reference63AcroForm Methods

64

Acrobat Forms API ReferenceAcroForm Callbacks

AFPDFieldEnumProc
ACCB1 ASBool ACCB2 AFPDFieldEnumProc (PDField fldP,
void *clientData);
Description
Callback used by AFPDDocEnumPDFields. It is called once for each PDField in a form.
Parameters

fldP

The PDField currently being enumerated.

clientData User-supplied data passed in the call to AFPDDocEnumPDFields.
Return Value

true to continue the enumeration, false to halt enumeration.
Header File
AF_ExpT.h
Related Methods

AFPDDocEnumPDFields

Acrobat Forms API Reference65AcroForm Callbacks

66

Acrobat Forms API ReferenceAcroForm Declarations

This chapter describes the data types and declarations used in the AcroForms API.
●

AcroForm Data Types●

Core Data Types

AcroForm Data Types
The following are data type and values defined in the AcroForms API.

AF_Flags_t
typedef enum {Flags_Annot,
Flags_Field,
SetFlagsAnnot,
ClrFlagsAnnot,
SetFlagsField,
ClrFlagsField,/* new in Acrobat 6.0 */FlagsIgnore} AF_Flags_t;
Description
The type of flag to be set in AFPDFieldSetFlags.
If Flags_Annot, SetFlagsAnnot, or ClrFlagsAnnot are specified and the
PDField is not an annotation, no flags are changed. See the PDF Reference for more
information on flags used for annotations.
ValuesFlags_Annot

Sets the flags defined in the F key of the annotation to thevalues specified in the flags parameter of
AFPDFieldSetFlags.

Flags_Field

Sets the flags defined in the Ff key of the form field to thevalues specified in the flags parameter of
AFPDFieldSetFlags.

Acrobat Forms API Reference67

AcroForm Declarations
AcroForm Data Types

SetFlagsAnnot

Sets the bits in the flags to those that are 1s in the flags
parameter of AFPDFieldSetFlags.

ClrFlagsAnnot

Clears the bits in the flags to those that are 1s in the flags
parameter of AFPDFieldSetFlags.

SetFlagsField

Sets the bits in the flags to those that are 1s in the flags
parameter of AFPDFieldSetFlags.

ClrFlagsField

Clears the bits in the flags to those that are 1s in the flags
parameter of AFPDFieldSetFlags.

FlagsIgnore

Does not change any flags for the field or annotation.

Header File
AF_ExpT.h
Related Methods

AFPDFieldSetFlags

68

Acrobat Forms API ReferenceAcroForm Declarations
AcroForm Data Types

AFPDFieldBorder
typedef AFPDWidgetBorderRec AFPDFieldBorder;
Description
Field Border data type.
Header File
AF_ExpT.h
Related Methods

AFLayoutBorder
AFLayoutText
AFPDWidgetGetBorder
AFPDWidgetSetBorder

Acrobat Forms API Reference69

AcroForm Declarations
AcroForm Data Types

AFPDFieldFlags_t
typedef ASUns32 AFPDFieldFlags_t;
Description
Used for the value of flags set by AFPDFieldSetFlags.
Header File
AF_ExpT.h
Related Methods

AFPDFieldSetFlags

70

Acrobat Forms API ReferenceAcroForm Declarations
AcroForm Data Types

AFPDWidgetBorder
AFPDWidgetBorderRec
typedef struct _AFPDWidgetBorderRec {AFPDWidgetBorderStyle nStyle;
ASInt32 nWidth;} AFPDWidgetBorderRec; *AFPDWidgetBorder
Description
Form field appearance definitions for the outside border of an annotation.
Members

nStyleStyle of the border. Possible types are solid, dashed, beveled, inset,
underline. See AFPDWidgetBorderStyle.

nWidthWidth of the border.

Header File
AF_ExpT.h
Related Methods

AFLayoutBorder
AFLayoutText
AFPDWidgetGetBorder
AFPDWidgetSetBorder

Acrobat Forms API Reference71AcroForm Declarations
AcroForm Data Types

AFPDWidgetBorderStyle
typedef enum {AFPDWBSolid,
AFPDWBDashed,
AFPDWBBeveled,
AFPDWBInset,
AFPDWBUnderline,
AFPDWPInvalid} AFPDWidgetBorderStyle;Description
Form field appearance definitions for the outside border of an annotation.
Values

AFPDWBSolid

Strokes the entire perimeter of the widget with a solid line.

AFPDWBDashed

Strokes the entire perimeter of the widget with a dashed line.

AFPDWBBeveled

Equivalent to AFPDWBSolid style with an additional beveled(pushed-out appearance) border applied inside the solidborder.

AFPDWBInset

Equivalent to AFPDWBBeveled style with an additional
beveled (pushed-in appearance) border applied inside thesolid border.

AFPDWBUnderline

Strokes the bottom portion of the widget with a underline
styled line.

AFPDWBInvalid

Do not change border.

Header File
AF_ExpT.h
Related Methods

AFLayoutBorder72

Acrobat Forms API ReferenceAcroForm Declarations
AcroForm Data Types

ExportAsFDFParams
ExportAsFDFParamsRec
typedef struct _t_ExportAsFDFParams {ASSize_t size;
AVDoc avForm;
PDDoc pdForm;
CosObj rgIncExcFlds;
ASBool bIncl;
ASBool bEmpty;
ASBool bExcludePasswd;
ASBool bCheckReqd;
ASAtom asaEncoding;
ASPathName fdfPath;char* submitBtnName;} ExportAsFDFParamsRec;
Description
A parameter block used in the call to ExportAsFDFWithParams.
Memberssize

Size of the data structure. Must be set to sizeof(ExportAsFDFParamsRec).

avFormThe AVDoc for the form from which you want to export the data.
You can pass NULL if the document does not have an AVDoc(that is, it is open only at the PD level).

pdFormThe PDDoc for the form from which you want to export the data.

Acrobat Forms API Reference73

AcroForm Declarations
AcroForm Data Types74

rgIncExcFlds

If rgIncExcFlds is CosNewNull, then all fields are exported,and bIncl is ignored. If it is a CosArray, then the arrayelements may be:● Names of fields (the names may be of non-terminal fields,
which is a fast and easy way to cause all their children to be
included in the FDF file).
● Arrays, whose first element is a field name, and the rest of theelements are field dictionary key names whose values should
be exported in the FDF file. For example, [(My listbox) /AP/Opt].
● If rgIncExcFlds contains a single element, which is itself
an array as described in b) above, and its first element, whichcorresponds to the field name, is NULL, then the FDF will
include the requested field properties of all fields. For
example: [ null /F /Ff ].
This variety of rgIncExcFlds array element can only be used
if bIncl is true.

bIncl

If true, then rgIncExcFlds is an array of the fields to export.
Otherwise, it is an array of the fields to exclude from exporting.

bEmptyIf true, then all fields selected per the criteria above areexported. Otherwise, exclude those that have no value.

bExcludePasswd

If true, will not include in the FDF text fields that have the"password” flag set.

bCheckReqd

If true, an alert pops up if any required field is empty.

asaEncoding

Encoding to use in the produced FDF file for the value of the V
entry when it is a string. If ASAtomNull gets passed, then
ExportAsFDF will determine which encoding to use. If
PDFDocEncoding is passed, then do not do any encoding
conversions and simply send V as is (which means, as
PDFDocEncoding or Unicode).
Other allowed values are Shift_JIS, BigFive, GBK, andUHC.

fdfPathPath where the FDF file will be saved (by the client) after it isproduced (by ExportAsFDFWithParams). You need this inorder to create an FDF file with an /F key that gives the relative
path to the form, from the location where the FDF file will besaved. Pass NULL if you want an absolute pathname.

Acrobat Forms API ReferenceAcroForm Declarations
AcroForm Data Types

submitBtnName

A NULL-terminated string containing the name of the button
used to submit. If the value passed is not NULL, then the FDF file
will include a field dictionary corresponding to the submit
button, which will only contain one key, namely /T. Thisdictionary is no different than the one you get when an
AcroForm has an empty text field (that is, no Value), andbEmpty is true.

Header File
AF_ExpT.h
Related Methods

ExportAsFDFWithParams

Acrobat Forms API Reference75

AcroForm Declarations
AcroForm Data Types

RetCodetypedef enum {
Good,
Bad,
Failed} RetCode;Description
A return code from functions.
ValuesGood

Indicates success.

Bad

Indicates possible parameter problem or other exception.

FailedIndicates a failure.

Header File
AF_ExpT.h
Related Methods

AFPDFieldSetOptions

76

Acrobat Forms API ReferenceAcroForm Declarations
AcroForm Data Types

TextAppearance
TextAppearanceP
typedef struct TextAppearance_t {ASFixed charSpacing;
ASFixed wordSpacing;
ASFixed horizontalScale;
ASFixed leading;
ASFixed textRise;
ASFixed textSize;
ASFixedMatrix textMatrix;
PDColorValueRec strokeColor;
PDColorValueRec fillColor;
ASUns16 renderMode;
ASUns16 quadding;
ASAtom baseFont;
ASAtom nameFont;} *TextAppearanceP;
Description
A structure containing information about the text appearance of a field.
Members

charSpacing

The spacing between characters.

wordSpacing

The spacing between words.

horizontalScale

Horizontal scale.

leading

Leading.

textRise

Text rise.

textSize

Point size of text. When fixedZero, enables text autosizing.

textMatrix

Font matrix.

strokeColorPen color.

fillColor

Fill color.

renderMode

Mode.

quadding

Text justification.

Acrobat Forms API Reference77AcroForm Declarations
AcroForm Data Types

baseFont

Default font name.

nameFont

Current font name.

Header File
AF_ExpT.h
Related Methods

AFLayoutText
Related Macros

Init_TextAppearanceP78

Acrobat Forms API ReferenceAcroForm Declarations
Core Data Types

Co re D at a Ty p e s
The following are data types from the Core API that are used in the AcroForms API.

PDColorSpaceConstants that specify the color space in which a color value is specified (for example, RGB
or grayscale).
Members

PDDeviceGray

Grayscale. Requires 1 value entry to specify the color.

PDDeviceRGB

Red–Green–Blue color specification. Requires 3 value entries tospecify the color.

PDDeviceCMYK

Cyan–Magenta–Yellow–Black color specification. Requires 4
value entries to specify the color.

Related Structures

PDColorValue

Acrobat Forms API Reference79AcroForm Declarations
Core Data Types

PDColorValue
PDColorValueRec
Data structure representing a color.

typedef struct _t_PDColorValueRec {PDColorSpace space;
ASFixed value[4];} PDColorValueRec, *PDColorValue;
Members

space

The color space.

value

The color value. The number of elements needed in the value
field depends on the color space type specified in the space field.

Related Structures

TextAppearanceP
Related Methods

AFLayoutBorder
AFPDWidgetGetAreaColors
AFPDWidgetSetAreaColors

80

Acrobat Forms API ReferenceAcroForm Declarations
Core Data Types

PDRotate
Constant values that specify page rotation, in degrees. Used for routines that set and get
the value of a page's Rotate key.

typedef ASEnum16 PDRotate;enum {
pdRotate0 = 0,
pdRotate90 = 90,
pdRotate180 = 180,
pdRotate270 = 270};
Related Methods

AFLayoutNew

Acrobat Forms API Reference81AcroForm Declarations
Core Data Types

82

Acrobat Forms API ReferenceAcroForm Macros

Init_TextAppearanceP#define Init_TextAppearanceP(aP) {\memset(aP, 0, sizeof(values));\(aP)->baseFont = ASAtomNull;\(aP)->nameFont = ASAtomNull;\}
Description
Macro for setting text appearance.
Header File
AF_ExpT.h

Acrobat Forms API Reference83AcroForm Macros

SetDefaultTextAppearanceP#define Init_TextAppearanceP(aP) {\memset(aP, 0, sizeof(values));\(aP)->baseFont = ASAtomFromString("Helvetica”);\(aP)->textSize = AutoSize;\(aP)->horizontalScale = fixedHundred;\(aP)->renderMode = Fill_text;\(aP)->fillColor.space = PDDeviceGray;\(aP)->textMatrix.a = fixedOne;\(aP)->textMatrix.d = fixedOne;\(aP)->quadding = LeftQ;\}
Description
Macro for setting text appearance. This macro uses Helvetica as the default font.
Header File
AF_ExpT.h84

Acrobat Forms API ReferenceAcroForm Macros

TextApperanceIsValid#define TextApperanceIsValid(aP) (\(aP)->quadding <= RightQ && \(aP)->renderMode <= Invisible_text && \(aP)->baseFont != ASAtomNull && \(aP)->textSize >= Autosize)
Description
Macro for checking whether a text appearance is valid.
Header File
AF_ExpT.h

Acrobat Forms API Reference85AcroForm Macros

86

Acrobat Forms API ReferenceText-to-Speech API (Windows only)

The Acrobat Forms plug-in provides a speech server API implemented over the Windows
Speech API (SAPI). It allows document vocalization via text-to-speech conversion to enable
accessibility for people with visual and reading disabilities.
To implement this API, the Forms plug-in exports another Host Function Table (AcroTTS) in
addition to its common AcroForms HFT. To use the AcroTTS HFT, a plug-in must do thefollowing:●

Include the header file TTSHFT.H, which in turn includes AFTTS_SEL.H.

●

Import the HFT using ASExtensionMgrGetHFT and assign the HFT returned by thiscall to a plug-in-defined global variable named gAcroTTSHFT. The easiest way to do
this is to use the Init_AcroTTSHFT macro defined in TTSHFT.h.

NOTE:Acrobat Forms API ReferenceThis API is also available throught Acrobat’s JavaScript interface.

87Text-to-Speech API (Windows only)

AFTTSGetNumberOfVoices
ASUns32 AFTTSGetNumberOfVoices();
Description
Gets the number of different speakers available to the current TTS engine.
Return Value
The number of speakers available.
Header File
AFTTS_Sel.h
Related Methods

AFTTSGetVoiceName88

Acrobat Forms API ReferenceText-to-Speech API (Windows only)

AFTTSGetPitch
ASUns32 AFTTSGetPitch();Description
Gets the baseline pitch for the voice of a speaker.
Return Value
The baseline pitch. The valid range is from 0 to 10, with 5 being the default for the speaker.
Header File
AFTTS_Sel.h
Related Methods

AFTTSSetPitch

Acrobat Forms API Reference89Text-to-Speech API (Windows only)

AFTTSGetSpeakerchar* AFTTSGetSpeaker();
Description
Gets the name of the current speaker.
Return Value
The name of the current speaker.
Header File
AFTTS_Sel.h
Related Methods

AFTTSSetSpeaker90

Acrobat Forms API ReferenceText-to-Speech API (Windows only)

AFTTSGetSpeechRate
ASUns32 AFTTSGetSpeechRate();Description
Gets the speed at which text is being spoken by the TTS engine.
Return Value
The speed, in number of words per minute, at which text is being spoken.
Header File
AFTTS_Sel.h
Related Methods

AFTTSSetSpeechRate

Acrobat Forms API Reference91Text-to-Speech API (Windows only)

AFTTSGetVoiceName
char* AFTTSGetVoiceName (ASInt32 index);
Description
Gets the voice name of any of the available speakers in the installed TTS engine.
Parameters

index

The index of the speaker.

Return Value
The name of the voice.
Header File
AFTTS_Sel.h
Related Methods

AFTTSSetSpeaker92

Acrobat Forms API ReferenceText-to-Speech API (Windows only)

AFTTSGetVolume
ASUns32 AFTTSGetVolume();Description
Gets the volume for the speaker.
Return Value
The volume. Valid values are from 0 (mute) to 10 (loudest). The default is 5.
Header File
AFTTS_Sel.h
Related Methods

AFTTSSetVolume

Acrobat Forms API Reference93Text-to-Speech API (Windows only)

AFTTSIsAvailable
ASBool AFTTSIsAvailable();Description
Determines whether the TTS object is available and the Text-to-Speech engine can be used.
NOTE:

Calling any method in this API causes the Forms plug-in to initialize TTS
automatically, if an SAPI engine is installed on the system.

Return Value

true if the Text-to-Speech engine can be used, false otherwise.
Header File
AFTTS_Sel.h94

Acrobat Forms API ReferenceText-to-Speech API (Windows only)

AFTTSPause
ASBool AFTTSPause();Description
Immediately pauses TTS output on a TTS object. Playback of the remaining queued text
can be resumed via AFTTSResume.
Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSResume

Acrobat Forms API Reference95Text-to-Speech API (Windows only)

AFTTSQSilence
ASBool AFTTSQSilence (ASUns32 duration);
Description
Queues a period of silence into the text.
Parameters

duration

The amount of silence in milliseconds.

Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSQSound
AFTTSQueueTextData

96

Acrobat Forms API ReferenceText-to-Speech API (Windows only)

AFTTSQSound
ASBool AFTTSQSound (const char* soundName);
Description
Puts a sound into the queue. The sound can then be performed by AFTTSTalk.
ParameterssoundName

The sound name. Names are: ActionCopy, ActionCut,
ActionDelete, ActionPaste, DocActive, DocClose,
DocOpen, DocPrint, DocSave, KeyEnd, KeyHome, and
PageTurn. This list can be augmented by adding sound files to theSoundCues folder in Acrobat’s installation, in 22kHz 16-bit PCM .wav
format.

Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSQSilence
AFTTSQueueTextData

Acrobat Forms API Reference97Text-to-Speech API (Windows only)

AFTTSQueueTextData
ASBool AFTTSQueueTextData (const char* textdata,
ASBool UseDefaultSpeaker);
Description
Puts text into the queue to be performed by AFTTSTalk.
Parameters

textdata

The text that will be put into the queue.

UseDefaultSpeaker Whether to use the default speaker.
Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSQSilence
AFTTSQSound

98

Acrobat Forms API ReferenceText-to-Speech API (Windows only)

AFTTSReset
ASBool AFTTSReset();Description
Stops playback of the currently queued text, and flushes the queue. Resets all theproperties of the TTS object to their default values.
NOTE:

Text playback cannot be resumed via AFTTSResume.

Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSStop

Acrobat Forms API Reference99Text-to-Speech API (Windows only)

AFTTSResume
ASBool AFTTSResume();Description
Resumes playback of text on a paused TTS object.
Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSPause

100

Acrobat Forms API ReferenceText-to-Speech API (Windows only)

AFTTSSetPitch
ASBool AFTTSSetPitch (ASUns32 pitch);
Description
Sets the baseline pitch for the voice of a speaker.
Parameterspitch

The baseline pitch. The valid range is from 0 to 10, with 5 being the default forthe speaker.

Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSGetPitch

Acrobat Forms API Reference101Text-to-Speech API (Windows only)

AFTTSSetSpeaker
ASBool AFTTSSetSpeaker (const char* voiceName);
Description
Sets the current voice. Valid values are any of those enumerated via

AFTTSGetVoiceName and AFTTSGetNumberOfVoices.
Parameters

voiceName

The speaker name.

Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSGetSpeaker

102

Acrobat Forms API ReferenceText-to-Speech API (Windows only)

AFTTSSetSpeechRate
ASBool AFTTSSetSpeechRate (ASUns32 speed);
Description
Sets the speed at which text is being spoken by the TTS engine.
Parameters

speed

The speed in number of words per minute.

Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSGetSpeechRate

Acrobat Forms API Reference103Text-to-Speech API (Windows only)

AFTTSSetVolume
ASBool AFTTSSetVolume (ASUns32 volume);
Description
Sets the speech volume.
ParametersvolumeThe volume. Valid values are from 0 (mute) to 10 (loudest).

Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSGetVolume

104

Acrobat Forms API ReferenceText-to-Speech API (Windows only)

AFTTSStop
ASBool AFTTSStop();
Description
Stops playback of currently queued text, and flushes the queue. Playback of queued text
cannot be resumed.
Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSReset

Acrobat Forms API Reference105Text-to-Speech API (Windows only)

AFTTSTalk
ASBool AFTTSTalk();
Description
Sends whatever is in the queue to be spoken by the SAPI TTS engine. If the text output had
been paused, resumes playback of the queued text.
Return Value

true if the speech engine is available, false otherwise.
Header File
AFTTS_Sel.h
Related Methods

AFTTSQueueTextData

106

Acrobat Forms API ReferenceAcroForm OLE Automation

Description
The Acrobat Forms plug-in has been enhanced to work as an Automation server in the
Win32 environment. Since the automation capabilities have been added to a plug-in, rather
than an executable that can be directly launched, the following steps are necessary toaccess them from an Automation controller:
First instantiate the Acrobat application by using the VB CreateObject method. For
example:CreateObject("AcroExch.App")

This causes the Acrobat Forms plug-in to run, at which time it registers its class object with
OLE. Then its main exposed object can be instantiated, that is:
CreateObject("AFormAut.App")

Presently, registration in the Windows registry (which is different from the class object
registration described above) happens every time Acrobat loads the plug-in. Therefore, youhave to run Acrobat at least once with the AForm32.api file in the plug-ins folder before
its type library can be found for object browsing from within the Visual Basic environment.
This is also necessary in order to allow early binding. Dim the program variables as thecorresponding classes in AFORMAUTLib, and not simply As Object.
The object model was designed in accordance with the applicable standards andguidelines for document-centric applications from the OLE Programmer's Reference. Thatmanual uses the term document to describe whatever an application uses as a file or anindividual entity of data (in our case a field).
NOTE:

Neither Acrobat, nor the Acrobat Forms plug-in, are thread-safe, and therefore
Acrobat Forms OLE Automation uses the single-threading model.

Contents
This reference contains the following sections:●

OLE Automation Objects. This section describes the Acrobat objects represented as OLE
objects.

●

OLE Automation Methods. This section describes each OLE method, including its
parameters, return value, and related methods.

●

OLE Automation Properties. This section details the properties that can be set in thevarious objects. Each property describes the key, the property type (for example, readonly), and the semantics.

Acrobat Forms API Reference107AcroForm OLE Automation
Conventions

Conventions
The syntax used in this reference follows that used in Microsoft Visual Basic references.

Exceptions
All methods and properties may return an exception. Some of the possible ones are
standard OLE exceptions, such as:●●

E_OUTOFMEMORY (0x8007000E)
E_INVALIDARG (0x80070057)

These exceptions are not specifically called out in the descriptions of the methods andproperties that appear below. Others are AcroForm-specific, and are listed in the following
table.
The actual numeric value of the returned exception is assembled as an HRESULT, uses the
FACILITY_ITF, and starts with decimal 512 (hex 0x0200), as recommended by Microsoft.
For example, the numeric value of the exception AutErcNoForm is hex 0x80040201. The
important part is the right-most hex 201, which is the first error in the enumeration below.

108

Exception Name

Numeric
Value

AutErcNoDoc

1

No document is currently open in the
Acrobat Viewer.

AutErcNotTerminal

2

This property or method applies toterminal fields, or their annotations.

AutErcNotToThisFieldType

3This property or method is notapplicable to this type of field.

Description

Acrobat Forms API Reference

OLE Automation Objects

AFormApp
AFormApp is the only object the controller can externally instantiate (that is, using
CreateObject). All other objects must be created by navigating down the hierarchy
with the methods and properties described in this document.

Field
A field in the document that is currently active in Acrobat.

FieldsA collection of all the fields in the document that are currently active in Acrobat at the time
Fields is instantiated.
The Fields collection includes both terminal and non-terminal fields. A terminal field is one
that either does not have children, or if it does, they are simply multiple appearances (thatis, child annotations) of the field in question.
NOTE:

Acrobat Forms API Reference

If you instantiate a Fields object, and subsequently fields are manually added or
removed using the Forms tool in Acrobat, the Fields object will no longer be insync with the document. You must re-instantiate the Fields object.

109

OLE Automation Objects

110

Acrobat Forms API Reference

OLE Automation Methods

Field
PopulateListOrComboBox
void PopulateListOrComboBox (const VARIANT& arrItems,
const VARIANT& arrExportVal);
Description
Specifies the item names and optionally exports values for a field of type listbox orcombobox.
Parameters

arrItems

An array of strings, with each element representing an item name.
N O T E : There is a limit of 64K for string data in a combo or list box

control on Windows platforms. For Mac OS systems, the limit
is 200 entries for the combo or list box control. Using morethan these limits degrades performance and makes thecontrol unusable.

arrExportVal(Optional) An array of strings, the same size as the first parameter,with each element representing an export value.
N O T E : Some of the elements in exportString may be empty

strings.
Return Value
None
Exceptions
Raises AutErcNotToThisFieldType if the field is not of type listbox or combobox.
Related Methods

Add

Acrobat Forms API Reference111

OLE Automation Methods
Field

SetBackgroundColor
void SetBackgroundColor (LPCTSTR bstrColorSpace,float GorRorC, float GorM, float BorY, float K);
Description
Specifies the background color for a field. The background color is used to fill the field’s
rectangle.
Parameters

bstrColorSpace

Values are defined by using transparent, gray, RGB or CMYK
color. Valid strings include (and must be spelled exactly as
shown):
● T
● G
● RGB
● CMYK

GorRorC

Used if bstrColorSpace is set to T, G, or RGB. A float range
between zero and one inclusive.

GorM

Used if bstrColorSpace is set to G. A float range between
zero and one inclusive.

BorY

Used if bstrColorSpace is set to RGB. A float range between
zero and one inclusive.

K

Used if bstrColorSpace is set to CMYK. A float range
between zero and one inclusive.

Return Value
None
Related Methods

SetBorderColor
SetForegroundColor
ExampleField.SetBackgroundColor "RGB", 0.7, 0.3, 0.6, 0112

Acrobat Forms API Reference

OLE Automation Methods
Field

SetBorderColor
void SetBorderColor (LPCTSTR bstrColorSpace, float GorRorC,
float GorM, float BorY, float K);
Description
Specifies the border color for a field. The border color is used to stroke the field’s rectangle
with a line as large as the border width. The new border color is propagated to any childannotations underneath, so the field may be non-terminal.
Parameters

bstrColorSpaceA string specifying the color space. Valid strings include (andmust be spelled exactly as shown):● T: transparent● G: gray

RGB● CMYK●

GorRorC

Used if bstrColorSpace is set to T, G, or RGB. A float range
between zero and one inclusive.

GorM

Used if bstrColorSpace is set to G. A float range between
zero and one inclusive.

BorY

Used if bstrColorSpace is set to RGB. A float range between
zero and one inclusive.

K

Used if bstrColorSpace is set to CMYK. A float range
between zero and one inclusive.

Return Value
None
Related Methods

SetBackgroundColor
SetForegroundColor
ExampleField.SetBorderColor "RGB", 0.7, 0.3, 0.6, 0

Acrobat Forms API Reference

113

OLE Automation Methods
Field

SetButtonCaption
void SetButtonCaption (LPCTSTR bstrFace, LPCTSTR bstrCaption);
Description
The caption to be used for the appearance of a field of type button.
Parameters

bstrFace

A string that specifies the face for which the caption will be
used. Valid strings include.
● N is the Normal appearance● D is the Down appearance● R is the appearance for Rollover

bstrCaption

The caption for the button.
N O T E : If a button’s layout is of type icon only, the caption is not

used in generating its appearance. In addition, only theNormal face is displayed, unless the Highlight is of type
push.
Return Value
None
Exceptions
Raises AutErcNotToThisFieldType if the field is not of type button. The new
appearance is propagated to any child annotations underneath; the field may be nonterminal.
Related Methods

SetButtonIcon
ExampleField.SetButtonCaption "D", "Submit Form"

114

Acrobat Forms API Reference

OLE Automation Methods
Field

SetButtonIcon
void SetButtonIcon (LPCTSTR bstrFace, LPCTSTR bstrFullPath,
short pageNum);
Description
Specifies the icon to be used for the appearance of a field of type button.
Parameters

bstrFace

A string that specifies the face for which the icon will be used.
Valid strings include:● N is the Normal appearance● D is the Down appearance● R is the appearance for Rollover

bstrFullPath

The full pathname of the PDF file to be used as the source of theappearance.

pageNum

Used to select the page inside that PDF file (zero-based).
N O T E : If a button’s layout is of type icon only, the caption is not

used in generating its appearance. In addition, only theNormal face is displayed, unless the Highlight is of type
push.
Return Value
None
Exceptions
Raises AutErcNotToThisFieldType if the field is not of type button. The new
appearance is propagated to any child annotations underneath, so it is OK if the field is
non-terminal.
Related Methods

SetButtonCaption
ExampleField.SetButtonIcon "N", "c:\Clipart.pdf", 0Acrobat Forms API Reference

115

OLE Automation Methods
Field

SetExportValues
void SetExportValues (const VARIANT& arrExportVal);
Description
Sets the export values for each of the annotations of a field of type radio button andcheckbox.
For radio button fields, this is necessary to make the field work properly as a group, with theone button checked at any given time giving its value to the field as a whole.
For checkbox fields, unless an export value is specified, the default is used when the field ischecked is Yes. When it is unchecked, its value is Off (this is also true for a radio button field
when none of its buttons are checked).
Parameters

arrExportVal

An array of strings, which is expected to have as many elements
as there are annotations in the field. The elements of the arrayare distributed among the individual annotations comprising
the field using their tab order.

Return Value
None
Exceptions
Raises AutErcNotToThisFieldType if the field is not of type radio button orcheckbox.
Related Methods

Add
ExampleDim arrExp(1) As StringarrExp(0) = "Visa"
arrExp(1) = "Mastercard"
Field.SetExportValues arrExp

116

Acrobat Forms API Reference

OLE Automation Methods
Field

SetForegroundColor
void SetForegroundColor (LPCTSTR bstrColorSpace,float GorRorC, float GorM, float BorY, float K);
Description
Specifies the foreground color for a field. It represents the text color for text, button,
combobox, or listbox fields and the check color for checkbox or radio button fields.
NOTE:

Parameters are similar to SetBorderColor and SetBackgroundColor except thattransparent color space is not allowed.

Parameters

bstrColorSpace

Values are defined by using transparent, gray, RGB or CMYK
color. Valid strings include (and must be spelled exactly as
shown):● T: transparent● G: gray
●
●

RGB
CMYK

GorRorC

Used if bstrColorSpace is set to T, G, or RGB. A float range
between zero and one inclusive.

GorM

Used if bstrColorSpace is set to G. A float range between
zero and one inclusive.

BorY

Used if bstrColorSpace is set to RGB. A float range between
zero and one inclusive.

K

Used if bstrColorSpace is set to CMYK. A float range
between zero and one inclusive.

Return Value
None
Related Methods

SetBackgroundColor
SetBorderColor
ExampleField.SetForegroundColor "CMYK", 0.25, 0.25, 0.25, 0.1

Acrobat Forms API Reference117OLE Automation Methods
Field

SetJavaScriptAction
void SetJavaScriptAction (LPCTSTR bstrTrigger,
LPCTSTR bstrTheScript);
Description
Sets the action of the field to be of type JavaScript. When using

SetJavaScriptAction, within Visual Basic, you may use Chr(13) to add a <CR>, andChr(9) for tabs, so that the function is nicely formatted.
Parameters

bstrTrigger

A string that specifies the trigger for the action. Valid strings
include:
up
down
enter
exit
calculatevalidate
formatkeystroke

bstrTheScript

The script itself.
N O T E : If the trigger is calculate, an entry is added at the end of

the calculation order array (see the CalcOrderIndex
property).
Return Value
None
Related Methods
None
Calculate Notes
There is a simple calculate script supplied with Acrobat.
AFSimple_Calculate(cFunction, cFields)– cFunction is one of "AVG", "SUM", "PRD", "MIN", "MAX"– cFields is the list of the fields to use in the calculation.

118

Acrobat Forms API Reference

OLE Automation Methods
Field

Formatting Notes
The following scripts and formats can be used for the format and keystroke triggers:
AFDate_KeystrokeEx(cFormat)
AFDate_Format(cFormat)– cFormat is one of:"m/d", "m/d/yy", "mm/dd/yy", "mm/yy", "d-mmm", "d-mmm-yy", "dd-mmm-yy", "yymm-dd", "mmm-yy", "mmmm-yy", "mmm d, yyyy", "mmmm d, yyyy","m/d/yy h:MM tt", "m/d/yy HH:MM"
AFTime_Keystroke(ptf)
AFTime_Format(ptf)– ptf is the time format:
0 = 24HR_MM [ 14:30 ]1 = 12HR_MM [ 2:30 PM ]2 = 24HR_MM_SS [ 14:30:15 ]3 = 12HR_MM_SS [ 2:30:15 PM ]AFPercent_Keystroke(nDec, sepStyle)
AFPercent_Format(nDec, sepStyle)– nDec is the number of places after the decimal point;– sepStyle is an integer denoting whether to use a separator or not. If sepStyle=0, usecommas. If sepStyle=1, do not separate.
AFSpecial_Keystroke(psf)
AFSpecial_Format(psf)– psf is the type of formatting to use:
0 = zip code
1 = zip + 4
2 = phone
3 = SSN
AFNumber_Format(nDec, sepStyle, negStyle, currStyle, strCurrency,bCurrencyPrepend)
AFNumber_Keystroke(nDec, sepStyle, negStyle, currStyle, strCurrency,bCurrencyPrepend)– nDec is the number of places after the decimal point;– sepStyle is an integer denoting whether to use a separator or not. If sepStyle=0, usecommas. If sepStyle=1, do not separate.

Acrobat Forms API Reference

119OLE Automation Methods
Field– negStyle is the formatting used for negative numbers:
0 = MinusBlack
1 = Red
2 = ParensBlack
3 = ParensRed– currStyle is the currency style - not used
– strCurrency is the currency symbol– bCurrencyPrepend is true to prepend the currency symbol; false to display on the endof the number

120

Acrobat Forms API Reference

OLE Automation Methods
Field

SetResetFormAction
void SetResetFormAction (LPCTSTR bstrTrigger, long theFlags,
const VARIANT& arrFields);
Description
Sets the action of the field to be of type ResetForm.
Parameters

bstrTrigger

A string that specifies which trigger is used for the action. Valid
strings include (and must be spelled exactly as shown):● up (for Mouse Up)● down (for Mouse Down)● enter (for Mouse Enter)● exit (for Mouse Exit)

theFlags

When 0 (Include), arrFields specifies which fields to include in
the reset operation. When non-zero (Exclude), arrFields
specifies which fields to exclude from the reset operation.

arrFields(Optional) An array of strings for the fully-qualified names of the
fields. Depending on the value of theFlags, these fields areincluded in or excluded from the reset operation.
When the fields are included, the set can include the names of nonterminal fields, which is a fast and easy way to cause all their children
to be included in the action.
When not supplied, all fields are reset.

Return Value
None
Related Methods
None

Acrobat Forms API Reference121OLE Automation Methods
Field

SetSubmitFormAction
void SetSubmitFormAction (LPCTSTR bstrTrigger,
LPCTSTR bstrTheURL, long theFlags, const VARIANT& arrFields);
Description
Sets the action of the field to be of type SubmitForm.
Parameters

bstrTrigger

A string that specifies which trigger is used for the action. Valid
strings include (and must be spelled exactly as shown):● up (for Mouse Up)● down (for Mouse Down)● enter (for Mouse Enter)● exit (for Mouse Exit)

bstrTheURL

A string containing the URL.

theFlags

A collection of flags that define various characteristics of the action.
N O T E : See Section 8.6 in the PDF Reference to learn how the binary

value of this long is interpreted.

arrFields(Optional) If passed, represents an array of strings for the fullyqualified names of the fields to submit when the action gets
executed. If the array is interpreted as fields to submit (as opposed
to exclude from submitting, depending on the least-significant bit in
the flags), then it may include the names of non-terminal fields,
which is a fast and easy way to cause all their children to be includedin the submission.
If not passed, then the created action will not include a /Fields key.

Return Value
None
Related Methods
None

122

Acrobat Forms API Reference

OLE Automation Methods
FieldsFieldsAdd
LPDISPATCH Add (LPCTSTR bstrFieldName, LPCTSTR bstrFieldType,short pageNum, float left, float top, float right,
float bottom);Description
Adds a new field "on-the-fly” to the Acrobat form and to the Fields collection.
Returns the newly-created Field object. You can pass as parameter the name of an
existing field, as long as that field is the same type as the one being created.
This is useful in the following circumstances:●

For radio buttons to use the SetExportValues method to make the radio buttons
mutually exclusive.

●

For fields that should have multiple appearances (that is, child annotations) in the
document.

Parameters

bstrFieldName

The fully-qualified name of the field.

bstrFieldType

Field type for the newly created field. Valid types are:"text”● "button”● "combobox”● "listbox”● "checkbox”● "radio button”● "signature"●

You must use the quotation marks. See the sample code below.
N O T E : When creating list or combo boxes, there is a limit of 64K for

string data on Windows platforms. MacOS systems have alimit of 200 entries for the list or combo boxes. Using morethan the limit degrades performance. You populate thefields of the list and combo boxes using the
PopulateListOrComboBox method.

pageNum

Acrobat Forms API Reference

The page number (zero-based).

123

OLE Automation Methods
Fieldsleft, top,right, bottom

These parameters are floats representing the left, top, right, andbottom coordinates of the field rectangle, measured in rotatedpage space; that is, [0,0] is always at the left bottom corner
regardless of page rotation.

Return Value
The newly-created Field object.
Related Methods

PopulateListOrComboBox
RemoveExampleSet Field = Fields.Add("payment”,_ "radiobutton”, 0, 100, 600, 130, 570)

124

Acrobat Forms API Reference

OLE Automation Methods
Fields

AddDocJavascript
void AddDocJavascript (LPCTSTR bstrScriptName,
LPCTSTR bstrTheScript);
Description
Adds a document-level JavaScript function to the PDF file. When using

AddDocJavascript, within Visual Basic, you can use Chr(13) to add a <CR>, andChr(9) for tabs, so that the function is nicely formatted.
Parameters

bstrScriptName

The name of the function being added to the document.

bstrTheScript

The definition being added to the document.

Return Value
None
Related Methods

ExecuteThisJavascript
Example‘Adding a document-level JavaScript‘function, to compute factorials:
Fields.AddDocJavaScript "Fact", _"function Fact(n)" & Chr(13) & _"{" & Chr(13) & _Chr(9) & "if (n <= 0)" & Chr(13) & _Chr(9) & Chr(9) & "return 1;" & Chr(13) & _Chr(9) & "else" & Chr(13) & _Chr(9) & Chr(9) & "return n * Fact(n - 1);" & Chr(13) & _"}"Acrobat Forms API Reference125OLE Automation Methods
FieldsExecuteThisJavascript
CString ExecuteThisJavascript (LPCTSTR bstrTheScript);
Description
Executes the specified JavaScript script.
Parameters

bstrTheScript

A string containing a JavaScript script, which is executed by
Acrobat in the context of the currently active document.
N O T E : See the Acrobat JavaScript Scripting Reference for

information on event level values.
Return Value
Returns a result by assigning it to event value.
Related Methods

AddDocJavascript
ExampleFields.ExecuteThisJavaScript "var f =_ this.getField(""myButton"");f.delay =_ false;"

To get the return value in Visual Basic:
Dim cSubmitName As String
cSubmitName = Fields.ExecuteThisJavaScript"event.value = this.getField(""myField"").submitName;"

126

Acrobat Forms API Reference

OLE Automation Methods
FieldsExportAsFDF
void ExportAsFDF (LPCTSTR bstrFullPath,
LPCTSTR bstrSubmitButton, BOOL bEmptyFields,
const VARIANT& arrFields);
Description
Exports the data as FDF from an AcroForm.
Parameters

bstrFullPath

A full pathname of the file to which the produced FDF file will
be saved.

bstrSubmitButton

The name of an existing form field of type Button (in case youwant it included in the FDF file, as if it had been used totrigger a SubmitForm action). You may pass an empty
string.

bEmptyFields

A boolean to indicate whether fields with no value should be
included in the produced FDF file.

arrFields(Optional) An array of strings representing the fully-qualified
names of the fields to include in the FDF file. This array may
include the names of non-terminal fields, which is a fast andeasy way to cause all their children to be included in the FDF
file.

Return Value
None
Related Methods

ImportAnFDF
ExportAsHtml
ExampleDim arrFields(1) As String
arrFields(0) = "name”
arrFields(1) = "address”‘This will create an FDF that includes‘name.last, name.first, address.street,‘etc., but only if they have a value‘(since we are passing False for the‘ "bEmptyFields” parameter.
Fields.ExportAsFDF "C:\Temp\out.fdf”, "”, False, arrFields

Acrobat Forms API Reference127OLE Automation Methods
FieldsExportAsHtml
void ExportAsHtml (LPCTSTR bstrFullPath,
LPCTSTR bstrSubmitButton, BOOL bEmptyFields,
const VARIANT& arrFields);
Description
Exports the data as HTML from an AcroForm. This method is similar to ExportAsFDF. The
only difference is that the form data is exported in URL-encoded format.
Parameters

bstrFullPath

A full pathname of the file to which the produced FDF file
will be saved.

bstrSubmitButton

The name of an existing form field of type Button (in case
you want it included in the FDF file, as if it had been used totrigger a SubmitForm action). You may pass an empty
string.

bEmptyFields

A boolean to indicate whether fields with no value should be
included in the produced FDF file.

arrFields(Optional) An array of strings representing the fully-qualified
names of the fields to include in the FDF file. This array may
include the names of non-terminal fields, which is a fast andeasy way to cause all their children to be included in the FDF
file.

Return Value
None
Related Methods

ExportAsFDF

128

Acrobat Forms API Reference

OLE Automation Methods
FieldsImportAnFDF
void ImportAnFDF (LPCTSTR bstrFullPath);
Description
Imports the FDF file to an AcroForm.
Parameters

bstrFullPath

The full pathname of the file containing the FDF file to import.

Return Value
None
Related Methods

ExportAsFDF

Acrobat Forms API Reference

129

OLE Automation Methods
FieldsRemovevoid Remove (LPCTSTR bstrFieldName);
Description
Removes a field from the Acrobat Form and from the Fields collection.
Parameters

bstrFieldName

The fully-qualified name of the field to remove from the Acrobat
form. If the field has multiple child annotations, all of them areremoved. If multiple fields have the same name, all are removed.

Return Value
None
Related Methods

Add
Example‘Remove fields you no longer used.
Fields.Remove("MyOldField")130

Acrobat Forms API Reference

OLE Automation Properties

Field
Alignment[get/set] String

Description
The text alignment of a text field. Valid alignments are (must be spelled exactly as shown):
leftcenterright

Return Value
If the field is terminal, and has multiple child annotations, a get returns the alignment for
the first child, whichever annotation that happens to be.
On a set, the property is propagated to any child annotations underneath, so the field may
be non-terminal.
Exceptions
If the field is not of type text, an exception AutErcNotToThisFieldType is returned.
On a get, if the field is non-terminal, an exception AutErcNotTerminal is returned.
ExampleField.Alignment = left

Acrobat Forms API Reference131OLE Automation Properties
Field

BorderStyle[get/set] String

Description
The border style for a field. Valid border styles include solid, dashed, beveled, inset, andunderline (and must be spelled exactly as shown).
Return Value
If it is terminal, and has multiple child annotations, a get returns the value of the borderstyle for the first child, whichever annotation that happens to be.
On a set, the property is propagated to any child annotations underneath, so the field may
be non-terminal.
Exceptions
On a get, raises AutErcNotTerminal if the field is non-terminal, an exception isreturned.
ExampleField.BorderStyle = "beveled"132

Acrobat Forms API Reference

OLE Automation Properties
Field

BorderWidth[get/set] short

Description
The thickness of the border when stroking the perimeter of a field’s rectangle. If the bordercolor is transparent, this property has no effect except in the case of a beveled border. The
value 0 represents no border, and the value 3 is a thick border.
Return Value
If it is terminal, and has multiple child annotations, a get returns the value of the borderwidth for the first child, whichever annotation that happens to be.
On a set, the property is propagated to any child annotations underneath, so the field may
be non-terminal.
Exceptions
On a get, if the field is non-terminal, an exception AutErcNotTerminal is returned.
ExampleField.BorderWidth = 1

Acrobat Forms API Reference133OLE Automation Properties
Field

ButtonLayout[get/set] short

Description
The layout appearance of a button. Valid values include:●

0 - text only; the button has a caption but no icon.

●

1 - icon only; the button has an icon but no caption.

●

2 - icon over text; the icon should appear on top of the caption.

●

3 - text over icon; the text should appear on top of the icon.

●

4 - icon then text; the icon should appear to the left of the caption.

●

5 - text then icon; the icon should appear to the right of the caption.

●

6 - text over icon; the text should be overlaid on top of the icon.

If it is terminal, and has multiple child annotations, a get returns the layout for the first child,
whichever annotation that happens to be.
On a set, the property is propagated to any child annotations underneath, so it is OK if the
field is non-terminal.
Exceptions
If the field is not of type button, an exception AutErcNotToThisFieldType isreturned.
On a get, if the field is non-terminal, an exception AutErcNotTerminal is returned.
ExampleField.ButtonLayout = 2

134

Acrobat Forms API Reference

OLE Automation Properties
Field

CalcOrderIndex[get/set] short

Description
The calculation order of fields in the document. It is zero-based. If you want the calculation
for a field f2 to be performed after that for field f1, you need only set the
CalcOrderIndex for f2 to f1’s CalcOrderIndex + 1. The elements in the calculation
order array get shifted as necessary to make room for the insertion (but the first calculationis still at index 0).
See also the section "The calculation order array” in the document AcroJS.PDF (under themenu Help -> Forms -> JavaScript).
ExampleSet F1 = Fields("SubTotal")
Set F2 = Fields("Total")
F2.CalcOrderIndex = F1.CalcOrderIndex + 1

Acrobat Forms API Reference

135OLE Automation Properties
Field

CharLimit[get/set] short

Description
The limit on the number of characters that a user can type into a text field.
On a set, the property is propagated to any child annotations underneath, if any.
Exceptions
If the field is not of type text, an exception AutErcNotToThisFieldType is returned.

136

Acrobat Forms API Reference

OLE Automation Properties
Field

DefaultValue[get/set] String

Description
The default value of the field. It returns the empty string if the field has no default value. If
the field is non-terminal, an exception AutErcNotTerminal is returned.
Setting a DefaultValue of ON for fields of type checkbox and radio button is equivalent
to selecting "Default is checked” when you edit the properties of the field using the Forms
tool in Acrobat. A DefaultValue of OFF is a default of unchecked.
See also Value.

Acrobat Forms API Reference137OLE Automation Properties
Field

Editable[get/set] Boolean

Description
Determines whether the user can type in a selection or must choose one of the provided
selections. Comboboxes can be editable; that is, the user can type in a selection.
On a set, the property is propagated to any child annotations underneath, if any.
Exceptions
Returns an exception of AutErcNotToThisFieldType if the field is not of typecombobox.
ExampleField.Editable = False

138

Acrobat Forms API Reference

OLE Automation Properties
Field

Highlight[get/set] String

Description
Defines how a button reacts when a user clicks it. The four highlight modes supported are:none
invertpush
outlineIf it is terminal, and has multiple child annotations, a get returns the highlight for the firstchild, whichever annotation that happens to be.
On a set, the property is propagated to any child annotations underneath, so the field may
be non-terminal.
Exceptions
If the field is not of type button, an exception AutErcNotToThisFieldType isreturned.
On a get, if the field is non-terminal, an exception AutErcNotTerminal is returned.
ExampleField.Highlight = "invert"

Acrobat Forms API Reference139OLE Automation Properties
Field

IsHidden[get/set] Boolean

Description
Controls whether the field is hidden or visible to the user. If the value is true the field isinvisible, false the field is visible.
During get operations, if the field is non-terminal, an exception AutErcNotTerminal isreturned. If it is terminal, and has multiple child annotations, a get returns the value of thehidden flag for the first child, whichever annotation that happens to be.
During set operations, the property is propagated to any child annotations underneath, so
it is OK if the field is non-terminal.
Example’Hide "name.last"
Set Field = Fields("name.last")
Field.IsHidden = True

140

Acrobat Forms API Reference

OLE Automation Properties
Field

IsMultiline[get/set] Boolean

Description
Determines whether the text field is multi-line or single-line.
On a set, the property is propagated to any child annotations underneath, if any.
Exceptions
If the field is not of type text, an exception AutErcNotToThisFieldType is returned.
ExampleField.IsMultiline = True

Acrobat Forms API Reference141

OLE Automation Properties
Field

IsPassword[get/set] Boolean

Description
The property for the field to display asterisks for the data entered into the field. Upon
submission, the actual data entered is sent. Fields that have the password attribute set will
not have the data in the field saved when the document is saved to disk.
On a set, the property is propagated to any child annotations underneath, if any.
Exceptions
If the field is not of type text, an exception AutErcNotToThisFieldType is returned.
ExampleField.IsPassword = True

142

Acrobat Forms API Reference

OLE Automation Properties
Field

IsReadOnly[get/set] Boolean

Description
The read-only characteristic of a field. When a field is read-only, the user can see the field
but cannot change it. If a button is read-only, the user cannot press it to execute an action.
Because this is a field flag and not an annotation flag, both a get and a set of this property
are allowed regardless of whether the field is terminal or non-terminal.
●

A get on a non-terminal field retrieves that field’s flag.

●

A set changes the flag on all its terminal children.

Acrobat Forms API Reference143OLE Automation Properties
Field

IsRequired[get/set] Boolean

Description
The required characteristic of a field. When a field is required, its value must be non- NULL
when the user clicks a submit button that causes the value of the field to be sent to theweb. If the field value is NULL, the user receives a warning message and the submit does
not occur.
Since this is a field flag and not an annotation flag, both a get and a set of this property areallowed, regardless of whether the field is terminal or non-terminal.
A get on a non-terminal field retrieves that field’s flag.
A set changes the flag on all its terminal children.

144

Acrobat Forms API Reference

OLE Automation Properties
Field

IsTerminal[read-only] Boolean

Description

true if the field is terminal, otherwise false.
ExampleDim Field As AFORMAUTLib.Field
Dim bTerminal As Boolean‘bTerminal should be TruebTerminal = Field.IsTerminal

Acrobat Forms API Reference

145OLE Automation Properties
Field

Name
[read-only] String

Description
The fully qualified name of the field. It is the default member of the Field interface.

146

Acrobat Forms API Reference

OLE Automation Properties
Field

NoViewFlag[get/set] Boolean

Description
Determines whether a given field prints but doesn’t display on the screen.
Set the NoViewFlag property to true to allow the field to appear when the user prints
the document but not when it displays on the screen; set it to false to allow both printing
and displaying.
On a get, if the field is non-terminal, an exception AutErcNotTerminal is returned. If it
is terminal, and has multiple child annotations, a get returns the value of the no-view flagfor the first child, whichever annotation that happens to be.
On a set, the property is propagated to any child annotations underneath, so the field may
be non-terminal.

Acrobat Forms API Reference147

OLE Automation Properties
Field

PrintFlag[get/set] Boolean

Description
Determines whether a field prints or not. Set the PrintFlag property to true to allow
the field to appear when the user prints the document, set it to false to prevent printing.
On a get, if the field is non-terminal, an exception AutErcNotTerminal is returned. If it
is terminal, and has multiple child annotations, a get returns the value of the print flag forthe first child, whichever annotation that happens to be.
On a set, the property is propagated to any child annotations underneath, so the field may
be non-terminal.

148

Acrobat Forms API Reference

OLE Automation Properties
Field

Style
[get/set] String

Description
The style of a checkbox or a radio button, that is, the glyph used to indicate that the checkbox or radio button has been selected.
Valid styles include (must be spelled exactly as shown):
check
cross
diamondcirclestar
squareIf it is terminal, and has multiple child annotations, a get returns the style for the first child,
whichever annotation that happens to be.
On a set, the property is propagated to any child annotations underneath, so it is OK if the
field is non-terminal.
Exceptions
During set, if the field is not of type checkbox or radio button, an exception
AutErcNotToThisFieldType is returned.
On a get, if the field is non-terminal, an exception AutErcNotTerminal is returned.
ExampleField.Style = "star"

Acrobat Forms API Reference149OLE Automation Properties
Field

TextFont[get/set] String

Description
The text font used when laying out the field. Valid fonts include (and must be spelled
exactly as shown):
Courier
Courier-Bold
Courier-Oblique
Courier-BoldOblique
Helvetica
Helvetica-Bold
Helvetica-Oblique
Helvetica-BoldObliqueSymbolTimes-Roman
Times-Bold
Times-Italic
Times-BoldItalic
ZapfDingbats

On a set, the property is propagated to any child annotations underneath, if any.
ExampleField.TextFont = "Times-BoldItalic"

150

Acrobat Forms API Reference

OLE Automation Properties
Field

TextSize[get/set] short

Description
The text points size used in the field. In combobox and radio button fields, the text size
determines the size of the check. Valid text sizes include zero and the range from 4 to 144
inclusive.
A text size of zero means that the largest point size that can still fit in the field’s rectangle
should be used (in multi-line text fields and buttons this is always 12 point).
On a set, the property is propagated to any child annotations underneath, if any.
ExampleField.TextSize = 18

Acrobat Forms API Reference151

OLE Automation Properties
Field

Type
[read-only] String

Description
The type of the field as a string. Valid types that are returned:
textbuttoncombobox
listboxcheckbox
radiobutton
signature

ExampleSet Field = Fields("name.last")’Should print "name.last"print Field’ Should print the type of field. Example,’ "text"
print Field.Type

152

Acrobat Forms API Reference

OLE Automation Properties
Field

Value
[get/set] String

Description
A string that represents the value of the field. Returns the empty string if the field has novalue. If the field is non-terminal, an exception AutErcNotTerminal is returned.
For fields of type checkbox, the value Off represents the unchecked state. The checkedstate is represented using the export value. This is also true for radio buttons (where eachindividual button in a group should have a different export value; see
SetExportValues.) For fields of type listbox or combobox, if an export value is defined,
then that represents the value, otherwise the item name is used.
These remarks apply also to DefaultValue.
ExampleDim arrExp(1) As StringarrExp(0) = "Visa"
arrExp(1) = "Mastercard"
Field.SetExportValues arrExp
Field.Value = arrExp(0)Acrobat Forms API Reference

153

OLE Automation Properties
FieldsFi e l ds
Count[read-only] long

Description
The number of items in the collection.
ExampleDim Field As AFORMAUTLib.Field
Dim nFields As LongnFields = Fields.CountFor Each Field In Fields
If Field.IsTerminal Then
print Field.ValueEnd IfNext Field

154

Acrobat Forms API Reference

OLE Automation Properties
FieldsItem[read-only] IDispatch*

Description
Takes the fully qualified name of the field (for example, "name.last”) as a parameter, andreturns the Field object for it. It is the default member of the Fields interface (that is, theproperty invoked if the object name is specified by itself without a property or a method in
the controller script).
ExampleDim Field As AFORMAUTLib.Field
Dim nFields As Long
Set Field = Fields.Item("name.last")‘Since Item is the default_ property:
Set Field = Fields("name.last")

Acrobat Forms API Reference

155OLE Automation Properties
Fields_NewEnum[read-only] IUnknown*

Description
The IEnumVariant enumerator for the collection.
NOTE:

You do not need to call this property directly. Visual Basic calls it in the backgroundwhenever the code contains a "For Each Field In Fields” loop. For example:
For Each Field in Fields
If Field.IsTerminal
print Field.ValueEnd IfNext Field

156

Acrobat Forms API Reference