Extending the Gupta Development Environment

Transcription

1 Extending the Gupta Development Environment

2 Trademarks Copyright GUPTA, SQLBase, SQLRouter, Team Developer, and SQLTalk are trademarks of Gupta Technologies, LLC registered in the United States and/or other countries. SQLWindows is a registered trademark of Microsoft Corporation, and is used under license to Gupta Technologies, LLC. Centura and Centura Software are registered trademarks of Centura Software Corporation, and are used under license to Gupta Technologies, LLC. Team Object Manager, Web Developer, QuickObjects, Object Nationalizer, Report Builder, Connectivity Administrator, Development Kit, Component Development Kit, SQLBase Resource Manager, and SQLConsole are names of products from Gupta Technologies, LLC. Adobe is a trademark of Adobe Systems, Incorporated. IBM, OS/2, NetBIOS, and AIX are registered trademarks of International Business Machines Corporation. Linux is a trademark of Linus Torvalds. Red Hat is a trademark of Red Hat, Incorporated. Novell and Netware are trademarks of Novell, Inc. SUSE is a trademark of SUSE LINUX AG. Java, JavaScript, and Solaris are trademarks of Sun Microsystems, Incorporated. Microsoft, Outlook, PowerPoint, Visual C++, Visual Studio, Internet Explorer, Internet Information Server, DOS, Win 32, Windows, ActiveX, MSDN, SQL Server, and Visual Basic are either registered trademarks or trademarks of Microsoft Corporation in the United States of America and/or other countries. Netscape FastTrack and Navigator are trademarks of Netscape Communications Corporation. All other product or service names mentioned herein are trademarks or registered trademarks of their respective owners. Copyright by Gupta Technologies LLC. All rights reserved. Extending the Gupta Development Environment October 2004

3 Extending the Gupta Development Environment Contents Preface Purpose of this Manual Prerequisites Typographical conventions Summary of Chapters Other Helpful Sources Sending Comments to Getting Started What is the CDK? CDK add-on tools CDK interfaces Outline interface Runtime Inspector interface Notification interface What the CDK includes SAL CDK Sample applications C++ CDK Sample applications Add-on tools How to install Wizard Wizard Using the CDK from SAL Class structure diagrams Linking to external SAL applications Link applications using the QuickObject Editor Extending the Gupta Development Environment 3

4 Create a link using the toolbar Summary Writing code from a runtime editor application Install the editor application as a wizard Extending Objects from SAL Setting object properties Get and set properties Writing code using the CDK Populating a form using the CDK Using the CDK from Microsoft Visual C Application types EXE applications DLL applications The compiler environment Microsoft Visual C++ software version Installation directories Set up the Microsoft Visual C++ environment Troubleshooting Linker error messages Setting design hooks into the SQLWindows IDE Extending Objects from Microsoft Visual C Create a QuickObject editor in Microsoft Visual C Modify the property editor Populating a form using the CDK Index Extending the Gupta Development Environment

5 Extending the Gupta Development Environment Preface This preface explains how Extending the Gupta Development Environment can help you use the GUPTA Developer Extension Kit (CDK). In this preface, you find the following information: Who should read this manual. Conventions used in this manual. How this manual is organized. Other helpful resources. How to send us your comments. Extending the Gupta Development Environment -5

6 Preface Purpose of this Manual This manual, Extending the Gupta Development Environment, explains the basic features, advanced features, and capabilities of the CDK. It contains information a developer needs to modify GUPTA applications using the CDK for SAL programmers or the CDK for C++ programmers. (Use the online help for reference material such as the CDK functions.) Experienced developers who use GUPTA to write applications, such as corporate developers who build custom applications, vertical application builders (OEMs), and independent software vendors (ISVs), can benefit from using the CDK. Prerequisites This manual assumes you: Have installed your OS, GUPTA, and the CDK. Are an experienced GUPTA developer who is familiar with GUPTA, objectoriented programming, the SAL programming language. Are familiar with the concepts in the Using and Extending QuickObjects manual. Typographical conventions We use these typographical conventions in this manual: Formatting Convention bold type italic type courier type cdki*.dll Type of Information Menu items, push buttons, and field names. Things that you select. Keyboard keys that you press. Names of books and publications. Place holders for items you must supply, such as file names. For example, when the manual says to type cd directory name you type the letters cd followed by a space and then the name of a directory. Commands or code you must enter through the keyboard exactly as shown. File names where the asterisk respresents the version number. For example, the DLL name for cdk 2.0 is cdki20.dll. -6 Extending the Gupta Development Environment

7 Summary of Chapters This manual is organized in the following chapters: Chapter 1. Getting Started This chapter introduces the CDK concepts, what is included with the CDK, and how to install it. This chapter also includes a list of sample applications that are included with the CDK. Chapter 2. Using the CDK from SAL This chapter describes the class structure and how to link a GUPTA application to an external SAL application. Chapter 3. Extending Objects from SAL Through a series of short tutorials, you review how simple QuickObjects extend their designtime interface using SAL. You also create a QuickObject application to set a named property and write code into one application from a linked application. Chapter 4. Using the CDK from C++ This chapter describes how to prepare your environment to use the C++ CDK. Chapter 5. Extending Objects from C++ Like Chapter 3, you review how to extend the designtime interface for QuickObjects from C++. You also create a QuickObject application to set a named property and write code into one application from a linked application. Other Helpful Sources GUPTA Books Online. The GUPTA document suite is available online. This document collection lets you perform full-text indexed searches across the entire document suite, navigate the table of contents using the expandable/collapsible browser, or print any chapter. Open the collection by selecting the GUPTA Books Online icon from the Start menu or by double-clicking on the launcher icon in the program group. Online Help. The online help offers a quick way to find information on functions and constants. World Wide Web. Gupta s World Wide Web site contains information about Gupta Technologies LLC s partners, products, sales, support, training, and users. The URL is Our Web site is a valuable resource for customers with technical support issues, and addresses a variety of topics and services, including technical support case status, commonly asked questions, access to GUPTA s Online Newsgroups, links to Shareware tools, product bulletins, white papers, and downloadable product updates. Our site also provides information on training, including course descriptions, class schedules, and Certified Training Partners. Extending the Gupta Development Environment -7

8 Preface Sending Comments to... If you have any comments or suggestions about this manual, please send them to: Technical Publications Department Gupta Technologies LLC 975 Island Drive Redwood Shores, CA or send , with comments or suggestions to: -8 Extending the Gupta Development Environment

9 Extending the Gupta Development Environment Chapter 1 Getting Started This chapter helps you start using the GUPTA Developer Extensions Kit (CDK). It describes: What the CDK is. The CDK Interfaces. What the CDK includes. System requirements. Extending the Gupta Development Environment 1-1

10 Chapter 1 Getting Started What is the CDK? CDK add-on tools The CDK is a library that provides object-oriented interfaces to the SQLWindows development environment for: Add-on tools for GUPTA programmers. Components such as QuickWizards and other productivity enhancing utilities. Customization of the GUPTA development environment. Tighter integration of GUPTA with other development tools such as upper- CASE, testing, and performance monitoring tools. Using the CDK, you can: Extend and augment your design environment by creating your own utilities to help with the development process. Improve the accuracy of code implementation using automated code generation and simple, graphical user interfaces. The CDK interfaces are available as Scalable Application Language (SAL) classes and C++ classes. One of the main advantages of the CDK add-on tools is automating routine or tedious tasks. Using these tools, you can automate: File-based operations, such as saving applications with their libraries to text or binary format. This is an ideal way to save space or refresh your source code. You can also use an add-on tool to modify the Save option on your toolbar to automatically save and create a backup file. Customization of your development environment, such as selecting and setting properties for multiple objects on a form. For example, using a CDK add-on tool you can set the label font and size for all the data fields on your form. Accessing and using properties (internal data storage elements) that provide structural or static data in your application. For example, if you do not want to use the standard properties of a QuickObject, you can use a CDK add-on tool to directly and quickly modify the properties. Another CDK utility allows you to initialize tool tip and status bar help (also called MicroHelp) at designtime rather than process a SAM_Create or user-defined message at runtime. Routine programming tasks. A CDK add-on tool provides a convenient dialog box to specify arguments for a function. Another tool allows you to 1-2 Extending the Gupta Development Environment

