DToolsX-DWG. Version: An ActiveX DLL To Retrieve DWG/DXF information. DToolsX-DWG REFERENCE MANUAL

Transcription

1 DToolsX-DWG Version: 2007 An ActiveX DLL To Retrieve DWG/DXF information DToolsX-DWG REFERENCE MANUAL (C)opyright CADology Limited, UK

2 License Agreement CADology LIMITED (UK) designed and provides this computer OLE control - ActiveX (DToolsX) and documentation as is and licenses its use. The user assumes responsibility for the choice of this program to achieve its intended results, and for the installation, use and results achieved. DToolsX is not, nor has ever been, public domain or free computer software. This software may only be distributed with a valid distribution license; this license is obtained on an annual basis from CADology. However, the user may distribute this software with their application as long as the user is a valid Sustaining or Founder member of the Open Design Alliance. Limited Warranty: DToolsX is provided without warranty of any kind. The complete risk as to the results produced by this program is assumed by purchaser/user. If the program becomes defective, the purchaser/user assumes the complete cost of all associated damages. CADology Limited shall have no responsibility or liability to any person or company. The Governing Law The Governing law of this Agreement shall be that of England, UK. Acknowledgements AutoCAD, AutoCAD 2007, AutoCAD 2006, AutoCAD 2005, AutoCAD 2004, AutoCAD 2002, AutoLISP, DWG and DXF are trademarks of Autodesk, Inc. Windows 95, Windows 98, Windows ME, Window NT, Windows 2000 and Windows XP are trademarks of Microsoft, Inc. 2

3 Contents License Agreement...2 Contents...3 Introduction...5 Installing DToolsX...6 Distributing DToolsX with your Application...8 Control Registration...8 DToolsX Hints and Tips...9 (1) Unlock Code...9 (2) String/Char Declaration Size...9 Open and Close a drawing file...9 Enumerations...9 Adding DToolsX to be a Custom Control (VB6)...10 DToolsX with Visual C/C DToolsX Classes...13 dtxdrawing...13 dtxdrawing Class...14 Overview...14 Member Properties...14 dtxerrormessage...14 Member Methods...14 LoadDrawing...14 CloseDrawing...15 AttributeUpdateByHandle...15 CreateDXF...15 DeleteObject...16 DToolsXVersion...16 DToolsXVersionToProperties...16 DWGVersionFilename...16 RecoverDrawing...17 SaveDrawing...17 SetImagePath...18 SetLayerState...18 SetXrefPath...18 TextUpdateByHandle...19 UnlockProduct...19 XMLReport...20 XrefAttach...21 XrefBind...21 Error and Warning Strings

4 Error strings...22 Warning strings...22 XML Definition...23 Wanted : New Methods and Properties...27 Technical Support

5 Introduction Welcome to DToolsX-DWG, DToolsX-DWG is a Windows ActiveX DLL which allows the user to place a reference control into other Window software programs so that AutoCAD DWG/DXF information inside the DWG/DXF can be retrieved. DToolsX is available in two versions:- DToolsX-DWG, retrieval of AutoCAD drawing data in XML format. DToolsX has been designed to work with Windows NT 4.0, Windows 2000 and Windows XP. And there is a version of DToolsX for MicroStation Design files to, this is known as DToolsX-DGN and will work with both V7 and V8 Design files. 5

6 Installing DToolsX Minimum Configuration DToolsX ActiveX DLL requires Windows 2000 or Windows XP with the latest Service Packs, although it should work with older versions of Microsoft Windows NT 4.0, Windows 98 SE2 and ME. Installing DToolsX Software(all versions) DToolsX has been designed to have minimal files and is developed using Microsoft Visual Studio 2005, these are: DToolsXDWG.DLL CADology MSVCR80.DLL ( ) - Microsoft MSVCRT.DLL ( ) - Microsoft MSVCP80.DLL ( ) - Microsoft Some which you may already have on your system. From the distribution media, please copy DToolsXDWG.dll to a directory of your choice. If you not have the other DLL already present in the SYSTEM directory of your Windows operating system, just copy the DLL files to the Windows system directory. Once the DLL files are present on your computer, you will need to Register DToolsX. See the next paragraph. Registering the Custom Control To register the DToolsX control on your system, you need a program that comes with the Windows OS called REGSVR32.exe. To run this program, enter the console (or MS-DOS) prompt, change directory to the DToolsX directory, and key in: C:\DToolsXDev\: REGSVR32 DToolsXDWG.dll Your operating system will respond that the control has been registered. 6

