4D CAD Reference

About this manual

This manual is UNDER CONSTRUCTION.

Documentation on one or multiple html pages.

How to use this manual

• Contents
• Introduction
• User reference
• Concepts
• Programming tasks
• Errors and constants
• Areas and methods
• Events
• 4D Draw emulation
• 4D Draw areas and methods
• Release notes
• Constant index
• Parameter index
• Method index
• General index
• Concept index

This documentation last updated on 7 May 2012.

This manual copyright ©2005 Adriaan van Os, The Netherlands. All rights reserved
The names of the actual products and companies listed herein are the trademarks of their
respective owners.

Contents

1 Introduction

• History
• Rationale
• How to use this manual
• Requirements
• Installation and licensing
• DemoCAD
• Technical support
• Bibliography
• The documentation system

1.1 History

Development of 4D CAD started in October 1998 at ARPA-Intrabouw, a leading software developer for the building-industries in The Netherlands.

The reasons for starting the project were quite convincing. End-users were dissatisfied with 4D Draw, it missed typical CAD features and we wanted something stable, fast and powerful.

I were given the task of writing the software and a first partial development release (4D CAD 1.0d2) was ready in June 1999. Yet, many features were missing and more development releases had to follow.

New features were always discussed first with Arend van Randen and I have to thank Arend for his excellent analyses and his many valuable suggestions.

When development releases came ready, David Righart started work on the DrawToCAD test application. I thank David for his feedback, his many suggestions and bug reports and for his fine cooperation up to today.

Also I have to thank Justus Janssen for answering my endless questions about AutoCAD and for providing me with test drawings in DXF format. Justus wrote the DXF export module of DrawToCAD.

My father Drs. Hans van Os, a retired teacher of mathematics, wrote a first version of the CADPolyAndPoly polyline intersection function, a daunting task.

In January 2001, I founded Microbizz. From then on, development continued at Microbizz and a first release version (4D CAD 1.0) was ready in July 2001. In successive months, 4D CAD was built into ARPA-Intrabouw’s application software, to the great satisfaction of end-users.

More releases and features followed and finally in November 2004, I found the time to rewrite DrawToCAD to a DemoCAD demonstration package. Work on the 4D CAD Reference started in April 2005 and will continue from there.

It is my sincere hope that 4D CAD will find enthousiastic developers and happy end-users.

Adriaan van Os
April 2005

1.2 Rationale

The rationale behind 4D CAD is simple. It combines the advantages of component software and integrated software.

• An application developer is most productive when he can fully concentrate on application functionality, using well-designed plug-in components
• And end-user is most productive in a tightly integrated software package.

1.3 How to use this manual

Read the chapter on Concepts to get a fundamental understanding of 4D CAD. Take special care studying the sections on

• Elementary mathematics (Coordinates, Angle and Linear transformation matrix)
• Base elements of a drawing (ID, Layer, Sublayer, Block and Scope).

To learn how to use 4D CAD, read the User reference chapter. The rest of the manual can be used as a reference work. Note the various indices

• Thematical method index
• List of Programming tasks
• Alphabetical list of Areas and methods
• List of Errors and constants
• List of Events
• Constant index
• Parameter index
• Method index
• General index
• Concept index.

Important

• This manual displays Mac OS X illustrations, but 4D CAD is compatible with Mac OS, Mac OS X and Windows
• Where this manual prints command key, on Windows the control key is meant. Where it prints option key, it is the alt key on Windows.

1.4 Requirements

4D CAD strives to be compatible with

• Mac OS X, version 10.5 or later
• Windows XP or later
• 4th Dimension 2003
• 4th Dimension 2004
• 4th Dimension v11 and v12, except for "Unicode mode"

Enough memory must be available to load large drawings. Importing raster images only works if Apple Quicktime is installed, both on Macintosh and on Windows.

1.5 Installation and licensing

On Macintosh put 4D CAD into the Mac4DX folder, on Windows put both plug-in files into the Win4DX folder.

You received a developer license file when you purchased 4D CAD. This file contains your name plus a unique number. It must be put in the resource fork of the 4D structure file (contact support@microbizz.nl if you don’t have access to a Macintosh to do this). Without this file, 4D will quit upon opening the application (don’t panic).

License files for server, client and run-time deployment must be put into the Mac4DX and Win4DX folders.

1.6 DemoCAD

DemoCAD is a 4D application with full source code, that demonstrates how to use 4D CAD. To get started with DemoCAD, run the software and play around with the various functions, available in menus.

Then, study the source code, starting with the procedures

• TAppMenuEvent
• TAppMenuEvent_I
• LDtCInput
• EDtCEvent
• EBlockEdEvent
• PCadMyTest

To get an understanding of DemoCAD internals, study

• TAppMenuSetup
• TAppMenuEnable
• TAppMenuEnabl_I
• TAppMenuEvent
• MHilbert
• MTurtle
• MDtC

DemoCAD was written using Microbizz Toolbox, an application framework for 4th Dimension, written over the years by Adriaan van Os and used by several 4D developers in The Netherlands. This manual doesn’t discuss Microbizz Toolbox (the methods starting with the letter T), but if you are interested, study the above procedures plus

• TStartup
• TMainSetup
• TMainEventLoop
• TOutput2Before
• TInputBefore
• TDialogBefore
• TWork2

Integrated into Microbizz Toolbox are two more plug-in packages

• Booster
• MultiDB

This manual doesn’t discuss them either.

Important

• The software is copyrighted. You are not allowed to redistribute the software. You may, however, use parts of it in your own end-user applications.
• Please increase the stack size of 4D before running the software.
• The software is provided AS IS, use it at your own risk.

DemoCAD
©2004-2011 ARPA-Intrabouw, The Netherlands
©2004-2011 Microbizz, The Netherlands

1.7 Technical support

For technical support by email, write to support@microbizz.nl with a clear description of the problem, precise error codes and possibly a screendump of what you are doing.

Microbizz can provide technical training and development services. Contact adriaan@microbizz.nl for more information.

1.8 Bibliography

Selected bibliography

• I.N. Bronshtein and K.A. Semendyayev, Handbook of Mathematics, third edition, english translation edited by K.A. Hirsch, Springer 1997, ISBN 3-540-62130-x.

  Standard work of mathematics, densely packed with formulas

• Adrian Bowyer and John Woodwark, A programmer’s geometry, Butterworths London 1988, ISBN 0-408-01242-0.

  An excellent and very useful book, in spite of the examples in Fortran. One of the few books on programming with geometry

• Niklaus Wirth, Algorithms and Data structures, Prentice-Hall 1986, ISBN 0-13-022005-1 01.

  The one famous book that must be on every programmer’s desk

• Apple Developer Connection http://developer.apple.com

  Apple developer documentation and services

• Microsoft Developer Network http://www.msdn.com

  Microsoft developer documentation and services

• 4D Support http://4d.com/support.html

  4th Dimension developer documentation and services.

1.9 The documentation system

This manual was created with the GNU Texinfo documentation system, using a CodeWarrior plug-in compiler written by Adriaan van Os. It was later ported to Xcode.

Illustrations were created using 4D CAD and Apple Preview (and exported to the patent-free PNG format).

2 User reference

This chapter describes 4D CAD from a user perspective, although with hints for developers on customization and related methods.

• Area
• Mode palette
• Tool palette
• Measure pane
• Anchor pane
• Zoom info bar
• Title split
• Grips and blips
• Current layer
• Current drawing attributes
• Double-click
• Copy and paste
• Undo and redo
• Snaps
• Fast dragging
• Using the keyboard
• Using the mouse wheel
• String editing

The mode palette section has subsections for the various modes

• Intersect mode
• Enclose mode
• Touch mode
• Reshape mode
• Translate mode
• Zoom in mode
• Zoom out mode
• Zoom continuous mode
• Drag-scroll mode
• Draw line mode
• Draw polyline mode
• Draw square mode
• Draw rectangle mode
• Draw circle mode
• Draw ellipse mode
• Draw circle arc mode
• Draw ellipse arc mode
• Special click mode
• Write string mode
• Clip box mode
• Printing preview mode

2.1 Area

A 4D CAD area consists of the following elements

More elements can be added with a Title split.

Programming
The area can be customized with CADSetDisplay.

Areas
%CAD, %CADView, %CADBackground

Methods
CADGetDisplay, CADSetDisplay.

2.2 Mode palette

Modes on the mode palette are:

• Intersect mode
• Enclose mode
• Touch mode
• Reshape mode
• Translate mode
• Zoom in mode
• Zoom out mode
• Zoom continuous mode
• Drag-scroll mode
• Draw line mode
• Draw polyline mode
• Draw square mode
• Draw rectangle mode
• Draw circle mode
• Draw ellipse mode
• Draw circle arc mode
• Draw ellipse arc mode
• Special click mode
• Write string mode
• Clip box mode
• Printing preview mode

Methods
CADGetMode, CADSetMode.

2.2.1 Intersect mode

Intersect mode is a specialized object selection mode. In this mode you can

