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 */
}

Related Methods

• wpclsFindObjectFirst
• wpclsFindObjectNext
• wpclsFindObjectEnd