7 If the DToolsXDWG.dll can not be registered, please contact CADology. Updating to a newer version of DToolsX To update to a newer version of DToolsX, you must first UN- REGISTER the control using the REGSVR32 program or by any other route you know. C:\DToolsXDev\: REGSVR32 /U DToolsXDWG.dll A dialog message box will confirm if the control has been successfully unloaded. Important: It is also wise to remove the DToolsX component from your development project and re-import DToolsX otherwise some errors may appear. 7

8 Distributing DToolsX with your Application You may only distribute this software with your application only if you have purchased the annual distribution license. This is included in the first year but after 1 year from purchase you are obliged to purchase the license to distribute. DToolsX requires the following files and they must be included in your install routine when your application is ready, these files can be found on your Development computer. The following system support files are to be placed in the application directory and not in the System/System32 directory: MSVCR80.DLL Microsoft C runtime MSVCP80.DLL Microsoft C runtime MSVCRT.DLL Microsoft C runtime Important: When written your installation program, please read the Microsoft Knowledge Base Article titled Redistribution of the Shared C Runtime Components in Visual C++.NET The following files can be placed in a sub-directory of your application: DToolsXDWG.DLL ActiveX DLL Control Registration Don t forget, DToolsX will need to be registered. This can be done in the installation program of your application, your application itself or manually by the user. DToolsX is a self-registering ActiveX control as it supports self-registration by implementing the DllRegisterServer and DllUnregisterServer functions. 8

9 DToolsX Hints and Tips The following is a list of notes and hints that maybe helpful as a user of DToolsX. (1) Unlock Code IMPORTANT: DToolsX will be restricted unless the product is unlocked. Once you have purchased DToolsX, you will be given a unlock code, this code must be assigned in the programming source code before a drawing is opened. Please do not given this unlock code to persons outside of your company. Please read the unlockproduct method in the dtxdrawing class. (2) String/Char Declaration Size In the DWG/DXF file format, most string definitions can be up to 512 bytes long, so make sure your declaration handle this length. The following steps are required to get DToolsX going. Dim dtoolsx As New dtxdrawing Create new object Dim hdwg As Long Need a handle to drawing dtoolsx.unlockproduct = xxxxxx dtoolsx.loaddrawing hdwg, C:\myDrawing.dwg {Other code goes here} dtoolsx.closedrawing hdwg Open and Close a drawing file Enumerations To assist in the options for some of parameters when calling Methods, the following Enumerations have been created. 9

10 None have been defined in DTools-DWG yet. Adding DToolsX to be a Custom Control (VB6) From a new project in Visual Basic, select the Project menu bar option, then move down the menu bar option s to References. And click. A dialog box will appear listing all reference components, check the box for DToolsX and click the OK button. 10

11 DToolsX with Visual C/C++ As DToolsX is an ActiveX DLL, information about the interface must be obtained by the compiler. This is performed by using the #import option at the top of your source file. I.e. #import <DToolsXDWG.dll> no_namespace The following C code will start the OLE interface, get an instance on the ActiveX DLL DToolsX and the class we are interested in, and then it will call a method in the class. #include "stdafx.h" // Get Visual C to understand the interface and create some PTR's #import <\code\dtoolsx\releasemindependency\dtoolsxdwg.dll> no_namespace int main(int argc, char* argv[]) { OleInitialize (NULL); // Nested as needs to be destroyed before OLE is uninitialised. { // Create the smart pointer to our object. IdtxDrawingPtr DToolsPtr; // Create our object? if (SUCCEEDED ( DToolsPtr.CreateInstance ( "DToolsXDWG.dtxDrawing.1" ) ) ) { try { int hdwg = 0; DToolsPtr->LoadDrawing ( &hdwg, "c:\\db2000.dwg" ); if ( hdwg!= 0 ) { // Opened drawing so we create a DXF file DToolsPtr->CreateDXF( hdwg, "C:\\TMP.DXF", (AutoCADDXFTypes)DXFASCII, 6 ); DToolsPtr->CloseDrawing ( hdwg ); } else { printf( "Drawing could not be opened\n " ); } } 11

