                         === DISCLAIMER ===


I allow you to use and distribute WPTOOLS.DLL freely under the condition 
that I am in no way responsible for any damage or loss you may suffer. 

Henk Kelder, 2:280/801.339@fidonet.org


What is WPTOOLS.DLL:

WPTOOLS.DLL is a Dynamic Link Library that is contains code to query the
settings for workplace shell objects. This DLL is used by WPSBKP.EXE but
can also be used from within a REXX program.


The following REXX functions are available:



Function: WPToolsLoadFuncs
Purpose : Make the functions in WPTOOLS.DLL available to REXX.

Usage:

/*  First declare WPToolsLoadFuncs itself to REXX */
call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs' 
/*  Call WPToolsLoadFuncs itself. */
call WPToolsLoadFuncs



Function: WPToolsQueryObject
Purpose : Query objects

Usage  :  rc=WPToolsQueryObject(object, [Class], [Title], [Setup], [Location])

Where:
        object = A fully qualified pathname to a file or directory, or
                 A OBJECTID string (e.g. <WP_DESKTOP>), or
                 A string starting with a '#' and being followed
                 by a hexidecimal objecthandle (See WPToolsFolderContent)

        Class  = The name of a REXX variabele enclosed in double quotes
                 that will be created by WPTOOLS and will contain the
                 classname of the object. This argument is optional.
                 
        Title  = The name of a REXX variabele enclosed in double quotes
                 that will be created by WPTOOLS and will contain the
                 Title of the object. This argument is optional.

        Setup  = The name of a REXX variabele enclosed in double quotes
                 that will be created by WPTOOLS and will contain the
                 Setupstring of the object. This argument is optional.

        Location = The name of a REXX variabele enclosed in double quotes
                 that will be created by WPTOOLS and will contain the
                 location of the object. This argument is optional.

Returns: 1 on succes and 0 when a error occured.

Please note that only the object argument is mandatory. All other arguments
only need to be present when the result is needed. Should you not need one
argument, but need a argument that is after the not needed one make sure
you enter all comma's. (e.g.: rc = WPToolsQueryObject(object,,,"SetupString")

See Appendix I and II for information about objects and the setupvalues 
this call returns.


Example:

/* Rexx must start with a comment line */

call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs' 
call WPToolsLoadFuncs

iRetco = WPToolsQueryObject("<WP_DESKTOP>", "szClass", "szTitle", "szSetupString", "szLocation") 
if iRetco Then do
     say 'Classname :' szClass
     say 'Title     :' szTitle
     say 'Location  :'  szLocation
     say 'Setupstring: ' szSetupString
  end 
else
  say 'Unable to return object settings for <WP_DESKTOP>'

End of Example


Function: WPToolsFolderContent
Purpose : Query abstract (non-disk) objects in a specific folder

Usage   : rc=WPToolsFolderContent(folder, stem)