11 CDK interfaces CDK interfaces quickly and easily create a window from a list of valid top-level windows in your application. The CDK has three interfaces: Outline interface Runtime Inspector interface Notification interface Outline interface This interface is a set of classes and functions you use to directly manipulate a SQLWindows application outline from another program written in SAL or C++. To use this Application Program Interface (API), you need to only understand the structure of a SQLWindows application. The Outline interface is available as SAL and C++ class libraries for SQLWindows and non-sqlwindows programmers. Use this interface if you are a SQLWindows or C++ programmer and need to read and generate SQLWindows applications using SAL or C++. Runtime Inspector interface Use this interface to determine the runtime state and properties of objects (such as, pushbuttons, table windows, list boxes) in a SQLWindows application. Several testing tools vendors use this interface to build links to GUPTA Team Developer. Use the new trace feature for performance tuning, debugging, and profiling. You can get a trace of all the statements executed, and the order in which they were executed, without adding any debugging statements to a SQLWindows application. Notification interface This interface allows a program to receive notifications when you change the outline focus, delete an item, add an item, or open or save an outline in SQLWindows. You can also create a tool that performs tasks, such as selecting a line in the Outline view, expanding a node (on the left side) in the tree view, or changing (on the right side) from the Layout tab to the Variables tab. These functions act on the user interface of SQLWindows. Extending the Gupta Development Environment 1-3

12 Chapter 1 Getting Started What the CDK includes SAL CDK You receive the following components in the SAL CDK. Component CDK.APL CDKI*.DLL TLNOTIFY.APL Sample applications Description A library that you can include in the SQLWindows outline. This library gives your program access to the Outline interface. A compiled Dynamic Link Library of function calls and methods used by CDK.APL. Also, it has an encapsulated set of SQLWindows outline rules the CDK uses to determine the legal and illegal operations. This library is used by the Runtime Inspector interface. A library that lets programs receive notification when you change the outline focus, delete an item, add an item, or open or save an outline in SQLWindows. Applications used in the tutorials. See the following section for details. You can find these files in the GUPTA directory (base directory or the samples\cdksal subdirectory). Sample applications The CDK provides several sample SAL applications (in the samples\cdksal directory) to demonstrate various portions of the CDK framework. For more detailed information, see the comments and code in the applications. Application Type Description AppGen.app GenProp.app Before.app PreProc.app Source for GenProp.app Editor for AppGen.app Source for PreProc.app Editor for Before.app Displays a form whose outline is read and modified by GenProp.app. Covers most of the application classes in the CDK. Its dialogs implement enumeration, creation, and deletion of most of the application components. Contains debug code which PreProc.app can remove. Demonstrates a very simple preprocessor that can be used to remove blocks of debug code from an outline. 1-4 Extending the Gupta Development Environment

13 What the CDK includes Application Type Description CDKRTest.app CDKRunT.app ClasHost.app ClasProp.app ClasCode.app ClasObjc.app CodeGenS.app CodeGenE.app ClasLib.apl UnitTest.app Cover.app DsgnTest.app Source for CDKRunT.app Editor for CDKRTest.app Source for ClasProp.app, ClasCode.app, and ClasObjc.app Editor for ClasHost.app Editor for ClasHost.app Editor for ClasHost.app Source for CodeGenE.app Editor for CodeGenS.app Source for Cover.app Source for Cover.app Editor for ClasLib.apl and UnitTest.app Source for Design.app Provides an application for CDKRunT to inspect at runtime. Inspects windows within CDKRTest.app at runtime. Provides a QuickObject pushbutton and form for the editor applications to modify. Sets the properties of a pushbutton QuickObject in ClasHost.app. See Lesson 1 in Chapter 3 for details. Inserts code into the message actions of a pushbutton QuickObject in ClasHost.app. See Lesson 2 in Chapter 3 for details. Creates a pushbutton QuickObject, data fields, and background text items on a form. See Lesson 3 in Chapter 3 for details. Provides an outline for CodeGenE to modify. To run this application, right click-on frmcodegen and select Generate Code. Modifies CodeGenS.app and writes SAL code into the form s message action section. Also tests all the SQLWindows verbs. Note that the application created is for demonstration purposes only. Provides an outline for Cover.app to modify. Provides an outline for Cover.app to modify. Includes ClasLib.apl. this application is a test driver for ClasLib.apl. Modifies ClassLib.apl, includes the modified version in UnitTest.app, and then runs UnitTest.app to test the coverage of class functions when the modified ClassLib.apl is used. Provides an outline for Design.app to modify. Extending the Gupta Development Environment 1-5

14 Chapter 1 Getting Started Application Type Description Design.app Docker.app LineHost.app LineProp.app Notify.app PromptS.app PromptE.app VarEditS.app VarEditE.app VisHost.app VisProp.app Editor for DsgnTest.app Editor for any outline Editor for LineProp.app Editor for LineHost.app Editor for any outline Source for PromptE.app Editor for PromptS.app Source for VarEditE.app Editor for VarEditS.app Source for VisProp.app Editor for VisHost.app Displays windows from an outline in design mode and allows you to add windows and change attributes. Use it on DsgnTest.app or any other outline. Demonstrates how to write a class documentor or browser. You can select a class that is part of your application and output its documentation to a text or HTML file. Provides the source for LineProp.app. This application starts a blank form. Right-click on frm1.demo Dialog to invoke LineProp.app. Modifies the outline of LineHost.app and adds visual objects to it. After exiting from the dialog, you see the objects created on the form in LineHost.app. Demonstrates the Notification Interface. You can run this application from the SQLWindows toolbar. Displays windows that monitor user edits (such as, cutting and pasting text) to the currently open outline. Contains a QuickObject data field for PromptE.app to modify. QuickObject editor done in a wizard style. Provides an outline for VarEditE.app to modify. Shows how to add, edit, and delete global variables. Provides a form for VisProp.app to modify. Shows many of the items you can modify for a form. In addition, it creates visual objects on the form. We also provide sample source for building tools. You find these files in the GUPTA\tools subdirectory. They are: 1-6 Extending the Gupta Development Environment

15 What the CDK includes C++ CDK WizWiz.apt PropEdit.apt SoProps.apt You receive these components in the C++ CDK. Component Include files Sample applications Description Contain function prototypes and constant definitions. Applications used in the tutorials. See the following section for details. cdk.lib is installed in the GUPTA directory. You can find include files in the inc subdirectory under GUPTA directory. Sample applications The C++ CDK provides sample applications (in the samples\cdkcpp subdirectory) to demonstrate various portions of the C++ CDK framework. For more detailed information, see the comments and code in the applications. Open these applications in Microsoft Developer Suite. Sample Application Cmdmapr.dsw Notify.dsw Description Demonstrates a toolbar interface to SQLWindows. Writes messages to an output window, finds and manipulates marked items, and generates message handlers, code, and functions. For example, if you select a pushbutton (such as, pbfirst or pbnext) and then invoke cmdmapr.dll, the application generates the functions OnFirst and OnNext in the window with the pushbutton. Then, a SAM_Click message handler calls these functions. Demonstrates a design hook interface, toolbar interface, and notification callbacks. (Similar to the SAL sample application notify.app.) Extending the Gupta Development Environment 1-7

16 Chapter 1 Getting Started Add-on tools You receive these add-on tools for GUPTA SQLWindows. Tool Item Explorer Wizard Wizard Property Editor Mass Customizer Description Displays the IT value stored for each item in the outline. Turns your wizard application into a self-installing wizard so that you can add new wizards to SQLWindows. Property Editor shows you properties for an object. You can modify the properties. Mass Customizer enumerates all the child window objects of a selected window, and you can change the attributes of one or more of them at the same time. You can find the tools in the GUPTA directory. How to install Wizard Wizard This section describes how to install the Wizard Wizard application, which is used to convert applications into wizards. Installing the Wizard Wizard application 1. In SQLWindows, select Component, Wizards. This dialog displays all the available Wizards in GUPTA SQLWindows. 2. Click Cancel to close the Wizards dialog box. 1-8 Extending the Gupta Development Environment

17 How to install Wizard Wizard 3. In Microsoft Windows, open the Windows Explorer and find \GUPTA\tools\wizard. 4. Double-click WIZWIZ.EXE (the Wizard executable). 5. Follow the instructions in the dialog box to install Wizard Wizard. 6. In SQLWindows, select Components, Wizards again. Wizard Wizard added to the Wizards dialog The newly installed wizard has been added to the list of available wizards. Wizards store the information about themselves in the Microsoft Windows system registry. You can view the contents of the registry by running the Registry Editor application. 7. In Microsoft Windows, select Start, Run to display the Run dialog box. 8. Type regedit in the Open field and click OK. On NT, type regedit32. Extending the Gupta Development Environment 1-9

18 Chapter 1 Getting Started Microsoft Windows starts the Registry Editor application. Doubleclick here 9. Double-click HKEY_CURRENT_USER, Software, GUPTA, GUPTA SQLWindows, User Wizards, and then WizardWizard. The right side displays these three string values: ExecFileName is the path to the wizard application you can create with the CDK. IconFilename is the name of the icon file that appears in the Wizards dialog. TitleText is the text that appears below the icon in the Wizards dialog. When you ran WIZWIZ.EXE, it added the key WizardWizard with its three string values to the Registry. You can now use Wizard Wizard to make your wizard applications into self-installing wizards. These wizards automatically add their own key and string information to the Registry Extending the Gupta Development Environment

