Transcription
Getting Started withCreo Object TOOLKIT C 3.0Datecode M130
Copyright 2017 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved.User and training guides and related documentation from PTC Inc. and its subsidiary companies (collectively"PTC") are subject to the copyright laws of the United States and other countries and are provided under alicense agreement that restricts copying, disclosure, and use of such documentation. PTC hereby grants to thelicensed software user the right to make copies in printed form of this documentation if provided on softwaremedia, but only for internal/personal use and in accordance with the license agreement under which theapplicable software is licensed. Any copy made shall include the PTC copyright notice and any otherproprietary notice provided by PTC. Training materials may not be copied without the express written consentof PTC. This documentation may not be disclosed, transferred, modified, or reduced to any form, includingelectronic media, or transmitted or made publicly available by any means without the prior written consent ofPTC and no authorization is granted to make copies for such purposes. Information described herein isfurnished for general information only, is subject to change without notice, and should not be construed as awarranty or commitment by PTC. PTC assumes no responsibility or liability for any errors or inaccuraciesthat may appear in this document.The software described in this document is provided under written license agreement, contains valuable tradesecrets and proprietary information, and is protected by the copyright laws of the United States and othercountries. It may not be copied or distributed in any form or medium, disclosed to third parties, or used in anymanner not provided for in the software licenses agreement except with written prior approval from PTC.UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVILDAMAGES AND CRIMINAL PROSECUTION.PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate thepiracy of PTC software products, and we pursue (both civilly and criminally) those who do so using all legalmeans available, including public and private surveillance resources. As part of these efforts, PTC uses datamonitoring and scouring technologies to obtain and transmit data on users of illegal copies of our software.This data collection is not performed on users of legally licensed software from PTC and its authorizeddistributors. If you are using an illegal copy of our software and do not consent to the collection andtransmission of such data (including to the United States), cease using the illegal version, and contact PTC toobtain a legally licensed copy.Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyrightnotice, of your PTC software.UNITED STATES GOVERNMENT RIGHTSPTC software products and software documentation are “commercial items” as that term is defined at 48 C.F.R. 2.101. Pursuant to Federal Acquisition Regulation (FAR) 12.212 (a)-(b) (Computer Software) (MAY 2014)for civilian agencies or the Defense Federal Acquisition Regulation Supplement (DFARS) at 227.7202-1(a)(Policy) and 227.7202-3 (a) (Rights in commercial computer software or commercial computer softwaredocumentation) (FEB 2014) for the Department of Defense, PTC software products and softwaredocumentation are provided to the U.S. Government under the PTC commercial license agreement. Use,duplication or disclosure by the U.S. Government is subject solely to the terms and conditions set forth in theapplicable PTC software license agreement.PTC Inc., 140 Kendrick Street, Needham, MA 02494 USA
ContentsIntroduction.7Creo Object TOOLKIT C Concepts . 11What Can You Do with Creo Object TOOLKIT C ?.12Communication Modes for Creo Object TOOLKIT C .12Installing and Testing the Creo Object TOOLKIT C DevelopmentEnvironment .13Installing Creo Object TOOLKIT C .14Setting Up the Development Environment .15Testing the Creo Object TOOLKIT C Installation .24Migrating Creo Parametric TOOLKIT Applications to Creo Object TOOLKIT C Using Tools .30Creating Ribbon Tabs, Groups, and Menu Items .30Creating Dialog Boxes Using the Creo UI Editor.32Using the Creo Object TOOLKIT C Documentation .33Installing the APIWizard .34Non-Applet Based Version of the APIWizard.34Methods Supported in Creo Direct .35Viewing the PDF Version of the User's Guide .35Using the Release Notes.35Using Extended Resources.37Locating Example Code .38Using the User's Guide.39Contacting PTC Technical Support.39Joining the PTC/USER Community .40Index.415
IntroductionGetting Started with Creo Object TOOLKIT C introduces the techniques andpractices of developing applications with Creo Object TOOLKIT C for CreoParametric and Creo Direct. This guide outlines the installation procedure forCreo Object TOOLKIT C and helps you locate the Creo Object TOOLKIT C functions and documentation. Familiarity with the basics of Creo ObjectTOOLKIT C will help you understand and create advanced applications.The following table lists conventions and terms used throughout this book.ConventionDescriptionUPPERCASECreo-type menu name (for example, PART).BoldfaceWindows-type menu name or menu or dialog boxoption (for example, View), or utility (for example,promonitor). Function names also appear inboldface font.Code samples appearMonospace(Courier)EmphasisImportant information appears in italics. Italic fontalso indicates file names and function arguments.ChooseHighlight a menu option by placing the arrow cursoron the option and pressing the left mouse button.SelectA synonym for “choose” as above, Select alsodescribes the actions of selecting elements on amodel and checking boxes.ElementAn element describes redefinable characteristics of afeature in a model.An environment in Creo in which you can perform agroup of closely related functions (Drawing, forexample).ModeModelAn assembly, part, drawing, format, notebook, casestudy, sketch, and so on.OptionAn item in a menu or an entry in a configuration file7
ConventionDescriptionor a setup file.SolidA part or an assembly. creo loadpoint The location where the Creo applications areinstalled, for example, C:\Program Files\PTC\Creo 3.0.The location where the Creo Object TOOLKIT C application files are installed, that is, creoloadpoint \ datecode \Common Files\otk\otk cpp. creo otk loadpoint app creo otk loadpoint doc The location where the Creo Object TOOLKIT C documentation files are installed, that is, creoloadpoint \ datecode \Common Files\otk cpp doc. creo toolkit loadpoint The location where the Creo Parametric TOOLKITapplication is installed, that is, creoloadpoint \ datecode \Common Files\protoolkit.Intended AudienceThis guide is for programmers experienced in C/C programming prior toworking with Creo Object TOOLKIT C . The experience of the programmershould include: Training in fundamentals of Creo Parametric and Creo Direct Good experience of working with Creo Parametric and Creo Direct in theareas being customized C/C experience with knowledge of pointers, data structures, and dynamicmemory management Use of Microsoft Visual StudioIn addition, you must have the Creo Object TOOLKIT C license to develop,build, and test applications.Scope and PurposeThis guide is not a complete summary of Creo Object TOOLKIT C techniques.It walks you through the process of building and testing a simple Creo ObjectTOOLKIT C application. It introduces the basic concepts of Creo ObjectTOOLKIT C to new users. It also provides pointers to resources that enhanceyour knowledge about Creo Object TOOLKIT C .The guide focuses only on running a Creo Object TOOLKIT C DLLapplication in an interactive session of Creo Parametric. It does not cover anyother application configuration.8Getting Started with Creo Object TOOLKIT C 3.0
CommentsPTC welcomes your suggestions and comments on its documentation. You cansend comments to the following e-mail address:MCAD-documentation@ptc.comPlease include the name of the application and its release number with yourcomments. For online books, provide the book title.Introduction9
1Creo Object TOOLKIT C ConceptsWhat Can You Do with Creo Object TOOLKIT C ? .12Communication Modes for Creo Object TOOLKIT C .12Creo Object TOOLKIT C is the customization toolkit for Creo Parametric andCreo Direct. Customers and partners can expand the capabilities of CreoParametric and Creo Direct by writing C programming language code usingCreo Object TOOLKIT C and then seamlessly integrating the resultingapplication into Creo. PTC provides new releases of Creo Object TOOLKIT C concurrently with releases of Creo Parametric and Creo Direct.Creo Object TOOLKIT C uses an object-oriented design. A library of C functions provides safe and controlled access to the Creo Parametric and CreoDirect database and applications. Many data structures that are used to transferinformation between Creo and the application are not directly visible to theapplication. The contents of these data structures are accessible only with CreoObject TOOLKIT C functions. The sections in this chapter describe thecapabilities and modes of communication of Creo Object TOOLKIT C .NoteThe methods that are supported for Creo Direct have the comment “Thismethod is enabled for Creo Direct” in the Creo Object TOOLKIT C APIWizard.11
What Can You Do with Creo ObjectTOOLKIT C ?With Creo Object TOOLKIT C you can: Develop customizations for both Creo Parametric and Creo Direct Automate modeling for derived or single-use models driven by geometric orparametric constraints Monitor the state of the user's interactive session to enforce company rules oroffer design advice Integrate external applications requiring access to Creo Parametric and CreoDirect data or operations Extend the Creo Parametric and Creo Direct user interface with customprocesses seamlessly embedded into the interface Automate tedious or difficult Creo Parametric and Creo Direct operations withapplications designed to save design time and prevent mistakes. Create processes to run automatically without a user interface on demand or atdesignated times.Communication Modes for Creo ObjectTOOLKIT C Creo Object TOOLKIT C supports synchronous applications that are invokedfrom commands within a session of Creo. Another mode available isasynchronous mode, where the external application starts or connects to externalsessions of Creo as needed.The modes of communication for synchronous applications are: DLL mode—A dynamically-linked library (DLL) is loaded by the Creoexecutable at runtime. Communication between the DLL and Creo is fast andhence the DLL mode is the preferred mode for application development. Spawn (multiprocess) mode —A separate executable is spawned by Creo.Spawn-mode applications interact with Creo through interprocesscommunications and hence are slower than the DLL mode. This mode istypically used as a part of asynchronous mode applications, where the externalapplication starts or connects to external sessions of Creo as needed.12Getting Started with Creo Object TOOLKIT C 3.0
2Installing and Testing the CreoObject TOOLKIT C DevelopmentEnvironmentInstalling Creo Object TOOLKIT C .14Setting Up the Development Environment .15Testing the Creo Object TOOLKIT C Installation.24Migrating Creo Parametric TOOLKIT Applications to Creo Object TOOLKIT C Using Tools.30Creating Ribbon Tabs, Groups, and Menu Items .30Creating Dialog Boxes Using the Creo UI Editor .32This chapter discusses the process to install Creo Object TOOLKIT C and totest the development environment. The test application and other sample codedescribed in this guide assume the use of a Windows environment.13
Installing Creo Object TOOLKIT C Creo Object TOOLKIT C is on the Creo Parametric and Creo Direct DVDROM. When you install Creo Parametric or Creo Direct, under API Toolkits, selectCreo Object TOOLKIT C to install it.An installation of Creo Object TOOLKIT C contains directories under the Creoload point.Directoryotk\otk cppDescriptionTop-level directory where C application files are installedotk\otk cpp\includeContains all the header filesotk\otk cpp\otk async examples Sample application source files forasynchronous mode of applicationotk\otk cpp\otk examplesSample application source files forsynchronous mode of applicationotk\otk cpp\ machine type \obj Library files and sample makefiles14Getting Started with Creo Object TOOLKIT C 3.0
Directoryotk cpp docotk cpp doc\otk cpp exampleshtmlDescriptionTop-level directory where C documentation files, such as,APIWizard and User’s Guide, areinstalledSample application files in HTMLformat.Setting Up the Development EnvironmentBefore you build your first Creo Object TOOLKIT C application, set up thesupported compilers, sample make files or Visual Studio solution, and theappropriate licensing for your application development environment.Platform and Compiler SupportCreo Object TOOLKIT C runs on the same platforms as Creo Parametric andCreo Direct. The Platform Support notes at rt.htm describe the compilers supported by PTC.Licensing for Creo Object TOOLKIT C To develop and test Creo Object TOOLKIT C applications, you require theCreo Object TOOLKIT C license. To check if you have the Creo ObjectTOOLKIT C license option, run the Ptcstatus utility from the Creo loadpoint. Check for the license option ObjectToolkitCpp.You can check if you have the Creo Object TOOLKIT C license option in theCreo user interface. Click File Help System Information. In the INFORMATIONWINDOW, under Configured Option Modules check for the license optionObjectToolkitCpp. In case the license is not available please contact yoursystem administrator.The Creo Object TOOLKIT C applications must be unlocked beforedistributing it to the end users. To unlock the application, both the Creo ObjectTOOLKIT C and Creo Parametric TOOLKIT licenses are required.Unlocking the Creo Object TOOLKIT C ApplicationBefore you distribute your application executable to the end user, you must unlockit. This enables the end user to run your applications without having Creo ObjectTOOLKIT C as an option.Installing and Testing the Creo Object TOOLKIT C Development Environment15
To unlock a Creo Object TOOLKIT C application, you must have both theCreo Object TOOLKIT C license and the Creo Parametric TOOLKIT license.NoteThe Creo Object TOOLKIT C license is now a part of the Creo ParametricTOOLKIT license pack. If you are unable to unlock the Creo ObjectTOOLKIT C applications, request for the updated license pack from theTechnical Support page.To unlock your application, enter the following command: creo loadpoint / app name /bin/protk unlock.bat [-cxx] pathto executables or DLLs to unlock where, app name —Parametric for Creo Parametric and Direct forCreo Direct.NoteThe Creo Object TOOLKIT C is unlocked even if you do not specify the-cxx option.You can provide more than one Creo Parametric TOOLKIT binary file on thecommand line.NoteOnce you have unlocked the executable, you can distribute your applicationprogram to Creo Object TOOLKIT C users in accordance with the licenseagreement.Using protk unlock.bat requires a valid Creo Parametric TOOLKIT licenseto be present and unused on your license server. If the Creo Parametric licenseserver is configured to add a Creo Parametric TOOLKIT license as a startupoption, protk unlock.bat will cause the license server to hold only the CreoParametric TOOLKIT option for 15 minutes. The license will not be available forany other development activity or unlocking during this period.If the only available Creo Parametric TOOLKIT license is locked to a CreoParametric license, the entire Creo Parametric license including the CreoParametric TOOLKIT option will be held for 15 minutes. PTC recommends youconfigure your Creo Parametric TOOLKIT license option as a startup option toavoid tying up your Creo Parametric licenses.16Getting Started with Creo Object TOOLKIT C 3.0
NoteOnly one license will be held for the specified time period, even if multipleapplications were successfully unlocked.Your Creo Object TOOLKIT C application may have calls to Creo ParametricTOOLKIT functions, which require one or more advanced licensing options.Refer to the section Using Creo Object TOOLKIT C with Creo ParametricTOOLKIT on page 22 for more information on using C and C functionstogether, in the same application.In such cases, you will require the advanced Creo Parametric TOOLKIT license tounlock the application. The protk unlock.bat application will check for theavailability of the advanced license option. If the option is not available,unlocking will not be permitted. If the option is available, the application isunlocked. Advanced options are not held on the license server for any length oftime. Refer to the Advanced Licensing Options chapter, in Creo ParametricTOOLKIT User’s Guide for more information on advanced licensing.If the required licenses are available, the protk unlock.bat application willunlock the Creo Object TOOLKIT C application immediately. An unlockedapplication does not require any of the Creo Parametric TOOLKIT license optionsto run. Depending on the functionality invoked by the application, it may stillrequire certain Creo Parametric options to work correctly.NoteOnce an application binary has been unlocked, it should not be modified inany way (which includes statically linking the unlocked binary with otherlibraries after the unlock). The unlocked binary must not be changed or elseCreo Parametric will again consider it locked.Registry FileA registry file contains Creo-specific information about the application you wantto load.The registry file called creotk.dat or protk.dat is a simple text file, whereeach line consists of one predefined keyword followed by a value. The standardform of the creotk.dat or protk.dat file is as follows:NAMEotk examplesTOOLKITCREO TYPEEXEC FILEOBJECT [optional; omitted means protoolkit]DIRECT [optional; omitted means PARAMETRIC]otk examples dll.dllInstalling and Testing the Creo Object TOOLKIT C Development Environment17
TEXT DIRSTARTUPEND./textdll [dll/spawn/java]The fields of the registry file are as follows: name—Assigns a unique name to the Creo Object TOOLKIT C application. The name is used to identify the application if there is more thanone. The name can be the product name and does not have to be the same asthe executable name. This field has a limit of PRO NAME SIZE-1 widecharacters (wchar t). startup—Specifies the method Creo should use to communicate with theCreo Object TOOLKIT C application.This field can take one of two values; spawn or dll. spawn—If the value is spawn, Creo starts the foreign program usinginterprocess communications. dll—If the value is dll, Creo loads the foreign program as a DLL.The default value is spawn. toolkit—Specifies the name of the Toolkit which was used to create thecustomization. The valid values for this field are object and protoolkit.An application created in Creo Object TOOLKIT C must always have thevalue of this field set as object.NoteThis field can also be used to indicate other toolkits. Its default value isprotoolkit, which specifies that the customizing application wascreated in Creo Parametric TOOLKIT. If you set the value for this field asprotoolkit, or omit this field, then the application can be used onlywith Creo Parametric. creo type—Specifies the Creo applications that support the Creo ObjectTOOLKIT C applications. The valid values for this field are: parametric—This is the default value. Specify parametric to loadthe Creo Object TOOLKIT C application in Creo Parametric.18Getting Started with Creo Object TOOLKIT C 3.0
direct—Specify direct to load the Creo Object TOOLKIT C application in Creo Direct.NoteOther Creo applications will be supported in future releases. fail tol—Specifies the action of Creo if the call to userinitialize() in the foreign program returns non-zero, or if the foreignprogram subsequently fails. If this is TRUE, Creo continues as normal. If thisfield is missing or is set to FALSE, Creo shuts down the application and otherforeign programs. exec file—Specifies the full path and name of the file produced bycompiling and linking the Creo Object TOOLKIT C application. In DLLmode, this field is a dynamically linkable library; in spawn mode, it is acomplete executable. This field has a limit of PRO PATH SIZE-1 widecharacters (wchar t). text dir—Specifies the full path name to text directory that contains thelanguage-specific directories. The language-specific directories contain themessage files, menu files, resource files and UI bitmaps in the languagesupported by the Creo Object TOOLKIT C application.The text dir does not need to include the trailing /text; it is addedautomatically by Creo.The search priority for messages and menu files is as follows: Current working directory text dir\text creo loadpoint \Common Files\ datecode \ machinetype \textThe text dir should be different from the Creo text tree. This field has alimit of PRO PATH SIZE-1 wide characters (wchar t). rbn path—Specifies the name of the ribbon file along with its path, whichmust be loaded when you open the Creo application. The location of theribbon file is relative to the location of the text directory. The field text dirspecifies the path for the text directory. For example, if you want to specify aribbon file dma rbn.rbn placed at text dir/dma/dma rbn.rbn,specify rbn path as dma/dma rbn.rbn.If the field is not specified, by default, the ribbon file with its location, textdir/toolkitribbonui.rbn is used.Installing and Testing the Creo Object TOOLKIT C Development Environment19
delay start—If you set this to TRUE, Creo does not invoke the CreoObject TOOLKIT C application as it starts up, but enables you to choosewhen to start the application. If this field is missing or is set to FALSE, theCreo Object TOOLKIT C application starts automatically. description—Acts as a help line for your auxiliary application. If youleave the cursor on an application in the Start/Stop GUI, Creo displays thedescription text (up to 80 characters). You can use non-ASCII characters, as inmenu files.To make the description appear in multiple languages, you must use separateprotk.dat files in hierarchy / platform / text / language . allow stop—If you set this to TRUE, you can stop the application duringthe session. If this field is missing or is set to FALSE, you cannot stop theapplication, regardless of how it was started. end—Indicates the end of the description of the Creo Object TOOLKIT C application. It is possible to add further statements that define other foreignapplications. All of these applications are initialized by Creo.Registering a Creo Object TOOLKIT C ApplicationRegistering a Creo Object TOOLKIT C application means providinginformation about the files that form the Creo Object TOOLKIT C applicationto Creo. Creo application will find and read the registry file. Refer to the sectionRegistry File on page 17 for more information on registry file.Creo application searches for the registry file in the following order:1. A file called creotk.dat or protk.dat in the current directory2. A file named in a creotk.dat, protk.dat, or toolkit registryfile statement in the Creo application configuration file3. A file called creotk.dat or protk.dat in the directory creoloadpoint \ datecode \Common Files\ machine type \text\ language 4. A file called creotk.dat or protk.dat in the directory creoloadpoint \ datecode \Common Files\textIn the last two options, the variables are as follows:20Getting Started with Creo Object TOOLKIT C 3.0
creo loadpoint —The Creo loadpoint (not the Creo Object TOOLKITC loadpoint) machine type —The machine-specific subdirectory such as x86ewin64 or i486 nt language —The language of Creo application with which the CreoObject TOOLKIT C application is used such as usascii (English),german, or japaneseIf more than one registry file with the same filename exists in this search path,Creo Object TOOLKIT C stops searching after finding the first instance of thefile and starts all the Creo Object TOOLKIT C applications specified in it. Ifmore than one registry file having different filenames exists in this search path,Creo application stops searching after finding one instance of each of them andstarts all the Creo Object TOOLKIT C applications specified in them.Option 1 is used normally during development, because the Creo ObjectTOOLKIT C application is seen only if you start Creo application from thespecific directory that contains creotk.dat or protk.dat.Option 2 or 4 is recommended when making an end-user installation, because itmakes sure that the registry file is found irrespective of the directory used to startCreo application.Option 3 enables you to have a different registry file for each platform, and foreach Creo application language. This is more commonly used for Creo ObjectTOOLKIT C applications that have a platform dependent setup.How Creo Object TOOLKIT C WorksThe standard method by which Creo Object TOOLKIT C application code isintegrated into Creo application is through the use of dynamically linked libraries(DLLs). When you compile your Creo Object TOOLKIT C application codeand link it with the Creo Object TOOLKIT C libraries, you create an objectlibrary file designed to be linked into the Creo executable when the Creoapplication starts up. This method is referred to as DLL mode.Creo Object TOOLKIT C also supports a second method of integration: themultiprocess or spawned mode. In this mode, the Creo Object TOOLKIT C application code is compiled and linked to form a separate executable. Thisexecutable is designed to be spawned by Creo application and runs as a childprocess of the Creo session. In DLL mode, the exchanges between the CreoObject TOOLKIT C application and Creo application are made through directfunction calls. In multiprocess mode, the same effect is created by an inter-processmessaging system that simulates direct function calls by passing the informationnecessary to identify the function and its argument values between the twoprocesses.Installing and Testing the Creo Object TOOLKIT C Development Environment21
Multiprocess mode involves more communications overhead than DLL mode,especially when the Creo Object TOOLKIT C application makes frequent callsto Creo Object TOOLKIT C library functions, because of the more complexmethod of implementing those calls. However, it offers the following advantage: itenables you to run the Creo Object TOOLKIT C application with a source-codedebugger without even loading the whole Creo executable into the debugger.You can use a Creo Object TOOLKIT C application in either DLL mode ormultiprocess mode without changing any of the source code in the application. Itis also possible to use more than one Creo Object TOOLKIT C applicationwithin a single session of Creo application, and these can use any combination ofmodes.If you use multiprocess mode during development of your application to debugmore easily, you should switch to DLL mode when you install the application foryour end users because the performance is better in that mode. However, take careto test your application thoroughly in DLL mode before you deliver it. Anyprogramming errors in your application that cause corruption to memory used byCreo or Creo Object TOOLKIT C are likely to show quite different symptomsin each mode,
Creo Object TOOLKIT C is on the Creo Parametric and Creo Direct DVD-ROM. When you install Creo Parametric or Creo Direct, under API Toolkits, select Creo Object TOOLKIT C to install it. An installation of Creo Object TOOLKIT C contains directories under the Creo load point. Directory Description otk\otk_cpp Top-level directory where C