• Drag an intersection rectangle to select those objects that intersect the rectangle
• Drag an intersection rectangle with the shift key to add those objects to the selection that intersect the rectangle
• Drag an intersection rectangle with the command key to remove those objects from the selection that intersect the rectangle
• Click on an object to select it
• Click on an object with the shift key to add it to the selection
• Click on an object with the command key to remove it from the selection
• Click on a selected object to select instead the object that is at the same point behind it
• Click on a selected object with the shift key to add to the selection the object that is at the same point behind it
• Click on a deselected object with the command key to remove from the selection the deselected object that is at the same point behind it
• Click in empty space to deselect all objects
• Hold down the option key to use Drag-scroll mode
• Press the space bar to switch to Drag-scroll mode.

Methods
CADSelect.

2.2.2 Enclose mode

Enclose mode is a specialized object selection mode. In this mode you can

• Drag an enclosure rectangle to select those objects that are enclosed by the rectangle
• Drag an enclosure rectangle with the shift key to add those objects to the selection that are enclosed by the rectangle
• Drag an enclosure rectangle with the command key to remove those objects from the selection that are enclosed by the rectangle
• Click on an object to select it
• Click on an object with the shift key to add it to the selection
• Click on an object with the command key to remove it from the selection
• Click on a selected object to select instead the object that is at the same point behind it
• Click on a selected object with the shift key to add to the selection the object that is at the same point behind it
• Click on a deselected object with the command key to remove from the selection the deselected object that is at the same point behind it
• Click in empty space to deselect all objects
• Hold down the option key to use Drag-scroll mode
• Press the space bar to switch to Drag-scroll mode.

Methods
CADSelect.

2.2.3 Touch mode

Touch mode is a specialized object selection mode. In this mode you can

• Drag a touch line to select those objects that are touched by the line
• Drag a touch line with the shift key to add those objects to the selection that are touched by the line
• Drag a touch line with the command key to remove those objects from the selection that are touched by the line
• Click on an object to select it
• Click on an object with the shift key to add it to the selection
• Click on an object with the command key to remove it from the selection
• Click on a selected object to select instead the object that is at the same point behind it
• Click on a selected object with the shift key to add to the selection the object that is at the same point behind it
• Click on a deselected object with the command key to remove from the selection the deselected object that is at the same point behind it
• Click in empty space to deselect all objects
• Hold down the option key to use Drag-scroll mode
• Press the space bar to switch to Drag-scroll mode.

Methods
CADSelect.

2.2.4 Reshape mode

Reshape mode is a general purpose object selection and edit mode. In this mode you can

• Drag an intersection rectangle to select those objects that intersect the rectangle
• Drag an intersection rectangle with the shift key to add those objects to the selection that intersect the rectangle
• Drag an intersection rectangle with the command key to remove those objects from the selection that intersect the rectangle
• Click on a deselected object to select it
• Click on an object with the shift key to add it to the selection
• Click on an object with the command key to remove it from the selection
• Click in empty space to deselect all objects
• Click on an object’s grip handle to reshape or resize it (as listed in the table)
• Click on an object’s outline, center blip, fill or on a hatch line to translate it
• Press the space bar to switch to Drag-scroll mode.

When translating, you can

• Choose as the target point for snaps the grip handle or center blip that is nearest to the cursor
• Hold down the shift key to restrict the translation to a horizontal or vertical movement
• Hold down the option key to use fast drags
• Press ESC to cancel the translation.

The cursor changes to an arrow cursor when it is on top of a grip handle. It is used for a reshape or resize, where you can

• Hold down the shift key during the drag to change the action (as listed in the table)
• Hold down the command key before the drag to change the action (as listed in the table)
• Hold down the option key to use fast drags
• Press ESC to cancel the reshape or resize.

Object type	Modifier key	Solid grip handle	Open grip handle
Line	−	Drag the line’s start- or endpoint	−
	shift	Restrict movement to the line’s direction	−
	command	Anchor the line’s center	−
Polyline	−	Drag a polyline vertex	Move a polyline line
	shift	Restrict movement to an adjacent line’s direction	Move the line perpendicular to its own direction
	command	Resize the polyline from its center	Resize the polyline from its center
	shift & command	Resize the polyline proportionally from its center	Resize the polyline proportionally from its center
Square	−	Resize the square diagonally	Resize the square horizontally or vertically
	command	Anchor the square’s center	Anchor the square’s center
Rectangle	−	Drag a rectangle vertex	Drag a rectangle line
	shift	Resize the rectangle proportionally	Resize the rectangle proportionally
	command	Anchor the rectangle’s center	Anchor the rectangle’s center
Circle	−	Resize the circle diagonally	Resize the circle horizontally or vertically
	command	Anchor the circle’s opposite box vertex	Anchor the circle’s opposite side
Ellipse	−	Reshape the ellipse, anchoring its center	Resize the ellipse horizontally or vertically
	shift	Resize the ellipse proportionally	Resize the ellipse proportionally
	command	Anchor the ellipse’s opposite box vertex	Anchor the ellipse’s center
Circle arc	−	Resize the circle arc	Change the circle arc’s start or end angle
Ellipse arc	−	Reshape the ellipse arc	Change the ellipse arc’s start or end angle
	shift	Resize the ellipse arc proportionally	−
String	−	−	Resize the string
Raster image	−	Resize the raster image proportionally	Resize the raster image vertically or horizontally
	shift	Resize the raster image unrestricted (unless it is sheared)	Resize the raster image proportionally
	command	Anchor the raster image’s center	Anchor the raster image’s center
Block insert	−	Resize the block insert proportionally	Resize the block insert vertically or horizontally
	shift	Resize the block insert unrestricted (unless it is sheared)	Resize the block insert proportionally
	command	Anchor the block insert’s center	Anchor the block insert’s center

A reshape or resize can have the effect that an object is flipped horizontally or vertically or both horizontally and vertically. The latter is equal to a 180 degrees rotation.

Important
When you drag, you will notice that nothing happens until the cursor moves a few pixels. This is called drag hesitation and its purpose is to prevent unintentional drags caused by object selection.

Programming
Drags can be customized with CADSetDragPrefs, snaps with CADSetSnapPrefs.

Methods
CADGetSnapPrefs, CADSetSnapPrefs, CADGetDragPrefs, CADSetDragPrefs.

2.2.5 Translate mode

Translate mode is a specialized object selection and translation mode, available only by calling CADSetMode. In this mode you can

• Click on a selected object’s outline, grip handle, center blip, fill or on a hatch line to translate selected objects
• Click on a deselected object to select it
• Click on a deselected object to select and translate it
• Click on a deselected object with the command key to translate selected objects
• Click in empty space with the command key to translate selected objects
• Click on an object with the shift key to add it to the selection
• Click on an object with the shift key to add it to the selection and to translate the new selection
• Click on selected object with the command key to remove it from the selection
• Click in empty space to deselect all objects
• Press the space bar to switch to Drag-scroll mode.

When translating, you can

• Choose as the target point for snaps the grip handle or center blip that is nearest to the cursor
• Hold down the shift key to restrict the translation to a horizontal or vertical movement
• Hold down the option key to use fast drags
• Press ESC to cancel the translation.

Important
When you drag, you will notice that nothing happens until the cursor moves a few pixels. This is called drag hesitation and its purpose is to prevent unintentional drags caused by object selection.

Programming
Drags can be customized with CADSetDragPrefs, snaps with CADSetSnapPrefs.

Methods
CADSetMode, CADGetSnapPrefs, CADSetSnapPrefs, CADGetDragPrefs, CADSetDragPrefs.

2.2.6 Zoom in mode

Zoom in mode is a specialized zoom mode. In this mode you can

• Click to zoom in at that point
• Drag a zoom rectangle to zoom in to that rectangle
• Hold down the option key to use Zoom out mode
• Hold down the shift key to use Drag-scroll mode
• Press the space bar to switch to Reshape mode.

Important
This mode implements stepped zooming, which makes sure that a pixel on the screen always corresponds to an integral number of units. Thus, drawing objects is more precise. This feature can be customized with CADSetZoomPrefs. Also see Zoom info bar.

Methods
CADZoom, CADGetZoom, CADAutoZoom, CADGetZoomPrefs, CADSetZoomPrefs.

2.2.7 Zoom out mode

Zoom out mode is a specialized zoom mode. In this mode you can

• Click to zoom out at that point
• Drag a zoom rectangle to zoom out to a rectangle proportional to that rectangle
• Hold down the command key to use Zoom in mode
• Hold down the shift key to use Drag-scroll mode
• Press the space bar to switch to Reshape mode.

Important
This mode implements stepped zooming, which makes sure that a pixel on the screen always corresponds to an integral number of units. Thus, drawing objects is more precise. This feature can be customized with CADSetZoomPrefs. Also see Zoom info bar.

Methods
CADZoom, CADGetZoom, CADAutoZoom, CADGetZoomPrefs, CADSetZoomPrefs.

2.2.8 Zoom continuous mode

Zoom continuous mode is a specialized zoom mode. In this mode you can

• Click and drag around a point to zoom continous at that point, clockwise to zoom in, counter-clockwise to zoom out
• Hold down the command key to use Zoom in mode
• Hold down the option key to use Zoom out mode
• Hold down the shift key to use Drag-scroll mode
• Press the space bar to switch to Reshape mode.

Important
This mode does not implement stepped zooming,

