Te chnical Note #5181 Versio n : Acrobat 6

1 adobe SYSTEMS INCORPORATED Corporate Headquarters 345 Park AvenueSan Jose, CA 95110-2704(408) 536-6000 bbc May 2003 Technical Note #5181Ve r s i on : Acrobat Acrobat Forms API Reference 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 or electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, 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 product trademark 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 , the adobe logo, Acrobat , the Acrobat logo, Acrobat Capture, Distiller, PostScript, the PostScript logo and Reader are either registered trademarks or trademarks of adobe Systems Incorporated in the United States and/or other countries.

2 Apple, Macintosh, and Power Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries. PowerPC is a registered trademark of IBM Corporation in the United States. ActiveX, Microsoft, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. UNIX is a registered trademark of The Open Group. All other trademarks are the property of their respective publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as a commitment by adobe Systems Incorporated. adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies, 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.

3 Acrobat Developer FAQPDF Creation APIs and SpecificationsAcrobat InterapplicationCommunication (IAC) Acrobat Core API Extended API for Plug-inAcrobat Core API ReferenceAcrobat Distiller ParametersAcrobat Distiller API Referencepdfmark Reference Digital Signature API ReferenceForms API ReferenceSearch API ReferenceWeblink API ReferenceAcrobat SDK Release NotesCatalog API ReferenceAcrobat SDK Samples GuideAcrobat Core API OverviewAcrobat Plug-in TutorialAcrobat IAC OverviewAcrobat IAC ReferenceADM Programmer s Guide and ReferenceGetting Started Using the Acrobat Software Development Kit Using the Save as XML Plug-inSpelling API Reference Acrobat SDK Documentation Roadmap AcroColor API ReferenceAcrobat Development OverviewPDF Consultant Accessibility CheckerPDF Reference ManualJavaScriptAcrobat JavaScript Scripting ReferenceAcrobat JavaScript Scripting GuideProgramming Acrobat JavaScript Using Visual BasicUpgrading Plug-ins from Acrobat to Acrobat EnablingPDF Specification Getting Started Acrobat Forms API Reference 5 Contents Preface.

4 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 Contents 6 Acrobat Forms API Reference AFPDDocLoadPDFields .. 31 AFPDF ieldFromCosObj .. 32 AFPDF ieldGetCosObj .. 33 AFPDF ieldGetDefaultTextAppearance .. 34 AFPDF ieldGetFlags .. 35 AFPDF ieldGetName .. 36 AFPDF ieldGetValue .. 37 AFPDF ieldIsAnnot.

5 38 AFPDF ieldIsTerminal .. 39 AFPDF ieldIsValid .. 40 AFPDF ieldReset .. 41 AFPDF ieldSetDefaultTextAppearance .. 42 AFPDF ieldSetFlags .. 43 AFPDF ieldSetOptions .. 44 AFPDF ieldSetValue .. 45 AFPDFormFromPage .. 46 AFPDW idgetGetAreaColors .. 47 AFPDW idgetGetBorder .. 48 AFPDW idgetGetRotation .. 49 AFPDW idgetSetAreaColors.. 50 AFPDW idgetSetBorder .. 51 AssembleFormAndImportFDF.. 52 ExportAsFDF .. 53 ExportAsFDFEx .. 55 ExportAsFDFWithParams .. 57 ExportAsHtml .. 58 ExportAsHtmlEx.. 59 ImportAnFDF .. 61 IsPDDocAcroForm .. 62 ResetForm .. 63 AcroForm Callbacks .. 65 AFPDF ieldEnumProc .. 65 AcroForm Declarations.. 67 AcroForm Data Types .. 67AF_Flags_t .. 67 AFPDF ieldBorder .. 69 AFPDF ieldFlags_t .. 70 AFPDW idgetBorder .. 71 AFPDW idgetBorderRec .. 71 AFPDW idgetBorderStyle .. 72 ExportAsFDFP arams .. 73 ExportAsFDFP aramsRec.. 73 Acrobat Forms API Reference 7 Contents RetCode.

6 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 AFTTSP ause .. 95 AFTTSQS ilence .. 96 AFTTSQS ound .. 97 AFTTSQ ueueTextData .. 98 AFTTSR eset.. 99 AFTTSR esume ..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 Contents 8 Acrobat Forms API Reference OLE Automation Objects .. 109 AFormApp ..109 Field ..109 Fields.

7 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 Acrobat Forms API Reference 9 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 Contents 10 Acrobat Forms API Reference Acrobat Forms API Reference 11 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.

8 It is now faster and easier to exchange information either in familiar paper or electronic forms converted to PDF files with Acrobat , or as dynamic interactive database templates. N OTE : Forms as used here do not refer to XObject forms as defined in the PDF Reference. The Forms plug-in for Acrobat (versions and above) allows users to author form fields. For Acrobat Reader, the Forms plug-in does not allow form authoring, but allows users to fill in data and print Acrobat forms. The Reader Forms plug-in also does not allow users to save data to the local hard disk. Both Acrobat and Reader allow Web designers to send data from the 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 you received this technical note without obtaining the entire Acrobat Software Development Kit (SDK), you can get the complete SDK by visiting: Useful Documentation Other Useful Documentation You should be familiar with the Acrobat core API.

9 The following technical notes provide this information. Acrobat Core API Overview, technical note 5190,gives an overview of the objects and methods 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. Preface Conventions Used in This Book 12 Acrobat Forms API Reference PDF Reference, Fourth Edition, version 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. FontUsed forExamples monospacedPaths and filenames C:\templates\ Code examples set off from plain textThese are variable declarations: AVMenu commandMenu,helpMenu; monospaced boldCode items within plain textThe GetExtensionID method.

10 Parameter names and literal values in reference documentsThe enumeration terminates if proc returns false .monospaced italicPseudocode ACCB1 void ACCB2 ExeProc(void){ do something } Placeholders in code examples AFSimple_Calculate( cFunction , cFields ) blue Live links to Web pagesThe Acrobat Solutions Network URL is:http:// links to sections within this documentSee Using the links to other Acrobat SDK documentsSee the Acrobat Core API Overview .Live links to code items within this documentTest whether an ASAtom PostScript language and PDF operators, keywords, dictionary key namesThe setpagedevice operatorUser interface namesThe File menu Acrobat Forms API Reference 13 Preface Conventions Used in This Book italicDocument titles that are not live links Acrobat Core API Overview New terms User space specifies coordinates variables filename deletefileFontUsed forExamples Preface Conventions Used in This Book 14 Acrobat Forms API Reference Acrobat Forms API Reference 15 AcroForm API Reference Introduction The Acrobat Forms plug-in exports its own Host Function Table (HFT), whose methods can be used by other plug-ins.