Understanding the CorelDRAW object model : Working with shapes : Creating shapes

Creating shapes

Every document is made up of shapes, or Shape objects, which are created by using the drawing tools. The shapes on a document page are stored on layers, so the various shape-creation methods belong to the Layer class.

For information on creating specific types of shapes, see the following subtopics:

If you want, you can use event handlers to respond to events that are triggered by creating a shape:

Creating rectangles

You can add rectangles (or Rectangle objects) to your documents by using one of the following methods:

These methods return a reference to the new Shape object. They differ only in the parameters that they take, so you can choose the method that best suits your macro solution.

The CreateRectangle method creates a rectangle by using four parameters that specify the following:

The following VBA example uses the CreateRectangle method to create a 2" × 1" rectangle that is positioned 6" up from the bottom of the page frame and 3" in from the left side of the page frame:

The CreateRectangle2 method creates a rectangle based on the coordinates of its lower-left corner, its width, and its height.

The following VBA example uses the CreateRectangle2 method to create the same rectangle as the previous example:

Finally, the CreateRectangleRect method creates a rectangle based on its bounding box (or Rect object).

These three rectangle-creation methods provide optional parameters for specifying corner roundness.

The CreateRectangle method specifies corner roundness by using parameters for the upper-left, upper-right, lower-left, and lower-right corners (in that order). These parameters take integer values (which range from the default 0 to 100) that define the radius of the four corners as a whole-number percentage of half of the length of the shortest side.

The following VBA example re-creates the 2" × 1" rectangle from the previous examples. However, this time, the four corner radii are set to 100%, 75%, 50%, and 0% of half of the length of the shortest side (that is, to 0.5", 0.375", 0.25", and a cusp):

The CreateRectangle2 method and the CreateRectangleRect method define the corner radii in the same order as the CreateRectangle method (that is, upper-left, upper-right, lower-left, and lower-right). However, CreateRectangle2 and CreateRectangleRect take double (floating-point) values that measure the corner radii in document units.

The following VBA example uses the CreateRectangle2 method to create the same round-cornered rectangle as the previous example:

Creating ellipses

You can add ellipses (or Ellipse objects) to your documents by using one of the following methods:

These methods return a reference to the new Shape object. They differ only in the parameters that they take, so you can choose the method that best suits your macro solution.

The CreateEllipse method creates an ellipse by using four parameters that specify the following:

The following VBA example creates a 50-millimeter circle:

The CreateEllipse2 method creates an ellipse based on its center point, its horizontal radius, and its vertical radius. (If only one radius is given, a circle is created.)

The following VBA example uses the CreateEllipse2 method to create an ellipse:

The following VBA example uses the CreateEllipse2 method to create the same 50-millimeter circle as the CreateEllipse example:

Finally, the CreateEllipseRect method creates an ellipse based on its bounding box (or Rect object).

These three ellipse-creation methods provide three optional parameters for creating an arc or a pie shape. The StartAngle and EndAngle parameters — which are double values that are measured with zero being horizontally right on the page and with positive values being degrees from zero and moving counterclockwise — are used to define the start angle and end angle of the shape (respectively). In addition, the Pie parameter — which is a Boolean value — defines whether the shape is an arc (False) or a pie shape (True).

The following VBA code uses the CreateEllipse method to create a “C” shape:

Creating lines and curves

You can add lines and curves (or Curve objects) to your documents. To create a line or a curve, you must first create a Curve object “in memory” by using the Application.CreateCurve method.

Each Curve object has at least one subpath (or SubPath object). You can add a subpath to a line or a curve by using the Curve.CreateSubPath method.

Each SubPath object has at least one segment (or Segment object), which can be line-type or curve-type. You can add a line-type segment to the end of a subpath by using the SubPath.AppendLineSegment method; you can add a curve-type segment by using the SubPath.AppendCurveSegment method or the SubPath.AppendCurveSegment2 method.

Finally, each Segment object has at least one node (or Node object). You can add a node to a segment by using the Segment.AddNodeAt method.

After creating a curve “in memory,” you can apply it to a layer by using the Layer.CreateCurve method. A reference to the new Shape object is returned.

The following VBA code creates a D-shaped curve that is closed:

The Layer class provides three additional methods that act as shortcuts for creating a basic line or basic curve that has a single segment on a single subpath:

Creating text objects

You can add text (or Text objects) to your documents. Two types of text are supported: artistic text and paragraph text. An artistic-text object is a short line of text to which you can apply graphical effects. In contrast, a paragraph-text object is a large block of text — stored in a rectangular container called a “frame” — to which you can apply more complex formatting.

To create an artistic-text object, you can use one of the following methods:

The following VBA code uses the CreateArtisticText method to create a basic artistic-text object that places the words “Hello World” at the specified position:

You can fit artistic text to a path by using the Text.FitTextToPath method, which simply attaches the text to the outline of a shape such that the text flows along the path of that shape.

The following VBA code creates a new artistic-text object and attaches it to the selected shape:

To create a paragraph-text object, you can use one of the following methods:

The following VBA code uses the CreateParagraphText method to create a basic paragraph-text object that centers the words “Hi There” in a frame of the specified size:

You can format existing paragraph text by using text ranges (or TextRange objects). Text ranges are handled in two ways, both of which involve frames (or TextFrame objects):

A text range can be treated as a single block of text, such that any changes to text properties (such as font style and font size) are applied to all text in that text range. Alternatively, a text range can be broken down into the following smaller text ranges:

The following VBA code formats the specified text range by using the Text.Story property. The first paragraph of the story is changed to a heading style and the second and third paragraphs into a body-text style:

You can place selected text inside closed shapes by using the Shape.PlaceTextInside method.

The following VBA code creates a 5" × 2" ellipse and places the selected text inside it:

Creating symbols

A symbol (or Symbol object) is a reusable graphic element that is defined in a symbol library. Using symbols in your documents provides the following benefits:

Symbol libraries come in two varieties: external and internal.

External symbol libraries use the filename extension CSL and contain symbol definitions that must be manually added to the workspace at the application level. You cannot modify a symbol that is defined in an external library unless you open the associated external library (CSL) file; simply importing the file as a library does not let you modify its contents.

Internal symbol libraries exist at the document level. Defining a new symbol in a document — or adding an instance of an external-library symbol to a document — automatically adds that symbol to the internal library for that document. For this reason, each document has its own unique internal symbol library.

The Application.SymbolLibraries property contains the collection of all external symbol libraries (or SymbolLibrary objects) that are available to the application; the Document.SymbolLibrary property returns just the internal symbol library for that document. The SymbolLibrary.Symbols property contains the collection of all symbol definitions (or SymbolDefinition objects) in that symbol library. A SymbolDefinition object is also returned by the Symbol.Defintion property; therefore, you can modify the defintion of a symbol by using the various properties and methods of the SymbolDefinition class.

The following VBA code demonstrates the basics of using symbols:

A symbol can contain (or “nest”) other symbols. A top-level symbol can contain symbols, and each of those symbols can contain a symbol, and so forth. In the object model, the SymbolDefinition.NestedSymbols property returns (as a SymbolDefinitions object) the collection of nested symbols for a symbol definition. While there is no restriction on how many nesting levels can be created, the symbol cannot be rendered without access to its symbol definition (whether external or internal). In addition, even if the first and second nesting layers of a symbol are rendered correctly, a symbol on the third nesting layer may not be rendered correctly without access to its required symbol definition.

Symbols and nested symbols

The following VBA code demonstrates the basics of using nested symbols:

Copyright 2013 Corel Corporation. All rights reserved.