Methods
CADZoom, CADGetZoom, CADAutoZoom, CADGetZoomPrefs, CADSetZoomPrefs.

2.2.9 Drag-scroll mode

Drag-scroll mode is a general-purpose drag-scroll and zoom mode. In this mode you can

• Click to drag the entire drawing (in full animation)
• Hold down the command key to use Zoom in mode
• Hold down the option key to use Zoom out mode
• Hold down the shift key to use Zoom continuous mode
• Press the space bar to switch to Reshape mode.

Important
Drag-scroll only works if the corresponding scroll bar is present. The presence of scroll bars can be customized with CADSetDisplay.

Methods
CADScroll, CADScrollTo, CADGetScroll, CADZoom, CADGetZoom, CADAutoZoom, CADGetDisplay, CADSetDisplay. CADGetZoomPrefs, CADSetZoomPrefs.

2.2.10 Draw line mode

Draw line mode is a specialized mode to draw lines. In this mode you can

• Click, drag and click again to create a line object
• Move the cursor out of the drawing plane during the drag, to scroll
• Hold down the shift key to create a horizontal or vertical line object
• Hold down the command key (before the first click) to create a line object from its center
• Hold down the option key to use fast drags
• Hold down the S key to disable Snaps
• Press ESC to cancel the creation of the line
• Press the space bar to switch to Reshape mode.

Line objects are created on the Current layer and with the Current drawing attributes.

Programming
Line drawing can be customized with CADSetDragPrefs, snaps with CADSetSnapPrefs.

Methods
CADAddLine, CADGetCurrentLayer, CADSetCurrentLayer, CADGetDefaults, CADSetDefaults, CADGetSnapPrefs, CADSetSnapPrefs, CADGetDragPrefs, CADSetDragPrefs.

2.2.11 Draw polyline mode

Draw polyline mode is a specialized mode to draw polylines. In this mode you can

• Click to start the polyline
• Drag and click to create successive line sections
• Click on the last or first polyline point to complete the creation of the polyline
• Move the cursor out of the drawing plane during a drag, to scroll
• Hold down the shift key to create a horizontal or vertical line section
• Hold down the option key to use fast drags
• Hold down the S key to disable Snaps
• Press Backspace to remove the last polyline point
• Press ESC to cancel the creation of the polyline
• Press the space bar to switch to Reshape mode.

Polyline objects are created on the Current layer and with the Current drawing attributes. A closed polyline object must have at least three vertices, an open polyline at least two.

Programming
Polyline drawing can be customized with CADSetDragPrefs, snaps with CADSetSnapPrefs.

Methods
CADAddPolyLine, CADGetCurrentLayer, CADSetCurrentLayer, CADGetDefaults, CADSetDefaults, CADGetSnapPrefs, CADSetSnapPrefs, CADGetDragPrefs, CADSetDragPrefs.

2.2.12 Draw square mode

Draw square mode is a specialized mode to draw squares. In this mode you can

• Click, drag to the left or right, and click again to create a square object
• Move the cursor out of the drawing plane during the drag, to scroll
• Hold down the shift key (before the first click) to drag a square object at a vertex (diagonally)
• Hold down the command key (before the first click) to create a square object from its center
• Hold down the option key to use fast drags
• Press ESC to cancel the creation of the square
• Press the space bar to switch to Reshape mode.

Square objects are created on the Current layer and with the Current drawing attributes.

Programming
Square drawing can be customized with CADSetDragPrefs.

Methods
CADAddSquare, CADGetCurrentLayer, CADSetCurrentLayer, CADGetDefaults, CADSetDefaults, CADGetDragPrefs, CADSetDragPrefs.

2.2.13 Draw rectangle mode

Draw rectangle mode is a specialized mode to draw rectangles. In this mode you can

• Click, drag and click again to create a rectangle object
• Move the cursor out of the drawing plane during the drag, to scroll
• Hold down the shift key to create a square rectangle (but still a rectangle object)
• Hold down the command key (before the first click) to create a rectangle object from its center
• Hold down the option key to use fast drags
• Hold down the S key to disable Snaps
• Draw a rectangle in the length when a fixed-width has been set for the Current drawing attributes
• Draw a rectangle in the width when a fixed-length has been set for the Current drawing attributes
• Press ESC to cancel the creation of the rectangle
• Press the space bar to switch to Reshape mode.

Rectangle objects are created on the Current layer and with the Current drawing attributes.

Programming
Rectangle drawing can be customized with CADSetDragPrefs, snaps with CADSetSnapPrefs. To set a fixed-width or fixed-length drawing default, call CADSetDefaults.

Methods
CADAddRectangle, CADGetCurrentLayer, CADSetCurrentLayer, CADGetDefaults, CADSetDefaults, CADGetSnapPrefs, CADSetSnapPrefs, CADGetDragPrefs, CADSetDragPrefs.

2.2.14 Draw circle mode

Draw circle mode is a specialized mode to draw circles. In this mode you can

• Click, drag to the left or right, and click again to create a circle object
• Move the cursor out of the drawing plane during the drag, to scroll
• Hold down the shift key (before the first click) to drag a circle object at a solid grip handle (diagonally)
• Hold down the command key (before the first click) to create a circle object from an anchored side
• Hold down the shift and command keys (before the first click) to create a circle object from an anchored box vertex
• Hold down the option key to use fast drags
• Press ESC to cancel the creation of the circle
• Press the space bar to switch to Reshape mode.

Circle objects are created on the Current layer and with the Current drawing attributes.

Programming
Circle drawing can be customized with CADSetDragPrefs.

Methods
CADAddCircle, CADGetCurrentLayer, CADSetCurrentLayer, CADGetDefaults, CADSetDefaults, CADGetDragPrefs, CADSetDragPrefs.

2.2.15 Draw ellipse mode

Draw ellipse mode is a specialized mode to draw ellipses. In this mode you can

• Click, drag and click again to create an ellipse object
• Move the cursor out of the drawing plane during the drag, to scroll
• Hold down the shift key to create a circular ellipse (but still an ellipse object)
• Hold down the command key (before the first click) to create a ellipse object from an anchored box vertex
• Hold down the option key to use fast drags
• Hold down the S key to disable Snaps
• Press ESC to cancel the creation of the ellipse
• Press the space bar to switch to Reshape mode.

Ellipse objects are created on the Current layer and with the Current drawing attributes.

Programming
Ellipse drawing can be customized with CADSetDragPrefs, snaps with CADSetSnapPrefs.

Methods
CADAddEllipse, CADGetCurrentLayer, CADSetCurrentLayer, CADGetDefaults, CADSetDefaults, CADGetSnapPrefs, CADSetSnapPrefs, CADGetDragPrefs, CADSetDragPrefs.

2.2.16 Draw circle arc mode

Draw circle arc mode is a specialized mode to draw circle arcs. In this mode you can

• Click, drag to the left or right, and click again to create a circle arc object
• Move the cursor out of the drawing plane during the drag, to scroll
• Hold down the option key to use fast drags
• Press ESC to cancel the creation of the circle arc
• Press the space bar to switch to Reshape mode.

Circle arc objects are created on the Current layer and with the Current drawing attributes.

Programming
Circle arc drawing can be customized with CADSetDragPrefs.

Methods
CADAddCircleArc, CADGetCurrentLayer, CADSetCurrentLayer, CADGetDefaults, CADSetDefaults, CADGetDragPrefs, CADSetDragPrefs.

2.2.17 Draw ellipse arc mode

Draw ellipse arc mode is a specialized mode to draw ellipse arcs. In this mode you can

• Click, drag and click again to create an ellipse arc object
• Move the cursor out of the drawing plane during the drag, to scroll
• Hold down the shift key to create a circular ellipse arc (but still an ellipse arc object)
• Hold down the option key to use fast drags
• Hold down the S key to disable Snaps
• Press ESC to cancel the creation of the ellipse arc
• Press the space bar to switch to Reshape mode.

Ellipse arc objects are created on the Current layer and with the Current drawing attributes.

Programming
Ellipse arc drawing can be customized with CADSetDragPrefs, snaps with CADSetSnapPrefs.

Methods
CADAddEllipseArc, CADGetCurrentLayer, CADSetCurrentLayer, CADGetDefaults, CADSetDefaults, CADGetSnapPrefs, CADSetSnapPrefs, CADGetDragPrefs, CADSetDragPrefs.

2.2.18 Special click mode

The purpose of special click mode is application specific. Typical examples are

• the insertion of blocks
• special functions in customized applications.

Dependent on the setting of theSpecialClickModeModifiers parameter of CADSetAreaPrefs, you can

• Hold down the command key to use Zoom in mode
• Hold down the option key to use Zoom out mode
• Hold down the shift key to use Drag-scroll mode
• Press the space bar to switch to Drag-scroll mode.

Important
Implementation is left to the application developer (see kCADEventIDSpecialClick and Events and for example code the EDtCEvent method in DemoCAD).

Methods
CADAddInsert, CADAddInsertXY, CADGetAreaPrefs, CADSetAreaPrefs, CADGetOnEvent, CADSetOnEvent, CADOnEvent.

2.2.19 Write string mode

The purpose of write string mode is to add and edit strings. The string

• has a maximum of 255 characters
• may not contain carriage return, line feed or tab characters
• is always on one line
• has one set of style attributes for the entire string.

