Corel Corel Draw Graphics Suite - X5 Programming Guide

Macro Programming Guide

Contents

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

About this documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

About additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

About Corel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Understanding automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

What is automation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Which automation environments are supported? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

What is VBA?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

What is VSTA?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

What are the main elements of automation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

What is an object model? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

What is a class?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

What is a collection? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

What is a property?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

What is a method? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

What is an event? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

What is an enumeration? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

What is a constant?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

How is automation coding structured? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

How are variables declared? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

How are functions and subroutines built?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

How are lines ended? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

How are comments included?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

How are memory pointers used, and how is memory allocated? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

How is scope defined? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

How are Boolean comparisons and assignments used? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

How are logical and bitwise operators used? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

How are message boxes and input boxes provided? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

How are objects referenced?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

How are collections referenced? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

How are object shortcuts used? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

How are event handlers provided? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Getting started with macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Setting up the automation feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

To install the VBA and VSTA features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

To specify VBA options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

Using the Macros toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Using the Macro Manager docker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Using the Add-in Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Using the Macro Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Using the Project Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

CorelDRAW Graphics Suite X5 Macro Programming Guide i

Using the Code window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Using the Properties window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Using the Macro Editor toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Using the Object Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Using the VSTA Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Creating macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Creating macro projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

To create a macro project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

To add a dialog box to a macro project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

To add a code module to a macro project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

To add a class module to a macro project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Writing macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

To add a macro to a macro project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

To edit a VBA macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

To delete a VBA macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Recording macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

To record and save a macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

To record a temporary macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Running macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

To run a saved macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

To run a temporary macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Debugging macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Making macros user-friendly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Providing toolbars for macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

To create a macro toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

To add buttons to a macro toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

To associate an image or icon with a macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

To set a caption for a macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

To set a tooltip for a macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Providing dialog boxes for macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Setting up dialog boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Coding dialog boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

Providing user interaction for macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Capturing mouse clicks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

Capturing mouse drags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66

Capturing coordinates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Providing documentation for macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Organizing and deploying macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Organizing macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Deploying macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

To export a GMS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

To import a GMS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

To export workspace features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

To import workspace features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71

Understanding the CorelDRAW object model . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Working with documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Creating documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Opening documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Contents ii

Activating documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Setting document properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82

Displaying documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Modifying documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85

Creating command groups for documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Saving documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86

Exporting files from documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Publishing documents to PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Printing documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89

Closing documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Working with pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Creating pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94

Activating pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94

Reordering pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

Sizing pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

Modifying pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97

Deleting pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97

Working with layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Creating layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99

Activating layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Locking and hiding layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Reordering layers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Renaming layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Importing files into layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Deleting layers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Working with shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Creating shapes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Determining shape type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121

Selecting shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Duplicating shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Transforming shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Coloring shapes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129

Applying effects to shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Searching for shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Deleting shapes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Working with import filters and export filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Working with import filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138

Working with export filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Contents iii

Introduction

Welcome to the Macro Programming Guide!

This resource can help you explore the macro-related features and functions of CorelDRAW® and Corel®PHO develop comm

This guide contains the following sections:

• Understanding automation — introduces you to the concepts of automation and macros, and to the macroprogramming formats that are supported by CorelDRAW and Corel PHOTO-PAINT

• Getting started with macros — provides an overview of the macro-related tools and features of CorelDRAW and Corel PHOTO-PAINT

• Creating macros — describes how to write, record, run, and debug macros

• Making macros user-friendly — demonstrates how to enhance the usability of macros through dialog boxes, toolbar buttons, user interaction, and documentation

• Organizing and deploying macros — shows you how to organize and deploy the macros you create

• Understanding the CorelDRAW object model — explains the most important features and functions of the CorelDRAW object model

Also included is a glossary, which defines many of the key terms used in this documentation.

This section contains the following topics:

• About this documentation

• About additional resources

•About Corel

TO-PAINT™. An understanding of these features and

ercial solutions that integrate with the product.

functions can help you automate tasks or

Most of the code examples provided in this documentation are written in VBA.

About this documentation

This documentation assumes that the reader has experience with at least one procedural programming language, such as BASIC, Microsoft® Visual Basic® (VB), C, C++, Java™, Pascal, Cobol, or Fortran.

This documentation does not describe the basics of procedural programming (such as functions, conditional branching, and looping). Therefore, before using this documentation, non-programmers are strongly advised to learn basic programming in a language such as Microsoft® Visual Basic® for Applications (VBA).

Most of the code examples provided in this documentation are written in VBA.

CorelDRAW Graphics Suite X5 Macro Programming Guide 1

For more detailed instruction on the VB programming environment and on VBA, see Microsoft Visual Basic Help, which is available from the Help menu in the Macro Editor.

For a more basic introduction to macros, please see the topic “Working with macros” in the main Help file for CorelDRAW or Corel PHOTO-PAINT. You can access the main Help from within an application by clicking Help ` Help topics.

The documentation conventions followed in this guide are explained in the following table.

Wherever you see this You’ll find

A note — describes required conditions for performing a procedure or presents other essential information

A tip — describes helpful information such as shortcuts, alternate methods, or benefits that are related to a procedure

bold text The name of a control or other element on the user

interface

<text in italics and between angle brackets> A placeholder for user-specified information, such as a path

or filename

monospace text

For more information about macros

A reference to coding

CorelDRAW Graphics Suite X5 provides additional resources with helpful information about macros.

Macro documentation for CorelDRAW Graphics Suite X5 is installed to the following location (where X: is the drive where the software is installed):

X:\Program Files\Corel\CorelDRAW Graphics Suite X5\Data

These additional resources are described in the following table.

Resource Description and filename

Macro Help for CorelDRAW Provides comprehensive information about the

CorelDRAW object model and the macro-related features and functions of the application

draw_om.chm

Macro Help for Corel PHOTO-PAINT Provides comprehensive information about the

Corel PHOTO-PAINT object model and the macrorelated features and functions of the application

pp_om.chm

Object-model diagram for CorelDRAW Provides a hierarchical representation of the CorelDRAW

object model

CorelDRAW Object Model Diagram.pdf

Introduction 2

Resource Description and filename

Object-model diagram for Corel PHOTO-PAINT Provides a hierarchical representation of the

Corel PHOTO-PAINT object model

Corel PHOTO-PAINT Object Model Diagram.pdf

You can submit any comments or suggestions about the macro documentation by using the contact information provided at www.corel.com/contact.

About additional resources

CorelDRAW Graphics Suite X5 provides resources with helpful information about the software.

For comprehensive information about the features in CorelDRAW Graphics Suite X5, you can consult the user guide or the Help.

By default, the user guide is installed to the following location (where X: is the drive where the software is installed):

X:\Program Files\Corel\CorelDRAW Graphics Suite X5\Languages\<language>\Help

You can access the Help from within CorelDRAW or Corel PHOTO-PAINT by clicking Help ` Help topics.

For more information about the software

For more information about CorelDRAW Graphics Suite X5, see the following online resources.

Resource Description and URL

CorelDRAW Graphics Suite X5 Web site Provides the latest news, tips and tricks, and information

about upgrades

www.corel.com/coreldraw

Corel® Support Services Web site Provides prompt and accurate information about product

features, specifications, pricing, availability, services, and technical support

www.corel.com/support

Corel® Knowledge Base™ Provides a repository of articles written by the Corel

Technical Support Services team in response to questions by users

www.corel.com/knowledgebase

Introduction 3

Resource Description and URL

CorelDRAW online community Provides interaction with other users through sharing

experiences, asking questions, and receiving help and suggestions

www.coreldraw.com

You can submit any comments or suggestions about CorelDRAW Graphics Suite by using the contact information provided at www.corel.com/contact.

About Corel

Corel is one of the world’s top software companies, with more than 100 million active users in over 75 countries. We develop software that helps people express their ideas and share their stories in more exciting, creative, and persuasive ways. Through the years, we’ve built a reputation for delivering innovative, trusted products that are easy to learn and use, helping people achieve new levels of productivity. The industry has responded with hundreds of awards for software innovation, design, and value.

Our award-winning product portfolio includes some of the world’s most widely recognized and popular software brands, including CorelDRAW® Graphics Suite, Corel® Painter™, Corel DESIGNER® Technical Suite, Corel® PaintShop Photo™ Pro, Corel® VideoStudio®, Corel® WinDVD®, Corel® WordPerfect® Office, WinZip®, and the recently released Corel® Digital Studio™ 2010. Our global headquarters are in Ottawa, Canada, with major offices in the United States, United Kingdom, Germany, China, Taiwan, and Japan.

Introduction 4

Understanding automation

Before you begin to work with macros, you need to understand the concept of automation. This section provides basic information about automation and about the macro-programming formats that are supported by CorelDRAW and Corel PHOTO-PAINT.

This section contains the following topics:

• What is automation?

• Which automation environments are supported?

• What are the main elements of automation?

• How is automation coding structured?

What is automation?

Many actions that you perform in CorelDRAW and Corel PHOTO-PAINT can be combined with other, related actions into a single automated solution. Automating repetitive tasks saves time, reduces effort, and lets you perform operations that are too complex to perform manually.

Automation can be used by programmers and nonprogrammers alike.

This documentation does not teach programming skills to nonprogrammers; rather, it helps experienced programmers develop useful solutions within CorelDRAW and Corel PHOTO-PAINT. If you are not a programmer, you may want to refer to other programming-related resources before continuing to read this documentation.

What is a macro?

Most macros are created to automate a series of tasks within an application. The simplest meaning of the term “macro” is the recording of a group of related actions that can be played back automatically, in sequence, whenever you need to perform them. Macros consist of instructions that are written in a programming language, and some programming languages provide access to additional, more advanced, actions that cannot be recorded.

For the purposes of this documentation, a macro refers to a coded solution that performs tasks in the application by automating functions and subroutines (see “How are functions and subroutines built?” on page 16).

CorelDRAW Graphics Suite X5 Macro Programming Guide 5

Although you can record a sequence of actions in CorelDRAW and Corel PHOTO-PAINT, the real power of automation is that you can add conditions and looping mechanisms to a recording. As an example, let’s consider a simple macro that applies a red fill and a 1-point outline to a selected shape. By adding a condition and a looping mechanism to the code, you can produce a macro that seeks out each selected shape and applies only the fill to text shapes and only the outline to all other shape types.

After you create a macro, you can ensure that it has the desired outcome by setpping through its code one line a a time, or “debugging” it. When you are happy with the macro, you can keep it for future use and even share it with others.

Which sample macros are available?

CorelDRAW Graphics Suite X5 includes sample VBA macros, which supply additional functionality, demonstrate automation in the suite, and provide sample code.

The following sample VBA macros are included for CorelDRAW:

• Calendar wizard (CalendarWizard.gms) — generates customized calendars. You can choose the date range, layout, font, color, language, and many other options. You can also add holidays and moon phases.

•File converter (FileConverter.gms) — converts a vector or bitmap to a specified vector or bitmap format. You can choose export parameters by using dialog boxes associated with particular filters. You can also save each page as a separate file and set various page properties, such as size, orientation, and background color. The following file formats are supported: AI, BMP, CDR, CGM, CMX, CPT, DSF, DXF, EPS, GIF, JPEG, PCT, PNG, PPF, SVG, SWF, TIF, WMF, and WPG.

The following sample VBA macro is included for Corel PHOTO-PAINT:

• HTML slide show creator (Slideshow.gms) — generates an HTML slide show from the images you specify. Open files can be added, ordered, and published as a series of HTML files, each of which displays one image and provides navigation buttons. You can create a title, alternate text, and a name for each slide. You can also choose a location and a name for the delineation folder; select the image folder; and specify notes, a caption, a URL, and more.

Which automation environments are supported?

For CorelDRAW versions 6 through 9, the only method of automating tasks was using the Corel SCRIPT™ language. Solution developers used Corel SCRIPT to create intelligent mini-applications for drawing shapes, repositioning and resizing shapes, opening and closing documents, and setting styles within CorelDRAW.

Although the Corel SCRIPT language was useful for automating basic tasks, a more flexible and powerful solution became necessary. For version 10, CorelDRAW was enhanced with the Microsoft Visual Basic for Applications (VBA) engine, which handled behind-the-scenes automation. The addition of VBA made CorelDRAW immediately accessible to millions of VBA and Microsoft Visual Basic (VB) developers around the world. Since then, VBA has been included in every version of CorelDRAW Graphics Suite. More recently, CorelDRAW Graphics Suite has included Microsoft® Visual Studio® Tools for Applications (VSTA), the successor to VBA. CorelDRAW X5 and Corel PHOTO-PAINT X5 supports VBA version 6.4 and VSTA version 2.0.

Although CorelDRAW no longer includes the Corel SCRIPT editor, it does include the Corel SCRIPT run-time engine. Therefore, you can easily migrate scripts that were written for earlier versions of

Understanding automation 6

CorelDRAW and to later versions of the software. For information on using Corel SCRIPT with CorelDRAW, see “Working with scripts” in the main Help file for CorelDRAW (draw.chm).

In Corel PHOTO-PAINT, you can automate tasks by using VBA or VSTA to create a macro, or by using Corel SCRIPT to create a script. A macro is the better choice if you want to write the code that is required to carry out the task (by using VBA or VSTA), while a script is the better choice if you want to record the steps that are required to carry out the task (by using Corel SCRIPT). For information on using Corel SCRIPT with Corel PHOTO-PAINT, see “Working with scripts” in the main Help file for Corel PHOTO-PAINT (corelpp.chm).

The combination of VBA and VSTA with CorelDRAW Graphics Suite provides a platform for developing powerful corporate graphical solutions, such as automated ticket generators, customized calendars, and batch file processors. These applications can also be used to optimize your workflow. For example, when creating company letterhead, you can add a page layout on the fly. You can also customize some of the built-in functionality of the software, such as the creation, alignment, or transformation of objects

VBA and VSTA each provide their own fully integrated development environment (IDE), with contextual popup lists, syntax highlighting, line-by-line debugging, and visual designer windows. These features are particularly helpful to inexperienced developers.

For more information on VBA and VSTA, see the following sections:

• What is VBA?

•What is VSTA?

What is VBA?

Microsoft Visual Basic for Applications (VBA) is a built-in programming environment that can be used to automate repetitive functions and create intelligent solutions in CorelDRAW and Corel PHOTO-PAINT. VBA is a subset of the Microsoft Visual Basic (VB) object-driven programming environment. Usually, VBA is integrated into another application to customize functionality within that application.

VBA is both a language and an editor. The VBA language cannot be used without its editor, and the VBA editor is the only utility in which VBA code can be edited or VBA programs can be run.

The VBA language is an event-driven programming language. In other words, it is used to write code that produces a response to an action, such as clicking a button or choosing an option from a list box. When the action occurs, the appropriate event is called, and the code for that event is executed. Events can be simple or complex. For instance, you can code a single line that displays a message box or write an entire procedure that interacts with a database.

With traditional procedural programming (or “object-driven programming”), the program starts at the first line and executes one line at a time. VB provides an example of an object-driven programming environment.

Most of the code examples provided in this documentation are written in VBA.

The VBA editor, called the “Macro Editor” (formerly the “Visual Basic Editor”) in CorelDRAW and Corel PHOTO-PAINT, is an integrated development environment (IDE) that lets you manipulate the objects that are exposed by the object model of the application. To help you code macros, the Macro Editor provides context-sensitive Help for all the object-model elements that are available to you.

Understanding automation 7

VBA is an in-process automation controller. In other words, VBA can be used to control the features of CorelDRAW and Corel PHOTO-PAINT that can be automated, and VBA runs efficiently by bypassing the interprocess synchronization mechanisms. However, the automation that the in-process VBA can access can also be accessed by the following:

• external out-of-process automation controllers (OLE clients)

• applications that are developed in programming languages (such as VB, Visual C++, Windows® Script Host, and C++) that can be used to develop OLE clients

• the VBA engines of other applications

VBA provides a set of tools for customizing the graphical user interface of CorelDRAW and Corel PHOTOPAINT. These tools let you process and present data efficiently and effectively. Advantages of using VBA with CorelDRAW and Corel PHOTO-PAINT include the following:

• familiarity of the VB language

• rapid application development (RAD) IDE

• fast run-time performance of the resulting integrated solutions

• extensible forms package that supports ActiveX® controls for creating user interfaces

• access to the full Windows® application programming interface (API) and the underlying file system

• connectivity to corporate data

• integration with other software that is based on component object models (COMs)

VBA lets you customize an application to suit your needs, or even integrate it with another VBA-enabled application by referencing the object-model components of the second application. Although VBA was developed by Microsoft and is built into almost all its desktop applications (including Microsoft Office), Microsoft licenses the technology to other companies, including Corel Corporation (in CorelDRAW Graphics Suite, Corel DESIGNER® Technical Suite, and Corel® WordPerfect® Office), Autodesk, Inc. (in AutoCAD®), and IntelliCAD Technology Consortium (in IntelliCAD®). For this reason, CorelDRAW Graphics Suite X5 is compatible with a wide array of applications that support VBA. However, the CorelDRAW Graphics Suite X5 engine can also control applications that do not support VBA. Consequently, you can build solutions in CorelDRAW and Corel PHOTO-PAINT that access databases, word processors, specialized content editors, XML documents, and more.

For a complete list of applications that support VBA, see the Microsoft Web site.

CorelDRAW Graphics Suite X5 includes VBA version 6.4.

How does VBA differ from VB and VBScript?

The VB programming system is an advanced set of programming tools that provides advanced functionality and components for the Windows operating system and other Windows-based programs. For example, unlike VBA or VBScript, VB lets you create application extensions (DLL files) and stand-alone executable programs (EXE files). (The programs that you create with VBA must run inside the host application.)

VB is a “visual”version of the BASIC programming language — that is, it provides visual cues within the editor. As a result, VB is an easy language to learn. In addition, Microsoft has greatly enhanced the original BASIC language, so that VB is both powerful and fast (although not as powerful as Java or C++, nor as fast as C).

VBA is a subset of the VB programming language, and it uses the programming structure of VB to manipulate the object-model elements that are exposed by an application. The manipulation of these objects results in small

Understanding automation 8

packets of code procedures within the application. These code procedures and resulting projects are called “addins.”

VBScript (sometimes referred to as Microsoft Visual Basic, Scripting Edition) is also a subset of the VB programming language. VBScript is a Web-based HTML document scripting language.

How does VBA differ from Java and JavaScript?