19 How to install Wizard Wizard Extending the Gupta Development Environment 1-11

20

21 Extending the Gupta Development Environment Chapter 2 Using the CDK from SAL This chapter describes the CDK class structure and three methods for linking a GUPTA source application to an editor application. It describes: The CDK class structure for SAL. How to link a QuickObject to an editor application. How to link a source application to an editor application using the tool bar. How to link source and editor applications using the InitFromFile function. For complete documentaiton of the CDK SAL classes and functions, please refer to the online help. Extending the Gupta Development Environment 2-1

22 Chapter 2 Using the CDK from SAL Class structure diagrams The following flowchart shows the class structure for the non-visual CDK classes. The cdkstaticwindow is the parent class for the visual classes. (Next page.) _ErrorBase Non-Visual Classes cdkitem cdkbuildsettings cdkactionblock cdkapplication cdkclass cdkcomattributes cdkconstant cdkenumeration cdkenumerationitem cdkevent cdkevents cdkextabsbase cdkexternallibrary cdkfunction cdklibrary cdkmenu cdknotifywindow cdkmenuitem cdkmessageaction cdkresource cdkvariable cdkcoclass cdkinterface cdkstaticwindow Visual Classes cdkextstructpointer cdkexternalfunction cdkinterfacefunction cdknotifyform 2-2 Extending the Gupta Development Environment

23 Class structure diagrams The visual classes are derived from cdkstaticwindow. (Previous page.) cdkstaticwindow Visual Classes cdkwindow cdkline cdkgroupbox cdkframe cdkbackgroundtext cdkvertical ScrollBar cdkradiobutton cdkpushbutton cdkpicture cdkoptionbutton cdkmultilinetext cdklistcombobox cdkhorizontal ScrollBar cdklistbox cdkcombobox cdkdatafield cdkcustomcontrol cdkcontainer cdkcolumn cdkcheckbox cdkform cdkmdiform cdkdialog cdkbasetable cdktoolbar cdkdesignwindow cdktablewindow cdkchildtable Extending the Gupta Development Environment 2-3

24 Chapter 2 Using the CDK from SAL Linking to external SAL applications The CDK class components are used by an editor (active) GUPTA application that uses the CDK to read and write code back into the source (passive) application. You have four ways to link your GUPTA source applications to editor applications: Link QuickObjects to the property editor application using the QuickObject Editor. Create a tool on the tool bar to link your property editor application to the source application. Write code from a runtime editor application to the source application by calling the InitFromFile CDK function. Install the editor application as a wizard. These methods are covered in the following procedures. Link applications using the QuickObject Editor In this procedure, you extend the designtime properties of a QuickObject by linking it to a property editor application. You define a visual class, link the class to the editor application using the QuickObject Editor, and then invoke the editor application. Creating a link using the QuickObject Editor 1. In SQLWindows, open a new application. 2-4 Extending the Gupta Development Environment

25 Linking to external SAL applications 2. Define a visual class. Right-click Classes in the Tree view and select New, Pushbutton Class from the displayed menu. 3. Enter cmypb for the new class name and press Enter. 4. Right-click the Windows folder in the tree view and select New, Form Window from the displayed menu. 5. Enter frmmain for the window name and press Enter. Extending the Gupta Development Environment 2-5

26 Chapter 2 Using the CDK from SAL 6. If necessary, display the Controls toolbar (select Tools, Controls). Click the push button tool. Push button tool Select cmypb from the class 7. Select cmypb from the class list and drop a push button on the form. 8. Enter QuickObject for the push button label and press Enter. 9. Right-click the push button, select Properties, and then Object Name. Enter pbquickobject, press Enter, then click Done. 2-6 Extending the Gupta Development Environment

27 Linking to external SAL applications Now you link this push button to a property editor application using the QuickObject Editor. 10. Select Component, QuickObject Editor to open the QuickObject Editor. The new class, cmypb, is highlighted in the Classes list box. 11. Click Browse to display the File Open dialog box. Select the path and directory samples under the GUPTA directory. Select ClasProp.app and click Open. This step links the object (cmypb in this case) to an external application. The application filename can have the extension APT, APP, or EXE. In this example, the ClasProp.app application is a QuickObject property editor application and expects to be called with four parameters. This is discussed in the next section. The QuickObject Editor automatically sets up the parameters. 12. Select dlgdemo in the Dialog Name list box. 13. Click OK to close the QuickObject Editor dialog box. Extending the Gupta Development Environment 2-7

28 Chapter 2 Using the CDK from SAL 14. Right-click the QuickObject push button you dropped on the form, select Properties, QuickObject to invoke the editor application with the property dialog box (dlgdemo). 15. Click Close. 16. Save your application as Source.app. Congratulations! You just created a push button QuickObject and linked it to the property editor application, using the QuickObject Editor. Then you invoked the editor application (a property dialog) by clicking the Attribute Inspector. Create a link using the toolbar This procedure continues the previous tutorial using the QuickObject property editor application (ClasProp.app). In this procedure, you: Set the editor application to be launched from the toolbar (instead of Attribute Inspector) in the source application. To do this, you create a tool on the toolbar linking your source application to the editor application. Use SQLWindows to run the application version instead of the executable for debugging purposes. Creating a link using the toolbar 1. Open Source.app you created in the previous procedure. 2-8 Extending the Gupta Development Environment

29 Linking to external SAL applications 2. Select Tools, Tools to open the Tools dialog box. Click here to add a new tool Click here to add parameters 3. Click Add. This clears the fields in the dialog box and adds a default value in the Command field. 4. Replace the default value in the Command field with cbi*.exe. This command line launches GUPTA. 5. Enter -r ClasProp.app dlgdemo in the Parameters field. 6. Click the... (Ellipsis) push button to display the list of additional parameters. 7. Click Current Outline. 8. Repeat Step 6 to add the MarkedItem and MainWindow parameters. Your Parameters field now looks like this: -r ClasProp.app dlgdemo $Outline $MarkedItem $MainWindow 9. Enter the path and directory for the SAL CDK sample applications in the Working directory text box. The default is c:\program files\gupta\samples. 10. Enter Properties in the Menu Text and Tool Tip text boxes. Your application will display Properties in the Attribute Inspector menu and the tool tip Properties for the new tool on the toolbar. Extending the Gupta Development Environment 2-9

30 Chapter 2 Using the CDK from SAL Your dialog box now looks like this. 11. Click OK. The application displays a new tool icon at the end of the toolbar. Toolbar New tool icon. Testing the application 1. Click the push button you created in Source.app. (Click the Layout tab to display the dialog box.) 2. Move the cursor over the tool and hold for a couple of seconds. The application displays Properties as the tool tip for the tool. 3. Click the Properties tool Extending the Gupta Development Environment

31 Linking to external SAL applications SQLWindows displays the Demo Properties dialog box (dlgdemo) from the CLASPROP application. 4. Click Close in the dialog box and then close the second instance of SQLWindows. You now have a tool on the toolbar that is linked to a property editor application. You can click the tool and invoke the editor application from the source application at any time. Summary Let us look at how this tool was set up: The tool icon launches GUPTA SQLWindows because the command is the SQLWindows executable filename. The -r parameter causes SQLWindows to run the ClasProp.app editor application. This is useful for debugging the property editor. The dlgdemo parameter is the name of the dialog box that ClasProp.app opens. The $Outline, $MarkedItem, and $MainWindow parameters are macros used by ClasProp.app. These macros are pointers into the current environment so that a second application (ClasProp.app in this case) can start working on it. The Tools dialog box provides these seven macros: Macros Description $File $FileName Fully qualified outline file name. Outline file base name and extension. $FileDir Outline file drive and directory (ending in \). $Outline $MainWindow Passes a decimal number that represents the current outline. Passes a decimal number that represents the handle of the main window. Extending the Gupta Development Environment 2-11

32 Chapter 2 Using the CDK from SAL $DesignItem $MarkedItem Macros Description Passes a decimal number that represents the item of the current design window (form, table, MDI, or dialog). Passes zero if there is no current design window. Passes a decimal number that represents the current marked item in the application. Passes zero if no item is marked. Note: You can use any of the above macros as parameters in a typical QuickObject property application but the first four parameters must be the property dialog box name, the current outline, the marked item, and the filename of the editor application respectively. Writing code from a runtime editor application So far, you have called the editor application from the source application by having the source application open and launch the editor application. In this lesson, you run the editor application on the source application without opening the source application. To do this, you link the property and source applications using the InitFromFile function. When the property application calls this function, it opens the source application, writes code into it, and then saves and closes it. (You can also look at Docker.app in the CDK samples directory to see InitFromFile in use.) Creating a link using the InitFromFile function 1. Open a new application and save it as Editor.app Extending the Gupta Development Environment