12 catch (...) { printf ("DToolsX Error: Failed to call function!\n"); } } else { printf ("DToolsX Error: Failed to create instance!\n"); } } OleUninitialize (); return 0; } A drawing file is opened and then a DXF is created from it. 12

13 DToolsX Classes DToolsX has been divided into a series of classes; these classes can be seen by looking at the Object Browser that comes with your software development environment. These classes are listed below and a full reference follows in this documentation. In the detailed description of the parameters for the methods, a parameter that is passed to the method where the value is just used is coloured Green. And, parameter coloured Red means that this variable will be set by DToolsX for your application to act upon afterwards. dtxdrawing This class define access to the drawing file to retrieve information about the drawing files. This is the main class and is used to load the drawing file into DToolsX. Once loaded, the other classes can be used to retrieve information with respect to certain areas in the drawing file. 13

14 dtxdrawing Class Overview This is the main class and is used to load the drawing files into the DToolsX environment, no other classes will work unless a drawing file has been open into the CdtxDrawing class. Member Properties dtxerrormessage This is a read only character string value that is used to check if the method call was successful. If the method call was successful, then 1000:Ok will be returned other the error string can be seen. Member Methods LoadDrawing [form.]control.loaddrawing <DWG handle> <DWG/DXF filename> <DWG password> DWG handle: A handle will be returned of the opened drawing DWG/DXF filename: A filename and path to a drawing file DWG password: A password for the drawing file This is used to open (load) the DWG or DXF filename into the DToolsX component so that information can then be accessed. If the drawing has been loaded successfully than the DWG handle will be assigned to 1, otherwise a 0 if the load has failed. The dtxerrormessage will report why the loading of the drawing has not been successful. It is very important that each opened drawing is called by CloseDrawing. From AutoCAD 2004 drawing files in DWG format a password can be assigned to the file, the password must be passed as a parameter so that DToolsX can open the drawing. 14

15 CloseDrawing [form.]control.closedrawing This must be called when an opened drawing is no longer needed AttributeUpdateByHandle [form.]control.attributeupdatebyhandle <attribute value> <attribute handle> attribute value: New value for attribute entity. Attribute handle: Handle of attribute entity to update. This method allows an attribute entity value to be updated, once the attribute has been update the DWG file can then be saved using the SaveDrawing method. The attribute entity is found by its unique handle, the handle is extracted in the XML so it can be used here to assist in the update. Please make sure the entity handle is valid and it is an Attribute Entity otherwise this updating of the attribute will fail. CreateDXF [form.]control.createdxf <DXF filename> <DXF precision> <DXF version> DXF filename: Filename of the DXF file to be created. DXF precision: 0 to 16 for decimal places in ASCII DXF file. DXF version: Set to the version required for the DXF file. This method will create a DXF based on the drawing that has been loaded using the LoadDrawing() method. The DXF precision must be between 0 and 16. This indicates the number of decimal places that will be output in the DXF file. The DXF version can be set to one of the following: 2004 AutoCAD AutoCAD AutoCAD 2002, AutoCAD AutoCAD Release AutoCAD Release AutoCAD Release AutoCAD Release 10 15