String editing in the form of a string edit box is built into 4D CAD.

Dependent on the setting of theWriteStringModeModifiers parameter of CADSetAreaPrefs, you can also

• Hold down the command key to use Zoom in mode
• Hold down the option key to use Zoom out mode
• Hold down the shift key to use Drag-scroll mode
• Press the space bar to switch to Drag-scroll mode.

Important
The application can overrule the built-in string editor with CADSetAreaPrefs (also see kCADEventIDWriteString and Events and the EDtCEvent method in DemoCAD).

Methods
CADAddString, CADGetAreaPrefs, CADSetAreaPrefs, CADGetOnEvent, CADSetOnEvent, CADOnEvent.

2.2.20 Clip box mode

Clip box mode sets a clipping rectangle. In this mode you can

• Drag a clipping rectangle to set the clip box
• Click on an object to set the clip box to the object’s physical bounds
• Click in empty space to clear the clip box
• Hold down the command key to use Zoom in mode
• Hold down the option key to use Zoom out mode
• Hold down the shift key to use Drag-scroll mode
• Press the space bar to switch to Drag-scroll mode.

The Clip box is used

• when printing with CADPrint
• when zooming with CADAutoZoom
• when displaying a CAD area in a 4D output form
• when displaying a CAD drawing in another plug-in’s area.

Programming
The clip box can be read with CADGetClipBox and set with CADSetClipBox.

Methods
CADGetClipBox, CADSetClipBox, CADAutoZoom, CADPrint.

2.2.21 Printing preview mode

Printing preview mode shows a preview of how a drawing would print on paper, with numbered pages. In this mode you can

• Click to drag the entire drawing
• Hold down the command key to use Zoom in mode
• Hold down the option key to use Zoom out mode
• Hold down the shift key to use Zoom continuous mode
• Press the space bar to switch to Drag-scroll mode.

To calculate the number of pages, their size and alignment, 4D CAD uses the area’s current settings for

• the printer’s page-setup (CADPageSetup)
• the printing scale (CADGetScale and CADSetScale)
• the printing prefs (CADGetPrintSpecs and CADSetPrintSpecs)
• the clip box (CADGetClipBox and CADSetClipBox).

Methods
CADPrint, CADPageSetup, CADGetPaperSizes, CADGetScale, CADSetScale, CADGetClipBox, CADSetClipBox, CADGetPrintSpecs, CADSetPrintSpecs.

2.3 Tool palette

With the buttons on the tool palette you can

• Mirror a selection horizontal (in the vertical line that runs through the center of their common bounds)
  
  
• Mirror a selection vertical (in the horizontal line that runs through the center of their common bounds)
  
  
• Flip objects horizontal (each object separately)
  
  
• Flip objects vertical (each object separately)
  
  
• Rotate a selection to the left (around the center of their common bounds)
  
  
• Rotate a selection to the right (around the center of their common bounds)
  
  
• Rotate objects to the left (each object separately)
  
  
• Rotate objects to the right (each object separately).
  
  

Methods
CADCommand.

2.4 Measure pane

The measure pane is used to display and edit metrical values of selected objects.

In the measure pane you can

• Click on an edit box to start editing a value
• Edit the floating point number to change the metrical value
• Enter numbers in scientific notation up to a maximum of 1e100 and −1e100
• Press Return to accept the value while leaving the measure pane
• Press Down Arrow or Tab to accept the value while moving to the next editable value
• Press Up Arrow or Shift-Tab to accept the value while moving to the previous editable value
• Press ESC to cancel the edit
• Translate objects by editing the x-translation and y-translation fields
• Rotate objects with a rotation attribute by editing the rotation and rotation change fields.

Special considerations

• When selected objects have non-matching values, the edit box shows "−−", but a value can still be entered
• The measure pane uses the decimal-point character that has been set in system software preferences
• When a measure pane value is applied, objects with a relevant lock are automatically skipped
• For objects of type Line, length is the x-length and width the y-length, unless the measure pane was customized not to display the line length box
• The Anchor pane determines which part of an object stays in place when the width or length is changed
• The values for x-coordinate and y-coordinate are non-editable. In translate, reshape and draw modes, snapped values are displayed (see snap)
• The values for perimeter and surface area are non-editable. They display the sum perimeter and sum surface area of all objects in the selection.
• The perimeter and surface area of block inserts are calculated from the length and width of the insert object, not from the objects in the block.

Programming
The measure pane can be customized with CADSetMeasurePrefs.

Methods
CADGetMeasurePrefs, CADSetMeasurePrefs.

2.5 Anchor pane

The Anchor pane determines which part of an object is anchored (stays in place) when in the Measure pane a width, length or line length value is changed.

Important
The anchor pane specifies each object’s anchor in its unrotated and unmirrored state. When objects are mirrored or rotated, their anchors will be mirrored and rotated also.

2.6 Zoom info bar

The zoom info bar displays the size of a screen pixel, measured in the area’s unit (see Unit and scale).

4D CAD implements stepped zooming, which makes sure that a pixel on the screen corresponds to an integral number of units. Thus, drawing objects is more precise (this feature can be customized with CADSetZoomPrefs).

In rare cases, the zoom info bar will display an error code instead. This happens when a screen refresh causes an error. If so, click on the zoom info bar to reset it.

Methods
CADZoom, CADGetZoom, CADAutoZoom, CADGetZoomPrefs, CADSetZoomPrefs.

2.7 Title split

A title split splits off left and top title views. The title views scroll in a special manner, most suitable to keep column and row titles into view, as in a spreadsheet. The figure shows (dimmed in the background) a planboard application, written in 4D CAD.

Programming

• Zooming a view also zooms the other views, but these views need a zoom anchor point that determines from which point they are zoomed
• Often, it will be desirable to limit the scroll range of a view, so that for example column and row titles don’t show up in the main view. The box that can be viewed is called the goggle box
• Horizontal and vertical title split scroll bars are optional
• You can set up a top-only or left-only title split
• Remember that even with a title split, there is only one drawing. A view is merely a way to look at it.

Methods
CADGetTitleSplit, CADSetTitleSplit, CADZoom, CADAutoZoom, CADGetZoom, CADScroll, CADScrollTo, CADGetScroll.

2.8 Grips and blips

In the figure you see center blips, solid grip handles and open grip handles for selected objects of diverse type. Note that the Cursor will change to an arrow cursor when you move it on top of a blip or grip handle.

The functions of grips and blips are discussed in the Reshape mode, Translate mode and various draw mode subsections. Not all grip handles will be present for objects with locks (see Locking).

Methods
CADGetLock, CADSetLock, CADGetObjLock, CADSetObjLock.

2.9 Current layer

All user operations work on the current layer. Typically, the application implements a dialog that lets you set the current layer. Please note that an empty drawing has no Layer, nor a current layer.

Important

• Unlike user operations, 4D CAD methods don’t necessarily operate on the current layer, see the section on Parameter passing
• Implementation of a dialog to set the current layer is left to the application developer (for example code see the Layer editor... menu item in the CAD menu of DemoCAD, called through the TAppMenuEvent_I method).

Programming
To create a current layer in an empty drawing, call CADAddLayer and CADSetCurrentLayer.

Methods
CADAddLayer, CADGetCurrentLayer, CADSetCurrentLayer.

2.10 Current drawing attributes

In the various draw modes, new user objects are drawn with current drawing attributes. Typically, the application implements a dialog that lets you enter these attributes as defaults

• Linetype
• Linewidth
• Line Color
• Fill color
• Fill style
• Hatch
• Start & end Marking
• Font
• Font style
• Font size
• String justification
• Object rotation
• Circle arc and Ellipse arc start angle
• Circle arc and Ellipse arc end angle
• Fixed width or fixed length of a Rectangle (see Draw rectangle mode)
• Locks (see Locking)

Important

• Unlike user operations, 4D CAD methods don’t use the current drawing attributes, see the section on Parameter passing
• Implementation of a dialog to set default drawing attributes is left to the application developer (for example code see the Drawing attributes... menu item in the CAD menu of DemoCAD, called through the TAppMenuEvent_I method).

Methods
CADGetDefaults, CADSetDefaults.

2.11 Double-click

Typically, the application implements object information dialogs that let you view and edit metrical data and object attributes. These dialogs show up when you double-click an object. There are several flavours of object information dialogs

• A dialog for each object type, shown when one object is selected
• A dialog for multiple objects, shown when several objects are selected.

The multiple objects variant must have an extra checkbox for each object attribute in the dialog. When the dialog is confirmed and the checkbox is set, the value entered for the attribute is applied to all objects in the selection.

Important
Implementation of object information dialogs is left to the application developer (for example code see the EDtCEvent method in DemoCAD).

2.12 Copy and paste

With copy and paste you can generally

• Choose Cut in the Edit menu or press command-x to move selected data to the clipboard
• Choose Copy in the Edit menu or press command-c to copy selected data to the clipboard
• Choose Paste in the Edit menu or press command-v to copy data from the clipboard
• Choose Clear in the Edit menu or press the delete or backspace key to remove selected data
• Choose Select All in the Edit menu or press the command-a to select all data.