33 Linking to external SAL applications 2. Add CDK.APL (the CDK outline interface library) to the Libraries section. Click the top level in the Application Explorer and then the Libraries tab. Right-click Libraries in the Outline and select Add Next Level, File Include. Select File Include... SQLWindows adds this line of code to the Outline: File Include: cdk.apl Extending the Gupta Development Environment 2-13

34 Chapter 2 Using the CDK from SAL 3. In the tree view, double-click EDITOR.APP, Classes, cdkapplication, and then Functions. The InitFromFile function, in the cdkapplication class, is used to initialize the application object based on a file handle. Note that most often you will add InitFromFile to a push button or menu item. 4. Close the cdkapplications class and then Classes. 5. Right-click the Windows folder in the tree view and select New, Form Window from the displayed menu. 6. Enter frmmain for the window name and press Enter. 7. If necessary, display the Controls toolbar (select Tools, Controls). Click the push button tool. push button tool 8. Drop a push button on the form Extending the Gupta Development Environment

35 Linking to external SAL applications 9. Enter GenerateCode for the push button label and press Enter. 10. Right-click the push button, select Properties, and then Object Name. Enter pbgeneratecode and press Enter. Select Done. 11. Click the Variables tab. 12. Right-click Window Variables in the outline, select Add Next Level and then variable cdkcontainer. Enter aformwindow and press Enter. The code line looks like this. Windows Variables cdkcontainer: aformwindow 13. Right-click the line cdkcontainer: aformwindow in the Outline, select Add Same Level, and then add variables cdkpushbutton, cdkactionblock, cdkmessageaction, and Boolean as follows: cdkpushbutton: apushbutton cdkactionblock: aactionblock cdkmessageaction: amsg Boolean: bsuccess Note: If the variable is not listed, click More to display additional variables in a scroll list box. The global variable representing the application is already defined by the CDK.APL library. It is a cdkapplication object called CDK_App. When you read in the outline for Source.app, you initialize this global variable to represent it. Extending the Gupta Development Environment 2-15

36 Chapter 2 Using the CDK from SAL Your Windows Variables code outline looks like this. 14. Double-click frmmain, ChildWindows, and then click pbgeneratecode. Add an On SAM_Click message with the following code to the Actions section. This code adds code to a push button in the source file. On SAM_Click Call CDK_App.InitFromFile( Source.app )!Find the main window Set bsuccess= CDK_App.GetTopLevelWindow( frmmain, aformwindow) If bsuccess!find the push button we created Set bsuccess = aformwindow.getchildwindow ( pbquickobject,apushbutton) If bsuccess!insert a SAM_Create message with actions Call apushbutton.addmessageaction( SAM_Create, amsg) Call amsg.getactions(aactionblock) Call aactionblock.insertafter( Call SalColorSet ( hwnditem, COLOR_IndexWindowText, COLOR_3DShadow) )!Cannot save the outline with the same name as the open one Call CDK_App.SaveOutline( Source2.app ) Call CDK_App.CloseApp() 2-16 Extending the Gupta Development Environment

37 Linking to external SAL applications Editor.app looks like this: In the code, the property application: Calls the function InitFromFile. Initializes CDK_App with the outline handle of the target file. Writes code, which makes the text color change when the push button is created, into the target file. Saves the code to a new file called Source2.app and then closes the file. Note that you cannot save an open outline with the same name. To overwrite Source.app, save the outline to a temporary file, and then rename the file after calling CloseApp. Testing the application 1. Run Editor.app by selecting Debug, Go. 2. Click GenerateCode and then close the application. Extending the Gupta Development Environment 2-17

38 Chapter 2 Using the CDK from SAL 3. Open Source2.app. 4. Double-click Windows, frmmain, ChildWindows, and then click pbquickobject. As you can see, a SAM_Create message has been added from a running GUPTA application. Install the editor application as a wizard You can install wizards in GUPTA SQLWindows and display them as icons in the Wizards dialog box. This procedure shows you how to turn a simple property editor application (ClasProp.app) into a wizard. Turning a property editor application into a wizard 1. If necessary, install the Wizard Wizard application, which is used to convert applications into wizards (run wizwiz.exe). Read Chapter 1, Getting Started, for details Extending the Gupta Development Environment

39 Linking to external SAL applications 2. Open the ClasProp.app application in the CDK SAL samples directory. The default is c:\program files\gupta\samples.. Since Wizard Wizard adds code to launch the property dialog as a wizard in the On SAM_AppStartup message, remove the message and dlgdemo. 3. Click the Actions tab. 4. Select the On SAM_AppStartup message and press Delete. Select this line and press Delete 5. Save ClasProp.app as MyProp.app. Extending the Gupta Development Environment 2-19

40 Chapter 2 Using the CDK from SAL 6. Select Component, Wizards. Double-click here 7. Double-click the Wizard Wizard icon. 8. Click Next. Enter Property Editor here Click this button 9. Enter Property Editor in the Title field Extending the Gupta Development Environment

41 Linking to external SAL applications 10. Click the... (Ellipsis) button to display the Open Icon dialog box. Double-click 11. Double-click palm.ico. 12. Click Next. Extending the Gupta Development Environment 2-21

42 Chapter 2 Using the CDK from SAL 13. Enter Property in the Key field and click Next. 14. Enter dlgdemo in the Dialog Box field and click Next. 15. Click Finish Extending the Gupta Development Environment

43 Linking to external SAL applications Testing the application 1. Click the Actions tab in MyProp.app. Code added to MyProp The code added by Wizard Wizard has turned MyProp.app into a self-installing wizard. The first time you run MyProp, it automatically creates the necessary key and values in the Microsoft Windows Registry and displays an icon for MyProp.app in the Wizards dialog. 2. Select Debug, Go to run MyProp.app. 3. Select Component, Wizards to display MyProp.app added to the Wizards dialog box as a self-installing wizard. Extending the Gupta Development Environment 2-23

44

45 Extending the Gupta Development Environment Chapter 3 Extending Objects from SAL This chapter contains a number of procedures explaining how to extend objects from SAL. The procedures: Get and set properties using QuickObjects. Use the CDK to set properties and write code. Use the CDK to populate a form with objects from an external application. Extending the Gupta Development Environment 3-1

46 Chapter 3 Extending Objects from SAL Setting object properties One of the most basic features of the CDK is getting and setting object properties. Use this feature if you are working with QuickObjects, which are classes derived from visual objects with properties set at designtime and stored in a SQLWindows outline. (Note that QuickObjects allow you to set and get named properties without using the CDK.) The SQLWindows installation includes the CDKFWRK.APL library (a subset of the CDK shipped with the GUPTA Team Developer) and several sample applications demonstrating using this library to create QuickObject property editors. If you used the CDKFWRK.APL library for creating property applications earlier and now want to use the CDK to build applications, note these differences: The CDK prefixes class names with cdk while the CDKFWRK.APL prefixes class names with cqo. The CDK uses the global variables CDK_App and CDK_Window while the CDKFRWRK.APL uses aapp and aitem. (The purpose of these global variables is explained in the following lessons.) Get and set properties When the editor application starts, it needs to be passed parameters to locate the item whose properties you want to edit. The QuickObject Editor passes these parameters to the editor application. After being passed the parameters, the editor application must initialize correctly. Using the property editor 1. Open ClasProp.app from the SAL CDK sample applications directory. The default is c:\program files\gupta\samplesl. 3-2 Extending the Gupta Development Environment

47 Setting object properties 2. Click the Actions tab and then double-click On SAM_AppStartup and On SAM_AppExit. In the above code: The InitializeFramework function (from the cdkitem class and inherited by the cdkapplication class) causes CDK_App object to point to the handle of the source application's outline. The InitializeFramework function does not take parameters because it automatically looks at the parameters list passed to the editor application. Then, it initializes the appropriate instance variables of the CDK_App object. The DisplayModalWindow function brings up the dialog specified in the parameters list. The CloseApp and CloseFrameWork functions close the handle to the source application when the property application is done. All property editor applications must call these functions to initialize and close correctly. Extending the Gupta Development Environment 3-3

48 Chapter 3 Extending Objects from SAL 3. Click the Variables tab. In the above code: The CDK_App object is automatically declared by including the CBCDK.APL library. This object represents the outline of the source application (ClasHost.app in this tutorial), and any action on this object is repeated on the source application. The cdkwindow object, CDK_Window, is a variable from CBCDK.APL. After InitializeFramework is called (see Step 2), this object represents the window object (push button, form, or data field) selected when you launched the property editor. Setting the properties of the selected item 1. Double-click Windows, click dlgdemo, and then the Variables tab. 3-4 Extending the Gupta Development Environment

