home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / vptool.zip / vpsom.inf (.txt) < prev    next >
OS/2 Help File  |  1994-01-21  |  16KB  |  444 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
  3.  
  4. VisPro/REXX provides access to the SOM class hierarchy to allow extending the 
  5. set of objects.  This allows you to: 
  6.  
  7. o Add your own icons to the VisPro/REXX tool bar. 
  8.  
  9. o Define events for your object. 
  10.  
  11. o Define a Style page for your object's Settings notebook. 
  12.  
  13. o Specify methods that will appear in the Create Link window. 
  14.  
  15. o Specify help panel IDs for your object and object Style page. 
  16.  
  17.  Extending VisPro/REXX requires knowledge in the following areas: 
  18.  
  19. o 'C' language programming 
  20.  
  21. o SOM programming 
  22.  
  23. o OS/2 Presentation Manager programming 
  24.  
  25. o Creating REXX extensions 
  26.  
  27.  
  28. ΓòÉΓòÉΓòÉ 1.1. OS/2 Presentation Manager Custom Controls ΓòÉΓòÉΓòÉ
  29.  
  30. The behavior for your object should be defined within an OS/2 PM custom 
  31. control.  This allows many existing OS/2 PM objects to be easily integrated 
  32. into VisPro/REXX, while minimizing your reliance on a proprietary class library 
  33. and, ultimately, protecting your investment.  Since PM controls are supported, 
  34. when an object is used within a form, VisPro/REXX stores the size, position, 
  35. text, color, font, and attributes for instances of your objects within a 
  36. standard OS/2 Presentation Manager Dialog Resource file. 
  37.  
  38. Presentation Manager Custom Controls 
  39.  
  40. Your PM control should support the following: 
  41.  
  42. o Instantiation using WinCreateWindow() 
  43.  
  44. o Handling of text using WinSetWindowText() and WinQueryWindowText() if text is 
  45.   displayed in your window.  This allows users to change the text of your 
  46.   object from within the VisPro/REXX views. (See WM_SETWINDOWPARAMS in the OS/2 
  47.   Programmer's Reference for more information) 
  48.  
  49. o Presentation Parameters 
  50.  
  51.    - PP_FONTNAMESIZE for fonts 
  52.  
  53.    - PP_FOREGROUNDCOLOR for foreground colors 
  54.  
  55.    - PP_BACKGROUNDCOLOR for background colors 
  56.  
  57. If your PM control has attributes that can be set, define a Style page that 
  58. allows these attributes to be set from within the VisPro/REXX views.  To allow 
  59. VisPro/REXX to save and restore these attributes, store the attributes in the 
  60. following standard ways: 
  61.  
  62. o Window Style Word - This is a PM defined word used for specifying style bits 
  63.   for your control.  WS_VISIBLE, WS_DISABLED, and WS_GROUP, and WS_TABSTOP are 
  64.   reserved, but the other bits are available to you. (See 
  65.   WinSetWindowUShort(,,QWS_STYLE) in the OS/2 Programmer's Reference for more 
  66.   information) 
  67.  
  68. o Control Data - If the style bits are insufficient for storing the attributes 
  69.   that can be set for your control, you can make your control respond to 
  70.   WM_QUERYWINDOWPARAMS and WM_SETWINDOWPARAMS with the WPM_CTLDATA option. 
  71.   This allows you to allocate a block of memory to hold information about your 
  72.   control.  For an example, see the ENTRYFDATA structure description for the 
  73.   WC_ENTRYFIELD in the OS/2 PM Programmer's Reference. 
  74.  
  75. Finally, define your events as WM_CONTROL messages. WM_CONTROL messages are PM 
  76. messages that are sent to the owner window of a control when a user interaction 
  77. occurs. 
  78.  
  79.  
  80. ΓòÉΓòÉΓòÉ 1.2. Extending VisPro/REXX by Subclassing VPOBJ ΓòÉΓòÉΓòÉ
  81.  
  82. An abstract object class, VPOBJ, is made available for extending VisPro/REXX. 
  83. You must subclass this object to define information about your new object 
  84. class.  Certain class methods must be overridden to integrate your object into 
  85. the VisPro/REXX environment. 
  86.  
  87. Upon completion, your object will be contained in a DLL file.  The DLL file 
  88. includes the following: 
  89.  
  90. o SOM method definitions 
  91.  
  92. o Window Procedure for your PM Control 
  93.  
  94. o Dialog Procedure for your Style page (optional) 
  95.  
  96. o Dialog Resource for your Style page (optional) 
  97.  
  98. o POINTER Resources for your object's icon as well as the icons for any events 
  99.  
  100. Note: The name of your object class must be identical to the name of the .DLL 
  101. file. 
  102.  
  103.  
  104. ΓòÉΓòÉΓòÉ 2. Sample Objects ΓòÉΓòÉΓòÉ
  105.  
  106. Two samples are included with the VisPro/REXX SOM Toolkit. 
  107.  
  108. o VPDIAL - MMPM/2 Circular Slider 
  109.  
  110. o VPTEXT - Rotatable Text Object 
  111.  
  112. This examples are described in the following sections. 
  113.  
  114.  
  115. ΓòÉΓòÉΓòÉ 2.1. The Circular Slider Example ΓòÉΓòÉΓòÉ
  116.  
  117. This sample provides a good example for extending an existing PM custom 
  118. control.  This object is virtually identical to the cirucular slider object 
  119. shipped with VisPro/REXX Gold Edition. Three events are supported: 
  120.  
  121. o Entered 
  122.  
  123. o Changed 
  124.  
  125. o Tracking 
  126.  
  127. Several VpDial methods are defined, all of which will appear in the VisPro/REXX 
  128. 'Create Link...' window.  These methods allow you to set the range and 
  129. appearance of the circular slider. 
  130.  
  131. There is also a dialog defined to be used as a Style page for the object 
  132. Settings View.  This allows the program to visually select attributes for the 
  133. circular slider. 
  134.  
  135.  
  136. ΓòÉΓòÉΓòÉ 2.2. The Rotated Text Example ΓòÉΓòÉΓòÉ
  137.  
  138. This sample show you how to define your own PM custom control and tie it into 
  139. VisPro/REXX SOM object hierarchy.  It is a static object that has no events 
  140. defined for it.  It is a piece of text which can appear drawn at selected 
  141. angles. 
  142.  
  143. The highlites of this example are: 
  144.  
  145. o Defining a custom control 
  146.  
  147. o Supporting a PM 'text' attribute 
  148.  
  149. o Supporting a control data block 
  150.  
  151. You can support text for your control by implementing a handler for the 
  152. WM_QUERYWINDOWPARAMS and WM_SETWINDOWPARAMS in the controls window procedure. 
  153. This allows your control to respond to WinSetWindowText, WinQueryWindowText, 
  154. and WinQueryWindowTextLength.  From a VisPro/REXX context, programmers will be 
  155. able to direct edit the object as well as change the objects text for the 
  156. General page or the List View.  Also, VpSetItemValue, and VpGetItemValue can be 
  157. used to set and query the text for the object. 
  158.  
  159. You can support a control block for your control by implementing a handler for 
  160. the WM_QUERYWINDOWPARAMS and WM_SETWINDOWPARAMS in the window procedure as well 
  161. as properly handling the WM_CREATE message.  This allows you to extend the 
  162. information stored for your object.  In this example, the information is a 
  163. Gradient structure that allows you to define the angle for the baseline for the 
  164. drawn text.  This gradient can be changed using the objects Styles page on the 
  165. Settings View.  The gradient will be stored by VisPro/REXX in a form's resource 
  166. file. 
  167.  
  168.  
  169. ΓòÉΓòÉΓòÉ 3. What You Need ΓòÉΓòÉΓòÉ
  170.  
  171. The following files are included with the VisPro/REXX SOM Toolkit and are 
  172. required for creating your SOM object: 
  173.  
  174. o VPOBJ.H - Include file 
  175.  
  176. o VPOBJ.SC - Class Definition File 
  177.  
  178. o VPOBJ.LIB - VPOBJ lib export file 
  179.  
  180. You also need IBM's CSET/2 compiler and the OS/2 2.0 Developer's Toolkit. 
  181.  
  182.  
  183. ΓòÉΓòÉΓòÉ 4. The Abstract Class VPOBJ ΓòÉΓòÉΓòÉ
  184.  
  185. The VPOBJ object class is an abstract class to be subclassed to add objects to 
  186. the VisPro/REXX environment. 
  187.  
  188.  
  189. ΓòÉΓòÉΓòÉ 4.1. Class Methods ΓòÉΓòÉΓòÉ
  190.  
  191. These Class methods should be overridden within your SOM object. 
  192.  
  193.  
  194. ΓòÉΓòÉΓòÉ 4.1.1. _somInitClass ΓòÉΓòÉΓòÉ
  195.  
  196. Override:  Yes 
  197.  
  198. SOM_Scope void  SOMLINK vpdiac_somInitClass(M_VPDial *somSelf,
  199.         IN zString className,
  200.         IN SOMAny *parentClass,
  201.         IN integer4 instanceSize,
  202.         IN int maxStaticMethods,
  203.         IN integer4 majorVersion,
  204.         IN integer4 minorVersion)
  205.  
  206. Called by: SOM when your object class is being initialized 
  207.  
  208. Use: Overriding this method allows you to perform initialization for your 
  209. object class.  Within your method implementation you should do the following: 
  210.  
  211. o Load your resources with DosLoadModule() 
  212.  
  213. o Register your control using WinRegisterClass() 
  214.  
  215. o Register your REXX extensions using RexxRegisterFunctionDll() 
  216.  
  217.  
  218. ΓòÉΓòÉΓòÉ 4.1.2. _InitHelpInstance ΓòÉΓòÉΓòÉ
  219.  
  220. Override:  Yes 
  221.  
  222. SOM_Scope HWND  SOMLINK vpdiac_InitHelpInstance(M_VPDial *somSelf)
  223.  
  224. Called by: VisPro/REXX when a user requests help for your object. 
  225.  
  226. Use: Overriding this method allows you to initialize the IPF help instance for 
  227. your object's help panels. 
  228.  
  229.  
  230. ΓòÉΓòÉΓòÉ 4.1.3. _QueryClassInfo ΓòÉΓòÉΓòÉ
  231.  
  232. Override:  Yes 
  233.  
  234. SOM_Scope VOID  SOMLINK vpdiac_QueryClassInfo(M_VPDial *somSelf,
  235.         PVPCLASSINFO pVpClassInfo)
  236.  
  237. Called by: VisPro/REXX when your object class is initialized. 
  238.  
  239. Use: Overriding this method allows you to populate the members of the 
  240. VPCLASSINFO structure.  This structure is described below: 
  241.  
  242. typedef struct _VPCLASSINFO {
  243.   ULONG cbSize;
  244.   PSZ  pszDescName;     /* descriptive name of object        */
  245.   PSZ  pszAbbrevName;    /* abbreviated name for the object, ie. PB */
  246.   BOOL  bHasText;      /* does the object support direct editing  */
  247.   PSZ  pszDefaultText;   /* default text for controls that have it  */
  248.   BOOL  bHasCtrlData;    /* does the object have create data     */
  249.   PSZ  pszWindowClass;   /* WC_* or the registered class name    */
  250.   LONG  lDefaultWidth;    /* default width for a new object      */
  251.   LONG  lDefaultHeight;   /* default height for a new object     */
  252.   ULONG ulDefaultStyle;   /* default window style for a new object  */
  253.   PVOID pDefaultCtrlData;  /* pointer to default control data     */
  254.   HMODULE hModResource;   /* module handle for resource file     */
  255.   LONG  lIconResID;     /* pointer resource id for the object    */
  256.   LONG  lStyleDlgID;     /* style dialog id for the styles page   */
  257.   PFNWP pfnwpStyleDlgProc;  /* address of the dialog style dialog proc */
  258.   LONG  lToolHelpID;     /* id for the tool help           */
  259.   LONG  lStylesPageHelpID;  /* id for the styles notebook help     */
  260.   HWND  hwndHelpInstance;  /* handle for the help instance       */
  261.   LONG  lNumEvents;     /* number of events defined for this class */
  262.   VPEVENTITEM Events[MAXNUMEVENTS];  /* event table for custom events */
  263.   ULONG usTranslate[MAXNUMEVENTS]; //notification ids for each event wm_control
  264.                //unused entries hold 0
  265.   PVPLOGICITEM Logic;    /* logic models for linking         */
  266.   HPOINTER hptrIcon;     /* reserved                 */
  267.   HPOINTER hptrMouse;    /* reserved                 */
  268.   ULONG  ulReserved;     /* reserved                 */
  269.   ULONG  ulReserved2;    /* reserved                 */
  270.  
  271.   } VPCLASSINFO;
  272.  
  273. The Events array is a list of VPEVENTITEM structures for your object. The 
  274. maximum number of events is 32. 
  275.  
  276. typedef struct _VPEVENTITEM {
  277.  PSZ pszDescName;   /* Descriptive name for the event */
  278.  PSZ pszAbbrevName;  /* abbrev name for the object, ie. 1CLK */
  279.  PSZ pszModel;    /* reserved must be zero */
  280.  ULONG useFlags;   /* reserved must be zero */
  281.  LONG lIconResID;   /* pointer resource id for the event */
  282.  LONG lHelpID;    /* reserved */
  283.  HPOINTER hptrIcon;  /* reserved */
  284. } VPEVENTITEM;
  285. typedef VPEVENTITEM *PVPEVENTITEM;
  286.  
  287. The Logic pointer is a pointer to a block of VPLOGICITEM structures.  These 
  288. structures allow you to define items that will appear in the Create Link window 
  289. for your object. 
  290.  
  291. typedef struct _VPLOGICITEM {
  292.  LONG lHelpID;     /* help panel id for the Create Link... item */
  293.  PSZ pszDescName;   /* descriptive name for the REXX extension */
  294.  PSZ pszModel;     /* function call prototype */
  295.  ULONG menuUseFlags;  /* reserved */
  296.  ULONG useFlags;    /* reserved */
  297.  } VPLOGICITEM;
  298. typedef VPLOGICITEM *PVPLOGICITEM;
  299.  
  300.  
  301. ΓòÉΓòÉΓòÉ 4.1.4. _QueryHelpInstance ΓòÉΓòÉΓòÉ
  302.  
  303. Override:  Not recommended 
  304.  
  305. SOM_Scope HWND  SOMLINK vprc_QueryHelpInstance(M_VPObj *somSelf)
  306.  
  307. Called by: WM_HELP message handler for a Style page dialog procedure. 
  308.  
  309. Use: Allows you to get the handle to the help instance so that the help panel 
  310. can be displayed. 
  311.  
  312.  
  313. ΓòÉΓòÉΓòÉ 4.2. Instance Methods ΓòÉΓòÉΓòÉ
  314.  
  315. These instance methods are provided for implementing a Style page for your 
  316. object.  They must not be overridden. 
  317.  
  318.  
  319. ΓòÉΓòÉΓòÉ 4.2.1. _GetHwnd ΓòÉΓòÉΓòÉ
  320.  
  321. Override:  Not recommended 
  322.  
  323. SOM_Scope HWND  SOMLINK vpr_GetHwnd(VPObj *somSelf)
  324.  
  325. Called by: Your object's Style page dialog procedure. 
  326.  
  327. Use: Gets the PM handle for your object, which is displayed on the canvas of a 
  328. VisPro/REXX Layout View. 
  329.  
  330.  
  331. ΓòÉΓòÉΓòÉ 4.2.2. _IndicateChanged ΓòÉΓòÉΓòÉ
  332.  
  333. Override:  Not recommended 
  334.  
  335. SOM_Scope VOID  SOMLINK vpr_IndicateChanged(VPObj *somSelf)
  336.  
  337. Called by: Your object's Style page dialog procedure. 
  338.  
  339. Use: Flags that the objects attributes have changed and VisPro/REXX should save 
  340. them to disk. 
  341.  
  342.  
  343. ΓòÉΓòÉΓòÉ 4.2.3. _RedrawObject ΓòÉΓòÉΓòÉ
  344.  
  345. Override:  Not recommended 
  346.  
  347. SOM_Scope VOID  SOMLINK vpr_RedrawObject(VPObj *somSelf)
  348.  
  349. Called by: Your object's Style page dialog procedure. 
  350.  
  351. Use: Redraws the object on the canvas of a VisPro/REXX Layout View.  This is 
  352. used when an attribute has changed via user interaction with the Style page 
  353. dialog. 
  354.  
  355.  
  356. ΓòÉΓòÉΓòÉ 4.2.4. _RecreateObject ΓòÉΓòÉΓòÉ
  357.  
  358. Override:  Not recommended 
  359.  
  360. SOM_Scope VOID  SOMLINK vpr_RecreateObject(VPObj *somSelf)
  361.  
  362. Called by: Your object's Style page dialog procedure. 
  363.  
  364. Use: Redraws the object on the canvas of a VisPro/REXX Layout View.  This is 
  365. used when an attribute has changed via user interaction with the Style page 
  366. dialog.  Some attributes require that the object be recreated rather than just 
  367. redrawn.  For example, the LS_HORZSCROLL style bit for a listbox requires the 
  368. object to be recreated in order for the scroll bar to appear. 
  369.  
  370.  
  371. ΓòÉΓòÉΓòÉ 5. The Circular Slider Example ΓòÉΓòÉΓòÉ
  372.  
  373. The circular slider example shows how an object was created to add the 
  374. VisPro/REXX tool bar.  The example consists of the following files: 
  375.  
  376. o VPDIAL.C - 'C' source file  The 'C' Source file has several sections 
  377.  
  378.    - Create Link... REXX extension definitions 
  379.  
  380.    - Styles page dialog procedure 
  381.  
  382.    - Rexx Extension entry point 
  383.  
  384.    - Miscelleneous instance methods 
  385.  
  386.    - Overridden Class methods 
  387.  
  388. o VPDIAL.CSC - SOM object definition file 
  389.  
  390. o VPDIAL.DEF - module definition file 
  391.  
  392. o VPDIAL.MAK - make file 
  393.  
  394. o VPDIAL.PTR - pointer for your object 
  395.  
  396. o VPDIAL.RC - resource file 
  397.  
  398. o VPDIALDG H - include file for the styles page dialog 
  399.  
  400. o VPDIALDG DLG - resource file for the styles page dialog 
  401.  
  402. o ENTER.PTR - pointer for When Entered event 
  403.  
  404. o CHANGED.PTR - pointer for When Changed event 
  405.  
  406. o TIMER.PTR - pointer for When Tracking event 
  407.  
  408.  
  409. ΓòÉΓòÉΓòÉ 6. Installation and Distribution of Your Object ΓòÉΓòÉΓòÉ
  410.  
  411. Your object will be contained within a .DLL file.  In order to allow 
  412. VisPro/REXX programmers to access your object, you must do these two things: 
  413.  
  414.  1. Place the .DLL in a directory contained in the LIBPATH statement of the 
  415.     CONFIG.SYS file. 
  416.  
  417.  2. Append the DLL/Object name to the VPRCLASS file. 
  418.  
  419. The VPRCLASS file is an ASCII text file, which is contained within the 
  420. directory specified by the VISPRORX environment variable.  (See DosGetEnv() in 
  421. the OS/2 Programmer's Reference).  If this environment variable has not been 
  422. defined, you can assume that the VPRCLASS file exists within the C:\VISPRORX 
  423. directory. 
  424.  
  425. When VisPro/REXX programmers distribute .EXE files created with VisPro/REXX, 
  426. your object .DLL must be distributed with the .EXE file only if that object was 
  427. used within that specific project. 
  428.  
  429.  
  430. ΓòÉΓòÉΓòÉ 7. Suggested Reading ΓòÉΓòÉΓòÉ
  431.  
  432. o IBM OS/2 2.0 Technical Library 
  433.  
  434.    - System Object Model Guide and Reference 
  435.  
  436.    - Presentation Manager Programmer's Reference 
  437.  
  438.    - Presentation Manager Programmer's Guide 
  439.  
  440.    - Presentation Manager REXX Programmer's Reference 
  441.  
  442. o OS/2 Developer Magazine, Winter 1993, "Demystifying Custom Controls", p. 120, 
  443.   Mark Benge, et. al. 
  444.