16 DeleteObject [form.]control.deleteobject <Object Handle> Object Handle: Handle of the object(entity). This method deletes an object from the drawing identified by its handle. In most cases you can use this to delete entities but it can also delete objects elsewhere in the drawing. Be careful when using this command as DWG files can be damaged. DToolsXVersion [form.]control.dtoolsxversion <Release> <Major> <Minor> <Build> Release: Release value. Major: Major value. Minor: Minor value. Build: Build value. Being an ActiveX DLL, the file has a version. This can be seen using Windows Explore to view the file properties. The version is broken into four numeric values; these being: Release, Major, Minor and Build. Please also look at the next method which will set properties in the Object Model instead of passing values. DToolsXVersionToProperties [form.]control.dtoolsxversiontoproperties This will set four properties in the DToolsX-DWG object model to the values of the version. These properties are: dtxrelease, dtxmajor, dtxminor and dtxbuild. DWGVersionFilename [form.]control.dwgversionfilename <DWG version> <DWG filename> DWG version: Returns version of DWG file. DWG filename: Filename and path of DWG file. This method will return back the version of the DWG file passed to the method. This method does NOT need to have the drawing loaded using the LoadDrawing() method as it looks at the DWG file directly by reading the first 6 bytes of the DWG file. The DWG version can be one of the following: 2007 AutoCAD

17 2004 AutoCAD 2004, AutoCAD 2005, AutoCAD AutoCAD 2000, AutoCAD 2000i, AutoCAD AutoCAD Release AutoCAD Release AutoCAD Release 12 RecoverDrawing [form.]control.recoverdrawing <DWG filename> <Password> <Num entities> <Num errors> <Num fixes> DWG filename: Filename of the DWG file to be repaired Password: Password of the DWG file, if required Num entities: Returns the number of entities in the DWG file Num errors: Returns number of errors found in the drawing Num fixes: Returns number of fixes for the errors found in the drawing Sometimes the data inside a DWG file can get damaged or corrupt, this method will open a DWG and try to repair any errors it find during the opening of the file. Once this method is called, you can use DToolsX as if you used the LoadDrawing() method. SaveDrawing [form.]control.savedrawing <DWG filename> <DXF version> DWG filename: Filename of the DWG file to be created DWG version: Set to the version required for the DWG file This allows an AutoCAD DWG to be created based on the drawing currently loaded. Most users would use the 1 option that will save the drawing to the same version. The DWG version can be set to one of the following: -1 The version of the drawing loaded 2004 AutoCAD AutoCAD AutoCAD 2000, AutoCAD 2000i, AutoCAD AutoCAD Release AutoCAD Release 12 17

18 SetImagePath [form.]control.setxrefpath <image path> <image handle> image path: This is the new path name of the image including filename image handle: The handle of the image to be changed This method will change the image path for an image entity selected by its handle. The handle is extracted in the XML report. The image path name must include the original file name of the image, so you may only change the path and not the image file name. SetLayerState [form.]control.setlayerstate <layer name> <state> <mode> layer name: This layer which the state needs to be changes state: Required state for the layer mode: Required state for the layer This method will turn layers On/Off or Thaw/Freeze. The mode parameter defines in the On/Off or Thaw/Freeze layer option is changed. The options for the mode parameter are: 1 On / Off 2 Thaw / Freeze The following states are allowed: 1 On / Thaw 3 Off / Freeze To turn off a layer, use SetLayerState( mylayer, 2, 1 ) To freeze a layer, use SetLayerState( mylayer, 2, 2 ) SetXrefPath [form.]control.setxrefpath <xref path> <xref name> xref path: This is the new path name of the xref xref name: The name of the xref to be changed This method will change the path name stored in the drawing for a reference file; the reference file is selected by its name. Note: Path name are not always stored in the drawing file. Some CAD users prefer to assign search paths in the CAD system to look for the 18

19 reference file. This allows the changing of the paths without having to edit each drawing. TextUpdateByHandle [form.]control.textupdatebyhandle <text value> <handle of text entity> Text value: This is the new literal required for the text entity handle of text entity: The handle of the text entity to update the literal value This method will update the text literal (value) of Text and Mtext entities in the drawing, the entities are selected by the handle. The handle is included in the XML report to assist in this process. UnlockProduct [form.]control.unlockproduct <unlock code> unlock code: unlock code provided when software is purchased When using DToolsX, the product must first be enabled to work with no restrictions or nag screens. Therefore, this method must be called with the unlock code that has been assigned to your company upon purchased. If the product has not been unlocked, then DToolsX will still work but only allow drawing files of about 250K and smaller to be loaded and worked upon. This will be confirmed by a nag screen that will be displayed. 19

