wpclsFindOneObject
This class method finds an object matching a predefined set of properties. It is specific to version 3 or higher of the OS/2 operating system.
Syntax
Object = _wpclsFindOneObject(somSelf, hwndOwner, pszFindParams);
Parameters
- somSelf (M_WPObject *) - input
- Pointer to the WPObject class object.
- hwndOwner (HWND) - input
- Handle of the owner window for any dialogs presented during the search.
- pszFindParams (PSZ) - input
- Null-terminated setup string defining the properties of the object to find. See Remarks for valid keyname-value pairs.
Returns
- Object (WPObject *) - returns
- Pointer to the found object or error indicator.
Value Description Non-NULL Pointer to the found WPObject. NULL No object was found matching the specified criteria.
Remarks
This method is used by find pushbuttons to locate an object based on properties defined in `pszFindParams`. The setup string overrides the default behavior of the wpSetup method, using keyname-value pairs to specify search criteria.
The following table lists valid keyname-value pairs for `pszFindParams`:
| Keyname | Value | Description |
|---|---|---|
| CLASSLIST | class-name | Specifies the name of the object class to search for (e.g., `CLASSLIST=WPBitmap` to search for bitmaps). |
| DEFAULTCRITERIA | YES | Uses default file system criteria, excluding hidden files. |
| DEFAULTCRITERIA | NO | Does not use default file system criteria. |
| DIALOG | YES | Presents a dialog allowing the user to modify search criteria. |
| DIALOG | NO | Prevents the user from modifying search criteria; the caller must specify exact criteria. |
| NAMEFILTER | search-string | Specifies the object name to locate, supporting wildcard characters (e.g., `NAMEFILTER=*.BMP` for all BMP files). |
| STARTFOLDER | path | Fully-qualified path to the folder where the search begins. A path starting with `?":` indicates the boot drive. |
| SUBTREESRCH | YES | Includes subfolders in the search. |
| SUBTREESRCH | NO | Searches only the specified folder, excluding subfolders. |
How to Override
This method is generally not overridden.
Usage
This method can be called at any time to find an object matching the specified properties.
Example Code
This example demonstrates finding a bitmap object using `wpclsFindOneObject`:
#define INCL_WINWORKPLACE
#include <os2.h>
M_WPObject *somSelf; /* Pointer to the WPObject class object */
HWND hwndOwner; /* Handle of the owner window */
PSZ pszFindParams; /* Setup string for search criteria */
WPObject *Object; /* Pointer to the found object */
pszFindParams = "CLASSLIST=WPBitmap;NAMEFILTER=*.BMP;DIALOG=YES";
Object = _wpclsFindOneObject(somSelf, hwndOwner, pszFindParams);
if (Object) {
/* Process the found object */
} else {
/* Handle case where no object was found */
}