Where   : 

        folder = A fully qualified pathname to a or directory, or
                 A OBJECTID string for a folder (e.g. <WP_DESKTOP>

        stem   = The name of a REXX Stem variable that on succesfull
                 return will contain all abstract objects present
                 in a specific folder. Each returned entry will either
                 be a OBJECTID, when an OBJECTID has been set for 
                 the returned object, or an string starting with a '#' and
                 being followed by the hexadecimal objectid.


Returns: 1 on succes and 0 when a error occured.

Example: 

/* Rexx must start with a comment line */

call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs' 
call WPToolsLoadFuncs

iRetco = WPToolsFolderContent("<WP_DESKTOP>", "list.")
if iRetco = 0 Then Do
   exit
End

say 'Abstract objects on <WP_DESKTOP>:'
do iObject = 1 to list.0
  iRetco=WPToolsQueryObject(list.iObject, "szClass", "szTitle", "szSetupString", "szLocation") 
  if iRetco Then do
     say '"'szClass'", "'szTitle'", "'szSetupString'", "'szLocation'"'
  end 
end

End of Example

APPENDIX I - The workplace shell class tree

      WPObject                       Base object class
         WPAbstract               Base abstract object class
              WPClock            
              WPCountry          
              WPDisk                     
              WPLaunchPad                
              WPKeyboard                 
              WPMouse                    
              WPPalette                  
                   WPColorPalette       
                   WPFontPalette        
                   WPSchemePalette      
              WPPower                    
              WPPrinter                  
              WPProgram                  
              WPShadow                   
                    WPNetLink           
              WPShredder                 
              WPSound                    
              WPSpecialNeeds             
              WPSpool                    
              WPSystem                   
         WPFileSystem                     
              WPDataFile                 
                    WPBitmap            
                    WPIcon              
                    WPMet               
                    WPPif               
                    WPPointer           
                    WPProgramFile       
                           WPCommandFile
              WPFolder                   
                    WPDesktop           
                    WPDrives            
                    WPMinWinViewer      
                    WPNetgrp            
                    WPNetwork           
                    WPRootFolder        
                    WPServer            
                    WPSharedDir         
                    WPStartup           
                    WPTemplates         
              WPWinConfig                
         WPTransient                      
               WPJob                      
               WPPort                     
               WPPdr                      
               WPQdr                      


APPENDIX II  

WPToolsQueryObject has code to support (almost) all object classes for
which object setupstrings are defined, being:

Class             Setup strings returned
-----             ----------------------
                      
WPObject          CCVIEW, DEFAULTVIEW, HELPPANEL, HIDEBUTTON, MINWIN, NOCOPY,
                  NODELETE, NODRAG, NODROP, NOLINK, NOMOVE, NOPRINT, NORENAME,
                  NOSETTINGS, NOSHADOW, NOTVISIBLE, OBJECTID, TITLE
WPAbstract        TEMPLATE
WPProgram         ASSOCFILTER, ASSOCTYPE, EXENAME, MAXIMIZED, MINIMIZED,
                  NOAUTOCLOSE, PARAMETERS, PROGTYPE, SET, STARTUPDIR
WPShadow          SHADOWID
WPRPrinter        NETID (1)
WPPrint           APPDEFAULT, JOBDIALOGBEFOREPRINT, OUTPUTTOFILE, PORTNAME, 
                  PRINTDRIVER, PRINTERSPECIFICFORMAT, PRINTWHILESPOOLING,
                  QSTARTTIME, QSTOPTIME, QUEUENAME, QUEUEDRIVER, SEPARATORFILE
WPServer          NETID (2)
WPNetgrp          NETID (2)
WPDisk            DRIVENUM
WPFontPalette     FONTS, XCELLCOUNT, YCELLCOUNT, XCELLWIDTH, XCELLHEIGHT,
                  XCELLGAP, YCELLGAP
WPColorPalette    COLORS, XCELLCOUNT, YCELLCOUNT, XCELLWIDTH, XCELLHEIGHT,
                  XCELLGAP, YCELLGAP
WPFileSystem      MENU (3)
WPProgramFile     ASSOCFILTER, ASSOCTYPE, EXENAME, MAXIMIZED, MINIMIZED,
                  NOAUTOCLOSE, PARAMETERS, PROGTYPE, SET, STARTUPDIR
WPFolder          ALWAYSSORT, BACKGROUND, DETAILSCLASS, DETAILSFONTS, 
                  ICONFONT, TREEFONT, ICONNFILE, ICONVIEW, SORTCLASS, 
                  TREEVIEW, DETAILSVIEW, WORKAREA,


(1) And all settings for WPPrint.
(2) These settings cannot be used to recreate the object.
(3) MENU doesn't work when applying.

For each object WPToolsQueryObject returns setupstring values for the object 
itself (when supported) but also for all parent classes. When for example
one uses WPToolsQueryObject against the desktop (class WPDesktop) setupstrings
will be returned from the classes WPFolder, WPFileSystem and WPObject.

I did not build any support for WPSchemePalette because the setupstring
for this class do not support settings the colors on an individual basis but
instead one should specify a colorscheme name that is already present
in the ini-files.