49 Setting object properties Like CDK_App and CDK_Window, apushbutton represents an object (pb1 in this case) in your source application. However, when dlgdemo is created, apushbutton does not point to anything. Thus, the first step is to assign apushbutton to the object in ClasHost.app. 2. Double-click dlgdemo, ChildWindows, and then click pbgeneratecode. Open the code in the Message Actions section. In the above code: Calling InitializeFromObject causes apushbutton to point to the handle of the cquickpushbutton pb1 in ClasHost.app. The global variable CDK_Window already points to pb1 since it represents the object selected when the property editor is launched. Note that cdkwindow is a generic class that can refer to any top-level or child window. Since, in this tutorial, actions are specifically performed on a push button, the cdkpushbutton object is declared to manipulate the push button in the source application. SetStrProperty takes the property name and value the user enters in the property dialog box (dlgdemo) and sets the property and its value for the push button pb1 in ClasHost.app. This value is stored internally in the outline. 3. Close ClasProp.app. Extending the Gupta Development Environment 3-5

50 Chapter 3 Extending Objects from SAL Writing code using the CDK This lesson explains how the CDK sets properties and writes code back into the source application from an editor application. In this lesson, you: Change the QuickObject link to an application that contains CDK functions. Use the CDK to write code into the source application. Writing code using the CDK 1. Open ClasHost.app from the SAL CDK sample applications directory. The default is c:\program files\gupta\samples. 2. Double-click Windows, frm1, ChildWindows, and then click pb1. Right-click On SAM_Click and choose Comment Items. The code now looks like this: CQuickPushButton: pb1 Message Actions! On SAM_Click Call SalWindowGetProperty( hwnditem, df1, df2 ) You commented out the On SAM_Click code because the editor application will write this code into the source application. 3-6 Extending the Gupta Development Environment

51 Setting object properties 3. Click pb1 in the tree view and then select Component, QuickObject Editor. 4. Change the Application Name to ClasCode.exe. 5. Click OK. 6. Right-click pb1, select Properties, and then Set Property Dialog. 7. Enter MyProp in the Property Name data field and CDK is the key to the future in the Property Val data field. 8. Click Write Code and then Close. Extending the Gupta Development Environment 3-7

52 Chapter 3 Extending Objects from SAL 9. Click the Actions tab and open all the code below Message Actions. As you can see, the property editor has written in new code and this code is identical to the code written by the source application. 10. Select File, Save to save the changes. 11. Open ClasCode.app from the SAL CDK sample applications directory. The default is c:\program files\gupta\samples. 12. Double-click Windows, dlgdemo, ChildWindows, and then click pbgeneratecode and the Actions tab. Double-click On SAM_Click. This code accomplishes a number of things: 3-8 Extending the Gupta Development Environment

53 Setting object properties InitializeFromObject sets apushbutton to point to pb1, the selected object in the source application. The objects amsg and aactionblock add code to the Message Actions section of pb1. The object amsg (class cdkmessageaction) represents On SAM_Click to the Message Actions of pb1. The object aactionblock (class cdkactionblock) represents the code under On SAM_Click. The amsg and aactionblock objects, declared in dlgdemo, do not as yet point to the Message Actions of pb1. They will be initialized to point to pb1 s Message Actions in ClasHost.app. Since apushbutton represents pb1 in the source application, it calls AddMessageAction to initialize amsg. By passing SAM_Click and amsg as parameters, the function creates a new On SAM_Click message in pb1 and amsg points to it. The aactionblock object is initialized by calling the GetActions function for amsg. (This function belongs to the cdkmessage class and not the cdkpushbutton class because the message action block belongs to the message.) Since adding a cdkmessage object with AddMessageAction creates a complete action block, aactionblock simply points to this action block. This is why the code uses a function that gets rather than a function that adds. After creating On SAM_Click and pointing aactionblock to the message s action block, the InsertAfter function (class cdkactionblock) adds the code. The function SetStrProperty sets the properties for apushbutton pb1. The SalWindowGetProperty function call is added to On SAM_Click for pb1. At runtime, this call enables pb1 to retrieve the properties set and stored at designtime in the outline using SetStrProperty. 13. Close ClasCode.app. You just wrote code into the source application from an editor application. Now you can use the CDK to expand GUPTA with this ability to write code from one application into another application. Extending the Gupta Development Environment 3-9

54 Chapter 3 Extending Objects from SAL Populating a form using the CDK This lesson first shows you how to link an empty form to an external application and then how the application automatically writes code to create the objects on the source form. In this lesson, you: Modify the code in ClasHost.app so the form itself is the QuickObject. Change the QuickObject link to a new external application that sets the properties and creates objects on the source form. Create objects on the blank Demo CDK Source App form from the external application. Creating objects on a form using the CDK 1. Open ClasObjc.app. This is an editor application, which, in addition to setting properties and writing code (like the previous editor applications), also creates the class cquickpushbutton and frm1 objects in ClasHost.app Extending the Gupta Development Environment

55 Setting object properties 2. Double-click Windows, then click dlgdemo and the Variables tab. In this code, ClasObjc.app first initializes aform to point to the selected form in the source application. Then, it initializes the other variables to point to new objects it creates. 3. Double-click dlgdemo, ChildWindows, and then click pbgeneratecode. Double-click On SAM_Click to open the code below it. Extending the Gupta Development Environment 3-11

56 Chapter 3 Extending Objects from SAL As you can see in the code, several new functions have been added to ClasCode.app: Call CDK_App.AddClass( "cquickpushbutton", CDK_IT_PushButton, aclass ) Adds the class cquickpushbutton to the source application. The parameter CDK_IT_PushButton specifies this is a push button class. This action initializes the window variable aclass to point to the newly created class. Call CDK_App.GetTopLevelWindow( "frm1", aform ) Initializes aform to point to the Form Window frm1 in the source application. Call aform.addchildwindow( CDK_IT_PushButton, "pb1", apushbutton ) Adds a new push button to frm1 (represented by aform) and initializes the window variable apushbutton to point to the newly created push button. Call apushbutton.setobjectclass( "cquickpushbutton" ) Causes the push button to become an object of class cquickpushbutton instead of being a plain push button. Call apushbutton.setattribute( CDK_IT_WindowTitle, "Get Property" ) Sets the push button's title to read Get Property. Call apushbutton.setwindowcoordinates(.59,.325, 2.2,.292 ) Coordinates positions the push button on frm1 in relative GUPTA SQLWindows form units (inches). Call apushbutton.createwindow() Makes the push button visible in the Layout tab in the source application. Call apushbutton.addmessageaction( "SAM_Click", amsg ) Call amsg.getactions( aactionblock ) Call aactionblock.insertafter("call SalWindowGetProperty(hWndItem, df1, df2)") Adds code to the On SAM_Click message actions of pb1 in ClasHost.app. (This code was introduced in the previous procedure.) 3-12 Extending the Gupta Development Environment

57 Setting object properties Call apushbutton.setstrproperty(dfproperty, dfvalue) Creates a property with the name entered in dfproperty with an associated value with the string entered in dfvalue. Call aform.addchildwindow( CDK_IT_BackgroundText, "Property Name", abackgroundtext) Creates a background text object called Property Name. Call abackgroundtext.setwindowcoordinates(.588,.698, 1.3,.167 ) Call abackgroundtext.createwindow() Positions the background text object on frm1 and makes it visible in the Layout tab in the source application. Call aform.addchildwindow( CDK_IT_DataField, "df1", adatafield ) Creates a data field called df1. Call adatafield.setwindowcoordinates(.588,.99, 2.2,.25 ) Call adatafield.createwindow() Positions the data field df1 on frm1 and makes it visible in the Layout tab in the source application. Call aform.addchildwindow(cdk_it_backgroundtext, "Property Contents", BackgroundText) Call abackgroundtext.setwindowcoordinates(.588, 1.365, 1.6,.167 ) Call abackgroundtext.createwindow() Call aform.addchildwindow( CDK_IT_DataField, "df2", adatafield ) Call adatafield.setwindowcoordinates(.588, 1.573, 2.2,.25 ) Call adatafield.createwindow() Creates a second background text item and data field. After viewing code used to generate child windows on a form, let us now look at ClasObjc.app in action. Instead of calling the application from the object properties of a QuickObject, we will create a button on the SQLWindows toolbar to execute it. Extending the Gupta Development Environment 3-13