VBA is similar to Java and JavaScript® in that it is a high-level, procedural programming language with full garbage collection and very little memory-pointer support. (For more information, see “How are memory pointers used, and how is memory allocated?” on page 17.) In addition, code that is developed in VBA, much like code developed in Java and JavaScript, supports on-demand compilation and can be executed without being compiled.

VBA is also similar to JavaScript in that it cannot be executed as a stand-alone application. JavaScript is embedded within Web pages as a mechanism for manipulating the document object model (DOM) of the Web browser. Likewise, VBA programs are executed inside a host environment (in this case, CorelDRAW or Corel PHOTO-PAINT) to manipulate the object model of the host.

Most VBA applications can be compiled to p-code to make them run more quickly, although the difference is hardly noticeable because of the sophistication of today’s computer hardware. Similar compilation is possible with Java, but not with JavaScript.

Finally, whereas VBA uses a single equals sign ( a single equals sign (

= ) for assignment and two equals signs ( == ) for Boolean comparison. (For more

= ) for both comparison and assignment, Java and JavaScript use

information, see “How are Boolean comparisons and assignments used?” on page 18.)

How does VBA differ from C and C++?

Like C and C++, VB uses functions. In VB, functions can be used to return a value, but subroutines cannot be used in that way. However, functions are used in C and C++, regardless of whether you want to return a value. (For more information, see “How are functions and subroutines built?” on page 16.)

VBA allocates and frees memory transparently. In C and C++, however, the developer is responsible for most memory management. As a result, using strings in VBA is even simpler than using the CString class in C++.

Finally, whereas VBA uses a single equals sign ( single equals sign (

= ) for assignment and two equals signs ( == ) for Boolean comparison. (For more

= ) for both comparison and assignment, C and C++ use a

information, see “How are Boolean comparisons and assignments used?” on page 18.)

How does VBA differ from WSH?

Windows Script Host (WSH)is an out-of-process automation controller that lets you do occasional scripting and automation of Windows tasks and can be used to control CorelDRAW Graphics Suite. Although WSH is a useful addition to the Windows operating system, WSH scripts tend to be slow because they must run out of process, and they cannot be compiled (and must be interpreted as they are executed).

WSH is a host for a number of scripting languages, each of which has its own syntax. However, the standard language that WSH uses is a macro language that resembles VB, so for standard scripts, the syntax is the same as in VBA.

Understanding automation 9

What is VSTA?

The successor to VBA, Microsoft Visual Studio Tools for Applications (VSTA) is based on Microsoft Visual Studio 2008. In CorelDRAW Graphics Suite X5, the VSTA feature supports the .NET framework and enables development in two programming languages: Visual Basic .NET and Visual C#.

Most of the code examples provided in this documentation are written in VBA.

The VSTA Editor in CorelDRAW and Corel PHOTO-PAINT is an integrated development environment (IDE) that lets you create VSTA solutions for the software.

CorelDRAW Graphics Suite X5 includes VSTA version 2.0.

How does VSTA compare with VBA?

Both VSTA and VBA allow you to create powerful macro solutions. With VSTA, you use the VSTA Editor as an IDE, and you use Visual Basic .NET or Visual C# as a programming language. With VBA, you use the Macro Editor as an IDE, and you use VBA as a programming language.

If you want to perform any of the following tasks, you can use either VSTA or VBA:

• customize or extend the features of CorelDRAW Graphics Suite X5

• interact with other applications that use Visual Basic 6 — or with other compatible components that are external to CorelDRAW Graphics Suite X5

• interact with Web-based services

• customize the IDE with add-ins

• create macro projects — with multi-threading support, if desired

• access macro projects programmatically

• generate macro code dynamically

• store macro code in a pre-compiled format

• hide macro code from other macro authors

• debug macro projects

• create customized user interfaces for macro projects

However, if you want to perform any of the following tasks, you must use VSTA:

• access the .NET framework natively — to support using Managed Add-in Framework (MAF), referencing .NET assemblies directly, running customized code on the Common Language Runtime (CLR), enforcing .NET security policies, or creating user interfaces by using .NET WinForms

• fully customize the IDE

• create macro projects that are certified to run on Windows Vista

• create macro projects that support 64-bit processors

• create macro projects that support server-side customizations

• create macro projects that support all data types, including

BigDecimal and Int64

• create macro projects and macro assemblies that persist without the use of structured storage

• open and modify macro projects in Visual Studio

• compile macro projects to DLL assemblies

• run macro projects out of process

Understanding automation 10

• run macro projects without causing the host application to stop execution at errors or breakpoints

• isolate macro projects from one another; run macro projects independently, and stop them during runtime without affecting other running projects

• author macros within managed code

• prevent servers from running customized user interfaces for macro projects

What are the main elements of automation?

If you’ve ever developed object-oriented code in C++, Borland Delphi, or Java, you’re already familiar with programming-related concepts such as “objects,” “classes,” “properties,” and “methods.” However, let’s reexamine these terms as they apply to automating CorelDRAW and Corel PHOTO-PAINT.

• What is an object model?

• What is a class?

• What is a collection?

• What is a property?

• What is a method?

• What is an event?

• What is an enumeration?

• What is a constant?

What is an object model?

An object model represents the hierarchy of items (or “objects”) that make up an application and defines the interrelationships of the objects within that hierarchy. In an object model, each object is a child of another object, which is a child of yet another object, and so on. Furthermore, each object in an object model is defined by a property, a method, or an event, or a combination of these items.

Besides providing a high level of structure, an object model also lets you use object types (or “classes”) in various ways. For example, a Shape object of type “group” is used to contain other Shape objects, each of which is from type “group” or some other type, such as “rectangle,” “curve,” or “text.”

This high level of organization makes the object model easy to use, yet powerful.

How is an object model used in automation?

Automating CorelDRAW or Corel PHOTO-PAINT is accomplished by using the object model of the application to access the various objects in a document and make changes to those objects.

In CorelDRAW and Corel PHOTO-PAINT, the Application object represents the top of the object hierarchy: the program itself. All objects are children or grandchildren (or great-grandchildren, and so on) of the application.

Starting with the Application object, you can “drill down” through the layers of hierarchy in the object model until you find the desired, and usually the more specific, object. To reference the desired object, you must use a standard notation to separate each level of the object hierarchy.

Understanding automation 11

As in many object-oriented languages, the CorelDRAW and Corel PHOTO -PAINT automation environment requires the use of a period or “dot operator” (

. ) to indicate that the object on the right is a member (or child)

of the object on the left.

Application.Documents(1).Pages(1).Layers(1).Shapes(1).Name = "ABC"

An object requires its full hierarchical (or “fully qualified”) reference unless a shortcut is available to it (or unless it has an implicit or implied meaning). An object shortcut is merely a syntactic replacement for the long-hand version of an object. For example, the shortcut object

Application.ActiveDocument.ActivePage.ActiveLayer, while the object shortcut ActiveSelection

replaces the long-hand version

Application.ActiveDocument.Selection.

ActiveLayer replaces the long-hand version

For more information on object shortcuts, see “How are object shortcuts used?” on page 22.

What is a class?

A class is the definition or description of an object. A class outlines the properties, methods, and events that apply to a type of object in an application; it acts as a template for all objects of that type class. To use a metaphor, the class “car” is a small vehicle with an engine and four wheels.

An object is an instance of a class. To extend the car metaphor, the actual, physical car purchased for the purposes of driving is an object (that is, an instance of the class “car”).

In the context of CorelDRAW and Corel PHOTO-PAINT, each open document is an instance of the Document class, each page in the document is an instance of the Page class, and each layer (and each shape on each layer) are more instances of more classes. For example, Corel PHOTO-PAINT. However,

ActiveDocument represents an object within that class because it makes

specific reference to one object.

Document represents the Document class in CorelDRAW and

As previously discussed, objects are often made up of other smaller objects. For example, a car contains four objects of the class “wheel,” two objects of the class “headlight,” and so on. Each of these child objects has the same properties and methods of its class-type. This parent/child relationship of objects is an important one to recognize, particularly when referencing an individual object.

Some classes “inherit” features from their parents. For example, in the context of CorelDRAW and Corel PHOTO-PAINT, the Shape type has many subtypes (or “inherited types”), including Rectangle, Ellipse, Curve, and Te x t . All these subtypes can make use of the basic members of the Shape type, including methods for moving and transforming the shape and for setting its color. However, the subtypes also have their own specialist members; for example, a Rectangle can have corner radii, whereas Te x t has an associated Font property.

What is a collection?

A collection is similar to an array of objects; it is an object that contains a group of objects that are similar in type. These objects share the same properties, methods, and events, and they are uniquely identified within the collection by their index number or their name. Collection objects act in the same manner and are always plural.

For example, However,

Documents represent the Documents collection class in CorelDRAW and Corel PHOTO-PAINT.

Documents.Item (1) references the first Document object in that collection.

Understanding automation 12

What is a property?

A property is like an adjective in that it represents an attribute or characteristic quality of an object. Properties can be returned or set, or they can be read-only.

Most classes have properties. As an illustration, the properties of the class “car” are that it is small, it has an engine, and it has four wheels. Every instance of the class “car” (that is, every object in that class) also has properties such as color, speed, and number of seats. Read-only properties are fixed by the design of the class; for example, the number of wheels or seats does not (usually) vary from car to car. However, other properties can be changed after the object has been created; for example, the speed of the car can go up and down, and, with a bit of help, its color can be changed.

In the context of CorelDRAW and Corel PHOTO-PAINT, Document objects have a name, a resolution, and horizontal and vertical ruler units; individual shapes have outline properties and fill properties, as well as a position and a rotation factor; and text objects have text properties, which may include the text itself. For example,

ActiveDocument.Name represents the Name property of a Document object; it specifies the name of

the active document.

What is a method?

A method is like a verb in that it represents an action that can be performed by or on an object. In the example of a class “car,” the car can be made to go faster and slower, so two methods for the class are “accelerate” and “decelerate.”

In the context of CorelDRAW and Corel PHOTO-PAINT, documents have methods for creating new pages, layers have methods for creating new shapes, and shapes have methods for applying transformations and effects. For example, document.

ActiveDocument.Close represents the Close method of a Document object; it closes the active

What is an event?

An event is like a noun in that it represents an action that takes place within an object. An event is triggered by an action, such as a mouse click, a key press, or a system timer. An event can be coded to trigger appropriate response in its object.

For example, the

ActiveDocument.AfterSave event triggers an action in the Document object after it has

been saved.

What is an enumeration?

An enumeration (also called an “enumerated type”) represents a fixed value in the procedures and functions of the coding for a macro. Whereas a variable temporarily stores a changing data value, the value of an enumeration does not change.

What is a constant?

A constant is an instance of an enumeration, and an enumeration groups similar constants together.

For example,

AddinFilterNew.

and

AddinFilter is an enumeration, yet it contains several constants, including AddinFilterNone

Understanding automation 13

How is automation coding structured?

Your programming knowledge should help you learn to automate CorelDRAW and Corel PHOTO-PAINT, regardless of your level of experience with Microsoft Visual Basic for Applications (VBA) or Microsoft Visual Studio Tools for Applications (VSTA).

This section examines the following topics on the structure and syntax of the VBA language:

• How are variables declared?

• How are functions and subroutines built?

• How are lines ended?

• How are comments included?

• How are memory pointers used, and how is memory allocated?

• How is scope defined?

• How are Boolean comparisons and assignments used?

• How are logical and bitwise operators used?

• How are message boxes and input boxes provided?

• How are objects referenced?

• How are collections referenced?

• How are object shortcuts used?

• How are event handlers provided?

The Macro Editor formats all VBA coding for you (as discussed in “Formatting code automatically” on page 32). The only way to customize the formatting is to change the size of the indentations.

VBA can be used to create object-oriented classes. However, this function is a feature of the programming language and is therefore not discussed in detail in this documentation.

How are variables declared?

In VBA, the construction for declaring variables is as follows:

Dim foobar As Integer

The built-in data types are Byte, Boolean, Integer, Long, Single, Double, String, Variant, and several other less-used types including

Variables can be declared anywhere within the body of a function, or at the top of the current module. However, it is generally a good idea to declare a variable before it is used; otherwise, the compiler interprets it as a

Variant, and inefficiencies can be incurred at run time.

Booleans take

Long results in True being converted to a value of –1.

False to be 0 and True to be any other value, although converting from a Boolean to a

To get more information about one of the built-in data types, type it in the Code window of the Macro Editor, select it, and then press F1.

Date, Decimal, and Object.

Understanding automation 14

Data structures can be built by using the following VBA syntax:

Public Type fooType item1 As Integer item2 As String End Type Dim myTypedItem As fooType

The items within a variable declared as type fooType are accessed by using dot notation:

myTypedItem.item1 = 5

How are strings declared?

Using strings is much simpler in VBA than in C. In VBA, strings can be added together, truncated, searched forwards and backwards, and passed as simple arguments to functions.

To add two strings together in VBA, simply use the concatenation operator (

Dim string1 As String, string2 As String string2 = string1 & " more text" + " even more text"

& ) or the addition operator ( + ):

In VBA, there are many functions for manipulating strings, including InStr(), Left(), Mid(), Right(),

Len(), and Trim().

How are enumerations declared?

To declare an enumeration in VBA, use the following construction:

Public Enum fooEnum ItemOne ItemTwo ItemThree End Enum

By default, the first item in an enumerated type is assigned a value of 0.

How are arrays declared?

To declare an array in VBA, use parentheses — that is, the ( and ) symbols:

Dim barArray (4) As Integer

The value defines the index of the last item in the array. Because array indexes are zero-based by default, there are five elements in the preceding sample array (that is, elements

0 thru 4, inclusive).

Arrays can be resized by using

ReDim. For example, the following VBA code adds an extra element to barArray

but preserves the existing contents of the original five elements:

ReDim Preserve barArray (6)

Upper and lower bounds for an array can be determined at run time by using the functions UBound() and

LBound().

Understanding automation 15

Multidimensional arrays can be declared by separating the dimension indexes with commas, as in the following VBA example:

Dim barArray (4, 3)

How are functions and subroutines built?

VBA uses both functions and subroutines (or “subs”). Functions can be used to return a value, but subs cannot.

In VBA, functions and subs do not need to be declared before they are used, nor before they are defined. In fact, functions and subs need to be declared only if they actually exist in external system DLLs.

Typical functions in a language such as Java or C++ can be structured as follows:

void foo( string stringItem ) { // The body of the function goes here } double bar( int numItem ) { return 23.2; }

In VBA, however, functions are structured as in the following example:

Public Sub foo (stringItem As String) ' The body of the subroutine goes here End Sub Public Function bar (numItem As Integer) As Double bar = 23.2 End Function

To force a function or sub to exit immediately, you can use Exit Function or Exit Sub (respectively).

How are lines ended?

In VBA, each statement must exist on its own line, but no special character is required to denote the end of each line. (In contrast, many other programming languages use a semicolon to separate individual statements.)

To break a long VBA statement over two or more lines, each of the lines (other than the last line) must end with an underscore (

newString = fooFunction ("This is a string", _ 5, 10, 2)

_ ) preceded by at least one space:

You can combine several statements in a single VBA line by separating them with colons:

a = 1 : b = 2 : c = a + b

A VBA line cannot end with a colon. VBA lines that end with a colon are labels that are used by the Goto statement.

How are comments included?

Comments in VBA — similarly to in ANSI, C++, and Java — can be created only at the end of a line. Comments begin with an apostrophe (

' ) and terminate at the end of the line.

Understanding automation 16

Each line of a multi-line comment must begin with its own apostrophe in VBA:

a = b ' This is a really interesting piece of code that ' requires so much explanation that I needed to break ' the comment over multiple lines.

To comment out large sections of VBA code, use the following syntax (similarly to in C or C++):

#If 0 Then ' That's a zero, not the letter 'oh'. ' All this code will be ignored by ' the compiler at run time! #End If

How are memory pointers used, and how is memory allocated?

VBA does not support C-style memory pointers. Memory allocation and garbage collection are automatic and transparent, just as in Java and JavaScript (and some C++ code).

How are arguments passed?

Most languages, including C++ and Java, pass an argument to a procedure as a copy of the original. If the original must be passed, then one of two things can happen:

• a memory pointer is passed that directs the procedure to the original argument in memory

• a reference to the original argument is passed

Microsoft Visual Basic (VB) has the same requirements for passing arguments. In VB, passing a copy of the original argument is called “passing by value” and passing a reference to the original is called “passing by reference.”

By default, function and subroutine parameters are passed by reference. A reference to the original variable is passed in the argument of the procedure; changing the value of that argument, in effect, changes the value of the original variable value as well. In this way, more than one value can be returned from a function or subroutine. To explicitly annotate the code to indicate that an argument is being passed by reference, you can prefix the argument with

ByRef.

If you want to prevent a procedure from changing the value of the original variable, you can force the copying of an argument. To do this in VBA, prefix the argument with functionality of

ByRef and ByVal is similar to the ability of C and C++ to pass a copy of a variable, or to pass a

ByVal, as shown in the example that follows. The

pointer to the original variable.

Private Sub fooFunc (ByVal int1 As Integer, _ ByRef long1 As Long, _ long2 As Long) ' Passed ByRef by default

In the preceding VBA example, arguments long1 and long2 are both, by default, passed by reference. Modifying either argument within the body of the function modifies the original variable; however, modifying

int1 does not modify the original because it is a copy of the original.

Understanding automation 17

How is scope defined?

You can define the scope of a data type or procedure (or even an object). Data types, functions, and subroutines (and members of classes) that are declared as private are visible only within that module (or file). By contrast, functions that are declared as public are visible throughout all the modules; however, you may need to use fully qualified referencing if the modules are almost out of scope — for example, if you are referencing a function in a different project.

Unlike C, VBA does not use braces — that is, the is defined by an opening function or subroutine definition statement (that is,

End statement (that is, End Function or End Sub). Any variables declared within the function are available

{ and } symbols — to define local scope. Local scope in VBA

Function or Sub) and a matching

only within the scope of the function itself.

How are Boolean comparisons and assignments used?

In Microsoft Visual Basic (VB), Boolean comparison and Boolean assignment are both performed by using a single equals sign (

If a = b Then c = d

By contrast, many other languages use a double equals sign for Boolean comparison and a single equals sign for Boolean assignment:

if( a == b ) c = d;

The following code, which is valid in C, C++, Java, and JavaScript, is invalid in VBA:

if( ( result = fooBar( ) ) == true )

The preceding example would be written in VBA as the following:

result = fooBar( ) If result = True Then

For other Boolean comparisons, VBA uses the same operators as other languages (except for the operators for “is equal to” and “is not equal to”). All the Boolean-comparison operators are provided in the following table.

= ):

Comparison VBA operator C-style operator

Is equal to

Is not equal to

Is greater than

Is less than

Is greater than or equal to

Is less than or equal to

The result of using a Boolean operator is always either

===

<> !=

>= >=

<= <=

True or False.

Understanding automation 18

How are logical and bitwise operators used?

In VBA, logical operations are performed by using the keywords And, Not, Or, Xor, Imp, and Eqv, which perform the logical operations AND, NOT, OR, Exclusive-OR, logical implication, and logical equivalence (respectively). These operators also perform Boolean comparisons.

The following code shows a comparison written in C or a similar language:

if( ( a && b ) || ( c && d ) )

This example would be written as follows in VBA:

If ( a And b ) Or ( c And d ) Then

Alternatively, the preceding VBA code could be written in the following full long-hand form:

If ( a And b = True ) Or ( c And d = True ) = True Then

The following table provides a comparison of the four common VBA logical and bitwise operators, and the Cstyle logical and bitwise operators that are used by C, C++, Java, and JavaScript.

VBA operator C-style bitwise operator C-style Boolean operator

And & &&

Not ~ !

Or | ||

Xor ^

How are message boxes and input boxes provided?

In VBA, you can present simple messages to the user by using the MsgBox function:

Dim retval As Long retval = MsgBox("Click OK if you agree.", _ vbOKCancel, "Easy Message") If retval = vbOK Then MsgBox "You clicked OK.", vbOK, "Affirmative" End If

You can also get strings from the user by using InputBox function:

Dim inText As

inText = InputBox("Input some text:", "type here") If Len(inText) > 0 Then MsgBox "You typed the following: " & inText & "." End If

If the user clicks Cancel, the length of the string returned in inText is zero.

String

For information on creating more complex user interfaces, see “Making macros user-friendly” on page 55.

Understanding automation 19

How are objects referenced?

If you want to create a reference to an object so that you can treat that reference like a variable (sh, in the VBA example for CorelDRAW that follows), you can use the

Dim sh As Shape Set sh = ActiveSelection.Shapes.Item(1)

After you create this reference, you can treat it as though it were the object itself.

sh.Outline.Color.GrayAssign 35

If the selection is changed while sh is still in scope, sh references the original shape from the old selection and is unaffected by the new selection. You cannot simply assign the object to the variable as in the following example:

Dim sh As Shape sh = ActiveSelection.Shapes.Item(1)

To release an object, you must set its reference value to Nothing.

Set sh = Nothing

You can also test whether a variable references a valid object by using the Nothing keyword.

If sh Is Nothing Then MsgBox "sh is de-referenced."

Objects do not need to be explicitly released. In most cases, VB releases the object upon disposal of the variable when you exit the function or subroutine.

Set keyword.

How are collections referenced?

Many objects are members of collections. A collection is similar to an array, except that it contains objects rather than values. However, members of collections can be accessed in the same way as arrays. For example, a collection that is used frequently in CorelDRAW is the collection of shapes on a layer: The object references either the current layer or the layer that is selected in the CorelDRAW Object Manager docker.

CorelDRAW contains many collections: A document contains pages, a page contains layers, a layer contains shapes, a curve contains subpaths, a subpath contains segments and nodes, a text range contains lines and words, a group contains shapes, and the application contains windows. All these collections are handled in the same way by VBA.

How are the items in a collection referenced?

To reference the shapes on a layer, the collection of shapes for that layer is used: ActiveLayer.Shapes. To reference the individual shapes in the collection, the

Item() property is used. Here is a VBA example for

CorelDRAW:

Dim sh As Shape Set sh = ActiveLayer.Shapes.Item(1)

Most elements of a collection start at 1 and increase. For the CorelDRAW collection ActiveLayer.Shapes,

Item(1) is the item at the “top” or “front” of the layer — in other words, it is the item that is in front of all

other shapes. Furthermore, because each item in the

ActiveLayer collection is an object of type Shape, you can

reference any item in VBA merely by appending the appropriate dot-notated member:

ActiveLayer.Shapes.Item(1).Outline.ConvertToObject

ActiveLayer

Understanding automation 20

Sometimes, individual items have names. If the item you are looking for has an associated name (and you know what the name is and which collection the item is in), you can use that name to reference the item directly, as in the following VBA example for CorelDRAW:

Dim sh1 As Shape, sh2 As Shape Set sh1 = ActiveLayer.CreateRectangle(0, 5, 7, 0) sh1.Name = "myShape" Set sh2 = ActiveLayer.Shapes.Item("myShape")

Also, because an item is usually the implied or default member of a collection, it is not strictly required. For this reason, the last line of the preceding VBA code can be rewritten as follows:

Set sh2 = ActiveLayer.Shapes("myShape")

How are the items in a collection counted?

All collections have a property called Count. This read-only property gives the number of members in the collection, as in the following VBA example for CorelDRAW:

Dim count As Long count = ActiveLayer.Shapes.Count

The returned value is not only the number of items in the collection: Because the collection starts from 1, it is also the index of the last item.

How are the items in a collection parsed?

It is often necessary to parse through the members of a collection to check or change the properties of each item.

By using the

Item() and Count members, it is straightforward to step through a collection of items. With each

iteration, it is possible to test the properties of the current item, or to call its methods. The following VBA code for CorelDRAW restricts all shapes on the layer to no wider than ten units:

Dim I As Long, count As Long count = ActiveLayer.Shapes.Count For I = 1 to count If ActiveLayer.Shapes.Item(i).SizeWidth > 10 Then ActiveLayer.Shapes.Item(i).SizeWidth = 10 End If Next I

There is, however, a more convenient way of parsing a collection in VBA. Instead of using the Count property and a For-Next loop, this technique uses a For-Each-In loop:

Dim sh As Shape For Each sh In ActiveLayer.Shapes If sh.SizeWidth > 10 Then sh.SizeWidth = 10 End If Next sh

Understanding automation 21

If you want to copy the selection and then parse it later when it is no longer selected, copy the selection into a

ShapeRange object:

Dim sr As ShapeRange Dim sh As Shape Set sr = ActiveSelectionRange For Each sh In sr ' Do something with each shape Next sh

How are object shortcuts used?

Shortcuts are provided for some frequently accessed objects. Using shortcuts requires less typing, so shortcuts are easier to use than their longhand versions. (Also, using shortcuts can improve run-time performance because the compiler does not need to determine every object in a long dot-separated reference.)

For CorelDRAW, a shortcut can be used on its own as a property of the CorelDRAW

Application object. The

following table provides the shortcuts and their long forms for CorelDRAW. (For a description of any item, please see the “Object Model Reference” section of the CorelDRAW Macros Help file [draw_om.chm].)

Shortcut Long form

ActiveLayer ActivePage.ActiveLayer

ActivePage ActiveDocument.ActivePage

ActiveSelection ActiveDocument.Selection

ActiveSelectionRange ActiveDocument.SelectionRange

ActiveShape ActiveDocument.Selection.Shapes(1)

ActiveView ActiveWindow.ActiveView

ActiveWindow ActiveDocument.ActiveWindow

For Corel PHOTO-PAINT, a shortcut can be used on its own as a property of the Corel PHOTO-PAINT

Application object. The following table provides the shortcuts and their long forms for Corel PHOTO-

PAINT. (For a description of any item, please see the “Object Model Reference” section of the Corel PHOTOPAINT Macros Help file [pp_om.chm].)

Shortcut Long form

ActiveLayer ActivePage.ActiveLayer

ActiveWindow ActiveDocument.ActiveWindow

For CorelDRAW, the following shortcuts can also be used as members of a given

• ActiveLayer

• ActivePage

• ActiveShape

• ActiveWindow

Understanding automation 22

Document object:

For Corel PHOTO-PAINT, the following shortcuts can also be used as members of a given Document object:

• ActiveLayer

• ActiveWindow

For CorelDRAW, the Document object also has the properties Selection and SelectionRange, which let you get the selection or selection range (respectively) from a specified document regardless of whether that document is active.

How are event handlers provided?

While running, CorelDRAW and Corel PHOTO-PAINT raise various events to which macros can respond through the use of event handlers — subroutines with specific, defined names. Each macro project defines its event handlers in one of the following code modules:

• ThisMacroStorage — for macro projects that are stored in Global Macro Storage (GMS) files

• ThisDocument — for macro projects that are stored in documents

The GlobalMacroStorage object is a virtual object that represents each and all open documents. The GlobalMacroStorage object has several events that are raised at the time of any event, such as opening, printing, saving, or closing a document (although the range of events is actually greater than this because each one has a “before” and “after” event).

To respond to an event, you must provide an event handler — a subroutine in any ThisMacroStorage module with a specific name for which the application is pre-programmed to search. However, the application does check all ThisMacroStorage modules in all installed projects; for this reason, you can create an event-driven solution and distribute it as a single project file just as you would provide any other solution. Each project can have only one ThisMacroStorage module, and it is automatically created when the project is first created.

In VBA, you can add event handlers to a ThisMacroStorage module by using the Macro Editor. For example, a CorelDRAW macro solution may need to respond to the closing of a document by logging the closure in a file as part of a workflow-management system. To respond to the opening of a document, the solution must respond to the

OpenDocument event for the GlobalMacroStorage class. To create this event handler in VBA, do the

following:

•Open a ThisMacroStorage module for editing in the Macro Editor.

•Next, choose GlobalMacroStorage from the Object list box at the top of the Code window, and then choose DocumentOpen from the Procedure list box.

The Macro Editor creates a new, empty subroutine called

GlobalMacroStorage_DocumentOpen()— or, if that

subroutine already exists, the Macro Editor places the cursor into it. To then add the name of the opened file to the log, you need only write some code. To reduce the size of the ThisMacroStorage module, you can assign this event-logging task to a public subroutine in another module. This technique lets the run-time interpreter more easily parse all the ThisMacroStorage modules each time an event is raised. The following VBA code illustrates this example for CorelDRAW:

Private Sub GlobalMacroStorage_OpenDocument(ByVal Doc As Document, _ ByVal FileName As String) Call LogFileOpen(FileName) End Sub

Understanding automation 23

Here is a small sample of the events available in CorelDRAW:

Event Description

Start

DocumentNew

DocumentOpen

DocumentBeforeSave

DocumentAfterSave

DocumentBeforePrint

DocumentAfterPrint

SelectionChange

DocumentClose

Quit

Event handlers for frequent events — such as events related to the Shape class — should be as efficient as possible, to keep the application running as quickly as possible.

Raised when the user starts the application

Raised when a document is created; passes a reference to the document

Raised when a document is opened; passes a reference to the document

Raised before a document is saved; passes the file name of the document as a parameter

Raised after a document is saved; passes the file name of the document as a parameter

Raised before the Print dialog box is displayed

Raised after a document is printed

Raised when a selection changes

Raised before a document is closed

Raised when the user quits the application

Understanding automation 24

Getting started with macros

Now that you understand a bit about automation, you’re ready to get started with macros. This section provides an overview of the macro-related tools and functionalities of CorelDRAW and Corel PHOTO-PAINT.

This section contains the following topics:

• Setting up the automation feature

• Using the Macros toolbars

• Using the Macro Manager docker

• Using the Add-in Manager

• Using the Macro Editor

•Using the VSTAEditor

Setting up the automation feature

Before you can develop and run macros in CorelDRAW Graphics Suite X5, you may need to set up the automation features for VBA and VSTA.

When you perform a “typical installation” of CorelDRAW Graphics Suite X5, the VBA and VSTA features are installed by default. However, you can manually install them if necessary. You can also specify various options for VBA.

• To install the VBA and VSTA features

• To specify VBA options

To install the VBA and VSTA features

1 Insert the installation disc into your computer.

If the installation wizard does not start automatically, locate and run the Setup.exe file on the installation disc.

2 Follow the on-screen instructions for modifying the software.

3 On the Features page of the setup, enable the following check boxes in the Utilities list box:

• Visual Basic for Applications 6.4

• Visual Studio Tools for Applications

CorelDRAW Graphics Suite X5 Macro Programming Guide 25

In the Utilities list box, enable the Visual Basic for Applications 6.4 and Visual Studio

Tools for Applications check boxes

To specify VBA options

1 Click To o l s ` Options.

2 In the Wo rk s pa c e list of categories, click VBA.

3 In the Security area, specify how to control the risk of running malicious macros by clicking Security

options. If you want to bypass this security feature, enable the Trust all installed GMS modules check box, and then

proceed to step 6.

4 On the Security level page of the Security dialog box, enable one of the following options:

• Very hig h — allows only macros installed in trusted locations to run. All other signed and unsigned

macros are disabled.

• High — allows only signed macros from trusted sources to run. Unsigned macros are automatically

disabled.

• Medium — lets you choose which macros run, even if they are potentially harmful.

• Low (not recommended) — allows all potentially unsafe macros to run. Enable this setting if you have

virus-scanning software installed, or if you check the safety of all documents that you open.

5 On the Trusted publishers page of the Security dialog box, review which macro publishers are trusted.

Click View to display details on the selected macro publisher, or click Remove to delete the selected macro publisher from the list.

If desired, you can enable or disable the Trust access to Visual Basic project check box for the selected macro publisher.

6 Disable the Delay load VBA check box if you want to load the VBA feature at start-up.

Getting started with macros 26

Using the Macros toolbars

CorelDRAW and Corel PHOTO-PAINT feature a Macros toolbar that lets you access common macro functionalities.

Using the Macros toolbar in CorelDRAW

The Macros toolbar in CorelDRAW provides easy access to several macro-related features, such as the Macro Editor.

The Macros toolbar in CorelDRAW

The Macros toolbar features the following buttons:

• Macro Manager button — opens the Macro Manager docker

• Run Macro button — runs a macro

• Macro Editor button — opens the Macro Editor

• Disable application events button — switches the Macro Editor between its modes for designing and running macros

• Start Recording button — records a macro

• Pause Recording button — pauses the recording of a macro

• Stop Recording button — stops the recording of a macro

To d i sp l a y th e Macros toolbar in CorelDRAW, click Window ` To o l b a r s ` Macros. A check mark next to the command indicates that the toolbar is displayed.

Using the Macros toolbar in Corel PHOTO-PAINT

The Macros toolbar in Corel PHOTO-PAINT provides easy access to a few macro-related features, such as the Macro Editor.

The Macros toolbar in Corel PHOTO-PAINT

The Macros toolbar features the following buttons:

• Macro Manager button — opens the Macro Manager docker

• Run Macro button — runs a macro

• Macro Editor button — opens the Macro Editor

• Disable application events button — switches the Macro Editor between its modes for designing and running macros

To d i sp l a y th e Macros toolbar in Corel PHOTO-PAINT, click Window ` To o l b a r s ` Macros. A check mark next to the command indicates that the toolbar is displayed.

Getting started with macros 27

Using the Macro Manager docker

In CorelDRAW and Corel PHOTO-PAINT, macros are stored in code modules, which are stored in macro projects. The Macro Manager docker in CorelDRAW and Corel PHOTO-PAINT provides a list of all existing VBA macro projects, plus the code modules and macros that are stored in them. You can use the Macro Manager docker to perform various tasks related to macro projects, code modules, and macros (as explained in “Creating macros” on page 43).

The Macro Manager docker in CorelDRAW, with a macro selected

The Macro Manager docker in Corel PHOTO-PAINT, with a macro selected

To d i sp l a y th e Macro Manager docker, do one of the following:

•Click To o l s ` Macros ` Macro Manager.

•Click the Macro Manager button on the Macros toolbar.

Using the Add-in Manager

An add-in is a separate module that extends the functionality of an application. The Add-in Manager for CorelDRAW and Corel PHOTO-PAINT displays a list of all registered add-ins for the application.

To open the Add-in Manager, click To o l s ` Macros ` Add-in Manager. You can then use the Add-in Manager to perform various tasks related to add-ins.

You can use a registered add-in by clicking To o l s ` Macros ` Add-ins and then choosing the add-in.

Getting started with macros 28

Using the Macro Editor

CorelDRAW and Corel PHOTO-PAINT provide an integrated development environment (IDE) for creating VBA macro projects. Called the Macro Editor, this IDE is similar to the one included with the full version of Visual Basic. You can use the Macro Editor to perform various tasks related to VBA macros, such as the following:

• browsing the contents of a VBA macro project

• developing and debugging VBA macro code

• setting object properties for VBA macros

• creating dialog boxes or “forms” for VBA macros

You cannot use the Macro Editor to compile executable (EXE) program files.

The Macro Editor features three main areas:

• Project Explorer — lets you browse macro projects and their contents. For more information, see “Using the Project Explorer” on page 30.

• Code window — lets you work with macro code. For more information, see “Using the Code window” on page 31.

• Properties window — lists all editable properties for the selected object. For more information, see “Using the Properties window” on page 35.

The Macro Editor also features four main toolbars:

• Standard toolbar — is the default toolbar

• Debug toolbar — contains buttons for common debugging tasks

• Edit toolbar — contains buttons for common code-editing tasks

• UserForm toolbar — contains buttons specific to designing dialog boxes

For more information on these toolbars, see “Using the Macro Editor toolbars” on page 35.

Getting started with macros 29

The Macro Editor features the following: 1) Project Explorer; 2) Code window; 3) Properties

window; 4) Standard toolbar; 5) Debug toolbar; 6) Edit toolbar; 7) UserForm toolbar

The Macro Editor also lets you access the Object Browser, which displays the entire object model of each referenced component and of CorelDRAW or Corel PHOTO-PAINT. For more information, see “Using the Object Browser” on page 36.

You can access the Macro Editor from within CorelDRAW or Corel PHOTO-PAINT. Although the Macro Editor opens in a separate window, it runs within the process of its source application. To display the Macro Editor, do any of the following:

•Click To o l s ` Macros ` Macro Editor on the main menu in the application.

•Click the Macro Editor button on the Macros toolbar.

•Right-click Visual Basic for Applications in the Macro Manager docker, and then click Show IDE.

• Press Alt + F11.

To switch between the Macro Editor and the application, use the Windows taskbar, or press Alt + F11 or Alt + Tab.

For more detailed information on constructing code procedures and setting properties, please see the Microsoft Visual Basic for Applications Help file, which is available from the Help menu in the Macro Editor.

Using the Project Explorer

The Project Explorer is essential for navigating macro projects and their contents: documents and objects, forms, modules, and class modules (or “classes”).

Getting started with macros 30

The Project Explorer

Each type of component in the Project Explorer has an icon assigned to it:

Icon Item

macro project

folder

document or object (CorelDRAW)

document or object (Corel PHOTO-PAINT)

form

module

class module (or “class”)

To display or hide the Project Explorer, do any of the following:

•Click View ` Project Explorer.

•Click the Project Explorer button on the Standard toolbar.

• Press Ctrl + R.

Using the Code window

The Code window is where you spend most of your time when working on macros. A standard code editor in the style of Microsoft Visual Studio, the Code window lets you do the following:

• format code automatically

• color syntax automatically

Getting started with macros 31

• check syntax automatically

• jump to definitions

• use contextual pop-up lists and automatic completion

If you are already familiar with any of the Microsoft Visual Studio editors, the Code window will be entirely familiar to you.

The Code window

To d i sp l a y th e Code window, do one of the following:

•Click View ` Code.

• Press F7.

Formatting code automatically

The Macro Editor formats code automatically for you. Even the capitalization of keywords, functions, subroutines, and variables is taken care of by the Macro Editor, irrespective of what you type. You cannot custom-format code, although you can set the indentation for each line, as well as the placing of custom line breaks.

If you use the returned value when calling a function, the parentheses around the parameters are mandatory (just as in most modern programming languages):

a = fooFunc (b, c)

However, if the returned value from a function call is being discarded, or if you are calling a subroutine, the parentheses must be left out (unlike in most other languages):

barFunc d, e fooBarSub f

If you prefer always to see the parentheses, use the Call keyword before the function call or subroutine call:

Call barFunc (d, e) Call fooBarSub (f)

Getting started with macros 32

Coloring syntax automatically

As you develop code in the Code window, the Macro Editor colors each word according to its classification.

Word color Classification

Blue Automation keyword or programming statement

Green Comment

Black All other text

The Code window also uses the following colorization techniques:

Colorization technique Classification

Red text Line of code containing errors

White text on blue background Selected text

Text highlighted in yellow Line where execution is paused for debugging

White text on red background and red dot in the left margin

Blue dot in the left margin Bookmark set in the code

Breakpoint set for debugging purposes

For more information, see “Setting breakpoints” on page 53.

These syntax-colorization techniques make the code much easier to read.

Syntax coloring and highlighting

Breakpoints and bookmarks are lost when you quit the application.

The Macro Editor lets you modify the default colors for syntax highlighting. Click To o l s ` Options, and choose your settings on the Editor Format page.

Checking syntax automatically

Every time you move the cursor out of a line of code, the Macro Editor checks the syntax of the code in that line; if an error is found, the line is colored red and a pop-up warning is displayed. This real-time checking is useful

Getting started with macros 33

(particularly when you are learning to program macros) because it indicates many possible errors in the code without having you run the code.

The Macro Editor lets you disable pop-up warnings. Click To o l s ` Options, click the Editor tab, and then disable the Auto Syntax Check check box. Although the Macro Editor still checks the syntax and colors erroneous lines red, it stops displaying a warning when you paste text from another line of code.

Jumping to definitions

The Macro Editor lets you jump directly to the definition of a variable, function, or object.

Desired definition Procedure Destination

Variable Right-click the variable in the Code

window, and then click Definition.

Function Right-click the function in the Code

window, and then click Definition.

Object Right-click the object in the Code

window, and then click Definition.

The definition of the variable in the code

The definition of the function in the code

The definition of the object in the Object Browser

To return to where you requested the definition, right-click anywhere in the Code window, and then click Last Position.

Using contextual pop-up lists for automatic completion

The Macro Editor adds the functions you write and the variables you define to an internal list that contains all built-in keywords and enumerated values. As you type, the Macro Editor displays a contextual list of words that are valid candidates for insertion at the current position. This auto-completion feature makes code development quicker and more convenient.

An auto-completion pop-up list

If you type the first few characters of the word you want to use, the pop-up list advances to the nearest candidate that matches those characters. Select the desired word, and then do one of the following:

• type the character to follow the word (typically a space, line feed, parenthesis, period, or comma)

• enter only the word by pressing Ta b or Ctrl + Enter

Getting started with macros 34

To force the pop-up menu display, press Ctrl + Spacebar; the menu scrolls to the word that most closely matches the characters that you have typed so far. This technique is particularly useful for filling parameter lists when calling a function or subroutine. If there is only one exact match, the Macro Editor inserts the word without popping up the list; to display the pop-up list for the selected keyword at any time without auto-filling it, press Ctrl + J.

Using the Properties window

The Properties window lists all editable properties for the selected object. Many macro objects — including projects, modules, and forms and their controls — have property sheets that can be modified.

The Properties window, with the properties of a form displayed

The Properties window is automatically updated when you select an object, or when you change the properties of the selected object by using other methods (for example, by using the mouse to move and resize form controls).

To display or hide the Properties window, do any of the following:

•Click View ` Properties Window.

•Click the Properties Window button on the Standard toolbar.

• Press F4.

Using the Macro Editor toolbars

The Macro Editor features four toolbars — Standard, Debug, Edit, and UserForm — that you can use to perform macro-related tasks.

The Standard toolbar is the default toolbar.

The Standard toolbar

Getting started with macros 35

The Debug toolbar contains buttons for common debugging tasks (as discussed in “Debugging macros” on page 51).

The Debug toolbar

The Edit toolbar contains buttons for common code-editing tasks.

The Edit toolbar

The UserForm toolbar contains buttons specific to designing dialog boxes (as discussed in “Designing dialog boxes” on page 59).

The UserForm toolbar

To display or hide a toolbar, click View ` To o l b a r s , and then click the corresponding command. A check mark next to a command indicates that its toolbar is currently displayed.

You can “float” a toolbar by dragging it from the menu bar.

You can dock a toolbar by dragging it to the menu bar.

Using the Object Browser

The Object Browser is one of the most useful tools that is provided by the Macro Editor. In an easy-to-use, structured format, the Object Browser displays the entire object model of each referenced component and, most importantly, of CorelDRAW or Corel PHOTO-PAINT.

Referenced components include all ActiveX or Object Linking and Embedding (OLE) objects that are used by the project.

The Object Browser window features the following items:

• Project/Library list box — lists all referenced components (projects and libraries). Choosing a project or library from this list updates the Object Browser to display only the items for that project or library. Generally, displaying only one project or library at a time makes it easier to use the Object Browser.

• navigation buttons — let you cycle through your selections from the Object Browser

• Copy to Clipboard button — copies the current selection to the Clipboard

• View Definition button — displays where the current selection is defined in the Code window

• Help button — displays a Help topic for the current selection. You can also access this Help topic by pressing F1.

• search controls — let you search the selected project or library for a given string. For more information, see “Using the search controls” on page 41.

• Search Results window — displays the results of a search. For more information, see “Using the search controls” on page 41.

Getting started with macros 36

• Class list — displays all class-related items for the selected project or library. For more information, see “Using the Class list” on page 37.

• Member list — displays the members of the selected class. For more information, see “Using the Member list” on page 39.

• Information window — displays information about the selected class or class member. For more information, see “Using the Information window” on page 40.

Project/ Library

list box

search controls

Search Results

window

Class list

Member

list

Information

window

The Object Browser window

navigation

buttons

Help

button

View

Definition

button

Copy to

Clipboard

button

To open the Object Browser from within the Macro Editor, do any of the following:

•Click View ` Object Browser.

•Click the Object Browser button on the Standard toolbar.

• Press F2.

To reference the object model of another application, click To o l s ` References. Referenced components can be accessed by the macro code.

Using the Class list

Every project and library has an object model that contains the following class-related items, which are displayed in the Class list:

• global values

•classes

•modules

•types

•enumerations

Global values apply to an entire project or library, and they include individual members from enumerations (such as text-paragraph alignments, shape types, and import/export filters).

Getting started with macros 37

Classes contain properties, methods, and events. For more information, see “What is a class?” on page 12.

For documentation on all classes available to CorelDRAW or Corel PHOTO-PAINT, see the “Object Model Reference | Classes” section of the Macros Help file for the application.

Modules contain macro code.

For documentation on all modules available to CorelDRAW, see the “Object Model Reference | Modules” section of the Macros Help file for the application.

Types are customized data types that supplement the built-in data types that are provided by the automation environment (as described in “How are variables declared?” on page 14).

For documentation on all types available to CorelDRAW, see the “Object Model Reference | Types” section of the Macros Help file for the application.

Enumerations represent fixed values in the procedures and functions of the coding for a macro. For more information, see “What is an enumeration?” on page 13.

For documentation on all enumerations available to CorelDRAW or Corel PHOTO-PAINT, see the “Object Model Reference | Enumerations” section of the Macros Help file for the application.

Each type of item in the Class list has an icon assigned to it:

Icon Item

global value

class

module

type

enumeration

To access the Help topic for a selected item, click the Help button, or press F1.

Getting started with macros 38

Using the Member list

When you choose an item from the Class list, the members of that item appear in the Member list. Class members include the following:

•properties

•methods

•events

•constants

A property can be a simple type (such as a Boolean, integer, or string), or it can be a class or enumeration from the Class list. A property that is based on a class from the Class list inherits all members of that class.

Many classes have a default property. The default property is implied if no property name is given when getting or setting the value of the parent object. For example, collection types have the default property Item, which can be indexed; in such instances, it is not necessary to specify the Item property. Here,

ActiveSelection.Shapes.Item(1).Selected = False

is the same as the shorter

ActiveSelection.Shapes(1).Selected = False

because Item is the default or implied property of a collection of shapes.

For documentation on all properties available to CorelDRAW or Corel PHOTO-PAINT, see the “Object Model Reference | Properties” section of the Macro Help file for the application.

Methods are commonly known as “member functions” — functions that a class can perform on itself. A good example is the Move method of the Shape class in CorelDRAW, which moves a shape by using an [x, y] vector. The following code moves the selected shapes 2 measurement units to the right and 3 measurement units upwards:

ActiveSelection.Move 2, 3

If the return value of a function is not used, the function call does not take parentheses around the argument list unless the

Call keyword is used.

For documentation on all methods available to CorelDRAW or Corel PHOTO-PAINT, see the “Object Model Reference | Methods” section of the Macro Help file for the application.

Events are associated with some classes. You can set up an event handler that is called when that event occurs in the application; this functionality lets you develop sophisticated applications that respond automatically to what is happening within the application. Commonly handled events include the BeforePrint, BeforeSave, PageActivate, SelectionChange, and ShapeMove events of the Document class.

For documentation on all events available to CorelDRAW or Corel PHOTO-PAINT, see the “Object Model Reference | Events” section of the Macro Help file for the application.

The constants displayed in the Member list are members of enumerations or are defined as public in a module. Enumerations group related items from a closed list — such as CorelDRAW shape types, import/export filters, and alignments — for use anywhere an integer value is required.

Getting started with macros 39

Many CorelDRAW and Corel PHOTO-PAINT constants begin with cdr (for example, cdrEPS and cdrLeftAlignment), while others begin with clr, cui, pdf, pnt, or prn. Visual Basic also has its own constants,

including ones (such as vbKeyEnter) for keystrokes and ones (such as vbOK) for dialog-box buttons.

For documentation on all constants available to CorelDRAW or Corel PHOTO-PAINT, see the “Object Model Reference | Constants” section of the Macro Help file for the application.

Each type of item in the Member list has an icon assigned to it:

Icon Item

property

default property

method

event

constant

To access the Help topic for a selected item, click the Help button, or press F1.

Using the Information window

The Information window provides information about the selected class or class member. This information includes the following:

• a prototype of the item

• an indication of whether the item is a read-only property

• the parent of the item

• a short description of the item

The Information window for the Document.Application property in

Corel PHOTO-PA IN T

Getting started with macros 40

The Information window provides hyperlinks to all referenced types and classes that are defined within the current object model. For example, the information for the Document.Application property in Corel PHOTOPAINT (see the preceding figure) includes the following hyperlinks:

• Application — accesses the Application class, because Application is both the type of the Document.Application property and a class in the PHOTOPAINT library

• PHOTOPAINT — accesses the class for the PHOTOPAINT library, which contains all classes in the Corel PHOTO-PAINT object model

• Document — accesses the Document class, which is the parent of the Application property

When the Information window is not tall enough to reveal its complete contents, a scroll bar is provided. To increase the height of the Information window, drag the top border of the window upwards.

Using the search controls

The search controls let you search the selected project or library for a given string. Searching is useful when you can only partly remember the name of a class or class member, or when you want to find classes and members that have similar names (such as those containing the word “open”).

Searching an object model

To search the classes and members of the selected object model, type a string into the Search box, and then click the Search button . The Search Results window displays, in alphabetical order, all matches. Clicking a match advances the Class list and Member list to that item and displays the Information window for that item.

Matching class names have a blank Member column in the Search Results window.

To hide the Search Results window, click the Hide Search Results button .

Getting started with macros 41

Using the VSTA Editor

CorelDRAW and Corel PHOTO-PAINT provide an integrated development environment (IDE) for creating VSTA macro projects. Called the VSTA Editor, this IDE is similar to the Macro Editor (which is the IDE for VBA macro projects in CorelDRAW and Corel PHOTO-PAINT). You can use the VSTA Editor to perform various tasks related to VSTA macros.

By default, CorelDRAW Graphics Suite X5 creates VSTA folders at the following location:

•for CorelDRAW: My Documents\Corel\VSTA\CorelDRAW

• for Corel PHOTO-PAINT: My Documents\Corel\VSTA\Corel PHOTO-PAINT

Be sure to load VSTA add-ins from the following location:

•for CorelDRAW: My Documents\Corel\VSTA\CorelDRAW\Addins

• for Corel PHOTO-PAINT: My Documents\Corel\VSTA\Corel PHOTO-PAINT\Addins

You can open the VSTA Editor from within CorelDRAW or Corel PHOTO-PAINT. Although the VSTA Editor opens in a separate window, it runs within the process of its source application. To open the VSTA Editor, do any of the following:

•Click To o l s ` Macros ` VSTA Editor on the main menu in the application.

• Press Alt + Shift + F12.

To switch between the VSTA Editor and the application, use the Windows taskbar, or press Alt + Shift F12 or Alt + Tab.

For more detailed information on VSTA and its programming environment, consult the Help menu in the VSTA Editor.

Getting started with macros 42

Creating macros

Now that you are familiar with the concept of automation and with the macro-related tools and functionalities of CorelDRAW and Corel PHOTO-PAINT, you are ready to create macros.

This section contains the following topics:

• Creating macro projects

•Writing macros

• Recording macros

• Running macros

• Debugging macros

Creating macro projects

The process of creating a macro begins with creating a macro project. A macro project can be created in one of two ways:

• as a Global Macro Storage (GMS), or “project,” file

• in a document

For best results in storing and distributing a macro project, it is highly recommended that you use a GMS file. GMS files are stored in the GMS folder for the application, which is installed at the following locations:

• for macro projects that ship with CorelDRAW Graphics Suite X5: X:\Program Files\Corel\

CorelDRAW Graphics Suite X5\<application> (where X: is the drive and Program Files\Corel\ CorelDRAW Graphics Suite X5 is the path where the software is installed, and where <application> is the

application subfolder)

• for user-created macro projects on Windows 7 and Windows Vista®: X:\Users\<user name>\

AppData\Roaming\Corel\\<application> (where X: is the drive where the software is installed, <user name> is the name of the user, and <application> is the application subfolder)

• for user-created macro projects on Windows XP: X:\Documents and Settings\<user name>\ Application Data\Corel\CorelDRAW Graphics Suite X5\<application> (where X: is the drive where the

software is installed, <user name> is the name of the user, and <application> is the application subfolder)

The Macro Manager docker provides basic tools for working with macro projects. For access to more advanced tools, you can use the Macro Editor (for VBA macro projects) or the VSTA Editor (for VSTA macro projects).

CorelDRAW Graphics Suite X5 Macro Programming Guide 43

In the Macro Editor, a VBA macro project is broken into four types of components, which are displayed as the following folders in the Project Explorer (see “Using the Project Explorer” on page 30):

• CorelDRAW X5 Objects or Corel PHOTO-PAINT X5 Objects — contains a single item that is used mostly for event handling: ThisMacroStorage for GMS-based macro projects, or ThisDocument for document-based macro projects. For normal code, this module is not used.

• Forms — contains customized dialog boxes and user interfaces, plus the code to control them

• Modules — contains code modules, for storing general code and macros

• Class Modules — contains object-oriented Visual Basic class modules (which are not discussed in this documentation)

In the Macro Editor, you cannot move a component from one folder to another within the same project. However, you can drag a component to another project to make a copy of it there.

For detailed procedures on creating macro projects, see the following topics:

• To create a macro project

• To add a dialog box to a macro project

• To add a code module to a macro project

• To add a class module to a macro project

To create a macro project

• In the Macro Manager docker, do one of the following:

•Click Visual Basic for Applications in the list, click New, and then click New macro project.

•Right-click Visual Basic for Applications in the list, and then click New macro project.

Project names must follow normal variable-naming conventions: They must begin with an alphabetic character, and they must not contain spaces nor special characters other than underscores ( _ ).

You can also

Load a macro project Do one of the following:

•Click Visual Basic for Applications in the list, click Load, and then choose the project.

•Right-click Visual Basic for Applications in the list, click Load macro project, and then choose the project.

Rename a macro project Right-click the project in the list, and then click Rename.

You can also rename a macro project from within the Macro Editor. Click the project in the Project Explorer, and then edit the (Name) value in the Properties window. Press Enter to commit your changes.

Creating macros 44

You can also

Copy a GMS-based macro project Right-click the project in the list, click Copy to, and then

choose the target location for the copy.

NOTE: You cannot copy a document-based macro project. Such projects are stored within a document and cannot be managed separately from that document.

Unload a GMS-based macro project Right-click the macro project in the list, and then click

Unload macro project.

NOTE: You can close a document-based macro project

only by closing the document in which it is stored.

Some macro projects are locked and cannot be modified.

To add a dialog box to a macro project

1 In the Project Explorer of the Macro Editor, right-click the project.

2 Click Insert ` UserForm.

A form is added to the Forms folder for the project.

Some macro projects are locked and cannot be modified.

For more information, see “Providing dialog boxes for macros” on page 57.

To add a code module to a macro project

• Do one of the following:

•In the Macro Manager docker, click the project in the list, click New, and then click New module.

•In the Macro Manager docker, right-click the project in the list, and then click New module.

• In the Project Explorer of the Macro Editor, right-click the project, and then click Insert ` Module.

You can also

Display or hide all code modules in the Macro Manager docker

Edit a code module In the Macro Manager docker, do one of the following:

Rename a code module In the Macro Manager docker, right-click the module in

In the Macro Manager docker, click the Simple mode button .

•Click the module in the list, and then click the Edit button .

•Right-click the module in the list, and then click Edit.

The code module opens in the Macro Editor.

the list, and then click Rename.

Creating macros 45

You can also

Delete a code module In the Macro Manager docker, do one of the following:

•Click the module in the list, and then click the Delete button .

•Right-click the module in the list, and then click Delete.

Some macro projects are locked and cannot be modified.

To add a class module to a macro project

1 In the Project Explorer of the Macro Editor, right-click the project.

2 Click Insert ` Class Module.

A new class module is added to the Class Modules folder for the project.

Some macro projects are locked and cannot be modified.

Detailed documentation on creating class modules is beyond the scope of this documentation.

Writing macros

You can manually code a macro by writing it in the Macro Editor or the VSTA Editor. (Alternatively, in CorelDRAW, you can create a VBA macro by recording it. For information, see “Recording macros” on page 47.) Macros that are developed in the Macro Editor or the VSTA Editor can take advantage of full programming control, including conditional execution, looping, and branching. In effect, you can write macros that are programs in their own right.

In this documentation, all macro code is referred to as a macro even though, in some contexts, a macro is just those parts of the code that can be run by CorelDRAW or Corel PHOTO-PAINT.

To write a macro, you must first add it to a code module for the desired macro project. You can edit, rename, or even delete macros.

For detailed procedures, see the following topics:

• To add a macro to a macro project

• To edit a VBA macro

• To delete a VBA macro

To add a macro to a macro project

1 In the Macro Manager docker, do one of the following:

• Click the desired container module in the macro project, click New, and then click New macro.

• Right-click the desired container module in the macro project, and then click New macro.

Some macro projects are locked and cannot be modified.

Creating macros 46

To edit a VBA macro

• In the Macro Manager docker, do one of the following:

• Click the macro in the list, and then click the Edit button

• Right-click the macro in the list, and then click Edit. The macro opens in the Macro Editor.

Some macro projects are locked and cannot be modified.

For detailed information on manually coding macros, see “How is automation coding structured?” on page 14.

To delete a VBA macro

• In the Macro Manager docker, do one of the following:

• Click the macro in the list, and then click the Delete button

• Right-click the macro in the list, and then click Delete.

Some macro projects are locked and cannot be modified.

Recording macros

CorelDRAW offers a recording feature that lets you create a macro without needing to manually code it. For many simple and repetitive tasks, recorded macros are a quick, efficient solution: They store the sequence of keys that you press and the mouse actions that you perform within the application. You may prefer to create macros by recording them if you are not familiar with the object model for the application, or if you are not sure which objects and methods to use.

In Corel PHOTO-PAINT, actions can be recorded as Corel SCRIPT scripts but not as VBA or VSTA macros. For information on recording scripts, see “Working with scripts” in the main Help file for Corel PHOTO-PAINT (corelpp.chm).

If you want to store a recorded macro for future use, you can save it by using the Record Macro dialog box. Saving a recorded macro is particularly useful if you want to extend or customize its functionality by editing it in the Macro Editor.

Creating macros 47

The Record Macro dialog box

However, if you want to use a recorded macro during the current session only, you can record a temporary macro.

For detailed procedures, see the following topics:

• To record and save a macro

• To record a temporary macro

To record and save a macro

1 Do one of the following:

•Click To o l s ` Macros ` Start recording, or click the Start recording button on the Macros toolbar, to store the macro in the default macro project for recordings.

• In the Macro Manager docker, click the project in which to store the macro, and then click the Record button .

The Record Macro dialog box appears.

2 In the Macro name box, type a name for the macro.

Macro names can contain numerals, but they must begin with a letter. Macro names cannot contain spaces or non-alphanumeric characters other than underscores ( _ ).

3 Type a description of the macro in the Description box, and then click OK.

4 Perform the actions that you want to record.

The application begins recording your actions. If you want to pause recording, do one of the following:

•Click To o l s ` Macros ` Pause recording. Repeat this step to resume recording.

•Click the Pause recording button on the Macros toolbar or in the Macro Manager docker. Repeat this step to resume recording.

Creating macros 48

To stop recording, do one of the following:

•Click To o l s ` Macros ` Stop recording.

•Click the Stop recording button on the Macros toolbar or in the Macro Manager docker.

• Press Ctrl+Shift+O.

You cannot record a macro if all available macro projects are locked..

Not all actions can be recorded — some because of their complexity (although many such actions can be manually coded in the Macro Editor). When an action cannot be recorded, a comment is placed in the macro code (“

The recording of this command is not supported.”), but the recording process

continues until you stop it. You can view any comments in the code by opening the macro in the Macro Editor.

You can specify the default macro project for recordings by right-clicking the project in the Macro Manager docker, and then clicking Set as recording project. However, you cannot specify a locked macro project.

You can cancel recording a macro, and discard any commands recorded thus far, by clicking To o l s ` Macros ` Cancel recording.

You can also

Save the actions in the Undo list as a VBA macro

Click To o l s record, and then click the Save list to a VBA macro

button in the Undo docker.

` Undo, perform the actions that you want to

To record a temporary macro

1 Do one of the following:

•Click To o l s ` Macros ` Record temporary macro.

• Press Ctrl+Shift+R.

2 Perform the actions that you want to record.

The application begins recording your actions. If you want to pause recording, do one of the following:

•Click To o l s ` Macros ` Pause recording. Repeat this step to resume recording.

•Click the Pause recording button on the Macros toolbar or in the Macro Manager docker. Repeat this step to resume recording.

3 To stop recording, do one of the following:

•Click To o l s ` Macros ` Stop recording.

•Click the Stop recording button on the Macros toolbar or in the Macro Manager docker.

• Press Ctrl+Shift+O.

The macro is temporarily saved to the default recording project. When the current session is ended, the macro is deleted from that project.

Creating macros 49

You cannot record a temporary macro if all available macro projects are locked.

Not all actions can be recorded.

You can specify the default recording project by right-clicking the project in the Macro Manager docker, and then clicking Set as recording project. (You cannot specify a locked macro project.) If you want, you can create multiple temporary recordings by assigning each one to its own macro project.

You can cancel recording a macro, and discard any commands recorded thus far, by clicking To o l s ` Macros ` Cancel recording.

Running macros

You can run saved macros either from directly within CorelDRAW or Corel PHOTO-PAINT or from within the Macro Editor.

The Run Macro dialog box

You can also run any temporary macro recorded in CorelDRAW.

For detailed procedures, see the following topics:

• To run a saved macro

• To run a temporary macro

To run a sa ved macro

• Do one of the following:

•Click To o l s ` Macros ` Run macro, or click the Run macro button on the Macros toolbar. From the Macros in list box, choose the project or file in which the macro is stored. From the Macro name list,

choose the macro. Click Run.

•In the Macro Manager docker, double-click the macro in the list.

•In the Macro Manager docker, click the macro in the list, and then click the Run button .

•In the Macro Manager docker, right-click the macro in the list, and then click Run.

• In the Macro Editor, click anywhere in the subroutine that forms the macro, and then click Run ` Run macro.

Creating macros 50

To run a temporary macro

• Do one of the following:

•Click To o l s ` Macros ` Run temporary macro.

• Press Ctrl+Shift+P.

This option is enabled only after you record a temporary macro.

If you have created multiple temporary macros, you must specify which macro project contains the one that you want to run. Right-click the project in the Macro Manager docker, and then click Set as recording project.

Debugging macros

To ensure that your macros run as expected, it’s important to debug them.

The Macro Editor provides four windows for debugging VBA code. The Macro Editor also provides two strong debugging facilities that are common to language editors: setting breakpoints, and stepping through code.

The Macro Editor also supports two advanced debugging techniques that are not discussed in this documentation: Making changes to the code while it is running, and watching and changing variables.

Using the debugging windows

The Macro Editor provides four windows for debugging VBA code: the Call Stack window, the Immediate window, the Locals window, and the Wa t ch es window. All of these windows provide important information about the state of functions and variables while an application is running.

The Call Stack window is a modal dialog box that lists which function calls which function. In long, complicated applications, this information is useful for tracing the steps to a particular function being called. To visit a function listed in the window, select the function name and then click Show, or else close the window.

To display the Call Stack window, click View ` Call Stack.

The Call Stack window

Creating macros 51

The Immediate window lets you type in and run arbitrary lines of code while a macro is paused. This functionality is useful for getting or setting the property of an object in the document, or for setting the value of a variable in the code. To run a piece of code, type it in the Immediate window, and then press Enter; the code is executed immediately.

To display the Immediate window, click View ` Immediate window.

The Immediate window

The Locals window displays all variables and objects that exist within the current scope. The type and value for each variable are listed in the columns next to the name of the variable. Some variables and objects have several children, which can be displayed by clicking the button next to the parent. Many variables let you edit their value by clicking it.

To display the Locals window, click View ` Locals window.

The Locals window

The Wa t ch e s window is used to watch specific variables or object properties. This functionality is useful for watching just one or two values rather than searching for them among all the values in the Locals window.

To display the Wa t ch e s window, click View ` Watch window.

Creating macros 52

The Watches window

To add a value to the Wa t ch e s window, do one of the following:

• Select the variable or object and its property, and then drag the selection onto the Wa t c he s window.

• Click the item, and then click Debug ` Quick watch.

The Add Watch dialog appears.

The Add Watch dialog box

Select the item that you want to watch, select any conditions for this watch, and then click OK. If the condition becomes true, the application pauses to let you examine the code.

Setting breakpoints

A breakpoint is a marker in a line of code that causes execution to pause. To continue, you must either restart the execution or step through the subsequent lines of code.

To set or clear a breakpoint, click the line, and then click Debug ` To g gl e b re a k po i n t . By default, the line is highlighted in dark red, and a red dot is placed in the margin.

To restart the code after it pauses at a breakpoint, click Run ` Continue. To pause the execution of the code (immediately exiting from all functions and discarding all return values), click Run ` Reset.

You can also “run to cursor” — that is, execute the code until it reaches the line that the cursor is on, and then pause at that line. To do this, click the line where you want execution to pause, and then click Debug ` Run to cursor.

Creating macros 53

To clear all breakpoints, click Debug ` Clear all breakpoints.

If the line with the breakpoint (or the cursor, when “running to cursor”) is not executed because it is in a conditional (if-then-else) block, the code does not stop at that line.

Breakpoints are not saved. They are lost when you close the Macro Editor.

Stepping through the code

When execution pauses at a breakpoint, you can continue through the code one line at a time. This functionality, called “stepping through the code,” lets you do the following:

• examine the values of individual variables after each line

• determine how the code affects the values

• determine how the values affect the code

To step through the code, click Debug ` Step into. The execution advances to every line in all called functions and subroutines.

To step through each line of the current function or subroutine but not through the lines of each called function or subroutine, click Debug ` Step over. The called functions and subroutines are executed, but not line-by-line.

To execute the rest of the current function or subroutine but pause when the function or subroutine returns to the point where it was called, click Debug ` Step out. This technique is a quick way of returning to the point of entry of a function, to continue stepping through the code of the calling function.

Creating macros 54

Making macros user-friendly

An important part of many macro solutions is the user interface. A well-designed interface improves the ease-ofuse, power, and acceptance of a macro solution. Simple user interfaces can be created with toolbars, while more complex interfaces can be created with dialog boxes or dockers — and can even allow the user to interact with the mouse.

However, for some macro solutions, a user interface alone is not enough. To make a macro solution as userfriendly as possible, you can provide documentation for it.

This section contains the following topics:

• Providing toolbars for macros

• Providing dialog boxes for macros

• Providing user interaction for macros

• Providing documentation for macros

Providing toolbars for macros

A toolbar provides a basic interface that enhances the user’s experience with your macro solution. Toolbars are useful because their buttons are memorable even if small, and because those buttons can be set to display meaningful captions and helpful tooltips.

Designing toolbars for macros

When creating toolbars, you should plan carefully. Having multiple small toolbars containing a few related buttons is better than having one big toolbar containing all of the buttons for all of your macros. By breaking your buttons into small groups, it is much easier to deploy them with the projects to which they belong.

For more information, see the following procedures:

• To create a macro toolbar

• To add buttons to a macro toolbar

Associating images or icons with macros

Macro commands can have an image or icon associated with them. This image or icon can be displayed or hidden on toolbars and menus, and it can be sized as small (16 × 16 pixels), medium (32 × 32 pixels), or large (48 × 48 pixels).

For more information, see the following procedure:

• To associate an image or icon with a macro

CorelDRAW Graphics Suite X5 Macro Programming Guide 55

Setting captions and tooltips for macros

Each macro can have both a caption and a tooltip. The caption is displayed whenever the menu command is used and can be displayed as part of a button, while the tooltip appears when the pointer hovers over the button or menu item.

For more information, see the following procedures:

• To set a caption for a macro

• To set a tooltip for a macro

To create a macro toolbar

1 Click To o l s ` Options.

2 Click Wo r ks p a ce ` Customization ` Command bars.

3 Click New.

4 Type a name for the toolbar.

5 Enable the check box next to the name of the toolbar.

To add buttons to a macro toolbar

1 Click Wo r ks p a ce ` Customization ` Commands.

2 Choose Macros from the Commands list box.

The list displays the fully qualified names of all of the public, parameter-free subroutines from all of the installed project (GMS) files.

3 Drag a macro from the list to the toolbar.

The macro appears on the toolbar with the default macro icon.

To associate an image or icon with a macro

1 Click Wo r ks p a ce ` Customization ` Commands.

2 Choose Macros from the Commands list box.

The list displays the fully qualified names of all of the public, parameter-free subroutines from all of the installed project (GMS) files.

3 Select a macro in the Command list.

4 Click the Appearance tab, and then do one of the following:

• To apply a Windows bitmap (BMP) image to the macro, click Import, navigate to where the image is stored, and select it. The colors in the image are mapped to their closest available matches.

• To create a customized icon for the macro, edit the pixels displayed in the Image area.

To set a caption for a macro

1 Click Wo r ks p a ce ` Customization ` Commands.

2 Choose Macros from the Commands list box.

The list displays the fully qualified names of all of the public, parameter-free subroutines from all of the installed project (GMS) files.

Making macros user-friendly 56

Select a macro in the Command list.

4 Click the Appearance tab, and then type the caption in the Caption box.

To specify a character in the caption as an accelerator that can be activated in combination with the Alt key, type an ampersand ( & ) in front of that character. This accelerator key applies only to menu commands, which display accelerator characters with an underscore ( _ ).

To set a tooltip for a macro

1 Click Wo r ks p a ce ` Customization ` Commands.

2 Choose Macros from the Commands list box.

The list displays the fully qualified names of all of the public, parameter-free subroutines from all of the installed project (GMS) files.

3 Select a macro in the Command list.

4 Click the General tab, and then type the tooltip in the To o l t i p h e l p box.

Providing dialog boxes for macros

A dialog box provides a user-friendly interface for more complex macro solutions.

For best results, all dialog boxes must provide the following:

• a meaningful title

• an obvious function for cancelling or closing the dialog box

• an easy-to-use layout

• a Help button from which users can access how-to documentation

• a tooltip (that is, a ControlTipText string) for every control

There are two kinds dialog boxes: modal and modeless.

Understanding modal dialog boxes

A modal dialog box locks the application until the user acts on and then closes the dialog box. Most built-in dialog boxes for macro solutions are modal, and most modal dialog boxes provide the following buttons:

• OK — performs an action and then closes the dialog box. This button is the default.

• Cancel — closes the dialog box without performing an action. This button provides the same functionality as the Close button in the upper-right corner of a dialog box.

In addition, some modal dialog boxes provide the following button:

• Apply — performs an action that can be commited by clicking the OK button or cancelled by clicking the Cancel button

Finally, most wizard-style dialog boxes provide the following buttons:

• Previous — returns to the previous page. This button can be disabled on the first page of the dialog box.

• Next — advances to the next page. This button can be replaced by a Finish button on the last page of the dialog box.

• Finish — performs the action for the dialog box and then closes the dialog box

Making macros user-friendly 57

Understanding modeless dialog boxes

A modeless dialog box does not lock the application, so the user can leave the dialog box open and continue working in the application. In this way, modeless dialog boxes behave like dockers. Most modeless dialog boxes provide the following buttons:

• Apply or Create — performs an action (and can, in fact, be specially labeled to describe that action). This button is typically the default.

• Close –– closes the dialog box. This button is used after the action is applied.

Choosing between modal and modeless dialog boxes

Before you can create a dialog box for your macro solution, you must decide whether to make it modal or modeless by considering what you want the dialog box to achieve.

For example, let’s say that you are creating a “one-shot” end-to-end solution such as a customized Print dialog box or Save dialog box. In this case, you would provide a modal dialog box because it is unlikely that the user would want to apply the specified settings repeatedly.

On the other hand, let’s say that you are creating a solution for setting up an effect to apply to a selection of shapes. To let the user specify the desired settings and then apply them repeatedly, you would provide a modeless dialog box.

After choosing which type of dialog box to provide, you are ready to set it up. For information, see “Setting up dialog boxes” on page 58.

After setting up a dialog box, you are ready to code it. For information, see “Coding dialog boxes” on page 61.

Setting up dialog boxes

The Form Designer in the Macro Editor provides easy access to the tools for setting up a dialog box.

You can access the Form Designer by creating a new, blank dialog box. In the Project Explorer, right-click the project to which you want to add a dialog box, and then click Insert ` UserForm.

A blank form in the Form Designer

Making macros user-friendly 58

The Form Designer provides two main features for designing dialog boxes:

•the Form Designer toolbox

•The UserForm toolbar

The Form Designer also provides functions for naming and testing dialog boxes.

Designing dialog boxes

The Form Designer toolbox is the main utility for designing dialog boxes. It lets you add controls to a dialog box by dragging them from the toolbox.

The Form Designer toolbox

The Form Designer toolbox lets you add the following controls to a dialog box:

Icon Control name Function

Label

Te x t B o x

Provides static text, such as instructions or captions

Provides an area for typing text. For information on coding this control, see “Providing text boxes in dialog boxes” on page 61.

ComboBox

Provides a list from which a single item can be selected; optionally, also provides an area for typing text. For information on coding this control, see “Providing combination boxes and list boxes in dialog boxes” on page 62.

ListBox

Provides a list from which multiple items can be selected. For information on coding this control, see “Providing combination boxes and list boxes in dialog boxes” on page 62.

CheckBox

Provides a check box that can be enabled (by clicking to display a check mark), disabled (by clicking to remove the check mark), or grayed (that is, made unavailable)

OptionButton

Provides a “radio button” that is linked to other radio buttons with the same

GroupName property, such that only one of the buttons can be enabled at a time

ToggleButton

Provides a button that can be toggled (to appear pressed or not pressed)

Making macros user-friendly 59

Icon Control name Function

Frame

CommandButton

Groups items together so that they move with the frame

Provides a button that can be clicked to commit an assigned action. For information on coding this control, see “Providing buttons in dialog boxes” on page 62.

Ta b S t r i p

MultiPage

ScrollBar

SpinButton

Provides separate views of related controls

Provides multiple pages of controls

Provides immediate access to a range of values by scrolling

Enhances another control (such as a Te x t B o x control) so that the value for that

control can be set more quickly

Image

Provides an image. For information on coding this control, see “Providing images in dialog boxes” on page 64.

The Form Designer toolbox also features a Pick tool , which lets you select and move the controls on a dialog box.

To display a Help topic containing information about a selected dialog-box control in the Form Designer, press F1.

The Form Designer also provides access to the UserForm toolbar, which you can use when designing a dialog box. For information on this toolbar, see “Using the Macro Editor toolbars” on page 35.

Naming dialog boxes

After you have finished designing your dialog box, you may want to change its title. Click the dialog box to select it, and then in the Properties window, change the Caption property.

For clarity, you can give each dialog box a unique, descriptive name by using the Properties window. However, remember to follow the standard programming conventions for naming variables.

Testing dialog boxes

At any time, you can test your dialog box by pressing F5 to run it.

After you finish setting up your dialog box, you can start coding it. For information, see “Coding dialog boxes” on page 61.

Making macros user-friendly 60

Coding dialog boxes

After setting up a dialog box, you can develop the VBA code for displaying it. You can also develop the code for providing its text boxes, combination boxes and list boxes, buttons, and images.

Displaying dialog boxes

The Show method for a dialog box lets you determine how the dialog box is displayed.

For example, the following code uses the Show method to display the dialog box frmFooForm:

frmFooForm.Show

In addition, the Show method provides a Modal parameter, which lets you specify whether the dialog box is modal or modeless. A value of vbModal (or 1) for this parameter creates a modal dialog box, while a value of vbModeless (or 0) creates a modeless dialog box. The following VBA example creates a modeless dialog box:

frmFooForm.Show vbModeless

To open a dialog box from a macro that is available from within the application itself, you must create a public subroutine within a code module. However, a subroutine cannot be made available from within the application if the subroutine exists either within the code for a dialog box or within a class module. In addition, the subroutine cannot take any parameters.

The following VBA example subroutine opens frmFooForm as a modeless dialog box:

Public Sub showFooForm() frmFooForm.Show vbModeless End Sub

When a dialog box loads, it triggers its own UserForm_Initialize event. From this event handler, you must initialize all the relevant controls on the dialog box. For more information, see “How are event handlers provided?” on page 23.

Finally, you can also use the Show method to open additional dialog boxes from within the current one, as in the following VBA example:

UserForm2.Show vbModal

However, control is not returned to you until all open dialog boxes are unloaded.

Providing text boxes in dialog boxes

Text boxes (that is, Te x t B o x controls) are the mainstay of user input. They are simple to use and quick to program, and they are suitable for a number of purposes.

To set the text in a text box when initializing it, set the Te x t (default or implicit) property for the Te x t B o x control, as in the following VBA example:

txtWidth.Text = "3" txtHeight = "1"

To get the value of a Te x t B o x control, get its Te x t property in the Properties window, as in the following VBA example:

Call SetSize(txtWidth.Text, txtHeight.Text)

Making macros user-friendly 61

Providing combination boxes and list boxes in dialog boxes

In a combination box (that is, a ComboBox control), the user can either choose an item from the list or type a value into the text box. You can prevent users from being able to type into a ComboBox control by setting its Style property (in the Properties window) to fmStyleDropDownList.

In a list box (that is, a ListBox control), the user can choose one or more items (typically, from between three and ten items) from the list.

To populate a list of any type, you must call the member function AddItem for the list. This function takes two parameters: the string or numerical value, and the position in the list. The position parameter is optional, so omitting it inserts the item at the last position in the list. For example, the following VBA code populates the list ComboBox1 with four items:

ComboBox1.AddItem 1 ComboBox1.AddItem 2 ComboBox1.AddItem 3 ComboBox1.AddItem 0, 0

To test which item is selected when the OK button is clicked, test the ListIndex property for the list.

To get the value of the caption for a selected combination box or list box, test the Te x t property for the item, as in the following VBA example:

Dim retList As String retList = ComboBox1.Text

Providing buttons in dialog boxes

You can add a button to a dialog box by using the CommandButton control. Click the dialog box to add a default-sized button, or drag to create a custom-sized one. Click the caption to edit it, or select the button and edit its Caption property in the Properties window. You might also want to change the name of the button to something more descriptive, such as buttonOK or buttonCancel.

Making macros user-friendly 62

Designing buttons in the Form Designer

Most dialog boxes have an OK button and a Cancel button. However, no button functions until its dialog box has code for handling the click event for the button. (This is because dialog boxes in VBA and VSTA are eventdriven.)

For an OK button, you can set its Default property to Tr u e so that the event handler for the button is called when the user presses Enter to activate the dialog box. That way, the click-event handler for the button performs the functionality of the dialog box and then unloads that dialog box.

If the dialog box is used to set the size of the selected CorelDRAW shapes by setting their width and height, then the click-event handler for the OK button could resemble the following VBA code sample (which assumes you have already created two text boxes called txtWidth and txtHeight):

Private Sub buttonOK_Click() Me.Hide Call SetSize(txtWidth.Text, txtHeight.Text) Unload Me End Sub

Similarly, the size-setting CorelDRAW subroutine could resemble the following:

Private Sub SetSize(width As String, height As String) ActiveDocument.Unit = cdrInch ActiveSelection.SetSize CDbl(width), CDbl(height) End Sub

From inside the code module for the dialog box, the dialog-box object is implicit, so all the controls can be simply accessed by name. From other modules, the controls must be accessed through their full name (as in UserForm1.buttonOK).

Making macros user-friendly 63

The Cancel button is the simplest control: it must dismiss the form without doing anything else. To add a cancel action to a Cancel button, double-click the button from within the Form Designer to display its code in the Code window. This creates a new subroutine called cmdCancel_Click:

The Code window with code for a Cancel button

The following VBA code, if applied to a Cancel button, dismisses the dialog box when the button is clicked:

Private Sub cmdCancel_Click() Unload Me End Sub

If you continue by setting the Cancel property for the dialog box to Tr u e , then when the user presses Escape, the cmdCancel_Click event is triggered and the provided code unloads the form.

Providing images in dialog boxes

The Image control is used to place graphics on a dialog box. The image (a bitmap) is contained in the Picture property, so you can either load an RGB image from a file (such as a GIF, JPEG, or Windows Bitmap BMP file) or paste one into the property.

At run time, you can change the Picture property if you want to load a new image into the Image control. To change the Picture property, use the function LoadPicture and provide a path to the new image file, as in the following VBA example:

Image1.Picture = LoadPicture("C:\Images\NewImage.gif")

Providing user interaction for macros

One way to make your macro solutions more user-friendly is to optimize them for user interaction, such as mouse input. A macro that captures mouse actions gives users real-time influence on the result of that macro.

Making macros user-friendly 64

The CorelDRAW object model provides three main ways to receive mouse input from users, as explained in the following topics:

• Capturing mouse clicks

•Capturing mouse drags

• Capturing coordinates

Capturing mouse clicks

To get the position of a single mouse click, you can use the GetUserClick method of the Document class. This method pauses the macro until the specified period of time elapses, or until the user clicks in the document or presses Escape. Here is a VBA example that uses the Document.GetUserClick method:

Dim doc As Document, retval As Long Dim x As Double, y As Double, shift As Long Set doc = ActiveDocument doc.Unit = cdrCentimeter retval = doc.GetUserClick(x, y, shift, 10, True, cdrCursorPick)

The following parameters for the Document.GetUserClick method are coded into the preceding example:

•The variable

• The parameter when clicking the mouse. The Shift, Ctrl, and Alt keys are assigned values of 1, 2, and 4 (respectively), the sum of which is the returned value.

•The value

•The value a custom icon.)

x returns the horizontal position of the mouse click. y returns the vertical position of the mouse click.

shift returns the combination of the Shift, Ctrl, and Alt keys that is held down by the user

10 specifies the number of seconds for the user to click in the document. True specifies that the SnapToObjects parameter is enabled. cdrCursorPick specifies that the icon for the Pick tool is used for the cursor icon. (You cannot use

One of the following values is returned:

• 0 — The user successfully completes the click.

• 1 — The user cancels by pressing Escape.

• 2 — The operation times out.

The returned coordinates are relative to the origin of the page and, unless explicity specified, are in document units.

To get the shapes under the returned click point, you can use the method SelectShapesAtPoint (which is a member of Page), as in the following VBA example:

doc.ActivePage.SelectShapesAtPoint x, y, True

A value of True selects unfilled objects, while False does not select unfilled objects.

Making macros user-friendly 65

Capturing mouse drags

To get the position of a mouse drag (or an area or rectangle), you can use the GetUserArea method of the Document class. This method pauses the macro until the specified period of time elapses, or until the user

clicks, drags, and releases in the document or presses Escape.

Here is a VBA example that uses the Document.GetUserArea method:

Dim doc As Document, retval As Long, shift As Long Dim x1 As Double, y1 As Double, x2 As Double, y2 As Double Set doc = ActiveDocument doc.Unit = cdrCentimeter retval = doc.GetUserArea(x1, y1, x2, y2, shift, 10, True, cdrCursorExtPick) ActivePage.SelectShapesFromRectangle x1, y1, x2, y2, False

The following parameters for the Document.GetUserArea method are coded into the preceding example:

•The variables the area.

• The parameter when dragging the mouse. The Shift, Ctrl, and Alt keys are assigned values of 1, 2, and 4 (respectively), the sum of which is the returned value.

•The value

x1 and y1 return the horizontal and vertical positions (respectively) of the upper-left corner of

x2 and y2 return the horizontal and vertical positions (respectively) of the lower-right corner of

shift returns the combination of the Shift, Ctrl, and Alt keys that is held down by the user

10 specifies the number of seconds for the user to click in the document. True specifies that the SnapToObjects parameter is enabled. cdrCursorExtPick specifies the icon to use for the cursor.

In the preceding example, the code ends by selecting the shapes that lie completely within the area by using the Page.SelectShapesFromRectangle method.

One of the following values is returned:

• 0 — The user successfully completes the selection.

• 1 — The user cancels by pressing Escape.

• 2 — The operation times out.

This method returns two points that are interpreted as the corners of a rectangle. However, the two points can also be used as the start point and end point of a mouse drag.

The returned coordinates are relative to the origin of the page and, unless explicity specified, are in document units.

Capturing coordinates

When capturing mouse actions, or when developing a complex macro solution, you may want to convert between screen coordinates and document coordinates. This conversion is done with the methods ScreenToDocument and DocumentToScreen of the Window class.

Making macros user-friendly 66

The following VBA example converts a set of screen coordinates into a point in the document that is visible in the active window:

Dim docX As Double, docY As Double ActiveDocument.Unit = cdrMillimeter ActiveWindow.ScreenToDocument 440, 500, docX, docY

The following VBA example returns the screen coordinates of a point in the document as it appears on the screen:

Dim screenX As Long, screenY As Long ActiveDocument.Unit = cdrMillimeter ActiveWindow.DocumentToScreen 40, 60, screenX, screenY

In both examples, the converted coordinates are returned in the last two parameters.

Screen coordinates start from the upper-left corner of the screen, so positive y-values are down the screen, whereas negative y-values are up the screen.

You can test whether a set of coordinates (that is, a point) is inside, outside, or on the outline of a curve by using the Shape.IsOnShape method. For a set of document coordinates, this method returns one of the following:

• cdrInsideShape — if the coordinate is inside the shape

• cdrOutsideShape — if the coordinate is outside the shape

• cdrOnMarginOfShape — if the coordinate is on or near the outline of the shape

For example, the following VBA code tests where the point (4, 6) is in relation to the active shape:

Dim onShape As Long ActiveDocument.Unit = cdrInch onShape = ActiveShape.IsOnShape(4, 6)

Providing documentation for macros

To make a macro as user-friendly as possible, you can provide documentation for it.

One solution is to create a Readme file or a printed manual. Another solution is to incorporate the documentation directly into the user interface for the macro, but this method uses up valuable on-screen “real estate.” Yet another solution is to create an online Help system, but this method requires special tools and a fair amount of additional work.

Perhaps the simplest way to provide macro documentation is in the form of a plain-text file. In fact, upon installation, a macro project can create a registry value that points to the location of this file. In VBA, the following function can be used to open a plain-text file (where the parameter file, such as C:\ReadMe.txt):

Public Sub launchNotepad(file As String) Shell "Notepad.exe" & " " & file, vbNormalFocus End Sub

file provides the full path to the

Making macros user-friendly 67

A much more powerful solution is to provide documentation in HTML format. HTML provides numerous benefits over plain-text, including support for graphics and for hypertext links (such as to specific locations in the document — for example, index.html#middle).

In VBA, the following function can be used to open an HTML file (where the parameter path to the file — such as C:\ReadMe.txt — or a URL for the file):

' Put this Declare statement before all Subs and Functions! Declare Function ShellExecute Lib "shell32.dll" _ Alias "ShellExecuteA" (ByVal hwnd As Long, _ ByVal lpOperation As String, ByVal lpFile As String, _ ByVal lpParameters As String, ByVal lpDirectory As String, _ ByVal nShowCmd As Long) As Long Public Sub launchBrowser(url As String) ShellExecute 0, vbNullString, url, vbNullString, vbNullString, 5 End Sub

url provides the full

Making macros user-friendly 68

Organizing and deploying macros

When you’ve finished developing your macro solution, you can make it available to other users.

This section contains the following topics:

• Organizing macros

•Deploying macros

Organizing macros

To make your macro solutions easy to deploy, you can organize them. Here are some tips:

• To sort your macros, use a separate code module for each macro, and then group related macros into a single GMS file.

• To help users find the entry point to a macro, place all public subroutines into a single code module so that the macro can be called from within CorelDRAW or Corel PHOTO-PAINT.

Deploying macros

You can deploy macro solutions to users for installation. You can deploy GMS files or workspaces, or both.

Deploying GMS files

Every CorelDRAW or Corel PHOTO-PAINT document has an intrinsic GMS file. For this reason, you can explicitly distribute a macro as part of a document because when that document is opened, the user has immediate access to its macros. This deployment technique lets you, for example, set up a macro to track how much time the user has spent editing a document.

Alternatively, you can distribute the code module that contains the macro. However, this deployment method requires users to manually integrate the code module into an existing project file.

The simplest and most reliable way to deploy a macro project is to use its GMS file. To begin, you must export the GMS file from your computer. Then, each user must import the GMS file by using the Macro Manager docker.

• To export a GMS file

• To import a GMS file

CorelDRAW Graphics Suite X5 Macro Programming Guide 69

Deploying workspaces

Some macro solutions include a customized workspace that contains relevant toolbars, menus, and shortcut keys. You can deploy the features of a customized workspace to users by creating a Corel workspace (XSLT) file. You can export a subset of workspace features — such as individual menus, individual toolbars, or complete sets of shortcut keys — if you want users to install only those features, or you can export the entire workspace if you prefer.

• To export workspace features

Users can install customized workspace features by importing the XSLT files that you provide.

• To import workspace features

In CorelDRAW, users can also import workspace features by using the Application.ImportWorkspace method.

To export a GMS file

• Locate the GMS file on your computer, and make it available to your users.

User-created macro projects are typically stored at the following locations:

• on Windows 7 and Windows Vista: X:\Users\<user name>\AppData\Roaming\Corel\

CorelDRAW Graphics Suite X5\<application> (where X: is the drive where the software is installed, <user name> is the name of the user, and <application> is the application subfolder)

• on Windows XP: X:\Documents and Settings\<user name>\Application Data\Corel\

CorelDRAW Graphics Suite X5\<application> (where X: is the drive where the software is installed,

<user name> is the name of the user, and <application> is the application subfolder)

To import a GMS file

1 Save the GMS file to your computer.

User-created macro projects are typically stored at the following locations:

• on Windows 7 and Windows Vista: X:\Users\<user name>\AppData\Roaming\Corel\

CorelDRAW Graphics Suite X5\<application> (where X: is the drive where the software is installed, <user name> is the name of the user, and <application> is the application subfolder)

• on Windows XP: X:\Documents and Settings\<user name>\Application Data\Corel\

CorelDRAW Graphics Suite X5\<application> (where X: is the drive where the software is installed,

<user name> is the name of the user, and <application> is the application subfolder)

2 In the Macro Manager docker, do one of the following:

•Click Visual Basic for Applications in the list, click Load, and then choose the project.

•Right-click Visual Basic for Applications in the list, and then click Load macro project.

To export workspace features

1 Right-click the menu bar, and click Customize ` Wo r ks p ac e ` Export Workspaces.

2 In the list, enable the check boxes next to the workspace features that you want to export:

• Dockers — includes the sizes and positions of dockers

• Menus — lets you choose which menus to include

Organizing and deploying macros 70

• Shortcut Keys — includes all available shortcut keys

• Status Bar — includes the status bar

• To o l b a r s — lets you choose which toolbars to include Enable all check boxes if you want to export the entire workspace.

3 Click Save.

4 In the File name box, type a filename.

The specified workspace features are saved to a single Corel workspace (XSLT) file with the specified filename.

If you want, you can export each workspace feature to a separate file. Simply export one item at a time to create a series of XSLT files.

When you export shortcut keys, you export all shortcut keys. If you want to distribute only a few keys, create a new workspace, remove all shortcut keys from it, and then add only the desired keys.

To import workspace features

1 Right-click the toolbar, and click Customize ` Wo r k sp a c e ` Import Workspaces.

2 Click Browse.

3 Select the desired Corel workspace (XSLT) file, and then click Next.

4 In the list, enable the check boxes next to the workspace features that you want to import:

• Dockers — includes the sizes and positions of dockers

• Menus — lets you choose which menus to include

• Shortcut Keys — includes all available shortcut keys

• Status Bar — includes the status bar

• To o l b a r s — lets you choose which toolbars to include Enable all check boxes if you want to import the entire workspace.

5 Click Next.

6 Choose a destination for the workspace features by doing one of the following:

• Enable the Current workspace option to import the specified workspace features into the current

workspace, and then click Next.

• Enable the New workspace option to import the specified workspace features into a new workspace. Click

Next, and provide details about the workspace. Click Next.

7 Confirm the details of the import, and then click Finish.

The specified workspace features are imported into the specified workspace.

If the name of an incoming toolbar is the same as an existing toolbar, the incoming toolbar is renamed.

If an imported command calls an uninstalled macro, it does not function.

Organizing and deploying macros 71

Understanding the CorelDRAW object model

In CorelDRAW, the Application object is the root of all other objects and is used if no other root object is specified. You can use the CorelDRAW Application object to reference the CorelDRAW object model from an out-of-process controller, as in the following Visual Basic example:

Dim cdr As CorelDRAW.Application Set cdr = CreateObject("CorelDRAW.Application")

If desired, you can avoid using the CreateObject keyword in the preceding example by importing the target type library and using the data types directly.

The Application object contains a Documents collection of all open Document objects (or “documents”) in the application. When a CorelDRAW document is created or opened, a corresponding Document object is added to the Documents collection for the Application object. Each Document object contains a Pages collection of all the Page objects (or “pages”) in that document. Each Page object contains a Layers collection of all the Layer objects (or “layers”) on that page. Finally, each Layer object contains a Shapes collection of all the Shape objects (or “shapes”) on that layer.

In addition, the object model contains a set of filter objects, which provide support for files from other technicalgraphics applications. Import filters are governed by the Layer class, while export filters are governed by the Document class.

Documents, pages, layers, shapes, and filters are among the most important objects in the CorelDRAW object model. Understanding these objects — and their relationships to one another — is the key to understanding the CorelDRAW object model.

This section contains the following topcis:

• Working with documents

• Working with pages

• Working with layers

• Working with shapes

• Working with import filters and export filters

All code examples in this section are written in VBA.

For a visual representation of the entire CorelDRAW object model, please see the CorelDRAW objectmodel diagram at the following location (where X: is the drive where the software is installed):

• X:\Program Files\Corel\CorelDRAW Graphics Suite X5\ Data\CorelDRAW Object Model Diagram.pdf

CorelDRAW Graphics Suite X5 Macro Programming Guide 72

Working with documents

Each open CorelDRAW document, or Document object, is a member of the Application.Documents collection. The documents in that collection appear in the order in which they were created or opened.

CorelDRAW provides a number of properties, methods, and events for working with documents, the most useful of which are listed in the following table.

Class Member Description

ActiveView OriginX property

and

OriginY property

ActiveView SetViewPoint method Specifies the origin of the active view

ActiveView Zoom property Specifies the zoom factor of the active view

AddInHook New event Is triggered when a document is created

Application ActiveDocument property Provides direct access to the active document

Application CreateDocument method

or CreateDocumentFromTemplate method

Combine to specify the origin of the active view

For more information, see “Panning” on page 84.

For more information, see “Zooming” on page 84.

For more information, see “Creating documents” on page 81.

For more information, see “Activating documents” on page 81.

Create a document

For more information, see “Creating documents” on page 81.

Application DocumentAfterExport event Is triggered when a document is exported (that

is, when the Export dialog box closes)

For more information, see “Exporting files from documents” on page 86.

Application DocumentAfterPrint event Is triggered when a document is printed (that is,

when the Print dialog box closes)

For more information, see “Printing documents” on page 89.

Application DocumentAfterSave event Is triggered when a document is saved (that is,

when the Save dialog box closes)

For more information, see “Saving documents” on page 86.

Understanding the CorelDRAW object model 73

Class Member Description

Application DocumentBeforeExport event Is triggered when the Export dialog box opens

For more information, see “Exporting files from documents” on page 86.

Application DocumentBeforePrint event Is triggered when the Print dialog box opens

For more information, see “Printing documents” on page 89.

Application DocumentBeforeSave event Is triggered when the Save dialog box opens

For more information, see “Saving documents” on page 86.

Application DocumentClose event Is triggered when a document is closed

For more information, see “Closing documents” on page 91.

Application DocumentNew event Is triggered when a document is created

For more information, see “Creating documents” on page 81.

Application DocumentOpen event Is triggered when a document is opened

For more information, see “Opening documents” on page 81.

Application Documents property Contains the collection of open documents

For more information, see “Activating documents” on page 81.

Application OpenDocument method Opens a document

For more information, see “Opening documents” on page 81.

Application QueryDocumentClose event Is triggered when the user responds to a request

to close a document

For more information, see “Closing documents” on page 91.

Application QueryDocumentExport event Is triggered when the user responds to a request

to export a document

For more information, see “Exporting files from documents” on page 86.

Understanding the CorelDRAW object model 74

Class Member Description

Application QueryDocumentPrint event Is triggered when the user responds to a request

to print a document

For more information, see “Printing documents” on page 89.

Application QueryDocumentSave event Is triggered when the user responds to a request

to save a document

For more information, see “Saving documents” on page 86.

Application WindowActivate event Is triggered when a window is activated

For more information, see “Activating documents” on page 81.

Application WindowDeactivate event Is triggered when a window is deactivated

For more information, see “Activating documents” on page 81.

Document Activate method Activates a document

For more information, see “Activating documents” on page 81.

Document ActiveWindow property Provides direct access to the active window for a

document

For more information, see “Working with windows” on page 83.

Document AfterExport event Is triggered when a document is exported (that

is, when the Export dialog box closes)

For more information, see “Exporting files from documents” on page 86.

Document AfterPrint event Is triggered when a document is printed (that is,

when the Print dialog box closes)

For more information, see “Printing documents” on page 89.

Document AfterSave event Is triggered when a document is saved (that is,

when the Save dialog box closes)

For more information, see “Saving documents” on page 86.

Document BeforeExport event Is triggered when the Export dialog box opens

For more information, see “Exporting files from documents” on page 86.

Understanding the CorelDRAW object model 75

Class Member Description

Document BeforePrint event Is triggered when the Print dialog box opens

For more information, see “Printing documents” on page 89.

Document BeforeSave event Is triggered when the Save dialog box opens

For more information, see “Saving documents” on page 86.

Document BeginCommandGroup method

and EndCommandGroup method

Combine to create a “command group” that reduces a series of programmed, documentrelated actions to a single, undoable step

For more information, see “Creating command groups for documents” on page 85.

Document Close event Is triggered when a document is closed

For more information, see “Closing documents” on page 91.

Document Close method Closes a document

For more information, see “Closing documents” on page 91.

Document CreateView method Creates a document view

For more information, see “Working with views” on page 84.

Document Export method,

ExportEx method,

ExportBitmap method

Document FilePath property,

FileName property,

or FullFileName property

Exports a file from a document

For more information, see “Exporting files from documents” on page 86.

Specifies the file path or filename (or both) of a saved document

For more information, see “Activating documents” on page 81.

Document GetUserArea method Returns information about a document area that

the user drags with the mouse

For more information, see “Capturing mouse drags” on page 66.

Document GetUserClick method Returns information about a document position

that the user clicks with the mouse

For more information, see “Capturing mouse clicks” on page 65.

Understanding the CorelDRAW object model 76

Class Member Description

Document Open event Is triggered when a document is opened

For more information, see “Opening documents” on page 81.

Document PrintOut method

and PrintSettings property

Combine to print a document by using the specified settings

For more information, see “Printing documents” on page 89.

Document PublishToPDF method

and PDFSettings property

Combine to publish a document to PDF by using the specified settings

For more information, see “Publishing documents to PDF” on page 88.

Document QueryClose event Is triggered when the user responds to a request

to close a document

For more information, see “Closing documents” on page 91.

Document QueryExport event Is triggered when the user responds to a request

to export a document

For more information, see “Exporting files from documents” on page 86.

Document QueryPrint event Is triggered when the user responds to a request

to print a document

For more information, see “Printing documents” on page 89.

Document QuerySave event Is triggered when the user responds to a request

to save a document

For more information, see “Saving documents” on page 86.

Document ReferencePoint property Specifies the reference point for the document

For more information, see “Setting document properties” on page 82.

Document SaveAs method

or Save method

Understanding the CorelDRAW object model 77

Saves a document

For more information, see “Saving documents” on page 86.

Class Member Description

Document Unit property Specifies the unit of measurement for the

document

For more information, see “Setting document properties” on page 82.

Document WorldScale property Specifies the drawing scale for the document

For more information, see “Setting document properties” on page 82.

Document Views property Contains the collection of views for a document

For more information, see “Working with views” on page 84.

GlobalMacroStorage DocumentAfterExport event Is triggered when a document is exported (that

is, when the Export dialog box closes)

For more information, see “Exporting files from documents” on page 86.

GlobalMacroStorage DocumentAfterPrint event Is triggered when a document is printed (that is,

when the Print dialog box closes)

For more information, see “Printing documents” on page 89.

GlobalMacroStorage DocumentAfterSave event Is triggered when a document is saved (that is,

when the Save dialog box closes)

For more information, see “Saving documents” on page 86.

GlobalMacroStorage DocumentBeforeExport event Is triggered when the Export dialog box opens

For more information, see “Exporting files from documents” on page 86.

GlobalMacroStorage DocumentBeforePrint event Is triggered when the Print dialog box opens

For more information, see “Printing documents” on page 89.

GlobalMacroStorage DocumentBeforeSave event Is triggered when the Save dialog box opens

For more information, see “Saving documents” on page 86.

GlobalMacroStorage DocumentClose event Is triggered when a document is closed

For more information, see “Closing documents” on page 91.

Understanding the CorelDRAW object model 78

Class Member Description

GlobalMacroStorage DocumentNew event Is triggered when a document is created

For more information, see “Creating documents” on page 81.

GlobalMacroStorage DocumentOpen event Is triggered when a document is opened

For more information, see “Opening documents” on page 81.

GlobalMacroStorage QueryDocumentClose event Is triggered when the user responds to a request

to close a document

For more information, see “Closing documents” on page 91.

GlobalMacroStorage QueryDocumentExport event Is triggered when the user responds to a request

to export a document

For more information, see “Exporting files from documents” on page 86.

GlobalMacroStorage QueryDocumentPrint event Is triggered when the user responds to a request

to print a document

For more information, see “Printing documents” on page 89.

GlobalMacroStorage QueryDocumentSave event Is triggered when the user responds to a request

to save a document

For more information, see “Saving documents” on page 86.

GlobalMacroStorage WindowActivate event Is triggered when a window is activated

For more information, see “Activating documents” on page 81.

GlobalMacroStorage WindowDeactivate event Is triggered when a window is deactivated

For more information, see “Activating documents” on page 81.

View Activate method Applies a saved view to the document window

For more information, see “Working with views” on page 84.

Window Activate method Activates a document window

For more information, see “Working with windows” on page 83.

Understanding the CorelDRAW object model 79

Class Member Description

Window ActiveView property Provides direct access to the active view for a

document window

For more information, see “Working with views” on page 84.

Window Close method Closes a document window

For more information, see “Working with windows” on page 83.

Window NewWindow method Creates a document window

For more information, see “Working with windows” on page 83.

Window Next property Accesses the next window for a document

For more information, see “Working with windows” on page 83.

Window Previous property Accesses the previous window for a document

For more information, see “Working with windows” on page 83.

For detailed information on any property, method, or event, see “Object Model Reference” section in the CorelDRAW Macros Help file.

For more information on document-related activitites, see the following topics:

• Creating documents

• Opening documents

• Activating documents

• Setting document properties

• Displaying documents

•Modifying documents

• Creating command groups for documents

• Saving documents

•Exporting files from documents

• Publishing documents to PDF

•Printing documents

• Closing documents

Files of all supported formats can be imported into CorelDRAW. Imported files are placed on document layers, so information on importing files is provided in the section on working with layers (see “Importing files into layers” on page 101) rather than in this section on working with documents.

Understanding the CorelDRAW object model 80

Creating documents

The Application object has two methods for creating documents: CreateDocument and CreateDocumentFromTemplate.

The Application.CreateDocument method creates an empty document based on the default page size, orientation, and styles:

Application.CreateDocument() As Document

The Application.CreateDocumentFromTemplate method creates an untitled document from a specified CorelDRAW (CDT) template:

Application.CreateDocumentFromTemplate(Template As String, _ [IncludeGraphics As Boolean = True])As Document

Both of these functions return a reference to the new document, so they are typically used in the following manner:

Dim newDoc as Document Set newDoc = CreateDocument

The new document becomes active immediately and can be referenced by using the Application.ActiveDocument property. For more information on this property, see “Activating documents” on page 81.

If you want, you can use event handlers to respond to events that are triggered by creating a document:

• AddinHook.New

• Application.DocumentNew

• GlobalMacroStorage.DocumentNew

Opening documents

To open a document, you can use the Application.OpenDocument method:

Dim doc As Document Set doc = OpenDocument("C:\graphic1.cdr")

If you want, you can use event handlers to respond to events that are triggered by opening a document:

• Application.DocumentOpen

• Document.Open

• GlobalMacroStorage.DocumentOpen

Activating documents

Each open document in CorelDRAW is a member of the Application.Documents collection. The documents in that collection appear in the order in which they were created or opened.

To reflect the actual stacking order of the documents in CorelDRAW, you must use the Application.Windows collection.

Understanding the CorelDRAW object model 81

The Application.ActiveDocument property provides direct access to the active document — that is, the document that is in front of all the other documents in the CorelDRAW window. ActiveDocument is an object of type Document and, therefore, has the same members — properties, methods, and objects — as the Document class.

If no documents are open, ActiveDocument returns nothing. You can check for open documents by using the following VBA code:

If Documents.Count = 0 Then MsgBox "There aren't any open documents.", vbOK, "No Docs" Exit Sub End If

The Document.Activate method activates a document so that it can be referenced by ActiveDocument. The following VBA code activates the third open document (if three or more documents are open in CorelDRAW):

Documents(3).Activate

Using the Document.Activate method on the Application.ActiveDocument property has no effect.

If you want, you can specify which open document to activate by referencing the one of the following properties:

• Document.FilePath — checks only the file path (for example, C:\My Documents)

• Document.FileName — checks only the filename (for example, Graphic1.cdr)

• Document.FullFileName — checks both the file path and the filename (for example, C:\My Documents\Graphic1.cdr)

You can check the filename of each open document by using the following VBA code:

Public Function findDocument(filename As String) As Document Dim doc As Document For Each doc In Documents If doc.FileName = filename Then Exit For Set doc = Nothing Next doc Set findDocument = doc End Function

You can then activate the returned document by using the Document.Activate method.

Setting document properties

You can specify the reference point, unit of measurement, and drawing scale for a document by using the corresponding properties of the Document class.

The Document.ReferencePoint property specifies the reference point for a document. This point is referenced when positioning the objects in that document.

The Document.Unit property specifies the unit of measurement for a document. This unit is used to position and size the objects in that document.

Understanding the CorelDRAW object model 82

The Document.WorldScale property specifies the drawing scale for a document. The drawing scale lets you make the distances in a drawing proportionate to real-world distances; for example, you can specify that 1 inch in the drawing corresponds to 1 meter in the physical world.

These properties affect all elements in your document, such as the objects that you draw. For optimal results, choose the settings that best fit your macro solution.

Displaying documents

CorelDRAW lets you simultaneously display multiple windows for a single document. For example, a large document can be displayed with one window zoomed in to the upper-right corner of the document and another zoomed in to the lower-right corner. Although the individual windows can be zoomed and panned independently, turning the page in one window affects all windows.

By using the View Manager, you can create views that have individual display settings. Choosing a saved view displays the page according to the settings for that view.

In VBA, the Window object provides access to the windows that contain each View object for (or view of) a given document. The Window object represents a frame, while the View object displays the document inside that frame.

Besides letting you work with windows and views, CorelDRAW lets you display documents by zooming and panning.

Working with windows

Each Document object has a Windows collection for displaying that document. To switch between windows, use the Window.Activate method:

ActiveDocument.Windows(2).Activate

The Document.ActiveWindow property provides direct access to the active window — that is, the document window that is in front of all other windows in CorelDRAW.

The next window and previous window for the active document are referenced in the Window.Next and Window.Previous properties:

ActiveWindow.Next.Activate

To create a new window, use the Window.NewWindow method:

ActiveWindow.NewWindow

To close a window (and the document, if it has only one open window), use the Window.Close method:

ActiveWindow.Close

If you want, you can use event handlers to respond to events that are triggered by activating a window:

• Application.WindowActivate

• GlobalMacroStorage.WindowActivate

You can also use event handlers to respond to events that are triggered by deactivating a window:

•Application.WindowDeactivate

• GlobalMacroStorage.WindowDeactivate

Understanding the CorelDRAW object model 83

Working with views

The Window.ActiveView property and the Document.Views property both represent document views. Each Window object has one ActiveView object, which represents the current view of the document; saving the display settings for an ActiveView object creates a view. In contrast, each Document object has a collection of View objects in its Views property; choosing a View object activates the corresponding saved view, which

contains the display settings for the corresponding ActiveView object.

The only way to access an ActiveView object is from the Window.ActiveView property.

You can create a View object and add it to a Document.Views collection. The following VBA code adds the current ActiveView settings to the Views collection:

ActiveDocument.Views.AddActiveView "New View"

You can also create a view with specific settings by using the Document.CreateView method. The following VBA code creates a new View object that accesses the position (3, 4) in inches, uses a zoom factor of 95%, and displays page 6:

ActiveDocument.Unit = cdrInch ActiveDocument.CreateView "New View 2", 3, 4, 95, 6

To apply a saved view to the active window, call the View.Activate method:

ActiveDocument.Views("New View").Activate

Zooming

To zoom an ActiveView object by a set amount, set the ActiveView.Zoom property by specifying a double value in percent. For example, the following VBA code sets the zoom factor to 200%:

ActiveWindow.ActiveView.Zoom = 200.0

You can also zoom by using the following methods of the ActiveView class:

•SetActualSize

• ToFitAllObjects

•ToFitArea

•ToFitPage

• ToFitPageHeight

•ToFitPageWidth

•ToFitSelection

•ToFitShape

• ToFitShapeRange

Panning

To p a n a n ActiveView object, you can move its origin by modifying the ActiveView.OriginX and ActiveView.OriginY properties.

Understanding the CorelDRAW object model 84

The following VBA code pans the document 5 inches to the left and 3 inches up:

Dim av As ActiveView ActiveDocument.Unit = cdrInch Set av = ActiveWindow.ActiveView av.OriginX = av.OriginX - 5 av.OriginY = av.OriginY + 3

Alternatively, you can use the ActiveView.SetViewPoint method:

Dim av As ActiveView ActiveDocument.Unit = cdrInch Set av = ActiveWindow.ActiveView av.SetViewPoint av.OriginX - 5, av.OriginY + 3

Modifying documents

You can modify a document regardless of whether it is active.

Modifying an inactive document does not activate that document. To activate a document, you must use its Activate method, as explained in “Activating documents” on page 81.

The following VBA code adds a layer named “fooLayer” to the third open document:

Dim doc As Document Set doc = Documents(3) doc.ActivePage.CreateLayer "fooLayer"

The following VBA code uses the findDocument() function to add a layer named “fooLayer” to the inactive document named barDoc.cdr:

Dim doc As Document Set doc = findDocument("barDoc.cdr") If Not doc Is Nothing Then doc.ActivePage.CreateLayer "fooLayer"

Creating command groups for documents

Two very useful methods of the Document class combine to create a “command group,” which can reduce a series of programmed, document-related actions to a single, undoable step. These methods — BeginCommandGroup and EndCommandGroup — are demonstrated in the following VBA example:

Dim sh As Shape ActiveDocument.BeginCommandGroup "CreateCurveEllipse" Set sh = ActiveLayer.CreateEllipse(0, 1, 1, 0) sh.ConvertToCurves ActiveDocument.EndCommandGroup

Understanding the CorelDRAW object model 85

The preceding code sets the Undo string in the Edit menu as Undo CreateCurveEllipse. Clicking this command undoes not only the ConvertToCurves operation but also the CreateEllipse operation.

A command group can contain many hundreds of commands, if required. Creating command groups can make your macros appear to be fully integrated into CorelDRAW.

Saving documents

CorelDRAW offers two methods for saving documents: Document.SaveAs and Document.Save.

The Document.SaveAs method saves a document by using the specified file path and filename. You can use this method to save a previously unsaved document or to save an existing document to a different file.

The Document.SaveAs method provides an optional parameter that lets you access the StructSaveAsOptions class to specify additional settings.

The Document.Save method saves over an existing document file — that is, by using the existing file path and filename for the document.

If you want, you can use event handlers to respond to events that are triggered by opening the Save dialog box:

• Application.DocumentBeforeSave

• Document.BeforeSave

• GlobalMacroStorage.DocumentBeforeSave

You can also use event handlers to respond to events that are triggered by saving a document and closing the

Save dialog box:

• Application.DocumentAfterSave

• Document.AfterSave

• GlobalMacroStorage.DocumentAfterSave

Finally, you can also use event handlers to respond to events that are triggered when the user responds to a request to save a document:

• Application.QueryDocumentSave

•Document.QuerySave

• GlobalMacroStorage.QueryDocumentSave

Exporting files from documents

Files of all supported formats can be exported from CorelDRAW.

Files are exported at the Document level because the range of exported objects can extend over multiple layers and multiple pages. However, files are imported at the Layer level because each imported object is assigned to a specified layer on a specified page (see “Importing files into layers” on page 101).

The Document class has three file-export methods — Export, ExportEx, and ExportBitmap — all of which can export to the bitmap and vector formats.

Understanding the CorelDRAW object model 86

The wide selection of file formats that are supported by CorelDRAW is due to the vast number of filters that are available to the application. Each filter lets you work with the files from another graphics application. To learn more about working with these filters, see “Working with import filters and export filters” on page 138.

If you want, you can use event handlers to respond to events that are triggered by opening the Export dialog box:

• Application.DocumentBeforeExport

• Document.BeforeExport

• GlobalMacroStorage.DocumentBeforeExport

You can also use event handlers to respond to events that are triggered by exporting a document and closing the

Export dialog box:

• Application.DocumentAfterExport

• Document.AfterExport

• GlobalMacroStorage.DocumentAfterExport

Finally, you can also use event handlers to respond to events that are triggered when the user responds to a request to export a document:

• Application.QueryDocumentExport

•Document.QueryExport

• GlobalMacroStorage.QueryDocumentExport

Understanding the Document.Export method

To export a page, you require only the Document.Export method, a filename, and a filter type. The following VBA code exports the current page to a TIFF bitmap file:

ActiveDocument.Export "C:\ThisPage.eps", cdrTIFF

However, the preceding code gives little control over the output of the image. More control is obtained by including a StructExportOptions object, as in the following VBA code:

Dim expOpts As New StructExportOptions expOpts.ImageType = cdrCMYKColorImage expOpts.AntiAliasingType = cdrNormalAntiAliasing expOpts.ResolutionX = 72 expOpts.ResolutionY = 72 expOpts.SizeX = 210 expOpts.SizeY = 297 ActiveDocument.Export "C:\ThisPage.eps", cdrTIFF, cdrCurrentPage, expOpts

A StructPaletteOptions object can also be included in the function call for palette-based image formats, if you want to provide the settings for automatically generating the palette.

Understanding the CorelDRAW object model 87

Understanding the Document.ExportEx method

The Document.ExportEx method is the same as the Document.Export method, except that ExportEx can retreive the dialog-box settings for a filter and apply those settings to the export:

Dim eFilt As ExportFilter Set eFilt = ActiveDocument.ExportEx("C:\ThisPage.eps", cdrEPS) If eFilt.HasDialog = True Then If eFilt.ShowDialog = True Then eFilt.Finish End If Else eFilt.Finish End If

Understanding the Document.ExportBitmap method

The Document.ExportBitmap method is similar to the Document.ExportEx method in that it returns an ExportFilter object that can be used to display the Export dialog box. However, the ExportBitmap method simplifies the coding by taking the individual members of the StructExportOptions object as parameters:

Dim eFilt As ExportFilter Set eFilt = ActiveDocument.ExportBitmap("C:\Selection.eps", _ cdrTIFF, cdrSelection, cdrCMYKColorImage, _ 210, 297, 72, 72, cdrNormalAntiAliasing, _ False, True, False, cdrCompressionLZW) eFilt.Finish

Publishing documents to PDF

Publishing documents to PDF is a two-step process. The first step is to specify the PDF settings (although this step can be skipped by specifying those settings from within CorelDRAW or by using the default settings). The second step is to export the file.

To specify the PDF settings, you can use the Document.PDFSettings property. This property is an object of type PDFVBASettings and contains properties for all PDF settings that can be set in the Publish To PDF dialog box.

Understanding the CorelDRAW object model 88

The following VBA code exports pages 2, 3, and 5 to a PDF file named MyPDF.pdf:

Dim doc As Document Set doc = ActiveDocument With doc.PDFSettings .Author = "Corel Corporation" .Bookmarks = True .ColorMode = pdfRGB .ComplexFillsAsBitmaps = False .CompressText = True .DownsampleGray = True .EmbedBaseFonts = True .EmbedFonts = True .Hyperlinks = True .Keywords = "Test, Example, Corel, CorelDRAW, PublishToPDF" .Linearize = True .PageRange = "2-3, 5" .pdfVersion = pdfVersion13 .PublishRange = pdfPageRange .TrueTypeToType1 = True End With doc.PublishToPDF "C:\MyPDF.pdf"

The following VBA example gives more control to the user by displaying the Publish to PDF Settings dialog box:

Dim doc As Document Set doc = ActiveDocument If doc.PDFSettings.ShowDialog = True Then doc.PublishToPDF "C:\MyPDF.pdf" End If

Profiles for PDF settings can be saved and loaded by using the PDFVBASettings.Save method and PDFVBASettings.Load method (respectively).

Printing documents

Using VBA to print documents is straightforward: almost all settings that are available in the CorelDRAW Print dialog box are available to the Document.PrintSettings property. When these properties are set, printing the document is simply a matter of calling the Document.PrintOut method.

Understanding the CorelDRAW object model 89

For example, the following VBA code prints three copies of pages 1, 3, and 4 to a level-3 PostScript® printer:

With ActiveDocument.PrintSettings .Copies = 3 .PrintRange = prnPageRange .PageRange = "1, 3-4" .Options.PrintJobInfo = True With .PostScript .DownloadType1 = True .Level = prnPSLevel3 End With End With ActiveDocument.PrintOut

Each page in the Print dialog box has a corresponding object-model class that contains all settings for that page. The following table lists these classes.

Page in Print dialog box Class in object model

General PrintSettings

Layout PrintSettings and PrintLayout

Separations PrintSeparations and PrintTrapping

Prepress PrintPrepress

PostScript PrintPostScript

Misc PrintOptions

You cannot set layout options in VBA. However, if necessary, you can open the Print dialog box by using the PrintSettings.ShowDialog method.

You can print only the selected objects in a document by setting the PrintSettings.PrintRange property to prnSelection.

You can use a specific printer in the Application.Printers collection by specifying it in the PrintSettings.Printer property.

You can save a printing profile by using the PrintSettings.Save method.

You can access a saved printing profile by using the PrintSettings.Load method, but be sure to specify the full path to the profile.

You can reset the print settings by using the PrintSettings.Reset method.

Understanding the CorelDRAW object model 90

If you want, you can use event handlers to respond to events that are triggered by opening the Print dialog box:

• Application.DocumentBeforePrint

• Document.BeforePrint

• GlobalMacroStorage.DocumentBeforePrint

You can also use event handlers to respond to events that are triggered by printing a document and closing the

Print dialog box:

• Application.DocumentAfterPrint

• Document.AfterPrint

• GlobalMacroStorage.DocumentAfterPrint

Finally, you can also use event handlers to respond to events that are triggered when the user responds to a request to print a document:

• Application.QueryDocumentPrint

•Document.QueryPrint

• GlobalMacroStorage.QueryDocumentPrint

Closing documents

You can close a document by calling the Document.Close method.

The following VBA code closes the active document and activates the document behind it in CorelDRAW:

ActiveDocument.Close

If the code closes a document that is not active, the document referenced by the Application.ActiveDocument property does not change.

You must explicitly test the Dirty property for a document and take appropriate action if that document has been modified.

You can also close a document by using the Close method of the Document object itself (as in

doc.Close).

If you want, you can use event handlers to respond to events that are triggered by closing a document:

• Application.DocumentClose

• Document.Close

• GlobalMacroStorage.DocumentClose

You can also use event handlers to respond to events that are triggered when the user responds to a request to close a document:

• Application.QueryDocumentClose

•Document.QueryClose

• GlobalMacroStorage.QueryDocumentClose

Understanding the CorelDRAW object model 91

Working with pages

Each page, or Page object, is a member of the Document.Pages collection for the document in which it appears. The pages in a Document.Pages collection appear in the order in which they appear in that document — for example, the fifth page in the active document is reordered, or deleted, the affected Pages collection is immediately updated to reflect the new page order of that document.

CorelDRAW provides a number of properties, methods, and events for working with pages, the most useful of which are listed in the following table.

Class Member Description

Application ActivePage property Provides direct access to the active page of the active document

Application PageSizes property Contains the collection of defined page sizes for the application

Document ActivePage property Provides direct access to the active page of a document

ActiveDocument.Pages.Item(5). If pages are added,

For more information, see “Activating pages” on page 94.

For more information, see “Using defined page sizes” on page 96.

For more information, see “Activating pages” on page 94.

Document AddPages method

AddPagesEx method

Document InsertPages method

InsertPagesEx method

Document MasterPage property Specifies the default page size

Document PageActivate event Is triggered when a page is activated

Document PageChange event Is triggered when a page is deactivated

Document PageCreate event Is triggered when a page is created

Document PageDelete event Is triggered when a page is deleted

Adds blank pages to the end of a document

For more information, see “Creating pages” on page 94.

Inserts pages at the specified location in a document

For more information, see “Creating pages” on page 94.

For more information, see “Specifying the default page size” on page 96.

For more information, see “Activating pages” on page 94.

For more information, see “Creating pages” on page 94.

For more information, see “Deleting pages” on page 97.

Document Pages property Contains the collection of pages for a document

For more information, see “Activating pages” on page 94.

Understanding the CorelDRAW object model 92

Class Member Description

Page Activate method Activates a page

For more information, see “Activating pages” on page 94.

Page Delete method Deletes a page

For more information, see “Deleting pages” on page 97.

Page MoveTo method Moves a page to the specified location in a document

For more information, see “Reordering pages” on page 95.

Page SetSize method Sets the size of a page

For more information, see “Specifying the size and orientation of pages” on page 95.

PageSize BuiltIn property Returns Tr u e if a page size is built-in (rather than user-defined)

For more information, see “Using defined page sizes” on page 96.

PageSize Delete method Deletes a user-defined page size

For more information, see “Using defined page sizes” on page 96.

PageSize Height property Specifies the height of a defined page size

For more information, see “Using defined page sizes” on page 96.

PageSize Name property Specifies the name of a defined page size

For more information, see “Using defined page sizes” on page 96.

PageSize Width property Specifies the width of a defined page size

For more information, see “Using defined page sizes” on page 96.

For detailed information on any property, method, or event, see “Object Model Reference” section in the CorelDRAW Macros Help file.

For more information on page-related activitites, see the following topics:

•Creating pages

• Activating pages

•Reordering pages

• Sizing pages

•Modifying pages

• Deleting pages

Understanding the CorelDRAW object model 93

Creating pages

The methods for creating pages belong to the Document class.

Both the Document.AddPages method and the Document.AddPagesEx method add the specified number of pages to the end of a document. The difference between these methods is that AddPages uses the default page size, while AddPagesEx uses a specified size.

Similarly, both the Document.InsertPages method and the Document.InsertPagesEx method insert the specified number of pages at the specified location in a document. The difference between these methods is that InsertPages uses the default page size, while InsertPagesEx uses a specified size.

As an example, the following VBA code uses the AddPages method to add three default-sized pages to the end of the document:

Public Function AddSomeSimplePages() as Page Set AddSomeSimplePages = ActiveDocument.AddPages(3) End Function

The following VBA example uses the AddPagesEx method to add to the end of the document three pages that are 8.5 inches wide by 11 inches high:

Public Function AddSomeSpecifiedPages() as Page Dim doc as Document Set doc = ActiveDocument doc.Unit = cdrInch Set AddSomeSpecifiedPages = doc.AddPagesEx(3, 8.5, 11) End Function

The preceding examples return the first page that was added; all other added pages follow this page. You can therefore reference any of the added pages by incrementing the Index property of the returned page:

Dim firstNewPage As Page, secondNewPage As Page Set firstNewPage = AddSomeSimplePages Set secondNewPage = ActiveDocument.Pages(firstNewPage.Index + 1)

If you want, you can use event handlers to respond to events that are triggered by creating a page:

• Document.PageCreate

Activating pages

Each page is a member of the Document.Pages collection for the document in which it appears. The pages in a Document.Pages collection appear in the order in which they appear in that document — for example, the fifth

page in the active document is the affected Pages collection is immediately updated to reflect the new page order of that document.

ActiveDocument.Pages.Item(5). If pages are added, reordered, or deleted,

Understanding the CorelDRAW object model 94

You can access the active page of the active document by using the Application.ActivePage property (or

ActiveDocument.ActivePage, or simply ActivePage). A reference to the active page in the active document,

of type Page, is returned.

Dim pg As Page Set pg = ActivePage

You can access the active page of a document, regardless of whether that document is active, by using ActivePage property for that document:

Public Function getDocsActivePage(doc As Document) As Page Set getDocsActivePage = doc.ActivePage End Function

You can switch pages by finding the desired page and then invoking its Activate method. The following VBA code activates page 3 in a CorelDRAW document:

ActiveDocument.Pages(3).Activate

If you want, you can use event handlers to respond to events that are triggered by activating a page:

• Document.PageActivate

You can also use event handlers to respond to events that are triggered by deactivating a page:

• Document.PageChange

Reordering pages

A page can be moved to another location in a document by using its MoveTo method. The following VBA code moves page 2 to the position of page 4:

ActiveDocument.Pages(2).MoveTo 4

Activating a page in an inactive document does not activate that document. To activate a document, you must use its Activate method, as explained in “Activating documents” on page 81.

Sizing pages

You can specify the size and orientation of pages, specifying the default page size, and use defined page sizes.

Specifying the size and orientation of pages

You can size a page by using its SetSize method, which applies two size values (width and height) to the page.

The following VBA code changes the size of the active page in the active document to A4:

ActiveDocument.Unit = cdrMillimeter ActivePage.SetSize 210, 297 ActivePage.Orientation = cdrLandscape

For the SetSize method, the first number is always the page width and the second number is always the page height. Reversing the two numbers switches the orientation of the page.

Understanding the CorelDRAW object model 95

Specifying the default page size

The default page size for a document is determined by the value of the item that has an index of 0 in the Document.Pages collection. You can specify the default page size by changing the value of this item:

Dim doc As Document Set doc = ActiveDocument doc.Unit = cdrMillimeter doc.Pages(0).SetSize 297, 210

Alternatively, you can use the Document.MasterPage property to specify the default page size:

Dim doc As Document Set doc = ActiveDocument doc.Unit = cdrMillimeter doc.MasterPage.SetSize 297, 210

Using defined page sizes

Page sizes can be defined by either CorelDRAW or the user. All defined page sizes are stored in the

Application.PageSizes collection, and the name of each PageSize object in that collection is defined by its Name property:

Dim pageSizeName As String pageSizeName = Application.PageSizes(3).Name

Page sizes can be specified by name. For example, the following VBA code gets the PageSize object named “Business Card”:

Dim thisSize As PageSize Set thisSize = Application.PageSizes("Business Card")

You can get the actual dimensions of a PageSize object by using its Width and Height properties. The following VBA code retrieves the width and height (in millimeters) of the third PageSize object:

Dim pageWidth As Double, pageHeight As Double Application.Unit = cdrMillimeter pageWidth = Application.PageSizes(3).Width pageHeight = Application.PageSizes(3).Height

Although each PageSize object provides a Delete method, this method can be used only on user-defined page sizes. You can determine whether a PageSize object is user-defined by testing its BuiltIn Boolean property:

Public Sub deletePageSize(thisSize As PageSize) If Not thisSize.BuiltIn Then thisSize.Delete End Sub

You can specify a particular unit of measurement for a page size by setting the units for the document before getting its width and height.

Understanding the CorelDRAW object model 96

Corel Corel Draw Graphics Suite - X5 Programming Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Introduction

About this documentation

About additional resources

About Corel

Understanding automation

What is automation?

Which automation environments are supported?

What are the main elements of automation?

How is automation coding structured?

Getting started with macros

Setting up the automation feature

Using the Macros toolbars

Using the Macro Manager docker

Using the Add-in Manager

Using the Macro Editor

Using the VSTA Editor

Creating macros

Creating macro projects

Writing macros

Recording macros

Running macros

Debugging macros

Making macros user-friendly

Providing toolbars for macros

Providing dialog boxes for macros

Providing user interaction for macros

Providing documentation for macros

Organizing and deploying macros

Organizing macros

Deploying macros

Understanding the CorelDRAW object model

Working with documents

Working with pages