In 4D CAD this applies to selected objects in drawings and to selected characters in a measure pane edit box. In particular, you can

• Hold down the option key while pasting objects, in order to copy the objects to the current layer (normally objects are pasted to their original layers).

Special considerations

• You can copy and paste objects in a drawing and between drawings, but not between different applications
• Copying and pasting raster images, Macintosh pictures and Windows WMF and EMF drawings, has not been implemented (yet).
• Paste may zoom in automatically, so that it is clear that objects have been pasted
• Paste may change the drawing bounds if needed
• Paste automatically scales objects pasted to an area with a different unit.
• Pasting objects also pastes elements needed by those objects: layers, inserted blocks, linetypes, hatches, markings. To prevent unnecessary copying, elements in the drawing are compared with elements in the clipboard. Layers are identified by their name and unmasked keys. Other elements are identified by their content and unmasked keys (see Key masks).

Programming
Installing an event procedure gives the programmer full control over copy and paste, see Copy and paste control.

Methods
CADGetOnEvent, CADSetOnEvent, CADCommand, CADGotoPage, CADGetKeyMask, CADSetKeyMask, CADMoveTo, CADCopyTo, CADCopyObjTo, CADCopyBlocks, CADCompareBlock, CADCompareObj.

2.13 Undo and redo

4D CAD implements single undo and redo. You can

• Choose Undo in the Edit menu or press command-z to undo the last action
• Choose Redo in the Edit menu or press command-z to redo it afterwards.

Special considerations

• Undo and redo restore the zoom box, the drawing size and the clip box
• 4D CAD does not implement undo and redo for cut and paste. You can paste and cut to undo and redo these actions
• Selecting objects is not an undoable action, nor does it affect the undo state
• DemoCAD does not implement undo and redo for application dialogs.

Programming
See Undo handling.

Methods
CADGetOnEvent, CADSetOnEvent, CADGetUndoPrefs, CADSetUndoPrefs, CADTriggerUndo, CADResetUndo.

2.14 Snaps

Snaps are like magnetic points, they attract the cursor when you drag or draw. Is the cursor too near, then it snaps to the magnetic point. Snaps are visible in the drawing as small circles. They are defined for

• Object grips, both solid and open grips (see Grips and blips)
• Object center blips (see Grips and blips)
• Any intersection point of two objects
• Any snaps that application code adds to blocks (e.g. to mark a block’s insertion point).

Special considerations

• Holding down the S key releases the snap
• Hatch lines don’t snap
• There are currently no snaps for restricted draw and drag movements (like when the shift key was pressed or when you draw a square or circle)
• Objects on dimmed and invisible Layers don’t snap (unless this was changed with CADSetSnapPrefs)
• Snapping can be put on and off for each Layer (by calling CADSetLayerAttributes).

Important
The application can add custom snaps to a block with CADSetBlockAddedSnaps. It can determine which snaps are active, by calling CADSetLayerAttributes, CADSetBlockSnapMask and CADSetSnapPrefs.

Methods
CADGetSnapPrefs, CADSetSnapPrefs, CADFindSnap, CADGetLayerAttributes, CADSetLayerAttributes, CADGetBlockAddedSnaps, CADSetBlockAddedSnaps, CADGetBlockSnapMask, CADSetBlockSnapMask.

2.15 Fast dragging

Normally, full animation is used when you draw or drag objects. 4D CAD was designed to be very fast, but in special circumstances full animation may be too slow (e.g. when working with large raster images). If so, press the option key to draw or drag an outline instead of the full object.

Important
This feature can be customized with CADSetDragPrefs.

Methods
CADGetDragPrefs, CADSetDragPrefs.

2.16 Using the keyboard

With the keyboard you can

• Run items in the Edit menu, as disussed in the Copy and paste and Undo and redo sections
• Work with the Measure pane, as disussed in that section
• Select Drag-scroll mode or Reshape mode with the space bar, as discussed in Mode palette subsections
• Translate selected objects one pixel at the time with the arrow keys
• Translate selected objects ten pixels at the time with the arrow keys plus the command key modifier
• Trigger application defined actions through keyboard events.

Programming
See Event handling.

Methods
CADGetOnEvent, CADSetOnEvent.

2.17 Using the mouse wheel

With the mouse wheel you can, by default

• Scroll vertically up and down
• Scroll horizontally up and down when the mouse wheel permits horizontal scroll
• Hold down the shift key to scroll horizontally up and down
• Hold down the option key on Macintosh or the control key on Windows to zoom in and out

Important
The use of the mouse wheel can be customized with CADSetMouseWheelPrefs.

Methods
CADGetMouseWheelPrefs, CADSetMouseWheelPrefs.

2.18 String editing

In a 4D CAD string edit box, you can apply the following edit operations:

If a caret is shown

• press the left-arrow key to move the caret one character to the left
• press the left-arrow and option keys to move the caret one word to the left
• press the left-arrow and shift keys to select the character at the left of the caret
• press the left-arrow and shift and option keys to select the word at the left of the caret
• press the right-arrow key to move the caret one character to the right
• press the right-arrow and option keys to move the caret one word to the right
• press the right-arrow and shift keys to select the character at the right of the caret
• press the right-arrow and shift and option keys to select the word at the right of the caret
• press the up-arrow key to move the caret to the start of the text
• press the up-arrow and shift keys to select the text from the start of the text up to the caret
• press the down-arrow key to move the caret to the end of the text
• press the down-arrow and shift keys to select the text from the caret to the end of the text
• press the backspace key to remove the character at the left of the caret
• press the forward delete key to remove the character at the right of the caret
• press the return, tab and enter key to conclude the edit box, accepting the changes
• press the escape key to conclude the edit box, canceling the changes
• enter characters to insert them at the caret position
• click the mouse to set the caret at the nearest character position
• click the mouse holding the shift key to select the text from the nearest character position to the caret
• click and drag the mouse to dynamically select text
• double-click the mouse to select a word
• double-click and drag the mouse to dynamically select text, starting with a word
• triple-click the mouse to select a whole line of text
• perform an edit-paste to insert clipboard text (if any) at the caret position
• perform an edit-undo to cancel the last editing operation
• perform an edit-redo to redo the last editing operation

If a selection is highlighted

• press the left-arrow key to show a caret at the left of the former selection
• press the left-arrow and option keys to show a caret one word to the left of the former selection
• press the left-arrow and shift keys to extend the selection with the character at the left (or to remove a character from a previous extension at the right)
• press the left-arrow and shift and option keys to extend the selection with the word at the left (or to remove a word from a previous extension at the right)
• press the right-arrow key key to show a caret at the right of the former selection
• press the right-arrow and option keys to show a caret one word to the right of the former selection
• press the right-arrow and shift keys to extend the selection with the character at the right (or to remove a character from a previous extension at the left)
• press the right-arrow and shift and option keys to extend the selection with the word at the right (or to remove a word from a previous extension at the left)
• press the up-arrow key to move the caret to the start of the text
• press the up-arrow and shift keys to select the text from the start of the text up to the end of the former selection
• press the down-arrow key to move the caret to the end of the text
• press the down-arrow and shift keys to select the text from the start of the former selection to the end of the text
• press the backspace key to remove the selection from the text
• press the forward delete key to remove the selection from the text
• press the return, tab and enter key to conclude the edit box, accepting the changes
• press the escape key to conclude the edit box, canceling the changes
• enter characters to insert them, replacing the selection
• click the mouse to place a caret at the nearest character position
• click the mouse holding the shift key to extend the selection to the nearest character position
• click and drag the mouse to dynamically select text
• double-click the mouse to select a word
• double-click and drag the mouse to dynamically select text, starting with a word
• triple-click the mouse to select a whole line of text
• perform an edit-cut to remove the selection from the text, moving it to the clipboard
• perform an edit-copy to copy the selection from the text to the clipboard
• perform an edit-paste to copy the clipboard (if any) to the text, replacing the selection
• perform an edit-clear to remove the selection from the text
• perform an edit-undo to cancel the last editing operation
• perform an edit-redo to redo the last editing operation

The edit box automatically grows and shrinks with the size of the text. If it can not grow, as it has reached the visible edges of the drawing, the text inside the edit box automatically scrolls.

The string edit box has the same position and rotation angle as the text in the drawing.

3 Concepts

Elementary mathematics

• Coordinates
• Angle
• Goniometry
• Linear transformation matrix

Base elements of a drawing

• ID
• Layer
• Sublayer
• Block
• Object
• Scope

Area attributes

• Unit and scale
• Drawing plane
• Mode
• Cursor
• Area prefs

Object attributes

• Color
• Fill
• Linewidth
• Linetype
• Marking
• Font
• Hatch
• Metrics
• Bounds
• Locking

Application data

• Keys
• Key masks
• Arrays

Transforms

• Translate
• Scale
• Mirror
• Rotate
• Shear
• Transform
• Lengthen
• Stretch
• Flip
• Align

3.1 Coordinates

Unlike 4D Draw, 4D CAD follows mathematical conventions for coordinates

• positive X-coordinates extend to the right (the positive X-axis)
• negative X-coordinates extend to the left (the negative X-axis)
• positive Y-coordinates extend to the top (the positive Y-axis)
• negative Y-coordinates extend to the bottom (the negative Y-axis).