58 Chapter 3 Extending Objects from SAL Calling an editor application without using QuickObjects In this procedure, you create a toolbar button to call the editor application from the toolbar rather than from the object properties dialog. You can use the QuickObject editor to assign an editor application to a class in your source application. The object to edit, frm1, is a regular Form Window and not a member of any class. To change this, you can create a class of form window and making frm1 an instance, but this is not a good general solution. For this exercise, we need a tool that can work on any top-level window selected by the user. So we create a tool that can launch the editor application from the GUPTA SQLWindows toolbar. 1. Select Tools, Tool Users to open the Tools dialog box. Click here to add a new tool Click here to add parameters This dialog box creates a new tool with an executable name and an icon. 2. Click Add. This clears the fields in the dialog box and adds a default value in the Command field. 3. Replace the default value with clasobjc.exe in the Command field. This command line launches GUPTA and runs the editor application. 4. Enter "dlgdemo" in the Parameters field. This tells ClasObjc.EXE to call dlgdemo and to initialize itself to point to the outline currently open and the item currently selected Extending the Gupta Development Environment

59 Setting object properties 5. Click the... (Ellipsis) button and select Current Outline from the list. 6. Repeat Step 5 to add Marked Item to the Parameters field. 7. Enter path and directory where GUPTA SQLWindows is installed. The default is c:\gupta. The working directory is the path the editor application will use to search for any files it depends on, such as dlls. 8. Enter Object Creator in the Menu Text and Tool Tip fields. This text appears as the tool tip for the toolbar icon and as text in the Tools menu. Your dialog box now looks like this. 9. Click OK. You added a new tool to your toolbar. If the bar is not visible, select Tools, Toolbars, check Tools, and click OK. New tool icon. 10. Select File, Save to save the changes. Extending the Gupta Development Environment 3-15

60 Chapter 3 Extending Objects from SAL Now you are ready to use the Object Creator tool on a source application, ClasHost.app. Using the Object Creator tool on a source application 1. Open ClasHost.app. The objects that the CDK editor application will create already exist in ClasHost.app. Remove these objects so you can see them recreated by the editor application. 2. Double-click Windows and then click frm1 and the Layout tab. 3. Select all the objects on the form and delete them. Your form looks like this: 4. Double-click Classes in the tree view, then highlight and delete the cquickpushbutton class. 5. Click frm1 and select the Layout tab Extending the Gupta Development Environment

61 Setting object properties 6. Click the Object Creator tool you added to the toolbar (the last icon) to display the Demo Properties Dialog dialog box. 7. Enter MyProp in the Property Name data field and CDK is the tool of the future in the Property Contents data field. 8. Click the Create Objects, Write SAL, and Set Property button. The application creates the buttons and fields in the Demo CDK Host dialog box. You created objects on an empty form by clicking a button on your toolbar! You did this by invoking an editor application that wrote the code to create the objects. 9. Click Close in the Demo Properties Dialog dialog box. 10. Close the ClasHost.app application. Extending the Gupta Development Environment 3-17

62

63 Extending the Gupta Development Environment Chapter 4 Using the CDK from Microsoft Visual C++ This chapter helps you start using the CDK from Microsoft Visual C++. It includes information about: Types of applications you can create. The compiler environment. Setting up the Microsoft Visual C++ environment. Troubleshooting. For complete documentation of CDK C++ classes and functions, please refer to the online help. Extending the Gupta Development Environment 4-1

64 Chapter 4 Using the CDK from Microsoft Visual C++ Application types You can create two types of applications using the C++ CDK: EXE and DLL. Both types are discussed below. EXE applications EXE applications use CDLLI*.DLL (linked via CBDLL.LIB) to access outlines. Note that due to the shared memory restrictions of Win 32, you cannot access an outline currently loaded into SQLWindows. This means that EXE applications can only operate on outlines loaded from a file. DLL applications DLL applications operate in conjunction with a running instance of GUPTA SQLWindows (CBI*.EXE). These applications can operate on an outline loaded from file or the currently loaded outline. You can invoke the DLL in these ways: External tools: Attach the DLL to the Tools menu or add it to a toolbar. Read Chapter 5, Extending Objects from Microsoft Visual C++, for details. QuickObject editor: Attach the DLL to a class in an outline. You can do this by adding a special entry to the Registry Editor, which adds a new option to the Customizer. Read Chapter 5, Extending Objects from Microsoft Visual C++, for details. User wizard: Attach the DLL as a wizard. You can do this by adding entries to the Registry Editor in Microsoft Windows. The compiler environment Microsoft Visual C++ software version Installation directories The C++ CDK and samples are built and tested using Microsoft s Visual C++ Version 6.0. When you set up your compiler environment, the compiler and linker must be able to locate the header files (GUPTA\inc directory) and.lib files (GUPTA directory) required for building projects. 4-2 Extending the Gupta Development Environment

65 Set up the Microsoft Visual C++ environment Set up the Microsoft Visual C++ environment Setting up the Visual C++ environment to work with the C++ CDK 1. Make sure GUPTA Team Developer is installed. 2. Open Microsoft Visual C++ and select Tools, Options from the menu bar. Note: If you did not install GUPTA Team Developer in c:\gupta, use the appropriate path and directory name in Steps 4 and Click the Directories tab. 4. Add the following lines to your include file directories: c:\gupta\inc 5. Add the following lines to your library file directories: c:\gupta 6. Click OK. Troubleshooting Linker error messages Cannot find CDK.LIB or CBDLL.LIB The C++ CDK file CDK.H causes any module that uses it to link with CDK.LIB and CBDLL.LIB. Add the directory where these files reside to the Lib path for Microsoft Visual C++. Read the previous section, Set up the Microsoft Visual C++ environment. By default, these library files are installed in the GUPTA directory. Cannot find a function Set stdcall as the calling convention in the Project Settings dialog box. Setting design hooks into the SQLWindows IDE A design time hook can be set in SQLWindows to enable the SQLWindows design environment to notify tools about certain events. The hook can be set by specifying a DLL name under the following key in the registry: HKEY_CURRENT_USER\Software\Gupta\SQLWindows 2005\DesignHookDLL. Note: This key does not exist in the default installation; you must add it manually. Extending the Gupta Development Environment 4-3

66 Add a new named-string-value under this key for the specified DLL. The namedstring-value will contain the DLL name (without the file extension) and the corresponding value data will contain the file location of the DLL (full DLL path). For example: There can be more than one entry under this registry key, but it is important that the string name for each entry be unique. Use the format shown below to make registry entries:l where testlib.dll is replaced by a dll name of your choice. This dll must have an entry point of SWinDesignHookSet. This entry point is called after the outline window is created. It takes no parameters. SwinDesignHookSet should call SalOutlineSetOutlineHook. This function takes one parameter, which is the address of the function you want to be notified of certain events. The SalOutlineSetOutlineHook returns the address of the previous hook function (or null). It there is a previous hook, it should be called from the new hook function, or the chain will be broken and unknown results will occur as the events will not get propagated across the chain. The hook can also be set from a quickobject dll or from a SQLWindows specific custom control. The following functions in the CDK deal with design hooks. BOOL CDKClearDesignHook(LPCSTR lpszdllname) Clears the design hook DLL passed in as a parameter from the registry. Parameters Name Type Data foobar REG_SZ c:\program Files\Gupta\foobar.dll testlib REG_SZ Drive:\Dir\testlib.dll

67 Setting design hooks into the SQLWindows IDE LpszDLLName:The name of the DLL to remove from the registry Return Value Returns TRUE if the hook was removed, FALSE if not. int CDKGetDesignHookOrdinal(LPCSTR lpszdllname) This call is obsolete in versions 3.0 and later of Team Developer, as the design hook implementation is no longer based on ordinal number. int CDKSetDesignHook(LPCSTR lpszdllname) Sets a DLL as a design hook in the registry to be loaded during startup Return Value Returns TRUE if successful, FALSE if not Parameters LpszDLLName:The file path of the DLL to locate (optional). If NULL, the current module is assumed Comments Design hooks can be set into the Team Developer environment in the registry by making use of this API. This API function helps to register the DLL name as a design hook DLL to be loaded on startup under the following key in the registry: HKEY_CURRENT_USER\Software\Gupta\SQLWindows 2005\DesignHookDLL. One or more DLLs can be set and, since each DLL is identified by the DLL Name, please ensure that the DLL Names are unique. Such DLLs will be loaded by Team Developer during startup. For example, to load foobar.dll, call CDKSetDesignHook( c:\program Files\Gupta\foobar.dll ); Extending the Gupta Development Environment 4-5

68 Chapter 4 Using the CDK from Microsoft Visual C Extending the Gupta Development Environment

69 Extending the Gupta Development Environment Chapter 5 Extending Objects from Microsoft Visual C++ This chapter introduces you to the C++ CDK. It describes: How to create a QuickObject Editor in Microsoft Visual C++. How to add functionality to the QuickObject Editor so that it sets properties and creates QuickObjects in your SQLWindows applications. For complete documentaiton of the CDK C++ classes and functions, please refer to the online help. Extending the Gupta Development Environment 5-1