20 XMLReport [form.]control.xmlreport <XML filename> <Attributes> <Attribute definitions> <References> <Layers> <Layouts> <System variables> <Images> <Text> XML filename: Filename of XML file you would like DToolsX to create. Attributes: Set to 1 to export Attribute data to XML. Attribute definitions: Set to 1 to export Attribute definitions data to XML. References: Set to 1 to export Reference data to XML. Layers: Set to 1 to export Layers and their states to XML. Layouts: Set to 1 to export Layout data to XML. System variables: Set to 1 to export a few important system variables to XML. Images: Set to 1 to export Image entity data to XML. Texts: Set to 1 to export text literals in Text and Mtext entities to XML. This method is used to export data inside the drawing to a XML file passed by the calling application. The XML filename will be deleted and a new data from the drawing will be added. The parameters control which data is exported to the XML file, simply pass a 1 to output the data or 0 if it s not needed in the XML file. Attribute Extraction The XML report is very flexible for getting access to attribute values but there are some key points you will need to know about getting the correct attribute data. In the XML for the INSERT element, there is information that tells us the number of attributes and the number of constant attributes. Constant Attribute values are NOT stored following the INSERT entity and hence will not be found in the XML in the <Attribute> element. If there is a constant attribute you will need to then visit the <AttributeDefinition> part of the XML file to get access to the constant value. The normal attributes will follow in the XML. The user may have used the MINSERT command to place a block with attributes in the drawing, for this case there is the <rows> and <columns> element to inform you of the details. Text Extraction For the text option, both Text and MText entities will have the literals extracted, the MText will have the formatting show. The text values can be updated using the UpdateTextByHandle method. Please contact CADology to have any further or new information added to the XML file. It is thought this will grow by requests from customers. 20

21 XrefAttach [form.]control.xrefattach <xref filename> <block name> <x coord> <y coord> <z coord> <x scale factor> <y scale factor> <z scale factor> Xref filename: Filename with path to the external DWG that is to be attached Block name: The name given to the xref when attached in the opened drawing X coord: The X coordinate of the insertion point of the xref Y coord: The Y coordinate of the insertion point of the xref Z coord: The Z coordinate of the insertion point of the xref X scale factor: The X axis scale factor of the xref Y scale factor: The Y axis scale factor of the xref Z scale factor: The Z axis scale factor of the xref This method will attached an external DWG file as an xref into the currently opened drawing. XrefBind [form.]control.xrefbind <xref name> Xref name: Name of the xref to bind This method will bind an xref selected by the name into the current drawing. 21

22 Error and Warning Strings 1000:Ok 9999:Unknown Error - Contact CADology Error strings 1001:Error trying to open XML file for writing 1002:Error opening DWG file 1003:Drawing not opened in DToolsX-DWG 1004:Unknown DWG version type 1005:Handle not found in drawing 1006:Handle is not a Attribute Entity 1007:Reference name not found in drawing 1008:Handle does not point to an Image entity 1009:Layer name not found in drawing 1010:Layer state parameter not understood 1011:Layer mode parameter not understood 1012:Object handle not found in drawing 1013:Unable to delete object 1014:Unable to load Xref for bind process 1015:Unable to bind Xref for bind process 5001: Warning: The drawing file has a password Warning strings 22