4D CAD is two-dimensional (there are no 3D features).

Coordinates are 64-bit floating-point values, see Unit and scale.

This manual uses the . for decimal fractions The notation for a point with X-coordinate 1.23 and Y-coordinate −4.56 is (1.23,−4.56).

Methods
CADDistanceXY.

3.2 Angle

Unlike 4D Draw, 4D CAD follows mathematical conventions for angles

• positive angles turn counter-clockwise
• negative angles turn clockwise
• angles are measured from the positive X-axis.

In 4D CAD, angles are always given in degrees, never in radians. The range is 0 to 360 or −180 to 180.

Methods
CADRotateXY.

3.3 Goniometry

(under construction)

Methods
CADSin, CADCos, CADArcSin, CADArcCos, CADArcTan2.

3.4 Linear transformation matrix

A linear transformation matrix is a mathematical tool for describing linear transformations

• Translate
• Scale
• Mirror
• Rotate
• Shear.

Any sequence of these operations in a 2-dimensional plane can be described by one linear transformation matrix of 6 parameters. It can do the following

• Transform a square into a square, a rotated square, a rectangle, a rotated rectangle, a rhomb, a rotated rhomb, a parallellogram or a rotated parallellogram
• Transform a circle into a circle, a rotated circle, an ellipse or a rotated ellipse
• Transform parallel lines into parallel lines.

Because parallel lines stay parallel, a linear transformation matrix can describe a 3D isometric projection, but not a 3D perspective projection.

The transformation of a triangle into another triangle uniquely identifies a linear transformation matrix (CADCalcMatrix).

Applying a linear transformation matrix with CADTransform is generally more efficient than a succession of singular operations (CADTranslate, CADScale, CADMirror, CADRotate and CADShear).

Objects of type Block insert and Raster image have a linear transformation matrix attached

• because linear transformation matrices are generally very efficient
• because linear transforms on those objects will not touch their original content.

The matrix that doesn’t change anything is called the identity matrix (CADIdentityMatrix). A matrix that describes one sequence of the operations scale, rotate and translate (in that order) is called a standard matrix (CADStandardMatrix). A matrix that undoes the effect of another matrix is called an inverse matrix (CADInvertMatrix).

Applying one matrix transformation on another is called a matrix multiplication (CADTransformMatrix). The term multiplication is somewhat misleading. When multiplying two numbers, the order of the two numbers is not important. But when multiplying two matrices the order is important.

Methods
CADIdentityMatrix, CADStandardMatrix, CADTranslateMatrix, CADRotateMatrix, CADScaleMatrix, CADMirrorMatrix, CADShearMatrix, CADTransformMatrix, CADFlipMatrix, CADStretchMatrix, CADInvertMatrix, CADCalcMatrix, CADGetMatrixPlane.

3.5 ID

An ID is a number (of type longint) that uniquely identifies an element of a drawing.

3.6 Layer

Layers are like transparent sheets laying op top of each other, with objects glued to them.

The layer order determines the drawing order of the objects, although there is a second drawing order, that of the objects of each layer. Within a layer, objects can be moved to the front or to the back of the layer. The layer itself can be moved in front of or behind other layers.

The next figure shows a drawing where some of the layers are dimmed. Each layer can be in one of the following modes

• editable (same as selectable)
• visible
• dimmed
• invisible

So, for example, to create the situation in 4D Draw, you would have

• one layer with mode invisible for "hidden objects"
• one layer with mode visible that serves as "background"
• one layer with mode editable on top of it that serves as "foreground".

Of course, 4D CAD gives you more power to work with layers than 4D Draw does. Other attributes of a layer are

• the layer’s ID, a number (of type longint) that uniquely identifies it
• the layer’s name. The name of a layer need not be unique, but there is a special case. When pasting objects from other areas, the layer’s name and its unmasked keys, identify the layer, see Copy and paste and Keys
• the layer’s transparency flag. A transparent layer automaticaly shows all solid and background object fills as if they were transparent (see Fill)
• the layer’s hatching flag. Objects on a non-hatching layer don’t show hatches (see Hatch)
• the layer’s snapping flag. Objects on a non-snapping layer don’t snap (see Snaps). By default, the layer’s mode determines whether a layer snaps. You can reset the minimum mode where a layer snaps with CADSetSnapPrefs and then maintain the snapping flag of each layer by calling CADSetLayerAttributes This is useful when you want to add invisible snapping points or an invisible snapping grid
• the layer’s keys can be used to further identify the layer, for example to distinguish between user layers and application specific layers, see Keys
• the layer’s sublayers, see Sublayer
• whether it is the Current layer or not.

A layer ID passed as a Scope ID, describes all objects on the layer.

Methods
CADAddLayer, CADRemoveLayer, CADGetLayers, CADGetLayerAttributes, CADSetLayerAttributes, CADGetLayerKey, CADSetLayerKey, CADGetLayerOrder, CADSetLayerOrder, CADGetCurrentLayer, CADSetCurrentLayer, CADGetSnapPrefs, CADSetSnapPrefs.

3.7 Sublayer

Sublayers are a further subdivision of layers (see Layer), but there are some differences

• there is no sublayer ordering or drawing order linked to sublayers
• even if a layer has sublayers, an object can be on none of the sublayers, just on the parent layer itself (kCADNotOnSubLayerID).

Sublayers are automatically created when importing DXF files. A sublayer can be the Current layer.

When a sublayer and its parent layer have different attribute values, the weakest value wins. For example, when the layer is dimmed and the sublayer is visible, any object on the sublayer will still be dimmed.

A sublayer ID passed as a Scope ID, describes all objects on the sublayer.

Methods
CADAddSubLayer, CADRemoveLayer, CADGetSubLayers, CADGetLayerAttributes, CADSetLayerAttributes, CADGetLayerKey, CADSetLayerKey, CADGetCurrentLayer, CADSetCurrentLayer, CADGetSnapPrefs, CADSetSnapPrefs.

3.8 Block

Blocks are like mini drawings. The figure shows a block, inserted at two different places in the drawing.

Inserting a block does not copy the objects of the block. A reference to the block is created in the form of a block insertion object. The block insertion object (or Block insert for short) has a number of attributes

• a reference to the block that it inserts. If there are any changes in the block, all insertion objects that reference the block will change with it
• a Linear transformation matrix that describes a possible translation, rotation, scaling, mirroring, shear or combination of those operations. In the figure, one of the block inserts is mirrored and both inserts are translated, but still they are insertions of the same block
• an insert line color. The default value is kCADColorUncolored, which retains individual line colors. Setting it to another color, recursively overrules line colors of objects in the block
• an insert fill color. The default value is kCADColorUncolored, which retains individual fill colors. Setting it to another color, recursively overrules fill colors of objects in the block
• a layer. The insertion object is placed on a layer and individual objects of the blocks are also placed on layers. When these layers have different attribute values, the weakest value wins. For example, when the block insert’s layer is dimmed, all objects in the placed block will also be dimmed, unless a block object is put on an invisible layer (and therefore invisible in each insertion).

A block can be inserted not only in a drawing but also in another block. DemoCAD lets you edit blocks recursively with option double-click, the code is worth studying.

In fact, there is little difference between a block and the true drawing, except that the true drawing has a drawing plane attached and is immediately visible. The true drawing can be considered the root block in the drawing’s block hierarchy and for programming purposes the true drawing is considered a block with a special block ID assigned, kCADRootBlockID.

A block has the following attributes

• the block’s ID, a number (of type longint) that uniquely identifies it
• the block’s name. The name of a block need not be unique. When pasting objects from other areas, not only the block’s name, attributes and unmasked keys identify the block, but also its content in the form of objects
• the block’s DXF flag, kCADTrue if the block was imported from a DXF file, kCADFalse if not (see Importing DXF files)
• the block’s DXF dimension flag, kCADTrue if the block is a dimension in the DXF file from which it was imported (see Importing DXF files)
• the block’s keys can be used to further identify the block, for example to distinguish between user blocks and application specific blocks, see Keys.

Methods
CADAddBlock, CADRemoveBlock, CADGetBlocks, CADGetBlockInfo, CADSetBlockName, CADGetBlockKey, CADSetBlockKey, CADAddInsertXY, CADAddInsert, CADObjInsert, CADGetInsertID, CADGetInsert, CADGetInsertXY, CADSetInsertID, CADSetInsert, CADSetInsertXY, CADGetInsertColor, CADSetInsertColor, CADClear.

3.9 Object

• Line
• Polyline
• Square
• Rectangle
• Circle
• Circle arc
• Ellipse
• Ellipse arc
• String
• Raster image
• Block insert

3.9.1 Line

(under construction)

3.9.2 Polyline

(under construction)

3.9.3 Square

(under construction)

3.9.4 Rectangle

(under construction)

3.9.5 Circle

(under construction)

3.9.6 Circle arc

(under construction)

3.9.7 Ellipse

(under construction)

3.9.8 Ellipse arc

(under construction)

3.9.9 String

(under construction)

3.9.10 Raster image

(under construction)

3.9.11 Block insert

(under construction)

Also see Block.

3.10 Scope

An object scope describes a set of objects. It can have different forms:

• An Object ID can be used as a scope that consists of one object
• A Layer ID can be used as a scope that consists of all objects on a layer
• A Sublayer ID can be used as a scope that consists of all objects on a sublayer
• kCADScopeSelectedObjects describes all objects currently selected by the user
• kCADScopeObjOnEditableLayers describes all objects currently editable (selectable) by the user
• kCADScopeAllObjects describes all objects
• CADAddScope creates a programmer scope.

4D CAD differentiates between the various IDs, so you can pass any of the above values as a scope ID. The method CADTypeOfScope returns which kind of scope an ID is.

4D CAD methods that expect an object ID operate on a single object, those that expect a scope ID operate on a number of objects (0 or more). Letting 4D CAD operate on a scope is faster and more convenient than working with single objects in a loop (Iterating object scopes).

A target object scope is a scope that a method will change. It can be kCADScopeSelectedObjects or a programmer scope. By passing a programmer scope, you can manipulate objects while leaving the current user selection of objects intact. This is a fundamental programming concept, not found in 4D Draw.

Call CADRemoveScope when you are finished using a programmer scope. CADRemoveBlock removes all programmer scopes attached to the block. CADClear removes all programmer scopes in an area. All other scopes are maintained automatically by 4D CAD.

Scopes change when you remove objects from it (CADFromScope), add objects to it (CADToScope) or apply logical operations on it like addition, negation and intersection (CADScopeLogic).

Be aware that object scopes can change automatically as a result of user operations or as a side effect of methods being called:

• User operations affect kCADScopeSelectedObjects and possibly other scopes
• Adding objects affects layer scopes, sublayer scopes and kCADScopeAllObjects
• Removing objects affects all scopes, including programmer scopes
• Changing an object’s layer or sublayer affects layer and sublayer scopes. It may also affect kCADScopeSelectedObjects and kCADScopeSelectedObjects (as in next item)
• Changing a layer or sublayer mode will affect kCADScopeSelectedObjects and kCADScopeSelectedObjects if the object’s new layer or sublayer has a more restricted Layer mode. This side effect can lead to interesting programming errors.

By intercepting certain Events, you can manipulate the object scope the user operates on.

Important
An object scope describes objects in a block or in the root drawing. It can not enclose objects in several blocks.

Methods
CADAddScope, CADRemoveScope, CADGetScopeIDs, CADTypeOfScope, CADCount, CADGetObjIDsArray, CADOneObjID, CADGetObjID, CADEmptyScope, CADCopyScope, CADToScope, CADFromScope, CADInScope, CADScopeLogic.

3.11 Unit and scale

The current unit of a drawing is shown in the Zoom info bar. Default it is in mm, but you can change it by calling CADSetUnit. Setting the unit doesn’t scale current objects. Measure pane edit boxes can have their own unit, see Measure pane.

In 4D CAD, there is no arcane scaling system as in 4D Draw. There is one unit, that represents real world values in the drawing. The drawing is scaled in order to print it on a specific scale or at a given paper size. Setting the print scale doesn’t affect object metrics, as all metric values are specified and stored in real world values.

Linked to the print scale are three other scales

• Linetype scale
• Marking scale
• Hatch scale.

These scales allow you to make fine adjustments to the appearence of linetypes, markings and hatches, both on paper and on the screen. Their initial value is equal to the print scale (default 1:50).

To set the print scale, call CADSetScale. To calculate the scale for a given paper size, call CADGetPaperSizes. Fine adjustment can be made with CADSetPrintSpecs.

Methods
CADGetUnit, CADSetUnit, CADPageSetup, CADGetPaperSizes, CADGetScale, CADSetScale, CADGetPrintSpecs, CADSetPrintSpecs.

3.12 Drawing plane

The drawing plane is the size of the drawing, specified in real world coordinates, and given in the area’s unit (see Unit and scale).

Default, the drawing plane is 56 meters wide and 40 meters high. At the default print scale of 1:50, it will print on A0 paper. However, you can set the drawing plane’s boundary coordinates to any 64-bit floating point value (which is large enough for a drawing of the universe in mm).

4D CAD has an auto-resize feature. If objects move outside the drawing plane, the bounds of the drawing plane are automatically extended. This is true for user actions as well as for 4D CAD methods being called.

Methods
CADGetDrawSize, CADSetDrawSize.

3.13 Mode

Area modes have been discussed in the Mode palette section of the User reference chapter.

Methods
CADGetMode, CADSetMode.

3.14 Cursor

(under construction)

3.15 Area prefs

For an overview of area preferences, see the Thematical method index.

3.16 Color

(under construction)

3.17 Fill

(under construction)

3.18 Linewidth

(under construction)

3.19 Linetype

(under construction)

3.20 Marking

(under construction)

3.21 Font

(under construction)

3.22 Hatch

(under construction)

Also see CAD hatch ID constants

3.23 Metrics

(under construction)

3.24 Bounds

(under construction)

3.25 Locking

(under construction)

3.26 Keys

(under construction)

3.27 Key masks

(under construction)

3.28 Arrays

(under construction)

3.29 Translate

(under construction)

3.30 Scale

(under construction)

3.31 Mirror

(under construction)

3.32 Rotate

(under construction)

3.33 Shear

(under construction)

3.34 Transform

(under construction)

3.35 Lengthen

(under construction)

3.36 Stretch

(under construction)

3.37 Flip

(under construction)

3.38 Align

(under construction)

4 Programming tasks

Thematical method index

• Thematical method index

Programming style

• Parameter passing
• Error handling

Event control

• Event handling
• Undo handling
• Copy and paste control

Special programming tasks

• Storing and loading drawings
• Importing DXF files
• Importing raster images
• Handling raster image resolutions
• Handling redraws
• Handling 4D form pages and scrollbars
• Specifying drawing orders
• Iterating object scopes
• Converting from 4D Draw
• Displaying 4D CAD drawings in other plug-ins

4.1 Thematical method index

Drawings

• Identifying areas and drawings: CADGetRef , CADSetRef , CADRefFromFile , CADRefFromBlob , CADRefFromPict .
• Storing and loading drawings: CADGetCADFile , CADPutCADFile , CADLoadFromFile , CADLoadFromBlob , CADLoadFromPict , CADLoadFromRes , CADStoreToFile , CADStoreToBlob , CADStoreToPict , CADFileToBlob , CADBlobToFile , CADFileToPict , CADPictToFile , CADPictToBlob .
• Extending drawings with custom data: CADAddArray , CADRemoveArray , CADGetArray , CADSetArray , CADGetArrayIDs .

Imports

• Importing DXF files: CADGetDXFFile , CADImportDXF , CADAcceptDXF , CADCancelDXF .
• Importing raster images: CADGetImageFile , CADGetImageFileInfo , CADGetImageInfo , CADImportImage .

Exporting

• Exporting raster images: CADToPixels .

4D CAD areas

• 4D CAD areas: %CAD , %CADView , %CADBackground .
• Specifying drawing sizes: CADGetDrawSize , CADSetDrawSize .
• Setting area looks: CADGetDisplay , CADSetDisplay , CADGetTitleSplit , CADSetTitleSplit .
• Zooming and scrolling: CADScroll , CADScrollTo , CADGetScroll , CADZoom , CADAutoZoom , CADGetZoom .
• Handling areas: CADLastArea , CADClear , CADNewOffscreen , CADEndOffscreen .
• Setting area properties: CADGetBackColor , CADSetBackColor , CADGetScale , CADSetScale , CADGetUnit , CADSetUnit .
• Getting linetype definitions: CADGetLineTypeIDs , CADGetLineTypeDefinition .
• Setting area preferences: CADGetZoomPrefs , CADSetZoomPrefs , CADGetSnapPrefs , CADSetSnapPrefs , CADGetDragPrefs , CADSetDragPrefs , CADGetDimPrefs , CADSetDimPrefs , CADGetDrawPrefs , CADSetDrawPrefs , CADGetAreaPrefs , CADSetAreaPrefs , CADGetMouseWheelPrefs , CADSetMouseWheelPrefs .
• Managing measure panes: CADGetMeasurePrefs , CADSetMeasurePrefs .
• Setting default properties of user-drawn objects: CADGetDefaults , CADSetDefaults .
• Setting modes: CADGetMode , CADSetMode .

Redraws and 4D forms

• Managing redraws: CADGetRedraw , CADSetRedraw , CADRedrawArea .
• Struggling with pages on 4D forms: CADGotoPage .

Commands, events, errors and undos

• Executing commands: CADCommand .
• Intercepting events: CADGetOnEvent , CADSetOnEvent , CADOnEvent .
• Intercepting errors: CADGetOnError , CADSetOnError , CADOnError .
• Handling undos: CADGetUndoPrefs , CADSetUndoPrefs , CADTriggerUndo , CADResetUndo .

Printing

• Setting printing prefs: CADGetPrintSpecs , CADSetPrintSpecs .
• Specifying a clip box: CADGetClipBox , CADSetClipBox .
• Handling page setup: CADPageSetup , CADCopyPageSetup , CADGetPaperSizes .
• Printing: CADPrint , CADPrintToPDF .

Layers