70 Chapter 5 Extending Objects from Microsoft Visual C++ Create a QuickObject editor in Microsoft Visual C++ In these procedures, you create a push button class in ClasHost.app in SQLWindows and use the C++ CDK to write a simple QuickObject property editor application that edits classes you create in SQLWindows. In addition, other programmers can configure your classes using this property editor. Note: You cannot use.exe files written using the C++ CDK as property editors because of shared memory constraints of the Win 32 API. Creating a push button class in SQLWindows 1. Open ClasHost.app in the GUPTA\sample\sdksal directory. 2. Double-click Classes in the tree view to display a list of defined classes. We created the cquickpushbutton class by selecting New, Pushbutton Class. Opening the DLL-based application in Visual C++ 1. Build the CDK libraries, set the library and include directories before starting these procedures. See Chapter 4, Using the CDK from C++, for details. 2. Open the Microsoft Developer Studio. 3. Select File, Open Workspace. Open ClasProp.dsw in the cdk\cpp\samples directory. The default is c:\gupta. 5-2 Extending the Gupta Development Environment

71 Create a QuickObject editor in Microsoft Visual C++ Microsoft Developer displays the project. Copying and including QOINTF.H and QOINTF.CPP SQLWindows invokes your interface by invoking callbacks from the DLL.You need to subclass CGQuickObjectInterface and override the virtual functions you want supported in the QuickObject DLL. To do this, copy QOINTF.CPP (GUPTA\samples\cdkcpp) to your C++ project directory and then include the file in your C++ project. (Note that adding QOINTF.CPP automatically adds QOINTF.H.) The QOINTF.H file contains prototypes for all the supported interface functions commented out. To implement the functions, uncomment the file. The QOINTF.CPP file contains a template for the DoQuickObjectEditor function. This function displays the property editor dialog box. To implement this function, comment out the existing code and add your own code. 1. In Microsoft Developer Studio (with ClasProp open), select Insert, Files into Project. 2. Select Source Files in the Files of type list box. The project directory lists QOINTF.CPP included in this project. 3. Click Cancel to close the dialog box. Extending the Gupta Development Environment 5-3

72 Chapter 5 Extending Objects from Microsoft Visual C++ Viewing the property editor dialog box in C++ We used a standard dialog box to create the property editor dialog box. 1. Click the ResourceView icon, double-click ClasProp resources, Dialog, and then IDD_PROPDLG. The Demo Properties Dialog looks like this: Labels Standard Text Standard Close button 2. To display the properties and labels for any of the objects, right-click the object and select Properties. In this dialog box: The ID for the dialog box is IDD_PROPDLG. The ID for the edit field below Property Name is IDC_PROPNAME and the ID for the edit field below Property Value is IDC_PROPVALUE. The ID for the Apply button is IDC_APPLY and the ID for the Close button to IDC_CLOSE. Viewing the property dialog class and member variables We created a class based on the Demo Properties Dialog and added member variables for the class objects. 1. Right-click the Demo Properties Dialog and select ClassWizard. 5-4 Extending the Gupta Development Environment

73 Create a QuickObject editor in Microsoft Visual C++ Microsoft Developer displays the MFC ClassWizard dialog box. In this dialog: The class name for the new class (based on the property dialog) is CPropEditor. The class contains the objects listed in the Object IDs list box. The Apply and Close member functions have the message BN_Clicked associated with them. These will be discussed later in this chapter. Now, let us look at the member variables for the controls. 2. Click the Member Variables tab. Extending the Gupta Development Environment 5-5

74 Chapter 5 Extending Objects from Microsoft Visual C++ Your dialog box looks like this: In this dialog box: The IDC_PROPNAME (Property Name text field) control has the member variable m_spropname of type CString. The IDC_PROPVALUE control (Property Value text field) has the member variable m_spropvalue in the Variable field of type CString. 3. Click Cancel to close the dialog box. Adding member variables to CPropEditor Your class needs a pointer of type CGWindow. (The CGWindow class corresponds to the SAL cdkwindow class.) The CGWindow object is passed by the interface function. There are several ways to do this; in this tutorial we added the pointer to the constructor for the class. 1. Click the FileView icon. 2. Double-click ClasProp files, Dependencies, and then PropEdit.h to open the code outline. The PropEdit.h is the header file for the property editor dialog class. Your code outline looks like this: 5-6 Extending the Gupta Development Environment

75 Create a QuickObject editor in Microsoft Visual C++ In this code: The #include "cdk.h" statement gives access to the CDK classes and their functions. CGWindow* pwindow = NULL is a pointer to the CGWindow class object, which represents the window object (push button, form, or data field) selected when you launch the property editor. The pwindow variable is used by the CPropEditor constructor in PropEdit.cpp to initialize member variable CDK_Window. (Note that this corresponds to the CDK_Window SAL object in Chapter 3.) Adding a message map handler to the Apply button 1. Click the ResourceView icon. 2. Select View, ClassWizard. Extending the Gupta Development Environment 5-7

76 Chapter 5 Extending Objects from Microsoft Visual C++ Microsoft Developer displays the ClassWizard dialog box. 3. If necessary, click the Message Maps tab. The message map handler BN_CLICKED has been added to the Apply and Close buttons. 4. Double-click OnApply in the Member functions list box to display the code outline. In this code: The code below void CPropEditor::OnApply() is the implementation for the OnApply function. 5-8 Extending the Gupta Development Environment

77 Create a QuickObject editor in Microsoft Visual C++ The SetProperty function takes the property name and value the user enters in the Property Name and Property Value fields and saves them as the member variables m_spropname and m_spropvalue. Implementing the DoQuickObjectEditor function This function is invoked when the user selects Properties from the right-click context menu of an instance of the associated class (cquickpushbutton). The qointf.cpp file (in the GUPTA\samples\cdkcpp directory) defines the CGQOInterface class and its function DoQuickObjectEditor. We copied this file into the project directory and overrode the DoQuickObjectEditor function to display the customized property editor dialog. Do this for any QuickObject editor project. 1. Click the FilesView icon and then double-click Qointf.cpp under ClasProp files. In this code: The include statement #include "qointf.h" gives access to the QuickObject interface classes and functions. The function DoQuickObjectEditor has been overridden by adding this code: //Construct a property editor CPropEditor PropEditor(CWnd::FromHandle(hWndParent), &Container); return PropEditor.DoModal(); Extending the Gupta Development Environment 5-9

78 Chapter 5 Extending Objects from Microsoft Visual C++ The Do Modal function brings up the property editor dialog box. Adding Entrypoint to the ClasProp.def file For SQLWindows to invoke your DLL it must be able to locate the callbacks needed. Though these callbacks are implemented by the CDK, you must include one DEF in the exports for the DLL. Otherwise, the linker strips these functions from your DLL. 1. Double-click ClasProp.def. In this code, the function SWinPropGetCallbacks sets up ClasProp.dll to communicate with the SQLWindows QuickObject framework. Registering your interface class with the CDK Because you do not know when your interface will be needed, you need to supply the CDK with a runtime class CGQOInterface pointer to your class. This allows the CDK to create your interface when needed to support a callback. The best place to do this is from the constructor of your CWinApp derived class Extending the Gupta Development Environment

79 Create a QuickObject editor in Microsoft Visual C++ 1. Double-click Clasprop.cpp. 2. Scroll to the code CClasPropApp::CClasPropApp(). In this code: The include statement #include "cdk.h" gives access to the CDK classes and functions. The function RegisterQuickObjectInterface sets up ClasProp.dll to communicate with the SQLWindows QuickObject. Note: If you have trouble locating header files or are getting linker errors, check your library include path. The CDK.H file automatically links to the CDK LIB file. See Chapter 4, Using the CDK from Microsoft Visual C++, for details. Hooking up ClasProp.dll to the class in SQLWindows 1. In SQLWindows, open ClasHost.app from the GUPTA\samples\cdksal directory. 2. Double-click Classes in the tree view. 3. Right-click cquickpushbutton to display its context menu and select Properties. 4. Click QuickObject DLL. We added the path and the name of the DLL. The default for this procedure is c:\program files\gupta\samples\cdkcpp\tut1\release\clasprop.dll. 5. Click Done. Extending the Gupta Development Environment 5-11

80 Chapter 5 Extending Objects from Microsoft Visual C++ Debugging your application When debugging a QuickObject DLL use CBI*.EXE as the host application. The function SWinPropEditorItem invokes the property editor. 1. In ClasProp project in Microsoft Developer Suite, select Build, ClasProp.dll. 2. Close ClasProp.mdp in Microsoft Studio. Testing the application 1. Open ClasHost.app in SQLWindows, if necessary. This application is located in the GUPTA\samplescdksal directory. 2. Right-click the GetProperty push button to display its context menu. 3. Select Properties and then QuickObject to run the C++ editor application. Modify the property editor In these procedures, you modify the property editor so that it sets the property for the push button and writes the code to add the push button. Commenting the SAM_Click message action 1. Open ClasHost.app in SQLWindows, if necessary. This application is located in the GUPTA\samples\cdksal directory. 2. Double-click Windows, frm1, ChildWindows, pb1, then click the Actions tab. 3. Select the SAM_Click message and select Edit, Comment Items. Adding strings to the string table The strings you add in this section will be used in the OnApply function. 1. In Microsoft Developer Studio, select File, Open Workspace. Open ClasProp.mdp in GUPTA\samples\cdkcpp\tut Extending the Gupta Development Environment

