═══ 1. Installation ═══ You should modify the ENVIRON file contained in the VPTOOLKT directory if it does not already match the configuration of your development environment. ═══ 2. Introduction ═══ VisPro/Objects gives you a quick start when developing objects for VisPro/REXX, VisPro/C and VisPro/C++. You simply fill out four notebook pages containing information about about your object: General Fill in general information including the name of your object. Events Define the events that your object supports. Styles Define style flags for your object. Methods Define the methods for your object. Once all the information for your object has been defined, selecting the generate button will create all the source code files for your object. ═══ 3. General Page ═══ The general page allows you to specify the following information for your object: Object Name The contents of the object name field will define the name of your SOM object as well as the names of the generated source code files. It should contain a maximum of 6 alpha-numeric characters and no spaces. Use of mixed case characters are recommended. Descriptive name The contents of the descriptive name field will be used to describe your object within the VisPro development environment. Size The X Size and Y Size spin buttons allow you to define a default size for your objects. This is the initial horizontal and vertical size of the the object when it is dragged from the tool bar and dropped on a VisPro canvas. Has Text This defines whether or not your objects has text associated with it. For example, an entry field has text while a value set does not. Objects that have text will support direct editing of the text within the VisPro views. Objects that have text will also respond to the VpGetItemValue and VpSetItemValue methods. Help entries and method templates will be generated if the text attribute is selected. Default Text If your object has text, the value entered into the default text entry field will be the text the object will have when it is added to a VisPro canvas. Has Control Data Control data is a 'C' struct that allows you to store extra information about your object. For example, the ENTRYFDATA structure for an OS/2 entry field allows you to specify the character limit of the entry field as well as the initial selection. You can program the style page of your object so that VisPro users can set the control data visually using controls on your style page. Note: Since VisPro stores the contents of your control data, the struct should only contain things that can be stored statically. Integers, and fixed length strings are appropriate but pointers, PM handles and other runtime objects can not be stored in control data for there values can change from run to run. Generate Style Page If you select this check box, a style page will appear in the Settings View for your object. All the elements of a style page will be generated for you. This includes the dialog resource file as well as the shell of a dialog procedure. The dialog will contain check boxes for the base styles: visible, tabstop, group, and disabled. Checkboxes will also appear for any styles that you define for your object. Window Procedure Name If you do not select to have a window procedure generated for you, this entry field will contain than name of the window class for your object. Note that you can not use any of the window class names used by VisPro: WC_BUTTON, WC_STATIC, WC_COMBOBOX, WC_LISTBOX, WC_ENTRYFIELD, WC_MLE, WC_VALUESET, WC_NOTEBOOK, WC_SLIDER, WC_CONTAINER, or WC_CIRCULARSLIDER. Include File If you do not select to have a window procedure generated for you, you should enter the name of the include file that contains the definitions for your window class. Lib File If you do not select to have a window procedure generated for you, you should enter the name of the LIB file that contains entry points for your PM window procedure. ═══ 4. Events Page ═══ You can add, change and delete events for your object using the Events Page. Add a generic event by selecting the Add button. Once a generic event is added, change the event by direct editing each column . Descriptive Name This is the text that will appear in the Event menu for your object. Abbreviation This must be a unique alphabetic name of no more than 8 characters and no spaces. It is a good convention to use uppercase characters. WM_CONTROL Symbol This is the WM_CONTROL notification symbol that will be used for your events PM message. If you do not use a standard OS/2 symbol or it is not defined in an include file, you will have to use the #define statement in your object's .CSC file in order to define the symbol. Also, if you are defining your own PM window procedure , you will have to add statements of the following form in order to implement the event notification: WinSendMsg(WinQueryWindow(hwnd,QW_OWNER), WM_CONTROL, MPFROM2SHORT(WinQueryWindowUShort(hwnd,QWS_ID),symbol ,0); C++ Override function This is the name of the virtual function that will be defined as a member function of this objects handler. It must be a unique name. Description Fill in a short description of this event. This description will appear as a comments in your objects .H and .HPP files for the C and C++ version respectively. Also, it will be generated into the .IPF help file for this object. A .PTR pointer file will be created for each of your object's events. The Abbreviation will be used as the file name for each pointer. These pointers will be used to display each event in a form's Event Tree View and the VisPro/REXX debugger. Note that you can use the OS/2 icon editor to edit .PTR files. ═══ 5. Styles Page ═══ You can add, change and delete style bits for your object using the Styles Page. Add a generic style by selecting the Add button. Once a generic style is added, change the style by direct editing each column . Name This must be a unique alphabetic name with no spaces. It is a good convention to use uppercase characters. Bit value Enter a unique hexadecimal value for the bit which is reserved for this style. C++ name This is the C++ name for the style. This will be used in the enumeration of C++ styles for the object. Description Fill in a short description of this style. This description will appear as a comments in your objects .H and .HPP files for the C and C++ version respectively. Also, it will be generated into the .IPF help file for this object. MutEx This field indicates whether the style is mutually exclusive or not. Mutually exclusive styles mean that only one of a set of styles is valid at any one time. Any value other than a zero lengthed string will indicate the style is mutually exclusive (use of an X is a recommend convention). Mutually exclusive styles will have a radio button generated on their styles page rather than a check box. If a style is flagged as mutually exclusive, you will have to edit your files xxxxxxRS.C and VCxxxxxx.C files to replace the 0xFFFFFFFF values to contain all of the objects in the set. Static This field indicates whether the style is static or not. Static styles can not be changed on the fly, rather they can only be set upon instansiation/creation. Any value in this field other than a zero length string will indicate that the style is static (use of an X is a recommend convention). If a style is static, methods for setting/reseting and querying its state will not be generated. Note: Each style you add will have a corresponding check box on the object settings view style page that is created for your object. Also, methods to set and reset the style bits will be created for your object. ═══ 6. Methods Page ═══ You can add, change and delete methods for your object using the Methods Page. Add a generic method by selecting the Add button. Once a generic method is added, change the method by direct editing each column . Description This is the textual description that will appear in the VisPro Create Link window for your method. Model This is the template for your method. This template will be inserted into an event editor as a result of drag and drop programming. Note that the %s statement is required. VisPro will use this as a marker to substitute the object id for an object. C Model This is the template for the C version of the method. C++ Model This is the template for the C++ method of the method. Description Fill in a short description of this method. This description will appear as a comments in your objects .H and .HPP files for the C and C++ version respectively. Also, it will be generated into the .IPF help file for this object. ═══ 7. Generate ═══ Selecting the generate button will create the following source code files. The files will be created in the same directory as your .VPJ file. M.CMD This is a macro file that will set up your environment and build your object. .MAK This is a make file that will define the components that are needed to build your object VP.CSC This is a SOM object definition file that contains all the SOM definitions required to build your object. VP.PTR This file contains the tool bar icon for your object. It can be modified using the OS/2 Icon Editor. event icons An event icon is created for each event for your object. It can be modified using the OS/2 Icon Editor. VP.RC This is the resource file that defines the icon/pointer files for your object. These include icons for events as well as the tool bar icon for your object. VP.DLG If you chose to generate a style page dialog, the resources for the dialog will appear in this file. Note that a check box will be generated for the base styles as well as for each style flag defined by you. VP.RCH This is an include file that contains and #define statements of symbols included in the resource and dialog files. VP.C This 'C' source file contains the SOM methods for your object. You only need to modify this file if you wish to modify the default style for your object or the PM WinRegisterClass statement for your objects window procedure. Note the the default style for your object will be initially set to WS_VISIBLE. RS.C This 'C' source file contains the dialog procedure for your objects style page (if applicable). It also contains the templates for your objects methods. You will need to modify the dialog procedure if your object supports control data information. There will als be comments located in the file where you need to define 'C' statments to implement each of your object's methods. PM.C This 'C' source file contains the Presentation Manager window procedure for your object (if applicable). You will need to modify this window procedure to define : o Visual behavior (WM_PAINT) o Mouse and mouse button behavior (WM_MOUSEMOVE, WM_BUTTONxDOWN, WM_BUTTONxUP, and WM_BUTTONxDBLCLK) o Keyboard behavior (WM_CHAR) VP.DEF This is the linker definition file for your object. VP.IPF This is the shell of the help file for your object. The shell of many help panels are created for you including panels for general help, events, methods, and the style page. After your source files have been generated, run the M macro to build your object. Copy the dynamic link library (.DLL) and the help file (.HLP) into your VISPRORX directory. Also add the object name to the VPRCLASS file located in the VISPRORX directory. The next time you open a VisPro form, your object will appear on the tool bar.