23 XML Definition The XML file is divided into sections that can be exported to the XML or not, this enables the user to extract only information that is needed. This will reduce the file size of the XML resultant file. These sections are: Attributes Attribute Definitions References Layers Layouts Variables Images Text The XML format is now using UTF-8, this allows the different UNICODE characters. If there some information that you would like to see in the XML file, then please do contact CADology and request the user information that you would like to see added and why. Below is a sample XML listing from DToolsX but this may not include the latest version of the XML hence in your version there may be more information: <?xml version="1.0" encoding="utf-8"?> - <DToolsX> - <DrawingInformation> <DatabaseFilename>c:\parent.dwg</DatabaseFile name> <ApproxNumObjects>85</ApproxNumObjects> <NumberOfSaves>0</NumberOfSaves> <OriginalFileVersion>AC1015</OriginalFileVersion> <LastSavedVersion>AC1018</LastSavedVersion> <OriginalFileSavedByVersion>AC1015</OriginalFileSave dbyversion> <Hyperlinkbase /> <Title /> <Subject /> <Author /> <Comments /> <Keywords /> 23

24 <LastSavedBy /> <Custom /> </DrawingInformation> - <Attributes> - <Block name="*model_space"> - <Insert name="ref"> <LayerName>0</LayerName> </Insert> - <Insert name="ref"> <LayerName>0</LayerName> </Insert> - <Insert name="ref"> <LayerName>0</LayerName> </Insert> </Block> <Block name="*paper_space" /> <Block name="*paper_space0" /> <Block name="ref" /> <Block name="xdata" /> </Attributes> - <AttributeDefinitions> <Block name="*model_space" /> <Block name="*paper_space" /> <Block name="*paper_space0" /> <Block name="ref" /> <Block name="xdata" /> </AttributeDefinitions> - <ExternalReferences> - <Reference name="ref"> <PathName>C:\ref.dwg</PathName> </Reference> - <Reference name="xdata"> <PathName>C:\xdata.dwg</PathName> </Reference> </ExternalReferences> - <Layers> - <LayerName name="0"> <Display>On</Display> </LayerName> - <LayerName name="defpoints"> <Display>Off</Display> </LayerName> - <LayerName name="ref Dawson"> <Display>On</Display> </LayerName> - <LayerName name="level 51"> 24

25 <Display>On</Display> </LayerName> - <LayerName name="level 52"> <Display>On</Display> </LayerName> - <LayerName name="level 53"> <Display>On</Display> </LayerName> - <LayerName name="level 54"> <Display>On</Display> </LayerName> - <LayerName name="level 55"> <Display>On</Display> </LayerName> - <LayerName name="level 57"> <Display>On</Display> </LayerName> </Layers> - <Layouts> - <LayoutName name="layout1"> <TabOrder>1</TabOrder> </LayoutName> - <LayoutName name="layout2"> <TabOrder>2</TabOrder> </LayoutName> - <LayoutName name="model"> <TabOrder>0</TabOrder> </LayoutName> </Layouts> - <Variables> - <TILEMODE> <Value>1</Value> </TILEMODE> - <EXTMIN> <X> </X> <Y> </Y> <Z> </Z> </EXTMIN> - <EXTMAX> <X> </X> <Y> </Y> <Z> </Z> </EXTMAX> - <PEXTMIN> <X> </X> <Y> </Y> <Z> </Z> 25

26 </PEXTMIN> - <PEXTMAX> <X> </X> <Y> </Y> <Z> </Z> </PEXTMAX> </Variables> - <Images> - <Block name="*model_space"> - <Image> <Handle>24</Handle> <ElementId>36</ElementId> <PathName>C:\Ark_174_110.TIF</Pa thname> </Image> - <Image> <Handle>29</Handle> <ElementId>41</ElementId> <PathName>C:\Documents and Settings\Ark_174.TIF</PathName> </Image> </Block> <Block name="*paper_space" /> </Images> </DToolsX> 26

27 Wanted : New Methods and Properties Suggestions: If you require or have an idea for a new method or property, please contact CADology by with details. If your suggestion is included, then the latest version will be shipped free of charge. Please contact CADology with your requirements. 27

28 Technical Support The latest version of DToolsX (Software, revision history and this manual) can be found and downloaded from the CADology web site on Internet; For technical support, please contact CADology either by : Electronic Mail : techsupp@cadology.com Voice : Fax : Post : (International) 44 (0) (International) 44 (0) CADology Limited Meach House, 71 Nonsuch Walk, Cheam, Surrey. SM2 7LF United Kingdom 28