81 Create a QuickObject editor in Microsoft Visual C++ 2. Click the ResourcesView tab, then double-click ClasProp resources, String Table, and String Table. In this window: The editor application uses strings to mark generated code in the SQLWindows source application. IDS_BEGINBLOCK identifies the string that is entered at the beginning of the block of code and IDS_ENDBLOCK identifies the string that is entered at the end of the block of code. Marking generated code in this manner prevents the application from overwriting or removing user-added code. Viewing code added to CPropEditor::OnApply() 1. Click the FileResource tab, double-click ClasProp files and then PropEdit.cpp. 2. Scroll to the cpropeditor message handlers section. Extending the Gupta Development Environment 5-13

82 Chapter 5 Extending Objects from Microsoft Visual C++ In this code: The amsg and aactionblock objects represent code to the Message Actions section of CDK_Window, the QuickObject. The object amsg represents a SAM_Click message to the Message Actions of CDK_Window and the object aactionblock represents the code below On SAM_Click. The CDK_Window QuickObject calls the AddMessageAction function to initialize the amsg object. By passing SAM_CLICK and amsg as parameters, the function creates a new On SAM_Click message in CDK_Window and amsg points to the message. The Actions object is initialized by calling the GetActions function for amsg. Since adding a cdkmessage object with AddMessageAction creates a complete action block, aactionblock simply points to the this action block. This is why the code uses a function that gets rather than a function that adds. The RemoveBlock function looks for code in the Message Actions section of the SQLWindows application (ClasHost.app) that begins and ends with the strings (defined in the previous procedure) and then removes the code. The AddBlockMarkers adds comment strings (defined in the previous procedure) to the Actions section of CDK_Window. Code is added between the strings by the InsertAfter function, described next. The InsertAfter function sets the properties for CDK_Window. The SalWindowGetProperty function call is added to On SAM_click for CDK_Window. At runtime, this call enables CDK_Window to retrieve the properties set and stored at designtime in the outline using SetProperty function call in PropEdit.cpp. 3. Close the workspace. Populating a form using the CDK In these procedures, you add more capability to the property editor so that it will adds the controls and the pusbbutton in your SQLWindows application, and sets the property for the push button. Changing the CPropEditor class definition By default, the QuickObject interface passes a CGQuickObject reference to your interface class. However, you need a more specialized object, a CGContainer. CGContainer has member functions for managing child windows. 1. Open the ClasProp.mdp project workspace from the GUPTA\samples\cdkcpp\tut3 directory Extending the Gupta Development Environment

83 Create a QuickObject editor in Microsoft Visual C++ 2. Double-click PropEdit.h in the Dependencies list. Scroll to the Implementation section. In this code, the selected window is defined as a container. Changing the interface to initialize a CGContainer 1. Double-click qointf.cpp. In this code: Extending the Gupta Development Environment 5-15

84 Chapter 5 Extending Objects from Microsoft Visual C++ A new variable CGContainer has been declared and set equal to awindow. The variable awindow points to the selected object and in this tutorial, the selected object is the top-level window. The variable awindow gets passed to DoQuickObjectEditor function as a CGContainer. Adding code to CPropEditor::OnApply to generate the objects and the code 1. Double-click the PropEdit.cpp file. 2. Scroll to the cpropeditor message handlers section. In this code: CGApplication CDK_App; CGChildWindow apushbutton; CGChildWindow adatafield; CGChildWindow abackgroundtext; CGMessageAction amsg; CGActionBlock aactionblock; CGItem BeginMarker; Defines variables for the objects to be created on the form. VERIFY(CDK_App.AddClass("cQuickPushButton", kit_classpushbutton, "Added by the C++ CDK Sample ClasProp", &BeginMarker)); 5-16 Extending the Gupta Development Environment

85 Create a QuickObject editor in Microsoft Visual C++ Adds the class cquickpushbutton to the source application. The parameter kit_classpushbutton specifies this is a push button class. VERIFY(CDK_Window->AddChildWindow(kIT_PushButton, ChildWindow, "pbgetprop", "Added by the C++ CDK Sample ClasProp", "cquickpushbutton", &BeginMarker )); Adds a new push button (ChildWindow) to the CDK_Window form window and initializes ChildWindow to point to the push button. Also, the push button becomes an object of class cquickpushbutton. VERIFY(ChildWindow.SetWindowCoordinates(.59,.325, 2.2,.292)); Positions the push button on the CDK_Window form in relative GUPTA SQLWindows form units (inches). VERIFY(ChildWindow.SetTitle("Get Property")); Sets the push button s label to read Get Property. apushbutton.createitem(); Creates the window with the Get Property push button with the coordinates and the title. The remaining code adds the text fields, push buttons, and labels. Read Chapter 3, Extending Objects from SAL, for details. Calling an editor application without using QuickObjects. In this procedure, we added a new entry point, called GUPTATool, for toolbar applications. 1. Scroll to the code extern C void GUPTATool. Extending the Gupta Development Environment 5-17

86 Chapter 5 Extending Objects from Microsoft Visual C++ In this code: A special entry point, called GUPTATool has been declared. SQLWindows looks for this function when a toolbar utility has DLL as its extension. Note that GUPTATool must also be added to the DEF file. The variable hwndparent is set to the window handle of the GUPTA Frame. The Container is initialized with the first marked or selected item in the outline. Even though the user can select more than one item, this code operates only on the first item selected. If the selected item is not allowed by the container class, GetFirstMarked will fail. 2. Double-click ClasProp.def under ClasProp files Extending the Gupta Development Environment

87 Create a QuickObject editor in Microsoft Visual C++ As you can see in this code, GUPTATool is added to the EXPORTS section of the DEF file. Creating a toolbar button to call the editor application In this procedure, you add ClasObjc.dll to your toolbar in ClasHost.app. This toolbar button calls the editor application (ClasObjc.ddl in this case) from the toolbar rather than from the object properties dialog. The QuickObject editor allows you to assign an editor application to a class in your source application. The object to edit, frm1, is a regular Form Window and not a member of any class. For this tutorial, you create a tool that can works on any toplevel window the user has selected. 1. In SQLWindows, open ClasHost.app in GUPTA\samples\cdksal. 2. Select Tools, Tools to open the Tools dialog box. Click here to add a new tool Click here to add parameters This creates a new tool with a default executable name and an icon automatically pre-selected. You can choose a different icon from the list at the bottom of this dialog if you wish. 3. Click Add. This clears the fields in the dialog box and adds a default value in the Command field. 4. Replace the default value with clasobjc.dll in the Command field. Browse to this file. The default location is GUPTA\samples\cdkcpp\tut3\release. This command line runs the dll application. Extending the Gupta Development Environment 5-19

88 Chapter 5 Extending Objects from Microsoft Visual C++ 5. In the working directory, enter path and directory where GUPTA SQLWindows is installed. The default is c:\gupta. The working directory is the path the editor application will use to search for any files it depends on, such as dlls. 6. Enter Object Creator in the Menu Text and Tool Tip fields. This is the text that will appear in the tool tip for the toolbar icon and in the Tools menu. 7. Click OK. You have now added a new tool to your toolbar. If your toolbar is not visible, select Tools, Toolbars from the menu and check Tools in the list box and click OK. Any tools you add will appear on the toolbar. New tool icon. Now you are ready to use the Object Creator tool on a source application. Using the Object Creator tool on a source application The objects that the CDK editor application will create already exist in ClasHost.app. Remove these objects so you can see them recreated by the editor application. 8. Double-click Windows and then click frm1 and the Layout tab Extending the Gupta Development Environment

89 Create a QuickObject editor in Microsoft Visual C++ 9. Select all the objects on the form and delete them. Your form looks like this: 10. Double-click Classes in the tree view, then highlight and delete the cquickpushbutton class. 11. Click frm1 and select the Layout tab. 12. Click the Object Creator tool you added to the toolbar (the last icon) to display the Demo Properties Dialog box. 13. Enter MyProp in the Property Name data field and CDK is the tool of the future in the Property Contents text field. 14. Click the Create Objects, Write SAL, and Set Property button. The application creates the buttons and fields in the Demo CDK Host dialog box. Extending the Gupta Development Environment 5-21