home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: Graphics / Graphics.zip / pmsan052.zip / WPTOOLS.TXT < prev   
Text File  |  1999-06-01  |  11KB  |  313 lines
  1.                           === DISCLAIMER ===
  2.  
  3.  
  4. I allow you to use and distribute WPTOOLS.DLL freely under the condition
  5. that I am in no way responsible for any damage or loss you may suffer.
  6.  
  7. Henk Kelder
  8. hkelder@capgemini.nl
  9. http://www.os2ss.com/information/kelder/
  10.  
  11.  
  12. What is WPTOOLS.DLL:
  13.  
  14. WPTOOLS.DLL is a Dynamic Link Library that contains code to query the
  15. settings for workplace shell objects. This DLL is used by WPSBKP.EXE but
  16. can also be used from within a REXX program.
  17.  
  18.  
  19. The following REXX functions are available:
  20.  
  21.  
  22.  
  23. Function: WPToolsLoadFuncs
  24. Purpose : Make the functions in WPTOOLS.DLL available to REXX.
  25.  
  26. Usage:
  27.  
  28. /*  First declare WPToolsLoadFuncs itself to REXX */
  29. call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs'
  30. /*  Call WPToolsLoadFuncs itself. */
  31. call WPToolsLoadFuncs
  32.  
  33.  
  34.  
  35. Function: WPToolsQueryObject
  36. Purpose : Query objects
  37.  
  38. Usage  :  rc=WPToolsQueryObject(object, [Class], [Title], [Setup], [Location])
  39.  
  40. Where:
  41.         object = A fully qualified path name to a file or directory, or
  42.                  An OBJECTID string (e.g. <WP_DESKTOP>), or
  43.                  A string starting with a '#' and being followed
  44.                  by a hexadecimal object handle (See WPToolsFolderContent)
  45.  
  46.         Class  = The name of a REXX variable, enclosed in quotes,
  47.                  that will be created by WPTOOLS and will contain the
  48.                  class name of the object. This argument is optional.
  49.  
  50.         Title  = The name of a REXX variable, enclosed in quotes,
  51.                  that will be created by WPTOOLS and will contain the
  52.                  title of the object. This argument is optional.
  53.  
  54.         Setup  = The name of a REXX variable, enclosed in quotes,
  55.                  that will be created by WPTOOLS and will contain the
  56.                  setup string of the object. This argument is optional.
  57.  
  58.         Location = The name of a REXX variable, enclosed in quotes,
  59.                  that will be created by WPTOOLS and will contain the
  60.                  location of the object. This argument is optional.
  61.  
  62. Returns: 1 on success and 0 when a error occurred.
  63.  
  64. Please note that only the object argument is mandatory. All other arguments
  65. only need to be present when the result is needed. Should you not need one
  66. argument, but need a argument that is after the not needed one, make sure
  67. you enter all comma's. (e.g.: rc = WPToolsQueryObject(object,,,"SetupString")
  68.  
  69. See Appendix I and II for information about objects and the setup values
  70. this call returns.
  71.  
  72.  
  73. Example:
  74.  
  75. /* REXX must start with a comment line */
  76.  
  77. call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs'
  78. call WPToolsLoadFuncs
  79.  
  80. iRetco = WPToolsQueryObject("<WP_DESKTOP>", "szClass", "szTitle", "szSetupString", "szLocation")
  81. if Iretco Then do
  82.      say 'Class name :' szclass
  83.      say 'Title      :' sztitle
  84.      say 'Location   :' szlocation
  85.      say 'Setupstring:' szsetupstring
  86.   end
  87. else
  88.   say 'Unable to return object settings for <WP_DESKTOP>'
  89.  
  90. End of Example
  91.  
  92.  
  93. Function: WPToolsFolderContent
  94. Purpose : Query abstract (non-disk) objects in a specific folder
  95.  
  96. Usage   : rc=WPToolsFolderContent(folder, stem [,'F'])
  97.  
  98. Where   :
  99.  
  100.         folder = A fully qualified path name to a directory, or
  101.                  an OBJECTID string for a folder (e.g. <WP_DESKTOP>
  102.  
  103.         stem   = The name of a REXX stem variable that, on successful
  104.                  return, will contain all abstract objects present
  105.                  in a specific folder. Each returned entry will either
  106.                  be an OBJECTID (when an OBJECTID has been set for
  107.                  the returned object) or a string starting with a '#' and
  108.                  followed by the hexadecimal object handle.
  109.  
  110.         'F'    =  If specified, WPToolsFolderContent will return all 
  111.                   filesystem objects as well.
  112.  
  113. Returns: 1 on success and 0 when a error occurred.
  114.  
  115. Example:
  116.  
  117. /* REXX must start with a comment line */
  118.  
  119. call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs'
  120. call WPToolsLoadFuncs
  121.  
  122. iRetco = WPToolsFolderContent("<WP_DESKTOP>", "list.")
  123. if iRetco = 0 Then Do
  124.    exit
  125. End
  126.  
  127. say 'Abstract objects on <WP_DESKTOP>:'
  128. do iObject = 1 to list.0
  129.   Iretco=WPToolsQueryObject(list.Iobject, "szclass", "sztitle", "szsetupstring", "szlocation")
  130.   if Iretco Then do
  131.      say '"'szClass'", "'szTitle'", "'szSetupString'", "'szLocation'"'
  132.   end
  133. end
  134.  
  135. End of Example
  136.  
  137. Function: WPToolsSetObjectData
  138. Purpose : Change the settings of an existing object
  139.  
  140. Usage   : rc=WPToolsSetObjectData(object, setup)
  141.  
  142. Where   : 
  143.         object = A fully qualified path name to a file or directory, or
  144.                  An OBJECTID string (e.g. <WP_DESKTOP>), or
  145.                  A string starting with a '#' and being followed
  146.                  by a hexadecimal object handle (See WPToolsFolderContent)
  147.  
  148.         setup  = A WinCreateObject setup string
  149.  
  150. Returns: 1 on success and 0 when a error occurred.
  151.  
  152. NOTE: This function is equal to SysSetObjectData with one difference that
  153.       beside a file name or OBJECTID also a '#' followed by an hexadecimal
  154.       object handle can be specified. This makes it posible that the outcome
  155.       if WPToolsFolderContant can be used.
  156.  
  157.  
  158.  
  159. Function: WPToolsVersion
  160. Purpose : Query version of WPTOOLS.DLL
  161.  
  162. Usage  :  version=WPToolsVersion()
  163.  
  164. Example:
  165.  
  166. /* REXX must start with a comment line */
  167.  
  168. call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs'
  169. call WPToolsLoadFuncs
  170.  
  171. Version = WPToolsVersion()
  172. say 'WPTOOLS.DLL is of version' version
  173.  
  174. End of Example
  175.  
  176. APPENDIX I - The workplace shell class tree
  177.  
  178.       WPObject                       Base object class
  179.         ├── WPAbstract               Base abstract object class
  180.         │     ├── WPClock
  181.         │     ├── WPCountry
  182.         │     ├── WPDisk
  183.         │     ├── WPLaunchPad
  184.         │     ├── WPKeyboard
  185.         │     ├── WPMouse
  186.         │     ├── WPPalette
  187.         │     │     ├── WPColorPalette
  188.         │     │     ├── WPFontPalette
  189.         │     │     └── WPSchemePalette
  190.         │     ├── WPPower
  191.         │     ├── WPPrinter
  192.         │     ├── WPProgram
  193.         │     ├── WPShadow
  194.         │     │      └── WPNetLink
  195.         │     ├── WPShredder
  196.         │     ├── WPSound
  197.         │     ├── WPSpecialNeeds
  198.         │     ├── WPSpool
  199.         │     └── WPSystem
  200.         ├── WPFileSystem
  201.         │     ├── WPDataFile
  202.         │     │      ├── WPBitmap
  203.         │     │      ├── WPIcon
  204.         │     │      ├── WPMet
  205.         │     │      ├── WPPif
  206.         │     │      ├── WPPointer
  207.         │     │      └── WPProgramFile
  208.         │     │             └── WPCommandFile
  209.         │     ├── WPFolder
  210.         │     │      ├── WPDesktop
  211.         │     │      ├── WPDrives
  212.         │     │      ├── WPMinWinViewer
  213.         │     │      ├── WPNetgrp
  214.         │     │      ├── WPNetwork
  215.         │     │      ├── WPRootFolder
  216.         │     │      ├── WPServer
  217.         │     │      ├── WPSharedDir
  218.         │     │      ├── WPStartup
  219.         │     │      └── WPTemplates
  220.         │     └── WPWinConfig
  221.         └── WPTransient
  222.               ├── WPJob
  223.               ├── WPPort
  224.               ├── WPPdr
  225.               └── WPQdr
  226.  
  227.  
  228. APPENDIX II
  229.  
  230. WPToolsQueryObject has code to support (almost) all object classes for
  231. which object setup strings are defined, being:
  232.  
  233. Class             Setup strings returned
  234. -----             ----------------------
  235.  
  236. WPObject          CCVIEW, DEFAULTVIEW, HELPPANEL, HIDEBUTTON, MINWIN, NOCOPY,
  237.                   NODELETE, NODRAG, NODROP, NOLINK, NOMOVE, NOPRINT, NORENAME,
  238.                   NOSETTINGS, NOSHADOW, NOTVISIBLE, OBJECTID, TITLE
  239. WPAbstract        TEMPLATE
  240. WPProgram         ASSOCFILTER, ASSOCTYPE, EXENAME, MAXIMIZED, MINIMIZED,
  241.                   NOAUTOCLOSE, PARAMETERS, PROGTYPE, SET, STARTUPDIR
  242. WPShadow          SHADOWID
  243. WPRPrinter        NETID (1)
  244. WPPrint           APPDEFAULT, JOBDIALOGBEFOREPRINT, OUTPUTTOFILE, PORTNAME,
  245.                   PRINTDRIVER, PRINTERSPECIFICFORMAT, PRINTWHILESPOOLING,
  246.                   QSTARTTIME, QSTOPTIME, QUEUENAME, QUEUEDRIVER, SEPARATORFILE
  247. WPServer          NETID (2)
  248. WPNetgrp          NETID (2)
  249. WPDisk            DRIVENUM
  250. WPFontPalette     FONTS, XCELLCOUNT, YCELLCOUNT, XCELLWIDTH, XCELLHEIGHT,
  251.                   XCELLGAP, YCELLGAP
  252. WPColorPalette    COLORS, XCELLCOUNT, YCELLCOUNT, XCELLWIDTH, XCELLHEIGHT,
  253.                   XCELLGAP, YCELLGAP
  254. WPFileSystem      MENU (3)
  255. WPProgramFile     ASSOCFILTER, ASSOCTYPE, EXENAME, MAXIMIZED, MINIMIZED,
  256.                   NOAUTOCLOSE, PARAMETERS, PROGTYPE, SET, STARTUPDIR
  257. WPFolder          ALWAYSSORT, BACKGROUND, DETAILSCLASS, DETAILSFONTS,
  258.                   ICONFONT, TREEFONT, ICONNFILE, ICONVIEW, SORTCLASS,
  259.                   TREEVIEW, DETAILSVIEW, WORKAREA,
  260. WPLaunchPad       All documented setup strings.
  261.  
  262. (1) Along with all settings for WPPrint.
  263. (2) These settings cannot be used to recreate the object.
  264. (3) MENU doesn't work when applying.
  265.  
  266. For each object, WPToolsQueryObject returns setup string values not only for the object
  267. itself (when supported) but also for all parent classes. When, for example,
  268. one uses WPToolsQueryObject against the Desktop (class WPDesktop) setup strings
  269. will be returned from the classes WPFolder, WPFileSystem and WPObject.
  270.  
  271. I did not build any support for WPSchemePalette because the setup string
  272. for this class do not support settings the colors on an individual basis but
  273. instead one should specify a color scheme name that is already present
  274. in the INI files.
  275.  
  276.  
  277. HISTORY:
  278.  
  279. Version 1.00 - Initial release
  280.  
  281. Version 1.01 - Added support for the Launchpad.
  282.                Added a new REXX API call: WPToolsVersion
  283.  
  284. Version 1.02/1.19 - Not released
  285.  
  286. Version 1.20 - Increased several internal buffers to accommodate OS/2
  287.                Warp Version 4 (Merlin) GAMMA.
  288.  
  289. Version 1.21 - Changed the return code from WPToolsFolderContent for '0' to '1'
  290.                when a folder does not contain any abstract objects.
  291.  
  292. Version 1.32 - Enlarged an internal buffer to overcome a buffer too 
  293.                small error for tag 12.
  294.  
  295. Version 1.33 - Added WPToolsSetObjectData as new REXX API call.
  296.                Modified WPToolsFolderContent so it will, optionally, 
  297.                return all filesystem objects as well.
  298.  
  299. Version 1.34 - Corrected WPHost to return a proper password.
  300.  
  301. Version 1.35 - Added logic for the WarpCenter.
  302.  
  303. Version 1.37 - Corrected one of the internal functions for a possible 
  304.                problem.
  305.  
  306. Version 2.00 - Corrected a problem because internal objecthandles with
  307.                their HIWORD being 0x0004 were not recoqnized as file system
  308.                objects.
  309.  
  310. Version 2.01 - Corrected a problem in an internal routine for retrieving data
  311.                from the ini's. These routine failed if the key didn't contain
  312.                any data. 
  313.