• Working with layers: CADAddLayer , CADAddSubLayer , CADRemoveLayer , CADGetLayers , CADGetSubLayers .
• Setting layer attributes: CADGetLayerAttributes , CADSetLayerAttributes , CADGetLayerKey , CADSetLayerKey .
• Specifying layer drawing order: CADGetLayerOrder , CADSetLayerOrder .
• Handling the current layer: CADGetCurrentLayer , CADSetCurrentLayer .

Blocks

• Working with blocks: CADAddBlock , CADRemoveBlock , CADGetBlocks .
• Setting block attributes: CADGetBlockInfo , CADSetBlockName , CADGetBlockKey , CADSetBlockKey .

Scopes

• Working with programmer scopes: CADAddScope , CADRemoveScope , CADEmptyScope , CADGetScopeIDs , CADCopyScope .
• Specifying the objects in a scope: CADToScope , CADFromScope , CADInScope , CADScopeLogic .
• Selecting objects: CADSelect .
• Getting information about a scope: CADCount , CADTypeOfScope .
• Getting the objects in a scope: CADGetObjIDsArray , CADOneObjID , CADGetObjID .

Colors & color palette areas

• Color palette area: %CADColors .
• Managing color palette areas: CADGetColorItem , CADSetColorItem , CADGetItemColor , CADSetItemColor , CADGetColorsDim , CADSetColorsDim .
• Matching colors with the 4D CAD color palette: CADIndexToColor , CADColorToIndex .
• Matching colors with RGB values: CADRGBToColor , CADColorToRGB .
• Matching colors with the DXF color palette: CADDXFToColor , CADColorToDXF .
• Getting background colors: CADGetSysBackColor .
• Blending colors and objects into a background: CADBlendColor , CADBlend .

Objects

• Getting general object information: CADGetObjType , CADGetObjInfo , CADFindByType .
• Managing object keys: CADGetKey , CADSetKey , CADGetObjKey , CADSetObjKey , CADGetKeyArray , CADSetKeyArray , CADFindByKey .
• Managing object locks: CADGetLock , CADSetLock , CADGetObjLock , CADSetObjLock , CADFindByLock .
• Specifying object layers: CADGetLayer , CADSetLayer .
• Specifying object drawing order within a layer: CADMoveToFront , CADMoveToBack .
• Adding objects: CADAddLine , CADAddSquare , CADAddRectangle , CADAddPolyLine , CADAddCircle , CADAddCircleArc , CADAddEllipse , CADAddEllipseArc , CADAddString , CADAddInsertXY , CADAddImage , CADAddInsert .
• Getting object-specific information: CADObjLine , CADObjSquare , CADObjRectangle , CADObjPolyLine , CADObjCircle , CADObjCircleArc , CADObjEllipse , CADObjEllipseArc , CADObjString , CADObjImage , CADObjInsert .
• Getting metrical object data: CADGetLine , CADGetSquare , CADGetRectangle , CADGetPolyLine , CADGetCircle , CADGetCircleArc , CADGetEllipse , CADGetEllipseArc , CADGetString , CADGetStringXY , CADGetImage , CADGetImageXY , CADGetInsertID , CADGetInsert , CADGetInsertXY .
• Setting metrical object data: CADSetLine , CADSetSquare , CADSetRectangle , CADSetPolyLine , CADSetCircle , CADSetCircleArc , CADSetEllipse , CADSetEllipseArc , CADSetString , CADSetStringXY , CADSetImage , CADSetImageXY , CADSetInsertID , CADSetInsert , CADSetInsertXY .
• Specifying application specific polyline angles: CADGetPolyAngle , CADSetPolyAngle .
• Removing objects: CADRemoveObj .

Object attributes

• Setting object fills: CADGetFill , CADSetFill .
• Setting object colors: CADGetColor , CADSetColor , CADGetInsertColor , CADSetInsertColor .
• Setting object linewidths: CADGetLineWidth , CADSetLineWidth .
• Setting object linetypes: CADGetLineType , CADSetLineType .
• Setting object markings: CADGetMarking , CADSetMarking .
• Setting object hatches: CADGetHatch , CADSetHatch .
• Setting object fonts: CADGetFont , CADSetFont .

Object metrics

• Getting object bounds: CADBounds , CADPolyBounds , CADStringBounds , CADObjBox .
• Getting the rotation center: CADObjCenter , CADPolyCalc .
• Getting metrical data: CADObjSurface , CADObjPerimeter , CADMetrics , CADMetricsByMatrix .
• Manipulating polylines: CADPolyUndouble , CADSplitPoly , CADSplitPolyXY .
• Working with raster image resolutions: CADCalcImageResolution , CADCalcImageMatrix .
• Snaps and crossings: CADGetBlockAddedSnaps , CADSetBlockAddedSnaps CADGetBlockSnapMask , CADSetBlockSnapMask , CADFindSnap , CADFindCrossings .
• Exporting hatches: CADHatchToLine .

Move, copy & compare

• Specifying the key mask: CADGetKeyMask , CADSetKeyMask .
• Moving and copying objects: CADMoveTo , CADCopyTo , CADCopyObjTo , CADMoveByMatrix , CADCopyByMatrix , CADCopyObjByMatrix .
• Copying areas: CADCopyLayers , CADCopyAttributes , CADCopyBlocks , CADCopyArrays .
• Comparing objects and blocks: CADCompareBlock , CADCompareObj .

Mathematics

• Calculating basic goniometry: CADSin , CADCos , CADArcSin , CADArcCos , CADArcTan2 .
• Calculating basic geometry: CADDistanceXY , CADRotateXY , CADScaleXY , CADTransformXY .
• Applying decimal operations on floating point values: CADDecimalSum , CADDecimalDifference .
• Calculating with points: CADPointOnLine , CADPointInRect , CADPointInPoly .
• Calculating crossings and intersections: CADRectAndRect , CADLineAndRect , CADLineAndLine , CADLineAndArc , CADArcAndArc , CADCheckPoly , CADPolyAndPoly .

Linear transformation matrices

• Getting standard matrices: CADIdentityMatrix , CADStandardMatrix .
• Transforming matrices: CADTranslateMatrix , CADRotateMatrix , CADScaleMatrix , CADMirrorMatrix , CADShearMatrix , CADTransformMatrix , CADFlipMatrix , CADStretchMatrix , CADInvertMatrix .
• Calculating matrices from points: CADCalcMatrix .
• Getting matrix information: CADGetMatrixPlane .

Transform & align

• Transforming objects xy-oriented: CADTranslate , CADRotate , CADScale , CADMirror , CADShear , CADTransform .
• Transforming objects object-oriented: CADRotateObj , CADStretchObj , CADLengthenObj , CADFlipObj .
• Aligning objects: CADAlign .

Demos

• Drawing spirographs: CADSpirograph .

Version info

• Getting version info: CADGetVersion .

4.2 Parameter passing

(under construction)

4.3 Error handling

(under construction)

Also see the list of Error result codes.

4.4 Event handling

(under construction)

Also see the chapter on Events.

4.5 Undo handling

Methods that call CADResetUndo internally. They always clear undo data.

CADAcceptDXF
CADCancelDXF
CADClear
CADCommand (except for command kCADCommandEditSelectAll)
CADImportDXF
CADLoadFromBlob
CADLoadFromFile
CADLoadFromPict
CADResetUndo

Methods that call CADAutoResetUndo internally. They clear undo data if theAutoResetUndoFlag of the area is kCADTrue (see CADGetUndoPrefs and CADSetUndoPrefs).

CADAddBlock
CADAddCircle
CADAddCircleArc
CADAddEllipse
CADAddEllipseArc
CADAddImage
CADAddInsert
CADAddInsertXY
CADAddLayer
CADAddLine
CADAddPolyLine
CADAddRectangle
CADAddSquare
CADAddString
CADAddSubLayer
CADAlign
CADBlend
CADCopyArrays (target)
CADCopyAttributes (target)
CADCopyBlocks (target)
CADCopyByMatrix (target)
CADCopyLayers (target)
CADCopyObjByMatrix (target)
CADCopyObjTo (target)
CADCopyTo (target)
CADFlipObj
CADImportImage
CADLengthenObj
CADMirror
CADMoveByMatrix (source and target)
CADMoveTo (source and target)
CADMoveToBack
CADMoveToFront
CADPageSetup
CADPolyUndouble
CADPrint
CADPrintToPDF
CADRemoveArray
CADRemoveBlock
CADRemoveLayer
CADRemoveObj
CADRotateObj
CADRotate
CADScale
CADSetBlockName
CADSetCircleArc
CADSetCircle
CADSetClipBox
CADSetColor
CADSetDrawSize
CADSetEllipseArc
CADSetEllipse
CADSetFill
CADSetFont
CADSetHatch
CADSetImage
CADSetImageXY
CADSetInsertColor
CADSetInsert
CADSetInsertID
CADSetInsertXY
CADSetKeyMask
CADSetLayer
CADSetLayerAttributes
CADSetLine
CADSetLineType
CADSetLineWidth
CADSetLock
CADSetMarking
CADSetObjLock
CADSetPolyAngle
CADSetPolyLine
CADSetPrintSpecs
CADSetRectangle
CADSetScale
CADSetSquare
CADSetString
CADSetStringXY
CADSetUnit
CADShear
CADSplitPoly
CADStretchObj
CADTransform
CADTranslate